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

package/dist/http.js

@@ -0,0 +1,158 @@
+/**
+ * The one internal HTTP transport every outbound call in the SDK goes through. Not exported from the
+ * package index.
+ *
+ * Uniform behaviour, because these requests carry credentials (Authorization, DPoP, client attestation
+ * headers, X-Vault-Token, SVIDs and proofs in bodies):
+ *
+ * - every call has a timeout, covering the body read as well as the headers;
+ * - redirects are never followed — a 3xx is a {@link TransportError}, and the target is never contacted;
+ * - the response body is capped (default 1 MiB), by `content-length` and again while streaming;
+ * - {@link request} returns non-2xx responses as data; {@link jsonOk} turns them, and malformed JSON,
+ *   into a {@link TransportError}.
+ */
+import { TransportError } from "./errors.js";
+export const DEFAULT_MAX_BYTES = 1024 * 1024;
+export const DEFAULT_TIMEOUT_MS = 20_000;
+/** At most this many characters of a response body are carried in an error. */
+export const ERROR_BODY_CHARS = 512;
+/** The first {@link ERROR_BODY_CHARS} characters of a body, for an error message. */
+export function snippet(body) {
+    return body.length > ERROR_BODY_CHARS ? body.slice(0, ERROR_BODY_CHARS) : body;
+}
+function describe(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function isAbort(err) {
+    const name = err?.name;
+    return name === "TimeoutError" || name === "AbortError";
+}
+/**
+ * Make one HTTP request. Resolves with the status, headers and body text for any non-3xx response
+ * (non-2xx included); rejects with a {@link TransportError} for a network failure, timeout, redirect or
+ * oversized body.
+ */
+export async function request(url, opts = {}) {
+    const method = opts.method ?? "GET";
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+    const where = `${method} ${url}`;
+    const timedOut = (cause) => new TransportError(`${where} timed out after ${timeoutMs} ms`, "timeout", { cause });
+    let res;
+    try {
+        res = await fetch(url, {
+            method,
+            headers: opts.headers,
+            body: opts.body,
+            redirect: "manual",
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        if (isAbort(err))
+            throw timedOut(err);
+        throw new TransportError(`${where} failed: ${describe(err)}`, "network", { cause: err });
+    }
+    const status = res.status;
+    if (res.type === "opaqueredirect" || (status >= 300 && status < 400)) {
+        await discard(res);
+        throw new TransportError(`${where} answered with a redirect (HTTP ${status}); redirects are not followed`, "redirect", {
+            status,
+        });
+    }
+    const tooLarge = () => new TransportError(`${where} response is larger than ${maxBytes} bytes`, "too_large", { status });
+    const declared = Number(res.headers?.get("content-length") ?? NaN);
+    if (declared > maxBytes) {
+        await discard(res);
+        throw tooLarge();
+    }
+    let body;
+    try {
+        body = await readCapped(res, maxBytes, tooLarge);
+    }
+    catch (err) {
+        if (err instanceof TransportError)
+            throw err;
+        if (isAbort(err))
+            throw timedOut(err);
+        throw new TransportError(`${where} failed reading the response: ${describe(err)}`, "network", { cause: err });
+    }
+    return {
+        method,
+        url,
+        status,
+        ok: status >= 200 && status < 300,
+        headers: res.headers ?? new Headers(),
+        body,
+    };
+}
+async function discard(res) {
+    try {
+        await res.body?.cancel();
+    }
+    catch {
+        // nothing to do: the response is being refused anyway
+    }
+}
+async function readCapped(res, maxBytes, tooLarge) {
+    if (!res.body) {
+        // only reached by stand-in Response objects (tests); a real fetch always has a stream
+        const text = await res.text();
+        if (Buffer.byteLength(text, "utf8") > maxBytes)
+            throw tooLarge();
+        return text;
+    }
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel().catch(() => undefined);
+            throw tooLarge();
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+/**
+ * Parse `res.body` as a JSON object. Throws a {@link TransportError} for a non-2xx status (carrying the
+ * status and at most 512 characters of the body) and for a body that is not a JSON object. An empty body
+ * reads as `{}` when `allowEmpty` is set.
+ */
+export function jsonOk(res, opts = {}) {
+    if (!res.ok) {
+        const body = snippet(res.body);
+        throw new TransportError(`${res.method} ${res.url} returned HTTP ${res.status}: ${body}`, "status", {
+            status: res.status,
+            body,
+        });
+    }
+    return parseJsonObject(res, opts);
+}
+/** Parse `res.body` as a JSON object regardless of status; a {@link TransportError} if it is not one. */
+export function parseJsonObject(res, opts = {}) {
+    if (opts.allowEmpty && res.body === "")
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(res.body);
+    }
+    catch (err) {
+        throw new TransportError(`${res.method} ${res.url} returned malformed JSON: ${describe(err)}`, "json", {
+            status: res.status,
+            body: snippet(res.body),
+            cause: err,
+        });
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new TransportError(`${res.method} ${res.url} did not return a JSON object`, "json", {
+            status: res.status,
+            body: snippet(res.body),
+        });
+    }
+    return parsed;
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Client-side builder SDK for OAuth Attestation-Based Client Authentication.
+ */
+export { SigningKeyPair } from "./signing-key-pair.js";
+export { ClientAttestationBuilder, DpopProofBuilder, PopBuilder, ATTESTATION_TYP, POP_TYP, DPOP_TYP, } from "./builders.js";
+export { ClientAttestationCredential, ATTESTATION_HEADER, POP_HEADER, DPOP_HEADER, } from "./credential.js";
+export { OpenBaoTransitSigner } from "./signer.js";
+export type { JwsSigner } from "./signer.js";
+export { AttestationIssuanceClient, IssuedAttestation, IssuanceError, INSTANCE_PROOF_TYP, } from "./issuance.js";
+export { StaticSvidSource, HttpSvidSource, SpireWorkloadApiSvidSource, } from "./svid-source.js";
+export type { SvidSource } from "./svid-source.js";
+export { EvidenceNotFound, FileTokenSvidSource, GoogleMetadataSvidSource, autoDetectEvidence, ENV_SVID, ENV_TOKEN_FILE, ENV_SPIFFE_SOCKET, DEFAULT_TOKEN_FILE, DEFAULT_SPIFFE_SOCKET, } from "./evidence.js";
+export { ClientAttestation, ClientAttestationError, TransportError, normalizeBaseUrl, jwtSub, DEFAULT_EXPIRY_SKEW_SECONDS, WELL_KNOWN_PATH, } from "./token-source.js";
+export type { ClientAttestationOptions } from "./token-source.js";
+export type { TransportFailure } from "./errors.js";
+export declare const VERSION = "0.2.0";
+/** draft-ietf-oauth-attestation-based-client-auth revision this SDK implements. */
+export declare const DRAFT_REVISION = "10";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * Client-side builder SDK for OAuth Attestation-Based Client Authentication.
+ */
+export { SigningKeyPair } from "./signing-key-pair.js";
+export { ClientAttestationBuilder, DpopProofBuilder, PopBuilder, ATTESTATION_TYP, POP_TYP, DPOP_TYP, } from "./builders.js";
+export { ClientAttestationCredential, ATTESTATION_HEADER, POP_HEADER, DPOP_HEADER, } from "./credential.js";
+export { OpenBaoTransitSigner } from "./signer.js";
+export { AttestationIssuanceClient, IssuedAttestation, IssuanceError, INSTANCE_PROOF_TYP, } from "./issuance.js";
+export { StaticSvidSource, HttpSvidSource, SpireWorkloadApiSvidSource, } from "./svid-source.js";
+export { EvidenceNotFound, FileTokenSvidSource, GoogleMetadataSvidSource, autoDetectEvidence, ENV_SVID, ENV_TOKEN_FILE, ENV_SPIFFE_SOCKET, DEFAULT_TOKEN_FILE, DEFAULT_SPIFFE_SOCKET, } from "./evidence.js";
+export { ClientAttestation, ClientAttestationError, TransportError, normalizeBaseUrl, jwtSub, DEFAULT_EXPIRY_SKEW_SECONDS, WELL_KNOWN_PATH, } from "./token-source.js";
+export const VERSION = "0.2.0";
+/** draft-ietf-oauth-attestation-based-client-auth revision this SDK implements. */
+export const DRAFT_REVISION = "10";

package/dist/issuance.d.ts

@@ -0,0 +1,42 @@
+import { SigningKeyPair } from "./signing-key-pair.js";
+import type { SvidSource } from "./svid-source.js";
+/** The instance-key proof typ presented at the issuance endpoint (server InstanceKeyProofValidator.TYP). */
+export declare const INSTANCE_PROOF_TYP = "oauth-attestation-instance-proof+jwt";
+/**
+ * Thrown when the issuance endpoint rejects the request (non-2xx). Transport failures — unreachable,
+ * timeout, redirect, oversized or malformed response — are a {@link TransportError} instead.
+ */
+export declare class IssuanceError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+/** A minted Client Attestation plus the instance key it is bound to. */
+export declare class IssuedAttestation {
+    readonly attestation: string;
+    readonly expiresIn: number | undefined;
+    readonly instanceKey: SigningKeyPair;
+    constructor(attestation: string, expiresIn: number | undefined, instanceKey: SigningKeyPair);
+    /** A fresh Client Attestation PoP for the token endpoint, signed by the bound instance key. */
+    pop(audience: string, clientId?: string, challenge?: string): Promise<string>;
+    /**
+     * A fresh DPoP proof (RFC 9449) for the token endpoint (attestation combined mode, PoP method
+     * `dpop_combined`), signed by the same bound instance key.
+     */
+    dpop(method: string, uri: string, challenge?: string): Promise<string>;
+}
+/** Bootstraps a Client Attestation for a workload from its SPIFFE JWT-SVID. */
+export declare class AttestationIssuanceClient {
+    readonly endpoint: string;
+    readonly clientId: string;
+    readonly attesterIssuer: string;
+    private readonly source;
+    readonly instanceKey: SigningKeyPair;
+    private constructor();
+    /** Generate a fresh ES256 instance key and return a ready client. */
+    static create(endpoint: string, clientId: string, attesterIssuer: string, source: SvidSource, opts?: {
+        instanceKey?: SigningKeyPair;
+    }): Promise<AttestationIssuanceClient>;
+    /** Fetch the SVID, prove possession of the instance key, and exchange them for a minted attestation. */
+    bootstrap(authorizationDetails?: Array<Record<string, unknown>>, challenge?: string): Promise<IssuedAttestation>;
+}

package/dist/issuance.js

@@ -0,0 +1,110 @@
+/**
+ * Client for the Client Attestation **issuance** endpoint (`POST /federation/attestation`).
+ *
+ * The inverse of {@link ClientAttestationBuilder}: instead of building an attestation locally with an
+ * attester key, a workload proves its SPIFFE identity (a JWT-SVID) and the Authorization Server
+ * (PingFederate) validates it and **mints** a Client Attestation bound to the workload's own instance
+ * key — bootstrapping a client credential from infra identity, no pre-shared secret.
+ */
+import { randomUUID } from "node:crypto";
+import { DpopProofBuilder, PopBuilder } from "./builders.js";
+import { jsonOk, request } from "./http.js";
+import { SigningKeyPair, signCompact } from "./signing-key-pair.js";
+/** The instance-key proof typ presented at the issuance endpoint (server InstanceKeyProofValidator.TYP). */
+export const INSTANCE_PROOF_TYP = "oauth-attestation-instance-proof+jwt";
+/** Per-call timeout for the issuance endpoint. */
+const ISSUANCE_TIMEOUT_MS = 20_000;
+/**
+ * Thrown when the issuance endpoint rejects the request (non-2xx). Transport failures — unreachable,
+ * timeout, redirect, oversized or malformed response — are a {@link TransportError} instead.
+ */
+export class IssuanceError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`attestation issuance failed: HTTP ${status}: ${body}`);
+        this.status = status;
+        this.body = body;
+        this.name = "IssuanceError";
+    }
+}
+/** A minted Client Attestation plus the instance key it is bound to. */
+export class IssuedAttestation {
+    attestation;
+    expiresIn;
+    instanceKey;
+    constructor(attestation, expiresIn, instanceKey) {
+        this.attestation = attestation;
+        this.expiresIn = expiresIn;
+        this.instanceKey = instanceKey;
+    }
+    /** A fresh Client Attestation PoP for the token endpoint, signed by the bound instance key. */
+    async pop(audience, clientId, challenge) {
+        const builder = new PopBuilder(this.instanceKey).audience(audience);
+        if (clientId)
+            builder.clientId(clientId);
+        if (challenge)
+            builder.challenge(challenge);
+        return builder.build();
+    }
+    /**
+     * A fresh DPoP proof (RFC 9449) for the token endpoint (attestation combined mode, PoP method
+     * `dpop_combined`), signed by the same bound instance key.
+     */
+    async dpop(method, uri, challenge) {
+        const builder = new DpopProofBuilder(this.instanceKey).method(method).uri(uri);
+        if (challenge)
+            builder.nonce(challenge);
+        return builder.build();
+    }
+}
+/** Bootstraps a Client Attestation for a workload from its SPIFFE JWT-SVID. */
+export class AttestationIssuanceClient {
+    endpoint;
+    clientId;
+    attesterIssuer;
+    source;
+    instanceKey;
+    constructor(endpoint, clientId, attesterIssuer, source, instanceKey) {
+        this.endpoint = endpoint;
+        this.clientId = clientId;
+        this.attesterIssuer = attesterIssuer;
+        this.source = source;
+        this.instanceKey = instanceKey;
+    }
+    /** Generate a fresh ES256 instance key and return a ready client. */
+    static async create(endpoint, clientId, attesterIssuer, source, opts) {
+        const key = opts?.instanceKey ?? (await SigningKeyPair.generate("ES256"));
+        return new AttestationIssuanceClient(endpoint.replace(/\/$/, ""), clientId, attesterIssuer, source, key);
+    }
+    /** Fetch the SVID, prove possession of the instance key, and exchange them for a minted attestation. */
+    async bootstrap(authorizationDetails, challenge) {
+        const svid = await this.source.fetch(this.attesterIssuer);
+        const proofClaims = {
+            aud: this.attesterIssuer,
+            jti: randomUUID(),
+            iat: Math.floor(Date.now() / 1000),
+        };
+        if (challenge)
+            proofClaims.challenge = challenge;
+        const proof = await signCompact(proofClaims, this.instanceKey, INSTANCE_PROOF_TYP, false);
+        const body = {
+            client_id: this.clientId,
+            instance_key: this.instanceKey.publicJwk(),
+            svid,
+            proof,
+        };
+        if (authorizationDetails)
+            body.authorization_details = authorizationDetails;
+        const res = await request(this.endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Accept: "application/json" },
+            body: JSON.stringify(body),
+            timeoutMs: ISSUANCE_TIMEOUT_MS,
+        });
+        if (!res.ok)
+            throw new IssuanceError(res.status, res.body);
+        const json = jsonOk(res);
+        return new IssuedAttestation(json.attestation, json.expires_in, this.instanceKey);
+    }
+}

package/dist/signer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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>;
+}
+/** Assemble a compact JWS whose signature is produced by an external signer (header carries `kid`; external
+ * signers hold issuing keys, referenced by id, never an embedded jwk). */
+export declare function signExternal(claims: Record<string, unknown>, signer: JwsSigner, typ: string): Promise<string>;
+/**
+ * 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).
+ */
+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,116 @@
+/**
+ * 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 { calculateJwkThumbprint, exportJWK, importSPKI } from "jose";
+import { TransportError } from "./errors.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) => Buffer.from(bytes).toString("base64url");
+/** Assemble a compact JWS whose signature is produced by an external signer (header carries `kid`; external
+ * 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).
+ */
+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: Buffer.from(signingInput).toString("base64"),
+            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 new Uint8Array(Buffer.from(raw, "base64url"));
+    }
+}
+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,50 @@
+/**
+ * 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 extractable 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).
+     */
+    static generate(algorithm: string): 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;
+}
+/** The JWS algorithms {@link SigningKeyPair} can generate and sign with. */
+export declare const SUPPORTED_ALGORITHMS: readonly string[];
+/** RFC 7638 JWK thumbprint (SHA-256, base64url) over the required members only. */
+export declare function thumbprint(publicJwk: JWK): Promise<string>;
+/**
+ * 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.
+ */
+export declare function signCompact(claims: Record<string, unknown>, key: SigningKeyPair, typ: string, embedJwk: boolean): Promise<string>;
+export declare function requireText(value: string | null | undefined, field: string): string;

package/dist/signing-key-pair.js

@@ -0,0 +1,115 @@
+/**
+ * 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 extractable 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).
+     */
+    static async generate(algorithm) {
+        checkAlgorithm(algorithm);
+        const { privateKey, publicKey } = await generateKeyPair(algorithm, {
+            extractable: true,
+            ...(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. */
+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. */
+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.
+ */
+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);
+}
+export function requireText(value, field) {
+    if (value == null || String(value).trim() === "") {
+        throw new Error(`${field} is required`);
+    }
+    return value;
+}