@idpartners/client-attestation-sdk 1.0.1 → 1.4.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,33 +20,53 @@
  *     const headers = await ca.requestHeaders("GET", "https://api.example.com/things");
  */
 import { base64url } from "jose";
-import { DpopProofBuilder } from "./builders.js";
-import { ClientAttestationCredential, DPOP_HEADER } from "./credential.js";
+import { checkHtu, DpopProofBuilder, htuParts, normalizeHtu } from "./builders.js";
+import { CHALLENGE_HEADER, 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";
+import { isDpopNonceChallenge } from "./www-authenticate.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";
+/** draft -11 section 6.1: the refusal a server that uses challenges answers a PoP-JWT request without one. */
+const USE_ATTESTATION_CHALLENGE = "use_attestation_challenge";
+/** 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",
     mint: "attestation_endpoint",
     challenge: "challenge_endpoint",
+    token_challenge: "token_challenge_endpoint",
 };
 /**
  * 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 +90,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 +103,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;
@@ -99,6 +126,14 @@ export class ClientAttestation {
             this.baseUrl = normalizeBaseUrl(url);
             this.#checkSecure(this.baseUrl, "attesterUrl");
         }
+        // A client given an evidence source is set up to mint, and a client that discovers its attester needs the
+        // pin to mint: without it the discovery document would choose the audience the workload's identity token
+        // is for. Refused here, at startup, not at the first token(); last, so a bad URL or option is reported as
+        // itself first. A pin-less client with auto-detected evidence still builds (attesterMetadata() needs no
+        // pin); runFlow refuses its token().
+        if (this.#evidence != null && !this.#evidenceAudience && !this.#staticMetadata) {
+            throw new ClientAttestationError(PIN_REQUIRED);
+        }
     }
     // ── public API ──────────────────────────────────────────────────────────────────────────────────
     /** Return a valid access token, minting a new one only when the cached one is near expiry. */
@@ -121,16 +156,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 +217,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 +236,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 +287,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,27 +306,38 @@ 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 });
         const instanceKey = await SigningKeyPair.generate(this.#algorithm);
-        const challenge = await this.#fetchChallenge(meta.challengeEndpoint);
+        const challenge = await this.#fetchChallenge(meta.challengeEndpoint, "attester");
         const { attestation } = await this.#profile.mint(this.#transport(), meta, new MintRequest({
             instanceKey,
             evidence: svid,
@@ -263,53 +361,77 @@ export class ClientAttestation {
         // Falling back to the token endpoint URL only works when the dialed URL matches PF's issuer (no
         // proxy in between) — so prefer the advertised value.
         const popAudience = meta.popAudience || tokenEndpoint;
-        // See `challengeAtToken`: some attesters consume the challenge the moment the mint's instance
-        // proof uses it, and reject a token request that presents the same value a second time. Against
-        // one of those, only the mint gets the challenge.
-        const tokenChallenge = this.#challengeAtToken ? challenge : undefined;
+        // The challenge the token-endpoint proof carries: the authorization server's own, from its challenge
+        // endpoint (draft -11 section 6.3), when the metadata names one; else the attester's (see
+        // `challengeAtToken`: some attesters consume the challenge the moment the mint's instance proof uses
+        // it, and reject a token request that presents the same value a second time; against one of those,
+        // only the mint gets the challenge). A challenge the server demands in a refusal (section 6.1
+        // `use_attestation_challenge`, or RFC 9449 `use_dpop_nonce` in combined mode) wins over either.
+        const tokenChallenge = meta.tokenChallengeEndpoint
+            ? await this.#fetchChallenge(meta.tokenChallengeEndpoint, "authorization_server")
+            : 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") {
-            const headers = await credential.popHeaders(clientId, popAudience, tokenChallenge ?? null);
-            return obtained(this.#tokenResponse(tokenEndpoint, await this.#postToken(tokenEndpoint, headers)));
+        if (this.#popMethod === POP_JWT) {
+            let res = await this.#postToken(tokenEndpoint, await credential.popHeaders(clientId, popAudience, tokenChallenge ?? null));
+            // draft -11 section 6.1: a server that uses challenges refuses a request without a usable one as
+            // 400 use_attestation_challenge and always carries a fresh challenge in
+            // OAuth-Client-Attestation-Challenge. Send once more with that one. A refusal with no header
+            // (or one too long to be a challenge), any other error, or a second refusal is the error the
+            // caller sees: a server that keeps refusing is not retried in a loop.
+            const served = usableNonce(res.headers.get(CHALLENGE_HEADER));
+            if (res.status === 400 && served && jsonError(res.body) === USE_ATTESTATION_CHALLENGE) {
+                emit(this.#logger, "info", "pop.challenge_retry", { host: hostOf(tokenEndpoint), status: res.status, at: "token_endpoint" });
+                res = await this.#postToken(tokenEndpoint, await credential.popHeaders(clientId, popAudience, served));
+            }
+            return obtained(this.#tokenResponse(tokenEndpoint, res));
         }
-        // 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 challenge rides as the
+        // DPoP nonce, and RFC 9449's nonce mechanism is the only challenge mechanism in this mode (draft -11
+        // section 5.2: no `challenge` claim, no OAuth-Client-Attestation-Challenge). 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));
         }
         return obtained(this.#tokenResponse(tokenEndpoint, res));
     }
-    async #fetchChallenge(endpoint) {
+    /**
+     * `POST` a challenge endpoint - the attester's (CAS section 4.1, for the mint) or the authorization
+     * server's (draft -11 section 6.3, for the token request); both answer `{"attestation_challenge"}`.
+     */
+    async #fetchChallenge(endpoint, at) {
         if (!endpoint)
             return undefined;
-        this.#checkSecure(endpoint, "challenge_endpoint");
-        // The attester advertised a challenge, so minting without one weakens replay protection: fail
+        const step = at === "attester" ? "challenge" : "token_challenge";
+        this.#checkSecure(endpoint, STEP_LABELS[step]);
+        // The server advertised a challenge, so going on without one weakens replay protection: fail
         // closed unless the caller opted out with requireChallenge: false.
         let body;
         try {
-            body = await this.#getJson("challenge", "POST", endpoint);
+            body = await this.#getJson(step, "POST", endpoint);
         }
         catch (err) {
             if (!(err instanceof ClientAttestationError))
                 throw err;
             if (!this.#requireChallenge) {
-                emit(this.#logger, "warn", "challenge.skipped", { host: hostOf(endpoint) });
+                emit(this.#logger, "warn", "challenge.skipped", { host: hostOf(endpoint), at });
                 return undefined;
             }
             throw new ClientAttestationError(`could not fetch the attestation challenge from ${endpoint}: ${err.message}`, {
@@ -320,11 +442,11 @@ export class ClientAttestation {
         }
         const challenge = body.attestation_challenge;
         if (typeof challenge === "string" && challenge) {
-            emit(this.#logger, "debug", "challenge.fetched", { host: hostOf(endpoint) });
+            emit(this.#logger, "debug", "challenge.fetched", { host: hostOf(endpoint), at });
             return challenge;
         }
         if (!this.#requireChallenge) {
-            emit(this.#logger, "warn", "challenge.skipped", { host: hostOf(endpoint) });
+            emit(this.#logger, "warn", "challenge.skipped", { host: hostOf(endpoint), at });
             return undefined;
         }
         throw new ClientAttestationError(`challenge endpoint ${endpoint} returned no attestation_challenge`);
@@ -362,18 +484,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 +517,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 +597,65 @@ 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);
+        // fetch's Headers hands back the fields combined as one list (RFC 9110 section 5.3)
+        const challenge = res.headers.get("WWW-Authenticate");
+        return challenge !== null && isDpopNonceChallenge([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 +674,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(/\/+$/, "");