@raishin/vanguard-frontier-agentic 3.15.0 → 3.17.0

package/mods/README.md

@@ -0,0 +1,220 @@
+# Vanguard Mods
+
+<div align="center">
+
+  <img src="../assets/logos/vanguard-frontier-agentic-logo.png" alt="Vanguard Frontier Agentic" width="140" />
+
+  <p><strong>Less “oops.” More visibility.</strong></p>
+  <p>Tool-call guardrails and observers for Claude Code, Kiro and Codex.</p>
+
+  <p>
+    <a href="#pick-a-mod">Pick a mod</a> &nbsp;·&nbsp;
+    <a href="#get-started">Get started</a> &nbsp;·&nbsp;
+    <a href="#know-the-limits">Know the limits</a> &nbsp;·&nbsp;
+    <a href="#under-the-hood">Under the hood</a>
+  </p>
+
+</div>
+
+---
+
+Skills guide the agent. **Mods inspect its tool calls.** Ask before risky actions,
+redact supported output, or record what happened. Pick what you need—not everything at once.
+
+<a id="pick-a-mod"></a>
+
+## 🧰 Pick your guardrails
+
+| Mod | The job | Reach |
+| --- | --- | --- |
+| [Secret Redactor](secret-redactor/README.md) | Spot credential-shaped input; redact supported output. | L0 |
+| [Blast Radius Guard](blast-radius-guard/README.md) | Ask or deny on destructive commands and system-path writes. | L0 |
+| [Live Guard Gate](live-guard-gate/README.md) | Flag cloud mutations and name guard agents to consult. | L0 |
+| [Context Burn](context-burn/README.md) | Count tool calls; warn on reported context use where supported. | L1 |
+| [Audit Trail](audit-trail/README.md) | Append call hashes and per-session sequence numbers. | L1 |
+
+**Reach is a label, not a sandbox:** L0 = no declared writes/spawns/network;
+L1 = file writes; L2 = subprocesses; L3 = network (warned, not blocked).
+Reads are allowed at L0; starting the Node adapter is not a mod-spawned subprocess.
+
+**Support differs:** Kiro/Codex deny instead of asking and cannot redact output.
+Claude Code Audit Trail needs classic. Classic Post hooks miss failed calls.
+
+<details>
+<summary><strong>🔎 Same mod, different harness? Check the fine print.</strong></summary>
+
+| Mod | Claude Code native | Claude Code classic | Kiro / Codex |
+| --- | --- | --- | --- |
+| Secret Redactor | Ask on input; redact or withhold output | Ask on input; replace successful output only | Deny matching input; no output redaction |
+| Blast Radius Guard | Ask in confirm mode; deny in block mode | Same | Deny in either mode |
+| Live Guard Gate | Ask and name guard agents | Same | Deny and name guard agents |
+| Context Burn | Session context usage and threshold toasts | Tool-call counter only | Tool-call counter only |
+| Audit Trail | Unsupported—use classic | Append after successful calls | Append; Kiro payload interpretation is degraded |
+
+Guards use `PreToolUse`; supported redaction and observers use `PostToolUse`;
+Context Burn also uses `SessionStart`.
+Native equivalents are `tool.check`, `tool.call` and `session.start`.
+
+Kiro's stdin fields are undocumented: guards scan the whole payload if input is
+unrecognized; Audit Trail hashes that payload as arguments and `null` as the result.
+Set `VANGUARD_AUDIT_TRAIL_SESSION_ID` to avoid its shared `unsessioned` fallback.
+See generated `<harness>/UNSUPPORTED.md` for remaining limits.
+
+</details>
+
+---
+
+<a id="get-started"></a>
+
+## 🚀 Get started
+
+Use a local checkout. Command adapters need **Node 22+**; native modules use the
+harness runtime. No service needed.
+
+```bash
+source=/absolute/path/to/vanguard-frontier-agentic
+target=/absolute/path/to/your/project
+mod=blast-radius-guard
+```
+
+> [!IMPORTANT]
+> **Native or classic. Not both for the same mod.** They duplicate checks and can
+> double-count Context Burn. Audit Trail has no native adapter—use classic.
+
+<details>
+<summary><strong>🤖 Claude Code native</strong> — load a plugin root</summary>
+
+```bash
+cd "$target"
+claude --plugin-dir "$source/mods/$mod"
+```
+
+Not for `audit-trail`. Native API: early access. Check the verified build in the
+[implementation notes](#under-the-hood) before upgrading.
+
+</details>
+
+<details>
+<summary><strong>🤖 Claude Code classic</strong> — copy, then merge hooks</summary>
+
+```bash
+mkdir -p "$target/.claude/vanguard-mods/$mod"
+cp -R "$source/mods/$mod/bin" "$source/mods/$mod/lib" "$target/.claude/vanguard-mods/$mod/"
+```
+
+Append `mods/<id>/claude-code/settings.hooks.json` entries under `hooks` in the
+target's `.claude/settings.json`. **Keep existing hooks/settings.** Generated command:
+
+```text
+node "$CLAUDE_PROJECT_DIR/.claude/vanguard-mods/<id>/bin/hook.mjs" --harness claude-code --event <event>
+```
+
+`CLAUDE_PROJECT_DIR` stays at the initial project root, even across worktree changes.
+Observers resolve relative writes from the installed adapter location.
+
+</details>
+
+<details>
+<summary><strong>🔮 Kiro</strong> — copy the adapters and hook JSON</summary>
+
+```bash
+mkdir -p "$target/.kiro/hooks" "$target/.kiro/vanguard-mods/$mod"
+cp -R "$source/mods/$mod/bin" "$source/mods/$mod/lib" "$target/.kiro/vanguard-mods/$mod/"
+cp "$source/mods/$mod/kiro/"*-hook.json "$target/.kiro/hooks/"
+```
+
+Copy only `*-hook.json`, not `UNSUPPORTED.md`. Replace the relative script path
+inside each hook with its **absolute installed path**: hook cwd is undocumented.
+Commands use `--harness kiro --event <event>`; confirmation requests deny with exit 2.
+
+</details>
+
+<details>
+<summary><strong>⚡ Codex</strong> — copy, merge, then review trust</summary>
+
+```bash
+mkdir -p "$target/.codex/vanguard-mods/$mod"
+cp -R "$source/mods/$mod/bin" "$source/mods/$mod/lib" "$target/.codex/vanguard-mods/$mod/"
+```
+
+Append event entries from `mods/<id>/codex/hooks.json` to the target's
+`.codex/hooks.json`, preserving existing hooks. Replace relative script paths with
+**absolute installed paths**; hook cwd is undocumented. Complete Codex's hook trust review.
+
+Commands use `--harness codex --event <event>`; asks deny with exit 2.
+Redactor Post is unsupported; the narrower MCP output field is not substituted.
+
+</details>
+
+**Try it before trusting it:** run ordinary and harmless pattern-matching calls in
+the harness. Inspect the decision, output or observer file—not just exit codes.
+Repeat after path, permission, Node or harness changes.
+
+---
+
+<a id="know-the-limits"></a>
+
+## ⚠️ Guardrails, not guarantees
+
+- **A hook must run to help.** Guards deny handler/input errors; missing Node,
+  moved scripts, startup crashes and timeouts can leave calls unguarded.
+  CLI errors may not block; Kiro IDE handling differs.
+- **Regex is not complete DLP.** Pre checks never rewrite arguments; approved input
+  still reaches the tool. Post redaction does not scrub other logs or network traffic.
+  Redactor errors attempt withholding; classic shape mismatches may be ignored.
+  [Withholding has limits, too](secret-redactor/README.md#limitations).
+- **A review prompt is not authorization.** Live Guard Gate names agents—it never
+  spawns them or verifies production accounts. Guards scan strings, not shell semantics;
+  relative paths stay unresolved. Bypass modes can auto-approve an ask.
+- **Observers are not compliance proof.** Node counters track calls, not tokens or
+  spend; only native Context Burn uses reported context data. Unlocked updates can
+  lose increments. Audit logs are mutable, unsigned and not tamper-evident.
+  Observer failures do not block tools.
+
+<details>
+<summary><strong>🗂️ State files and custom patterns</strong></summary>
+
+- **Context Burn:** `.<harness>/context-burn-status/<session-hash>.json`
+  (`.claude` for Claude Code). Filenames use the full lowercase SHA-256 of the UTF-8
+  session ID, never raw IDs. Missing/empty Node IDs share `unsessioned` state.
+  `VANGUARD_CONTEXT_BURN_STATUS_PATH` is an exact override; sharing it opts out of
+  isolation. Old single-file state is not migrated automatically.
+- **Audit Trail:** `.audit/<UTC-date>/<session>.jsonl`; an earlier file is reused
+  across dates. `VANGUARD_AUDIT_TRAIL_LOG_DIR` overrides the directory.
+- **Footprints disclose defaults, not containment.** Overrides can write outside
+  declared globs; overlap checks do not constrain operator overrides.
+- **Patterns append, never replace.** `VANGUARD_SECRET_REDACTOR_PATTERNS` and
+  `VANGUARD_BLAST_RADIUS_GUARD_PATTERNS` accept extra pattern files. Use absolute paths.
+  Unreadable/invalid configured files deny guards or withhold redactor output.
+  Each mod README documents schemas and environment names.
+
+</details>
+
+<a id="under-the-hood"></a>
+
+## 🔧 Under the hood
+
+`mod.toml` declares support and footprint; `lib/core.mjs` holds shared behavior.
+Edit those sources, `patterns.json`, entries and native modules—not generated adapters.
+The generator produces manifests, shared runtime copies, pattern modules and `catalog/mods.json`.
+
+<details>
+<summary><strong>🛠️ Contributing? Run the gates.</strong></summary>
+
+```bash
+npm run mods:write
+npm run validate:mods
+npm run test:fuzz
+npm run asset-integrity:write  # last generator, on its own
+npm run validate
+```
+
+The Python gate needs **Python 3.11+**. For each supported native mod, also run
+`claude plugin validate mods/<id>` and `claude plugin test mods/<id>` locally;
+CI has no native CLI. Spelling and Markdown lint are separate gates.
+Static checks are not proof that an installed hook runs.
+
+</details>
+
+[Implementation plan](https://github.com/VincentChuWaiChow/vanguard-frontier-agentic/blob/dc8b29c823fb89dc4246413f38a7b82fdd34aa18/.claude/plan/cross-harness-mods.md)
+· [Spec deviations](https://github.com/VincentChuWaiChow/vanguard-frontier-agentic/blob/dc8b29c823fb89dc4246413f38a7b82fdd34aa18/.kiro/specs/cross-harness-mods/deviations.md)

package/mods/audit-trail/README.md

@@ -0,0 +1,70 @@
+# Audit Trail
+
+Appends one JSON line per tool call to a per-session log. It is an honest append log: it makes
+no claim of immutability, carries no signatures, and any process with write access can edit or
+delete the file.
+
+## Reach and declared footprint
+
+**L1 (file writes).** The manifest declares default writes to `.audit/**`, reads
+`VANGUARD_AUDIT_TRAIL_LOG_DIR`, `VANGUARD_AUDIT_TRAIL_SESSION_ID` and
+`VANGUARD_AUDIT_TRAIL_AGENT_ID`, and declares no subprocess spawns or network egress.
+This is capability disclosure, not isolation; the log-directory override can write
+outside the declared default footprint.
+
+## What it records
+
+| Field | Value |
+|---|---|
+| `timestamp` | UTC ISO 8601 time of the hook run |
+| `session_id` | The safe session id (see below) |
+| `agent_id` | `VANGUARD_AUDIT_TRAIL_AGENT_ID`, or `null` |
+| `tool_name` | The payload `tool_name`, or `null` |
+| `args_hash` | SHA-256 of the canonical JSON of `tool_input` (`null` when absent) |
+| `result_hash` | SHA-256 of the canonical JSON of `tool_response` (`null` when absent) |
+| `sequence_number` | 1, 2, 3 ... per session file |
+
+Only hashes are stored, never the arguments or results themselves.
+
+## File layout
+
+`<dir>/<YYYY-MM-DD>/<session>.jsonl`, where `<dir>` defaults to `.audit` and dates are UTC. If
+the session already has a file under an earlier date directory, that file is reused, so the
+sequence does not reset at midnight. A relative `<dir>` resolves against the project root when
+the hook runs from its installed location, otherwise against the working directory.
+
+## Session ids
+
+1. `VANGUARD_AUDIT_TRAIL_SESSION_ID`, when set and non-empty.
+2. The payload `session_id`, when a non-empty string.
+3. Otherwise `unsessioned`.
+
+An id that does not match `[A-Za-z0-9._-]{1,128}` is replaced by the first 32 hex characters of
+its SHA-256, so it can never escape the date directory.
+
+## Environment
+
+| Variable | Purpose |
+|---|---|
+| `VANGUARD_AUDIT_TRAIL_LOG_DIR` | Log directory (default `.audit`). It can point outside the declared `.audit/**` write footprint; that is the operator's choice. |
+| `VANGUARD_AUDIT_TRAIL_SESSION_ID` | Session id override |
+| `VANGUARD_AUDIT_TRAIL_AGENT_ID` | Value for `agent_id` |
+
+## Harness support
+
+| Harness | Status |
+|---|---|
+| Claude Code native | Unsupported: the native API has no file append. Install the classic hook instead. |
+| Claude Code classic | Supported. `PostToolUse` fires only after a tool succeeds, so failed calls are not logged. |
+| Kiro | Degraded: stdin field names are undocumented, so `args_hash` covers the whole payload, `result_hash` hashes `null`, and without a session id env var every session shares the `unsessioned` log. |
+| Codex | Supported. |
+
+## Locking and failure
+
+Each append takes an exclusive `<dir>/<session>.lock` before selecting the session file
+(retrying for up to 2 s). Locks are never automatically stolen or removed based on age.
+After a crash, confirm no writer remains before manually removing its orphaned lock.
+A corrupt or unterminated last line, a lock timeout, or any I/O error exits 1 with a message on stderr and
+appends nothing. A failure is loud but never blocks the tool call.
+
+Requires Node 22+. Install: see `mods/README.md`.

package/mods/audit-trail/bin/hook.mjs

@@ -0,0 +1,65 @@
+// Node hook for audit-trail: appends one JSON line per tool call to a per-session log.
+// An honest append log, not tamper-evident: anything with write access can edit it.
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { runHook, projectPath } from '../lib/runtime.mjs'
+import { buildRecord, lastSequence, rawSessionId, safeSessionId } from '../lib/core.mjs'
+
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+
+// Reuses the earliest date dir that already holds this session, so the sequence never
+// resets at midnight.
+// ponytail: scans every date dir, O(days); index it if slow.
+function logFile(base, sid, today) {
+  const days = existsSync(base) ? readdirSync(base).filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(d)).sort() : []
+  const hit = days.find((d) => existsSync(join(base, d, `${sid}.jsonl`)))
+  return join(base, hit ?? today, `${sid}.jsonl`)
+}
+
+// Never steal a lock: its age does not prove the owner is dead. Explicit recovery is safer
+// than racing two writers after an automatic stale-lock takeover.
+function acquire(lock, file) {
+  const deadline = Date.now() + 2000
+  for (;;) {
+    try {
+      return openSync(lock, 'wx')
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err
+    }
+    if (Date.now() > deadline) throw new Error(`audit-trail: could not lock ${file} within 2s`)
+    sleep(20)
+  }
+}
+
+// Read directly instead of exists-then-read, so there is no check/use gap.
+function readIfExists(file) {
+  try {
+    return readFileSync(file, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') return ''
+    throw err
+  }
+}
+
+async function PostToolUse(payload, ctx) {
+  const base = projectPath(process.env.VANGUARD_AUDIT_TRAIL_LOG_DIR || '.audit', ctx.harness, import.meta.dirname)
+  const sid = await safeSessionId(rawSessionId(process.env.VANGUARD_AUDIT_TRAIL_SESSION_ID, payload))
+  const timestamp = new Date().toISOString()
+  mkdirSync(base, { recursive: true })
+  // Serialize session-file selection as well as appends, including across midnight.
+  const lock = join(base, `${sid}.lock`)
+  const fd = acquire(lock, lock)
+  try {
+    const file = logFile(base, sid, timestamp.slice(0, 10))
+    mkdirSync(dirname(file), { recursive: true })
+    const sequence = lastSequence(readIfExists(file), file) + 1
+    const agentId = process.env.VANGUARD_AUDIT_TRAIL_AGENT_ID
+    const record = await buildRecord({ timestamp, sessionId: sid, agentId, payload, harness: ctx.harness, sequence })
+    appendFileSync(file, JSON.stringify(record) + '\n')
+  } finally {
+    closeSync(fd)
+    unlinkSync(lock)
+  }
+}
+
+process.exitCode = await runHook({ name: 'audit-trail', handlers: { PostToolUse } })

package/mods/audit-trail/claude-code/UNSUPPORTED.md

@@ -0,0 +1,11 @@
+# Audit Trail on Claude Code
+
+<!-- Generated by scripts/generate-mods.mjs from mod.toml. Do not edit. -->
+
+## Unsupported
+
+- `native`: The native mod API has no file append; rewriting the whole log would break append-only writes. Install the classic hook instead.
+
+## Degraded
+
+- `classic`: Classic PostToolUse fires only after a tool succeeds, so failed tool calls are not logged.

package/mods/audit-trail/claude-code/settings.hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/vanguard-mods/audit-trail/bin/hook.mjs\" --harness claude-code --event PostToolUse"
+          }
+        ]
+      }
+    ]
+  }
+}

package/mods/audit-trail/codex/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .codex/vanguard-mods/audit-trail/bin/hook.mjs --harness codex --event PostToolUse"
+          }
+        ]
+      }
+    ]
+  }
+}

package/mods/audit-trail/kiro/UNSUPPORTED.md

@@ -0,0 +1,7 @@
+# Audit Trail on Kiro
+
+<!-- Generated by scripts/generate-mods.mjs from mod.toml. Do not edit. -->
+
+## Degraded
+
+- `PostToolUse`: Kiro does not document stdin field names; args_hash covers the whole payload, result_hash hashes null, and without VANGUARD_AUDIT_TRAIL_SESSION_ID every session shares the unsessioned log.

package/mods/audit-trail/kiro/audit-trail-post-tool-use-hook.json

@@ -0,0 +1,14 @@
+{
+  "version": "v1",
+  "hooks": [
+    {
+      "name": "audit-trail:PostToolUse",
+      "description": "Appends one JSON line per tool call to a per-session log with sha256 hashes of the arguments and result.",
+      "trigger": "PostToolUse",
+      "action": {
+        "type": "command",
+        "command": "node .kiro/vanguard-mods/audit-trail/bin/hook.mjs --harness kiro --event PostToolUse"
+      }
+    }
+  ]
+}

package/mods/audit-trail/lib/common.mjs

@@ -0,0 +1,213 @@
+// Shared helpers for the mods under mods/. scripts/generate-mods.mjs copies this file
+// byte-for-byte to mods/<id>/lib/common.mjs, so edit it here and run `npm run mods:write`.
+//
+// Pure on purpose: no imports, no environment, no I/O. Claude Code's native mod runtime
+// imports it and has no Node, and every harness must reach the same verdict on the same
+// input. Regexes compile without the `u` flag so Node and Python `re.ASCII`
+// (tests/validate-mods.py) read them the same way.
+
+export const LIMITS = Object.freeze({
+  // A redaction that still changes after this many passes is withheld as a whole.
+  maxPasses: 8,
+  // A guard candidate longer than this is not evaluated and counts as a hit.
+  maxCandidateChars: 65536,
+  // Guard candidates are not evaluated past this combined length; the call counts as a hit.
+  maxTotalChars: 262144,
+  // Only the tail of a leaf's context (key or previous sibling) is prefixed to it.
+  maxContextChars: 256,
+})
+
+const MARKER_PREFIX = '[REDACTED:'
+export const OVERFLOW_MARKER = '[REDACTED:overflow]'
+const OVERFLOW_HIT = Object.freeze({ id: 'overflow', name: 'redaction did not converge' })
+export const TOO_LARGE_HIT = Object.freeze({ id: 'too-large', name: 'input too large to evaluate' })
+
+const ID_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/
+const PATTERN_KEYS = new Set(['id', 'name', 'description', 'regex', 'flags', 'context', 'severity', 'agents'])
+const isStringArray = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string' && s !== '')
+
+// Parser diagnostics can quote credential-bearing data; never expose it in hook logs.
+export function parseJson(text, source) {
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Error(`${source}: invalid JSON`)
+  }
+}
+
+// Validates a patterns.json-shaped list and compiles it. Throws on anything malformed so a
+// bad extension file fails closed in the caller instead of silently matching nothing.
+export function compilePatterns(list, source = 'patterns') {
+  if (!Array.isArray(list)) throw new Error(`${source}: expected an array of patterns`)
+  const seen = new Set()
+  return list.map((p, i) => {
+    const where = `${source}[${i}]`
+    if (p === null || typeof p !== 'object' || Array.isArray(p)) throw new Error(`${where}: expected an object`)
+    for (const k of Object.keys(p)) if (!PATTERN_KEYS.has(k)) throw new Error(`${where}: unknown key ${k}`)
+    if (typeof p.id !== 'string' || !ID_RE.test(p.id)) throw new Error(`${where}: id must be kebab-case`)
+    if (seen.has(p.id)) throw new Error(`${where}: duplicate id ${p.id}`)
+    seen.add(p.id)
+    if (typeof p.name !== 'string' || p.name === '') throw new Error(`${where}: name must be a non-empty string`)
+    if (typeof p.regex !== 'string' || p.regex === '') throw new Error(`${where}: regex must be a non-empty string`)
+    if (p.flags !== '' && p.flags !== 'i') throw new Error(`${where}: flags must be "" or "i"`)
+    if (!isStringArray(p.context) || p.context.length === 0) throw new Error(`${where}: context must be a non-empty string array`)
+    for (const k of ['description', 'severity']) {
+      if (p[k] !== undefined && typeof p[k] !== 'string') throw new Error(`${where}: ${k} must be a string`)
+    }
+    if (p.agents !== undefined && !isStringArray(p.agents)) throw new Error(`${where}: agents must be a string array`)
+    let rx, rxg
+    try {
+      rx = new RegExp(p.regex, p.flags)
+      rxg = new RegExp(p.regex, 'g' + p.flags)
+    } catch {
+      throw new Error(`${where}: regex does not compile`)
+    }
+    return Object.freeze({
+      id: p.id,
+      name: p.name,
+      severity: p.severity,
+      context: Object.freeze([...p.context]),
+      agents: p.agents ? Object.freeze([...p.agents]) : undefined,
+      rx,
+      rxg,
+      marker: `${MARKER_PREFIX}${p.id}]`,
+    })
+  })
+}
+
+// Every string value (not key) in depth-first order. The order follows the input, so the
+// same payload always yields the same list.
+export function stringLeaves(value, out = []) {
+  if (typeof value === 'string') out.push(value)
+  else if (Array.isArray(value)) for (const v of value) stringLeaves(v, out)
+  else if (value !== null && typeof value === 'object') for (const v of Object.values(value)) stringLeaves(v, out)
+  return out
+}
+
+// Guard candidates: every string leaf, plus every all-string array joined with spaces so
+// an argv-style command (["rm", "-rf", "/"]) reads like the shell line it runs.
+export function candidates(value) {
+  const out = stringLeaves(value)
+  const joinArrays = (v) => {
+    if (Array.isArray(v)) {
+      if (v.length > 1 && v.every((s) => typeof s === 'string')) out.push(v.join(' '))
+      v.forEach(joinArrays)
+    } else if (v !== null && typeof v === 'object') {
+      Object.values(v).forEach(joinArrays)
+    }
+  }
+  joinArrays(value)
+  return out
+}
+
+// The patterns tagged with `context` that match any text, in catalog order. Oversized input
+// is not evaluated (regex cost is unbounded there) and reports TOO_LARGE_HIT instead.
+export function matchPatterns(patterns, texts, context) {
+  let total = 0
+  for (const t of texts) {
+    total += t.length
+    if (t.length > LIMITS.maxCandidateChars || total > LIMITS.maxTotalChars) return [TOO_LARGE_HIT]
+  }
+  return patterns.filter((p) => p.context.includes(context) && texts.some((t) => p.rx.test(t)))
+}
+
+// One pattern pass after another until the text stops changing. Each pass can expose a new
+// match (password-in-url can swallow an earlier marker), so a single pass is not enough.
+function fixedPoint(text, patterns, hits) {
+  let x = text
+  for (let pass = 0; pass <= LIMITS.maxPasses; pass++) {
+    let y = x
+    for (const p of patterns) {
+      y = y.replace(p.rxg, (m) => {
+        if (m === '') return m
+        hits.add(p)
+        return p.marker
+      })
+    }
+    if (y === x) return x
+    x = y
+  }
+  hits.add(OVERFLOW_HIT)
+  return OVERFLOW_MARKER
+}
+
+// Redacts `s` with `ctx` in front so a secret split across a key and its value, or across
+// argv elements ("Bearer", "<token>"), still matches; then strips the context back off.
+function redactLeaf(s, ctx, patterns, hits) {
+  if (ctx === '') return fixedPoint(s, patterns, hits)
+  const pre = ctx.slice(-LIMITS.maxContextChars) + ' '
+  const y = fixedPoint(pre + s, patterns, hits)
+  if (y === OVERFLOW_MARKER) return y
+  const r = fixedPoint(pre, patterns, new Set())
+  if (y.startsWith(r)) return fixedPoint(y.slice(r.length), patterns, hits)
+  // A match spans the boundary: keep from the marker that covers it. Slicing changes
+  // anchors and boundaries, so also check the standalone leaf after contextual matching.
+  let d = 0
+  while (d < r.length && y[d] === r[d]) d++
+  const i = y.lastIndexOf(MARKER_PREFIX, d)
+  return fixedPoint(i >= 0 ? y.slice(i) : y, patterns, hits)
+}
+
+function walk(v, ctx, patterns, hits) {
+  if (typeof v === 'string') {
+    const local = new Set()
+    const out = redactLeaf(v, ctx, patterns, local)
+    if (out !== v) for (const h of local) hits.add(h)
+    return out
+  }
+  if (Array.isArray(v)) {
+    let prev = null
+    return v.map((el) => {
+      const out = walk(el, typeof prev === 'string' ? prev : ctx, patterns, hits)
+      prev = el
+      return out
+    })
+  }
+  if (v !== null && typeof v === 'object') {
+    const named = typeof v.name === 'string' ? v.name : typeof v.key === 'string' ? v.key : null
+    // fromEntries, not assignment: `out[k] = v` would drop an own "__proto__" key.
+    return Object.fromEntries(
+      Object.entries(v).map(([k, x]) => [
+        walk(k, '', patterns, hits),
+        walk(x, k === 'value' && named !== null ? named : k, patterns, hits),
+      ]),
+    )
+  }
+  return v
+}
+
+// Returns a copy of `value` with every match replaced by `[REDACTED:<id>]`, plus the
+// patterns that fired (catalog order, unique). Keys are redacted too; two keys that redact
+// to the same marker collapse into one, which loses data but never leaks it.
+export function redactValue(value, patterns) {
+  const hits = new Set()
+  const out = walk(value, '', patterns, hits)
+  const order = [...patterns, OVERFLOW_HIT]
+  return { value: out, hits: order.filter((p) => hits.has(p)) }
+}
+
+// Same shape as `value`, every string replaced by `text`. The fallback when redaction
+// itself failed: withhold everything rather than pass anything through.
+export function maskValue(value, text) {
+  if (typeof value === 'string') return text
+  if (Array.isArray(value)) return value.map((v) => maskValue(v, text))
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, maskValue(v, text)]))
+  }
+  return value
+}
+
+// JSON with object keys sorted at every level, so equal values hash equally.
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return '[' + value.map((v) => (v === undefined ? 'null' : canonicalJson(v))).join(',') + ']'
+  if (value !== null && typeof value === 'object') {
+    const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort()
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(value[k])).join(',') + '}'
+  }
+  return JSON.stringify(value) ?? 'null'
+}
+
+export async function sha256Hex(text) {
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(text))
+  return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('')
+}