@idpartners/client-attestation-sdk 1.0.1 → 1.4.0

package/dist/issuance.js

@@ -8,15 +8,17 @@
  */
 import { MintRequest, PingFederateProfile } from "./attester.js";
 import { DpopProofBuilder, PopBuilder } from "./builders.js";
-import { jsonOk, request } from "./http.js";
+import { ClientAttestationError } from "./errors.js";
+import { checkSecure, jsonOk, request, snippet } from "./http.js";
 import { SigningKeyPair } from "./signing-key-pair.js";
 /** The instance-key proof typ the PingFederate profile presents (server InstanceKeyProofValidator.TYP). */
 export { INSTANCE_PROOF_TYP } from "./attester.js";
 /** Per-call timeout for the issuance endpoint. */
 const ISSUANCE_TIMEOUT_MS = 20_000;
 /**
- * Thrown when the issuance endpoint rejects the request (non-2xx). Transport failures — unreachable,
- * timeout, redirect, oversized or malformed response — are a {@link TransportError} instead.
+ * Thrown when the issuance endpoint rejects the request (non-2xx); `body` is at most the first 512
+ * characters of the response. Transport failures — unreachable, timeout, redirect, oversized or malformed
+ * response — are a {@link TransportError} instead.
  */
 export class IssuanceError extends Error {
     status;
@@ -28,15 +30,22 @@ export class IssuanceError extends Error {
         this.name = "IssuanceError";
     }
 }
-/** A minted Client Attestation plus the instance key it is bound to. */
+/**
+ * A minted Client Attestation plus the instance key it is bound to. The attestation is a getter over a
+ * private field, so `JSON.stringify` and `console.log` of this object don't show it.
+ */
 export class IssuedAttestation {
-    attestation;
     expiresIn;
     instanceKey;
+    #attestation;
     constructor(attestation, expiresIn, instanceKey) {
-        this.attestation = attestation;
         this.expiresIn = expiresIn;
         this.instanceKey = instanceKey;
+        this.#attestation = attestation;
+    }
+    /** The Client Attestation (a compact JWT). */
+    get attestation() {
+        return this.#attestation;
     }
     /** A fresh Client Attestation PoP for the token endpoint, signed by the bound instance key. */
     async pop(audience, clientId, challenge) {
@@ -63,6 +72,9 @@ export class IssuedAttestation {
  *
  * `opts.profile` sets the mint protocol (default {@link PingFederateProfile}; see
  * docs/attester-profiles.md). The endpoint is given directly, so the profile's discovery is not used.
+ *
+ * The SVID is a bearer credential to the attester, so the endpoint, and every URL the profile calls, must be
+ * https unless its host is loopback (`localhost`, `127.0.0.1`, `::1`) or `opts.allowInsecure` is set.
   *
   * @experimental See docs/api.md: it calls a PingFederate demo issuance servlet (/federation/attestation)
   * whose protocol is not standardised.
@@ -74,36 +86,47 @@ export class AttestationIssuanceClient {
     source;
     instanceKey;
     profile;
-    constructor(endpoint, clientId, attesterIssuer, source, instanceKey, profile) {
+    transport;
+    constructor(endpoint, clientId, attesterIssuer, source, instanceKey, profile, transport) {
         this.endpoint = endpoint;
         this.clientId = clientId;
         this.attesterIssuer = attesterIssuer;
         this.source = source;
         this.instanceKey = instanceKey;
         this.profile = profile;
+        this.transport = transport;
     }
-    /** Generate a fresh ES256 instance key and return a ready client. */
+    /**
+     * Generate a fresh ES256 instance key and return a ready client. `opts.allowInsecure` permits plain-http
+     * URLs on hosts that are not loopback (default `false`).
+     */
     static async create(endpoint, clientId, attesterIssuer, source, opts) {
+        const allowInsecure = opts?.allowInsecure ?? false;
+        const trimmed = endpoint.replace(/\/$/, "");
+        checkSecure(trimmed, "endpoint", allowInsecure);
         const key = opts?.instanceKey ?? (await SigningKeyPair.generate("ES256"));
         const profile = opts?.profile ?? new PingFederateProfile();
-        return new AttestationIssuanceClient(endpoint.replace(/\/$/, ""), clientId, attesterIssuer, source, key, profile);
+        return new AttestationIssuanceClient(trimmed, clientId, attesterIssuer, source, key, profile, issuanceTransport(allowInsecure));
     }
     /** Fetch the SVID, prove possession of the instance key, and exchange them for a minted attestation. */
     async bootstrap(authorizationDetails, challenge) {
         const svid = await this.source.fetch(this.attesterIssuer);
-        const minted = await this.profile.mint(issuanceTransport, { evidenceAudience: this.attesterIssuer, attestationEndpoint: this.endpoint }, new MintRequest({
+        const minted = await this.profile.mint(this.transport, { evidenceAudience: this.attesterIssuer, attestationEndpoint: this.endpoint }, new MintRequest({
             instanceKey: this.instanceKey,
             evidence: svid,
             challenge: challenge || undefined,
             clientId: this.clientId,
             authorizationDetails,
         }));
+        if (!minted?.attestation)
+            throw new ClientAttestationError("attester response contained no attestation");
         return new IssuedAttestation(minted.attestation, minted.expiresIn, this.instanceKey);
     }
 }
-/** The issuance endpoint's transport: a non-2xx answer is an {@link IssuanceError}. */
-const issuanceTransport = {
-    async requestJson(_step, method, url, body) {
+/** The issuance endpoint's transport: the https rule, and a non-2xx answer is an {@link IssuanceError}. */
+const issuanceTransport = (allowInsecure) => ({
+    async requestJson(step, method, url, body) {
+        checkSecure(url, `${step} URL`, allowInsecure);
         const res = await request(url, {
             method,
             headers: { "Content-Type": "application/json", Accept: "application/json" },
@@ -111,7 +134,7 @@ const issuanceTransport = {
             timeoutMs: ISSUANCE_TIMEOUT_MS,
         });
         if (!res.ok)
-            throw new IssuanceError(res.status, res.body);
+            throw new IssuanceError(res.status, snippet(res.body));
         return jsonOk(res);
     },
-};
+});

package/dist/logging.js

@@ -4,25 +4,59 @@
  * other ports; see docs/logging.md.
  *
  * Never logged: tokens, attestations, proofs, SVIDs, challenge values, key material, header values, or
- * URLs with their query string. As a backstop, any string attribute containing `eyJ` (how a JWT's
- * base64url-encoded header begins) is replaced with `<redacted:N bytes>` before it reaches the logger.
+ * URLs with their query string. As a backstop, an attribute under a credential key (`token`, `*_token`,
+ * `auth_req_id`, `code`, ...), or a string attribute that carries a credential (contains `eyJ`, how a
+ * JWT's base64url-encoded header begins; a Vault/OpenBao token; an `Authorization` header value), is
+ * replaced with `<redacted:N bytes>` before it reaches the logger.
  */
 import { TransportError } from "./errors.js";
 import { utf8Encode } from "./runtime.js";
 const noop = () => undefined;
 /** The default: drops everything. */
 export const NOOP_LOGGER = { debug: noop, info: noop, warn: noop, error: noop };
-function guard(value) {
+// The backstop (docs/logging.md, the same rule in every port): an attribute is redacted when its key names
+// a credential, or its value carries one this SDK handles. Keys are matched in lower case.
+const SECRET_KEYS = new Set([
+    "svid", "proof", "assertion", "client_assertion", "subject_token", "actor_token", "client_secret",
+    "attestation", "access_token", "refresh_token", "id_token", "authorization", "dpop",
+    "oauth-client-attestation", "oauth-client-attestation-pop", "auth_req_id", "code", "handle", "token",
+    "secret", "password", "private_key", "vault_token", "x-vault-token",
+]);
+const SECRET_KEY_SUFFIXES = ["_token", "-token", "_secret", "-secret", "_password"];
+// Vault/OpenBao tokens: hvs./hvb./hvr. and the older s./b./r. forms, standing alone.
+const VAULT_TOKEN = /(?:^|[^A-Za-z0-9._-])(?:hv[sbr]\.[A-Za-z0-9_-]{20,}|[sbr]\.[A-Za-z0-9_-]{24,}(?:$|[^A-Za-z0-9._-]))/;
+// An Authorization header value anywhere in the string: a scheme this SDK sends, standing alone, then
+// whitespace and the first character of a credential ("Bearer x", " Bearer x", "Authorization: Bearer x").
+// A bare scheme name ("Bearer", "token_type=Bearer", "dpop_combined") is not one.
+const AUTH_SCHEME = /(?:^|[^A-Za-z0-9_-])(?:bearer|dpop|basic)[ \t]+[A-Za-z0-9._~+/-]/i;
+function secretKey(key) {
+    const k = key.toLowerCase();
+    return SECRET_KEYS.has(k) || SECRET_KEY_SUFFIXES.some((suffix) => k.endsWith(suffix));
+}
+function redacted(value) {
+    return `<redacted:${utf8Encode(value).length} bytes>`;
+}
+function guard(key, value) {
+    if (secretKey(key)) {
+        try {
+            return redacted(typeof value === "string" ? value : String(value));
+        }
+        catch {
+            // a value whose toString throws (or an object with no prototype) must not throw out of logging
+            return "<redacted>";
+        }
+    }
     if (typeof value !== "string")
         return value;
     // A JWT's header and claims (any base64url-encoded JSON object) begin with "eyJ".
-    if (value.includes("eyJ")) {
-        return `<redacted:${utf8Encode(value).length} bytes>`;
+    if (value.includes("eyJ") || VAULT_TOKEN.test(value) || AUTH_SCHEME.test(value)) {
+        return redacted(value);
     }
     return value;
 }
 /**
- * Emit one event: undefined attributes dropped, JWT-looking values redacted. Never throws.
+ * Emit one event: undefined attributes dropped, credential keys and credential-looking values redacted.
+ * Never throws.
  *
  * @internal
  */
@@ -32,7 +66,7 @@ export function emit(logger, level, event, attrs = {}) {
     const clean = {};
     for (const [key, value] of Object.entries(attrs)) {
         if (value !== undefined && value !== null)
-            clean[key] = guard(value);
+            clean[key] = guard(key, value);
     }
     try {
         logger[level](event, clean);

package/dist/runtime.js

@@ -35,6 +35,15 @@ export function base64Encode(bytes) {
     }
     return btoa(binary);
 }
+/**
+ * Milliseconds on a monotonic clock (`performance.now()`, which Node, Deno, Bun and workerd provide), for
+ * measuring how long something has been cached: unlike `Date.now()`, a wall-clock step does not move it.
+ *
+ * @internal
+ */
+export function monotonicMs() {
+    return performance.now();
+}
 /**
  * An environment variable, or `undefined` on a runtime with no `process.env` (most edge runtimes).
  *

package/dist/signer.d.ts

@@ -19,6 +19,11 @@ export interface JwsSigner {
  * 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 declare class OpenBaoTransitSigner implements JwsSigner {
@@ -26,7 +31,9 @@ export declare class OpenBaoTransitSigner implements JwsSigner {
     readonly algorithm: string;
     readonly keyId: string;
     private constructor();
-    static create(baoAddr: string, token: string, keyName: string): Promise<OpenBaoTransitSigner>;
+    static create(baoAddr: string, token: string, keyName: string, opts?: {
+        allowInsecure?: boolean;
+    }): Promise<OpenBaoTransitSigner>;
     publicJwk(): JWK;
     sign(signingInput: Uint8Array): Promise<Uint8Array>;
 }

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,19 @@ 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. 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.