@nathapp/nax-agent 0.1.0

package/dist/native/credentials/fingerprint.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Keyed credential fingerprints (US-002).
+ *
+ * A fingerprint lets a run report "the credential this call was billed to has
+ * changed" without ever logging the credential: the first 12 lowercase hex
+ * characters of HMAC-SHA-256 over the credential's identifying secret, keyed by
+ * a per-machine salt held in `<configDir>/auth-fingerprint-salt`.
+ *
+ * The salt is what makes the digest useless as a lookup key, and it is per
+ * machine by design — a fingerprint cannot be compared across machines. It is
+ * published atomically at mode 0600, so a writer that loses the creation race
+ * reads the winner's complete file instead of overwriting it.
+ */
+import type { StoredCredential } from "@nathapp/nax-ai";
+/** Clears the salt memo and the warn-once set. Tests only. */
+export declare function _resetFingerprintSalt(): void;
+/**
+ * The first 12 lowercase hex characters of HMAC-SHA-256 over the credential's
+ * identifying secret, keyed by the machine salt.
+ *
+ * `api-key` fingerprints its `key` as written — a `$VAR` or `!command` template
+ * is fingerprinted as the template, because nax-ai documents `key` as opaque.
+ * `oauth` fingerprints its `refresh` token, so access-token rotation is
+ * invisible while refresh-token rotation is not.
+ */
+export declare function fingerprintCredential(credential: StoredCredential): Promise<string>;

package/dist/native/credentials/fingerprint.js

@@ -0,0 +1,174 @@
+/**
+ * Keyed credential fingerprints (US-002).
+ *
+ * A fingerprint lets a run report "the credential this call was billed to has
+ * changed" without ever logging the credential: the first 12 lowercase hex
+ * characters of HMAC-SHA-256 over the credential's identifying secret, keyed by
+ * a per-machine salt held in `<configDir>/auth-fingerprint-salt`.
+ *
+ * The salt is what makes the digest useless as a lookup key, and it is per
+ * machine by design — a fingerprint cannot be compared across machines. It is
+ * published atomically at mode 0600, so a writer that loses the creation race
+ * reads the winner's complete file instead of overwriting it.
+ */
+import { createHmac, randomBytes, randomUUID } from "node:crypto";
+import { link, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { errorMessage } from "#src/infra/errors";
+import { credentialsConfig, getSafeLogger } from "#src/infra/index";
+/** Exactly one HMAC key's worth. Anything shorter is a damaged file, not a salt. */
+const SALT_BYTES = 32;
+const SALT_FILENAME = "auth-fingerprint-salt";
+/** Lowercase hex characters retained from the digest. */
+const FINGERPRINT_CHARS = 12;
+/**
+ * Salt memo, and the salt-file path it belongs to: `NAX_GLOBAL_CONFIG_DIR`
+ * moves between tests, and a salt cached for a stale path would make every
+ * fingerprint in the new directory wrong.
+ */
+let memoPath;
+let memoSalt;
+/** Salt-file paths already reported invalid, so the event is emitted once per file. */
+const warnedInvalidPaths = new Set();
+/** Clears the salt memo and the warn-once set. Tests only. */
+export function _resetFingerprintSalt() {
+    memoPath = undefined;
+    memoSalt = undefined;
+    warnedInvalidPaths.clear();
+}
+/** Absolute path of the per-machine salt file. */
+function saltFilePath() {
+    return join(credentialsConfig().configDir(), SALT_FILENAME);
+}
+/** Read the salt file. `undefined` when it does not exist. */
+async function readSaltFile(path) {
+    try {
+        return await readFile(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Create the salt file with its bytes already in place, or read the winner's
+ * when another writer beat us to it.
+ *
+ * `open(path, "wx")` publishes the name before the payload lands, so a process
+ * that lost the creation race could read a 0-byte file, call it invalid and
+ * fingerprint with an in-memory salt nobody else on the machine shares. Staging
+ * the bytes and hard-linking them into place publishes the name only once the
+ * content exists: `link` fails with EEXIST when another writer got there first,
+ * and a hard link shares the inode, mode 0600 included.
+ *
+ * The staging name is unique per attempt, so two concurrent callers inside one
+ * process cannot overwrite each other's bytes.
+ */
+async function createSaltFile(path) {
+    // A fresh machine has no global config dir yet, and an exclusive create cannot
+    // make one: an absent parent surfaces as ENOENT, not EEXIST, so the first
+    // fingerprint would throw instead of creating the salt.
+    await mkdir(dirname(path), { recursive: true });
+    const candidate = randomBytes(SALT_BYTES);
+    const staged = `${path}.${randomUUID()}.staged`;
+    try {
+        await writeFile(staged, candidate, { mode: 0o600 });
+        try {
+            await link(staged, path);
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                return readSaltFile(path);
+            throw error;
+        }
+        return candidate;
+    }
+    finally {
+        await rm(staged, { force: true });
+    }
+}
+/**
+ * Load the machine salt, creating it on first use.
+ *
+ * A file that is not exactly 32 bytes is left untouched: it is replaced by a
+ * random in-memory salt for this process, and `credential.salt_invalid` is
+ * logged once for that path. Rewriting the file would destroy whatever an
+ * operator put there, and reusing a short read would be worse than a fresh key.
+ *
+ * Any filesystem failure resolves the same way. This runs on the run-start probe
+ * (`providersWithoutCredentials`), where a raw `EACCES`/`EISDIR` would escape as a
+ * non-`NaxError` and take the whole precheck report down with it.
+ *
+ * The trade is deliberate and it is a real loss: a random salt breaks the
+ * cross-process comparison on THIS machine, which is the one thing a per-machine
+ * salt exists to provide (fingerprints still cannot cross machines either way —
+ * that is what the salt buys). So a run whose `~/.nax` is unwritable reports
+ * `credential.changed`/`credential.renewed` against a baseline no sibling process
+ * shares, and its `auth` fingerprints do not line up with the next run's. The
+ * errno rides along on the event so an operator can tell a permissions problem
+ * from a truncated file, which is the difference between a fixable machine and a
+ * mysterious one.
+ */
+async function loadSalt(path) {
+    let stored;
+    let failure;
+    try {
+        stored = (await readSaltFile(path)) ?? (await createSaltFile(path));
+    }
+    catch (error) {
+        stored = undefined;
+        failure = error;
+    }
+    if (stored !== undefined && stored.byteLength === SALT_BYTES)
+        return stored;
+    if (!warnedInvalidPaths.has(path)) {
+        warnedInvalidPaths.add(path);
+        getSafeLogger()?.warn("credentials", "credential.salt_invalid", {
+            saltPath: path,
+            ...(failure !== undefined
+                ? { errno: failure.code, error: errorMessage(failure) }
+                : {}),
+        });
+    }
+    return randomBytes(SALT_BYTES);
+}
+/** The salt this process fingerprints with, memoised per salt-file path. */
+async function resolveSalt() {
+    const path = saltFilePath();
+    if (memoSalt !== undefined && memoPath === path)
+        return memoSalt;
+    const salt = await loadSalt(path);
+    memoPath = path;
+    memoSalt = salt;
+    return salt;
+}
+/**
+ * The part of a credential that identifies it.
+ *
+ * Exhaustive over the union on purpose: a third `StoredCredential` kind must
+ * fail the build here, not silently hash whichever field the `else` branch
+ * happened to name.
+ */
+function identifyingSecret(credential) {
+    switch (credential.kind) {
+        case "api-key":
+            return credential.key;
+        case "oauth":
+            return credential.refresh;
+    }
+}
+/**
+ * The first 12 lowercase hex characters of HMAC-SHA-256 over the credential's
+ * identifying secret, keyed by the machine salt.
+ *
+ * `api-key` fingerprints its `key` as written — a `$VAR` or `!command` template
+ * is fingerprinted as the template, because nax-ai documents `key` as opaque.
+ * `oauth` fingerprints its `refresh` token, so access-token rotation is
+ * invisible while refresh-token rotation is not.
+ */
+export async function fingerprintCredential(credential) {
+    const salt = await resolveSalt();
+    const secret = identifyingSecret(credential);
+    return createHmac("sha256", salt).update(secret).digest("hex").slice(0, FINGERPRINT_CHARS);
+}

package/dist/native/credentials/helper-process.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The exec helper's process boundary (US-003): spawn it, feed it one request
+ * line, bound both streams, and report what came back.
+ *
+ * Nothing here chooses a credential error code — that mapping belongs to
+ * exec-source.ts. What this module owns is the deadline, the stdout cap, the
+ * bounded drain after the process is gone, and the secrecy rule: stderr is
+ * redacted *before* it is truncated, so truncation can never cut a secret into a
+ * fragment the redaction patterns no longer recognise.
+ */
+/**
+ * Hard cap on the helper's stdout. Over it the reply is malformed and the
+ * process is killed. Not configurable (US-003 scope).
+ */
+export declare const AUTH_HELPER_STDOUT_MAX_BYTES = 65536;
+/** Hard cap on the stderr excerpt that may reach a log line or an error message. */
+export declare const AUTH_HELPER_STDERR_MAX_BYTES = 4096;
+/** The slice of the runtime's spawn result this module uses. */
+interface HelperProcess {
+    readonly stdin: {
+        write(data: string): unknown;
+        end(): unknown;
+    };
+    readonly stdout: ReadableStream<Uint8Array>;
+    readonly stderr: ReadableStream<Uint8Array>;
+    readonly exited: Promise<number>;
+    readonly exitCode: number | null;
+    /**
+     * Always SIGKILL. A deadline that a helper can ignore is not a deadline: the
+     * call would wait on a process that never exits, and `read` would never settle.
+     */
+    kill(signal: "SIGKILL"): void;
+}
+declare function spawnHelper(argv: readonly string[]): HelperProcess;
+/**
+ * Injectable seam (the `_deps` pattern): every external call this module makes
+ * goes through it, so a test can drive the helper without a real process.
+ *
+ * The spawn deliberately passes no `env`: the child inherits nax's environment,
+ * which is what the helper contract promises.
+ */
+export declare const _execSourceDeps: {
+    spawn: typeof spawnHelper;
+    /**
+     * Timer pair, wrapped so the global functions are resolved per call — a test
+     * that spies on `setTimeout` (the timer-leak helper) still sees these.
+     */
+    setTimeout: (fn: () => void, ms: number) => unknown;
+    clearTimeout: (id: unknown) => void;
+};
+/** What one helper invocation produced, as the process boundary saw it. */
+export type HelperProcessResult = {
+    kind: "spawn-failed";
+    detail: string;
+    cause: unknown;
+    stderr: string;
+} | {
+    kind: "timed-out";
+    detail: string;
+    stderr: string;
+} | {
+    kind: "stdout-over-cap";
+    detail: string;
+    stderr: string;
+}
+/** No reply to judge: the process was killed, or its streams failed under us. */
+ | {
+    kind: "no-answer";
+    detail: string;
+    stderr: string;
+} | {
+    kind: "exited";
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+/** Spawn the helper for `providerId` and report what it produced. Never throws for a helper failure. */
+export declare function runHelper(command: readonly string[], providerId: string, timeoutMs: number): Promise<HelperProcessResult>;
+export {};

package/dist/native/credentials/helper-process.js

@@ -0,0 +1,259 @@
+/**
+ * The exec helper's process boundary (US-003): spawn it, feed it one request
+ * line, bound both streams, and report what came back.
+ *
+ * Nothing here chooses a credential error code — that mapping belongs to
+ * exec-source.ts. What this module owns is the deadline, the stdout cap, the
+ * bounded drain after the process is gone, and the secrecy rule: stderr is
+ * redacted *before* it is truncated, so truncation can never cut a secret into a
+ * fragment the redaction patterns no longer recognise.
+ */
+import { errorMessage } from "#src/infra/errors";
+import { getSafeLogger, NaxError } from "#src/infra/index";
+import { redactSecrets } from "#src/internal/redact";
+import { runtimeSpawn } from "#src/runtime/index";
+import { HELPER_SUBCOMMAND, requestLine } from "./helper-protocol.js";
+/**
+ * Hard cap on the helper's stdout. Over it the reply is malformed and the
+ * process is killed. Not configurable (US-003 scope).
+ */
+export const AUTH_HELPER_STDOUT_MAX_BYTES = 65_536;
+/** Hard cap on the stderr excerpt that may reach a log line or an error message. */
+export const AUTH_HELPER_STDERR_MAX_BYTES = 4_096;
+/**
+ * How much stderr is collected before further bytes are dropped. Redaction runs
+ * over the whole collected prefix and only AUTH_HELPER_STDERR_MAX_BYTES of the
+ * result is kept, so the 8× margin leaves a secret that straddles the
+ * truncation point fully visible to the redaction patterns.
+ */
+const AUTH_HELPER_STDERR_COLLECT_MAX_BYTES = AUTH_HELPER_STDERR_MAX_BYTES * 8;
+/**
+ * How long the readers may keep waiting once the process is gone. A helper's
+ * pipes close the instant it exits; only an inherited pipe — a descendant of a
+ * killed helper, such as the `sleep` or the network client it shelled out to —
+ * outlives it, and that one will never end on its own.
+ */
+const DRAIN_GRACE_MS = 500;
+/** A piped spawn always has stdin; a runtime that broke that is a spawn failure, caught by the caller. */
+function hasStdin(proc) {
+    return proc.stdin !== undefined;
+}
+function spawnHelper(argv) {
+    // nax-git-env-allow: caller-supplied helper argv, not git; the child inherits nax's env by contract
+    const proc = runtimeSpawn(argv, { stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+    if (!hasStdin(proc)) {
+        throw new NaxError("[credentials] the runtime returned no stdin for a piped spawn", "CREDENTIAL_HELPER_FAILED", {
+            stage: "credentials",
+        });
+    }
+    return proc;
+}
+/**
+ * Injectable seam (the `_deps` pattern): every external call this module makes
+ * goes through it, so a test can drive the helper without a real process.
+ *
+ * The spawn deliberately passes no `env`: the child inherits nax's environment,
+ * which is what the helper contract promises.
+ */
+export const _execSourceDeps = {
+    spawn: spawnHelper,
+    /**
+     * Timer pair, wrapped so the global functions are resolved per call — a test
+     * that spies on `setTimeout` (the timer-leak helper) still sees these.
+     */
+    setTimeout: ((fn, ms) => setTimeout(fn, ms)),
+    clearTimeout: ((id) => clearTimeout(id)),
+};
+/**
+ * Read a stream to EOF, decoding UTF-8.
+ *
+ * Reads run concurrently with the exit wait: a child that fills the OS pipe
+ * buffer before anyone reads it would otherwise block on its own write and never
+ * reach `exited`, which would leave the timeout as the only way out.
+ *
+ * Past `cap` the two callers differ. With `onExceeded` the stream is abandoned —
+ * the callback kills the process, so there is nothing left to drain. Without it
+ * the stream is still drained (a full pipe must not wedge the child) but nothing
+ * more is kept.
+ */
+async function readCapped(stream, cap, options = {}) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let text = "";
+    let bytes = 0;
+    let exceeded = false;
+    /** Abort closes the stream, which resolves the pending `read()` with `done`. */
+    const onAbort = () => {
+        reader.cancel().catch(() => { });
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done === true)
+                break;
+            if (value === undefined)
+                continue;
+            bytes += value.byteLength;
+            if (bytes > cap && !exceeded) {
+                exceeded = true;
+                if (options.onExceeded !== undefined) {
+                    options.onExceeded();
+                    // The process is dying; do not wait for its pipe to notice.
+                    await reader.cancel().catch(() => { });
+                    break;
+                }
+            }
+            if (!exceeded)
+                text += decoder.decode(value, { stream: true });
+        }
+    }
+    catch {
+        // The pipe closed under us — a kill, an abort, or a child that exited
+        // mid-write. Whatever was collected before that still stands.
+    }
+    finally {
+        options.signal?.removeEventListener("abort", onAbort);
+    }
+    if (!exceeded)
+        text += decoder.decode();
+    return { text, exceeded };
+}
+/** Write the one-line request, then close stdin so the helper sees EOF. */
+function writeRequest(proc, providerId) {
+    try {
+        proc.stdin.write(requestLine(providerId));
+        proc.stdin.end();
+    }
+    catch (cause) {
+        // A helper that exits without draining stdin surfaces EPIPE here. Its exit
+        // code is the verdict, so this is a diagnostic, not a failure of its own.
+        getSafeLogger()?.debug("credentials", "credential.helper_stdin_failed", {
+            providerId,
+            error: errorMessage(cause),
+        });
+    }
+}
+/**
+ * Collect both streams, bounded by DRAIN_GRACE_MS once the process has exited.
+ *
+ * A helper's pipes close as it exits — unless it left a descendant holding them,
+ * and a killed helper leaves exactly that whenever it shelled out. That pipe
+ * never closes on its own, so it must not be allowed to hold the read past the
+ * deadline the source promises: whatever arrived within the grace is kept, and
+ * the rest is abandoned.
+ */
+async function drainStreams(streams) {
+    let graceTimer;
+    const grace = new Promise((resolve) => {
+        graceTimer = _execSourceDeps.setTimeout(() => resolve(null), DRAIN_GRACE_MS);
+    });
+    try {
+        const drained = await Promise.race([Promise.all([streams.stdout, streams.stderr]), grace]);
+        if (drained !== null)
+            return drained;
+        for (const controller of streams.controllers)
+            controller.abort();
+        return await Promise.all([streams.stdout, streams.stderr]);
+    }
+    finally {
+        // Cleared on both paths: an armed timer outliving the call keeps the event
+        // loop alive after the read has already resolved.
+        _execSourceDeps.clearTimeout(graceTimer);
+    }
+}
+/**
+ * SIGKILL a helper, tolerating a child that is already gone.
+ *
+ * A deadline that a helper can ignore is not a deadline: the call would wait on
+ * a process that never exits, and `read` would never settle. The `try` is for the
+ * race where the child is reaped between the decision to kill it and the signal.
+ */
+function killHelper(proc) {
+    try {
+        proc.kill("SIGKILL");
+    }
+    catch {
+        // The child was already gone; its exit code decides the outcome either way.
+    }
+}
+/** Run one helper process to its end, killing it if either kill switch trips first. */
+async function runHelperProcess(proc, providerId, timeoutMs) {
+    // Whichever trips first decides the outcome; both kill the process.
+    let trip;
+    const timer = _execSourceDeps.setTimeout(() => {
+        if (trip === undefined)
+            trip = "timeout";
+        killHelper(proc);
+    }, timeoutMs);
+    const stdoutController = new AbortController();
+    const stderrController = new AbortController();
+    try {
+        writeRequest(proc, providerId);
+        // Reading starts here, concurrently with the exit wait below.
+        const streams = {
+            stdout: readCapped(proc.stdout, AUTH_HELPER_STDOUT_MAX_BYTES, {
+                signal: stdoutController.signal,
+                onExceeded: () => {
+                    if (trip === undefined)
+                        trip = "cap";
+                    killHelper(proc);
+                },
+            }),
+            stderr: readCapped(proc.stderr, AUTH_HELPER_STDERR_COLLECT_MAX_BYTES, { signal: stderrController.signal }),
+            controllers: [stdoutController, stderrController],
+        };
+        await proc.exited;
+        const [stdout, stderr] = await drainStreams(streams);
+        return { trip, exitCode: proc.exitCode, stdout, stderr: stderr.text };
+    }
+    finally {
+        // Cleared however the call ends, including the timeout: a timer left armed
+        // holds the event loop open after the read has already resolved.
+        _execSourceDeps.clearTimeout(timer);
+    }
+}
+/** Spawn the helper for `providerId` and report what it produced. Never throws for a helper failure. */
+export async function runHelper(command, providerId, timeoutMs) {
+    let proc;
+    try {
+        // nax-git-env-allow: caller-supplied helper argv, not git; the child inherits nax's env by contract
+        proc = _execSourceDeps.spawn([...command, HELPER_SUBCOMMAND]);
+    }
+    catch (cause) {
+        // A missing binary never reaches `exited`: the runtime throws ENOENT from spawn.
+        return { kind: "spawn-failed", detail: `could not be started: ${errorMessage(cause)}`, cause, stderr: "" };
+    }
+    let run;
+    try {
+        run = await runHelperProcess(proc, providerId, timeoutMs);
+    }
+    catch (cause) {
+        // The streams or the exit wait failed under us, so nothing was learned about
+        // the provider. The child is NOT necessarily dead, though: the `finally` in
+        // runHelperProcess has already cleared the deadline timer that would have
+        // killed it, and that call's abort controllers died with the throw. Left
+        // alone it runs until it chooses to stop, holding two open pipes. Kill it
+        // and drop the readers here, where `proc` is still in scope.
+        killHelper(proc);
+        await Promise.allSettled([proc.stdout.cancel(), proc.stderr.cancel()]);
+        return { kind: "no-answer", detail: `could not be read: ${errorMessage(cause)}`, stderr: "" };
+    }
+    // Redact first, truncate second. The other order can cut a secret in half and
+    // leave a fragment no redaction pattern can recognise.
+    const stderr = redactSecrets(run.stderr).slice(0, AUTH_HELPER_STDERR_MAX_BYTES);
+    if (run.trip === "cap") {
+        return {
+            kind: "stdout-over-cap",
+            detail: `wrote more than ${AUTH_HELPER_STDOUT_MAX_BYTES} bytes to stdout`,
+            stderr,
+        };
+    }
+    if (run.trip === "timeout") {
+        return { kind: "timed-out", detail: `did not answer within ${timeoutMs}ms`, stderr };
+    }
+    if (run.exitCode === null) {
+        return { kind: "no-answer", detail: "was killed before it could answer", stderr };
+    }
+    return { kind: "exited", exitCode: run.exitCode, stdout: run.stdout.text, stderr };
+}

package/dist/native/credentials/helper-protocol.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The exec helper's wire contract (US-003): one request line in, one reply line
+ * out.
+ *
+ * Held apart from the process boundary (helper-process.ts) and the source itself
+ * (exec-source.ts) because this is the part koda implements against, and because
+ * every rule here is fail-closed: anything this module cannot name with certainty
+ * is invalid, never a best-effort read of the nearest field.
+ */
+/** The request/reply protocol version this source speaks. */
+export declare const REQUEST_VERSION = 1;
+/** The subcommand appended to the configured command. */
+export declare const HELPER_SUBCOMMAND = "get";
+/**
+ * One credential as the helper reported it. `expiresAt` absent means the lease
+ * is good for the life of the process; `account` is a label, never a secret.
+ */
+export interface Lease {
+    key: string;
+    expiresAt?: number;
+    account?: string;
+}
+/** What a helper's stdout said. */
+export type ParsedReply = {
+    kind: "credential";
+    lease: Lease;
+} | {
+    kind: "decline";
+} | {
+    kind: "invalid";
+    detail: string;
+};
+/** The one JSON line written to the helper's stdin. */
+export declare function requestLine(providerId: string): string;
+/** Validate one credential or decline reply, fail-closed. */
+export declare function parseReply(stdout: string): ParsedReply;

package/dist/native/credentials/helper-protocol.js

@@ -0,0 +1,79 @@
+/**
+ * The exec helper's wire contract (US-003): one request line in, one reply line
+ * out.
+ *
+ * Held apart from the process boundary (helper-process.ts) and the source itself
+ * (exec-source.ts) because this is the part koda implements against, and because
+ * every rule here is fail-closed: anything this module cannot name with certainty
+ * is invalid, never a best-effort read of the nearest field.
+ */
+/** The request/reply protocol version this source speaks. */
+export const REQUEST_VERSION = 1;
+/** The subcommand appended to the configured command. */
+export const HELPER_SUBCOMMAND = "get";
+/** A longer credential is a malformed reply, not a key to try. */
+const MAX_KEY_CHARS = 8_192;
+/** The non-secret account label's length cap. */
+const MAX_ACCOUNT_CHARS = 200;
+/** The one JSON line written to the helper's stdin. */
+export function requestLine(providerId) {
+    return `${JSON.stringify({ version: REQUEST_VERSION, providerId })}\n`;
+}
+/** Validate one credential or decline reply, fail-closed. */
+export function parseReply(stdout) {
+    const invalid = (detail) => ({ kind: "invalid", detail });
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        // The parser's message quotes the text it failed on, so it carries a fragment
+        // of stdout — which is where the key lives. The reply is malformed either
+        // way, and the caller has the code; naming the parser's text would put a
+        // secret in an error message, and from there in the CLI and the precheck
+        // report. See the Secrets rule in docs/specs/SPEC-credential-sources.md.
+        return invalid("stdout was not JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return invalid("the reply was not a JSON object");
+    }
+    const reply = parsed;
+    // Neither `version` nor `kind` is echoed back: both are helper-controlled and
+    // unvalidated, so `JSON.stringify` on one would copy an arbitrarily large
+    // subtree of stdout — which is where the key is — into the message. Naming the
+    // field and the expected value is enough to debug a helper.
+    if (reply.version !== REQUEST_VERSION) {
+        return invalid(`version was not ${REQUEST_VERSION}`);
+    }
+    // The decline reply carries no kind, so it is recognised before the credential
+    // fields are required.
+    if (reply.decline === true)
+        return { kind: "decline" };
+    if (reply.kind !== "api-key")
+        return invalid('kind was not "api-key"');
+    const key = reply.key;
+    if (typeof key !== "string" || key.length === 0)
+        return invalid("the reply carried no key");
+    if (key.length > MAX_KEY_CHARS)
+        return invalid(`the key was longer than ${MAX_KEY_CHARS} characters`);
+    const account = reply.account;
+    if (account !== undefined && (typeof account !== "string" || account.length > MAX_ACCOUNT_CHARS)) {
+        return invalid(`the account label was not a string of at most ${MAX_ACCOUNT_CHARS} characters`);
+    }
+    const expiresAt = reply.expiresAt;
+    if (expiresAt !== undefined) {
+        if (typeof expiresAt !== "number" || !Number.isSafeInteger(expiresAt) || expiresAt <= 0) {
+            return invalid("expiresAt was not a positive integer");
+        }
+        if (expiresAt < Date.now())
+            return invalid("expiresAt was already past on receipt");
+    }
+    return {
+        kind: "credential",
+        lease: {
+            key,
+            ...(typeof account === "string" ? { account } : {}),
+            ...(typeof expiresAt === "number" ? { expiresAt } : {}),
+        },
+    };
+}