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

package/dist/evidence.js

@@ -0,0 +1,168 @@
+/**
+ * Auto-detect the workload's platform identity (the evidence it presents to the attester).
+ *
+ * The workload proves *what it is* with a token its runtime already issues. Which token, and where it
+ * comes from, depends on the runtime:
+ *
+ * - an explicit token in an environment variable (any runtime that injects one),
+ * - a projected/mounted token file (Kubernetes, GKE),
+ * - a SPIRE Workload API socket (SPIRE / SPIFFE),
+ * - the GCP metadata server (GCE, GKE, Cloud Run, Vertex AI Agent Engine).
+ *
+ * {@link autoDetectEvidence} tries these in order and returns the first that applies, so a developer
+ * can write `new ClientAttestation(attesterUrl)` and have it work without naming the source. Override by
+ * passing an explicit {@link SvidSource} to {@link ClientAttestation}.
+ */
+import { TransportError } from "./errors.js";
+import { request, snippet } from "./http.js";
+import { envVar, importNodeBuiltin } from "./runtime.js";
+import { SpireWorkloadApiSvidSource, StaticSvidSource } from "./svid-source.js";
+/** Environment variable holding the evidence token itself (static). */
+export const ENV_SVID = "CLIENT_ATTESTATION_SVID";
+/** Environment variable holding a path to a projected token file. */
+export const ENV_TOKEN_FILE = "CLIENT_ATTESTATION_TOKEN_FILE";
+/** SPIRE Workload API socket (standard SPIFFE var). */
+export const ENV_SPIFFE_SOCKET = "SPIFFE_ENDPOINT_SOCKET";
+/** Default projected-token path used by the Kubernetes/GKE serviceAccountToken volume convention. */
+export const DEFAULT_TOKEN_FILE = "/var/run/secrets/tokens/attester-token";
+/** Default SPIRE agent socket path. */
+export const DEFAULT_SPIFFE_SOCKET = "/tmp/spire-agent/public/api.sock";
+/**
+ * GCP metadata server origin.
+ *
+ * @internal
+ */
+export const GCP_METADATA_BASE = "http://metadata.google.internal";
+/**
+ * GCP metadata server identity endpoint (returns a Google-signed ID token for the runtime SA).
+ *
+ * @internal
+ */
+export const GCP_METADATA_IDENTITY = GCP_METADATA_BASE + "/computeMetadata/v1/instance/service-accounts/default/identity";
+/** No platform identity could be detected and none was supplied. */
+export class EvidenceNotFound extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EvidenceNotFound";
+    }
+}
+/**
+ * Reads the evidence token from a file on every fetch.
+ *
+ * Kubernetes and GKE mount a short-lived, auto-rotated service-account token into the pod as a file
+ * (a projected `serviceAccountToken` volume). Reading it fresh each time picks up the rotation. The
+ * file's audience must already be the attester's evidence audience — set it when you declare the volume.
+ *
+ * Needs a filesystem: `node:fs/promises` is loaded on the first `fetch`, which throws a
+ * `ClientAttestationError` on a runtime without it.
+ */
+export class FileTokenSvidSource {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async fetch(_audience) {
+        const { readFile } = await importNodeBuiltin("fs/promises", "FileTokenSvidSource");
+        const contents = await readFile(this.path, "utf8");
+        return contents.trim();
+    }
+}
+/**
+ * Fetches a Google-signed ID token for the runtime service account from the GCP metadata server.
+ *
+ * Works on any Google runtime that exposes the metadata server (GCE, GKE, Cloud Run, Vertex AI Agent
+ * Engine). The token's `aud` is the attester's evidence audience; `sub` is the service account. No
+ * google-auth dependency — a plain metadata call.
+ */
+export class GoogleMetadataSvidSource {
+    timeoutMs;
+    identityUrl;
+    /**
+     * @param timeoutMs per-request timeout.
+     * @param identityUrl the identity endpoint; internal, for tests - defaults to the real metadata server.
+     */
+    constructor(timeoutMs = 5000, identityUrl = GCP_METADATA_IDENTITY) {
+        this.timeoutMs = timeoutMs;
+        this.identityUrl = identityUrl;
+    }
+    async fetch(audience) {
+        const url = `${this.identityUrl}?audience=${encodeURIComponent(audience)}&format=full`;
+        const res = await request(url, {
+            method: "GET",
+            headers: { "Metadata-Flavor": "Google" },
+            timeoutMs: this.timeoutMs,
+        });
+        if (!res.ok) {
+            throw new TransportError(`GCP metadata identity endpoint -> ${res.status}`, "status", {
+                status: res.status,
+                body: snippet(res.body),
+            });
+        }
+        return res.body.trim();
+    }
+}
+/**
+ * A path-existence check, or one that always answers `false` on a runtime with no filesystem (an edge
+ * runtime), where the file and socket sources cannot apply.
+ */
+async function pathProbe() {
+    try {
+        const { existsSync } = await importNodeBuiltin("fs", "autoDetectEvidence");
+        return existsSync;
+    }
+    catch {
+        return () => false;
+    }
+}
+async function gcpMetadataAvailable(base, timeoutMs = 300) {
+    try {
+        const res = await request(base + "/computeMetadata/v1/", {
+            method: "GET",
+            headers: { "Metadata-Flavor": "Google" },
+            timeoutMs,
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export async function autoDetectEvidence(opts = {}) {
+    const exists = await pathProbe();
+    const defaultTokenFile = opts.defaultTokenFile ?? DEFAULT_TOKEN_FILE;
+    const defaultSocket = opts.defaultSpiffeSocket ?? DEFAULT_SPIFFE_SOCKET;
+    const metadataBase = (opts.gcpMetadataBase ?? GCP_METADATA_BASE).replace(/\/+$/, "");
+    const staticToken = envVar(ENV_SVID);
+    if (staticToken) {
+        return new StaticSvidSource(staticToken.trim());
+    }
+    // An explicitly configured source that is missing is a misconfiguration: fail closed rather than
+    // fall through to a different identity the operator did not choose.
+    const tokenFile = envVar(ENV_TOKEN_FILE);
+    if (tokenFile) {
+        if (!exists(tokenFile)) {
+            throw new EvidenceNotFound(`${ENV_TOKEN_FILE} is set to ${tokenFile}, but no such file exists`);
+        }
+        return new FileTokenSvidSource(tokenFile);
+    }
+    if (exists(defaultTokenFile)) {
+        return new FileTokenSvidSource(defaultTokenFile);
+    }
+    const socket = envVar(ENV_SPIFFE_SOCKET);
+    if (socket) {
+        const socketPath = socket.replace(/^unix:\/\//, "");
+        if (!exists(socketPath)) {
+            throw new EvidenceNotFound(`${ENV_SPIFFE_SOCKET} is set to ${socket}, but no such socket exists`);
+        }
+        return new SpireWorkloadApiSvidSource(socketPath);
+    }
+    if (exists(defaultSocket)) {
+        return new SpireWorkloadApiSvidSource(defaultSocket);
+    }
+    if (await gcpMetadataAvailable(metadataBase, opts.gcpProbeTimeoutMs)) {
+        return new GoogleMetadataSvidSource(5000, metadataBase + "/computeMetadata/v1/instance/service-accounts/default/identity");
+    }
+    throw new EvidenceNotFound("Could not auto-detect the workload's platform identity. Set one of " +
+        `${ENV_SVID} (the token), ${ENV_TOKEN_FILE} (a token file), or ${ENV_SPIFFE_SOCKET} (SPIRE socket), ` +
+        "or pass evidence=<SvidSource> to ClientAttestation explicitly.");
+}

package/dist/http.d.ts

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

package/dist/http.js

@@ -0,0 +1,183 @@
+/**
+ * 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";
+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.
+ *
+ * @internal
+ */
+export const ERROR_BODY_CHARS = 512;
+/**
+ * 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;
+}
+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.
+ *
+ * @internal
+ */
+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 (utf8Encode(text).byteLength > 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);
+    }
+    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) {
+        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.
+ *
+ * @internal
+ */
+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,26 @@
+/**
+ * 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";
+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, 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 { 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

@@ -0,0 +1,20 @@
+/**
+ * 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";
+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, 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

@@ -0,0 +1,61 @@
+/**
+ * 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 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.
+ */
+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.
+ *
+ * `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

@@ -0,0 +1,117 @@
+/**
+ * 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 { MintRequest, PingFederateProfile } from "./attester.js";
+import { DpopProofBuilder, PopBuilder } from "./builders.js";
+import { jsonOk, request } from "./http.js";
+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;
+/**
+ * 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.
+ *
+ * `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;
+    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"));
+        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 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: body === undefined ? undefined : JSON.stringify(body),
+            timeoutMs: ISSUANCE_TIMEOUT_MS,
+        });
+        if (!res.ok)
+            throw new IssuanceError(res.status, res.body);
+        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 {};