@nathapp/nax-agent 0.1.0

package/dist/permissions/ask-chain.js

@@ -0,0 +1,32 @@
+/**
+ * Compose links into a resolver. First non-abstain wins.
+ *
+ * A throwing link abstains rather than propagating: `runtime.callTool` turns an
+ * exception out of the resolver into a TOOL ERROR surfaced to the model, not a
+ * denial, which would lose the `denied:ask` ledger row and hand the agent
+ * something it may retry around.
+ *
+ * US-003: forwards the same `control` object to every link so a turn-cancel
+ * signal reaches whichever link would have answered, not just the first one
+ * that asks.
+ */
+export function chainAskLinks(links) {
+    return {
+        async resolve(req, control) {
+            const started = Date.now();
+            for (const link of links) {
+                let outcome;
+                try {
+                    outcome = await link.resolve(req, control);
+                }
+                catch {
+                    continue;
+                }
+                if (outcome.decision === "abstain")
+                    continue;
+                return { decision: outcome.decision, decidedBy: outcome.decidedBy, latencyMs: Date.now() - started };
+            }
+            return { decision: "deny", decidedBy: "unavailable", latencyMs: Date.now() - started };
+        },
+    };
+}

package/dist/permissions/ask.d.ts

@@ -0,0 +1,23 @@
+import { type AskResolver } from "./ask-chain.ts";
+/**
+ * Why an ask-matched call was refused. One string per CASE: the previous single
+ * message asserted "this run is headless" for situations that are not, and the
+ * three are materially different facts for anyone reading the ledger.
+ */
+export declare const ASK_NO_CHANNEL_REASON = "matched an ask rule requiring human approval; no approval channel is configured for this run, so the call is refused";
+export declare const ASK_TIMEOUT_REASON = "matched an ask rule requiring human approval; no answer arrived before the approval timeout, so the call is refused";
+export declare const ASK_DENIED_REASON = "matched an ask rule requiring human approval; the operator denied it";
+/**
+ * US-003: the orchestrating turn was cancelled before anyone answered (or
+ * between the resolver returning allow and the tool actually running). The
+ * tool never executed; the message stays short so it reads in a tool error.
+ */
+export declare const ASK_CANCELLED_REASON = "Not run: the turn was cancelled before anyone answered.";
+export declare const ASK_UNSHOWABLE_REASON = "Not run: the command contains a secret that cannot be shown to the approver safely; pass it through an environment variable instead.";
+/** Kept for compatibility with existing callers and tests. */
+export declare const ASK_UNAVAILABLE_REASON = "matched an ask rule requiring human approval; no approval channel is configured for this run, so the call is refused";
+/**
+ * The resolver a run gets when no channel is available: a chain with zero
+ * links, whose terminal deny supplies the answer. TOTAL -- never abstains.
+ */
+export declare function headlessAskResolver(): AskResolver;

package/dist/permissions/ask.js

@@ -0,0 +1,25 @@
+import { chainAskLinks } from "./ask-chain.js";
+/**
+ * Why an ask-matched call was refused. One string per CASE: the previous single
+ * message asserted "this run is headless" for situations that are not, and the
+ * three are materially different facts for anyone reading the ledger.
+ */
+export const ASK_NO_CHANNEL_REASON = "matched an ask rule requiring human approval; no approval channel is configured for this run, so the call is refused";
+export const ASK_TIMEOUT_REASON = "matched an ask rule requiring human approval; no answer arrived before the approval timeout, so the call is refused";
+export const ASK_DENIED_REASON = "matched an ask rule requiring human approval; the operator denied it";
+/**
+ * US-003: the orchestrating turn was cancelled before anyone answered (or
+ * between the resolver returning allow and the tool actually running). The
+ * tool never executed; the message stays short so it reads in a tool error.
+ */
+export const ASK_CANCELLED_REASON = "Not run: the turn was cancelled before anyone answered.";
+export const ASK_UNSHOWABLE_REASON = "Not run: the command contains a secret that cannot be shown to the approver safely; pass it through an environment variable instead.";
+/** Kept for compatibility with existing callers and tests. */
+export const ASK_UNAVAILABLE_REASON = ASK_NO_CHANNEL_REASON;
+/**
+ * The resolver a run gets when no channel is available: a chain with zero
+ * links, whose terminal deny supplies the answer. TOTAL -- never abstains.
+ */
+export function headlessAskResolver() {
+    return chainAskLinks([]);
+}

package/dist/permissions/bash-lex.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Lexer and segmenter for a model-authored Bash command (spec §4 US-005.1-2).
+ *
+ * Safe-by-refusal, not safe-by-sandbox: any construct this lexer does not
+ * MODEL is refused by name, because a payload the gate cannot read is a
+ * payload no shell gets (spec R11). That is a deliberately small language —
+ * words, quotes, operators, simple redirections — and growing it is a
+ * permission decision, not a parser improvement.
+ *
+ * "Refused by name" is the whole guarantee, so it must hold for EVERY
+ * unmodelled construct, not only the ones that look dangerous. A construct
+ * that folds into a word instead is worse than one that is modelled: the
+ * segment still reaches the policy, and its first token is no longer the
+ * command a deny rule was written against.
+ *
+ * ZERO imports, on purpose. `src/permissions` must not value-import
+ * `@/tools` (the edge runs the other way: src/tools/runtime.ts imports this
+ * package), and a lexer that needs nothing is also a lexer that can be tested
+ * without a filesystem, a policy or a spawn.
+ */
+/** One word of a segment. `opaque` means it contained `$`-expansion, so its
+ * RUNTIME value is unknown here and policy-bash.ts refuses it before execution. */
+export interface BashToken {
+    readonly text: string;
+    readonly opaque: boolean;
+}
+/** A simple redirection. The target is containment-checked by the caller. */
+export interface BashRedirect {
+    readonly operator: string;
+    readonly target: string;
+    readonly opaque: boolean;
+}
+/** The control operator that follows a command segment, when any. */
+export type BashSegmentSeparator = ";" | "&&" | "||" | "|" | "&";
+/** One command between control operators. */
+export interface BashSegment {
+    readonly tokens: readonly BashToken[];
+    readonly redirects: readonly BashRedirect[];
+    readonly separator?: BashSegmentSeparator;
+}
+export type BashLexResult = {
+    readonly kind: "ok";
+    readonly segments: readonly BashSegment[];
+} | {
+    readonly kind: "refused";
+    readonly construct: string;
+    /**
+     * The lexable prefix at the point of refusal: the completed segments,
+     * followed by the interrupted segment's completed tokens and redirects
+     * only. The word being built when the refusal struck is dropped, as is a
+     * redirect operator still waiting for its target; a trailing segment with
+     * neither tokens nor redirects is omitted. `[]` when the refusal precedes
+     * any completed word. The gate runs its deny and payload checks over this
+     * prefix, so an out-of-bounds command never reaches the human just because
+     * a later construct was unreadable.
+     */
+    readonly prefix: readonly BashSegment[];
+};
+export declare function lexBashCommand(command: string): BashLexResult;

package/dist/permissions/bash-lex.js

@@ -0,0 +1,279 @@
+/**
+ * Lexer and segmenter for a model-authored Bash command (spec §4 US-005.1-2).
+ *
+ * Safe-by-refusal, not safe-by-sandbox: any construct this lexer does not
+ * MODEL is refused by name, because a payload the gate cannot read is a
+ * payload no shell gets (spec R11). That is a deliberately small language —
+ * words, quotes, operators, simple redirections — and growing it is a
+ * permission decision, not a parser improvement.
+ *
+ * "Refused by name" is the whole guarantee, so it must hold for EVERY
+ * unmodelled construct, not only the ones that look dangerous. A construct
+ * that folds into a word instead is worse than one that is modelled: the
+ * segment still reaches the policy, and its first token is no longer the
+ * command a deny rule was written against.
+ *
+ * ZERO imports, on purpose. `src/permissions` must not value-import
+ * `@/tools` (the edge runs the other way: src/tools/runtime.ts imports this
+ * package), and a lexer that needs nothing is also a lexer that can be tested
+ * without a filesystem, a policy or a spawn.
+ */
+/** End index of a double-quoted run starting at `from`, honouring backslash
+ * escapes, or -1 when the quote is never closed. */
+function doubleQuoteEnd(command, from) {
+    for (let i = from; i < command.length; i += 1) {
+        const char = command[i];
+        if (char === "\\") {
+            i += 1;
+            continue;
+        }
+        if (char === '"')
+            return i;
+    }
+    return -1;
+}
+export function lexBashCommand(command) {
+    // Checked up front so the reason names the real problem. Leaving it to the
+    // final flushSegment() would report "an empty command segment", which is
+    // true and useless.
+    if (command.trim() === "")
+        return { kind: "refused", construct: "an empty command", prefix: [] };
+    const state = {
+        command,
+        segments: [],
+        tokens: [],
+        redirects: [],
+        word: "",
+        opaque: false,
+        started: false,
+        pendingRedirect: undefined,
+    };
+    let i = 0;
+    while (i < command.length) {
+        const step = stepAt(state, i);
+        if (step === undefined) {
+            // Plain word character: accumulates into the token being built.
+            state.word += command[i];
+            state.started = true;
+            i += 1;
+            continue;
+        }
+        if (step.kind === "refuse")
+            return refusedHere(state, step.construct);
+        i += step.by;
+    }
+    const error = flushSegment(state);
+    if (error !== undefined)
+        return refusedHere(state, error);
+    return { kind: "ok", segments: state.segments };
+}
+/** Snapshots the lexable prefix at a refusal site (see `BashLexResult`). The
+ * in-progress `word` is deliberately excluded, and `pendingRedirect` -- an
+ * operator awaiting its target -- lives outside `redirects`, so it is dropped
+ * with it. */
+function refusedHere(state, construct) {
+    const prefix = state.tokens.length === 0 && state.redirects.length === 0
+        ? [...state.segments]
+        : [...state.segments, { tokens: state.tokens, redirects: state.redirects }];
+    return { kind: "refused", construct, prefix };
+}
+function flushWord(state) {
+    if (!state.started)
+        return;
+    if (state.pendingRedirect !== undefined) {
+        state.redirects.push({ operator: state.pendingRedirect, target: state.word, opaque: state.opaque });
+        state.pendingRedirect = undefined;
+    }
+    else {
+        state.tokens.push({ text: state.word, opaque: state.opaque });
+    }
+    state.word = "";
+    state.opaque = false;
+    state.started = false;
+}
+/** Closes a segment, or names why it cannot be closed. A dangling operator
+ * leaves an empty segment, which is refused rather than silently dropped:
+ * `bun test &&` is a truncated command, and guessing at intent here would
+ * approve something nobody wrote. */
+function flushSegment(state, separator) {
+    flushWord(state);
+    if (state.pendingRedirect !== undefined)
+        return "a redirection with no target";
+    if (state.tokens.length === 0 && state.redirects.length === 0)
+        return "an empty command segment";
+    state.segments.push({
+        tokens: state.tokens,
+        redirects: state.redirects,
+        ...(separator === undefined ? {} : { separator }),
+    });
+    state.tokens = [];
+    state.redirects = [];
+    return undefined;
+}
+function lexSingleQuote(state, i) {
+    if (state.command[i] !== "'")
+        return undefined;
+    const end = state.command.indexOf("'", i + 1);
+    if (end === -1)
+        return { kind: "refuse", construct: "an unbalanced single quote" };
+    // Single quotes suppress every expansion, so the content stays literal
+    // and the token stays analysable.
+    state.word += state.command.slice(i + 1, end);
+    state.started = true;
+    return { kind: "advance", by: end + 1 - i };
+}
+function lexDoubleQuote(state, i) {
+    if (state.command[i] !== '"')
+        return undefined;
+    const end = doubleQuoteEnd(state.command, i + 1);
+    if (end === -1)
+        return { kind: "refuse", construct: "an unbalanced double quote" };
+    const inner = state.command.slice(i + 1, end);
+    if (inner.includes("$("))
+        return { kind: "refuse", construct: "a command substitution `$(...)`" };
+    if (inner.includes("`"))
+        return { kind: "refuse", construct: "a backtick command substitution" };
+    if (inner.includes("$"))
+        state.opaque = true;
+    state.word += inner;
+    state.started = true;
+    return { kind: "advance", by: end + 1 - i };
+}
+function lexEscape(state, i) {
+    if (state.command[i] !== "\\")
+        return undefined;
+    const next = state.command[i + 1];
+    if (next === undefined)
+        return { kind: "refuse", construct: "a trailing backslash" };
+    state.word += next;
+    state.started = true;
+    return { kind: "advance", by: 2 };
+}
+/** Grouping, negation, comments and command substitutions are shell SYNTAX,
+ * not word characters: left unmodelled they fold into the token text, so
+ * `(rm -rf x)` and `! rm -rf x` present a first token of `(rm` / `!` that no
+ * `Bash(rm*)` deny rule can match, while /bin/sh runs the `rm` regardless.
+ * Refused by name, like every other construct this lexer cannot read. `!` and
+ * `#` are only special at the START of a word -- `a!b` and `a#b` are ordinary
+ * literals in sh, and refusing those would deny commands a grant plainly
+ * covers. */
+function refuseGroupingOrExpansion(state, i) {
+    const command = state.command;
+    const char = command[i];
+    const next = command[i + 1];
+    if (char === "(" || char === ")")
+        return { kind: "refuse", construct: "a subshell `( ... )`" };
+    if (char === "!" && !state.started)
+        return { kind: "refuse", construct: "a `!` negation" };
+    if (char === "#" && !state.started)
+        return { kind: "refuse", construct: "a `#` comment" };
+    if (char === "$" && next === "(")
+        return { kind: "refuse", construct: "a command substitution `$(...)`" };
+    if (char === "`")
+        return { kind: "refuse", construct: "a backtick command substitution" };
+    return undefined;
+}
+/** Redirection FORMS this lexer does not model: a process substitution, a
+ * here-document, file-descriptor duplication and bash's `&>` shorthand are
+ * each refused by name before the plain `<`/`>` handler can claim them. */
+function refuseRedirectForm(state, i) {
+    const command = state.command;
+    const char = command[i];
+    const next = command[i + 1];
+    if ((char === "<" || char === ">") && next === "(") {
+        return { kind: "refuse", construct: "a process substitution `<(...)` / `>(...)`" };
+    }
+    if (char === "<" && next === "<")
+        return { kind: "refuse", construct: "a here-document `<<`" };
+    if ((char === "<" || char === ">") && next === "&") {
+        return { kind: "refuse", construct: "file-descriptor duplication (`2>&1`)" };
+    }
+    if (char === "&" && next === ">")
+        return { kind: "refuse", construct: "the `&>` redirection form" };
+    return undefined;
+}
+function lexDollar(state, i) {
+    if (state.command[i] !== "$")
+        return undefined;
+    state.opaque = true;
+    state.word += "$";
+    state.started = true;
+    return { kind: "advance", by: 1 };
+}
+function skipWhitespace(state, i) {
+    const char = state.command[i];
+    if (char !== " " && char !== "\t" && char !== "\r")
+        return undefined;
+    flushWord(state);
+    return { kind: "advance", by: 1 };
+}
+function lexLineSeparator(state, i) {
+    const char = state.command[i];
+    if (char !== "\n" && char !== ";")
+        return undefined;
+    const error = flushSegment(state, ";");
+    if (error !== undefined)
+        return { kind: "refuse", construct: error };
+    return { kind: "advance", by: 1 };
+}
+function lexControlOperator(state, i) {
+    const command = state.command;
+    const char = command[i];
+    const next = command[i + 1];
+    if ((char === "&" && next === "&") || (char === "|" && next === "|")) {
+        const error = flushSegment(state, char === "&" ? "&&" : "||");
+        if (error !== undefined)
+            return { kind: "refuse", construct: error };
+        return { kind: "advance", by: 2 };
+    }
+    if (char === "|" || char === "&") {
+        const error = flushSegment(state, char);
+        if (error !== undefined)
+            return { kind: "refuse", construct: error };
+        return { kind: "advance", by: 1 };
+    }
+    return undefined;
+}
+function lexRedirect(state, i) {
+    const command = state.command;
+    const char = command[i];
+    if (char !== ">" && char !== "<")
+        return undefined;
+    // A bare fd digit belongs to the operator (`2>err.txt`), not to argv:
+    // left in the token list it would have to satisfy an allow rule, and
+    // `Bash(bun test *)` would refuse a command it plainly covers.
+    if (/^\d$/.test(state.word)) {
+        state.word = "";
+        state.started = false;
+    }
+    flushWord(state);
+    const appends = char === ">" && command[i + 1] === ">";
+    state.pendingRedirect = appends ? ">>" : char;
+    return { kind: "advance", by: appends ? 2 : 1 };
+}
+/** The dispatch table. ORDER IS BEHAVIOUR: the first handler that claims the
+ * character wins, so the table must stay in the original guard chain's order —
+ * quote/escape handling, structural refusals, redirect-form refusals, `$`,
+ * whitespace, separators, plain redirection. */
+const HANDLERS = [
+    lexSingleQuote,
+    lexDoubleQuote,
+    lexEscape,
+    refuseGroupingOrExpansion,
+    refuseRedirectForm,
+    lexDollar,
+    skipWhitespace,
+    lexLineSeparator,
+    lexControlOperator,
+    lexRedirect,
+];
+/** Runs the first handler that claims the character at `i`, or `undefined`
+ * when it is a plain word character (accumulated by `lexBashCommand`). */
+function stepAt(state, i) {
+    for (const lex of HANDLERS) {
+        const step = lex(state, i);
+        if (step !== undefined)
+            return step;
+    }
+    return undefined;
+}

package/dist/permissions/grammar.d.ts

@@ -0,0 +1,12 @@
+import type { ToolGrant } from "./types.ts";
+/**
+ * Parse one #374 tool expression.
+ *
+ * `Read`                  -> unconditional
+ * `Write(src/**,test/**)` -> those two globs
+ * `Git(diff,log)`         -> those two subcommands
+ */
+export declare function parseToolExpression(expression: string): ToolGrant;
+/** Parse a list of rule expressions into grants. Effect is carried by which
+ * config list (allow/deny/ask) the expressions came from, not by the grant. */
+export declare function parseRuleList(expressions: readonly string[]): ToolGrant[];

package/dist/permissions/grammar.js

@@ -0,0 +1,24 @@
+/**
+ * Parse one #374 tool expression.
+ *
+ * `Read`                  -> unconditional
+ * `Write(src/**,test/**)` -> those two globs
+ * `Git(diff,log)`         -> those two subcommands
+ */
+export function parseToolExpression(expression) {
+    const open = expression.indexOf("(");
+    if (open === -1)
+        return { tool: expression.trim(), patterns: ["*"] };
+    const tool = expression.slice(0, open).trim();
+    const inner = expression.slice(open + 1, expression.lastIndexOf(")"));
+    const patterns = inner
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+    return { tool, patterns: patterns.length > 0 ? patterns : ["*"] };
+}
+/** Parse a list of rule expressions into grants. Effect is carried by which
+ * config list (allow/deny/ask) the expressions came from, not by the grant. */
+export function parseRuleList(expressions) {
+    return expressions.map(parseToolExpression);
+}

package/dist/permissions/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./approval-audit.ts";
+export * from "./approvals-link.ts";
+export * from "./approvals-store.ts";
+export * from "./approvals-taint.ts";
+export { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, headlessAskResolver, } from "./ask.ts";
+export * from "./ask-chain.ts";
+export type { BashLexResult, BashRedirect, BashSegment, BashSegmentSeparator, BashToken } from "./bash-lex.ts";
+export { lexBashCommand } from "./bash-lex.ts";
+export { parseRuleList, parseToolExpression } from "./grammar.ts";
+export * from "./secret-spans.ts";
+export type { AskRequest, ResolvedPermissions } from "./types.ts";

package/dist/permissions/index.js

@@ -0,0 +1,9 @@
+export * from "./approval-audit.js";
+export * from "./approvals-link.js";
+export * from "./approvals-store.js";
+export * from "./approvals-taint.js";
+export { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, headlessAskResolver, } from "./ask.js";
+export * from "./ask-chain.js";
+export { lexBashCommand } from "./bash-lex.js";
+export { parseRuleList, parseToolExpression } from "./grammar.js";
+export * from "./secret-spans.js";

package/dist/permissions/secret-spans.d.ts

@@ -0,0 +1,19 @@
+export interface SecretSpan {
+    readonly start: number;
+    readonly end: number;
+    readonly kind: string;
+}
+export type MaskResult = {
+    readonly ok: true;
+    readonly masked: string;
+    readonly count: number;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Non-overlapping spans, sorted; overlapping or touching matches merge (earliest kind wins). */
+export declare function findSecretSpans(text: string): readonly SecretSpan[];
+export declare function maskForPrompt(text: string): MaskResult;
+export declare function redactForRow(text: string): string;
+/** Apply `redactForRow` to every string leaf. Keys and non-string values are kept as-is. */
+export declare function redactRowStrings<T>(value: T): T;

package/dist/permissions/secret-spans.js

@@ -0,0 +1,88 @@
+/**
+ * Secret spans in agent-authored command text (review #9, spec section 1).
+ *
+ * Two consumers with different stakes:
+ *  - `maskForPrompt` feeds an approval prompt. A masked span must never hide
+ *    code from the human approving it, so any span containing shell syntax
+ *    makes the whole text unshowable and the ask is denied instead (D18).
+ *  - `redactForRow` feeds local audit rows. Nothing is approved from them but
+ *    forensic content matters, so each span is masked only up to its first
+ *    shell-active character: `Cookie: a=b'; rm -rf ~` keeps `'; rm -rf ~`.
+ *    Accepted residual: secret characters after a shell-active character stay
+ *    visible in the row.
+ */
+import { SECRET_VALUE_PATTERNS } from "#src/internal/redact";
+const SHELL_ACTIVE = /[$`;|&<>()'"\n]/;
+/** A PEM body is newline-separated by construction; only real shell syntax cuts it. */
+const SHELL_ACTIVE_IN_PEM = /[$`;|&<>()'"]/;
+/** Kinds whose match is `NAME=value` / `name: value`; a `$` value is a reference, not a secret. */
+const VALUE_KINDS = new Set(["assignment", "api-key-header"]);
+function referencesVariable(kind, match) {
+    if (!VALUE_KINDS.has(kind))
+        return false;
+    const sep = match.search(/[=:]/);
+    return (sep >= 0 &&
+        match
+            .slice(sep + 1)
+            .trimStart()
+            .startsWith("$"));
+}
+function rawSpans(text) {
+    return SECRET_VALUE_PATTERNS.flatMap(({ kind, re }) => {
+        // A private copy: the shared /g regex carries lastIndex between callers.
+        const scan = new RegExp(re.source, re.flags);
+        const found = [];
+        for (let m = scan.exec(text); m !== null; m = scan.exec(text)) {
+            if (!referencesVariable(kind, m[0]))
+                found.push({ start: m.index, end: m.index + m[0].length, kind });
+        }
+        return found;
+    });
+}
+/** Non-overlapping spans, sorted; overlapping or touching matches merge (earliest kind wins). */
+export function findSecretSpans(text) {
+    const sorted = [...rawSpans(text)].sort((a, b) => a.start - b.start || b.end - a.end);
+    const merged = [];
+    for (const span of sorted) {
+        const last = merged.at(-1);
+        if (last !== undefined && span.start <= last.end) {
+            merged[merged.length - 1] = { ...last, end: Math.max(last.end, span.end) };
+        }
+        else {
+            merged.push(span);
+        }
+    }
+    return merged;
+}
+function replaceSpans(text, spans, render) {
+    const parts = spans.map((span, i) => {
+        const gapStart = i === 0 ? 0 : (spans[i - 1]?.end ?? 0);
+        return text.slice(gapStart, span.start) + render(span, text.slice(span.start, span.end));
+    });
+    return parts.join("") + text.slice(spans.at(-1)?.end ?? 0);
+}
+export function maskForPrompt(text) {
+    const spans = findSecretSpans(text);
+    const unsafe = spans.find((span) => SHELL_ACTIVE.test(text.slice(span.start, span.end)));
+    if (unsafe !== undefined) {
+        return { ok: false, reason: `a ${unsafe.kind} secret spans shell syntax` };
+    }
+    return { ok: true, masked: replaceSpans(text, spans, (span) => `[REDACTED:${span.kind}]`), count: spans.length };
+}
+export function redactForRow(text) {
+    return replaceSpans(text, findSecretSpans(text), (span, body) => {
+        const cut = body.search(span.kind === "pem" ? SHELL_ACTIVE_IN_PEM : SHELL_ACTIVE);
+        return cut === -1 ? `[REDACTED:${span.kind}]` : `[REDACTED:${span.kind}]${body.slice(cut)}`;
+    });
+}
+/** Apply `redactForRow` to every string leaf. Keys and non-string values are kept as-is. */
+export function redactRowStrings(value) {
+    if (typeof value === "string")
+        return redactForRow(value);
+    if (Array.isArray(value))
+        return value.map((item) => redactRowStrings(item));
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactRowStrings(v)]));
+    }
+    return value;
+}