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

package/dist/runtime.js

@@ -0,0 +1,64 @@
+/**
+ * Runtime-neutral helpers, so the package loads on edge runtimes (Cloudflare Workers, Vercel Edge,
+ * Deno Deploy) as well as Node. Nothing here, or anywhere else in `src`, imports a Node builtin
+ * statically: the few features that need one load it lazily through {@link importNodeBuiltin}.
+ * Not exported from the package index.
+ */
+import { ClientAttestationError } from "./errors.js";
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+/**
+ * UTF-8 bytes of a string.
+ *
+ * @internal
+ */
+export function utf8Encode(text) {
+    return textEncoder.encode(text);
+}
+/**
+ * A string from UTF-8 bytes; malformed sequences become U+FFFD, as `Buffer#toString` does.
+ *
+ * @internal
+ */
+export function utf8Decode(bytes) {
+    return textDecoder.decode(bytes);
+}
+/**
+ * Standard (padded) base64 of some bytes.
+ *
+ * @internal
+ */
+export function base64Encode(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    }
+    return btoa(binary);
+}
+/**
+ * An environment variable, or `undefined` on a runtime with no `process.env` (most edge runtimes).
+ *
+ * @internal
+ */
+export function envVar(name) {
+    const proc = globalThis.process;
+    return proc?.env?.[name];
+}
+/**
+ * Load a Node builtin (`node:<name>`) on first use. Throws a {@link ClientAttestationError} naming the
+ * feature when the runtime has no such module (an edge runtime without Node compatibility).
+ *
+ * The specifier is built at run time so bundlers for edge targets leave it alone instead of failing to
+ * resolve it.
+ *
+ * @internal
+ */
+export async function importNodeBuiltin(name, feature) {
+    const specifier = "node:" + name;
+    try {
+        return (await import(/* @vite-ignore */ /* webpackIgnore: true */ specifier));
+    }
+    catch (err) {
+        throw new ClientAttestationError(`${feature} needs the Node.js module '${specifier}', which this runtime does not provide`, { cause: err });
+    }
+}

package/dist/signer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * External JWS signing — keys that live outside the process (a vault, HSM, or KMS).
+ *
+ * {@link SigningKeyPair} covers the local-key case; {@link OpenBaoTransitSigner} signs inside an
+ * OpenBao / HashiCorp Vault transit engine so the attester's private key never leaves it.
+ */
+import { type JWK } from "jose";
+/** A JWS signing capability whose private key may live outside the process. `sign` returns the RAW JWS
+ * signature over the signing input — for ECDSA the fixed-width `r||s`, not ASN.1/DER. */
+export interface JwsSigner {
+    readonly algorithm: string;
+    readonly keyId: string;
+    publicJwk(): JWK;
+    sign(signingInput: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * A {@link JwsSigner} backed by an OpenBao / HashiCorp Vault transit engine: the attestation is signed
+ * inside the vault (`POST /v1/transit/sign/<key>` with `marshaling_algorithm=jws`, which returns the
+ * fixed-width `r||s`) and the private key never leaves it. `create` reads the key metadata to pin the
+ * latest version, derive the public JWK and compute its RFC 7638 `kid`. Fail-closed (vault errors throw).
+ *
+ * @experimental See docs/api.md: a client for a third-party API that authenticates with a static token only; its constructor will change when other auth methods are added.
+ */
+export declare class OpenBaoTransitSigner implements JwsSigner {
+    #private;
+    readonly algorithm: string;
+    readonly keyId: string;
+    private constructor();
+    static create(baoAddr: string, token: string, keyName: string): Promise<OpenBaoTransitSigner>;
+    publicJwk(): JWK;
+    sign(signingInput: Uint8Array): Promise<Uint8Array>;
+}

package/dist/signer.js

@@ -0,0 +1,121 @@
+/**
+ * External JWS signing — keys that live outside the process (a vault, HSM, or KMS).
+ *
+ * {@link SigningKeyPair} covers the local-key case; {@link OpenBaoTransitSigner} signs inside an
+ * OpenBao / HashiCorp Vault transit engine so the attester's private key never leaves it.
+ */
+import { base64url, calculateJwkThumbprint, exportJWK, importSPKI } from "jose";
+import { TransportError } from "./errors.js";
+import { base64Encode } from "./runtime.js";
+import { parseJsonObject, request as httpRequest, snippet } from "./http.js";
+/** Per-call timeout for the vault. */
+const OPENBAO_TIMEOUT_MS = 5_000;
+const b64url = (bytes) => base64url.encode(bytes);
+/** Assemble a compact JWS whose signature is produced by an external signer (header carries `kid`; external
+ *
+ * @internal
+ * signers hold issuing keys, referenced by id, never an embedded jwk). */
+export async function signExternal(claims, signer, typ) {
+    const enc = new TextEncoder();
+    const header = { alg: signer.algorithm, typ, kid: signer.keyId };
+    const signingInput = `${b64url(enc.encode(JSON.stringify(header)))}.${b64url(enc.encode(JSON.stringify(claims)))}`;
+    const signature = await signer.sign(enc.encode(signingInput));
+    return `${signingInput}.${b64url(signature)}`;
+}
+const KEY_TYPE_ALG = { "ecdsa-p256": "ES256", "ecdsa-p384": "ES384", "ecdsa-p521": "ES512" };
+const ALG_HASH = { ES256: "sha2-256", ES384: "sha2-384", ES512: "sha2-512" };
+/**
+ * A {@link JwsSigner} backed by an OpenBao / HashiCorp Vault transit engine: the attestation is signed
+ * inside the vault (`POST /v1/transit/sign/<key>` with `marshaling_algorithm=jws`, which returns the
+ * fixed-width `r||s`) and the private key never leaves it. `create` reads the key metadata to pin the
+ * latest version, derive the public JWK and compute its RFC 7638 `kid`. Fail-closed (vault errors throw).
+ *
+ * @experimental See docs/api.md: a client for a third-party API that authenticates with a static token only; its constructor will change when other auth methods are added.
+ */
+export class OpenBaoTransitSigner {
+    algorithm;
+    keyId;
+    #base;
+    #token;
+    #keyName;
+    #hash;
+    #keyVersion;
+    #publicJwk;
+    constructor(base, token, keyName, algorithm, hash, keyVersion, publicJwk, keyId) {
+        this.#base = base;
+        this.#token = token;
+        this.#keyName = keyName;
+        this.algorithm = algorithm;
+        this.#hash = hash;
+        this.#keyVersion = keyVersion;
+        this.#publicJwk = publicJwk;
+        this.keyId = keyId;
+    }
+    static async create(baoAddr, token, keyName) {
+        const base = baoAddr.replace(/\/+$/, "");
+        const data = await request("GET", base, token, `/v1/transit/keys/${keyName}`);
+        const keyType = String(data.type);
+        const algorithm = KEY_TYPE_ALG[keyType];
+        if (!algorithm) {
+            throw new Error(`transit key '${keyName}' has unsupported type for JWS signing: ${keyType}`);
+        }
+        const keyVersion = Number(data.latest_version);
+        const keys = data.keys;
+        const pem = keys[String(keyVersion)].public_key;
+        const jwk = await exportJWK(await importSPKI(pem, algorithm, { extractable: true }));
+        const keyId = await calculateJwkThumbprint(jwk, "sha256");
+        const publicJwk = { ...jwk, kid: keyId, alg: algorithm };
+        return new OpenBaoTransitSigner(base, token, keyName, algorithm, ALG_HASH[algorithm], keyVersion, publicJwk, keyId);
+    }
+    publicJwk() {
+        return { ...this.#publicJwk };
+    }
+    async sign(signingInput) {
+        const body = JSON.stringify({
+            input: base64Encode(signingInput),
+            marshaling_algorithm: "jws",
+            hash_algorithm: this.#hash,
+            key_version: this.#keyVersion,
+        });
+        const data = await request("POST", this.#base, this.#token, `/v1/transit/sign/${this.#keyName}`, body);
+        const signature = data.signature;
+        if (!signature) {
+            throw new Error("transit sign response carried no signature");
+        }
+        const raw = signature.slice(signature.lastIndexOf(":") + 1); // envelope: vault:v<n>:<base64url(r||s)>
+        return base64url.decode(raw);
+    }
+}
+async function request(method, base, token, path, body) {
+    let response;
+    try {
+        response = await httpRequest(base + path, {
+            method,
+            headers: { "X-Vault-Token": token, ...(body ? { "Content-Type": "application/json" } : {}) },
+            body,
+            timeoutMs: OPENBAO_TIMEOUT_MS,
+        });
+    }
+    catch (exc) {
+        if (exc instanceof TransportError && (exc.kind === "network" || exc.kind === "timeout")) {
+            const why = exc.kind === "timeout"
+                ? `timed out after ${OPENBAO_TIMEOUT_MS} ms`
+                : exc.cause instanceof Error
+                    ? exc.cause.message
+                    : String(exc.cause);
+            throw new TransportError(`OpenBao unreachable at ${base}: ${why}`, exc.kind, { cause: exc });
+        }
+        throw exc;
+    }
+    if (response.status !== 200) {
+        throw new TransportError(`OpenBao returned HTTP ${response.status} for ${path}`, "status", {
+            status: response.status,
+            body: snippet(response.body),
+        });
+    }
+    const parsed = parseJsonObject(response);
+    if (!parsed.data || typeof parsed.data !== "object") {
+        throw new Error("OpenBao response carried no data");
+    }
+    return parsed.data;
+}

package/dist/signing-key-pair.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Signing keys for attestation-based client authentication.
+ */
+import { type CryptoKey, type JWK } from "jose";
+/**
+ * A signing key pair (public + private) with its JWS `alg` and RFC 7638 thumbprint `kid`.
+ *
+ * Used both as the client instance key — which signs PoP / DPoP proofs and is bound into an
+ * attestation's `cnf` — and as a Client Attester's issuing key.
+ *
+ * jose's crypto operations are async, so instances are created via the static async
+ * factories {@link SigningKeyPair.generate} and {@link SigningKeyPair.fromJwk}.
+ */
+export declare class SigningKeyPair {
+    #private;
+    /** The JWS algorithm (e.g. `ES256`). */
+    readonly algorithm: string;
+    /** The RFC 7638 JWK thumbprint (SHA-256, base64url) — this key's `kid`. */
+    readonly keyId: string;
+    private constructor();
+    /**
+     * Generate a fresh key pair for the given JWS algorithm: `ES256` / `ES384` / `ES512`
+     * (EC P-256 / P-384 / P-521), or `RS256` / `RS384` / `RS512` / `PS256` / `PS384` / `PS512`
+     * (RSA 2048).
+     *
+     * The private key is not extractable unless `options.extractable` is true: nothing in the SDK needs
+     * to export it, so by default it can't leak through `exportJWK`. Pass `{ extractable: true }` only to
+     * persist the key yourself (then restore it with {@link SigningKeyPair.fromJwk}).
+     */
+    static generate(algorithm: string, options?: {
+        extractable?: boolean;
+    }): Promise<SigningKeyPair>;
+    /**
+     * Wrap an existing JWK (which must contain the private component `d`) for the given algorithm.
+     */
+    static fromJwk(jwk: JWK, algorithm: string): Promise<SigningKeyPair>;
+    /** The private CryptoKey — package-internal; used by the JWS signer. */
+    get privateKey(): CryptoKey;
+    /**
+     * The public-only JWK (including `kid`) as a fresh object — suitable as an attestation
+     * `cnf.jwk` or a DPoP header value (from which callers strip `kid`).
+     */
+    publicJwk(): JWK;
+}

package/dist/signing-key-pair.js

@@ -0,0 +1,130 @@
+/**
+ * Signing keys for attestation-based client authentication.
+ */
+import { SignJWT, calculateJwkThumbprint, exportJWK, generateKeyPair, importJWK, } from "jose";
+/**
+ * A signing key pair (public + private) with its JWS `alg` and RFC 7638 thumbprint `kid`.
+ *
+ * Used both as the client instance key — which signs PoP / DPoP proofs and is bound into an
+ * attestation's `cnf` — and as a Client Attester's issuing key.
+ *
+ * jose's crypto operations are async, so instances are created via the static async
+ * factories {@link SigningKeyPair.generate} and {@link SigningKeyPair.fromJwk}.
+ */
+export class SigningKeyPair {
+    /** The JWS algorithm (e.g. `ES256`). */
+    algorithm;
+    /** The RFC 7638 JWK thumbprint (SHA-256, base64url) — this key's `kid`. */
+    keyId;
+    #privateKey;
+    #publicJwk;
+    constructor(privateKey, algorithm, publicJwk, keyId) {
+        this.#privateKey = privateKey;
+        this.algorithm = algorithm;
+        // Store the public JWK with its kid stamped, so publicJwk() hands out a copy including kid.
+        this.#publicJwk = { ...publicJwk, kid: keyId };
+        this.keyId = keyId;
+    }
+    /**
+     * Generate a fresh key pair for the given JWS algorithm: `ES256` / `ES384` / `ES512`
+     * (EC P-256 / P-384 / P-521), or `RS256` / `RS384` / `RS512` / `PS256` / `PS384` / `PS512`
+     * (RSA 2048).
+     *
+     * The private key is not extractable unless `options.extractable` is true: nothing in the SDK needs
+     * to export it, so by default it can't leak through `exportJWK`. Pass `{ extractable: true }` only to
+     * persist the key yourself (then restore it with {@link SigningKeyPair.fromJwk}).
+     */
+    static async generate(algorithm, options = {}) {
+        checkAlgorithm(algorithm);
+        const { privateKey, publicKey } = await generateKeyPair(algorithm, {
+            extractable: options.extractable ?? false,
+            ...(algorithm.startsWith("ES") ? {} : { modulusLength: RSA_MODULUS_BITS }),
+        });
+        const publicJwk = publicMembers(await exportJWK(publicKey));
+        const keyId = await calculateJwkThumbprint(publicJwk, "sha256");
+        return new SigningKeyPair(privateKey, algorithm, publicJwk, keyId);
+    }
+    /**
+     * Wrap an existing JWK (which must contain the private component `d`) for the given algorithm.
+     */
+    static async fromJwk(jwk, algorithm) {
+        if (!jwk.d) {
+            throw new Error("JWK does not contain a private key");
+        }
+        checkAlgorithm(algorithm);
+        const privateKey = (await importJWK(jwk, algorithm));
+        // Derive the public-only JWK from the supplied members (drop the private ones).
+        const publicJwk = publicMembers(jwk);
+        const keyId = await calculateJwkThumbprint(publicJwk, "sha256");
+        return new SigningKeyPair(privateKey, algorithm, publicJwk, keyId);
+    }
+    /** The private CryptoKey — package-internal; used by the JWS signer. */
+    get privateKey() {
+        return this.#privateKey;
+    }
+    /**
+     * The public-only JWK (including `kid`) as a fresh object — suitable as an attestation
+     * `cnf.jwk` or a DPoP header value (from which callers strip `kid`).
+     */
+    publicJwk() {
+        return { ...this.#publicJwk };
+    }
+}
+/**
+ * The JWS algorithms {@link SigningKeyPair} can generate and sign with.
+ *
+ * @internal
+ */
+export const SUPPORTED_ALGORITHMS = [
+    "ES256", "ES384", "ES512",
+    "RS256", "RS384", "RS512",
+    "PS256", "PS384", "PS512",
+];
+/** RSA modulus size for generated RS* / PS* keys. */
+const RSA_MODULUS_BITS = 2048;
+function checkAlgorithm(algorithm) {
+    if (!SUPPORTED_ALGORITHMS.includes(algorithm)) {
+        throw new Error(`unsupported signing algorithm: ${algorithm}`);
+    }
+}
+/** The public members of an EC or RSA JWK (no private parameters, no metadata). */
+function publicMembers(jwk) {
+    return jwk.kty === "RSA"
+        ? { kty: jwk.kty, n: jwk.n, e: jwk.e }
+        : { kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y };
+}
+/**
+ * RFC 7638 JWK thumbprint (SHA-256, base64url) over the required members only.
+ *
+ * @internal
+ */
+export async function thumbprint(publicJwk) {
+    return calculateJwkThumbprint(publicJwk, "sha256");
+}
+/**
+ * Sign claims into a compact JWS with an explicit `typ` header, keyed by `key`.
+ *
+ * When `embedJwk` is set the public key travels in a `jwk` header (as DPoP requires); otherwise
+ * the key's thumbprint `kid` is set.
+ *
+ * @internal
+ */
+export async function signCompact(claims, key, typ, embedJwk) {
+    const header = { alg: key.algorithm, typ };
+    if (embedJwk) {
+        const publicJwk = key.publicJwk();
+        delete publicJwk.kid;
+        header.jwk = publicJwk;
+    }
+    else {
+        header.kid = key.keyId;
+    }
+    return new SignJWT(claims).setProtectedHeader(header).sign(key.privateKey);
+}
+/** @internal */
+export function requireText(value, field) {
+    if (value == null || String(value).trim() === "") {
+        throw new Error(`${field} is required`);
+    }
+    return value;
+}

package/dist/svid-source.d.ts

@@ -0,0 +1,41 @@
+/** 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.
+ *
+ * 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 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.
+ *
+ * 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 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,77 @@
+/**
+ * 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 { jsonOk, request } from "./http.js";
+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. */
+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.
+ *
+ * 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) {
+        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.
+ *
+ * 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;
+    spireAgentBin;
+    constructor(socketPath = "/tmp/spire-agent/public/api.sock", spireAgentBin = "spire-agent") {
+        this.socketPath = socketPath;
+        this.spireAgentBin = spireAgentBin;
+    }
+    async fetch(audience) {
+        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(")) {
+                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,146 @@
+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";
+/** 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 discovery document (PingFederate: `/.well-known/client-attester`). */
+export interface AttesterDiscovery {
+    [member: string]: unknown;
+    evidence_audience?: string;
+    attestation_endpoint?: string;
+    challenge_endpoint?: string;
+    token_endpoint?: string;
+    pop_audience?: string;
+}
+/** 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.
+     */
+    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 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 using client attestation.
+ *
+ * `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 declare class ClientAttestation {
+    #private;
+    /** The normalised attester URL, or `""` when the client was built from static metadata alone. */
+    readonly baseUrl: string;
+    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;
+    }): 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 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>;
+}