@idpartners/client-attestation-sdk 1.0.0 → 1.2.0

package/dist/signer.js

@@ -7,29 +7,52 @@
 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";
+import { checkSecure, parseJsonObject, request as httpRequest, snippet } from "./http.js";
+import { SUPPORTED_ALGORITHMS } from "./signing-key-pair.js";
 /** Per-call timeout for the vault. */
 const OPENBAO_TIMEOUT_MS = 5_000;
 const b64url = (bytes) => base64url.encode(bytes);
+/** The length of a raw `r||s` JWS signature for each ECDSA algorithm. */
+const EC_SIGNATURE_BYTES = { ES256: 64, ES384: 96, ES512: 132 };
 /** 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). The signer's algorithm must be one the
+ * SDK signs with (never `none`), and its signature must not be empty and, for ES*, must be the fixed-width
+ * `r||s` (not DER, not truncated).
  *
- * @internal
- * signers hold issuing keys, referenced by id, never an embedded jwk). */
+ * @internal */
 export async function signExternal(claims, signer, typ) {
+    const alg = signer.algorithm;
+    if (!SUPPORTED_ALGORITHMS.includes(alg)) {
+        throw new Error(`external signer algorithm ${JSON.stringify(alg)} is not allowed: use ES256/384/512, RS256/384/512 or PS256/384/512`);
+    }
     const enc = new TextEncoder();
-    const header = { alg: signer.algorithm, typ, kid: signer.keyId };
+    const header = { alg, typ, kid: signer.keyId };
     const signingInput = `${b64url(enc.encode(JSON.stringify(header)))}.${b64url(enc.encode(JSON.stringify(claims)))}`;
     const signature = await signer.sign(enc.encode(signingInput));
+    if (!signature || signature.length === 0) {
+        throw new Error("external signer returned an empty signature");
+    }
+    const want = EC_SIGNATURE_BYTES[alg];
+    if (want !== undefined && signature.length !== want) {
+        throw new Error(`external signer returned a ${signature.length}-byte ${alg} signature; want the ${want}-byte raw r||s`);
+    }
     return `${signingInput}.${b64url(signature)}`;
 }
 const KEY_TYPE_ALG = { "ecdsa-p256": "ES256", "ecdsa-p384": "ES384", "ecdsa-p521": "ES512" };
 const ALG_HASH = { ES256: "sha2-256", ES384: "sha2-384", ES512: "sha2-512" };
+/** The key name goes into the request path, so "/", "?", "#", "%" and dot segments are refused. */
+const KEY_NAME = /^[A-Za-z0-9_.-]+$/;
 /**
  * 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).
  *
+ * `baoAddr` must be https unless its host is loopback (`localhost`, `127.0.0.1`, `::1`) or
+ * `allowInsecure: true` is passed: the vault token rides on every call, and the public key read from the
+ * vault becomes the attester's published JWK. `keyName` may contain only letters, digits, `_`, `.` and `-`
+ * (and is not `.` or `..`).
+ *
  * @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 {
@@ -51,8 +74,12 @@ export class OpenBaoTransitSigner {
         this.#publicJwk = publicJwk;
         this.keyId = keyId;
     }
-    static async create(baoAddr, token, keyName) {
+    static async create(baoAddr, token, keyName, opts) {
         const base = baoAddr.replace(/\/+$/, "");
+        checkSecure(base, "baoAddr", opts?.allowInsecure ?? false);
+        if (!KEY_NAME.test(keyName) || keyName === "." || keyName === "..") {
+            throw new Error(`invalid transit key name '${keyName}': use only letters, digits, '_', '.' and '-'`);
+        }
         const data = await request("GET", base, token, `/v1/transit/keys/${keyName}`);
         const keyType = String(data.type);
         const algorithm = KEY_TYPE_ALG[keyType];

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

@@ -32,6 +32,12 @@ export declare class SigningKeyPair {
     }): Promise<SigningKeyPair>;
     /**
      * Wrap an existing JWK (which must contain the private component `d`) for the given algorithm.
+     *
+     * The key must suit the algorithm: an EC key on its curve for `ES256` / `ES384` / `ES512`
+     * (P-256 / P-384 / P-521), an RSA key of at least 2048 bits for `RS*` / `PS*`, and its public
+     * members must belong to its private key. Only the key material is kept: the published JWK is
+     * re-encoded canonically (full-width EC coordinates, minimal RSA integers) and its `kid` is the
+     * RFC 7638 thumbprint, whatever `kid` or other members the input had.
      */
     static fromJwk(jwk: JWK, algorithm: string): Promise<SigningKeyPair>;
     /** The private CryptoKey — package-internal; used by the JWS signer. */

package/dist/signing-key-pair.js

@@ -1,7 +1,7 @@
 /**
  * Signing keys for attestation-based client authentication.
  */
-import { SignJWT, calculateJwkThumbprint, exportJWK, generateKeyPair, importJWK, } from "jose";
+import { CompactSign, SignJWT, base64url, calculateJwkThumbprint, compactVerify, exportJWK, generateKeyPair, importJWK, } from "jose";
 /**
  * A signing key pair (public + private) with its JWS `alg` and RFC 7638 thumbprint `kid`.
  *
@@ -46,15 +46,22 @@ export class SigningKeyPair {
     }
     /**
      * Wrap an existing JWK (which must contain the private component `d`) for the given algorithm.
+     *
+     * The key must suit the algorithm: an EC key on its curve for `ES256` / `ES384` / `ES512`
+     * (P-256 / P-384 / P-521), an RSA key of at least 2048 bits for `RS*` / `PS*`, and its public
+     * members must belong to its private key. Only the key material is kept: the published JWK is
+     * re-encoded canonically (full-width EC coordinates, minimal RSA integers) and its `kid` is the
+     * RFC 7638 thumbprint, whatever `kid` or other members the input had.
      */
     static async fromJwk(jwk, algorithm) {
         if (!jwk.d) {
             throw new Error("JWK does not contain a private key");
         }
         checkAlgorithm(algorithm);
-        const privateKey = (await importJWK(jwk, algorithm));
-        // Derive the public-only JWK from the supplied members (drop the private ones).
-        const publicJwk = publicMembers(jwk);
+        const canonical = canonicalPrivateJwk(jwk, algorithm);
+        const privateKey = (await importJWK(canonical, algorithm));
+        const publicJwk = publicMembers(canonical);
+        await checkKeyPair(privateKey, publicJwk, algorithm);
         const keyId = await calculateJwkThumbprint(publicJwk, "sha256");
         return new SigningKeyPair(privateKey, algorithm, publicJwk, keyId);
     }
@@ -80,8 +87,87 @@ export const SUPPORTED_ALGORITHMS = [
     "RS256", "RS384", "RS512",
     "PS256", "PS384", "PS512",
 ];
-/** RSA modulus size for generated RS* / PS* keys. */
+/** RSA modulus size for generated RS* / PS* keys, and the smallest one the SDK signs with. */
 const RSA_MODULUS_BITS = 2048;
+/** The curve, and its coordinate width in bytes, each ECDSA algorithm signs on. */
+const EC_CURVES = {
+    ES256: ["P-256", 32],
+    ES384: ["P-384", 48],
+    ES512: ["P-521", 66],
+};
+/** Strict base64url decoding; the error names the member, never its value. */
+function decodeMember(jwk, member) {
+    const value = jwk[member];
+    if (typeof value !== "string" || !/^[A-Za-z0-9_-]+$/.test(value)) {
+        throw new Error(`JWK member '${member}' is missing or not base64url`);
+    }
+    return base64url.decode(value);
+}
+function stripLeadingZeros(bytes) {
+    let i = 0;
+    while (i < bytes.length - 1 && bytes[i] === 0)
+        i++;
+    return bytes.subarray(i);
+}
+/**
+ * The key members of a private JWK, checked against `algorithm` and re-encoded canonically: EC
+ * coordinates and `d` at the curve's full width, RSA `n` and `e` in their minimal octets (RFC 7518
+ * section 6). Every other member (`kid`, `alg`, `use`, ...) is dropped.
+ */
+function canonicalPrivateJwk(jwk, algorithm) {
+    const ec = EC_CURVES[algorithm];
+    if (ec) {
+        const [crv, size] = ec;
+        if (jwk.kty !== "EC") {
+            throw new Error(`${algorithm} needs an EC key, not kty ${JSON.stringify(jwk.kty)}`);
+        }
+        if (jwk.crv !== crv) {
+            throw new Error(`${algorithm} needs an EC key on ${crv}`);
+        }
+        const out = { kty: "EC", crv };
+        for (const member of ["x", "y", "d"]) {
+            const value = stripLeadingZeros(decodeMember(jwk, member));
+            if (value.length > size) {
+                throw new Error(`JWK member '${member}' is too long for ${crv}`);
+            }
+            const fixed = new Uint8Array(size);
+            fixed.set(value, size - value.length);
+            out[member] = base64url.encode(fixed);
+        }
+        return out;
+    }
+    if (jwk.kty !== "RSA") {
+        throw new Error(`${algorithm} needs an RSA key, not kty ${JSON.stringify(jwk.kty)}`);
+    }
+    const out = {};
+    for (const member of ["kty", "n", "e", "d", "p", "q", "dp", "dq", "qi", "oth"]) {
+        if (jwk[member] !== undefined) {
+            out[member] = jwk[member];
+        }
+    }
+    const n = stripLeadingZeros(decodeMember(jwk, "n"));
+    out.n = base64url.encode(n);
+    out.e = base64url.encode(stripLeadingZeros(decodeMember(jwk, "e")));
+    const bits = n[0] === 0 ? 0 : (n.length - 1) * 8 + (32 - Math.clz32(n[0]));
+    if (bits < RSA_MODULUS_BITS) {
+        throw new Error(`RSA keys must be at least ${RSA_MODULUS_BITS} bits`);
+    }
+    return out;
+}
+/**
+ * Refuse a private key whose published public half is another key: signing with one key while
+ * advertising another (as `kid`, `cnf.jwk` or the DPoP `jwk`) gives credentials no verifier accepts.
+ */
+async function checkKeyPair(privateKey, publicJwk, algorithm) {
+    try {
+        const probe = new TextEncoder().encode("client-attestation-sdk key pair check");
+        const jws = await new CompactSign(probe).setProtectedHeader({ alg: algorithm }).sign(privateKey);
+        await compactVerify(jws, await importJWK(publicJwk, algorithm));
+    }
+    catch {
+        throw new Error("the JWK's public key does not match its private key");
+    }
+}
 function checkAlgorithm(algorithm) {
     if (!SUPPORTED_ALGORITHMS.includes(algorithm)) {
         throw new Error(`unsupported signing algorithm: ${algorithm}`);

package/dist/svid-source.d.ts

@@ -4,7 +4,7 @@ export interface SvidSource {
 }
 /** A fixed, pre-fetched SVID — for tests, or when the caller already holds one. */
 export declare class StaticSvidSource implements SvidSource {
-    private readonly svid;
+    #private;
     constructor(svid: string);
     fetch(_audience: string): Promise<string>;
 }
@@ -25,7 +25,18 @@ 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.
+ * subprocess. An agent that has not exited within 30 s is killed and `fetch` rejects. `fetch` returns the
+ * first JWT-SVID the agent prints on stdout and throws {@link EvidenceNotFound} if there is none. The
+ * agent's stderr is discarded, never read as output or held in memory.
+ *
+ * The agent's exit decides the outcome, as in the other ports. While the agent is running, more than
+ * 1 MiB of stdout kills it and `fetch` rejects. Once it has exited, stdout is read for at most 250 ms more
+ * and at most 1 MiB in all (a helper the agent started can inherit the pipe and keep writing to it or hold
+ * it open), then the pipe is closed. On exit status 0 what was read is parsed; on any other status, or if
+ * the agent was killed, `fetch` rejects. So output a helper writes after the agent has exited never turns a
+ * success into a failure, and never keeps `fetch` waiting longer than that. If reading stopped at the
+ * 1 MiB or at the end of the 250 ms, the last line may be cut off, so a token is only taken from a line
+ * that ends in a newline.
  *
  * 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.

package/dist/svid-source.js

@@ -3,18 +3,32 @@
  * bootstrapping ({@link AttestationIssuanceClient}). The default {@link SpireWorkloadApiSvidSource}
  * fetches it from a real SPIRE agent; the others cover dev and tests.
  */
+import { EvidenceNotFound } from "./evidence.js";
 import { jsonOk, request } from "./http.js";
-import { importNodeBuiltin } from "./runtime.js";
+import { importNodeBuiltin, utf8Encode } from "./runtime.js";
+import { decodeSegment, Malformed, parseObject } from "./validator/strict.js";
 /** Per-call timeout for {@link HttpSvidSource}. */
 const HTTP_SVID_TIMEOUT_MS = 20_000;
+/** How long `spire-agent` may run before it is killed (as in the other ports). */
+const SPIRE_AGENT_TIMEOUT_MS = 30_000;
+/**
+ * The most stdout read from `spire-agent` (as in the other ports). More while the agent is running fails the
+ * fetch; once it has exited, reading stops there.
+ */
+const SPIRE_AGENT_MAX_OUTPUT = 1 << 20;
+/**
+ * How long stdout is still read after `spire-agent` has exited (as in the other ports). A helper the agent
+ * started can inherit the pipe and hold it open; after this the pipe is closed.
+ */
+const SPIRE_AGENT_STDOUT_GRACE_MS = 250;
 /** A fixed, pre-fetched SVID — for tests, or when the caller already holds one. */
 export class StaticSvidSource {
-    svid;
+    #svid; // private, so JSON.stringify and console.log don't show it
     constructor(svid) {
-        this.svid = svid;
+        this.#svid = svid;
     }
     async fetch(_audience) {
-        return this.svid;
+        return this.#svid;
     }
 }
 /**
@@ -42,7 +56,18 @@ export class HttpSvidSource {
 /**
  * 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.
+ * subprocess. An agent that has not exited within 30 s is killed and `fetch` rejects. `fetch` returns the
+ * first JWT-SVID the agent prints on stdout and throws {@link EvidenceNotFound} if there is none. The
+ * agent's stderr is discarded, never read as output or held in memory.
+ *
+ * The agent's exit decides the outcome, as in the other ports. While the agent is running, more than
+ * 1 MiB of stdout kills it and `fetch` rejects. Once it has exited, stdout is read for at most 250 ms more
+ * and at most 1 MiB in all (a helper the agent started can inherit the pipe and keep writing to it or hold
+ * it open), then the pipe is closed. On exit status 0 what was read is parsed; on any other status, or if
+ * the agent was killed, `fetch` rejects. So output a helper writes after the agent has exited never turns a
+ * success into a failure, and never keeps `fetch` waiting longer than that. If reading stopped at the
+ * 1 MiB or at the end of the 250 ms, the last line may be cut off, so a token is only taken from a line
+ * that ends in a newline.
  *
  * 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.
@@ -58,20 +83,182 @@ export class SpireWorkloadApiSvidSource {
         this.spireAgentBin = spireAgentBin;
     }
     async fetch(audience) {
-        const { execFile } = await importNodeBuiltin("child_process", "SpireWorkloadApiSvidSource");
-        const stdout = await new Promise((resolve, reject) => {
-            execFile(this.spireAgentBin, ["api", "fetch", "jwt", "-audience", audience, "-socketPath", this.socketPath], (err, out) => (err ? reject(err) : resolve(String(out))));
+        const { spawn } = await importNodeBuiltin("child_process", "SpireWorkloadApiSvidSource");
+        // stdout only: stderr goes to the null device, so a log line or version string the agent writes there
+        // is never parsed, and a flood of it is never held in memory.
+        const { stdout, complete } = await new Promise((resolve, reject) => {
+            const args = ["api", "fetch", "jwt", "-audience", audience, "-socketPath", this.socketPath];
+            const child = spawn(this.spireAgentBin, args, {
+                stdio: ["ignore", "pipe", "ignore"],
+                timeout: SPIRE_AGENT_TIMEOUT_MS,
+                killSignal: "SIGKILL",
+            });
+            const chunks = [];
+            let size = 0;
+            let over = false; // past the cap while the agent was running
+            let ended = false; // stdout was read to its end
+            let exited;
+            let settled = false;
+            let grace;
+            // Settle once, and let go of stdout: a helper the agent started can inherit the pipe and hold it open
+            // after the agent is gone, so neither the timeout nor the size cap may wait for stdout to close.
+            const settle = (code, signal) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (grace)
+                    clearTimeout(grace);
+                child.stdout?.destroy?.();
+                if (over) {
+                    const message = `spire-agent fetch failed: output is larger than ${SPIRE_AGENT_MAX_OUTPUT} bytes`;
+                    reject(Object.assign(new Error(message), { code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" }));
+                }
+                else if (code === 0) {
+                    resolve({ stdout: concatUtf8(chunks, size), complete: ended });
+                }
+                else {
+                    reject(spireAgentExitFailure(code, signal, child.killed));
+                }
+            };
+            child.stdout?.on("data", (chunk) => {
+                if (over || settled)
+                    return;
+                if (size + chunk.length > SPIRE_AGENT_MAX_OUTPUT) {
+                    if (exited) {
+                        // The agent has exited: stop at the cap, and let its exit status decide.
+                        chunks.push(chunk.subarray(0, SPIRE_AGENT_MAX_OUTPUT - size));
+                        size = SPIRE_AGENT_MAX_OUTPUT;
+                        settle(exited.code, exited.signal);
+                        return;
+                    }
+                    // Still running: kill it and fail.
+                    over = true;
+                    chunks.length = 0;
+                    child.kill("SIGKILL");
+                    settle(null, "SIGKILL");
+                    return;
+                }
+                size += chunk.length;
+                chunks.push(chunk);
+            });
+            child.stdout?.on("end", () => {
+                if (!settled)
+                    ended = true;
+            });
+            child.stdout?.on("error", () => { }); // the outcome comes from "exit" or "close"
+            child.on("error", (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (grace)
+                    clearTimeout(grace);
+                child.stdout?.destroy?.();
+                reject(spireAgentStartFailure(this.spireAgentBin, err));
+            });
+            // The agent has exited (on its own, or killed at the timeout): what it wrote is in the pipe, so give
+            // stdout a moment to drain, then settle whether or not something else still holds it open.
+            child.on("exit", (code, signal) => {
+                exited = { code, signal };
+                if (!settled)
+                    grace = setTimeout(() => settle(code, signal), SPIRE_AGENT_STDOUT_GRACE_MS);
+            });
+            child.on("close", (code, signal) => settle(code, signal));
         });
-        for (let line of stdout.split("\n")) {
-            line = line.trim();
-            if (line.startsWith("token(")) {
-                const idx = line.indexOf("):");
-                if (idx >= 0)
-                    return line.slice(idx + 2).trim();
+        // If reading stopped before the end of stdout (at the cap or the end of the grace period), the line
+        // after the last newline may have been cut off.
+        const svid = parseSpireJwtOutput(complete ? stdout : stdout.slice(0, stdout.lastIndexOf("\n") + 1));
+        if (svid)
+            return svid;
+        // The output may hold a token or bundle that failed to parse, so the error gives only its size.
+        const lines = stdout.split("\n").length - (stdout === "" || stdout.endsWith("\n") ? 1 : 0);
+        throw new EvidenceNotFound(`could not parse a JWT-SVID from spire-agent output (${utf8Encode(stdout).length} bytes, ${lines} lines; not shown)`);
+    }
+}
+/** stdout as text: invalid UTF-8 becomes U+FFFD and a leading BOM is kept, as in the other ports. */
+function concatUtf8(chunks, size) {
+    const all = new Uint8Array(size);
+    let at = 0;
+    for (const chunk of chunks) {
+        all.set(chunk, at);
+        at += chunk.length;
+    }
+    return new TextDecoder("utf-8", { ignoreBOM: true }).decode(all);
+}
+/**
+ * The error for a `spire-agent` that could not be started: its `code` (`ENOENT` when it is not installed)
+ * and nothing else from Node's error.
+ */
+function spireAgentStartFailure(bin, err) {
+    const code = typeof err.code === "string" ? err.code : "unknown error";
+    return Object.assign(new Error(`spire-agent fetch failed: could not run ${bin} (${code})`), { code: err.code });
+}
+/**
+ * The error for a `spire-agent` that ran and failed: how it ended, never its output. `code`, `killed` and
+ * `signal` are kept.
+ */
+function spireAgentExitFailure(code, signal, killed) {
+    const how = signal ? `killed with ${signal}` : `exit status ${code}`;
+    return Object.assign(new Error(`spire-agent fetch failed: ${how}`), { code, killed, signal });
+}
+const SPIRE_SECTION = /^(token|hint|bundle)\(.*?\):(.*)$/s;
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+/**
+ * `s` without the ASCII spaces, tabs and CRs around it, and nothing else: not a BOM, an NBSP or other
+ * Unicode space (as `String#trim` would), so every port reads the same output the same way.
+ */
+function trimSpireSpace(s) {
+    return s.replace(/^[ \t\r]+|[ \t\r]+$/g, "");
+}
+/**
+ * The first JWT-SVID in the output of `spire-agent api fetch jwt`, or `undefined`.
+ *
+ * SPIRE prints each SVID as `token(<spiffe id>):` with the JWT on the next, tab-indented line, then
+ * `hint(<spiffe id>):` and `bundle(<trust domain>):` sections laid out the same way. The single-line form
+ * `token(<spiffe id>): <jwt>` and a bare JWT line are accepted too. Only a syntactically valid compact JWS
+ * is returned; the values of hint and bundle sections are skipped. A label with no value takes the next
+ * line as its value only if that line is not itself a label. Only ASCII space, tab and CR around a line or
+ * value are ignored.
+ */
+function parseSpireJwtOutput(out) {
+    const lines = out.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = trimSpireSpace(lines[i]);
+        const section = SPIRE_SECTION.exec(line);
+        if (!section) {
+            if (isCompactJws(line))
+                return line; // a bare compact JWT line
+            continue;
+        }
+        let value = trimSpireSpace(section[2]);
+        if (!value && i + 1 < lines.length) {
+            // the value is on the next line, unless that is another label
+            const following = trimSpireSpace(lines[i + 1]);
+            if (!SPIRE_SECTION.test(following)) {
+                value = following;
+                i++;
             }
-            if ((line.match(/\./g) ?? []).length === 2)
-                return line;
         }
-        throw new Error(`could not parse SVID from spire-agent output:\n${stdout}`);
+        if (section[1] === "token" && isCompactJws(value))
+            return value;
+    }
+    return undefined;
+}
+/**
+ * Three non-empty base64url segments whose first is the canonical encoding of a strict JSON object (the
+ * token validator's reader) with a non-empty string `alg`. It verifies nothing; it tells a JWT from a
+ * version string or log line.
+ */
+function isCompactJws(s) {
+    const parts = s.split(".");
+    if (parts.length !== 3 || !parts.every((p) => BASE64URL.test(p)))
+        return false;
+    try {
+        const alg = parseObject(decodeSegment(parts[0]), "header").alg;
+        return typeof alg === "string" && alg !== "";
+    }
+    catch (err) {
+        if (err instanceof Malformed)
+            return false;
+        throw err;
     }
 }

package/dist/token-source.d.ts

@@ -32,6 +32,16 @@ export interface ClientAttestationOptions {
      * endpoint and PoP audience). When set, no discovery request is made; the profile still mints.
      */
     metadata?: AttesterMetadata;
+    /**
+     * The audience the workload's platform identity token is requested for, which the attester's
+     * discovery document must name. Required unless `metadata` is given: every evidence source (GCP,
+     * AWS, Azure, SPIRE) fetches a token for whatever audience it is asked for, so without a pin an
+     * attester could have the workload mint a token for another service that trusts it. A missing pin or
+     * a different discovered audience throws {@link ClientAttestationError} before any evidence is
+     * fetched. With static `metadata`, the pin is optional and, when given, must match
+     * `metadata.evidenceAudience`.
+     */
+    evidenceAudience?: string;
     /**
      * How to get the workload's platform identity. Leave unset to auto-detect the runtime (env token,
      * projected token file, SPIRE socket, or GCP metadata). Pass an {@link SvidSource} to override.
@@ -53,16 +63,18 @@ export interface ClientAttestationOptions {
     operator?: Record<string, unknown>;
     /** Instance-key signature algorithm (default `ES256`). */
     algorithm?: string;
-    /** Refresh this long before the token expires (default 30s). */
+    /** Refresh this long before the token expires (default 30s). Must be a finite number, not negative. */
     expirySkewSeconds?: number;
     /** Per-request HTTP timeout in milliseconds (default 20000). */
     timeoutMs?: number;
     /**
      * How to prove possession of the instance key at the token endpoint: the dedicated
      * `OAuth-Client-Attestation-PoP` JWT (`"attestation_pop_jwt"`, the default), or a `DPoP` proof
-     * carrying the same challenge in `nonce` (`"dpop_combined"`).
+     * carrying the same challenge in `nonce` (`"dpop_combined"`). `undefined`, `null` or `""` means the
+     * default. The names are case-sensitive; the constructor throws a `RangeError` for any other value,
+     * including one with surrounding whitespace or a non-string.
      */
-    popMethod?: "attestation_pop_jwt" | "dpop_combined";
+    popMethod?: "attestation_pop_jwt" | "dpop_combined" | "" | null;
     /**
      * Whether the attester-issued challenge also rides in the token-endpoint proof (the PoP's
      * `challenge` claim, or the DPoP `nonce`), on top of the mint-time instance proof it always
@@ -95,7 +107,7 @@ export interface ClientAttestationOptions {
  * Gets and caches an access token using client attestation.
  *
  * `new ClientAttestation(attesterUrl, opts)`, or `new ClientAttestation(opts)` with `opts.metadata` (no
- * discovery) or a custom `opts.profile`.
+ * discovery) or a custom `opts.profile`. A client that discovers its attester needs `opts.evidenceAudience`.
  *
  * @param attesterUrl the attester's host — `"pf.example.com"`, or a full base URL
  *   `"https://pf.example.com"`. Plain hostnames default to https. Optional when `metadata` or `profile`
@@ -125,6 +137,17 @@ export declare class ClientAttestation {
      * - DPoP token: `{ Authorization: "DPoP <t>", DPoP: <proof> }` — a fresh proof signed by the key the
      *   token is bound to, for this `method` and `url`, carrying `ath` and the last `DPoP-Nonce` the
      *   url's origin returned, if any.
+     *
+     * `url` must be https, like every other URL the client sends a credential to (loopback hosts and
+     * `allowInsecure` excepted).
+     *
+     * Pass the exact URL your HTTP client sends: the proof is only valid for the `htu` it names. A url with
+     * a backslash, ASCII whitespace or a control character before its query or fragment is refused with a
+     * {@link ClientAttestationError}, because URL parsers disagree on where it goes. For a DPoP-bound token,
+     * so is a url that is not an absolute http(s) URL with a valid ASCII host, port and path; with
+     * `popMethod: "dpop_combined"` that is checked before the token is fetched. The path is signed as
+     * written, so pass `new URL(u).href` (what `fetch` sends) rather than a hand-written string: `fetch` may
+     * escape characters (a `{`, say) that the string leaves as they are. {@link fetch} does this for you.
      */
     requestHeaders(method: string, url: string, opts?: {
         forceRefresh?: boolean;
@@ -134,6 +157,7 @@ export declare class ClientAttestation {
      * as global `fetch`. For a DPoP-bound token it adds a fresh proof and, when the resource answers with
      * a `use_dpop_nonce` challenge and a `DPoP-Nonce`, resends ONCE with a proof carrying that nonce —
      * unless the body is a one-shot stream, which cannot be resent (the challenge response is returned).
+     * Redirects are returned without following them, even if the input or init requests redirect following.
      */
     fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
     /**