@idpartners/client-attestation-sdk 1.0.1 → 1.4.0

package/dist/validator/config.d.ts

@@ -6,6 +6,8 @@ import type { JSONWebKeySet } from "jose";
 export declare const DEFAULT_ALGORITHMS: readonly string[];
 /** RFC 9068 section 2.1: a JWT access token's `typ` is `at+jwt` (the `application/` prefix is optional). */
 export declare const DEFAULT_TOKEN_TYPES: readonly string[];
+/** How long keys fetched from `jwksUri` are still used after the last successful fetch: 24 hours. */
+export declare const DEFAULT_JWKS_MAX_STALE_SECONDS: number;
 /** How the resource server authenticates to the AS when introspecting. */
 export type IntrospectionAuthMethod = "client_secret_basic" | "client_secret_post";
 /**
@@ -15,7 +17,11 @@ export interface IntrospectionConfig {
     endpoint: string;
     clientId: string;
     clientSecret: string;
-    /** Defaults to `"client_secret_basic"`. */
+    /**
+     * Defaults to `"client_secret_basic"`, also when `null` or `""` (so an unset environment variable can be
+     * passed straight in). The validator refuses any other value than the two {@link IntrospectionAuthMethod}s,
+     * so a typo can't move the secret into the form body.
+     */
     authMethod?: IntrospectionAuthMethod;
 }
 /**
@@ -24,13 +30,25 @@ export interface IntrospectionConfig {
  * and optional introspection.
  *
  * `issuer` and `audiences` are required: a validator that skips either accepts tokens minted for someone
- * else. `acceptedTokenTypes` is checked against the JWT `typ` header when the token carries one, so an ID
- * token can't stand in for an access token. Pass `null` to turn that check off for an issuer that stamps
- * something other than `at+jwt`.
+ * else. `acceptedTokenTypes` is checked against the JWT `typ` header, so an ID token can't stand in for an
+ * access token: a token without `typ` is refused like one with the wrong `typ`. For an issuer that mints
+ * access tokens without `typ`, `allowMissingTokenType: true` accepts a missing `typ` while a wrong one is
+ * still refused. Pass `null` to turn the check off altogether, for an issuer that stamps something other
+ * than `at+jwt`.
  *
  * An explicitly empty `acceptedAlgorithms` or `acceptedTokenTypes` accepts nothing, and `leewaySeconds: 0`
  * allows no clock skew: only an omitted field takes the default. `none` and the `HS*` algorithms are
  * refused even when listed (see validation/SEMANTICS.md).
+ *
+ * `jwksUri` and the introspection `endpoint` must use https unless their host is loopback (`localhost`,
+ * `127.0.0.1`, `::1`) or `allowInsecure` is set: over plain http anyone on the path could serve their own
+ * keys, or read the resource server's client secret.
+ *
+ * Keys fetched from `jwksUri` are refreshed after an hour, and a failed refresh keeps serving them for up to
+ * `jwksMaxStaleSeconds` after the last successful fetch (default {@link DEFAULT_JWKS_MAX_STALE_SECONDS}).
+ * Past that, every token fails with `key_not_found` (`signing keys unavailable`) until a fetch succeeds, so a
+ * retired key the issuer no longer publishes can't verify tokens indefinitely while the JWKS endpoint is
+ * unreachable. `null` removes the limit: availability over that protection.
  */
 export interface ValidatorConfig {
     issuer: string;
@@ -43,8 +61,21 @@ export interface ValidatorConfig {
     /** Clock skew allowed on `exp` / `nbf` / `iat`, in seconds. Defaults to 60. */
     leewaySeconds?: number;
     introspection?: IntrospectionConfig;
-    /** Defaults to {@link DEFAULT_TOKEN_TYPES}; `null` disables the `typ` check. */
+    /** Defaults to {@link DEFAULT_TOKEN_TYPES}; a token without `typ` is refused. `null` disables the `typ` check. */
     acceptedTokenTypes?: string[] | null;
+    /**
+     * Accept a token without `typ` (or with `"typ": null`) while still refusing a wrong `typ`, for an issuer
+     * that mints access tokens without one. Defaults to `false`.
+     */
+    allowMissingTokenType?: boolean;
+    /** Allow a plain-http `jwksUri` and introspection `endpoint` on non-loopback hosts. Defaults to `false`. */
+    allowInsecure?: boolean;
+    /**
+     * How long keys fetched from `jwksUri` are still used when the refresh keeps failing, in seconds since the
+     * last successful fetch. A positive integer; defaults to {@link DEFAULT_JWKS_MAX_STALE_SECONDS}. `null`
+     * for no limit.
+     */
+    jwksMaxStaleSeconds?: number | null;
 }
 /** A {@link ValidatorConfig} with every optional field defaulted. */
 export interface ResolvedConfig {
@@ -58,4 +89,7 @@ export interface ResolvedConfig {
     introspection?: IntrospectionConfig;
     /** Normalised with {@link normaliseType}; `null` when the check is off. */
     acceptedTokenTypes: string[] | null;
+    allowMissingTokenType: boolean;
+    /** `null` for no limit. */
+    jwksMaxStaleSeconds: number | null;
 }

package/dist/validator/config.js

@@ -12,6 +12,8 @@ export const DEFAULT_ALGORITHMS = Object.freeze([
 ]);
 /** RFC 9068 section 2.1: a JWT access token's `typ` is `at+jwt` (the `application/` prefix is optional). */
 export const DEFAULT_TOKEN_TYPES = Object.freeze(["at+jwt"]);
+/** How long keys fetched from `jwksUri` are still used after the last successful fetch: 24 hours. */
+export const DEFAULT_JWKS_MAX_STALE_SECONDS = 24 * 3600;
 /**
  * `none` (in any case) and the HMAC algorithms are refused whatever `acceptedAlgorithms` says: an unsigned
  * token proves nothing, and an HMAC "signature" checked against an issuer's public key is forgeable by
@@ -33,8 +35,37 @@ export function normaliseType(value) {
     const lower = value.toLowerCase();
     return lower.startsWith("application/") ? lower.slice("application/".length) : lower;
 }
+const AUTH_METHODS = ["client_secret_basic", "client_secret_post"];
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+/** Refuse a non-https URL unless it is loopback or `allowInsecure` is set: the rule the client applies. */
+function checkSecure(url, what, allowInsecure) {
+    if (allowInsecure)
+        return;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`${what} is not a valid URL: ${url}`);
+    }
+    if (parsed.protocol === "https:" || LOOPBACK_HOSTS.has(parsed.hostname.toLowerCase()))
+        return;
+    throw new Error(`${what} must use https: ${url} (loopback hosts are exempt; pass allowInsecure: true to override)`);
+}
+/**
+ * A list option as a copy, refusing anything but an array of strings. JavaScript callers aren't held to
+ * the types, and a bare string would otherwise spread into its characters.
+ */
+function stringList(value, what) {
+    if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
+        throw new Error(`${what} must be an array of strings`);
+    }
+    return [...value];
+}
 /**
- * Normalize a caller-supplied config, applying defaults (mirrors Python's `ValidatorConfig`).
+ * Normalize a caller-supplied config, applying defaults (mirrors Python's `ValidatorConfig`). The result
+ * shares nothing mutable with `config`: a caller reusing or changing its config object afterwards (its
+ * arrays, its JWKS, its introspection settings) can't change a live validator.
  *
  * @internal
  */
@@ -42,20 +73,70 @@ export function resolveConfig(config) {
     if (!config.issuer) {
         throw new Error("issuer is required");
     }
-    const audiences = typeof config.audiences === "string" ? [config.audiences] : [...(config.audiences ?? [])];
+    const audiences = typeof config.audiences === "string" ? [config.audiences] : stringList(config.audiences ?? [], "audiences");
     if (audiences.length === 0) {
         throw new Error("at least one audience is required");
     }
+    // NaN would make every exp/nbf/iat comparison false (no time check at all), and "60" would concatenate
+    const leeway = config.leewaySeconds ?? 60;
+    if (typeof leeway !== "number" || !Number.isSafeInteger(leeway) || leeway < 0) {
+        throw new Error("leewaySeconds must be a non-negative integer");
+    }
+    const allowInsecure = config.allowInsecure ?? false;
+    if (typeof allowInsecure !== "boolean") {
+        throw new Error("allowInsecure must be a boolean");
+    }
+    const allowMissingTokenType = config.allowMissingTokenType ?? false;
+    if (typeof allowMissingTokenType !== "boolean") {
+        throw new Error("allowMissingTokenType must be a boolean");
+    }
+    const maxStale = config.jwksMaxStaleSeconds === undefined ? DEFAULT_JWKS_MAX_STALE_SECONDS : config.jwksMaxStaleSeconds;
+    if (maxStale !== null && (typeof maxStale !== "number" || !Number.isSafeInteger(maxStale) || maxStale <= 0)) {
+        throw new Error("jwksMaxStaleSeconds must be a positive integer, or null for no limit");
+    }
+    if (config.jwksUri) {
+        checkSecure(config.jwksUri, "jwksUri", allowInsecure);
+    }
+    if (config.introspection?.endpoint) {
+        checkSecure(config.introspection.endpoint, "introspection endpoint", allowInsecure);
+    }
+    // JavaScript callers aren't held to the union type: anything else used to be taken as client_secret_post.
+    // Unset (undefined, null or "") is the default, client_secret_basic.
+    const authMethod = config.introspection?.authMethod;
+    const unset = authMethod == null || authMethod === "";
+    if (config.introspection != null && !unset && !AUTH_METHODS.includes(authMethod)) {
+        // never echo the value: a secret passed in the wrong field would end up in the message
+        throw new Error(`introspection authMethod must be "client_secret_basic" or "client_secret_post", got ${describe(authMethod)}`);
+    }
+    if (config.introspection != null) {
+        for (const field of ["clientId", "clientSecret"]) {
+            const value = config.introspection[field];
+            if (typeof value !== "string" || value === "") {
+                throw new Error(`introspection ${field} must be a non-empty string, got ${value === "" ? "an empty string" : describe(value)}`);
+            }
+        }
+    }
     const types = config.acceptedTokenTypes === undefined ? DEFAULT_TOKEN_TYPES : config.acceptedTokenTypes;
     return {
         issuer: config.issuer,
         audiences,
-        jwks: config.jwks,
+        // the JWKS provider keeps each JWK and imports it again for each algorithm a token names
+        jwks: config.jwks == null ? undefined : structuredClone(config.jwks),
         jwksUri: config.jwksUri,
-        requiredScopes: [...(config.requiredScopes ?? [])],
-        acceptedAlgorithms: [...(config.acceptedAlgorithms ?? DEFAULT_ALGORITHMS)],
-        leewaySeconds: config.leewaySeconds ?? 60,
-        introspection: config.introspection,
-        acceptedTokenTypes: types === null ? null : types.map(normaliseType),
+        requiredScopes: stringList(config.requiredScopes ?? [], "requiredScopes"),
+        acceptedAlgorithms: stringList(config.acceptedAlgorithms ?? DEFAULT_ALGORITHMS, "acceptedAlgorithms"),
+        leewaySeconds: leeway,
+        introspection: config.introspection == null
+            ? undefined
+            : { ...config.introspection, authMethod: config.introspection.authMethod || "client_secret_basic" },
+        acceptedTokenTypes: types === null ? null : stringList(types, "acceptedTokenTypes").map(normaliseType),
+        allowMissingTokenType,
+        jwksMaxStaleSeconds: maxStale,
     };
 }
+/** A value's type and size, never its content (it may be a secret). */
+function describe(value) {
+    if (typeof value === "string")
+        return `a string of ${[...value].length} characters`;
+    return value === null ? "null" : `a ${typeof value}`;
+}

package/dist/validator/index.d.ts

@@ -9,11 +9,11 @@ export { AccessTokenValidator } from "./validator.js";
 export type { HttpPost, Claims, ValidatorOptions } from "./validator.js";
 export type { HttpGet } from "./jwks.js";
 export type { Logger, LogAttributes, LogLevel } from "../logging.js";
-export { DEFAULT_ALGORITHMS, DEFAULT_TOKEN_TYPES } from "./config.js";
+export { DEFAULT_ALGORITHMS, DEFAULT_TOKEN_TYPES, DEFAULT_JWKS_MAX_STALE_SECONDS } from "./config.js";
 export type { ValidatorConfig, ResolvedConfig, IntrospectionConfig, IntrospectionAuthMethod, } from "./config.js";
 export type { ValidationResult } from "./result.js";
 export type { ValidationError } from "./errors.js";
 export * as errors from "./errors.js";
 export { ProtectedResource, bearerToken } from "./resource.js";
 export type { ProtectedResourceMetadata, AuthDecision } from "./resource.js";
-export declare const VALIDATOR_VERSION = "1.0.1";
+export declare const VALIDATOR_VERSION = "1.4.0";

package/dist/validator/index.js

@@ -6,7 +6,7 @@
  * `client_attestation_sdk.token_validator` package so every port reports the same verdict for the shared vectors.
  */
 export { AccessTokenValidator } from "./validator.js";
-export { DEFAULT_ALGORITHMS, DEFAULT_TOKEN_TYPES } from "./config.js";
+export { DEFAULT_ALGORITHMS, DEFAULT_TOKEN_TYPES, DEFAULT_JWKS_MAX_STALE_SECONDS } from "./config.js";
 export * as errors from "./errors.js";
 export { ProtectedResource, bearerToken } from "./resource.js";
-export const VALIDATOR_VERSION = "1.0.1";
+export const VALIDATOR_VERSION = "1.4.0";

package/dist/validator/jwks.js

@@ -17,6 +17,8 @@ export const MAX_JWKS_BYTES = 512 * 1024;
 export const DEFAULT_MIN_REFRESH_SECONDS = 30;
 /** @internal */
 export const DEFAULT_MAX_AGE_SECONDS = 3600;
+/** How long fetched keys are still served after the last successful fetch (config `DEFAULT_JWKS_MAX_STALE_SECONDS`). @internal */
+export const DEFAULT_MAX_STALE_SECONDS = 24 * 3600;
 const FETCH_TIMEOUT_MS = 10_000;
 const defaultGet = async (url) => {
     // the shared transport refuses redirects and caps the body at MAX_JWKS_BYTES while reading it
@@ -26,6 +28,25 @@ const defaultGet = async (url) => {
     }
     return resp.body;
 };
+/** The JWK members only a private or symmetric key carries (RFC 7518 section 6). */
+const PRIVATE_MEMBERS = ["d", "p", "q", "dp", "dq", "qi", "k"];
+/**
+ * Whether a JWK may verify a signature: not when its `use` is present and not `sig`, its `key_ops` is present
+ * and lacks `verify`, or it carries private members. Checked on the JWK as published, before jose's
+ * `importJWK` (which drops `use`) sees it.
+ */
+function verifiesSignatures(jwk) {
+    if (typeof jwk !== "object" || jwk === null || Array.isArray(jwk)) {
+        return false; // not a JWK at all: skipped like any key that can't be read
+    }
+    if ("use" in jwk && jwk.use !== "sig") {
+        return false;
+    }
+    if ("key_ops" in jwk && !(Array.isArray(jwk.key_ops) && jwk.key_ops.includes("verify"))) {
+        return false;
+    }
+    return !PRIVATE_MEMBERS.some((member) => member in jwk);
+}
 /** Best-effort JWS `alg` for a JWK that omits `alg`, from its key type / curve. */
 function algorithmFor(jwk) {
     if (jwk.kty === "EC") {
@@ -46,10 +67,11 @@ export class JwksProvider {
     #httpGet;
     #minRefreshMs;
     #maxAgeMs;
+    #maxStaleMs;
     #clock;
     #logger;
-    /** kid -> key, plus the JWK's declared `alg` (a JWK that declares one is only used for that alg). */
-    #keys = new Map();
+    /** The usable keys, in document order: kid-less JWKs are distinct keys, and the first of a duplicate kid wins. */
+    #keys = [];
     #loaded = null;
     #inFlight = null;
     #loadedAt = null;
@@ -62,7 +84,13 @@ export class JwksProvider {
         this.#httpGet = opts.httpGet ?? defaultGet;
         this.#minRefreshMs = (opts.minRefreshSeconds ?? DEFAULT_MIN_REFRESH_SECONDS) * 1000;
         this.#maxAgeMs = (opts.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS) * 1000;
-        this.#clock = opts.clock ?? Date.now;
+        this.#maxStaleMs =
+            opts.maxStaleSeconds === undefined
+                ? DEFAULT_MAX_STALE_SECONDS * 1000
+                : opts.maxStaleSeconds === null
+                    ? null
+                    : opts.maxStaleSeconds * 1000;
+        this.#clock = opts.clock ?? (() => performance.now());
         this.#logger = opts.logger ?? NOOP_LOGGER;
         if (opts.jwks != null) {
             this.#loaded = _a.#parse(opts.jwks).then((keys) => {
@@ -71,11 +99,20 @@ export class JwksProvider {
         }
     }
     static async #parse(jwks) {
-        const keys = new Map();
-        for (const jwk of jwks.keys ?? []) {
-            const alg = jwk.alg ?? algorithmFor(jwk);
+        const keys = [];
+        for (const published of (jwks.keys ?? [])) {
+            if (!verifiesSignatures(published)) {
+                continue;
+            }
+            // Imported without its key_ops: verifiesSignatures has checked them, and jose would hand them to
+            // WebCrypto as the key's usages, which refuses a public key with any usage but "verify" (a JWK exported
+            // from a key pair says ["sign","verify"]). Every later import of this entry (resolve) uses this copy.
+            const { key_ops: _keyOps, ...jwk } = published;
+            // a JWK jose can't read at all is skipped; its key type and curve say how to read it
+            const inferred = algorithmFor(jwk);
             try {
-                keys.set(jwk.kid, { key: await importJWK(jwk, alg), alg: jwk.alg });
+                const key = await importJWK(jwk, inferred);
+                keys.push({ kid: jwk.kid, jwk, alg: jwk.alg, imported: new Map([[inferred, key]]) });
             }
             catch {
                 continue;
@@ -85,34 +122,69 @@ export class JwksProvider {
     }
     /**
      * Resolve the verification key for a header `kid` (and `alg`). Falls back to the single configured key
-     * when the header carries no `kid`. Returns `undefined` when no key can be found; never rejects — a
-     * failed fetch leaves its reason in {@link lastError}.
+     * when the header carries no `kid`. Returns `undefined` when no key can be found, and `null` when the key
+     * found can't be used with `alg` (an EC key of another curve, an RSA key for an EC algorithm); never
+     * rejects — a failed fetch leaves its reason in {@link lastError}.
      */
     async resolve(kid, alg) {
         if (this.#loaded) {
             await this.#loaded;
         }
-        if (!this.#static && this.#jwksUri && (this.#lookup(kid) === undefined || this.#stale())) {
-            await this.#refresh();
+        if (!this.#static && this.#jwksUri) {
+            const held = this.#lookup(kid, alg) !== undefined;
+            if (!held || this.#stale()) {
+                await this.#refresh(held);
+            }
+            if (this.#expired()) {
+                // past the stale limit without a successful refresh: the keys held are not served
+                this.lastError ??= "JWKS fetch failed: cached keys are past the stale limit";
+                return undefined;
+            }
         }
-        const entry = this.#lookup(kid);
-        if (entry === undefined || (alg != null && entry.alg != null && entry.alg !== alg)) {
+        const entry = this.#lookup(kid, alg);
+        if (entry === undefined) {
             return undefined;
         }
-        return entry.key;
+        const as = alg ?? entry.alg ?? algorithmFor(entry.jwk);
+        if (!entry.imported.has(as)) {
+            entry.imported.set(as, await importJWK(entry.jwk, as).catch(() => null));
+        }
+        return entry.imported.get(as) ?? null;
     }
-    #lookup(kid) {
+    /**
+     * For a `kid`, the first key with that `kid` that may be used for `alg`; without one, the sole key when the
+     * set holds exactly one. An empty `kid` names no key.
+     */
+    #lookup(kid, alg) {
+        const allowed = (entry) => alg == null || entry.alg == null || entry.alg === alg;
         if (kid != null) {
-            return this.#keys.get(kid);
+            return kid === "" ? undefined : this.#keys.find((entry) => entry.kid === kid && allowed(entry));
         }
-        return this.#keys.size === 1 ? this.#keys.values().next().value : undefined;
+        return this.#keys.length === 1 && allowed(this.#keys[0]) ? this.#keys[0] : undefined;
+    }
+    /** Milliseconds since the last successful fetch, or `null` before one. */
+    #age() {
+        return this.#loadedAt === null ? null : this.#clock() - this.#loadedAt;
+    }
+    #pastLimit(age) {
+        return this.#maxStaleMs !== null && age !== null && age >= this.#maxStaleMs;
     }
+    /** Whether the set should be refreshed: never fetched, older than the max age, or past the stale limit. */
     #stale() {
-        return this.#loadedAt === null || this.#clock() - this.#loadedAt >= this.#maxAgeMs;
+        const age = this.#age();
+        return age === null || age >= this.#maxAgeMs || this.#pastLimit(age);
     }
-    #refresh() {
+    /** Whether the keys held are past the stale limit, and so not served until a fetch succeeds. */
+    #expired() {
+        return this.#pastLimit(this.#age());
+    }
+    /**
+     * A caller that already holds a usable (if stale) key never waits for another request's fetch: it goes on
+     * with the key it has. One without a key waits for a fetch in flight, which may bring its key.
+     */
+    #refresh(haveKey) {
         if (this.#inFlight) {
-            return this.#inFlight;
+            return haveKey ? Promise.resolve() : this.#inFlight;
         }
         const now = this.#clock();
         if (this.#lastAttempt !== null && now - this.#lastAttempt < this.#minRefreshMs) {
@@ -129,7 +201,7 @@ export class JwksProvider {
                 this.#keys = await _a.#parse(JSON.parse(body));
                 this.#loadedAt = this.#clock();
                 this.lastError = null;
-                emit(this.#logger, "debug", "jwks.fetched", { host: hostOf(this.#jwksUri), keys: this.#keys.size });
+                emit(this.#logger, "debug", "jwks.fetched", { host: hostOf(this.#jwksUri), keys: this.#keys.length });
             }
             catch (exc) {
                 emit(this.#logger, "warn", "jwks.fetch_failed", {
@@ -137,8 +209,15 @@ export class JwksProvider {
                     reason: failureReason(exc),
                     status: exc instanceof TransportError ? exc.status : undefined,
                 });
-                // keep serving the keys already held
+                // keep serving the keys already held, up to the stale limit
                 this.lastError = `JWKS fetch failed: ${exc instanceof Error ? exc.message : String(exc)}`;
+                const age = this.#age();
+                if (this.#pastLimit(age)) {
+                    emit(this.#logger, "warn", "jwks.stale", {
+                        host: hostOf(this.#jwksUri),
+                        age: Math.floor(age / 1000),
+                    });
+                }
             }
             finally {
                 this.#inFlight = null;

package/dist/validator/resource.d.ts

@@ -34,4 +34,12 @@ export declare class ProtectedResource {
     metadataUrl(): string;
     challenge(error?: string, errorDescription?: string | null): string;
     authenticate(authorizationHeader?: string | null, requiredScopes?: string[]): Promise<AuthDecision>;
+    /**
+     * {@link authenticate} for tokens checked by RFC 7662 introspection ({@link AccessTokenValidator.validateActive}),
+     * such as opaque tokens, with the same rules: the response's `aud` must name this resource, so a response
+     * without one is refused (401), and a sender-constrained token (`cnf`) is refused (401). A failed
+     * introspection call is not a verdict: it rejects, as `validateActive` does, and the caller answers it (503,
+     * say).
+     */
+    authenticateActive(authorizationHeader?: string | null, requiredScopes?: string[]): Promise<AuthDecision>;
 }

package/dist/validator/resource.js

@@ -10,12 +10,46 @@
 import * as errors from "./errors.js";
 import { failure } from "./result.js";
 const WELL_KNOWN = "/.well-known/oauth-protected-resource";
+const BEARER = "bearer";
 /** Extract the token from an `Authorization: Bearer <token>` header value, or null. */
 export function bearerToken(authorizationHeader) {
     if (!authorizationHeader)
         return null;
-    const match = /^\s*Bearer\s+(.+?)\s*$/i.exec(authorizationHeader);
-    return match ? match[1] : null;
+    // One linear pass, no regex: a backtracking pattern here costs quadratic or cubic time on a hostile header.
+    // The result is what Go's RE2 (?i)^\s*Bearer\s+(.+?)\s*$ returns, so every port extracts the same token.
+    const h = authorizationHeader;
+    const n = h.length;
+    let i = 0;
+    while (i < n && isSpace(h.charCodeAt(i)))
+        i++;
+    if (n - i <= BEARER.length)
+        return null;
+    for (let k = 0; k < BEARER.length; k++, i++) {
+        if ((h.charCodeAt(i) | 0x20) !== BEARER.charCodeAt(k))
+            return null;
+    }
+    if (!isSpace(h.charCodeAt(i)))
+        return null;
+    let end = n;
+    while (end > i && isSpace(h.charCodeAt(end - 1)))
+        end--;
+    if (end === i) {
+        // Only whitespace after the scheme: RE2 takes the last non-LF whitespace character after the first.
+        for (let j = n - 1; j > i; j--) {
+            if (h[j] !== "\n")
+                return h[j];
+        }
+        return null;
+    }
+    let start = i + 1;
+    while (isSpace(h.charCodeAt(start)))
+        start++;
+    const token = h.slice(start, end);
+    return token.includes("\n") ? null : token;
+}
+/** RE2's `\s`: space, tab, LF, FF and CR. */
+function isSpace(c) {
+    return c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0c || c === 0x0d;
 }
 /**
  * An OAuth-protected resource server. The `validator` must accept `resource` as an audience — that binds
@@ -65,11 +99,24 @@ export class ProtectedResource {
         return "Bearer " + params.join(", ");
     }
     async authenticate(authorizationHeader, requiredScopes) {
+        return this.#guard(authorizationHeader, (token) => this.#validator.validate(token, requiredScopes));
+    }
+    /**
+     * {@link authenticate} for tokens checked by RFC 7662 introspection ({@link AccessTokenValidator.validateActive}),
+     * such as opaque tokens, with the same rules: the response's `aud` must name this resource, so a response
+     * without one is refused (401), and a sender-constrained token (`cnf`) is refused (401). A failed
+     * introspection call is not a verdict: it rejects, as `validateActive` does, and the caller answers it (503,
+     * say).
+     */
+    async authenticateActive(authorizationHeader, requiredScopes) {
+        return this.#guard(authorizationHeader, (token) => this.#validator.validateActive(token, requiredScopes));
+    }
+    async #guard(authorizationHeader, validate) {
         const token = bearerToken(authorizationHeader);
         if (token == null) {
             return { authorized: false, status: 401, wwwAuthenticate: this.challenge(), errorDescription: "authentication required" };
         }
-        let result = await this.#validator.validate(token, requiredScopes);
+        let result = await validate(token);
         if (result.valid && !result.audience.includes(this.resource)) {
             result = failure(errors.INVALID_AUDIENCE, "token audience is not this resource");
         }

package/dist/validator/strict.js

@@ -19,7 +19,12 @@ const SEGMENT = /^[A-Za-z0-9_-]*$/;
  */
 export class Malformed extends Error {
 }
-function decodeSegment(segment) {
+/**
+ * One segment of a compact JWS: unpadded base64url in its canonical form (no non-zero padding bits).
+ *
+ * @internal
+ */
+export function decodeSegment(segment) {
     if (!SEGMENT.test(segment) || segment.length % 4 === 1) {
         throw new Malformed("malformed token");
     }

package/dist/validator/validator.js

@@ -2,7 +2,7 @@
  * Access-token validation: JWT signature + claim checks, and optional RFC 7662 introspection.
  *
  * `validate` does local JWT validation in a fixed order — algorithm accepted, key resolvable,
- * signature, `typ` (when present), `iss`, `exp` present, `exp`, `nbf`, `iat` not in the future, audience,
+ * signature, `typ` (unless the check is off), `iss`, `exp` present, `exp`, `nbf`, `iat` not in the future, audience,
  * then scope — returning the first failure's stable error code. That order is part of the cross-language contract so every port reports the same verdict.
  * `validateActive` instead uses RFC 7662 introspection.
  */
@@ -57,6 +57,7 @@ export class AccessTokenValidator {
             jwks: this.config.jwks,
             jwksUri: this.config.jwksUri,
             httpGet: opts.httpGet,
+            maxStaleSeconds: this.config.jwksMaxStaleSeconds,
             logger: opts.logger,
         });
         this.#httpPost = opts.httpPost ?? defaultPost;
@@ -92,11 +93,16 @@ export class AccessTokenValidator {
             return failure(errors.UNSUPPORTED_ALGORITHM, "algorithm not accepted");
         }
         const kid = header.kid;
-        const key = kid == null || typeof kid === "string" ? await this.#jwks.resolve(kid ?? undefined, alg) : null;
-        if (key == null) {
-            return failure(errors.KEY_NOT_FOUND, this.#jwks.lastError ?? "no signing key for this kid");
+        const key = kid == null || typeof kid === "string" ? await this.#jwks.resolve(kid ?? undefined, alg) : undefined;
+        if (key === undefined) {
+            // a fetch failure's detail (internal host, dial error, IdP body) went to the logger as jwks.fetch_failed;
+            // the description lands in WWW-Authenticate, in front of anyone
+            return failure(errors.KEY_NOT_FOUND, this.#jwks.lastError !== null ? "signing keys unavailable" : "no signing key for this kid");
         }
         try {
+            if (key === null) {
+                throw new Error("the key can't be used with this algorithm");
+            }
             await compactVerify(token, key, { algorithms: [alg] });
         }
         catch {
@@ -109,9 +115,14 @@ export class AccessTokenValidator {
         catch (exc) {
             return failure(errors.INVALID_TOKEN, errMessage(exc));
         }
+        // A token without typ (or with "typ": null) is refused like one with the wrong typ: an ID token or
+        // another JWT the issuer signs without a typ must not pass as an access token. allowMissingTokenType
+        // accepts the missing typ only; a wrong one is still refused.
         const types = this.config.acceptedTokenTypes;
         const typ = header.typ;
-        if (typ != null && types !== null && (typeof typ !== "string" || !types.includes(normaliseType(typ)))) {
+        if (types !== null &&
+            !(typ == null && this.config.allowMissingTokenType) &&
+            (typeof typ !== "string" || !types.includes(normaliseType(typ)))) {
             return failure(errors.INVALID_TOKEN_TYPE, "token is not a JWT access token");
         }
         if (claims.iss !== this.config.issuer) {
@@ -174,15 +185,14 @@ export class AccessTokenValidator {
             "Content-Type": "application/x-www-form-urlencoded",
             Accept: "application/json",
         };
-        const authMethod = cfg.authMethod ?? "client_secret_basic";
-        if (authMethod === "client_secret_basic") {
-            const raw = `${cfg.clientId}:${cfg.clientSecret}`;
-            headers.Authorization = `Basic ${base64(raw)}`;
-        }
-        else {
+        if (cfg.authMethod === "client_secret_post") {
             form.set("client_id", cfg.clientId);
             form.set("client_secret", cfg.clientSecret);
         }
+        else {
+            // client_secret_basic: resolveConfig refuses anything but the two, or unset
+            headers.Authorization = basicAuthorization(cfg.clientId, cfg.clientSecret);
+        }
         try {
             const data = await this.#httpPost(cfg.endpoint, form.toString(), headers);
             if (data === null || typeof data !== "object" || Array.isArray(data)) {
@@ -232,8 +242,35 @@ export class AccessTokenValidator {
         }
     }
 }
-function base64(value) {
-    return base64Encode(utf8Encode(value));
+/**
+ * The `client_secret_basic` Authorization header value (RFC 6749 section 2.3.1): the client id and the secret
+ * are each form-urlencoded (Appendix B), joined with `:` and base64'd. The encoding is the same bytes as
+ * Python's `urllib.parse.quote_plus(s, safe="")`: each UTF-8 byte of `A-Z a-z 0-9 - . _ ~` stays as it is, a
+ * space becomes `+`, and every other byte is `%XX` with uppercase hex (so `:` is `%3A`, `%` is `%25`, `+` is
+ * `%2B` and `*` is `%2A`). Not `encodeURIComponent`, which leaves `! ' ( ) *` alone, nor `URLSearchParams`,
+ * which leaves `*` alone and encodes `~`. validation/SEMANTICS.md, Introspection.
+ *
+ * @internal
+ */
+export function basicAuthorization(clientId, clientSecret) {
+    return `Basic ${base64Encode(utf8Encode(`${formEncode(clientId)}:${formEncode(clientSecret)}`))}`;
+}
+const HEX = "0123456789ABCDEF";
+function formEncode(value) {
+    let out = "";
+    for (const b of utf8Encode(value)) {
+        const unreserved = (b >= 0x30 && b <= 0x39) || // 0-9
+            (b >= 0x41 && b <= 0x5a) || // A-Z
+            (b >= 0x61 && b <= 0x7a) || // a-z
+            b === 0x2d || b === 0x2e || b === 0x5f || b === 0x7e; // - . _ ~
+        if (unreserved)
+            out += String.fromCharCode(b);
+        else if (b === 0x20)
+            out += "+";
+        else
+            out += "%" + HEX[b >> 4] + HEX[b & 0x0f];
+    }
+    return out;
 }
 function errMessage(exc) {
     return exc instanceof Error ? exc.message : String(exc);

package/dist/www-authenticate.d.ts

@@ -0,0 +1,7 @@
+/**
+ * WWW-Authenticate parsing (RFC 9110 section 11.6.1) by the rule every port shares (vectors/README.md, "The
+ * WWW-Authenticate rule"; cases in vectors/www-authenticate.json). Anything that does not follow the grammar
+ * makes the whole value malformed, so a caller that acts on a challenge fails closed.
+ * @internal
+ */
+export {};