agentleFS
Sign inStart free
ScaleDockHQScaleDockHQ/scaledock-skills/skills/jwt/SKILL.md

jwt

Skill1 starsChanged 31 days agoMITView on GitHub

JWT and JOSE: verify and issue JWS, JWE and JWK safely. Covers RFC 7515 JWS, RFC 7516 JWE, RFC 7517 JWK, RFC 7518 JWA, RFC 7519 JWT, RFC 8037 OKP keys, the RFC 8725 JWT Best Current Practices and its rfc8725bis update, RFC 9864 fully specified algorithms (Ed25519 instead of EdDSA), the deprecation of none and RSA1_5, RFC 9068 JWT access tokens with the roles, groups and entitlements claims, RFC 7638 JWK thumbprints, the RFC 7800 cnf claim, and the IANA JOSE and JWT claims registries. Use when validating or signing JWTs, choosing alg values, publishing a JWKS, checking typ, kid, iss, aud, exp or nbf, preventing algorithm confusion or alg none attacks, issuing at+jwt access tokens, naming a new claim, or reviewing a JWT library configuration.

We split this skill into the rules it gives an agent

1 rule. 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 5 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Choose algorithms and keys: Prefer ES256 or Ed25519; use HMAC only with a shared secret of at least the hash size.

    line 43

“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

JWT and JOSE

The IETF JOSE specifications define signed (JWS), encrypted (JWE) and key (JWK) formats, and JWT (RFC 7519) puts claims inside them. RFC 8725 and its pending update list the ways JWT validation goes wrong. With this skill the agent issues and verifies JWTs, chooses algorithms and keys, and reviews library settings against those rules.

Follow the workflow below step by step. Every rule here comes from a source in Sources, with the section it cites. When a rule and the pinned source disagree, the source wins; when the source has a newer revision than the pin, follow the refresh steps.

Inputs (fill in, or ask before starting)

  • Role: issuer, verifier, or both. For a verifier, which issuers and which kinds of token (access token, ID token, logout token, custom).
  • Protection: signed only, or also encrypted.
  • Revision: the pinned revisions in Sources, unless the user names another. Drafts apply only at the posture recorded there.
  • Sources: when refreshing this skill or when a rule looks out of date, re-read every URL in Sources first, check the IETF datatracker for a published RFC 8725 successor or a published deprecation of none and RSA1_5, re-read both IANA registries, and update the pins.

Invariants

  1. Algorithms come from an allow-list, never from the token. Allow only algorithms chosen for this issuer and this kind of token, compared case-sensitively (RFC 8725 § 3.1; draft-ietf-oauth-rfc8725bis-10 § 3.1).
  2. none is never accepted by default (RFC 7518 § 3.6). none and RSA1_5 are disabled by default and enabled, if ever, only per object (draft-ietf-jose-deprecate-none-rsa15-06 § 5).
  3. One key, one algorithm. The header alg MUST be consistent with the key found by kid (RFC 8725 § 3.1; rfc8725bis § 3.1). This blocks the RS256-to-HS256 key confusion attack.
  4. The verification key belongs to the issuer named in iss, or the token is rejected (RFC 8725 § 3.8).
  5. aud names the recipient whenever the issuer serves more than one audience; otherwise reject (RFC 7519 § 4.1.3; RFC 8725 § 3.9).
  6. exp and nbf are enforced, with only a small leeway for clock skew (RFC 7519 § 4.1.4, § 4.1.5).
  7. Each kind of JWT has its own explicit typ and validation rules that reject the other kinds (RFC 8725 § 3.11, § 3.12). Access tokens use at+jwt (RFC 9068 § 2.1).
  8. An unknown crit extension makes the token invalid (RFC 7515 § 4.1.11).
  9. kid, jku and x5u are attacker input. Sanitize kid; never fetch jku or x5u outside an allow-list (rfc8725bis § 3.10).
  10. Every layer of a nested JWT is validated (RFC 8725 § 3.3).
  11. Keys are strong enough. HMAC keys are at least the hash size (RFC 7518 § 3.2) and never passwords (RFC 8725 § 3.5); RSA keys are at least 2048 bits (RFC 7518 § 3.3).
  12. New deployments use fully specified algorithms, such as Ed25519 rather than the deprecated EdDSA (RFC 9864 § 2.2, § 4.1.2; rfc8725bis § 3.2).

Workflow

  1. List issuers and token kinds. For each, write down the issuer identifier, the key source, the expected typ, the audience and the allowed algorithms. ✓ No verifier accepts "any algorithm the key supports" or "any issuer".
  2. Choose algorithms and keys. Prefer ES256 or Ed25519; use HMAC only with a shared secret of at least the hash size. -> references/algorithms-and-keys.md ✓ Every key has exactly one alg, and none, RSA1_5 and EdDSA are not on any new allow-list.
  3. Publish keys as a JWK Set with kid, alg and use on each key. Distinct kid values let verifiers pick the right key during rollover (RFC 7517 § 4.5). -> references/algorithms-and-keys.md ✓ The JWK Set has no private members (d, p, q) and no duplicate kid.
  4. Issue tokens with an explicit typ, the claims the profile requires, a short exp and a distinct aud per recipient. -> references/access-tokens.md ✓ An access token carries typ: at+jwt and iss, exp, aud, sub, client_id, iat and jti.
  5. Verify tokens by running the checklist: format, header, key lookup, cryptography, claims. -> references/verification.md ✓ Tokens with alg: none, an HS256 signature made with the RSA public key, a wrong typ, a wrong aud or a past exp are each rejected.
  6. Add encryption only when needed, with OAEP or ECDH-ES, no compression unless required, and limits on PBES2 iterations and decompressed size. -> references/algorithms-and-keys.md ✓ A JWE with RSA1_5, or with a p2c above the limit, is rejected.
  7. Name claims from the registry. Reuse registered claims; give new ones a collision-resistant name. -> references/access-tokens.md ✓ Every custom claim is either registered with IANA or a name you control.

Verify before done

  • The verifier passes a fixed algorithms list, and that list excludes none.
  • iss, aud, exp, nbf and typ are checked for every token kind.
  • Keys come from configuration or the issuer's metadata, never from jku, x5u or jwk in the token.
  • A test token signed with HS256 using the RSA public key as secret is rejected.
  • HMAC secrets are at least as long as the hash output and RSA keys at least 2048 bits.
  • Access tokens use at+jwt and the RFC 9068 § 2.2 claims; roles, groups and entitlements follow RFC 9068 § 2.2.3.1.
  • Every draft in use carries its pinned revision and posture.

Reference index

  • references/verification.md: the step-by-step verification checklist, key confusion, claim checks and a TypeScript example with jose.
  • references/algorithms-and-keys.md: the IANA algorithm statuses, RFC 9864, the none and RSA1_5 deprecation, key strength, JWE limits, JWK members, thumbprints and cnf.
  • references/access-tokens.md: the RFC 9068 access token profile, roles, groups and entitlements, its validation steps, and the IANA claims registry.

Related skills

  • oauth for how access tokens are obtained, presented, bound with DPoP or mTLS, and challenged: npx skills add ScaleDockHQ/scaledock-skills --skill oauth
  • openid-connect for ID tokens and their validation: npx skills add ScaleDockHQ/scaledock-skills --skill openid-connect

Sources

Status uses the publishing body's own maturity term. Checked is the date the source was last read.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free