@idpartners/client-attestation-sdk 1.0.1 → 1.2.0

package/dist/token-source.js

@@ -11,7 +11,7 @@
  *
  *     import { ClientAttestation } from "@idpartners/client-attestation-sdk";
  *
- *     const ca = new ClientAttestation("pf.example.com");
+ *     const ca = new ClientAttestation("pf.example.com", { evidenceAudience: "https://attester.example.com/evidence" });
  *     const token = await ca.token();                       // cached until it nears expiry
  *
  *     // the fetch wrapper attaches the token (and a DPoP proof for a DPoP-bound token):
@@ -20,22 +20,38 @@
  *     const headers = await ca.requestHeaders("GET", "https://api.example.com/things");
  */
 import { base64url } from "jose";
-import { DpopProofBuilder } from "./builders.js";
+import { checkHtu, DpopProofBuilder, htuParts, normalizeHtu } from "./builders.js";
 import { ClientAttestationCredential, DPOP_HEADER } from "./credential.js";
 import { ClientAttestationError, TransportError } from "./errors.js";
 import { autoDetectEvidence } from "./evidence.js";
 import { MintRequest, PingFederateProfile, metadataDocument, } from "./attester.js";
-import { jsonOk, request } from "./http.js";
+import { checkSecure, jsonOk, request, snippet } from "./http.js";
 import { emit, failureReason, hostOf, NOOP_LOGGER, urlParts } from "./logging.js";
-import { utf8Decode } from "./runtime.js";
+import { monotonicMs, utf8Decode } from "./runtime.js";
 import { SigningKeyPair } from "./signing-key-pair.js";
 export const ATTESTATION_HEADER = "OAuth-Client-Attestation";
 export const POP_HEADER = "OAuth-Client-Attestation-PoP";
 /** Refresh this many seconds before the token actually expires, so a token is never used at the edge. */
 export const DEFAULT_EXPIRY_SKEW_SECONDS = 30;
+const POP_JWT = "attestation_pop_jwt";
+const DPOP_COMBINED = "dpop_combined";
+const POP_METHODS = [POP_JWT, DPOP_COMBINED];
+const PIN_REQUIRED = "evidenceAudience is required: set it to the audience your attester expects the workload's " +
+    "identity token for, so the attester's discovery document can't choose it";
 export { ClientAttestationError, TransportError } from "./errors.js";
 const USE_DPOP_NONCE = "use_dpop_nonce";
 const DPOP_NONCE_HEADER = "DPoP-Nonce";
+/** At most this much of a 400 body is read to look for `use_dpop_nonce`; a longer body is not a challenge. */
+const MAX_NONCE_CHALLENGE_BODY = 64 * 1024;
+/** RFC 9449 nonces are short opaque strings: a longer `DPoP-Nonce` is ignored, as if there were none. */
+const MAX_DPOP_NONCE_LENGTH = 1024;
+/**
+ * At most this many origins' nonces are remembered; a new origin over the cap replaces the one stored
+ * longest ago (it costs that origin one challenge).
+ */
+const MAX_DPOP_NONCE_ORIGINS = 256;
+/** A token is cached for at most this long (seconds), whatever `expires_in` the token endpoint gives. */
+const MAX_TOKEN_LIFETIME_SECONDS = 24 * 60 * 60;
 /** What the https check calls the URL a profile's call goes to, by step. */
 const STEP_LABELS = {
     discover: "attesterUrl",
@@ -46,7 +62,7 @@ const STEP_LABELS = {
  * Gets and caches an access token using client attestation.
  *
  * `new ClientAttestation(attesterUrl, opts)`, or `new ClientAttestation(opts)` with `opts.metadata` (no
- * discovery) or a custom `opts.profile`.
+ * discovery) or a custom `opts.profile`. A client that discovers its attester needs `opts.evidenceAudience`.
  *
  * @param attesterUrl the attester's host — `"pf.example.com"`, or a full base URL
  *   `"https://pf.example.com"`. Plain hostnames default to https. Optional when `metadata` or `profile`
@@ -70,8 +86,10 @@ export class ClientAttestation {
     /** The token, its type and its bound key: always replaced together, never one without the others. */
     #state = null;
     #metadata;
+    #staticMetadata;
+    #evidenceAudience;
     #refreshing = null;
-    /** The last `DPoP-Nonce` each origin returned. */
+    /** The last `DPoP-Nonce` each origin returned, oldest first. */
     #nonces = new Map();
     constructor(attesterUrl, opts = {}) {
         if (typeof attesterUrl === "object" && attesterUrl !== null) {
@@ -81,14 +99,19 @@ export class ClientAttestation {
         const url = attesterUrl ?? opts.attesterUrl;
         this.#profile = opts.profile ?? new PingFederateProfile();
         this.#metadata = opts.metadata ?? null;
+        this.#staticMetadata = this.#metadata !== null;
+        this.#evidenceAudience = opts.evidenceAudience;
         this.#evidence = opts.evidence;
         this.#authorizationDetails = opts.authorizationDetails;
         this.#operator = opts.operator && Object.keys(opts.operator).length > 0 ? opts.operator : undefined;
         this.#challengeAtToken = opts.challengeAtToken ?? true;
         this.#algorithm = opts.algorithm ?? "ES256";
         this.#skew = opts.expirySkewSeconds ?? DEFAULT_EXPIRY_SKEW_SECONDS;
+        if (!Number.isFinite(this.#skew) || this.#skew < 0) {
+            throw new RangeError(`expirySkewSeconds must be a finite number, not negative: ${this.#skew}`);
+        }
         this.#timeoutMs = opts.timeoutMs ?? 20_000;
-        this.#popMethod = opts.popMethod ?? "attestation_pop_jwt";
+        this.#popMethod = checkPopMethod(opts.popMethod);
         this.#requireChallenge = opts.requireChallenge ?? true;
         this.#allowInsecure = opts.allowInsecure ?? false;
         this.#logger = opts.logger ?? NOOP_LOGGER;
@@ -121,16 +144,54 @@ export class ClientAttestation {
      * - DPoP token: `{ Authorization: "DPoP <t>", DPoP: <proof> }` — a fresh proof signed by the key the
      *   token is bound to, for this `method` and `url`, carrying `ath` and the last `DPoP-Nonce` the
      *   url's origin returned, if any.
+     *
+     * `url` must be https, like every other URL the client sends a credential to (loopback hosts and
+     * `allowInsecure` excepted).
+     *
+     * Pass the exact URL your HTTP client sends: the proof is only valid for the `htu` it names. A url with
+     * a backslash, ASCII whitespace or a control character before its query or fragment is refused with a
+     * {@link ClientAttestationError}, because URL parsers disagree on where it goes. For a DPoP-bound token,
+     * so is a url that is not an absolute http(s) URL with a valid ASCII host, port and path; with
+     * `popMethod: "dpop_combined"` that is checked before the token is fetched. The path is signed as
+     * written, so pass `new URL(u).href` (what `fetch` sends) rather than a hand-written string: `fetch` may
+     * escape characters (a `{`, say) that the string leaves as they are. {@link fetch} does this for you.
      */
     async requestHeaders(method, url, opts = {}) {
+        return this.#requestHeaders(method, url, opts);
+    }
+    /**
+     * {@link requestHeaders}, with the proof carrying `nonce` when given (the nonce of the challenge being
+     * answered) instead of the origin's remembered one.
+     */
+    async #requestHeaders(method, url, opts, nonce) {
+        this.#checkSecure(url, "resource URL");
+        // A client configured for DPoP checks the whole htu before fetching the token, so a URL with no htu
+        // never costs a mint and token request on a cold cache. Otherwise only what parsers disagree on is
+        // refused up front: a Bearer token carries no htu.
+        try {
+            if (this.#popMethod === DPOP_COMBINED)
+                normalizeHtu(url);
+            else
+                checkHtu(url);
+        }
+        catch (err) {
+            throw new ClientAttestationError(err.message);
+        }
         const state = await this.#current(opts);
         const headers = { Authorization: `${scheme(state)} ${state.accessToken}` };
         if (isDpop(state)) {
+            // Also for a DPoP token from a client not configured for DPoP (the AS chose the token type).
+            try {
+                normalizeHtu(url);
+            }
+            catch (err) {
+                throw new ClientAttestationError(err.message);
+            }
             headers[DPOP_HEADER] = await new DpopProofBuilder(state.key)
                 .method(method)
                 .uri(url)
                 .accessToken(state.accessToken)
-                .nonce(this.#nonces.get(originOf(url)) ?? null)
+                .nonce(nonce ?? this.#nonces.get(originOf(url)) ?? null)
                 .build();
         }
         return headers;
@@ -144,14 +205,17 @@ export class ClientAttestation {
      */
     async fetch(input, init = {}) {
         const isRequest = typeof Request !== "undefined" && input instanceof Request;
-        const url = isRequest ? input.url : String(input);
+        // The proof names the URL as fetch parses it (WHATWG), which is where the request goes.
+        const url = isRequest ? input.url : parsedHref(String(input));
         const method = (init.method ?? (isRequest ? input.method : "GET")).toUpperCase();
         // A Request's own body is cloned so the retry can send it again.
         const nextInput = () => (isRequest ? input.clone() : input);
         let dpopBound = false;
-        const send = async () => {
+        const send = async (nonce) => {
             const headers = new Headers(init.headers ?? (isRequest ? input.headers : undefined));
-            const auth = await this.requestHeaders(method, url);
+            const auth = nonce === undefined
+                ? await this.requestHeaders(method, url)
+                : await this.#requestHeaders(method, url, {}, nonce);
             dpopBound = DPOP_HEADER in auth;
             for (const [name, value] of Object.entries(auth))
                 headers.set(name, value);
@@ -160,14 +224,24 @@ export class ClientAttestation {
         const first = await send();
         if (!dpopBound)
             return first;
-        const nonce = first.headers.get(DPOP_NONCE_HEADER);
+        const nonce = usableNonce(first.headers.get(DPOP_NONCE_HEADER));
         if (nonce)
-            this.#nonces.set(originOf(url), nonce);
-        if (!nonce || !replayable(init.body) || !(await isNonceChallenge(first)))
+            this.#rememberNonce(url, nonce);
+        if (!nonce || !replayable(init.body) || !(await isNonceChallenge(first, this.#timeoutMs)))
             return first;
         emit(this.#logger, "info", "dpop.nonce_retry", { host: hostOf(url), status: first.status, at: "resource" });
         await first.body?.cancel().catch(() => undefined);
-        return send();
+        // Answer this challenge with its own nonce, not one a concurrent response stored since.
+        return send(nonce);
+    }
+    /** Store `nonce` as the origin's latest, forgetting the origin stored longest ago over the cap. */
+    #rememberNonce(url, nonce) {
+        const key = originOf(url);
+        this.#nonces.delete(key);
+        if (this.#nonces.size >= MAX_DPOP_NONCE_ORIGINS) {
+            this.#nonces.delete(this.#nonces.keys().next().value);
+        }
+        this.#nonces.set(key, nonce);
     }
     /**
      * The attester's discovery document (PingFederate: `/.well-known/client-attester`), fetched once and
@@ -201,9 +275,10 @@ export class ClientAttestation {
     /** The cached token state, or a freshly minted one. Concurrent callers share one refresh. */
     async #current(opts) {
         const state = this.#state;
-        if (!opts.forceRefresh && state && Date.now() < state.expiresAt) {
+        const now = monotonicMs();
+        if (!opts.forceRefresh && state && now < state.expiresAt) {
             emit(this.#logger, "debug", "token.cache_hit", {
-                expires_in: Math.max(0, Math.round((state.expiresAt - Date.now()) / 1000)),
+                expires_in: Math.max(0, Math.round((state.expiresAt - now) / 1000)),
             });
             return state;
         }
@@ -219,22 +294,33 @@ export class ClientAttestation {
     }
     async #refresh() {
         const { response, key } = await this.#runFlow();
-        const expiresIn = response.expires_in;
+        const lifetime = tokenLifetime(response.expires_in);
         const state = {
             accessToken: response.access_token,
             tokenType: typeof response.token_type === "string" && response.token_type ? response.token_type : "Bearer",
             key,
-            expiresAt: expiresIn ? Date.now() + (Number(expiresIn) - this.#skew) * 1000 : 0,
+            expiresAt: lifetime !== undefined ? monotonicMs() + (lifetime - this.#skew) * 1000 : 0,
         };
         this.#state = state;
         return state;
     }
     async #runFlow() {
+        // The constructor refused anything else. A value that still isn't one of the two fails here, before
+        // any request, rather than falling back to a PoP JWT.
+        if (!POP_METHODS.includes(this.#popMethod)) {
+            throw new ClientAttestationError(`unsupported popMethod ${describe(this.#popMethod)}`);
+        }
+        if (!this.#evidenceAudience && !this.#staticMetadata)
+            throw new ClientAttestationError(PIN_REQUIRED);
         const meta = await this.attesterMetadata();
         const audience = meta.evidenceAudience;
         if (!audience) {
             throw new ClientAttestationError("attester discovery document has no evidence_audience");
         }
+        if (this.#evidenceAudience && audience !== this.#evidenceAudience) {
+            throw new ClientAttestationError(`the attester asks for evidence for ${JSON.stringify(audience)}, but evidenceAudience is ` +
+                JSON.stringify(this.#evidenceAudience));
+        }
         const evidenceSource = this.#evidence ?? (await autoDetectEvidence());
         const svid = await evidenceSource.fetch(audience);
         emit(this.#logger, "debug", "evidence.obtained", { source: evidenceSource.constructor?.name });
@@ -269,26 +355,27 @@ export class ClientAttestation {
         const tokenChallenge = this.#challengeAtToken ? challenge : undefined;
         const credential = new ClientAttestationCredential(attestation, instanceKey);
         const obtained = (response) => {
-            const expiresIn = Number(response.expires_in);
+            const lifetime = tokenLifetime(response.expires_in);
             emit(this.#logger, "info", "token.obtained", {
                 host: hostOf(tokenEndpoint),
                 client_id: clientId,
                 token_type: typeof response.token_type === "string" && response.token_type ? response.token_type : "Bearer",
-                expires_in: response.expires_in != null && Number.isFinite(expiresIn) ? expiresIn : undefined,
+                expires_in: lifetime !== undefined ? Math.trunc(lifetime) : undefined,
                 pop_method: this.#popMethod,
             });
             return { response, key: instanceKey };
         };
-        if (this.#popMethod !== "dpop_combined") {
+        if (this.#popMethod === POP_JWT) {
             const headers = await credential.popHeaders(clientId, popAudience, tokenChallenge ?? null);
             return obtained(this.#tokenResponse(tokenEndpoint, await this.#postToken(tokenEndpoint, headers)));
         }
-        // DPoP combined: the attester challenge rides as the DPoP nonce. If the AS demands its own nonce
-        // (400 use_dpop_nonce + DPoP-Nonce), retry once with that — the server's demand wins.
+        // DPoP combined, the only other value (checked at the top of the flow): the attester challenge rides
+        // as the DPoP nonce. If the AS demands its own nonce (400 use_dpop_nonce + DPoP-Nonce), retry once
+        // with that — the server's demand wins.
         let res = await this.#postToken(tokenEndpoint, await credential.dpopHeaders("POST", tokenEndpoint, tokenChallenge ?? null));
-        const serverNonce = res.headers.get(DPOP_NONCE_HEADER);
+        const serverNonce = usableNonce(res.headers.get(DPOP_NONCE_HEADER));
         if (serverNonce)
-            this.#nonces.set(originOf(tokenEndpoint), serverNonce);
+            this.#rememberNonce(tokenEndpoint, serverNonce);
         if (res.status === 400 && serverNonce && jsonError(res.body) === USE_DPOP_NONCE) {
             emit(this.#logger, "info", "dpop.nonce_retry", { host: hostOf(tokenEndpoint), status: res.status, at: "token_endpoint" });
             res = await this.#postToken(tokenEndpoint, await credential.dpopHeaders("POST", tokenEndpoint, serverNonce));
@@ -362,18 +449,7 @@ export class ClientAttestation {
     }
     /** Refuse a non-https URL unless it is loopback or the caller passed `allowInsecure`. */
     #checkSecure(url, what) {
-        if (this.#allowInsecure)
-            return;
-        let parsed;
-        try {
-            parsed = new URL(url);
-        }
-        catch {
-            throw new ClientAttestationError(`${what} is not a valid URL: ${url}`);
-        }
-        if (parsed.protocol === "https:" || LOOPBACK_HOSTS.has(parsed.hostname.toLowerCase()))
-            return;
-        throw new ClientAttestationError(`${what} must use https: ${url} (loopback hosts are exempt; pass allowInsecure: true to override)`);
+        checkSecure(url, what, this.#allowInsecure);
     }
     async #getJson(step, method, url, jsonBody) {
         const headers = { Accept: "application/json" };
@@ -406,30 +482,63 @@ export class ClientAttestation {
         }
     }
 }
-const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
 function tokenResponse(res) {
     if (!res.ok) {
         throw new ClientAttestationError(`token endpoint returned HTTP ${res.status}`, {
             status: res.status,
-            body: res.body,
+            body: snippet(res.body),
         });
     }
     const parsed = jsonOk(res, { allowEmpty: true });
     if (!parsed.access_token) {
-        throw new ClientAttestationError("token endpoint returned no access_token", { body: res.body });
+        // No body: a 2xx token response may hold the token under another name.
+        throw new ClientAttestationError("token endpoint returned no access_token");
     }
     return parsed;
 }
+/**
+ * How long to cache a token, in seconds: `expires_in` as a JSON number, or a string of decimal digits,
+ * capped at {@link MAX_TOKEN_LIFETIME_SECONDS}. Anything else - missing, null, not a number, not finite,
+ * zero or negative - is undefined, and the token is not cached, as with no `expires_in` at all.
+ */
+function tokenLifetime(expiresIn) {
+    let seconds;
+    if (typeof expiresIn === "number")
+        seconds = expiresIn;
+    else if (typeof expiresIn === "string" && /^[0-9]+(\.[0-9]+)?$/.test(expiresIn))
+        seconds = Number(expiresIn);
+    else
+        return undefined;
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        return undefined;
+    return Math.min(seconds, MAX_TOKEN_LIFETIME_SECONDS);
+}
 function isDpop(state) {
     return state.tokenType.toLowerCase() === "dpop";
 }
 function scheme(state) {
     return isDpop(state) ? "DPoP" : "Bearer";
 }
-/** `scheme://host[:port]` of a URL, the key DPoP nonces are remembered under. */
+/** A `DPoP-Nonce` value, or null when there is none or it is longer than {@link MAX_DPOP_NONCE_LENGTH}. */
+function usableNonce(nonce) {
+    return nonce && nonce.length <= MAX_DPOP_NONCE_LENGTH ? nonce : null;
+}
+/** `url` as WHATWG URL parsing (and so fetch) serialises it, or as given when it does not parse. */
+function parsedHref(url) {
+    try {
+        return new URL(url).href;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * `scheme://host[:port]` of a URL as its `htu` names it ({@link htuParts}), the key DPoP nonces are
+ * remembered under. A URL that rule refuses is its own key.
+ */
 function originOf(url) {
     try {
-        return new URL(url).origin;
+        return htuParts(url)[0];
     }
     catch {
         return url;
@@ -453,18 +562,64 @@ function replayable(body) {
 }
 /**
  * RFC 9449 section 9: a resource asks for a nonce with 401 + `WWW-Authenticate: DPoP error="use_dpop_nonce"`;
- * section 8 (and some resources) use a 400 JSON `{"error":"use_dpop_nonce"}`.
+ * section 8 (and some resources) use a 400 JSON `{"error":"use_dpop_nonce"}`. The 400 body is read from a
+ * clone, at most {@link MAX_NONCE_CHALLENGE_BODY} bytes and for at most `timeoutMs`, so the caller still
+ * gets the whole body.
  */
-async function isNonceChallenge(res) {
+async function isNonceChallenge(res, timeoutMs) {
     if (res.status === 401) {
         const challenge = res.headers.get("WWW-Authenticate") ?? "";
         return /(^|,)\s*DPoP\b/i.test(challenge) && /error\s*=\s*"?use_dpop_nonce"?/i.test(challenge);
     }
     if (res.status === 400) {
-        return jsonError(await res.clone().text()) === USE_DPOP_NONCE;
+        const body = await peekBody(res, MAX_NONCE_CHALLENGE_BODY, timeoutMs);
+        return body !== undefined && jsonError(body) === USE_DPOP_NONCE;
     }
     return false;
 }
+/**
+ * The text of `res`'s body read from a clone, or undefined when it is longer than `maxBytes`, fails, or is
+ * not complete within `timeoutMs`. The clone is cancelled once read, so no more than about `maxBytes` is
+ * buffered for the caller's copy.
+ */
+async function peekBody(res, maxBytes, timeoutMs) {
+    const reader = res.clone().body?.getReader();
+    if (!reader)
+        return "";
+    let timer;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(undefined), timeoutMs);
+    });
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const next = await Promise.race([reader.read(), expired]);
+            if (next === undefined)
+                return undefined;
+            if (next.done)
+                break;
+            total += next.value.byteLength;
+            if (total > maxBytes)
+                return undefined;
+            chunks.push(next.value);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+        reader.cancel().catch(() => undefined);
+    }
+    const all = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        all.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return utf8Decode(all);
+}
 /**
  * Compact JSON with object keys sorted at every depth and non-ASCII escaped as `\uXXXX` - the same
  * bytes as Python's `json.dumps(value, separators=(",", ":"), sort_keys=True)`.
@@ -483,6 +638,37 @@ function sortKeys(value) {
     }
     return value;
 }
+/**
+ * The PoP method to use. `undefined`, `null` or `""` (unset) is the default; any other value must be
+ * exactly one of the two the draft names (case-sensitive), so a misspelt value can't quietly send a PoP
+ * JWT (vectors/pop-method.json).
+ */
+function checkPopMethod(popMethod) {
+    if (popMethod === undefined || popMethod === null || popMethod === "")
+        return POP_JWT;
+    const known = POP_METHODS.find((name) => name === popMethod);
+    if (known === undefined) {
+        throw new RangeError(`popMethod must be "${POP_JWT}" or "${DPOP_COMBINED}", got ${describe(popMethod)}`);
+    }
+    return known;
+}
+/** A value for an error message: JSON where that works, never a throw (BigInt, a cycle, a symbol). */
+function describe(value) {
+    try {
+        const json = JSON.stringify(value);
+        if (json !== undefined)
+            return json;
+    }
+    catch {
+        // fall through
+    }
+    try {
+        return typeof value === "bigint" ? `${value}n` : String(value);
+    }
+    catch {
+        return Object.prototype.toString.call(value);
+    }
+}
 /** @internal */
 export function normalizeBaseUrl(attesterUrl) {
     let host = (attesterUrl ?? "").trim().replace(/\/+$/, "");

package/dist/validator/config.d.ts

@@ -15,7 +15,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;
 }
 /**
@@ -31,6 +35,10 @@ export interface IntrospectionConfig {
  * 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.
  */
 export interface ValidatorConfig {
     issuer: string;
@@ -45,6 +53,8 @@ export interface ValidatorConfig {
     introspection?: IntrospectionConfig;
     /** Defaults to {@link DEFAULT_TOKEN_TYPES}; `null` disables the `typ` check. */
     acceptedTokenTypes?: string[] | null;
+    /** Allow a plain-http `jwksUri` and introspection `endpoint` on non-loopback hosts. Defaults to `false`. */
+    allowInsecure?: boolean;
 }
 /** A {@link ValidatorConfig} with every optional field defaulted. */
 export interface ResolvedConfig {

package/dist/validator/config.js

@@ -33,8 +33,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 +71,60 @@ 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");
+    }
+    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),
     };
 }
+/** 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

@@ -16,4 +16,4 @@ 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.2.0";

package/dist/validator/index.js

@@ -9,4 +9,4 @@ export { AccessTokenValidator } from "./validator.js";
 export { DEFAULT_ALGORITHMS, DEFAULT_TOKEN_TYPES } 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.2.0";