verifyToken decides whether a JWT is genuine, current, and meant for you. This page covers the theory: what ES256 proves, how JWKS distributes the verifying keys, which claims are checked and why, and the formal case for the SDK’s most opinionated choice — a mandatory audience.

What a verified token proves

A JWT is header.payload.signature, base64url-encoded. Verification establishes three independent properties:

1. Authenticity — the signature was produced by the holder of the issuer’s private key (the PDP), so the payload wasn’t forged.
2. Integrity — the payload hasn’t been altered since signing; any tampering invalidates the signature.
3. Validity — the standardised claims place the token in time and scope: iss (who issued it), aud (who it’s for), exp / nbf (when it’s valid).

Authenticity + integrity come from the signature; validity comes from the claim checks. A token can be perfectly signed and still invalid (expired, wrong audience). Both must pass.

ES256

Laravel IAM signs with ES256 — ECDSA over the NIST P-256 curve with SHA-256. It’s an asymmetric scheme: the PDP signs with a private key it never shares; verifiers check with the corresponding public key. That asymmetry is what lets your Node service verify tokens without holding any secret — it only needs the public key, published openly via JWKS.

The SDK pins the algorithm to ['ES256']. Pinning matters: accepting “whatever alg the token declares” is the classic JWT vulnerability (the alg: none and RS/HS confusion attacks). By fixing ES256, a token that asks to be verified some other way is rejected outright.

JWKS: distributing the public key

A JWKS (JSON Web Key Set) is a JSON document of public keys the issuer publishes at a well-known URL — here, <origin>/.well-known/jwks.json. Each key has a kid (key id); a token’s header names the kid it was signed with, so the verifier selects the matching key from the set.

The SDK fetches the JWKS through its own fetch (honouring your timeout and any injected client), builds a local key set, and caches it for up to 10 minutes so it isn’t refetched per token.

Key rotation

Issuers rotate signing keys periodically. During rotation the JWKS publishes both the old and new keys, and tokens may be signed by either. If verification fails specifically because no cached key matches the token’s kid (ERR_JWKS_NO_MATCHING_KEY / ERR_JWKS_MULTIPLE_MATCHING_KEYS), the SDK refetches the JWKS once and retries — catching a key the cache hasn’t seen yet. Any other failure (bad signature, expired, wrong audience) denies immediately, so a forged token can’t trigger a refetch storm.

The claim checks

After the signature verifies, the SDK checks:

exp/nbf are enforced by the underlying library; iss/aud are enforced against the values you supply (or the issuer the SDK derives).

Why the audience must be mandatory

This is the SDK’s most opinionated choice, and it’s worth the formal argument.

The vulnerability. jose.jwtVerify skips the aud check entirely when no expected audience is passed. Consider a cluster where services share one issuer $I$ and one signing key. A token minted for service $A$ has iss = I, a valid signature, and aud = A. If service $B$ verifies it without specifying its own audience, then:

So $B$ accepts a token that was never meant for it — a confused-deputy escalation. The token holder, authorised only for $A$, now passes authentication at $B$.

The fix. Require an expected audience $\text{aud}_B$ and check membership:

Now $\text{token}_A$ (with aud = A, $A \neq B$) fails the membership check and is rejected. The SDK enforces this by refusing to verify at all when no audience is configured — absent audience is a verification failure, not an accept-any:

// inside verifyToken:
if (opts.audience === undefined) {
  throw new TokenVerificationError('audience is required: …');
}

ADR: reject on missing audience instead of accept-any

Gotchas

Next steps

• Verifying tokens (JWKS) — the practical how-to.
• Errors — TokenVerificationError.
• Fail-closed by design — the invariant this upholds.