@idpartners/client-attestation-sdk 0.2.0 → 1.0.0

package/dist/http.js

@@ -12,11 +12,22 @@
  *   into a {@link TransportError}.
  */
 import { TransportError } from "./errors.js";
+import { utf8Decode, utf8Encode } from "./runtime.js";
+/** @internal */
 export const DEFAULT_MAX_BYTES = 1024 * 1024;
+/** @internal */
 export const DEFAULT_TIMEOUT_MS = 20_000;
-/** At most this many characters of a response body are carried in an error. */
+/**
+ * At most this many characters of a response body are carried in an error.
+ *
+ * @internal
+ */
 export const ERROR_BODY_CHARS = 512;
-/** The first {@link ERROR_BODY_CHARS} characters of a body, for an error message. */
+/**
+ * The first {@link ERROR_BODY_CHARS} characters of a body, for an error message.
+ *
+ * @internal
+ */
 export function snippet(body) {
     return body.length > ERROR_BODY_CHARS ? body.slice(0, ERROR_BODY_CHARS) : body;
 }
@@ -31,6 +42,8 @@ function isAbort(err) {
  * 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.
+ *
+ * @internal
  */
 export async function request(url, opts = {}) {
     const method = opts.method ?? "GET";
@@ -98,7 +111,7 @@ 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)
+        if (utf8Encode(text).byteLength > maxBytes)
             throw tooLarge();
         return text;
     }
@@ -116,12 +129,20 @@ async function readCapped(res, maxBytes, tooLarge) {
         }
         chunks.push(value);
     }
-    return Buffer.concat(chunks).toString("utf8");
+    const all = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        all.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return utf8Decode(all);
 }
 /**
  * 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.
+ *
+ * @internal
  */
 export function jsonOk(res, opts = {}) {
     if (!res.ok) {
@@ -133,7 +154,11 @@ export function jsonOk(res, opts = {}) {
     }
     return parseJsonObject(res, opts);
 }
-/** Parse `res.body` as a JSON object regardless of status; a {@link TransportError} if it is not one. */
+/**
+ * Parse `res.body` as a JSON object regardless of status; a {@link TransportError} if it is not one.
+ *
+ * @internal
+ */
 export function parseJsonObject(res, opts = {}) {
     if (opts.allowEmpty && res.body === "")
         return {};

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 /**
  * Client-side builder SDK for OAuth Attestation-Based Client Authentication.
+ *
+ * Everything exported here is the package's API; docs/api.md says which parts are Stable and which are
+ * Experimental. Nothing else under dist/ can be imported: package.json "exports" allows only this entry
+ * point and "./validator".
  */
 export { SigningKeyPair } from "./signing-key-pair.js";
 export { ClientAttestationBuilder, DpopProofBuilder, PopBuilder, ATTESTATION_TYP, POP_TYP, DPOP_TYP, } from "./builders.js";
@@ -10,9 +14,13 @@ export { AttestationIssuanceClient, IssuedAttestation, IssuanceError, INSTANCE_P
 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 { ClientAttestation, ClientAttestationError, TransportError, DEFAULT_EXPIRY_SKEW_SECONDS, } from "./token-source.js";
+export type { AttesterDiscovery, ClientAttestationOptions } from "./token-source.js";
+export { MintRequest, PingFederateProfile } from "./attester.js";
+export type { AttesterMetadata, AttesterProfile, AttesterTransport, MintResult } from "./attester.js";
 export type { TransportFailure } from "./errors.js";
-export declare const VERSION = "0.2.0";
+export { NOOP_LOGGER } from "./logging.js";
+export type { Logger, LogAttributes, LogLevel } from "./logging.js";
+export declare const VERSION = "1.0.0";
 /** draft-ietf-oauth-attestation-based-client-auth revision this SDK implements. */
 export declare const DRAFT_REVISION = "10";

package/dist/index.js

@@ -1,5 +1,9 @@
 /**
  * Client-side builder SDK for OAuth Attestation-Based Client Authentication.
+ *
+ * Everything exported here is the package's API; docs/api.md says which parts are Stable and which are
+ * Experimental. Nothing else under dist/ can be imported: package.json "exports" allows only this entry
+ * point and "./validator".
  */
 export { SigningKeyPair } from "./signing-key-pair.js";
 export { ClientAttestationBuilder, DpopProofBuilder, PopBuilder, ATTESTATION_TYP, POP_TYP, DPOP_TYP, } from "./builders.js";
@@ -8,7 +12,9 @@ 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";
+export { ClientAttestation, ClientAttestationError, TransportError, DEFAULT_EXPIRY_SKEW_SECONDS, } from "./token-source.js";
+export { MintRequest, PingFederateProfile } from "./attester.js";
+export { NOOP_LOGGER } from "./logging.js";
+export const VERSION = "1.0.0";
 /** draft-ietf-oauth-attestation-based-client-auth revision this SDK implements. */
 export const DRAFT_REVISION = "10";

package/dist/issuance.d.ts

@@ -1,7 +1,16 @@
+/**
+ * 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 { type AttesterProfile } from "./attester.js";
 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";
+/** The instance-key proof typ the PingFederate profile presents (server InstanceKeyProofValidator.TYP). */
+export { INSTANCE_PROOF_TYP } from "./attester.js";
 /**
  * Thrown when the issuance endpoint rejects the request (non-2xx). Transport failures — unreachable,
  * timeout, redirect, oversized or malformed response — are a {@link TransportError} instead.
@@ -25,17 +34,27 @@ export declare class IssuedAttestation {
      */
     dpop(method: string, uri: string, challenge?: string): Promise<string>;
 }
-/** Bootstraps a Client Attestation for a workload from its SPIFFE JWT-SVID. */
+/**
+ * Bootstraps a Client Attestation for a workload from its SPIFFE JWT-SVID.
+ *
+ * `opts.profile` sets the mint protocol (default {@link PingFederateProfile}; see
+ * docs/attester-profiles.md). The endpoint is given directly, so the profile's discovery is not used.
+  *
+  * @experimental See docs/api.md: it calls a PingFederate demo issuance servlet (/federation/attestation)
+  * whose protocol is not standardised.
+ */
 export declare class AttestationIssuanceClient {
     readonly endpoint: string;
     readonly clientId: string;
     readonly attesterIssuer: string;
     private readonly source;
     readonly instanceKey: SigningKeyPair;
+    readonly profile: AttesterProfile;
     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;
+        profile?: AttesterProfile;
     }): 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

@@ -6,12 +6,12 @@
  * (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 { MintRequest, PingFederateProfile } from "./attester.js";
 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";
+import { SigningKeyPair } from "./signing-key-pair.js";
+/** The instance-key proof typ the PingFederate profile presents (server InstanceKeyProofValidator.TYP). */
+export { INSTANCE_PROOF_TYP } from "./attester.js";
 /** Per-call timeout for the issuance endpoint. */
 const ISSUANCE_TIMEOUT_MS = 20_000;
 /**
@@ -58,53 +58,60 @@ export class IssuedAttestation {
         return builder.build();
     }
 }
-/** Bootstraps a Client Attestation for a workload from its SPIFFE JWT-SVID. */
+/**
+ * Bootstraps a Client Attestation for a workload from its SPIFFE JWT-SVID.
+ *
+ * `opts.profile` sets the mint protocol (default {@link PingFederateProfile}; see
+ * docs/attester-profiles.md). The endpoint is given directly, so the profile's discovery is not used.
+  *
+  * @experimental See docs/api.md: it calls a PingFederate demo issuance servlet (/federation/attestation)
+  * whose protocol is not standardised.
+ */
 export class AttestationIssuanceClient {
     endpoint;
     clientId;
     attesterIssuer;
     source;
     instanceKey;
-    constructor(endpoint, clientId, attesterIssuer, source, instanceKey) {
+    profile;
+    constructor(endpoint, clientId, attesterIssuer, source, instanceKey, profile) {
         this.endpoint = endpoint;
         this.clientId = clientId;
         this.attesterIssuer = attesterIssuer;
         this.source = source;
         this.instanceKey = instanceKey;
+        this.profile = profile;
     }
     /** 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);
+        const profile = opts?.profile ?? new PingFederateProfile();
+        return new AttestationIssuanceClient(endpoint.replace(/\/$/, ""), clientId, attesterIssuer, source, key, profile);
     }
     /** 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",
+        const minted = await this.profile.mint(issuanceTransport, { evidenceAudience: this.attesterIssuer, attestationEndpoint: this.endpoint }, new MintRequest({
+            instanceKey: this.instanceKey,
+            evidence: svid,
+            challenge: challenge || undefined,
+            clientId: this.clientId,
+            authorizationDetails,
+        }));
+        return new IssuedAttestation(minted.attestation, minted.expiresIn, this.instanceKey);
+    }
+}
+/** The issuance endpoint's transport: a non-2xx answer is an {@link IssuanceError}. */
+const issuanceTransport = {
+    async requestJson(_step, method, url, body) {
+        const res = await request(url, {
+            method,
             headers: { "Content-Type": "application/json", Accept: "application/json" },
-            body: JSON.stringify(body),
+            body: body === undefined ? undefined : 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);
-    }
-}
+        return jsonOk(res);
+    },
+};

package/dist/logging.d.ts

@@ -0,0 +1,12 @@
+/** Attributes carried with an event. */
+export type LogAttributes = Record<string, unknown>;
+/** Anything with these four methods: `console` fits, as do pino, winston and bunyan wrappers. */
+export interface Logger {
+    debug(msg: string, attrs?: LogAttributes): void;
+    info(msg: string, attrs?: LogAttributes): void;
+    warn(msg: string, attrs?: LogAttributes): void;
+    error(msg: string, attrs?: LogAttributes): void;
+}
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/** The default: drops everything. */
+export declare const NOOP_LOGGER: Logger;

package/dist/logging.js

@@ -0,0 +1,77 @@
+/**
+ * Optional logging. The SDK is silent unless a {@link Logger} is passed in (`logger` on
+ * `ClientAttestation` and on `AccessTokenValidator`). Event names and attribute keys are shared with the
+ * other ports; see docs/logging.md.
+ *
+ * Never logged: tokens, attestations, proofs, SVIDs, challenge values, key material, header values, or
+ * URLs with their query string. As a backstop, any string attribute containing `eyJ` (how a JWT's
+ * base64url-encoded header begins) is replaced with `<redacted:N bytes>` before it reaches the logger.
+ */
+import { TransportError } from "./errors.js";
+import { utf8Encode } from "./runtime.js";
+const noop = () => undefined;
+/** The default: drops everything. */
+export const NOOP_LOGGER = { debug: noop, info: noop, warn: noop, error: noop };
+function guard(value) {
+    if (typeof value !== "string")
+        return value;
+    // A JWT's header and claims (any base64url-encoded JSON object) begin with "eyJ".
+    if (value.includes("eyJ")) {
+        return `<redacted:${utf8Encode(value).length} bytes>`;
+    }
+    return value;
+}
+/**
+ * Emit one event: undefined attributes dropped, JWT-looking values redacted. Never throws.
+ *
+ * @internal
+ */
+export function emit(logger, level, event, attrs = {}) {
+    if (logger === NOOP_LOGGER)
+        return;
+    const clean = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value !== undefined && value !== null)
+            clean[key] = guard(value);
+    }
+    try {
+        logger[level](event, clean);
+    }
+    catch {
+        // a broken logger must never break the flow
+    }
+}
+/**
+ * `host[:port]` and the path of a URL, never its query string or fragment.
+ *
+ * @internal
+ */
+export function urlParts(url) {
+    try {
+        const parsed = new URL(url);
+        return { host: parsed.host, path: parsed.pathname };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * `host[:port]` of a URL.
+ *
+ * @internal
+ */
+export function hostOf(url) {
+    return urlParts(url).host;
+}
+/**
+ * The `reason` attribute for a failed outbound call.
+ *
+ * @internal
+ */
+export function failureReason(err) {
+    if (err instanceof TransportError)
+        return err.kind === "json" ? "malformed" : err.kind;
+    if (err instanceof SyntaxError)
+        return "malformed";
+    return "network";
+}

package/dist/runtime.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -13,14 +13,13 @@ export interface JwsSigner {
     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).
+ *
+ * @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;

package/dist/signer.js

@@ -4,13 +4,16 @@
  * {@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 { 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) => Buffer.from(bytes).toString("base64url");
+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();
@@ -26,6 +29,8 @@ const ALG_HASH = { ES256: "sha2-256", ES384: "sha2-384", ES512: "sha2-512" };
  * 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;
@@ -67,7 +72,7 @@ export class OpenBaoTransitSigner {
     }
     async sign(signingInput) {
         const body = JSON.stringify({
-            input: Buffer.from(signingInput).toString("base64"),
+            input: base64Encode(signingInput),
             marshaling_algorithm: "jws",
             hash_algorithm: this.#hash,
             key_version: this.#keyVersion,
@@ -78,7 +83,7 @@ export class OpenBaoTransitSigner {
             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"));
+        return base64url.decode(raw);
     }
 }
 async function request(method, base, token, path, body) {

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

@@ -19,11 +19,17 @@ export declare class SigningKeyPair {
     readonly keyId: string;
     private constructor();
     /**
-     * Generate a fresh extractable key pair for the given JWS algorithm: `ES256` / `ES384` / `ES512`
+     * 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): Promise<SigningKeyPair>;
+    static generate(algorithm: string, options?: {
+        extractable?: boolean;
+    }): Promise<SigningKeyPair>;
     /**
      * Wrap an existing JWK (which must contain the private component `d`) for the given algorithm.
      */
@@ -36,15 +42,3 @@ export declare class SigningKeyPair {
      */
     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

@@ -26,14 +26,18 @@ export class SigningKeyPair {
         this.keyId = keyId;
     }
     /**
-     * Generate a fresh extractable key pair for the given JWS algorithm: `ES256` / `ES384` / `ES512`
+     * 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) {
+    static async generate(algorithm, options = {}) {
         checkAlgorithm(algorithm);
         const { privateKey, publicKey } = await generateKeyPair(algorithm, {
-            extractable: true,
+            extractable: options.extractable ?? false,
             ...(algorithm.startsWith("ES") ? {} : { modulusLength: RSA_MODULUS_BITS }),
         });
         const publicJwk = publicMembers(await exportJWK(publicKey));
@@ -66,7 +70,11 @@ export class SigningKeyPair {
         return { ...this.#publicJwk };
     }
 }
-/** The JWS algorithms {@link SigningKeyPair} can generate and sign with. */
+/**
+ * The JWS algorithms {@link SigningKeyPair} can generate and sign with.
+ *
+ * @internal
+ */
 export const SUPPORTED_ALGORITHMS = [
     "ES256", "ES384", "ES512",
     "RS256", "RS384", "RS512",
@@ -85,7 +93,11 @@ function publicMembers(jwk) {
         ? { 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. */
+/**
+ * RFC 7638 JWK thumbprint (SHA-256, base64url) over the required members only.
+ *
+ * @internal
+ */
 export async function thumbprint(publicJwk) {
     return calculateJwkThumbprint(publicJwk, "sha256");
 }
@@ -94,6 +106,8 @@ export async function thumbprint(publicJwk) {
  *
  * 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 };
@@ -107,6 +121,7 @@ export async function signCompact(claims, key, typ, embedJwk) {
     }
     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`);

package/dist/svid-source.d.ts

@@ -8,7 +8,15 @@ export declare class StaticSvidSource implements SvidSource {
     constructor(svid: string);
     fetch(_audience: string): Promise<string>;
 }
-/** 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 declare class HttpSvidSource implements SvidSource {
     private readonly url;
     constructor(url: string);
@@ -18,6 +26,12 @@ export declare class HttpSvidSource implements SvidSource {
  * 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;