JWT Auth skill for Codex

Done well means: access tokens are short-lived and verified with a pinned algorithm, issuer, audience and expiry; refresh tokens are opaque, stored hashed, rotated on every use and revoked as a family on reuse; and signing keys can be rotated without logging anyone out. A JWT you cannot revoke must die quickly.

Decide first

Situation	Choice
Browser app on the same site as its API	Prefer session-auth; JWTs add revocation problems for no gain
Mobile app, CLI, or several APIs verifying one login	Short JWT access token + opaque refresh token (this skill)
Users sign in through an external IdP (Auth0, Entra, Keycloak, Cognito)	You only verify their tokens; read oauth2-oidc for the flow
Service-to-service calls	OAuth client credentials or mTLS; JWT verified with aud per service

Never accept a design where a long-lived JWT (days) is the only credential. That is an unrevocable password with an expiry date.

Token design

Token	Format	Lifetime	Storage (browser)	Storage (server)
Access	JWT, asymmetric signature	5-15 min	Memory only	Nothing (stateless)
Refresh	Opaque 256-bit random string	7-30 d sliding, 90 d absolute cap	HttpOnly; Secure; SameSite=Strict cookie scoped to Path=/auth/refresh	sha256(token), user_id, family_id, expires_at, used_at, revoked_at

Access token claims: iss, sub (stable user ID, never email), aud, exp, iat, jti, plus minimal authorization data (scope, tenant_id). Use header typ: "at+jwt" (RFC 9068) so ID tokens and other JWTs cannot be confused with access tokens. Never put PII, secrets or anything you would not print in a log into the payload: it is base64, not encrypted.

Algorithm: ES256 or EdDSA by default. RS256 when an ecosystem requires it. HS256 only when the issuer and the single verifier are the same service, because anyone who can verify can also mint.

Issuing and verifying

Node (jose)

import { SignJWT, jwtVerify, createRemoteJWKSet, importPKCS8 } from "jose";

const privateKey = await importPKCS8(process.env.JWT_PRIVATE_KEY_PEM!, "ES256");

export async function issueAccessToken(user: { id: string; tenantId: string }) {
  return new SignJWT({ scope: "orders:read orders:write", tenant_id: user.tenantId })
    .setProtectedHeader({ alg: "ES256", kid: process.env.JWT_KID!, typ: "at+jwt" })
    .setIssuer("https://auth.example.com")
    .setAudience("https://api.example.com")
    .setSubject(user.id)
    .setIssuedAt()
    .setExpirationTime("10m")
    .setJti(crypto.randomUUID())
    .sign(privateKey);
}

const JWKS = createRemoteJWKSet(new URL("https://auth.example.com/.well-known/jwks.json"));

export async function verifyAccessToken(token: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: "https://auth.example.com",
    audience: "https://api.example.com",
    algorithms: ["ES256"],          // pin: never derive the algorithm from the token
    typ: "at+jwt",
    clockTolerance: 30,             // seconds
  });
  return payload;
}

Python (PyJWT)

import jwt
from jwt import PyJWKClient

jwks = PyJWKClient("https://auth.example.com/.well-known/jwks.json", cache_keys=True)

def verify(token: str) -> dict:
    key = jwks.get_signing_key_from_jwt(token).key
    return jwt.decode(
        token, key,
        algorithms=["ES256"],
        audience="https://api.example.com",
        issuer="https://auth.example.com",
        leeway=30,
        options={"require": ["exp", "iat", "iss", "aud", "sub"]},
    )

Go (golang-jwt/jwt/v5)

tok, err := jwt.Parse(raw, keyFunc, // keyFunc looks up the public key by tok.Header["kid"]
    jwt.WithValidMethods([]string{"ES256"}),
    jwt.WithIssuer("https://auth.example.com"),
    jwt.WithAudience("https://api.example.com"),
    jwt.WithExpirationRequired(),
    jwt.WithLeeway(30*time.Second),
)

Refresh token rotation with reuse detection

POST /auth/refresh  (cookie: rt=<opaque>)
1. row = SELECT ... WHERE token_hash = sha256(rt) FOR UPDATE
2. if no row or row.expires_at < now or row.revoked_at -> 401
3. if row.used_at is not null:                # replay of an already-rotated token
      UPDATE refresh_tokens SET revoked_at = now WHERE family_id = row.family_id
      -> 401 and log a security event (likely theft)
4. UPDATE row SET used_at = now
5. INSERT new row (same family_id, new hash, expires_at = min(now + 30d, family_started + 90d))
6. return new access token + Set-Cookie with the new refresh token

Do steps 1-5 in one transaction. Allow a small grace window (a few seconds) where the previous token returns the same new pair, or parallel tabs and flaky mobile networks will trigger false theft alarms. Logout revokes the family; password change revokes all families for the user.

Revoking access tokens

Pick one, in this order of preference:

1. Short expiry only (5-10 min). Revocation latency equals token lifetime. Fine for most apps.
2. Per-user tokens_valid_after timestamp checked against iat (one cached lookup per request). Handles “log out everywhere” and password reset.
3. jti denylist in Redis with TTL = remaining lifetime. Use for individual compromised tokens. Every verifier must consult it, so this reintroduces a shared dependency.

Key management and rotation

• Keep private keys in a secret manager or KMS; verifiers get only public keys via /.well-known/jwks.json with Cache-Control: max-age=300 or similar.
• Every key has a kid. Verifiers select keys by kid and refetch the JWKS (rate-limited) on an unknown kid.
• Rotation without logouts:
  1. Generate key B, publish JWKS containing A and B. Wait at least the JWKS cache TTL.
  2. Start signing with B.
  3. Keep A published until the longest-lived token signed with A has expired.
  4. Remove A.
• Emergency rotation after key compromise: remove A immediately and accept that every session must re-authenticate. Confirm with the user before doing this in production.

Inspecting a token

scripts/jwt_audit.py decodes a token without verifying it and flags alg: none, jku/x5u headers, missing exp/aud/iss, millisecond timestamps, long lifetimes and claims that look sensitive. Standard library only, works offline:

python3 scripts/jwt_audit.py "$TOKEN" --max-lifetime 900 \
  --expect-iss https://auth.example.com --expect-aud https://api.example.com

Exit 0 means no error findings, 1 means errors, 2 means the input is not a JWS. Never paste production tokens into online decoders; they are live credentials.

Workflow checklist

• Read AGENTS.md; find existing token code (rg -n "jwt|jsonwebtoken|jose|PyJWT|Bearer")
• Confirm JWTs are the right tool (table above)
• Pin algorithm, issuer, audience, typ and leeway in every verifier
• Short access lifetime; opaque refresh tokens stored hashed with rotation and reuse detection
• Choose a revocation strategy and implement logout and revoke-all
• Publish JWKS with kid; document the rotation runbook
• Add the negative tests below

Verification

Write tests that must fail closed:

• Token with alg: none, or HS256 signed with the public key as secret, is rejected.
• Wrong aud, wrong iss, expired by more than leeway, and missing exp are each rejected.
• An ID token (or any token without typ: at+jwt) is rejected by the API.
• Reusing a rotated refresh token returns 401 and revokes the newer token in the same family.
• After key rotation, tokens signed with the old key still verify until removal, then fail.

Gotchas

• Using jwt.decode without algorithms= in older libraries, or verify=False “for now”.
• exp in milliseconds (Date.now()) makes tokens valid for 50,000 years.
• Comparing aud as a string when it may be an array; let the library do it.
• Trusting jku, x5u or an embedded jwk header lets attackers supply their own key.
• Storing access tokens in localStorage exposes them to any XSS; keep them in memory and accept a silent refresh on page load.
• Scopes and roles baked into a 24 h token survive demotion for 24 h.
• Sharing one signing key across environments means a staging leak forges production tokens.
• For broader token-handling review (storage, leakage in logs, URLs), use token-security.