@idpartners/client-attestation-sdk 0.2.0 → 1.0.1

package/dist/svid-source.js

@@ -3,10 +3,8 @@
  * bootstrapping ({@link AttestationIssuanceClient}). The default {@link SpireWorkloadApiSvidSource}
  * fetches it from a real SPIRE agent; the others cover dev and tests.
  */
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
 import { jsonOk, request } from "./http.js";
-const execFileAsync = promisify(execFile);
+import { importNodeBuiltin } from "./runtime.js";
 /** Per-call timeout for {@link HttpSvidSource}. */
 const HTTP_SVID_TIMEOUT_MS = 20_000;
 /** A fixed, pre-fetched SVID — for tests, or when the caller already holds one. */
@@ -19,7 +17,15 @@ export class StaticSvidSource {
         return this.svid;
     }
 }
-/** GET a URL returning `{"svid":"<jwt>"}` — e.g. the demo harness `/dev/svid` endpoint. */
+/**
+ * GET a URL returning `{"svid":"<jwt>"}` — e.g. the demo harness `/dev/svid` endpoint.
+ *
+ * For development and testing only. It trusts whatever the URL returns and the endpoint has no caller
+ * authentication, so anyone who can reach it can obtain the workload's SVID. In production use a SPIRE,
+ * file or cloud source.
+  *
+  * @experimental See docs/api.md: a development and test source with no caller authentication.
+ */
 export class HttpSvidSource {
     url;
     constructor(url) {
@@ -37,6 +43,12 @@ export class HttpSvidSource {
  * The default source: fetch a JWT-SVID from a real SPIRE agent's Workload API via the `spire-agent`
  * CLI. Swap for a native Workload API client by implementing {@link SvidSource} if you prefer no
  * subprocess.
+ *
+ * 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.
+  *
+  * @experimental See docs/api.md: it shells out to the spire-agent CLI, and its constructor will change
+  * when it moves to the Workload API socket.
  */
 export class SpireWorkloadApiSvidSource {
     socketPath;
@@ -46,9 +58,10 @@ export class SpireWorkloadApiSvidSource {
         this.spireAgentBin = spireAgentBin;
     }
     async fetch(audience) {
-        const { stdout } = await execFileAsync(this.spireAgentBin, [
-            "api", "fetch", "jwt", "-audience", audience, "-socketPath", this.socketPath,
-        ]);
+        const { execFile } = await importNodeBuiltin("child_process", "SpireWorkloadApiSvidSource");
+        const stdout = await new Promise((resolve, reject) => {
+            execFile(this.spireAgentBin, ["api", "fetch", "jwt", "-audience", audience, "-socketPath", this.socketPath], (err, out) => (err ? reject(err) : resolve(String(out))));
+        });
         for (let line of stdout.split("\n")) {
             line = line.trim();
             if (line.startsWith("token(")) {

package/dist/token-source.d.ts

@@ -1,12 +1,14 @@
+import { type AttesterMetadata, type AttesterProfile } from "./attester.js";
+import { type Logger } from "./logging.js";
 import type { SvidSource } from "./svid-source.js";
 export declare const ATTESTATION_HEADER = "OAuth-Client-Attestation";
 export declare const POP_HEADER = "OAuth-Client-Attestation-PoP";
-export declare const WELL_KNOWN_PATH = "/.well-known/client-attester";
 /** Refresh this many seconds before the token actually expires, so a token is never used at the edge. */
 export declare const DEFAULT_EXPIRY_SKEW_SECONDS = 30;
 export { ClientAttestationError, TransportError } from "./errors.js";
-/** The attester's `/.well-known/client-attester` discovery document. */
-interface AttesterDiscovery {
+/** The attester's discovery document (PingFederate: `/.well-known/client-attester`). */
+export interface AttesterDiscovery {
+    [member: string]: unknown;
     evidence_audience?: string;
     attestation_endpoint?: string;
     challenge_endpoint?: string;
@@ -15,6 +17,21 @@ interface AttesterDiscovery {
 }
 /** Options for {@link ClientAttestation}. */
 export interface ClientAttestationOptions {
+    /**
+     * The attester's host, when the options object is the only argument. The positional argument wins
+     * when both are given.
+     */
+    attesterUrl?: string;
+    /**
+     * The attester profile that discovers the attester and mints the attestation. Default
+     * {@link PingFederateProfile}, the behaviour of every earlier release. See docs/attester-profiles.md.
+     */
+    profile?: AttesterProfile;
+    /**
+     * Static attester metadata (evidence audience, attestation and token endpoints, optionally challenge
+     * endpoint and PoP audience). When set, no discovery request is made; the profile still mints.
+     */
+    metadata?: AttesterMetadata;
     /**
      * How to get the workload's platform identity. Leave unset to auto-detect the runtime (env token,
      * projected token file, SPIRE socket, or GCP metadata). Pass an {@link SvidSource} to override.
@@ -63,21 +80,32 @@ export interface ClientAttestationOptions {
      */
     requireChallenge?: boolean;
     /**
-     * Allow plain `http` for the PingFederate host and the endpoints the attester advertises (default
+     * Allow plain `http` for the attester URL and the endpoints the attester advertises (default
      * `false`). Loopback hosts (`localhost`, `127.0.0.1`, `::1`) are always allowed.
      */
     allowInsecure?: boolean;
+    /**
+     * Where to send log events (see docs/logging.md). Any object with `debug`, `info`, `warn` and
+     * `error(msg, attrs)` works, `console` included. Unset, nothing is logged. Tokens, proofs,
+     * attestations, SVIDs and key material are never logged.
+     */
+    logger?: Logger;
 }
 /**
- * Gets and caches an access token from a PingFederate host using client attestation.
+ * 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`.
  *
- * @param pfHost the PingFederate host — `"pf.example.com"`, or a full base URL
- *   `"https://pf.example.com"`. Plain hostnames default to https.
+ * @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`
+ *   is given.
  */
 export declare class ClientAttestation {
     #private;
+    /** The normalised attester URL, or `""` when the client was built from static metadata alone. */
     readonly baseUrl: string;
-    constructor(pfHost: string, opts?: ClientAttestationOptions);
+    constructor(attesterUrl?: string | ClientAttestationOptions, opts?: ClientAttestationOptions);
     /** Return a valid access token, minting a new one only when the cached one is near expiry. */
     token(opts?: {
         forceRefresh?: boolean;
@@ -106,15 +134,14 @@ export declare class ClientAttestation {
      * as global `fetch`. For a DPoP-bound token it adds a fresh proof and, when the resource answers with
      * a `use_dpop_nonce` challenge and a `DPoP-Nonce`, resends ONCE with a proof carrying that nonce —
      * unless the body is a one-shot stream, which cannot be resent (the challenge response is returned).
+     * Redirects are returned without following them, even if the input or init requests redirect following.
      */
     fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
-    /** The attester's `/.well-known/client-attester` document (fetched once, then cached). */
+    /**
+     * The attester's discovery document (PingFederate: `/.well-known/client-attester`), fetched once and
+     * then cached. With static `metadata`, the fields that were given, in the document's snake_case.
+     */
     discovery(): Promise<AttesterDiscovery>;
+    /** The attester's endpoints: the static `metadata`, or what the profile discovered (once, then cached). */
+    attesterMetadata(): Promise<AttesterMetadata>;
 }
-/**
- * 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)`.
- */
-export declare function canonicalJson(value: unknown): string;
-export declare function normalizeBaseUrl(pfHost: string): string;
-export declare function jwtSub(compactJwt: string): string;

package/dist/token-source.js

@@ -1,7 +1,7 @@
 /**
  * One call to get an access token with client attestation.
  *
- * Point it at a PingFederate host and call `.token()`. It runs the whole flow:
+ * Point it at an attester (PingFederate by default) and call `.token()`. It runs the whole flow:
  *
  *     discover -> get platform identity (evidence) -> get a challenge -> mint the attestation ->
  *     call the token endpoint with the attestation headers -> cache the access token
@@ -19,30 +19,43 @@
  *     // or build the headers for any other client:
  *     const headers = await ca.requestHeaders("GET", "https://api.example.com/things");
  */
-import { randomUUID } from "node:crypto";
+import { base64url } from "jose";
 import { DpopProofBuilder } from "./builders.js";
 import { ClientAttestationCredential, DPOP_HEADER } from "./credential.js";
-import { ClientAttestationError } from "./errors.js";
+import { ClientAttestationError, TransportError } from "./errors.js";
 import { autoDetectEvidence } from "./evidence.js";
-import { INSTANCE_PROOF_TYP } from "./issuance.js";
+import { MintRequest, PingFederateProfile, metadataDocument, } from "./attester.js";
 import { jsonOk, request } from "./http.js";
-import { SigningKeyPair, signCompact } from "./signing-key-pair.js";
+import { emit, failureReason, hostOf, NOOP_LOGGER, urlParts } from "./logging.js";
+import { 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";
-export const WELL_KNOWN_PATH = "/.well-known/client-attester";
 /** 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;
 export { ClientAttestationError, TransportError } from "./errors.js";
 const USE_DPOP_NONCE = "use_dpop_nonce";
 const DPOP_NONCE_HEADER = "DPoP-Nonce";
+/** 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",
+};
 /**
- * Gets and caches an access token from a PingFederate host using client attestation.
+ * Gets and caches an access token using client attestation.
  *
- * @param pfHost the PingFederate host — `"pf.example.com"`, or a full base URL
- *   `"https://pf.example.com"`. Plain hostnames default to https.
+ * `new ClientAttestation(attesterUrl, opts)`, or `new ClientAttestation(opts)` with `opts.metadata` (no
+ * discovery) or a custom `opts.profile`.
+ *
+ * @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`
+ *   is given.
  */
 export class ClientAttestation {
+    /** The normalised attester URL, or `""` when the client was built from static metadata alone. */
     baseUrl;
+    #profile;
     #evidence;
     #authorizationDetails;
     #operator;
@@ -53,14 +66,21 @@ export class ClientAttestation {
     #popMethod;
     #requireChallenge;
     #allowInsecure;
+    #logger;
     /** The token, its type and its bound key: always replaced together, never one without the others. */
     #state = null;
-    #discovery = null;
+    #metadata;
     #refreshing = null;
     /** The last `DPoP-Nonce` each origin returned. */
     #nonces = new Map();
-    constructor(pfHost, opts = {}) {
-        this.baseUrl = normalizeBaseUrl(pfHost);
+    constructor(attesterUrl, opts = {}) {
+        if (typeof attesterUrl === "object" && attesterUrl !== null) {
+            opts = attesterUrl;
+            attesterUrl = undefined;
+        }
+        const url = attesterUrl ?? opts.attesterUrl;
+        this.#profile = opts.profile ?? new PingFederateProfile();
+        this.#metadata = opts.metadata ?? null;
         this.#evidence = opts.evidence;
         this.#authorizationDetails = opts.authorizationDetails;
         this.#operator = opts.operator && Object.keys(opts.operator).length > 0 ? opts.operator : undefined;
@@ -71,7 +91,14 @@ export class ClientAttestation {
         this.#popMethod = opts.popMethod ?? "attestation_pop_jwt";
         this.#requireChallenge = opts.requireChallenge ?? true;
         this.#allowInsecure = opts.allowInsecure ?? false;
-        this.#checkSecure(this.baseUrl, "pfHost");
+        this.#logger = opts.logger ?? NOOP_LOGGER;
+        if (url === undefined && (opts.metadata || opts.profile)) {
+            this.baseUrl = "";
+        }
+        else {
+            this.baseUrl = normalizeBaseUrl(url);
+            this.#checkSecure(this.baseUrl, "attesterUrl");
+        }
     }
     // ── public API ──────────────────────────────────────────────────────────────────────────────────
     /** Return a valid access token, minting a new one only when the cached one is near expiry. */
@@ -113,6 +140,7 @@ export class ClientAttestation {
      * as global `fetch`. For a DPoP-bound token it adds a fresh proof and, when the resource answers with
      * a `use_dpop_nonce` challenge and a `DPoP-Nonce`, resends ONCE with a proof carrying that nonce —
      * unless the body is a one-shot stream, which cannot be resent (the challenge response is returned).
+     * Redirects are returned without following them, even if the input or init requests redirect following.
      */
     async fetch(input, init = {}) {
         const isRequest = typeof Request !== "undefined" && input instanceof Request;
@@ -127,7 +155,7 @@ export class ClientAttestation {
             dpopBound = DPOP_HEADER in auth;
             for (const [name, value] of Object.entries(auth))
                 headers.set(name, value);
-            return fetch(nextInput(), { ...init, headers });
+            return fetch(nextInput(), { ...init, headers, redirect: "manual" });
         };
         const first = await send();
         if (!dpopBound)
@@ -137,24 +165,52 @@ export class ClientAttestation {
             this.#nonces.set(originOf(url), nonce);
         if (!nonce || !replayable(init.body) || !(await isNonceChallenge(first)))
             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();
     }
-    /** The attester's `/.well-known/client-attester` document (fetched once, then cached). */
+    /**
+     * The attester's discovery document (PingFederate: `/.well-known/client-attester`), fetched once and
+     * then cached. With static `metadata`, the fields that were given, in the document's snake_case.
+     */
     async discovery() {
-        if (this.#discovery === null) {
-            this.#discovery = await this.#getJson("GET", this.baseUrl + WELL_KNOWN_PATH);
+        return metadataDocument(await this.attesterMetadata());
+    }
+    /** The attester's endpoints: the static `metadata`, or what the profile discovered (once, then cached). */
+    async attesterMetadata() {
+        const host = this.baseUrl ? hostOf(this.baseUrl) : undefined;
+        if (this.#metadata === null) {
+            this.#metadata = await this.#profile.discover(this.#transport(), this.baseUrl || undefined);
+            emit(this.#logger, "debug", "discovery.fetched", { host });
         }
-        return this.#discovery;
+        else {
+            emit(this.#logger, "debug", "discovery.cached", { host });
+        }
+        return this.#metadata;
+    }
+    /** The transport handed to the profile: this client's https rule, timeout and logging. */
+    #transport() {
+        return {
+            requestJson: (step, method, url, body) => {
+                this.#checkSecure(url, STEP_LABELS[step] ?? `${step} URL`);
+                return this.#getJson(step, method, url, body);
+            },
+        };
     }
     // ── the flow ────────────────────────────────────────────────────────────────────────────────────
     /** 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) {
+            emit(this.#logger, "debug", "token.cache_hit", {
+                expires_in: Math.max(0, Math.round((state.expiresAt - Date.now()) / 1000)),
+            });
             return state;
         }
         if (!this.#refreshing) {
+            emit(this.#logger, "debug", "token.refreshing", {
+                reason: opts.forceRefresh ? "forced" : state ? "expired" : "initial",
+            });
             this.#refreshing = this.#refresh().finally(() => {
                 this.#refreshing = null;
             });
@@ -174,33 +230,58 @@ export class ClientAttestation {
         return state;
     }
     async #runFlow() {
-        const doc = await this.discovery();
-        const audience = doc.evidence_audience;
+        const meta = await this.attesterMetadata();
+        const audience = meta.evidenceAudience;
         if (!audience) {
             throw new ClientAttestationError("attester discovery document has no evidence_audience");
         }
         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(doc);
-        const attestation = await this.#mint(doc, instanceKey, svid, challenge);
-        // token_endpoint is advertised by current attesters; fall back to the standard PF path so an older
-        // discovery document still works from the host alone.
-        const tokenEndpoint = doc.token_endpoint || this.baseUrl + "/as/token.oauth2";
+        const challenge = await this.#fetchChallenge(meta.challengeEndpoint);
+        const { attestation } = await this.#profile.mint(this.#transport(), meta, new MintRequest({
+            instanceKey,
+            evidence: svid,
+            challenge,
+            authorizationDetails: this.#authorizationDetails,
+            operator: this.#operator,
+        }));
+        // The profile resolves the token endpoint (PingFederate: the advertised one, else the standard path
+        // on the attester host).
+        const tokenEndpoint = meta.tokenEndpoint;
+        if (!tokenEndpoint)
+            throw new ClientAttestationError("attester metadata has no token_endpoint");
         this.#checkSecure(tokenEndpoint, "token_endpoint");
         const clientId = jwtSub(attestation);
+        emit(this.#logger, "debug", "attestation.minted", {
+            host: meta.attestationEndpoint ? hostOf(meta.attestationEndpoint) : undefined,
+            client_id: clientId,
+            alg: this.#algorithm,
+        });
         // The PoP audience must be PF's configured issuer, which the attester advertises as pop_audience.
         // 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 = doc.pop_audience || tokenEndpoint;
+        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;
         const credential = new ClientAttestationCredential(attestation, instanceKey);
+        const obtained = (response) => {
+            const expiresIn = Number(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,
+                pop_method: this.#popMethod,
+            });
+            return { response, key: instanceKey };
+        };
         if (this.#popMethod !== "dpop_combined") {
             const headers = await credential.popHeaders(clientId, popAudience, tokenChallenge ?? null);
-            return { response: await this.#callTokenEndpoint(tokenEndpoint, headers), key: instanceKey };
+            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.
@@ -209,12 +290,12 @@ export class ClientAttestation {
         if (serverNonce)
             this.#nonces.set(originOf(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 { response: tokenResponse(res), key: instanceKey };
+        return obtained(this.#tokenResponse(tokenEndpoint, res));
     }
-    async #fetchChallenge(doc) {
-        const endpoint = doc.challenge_endpoint;
+    async #fetchChallenge(endpoint) {
         if (!endpoint)
             return undefined;
         this.#checkSecure(endpoint, "challenge_endpoint");
@@ -222,13 +303,15 @@ export class ClientAttestation {
         // closed unless the caller opted out with requireChallenge: false.
         let body;
         try {
-            body = await this.#getJson("POST", endpoint);
+            body = await this.#getJson("challenge", "POST", endpoint);
         }
         catch (err) {
             if (!(err instanceof ClientAttestationError))
                 throw err;
-            if (!this.#requireChallenge)
+            if (!this.#requireChallenge) {
+                emit(this.#logger, "warn", "challenge.skipped", { host: hostOf(endpoint) });
                 return undefined;
+            }
             throw new ClientAttestationError(`could not fetch the attestation challenge from ${endpoint}: ${err.message}`, {
                 status: err.status,
                 body: err.body,
@@ -236,46 +319,29 @@ export class ClientAttestation {
             });
         }
         const challenge = body.attestation_challenge;
-        if (typeof challenge === "string" && challenge)
+        if (typeof challenge === "string" && challenge) {
+            emit(this.#logger, "debug", "challenge.fetched", { host: hostOf(endpoint) });
             return challenge;
-        if (!this.#requireChallenge)
+        }
+        if (!this.#requireChallenge) {
+            emit(this.#logger, "warn", "challenge.skipped", { host: hostOf(endpoint) });
             return undefined;
+        }
         throw new ClientAttestationError(`challenge endpoint ${endpoint} returned no attestation_challenge`);
     }
-    async #mint(doc, instanceKey, svid, challenge) {
-        if (!doc.attestation_endpoint) {
-            throw new ClientAttestationError("attester discovery document has no attestation_endpoint");
+    /** The parsed token response; a failure is logged as `http.failed` before it is thrown. */
+    #tokenResponse(endpoint, res) {
+        try {
+            return tokenResponse(res);
         }
-        this.#checkSecure(doc.attestation_endpoint, "attestation_endpoint");
-        const now = Math.floor(Date.now() / 1000);
-        const proofClaims = {
-            aud: doc.evidence_audience,
-            jti: randomUUID(),
-            iat: now,
-        };
-        if (challenge)
-            proofClaims.challenge = challenge;
-        const proof = await signCompact(proofClaims, instanceKey, INSTANCE_PROOF_TYP, false);
-        // Evidence-first: no client_id. The attester maps the identity to a client.
-        const body = {
-            instance_key: instanceKey.publicJwk(),
-            svid,
-            proof,
-        };
-        if (this.#authorizationDetails)
-            body.authorization_details = this.#authorizationDetails;
-        if (this.#operator)
-            body.operator = this.#operator;
-        const response = await this.#getJson("POST", doc.attestation_endpoint, body);
-        if (!response.attestation) {
-            throw new ClientAttestationError("attester response contained no attestation", {
-                body: JSON.stringify(response),
-            });
+        catch (err) {
+            const reason = err instanceof TransportError ? failureReason(err) : res.ok ? "malformed" : "status";
+            this.#failed("token", "POST", endpoint, reason, res.status);
+            throw err;
         }
-        return response.attestation;
     }
-    async #callTokenEndpoint(endpoint, authHeaders) {
-        return tokenResponse(await this.#postToken(endpoint, authHeaders));
+    #failed(step, method, url, reason, status) {
+        emit(this.#logger, "warn", "http.failed", { step, method, ...urlParts(url), status, reason });
     }
     #postToken(endpoint, authHeaders) {
         const params = new URLSearchParams({ grant_type: "client_credentials" });
@@ -284,7 +350,7 @@ export class ClientAttestation {
         if (this.#operator)
             params.set("operator", canonicalJson(this.#operator));
         const form = params.toString();
-        return this.#send(endpoint, {
+        return this.#send("token", endpoint, {
             method: "POST",
             headers: {
                 "Content-Type": "application/x-www-form-urlencoded",
@@ -309,18 +375,35 @@ export class ClientAttestation {
             return;
         throw new ClientAttestationError(`${what} must use https: ${url} (loopback hosts are exempt; pass allowInsecure: true to override)`);
     }
-    async #getJson(method, url, jsonBody) {
+    async #getJson(step, method, url, jsonBody) {
         const headers = { Accept: "application/json" };
         let body;
         if (jsonBody !== undefined) {
             headers["Content-Type"] = "application/json";
             body = JSON.stringify(jsonBody);
         }
-        return jsonOk(await this.#send(url, { method, headers, body }), { allowEmpty: true });
+        const res = await this.#send(step, url, { method, headers, body });
+        try {
+            return jsonOk(res, { allowEmpty: true });
+        }
+        catch (err) {
+            this.#failed(step, method, url, failureReason(err), res.status);
+            throw err;
+        }
     }
-    /** Every call the flow makes goes through the shared transport, with this client's timeout. */
-    #send(url, opts) {
-        return request(url, { ...opts, timeoutMs: this.#timeoutMs });
+    /**
+     * Every call the flow makes goes through the shared transport, with this client's timeout. A call that
+     * gets no usable response is logged as `http.failed`.
+     */
+    async #send(step, url, opts) {
+        try {
+            return await request(url, { ...opts, timeoutMs: this.#timeoutMs });
+        }
+        catch (err) {
+            const status = err instanceof ClientAttestationError ? err.status : undefined;
+            this.#failed(step, opts.method ?? "GET", url, failureReason(err), status);
+            throw err;
+        }
     }
 }
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
@@ -385,6 +468,8 @@ async function isNonceChallenge(res) {
 /**
  * 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)`.
+ *
+ * @internal
  */
 export function canonicalJson(value) {
     return JSON.stringify(sortKeys(value)).replace(/[\u0080-\uffff]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
@@ -398,21 +483,23 @@ function sortKeys(value) {
     }
     return value;
 }
-export function normalizeBaseUrl(pfHost) {
-    let host = (pfHost ?? "").trim().replace(/\/+$/, "");
+/** @internal */
+export function normalizeBaseUrl(attesterUrl) {
+    let host = (attesterUrl ?? "").trim().replace(/\/+$/, "");
     if (!host) {
-        throw new Error("pfHost is required");
+        throw new Error("attesterUrl is required");
     }
     if (!host.includes("://")) {
         host = "https://" + host;
     }
     return host;
 }
+/** @internal */
 export function jwtSub(compactJwt) {
     const payload = compactJwt.split(".")[1] ?? "";
     let claims;
     try {
-        claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+        claims = JSON.parse(utf8Decode(base64url.decode(payload)));
     }
     catch {
         throw new ClientAttestationError("minted attestation is not a well-formed JWT");

package/dist/validator/config.d.ts

@@ -2,7 +2,7 @@
  * Validator configuration.
  */
 import type { JSONWebKeySet } from "jose";
-/** Default accepted JWS algorithms: EC / RSA / RSA-PSS at 256/384/512. */
+/** Default accepted JWS algorithms: EC / RSA / RSA-PSS at 256/384/512. Frozen, so it can't be widened. */
 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[];
@@ -27,6 +27,10 @@ export interface IntrospectionConfig {
  * 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`.
+ *
+ * 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).
  */
 export interface ValidatorConfig {
     issuer: string;
@@ -55,10 +59,3 @@ export interface ResolvedConfig {
     /** Normalised with {@link normaliseType}; `null` when the check is off. */
     acceptedTokenTypes: string[] | null;
 }
-/**
- * Compare JOSE `typ` values the way RFC 7515 section 4.1.9 says to: case-insensitively, with an optional
- * `application/` prefix.
- */
-export declare function normaliseType(value: string): string;
-/** Normalize a caller-supplied config, applying defaults (mirrors Python's `ValidatorConfig`). */
-export declare function resolveConfig(config: ValidatorConfig): ResolvedConfig;

package/dist/validator/config.js

@@ -1,5 +1,5 @@
-/** Default accepted JWS algorithms: EC / RSA / RSA-PSS at 256/384/512. */
-export const DEFAULT_ALGORITHMS = [
+/** Default accepted JWS algorithms: EC / RSA / RSA-PSS at 256/384/512. Frozen, so it can't be widened. */
+export const DEFAULT_ALGORITHMS = Object.freeze([
     "ES256",
     "ES384",
     "ES512",
@@ -9,18 +9,35 @@ export const DEFAULT_ALGORITHMS = [
     "PS256",
     "PS384",
     "PS512",
-];
+]);
 /** RFC 9068 section 2.1: a JWT access token's `typ` is `at+jwt` (the `application/` prefix is optional). */
-export const DEFAULT_TOKEN_TYPES = ["at+jwt"];
+export const DEFAULT_TOKEN_TYPES = Object.freeze(["at+jwt"]);
+/**
+ * `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
+ * anyone who has that key.
+ *
+ * @internal
+ */
+export function isForbiddenAlgorithm(alg) {
+    const lowered = alg.toLowerCase();
+    return lowered === "none" || lowered.startsWith("hs");
+}
 /**
  * Compare JOSE `typ` values the way RFC 7515 section 4.1.9 says to: case-insensitively, with an optional
  * `application/` prefix.
+ *
+ * @internal
  */
 export function normaliseType(value) {
     const lower = value.toLowerCase();
     return lower.startsWith("application/") ? lower.slice("application/".length) : lower;
 }
-/** Normalize a caller-supplied config, applying defaults (mirrors Python's `ValidatorConfig`). */
+/**
+ * Normalize a caller-supplied config, applying defaults (mirrors Python's `ValidatorConfig`).
+ *
+ * @internal
+ */
 export function resolveConfig(config) {
     if (!config.issuer) {
         throw new Error("issuer is required");