Module secret_gate 

Write-time secret detection gate.

Scans caller-supplied content strings before any storage write. A match causes a hard RuntimeError::SecretDetected that names the detector and carries a masked excerpt — it never echoes the full candidate back.

Scope: credentials only — API keys, tokens, private keys, passwords, and connection strings with embedded credentials. General PII (emails, phone numbers, company names) is intentionally NOT blocked.

Detection is layered, cheap-first:

1. Known-prefix / known-shape patterns — AWS AKIA/ASIA, GitHub tokens, OpenAI sk-proj-, Anthropic sk-ant-, Stripe live keys, Fly.io tokens, Vercel secrets, Slack xox*, JWT triples, PEM private-key headers, Age secret keys, URL userinfo (scheme://user:pass@).
2. High-entropy token heuristic — base64/hex/base64url runs ≥ 24 chars near a trigger word (key, secret, password, credential, bearer, auth, apikey, api_key, access_key, private_key). The word token alone is NOT a trigger, to avoid blocking tokenizer_*, token_count, etc.

A credential trigger word in the surrounding window always dominates the allowlist below — no exemption is unconditional near a trigger.

Full exemption rules (hex/UUID/SRI-hash passes, non-ASCII token delimiting, structured-identifier decomposition, trigger word-boundary matching, the underscore-boundary asymmetry between bare trigger words and the word token, and the adversarial-corpus rationale for why some false positives are accepted) are documented in full in docs/api/secret_gate.md#module-level-detection-algorithm — read that before changing any detection or exemption logic in this file.

The caller-visible block message (SecretMatch’s Display impl) also carries actionable guidance (block_guidance) to split or reword the flagged token.

A production-corpus replay harness (corpus_replay, #[ignore]d, run via KHIVE_REPLAY_DB=<path> cargo test ... -- --ignored --nocapture) measures the detector’s block rate against real note/entity content; see the harness’s own output for current numbers rather than a point-in-time count here, which would drift as the corpus changes.

Structs

SecretMatch

Returned when a write would store credential-looking content.

Functions

check

Hard-block content from being written.

check_json

Recursively scan a JSON value for credential-shaped strings.

check_tags

Scan a string-tagged slice (entity/note tags).

mask_secrets

Redact every detected secret span in text, replacing each with ***MASKED***.