@idpartners/client-attestation-sdk 1.2.0 → 1.4.0

package/dist/attester.d.ts

@@ -7,8 +7,14 @@ export interface AttesterMetadata {
     attestationEndpoint?: string;
     /** The authorization server's token endpoint. A profile fills in its own fallback. */
     tokenEndpoint?: string;
-    /** The draft's challenge endpoint, if the attester issues challenges. */
+    /** The attester's challenge endpoint (CAS section 4.1), if the attester issues challenges for the mint. */
     challengeEndpoint?: string;
+    /**
+     * The authorization server's challenge endpoint (draft -11 section 6.3), if it issues challenges for
+     * the token request: `POST`ed before each token request, and its `attestation_challenge` carried as
+     * the PoP JWT's `challenge` claim or the DPoP proof's `nonce`. PingFederate: `/federation/attestation-challenge`.
+     */
+    tokenChallengeEndpoint?: string;
     /** The Client Attestation PoP `aud` (the AS issuer); falls back to the token endpoint URL. */
     popAudience?: string;
     /** The raw discovery document, when there was one; returned by `ClientAttestation.discovery()`. */
@@ -85,8 +91,8 @@ export declare const INSTANCE_PROOF_TYP = "oauth-attestation-instance-proof+jwt"
  * The attester this SDK was built against (PingFederate), and the default.
  *
  * - Discovery: `GET {attesterUrl}/.well-known/client-attester`, a JSON object with `evidence_audience`,
- *   `attestation_endpoint`, `challenge_endpoint`, `token_endpoint` and `pop_audience`. With no
- *   `token_endpoint`, `{attesterUrl}/as/token.oauth2`.
+ *   `attestation_endpoint`, `challenge_endpoint`, `token_endpoint`, `token_challenge_endpoint` and
+ *   `pop_audience`. With no `token_endpoint`, `{attesterUrl}/as/token.oauth2`.
  * - Mint: `POST attestation_endpoint` with JSON `{[client_id,] instance_key, svid, proof
  *   [, authorization_details][, operator]}`, where `proof` is `{aud: evidence_audience, jti, iat
  *   [, challenge]}` signed by the instance key with `typ` `oauth-attestation-instance-proof+jwt`. The

package/dist/attester.js

@@ -86,8 +86,8 @@ export const INSTANCE_PROOF_TYP = "oauth-attestation-instance-proof+jwt";
  * The attester this SDK was built against (PingFederate), and the default.
  *
  * - Discovery: `GET {attesterUrl}/.well-known/client-attester`, a JSON object with `evidence_audience`,
- *   `attestation_endpoint`, `challenge_endpoint`, `token_endpoint` and `pop_audience`. With no
- *   `token_endpoint`, `{attesterUrl}/as/token.oauth2`.
+ *   `attestation_endpoint`, `challenge_endpoint`, `token_endpoint`, `token_challenge_endpoint` and
+ *   `pop_audience`. With no `token_endpoint`, `{attesterUrl}/as/token.oauth2`.
  * - Mint: `POST attestation_endpoint` with JSON `{[client_id,] instance_key, svid, proof
  *   [, authorization_details][, operator]}`, where `proof` is `{aud: evidence_audience, jti, iat
  *   [, challenge]}` signed by the instance key with `typ` `oauth-attestation-instance-proof+jwt`. The
@@ -109,6 +109,7 @@ export class PingFederateProfile {
             // discovery document still works from the host alone.
             tokenEndpoint: str("token_endpoint") ?? attesterUrl + PingFederateProfile.DEFAULT_TOKEN_PATH,
             challengeEndpoint: str("challenge_endpoint"),
+            tokenChallengeEndpoint: str("token_challenge_endpoint"),
             popAudience: str("pop_audience"),
             document: doc,
         };
@@ -154,6 +155,7 @@ export function metadataDocument(metadata) {
         ["attestation_endpoint", metadata.attestationEndpoint],
         ["challenge_endpoint", metadata.challengeEndpoint],
         ["token_endpoint", metadata.tokenEndpoint],
+        ["token_challenge_endpoint", metadata.tokenChallengeEndpoint],
         ["pop_audience", metadata.popAudience],
     ];
     for (const [key, value] of fields)

package/dist/credential.d.ts

@@ -2,6 +2,8 @@ import { SigningKeyPair } from "./signing-key-pair.js";
 export declare const ATTESTATION_HEADER = "OAuth-Client-Attestation";
 export declare const POP_HEADER = "OAuth-Client-Attestation-PoP";
 export declare const DPOP_HEADER = "DPoP";
+/** The response header a `use_attestation_challenge` refusal carries a fresh challenge in (draft -11 section 6.1). */
+export declare const CHALLENGE_HEADER = "OAuth-Client-Attestation-Challenge";
 /**
  * The Attester-issued attestation JWT plus the instance key it is bound to. Produces the
  * token-request headers — PoP-JWT mode or DPoP combined mode — minting a fresh proof each call.

package/dist/credential.js

@@ -6,6 +6,8 @@ import { requireText } from "./signing-key-pair.js";
 export const ATTESTATION_HEADER = "OAuth-Client-Attestation";
 export const POP_HEADER = "OAuth-Client-Attestation-PoP";
 export const DPOP_HEADER = "DPoP";
+/** The response header a `use_attestation_challenge` refusal carries a fresh challenge in (draft -11 section 6.1). */
+export const CHALLENGE_HEADER = "OAuth-Client-Attestation-Challenge";
 /**
  * The Attester-issued attestation JWT plus the instance key it is bound to. Produces the
  * token-request headers — PoP-JWT mode or DPoP combined mode — minting a fresh proof each call.

package/dist/index.d.ts

@@ -7,7 +7,7 @@
  */
 export { SigningKeyPair } from "./signing-key-pair.js";
 export { ClientAttestationBuilder, DpopProofBuilder, PopBuilder, ATTESTATION_TYP, POP_TYP, DPOP_TYP, } from "./builders.js";
-export { ClientAttestationCredential, ATTESTATION_HEADER, POP_HEADER, DPOP_HEADER, } from "./credential.js";
+export { ClientAttestationCredential, ATTESTATION_HEADER, POP_HEADER, DPOP_HEADER, CHALLENGE_HEADER, } from "./credential.js";
 export { OpenBaoTransitSigner } from "./signer.js";
 export type { JwsSigner } from "./signer.js";
 export { AttestationIssuanceClient, IssuedAttestation, IssuanceError, INSTANCE_PROOF_TYP, } from "./issuance.js";
@@ -21,6 +21,10 @@ export type { AttesterMetadata, AttesterProfile, AttesterTransport, MintResult }
 export type { TransportFailure } from "./errors.js";
 export { NOOP_LOGGER } from "./logging.js";
 export type { Logger, LogAttributes, LogLevel } from "./logging.js";
-export declare const VERSION = "1.2.0";
-/** draft-ietf-oauth-attestation-based-client-auth revision this SDK implements. */
-export declare const DRAFT_REVISION = "10";
+export declare const VERSION = "1.4.0";
+/**
+ * draft-ietf-oauth-attestation-based-client-auth revision this port implements. -11 (the Go, Java and
+ * Python ports are at -10): the authorization server's challenge endpoint and the
+ * `use_attestation_challenge` retry, with combined mode on RFC 9449 nonces alone.
+ */
+export declare const DRAFT_REVISION = "11";

package/dist/index.js

@@ -7,7 +7,7 @@
  */
 export { SigningKeyPair } from "./signing-key-pair.js";
 export { ClientAttestationBuilder, DpopProofBuilder, PopBuilder, ATTESTATION_TYP, POP_TYP, DPOP_TYP, } from "./builders.js";
-export { ClientAttestationCredential, ATTESTATION_HEADER, POP_HEADER, DPOP_HEADER, } from "./credential.js";
+export { ClientAttestationCredential, ATTESTATION_HEADER, POP_HEADER, DPOP_HEADER, CHALLENGE_HEADER, } from "./credential.js";
 export { OpenBaoTransitSigner } from "./signer.js";
 export { AttestationIssuanceClient, IssuedAttestation, IssuanceError, INSTANCE_PROOF_TYP, } from "./issuance.js";
 export { StaticSvidSource, HttpSvidSource, SpireWorkloadApiSvidSource, } from "./svid-source.js";
@@ -15,6 +15,10 @@ export { EvidenceNotFound, FileTokenSvidSource, GoogleMetadataSvidSource, autoDe
 export { ClientAttestation, ClientAttestationError, TransportError, DEFAULT_EXPIRY_SKEW_SECONDS, } from "./token-source.js";
 export { MintRequest, PingFederateProfile } from "./attester.js";
 export { NOOP_LOGGER } from "./logging.js";
-export const VERSION = "1.2.0";
-/** draft-ietf-oauth-attestation-based-client-auth revision this SDK implements. */
-export const DRAFT_REVISION = "10";
+export const VERSION = "1.4.0";
+/**
+ * draft-ietf-oauth-attestation-based-client-auth revision this port implements. -11 (the Go, Java and
+ * Python ports are at -10): the authorization server's challenge endpoint and the
+ * `use_attestation_challenge` retry, with combined mode on RFC 9449 nonces alone.
+ */
+export const DRAFT_REVISION = "11";

package/dist/svid-source.d.ts

@@ -34,9 +34,10 @@ export declare class HttpSvidSource implements SvidSource {
  * and at most 1 MiB in all (a helper the agent started can inherit the pipe and keep writing to it or hold
  * it open), then the pipe is closed. On exit status 0 what was read is parsed; on any other status, or if
  * the agent was killed, `fetch` rejects. So output a helper writes after the agent has exited never turns a
- * success into a failure, and never keeps `fetch` waiting longer than that. If reading stopped at the
- * 1 MiB or at the end of the 250 ms, the last line may be cut off, so a token is only taken from a line
- * that ends in a newline.
+ * success into a failure, and never keeps `fetch` waiting longer than that. A token is only taken from a
+ * line that ends in a newline, whether or not stdout was read to its end: if reading stopped at the 1 MiB
+ * or at the end of the 250 ms the last line may be cut off, and no port can tell that from an agent whose
+ * last line lacks a newline (real spire-agent output always ends in one), so every port refuses it.
  *
  * Needs Node.js (it spawns a process): `node:child_process` is loaded on the first `fetch`, which throws
  * a `ClientAttestationError` on a runtime without it.

package/dist/svid-source.js

@@ -65,9 +65,10 @@ export class HttpSvidSource {
  * and at most 1 MiB in all (a helper the agent started can inherit the pipe and keep writing to it or hold
  * it open), then the pipe is closed. On exit status 0 what was read is parsed; on any other status, or if
  * the agent was killed, `fetch` rejects. So output a helper writes after the agent has exited never turns a
- * success into a failure, and never keeps `fetch` waiting longer than that. If reading stopped at the
- * 1 MiB or at the end of the 250 ms, the last line may be cut off, so a token is only taken from a line
- * that ends in a newline.
+ * success into a failure, and never keeps `fetch` waiting longer than that. A token is only taken from a
+ * line that ends in a newline, whether or not stdout was read to its end: if reading stopped at the 1 MiB
+ * or at the end of the 250 ms the last line may be cut off, and no port can tell that from an agent whose
+ * last line lacks a newline (real spire-agent output always ends in one), so every port refuses it.
  *
  * Needs Node.js (it spawns a process): `node:child_process` is loaded on the first `fetch`, which throws
  * a `ClientAttestationError` on a runtime without it.
@@ -86,7 +87,7 @@ export class SpireWorkloadApiSvidSource {
         const { spawn } = await importNodeBuiltin("child_process", "SpireWorkloadApiSvidSource");
         // stdout only: stderr goes to the null device, so a log line or version string the agent writes there
         // is never parsed, and a flood of it is never held in memory.
-        const { stdout, complete } = await new Promise((resolve, reject) => {
+        const stdout = await new Promise((resolve, reject) => {
             const args = ["api", "fetch", "jwt", "-audience", audience, "-socketPath", this.socketPath];
             const child = spawn(this.spireAgentBin, args, {
                 stdio: ["ignore", "pipe", "ignore"],
@@ -96,7 +97,6 @@ export class SpireWorkloadApiSvidSource {
             const chunks = [];
             let size = 0;
             let over = false; // past the cap while the agent was running
-            let ended = false; // stdout was read to its end
             let exited;
             let settled = false;
             let grace;
@@ -114,7 +114,7 @@ export class SpireWorkloadApiSvidSource {
                     reject(Object.assign(new Error(message), { code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" }));
                 }
                 else if (code === 0) {
-                    resolve({ stdout: concatUtf8(chunks, size), complete: ended });
+                    resolve(concatUtf8(chunks, size));
                 }
                 else {
                     reject(spireAgentExitFailure(code, signal, child.killed));
@@ -141,10 +141,6 @@ export class SpireWorkloadApiSvidSource {
                 size += chunk.length;
                 chunks.push(chunk);
             });
-            child.stdout?.on("end", () => {
-                if (!settled)
-                    ended = true;
-            });
             child.stdout?.on("error", () => { }); // the outcome comes from "exit" or "close"
             child.on("error", (err) => {
                 if (settled)
@@ -164,9 +160,10 @@ export class SpireWorkloadApiSvidSource {
             });
             child.on("close", (code, signal) => settle(code, signal));
         });
-        // If reading stopped before the end of stdout (at the cap or the end of the grace period), the line
-        // after the last newline may have been cut off.
-        const svid = parseSpireJwtOutput(complete ? stdout : stdout.slice(0, stdout.lastIndexOf("\n") + 1));
+        // A token is only taken from a line that ends in a newline: the line after the last newline may have been
+        // cut off (reading stopped at the cap or the end of the grace period), and whether stdout was read to its
+        // end can't tell that apart from an agent whose last line lacks a newline, so every port refuses it.
+        const svid = parseSpireJwtOutput(stdout.slice(0, stdout.lastIndexOf("\n") + 1));
         if (svid)
             return svid;
         // The output may hold a token or bundle that failed to parse, so the error gives only its size.

package/dist/token-source.d.ts

@@ -13,6 +13,7 @@ export interface AttesterDiscovery {
     attestation_endpoint?: string;
     challenge_endpoint?: string;
     token_endpoint?: string;
+    token_challenge_endpoint?: string;
     pop_audience?: string;
 }
 /** Options for {@link ClientAttestation}. */

package/dist/token-source.js

@@ -21,7 +21,7 @@
  */
 import { base64url } from "jose";
 import { checkHtu, DpopProofBuilder, htuParts, normalizeHtu } from "./builders.js";
-import { ClientAttestationCredential, DPOP_HEADER } from "./credential.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";
@@ -29,6 +29,7 @@ import { checkSecure, jsonOk, request, snippet } from "./http.js";
 import { emit, failureReason, hostOf, NOOP_LOGGER, urlParts } from "./logging.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. */
@@ -41,6 +42,8 @@ const PIN_REQUIRED = "evidenceAudience is required: set it to the audience your
 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. */
@@ -57,6 +60,7 @@ 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.
@@ -122,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. */
@@ -325,7 +337,7 @@ export class ClientAttestation {
         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,
@@ -349,10 +361,17 @@ 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 lifetime = tokenLifetime(response.expires_in);
@@ -366,12 +385,23 @@ export class ClientAttestation {
             return { response, key: instanceKey };
         };
         if (this.#popMethod === POP_JWT) {
-            const headers = await credential.popHeaders(clientId, popAudience, tokenChallenge ?? null);
-            return obtained(this.#tokenResponse(tokenEndpoint, await this.#postToken(tokenEndpoint, headers)));
+            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 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.
+        // 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 = usableNonce(res.headers.get(DPOP_NONCE_HEADER));
         if (serverNonce)
@@ -382,21 +412,26 @@ export class ClientAttestation {
         }
         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}`, {
@@ -407,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`);
@@ -568,8 +603,9 @@ function replayable(body) {
  */
 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) {
         const body = await peekBody(res, MAX_NONCE_CHALLENGE_BODY, timeoutMs);

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";
 /**
@@ -28,9 +30,11 @@ 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
@@ -39,6 +43,12 @@ export interface IntrospectionConfig {
  * `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;
@@ -51,10 +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 {
@@ -68,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
@@ -84,6 +86,14 @@ export function resolveConfig(config) {
     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);
     }
@@ -120,6 +130,8 @@ export function resolveConfig(config) {
             ? 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). */

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.2.0";
+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.2.0";
+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
@@ -65,6 +67,7 @@ export class JwksProvider {
     #httpGet;
     #minRefreshMs;
     #maxAgeMs;
+    #maxStaleMs;
     #clock;
     #logger;
     /** The usable keys, in document order: kid-less JWKs are distinct keys, and the first of a duplicate kid wins. */
@@ -81,6 +84,12 @@ 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.#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) {
@@ -126,6 +135,11 @@ export class JwksProvider {
             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, alg);
         if (entry === undefined) {
@@ -148,8 +162,21 @@ export class JwksProvider {
         }
         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);
+    }
+    /** 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
@@ -182,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/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;
@@ -114,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) {

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 {};

package/dist/www-authenticate.js

@@ -0,0 +1,114 @@
+/**
+ * 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
+ */
+const TCHAR = /[!#$%&'*+\-.^_`|~0-9A-Za-z]/;
+const TOKEN68 = /[\-._~+/0-9A-Za-z]/;
+function ows(s, i) {
+    while (i < s.length && (s[i] === " " || s[i] === "\t"))
+        i++;
+    return i;
+}
+function token(s, i) {
+    while (i < s.length && TCHAR.test(s[i]))
+        i++;
+    return i;
+}
+function token68(s, i) {
+    const start = i;
+    while (i < s.length && TOKEN68.test(s[i]))
+        i++;
+    if (i === start)
+        return undefined;
+    while (s[i] === "=")
+        i++;
+    const k = ows(s, i);
+    return k === s.length || s[k] === "," ? i : undefined;
+}
+function qdtext(c) {
+    return c === 0x09 || c === 0x20 || c === 0x21 || (c >= 0x23 && c <= 0x5b) || (c >= 0x5d && c <= 0x7e) || c >= 0x80;
+}
+function quotedPairChar(c) {
+    return c === 0x09 || (c >= 0x20 && c <= 0x7e) || c >= 0x80;
+}
+/** A token or quoted-string at `i`: [value, index after it], or undefined. */
+function value(s, i) {
+    if (s[i] === '"') {
+        let out = "";
+        for (i++; i < s.length;) {
+            const c = s.charCodeAt(i);
+            if (c === 0x22)
+                return [out, i + 1];
+            if (c === 0x5c) {
+                if (i + 1 >= s.length || !quotedPairChar(s.charCodeAt(i + 1)))
+                    return undefined;
+                out += s[i + 1];
+                i += 2;
+            }
+            else if (qdtext(c)) {
+                out += s[i];
+                i++;
+            }
+            else {
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+    const k = token(s, i);
+    return k > i ? [s.slice(i, k), k] : undefined;
+}
+/**
+ * Every field value of a WWW-Authenticate header, combined as one list (RFC 9110 section 5.3), as
+ * challenges; undefined when the combined value is malformed.
+ * @internal
+ */
+export function parseWwwAuthenticate(values) {
+    const s = values.join(", ");
+    const out = [];
+    let i = 0;
+    for (;;) {
+        while (i < s.length && (s[i] === " " || s[i] === "\t" || s[i] === ","))
+            i++;
+        if (i >= s.length)
+            return out;
+        const start = i;
+        i = token(s, i);
+        if (i === start)
+            return undefined;
+        const name = s.slice(start, i).toLowerCase();
+        const j = ows(s, i);
+        if (s[j] === "=") {
+            if (out.length === 0)
+                return undefined;
+            const got = value(s, ows(s, j + 1));
+            if (got === undefined)
+                return undefined;
+            const params = out[out.length - 1].params;
+            if (params.has(name))
+                return undefined;
+            params.set(name, got[0]);
+            i = got[1];
+        }
+        else {
+            out.push({ scheme: name, params: new Map() });
+            const k = j > i ? token68(s, j) : undefined;
+            if (k === undefined) {
+                i = j; // its first auth-param (if any) follows without a comma
+                continue;
+            }
+            i = k;
+        }
+        i = ows(s, i);
+        if (i < s.length && s[i] !== ",")
+            return undefined;
+    }
+}
+/** A DPoP challenge whose error is exactly "use_dpop_nonce" (RFC 9449 section 9). @internal */
+export function isDpopNonceChallenge(values) {
+    const challenges = parseWwwAuthenticate(values);
+    return challenges !== undefined &&
+        challenges.some((c) => c.scheme === "dpop" && c.params.get("error") === "use_dpop_nonce");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idpartners/client-attestation-sdk",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Client-side builder SDK for OAuth Attestation-Based Client Authentication",
   "type": "module",
   "main": "dist/index.js",
@@ -50,6 +50,7 @@
     "@types/node": "^20.0.0",
     "@vitest/coverage-v8": "^4.1.11",
     "esbuild": "^0.28.1",
+    "fast-check": "4.10.2",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",