agent-sanitizer 2.26.2 → 2.26.3

package/README.md

@@ -217,14 +217,34 @@ import {
 } from "agent-sanitizer/claude-hooks/lib/hook-io";
 ```
 
-The exported set is deliberately small — the four hooks
-(`sanitize-output`, `pretooluse-sanitize`, `sanitize-user-prompt`,
-`scan-invisible-chars`) plus `lib/hook-io` and `lib/control-plane`. Everything
-else under `claude-hooks/` stays internal and is refused by the exports map, so
-it never becomes a surface this package owes compatibility on. `lib/hook-io` is
-exported because it must be _shared_ rather than copied: it owns the
-lazy-module registry and the CLI-slot singleton, and two copies in one bundle
-double-fire the inlined CLIs.
+The exported set is **curated, not a wildcard**: exactly the subpaths below and
+nothing else. Anything unlisted is refused by the exports map with
+`ERR_PACKAGE_PATH_NOT_EXPORTED`, so it never becomes a surface this package owes
+compatibility on. `lib/hook-io` in particular is exported because it must be
+_shared_ rather than copied: it owns the lazy-module registry and the CLI-slot
+singleton, and two copies in one bundle double-fire the inlined CLIs.
+
+<!-- exports-table: rows are asserted to equal package.json's ./claude-hooks* exports by test/claude-hooks-exports.test.mjs -->
+
+| Subpath                             | What it is                                                                                 |
+| ----------------------------------- | ------------------------------------------------------------------------------------------ |
+| `claude-hooks`                      | The `--hook=` CLI dispatcher all four hooks are spawned through                            |
+| `claude-hooks/pretooluse-sanitize`  | PreToolUse orchestrator: invisible-char gate, confusable folding, stego strip, rehydration |
+| `claude-hooks/sanitize-output`      | PostToolUse pipeline: Layers 1–4 over tool output, plus the host-extension bag             |
+| `claude-hooks/sanitize-user-prompt` | UserPromptSubmit verdict on payload-capable invisible/ANSI content                         |
+| `claude-hooks/scan-invisible-chars` | SessionStart scan of `CLAUDE.md` / `.claude/` markdown                                     |
+| `claude-hooks/lib/hook-io`          | Shared hook I/O: the lazy-module registry, the CLI slot, deadlines, the hookgate marker    |
+| `claude-hooks/lib/control-plane`    | Bridge to `agent-control-plane-core` and the shared judge-CLI transport                    |
+| `claude-hooks/lib/authored-content` | Stego + terminal-control stripping of the fields the MODEL authors                         |
+| `claude-hooks/lib/env-config`       | The env-bound secret vocabulary the Layer-4 pre-gate and the redactor client share         |
+| `claude-hooks/lib/invisible-alert`  | Cross-hook alert state for uncleanable invisible-char injection in instruction files       |
+| `claude-hooks/lib/redactor-client`  | Client for the long-lived `agent-secret-redactor-daemon` (Layer 4's transport)             |
+| `claude-hooks/lib/reveal`           | The Layer-2 sidecar that lets the model re-read what the HTML splice removed               |
+| `claude-hooks/lib/secret-annotate`  | The cheap deterministic Layer-4 pre-gate checks around the daemon call                     |
+| `claude-hooks/lib/trace`            | The opt-in structured trace channel every layer announces itself on                        |
+
+Only `plugin-hooks` itself is unexported under its own name — it is reachable as
+the bare `claude-hooks` entry above.
 
 Importing one runs no CLI and reads no stdin. Same stability posture as the
 `_AGENT_SANITIZER_*` variables below: reachable and typed, but the supported

package/THREAT-MODEL.md

@@ -135,6 +135,74 @@ the model chooses to follow it — and the sentence reporting it is precisely th
 instruction not to. A target whose kind cannot be resolved is treated as
 auto-fetched (fail closed).
 
+## Layer 4—secret redaction (injected engine)
+
+The threat is the reverse of the other layers: not attacker text reaching the
+model, but a credential in tool output (a `.env` cat, a failing curl, a CI log)
+reaching a model that will paste it into the next tool call, a commit, or a
+bug report.
+
+**The package bundles no detector.** Layer 4 is an injected
+`redact(text) => {text, found, note?} | null` callback on `./output`, so the npm
+package ships no secret engine and a host may supply its own. The Claude Code
+plugin injects the Python engine from `agent-sanitizer[secrets]`
+(`python/agent_sanitizer/secrets/engine.py`) over a local daemon;
+`plugin/scripts/provision-redactor.sh` installs it at SessionStart.
+
+**It is the one fail-closed layer.** A redactor that throws — unreachable
+daemon, engine error — is rethrown from `sanitizeValue` as `CRITICAL: secret
+redaction failed …` (`src/output.mjs`), so the caller suppresses the output
+rather than emit a value nothing vetted. That is distinct from an engine that
+was never provisioned: there the hooks' posture applies, passing the output
+through with a loud warning by default and suppressing it under
+`AGENT_SANITIZER_FAIL_OPEN=0`. Either way the gap is announced, never silent.
+
+**Lone surrogates are normalized to U+FFFD before the redactor sees the text.**
+A secret split by an interposed lone surrogate renders as contiguous to the
+model but arrives broken at the redactor, so without normalization a
+reconstituted secret survives redaction. Both redact-input paths share one
+normalizer so they cannot drift.
+
+**Detection.** detect-secrets is the single oracle — its bundled plugins plus
+gitleaks-sourced ones for formats it lacks — extended with a regex
+for the unquoted `key=value` shapes `KeywordDetector` misses, PEM block
+collapse, cross-line reassembly of a secret split across lines, and exact-match
+redaction of caller-supplied env-var **values**. Each hit becomes
+`[REDACTED: <label>]` and its label joins `found`.
+
+**The engine discovers nothing about its environment.** Every
+environment-specific input — which env-var values to redact, the invisible
+charset, whether the text is web ingress — arrives through `RedactorConfig`; the
+engine never reads `os.environ`. Passing values rather than names is
+load-bearing for the daemon, which serves many sessions and must redact the
+_requester's_ keys. The invisible charset is sourced from the same SSOT Layer 1
+uses (and raises if that dependency is missing rather than silently using a
+partial set): a key spliced with a code point one layer omits would otherwise
+escape both.
+
+**Precision over recall, deliberately.** Redacting a UUID, a content digest, a
+timestamp, a version, a filesystem path, a public endpoint URL, a `$VAR`
+reference, a documentation placeholder or a markdown code span would delete text
+the model needed, so each is filtered out before redaction, and an env value
+shorter than `min_secret_len` (16) is treated as a test stub rather than a key.
+Two config switches move the trade-off where the context justifies it:
+`web_ingress` disables the name-based benign skips for attacker-controlled text,
+and `high_confidence` drops the fuzzy keyword/field-value detectors for source
+scans, where secret-shaped names appear legitimately.
+
+**Redaction stays reversible for editing, never for the model.**
+`redact_map` returns placeholder ↔ original pairs with offsets, which
+`./rehydrate` uses to re-anchor a model `Edit` composed from the redacted view
+back onto the real bytes. If the input already contains the private-use
+sentinels the map machinery reserves, it returns `{"unmappable": …}` rather than
+risk mis-pairing a placeholder with the wrong secret.
+
+**Ordering.** Layer 4 runs after Layers 1–2 have removed bytes, and is re-run on
+the post-deletion text whenever Layer 5 deletes a span — a deletion can
+reconstitute a secret the first pass never saw intact. On `Bash.command` it runs
+before `sanitizeAuthoredContent`, which is the assumption the confusable-folding
+soundness argument below relies on.
+
 ## Confusable folding (tool input)
 
 `./confusables` folds look-alike glyphs in tool-call **input** fields (paths,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.26.2",
+  "version": "2.26.3",
   "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
   "type": "module",
   "repository": {