fix: mask filesystem paths in telemetry error text

Merged
RA
3mo ago
+1284-4

Closes #1118

Why this PR exists

While triaging this product's error telemetry, we found a live 32-machine core_failure / file_not_found cluster whose messages carried complete /Users/<name>/… paths — the OS username and the customer's repository layout, verbatim, in App Insights. maskString (the telemetry redactor every error message and masked_args value passes through) deliberately covered API keys, bearer tokens, emails, internal hosts, and quoted strings — but had no rule for filesystem paths. The gap had stayed invisible for a subtle reason: quoted paths were coincidentally destroyed by the quoted-string rule, so only unquoted paths (File not found: /Users/… — the most common way tools print them) leaked.

This PR makes path-shaped content in telemetry text mask to <path> while keeping the surrounding words intact.

Why surgical masking instead of the industry shortcuts

Most mature CLIs never face this problem: the .NET SDK, AWS SAM, Homebrew, and dbt Core send no free text at all (exception names, enumerated events, timings). That is the strongest design, but this codebase sends error messages by design — the downstream error-triage pipeline clusters on them, so the message content is the product value being protected.

The other established shortcut is VS Code's: one crude segment-chain regex that turns anything word/word-shaped into <REDACTED: user-file-path>, plus nuking any property that merely contains the words password/token/key/secret. We replayed that strategy over 800 distinct live error messages from this product's own telemetry:

VS Code-style outcome on our corpusCount
Whole message destroyed by the secret-word rule48 (6%) — the credential/auth error class, among the most actionable
Help-URLs destroyed14
Over-masked (package names in install instructions eaten, fragmented redactions)328
Leaks that the rules in this PR catch4 (all benign carve-outs)

VS Code's telemetry is stack traces, where the words around a path carry no value. Ours is error prose, where those words — package names, support URLs, "a password must be specified" — are the diagnostic payload. So this PR does the harder thing: mask the path, keep the sentence.

How it works

Masking runs in layers, ordered after the credential rules and before the email/internal-host rules (so whole URIs mask before userinfo can fragment):

  1. Preprocessing. ANSI CSI/OSC escape sequences are stripped (colored subprocess stderr otherwise hides paths — and credentials — from every rule), and runs of 4+ bare separators collapse via one cheap rule.
  2. Structural rules — six regexes composed from shared, documented fragments: cloud URIs (s3 gs abfss wasbs adl dbfs hdfs file:), Windows homes, Windows drive/UNC/drive-relative/rooted forms, POSIX homes, POSIX absolute/dot-relative/shallow forms, and tildes (incl. ~user and PowerShell ~\). Home-rooted paths and cloud keys get an unconditional spaced-tail (usernames and object keys are the high-PII class); everything else takes a trailing word only at end-of-string or punctuation. Delimiters and quotes inside components count as path content only when a later separator or attached dotted filename proves them — otherwise they are boundaries, which is what keeps cd /a/b;ls, closing parens, and quote pairing intact.
  3. Known-prefix literals. The local user's home directory and cwd are known values, so paths under them are additionally replaced by exact literal match (JSON-doubled-backslash and swapped-separator variants, token-boundary guarded) — the approach Salesforce's telemetry and gatsby-telemetry use. This pass runs after the structural rules as a mop-up: structure must see the original string, or a stripped prefix orphans terminal spaced components.

Fast-path gates keep the cost honest: separator-free strings skip the whole path stack, and the two widest Windows rules additionally skip unless a backslash, boundary drive-colon, or non-scheme // is present.

Doctrine, applied consistently: over-masking is the correct failure mode; public https links are deliberately preserved (support-doc URLs in errors are triage signal); past an unproven delimiter, "path content vs prose" is undecidable and stays a documented boundary rather than a heuristic guess.

How it was hardened

The rules went through ~30 rounds of adversarial AI review (Codex, cubic, Kilo, CodeRabbit), with every finding probe-verified against the real corpus before any fix — several were rejected with evidence instead. Every round re-ran all 800 distinct 30-day live telemetry messages through the patched chain: zero residual path content throughout (intentional survivors: public https doc-links). Catches worth naming:

  • a nested-quantifier ReDoS shape (proven exponential) and later a quadratic delimiter-run scan (measured ~400ms) — both eliminated; every proof lookahead is now bounded by the filesystem's own 255-byte component limit, and the repo's upstream DoS-budget chaos suite passes;
  • an engine divergence: under /iu, spec-conformant engines case-fold \p{Lu} (V8 folds, JSC does not), which would have turned the capitalized-tail gate into "eat all prose" on any V8 runtime while tests stayed green on Bun — the i flag is gone, case-insensitivity is hand-expanded per letter, behavior verified identical on both engines;
  • a genuine unmask regression (an eaten closing quote shifted downstream quote pairing and leaked the next quoted value) — caught by a reviewer, fixed, and pinned;
  • WSL-mounted homes (/mnt/c/Users/Jane Doe), JSON-doubled separators, NBSP-bearing usernames, and legacy Documents and Settings roots — all real-world spellings of the same high-PII class.

Performance

Mean over the live corpus: ~220µs/message; ~4 masked fields per telemetry event, so well under 1ms per event, entirely off the interactive path. Adversarial inputs are bounded (a 20k-character separator run costs <1ms). Timing regression tests pin the adversarial shapes.

Verification

  • test/telemetry/mask-file-paths.test.ts: ~120 tests / 250+ assertions, organized by subject (preprocessing, each path family, anchors, in-component delimiters, extensions, the must-not-mask set, performance budgets) with doctrine comments per section.
  • The 800-message live-corpus sweep: 0 residual paths.
  • Full masking-adjacent suites (incl. the v1.4.0 chaos/fuzz files) and tsgo --noEmit pass; cross-engine spot-checks on JSC and V8 agree.

Documented residue (by design, not defects): one prose word may be over-masked after an extensionless home/cloud path; a non-home path's terminal spaced component can leak one structure word mid-sentence (no personal names in that class); an unproven delimiter is a permanent boundary; spaced terminal filenames may span interior words only when the run ends in a dotted extension (4 words on deep paths, 12 on explicit ./-style paths).

🤖 Generated with Claude Code

https://claude.ai/code/session_01LKJeLDMhBaYu16LrjGCf25


Summary by cubic

Masks filesystem, UNC (incl. FQDN), cloud-storage, and tilde paths in telemetry error text to prevent leaking usernames and repo structure. Previously, unquoted non-HTTP paths were sent verbatim; now they are replaced with

  • Centralizes path masking in packages/opencode using composed PATH_RULES; covers gs://, s3:///s3a://, abfss://, wasbs://, adl://, dbfs://, hdfs://, and file:/|//|///; Windows drive/UNC (extended-length, forward-slash UNC, current-drive rooted, drive-relative); POSIX absolute/dot-relative/single-file; and tildes (~, ~user, PowerShell ~\). Handles spaces, Unicode/combining marks, NBSP, and backslash-in-slash paths.
  • Ordering: runs after credential masking and before email/internal-host; preserves delimiters and quote pairing; public https URLs are untouched.
  • Bounded bridging: spaced continuation is now a proof (≤2 words, excludes delimiters and colon) to a later separator or dotted filename, which restores classification and prevents swallowing clauses between a path and URLs/dates/MIME types.
  • Performance/safety: 8 KB input cap; fast-path skip when no separators; collapses 4+ separator runs; bounded scans; eliminates drive-colon quadratic with opener bounds and a plausible-filename gate. Email masking gains a left boundary to avoid quadratic cases.
  • Known-prefix literals: exact os.homedir() and dynamic process.cwd() prefixes (incl. JSON-doubled and swapped separators) mop up after structural rules; adjacent
  • Tests: adds packages/opencode/test/telemetry/mask-file-paths.test.ts with Unicode/NBSP cases, anchors/delimiters, and growth-based perf assertions.

Summary by CodeRabbit

  • Privacy Enhancements
    • Telemetry error messages now redact filesystem paths and cloud-storage locations across Unix, Windows, network, Unicode, URI-based, and relative path formats.
    • Existing protection for email addresses, credentials, internal hosts, and public URLs remains supported.
  • Bug Fixes
    • Improved masking for paths containing spaces, quotes, brackets, symbols, punctuation, semicolons, and nested components.
    • Added support for intermediate home-directory paths and named-user home paths.
    • Improved consistency and performance for complex or unusually formatted error messages while preserving surrounding text and delimiters.