@openthread/claude-code-plugin 0.1.5 → 0.1.9

package/scripts/lib/mask.py

@@ -0,0 +1,669 @@
+"""Privacy masking library for Claude Code session content.
+
+This is a Python port of ``apps/api/src/lib/privacy-mask.ts``. The
+pipeline, regex patterns, and replacement values are kept in lock-step
+with the TypeScript source so that client-side masked content matches
+the server's expectations.
+
+Pipeline:
+  0. sanitize.normalize(text)
+  A. rewrite_project(text, cwds)   -> cwd-relative [project] rewrite
+  B. paths                         -> home directories across OSes
+  C. secrets                       -> known prefixes, JWTs, etc.
+  D. entropy fallback              -> high-entropy near sensitive labels
+  E. PII                           -> email / IP / MAC / shell prompts
+  F. usernames                     -> back-reference bare usernames
+
+Python regex caveats vs JavaScript (documented here because they affect
+fidelity with the TS source):
+
+  * Python's ``re`` does not support ``\p{L}`` / ``\p{N}``. We emulate
+    with a custom character class that matches unicode letters and
+    digits where needed. ``re.UNICODE`` is on by default in Python 3.
+  * Python does not need the TS "lastIndex" reset dance — we use
+    ``finditer`` and module-level compiled patterns.
+  * The TS ``^`` / ``$`` with ``/m`` is the same as Python's
+    ``re.MULTILINE``.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import Any, Iterable
+
+try:
+    from . import sanitize  # package-style import (preferred)
+except ImportError:  # pragma: no cover - fallback when lib is on sys.path
+    import sanitize  # type: ignore[no-redef]
+
+
+# ---------------------------------------------------------------------------
+# Unicode character-class helpers
+# ---------------------------------------------------------------------------
+#
+# Python's stdlib re does not support \p{L} / \p{N}. We approximate the TS
+# "username segment" class by matching the Latin-compatible character set:
+# all letters/digits that Python treats as word characters except ``_`` and
+# the additional punctuation the TS class allows. Because ``\w`` under
+# ``re.UNICODE`` already spans ``\p{L}\p{N}_``, we widen it with
+# ``._+-`` and explicitly strip the leading underscore behaviour when we
+# need the stricter variant.
+
+# Matches \p{L}\p{N}._+-
+USER_SEG_CHARS = r"\w.+\-"  # \w already covers letters/digits/underscore
+
+# Bounded username segment: 1..64 of the above characters.
+USER_SEG = r"[" + USER_SEG_CHARS + r"]{1,64}"
+
+# A stricter "letter or digit" class used for word-boundary assertions in
+# the username back-reference pass. Matches Python's \w minus underscore.
+LETTER_OR_DIGIT = r"[^\W_]"
+
+
+# ---------------------------------------------------------------------------
+# A. Project (cwd) rewrite
+# ---------------------------------------------------------------------------
+
+# Chars that end a "path-like" run. We don't let the cwd rewriter consume
+# trailing punctuation (comma, colon, etc.).
+_PROJECT_BOUNDARY = r"(?=/|\s|$|[,;:\)\]\}\"'`>])"
+
+
+def rewrite_project(text: str, cwds: Iterable[str] | None) -> str:
+    """Replace occurrences of the user's cwd with the literal token
+    ``[project]``. The cwd rewrite runs BEFORE the generic home-dir rules
+    so that deeper paths collapse to ``[project]/sub/path`` instead of
+    ``[user-home]/...``.
+
+    * ``cwds`` is sorted longest-first so nested working directories
+      (e.g. ``/Users/a/code/app`` and ``/Users/a/code``) are matched in
+      the most-specific-first order.
+    * Matching is case-insensitive to handle macOS case-preserving
+      filesystems.
+    * The bare root ``/`` is silently skipped: rewriting ``/`` would
+      blank every absolute path in the document.
+    """
+    if not text or not cwds:
+        return text
+    # De-duplicate + longest-first.
+    unique = {c.rstrip("/") for c in cwds if isinstance(c, str) and c and c != "/"}
+    if not unique:
+        return text
+    ordered = sorted(unique, key=len, reverse=True)
+    out = text
+    for cwd in ordered:
+        pattern = re.compile(re.escape(cwd) + _PROJECT_BOUNDARY, re.IGNORECASE)
+        out = pattern.sub("[project]", out)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# B. Path rules
+# ---------------------------------------------------------------------------
+
+# Order matters: longest / most specific first. Each tuple is
+# ``(compiled_regex, replacement)``.
+_PATH_RULES: list[tuple[re.Pattern[str], str]] = [
+    # Windows UNC: \\server\share\... -> \\[server]\[share]
+    (
+        re.compile(r"\\\\[A-Za-z0-9._\-$]{1,64}\\[A-Za-z0-9._\-$]{1,64}"),
+        r"\\\\[server]\\[share]",
+    ),
+    # Windows drive: C:\Users\<name>
+    (
+        re.compile(
+            r"[A-Za-z]:\\[Uu][Ss][Ee][Rr][Ss]\\" + USER_SEG + r"(?=\\|$|[^\w.+\-])",
+        ),
+        r"C:\\Users\\[user]",
+    ),
+    # WSL: /mnt/<drive>/Users/<name>
+    (
+        re.compile(r"/mnt/[a-zA-Z]/[Uu][Ss][Ee][Rr][Ss]/" + USER_SEG),
+        "/mnt/[drive]/Users/[user]",
+    ),
+    # macOS Volumes: /Volumes/<vol>
+    (
+        re.compile(r"/Volumes/[\w.+\- ]{1,64}"),
+        "/Volumes/[volume]",
+    ),
+    # Linux mounted media: /mnt/<name> or /media/<name>
+    (
+        re.compile(r"/(?:mnt|media)/" + USER_SEG),
+        "/[mount]/[user]",
+    ),
+    # POSIX /Users/<name>
+    (
+        re.compile(r"/[Uu][Ss][Ee][Rr][Ss]/" + USER_SEG),
+        "/Users/[user]",
+    ),
+    # Linux /home/<name>
+    (
+        re.compile(r"/home/" + USER_SEG),
+        "/home/[user]",
+    ),
+    # /root
+    (
+        re.compile(r"/root(?=/|$|[^\w])"),
+        "/root",
+    ),
+    # ~/... tilde paths. Exclude shell metacharacters so we don't eat a
+    # shell prompt terminator and don't re-match an already redacted
+    # "~/[path]". Mirrors the TS exclude set.
+    (
+        re.compile(r"~/[^\s\"'`\)\]\}>$#\[\]]{1,512}"),
+        "~/[path]",
+    ),
+]
+
+
+def _apply_path_rules(text: str) -> str:
+    out = text
+    for pattern, repl in _PATH_RULES:
+        out = pattern.sub(repl, out)
+    return out
+
+
+# A second pass that converts the stable "[user-home]" marker used in
+# replacements into a shorter form. After ``_apply_path_rules`` runs, all
+# POSIX ``/Users/<name>`` segments become ``/Users/[user]``. For the
+# plugin-side flow the user wants the leading root path to become
+# ``[user-home]`` when no cwd matched. We therefore run a final pass to
+# collapse ``/Users/[user]``, ``/home/[user]``, and tilde forms to
+# ``[user-home]`` ONLY when not already rewritten to ``[project]``.
+_HOME_COLLAPSE_RE = re.compile(
+    r"(?:/Users/\[user\]|/home/\[user\]|C:\\Users\\\[user\]|/mnt/\[drive\]/Users/\[user\])"
+)
+
+
+def _collapse_home(text: str) -> str:
+    return _HOME_COLLAPSE_RE.sub("[user-home]", text)
+
+
+# ---------------------------------------------------------------------------
+# C. Secret rules
+# ---------------------------------------------------------------------------
+
+_SECRET_RULES: list[tuple[re.Pattern[str], str]] = [
+    # PEM private keys (generic)
+    (
+        re.compile(
+            r"-----BEGIN[ \t]+(?:[A-Z0-9]{1,12}[ \t]){0,4}PRIVATE KEY-----"
+            r"[\s\S]{1,16384}?"
+            r"-----END[ \t]+(?:[A-Z0-9]{1,12}[ \t]){0,4}PRIVATE KEY-----"
+        ),
+        "[REDACTED_PRIVATE_KEY]",
+    ),
+    # PGP private key block
+    (
+        re.compile(
+            r"-----BEGIN PGP PRIVATE KEY BLOCK-----"
+            r"[\s\S]{1,16384}?"
+            r"-----END PGP PRIVATE KEY BLOCK-----"
+        ),
+        "[REDACTED_PRIVATE_KEY]",
+    ),
+    # OpenSSH private key
+    (
+        re.compile(
+            r"-----BEGIN OPENSSH PRIVATE KEY-----"
+            r"[\s\S]{1,16384}?"
+            r"-----END OPENSSH PRIVATE KEY-----"
+        ),
+        "[REDACTED_PRIVATE_KEY]",
+    ),
+    # JWT (header.payload.signature)
+    (
+        re.compile(
+            r"\beyJ[A-Za-z0-9_-]{10,4096}\.[A-Za-z0-9_-]{10,4096}"
+            r"(?:\.[A-Za-z0-9_-]{0,4096})?"
+        ),
+        "[REDACTED_JWT]",
+    ),
+    # Authorization: <anything>
+    (
+        re.compile(r"Authorization[ \t]*:[ \t]*[^\r\n]{1,4096}", re.IGNORECASE),
+        "Authorization: [REDACTED]",
+    ),
+    # Bearer tokens
+    (
+        re.compile(r"\bBearer[ \t]+[A-Za-z0-9_\-.~+/]{8,4096}=*"),
+        "Bearer [REDACTED_TOKEN]",
+    ),
+    # Basic auth embedded in URL: scheme://user:pass@host
+    (
+        re.compile(
+            r"\b([a-zA-Z][a-zA-Z0-9+.\-]{1,16}):"
+            r"//[^\s/:@]{1,256}:[^\s/@]{1,256}@"
+        ),
+        r"\1://[REDACTED_BASIC_AUTH]@",
+    ),
+    # DB connection strings (runs after basic-auth scrub above)
+    (
+        re.compile(
+            r"\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|amqp|amqps)"
+            r"[+\w]{0,16}://[^\s\"'`\)\]\}>]{1,2048}",
+            re.IGNORECASE,
+        ),
+        "[REDACTED_CONNECTION_STRING]",
+    ),
+    # Anthropic
+    (re.compile(r"\bsk-ant-[A-Za-z0-9_\-]{20,200}"), "[REDACTED_KEY]"),
+    (re.compile(r"\banthropic-api03-[A-Za-z0-9_\-]{20,200}"), "[REDACTED_KEY]"),
+    # OpenAI
+    (re.compile(r"\bsk-(?:proj-|svcacct-)?[A-Za-z0-9_\-]{20,200}"), "[REDACTED_KEY]"),
+    # Google API key
+    (re.compile(r"\bAIza[0-9A-Za-z_\-]{35}"), "[REDACTED_KEY]"),
+    # AWS access keys
+    (re.compile(r"\b(?:AKIA|ASIA)[0-9A-Z]{16}"), "[REDACTED_KEY]"),
+    # GitHub
+    (re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,255}"), "[REDACTED_KEY]"),
+    (re.compile(r"\bgithub_pat_[A-Za-z0-9_]{20,255}"), "[REDACTED_KEY]"),
+    # GitLab
+    (re.compile(r"\bglpat-[A-Za-z0-9_\-]{20,255}"), "[REDACTED_KEY]"),
+    # Slack
+    (re.compile(r"\bxox[bpars]-[A-Za-z0-9\-]{10,255}"), "[REDACTED_KEY]"),
+    (re.compile(r"\bxapp-[A-Za-z0-9\-]{10,255}"), "[REDACTED_KEY]"),
+    # Stripe live/test secret/restricted/publishable
+    (re.compile(r"\b(?:sk|rk|pk)_live_[A-Za-z0-9]{20,255}"), "[REDACTED_KEY]"),
+    (re.compile(r"\b(?:sk|rk|pk)_test_[A-Za-z0-9]{20,255}"), "[REDACTED_KEY]"),
+    # Stripe legacy SK<32> / AC<32>
+    (re.compile(r"\b(?:SK|AC)[0-9a-fA-F]{32}\b"), "[REDACTED_KEY]"),
+    # Hugging Face
+    (re.compile(r"\bhf_[A-Za-z0-9]{20,255}"), "[REDACTED_KEY]"),
+    # xAI
+    (re.compile(r"\bxai-[A-Za-z0-9]{20,255}"), "[REDACTED_KEY]"),
+    # DigitalOcean PAT
+    (re.compile(r"\bdop_v1_[a-f0-9]{40,128}"), "[REDACTED_KEY]"),
+    # Generic env-var assignment lines: KEY=value
+    (
+        re.compile(
+            r"^([A-Z][A-Z0-9_]{2,64})[ \t]*=[ \t]*(?![ \t]*[{(])[^\r\n]{1,2048}$",
+            re.MULTILINE,
+        ),
+        r"\1=[REDACTED]",
+    ),
+]
+
+
+def _apply_secret_rules(text: str) -> str:
+    out = text
+    for pattern, repl in _SECRET_RULES:
+        out = pattern.sub(repl, out)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# D. Entropy fallback
+# ---------------------------------------------------------------------------
+
+_SECRET_LABELS_RE = re.compile(
+    r"(api[_\-]?key|api[_\-]?secret|auth(?:orization)?|access[_\-]?token|"
+    r"refresh[_\-]?token|secret|password|passwd|passphrase|token|bearer|"
+    r"credential|client[_\-]?secret|private[_\-]?key)",
+    re.IGNORECASE,
+)
+
+_ADJACENT_TOKEN_RE = re.compile(r"[A-Za-z0-9+/=._\-]{24,512}")
+
+
+def _shannon_entropy(s: str) -> float:
+    if not s:
+        return 0.0
+    counts: dict[str, int] = {}
+    for ch in s:
+        counts[ch] = counts.get(ch, 0) + 1
+    length = len(s)
+    h = 0.0
+    for c in counts.values():
+        p = c / length
+        h -= p * math.log2(p)
+    return h
+
+
+def _apply_entropy_rule(text: str) -> str:
+    out = text
+    replacements: list[tuple[int, int]] = []
+    for label in _SECRET_LABELS_RE.finditer(out):
+        label_end = label.end()
+        window = out[label_end : label_end + 256]
+        for tok in _ADJACENT_TOKEN_RE.finditer(window):
+            value = tok.group(0)
+            if value.startswith("[REDACTED"):
+                continue
+            if _shannon_entropy(value) >= 4.0:
+                start = label_end + tok.start()
+                replacements.append((start, start + len(value)))
+                # Mask only the first qualifying token per label.
+                break
+    if not replacements:
+        return out
+    # Apply right-to-left so indices remain valid.
+    replacements.sort(key=lambda r: r[0], reverse=True)
+    for start, end in replacements:
+        out = out[:start] + "[REDACTED_KEY]" + out[end:]
+    return out
+
+
+# ---------------------------------------------------------------------------
+# E. PII rules
+# ---------------------------------------------------------------------------
+
+# IPv4 with RFC1918 + loopback + link-local exemptions.
+_IPV4_RE = re.compile(
+    r"\b"
+    r"(?!127\.)"
+    r"(?!10\.)"
+    r"(?!192\.168\.)"
+    r"(?!172\.(?:1[6-9]|2\d|3[01])\.)"
+    r"(?!169\.254\.)"
+    r"(?!0\.0\.0\.0\b)"
+    r"(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)"
+    r"(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}"
+    r"\b"
+)
+
+_IPV6_RE = re.compile(
+    r"\b(?:[0-9A-Fa-f]{1,4}:){2,7}[0-9A-Fa-f]{0,4}\b"
+    r"|\b(?:[0-9A-Fa-f]{1,4}:){1,7}:"
+    r"|\b::(?:[0-9A-Fa-f]{1,4}:){0,6}[0-9A-Fa-f]{1,4}\b"
+)
+
+_MAC_RE = re.compile(r"\b(?:[0-9A-Fa-f]{2}[:\-]){5}[0-9A-Fa-f]{2}\b")
+
+_EMAIL_RE = re.compile(
+    r"[A-Za-z0-9._%+\-]{1,64}@[A-Za-z0-9.\-]{1,253}\.[A-Za-z]{2,24}"
+)
+
+# Shell prompt: user@host:path[$#]. We accept unicode letters/digits via
+# \w (which includes _) and extend with the TS punctuation class.
+_SHELL_PROMPT_RE = re.compile(
+    r"\b[\w.\-]{1,64}@[\w.\-]{1,253}:[^\s$#]{0,256}[$#]"
+)
+
+
+def _mask_ipv6(match: "re.Match[str]") -> str:
+    m = match.group(0)
+    colons = m.count(":")
+    if colons < 2:
+        return m
+    if m == "::1":
+        return m
+    return "[ipv6]"
+
+
+def _apply_pii_rules(text: str) -> str:
+    out = text
+    # Shell prompts first so user@host isn't chewed by email.
+    out = _SHELL_PROMPT_RE.sub("[shell-prompt]", out)
+    out = _EMAIL_RE.sub("[email]", out)
+    # MAC before IPv6: IPv6 regex would otherwise eat MAC sequences.
+    out = _MAC_RE.sub("[mac]", out)
+    out = _IPV6_RE.sub(_mask_ipv6, out)
+    out = _IPV4_RE.sub("[ip_address]", out)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# F. Username back-references
+# ---------------------------------------------------------------------------
+
+_USERNAME_EXTRACT_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(r"/[Uu][Ss][Ee][Rr][Ss]/([" + USER_SEG_CHARS + r"]{2,64})"),
+    re.compile(r"/home/([" + USER_SEG_CHARS + r"]{2,64})"),
+    re.compile(
+        r"[A-Za-z]:\\[Uu][Ss][Ee][Rr][Ss]\\([" + USER_SEG_CHARS + r"]{2,64})"
+    ),
+    re.compile(
+        r"/mnt/[a-zA-Z]/[Uu][Ss][Ee][Rr][Ss]/([" + USER_SEG_CHARS + r"]{2,64})"
+    ),
+]
+
+_RESERVED_USERNAMES = frozenset(
+    {
+        "[user]",
+        "[path]",
+        "Public",
+        "Shared",
+        "Default",
+        "All Users",
+        "root",
+        "admin",
+    }
+)
+
+
+def _extract_usernames(text: str) -> set[str]:
+    found: set[str] = set()
+    for pattern in _USERNAME_EXTRACT_PATTERNS:
+        for match in pattern.finditer(text):
+            name = match.group(1)
+            if not name:
+                continue
+            if len(name) < 2 or len(name) > 64:
+                continue
+            if name in _RESERVED_USERNAMES:
+                continue
+            found.add(name)
+    return found
+
+
+def _mask_bare_usernames(text: str, usernames: set[str]) -> str:
+    result = text
+    for username in usernames:
+        if len(username) < 3:
+            continue
+        escaped = re.escape(username)
+        # Hostname-style: alice-macbook, alice.dev
+        result = re.sub(
+            r"\b" + escaped
+            + r"s?[-.](?:macbook|laptop|desktop|pc|dev|server|local)[\w.\-]{0,64}",
+            "[hostname]",
+            result,
+            flags=re.IGNORECASE,
+        )
+        # Bare standalone reference. Approximate JS \p{L}\p{N}_ boundaries
+        # using Python's \w (which in Python 3 covers unicode letters +
+        # digits + underscore).
+        result = re.sub(
+            r"(^|[^\w])" + escaped + r"(?=$|[^\w])",
+            r"\1[user]",
+            result,
+        )
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def mask(
+    text: str,
+    cwds: list[str] | None = None,
+    home: str | None = None,
+) -> str:
+    """Mask sensitive data in a single string.
+
+    ``cwds`` — optional list of working directories to rewrite to
+    ``[project]``. Provide this for Claude Code session content so that
+    the actual project root becomes a stable placeholder regardless of
+    where the user cloned the repo.
+
+    ``home`` — optional explicit home-directory path to rewrite to
+    ``[user-home]`` early. If omitted, falls back to the path-rule
+    pipeline which still collapses home dirs via pattern matching.
+    """
+    if not isinstance(text, str) or not text:
+        return text
+
+    out = sanitize.normalize(text)
+
+    # Shell prompts first (see TS: before path rules so prompt "$" doesn't
+    # get consumed).
+    out = _SHELL_PROMPT_RE.sub("[shell-prompt]", out)
+
+    # A. cwd -> [project]
+    if cwds:
+        out = rewrite_project(out, cwds)
+
+    # A'. explicit home rewrite (optional). Done after cwd so cwd wins
+    # when it is a subpath of home.
+    if home and isinstance(home, str) and home.strip() and home != "/":
+        home_clean = home.rstrip("/")
+        out = re.sub(
+            re.escape(home_clean) + _PROJECT_BOUNDARY,
+            "[user-home]",
+            out,
+            flags=re.IGNORECASE,
+        )
+
+    # B. generic path rules
+    out = _apply_path_rules(out)
+
+    # B'. Collapse residual /Users/[user], C:\Users\[user], etc. to
+    # the shorter [user-home] placeholder for a nicer UX.
+    out = _collapse_home(out)
+
+    # C. secrets
+    out = _apply_secret_rules(out)
+
+    # D. entropy fallback
+    out = _apply_entropy_rule(out)
+
+    # E. PII
+    out = _apply_pii_rules(out)
+
+    # F. username back-references. Extract from normalized original so
+    # the path rule hasn't erased them yet.
+    normalized_original = sanitize.normalize(text)
+    usernames = _extract_usernames(normalized_original)
+    if usernames:
+        out = _mask_bare_usernames(out, usernames)
+
+    return out
+
+
+def _mask_value_deep(value: Any, usernames: set[str], cwds: list[str] | None, home: str | None) -> Any:
+    if isinstance(value, str):
+        masked = mask(value, cwds=cwds, home=home)
+        if usernames:
+            masked = _mask_bare_usernames(masked, usernames)
+        return masked
+    if isinstance(value, list):
+        return [_mask_value_deep(v, usernames, cwds, home) for v in value]
+    if isinstance(value, dict):
+        return {k: _mask_value_deep(v, usernames, cwds, home) for k, v in value.items()}
+    return value
+
+
+def _collect_block_strings(block: dict) -> list[str]:
+    """Return every text-bearing string in a Claude Code content block so
+    the two-pass username scan can see them."""
+    parts: list[str] = []
+
+    def visit(v: Any) -> None:
+        if isinstance(v, str):
+            parts.append(v)
+        elif isinstance(v, list):
+            for x in v:
+                visit(x)
+        elif isinstance(v, dict):
+            for x in v.values():
+                visit(x)
+
+    btype = block.get("type")
+    if btype in ("text", "thinking", "tool_result"):
+        content = block.get("content") or block.get("text") or ""
+        if isinstance(content, str):
+            parts.append(content)
+    elif btype == "code":
+        parts.append(str(block.get("content", "")))
+        if block.get("filename"):
+            parts.append(str(block["filename"]))
+    elif btype == "file":
+        parts.append(str(block.get("content", "")))
+        parts.append(str(block.get("filename", "")))
+    elif btype == "error":
+        parts.append(str(block.get("message", "")))
+    elif btype == "artifact":
+        parts.append(str(block.get("content", "")))
+        parts.append(str(block.get("title", "")))
+        parts.append(str(block.get("identifier", "")))
+    elif btype == "tool_use":
+        visit(block.get("input"))
+    return parts
+
+
+def mask_block_content(
+    block: dict,
+    usernames: set[str],
+    *,
+    cwds: list[str] | None = None,
+    home: str | None = None,
+) -> dict:
+    """Mask a single content block. ``usernames`` is the pre-gathered
+    set from a two-pass scan so cross-block bare references are caught.
+    """
+    btype = block.get("type")
+
+    def _mask_str(s: Any) -> Any:
+        if not isinstance(s, str):
+            return s
+        masked = mask(s, cwds=cwds, home=home)
+        if usernames:
+            masked = _mask_bare_usernames(masked, usernames)
+        return masked
+
+    if btype in ("text", "thinking", "tool_result"):
+        return {**block, "content": _mask_str(block.get("content", ""))}
+    if btype == "code":
+        out = {**block, "content": _mask_str(block.get("content", ""))}
+        if block.get("filename"):
+            out["filename"] = _mask_str(block["filename"])
+        return out
+    if btype == "file":
+        return {
+            **block,
+            "content": _mask_str(block.get("content", "")),
+            "filename": _mask_str(block.get("filename", "")),
+        }
+    if btype == "error":
+        return {**block, "message": _mask_str(block.get("message", ""))}
+    if btype == "artifact":
+        return {
+            **block,
+            "content": _mask_str(block.get("content", "")),
+            "title": _mask_str(block.get("title", "")),
+        }
+    if btype == "tool_use":
+        return {
+            **block,
+            "input": _mask_value_deep(block.get("input"), usernames, cwds, home),
+        }
+    # image, math, unknown: pass through.
+    return block
+
+
+def mask_thread_blocks(
+    blocks: list[dict],
+    *,
+    cwds: list[str] | None = None,
+    home: str | None = None,
+) -> list[dict]:
+    """Two-pass masking over a list of Claude Code content blocks.
+
+    Pass 1 scans every text-bearing field to gather usernames so that a
+    bare reference in block B can be masked because the path appeared in
+    block A.
+    """
+    haystack_parts: list[str] = []
+    for block in blocks:
+        haystack_parts.extend(_collect_block_strings(block))
+    haystack = sanitize.normalize("\n".join(haystack_parts))
+    usernames = _extract_usernames(haystack)
+
+    return [
+        mask_block_content(block, usernames, cwds=cwds, home=home)
+        for block in blocks
+    ]