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

package/dist/builders.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Builders for the attestation, PoP and DPoP JWTs (draft-ietf-oauth-attestation-based-client-auth).
+ */
+import { type JWK } from "jose";
+import { SigningKeyPair } from "./signing-key-pair.js";
+import { type JwsSigner } from "./signer.js";
+export declare const ATTESTATION_TYP = "oauth-client-attestation+jwt";
+export declare const POP_TYP = "oauth-client-attestation-pop+jwt";
+export declare const DPOP_TYP = "dpop+jwt";
+/**
+ * Builds a Client Attestation JWT — the credential a Client Attester issues to name a client
+ * (`sub`) and bind its instance key via `cnf.jwk`. Attester side; sign with the attester's key.
+ */
+export declare class ClientAttestationBuilder {
+    #private;
+    constructor(attesterKey: SigningKeyPair | JwsSigner, issuer: string);
+    /** The client being attested — becomes the attestation `sub` (= `client_id`). */
+    clientId(clientId: string): this;
+    /** Binds the client instance key as `cnf.jwk`. Must be a public JWK. */
+    confirmationJwk(publicInstanceJwk: JWK): this;
+    /** Convenience: binds the public half of the given instance key as `cnf.jwk`. */
+    confirmationKey(instanceKey: SigningKeyPair): this;
+    issuedAt(epochSeconds: number): this;
+    /** Sets an absolute `exp`. */
+    expiresAt(epochSeconds: number): this;
+    /** Sets `exp` to `iat + seconds`. */
+    expiresIn(seconds: number): this;
+    /** The optional RFC 9396 `authorization_details` entitlement the attester asserts. */
+    authorizationDetails(details: unknown[]): this;
+    /** Optional attester-asserted `workload` attributes. */
+    workload(workload: Record<string, unknown>): this;
+    /**
+     * Names the client's OPERATOR — the human or organisation accountable for running this client,
+     * as distinct from the client itself (`sub`) and from the principal it acts for.
+     *
+     * Deliberately a top-level claim rather than a member of `workload`: `workload` describes the
+     * running software, whereas the operator is an accountability statement about who answers for
+     * it. It is per-client and static, so it does not affect how far an attestation can be cached.
+     *
+     * The shape mirrors RFC 8693 `may_act` (`{ sub: ..., iss: ... }`) on purpose. An AS that wants
+     * the operator to become the party authorised to act for the subject can lift this straight
+     * into `may_act`; `iss` names the OP the operator's `sub` is meaningful in, so the identifier is
+     * not ambiguous across directories.
+     *
+     * This is an ASSERTION by the attester, not proof the operator authorised anything. A relying
+     * AS should treat it as it treats the rest of the attestation: trusted exactly as far as the
+     * attester is.
+     */
+    operator(sub: string, issuer?: string | null): this;
+    build(): Promise<string>;
+}
+/**
+ * Builds a Client Attestation PoP JWT proving possession of the instance key. Client side of
+ * `attest_jwt_client_auth`; mint a fresh one per token request.
+ */
+export declare class PopBuilder {
+    #private;
+    constructor(instanceKey: SigningKeyPair);
+    /** Sets the optional `iss`; when present the verifier requires it to equal the attestation `sub`. */
+    clientId(clientId: string | null): this;
+    /** The AS identifier this PoP is bound to (`aud`) — required. */
+    audience(audience: string): this;
+    challenge(challenge: string | null): this;
+    jwtId(jwtId: string): this;
+    issuedAt(epochSeconds: number): this;
+    build(): Promise<string>;
+}
+/**
+ * Builds a DPoP proof JWT (RFC 9449) for attestation combined mode
+ * (PoP method `dpop_combined`): the embedded `jwk` header MUST be the attestation's `cnf` key.
+ */
+export declare class DpopProofBuilder {
+    #private;
+    constructor(instanceKey: SigningKeyPair);
+    /** The request's HTTP method (`htm`, upper-cased when built); defaults to `POST`. */
+    method(htm: string | null | undefined): this;
+    /**
+     * The target URL (`htu`) — required. Normalised when built: query and fragment are dropped, and
+     * scheme and host lower-cased (RFC 9449 section 4.2).
+     */
+    uri(htu: string): this;
+    /** The server challenge, carried in DPoP `nonce`. */
+    nonce(nonce: string | null): this;
+    /**
+     * The access token this proof accompanies at a resource: sets `ath` = base64url(SHA-256(token)).
+     * Leave unset for a proof sent to the token endpoint.
+     */
+    accessToken(accessToken: string | null): this;
+    jwtId(jwtId: string): this;
+    issuedAt(epochSeconds: number): this;
+    build(): Promise<string>;
+}

package/dist/builders.js

@@ -0,0 +1,284 @@
+/**
+ * Builders for the attestation, PoP and DPoP JWTs (draft-ietf-oauth-attestation-based-client-auth).
+ */
+import { base64url } from "jose";
+import { SigningKeyPair, requireText, signCompact } from "./signing-key-pair.js";
+import { utf8Encode } from "./runtime.js";
+import { signExternal } from "./signer.js";
+export const ATTESTATION_TYP = "oauth-client-attestation+jwt";
+export const POP_TYP = "oauth-client-attestation-pop+jwt";
+export const DPOP_TYP = "dpop+jwt";
+function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+/**
+ * Builds a Client Attestation JWT — the credential a Client Attester issues to name a client
+ * (`sub`) and bind its instance key via `cnf.jwk`. Attester side; sign with the attester's key.
+ */
+export class ClientAttestationBuilder {
+    #attesterKey;
+    #issuer;
+    #clientId = null;
+    #cnfJwk = null;
+    #issuedAt = null;
+    #expiresAt = null;
+    #ttl = null;
+    #authorizationDetails = null;
+    #workload = null;
+    #operator = null;
+    constructor(attesterKey, issuer) {
+        this.#attesterKey = attesterKey;
+        this.#issuer = requireText(issuer, "issuer");
+    }
+    /** The client being attested — becomes the attestation `sub` (= `client_id`). */
+    clientId(clientId) {
+        this.#clientId = clientId;
+        return this;
+    }
+    /** Binds the client instance key as `cnf.jwk`. Must be a public JWK. */
+    confirmationJwk(publicInstanceJwk) {
+        this.#cnfJwk = publicInstanceJwk;
+        return this;
+    }
+    /** Convenience: binds the public half of the given instance key as `cnf.jwk`. */
+    confirmationKey(instanceKey) {
+        return this.confirmationJwk(instanceKey.publicJwk());
+    }
+    issuedAt(epochSeconds) {
+        this.#issuedAt = epochSeconds;
+        return this;
+    }
+    /** Sets an absolute `exp`. */
+    expiresAt(epochSeconds) {
+        this.#expiresAt = epochSeconds;
+        return this;
+    }
+    /** Sets `exp` to `iat + seconds`. */
+    expiresIn(seconds) {
+        this.#ttl = seconds;
+        return this;
+    }
+    /** The optional RFC 9396 `authorization_details` entitlement the attester asserts. */
+    authorizationDetails(details) {
+        this.#authorizationDetails = details;
+        return this;
+    }
+    /** Optional attester-asserted `workload` attributes. */
+    workload(workload) {
+        this.#workload = workload;
+        return this;
+    }
+    /**
+     * Names the client's OPERATOR — the human or organisation accountable for running this client,
+     * as distinct from the client itself (`sub`) and from the principal it acts for.
+     *
+     * Deliberately a top-level claim rather than a member of `workload`: `workload` describes the
+     * running software, whereas the operator is an accountability statement about who answers for
+     * it. It is per-client and static, so it does not affect how far an attestation can be cached.
+     *
+     * The shape mirrors RFC 8693 `may_act` (`{ sub: ..., iss: ... }`) on purpose. An AS that wants
+     * the operator to become the party authorised to act for the subject can lift this straight
+     * into `may_act`; `iss` names the OP the operator's `sub` is meaningful in, so the identifier is
+     * not ambiguous across directories.
+     *
+     * This is an ASSERTION by the attester, not proof the operator authorised anything. A relying
+     * AS should treat it as it treats the rest of the attestation: trusted exactly as far as the
+     * attester is.
+     */
+    operator(sub, issuer) {
+        const operator = { sub: requireText(sub, "operator sub") };
+        if (issuer) {
+            operator.iss = issuer;
+        }
+        this.#operator = operator;
+        return this;
+    }
+    async build() {
+        const sub = requireText(this.#clientId, "client_id");
+        if (this.#cnfJwk === null) {
+            throw new Error("confirmation key (cnf.jwk) is required");
+        }
+        const iat = this.#issuedAt !== null ? this.#issuedAt : nowSeconds();
+        const exp = this.#resolveExpiry(iat);
+        const claims = {
+            iss: this.#issuer,
+            sub,
+            iat,
+            exp,
+            cnf: { jwk: this.#cnfJwk },
+        };
+        if (this.#authorizationDetails && this.#authorizationDetails.length > 0) {
+            claims.authorization_details = this.#authorizationDetails;
+        }
+        if (this.#workload && Object.keys(this.#workload).length > 0) {
+            claims.workload = this.#workload;
+        }
+        if (this.#operator) {
+            claims.operator = this.#operator;
+        }
+        if (this.#attesterKey instanceof SigningKeyPair) {
+            return signCompact(claims, this.#attesterKey, ATTESTATION_TYP, false);
+        }
+        return signExternal(claims, this.#attesterKey, ATTESTATION_TYP);
+    }
+    #resolveExpiry(iat) {
+        if (this.#expiresAt !== null) {
+            return this.#expiresAt;
+        }
+        if (this.#ttl !== null) {
+            return iat + this.#ttl;
+        }
+        throw new Error("expiry is required: call expiresAt(...) or expiresIn(...)");
+    }
+}
+/**
+ * Builds a Client Attestation PoP JWT proving possession of the instance key. Client side of
+ * `attest_jwt_client_auth`; mint a fresh one per token request.
+ */
+export class PopBuilder {
+    #instanceKey;
+    #clientId = null;
+    #audience = null;
+    #challenge = null;
+    #jwtId = null;
+    #issuedAt = null;
+    constructor(instanceKey) {
+        this.#instanceKey = instanceKey;
+    }
+    /** Sets the optional `iss`; when present the verifier requires it to equal the attestation `sub`. */
+    clientId(clientId) {
+        this.#clientId = clientId;
+        return this;
+    }
+    /** The AS identifier this PoP is bound to (`aud`) — required. */
+    audience(audience) {
+        this.#audience = audience;
+        return this;
+    }
+    challenge(challenge) {
+        this.#challenge = challenge;
+        return this;
+    }
+    jwtId(jwtId) {
+        this.#jwtId = jwtId;
+        return this;
+    }
+    issuedAt(epochSeconds) {
+        this.#issuedAt = epochSeconds;
+        return this;
+    }
+    async build() {
+        if (!this.#audience) {
+            throw new Error("audience (aud) is required");
+        }
+        const claims = {
+            aud: this.#audience,
+            jti: this.#jwtId ?? crypto.randomUUID(),
+            iat: this.#issuedAt !== null ? this.#issuedAt : nowSeconds(),
+        };
+        if (this.#clientId) {
+            claims.iss = this.#clientId;
+        }
+        if (this.#challenge) {
+            claims.challenge = this.#challenge;
+        }
+        return signCompact(claims, this.#instanceKey, POP_TYP, false);
+    }
+}
+/**
+ * Builds a DPoP proof JWT (RFC 9449) for attestation combined mode
+ * (PoP method `dpop_combined`): the embedded `jwk` header MUST be the attestation's `cnf` key.
+ */
+export class DpopProofBuilder {
+    #instanceKey;
+    #htm = "POST";
+    #htu = null;
+    #nonce = null;
+    #accessToken = null;
+    #jwtId = null;
+    #issuedAt = null;
+    constructor(instanceKey) {
+        this.#instanceKey = instanceKey;
+    }
+    /** The request's HTTP method (`htm`, upper-cased when built); defaults to `POST`. */
+    method(htm) {
+        if (htm) {
+            this.#htm = htm;
+        }
+        return this;
+    }
+    /**
+     * The target URL (`htu`) — required. Normalised when built: query and fragment are dropped, and
+     * scheme and host lower-cased (RFC 9449 section 4.2).
+     */
+    uri(htu) {
+        this.#htu = htu;
+        return this;
+    }
+    /** The server challenge, carried in DPoP `nonce`. */
+    nonce(nonce) {
+        this.#nonce = nonce;
+        return this;
+    }
+    /**
+     * The access token this proof accompanies at a resource: sets `ath` = base64url(SHA-256(token)).
+     * Leave unset for a proof sent to the token endpoint.
+     */
+    accessToken(accessToken) {
+        this.#accessToken = accessToken || null;
+        return this;
+    }
+    jwtId(jwtId) {
+        this.#jwtId = jwtId;
+        return this;
+    }
+    issuedAt(epochSeconds) {
+        this.#issuedAt = epochSeconds;
+        return this;
+    }
+    async build() {
+        if (!this.#htu) {
+            throw new Error("uri (htu) is required");
+        }
+        const claims = {
+            htm: this.#htm.toUpperCase(),
+            htu: normalizeHtu(this.#htu),
+            jti: this.#jwtId ?? crypto.randomUUID(),
+            iat: this.#issuedAt !== null ? this.#issuedAt : nowSeconds(),
+        };
+        if (this.#nonce) {
+            claims.nonce = this.#nonce;
+        }
+        if (this.#accessToken) {
+            claims.ath = await accessTokenHash(this.#accessToken);
+        }
+        return signCompact(claims, this.#instanceKey, DPOP_TYP, true);
+    }
+}
+/**
+ * RFC 9449 `ath`: base64url(SHA-256(ASCII access token)).
+ *
+ * @internal
+ */
+export async function accessTokenHash(accessToken) {
+    const digest = await crypto.subtle.digest("SHA-256", utf8Encode(accessToken));
+    return base64url.encode(new Uint8Array(digest));
+}
+/**
+ * The DPoP `htu` for a URL: scheme, host, port and path, with no query and no fragment. Scheme and host
+ * are lower-cased and a default port dropped; a URL with no path keeps none (no slash is invented).
+ *
+ * @internal
+ */
+export function normalizeHtu(url) {
+    const bare = url.split(/[?#]/, 1)[0];
+    let parsed;
+    try {
+        parsed = new URL(bare);
+    }
+    catch {
+        return bare;
+    }
+    const hasPath = /^[a-z][a-z0-9+.-]*:\/\/[^/]*\//i.test(bare);
+    return `${parsed.protocol}//${parsed.host}${hasPath ? parsed.pathname : ""}`;
+}

package/dist/credential.d.ts

@@ -0,0 +1,22 @@
+import { SigningKeyPair } from "./signing-key-pair.js";
+export declare const ATTESTATION_HEADER = "OAuth-Client-Attestation";
+export declare const POP_HEADER = "OAuth-Client-Attestation-PoP";
+export declare const DPOP_HEADER = "DPoP";
+/**
+ * The Attester-issued attestation JWT plus the instance key it is bound to. Produces the
+ * token-request headers — PoP-JWT mode or DPoP combined mode — minting a fresh proof each call.
+ */
+export declare class ClientAttestationCredential {
+    #private;
+    constructor(attestationJwt: string, instanceKey: SigningKeyPair);
+    /**
+     * Headers for dedicated PoP-JWT mode (PoP method `attestation_pop_jwt`):
+     * `OAuth-Client-Attestation` + `OAuth-Client-Attestation-PoP`.
+     */
+    popHeaders(clientId: string | null, audience: string, challenge?: string | null): Promise<Record<string, string>>;
+    /**
+     * Headers for DPoP combined mode (PoP method `dpop_combined`):
+     * `OAuth-Client-Attestation` + `DPoP` (and no PoP header).
+     */
+    dpopHeaders(method: string, uri: string, challenge?: string | null): Promise<Record<string, string>>;
+}

package/dist/credential.js

@@ -0,0 +1,44 @@
+/**
+ * Assembles the request headers a client sends at the token endpoint.
+ */
+import { DpopProofBuilder, PopBuilder } from "./builders.js";
+import { requireText } from "./signing-key-pair.js";
+export const ATTESTATION_HEADER = "OAuth-Client-Attestation";
+export const POP_HEADER = "OAuth-Client-Attestation-PoP";
+export const DPOP_HEADER = "DPoP";
+/**
+ * The Attester-issued attestation JWT plus the instance key it is bound to. Produces the
+ * token-request headers — PoP-JWT mode or DPoP combined mode — minting a fresh proof each call.
+ */
+export class ClientAttestationCredential {
+    #attestationJwt;
+    #instanceKey;
+    constructor(attestationJwt, instanceKey) {
+        this.#attestationJwt = requireText(attestationJwt, "attestation_jwt");
+        this.#instanceKey = instanceKey;
+    }
+    /**
+     * Headers for dedicated PoP-JWT mode (PoP method `attestation_pop_jwt`):
+     * `OAuth-Client-Attestation` + `OAuth-Client-Attestation-PoP`.
+     */
+    async popHeaders(clientId, audience, challenge) {
+        const pop = await new PopBuilder(this.#instanceKey)
+            .clientId(clientId)
+            .audience(audience)
+            .challenge(challenge ?? null)
+            .build();
+        return { [ATTESTATION_HEADER]: this.#attestationJwt, [POP_HEADER]: pop };
+    }
+    /**
+     * Headers for DPoP combined mode (PoP method `dpop_combined`):
+     * `OAuth-Client-Attestation` + `DPoP` (and no PoP header).
+     */
+    async dpopHeaders(method, uri, challenge) {
+        const dpop = await new DpopProofBuilder(this.#instanceKey)
+            .method(method)
+            .uri(uri)
+            .nonce(challenge ?? null)
+            .build();
+        return { [ATTESTATION_HEADER]: this.#attestationJwt, [DPOP_HEADER]: dpop };
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The SDK's error types. {@link ClientAttestationError} is the base for every failure of the
+ * one-call flow; {@link TransportError} is the subclass for anything that went wrong on the wire.
+ */
+/** A step in the flow failed. `status` and `body` are set for HTTP failures. */
+export declare class ClientAttestationError extends Error {
+    readonly status?: number;
+    readonly body?: string;
+    constructor(message: string, opts?: {
+        status?: number;
+        body?: string;
+        cause?: unknown;
+    });
+}
+/** Why an outbound HTTP call failed. */
+export type TransportFailure = "network" | "timeout" | "redirect" | "too_large" | "status" | "json";
+/**
+ * An outbound HTTP call failed: unreachable, timed out, redirected, oversized, non-2xx, or malformed
+ * JSON (see {@link kind}). `status` is set when a response was received; `body` holds at most the first
+ * 512 characters of it.
+ */
+export declare class TransportError extends ClientAttestationError {
+    readonly kind: TransportFailure;
+    constructor(message: string, kind: TransportFailure, opts?: {
+        status?: number;
+        body?: string;
+        cause?: unknown;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,28 @@
+/**
+ * The SDK's error types. {@link ClientAttestationError} is the base for every failure of the
+ * one-call flow; {@link TransportError} is the subclass for anything that went wrong on the wire.
+ */
+/** A step in the flow failed. `status` and `body` are set for HTTP failures. */
+export class ClientAttestationError extends Error {
+    status;
+    body;
+    constructor(message, opts) {
+        super(message, opts?.cause === undefined ? undefined : { cause: opts.cause });
+        this.name = "ClientAttestationError";
+        this.status = opts?.status;
+        this.body = opts?.body;
+    }
+}
+/**
+ * An outbound HTTP call failed: unreachable, timed out, redirected, oversized, non-2xx, or malformed
+ * JSON (see {@link kind}). `status` is set when a response was received; `body` holds at most the first
+ * 512 characters of it.
+ */
+export class TransportError extends ClientAttestationError {
+    kind;
+    constructor(message, kind, opts) {
+        super(message, opts);
+        this.name = "TransportError";
+        this.kind = kind;
+    }
+}

package/dist/evidence.d.ts

@@ -0,0 +1,55 @@
+import { type SvidSource } from "./svid-source.js";
+/** Environment variable holding the evidence token itself (static). */
+export declare const ENV_SVID = "CLIENT_ATTESTATION_SVID";
+/** Environment variable holding a path to a projected token file. */
+export declare const ENV_TOKEN_FILE = "CLIENT_ATTESTATION_TOKEN_FILE";
+/** SPIRE Workload API socket (standard SPIFFE var). */
+export declare const ENV_SPIFFE_SOCKET = "SPIFFE_ENDPOINT_SOCKET";
+/** Default projected-token path used by the Kubernetes/GKE serviceAccountToken volume convention. */
+export declare const DEFAULT_TOKEN_FILE = "/var/run/secrets/tokens/attester-token";
+/** Default SPIRE agent socket path. */
+export declare const DEFAULT_SPIFFE_SOCKET = "/tmp/spire-agent/public/api.sock";
+/** No platform identity could be detected and none was supplied. */
+export declare class EvidenceNotFound extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare class FileTokenSvidSource implements SvidSource {
+    private readonly path;
+    constructor(path: string);
+    fetch(_audience: string): Promise<string>;
+}
+/**
+ * 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 declare class GoogleMetadataSvidSource implements SvidSource {
+    private readonly timeoutMs;
+    private readonly identityUrl;
+    /**
+     * @param timeoutMs per-request timeout.
+     * @param identityUrl the identity endpoint; internal, for tests - defaults to the real metadata server.
+     */
+    constructor(timeoutMs?: number, identityUrl?: string);
+    fetch(audience: string): Promise<string>;
+}
+/**
+ * Return the first evidence source that applies to this runtime, or throw with guidance.
+ *
+ * Order: explicit env token, projected token file, SPIRE socket, GCP metadata server. A source named
+ * by an environment variable ({@link ENV_TOKEN_FILE}, {@link ENV_SPIFFE_SOCKET}) whose path does not
+ * exist throws {@link EvidenceNotFound} naming the variable; it never falls through to the next source.
+ */
+export declare function autoDetectEvidence(): Promise<SvidSource>;