devflow-kit 2.4.0 → 2.5.0

package/src/assets/scripts/redact-secrets.cjs

@@ -6,17 +6,44 @@
 // Installed as a top-level sibling of hud.sh under ~/.devflow/scripts/.
 //
 // Usage: node redact-secrets.cjs <input-file> <output-file>
+//        node redact-secrets.cjs --emit <input-file>
+//
+// The two modes exist because their sinks differ, not for convenience.
+//   <in> <out>  FILE sink. The caller gates the post with a shell `&&` chain and
+//               passes the scrubbed FILE to `--body-file`.
+//   --emit      TOOL-CALL sink (GAP-04). A tracker reached through a tool call has
+//               no `--body-file` and no shell operator between the scrub and the
+//               post, so the `&&` gate cannot exist. Instead the scrubbed bytes
+//               are printed behind a framing line only this script can produce,
+//               and LINE 1 is always that line:
+//                 D11-OK <nonce> <sha256> <bytes> <n> [type:count,…]
+//                 <the scrubbed body>
+//               Stdout whose line 1 is not the framing is a body that was never
+//               scrubbed, and a body that would itself have carried a framing
+//               line is refused rather than emitted — so "the bytes after line 1"
+//               and "the bytes after the framing" can never name different bytes.
+//               No failure ever writes body bytes: a failure the mode
+//               owns is EXACTLY `D11-FAIL <reason>` and nothing else, and the two
+//               that precede or escape mode selection — a usage error and an
+//               internal error — leave stdout entirely EMPTY. The consumer gates
+//               on the presence of `D11-OK`, so all three are one case to it.
 //
 // Exit codes:
 //   0  success (zero or more redactions made)
-//   1  usage error (wrong number of arguments)
+//   1  usage error (wrong arity, or an unrecognised flag)
 //   2  input file unreadable or larger than 1 MiB
-//   3  output file write failed
+//   3  output file write failed — the FILE sink only; `--emit` writes no file
 //   4  internal / unexpected error
+//   5  --emit only: a gate refused — the second scrub pass was non-zero, the
+//      scrubbed body carried a framing line of its own, or a nonce could not be
+//      generated. Distinct from 4 so a caller can tell "the body must not be
+//      posted" from "the script broke": the first is final, the second is retried.
 //
 // Design constraints (binding):
-//   PF-011  writes via temp-sibling + rename (atomic same-fs write; readers see
-//           old-or-new, never a momentarily absent file)
+//   PF-011  the file sink — the one file this script writes — goes via
+//           temp-sibling + rename (atomic same-fs write; readers see old-or-new,
+//           never a momentarily absent file). `--emit` prints to stdout and
+//           touches no file, so it has nothing to protect
 //   PF-014  never call process.exit() inside any scope with pending cleanup or
 //           buffered output; main() returns an exit code; the single top-level
 //           boundary writes stdout SYNCHRONOUSLY then sets process.exitCode so
@@ -30,6 +57,9 @@
 'use strict';
 
 const fs = require('fs');
+// Genuinely new: no hashing or randomness helper exists anywhere else
+// under src/assets/scripts. frameEmit is the ONLY consumer.
+const crypto = require('crypto');
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -38,6 +68,83 @@ const fs = require('fs');
 /** Maximum allowed input size in bytes (1 MiB). */
 const MAX_INPUT_BYTES = 1048576;
 
+/**
+ * Nonce width, in hex characters (16 random bytes).
+ *
+ * The nonce is per-invocation and REQUIRED (§14.9-3), and it is the SECOND of two
+ * independent controls over the same forgery. `FRAMING_IN_BODY_RE` below is the
+ * first: no emitted body can hold a framing line at all. The nonce is what a
+ * consumer still has if it reads the framing from somewhere other than line 1 —
+ * a fixed `D11-OK` literal would be reproducible by anyone who can write an issue
+ * comment, and an unpredictable one is not.
+ *
+ * Exported so the framing grammar's guard pins its width from here rather than
+ * from a retyped number.
+ */
+const NONCE_HEX_CHARS = 32;
+
+/**
+ * A BODY line that would read as framing.
+ *
+ * The framing's one job is to say where the scrubbed bytes begin, and it can only
+ * do that if line 1 is the only line shaped like it. Composed bodies carry
+ * untrusted issue and comment text, so a body is one comment away from holding a
+ * `D11-OK`-shaped line of its own — and a consumer that looked for "a D11-OK
+ * line" instead of "line 1" would take the planted one, post the attacker's half
+ * under a devflow-authored marker, and suppress the real summary along with its
+ * SECRET-EXPOSED rotation warning.
+ *
+ * Refusing such a body here is what makes the line-1 rule MECHANICAL: the prose
+ * rule then describes a property of every body this script can emit, instead of
+ * an obligation nine documents have to restate correctly.
+ *
+ * PF-018: bounded — a fixed alternation over two literals, anchored per line by
+ * the `m` flag, with no quantifier to backtrack through. The trailing space is
+ * load-bearing: it is what keeps prose such as `D11-FAILURE` out of the refusal.
+ */
+const FRAMING_IN_BODY_RE = /^D11-(OK|FAIL) /m;
+
+/** The `SCRUB: ` prefix — one spelling, shared by formatScrubLine and frameEmit. */
+const SCRUB_LINE_PREFIX = 'SCRUB: ';
+
+/** The exact text a clean pass produces. The second pass returning THIS is the gate. */
+const ZERO_SCRUB_LINE = SCRUB_LINE_PREFIX + '0 []';
+
+/**
+ * Every reason that may follow `D11-FAIL `.
+ *
+ * Bare lowercase tokens, never prose and never a path: stdout is read back by an
+ * agent and pasted into reports, so a reason carrying a tmpdir path or input
+ * bytes would travel with it. The human-readable diagnosis goes to stderr, which
+ * no recipe forwards.
+ *
+ * A closed registry rather than inline strings, for the reason
+ * compliance-compose.ts states about its token tables: a guard asserts the shape
+ * of every entry, and an entry added inline would not be covered by it.
+ */
+const D11_FAIL_REASONS = Object.freeze({
+  INPUT_UNREADABLE: 'input-unreadable',
+  INPUT_TOO_LARGE: 'input-too-large',
+  SECOND_PASS_NONZERO: 'second-pass-nonzero',
+  BODY_CONTAINS_FRAMING: 'body-contains-framing',
+  NONCE_UNAVAILABLE: 'nonce-unavailable',
+});
+
+// EVERY reason here is emitted by an arm of the emit mode, and a test drives the
+// arms and compares what they produce against this registry. Two tokens a reader
+// might expect are deliberately absent:
+//
+//   internal-error     the top-level catch fires BEFORE the boundary has written
+//                      anything and knows no mode, so it leaves stdout empty
+//                      rather than framing a reason.
+//   output-unwritable  the emit mode's sink is stdout and it writes no file, so
+//                      no write of its own can fail. Exit 3 belongs to the file
+//                      mode, which returns a bare code and frames nothing.
+//
+// A token with no arm that can emit it is a value in a closed vocabulary that a
+// consumer can never see, and it reads as a live refusal to anyone auditing the
+// set.
+
 // ---------------------------------------------------------------------------
 // Shannon entropy
 // Bounded by string length; O(n) time, O(distinct-chars) space.
@@ -69,23 +176,47 @@ function shannonEntropy(s) {
 // Applied before every replacement to guard against false positives.
 // ---------------------------------------------------------------------------
 
+/**
+ * A marker this script's own passes write. The slug vocabulary is lowercase and
+ * hyphenated, so the class is bounded and the pattern cannot span two markers.
+ */
+const REDACTION_MARKER_RE = /\[REDACTED:[a-z][a-z-]{1,38}\]/g;
+
 /**
  * @param {string} candidate  The matched text (or value portion) to test.
  * @returns {boolean}
  */
 function shouldSkip(candidate) {
-  // Idempotency guard: already-redacted markers are never re-matched
-  if (candidate.includes('[REDACTED:')) return true;
+  // Idempotency guard, marker-STRIPPED rather than contains-based (GAP-54).
+  //
+  // A value this script already produced is markers and whitespace and nothing
+  // else, so removing them leaves nothing and the value is skipped — which is
+  // what keeps the second pass at zero and the `--emit` gate open. Bytes that
+  // SURVIVE the strip are not this script's output: `[REDACTED:` is a literal
+  // anyone can type into an issue comment, and a contains-check let one disarm
+  // rule 8 — the only generic `key = value` rule — for the whole line. An
+  // anchored check cannot serve here either: a value holding two markers would
+  // fail it, the second pass could never return zero, and the gate would refuse
+  // every body.
+  if (candidate.replace(REDACTION_MARKER_RE, '').trim() === '') return true;
 
   // Environment variable references (value is not the secret itself)
   if (candidate.includes('process.env.')) return true;
   if (candidate.includes('os.environ')) return true;
 
-  // Template / shell variable references (bounded alternation, no ReDoS risk)
-  if (/\$\{[^}]{0,300}\}/.test(candidate)) return true;   // ${VAR}
-  if (/\$[A-Za-z_][A-Za-z0-9_]*/.test(candidate)) return true; // $VAR
-  if (/\{\{[^}]{0,300}\}\}/.test(candidate)) return true; // {{ template }}
-  if (/<[^>]{0,300}>/.test(candidate)) return true;        // <placeholder>
+  // Template / shell variable references (bounded alternation, no ReDoS risk).
+  //
+  // ANCHORED, both ends (GAP-54). These four skips exist to keep AUTHOR fixtures
+  // readable — `api_key = "${DEPLOY_KEY}"` is documentation, not a credential. A
+  // value that merely CONTAINS a placeholder is a different thing: `api_key =
+  // "<ref> a8Kd91jZx0Qw7Lp2Vn"` would disarm rule 8 — the only generic
+  // `key = value` rule — and provider-rendered bodies and remote issue text are
+  // exactly what flows into a composed comment sink. So the skip fires only when
+  // the value IS the placeholder and nothing else.
+  if (/^\$\{[^}]{0,300}\}$/.test(candidate)) return true;      // ${VAR}
+  if (/^\$[A-Za-z_][A-Za-z0-9_]*$/.test(candidate)) return true; // $VAR
+  if (/^\{\{[^}]{0,300}\}\}$/.test(candidate)) return true;    // {{ template }}
+  if (/^<[^>]{0,300}>$/.test(candidate)) return true;          // <placeholder>
 
   // Keyword / low-entropy values that are never real secrets
   if (/^(null|undefined|true|false|none|changeme|example)$/i.test(candidate)) return true;
@@ -301,7 +432,159 @@ function formatScrubLine(counts) {
   const entries = Object.entries(counts);
   const total = entries.reduce((sum, [, n]) => sum + n, 0);
   const parts = entries.map(([slug, n]) => slug + ':' + n);
-  return 'SCRUB: ' + total + ' [' + parts.join(',') + ']';
+  return SCRUB_LINE_PREFIX + total + ' [' + parts.join(',') + ']';
+}
+
+// ---------------------------------------------------------------------------
+// [DR-14] Three pure helpers, and main() is a dispatcher over them
+//
+// Without this split main() would parse arguments, run two scrub passes,
+// generate randomness, hash, manage a temp-file lifecycle, select between two
+// output framings and choose among four exit codes — nine responsibilities in
+// the D11 sink for every provider, with the only structural mitigation being
+// boundary-scoped. Each helper below is also the ONLY way to reach one arm:
+// parseArgs is observable without a subprocess, and the nonce-failure arm is
+// reachable through injection and through nothing else.
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{ kind: 'emit', inputPath: string }} EmitArgs
+ * @typedef {{ kind: 'file', inputPath: string, outputPath: string }} FileArgs
+ * @typedef {{ kind: 'usage', usage: string }} UsageError
+ */
+
+/**
+ * Parse argv into a mode and its positionals.
+ *
+ * THE FLAG IS READ BEFORE THE POSITIONALS ARE BOUND, so `--emit` can never bind
+ * as a FILENAME and die at statSync with exit 2 — reporting "your input is
+ * missing" for what is actually an unsupported flag.
+ *
+ * `kind` is the DISCRIMINANT, and main() dispatches on it alone. The three
+ * shapes also differ in which fields they carry, but reading the mode off field
+ * presence makes a renamed field — or a fourth shape — resolve to an existing
+ * arm instead of failing, and the arms differ in whether the scrubbed body
+ * reaches stdout.
+ *
+ * Arity is exact in both modes. A third positional is a usage error rather than
+ * an ignored argument: `--emit in out` is a caller who believes they are writing
+ * a file, and silently printing the body to stdout instead would put a scrubbed
+ * comment body into a terminal log they never read.
+ *
+ * @param {string[]} argv  process.argv
+ * @returns {EmitArgs | FileArgs | UsageError}
+ */
+function parseArgs(argv) {
+  const FILE_USAGE = 'Usage: node redact-secrets.cjs <input-file> <output-file>';
+  const EMIT_USAGE = 'Usage: node redact-secrets.cjs --emit <input-file>';
+
+  let emit = false;
+  /** @type {string[]} */
+  const positionals = [];
+  for (const arg of argv.slice(2)) {
+    if (arg === '--emit') {
+      emit = true;
+      continue;
+    }
+    if (arg.startsWith('-')) {
+      return {
+        kind: 'usage',
+        usage: 'redact-secrets: unrecognised flag ' + arg + '\n' + FILE_USAGE + '\n' + EMIT_USAGE,
+      };
+    }
+    positionals.push(arg);
+  }
+
+  if (emit) {
+    if (positionals.length !== 1) return { kind: 'usage', usage: EMIT_USAGE };
+    return { kind: 'emit', inputPath: positionals[0] };
+  }
+  if (positionals.length !== 2) return { kind: 'usage', usage: FILE_USAGE };
+  return { kind: 'file', inputPath: positionals[0], outputPath: positionals[1] };
+}
+
+/**
+ * Scrub, then scrub the RESULT again.
+ *
+ * The second pass is the gate: it re-scrubs what the first pass produced, so a
+ * zero second count is evidence that the first pass left nothing behind. Passing
+ * the ORIGINAL content twice would find the same secrets again and the gate would
+ * never open — the one wiring mistake that turns the whole mode off, which is why
+ * a test pins which content the second call receives.
+ *
+ * Nearly free: idempotency is already pinned by shouldSkip's marker-stripped
+ * skip, which passes over a value that is this script's own output.
+ *
+ * @param {string} content
+ * @param {(c: string) => ScrubResult} [scrubFn]  Injectable so the refusal arm is
+ *   provable without a pathological fixture — the real rules ARE idempotent, so
+ *   no input reaches a non-zero second pass.
+ * @returns {{ text: string, first: Record<string, number>, second: Record<string, number> }}
+ */
+function scrubTwice(content, scrubFn) {
+  const doScrub = scrubFn || scrub;
+  const first = doScrub(content);
+  const second = doScrub(first.result);
+  return { text: first.result, first: first.counts, second: second.counts };
+}
+
+/** Default nonce source: 16 CSPRNG bytes as lowercase hex. */
+function defaultNonceSource() {
+  return crypto.randomBytes(NONCE_HEX_CHARS / 2).toString('hex');
+}
+
+/**
+ * Build the `D11-OK` framing line for a scrubbed body.
+ *
+ * The line carries four facts, and each answers a specific way the channel can
+ * fail between this process's stdout and the tool call that posts the body:
+ *   <nonce>   per-invocation, so the line cannot be forged from inside the body;
+ *   <sha256>  identifies these exact bytes;
+ *   <bytes>   [DR-06] the UTF-8 byte length, so a consumer can detect a
+ *             harness-TRUNCATED result. Truncation keeps line 1 intact, so a bare
+ *             "no framing line ⇒ do not post" gate passes while the body is
+ *             partial — a guard that appears to work while failing;
+ *   <n> […]   [DR-01] the FIRST pass's count and per-type payload. The second
+ *             pass is always zero by construction, so without this the only
+ *             signal that a real credential was present is computed and discarded,
+ *             and the user is never told to rotate it.
+ *
+ * formatScrubLine stays the sole producer of the `N [type:count,…]` text; this
+ * embeds it by stripping the shared prefix rather than re-deriving the format.
+ *
+ * @param {string} scrubbed  The scrubbed body.
+ * @param {string} scrubLine The FIRST pass's formatScrubLine output.
+ * @param {() => unknown} [nonceSource]  `unknown` is the contract this function
+ *   implements: it type-checks what the source returns and refuses anything that
+ *   is not 32 hex characters, so declaring `() => string` would describe a
+ *   narrower contract than the code and force every malformed-nonce fixture to
+ *   cast past the check it exists to prove.
+ * @returns {{ emitLine: string, body: string } | { error: string }}
+ */
+function frameEmit(scrubbed, scrubLine, nonceSource) {
+  const source = nonceSource || defaultNonceSource;
+  let nonce;
+  try {
+    nonce = source();
+  } catch (/** @type {any} */ err) {
+    return { error: 'nonce generation failed: ' + (err.code || err.message) };
+  }
+  if (typeof nonce !== 'string' || !new RegExp('^[0-9a-f]{' + NONCE_HEX_CHARS + '}$').test(nonce)) {
+    // A short, empty or non-hex nonce is unforgeable-by-accident only; treating it
+    // as usable would ship a framing line whose one security property is absent.
+    return { error: 'nonce generation failed: malformed nonce' };
+  }
+
+  const sha256 = crypto.createHash('sha256').update(scrubbed, 'utf8').digest('hex');
+  const bytes = Buffer.byteLength(scrubbed, 'utf8');
+  const payload = scrubLine.startsWith(SCRUB_LINE_PREFIX)
+    ? scrubLine.slice(SCRUB_LINE_PREFIX.length)
+    : scrubLine;
+
+  return {
+    emitLine: 'D11-OK ' + nonce + ' ' + sha256 + ' ' + bytes + ' ' + payload,
+    body: scrubbed,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -315,61 +598,74 @@ function formatScrubLine(counts) {
 // ---------------------------------------------------------------------------
 
 /**
- * @param {string[]} argv  process.argv
- * @returns {number | { scrubLine: string }}
+ * Read the input, enforcing the size bound.
+ *
+ * Shared by both modes so the two cannot drift on what "unreadable" means. The
+ * `message` is exactly the stderr text the file mode has always written — the
+ * mode-specific part is only which stdout framing (if any) accompanies it.
+ *
+ * @param {string} inputPath
+ * @returns {{ ok: true, content: string } | { ok: false, code: number, reason: string, message: string }}
  */
-function main(argv) {
-  const inputPath = argv[2];
-  const outputPath = argv[3];
-
-  if (!inputPath || !outputPath) {
-    process.stderr.write('Usage: node redact-secrets.cjs <input-file> <output-file>\n');
-    return 1;
-  }
-
-  // ---- stat input ----
+function readInput(inputPath) {
   let stat;
   try {
     stat = fs.statSync(inputPath);
   } catch (/** @type {any} */ err) {
-    process.stderr.write(
-      'redact-secrets: cannot stat input: ' + inputPath + ': ' + (err.code || err.message) + '\n',
-    );
-    return 2;
+    return {
+      ok: false,
+      code: 2,
+      reason: D11_FAIL_REASONS.INPUT_UNREADABLE,
+      message: 'redact-secrets: cannot stat input: ' + inputPath + ': ' + (err.code || err.message) + '\n',
+    };
   }
 
   if (stat.size > MAX_INPUT_BYTES) {
-    process.stderr.write(
-      'redact-secrets: input exceeds 1 MiB: ' + inputPath + '\n',
-    );
-    return 2;
+    return {
+      ok: false,
+      code: 2,
+      reason: D11_FAIL_REASONS.INPUT_TOO_LARGE,
+      message: 'redact-secrets: input exceeds 1 MiB: ' + inputPath + '\n',
+    };
   }
 
-  // ---- read input ----
-  let rawBuffer;
   try {
-    rawBuffer = fs.readFileSync(inputPath);
+    return { ok: true, content: fs.readFileSync(inputPath).toString('utf8') };
   } catch (/** @type {any} */ err) {
-    process.stderr.write(
-      'redact-secrets: cannot read input: ' + inputPath + ': ' + (err.code || err.message) + '\n',
-    );
-    return 2;
+    return {
+      ok: false,
+      code: 2,
+      reason: D11_FAIL_REASONS.INPUT_UNREADABLE,
+      message: 'redact-secrets: cannot read input: ' + inputPath + ': ' + (err.code || err.message) + '\n',
+    };
   }
+}
 
-  // ---- scrub ----
-  const content = rawBuffer.toString('utf8');
+/**
+ * The FILE-sink mode — byte-for-byte the behaviour that shipped before `--emit`.
+ *
+ * Deliberately calls `scrub` ONCE, not scrubTwice: the recipes, the Tracker
+ * agent's write chain and every `gh` call depend on this path's exact stdout and
+ * exit codes, and a second pass here would add a failure mode to a contract
+ * nothing asked to change.
+ *
+ * @param {FileArgs} args
+ * @param {string} content
+ * @returns {number | { scrubLine: string }}
+ */
+function runFileMode(args, content) {
   const { result, counts } = scrub(content);
 
   // ---- atomic write (PF-011: temp-sibling + rename) ----
-  const tmpPath = outputPath + '.tmp';
+  const tmpPath = args.outputPath + '.tmp';
   try {
     fs.writeFileSync(tmpPath, result, 'utf8');
-    fs.renameSync(tmpPath, outputPath);
+    fs.renameSync(tmpPath, args.outputPath);
   } catch (/** @type {any} */ err) {
     // Best-effort cleanup of the temp file; ignore errors (the temp may not exist)
     try { fs.unlinkSync(tmpPath); } catch (_) { /* intentionally ignored */ }
     process.stderr.write(
-      'redact-secrets: cannot write output: ' + outputPath + ': ' + (err.code || err.message) + '\n',
+      'redact-secrets: cannot write output: ' + args.outputPath + ': ' + (err.code || err.message) + '\n',
     );
     return 3;
   }
@@ -377,34 +673,166 @@ function main(argv) {
   return { scrubLine: formatScrubLine(counts) };
 }
 
+/**
+ * The TOOL-CALL-sink mode.
+ *
+ * Always returns an `{ emitLine, body, code }` triple, and `body` is `''` on
+ * every non-zero code. That is what makes "no body on any non-zero exit" a
+ * property of the type rather than a rule each arm has to remember: the boundary
+ * writes `emitLine + '\n' + body` unconditionally, so a failing arm cannot emit a
+ * body even by forgetting to suppress one.
+ *
+ * THIS MODE TOUCHES NO FILE. It holds the bytes it returns and the boundary
+ * prints them, so there is nothing for a write discipline to protect: a scrubbed
+ * comment body put on disk is a second copy with the input directory's lifetime,
+ * and proving that directory writable would let a filesystem property refuse a
+ * clean, fully gated body. The file mode's temp-sibling + rename (PF-011) guards
+ * the one file this script does write.
+ *
+ * @param {string} content
+ * @param {{ scrubFn?: (c: string) => ScrubResult, nonceSource?: () => unknown }} deps
+ * @returns {{ emitLine: string, body: string, code: number }}
+ */
+function runEmitMode(content, deps) {
+  const { text, first, second } = scrubTwice(content, deps.scrubFn);
+
+  // THE GATE. A non-zero second pass means the first pass did not hold, so the
+  // body is not publishable and no amount of re-running changes that.
+  const secondLine = formatScrubLine(second);
+  if (secondLine !== ZERO_SCRUB_LINE) {
+    process.stderr.write(
+      'redact-secrets: second scrub pass was non-zero (' + secondLine + ') — refusing to emit\n',
+    );
+    return { emitLine: 'D11-FAIL ' + D11_FAIL_REASONS.SECOND_PASS_NONZERO, body: '', code: 5 };
+  }
+
+  // THE FRAMING GATE. A body that carries a framing line of its own lets its
+  // author decide where a consumer thinks the body begins. Refusing is fail-closed
+  // in the direction the sink needs: the item degrades and nothing is posted.
+  if (FRAMING_IN_BODY_RE.test(text)) {
+    process.stderr.write(
+      'redact-secrets: the scrubbed body carries a D11 framing line — refusing to emit\n',
+    );
+    return { emitLine: 'D11-FAIL ' + D11_FAIL_REASONS.BODY_CONTAINS_FRAMING, body: '', code: 5 };
+  }
+
+  const framed = frameEmit(text, formatScrubLine(first), deps.nonceSource);
+  if (framed.error !== undefined) {
+    process.stderr.write('redact-secrets: ' + framed.error + ' — refusing to emit\n');
+    return { emitLine: 'D11-FAIL ' + D11_FAIL_REASONS.NONCE_UNAVAILABLE, body: '', code: 5 };
+  }
+
+  return { emitLine: framed.emitLine, body: framed.body, code: 0 };
+}
+
+/**
+ * @param {string[]} argv  process.argv
+ * @param {{ scrubFn?: (c: string) => ScrubResult, nonceSource?: () => unknown }} [deps]
+ *   Injected only by tests, and only to reach the two arms no fixture can: a
+ *   non-idempotent scrub and an unavailable nonce. Defaulted here rather than at
+ *   each use site so production has exactly one set of dependencies.
+ * @returns {number | { scrubLine: string } | { emitLine: string, body: string, code: number }}
+ */
+function main(argv, deps) {
+  const args = parseArgs(argv);
+  if (args.kind === 'usage') {
+    // The one failure that precedes mode selection, so no framing line can
+    // describe it: stdout stays entirely empty and stderr carries the usage.
+    process.stderr.write(args.usage + '\n');
+    return 1;
+  }
+
+  const read = readInput(args.inputPath);
+  if (!read.ok) {
+    process.stderr.write(read.message);
+    // Each mode owns the SHAPE of its refusal: the tool-call sink frames every
+    // failure it can name, the file sink returns a bare code.
+    return args.kind === 'emit'
+      ? { emitLine: 'D11-FAIL ' + read.reason, body: '', code: read.code }
+      : read.code;
+  }
+
+  return args.kind === 'emit'
+    ? runEmitMode(read.content, deps || {})
+    : runFileMode(args, read.content);
+}
+
 // ---------------------------------------------------------------------------
 // Top-level boundary
 //
 // This is the ONLY place that writes to stdout and sets process.exitCode.
 // No other code path may call process.exit() or write to stdout.
 // (PF-014: single synchronous write, no pending cleanup, no buffered output)
+//
+// AMENDED for --emit, not bypassed. main()'s return widened from
+// `number | {scrubLine}` to also carry `{emitLine, body, code}`, and the write
+// became a TWO-BRANCH synchronous write — one branch per output shape. There are
+// still exactly two process.stdout.write sites in this file, and a guard asserts
+// that count: a third site is precisely how a body would reach stdout without
+// passing the gate.
+//
+// The emit branch writes `emitLine + '\n' + body` UNCONDITIONALLY, because a
+// failing emit result carries `body: ''` by construction. Suppressing the body
+// here instead would put the "no body on failure" property in this block, where
+// a future arm could forget it; putting it in the result keeps it a property of
+// every arm that can produce one.
+//
+// Guarded by `require.main === module` so the pure helpers above are importable
+// by their unit tests. Nothing else changes: `node redact-secrets.cjs …` still
+// enters here, and the block is still the only exit-code and stdout authority.
 // ---------------------------------------------------------------------------
 
-let exitCode = 0;
-let scrubLine = /** @type {string | null} */ (null);
+if (require.main === module) {
+  let exitCode = 0;
+  let scrubLine = /** @type {string | null} */ (null);
+  let emitted = /** @type {{ emitLine: string, body: string, code: number } | null} */ (null);
+
+  try {
+    const mainResult = main(process.argv);
+    if (typeof mainResult === 'number') {
+      exitCode = mainResult;
+    } else if (mainResult.emitLine !== undefined) {
+      emitted = /** @type {any} */ (mainResult);
+      exitCode = emitted.code;
+    } else {
+      scrubLine = /** @type {any} */ (mainResult).scrubLine;
+      exitCode = 0;
+    }
+  } catch (/** @type {any} */ err) {
+    process.stderr.write('redact-secrets: internal error: ' + err.message + '\n');
+    exitCode = 4;
+  }
 
-try {
-  const mainResult = main(process.argv);
-  if (typeof mainResult === 'number') {
-    exitCode = mainResult;
-  } else {
-    scrubLine = mainResult.scrubLine;
-    exitCode = 0;
+  // Synchronous stdout writes (must complete before process exits) — one per
+  // output shape, and no third site anywhere in this file.
+  if (emitted !== null) {
+    process.stdout.write(emitted.emitLine + '\n' + emitted.body);
+  } else if (scrubLine !== null) {
+    process.stdout.write(scrubLine + '\n');
   }
-} catch (/** @type {any} */ err) {
-  process.stderr.write('redact-secrets: internal error: ' + err.message + '\n');
-  exitCode = 4;
-}
 
-// Synchronous stdout write (must complete before process exits)
-if (scrubLine !== null) {
-  process.stdout.write(scrubLine + '\n');
+  // Set exitCode (preferred over process.exit() — does not bypass event loop cleanup)
+  process.exitCode = exitCode;
 }
 
-// Set exitCode (preferred over process.exit() — does not bypass event loop cleanup)
-process.exitCode = exitCode;
+// ---------------------------------------------------------------------------
+// Exports — for the unit tests of the pure helpers only [DR-14]
+//
+// parseArgs' behaviour is otherwise observable only end-to-end, and the
+// nonce-failure arm is not observable at all: no argv and no fixture can make
+// crypto.randomBytes fail. Exporting the helpers is what makes those two arms
+// assertable instead of argued-from-construction.
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  NONCE_HEX_CHARS,
+  ZERO_SCRUB_LINE,
+  D11_FAIL_REASONS: Object.freeze(Object.values(D11_FAIL_REASONS)),
+  shouldSkip,
+  scrub,
+  formatScrubLine,
+  parseArgs,
+  scrubTwice,
+  frameEmit,
+  main,
+};