@idpartners/client-attestation-sdk 0.0.0-stage → 0.2.0

package/dist/svid-source.d.ts

@@ -0,0 +1,27 @@
+/** Anything that can produce a compact JWT-SVID for an audience. */
+export interface SvidSource {
+    fetch(audience: string): Promise<string>;
+}
+/** A fixed, pre-fetched SVID — for tests, or when the caller already holds one. */
+export declare class StaticSvidSource implements SvidSource {
+    private readonly svid;
+    constructor(svid: string);
+    fetch(_audience: string): Promise<string>;
+}
+/** GET a URL returning `{"svid":"<jwt>"}` — e.g. the demo harness `/dev/svid` endpoint. */
+export declare class HttpSvidSource implements SvidSource {
+    private readonly url;
+    constructor(url: string);
+    fetch(_audience: string): Promise<string>;
+}
+/**
+ * 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.
+ */
+export declare class SpireWorkloadApiSvidSource implements SvidSource {
+    private readonly socketPath;
+    private readonly spireAgentBin;
+    constructor(socketPath?: string, spireAgentBin?: string);
+    fetch(audience: string): Promise<string>;
+}

package/dist/svid-source.js

@@ -0,0 +1,64 @@
+/**
+ * Pluggable sources for a workload's SPIFFE JWT-SVID — the infra-identity input to attestation
+ * 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);
+/** 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. */
+export class StaticSvidSource {
+    svid;
+    constructor(svid) {
+        this.svid = svid;
+    }
+    async fetch(_audience) {
+        return this.svid;
+    }
+}
+/** GET a URL returning `{"svid":"<jwt>"}` — e.g. the demo harness `/dev/svid` endpoint. */
+export class HttpSvidSource {
+    url;
+    constructor(url) {
+        this.url = url;
+    }
+    async fetch(_audience) {
+        const res = await request(this.url, { method: "GET", timeoutMs: HTTP_SVID_TIMEOUT_MS });
+        const body = jsonOk(res);
+        if (typeof body.svid !== "string" || !body.svid)
+            throw new Error(`no svid in response from ${this.url}`);
+        return body.svid;
+    }
+}
+/**
+ * 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.
+ */
+export class SpireWorkloadApiSvidSource {
+    socketPath;
+    spireAgentBin;
+    constructor(socketPath = "/tmp/spire-agent/public/api.sock", spireAgentBin = "spire-agent") {
+        this.socketPath = socketPath;
+        this.spireAgentBin = spireAgentBin;
+    }
+    async fetch(audience) {
+        const { stdout } = await execFileAsync(this.spireAgentBin, [
+            "api", "fetch", "jwt", "-audience", audience, "-socketPath", this.socketPath,
+        ]);
+        for (let line of stdout.split("\n")) {
+            line = line.trim();
+            if (line.startsWith("token(")) {
+                const idx = line.indexOf("):");
+                if (idx >= 0)
+                    return line.slice(idx + 2).trim();
+            }
+            if ((line.match(/\./g) ?? []).length === 2)
+                return line;
+        }
+        throw new Error(`could not parse SVID from spire-agent output:\n${stdout}`);
+    }
+}

package/dist/token-source.d.ts

@@ -0,0 +1,120 @@
+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 {
+    evidence_audience?: string;
+    attestation_endpoint?: string;
+    challenge_endpoint?: string;
+    token_endpoint?: string;
+    pop_audience?: string;
+}
+/** Options for {@link ClientAttestation}. */
+export interface ClientAttestationOptions {
+    /**
+     * 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.
+     */
+    evidence?: SvidSource;
+    /**
+     * Optional RFC 9396 access request sent at mint time; the attester grants at most what the workload
+     * is entitled to.
+     */
+    authorizationDetails?: Array<Record<string, unknown>>;
+    /**
+     * The client's operator - who answers for this workload. Sent in the mint request body as
+     * `operator`, so the attester (not the client) is what states it; an attester that does not know
+     * this key ignores it, one that does can refuse to name an operator it cannot corroborate. When set,
+     * it is also repeated at the token endpoint as the form parameter `operator` (compact JSON, sorted
+     * keys) so an AS can populate RFC 8693 `may_act` from it without parsing the attestation; an AS that
+     * does not know the parameter ignores it. Unset (or empty) sends nothing.
+     */
+    operator?: Record<string, unknown>;
+    /** Instance-key signature algorithm (default `ES256`). */
+    algorithm?: string;
+    /** Refresh this long before the token expires (default 30s). */
+    expirySkewSeconds?: number;
+    /** Per-request HTTP timeout in milliseconds (default 20000). */
+    timeoutMs?: number;
+    /**
+     * How to prove possession of the instance key at the token endpoint: the dedicated
+     * `OAuth-Client-Attestation-PoP` JWT (`"attestation_pop_jwt"`, the default), or a `DPoP` proof
+     * carrying the same challenge in `nonce` (`"dpop_combined"`).
+     */
+    popMethod?: "attestation_pop_jwt" | "dpop_combined";
+    /**
+     * Whether the attester-issued challenge also rides in the token-endpoint proof (the PoP's
+     * `challenge` claim, or the DPoP `nonce`), on top of the mint-time instance proof it always
+     * protects. The default `true` binds token issuance to the same challenge as the mint, so a captured
+     * attestation cannot be redeemed for a token without it - but it requires an attester whose
+     * challenge store tolerates being checked at both points. Some attesters treat a challenge as
+     * consumed the moment the mint's instance proof uses it, and then reject a token request that
+     * presents the same value as "unknown or expired" - set this `false` against one of those (the
+     * challenge still protects the mint; only the token-endpoint copy is dropped).
+     */
+    challengeAtToken?: boolean;
+    /**
+     * When the attester advertises a `challenge_endpoint`, fail the flow if the challenge cannot be
+     * fetched (default `true`). Set `false` to proceed without a challenge instead.
+     */
+    requireChallenge?: boolean;
+    /**
+     * Allow plain `http` for the PingFederate host and the endpoints the attester advertises (default
+     * `false`). Loopback hosts (`localhost`, `127.0.0.1`, `::1`) are always allowed.
+     */
+    allowInsecure?: boolean;
+}
+/**
+ * Gets and caches an access token from a PingFederate host 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.
+ */
+export declare class ClientAttestation {
+    #private;
+    readonly baseUrl: string;
+    constructor(pfHost: string, opts?: ClientAttestationOptions);
+    /** Return a valid access token, minting a new one only when the cached one is near expiry. */
+    token(opts?: {
+        forceRefresh?: boolean;
+    }): Promise<string>;
+    /**
+     * `{ Authorization: "<scheme> <token>" }`. For a Bearer token that is all a resource needs. For a
+     * DPoP-bound token (`token_type` DPoP) the scheme is `DPoP` and every request ALSO needs a fresh
+     * DPoP proof — use {@link requestHeaders} (or {@link fetch}) instead, which adds it.
+     */
+    authorizationHeader(opts?: {
+        forceRefresh?: boolean;
+    }): Promise<Record<string, string>>;
+    /**
+     * The headers to send to a resource for one request, obtaining or refreshing the token as needed.
+     *
+     * - Bearer token: `{ Authorization: "Bearer <t>" }`
+     * - 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.
+     */
+    requestHeaders(method: string, url: string, opts?: {
+        forceRefresh?: boolean;
+    }): Promise<Record<string, string>>;
+    /**
+     * A `fetch` wrapper that attaches the token (refreshing it as needed) to the request. Same signature
+     * 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).
+     */
+    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+    /** The attester's `/.well-known/client-attester` document (fetched once, then cached). */
+    discovery(): Promise<AttesterDiscovery>;
+}
+/**
+ * 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

@@ -0,0 +1,424 @@
+/**
+ * One call to get an access token with client attestation.
+ *
+ * Point it at a PingFederate host 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
+ *
+ * The workload sends no client secret and no client_id. Its only credential is the attestation, built
+ * from the identity its runtime already gives it (auto-detected; see `evidence.ts`).
+ *
+ *     import { ClientAttestation } from "@idpartners/client-attestation-sdk";
+ *
+ *     const ca = new ClientAttestation("pf.example.com");
+ *     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):
+ *     await ca.fetch("https://api.example.com/things");
+ *     // 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 { DpopProofBuilder } from "./builders.js";
+import { ClientAttestationCredential, DPOP_HEADER } from "./credential.js";
+import { ClientAttestationError } from "./errors.js";
+import { autoDetectEvidence } from "./evidence.js";
+import { INSTANCE_PROOF_TYP } from "./issuance.js";
+import { jsonOk, request } from "./http.js";
+import { SigningKeyPair, signCompact } 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";
+/**
+ * Gets and caches an access token from a PingFederate host 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.
+ */
+export class ClientAttestation {
+    baseUrl;
+    #evidence;
+    #authorizationDetails;
+    #operator;
+    #challengeAtToken;
+    #algorithm;
+    #skew;
+    #timeoutMs;
+    #popMethod;
+    #requireChallenge;
+    #allowInsecure;
+    /** The token, its type and its bound key: always replaced together, never one without the others. */
+    #state = null;
+    #discovery = null;
+    #refreshing = null;
+    /** The last `DPoP-Nonce` each origin returned. */
+    #nonces = new Map();
+    constructor(pfHost, opts = {}) {
+        this.baseUrl = normalizeBaseUrl(pfHost);
+        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;
+        this.#timeoutMs = opts.timeoutMs ?? 20_000;
+        this.#popMethod = opts.popMethod ?? "attestation_pop_jwt";
+        this.#requireChallenge = opts.requireChallenge ?? true;
+        this.#allowInsecure = opts.allowInsecure ?? false;
+        this.#checkSecure(this.baseUrl, "pfHost");
+    }
+    // ── public API ──────────────────────────────────────────────────────────────────────────────────
+    /** Return a valid access token, minting a new one only when the cached one is near expiry. */
+    async token(opts = {}) {
+        return (await this.#current(opts)).accessToken;
+    }
+    /**
+     * `{ Authorization: "<scheme> <token>" }`. For a Bearer token that is all a resource needs. For a
+     * DPoP-bound token (`token_type` DPoP) the scheme is `DPoP` and every request ALSO needs a fresh
+     * DPoP proof — use {@link requestHeaders} (or {@link fetch}) instead, which adds it.
+     */
+    async authorizationHeader(opts = {}) {
+        const state = await this.#current(opts);
+        return { Authorization: `${scheme(state)} ${state.accessToken}` };
+    }
+    /**
+     * The headers to send to a resource for one request, obtaining or refreshing the token as needed.
+     *
+     * - Bearer token: `{ Authorization: "Bearer <t>" }`
+     * - 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.
+     */
+    async requestHeaders(method, url, opts = {}) {
+        const state = await this.#current(opts);
+        const headers = { Authorization: `${scheme(state)} ${state.accessToken}` };
+        if (isDpop(state)) {
+            headers[DPOP_HEADER] = await new DpopProofBuilder(state.key)
+                .method(method)
+                .uri(url)
+                .accessToken(state.accessToken)
+                .nonce(this.#nonces.get(originOf(url)) ?? null)
+                .build();
+        }
+        return headers;
+    }
+    /**
+     * A `fetch` wrapper that attaches the token (refreshing it as needed) to the request. Same signature
+     * 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).
+     */
+    async fetch(input, init = {}) {
+        const isRequest = typeof Request !== "undefined" && input instanceof Request;
+        const url = isRequest ? input.url : 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 headers = new Headers(init.headers ?? (isRequest ? input.headers : undefined));
+            const auth = await this.requestHeaders(method, url);
+            dpopBound = DPOP_HEADER in auth;
+            for (const [name, value] of Object.entries(auth))
+                headers.set(name, value);
+            return fetch(nextInput(), { ...init, headers });
+        };
+        const first = await send();
+        if (!dpopBound)
+            return first;
+        const nonce = first.headers.get(DPOP_NONCE_HEADER);
+        if (nonce)
+            this.#nonces.set(originOf(url), nonce);
+        if (!nonce || !replayable(init.body) || !(await isNonceChallenge(first)))
+            return first;
+        await first.body?.cancel().catch(() => undefined);
+        return send();
+    }
+    /** The attester's `/.well-known/client-attester` document (fetched once, then cached). */
+    async discovery() {
+        if (this.#discovery === null) {
+            this.#discovery = await this.#getJson("GET", this.baseUrl + WELL_KNOWN_PATH);
+        }
+        return this.#discovery;
+    }
+    // ── 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) {
+            return state;
+        }
+        if (!this.#refreshing) {
+            this.#refreshing = this.#refresh().finally(() => {
+                this.#refreshing = null;
+            });
+        }
+        return this.#refreshing;
+    }
+    async #refresh() {
+        const { response, key } = await this.#runFlow();
+        const expiresIn = 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,
+        };
+        this.#state = state;
+        return state;
+    }
+    async #runFlow() {
+        const doc = await this.discovery();
+        const audience = doc.evidence_audience;
+        if (!audience) {
+            throw new ClientAttestationError("attester discovery document has no evidence_audience");
+        }
+        const evidenceSource = this.#evidence ?? (await autoDetectEvidence());
+        const svid = await evidenceSource.fetch(audience);
+        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";
+        this.#checkSecure(tokenEndpoint, "token_endpoint");
+        const clientId = jwtSub(attestation);
+        // 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;
+        // 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);
+        if (this.#popMethod !== "dpop_combined") {
+            const headers = await credential.popHeaders(clientId, popAudience, tokenChallenge ?? null);
+            return { response: await this.#callTokenEndpoint(tokenEndpoint, headers), key: instanceKey };
+        }
+        // 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.
+        let res = await this.#postToken(tokenEndpoint, await credential.dpopHeaders("POST", tokenEndpoint, tokenChallenge ?? null));
+        const serverNonce = res.headers.get(DPOP_NONCE_HEADER);
+        if (serverNonce)
+            this.#nonces.set(originOf(tokenEndpoint), serverNonce);
+        if (res.status === 400 && serverNonce && jsonError(res.body) === USE_DPOP_NONCE) {
+            res = await this.#postToken(tokenEndpoint, await credential.dpopHeaders("POST", tokenEndpoint, serverNonce));
+        }
+        return { response: tokenResponse(res), key: instanceKey };
+    }
+    async #fetchChallenge(doc) {
+        const endpoint = doc.challenge_endpoint;
+        if (!endpoint)
+            return undefined;
+        this.#checkSecure(endpoint, "challenge_endpoint");
+        // The attester advertised a challenge, so minting without one weakens replay protection: fail
+        // closed unless the caller opted out with requireChallenge: false.
+        let body;
+        try {
+            body = await this.#getJson("POST", endpoint);
+        }
+        catch (err) {
+            if (!(err instanceof ClientAttestationError))
+                throw err;
+            if (!this.#requireChallenge)
+                return undefined;
+            throw new ClientAttestationError(`could not fetch the attestation challenge from ${endpoint}: ${err.message}`, {
+                status: err.status,
+                body: err.body,
+                cause: err,
+            });
+        }
+        const challenge = body.attestation_challenge;
+        if (typeof challenge === "string" && challenge)
+            return challenge;
+        if (!this.#requireChallenge)
+            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");
+        }
+        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),
+            });
+        }
+        return response.attestation;
+    }
+    async #callTokenEndpoint(endpoint, authHeaders) {
+        return tokenResponse(await this.#postToken(endpoint, authHeaders));
+    }
+    #postToken(endpoint, authHeaders) {
+        const params = new URLSearchParams({ grant_type: "client_credentials" });
+        // Extension parameter, sent only when configured: the attestation is the authoritative carrier,
+        // this repeats the operator on the wire for an AS that maps it into may_act.
+        if (this.#operator)
+            params.set("operator", canonicalJson(this.#operator));
+        const form = params.toString();
+        return this.#send(endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+                ...authHeaders,
+            },
+            body: form,
+        });
+    }
+    /** 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)`);
+    }
+    async #getJson(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 });
+    }
+    /** 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 });
+    }
+}
+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,
+        });
+    }
+    const parsed = jsonOk(res, { allowEmpty: true });
+    if (!parsed.access_token) {
+        throw new ClientAttestationError("token endpoint returned no access_token", { body: res.body });
+    }
+    return parsed;
+}
+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. */
+function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return url;
+    }
+}
+/** The `error` member of a JSON object body, or undefined. */
+function jsonError(body) {
+    try {
+        return JSON.parse(body)?.error;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Can this fetch body be sent a second time? One-shot streams cannot. */
+function replayable(body) {
+    if (body == null)
+        return true;
+    return !(typeof ReadableStream !== "undefined" && body instanceof ReadableStream) &&
+        !(typeof body[Symbol.asyncIterator] === "function");
+}
+/**
+ * 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"}`.
+ */
+async function isNonceChallenge(res) {
+    if (res.status === 401) {
+        const challenge = res.headers.get("WWW-Authenticate") ?? "";
+        return /(^|,)\s*DPoP\b/i.test(challenge) && /error\s*=\s*"?use_dpop_nonce"?/i.test(challenge);
+    }
+    if (res.status === 400) {
+        return jsonError(await res.clone().text()) === USE_DPOP_NONCE;
+    }
+    return false;
+}
+/**
+ * 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 function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value)).replace(/[\u0080-\uffff]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === "object") {
+        const obj = value;
+        return Object.fromEntries(Object.keys(obj).sort().map((k) => [k, sortKeys(obj[k])]));
+    }
+    return value;
+}
+export function normalizeBaseUrl(pfHost) {
+    let host = (pfHost ?? "").trim().replace(/\/+$/, "");
+    if (!host) {
+        throw new Error("pfHost is required");
+    }
+    if (!host.includes("://")) {
+        host = "https://" + host;
+    }
+    return host;
+}
+export function jwtSub(compactJwt) {
+    const payload = compactJwt.split(".")[1] ?? "";
+    let claims;
+    try {
+        claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new ClientAttestationError("minted attestation is not a well-formed JWT");
+    }
+    if (!claims?.sub) {
+        throw new ClientAttestationError("minted attestation has no sub (client id)");
+    }
+    return claims.sub;
+}