@idpartners/client-attestation-sdk 1.0.1 → 1.4.0

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,19 @@ 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. A token is only taken from a
+ * line that ends in a newline, whether or not stdout was read to its end: if reading stopped at the 1 MiB
+ * or at the end of the 250 ms the last line may be cut off, and no port can tell that from an agent whose
+ * last line lacks a newline (real spire-agent output always ends in one), so every port refuses it.
  *
  * 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 +84,178 @@ export class SpireWorkloadApiSvidSource {
         this.spireAgentBin = spireAgentBin;
     }
     async fetch(audience) {
-        const { execFile } = await importNodeBuiltin("child_process", "SpireWorkloadApiSvidSource");
+        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 = 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 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 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(concatUtf8(chunks, size));
+                }
+                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("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();
+        // A token is only taken from a line that ends in a newline: the line after the last newline may have been
+        // cut off (reading stopped at the cap or the end of the grace period), and whether stdout was read to its
+        // end can't tell that apart from an agent whose last line lacks a newline, so every port refuses it.
+        const svid = parseSpireJwtOutput(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

@@ -13,6 +13,7 @@ export interface AttesterDiscovery {
     attestation_endpoint?: string;
     challenge_endpoint?: string;
     token_endpoint?: string;
+    token_challenge_endpoint?: string;
     pop_audience?: string;
 }
 /** Options for {@link ClientAttestation}. */
@@ -32,6 +33,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 +64,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 +108,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 +138,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;