ecoportal-api 0.10.15 → 0.10.17

data/.ai-assistance/scripts/scrub.py

@@ -0,0 +1,1149 @@
+#!/usr/bin/env python3
+"""
+scrub.py -- conservative, deterministic PII / secret / local-path redactor.
+
+FIRST PASS -- PENDING SECURITY REVIEW. This module is the ADR-011 /
+external-llm-review prerequisite: before any learning or worklog content is
+egressed to an external system (EPAI Confluence, Gemini), it must be stripped of
+PII, secrets, and machine-local filesystem paths. Today seed-epai-learnings.py
+--push is gated behind a manual EPAI_PUSH_CONFIRM=1 attestation precisely because
+no scrub function existed. This file provides that function.
+
+WIRING STATUS. Two consumers rely on this module:
+  - scripts/toggl-timesheet.py -- scrub() redaction of PII-adjacent free text (PII docking).
+  - scripts/seed-epai-learnings.py --push -- find_secrets() as a fail-closed BLOCK gate
+    before publishing auto-harvested content to the ROVO-indexed EPAI Confluence space.
+Two egress models, deliberately different (see find_secrets vs scrub below):
+  - REDACT (scrub) for LLM egress: over-redaction is acceptable, so replace secrets with
+    placeholders and send the cleaned text.
+  - BLOCK (find_secrets) for PUBLISH / bridge egress: silently rewriting a human-readable
+    doc would corrupt it, so instead REFUSE egress when a high-confidence secret is present.
+  - .ai-assistance/skills/gemini-assist/gemini_ask.rb -- scrub_for_egress() REDACTS the full
+    prompt (files + task) before it is sent to the Gemini API. Fail-closed: it shells out to
+    THIS module and aborts the send if scrubbing cannot run.
+The regexes are heuristics; they over-redact by design (false positives) and may still have
+false negatives. Treat findings as a strong prompt, not an absolute guarantee. Egress paths not
+separately gated are covered by compensating controls: the docs/structure Confluence seeders
+publish COMMITTED content already guarded by the secret_scan CI check + human review; bridge
+inbox/outbox are gitignored (no git leak) and the committed bridge archive is covered by
+secret_scan. Wire an explicit gate there too if belt-and-suspenders is wanted.
+
+Design notes:
+- Stdlib only. ASCII only (see .ai-assistance/conventions/documentation-style.md).
+- No network. No LLM. Pure-function, deterministic given the same input.
+- Conservative: prefer false-positives (over-redaction) over leaks. When in doubt
+  for a high-entropy token, we redact and record a finding so a human sees it.
+- scrub() NEVER raises: on any internal error it returns the original text plus an
+  {"type": "error", "count": 1} finding, so a caller can detect that scrubbing
+  did not run cleanly and refuse to egress.
+- Redactions replace the match with a clear placeholder, e.g. [REDACTED:email].
+
+Public API:
+    scrub(text) -> (scrubbed_text, findings)
+        findings is a list of {"type": str, "count": int}, one entry per pattern
+        that fired at least once.
+    scrub_file(path) -> (scrubbed_text, findings)
+
+CLI:
+    python scripts/lib/scrub.py <file>      # scrubbed text -> stdout, summary -> stderr
+    python scripts/lib/scrub.py --preview <file>
+                                            # NON-destructive redaction report (scrubbed
+                                            # text + findings table + MASKED samples);
+                                            # sends nothing, reveals no secret
+    python scripts/lib/scrub.py --selftest  # run built-in pattern assertions, exit 0/1
+"""
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# Code-fence masking
+# ---------------------------------------------------------------------------
+# High-entropy redaction is intentionally NOT applied inside fenced code blocks
+# (``` ... ``` or ~~~ ... ~~~), because legitimate hashes, base64 fixtures, and
+# sample data commonly live there and redacting them would mangle documentation.
+# All the *targeted* patterns (emails, paths, known secret prefixes, AWS keys,
+# JWTs, etc.) ARE still applied everywhere, including inside code fences -- a real
+# secret pasted into a code block is still a leak.
+
+_FENCE_RE = re.compile(r"(?ms)^[ \t]*(`{3,}|~{3,}).*?^[ \t]*\1[ \t]*$")
+
+
+def _fence_spans(text):
+    """Return a list of (start, end) char spans covered by fenced code blocks."""
+    spans = []
+    try:
+        for m in _FENCE_RE.finditer(text):
+            spans.append((m.start(), m.end()))
+    except Exception:
+        # Never let fence detection break scrubbing; just treat as no fences.
+        return []
+    return spans
+
+
+def _in_spans(pos, spans):
+    for s, e in spans:
+        if s <= pos < e:
+            return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Pattern table
+# ---------------------------------------------------------------------------
+# Each entry: (type_name, compiled_regex, respect_code_fences)
+# respect_code_fences=True means matches inside fenced code blocks are skipped
+# (used only for the broad high-entropy catch-alls).
+#
+# Order matters: more specific / higher-confidence patterns run first so that,
+# e.g., an AWS key or JWT is labelled as such rather than swallowed by the
+# generic high-entropy rule. Once a region is redacted it is replaced by an
+# ASCII placeholder that later patterns will not re-match.
+
+# Email -- deliberately broad local part.
+_EMAIL = re.compile(
+    r"[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}"
+)
+
+# Windows absolute path: drive letter + (\ or /) + at least one segment.
+# Matches C:\Users\rella\... and C:/claude/Projects/...
+_WIN_PATH = re.compile(
+    r"[A-Za-z]:[\\/](?:[^\s\\/:*?\"<>|]+[\\/]?)+"
+)
+
+# POSIX user-home / mount absolute paths.
+#   /home/<user>/...  /Users/<user>/...  /mnt/...  /root/...  /var/.../<user>...
+# Kept reasonably tight (requires a known root) to limit false positives on
+# ordinary prose containing slashes. Still over-redacts URLs paths sometimes;
+# acceptable per the conservative contract.
+_POSIX_HOME = re.compile(
+    r"(?:/home/|/Users/|/mnt/|/media/|/root/|/srv/|/opt/)"
+    r"[^\s\"'<>|:]*"
+)
+# Bare ~ home expansion: ~/something or ~user/something
+_TILDE_HOME = re.compile(r"~[A-Za-z0-9_\-]*\/[^\s\"'<>|:]+")
+
+# Secret prefixes (high confidence).
+_AWS_AKIA = re.compile(r"\b(?:AKIA|ASIA|AROA|AIDA|ANPA|ANVA|AIPA)[0-9A-Z]{16}\b")
+_GITLAB_PAT = re.compile(r"\bglpat-[A-Za-z0-9_\-]{20,}\b")
+_GITHUB_PAT = re.compile(r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b")
+_GITHUB_FINE_PAT = re.compile(r"\bgithub_pat_[A-Za-z0-9_]{30,}\b")
+_GOOGLE_API = re.compile(r"\bAIza[0-9A-Za-z_\-]{35}\b")
+# Google/Gemini newer API-key format: "AQ." + base64url body (e.g. AQ.Ab8R...).
+# The AIza pattern above does not cover it; observed on live Gemini keys.
+_GOOGLE_AQ = re.compile(r"\bAQ\.[A-Za-z0-9_\-]{30,}\b")
+# Slack tokens (bonus, high confidence).
+_SLACK = re.compile(r"\bxox[baprs]-[A-Za-z0-9\-]{10,}\b")
+# JWT: three dot-separated base64url segments starting with the typical eyJ header.
+_JWT = re.compile(r"\beyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+\b")
+
+# Ported from the AWS corpus-pipeline scrubber (do not lose these scoped detectors):
+_ATLASSIAN = re.compile(r"\bATATT3x[A-Za-z0-9]{30,}\b")            # Atlassian API token
+_ANTHROPIC = re.compile(r"\bsk-ant-[A-Za-z0-9_\-]{40,}\b")         # Anthropic API key
+_OPENAI = re.compile(r"\bsk-[A-Za-z0-9]{48,}\b")                   # OpenAI API key
+_AWS_ARN = re.compile(r"\barn:aws:[a-z0-9\-]+:[a-z0-9\-]*:\d{12}:[^\s`\]\n]+")
+_BASIC_AUTH_URL = re.compile(r"//[^@\s:/?#]{3,}:[^@\s:/?#]{3,}@")   # user:pass@ in a URL
+# Phone numbers (E.164 international + NZ/AU domestic; NZ-scoped per eP).
+_PHONE_E164 = re.compile(r"\+\d{1,3}[\s.\-]?\(?\d{1,4}\)?[\s.\-]?\d{3,4}[\s.\-]?\d{3,4}\b")
+_PHONE_NZ_AU = re.compile(r"\b0[2-9]\d?[\s.\-]?\d{3,4}[\s.\-]?\d{3,4}\b")
+# Private-range IP in CIDR notation (bare IPs still caught by _IPV4 below).
+_CIDR = re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}/\d{1,2}\b")
+
+# Bearer tokens: "Bearer <token>".
+_BEARER = re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._\-]{8,}")
+
+# key=value style secret assignments. Captures common key names with an optional
+# quote around the value. value is anything non-space / non-quote, >=6 chars.
+# NOTE: no leading \b -- the keyword must match even when it is a SUFFIX of a
+# prefixed identifier (GEMINI_API_KEY, CONFLUENCE_EPAI_API_KEY), where the char
+# before "api" is "_" (a word char, so \b fails). The trailing suffix group also
+# lets access-level-suffixed names match (FOO_TOKEN_RO=, BAR_TOKEN_RW=) -- exactly
+# the shape of our own env-var-naming convention. Matching starts mid-identifier,
+# so the redaction keeps the prefix (GEMINI_[REDACTED:secret_assignment]).
+_ASSIGN = re.compile(
+    r"(?i)(?:api[_\-]?key|apikey|secret(?:[_\-]?key)?|token|access[_\-]?token|"
+    r"auth[_\-]?token|password|passwd|pwd|client[_\-]?secret|private[_\-]?key)"
+    r"(?:[_\-][A-Za-z0-9]+)*"
+    r"\s*[:=]\s*['\"]?([^\s'\"]{6,})['\"]?"
+)
+
+# IPv4 (low priority, optional). Bounded octets to reduce matching version-like
+# strings; still may catch some non-address dotted quads -- acceptable.
+_IPV4 = re.compile(
+    r"\b(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)\b"
+)
+
+# High-entropy catch-alls (only OUTSIDE code fences). Long base64-ish or hex runs
+# that are likely keys/hashes pasted into prose. >= 40 hex chars or >= 32 base64
+# chars. These deliberately over-redact; every hit is recorded as a finding.
+_HEX_LONG = re.compile(r"\b[0-9a-fA-F]{40,}\b")
+_B64_LONG = re.compile(r"\b[A-Za-z0-9+/]{32,}={0,2}\b")
+
+
+# (type, regex, respect_fences). Targeted patterns ignore fences (real secrets
+# in code blocks still leak); only the generic entropy rules respect fences.
+_PATTERNS = [
+    ("basic_auth_url", _BASIC_AUTH_URL, False),
+    ("email", _EMAIL, False),
+    ("aws_access_key", _AWS_AKIA, False),
+    ("gitlab_pat", _GITLAB_PAT, False),
+    ("github_pat", _GITHUB_PAT, False),
+    ("github_fine_pat", _GITHUB_FINE_PAT, False),
+    ("google_api_key", _GOOGLE_API, False),
+    ("google_aq_key", _GOOGLE_AQ, False),
+    ("slack_token", _SLACK, False),
+    ("jwt", _JWT, False),
+    ("atlassian_token", _ATLASSIAN, False),
+    ("anthropic_key", _ANTHROPIC, False),
+    ("openai_key", _OPENAI, False),
+    ("aws_arn", _AWS_ARN, False),
+    ("bearer_token", _BEARER, False),
+    ("secret_assignment", _ASSIGN, False),
+    ("windows_path", _WIN_PATH, False),
+    ("posix_home_path", _POSIX_HOME, False),
+    ("tilde_home_path", _TILDE_HOME, False),
+    ("network_cidr", _CIDR, False),
+    ("phone", _PHONE_E164, False),
+    ("phone", _PHONE_NZ_AU, False),
+    ("ipv4", _IPV4, False),
+    ("high_entropy_hex", _HEX_LONG, True),
+    ("high_entropy_base64", _B64_LONG, True),
+]
+
+
+def _placeholder(type_name):
+    return "[REDACTED:%s]" % type_name
+
+
+def _apply_pattern(text, type_name, regex, respect_fences, matches=None):
+    """Replace all matches of one pattern. Returns (new_text, count).
+
+    Recomputes code-fence spans against the CURRENT text when respect_fences is
+    True, so a match's position is checked against fences in the same string.
+
+    If `matches` is a list, one dict per redaction is appended to it:
+      {"type", "start", "end", "replacement", "original"} where start/end are
+    offsets INTO THE OUTPUT (scrubbed) text and "original" is the raw matched
+    substring (used only for preview masking -- never persisted to egress).
+    """
+    placeholder = _placeholder(type_name)
+    if respect_fences:
+        spans = _fence_spans(text)
+    else:
+        spans = None
+
+    count = 0
+    out = []
+    out_len = 0
+    last = 0
+    for m in regex.finditer(text):
+        start = m.start()
+        if spans is not None and _in_spans(start, spans):
+            continue
+        gap = text[last:start]
+        out.append(gap)
+        out_len += len(gap)
+        if matches is not None:
+            matches.append({
+                "type": type_name,
+                "start": out_len,
+                "end": out_len + len(placeholder),
+                "replacement": placeholder,
+                "original": m.group(0),
+            })
+        out.append(placeholder)
+        out_len += len(placeholder)
+        last = m.end()
+        count += 1
+    out.append(text[last:])
+    return "".join(out), count
+
+
+# ---------------------------------------------------------------------------
+# Layer-1 dictionary pass (known private entities -> generic placeholder)
+# ---------------------------------------------------------------------------
+# A deterministic, dictionary-backed redaction of KNOWN private entities
+# (customer organizations, people, internal project names) that recur across
+# ecoPortal work and would otherwise leak on egress. The dictionary is built by
+# scripts/build-private-data-dictionary.py and lives, gitignored, at
+# .ai-assistance/local/private-data/ (override with $PRIVATE_DATA_DICT_DIR).
+#
+# Contract (shared with the builder):
+#   Sharded files organizations.json / people.json / projects.json, each:
+#     {"version":1, "generated":..., "category":..., "count":N,
+#      "entities":[{"key","display","placeholder","aliases":[],"sources":[]}]}
+#   Each entity's display + aliases all map, FORWARD-ONLY, to the SAME generic
+#   placeholder ([ORG]/[PERSON]/[PROJECT]). There is NO reverse map -- once
+#   redacted, the original name is unrecoverable from the output.
+#
+# Semantics: case-insensitive, word-boundary, LONGEST-MATCH-FIRST (so
+# "Briscoe Group" wins over "Briscoe"). A single precompiled regex alternation
+# (sorted longest-first, re.escape'd) does the matching in one pass.
+#
+# Graceful skip: if the directory is absent or holds no usable entities, the pass
+# is a no-op and regex-only behaviour is unchanged.
+
+_DICT_SHARD_FILES = ("organizations.json", "people.json", "projects.json")
+# Generic placeholders by category (must agree with the builder's PLACEHOLDERS).
+_DICT_PLACEHOLDERS = {
+    "organization": "[ORG]",
+    "person": "[PERSON]",
+    "project": "[PROJECT]",
+}
+
+
+def _dict_dir():
+    """Resolve the private-data dictionary directory.
+
+    Order: $PRIVATE_DATA_DICT_DIR, else the repo-default
+    .ai-assistance/local/private-data/ relative to this file (scripts/lib/).
+    """
+    env = os.environ.get("PRIVATE_DATA_DICT_DIR")
+    if env:
+        return Path(env)
+    # scripts/lib/scrub.py -> repo root is two parents up.
+    root = Path(__file__).resolve().parent.parent.parent
+    return root / ".ai-assistance" / "local" / "private-data"
+
+
+def load_dictionary(directory=None):
+    """Load the sharded dictionary into a list of (phrase, placeholder) pairs.
+
+    Reads organizations.json / people.json / projects.json from `directory`
+    (default: _dict_dir()). Each entity contributes its display and every alias
+    as a phrase, all mapped to the entity's generic placeholder. Returns [] if
+    the directory is absent/empty or nothing usable is found. NEVER raises.
+    """
+    try:
+        directory = Path(directory) if directory is not None else _dict_dir()
+        if not directory.is_dir():
+            return []
+        pairs = []
+        seen = set()
+        for fname in _DICT_SHARD_FILES:
+            fpath = directory / fname
+            if not fpath.is_file():
+                continue
+            try:
+                data = json.loads(fpath.read_text(encoding="utf-8"))
+            except Exception:
+                # A malformed shard is skipped, not fatal -- regex passes still run.
+                continue
+            entities = data.get("entities") if isinstance(data, dict) else None
+            if not isinstance(entities, list):
+                continue
+            for ent in entities:
+                if not isinstance(ent, dict):
+                    continue
+                placeholder = ent.get("placeholder")
+                if not placeholder:
+                    # Fall back to category default if placeholder missing.
+                    placeholder = _DICT_PLACEHOLDERS.get(ent.get("category"))
+                if not placeholder:
+                    continue
+                phrases = []
+                disp = ent.get("display")
+                if isinstance(disp, str):
+                    phrases.append(disp)
+                aliases = ent.get("aliases")
+                if isinstance(aliases, list):
+                    phrases.extend(a for a in aliases if isinstance(a, str))
+                for phrase in phrases:
+                    phrase = phrase.strip()
+                    if not phrase:
+                        continue
+                    dedup_key = (phrase.casefold(), placeholder)
+                    if dedup_key in seen:
+                        continue
+                    seen.add(dedup_key)
+                    pairs.append((phrase, placeholder))
+        return pairs
+    except Exception:
+        return []
+
+
+def _compile_dictionary(pairs):
+    """Compile (phrase, placeholder) pairs into (regex, {group->placeholder}).
+
+    Longest-match-first: phrases are sorted by descending length before being
+    joined into a single alternation, so the regex engine prefers the longest
+    phrase at a given position. Case-insensitive, word-boundary anchored.
+    Returns (None, {}) when there is nothing to compile.
+    """
+    if not pairs:
+        return None, {}
+    # Sort longest phrase first (tie-break casefold for determinism).
+    ordered = sorted(pairs, key=lambda p: (-len(p[0]), p[0].casefold()))
+    alts = []
+    group_placeholder = {}
+    for i, (phrase, placeholder) in enumerate(ordered):
+        gname = "d%d" % i
+        alts.append("(?P<%s>%s)" % (gname, re.escape(phrase)))
+        group_placeholder[gname] = placeholder
+    # Alphanumeric lookarounds (not \b) so entity names containing punctuation
+    # -- "AT&T", "Acme Corp." -- still match at their real boundaries (ported from
+    # the AWS corpus-pipeline registry cleaner). re.IGNORECASE for case.
+    pattern = r"(?<![A-Za-z0-9])(?:%s)(?![A-Za-z0-9])" % "|".join(alts)
+    try:
+        regex = re.compile(pattern, re.IGNORECASE)
+    except Exception:
+        return None, {}
+    return regex, group_placeholder
+
+
+def _apply_dictionary(text, compiled, matches=None):
+    """Replace known-entity matches with their generic placeholder.
+
+    Returns (new_text, count). `compiled` is (regex, group->placeholder) from
+    _compile_dictionary. No-op (returns text, 0) when regex is None.
+
+    If `matches` is a list, one dict per redaction is appended (same shape as
+    _apply_pattern), with type "known-entity" and offsets into the OUTPUT text.
+    """
+    regex, group_placeholder = compiled
+    if regex is None:
+        return text, 0
+    count = 0
+    out = []
+    out_len = 0
+    last = 0
+    for m in regex.finditer(text):
+        # Identify which named group actually matched.
+        placeholder = None
+        for gname, ph in group_placeholder.items():
+            if m.group(gname) is not None:
+                placeholder = ph
+                break
+        if placeholder is None:
+            continue
+        gap = text[last:m.start()]
+        out.append(gap)
+        out_len += len(gap)
+        if matches is not None:
+            matches.append({
+                "type": "known-entity",
+                "start": out_len,
+                "end": out_len + len(placeholder),
+                "replacement": placeholder,
+                "original": m.group(0),
+            })
+        out.append(placeholder)
+        out_len += len(placeholder)
+        last = m.end()
+        count += 1
+    out.append(text[last:])
+    return "".join(out), count
+
+
+# ---------------------------------------------------------------------------
+# Aho-Corasick fast path for the dictionary pass
+# ---------------------------------------------------------------------------
+# The regex oracle above compiles ~4,435 phrases into ONE alternation and lets
+# Python `re` backtrack over it (O(text x alternatives)); on an 84KB file that is
+# ~100s. This path builds an Aho-Corasick automaton once (linear build) and scans
+# the text once (linear O(text)), reproducing the oracle's selection rule EXACTLY:
+#
+#   - Case-insensitive via a length-preserving `str.lower()` fold. `re.IGNORECASE`
+#     matches char-by-char and (as proven exhaustively over all of Unicode) agrees
+#     with `.lower()` on every character pair EXCEPT a fixed set of 68 non-ASCII
+#     "exotic" codepoints (long-s, micro-sign, Greek/Cyrillic glyph variants, the
+#     U+0130 dotted-I whose lower() is 2 chars, a couple of ligatures). If ANY such
+#     char appears in the text or a phrase we do NOT fast-path: build_automaton
+#     returns None and scrub() uses the regex oracle. For all ASCII + Maori-macron
+#     text (the entire real corpus) `.lower()` is byte-for-byte equivalent to
+#     re.IGNORECASE and length-preserving, so offsets never drift.
+#   - Boundaries are the SAME ASCII-alnum lookarounds (not \b): a match needs a
+#     non-[A-Za-z0-9] char (or string end) immediately before its start and after
+#     its end, checked against the ORIGINAL text positions.
+#   - Leftmost, longest-at-start, non-overlapping: AC collects every phrase
+#     occurrence; a single left-to-right sweep then picks, at the earliest start
+#     with a boundary-valid phrase, the LONGEST such phrase (ties broken by the
+#     oracle's sort order: (-len, casefold), stable), emits it, and resumes at the
+#     match end -- identical to re.finditer over the sorted alternation.
+#   - The winning phrase's placeholder replaces the matched ORIGINAL-case span.
+
+# Codepoints where str.lower() is not a length-preserving, re.IGNORECASE-faithful
+# fold. Derived by exhaustively comparing str.lower() equivalence against
+# re.IGNORECASE over every Unicode codepoint (see the perf/scrub-aho-corasick
+# design notes). Presence of ANY of these in text or a phrase forces the oracle.
+_AC_EXOTIC_CODEPOINTS = frozenset({
+    0xB5, 0x130, 0x17F, 0x345, 0x390, 0x392, 0x395, 0x398, 0x399, 0x39A,
+    0x39C, 0x3A0, 0x3A1, 0x3A3, 0x3A6, 0x3B0, 0x3B2, 0x3B5, 0x3B8, 0x3B9,
+    0x3BA, 0x3BC, 0x3C0, 0x3C1, 0x3C2, 0x3C3, 0x3C6, 0x3D0, 0x3D1, 0x3D5,
+    0x3D6, 0x3F0, 0x3F1, 0x3F4, 0x3F5, 0x412, 0x414, 0x41E, 0x421, 0x422,
+    0x42A, 0x432, 0x434, 0x43E, 0x441, 0x442, 0x44A, 0x462, 0x463, 0x1C80,
+    0x1C81, 0x1C82, 0x1C83, 0x1C84, 0x1C85, 0x1C86, 0x1C87, 0x1C88, 0x1E60,
+    0x1E61, 0x1E9B, 0x1FBE, 0x1FD3, 0x1FE3, 0xA64A, 0xA64B, 0xFB05, 0xFB06,
+})
+
+
+def _ac_has_exotic(s):
+    """True if s contains any codepoint where str.lower() is not a faithful,
+    length-preserving stand-in for re.IGNORECASE (forces the regex oracle)."""
+    for ch in s:
+        if ord(ch) in _AC_EXOTIC_CODEPOINTS:
+            return True
+    return False
+
+
+def build_automaton(pairs):
+    """Build an Aho-Corasick automaton from (phrase, placeholder) pairs.
+
+    Returns an opaque dict consumed by _apply_dictionary_ac, or None when the
+    fast path is not usable (no pairs, or a phrase contains an exotic char --
+    see _AC_EXOTIC_CODEPOINTS -- in which case the caller falls back to the
+    regex oracle for guaranteed equivalence).
+
+    Phrases are keyed on their str.lower() fold. The same ordering the oracle
+    uses -- sorted by (-len(phrase), phrase.casefold()), stable -- is preserved
+    as each phrase's `rank`, so ties at a start position resolve identically.
+    """
+    if not pairs:
+        return None
+    # Same order the regex oracle imposes on its alternation.
+    ordered = sorted(pairs, key=lambda p: (-len(p[0]), p[0].casefold()))
+    # Node 0 is root. goto: list of dicts (char -> node). out: list of terminal
+    # payloads per node, each (phrase_len, rank, placeholder). fail: list of ints.
+    goto = [{}]
+    out = [[]]
+    for rank, (phrase, placeholder) in enumerate(ordered):
+        if _ac_has_exotic(phrase):
+            # A phrase with an exotic char cannot be folded safely -> no fast path.
+            return None
+        folded = phrase.lower()
+        if not folded:
+            continue
+        node = 0
+        for ch in folded:
+            nxt = goto[node].get(ch)
+            if nxt is None:
+                nxt = len(goto)
+                goto.append({})
+                out.append([])
+                goto[node][ch] = nxt
+            node = nxt
+        out[node].append((len(folded), rank, placeholder))
+    # Build failure links (BFS). fail[root]=0; fail of depth-1 nodes = root.
+    fail = [0] * len(goto)
+    queue = []
+    for ch, nxt in goto[0].items():
+        fail[nxt] = 0
+        queue.append(nxt)
+    head = 0
+    while head < len(queue):
+        node = queue[head]
+        head += 1
+        for ch, nxt in goto[node].items():
+            queue.append(nxt)
+            f = fail[node]
+            while f and ch not in goto[f]:
+                f = fail[f]
+            fail[nxt] = goto[f].get(ch, 0) if f or ch in goto[0] else 0
+            # Merge terminal outputs along the failure chain (report ALL phrases
+            # that end here, including shorter suffix phrases).
+            if out[fail[nxt]]:
+                out[nxt] = out[nxt] + out[fail[nxt]]
+    return {"goto": goto, "out": out, "fail": fail}
+
+
+def _ac_alnum(ch):
+    """ASCII alnum test matching the oracle's [A-Za-z0-9] character class."""
+    return ("0" <= ch <= "9") or ("A" <= ch <= "Z") or ("a" <= ch <= "z")
+
+
+def _apply_dictionary_ac(text, automaton, matches=None):
+    """Aho-Corasick equivalent of _apply_dictionary. Returns (new_text, count).
+
+    Reproduces the regex oracle byte-for-byte for text free of exotic chars.
+    Raises on any unexpected condition so scrub() can fall back to the oracle;
+    callers MUST wrap this and fall back on exception (fail-safe, never open).
+
+    `matches`, if a list, receives one dict per redaction (same shape/semantics
+    as _apply_dictionary): type "known-entity", offsets into the OUTPUT text,
+    "original" the matched original-case span, "replacement" the placeholder.
+    """
+    if automaton is None:
+        return text, 0
+    if _ac_has_exotic(text):
+        # Exotic char in the text: not safe to fold with .lower() -> force oracle.
+        raise ValueError("exotic codepoint in text; use regex oracle")
+
+    goto = automaton["goto"]
+    out = automaton["out"]
+    fail = automaton["fail"]
+    folded = text.lower()
+    # .lower() is length-preserving for all non-exotic input (guarded above);
+    # assert alignment so any surprise drift trips the fallback instead of leaking.
+    if len(folded) != len(text):
+        raise ValueError("fold changed length; use regex oracle")
+
+    n = len(text)
+    # Pass 1: AC sweep. For every end position, record the BEST phrase ending
+    # there whose start boundary is valid, keyed for start-position selection.
+    # best_at_start[start] = (phrase_len, rank, placeholder, end) for the phrase
+    # the oracle would choose if a match begins at `start` (longest, then lowest
+    # rank). We only keep boundary-valid candidates.
+    best_at_start = {}
+    node = 0
+    for i in range(n):
+        ch = folded[i]
+        while node and ch not in goto[node]:
+            node = fail[node]
+        node = goto[node].get(ch, 0)
+        if not out[node]:
+            continue
+        end = i + 1  # exclusive
+        # Trailing boundary: char after end must not be ASCII alnum (or be EOS).
+        if end < n and _ac_alnum(text[end]):
+            trailing_ok = False
+        else:
+            trailing_ok = True
+        if not trailing_ok:
+            continue
+        for (plen, rank, placeholder) in out[node]:
+            start = end - plen
+            # Leading boundary: char before start must not be ASCII alnum (or BOS).
+            if start > 0 and _ac_alnum(text[start - 1]):
+                continue
+            cur = best_at_start.get(start)
+            # Oracle preference at a start: longer wins, then lower rank.
+            if cur is None or (plen, -rank) > (cur[0], -cur[1]):
+                best_at_start[start] = (plen, rank, placeholder, end)
+
+    if not best_at_start:
+        return text, 0
+
+    # Pass 2: leftmost, non-overlapping selection -- resume at match end.
+    count = 0
+    out_parts = []
+    out_len = 0
+    last = 0
+    pos = 0
+    starts = sorted(best_at_start)
+    si = 0
+    ns = len(starts)
+    while si < ns:
+        start = starts[si]
+        if start < pos:
+            si += 1
+            continue
+        plen, rank, placeholder, end = best_at_start[start]
+        gap = text[last:start]
+        out_parts.append(gap)
+        out_len += len(gap)
+        if matches is not None:
+            matches.append({
+                "type": "known-entity",
+                "start": out_len,
+                "end": out_len + len(placeholder),
+                "replacement": placeholder,
+                "original": text[start:end],
+            })
+        out_parts.append(placeholder)
+        out_len += len(placeholder)
+        last = end
+        pos = end
+        count += 1
+        si += 1
+    out_parts.append(text[last:])
+    return "".join(out_parts), count
+
+
+def _run_dictionary_pass(text, matches=None):
+    """Run the layer-1 dictionary pass, preferring the Aho-Corasick fast path
+    and FALLING BACK to the regex oracle on any AC exception (fail-safe: the
+    oracle is the known-correct path, so a fallback can only be correct, never
+    a leak). Returns (new_text, count). Never raises.
+
+    Loads + builds the automaton (and the oracle) on each call, mirroring the
+    prior behaviour where _compile_dictionary(load_dictionary()) was rebuilt per
+    scrub. When AC is unavailable (no dict, or an exotic phrase) build_automaton
+    returns None and we use the oracle directly.
+    """
+    pairs = load_dictionary()
+    if not pairs:
+        return text, 0
+    automaton = None
+    try:
+        automaton = build_automaton(pairs)
+    except Exception:
+        automaton = None
+    if automaton is not None:
+        # AC fast path; any surprise -> oracle. If `matches` was partially
+        # populated before an exception, drop those entries so the oracle
+        # reruns cleanly (the oracle appends from a clean slate).
+        marker = len(matches) if matches is not None else 0
+        try:
+            return _apply_dictionary_ac(text, automaton, matches)
+        except Exception:
+            if matches is not None:
+                del matches[marker:]
+    # Regex oracle (fallback, or the only path when AC is unavailable).
+    compiled = _compile_dictionary(pairs)
+    return _apply_dictionary(text, compiled, matches)
+
+
+def scrub(text):
+    """Redact PII / secrets / local paths from text.
+
+    Returns (scrubbed_text, findings) where findings is a list of
+    {"type": str, "count": int}, one per pattern that matched at least once.
+
+    NEVER raises. On any internal error returns (original_text, [{"type":
+    "error", "count": 1}]) so a caller can detect failure and refuse to egress.
+    """
+    try:
+        if text is None:
+            return "", []
+        if not isinstance(text, str):
+            text = str(text)
+
+        findings = []
+        scrubbed = text
+
+        # Layer-1 dictionary pass FIRST: fold known private entities to their
+        # generic placeholder before the regex heuristics run. Graceful no-op if
+        # no dictionary is present. Never raises (loader/compile swallow errors).
+        try:
+            scrubbed, dict_count = _run_dictionary_pass(scrubbed)
+            if dict_count:
+                findings.append({"type": "known-entity", "count": dict_count})
+        except Exception:
+            # Dictionary pass must never break scrubbing; regex passes still run.
+            pass
+
+        for type_name, regex, respect_fences in _PATTERNS:
+            scrubbed, count = _apply_pattern(
+                scrubbed, type_name, regex, respect_fences
+            )
+            if count:
+                findings.append({"type": type_name, "count": count})
+        return scrubbed, findings
+    except Exception as exc:  # never raise out of scrub()
+        try:
+            sys.stderr.write("scrub: internal error: %r\n" % (exc,))
+        except Exception:
+            pass
+        return text if isinstance(text, str) else "", [
+            {"type": "error", "count": 1}
+        ]
+
+
+def scrub_detailed(text):
+    """Like scrub(), but also return per-match detail for PREVIEW/reporting.
+
+    Returns (scrubbed_text, findings, matches) where:
+      - scrubbed_text / findings are IDENTICAL to what scrub(text) returns
+        (same values, same shapes) -- this function does not change scrub()'s
+        public contract, it augments it.
+      - matches is a list of dicts, one per individual redaction, in the order
+        they were applied:
+            {"type": str, "start": int, "end": int,
+             "replacement": str, "original": str}
+        "original" is the RAW matched substring; it is provided ONLY so a caller
+        can render a MASKED sample and MUST NOT be egressed or logged verbatim.
+        "start"/"end" are offsets into the scrubbed text AT THE TIME that pattern
+        pass ran (passes run sequentially and later passes rewrite the string, so
+        treat them as an ordering/locality hint, not a guaranteed final offset).
+
+    NEVER raises: on internal error returns (original_text, [error-finding], []).
+    """
+    try:
+        if text is None:
+            return "", [], []
+        if not isinstance(text, str):
+            text = str(text)
+
+        findings = []
+        matches = []
+        scrubbed = text
+
+        try:
+            scrubbed, dict_count = _run_dictionary_pass(scrubbed, matches)
+            if dict_count:
+                findings.append({"type": "known-entity", "count": dict_count})
+        except Exception:
+            pass
+
+        for type_name, regex, respect_fences in _PATTERNS:
+            scrubbed, count = _apply_pattern(
+                scrubbed, type_name, regex, respect_fences, matches
+            )
+            if count:
+                findings.append({"type": type_name, "count": count})
+        return scrubbed, findings, matches
+    except Exception as exc:  # never raise
+        try:
+            sys.stderr.write("scrub_detailed: internal error: %r\n" % (exc,))
+        except Exception:
+            pass
+        return (text if isinstance(text, str) else ""), [
+            {"type": "error", "count": 1}
+        ], []
+
+
+# ---------------------------------------------------------------------------
+# Egress block-gate (B / ADR-011)
+# ---------------------------------------------------------------------------
+# High-confidence secret types: a match here is almost certainly a REAL credential,
+# not a heuristic false-positive. find_secrets() filters to these so it can be used as
+# a BLOCK gate before egress (publish to Confluence, write to a bridge file), where
+# silently redacting would corrupt legitimate content (governance docs contain example
+# tokens, IPs, paths). The noisy heuristics -- email, *_path, ipv4, network_cidr, phone,
+# high_entropy_*, known-entity -- are deliberately EXCLUDED here; they belong to
+# redaction (scrub()), used for LLM egress where over-redaction is acceptable.
+HIGH_CONFIDENCE_TYPES = frozenset({
+    "basic_auth_url", "aws_access_key", "gitlab_pat", "github_pat", "github_fine_pat",
+    "google_api_key", "google_aq_key", "slack_token", "jwt", "atlassian_token",
+    "anthropic_key", "openai_key", "bearer_token", "secret_assignment",
+})
+
+
+def find_secrets(text):
+    """Return high-confidence secret findings in `text` (list of {"type","count"}).
+
+    Non-empty => `text` contains something that must NOT be egressed. Uses scrub()'s
+    detector but filters to HIGH_CONFIDENCE_TYPES so noisy heuristics do not false-block.
+    Fail-closed: if scrub() itself errored (could not verify), that error finding is
+    included, so callers treat an un-verifiable input as unsafe. Never raises.
+    """
+    try:
+        _, findings = scrub(text)
+    except Exception:
+        return [{"type": "error", "count": 1}]
+    return [f for f in findings
+            if f["type"] in HIGH_CONFIDENCE_TYPES or f["type"] == "error"]
+
+
+def scrub_file(path):
+    """Read a file (UTF-8, errors replaced) and scrub its contents.
+
+    Returns (scrubbed_text, findings). Like scrub(), never raises: a read error
+    is reported as an {"type": "error", "count": 1} finding.
+    """
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as fh:
+            raw = fh.read()
+    except Exception as exc:
+        try:
+            sys.stderr.write("scrub_file: cannot read %s: %r\n" % (path, exc))
+        except Exception:
+            pass
+        return "", [{"type": "error", "count": 1}]
+    return scrub(raw)
+
+
+# ---------------------------------------------------------------------------
+# Self-test
+# ---------------------------------------------------------------------------
+# A built-in sample containing one of each pattern. Each entry asserts that the
+# raw fragment no longer appears verbatim in the scrubbed output and that the
+# expected finding type fired. Demonstrates correctness without any fixtures.
+
+_SELFTEST_CASES = [
+    ("email", "contact me at oscar@ecoportal.co.nz today"),
+    ("windows_path", r"see C:\Users\rella\.claude\paths.json for config"),
+    ("windows_path_fwd", "open C:/claude/Projects/ep-ai-standards/TODO.md"),
+    ("posix_home_path", "log lives at /home/oscar/.config/app/secret.cfg"),
+    ("posix_users_path", "build dir /Users/oscar/work/build/out"),
+    ("mnt_path", "data on /mnt/data/private/dump.sql"),
+    ("tilde_home", "config at ~/secrets/keys.txt loaded"),
+    ("aws_access_key", "key AKIAIOSFODNN7EXAMPLE used"),
+    ("gitlab_pat", "token glpat-ABCDEFGHIJKLMNOPQRSTUV set"),
+    ("github_pat", "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 here"),
+    ("github_fine_pat",
+     "github_pat_11ABCDEFG0abcdefghijklmnopqrstuvwxyz12345 here"),
+    ("google_api_key",
+     "AIzaSyA1234567890abcdefghijklmnopqrstuv in url"),
+    ("google_aq_key",
+     "gemini key AQ.Ab8RN6JjFAKEfakefakekey1234567890xyzABCdefg used"),
+    ("prefixed_api_key_assignment", "GEMINI_API_KEY=AbCdEfFake123456value"),
+    ("suffixed_token_assignment", "TOGGL_TOKEN_RW=zzzzfakevalue1234"),
+    ("slack_token", "xoxb-1234567890-abcdefghijklmnop posted"),
+    ("jwt",
+     "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w "
+     "is the token"),
+    ("bearer_token", "Authorization: Bearer abcdef1234567890XYZ"),
+    ("secret_assignment", 'api_key="s3cr3tValue12345"'),
+    ("password_assignment", "password = hunter2hunter2"),
+    ("ipv4", "host at 192.168.10.254 reachable"),
+    ("network_cidr", "subnet 10.0.0.0/8 allocated"),
+    ("phone_e164", "call +64 9 123 4567 tomorrow"),
+    ("phone_nz_au", "mobile 021 123 4567 for the site"),
+    ("atlassian_token", "atlassian ATATT3xFfGF0abcdefghijklmnopqrstuvwxyz012345 set"),
+    ("anthropic_key", "claude sk-ant-api03-abcdefghijklmnopqrstuvwxyz0123456789ABCD used"),
+    ("openai_key", "openai sk-abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKL here"),
+    ("aws_arn", "role arn:aws:iam::123456789012:role/MyExampleRole attached"),
+    ("basic_auth_url", "clone https://guser:s3cretpw@git.example.com/repo.git now"),
+    ("high_entropy_hex",
+     "digest 0123456789abcdef0123456789abcdef01234567 outside fence"),
+    ("high_entropy_base64",
+     "blob YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY3ODkw end"),
+]
+
+# Raw secret fragments that MUST disappear from the scrubbed output.
+_SELFTEST_SECRETS = [
+    "oscar@ecoportal.co.nz",
+    r"C:\Users\rella",
+    "C:/claude/Projects",
+    "/home/oscar/",
+    "/Users/oscar/",
+    "/mnt/data/private",
+    "~/secrets/keys.txt",
+    "AKIAIOSFODNN7EXAMPLE",
+    "glpat-ABCDEFGHIJKLMNOPQRSTUV",
+    "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
+    "github_pat_11ABCDEFG0abcdefghijklmnopqrstuvwxyz12345",
+    "AIzaSyA1234567890abcdefghijklmnopqrstuv",
+    "AQ.Ab8RN6JjFAKEfakefakekey1234567890xyzABCdefg",
+    "AbCdEfFake123456value",
+    "zzzzfakevalue1234",
+    "xoxb-1234567890-abcdefghijklmnop",
+    "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w",
+    "hunter2hunter2",
+    "s3cr3tValue12345",
+    "192.168.10.254",
+    "10.0.0.0/8",
+    "+64 9 123 4567",
+    "021 123 4567",
+    "ATATT3xFfGF0abcdefghijklmnopqrstuvwxyz012345",
+    "sk-ant-api03-abcdefghijklmnopqrstuvwxyz0123456789ABCD",
+    "sk-abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKL",
+    "arn:aws:iam::123456789012:role/MyExampleRole",
+    "s3cretpw",
+    "0123456789abcdef0123456789abcdef01234567",
+    "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY3ODkw",
+]
+
+
+def _selftest():
+    """Run built-in assertions. Returns 0 on success, 1 on any failure.
+
+    Hermetic: the machine-local entity dictionary is disabled so this exercises
+    the regex layer in isolation (the dictionary pass has its own tests).
+    """
+    os.environ["PRIVATE_DATA_DICT_DIR"] = os.path.join(
+        os.path.dirname(os.path.abspath(__file__)), "__no_such_dict__")
+    sample = "\n".join(desc for _, desc in _SELFTEST_CASES)
+    scrubbed, findings = scrub(sample)
+
+    ok = True
+
+    # 1. No raw secret fragment survives.
+    for secret in _SELFTEST_SECRETS:
+        if secret in scrubbed:
+            sys.stderr.write("FAIL: secret survived scrub: %r\n" % secret)
+            ok = False
+
+    # 2. The expected finding types all fired.
+    fired = {f["type"] for f in findings}
+    expected_types = {
+        "email", "windows_path", "posix_home_path", "tilde_home_path",
+        "aws_access_key", "gitlab_pat", "github_pat", "github_fine_pat",
+        "google_api_key", "google_aq_key", "slack_token", "jwt", "bearer_token",
+        "secret_assignment", "ipv4", "high_entropy_hex", "high_entropy_base64",
+        "atlassian_token", "anthropic_key", "openai_key", "aws_arn",
+        "basic_auth_url", "phone", "network_cidr",
+    }
+    missing = expected_types - fired
+    if missing:
+        sys.stderr.write("FAIL: finding types never fired: %s\n"
+                         % ", ".join(sorted(missing)))
+        ok = False
+
+    # 3. Code-fence sample: a hash INSIDE a fence is preserved; a real secret
+    #    (email) inside a fence is still redacted.
+    fenced = (
+        "Here is a legitimate hash in a code block:\n"
+        "```\n"
+        "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef\n"
+        "user@example.com\n"
+        "```\n"
+        "And outside: deadbeefdeadbeefdeadbeefdeadbeefdeadbeef\n"
+    )
+    fscrub, ffind = scrub(fenced)
+    # The in-fence hash should remain (not high-entropy-redacted).
+    if "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef" not in fscrub:
+        sys.stderr.write("FAIL: in-fence hash was redacted (should be kept)\n")
+        ok = False
+    # The out-of-fence hash should be redacted.
+    if fscrub.count("deadbeefdeadbeefdeadbeefdeadbeefdeadbeef") != 1:
+        sys.stderr.write(
+            "FAIL: out-of-fence hash not redacted "
+            "(in-fence copy should be the only survivor)\n"
+        )
+        ok = False
+    # The in-fence email should still be redacted (targeted patterns ignore fences).
+    if "user@example.com" in fscrub:
+        sys.stderr.write("FAIL: in-fence email survived (should be redacted)\n")
+        ok = False
+
+    # 4. scrub() never raises and handles odd input.
+    for bad in (None, 12345, b"bytes-not-str"):
+        try:
+            out, _ = scrub(bad)
+            if not isinstance(out, str):
+                sys.stderr.write("FAIL: scrub(%r) did not return str\n" % (bad,))
+                ok = False
+        except Exception as exc:
+            sys.stderr.write("FAIL: scrub(%r) raised %r\n" % (bad, exc))
+            ok = False
+
+    if ok:
+        sys.stderr.write("selftest: OK (%d findings on sample)\n" % len(findings))
+        return 0
+    sys.stderr.write("selftest: FAILED\n")
+    return 1
+
+
+def _summarize(findings, stream):
+    if not findings:
+        stream.write("scrub: no findings\n")
+        return
+    stream.write("scrub: findings:\n")
+    total = 0
+    for f in findings:
+        stream.write("  %-22s %d\n" % (f["type"], f["count"]))
+        total += f["count"]
+    stream.write("scrub: %d redaction(s) across %d pattern type(s)\n"
+                 % (total, len(findings)))
+
+
+def _mask_sample(original):
+    """Return a masked, safe-to-print rendering of a raw matched secret.
+
+    Reveals at most the first 2 and last 2 characters and masks the middle with
+    a run of '*', so the preview shows the SHAPE of what was redacted without
+    disclosing the value. Short values (<= 4 chars) are fully masked. Newlines
+    and tabs are collapsed so the sample stays on one line.
+    """
+    s = "".join(" " if c in "\r\n\t" else c for c in (original or ""))
+    n = len(s)
+    if n == 0:
+        return ""
+    if n <= 4:
+        return "*" * n
+    head = s[:2]
+    tail = s[-2:]
+    return "%s%s%s" % (head, "*" * (n - 4), tail)
+
+
+def _render_preview(scrubbed, findings, matches, stream):
+    """Write a human-readable, NON-leaking redaction report to `stream`.
+
+    Sections:
+      1. The scrubbed text (already safe -- secrets replaced by placeholders).
+      2. A findings table: one row per finding TYPE -> count.
+      3. A per-redaction list with a MASKED sample for each (never the raw value).
+    """
+    line = "=" * 60
+    stream.write(line + "\n")
+    stream.write("SCRUB PREVIEW -- REDACTION REPORT (nothing was sent)\n")
+    stream.write(line + "\n\n")
+
+    stream.write("--- Scrubbed text (safe to read) ---\n")
+    stream.write(scrubbed)
+    if scrubbed and not scrubbed.endswith("\n"):
+        stream.write("\n")
+    stream.write("\n")
+
+    stream.write("--- Findings (type -> count) ---\n")
+    if not findings:
+        stream.write("  (none -- nothing matched)\n")
+    else:
+        total = 0
+        for f in findings:
+            stream.write("  %-22s %d\n" % (f["type"], f["count"]))
+            total += f["count"]
+        stream.write("  %-22s %d redaction(s) across %d type(s)\n"
+                     % ("TOTAL", total, len(findings)))
+    stream.write("\n")
+
+    stream.write("--- Redactions (masked samples -- secrets NOT shown) ---\n")
+    if not matches:
+        stream.write("  (none)\n")
+    else:
+        for i, m in enumerate(matches, 1):
+            stream.write("  %3d. %-22s %s  (masked: %s)\n"
+                         % (i, m["type"], m["replacement"],
+                            _mask_sample(m.get("original", ""))))
+    stream.write("\n")
+    stream.write(line + "\n")
+
+
+def _preview(path):
+    """Render a non-destructive redaction report for `path` to stdout. Exit code
+    matches the scrubbed-text CLI: 2 if scrubbing errored, else 0."""
+    scrubbed, findings, matches = scrub_detailed_file(path)
+    _render_preview(scrubbed, findings, matches, sys.stdout)
+    if any(f["type"] == "error" for f in findings):
+        return 2
+    return 0
+
+
+def scrub_detailed_file(path):
+    """Read a file (UTF-8, errors replaced) and scrub_detailed() its contents.
+
+    Returns (scrubbed_text, findings, matches). Never raises: a read error is
+    reported as an {"type": "error", "count": 1} finding with no matches.
+    """
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as fh:
+            raw = fh.read()
+    except Exception as exc:
+        try:
+            sys.stderr.write("scrub_detailed_file: cannot read %s: %r\n"
+                             % (path, exc))
+        except Exception:
+            pass
+        return "", [{"type": "error", "count": 1}], []
+    return scrub_detailed(raw)
+
+
+def _main(argv):
+    # Windows stdout/stderr default to a locale codepage (cp1252) that cannot encode
+    # non-ASCII content (e.g. a stray glyph in a doc), which crashes the scrubber. Because
+    # the Ruby egress client (gemini_ask.rb) shells out to this and fail-closes on ANY
+    # scrubber error, that crash would silently BLOCK all Gemini egress of non-ASCII
+    # content. Force UTF-8 so the scrubbed text round-trips regardless of platform locale.
+    for _stream in (sys.stdout, sys.stderr):
+        try:
+            _stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    args = argv[1:]
+    if not args or args[0] in ("-h", "--help"):
+        sys.stderr.write(
+            "usage: python scripts/lib/scrub.py <file>\n"
+            "       python scripts/lib/scrub.py --preview <file>\n"
+            "       python scripts/lib/scrub.py --selftest\n"
+        )
+        return 0 if args else 1
+    if args[0] == "--selftest":
+        return _selftest()
+    if args[0] == "--preview":
+        if len(args) < 2:
+            sys.stderr.write(
+                "usage: python scripts/lib/scrub.py --preview <file>\n"
+            )
+            return 1
+        return _preview(args[1])
+
+    path = args[0]
+    scrubbed, findings = scrub_file(path)
+    sys.stdout.write(scrubbed)
+    if scrubbed and not scrubbed.endswith("\n"):
+        sys.stdout.write("\n")
+    _summarize(findings, sys.stderr)
+    # Non-zero exit if scrubbing errored, so callers/CI can detect it.
+    if any(f["type"] == "error" for f in findings):
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv))