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

package/dist/builders.js

@@ -0,0 +1,276 @@
+/**
+ * Builders for the attestation, PoP and DPoP JWTs (draft-ietf-oauth-attestation-based-client-auth).
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { SigningKeyPair, requireText, signCompact } from "./signing-key-pair.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 ?? 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;
+    #ath = 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.#ath = accessToken ? accessTokenHash(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 ?? randomUUID(),
+            iat: this.#issuedAt !== null ? this.#issuedAt : nowSeconds(),
+        };
+        if (this.#nonce) {
+            claims.nonce = this.#nonce;
+        }
+        if (this.#ath) {
+            claims.ath = this.#ath;
+        }
+        return signCompact(claims, this.#instanceKey, DPOP_TYP, true);
+    }
+}
+/** RFC 9449 `ath`: base64url(SHA-256(ASCII access token)). */
+export function accessTokenHash(accessToken) {
+    return createHash("sha256").update(accessToken, "ascii").digest("base64url");
+}
+/**
+ * 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).
+ */
+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,70 @@
+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";
+/** GCP metadata server origin. */
+export declare const GCP_METADATA_BASE = "http://metadata.google.internal";
+/** GCP metadata server identity endpoint (returns a Google-signed ID token for the runtime SA). */
+export declare const GCP_METADATA_IDENTITY: string;
+/** 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.
+ */
+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>;
+}
+/**
+ * Internal overrides for {@link autoDetectEvidence}, so tests can point detection at fixtures instead
+ * of the host's real paths and the real GCP metadata server. Not part of the supported API.
+ *
+ * @internal
+ */
+export interface AutoDetectOptions {
+    /** Path probed in place of {@link DEFAULT_TOKEN_FILE}. */
+    defaultTokenFile?: string;
+    /** Path probed in place of {@link DEFAULT_SPIFFE_SOCKET}. */
+    defaultSpiffeSocket?: string;
+    /** Origin used in place of {@link GCP_METADATA_BASE} for the probe and the identity call. */
+    gcpMetadataBase?: 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(opts?: AutoDetectOptions): Promise<SvidSource>;

package/dist/evidence.js

@@ -0,0 +1,150 @@
+/**
+ * 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(pfHost)` and have it work without naming the source. Override by
+ * passing an explicit {@link SvidSource} to {@link ClientAttestation}.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { TransportError } from "./errors.js";
+import { request, snippet } from "./http.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. */
+export const GCP_METADATA_BASE = "http://metadata.google.internal";
+/** GCP metadata server identity endpoint (returns a Google-signed ID token for the runtime SA). */
+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.
+ */
+export class FileTokenSvidSource {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async fetch(_audience) {
+        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();
+    }
+}
+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;
+    }
+}
+/**
+ * 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 async function autoDetectEvidence(opts = {}) {
+    const defaultTokenFile = opts.defaultTokenFile ?? DEFAULT_TOKEN_FILE;
+    const defaultSocket = opts.defaultSpiffeSocket ?? DEFAULT_SPIFFE_SOCKET;
+    const metadataBase = (opts.gcpMetadataBase ?? GCP_METADATA_BASE).replace(/\/+$/, "");
+    const staticToken = process.env[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 = process.env[ENV_TOKEN_FILE];
+    if (tokenFile) {
+        if (!existsSync(tokenFile)) {
+            throw new EvidenceNotFound(`${ENV_TOKEN_FILE} is set to ${tokenFile}, but no such file exists`);
+        }
+        return new FileTokenSvidSource(tokenFile);
+    }
+    if (existsSync(defaultTokenFile)) {
+        return new FileTokenSvidSource(defaultTokenFile);
+    }
+    const socket = process.env[ENV_SPIFFE_SOCKET];
+    if (socket) {
+        const socketPath = socket.replace(/^unix:\/\//, "");
+        if (!existsSync(socketPath)) {
+            throw new EvidenceNotFound(`${ENV_SPIFFE_SOCKET} is set to ${socket}, but no such socket exists`);
+        }
+        return new SpireWorkloadApiSvidSource(socketPath);
+    }
+    if (existsSync(defaultSocket)) {
+        return new SpireWorkloadApiSvidSource(defaultSocket);
+    }
+    if (await gcpMetadataAvailable(metadataBase)) {
+        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,41 @@
+export declare const DEFAULT_MAX_BYTES: number;
+export declare const DEFAULT_TIMEOUT_MS = 20000;
+/** At most this many characters of a response body are carried in an error. */
+export declare const ERROR_BODY_CHARS = 512;
+export interface HttpRequestOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    /** Whole-call timeout in milliseconds (connect, headers and body). Defaults to 20 s. */
+    timeoutMs?: number;
+    /** Largest response body accepted, in bytes. Defaults to 1 MiB. */
+    maxBytes?: number;
+}
+export interface HttpResponse {
+    method: string;
+    url: string;
+    status: number;
+    ok: boolean;
+    headers: Headers;
+    body: string;
+}
+/** The first {@link ERROR_BODY_CHARS} characters of a body, for an error message. */
+export declare function snippet(body: string): string;
+/**
+ * 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 declare function request(url: string, opts?: HttpRequestOptions): Promise<HttpResponse>;
+/**
+ * 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 declare function jsonOk<T = Record<string, unknown>>(res: HttpResponse, opts?: {
+    allowEmpty?: boolean;
+}): T;
+/** Parse `res.body` as a JSON object regardless of status; a {@link TransportError} if it is not one. */
+export declare function parseJsonObject<T = Record<string, unknown>>(res: HttpResponse, opts?: {
+    allowEmpty?: boolean;
+}): T;