Interface JwtVerifyOptions

Clock skew tolerance in milliseconds applied to exp/nbf/iat checks. Default: 300_000 (5 min) per RFC 8725 §3.10 guidance.

Override expected algorithms passed to jose. Default: [keyStore.algorithm]. Setting an explicit list is required when verifying tokens issued by an upstream provider whose alg differs from the local KeyStore.

Required aud claim — must be present (string) or contain (array).

Optional only because bearer-as-credential routes (introspect Bearer self-intro, /userinfo, /logout id_token_hint) cannot establish the calling-client identity before JWT verification, so the audience to pin against is unknown at the verify call. At those sites the caller passes undefined; the verifier emits a jwt_verify_aud_skipped warning so the gap is audit-visible. All sites that DO know the calling client (token / refresh / federation / token-exchange) MUST supply this.

Optional azp claim binding. When provided, payload.azp must equal this value or verification fails with reason: "azp". Used by refresh token verification to bind the RT to the authorized party (D-6 PB-2).

Required iss claim — exact match. Pass an empty string to skip iss pinning when the operator has not configured oauth.jwt.issuer and the call site has no other source of expected issuer; the verifier emits a jwt_verify_iss_skipped warning so the gap is audit-visible.

Optional nonce claim binding. Used by id_token verification to bind the token to the original authorization request (PB-4+5).

Override default typ for this JwtType. Pass null to skip typ checking entirely (legacy migration paths only).

Wave 1 (§4.5): SECURITY GUARDRAIL — set true ONLY in the /oauth/revoke AT path. Spreading this flag to other call sites bypasses token-lifetime enforcement. CI lint must restrict ignoreExpiration: true to revoke handler.

Default: false (exp check runs as normal).

SF-1 transition flag for the v0.4.x→v0.5.x typ-header rollout.

The default is false: tokens whose typ header is absent are rejected. Operators with v0.4.x tokens still in circulation can set this to true for their own bounded migration window — when true, typ-less tokens are accepted and emit a jwt_verify_legacy_typ warning. The v0.5.x default was true; Phase G S2 flips it.

Audit logger. All rejection paths emit a structured warn record with {reason, jti, sub, iss, typ} bindings so SIEM filters can index by reason without scraping message text. Optional — when absent the rejection is silent (caller handles it via the thrown error).

REQUIRED: what this verification consults about revocation (#367).

The two checks used to be independent optional options whose omission "preserved current behavior" — which meant a new call site skipped revocation silently, the same seam shape that produced the #277/#287/ #322 silent no-ops. Ten call sites hand-forwarded them; the eleventh would have failed open with no symptom. Making the field required turns that omission into a type error, and makes the deliberate skip a greppable, reviewable literal:

• { denylist?, subjectRevocation? } — consult what the composition wired. This is the shape for every surface that ACCEPTS a token as a credential; forward both slots even when they may be undefined, because "the deployment wired nothing" is the composition's decision (#363), not the call site's.
• "none" — this call site does not ask about revocation ON PRINCIPLE, and says so in a code review-able way. Correct only where the operation is safe or meaningful for a revoked token: revoking it again (idempotent), logging it out, or reading an id_token_hint.

Token type — selects default typ expectation.