Interface JwtVerifyOptions

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

Wave 1 (§4.5): when present, verifyJwt calls denylist.has(jti) after signature/expiry/type checks and throws with reason "revoked" if true. Omitting this option (the default) preserves current behavior.

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).

Token type — selects default typ expectation.