Skip to main content

khive_runtime/
secret_gate.rs

1//! Write-time secret detection gate.
2//!
3//! Scans caller-supplied content strings before any storage write. A match
4//! causes a hard `RuntimeError::SecretDetected` that names the detector and
5//! carries a masked excerpt — it never echoes the full candidate back.
6//!
7//! Scope: **credentials only** — API keys, tokens, private keys, passwords,
8//! and connection strings with embedded credentials. General PII (emails,
9//! phone numbers, company names) is intentionally NOT blocked.
10//!
11//! Detection is layered, cheap-first:
12//! 1. **Known-prefix / known-shape patterns** — AWS AKIA/ASIA, GitHub tokens,
13//!    OpenAI `sk-proj-`, Anthropic `sk-ant-`, Stripe live keys, Fly.io tokens,
14//!    Vercel secrets, Slack `xox*`, JWT triples, PEM private-key headers, Age
15//!    secret keys, URL userinfo (`scheme://user:pass@`).
16//! 2. **High-entropy token heuristic** — base64/hex/base64url runs ≥ 24 chars
17//!    near a trigger word (key, secret, password, credential, bearer, auth,
18//!    apikey, api_key, access_key, private_key). The word `token` alone is
19//!    NOT a trigger, to avoid blocking `tokenizer_*`, `token_count`, etc.
20//!
21//! Credential-shaped labels and assignments dominate the allowlist below.
22//! Public VCS revisions and plausible file paths remain exempt in ordinary
23//! technical prose, while path segments are still scanned independently.
24//!
25//! Full exemption rules (hex/UUID/SRI-hash passes, non-ASCII token
26//! delimiting, structured-identifier decomposition, trigger word-boundary
27//! matching, the underscore-boundary asymmetry between bare trigger words and
28//! the word `token`, and the adversarial-corpus rationale for why some
29//! false positives are accepted) are documented in full in
30//! `docs/api/secret_gate.md#module-level-detection-algorithm` — read that before
31//! changing any detection or exemption logic in this file.
32//!
33//! The caller-visible block message (`SecretMatch`'s `Display` impl) also
34//! carries actionable guidance (`block_guidance`) to split or reword the
35//! flagged token.
36//!
37//! A production-corpus replay harness (`corpus_replay`, `#[ignore]`d, run via
38//! `KHIVE_REPLAY_DB=<path> cargo test ... -- --ignored --nocapture`) measures
39//! the detector's block rate against real note/entity content; see the
40//! harness's own output for current numbers rather than a point-in-time count
41//! here, which would drift as the corpus changes. A checked-in, sanitized
42//! snapshot of that replay (per-detector block counts and sha256 digests of
43//! blocked content, never the content itself) lives at
44//! `tests/data/secret_gate_corpus_manifest.md`, generated by
45//! `corpus_replay::generate_corpus_manifest`.
46
47use crate::error::{RuntimeError, RuntimeResult};
48
49// ─── Public API ──────────────────────────────────────────────────────────────
50
51/// Returned when a write would store credential-looking content.
52///
53/// Carries the detector name and a masked excerpt (`first6...Nchars`).  The
54/// full candidate is never stored in the error.
55#[derive(Debug, Clone, PartialEq, Eq)]
56pub struct SecretMatch {
57    /// Human-readable name of the detector that fired.
58    pub detector: &'static str,
59    /// `first6...N` — the first 6 chars of the match followed by the total length.
60    pub masked: String,
61}
62
63impl std::fmt::Display for SecretMatch {
64    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
65        write!(
66            f,
67            "content matches secret pattern {} at masked excerpt {}. {}",
68            self.detector,
69            self.masked,
70            block_guidance(self.detector)
71        )
72    }
73}
74
75/// Actionable, caller-visible guidance for a hard block, keyed by detector
76/// name. If the content genuinely is a credential, remove it. If it
77/// is not — the common case for the detectors below, which key off SHAPE
78/// near a trigger word rather than a known credential prefix — the fix is to
79/// break up the flagged token so it no longer reads as one contiguous
80/// high-entropy value: put it on its own line away from words like
81/// key/secret/auth/token, or insert a space/punctuation inside a long path or
82/// identifier (e.g. `workspaces / 20260705 / topic` instead of one glued
83/// token).
84fn block_guidance(detector: &'static str) -> &'static str {
85    match detector {
86        "high-entropy-token"
87        | "uuid-near-trigger"
88        | "content-hash-near-trigger"
89        | "hex-credential-token" => {
90            "If this is a real credential, remove it before writing. If it is not \
91             (e.g. a file path, UUID, or hash that happens to sit near a word like \
92             key/secret/auth/token), reword so the token is not glued directly next \
93             to that word — e.g. move it to its own line, or insert a space or word \
94             between them."
95        }
96        _ => {
97            "If this is a real credential, remove it before writing; store secrets \
98              in an env var or secrets manager instead."
99        }
100    }
101}
102
103/// Hard-block content from being written.
104///
105/// Returns `Err(RuntimeError::SecretDetected)` on the first match found, or
106/// `Ok(())` if no secret pattern fires.
107pub fn check(content: &str) -> RuntimeResult<()> {
108    if let Some(m) = scan(content) {
109        return Err(RuntimeError::SecretDetected(m));
110    }
111    Ok(())
112}
113
114/// Recursively scan a JSON value for credential-shaped strings.
115///
116/// Walks every string leaf (object values, array elements, nested objects).
117/// Returns `Err(RuntimeError::SecretDetected)` on the first match found.
118/// `None` / null / numeric / boolean JSON values are skipped.
119pub fn check_json(value: &serde_json::Value) -> RuntimeResult<()> {
120    scan_json_value(value)
121}
122
123/// Scan a string-tagged slice (entity/note tags).
124///
125/// Each tag string is scanned individually.
126pub fn check_tags(tags: &[String]) -> RuntimeResult<()> {
127    for tag in tags {
128        check(tag)?;
129    }
130    Ok(())
131}
132
133// ─── Reserved property key (ADR-115 Amendment 1) ────────────────────────────
134
135/// Top-level JSON property key reserved for runtime-owned exemption state.
136///
137/// No caller may create, replace, merge, or remove this key through any
138/// properties-bearing write path — ADR-115 Amendment 1 §3. Reservation binds
139/// unconditionally: the runtime does not yet stamp any record with this key
140/// (the finalizer that would do so is a separate, later increment), so no
141/// caller-supplied occurrence of it can ever be a legitimate echo of
142/// persisted state. Only the exact top-level key is reserved; the same
143/// spelling nested inside an object *value* is ordinary content and remains
144/// subject to [`check_json`], never a posture mutation.
145pub const RESERVED_SECRET_GATE_KEY: &str = "khive:secret_gate";
146
147/// Reject a caller-supplied top-level `khive:secret_gate` property key.
148///
149/// Call this before any diff, merge, or storage preparation touches
150/// caller-supplied `properties` on any properties-bearing write path —
151/// create, patch update, or full replace. Returns `Ok(())` when `properties`
152/// is absent, is not a JSON object, or does not name the reserved key at the
153/// top level.
154///
155/// This is the one shared validator for the reservation rule (ADR-115
156/// Amendment 1 §3); every properties-bearing write path across every crate
157/// must call this instead of re-implementing the check.
158pub fn reject_reserved_secret_gate_property(
159    properties: Option<&serde_json::Value>,
160) -> RuntimeResult<()> {
161    if let Some(serde_json::Value::Object(map)) = properties {
162        if map.contains_key(RESERVED_SECRET_GATE_KEY) {
163            return Err(RuntimeError::InvalidInput(format!(
164                "property key `{RESERVED_SECRET_GATE_KEY}` is runtime-owned and cannot be \
165                 created, replaced, merged, or removed by callers"
166            )));
167        }
168    }
169    Ok(())
170}
171
172fn scan_json_value(value: &serde_json::Value) -> RuntimeResult<()> {
173    match value {
174        serde_json::Value::String(s) => check(s),
175        serde_json::Value::Array(arr) => {
176            for v in arr {
177                scan_json_value(v)?;
178            }
179            Ok(())
180        }
181        serde_json::Value::Object(map) => {
182            for (k, v) in map {
183                // Scan both the key (a credential can appear as a JSON key name)
184                // and the value recursively.
185                check(k)?;
186                scan_json_value(v)?;
187            }
188            Ok(())
189        }
190        _ => Ok(()),
191    }
192}
193
194// ─── Scanner ─────────────────────────────────────────────────────────────────
195
196/// Marker substituted for a detected secret span by [`mask_secrets`].
197const REDACTION_MARKER: &str = "***MASKED***";
198
199/// Return the LEFTMOST secret in `text` as `(matched_slice, detector)`.
200///
201/// The matched slice borrows from `text`, so the caller can recover its byte
202/// span via pointer arithmetic — this is what lets [`mask_secrets`] redact in
203/// place while [`scan`] only needs the masked excerpt.
204///
205/// "Leftmost" (smallest start offset), NOT first-by-detector-priority, is the
206/// load-bearing contract: [`mask_secrets`] copies the text *before* each match
207/// verbatim, so a non-leftmost match would leak an earlier secret detected by a
208/// lower-priority detector (e.g. an `sk-ant-` key sitting to the left of a
209/// `ghp_` token). Both detector layers are folded through [`keep_leftmost`].
210fn scan_match(text: &str) -> Option<(&str, &'static str)> {
211    scan_from(text, 0)
212}
213
214/// Like [`scan_match`], but only returns secrets whose span starts at or after
215/// `from`, while still evaluating Layer-2 trigger context against the FULL
216/// `text`. [`mask_secrets`] calls this with an advancing `from` so that an
217/// entropy token is detected even when its only trigger word sits to the left of
218/// an already-redacted earlier secret. Layer-1 known patterns are context-free,
219/// so scanning the `&text[from..]` suffix is equivalent; offsets recovered via
220/// pointer arithmetic against the original `text` base stay absolute.
221fn scan_from(text: &str, from: usize) -> Option<(&str, &'static str)> {
222    let base = text.as_ptr() as usize;
223    // Layer 1: known prefix / shape patterns. Context-free → suffix scan; the
224    // returned slice still borrows from the same allocation, so its absolute
225    // offset is `slice.as_ptr() - base`.
226    let mut best = check_known_patterns(&text[from..]);
227    // Layer 2: entropy heuristic on long tokens near trigger words. Evaluated
228    // over the full text (so left-of-`from` trigger words count) but only tokens
229    // at offset >= from are returned; kept only if left of the best known match.
230    keep_leftmost(&mut best, check_entropy_heuristic(text, from), base);
231    best
232}
233
234/// Replace `best` with `cand` when `cand` starts earlier in the original text
235/// (`base` is the start address of that text). On a tie the incumbent wins, so
236/// callers offer more-specific detectors first. This is what makes
237/// [`check_known_patterns`] and [`scan_match`] return the leftmost secret span
238/// rather than the first detector that happens to match anywhere.
239fn keep_leftmost<'a>(
240    best: &mut Option<(&'a str, &'static str)>,
241    cand: Option<(&'a str, &'static str)>,
242    base: usize,
243) {
244    if let Some((slice, name)) = cand {
245        let start = slice.as_ptr() as usize - base;
246        let replace = match *best {
247            Some((incumbent, _)) => start < (incumbent.as_ptr() as usize - base),
248            None => true,
249        };
250        if replace {
251            *best = Some((slice, name));
252        }
253    }
254}
255
256/// Return the first `SecretMatch` found in `text`, or `None`.
257fn scan(text: &str) -> Option<SecretMatch> {
258    scan_match(text).map(|(slice, detector)| build_match(detector, slice))
259}
260
261/// Redact every detected secret span in `text`, replacing each with
262/// `***MASKED***`.
263///
264/// This is the masking counterpart to [`check`]: where `check` hard-blocks a
265/// write on the first match, `mask_secrets` is for content that must be STORED
266/// with credentials stripped (the session mirror). It reuses the SAME
267/// canonical detector set as `check`/`scan`, so callers must never maintain a
268/// second, weaker masker.
269///
270/// Returns `Cow::Borrowed` when no secret is present (the common case), avoiding
271/// an allocation. Spans are discovered left to right against the ORIGINAL text,
272/// always evaluating trigger context over the full input — a high-entropy value
273/// whose only trigger word sits to the left of an earlier-redacted secret is
274/// still detected. See `docs/api/secret_gate.md#mask_secrets` for the scan-cursor
275/// mechanics.
276pub fn mask_secrets(text: &str) -> std::borrow::Cow<'_, str> {
277    let base = text.as_ptr() as usize;
278    // Collect every secret span (absolute byte offsets into `text`) before
279    // writing any output, so trigger-context detection always sees the original
280    // string rather than the suffix after the previous redaction.
281    let mut spans: Vec<(usize, usize)> = Vec::new();
282    let mut from = 0;
283    while from < text.len() {
284        match scan_from(text, from) {
285            Some((sub, _detector)) => {
286                let start = sub.as_ptr() as usize - base;
287                // The prefix detectors return whitespace-delimited tokens, so a
288                // credential glued to structural punctuation (JSON quotes/braces,
289                // sentence commas) carries that trailing punctuation into the
290                // match. Trim a conservative trailing set that can never be part
291                // of a credential, so redacting does not consume surrounding JSON
292                // or prose structure. `=` `/` `+` `.` `-` `_` are intentionally
293                // NOT trimmed — they are valid base64/JWT/key characters.
294                let core_len = sub
295                    .trim_end_matches(['"', '\'', '`', '}', ']', ')', ',', ';'])
296                    .len();
297                let end = start + core_len.max(1);
298                spans.push((start, end));
299                // `scan_from` only returns matches with start >= from, and `end`
300                // is strictly greater than `start`, so `from` strictly advances.
301                from = end;
302            }
303            None => break,
304        }
305    }
306    if spans.is_empty() {
307        return std::borrow::Cow::Borrowed(text);
308    }
309    let mut out = String::with_capacity(text.len());
310    let mut cursor = 0;
311    for (start, end) in spans {
312        // Spans are non-overlapping and ascending (each starts at/after the prior
313        // `end`); `max(cursor)` is a defensive guard, never load-bearing.
314        let start = start.max(cursor);
315        out.push_str(&text[cursor..start]);
316        out.push_str(REDACTION_MARKER);
317        cursor = end.max(cursor);
318    }
319    out.push_str(&text[cursor..]);
320    std::borrow::Cow::Owned(out)
321}
322
323/// Maximum characters of raw error text admitted to the masking pass.
324///
325/// This is NOT a tight bound like [`MAX_LOG_TEXT_OUTPUT_CHARS`] below — it exists only to
326/// stop a truly pathological input (gigabytes of attacker-controlled text funneled into one
327/// error/log line) from making the masking scan unbounded. It is a pure compute bound, not a
328/// safety bound: [`find_url_userinfo`] has no length limit on the password it recognizes, so
329/// no finite value of this constant can guarantee a credential never straddles it — a
330/// password longer than whatever this is set to always has a crossing case. The actual
331/// safety invariant lives in [`redact_crossing_boundary_url_userinfo`], the fallback
332/// [`bounded_masked_log_text`] runs after [`mask_secrets`]: it redacts any `scheme://user:`
333/// opening whose password run reaches this cut point without a terminating `@`, regardless
334/// of how long that password is. 1 MiB just keeps the scan itself cheap.
335const MAX_LOG_TEXT_MASK_INPUT_CHARS: usize = 1_048_576;
336/// Maximum characters of masked error text emitted to a log record.
337const MAX_LOG_TEXT_OUTPUT_CHARS: usize = 1_024;
338
339/// Bound and mask arbitrary error text for log emission.
340///
341/// Log records are a disclosure surface the same way wire errors are: they are
342/// shipped, aggregated, and read by consumers outside the process. Backend
343/// error text (gate backends included) can embed connection strings or
344/// credentials, so the FULL text (up to `MAX_LOG_TEXT_MASK_INPUT_CHARS`, a
345/// pure compute bound — see its doc comment) is masked with the canonical
346/// detector set before any truncation happens. Masking after truncation would
347/// let a secret whose tail sits past the bound lose the context (e.g. a URL's
348/// terminating `@`) a detector needs to recognize it, leaving its head
349/// unmasked in the log — truncate-then-mask must never replace
350/// mask-then-truncate here. Because `MAX_LOG_TEXT_MASK_INPUT_CHARS` is
351/// finite and `find_url_userinfo` has no bound on password length, a
352/// password long enough still crosses the cut before its terminating `@`
353/// ever appears; `redact_crossing_boundary_url_userinfo` closes that gap
354/// by redacting the unterminated opening directly, so no credential prefix
355/// survives regardless of secret length. Control (`Cc`), format (`Cf`), line
356/// separator (`Zl`), and paragraph separator (`Zp`) Unicode codepoints in the
357/// masked text are then escaped: a log line is plain text read by tooling
358/// outside this process, and an embedded line break or bidi/format override
359/// could forge or visually disguise part of the record. The result is bounded
360/// again for the emitted record. A truncation in either the masking pass or the
361/// output pass appends `…` so the record declares its own incompleteness.
362pub fn bounded_masked_log_text(text: &str) -> String {
363    let mask_input_truncated = text.chars().nth(MAX_LOG_TEXT_MASK_INPUT_CHARS).is_some();
364    let bounded_input: std::borrow::Cow<'_, str> = if mask_input_truncated {
365        std::borrow::Cow::Owned(text.chars().take(MAX_LOG_TEXT_MASK_INPUT_CHARS).collect())
366    } else {
367        std::borrow::Cow::Borrowed(text)
368    };
369    let masked = mask_secrets(&bounded_input);
370    let masked = if mask_input_truncated {
371        redact_crossing_boundary_url_userinfo(&masked)
372    } else {
373        masked
374    };
375    let neutralized = neutralize_log_unsafe_chars(&masked);
376
377    let mut chars = neutralized.chars();
378    let mut bounded: String = chars.by_ref().take(MAX_LOG_TEXT_OUTPUT_CHARS).collect();
379    if chars.next().is_some() || mask_input_truncated {
380        bounded.push('…');
381    }
382    bounded
383}
384
385/// Fallback for a `scheme://user:<password>` credential whose password run
386/// collided with [`bounded_masked_log_text`]'s truncation of the mask-scan
387/// input at [`MAX_LOG_TEXT_MASK_INPUT_CHARS`]. [`find_url_userinfo`] only
388/// recognizes a credential once it sees the terminating `@`; when that `@`
389/// sits past the truncation point, [`mask_secrets`] never sees the shape at
390/// all and the raw `scheme://user:<password prefix>` reaches the log. No
391/// finite value of [`MAX_LOG_TEXT_MASK_INPUT_CHARS`] can rule this out — the
392/// detector is unbounded, so any cap has a crossing case — so the invariant
393/// has to come from this fallback, not from the cap's size.
394///
395/// Only called when `bounded_masked_log_text` actually truncated the input.
396/// It scans `://` occurrences left to right and redacts at the EARLIEST
397/// unterminated `user:<password-run>` opening: a colon splits the tail into
398/// two non-empty pieces and no `@`, space, or newline appears anywhere from
399/// that occurrence to the end of the truncated text. An occurrence whose
400/// tail does contain one of those terminators is a complete URL or ordinary
401/// prose that ends inside the text (e.g. two URLs logged side by side) and
402/// is skipped, not redacted. The anchor must be the earliest such opening,
403/// never the last: a later `://` can sit INSIDE the crossing password
404/// itself (passwords may contain `://`), and anchoring there would leave
405/// the real `user:<password prefix>` before it in the emitted log. From the
406/// earliest unterminated opening's colon onward everything is redacted —
407/// zero password characters survive, no matter how long the password
408/// actually is.
409fn redact_crossing_boundary_url_userinfo(text: &str) -> std::borrow::Cow<'_, str> {
410    let mut search_from = 0usize;
411    while let Some(rel) = text[search_from..].find("://") {
412        let scheme_pos = search_from + rel;
413        let rest = &text[scheme_pos + 3..];
414        let terminated =
415            rest.contains('@') || rest.contains(' ') || rest.contains('\n') || rest.contains('\r');
416        if !terminated {
417            // Same rules as `find_url_userinfo`: the userinfo colon must sit
418            // in the authority component (before any `/`, `?`, or `#` — a
419            // later colon is path/query text), and only the password must be
420            // non-empty (an empty username, `redis://:pass`, is a standard
421            // connection-string form and no less a credential). The password
422            // run AFTER the colon is unrestricted — a crossing password may
423            // itself contain any of those delimiters.
424            let authority_end = rest.find(['/', '?', '#']).unwrap_or(rest.len());
425            if let Some(colon) = rest[..authority_end].find(':') {
426                let pass = &rest[colon + 1..];
427                if !pass.is_empty() {
428                    let redact_from = scheme_pos + 3 + colon;
429                    let mut out = String::with_capacity(redact_from + REDACTION_MARKER.len());
430                    out.push_str(&text[..redact_from]);
431                    out.push_str(REDACTION_MARKER);
432                    return std::borrow::Cow::Owned(out);
433                }
434            }
435        }
436        search_from = scheme_pos + 3;
437    }
438    std::borrow::Cow::Borrowed(text)
439}
440
441/// `true` for a Unicode control (`Cc`), format (`Cf`), line separator (`Zl`), or
442/// paragraph separator (`Zp`) codepoint, tab excepted.
443///
444/// Classification is by Unicode general category rather than an ASCII byte range so that
445/// multi-byte control/format characters (bidi overrides, zero-width joiners, line/paragraph
446/// separators encoded as UTF-8) are caught the same way as single-byte C0 controls like
447/// CR/LF — a byte-range check would only ever see the latter. Tab is excepted: it is
448/// visually inert in a log line and common in legitimately reformatted prose.
449fn is_log_unsafe_char(c: char) -> bool {
450    if c == '\t' {
451        return false;
452    }
453    matches!(
454        unicode_general_category::get_general_category(c),
455        unicode_general_category::GeneralCategory::Control
456            | unicode_general_category::GeneralCategory::Format
457            | unicode_general_category::GeneralCategory::LineSeparator
458            | unicode_general_category::GeneralCategory::ParagraphSeparator
459    )
460}
461
462/// Escape every [`is_log_unsafe_char`] codepoint in `text` as `\u{XXXX}`.
463///
464/// Returns `Cow::Borrowed` when nothing needs escaping (the common case), avoiding an
465/// allocation. This runs on already-masked text: it must never be skipped for text that
466/// bypassed [`mask_secrets`], since a control character can sit inside a would-be secret
467/// span and is a distinct disclosure vector from the credential detectors (log injection /
468/// forgery, not credential leakage).
469fn neutralize_log_unsafe_chars(text: &str) -> std::borrow::Cow<'_, str> {
470    if !text.chars().any(is_log_unsafe_char) {
471        return std::borrow::Cow::Borrowed(text);
472    }
473    let mut out = String::with_capacity(text.len());
474    for c in text.chars() {
475        if is_log_unsafe_char(c) {
476            out.push_str(&format!("\\u{{{:04x}}}", c as u32));
477        } else {
478            out.push(c);
479        }
480    }
481    std::borrow::Cow::Owned(out)
482}
483
484// ─── Layer 1: known patterns ─────────────────────────────────────────────────
485
486/// Each entry: (detector_name, needle, min_total_token_len).
487///
488/// The needle must appear as a word-boundary-adjacent prefix in the token.
489/// `min_total_token_len` is the minimum length the token (needle + remainder)
490/// must have — prevents the prefix alone triggering without a payload.
491const PREFIX_DETECTORS: &[(&str, &str, usize)] = &[
492    // AWS
493    ("aws-access-key-id", "AKIA", 20),
494    ("aws-access-key-id", "ASIA", 20),
495    // GitHub tokens: personal-access (ghp_), OAuth (gho_), GitHub App
496    // user-to-server (ghu_), server-to-server (ghs_), refresh (ghr_), and the
497    // fine-grained PAT (github_pat_). All but github_pat_ share the gh*_ + 36+
498    // base62 shape.
499    ("github-token", "ghp_", 36),
500    ("github-token", "gho_", 36),
501    ("github-token", "ghu_", 36),
502    ("github-token", "ghs_", 36),
503    ("github-token", "ghr_", 36),
504    ("github-token", "github_pat_", 20),
505    // OpenAI
506    ("openai-api-key", "sk-proj-", 40),
507    // NOTE: bare "sk-" also matches Anthropic/Stripe below; put it last so
508    // the more-specific detectors fire first when both would match.
509    // Anthropic
510    ("anthropic-api-key", "sk-ant-", 20),
511    // Stripe live keys
512    ("stripe-secret-key", "sk_live_", 30),
513    ("stripe-restricted-key", "rk_live_", 30),
514    // Fly.io (fm2_ prefix only — FlyV1 handled separately because it embeds a space)
515    ("fly-token", "fm2_", 20),
516    // Vercel
517    ("vercel-token", "vercel_", 20),
518    // Slack
519    ("slack-token", "xoxb-", 40),
520    ("slack-token", "xoxa-", 40),
521    ("slack-token", "xoxp-", 40),
522    ("slack-token", "xoxr-", 40),
523    ("slack-token", "xoxs-", 40),
524    // Age secret key
525    ("age-secret-key", "AGE-SECRET-KEY-", 60),
526];
527
528/// Known safe compound words that start with `sk-` but are not credentials.
529/// E.g. scikit-learn slugs such as `sk-learn`, `sk-image`, `sk-lego`.
530const SK_SAFE_PREFIXES: &[&str] = &["sk-learn", "sk-image", "sk-lego", "sk-base", "sk-misc"];
531
532/// Shape-based patterns checked with custom logic.
533///
534/// Returns the LEFTMOST match across every detector (see [`keep_leftmost`]). The
535/// detectors are still offered in priority order, so two detectors that match at
536/// the SAME offset (e.g. bare `sk-` and the more-specific `sk-ant-`) resolve to
537/// the first-offered one.
538fn check_known_patterns(text: &str) -> Option<(&str, &'static str)> {
539    let base = text.as_ptr() as usize;
540    let mut best: Option<(&str, &'static str)> = None;
541
542    // --- Prefix patterns ---
543    for &(name, needle, min_len) in PREFIX_DETECTORS {
544        keep_leftmost(
545            &mut best,
546            find_prefix_token(text, needle, min_len).map(|m| (m, name)),
547            base,
548        );
549    }
550
551    // --- Bare `sk-` (after all more-specific sk- detectors above) ---
552    // Require length ≥ 30 AND exclude known safe scikit/library compound words.
553    if let Some(token) = find_prefix_token(text, "sk-", 30) {
554        if !SK_SAFE_PREFIXES.iter().any(|safe| token.starts_with(safe)) {
555            keep_leftmost(&mut best, Some((token, "openai-api-key")), base);
556        }
557    }
558
559    // --- Fly.io FlyV1 token: "FlyV1 <base64-payload>" ---
560    // The format embeds a space, so the generic prefix extractor (which stops at
561    // whitespace) cannot measure the combined length.  Check for `FlyV1 ` followed
562    // by ≥ 4 non-whitespace characters as the payload.
563    if let Some(pos) = text.find("FlyV1 ") {
564        let at_boundary = pos == 0 || {
565            text[..pos]
566                .chars()
567                .next_back()
568                .is_none_or(|c| !c.is_ascii_alphanumeric())
569        };
570        if at_boundary {
571            let payload_start = pos + 6; // skip "FlyV1 "
572            let payload = extract_token(&text[payload_start..]);
573            if payload.len() >= 4 {
574                let candidate = &text[pos..payload_start + payload.len()];
575                keep_leftmost(&mut best, Some((candidate, "fly-token")), base);
576            }
577        }
578    }
579
580    // --- PEM private key block ---
581    // "-----BEGIN <TYPE> PRIVATE KEY-----"
582    if text.contains("-----BEGIN") && text.contains("PRIVATE KEY-----") {
583        if let Some(pos) = text.find("-----BEGIN") {
584            // Measure only the key block itself (up to END marker or end-of-string),
585            // not the rest of the surrounding text, so build_match reports the
586            // block length rather than the remaining string length.
587            let block_end = text[pos..]
588                .find("-----END")
589                .map(|rel| {
590                    text[pos + rel..]
591                        .find('\n')
592                        .map(|l| pos + rel + l + 1)
593                        .unwrap_or(text.len())
594                })
595                .unwrap_or(text.len());
596            let excerpt = &text[pos..block_end];
597            keep_leftmost(&mut best, Some((excerpt, "pem-private-key")), base);
598        }
599    }
600
601    // --- JWT triple: eyJ...eyJ...eyJ (header.payload.signature) ---
602    // A JWT starts with "eyJ" (base64url of `{"`) and has exactly two dots.
603    keep_leftmost(&mut best, find_jwt(text).map(|m| (m, "jwt")), base);
604
605    // --- URL userinfo: scheme://user:pass@host ---
606    keep_leftmost(
607        &mut best,
608        find_url_userinfo(text).map(|m| (m, "url-userinfo")),
609        base,
610    );
611
612    best
613}
614
615/// Locate the first token in `text` that starts with `needle` and has a
616/// total length >= `min_len`.  Returns a slice of the full token on match.
617fn find_prefix_token<'a>(text: &'a str, needle: &str, min_len: usize) -> Option<&'a str> {
618    let mut start = 0;
619    while let Some(rel) = text[start..].find(needle) {
620        let abs = start + rel;
621        // Require that the needle starts at a token boundary (start-of-string
622        // or preceded by a non-ASCII-alphanumeric char).  The needles are ASCII,
623        // so only an ASCII alphanumeric can be a real continuation of the same
624        // token; CJK/accented text (which Rust counts as `is_alphanumeric`) must
625        // act as a delimiter, else a secret glued to non-Latin prose (`数据AKIA…`)
626        // is missed.
627        let at_boundary = abs == 0 || {
628            let prev = text[..abs].chars().next_back().unwrap_or(' ');
629            !prev.is_ascii_alphanumeric()
630        };
631        if at_boundary {
632            let token = extract_token(&text[abs..]);
633            if token.len() >= min_len && !is_filename_shaped_prefix_match(token, needle) {
634                return Some(token);
635            }
636        }
637        start = abs + needle.len().max(1);
638    }
639    None
640}
641
642/// Known source-file extensions that can terminate an ordinary provider-
643/// prefixed filename. This is deliberately a closed set: an unknown suffix
644/// is not evidence strong enough to suppress a context-free prefix detector.
645const SOURCE_FILE_EXTENSIONS: &[&str] =
646    &[".py", ".rs", ".ts", ".js", ".sh", ".md", ".toml", ".json"];
647
648/// Returns `true` for a lowercase source filename after a known provider
649/// prefix, such as `vercel_deployment_monitor.py`.
650///
651/// A source extension alone is not enough. The payload before it must contain
652/// only lowercase ASCII letters and filename/path punctuation; any uppercase
653/// letter or digit is credential-value evidence and keeps the prefix match
654/// fail-closed. Outer Markdown/prose punctuation is ignored, but never any
655/// payload byte inside the filename itself.
656fn is_filename_shaped_prefix_match(token: &str, needle: &str) -> bool {
657    let token = token.trim_end_matches(|c: char| {
658        matches!(
659            c,
660            '`' | '"' | '\'' | ')' | ']' | '}' | '>' | ',' | ';' | ':' | '!' | '?'
661        )
662    });
663    let token = token.strip_suffix('.').unwrap_or(token);
664    let Some(payload) = token.strip_prefix(needle) else {
665        return false;
666    };
667    let Some(stem) = SOURCE_FILE_EXTENSIONS
668        .iter()
669        .find_map(|extension| payload.strip_suffix(extension))
670    else {
671        return false;
672    };
673
674    stem.bytes().any(|byte| byte.is_ascii_lowercase())
675        && stem
676            .bytes()
677            .any(|byte| matches!(byte, b'_' | b'-' | b'/' | b'.'))
678        && stem
679            .bytes()
680            .all(|byte| byte.is_ascii_lowercase() || matches!(byte, b'_' | b'-' | b'/' | b'.'))
681}
682
683/// Scan for a JWT pattern: at least two "eyJ" segments separated by a `.`
684/// character, with each segment at least 10 chars.
685fn find_jwt(text: &str) -> Option<&str> {
686    let bytes = text.as_bytes();
687    let mut i = 0;
688    while i + 4 < bytes.len() {
689        if bytes[i..].starts_with(b"eyJ") {
690            // Find the end of this JWT (whitespace or string end).
691            let end = bytes[i..]
692                .iter()
693                .position(|&b| b == b' ' || b == b'\n' || b == b'\r' || b == b'\t')
694                .map(|p| i + p)
695                .unwrap_or(bytes.len());
696            let candidate = &text[i..end];
697            // Must have at least 2 dots and 3 eyJ-prefixed segments.
698            let dots = candidate.as_bytes().iter().filter(|&&b| b == b'.').count();
699            if dots >= 2 {
700                let parts: Vec<&str> = candidate.splitn(3, '.').collect();
701                if parts.len() == 3
702                    && parts[0].starts_with("eyJ")
703                    && parts[1].starts_with("eyJ")
704                    && parts[0].len() >= 10
705                    && parts[1].len() >= 10
706                {
707                    return Some(candidate);
708                }
709            }
710            i = end + 1;
711        } else {
712            i += 1;
713        }
714    }
715    None
716}
717
718/// Detect `scheme://user:pass@host` patterns where the userinfo carries an
719/// actual credential: a non-empty password. The username may be empty —
720/// `redis://:secret@host` is a standard empty-user connection string and its
721/// password is no less a credential for the missing username.
722fn find_url_userinfo(text: &str) -> Option<&str> {
723    let mut search = text;
724    let mut base = 0usize;
725    while let Some(at_rel) = search.find("://") {
726        let at_abs = base + at_rel;
727        // After `://`, only the authority component may carry userinfo: it
728        // ends at the first `/`, `?`, `#`, space, or newline. An `@` past
729        // that boundary is path/query text (`https://host/a:x@next`), not a
730        // credential.
731        let rest_start = at_abs + 3;
732        let rest = &text[rest_start..];
733        let authority_end = rest
734            .find(['/', '?', '#', ' ', '\n', '\r'])
735            .unwrap_or(rest.len());
736        if let Some(at_pos) = rest[..authority_end].rfind('@') {
737            let userinfo = &rest[..at_pos];
738            // Must contain a colon with a non-empty password after it.
739            if let Some(colon) = userinfo.find(':') {
740                let pass = &userinfo[colon + 1..];
741                if !pass.is_empty() {
742                    // Return a slice starting from the scheme.  Walk back from
743                    // `at_abs` to the first non-scheme char and resume just past
744                    // it.  Use `char_indices` and skip by the separator's full
745                    // UTF-8 width: a multibyte separator (e.g. CJK prose before a
746                    // credential URL) would otherwise leave `scheme_start` inside
747                    // the codepoint and panic the slice below.
748                    let scheme_start = text[..at_abs]
749                        .char_indices()
750                        .rev()
751                        .find(|(_, c)| {
752                            !c.is_ascii_alphanumeric() && *c != '+' && *c != '-' && *c != '.'
753                        })
754                        .map(|(idx, c)| idx + c.len_utf8())
755                        .unwrap_or(0);
756                    // Ensure there are no spaces in userinfo (not a code snippet).
757                    if !userinfo.contains(' ') && !userinfo.contains('\n') {
758                        let end = rest_start
759                            + at_pos
760                            + 1
761                            + rest[at_pos + 1..]
762                                .find([' ', '\n', '\r'])
763                                .unwrap_or(rest[at_pos + 1..].len());
764                        return Some(&text[scheme_start..end.min(text.len())]);
765                    }
766                }
767            }
768        }
769        base = at_abs + 3;
770        search = &text[base..];
771    }
772    None
773}
774
775// ─── Layer 2: entropy heuristic ─────────────────────────────────────────────
776
777/// Trigger words checked as a bounded standalone word (see
778/// [`contains_bounded_word`]). `token` is deliberately excluded — see
779/// `has_standalone_token`/`has_token_assignment` instead.
780/// See `docs/api/secret_gate.md#trigger_words` for the substring-collision
781/// rationale (issues #577 / #632).
782const TRIGGER_WORDS: &[&str] = &[
783    "key",
784    "secret",
785    "password",
786    "passwd",
787    "credential",
788    "bearer",
789    "auth",
790    "apikey",
791];
792
793/// Compound triggers that retain suffix matching inside credential labels.
794/// Their underscore separator disambiguates them from ordinary prose, and
795/// suffixes are common in versioned credential names such as `api_keyv2`.
796const COMPOUND_TRIGGER_WORDS: &[&str] = &["api_key", "access_key", "private_key"];
797
798/// Minimum token length to apply the entropy check.
799const MIN_ENTROPY_LEN: usize = 24;
800
801/// Shannon entropy threshold (bits per character) above which a token is
802/// considered high-entropy.  7.0 corresponds to ~99% utilisation of a
803/// 128-symbol alphabet — typical for random base64/hex.
804const ENTROPY_THRESHOLD: f64 = 4.5;
805
806/// Window around a trigger word in which a high-entropy token must appear.
807const TRIGGER_WINDOW: usize = 120;
808
809/// Credential-shaped exact hex lengths (AWS secret key, SHA-256/git SHA
810/// doubled, SHA-512 hex, etc.) — checked against a whole token, a single
811/// separator-delimited run, and a normalized (separator-stripped)
812/// concatenation of adjacent hex runs/tokens; see
813/// [`contains_normalized_hex_credential`].
814const HEX_CREDENTIAL_LENGTHS: &[usize] = &[32, 40, 64, 128];
815
816/// Max fragments [`bridge_fragment_chain`] concatenates per credential (fragment-count bound,
817/// not gap byte length — see docs/api/secret_gate.md#bridge-fragment-reconstruction).
818const MAX_BRIDGE_FRAGMENTS: usize = 6;
819
820/// Max delimiter-only glue tokens absorbed per direction while bridging fragments; see
821/// docs/api/secret_gate.md#bridge-fragment-reconstruction.
822const MAX_BRIDGE_GLUE_TOKENS: usize = 6;
823
824/// Shortest bare token treated as a plausible bridge fragment; see
825/// docs/api/secret_gate.md#bridge-fragment-reconstruction.
826const MIN_BRIDGE_FRAGMENT_LEN: usize = 8;
827
828/// Largest index `<= i` that lies on a UTF-8 char boundary of `s`. Stable
829/// replacement for the unstable `str::floor_char_boundary`; used to snap
830/// byte-offset windows that may land inside a multibyte char before slicing.
831fn floor_char_boundary(s: &str, i: usize) -> usize {
832    let mut i = i.min(s.len());
833    while i > 0 && !s.is_char_boundary(i) {
834        i -= 1;
835    }
836    i
837}
838
839/// `from` restricts which tokens may be RETURNED (only those starting at or
840/// after `from`), but the trigger-context window is still computed over the full
841/// `text`. This lets [`mask_secrets`] advance past an earlier redaction without
842/// losing a trigger word that sat to the left of it.
843fn check_entropy_heuristic(text: &str, from: usize) -> Option<(&str, &'static str)> {
844    // Tokenize into maximal ASCII non-whitespace runs; non-ASCII chars are also
845    // delimiters (see docs/api/secret_gate.md#module-level-detection-algorithm,
846    // "non-ASCII token delimiting"). Identical to `split_ascii_whitespace` on
847    // pure-ASCII input.
848    let tokens: Vec<(usize, &str)> = text
849        .split(|c: char| c.is_ascii_whitespace() || !c.is_ascii())
850        .filter(|t| !t.is_empty())
851        .map(|t| {
852            let offset = t.as_ptr() as usize - text.as_ptr() as usize;
853            (offset, t)
854        })
855        .collect();
856
857    for (idx, &(tok_offset, raw_token)) in tokens.iter().enumerate() {
858        // Strip common delimiters that wrap the actual value.
859        let token = strip_delimiters(raw_token);
860        // Only RETURN tokens at or after `from` (already-redacted spans lie
861        // before it); the trigger window below still spans the full text.
862        let token_offset = token.as_ptr() as usize - text.as_ptr() as usize;
863        if token_offset < from {
864            continue;
865        }
866        // A token below MIN_ENTROPY_LEN still passes through when it's a plausible
867        // bridge FRAGMENT (see docs/api/secret_gate.md#bridge-fragment-reconstruction);
868        // gating on alphanumeric runs (not hex-only) covers base64/base64url halves too.
869        let is_bridge_candidate = is_bridge_fragment_shape(token);
870        if token.len() < MIN_ENTROPY_LEN && !is_bridge_candidate {
871            continue;
872        }
873
874        // `token` is ASCII here (non-ASCII was split out at tokenization), so
875        // `shannon_entropy` over its bytes is a true per-character entropy.
876
877        // Compute the trigger window before any shape-based allowlist decision.
878        // UUID and base64 content-hash exemptions remain trigger-sensitive.
879        // VCS revisions and file paths use narrower syntactic context below.
880        let window_start = floor_char_boundary(text, tok_offset.saturating_sub(TRIGGER_WINDOW));
881        let window_end = floor_char_boundary(text, tok_offset + raw_token.len() + TRIGGER_WINDOW);
882        let window = &text[window_start..window_end];
883        let raw_start = tok_offset - window_start;
884        let raw_end = raw_start + raw_token.len();
885
886        // Must not provide its own trigger context (e.g. a path slug like
887        // `ADR-051-cli-auth-and-kg-git-workflow.md`); see
888        // docs/api/secret_gate.md#check_entropy_heuristic--per-token-flagging-sequence.
889        let near_trigger = contains_trigger(&window[..raw_start])
890            || contains_trigger(&window[raw_end..])
891            || has_inline_credential_trigger(raw_token);
892
893        // Step 1 (see doc: per-token flagging sequence). UUID/content-hash checks fall
894        // through to detection near a trigger rather than being silently passed —
895        // hex-shaped entropy alone (<=4.0 bits/char) can never reach ENTROPY_THRESHOLD.
896        if near_trigger && value_candidates(token).any(is_uuid_canonical) {
897            return Some((token, "uuid-near-trigger"));
898        }
899        if near_trigger && value_candidates(token).any(is_base64_content_hash) {
900            return Some((token, "content-hash-near-trigger"));
901        }
902        if !near_trigger && (is_uuid_canonical(token) || is_base64_content_hash(token)) {
903            continue;
904        }
905
906        // Step 2. Pure hex off-trigger is allowlisted; trigger-adjacent hex needs an
907        // explicit VCS coordinate marker (see doc).
908        if !near_trigger && is_pure_hex(token) {
909            continue;
910        }
911
912        // VCS-marker exemption is a flag over the hex-credential-shape checks only,
913        // never an early skip of fragment reconstruction below (see doc).
914        if is_vcs_marker_before_hex(text, raw_token)
915            && !has_clause_credential_label(
916                text,
917                token_offset,
918                raw_token,
919                ClauseValueKind::VcsReference,
920            )
921        {
922            continue;
923        }
924
925        let vcs_reference_exempt = is_git_revision_reference(text, token_offset, raw_token)
926            && !has_clause_credential_label(
927                text,
928                token_offset,
929                raw_token,
930                ClauseValueKind::VcsReference,
931            );
932
933        // Step 3. Hex API keys aren't caught by the entropy heuristic (hex tops out at
934        // 4.0 bits/char, below ENTROPY_THRESHOLD 4.5); flag credential-shaped hex directly.
935        if !vcs_reference_exempt
936            && near_trigger
937            && is_pure_hex(token)
938            && HEX_CREDENTIAL_LENGTHS.contains(&token.len())
939        {
940            return Some((token, "hex-credential-token"));
941        }
942
943        // Step 4 (issue #1044): a credential can dilute below the whole-token-average
944        // checks above via low-entropy filler sharing its whitespace token
945        // (`vault/<payload>/rotate.md`); re-check each `/`-split run independently.
946        // See doc for the #1040 corpus rationale behind the MIN_ENTROPY_LEN floor.
947        if near_trigger {
948            // vcs_reference_exempt also covers single-token forms below (`rev:<hex>`);
949            // it does not cover fragment reconstruction.
950            for run in token.split(|c: char| !c.is_ascii_alphanumeric()) {
951                if run.len() < MIN_ENTROPY_LEN {
952                    continue;
953                }
954                if !vcs_reference_exempt
955                    && is_pure_hex(run)
956                    && HEX_CREDENTIAL_LENGTHS.contains(&run.len())
957                {
958                    return Some((token, "hex-credential-token"));
959                }
960                if shannon_entropy(run.as_bytes()) >= ENTROPY_THRESHOLD {
961                    return Some((token, "high-entropy-token"));
962                }
963            }
964
965            // Step 5 (#1062): concatenate consecutive pure-hex runs (dropping
966            // separators) and re-check against HEX_CREDENTIAL_LENGTHS — catches a
967            // hex payload split into multiple sub-floor runs. See doc.
968            if !vcs_reference_exempt && contains_normalized_hex_credential(token) {
969                return Some((token, "hex-credential-token"));
970            }
971
972            // Step 6 (#1062, Unicode variant): bridge fragments split across non-ASCII
973            // tokenizer delimiters (e.g. U+200B) via `bridge_fragment_chain`, which walks
974            // both directions across a bounded chain (MAX_BRIDGE_FRAGMENTS,
975            // MAX_BRIDGE_GLUE_TOKENS) rather than one adjacent pair — see
976            // docs/api/secret_gate.md#check_entropy_heuristic--per-token-flagging-sequence
977            // for the exact guarantee and its accepted residual (same-uid-host) limits.
978            if !vcs_reference_exempt && tokens.len() > 1 {
979                let fragments = bridge_fragment_chain(&tokens, text, idx);
980                if fragments.len() > 1 {
981                    let hex_probe = fragments.join(" ");
982                    if contains_normalized_hex_credential(&hex_probe) {
983                        return Some((token, "hex-credential-token"));
984                    }
985                    let concatenated: String = fragments.concat();
986                    if concatenated.len() >= MIN_ENTROPY_LEN
987                        && concatenated.bytes().all(|b| b.is_ascii_alphanumeric())
988                        && shannon_entropy(concatenated.as_bytes()) >= ENTROPY_THRESHOLD
989                    {
990                        return Some((token, "high-entropy-token"));
991                    }
992                }
993            }
994
995            if is_plausible_file_path(token)
996                && !has_clause_credential_label(
997                    text,
998                    token_offset,
999                    raw_token,
1000                    ClauseValueKind::FilePath,
1001                )
1002            {
1003                continue;
1004            }
1005        }
1006
1007        // Step 8: structured-identifier exemption, off-trigger only. Must run after the
1008        // UUID/hex checks and before the entropy computation (an identifier can exceed
1009        // ENTROPY_THRESHOLD on Shannon entropy alone).
1010        if !near_trigger && is_structured_identifier(token) {
1011            continue;
1012        }
1013
1014        let entropy = shannon_entropy(token.as_bytes());
1015        if entropy < ENTROPY_THRESHOLD {
1016            continue;
1017        }
1018
1019        // High-entropy token in trigger context — flag it.
1020        if near_trigger {
1021            return Some((token, "high-entropy-token"));
1022        }
1023    }
1024    None
1025}
1026
1027/// `true` when every byte of `run` is an ASCII hex digit. The
1028/// no-minimum-length, no-`0x`-prefix building block for
1029/// [`contains_normalized_hex_credential`]'s intra-token run decomposition.
1030/// Unlike [`is_pure_hex`] this has no 8-char floor of its own — a legitimate
1031/// credential split across separators can leave a shorter individual run
1032/// that still must sum correctly with its neighbors.
1033fn is_hex_run(run: &str) -> bool {
1034    !run.is_empty() && run.bytes().all(|b| b.is_ascii_hexdigit())
1035}
1036
1037const VCS_MARKERS: &[&str] = &["commit", "revision", "rev", "sha"];
1038
1039/// Marker-word form of a VCS reference: `raw_token` is itself a bare marker
1040/// and the next token in `text` is a 40-hex value.
1041fn is_vcs_marker_before_hex(text: &str, raw_token: &str) -> bool {
1042    let token = wrapper_strip_repeated(raw_token);
1043    let marker = strip_delimiters(token);
1044    if !VCS_MARKERS
1045        .iter()
1046        .any(|candidate| marker.eq_ignore_ascii_case(candidate))
1047    {
1048        return false;
1049    }
1050    let raw_offset = raw_token.as_ptr() as usize - text.as_ptr() as usize;
1051    let next = text[raw_offset + raw_token.len()..].trim_start();
1052    let next = wrapper_strip_repeated(extract_token(next));
1053    next.len() == 40 && next.bytes().all(|b| b.is_ascii_hexdigit())
1054}
1055
1056fn is_git_revision_reference(text: &str, token_offset: usize, raw_token: &str) -> bool {
1057    const MARKERS: &[&str] = VCS_MARKERS;
1058
1059    let token = wrapper_strip_repeated(raw_token);
1060    if is_vcs_marker_before_hex(text, raw_token) {
1061        return true;
1062    }
1063
1064    if token.len() == 40 && token.bytes().all(|b| b.is_ascii_hexdigit()) {
1065        let marker = trailing_identifier(&text[..token_offset]);
1066        return MARKERS
1067            .iter()
1068            .any(|candidate| marker.eq_ignore_ascii_case(candidate));
1069    }
1070
1071    let Some((label, value)) = token.rsplit_once(':') else {
1072        return false;
1073    };
1074    let label = wrapper_strip_repeated(label);
1075    let value = wrapper_strip_repeated(value);
1076    MARKERS
1077        .iter()
1078        .any(|candidate| label.eq_ignore_ascii_case(candidate))
1079        && value.len() == 40
1080        && value.bytes().all(|b| b.is_ascii_hexdigit())
1081}
1082
1083fn trailing_identifier(text: &str) -> &str {
1084    let trimmed = text.trim_end_matches(|c: char| !c.is_ascii_alphanumeric() && c != '_');
1085    trimmed
1086        .rsplit(|c: char| !c.is_ascii_alphanumeric() && c != '_')
1087        .next()
1088        .unwrap_or_default()
1089}
1090
1091/// Words the clause walk in [`has_clause_credential_label`] steps over when
1092/// searching backwards for a credential label. Connectors are the words that
1093/// commonly sit between a label and its value in natural assignment prose
1094/// ("api key value is X", "the token was X"); the VCS coordinate markers are
1095/// included so the marker itself cannot shield an earlier label from the
1096/// walk ("api key value is commit <hex>"); prepositions, determiners, and
1097/// possessives are the glue of noun-compound label qualifiers ("api key for
1098/// our production deploy: X") and carry no content of their own.
1099const LABEL_CLAUSE_SKIP_WORDS: &[&str] = &[
1100    "commit",
1101    "revision",
1102    "rev",
1103    "sha",
1104    "is",
1105    "was",
1106    "are",
1107    "were",
1108    "be",
1109    "been",
1110    "being",
1111    "value",
1112    "values",
1113    "the",
1114    "a",
1115    "an",
1116    "this",
1117    "that",
1118    "it",
1119    "its",
1120    "as",
1121    "here",
1122    "now",
1123    "currently",
1124    "equals",
1125    "for",
1126    "of",
1127    "to",
1128    "in",
1129    "on",
1130    "at",
1131    "by",
1132    "with",
1133    "from",
1134    "per",
1135    "and",
1136    "or",
1137    "our",
1138    "my",
1139    "your",
1140    "their",
1141];
1142
1143/// Maximum identifiers the clause walk examines. Bounds the scan cost to one
1144/// short assignment clause. Exhausting the budget is NOT evidence of absence:
1145/// when a value delimiter was crossed, running out of steps fails CLOSED
1146/// (treated as credential-labeled) — a truncated scan cannot prove the clause
1147/// is unlabeled, and any exhaustion-fails-open rule re-admits the labeled
1148/// value bypass one natural word past the budget. Sized so a label separated
1149/// from its value by connectors plus a dotted version qualifier ("api key
1150/// v1.2 value is commit <hex>" — the version costs two identifier steps)
1151/// stays in range without exhaustion.
1152const LABEL_CLAUSE_WALK_LIMIT: usize = 8;
1153
1154/// File-path candidates may walk across at most this many content identifiers
1155/// without a `:`/`=` delimiter. Two reaches the direct-label shapes that need
1156/// protection (`auth scanner found <path>`) while keeping the walk local.
1157const FILE_PATH_NO_DELIMITER_CONTENT_LIMIT: usize = 2;
1158
1159/// The two narrow trigger-context exemptions need different no-delimiter
1160/// behavior. VCS coordinates preserve the strict prose guard that keeps
1161/// `the key changes are in commit <sha>` readable; file paths admit the
1162/// bounded bridge above so a short label cannot disguise a credential value.
1163#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1164enum ClauseValueKind {
1165    VcsReference,
1166    FilePath,
1167}
1168
1169/// Sentence/paragraph boundary inside a clause-walk gap. `;`, `!`, `?`, and
1170/// blank lines always end the clause. `.` ends it only when it is not
1171/// immediately followed by an alphanumeric character: a dot tight between
1172/// identifier fragments ("v1.2") is intra-token punctuation, while a dot at
1173/// the end of the gap abuts the next identifier (gaps end where the adjacent
1174/// identifier begins) and is likewise intra-token.
1175fn gap_has_sentence_boundary(gap: &str) -> bool {
1176    if gap.contains("\n\n") || gap.contains("\r\n\r\n") || gap.contains([';', '!', '?']) {
1177        return true;
1178    }
1179    let bytes = gap.as_bytes();
1180    bytes.iter().enumerate().any(|(i, b)| {
1181        *b == b'.'
1182            && bytes
1183                .get(i + 1)
1184                .is_some_and(|next| !next.is_ascii_alphanumeric())
1185    })
1186}
1187
1188/// Version-shaped identifier fragment ("2", "v1", "12") — the pieces a dotted
1189/// version qualifier like `v1.2` splits into under identifier extraction.
1190/// Treated as connector material so a versioned label ("api key v1.2 value
1191/// is …") stays reachable.
1192fn is_version_fragment(word: &str) -> bool {
1193    let digits = word
1194        .strip_prefix('v')
1195        .or_else(|| word.strip_prefix('V'))
1196        .unwrap_or(word);
1197    !digits.is_empty() && digits.bytes().all(|b| b.is_ascii_digit())
1198}
1199
1200/// Hex-run identifier long enough to be credential material rather than a
1201/// word ("0123456789abcdef01234567"). Treated as connector material by the
1202/// clause walk: a separator-split payload fragment sitting between the
1203/// candidate value and its label is value material, not a label word that
1204/// ends the clause.
1205fn is_hex_fragment_word(word: &str) -> bool {
1206    word.len() >= 12 && word.bytes().all(|b| b.is_ascii_hexdigit())
1207}
1208
1209/// Allocation-free case-insensitive substring search for ASCII identifiers.
1210fn contains_ascii_case_insensitive(haystack: &str, needle: &str) -> bool {
1211    haystack
1212        .as_bytes()
1213        .windows(needle.len())
1214        .any(|window| window.eq_ignore_ascii_case(needle.as_bytes()))
1215}
1216
1217/// A trailing identifier can contain only ASCII alphanumerics and `_`, so
1218/// splitting on `_` exactly preserves the bare-trigger boundary rule used by
1219/// [`contains_bounded_word`] without allocating a lowercase copy.
1220fn clause_label_has_credential_trigger(label: &str) -> bool {
1221    label.eq_ignore_ascii_case("token")
1222        || COMPOUND_TRIGGER_WORDS
1223            .iter()
1224            .any(|trigger| contains_ascii_case_insensitive(label, trigger))
1225        || label.split('_').any(|part| {
1226            TRIGGER_WORDS
1227                .iter()
1228                .any(|trigger| part.eq_ignore_ascii_case(trigger))
1229        })
1230}
1231
1232fn is_label_clause_skip_word(label: &str) -> bool {
1233    LABEL_CLAUSE_SKIP_WORDS
1234        .iter()
1235        .any(|word| label.eq_ignore_ascii_case(word))
1236}
1237
1238/// Words ending in the byte sequence `ed` are only a cheap proxy for a
1239/// regular English participle. Keep known lexical false matches explicit so
1240/// a noun such as `hundred` cannot become evidence that a credential label is
1241/// merely narrative prose. Irregular forms such as `found` deliberately do
1242/// not qualify: they must not shield `api key found <value>`.
1243fn is_clause_narrative_participle(label: &str) -> bool {
1244    const NON_PARTICIPLE_ED_WORDS: &[&str] = &["hundred"];
1245
1246    label.len() >= 5
1247        && label
1248            .get(label.len().saturating_sub(2)..)
1249            .is_some_and(|suffix| suffix.eq_ignore_ascii_case("ed"))
1250        && !NON_PARTICIPLE_ED_WORDS
1251            .iter()
1252            .any(|word| label.eq_ignore_ascii_case(word))
1253}
1254
1255/// Cheap regular-gerund proxy used only after the no-delimiter file-path walk
1256/// has crossed an explicit `in` on the value side (`api_key handling in
1257/// <path>`). Adjacency alone is never narrative evidence: `api key handling
1258/// <value>` must keep walking to the direct credential label.
1259fn is_clause_narrative_gerund(label: &str) -> bool {
1260    label.len() >= 6
1261        && label
1262            .get(label.len().saturating_sub(3)..)
1263            .is_some_and(|suffix| suffix.eq_ignore_ascii_case("ing"))
1264}
1265
1266/// `true` when the candidate token sits in credential-value syntax: an inline
1267/// credential shape on the token itself, or a credential label reachable by
1268/// walking backwards through the current clause. The walk steps over
1269/// [`LABEL_CLAUSE_SKIP_WORDS`], version fragments, and long hex fragments,
1270/// and stops at a sentence/paragraph boundary (see
1271/// [`gap_has_sentence_boundary`]) — a label on the far side of a boundary is
1272/// prose context, not this value's label. Crossing a value delimiter (`:` or
1273/// `=`, including one attached to a VCS marker: "deploy sha: <hex>" is still
1274/// assignment syntax) additionally lets the walk step over content words
1275/// outside those sets, bounded only by [`LABEL_CLAUSE_WALK_LIMIT`], the
1276/// sentence boundary, and the past-participle stop: "label with qualifiers:
1277/// value" names the value regardless of how many qualifier nouns the label
1278/// carries ("api key for production deploy: X", "api key for shared
1279/// encrypted deploy: X"). A per-clause content-word cap was tried here and
1280/// removed — any cap re-admits the labeled-value bypass one natural
1281/// qualifier past the cap. For the same reason, exhausting the walk budget
1282/// after crossing a delimiter fails CLOSED: the clause is assignment-shaped
1283/// and its head was never scanned, so it is treated as credential-labeled.
1284/// A regular past-participle content word ("flagged", "introduced") ends the walk —
1285/// verb-phrase prose narrates an action on the value rather than labeling it
1286/// ("the auth scanner flagged this file: <path>", "one extra token was
1287/// introduced by sha: <hex>"). Coordinating conjunctions are transparent to
1288/// that position test — "shared and encrypted deploy" keeps both participles
1289/// in adjective position. Without a delimiter, VCS references step over only
1290/// the closed connector sets, preserving ordinary prose such as "the key
1291/// changes are in commit <hex>". File paths additionally step over at most
1292/// [`FILE_PATH_NO_DELIMITER_CONTENT_LIMIT`] content words, closing direct
1293/// label shapes such as "auth scanner found <path>" without broadening the
1294/// VCS tier.
1295fn has_clause_credential_label(
1296    text: &str,
1297    token_offset: usize,
1298    raw_token: &str,
1299    value_kind: ClauseValueKind,
1300) -> bool {
1301    if has_inline_credential_trigger(raw_token) {
1302        return true;
1303    }
1304
1305    let mut rest = &text[..token_offset];
1306    let mut crossed_value_delimiter = false;
1307    let mut no_delimiter_content_words = 0usize;
1308    // Whether the previously processed identifier (the one nearer the value)
1309    // was the literal preposition `in`. This starts false deliberately:
1310    // adjacency to the value must not make a gerund narrative evidence.
1311    let mut arrived_through_in_preposition = false;
1312    // Whether the previously processed identifier (the one nearer the value)
1313    // was connector material. Starts true: step 0 is adjacent to the value or
1314    // its delimiter.
1315    let mut arrived_through_connector = true;
1316    for step in 0..LABEL_CLAUSE_WALK_LIMIT {
1317        let label = trailing_identifier(rest);
1318        if label.is_empty() {
1319            return false;
1320        }
1321        let gap = &rest[label.as_ptr() as usize - rest.as_ptr() as usize + label.len()..];
1322        if step > 0 && gap_has_sentence_boundary(gap) {
1323            return false;
1324        }
1325        if gap.contains([':', '=']) {
1326            crossed_value_delimiter = true;
1327        }
1328        if clause_label_has_credential_trigger(label) {
1329            return true;
1330        }
1331        let skippable = is_label_clause_skip_word(label)
1332            || is_version_fragment(label)
1333            || is_hex_fragment_word(label);
1334        if !skippable {
1335            // This barrier applies to delimiter-bearing clauses and to the
1336            // bounded file-path bridge. It intentionally recognizes regular
1337            // `-ed` forms only: `found` is a bridge word, not a narrative
1338            // shield for a direct credential label.
1339            let no_delimiter_file_path_narrative = !crossed_value_delimiter
1340                && value_kind == ClauseValueKind::FilePath
1341                && arrived_through_in_preposition
1342                && is_clause_narrative_gerund(label);
1343            // Delimiter-bearing clauses and VCS coordinates preserve their
1344            // existing direct-participle semantics. A no-delimiter file path
1345            // must first process real value-side context: the synthetic
1346            // initial connector state alone cannot let `api key leaked
1347            // <value>` stop before reaching the trigger.
1348            let regular_participle_narrative = is_clause_narrative_participle(label)
1349                && (crossed_value_delimiter || value_kind != ClauseValueKind::FilePath || step > 0);
1350            if arrived_through_connector
1351                && (regular_participle_narrative || no_delimiter_file_path_narrative)
1352            {
1353                return false;
1354            }
1355            if !crossed_value_delimiter {
1356                if value_kind != ClauseValueKind::FilePath
1357                    || no_delimiter_content_words >= FILE_PATH_NO_DELIMITER_CONTENT_LIMIT
1358                {
1359                    return false;
1360                }
1361                no_delimiter_content_words += 1;
1362            }
1363        }
1364        // Coordinating conjunctions are transparent to participle-position
1365        // classification: in "shared and encrypted deploy" the coordination
1366        // as a whole is followed by a content noun, so "shared" is still an
1367        // adjective — the conjunction preserves the arrived state instead of
1368        // marking connector position.
1369        if !label.eq_ignore_ascii_case("and") && !label.eq_ignore_ascii_case("or") {
1370            arrived_through_connector = skippable;
1371        }
1372        arrived_through_in_preposition = label.eq_ignore_ascii_case("in");
1373        let start = label.as_ptr() as usize - rest.as_ptr() as usize;
1374        rest = &rest[..start];
1375    }
1376    // Budget exhausted. A clause that crossed a value delimiter and ran out
1377    // of steps without a sentence boundary or verb-position participle is
1378    // assignment-shaped with an unscanned head — fail closed rather than let
1379    // clause length launder a labeled credential into the exemptions.
1380    crossed_value_delimiter
1381}
1382
1383fn is_plausible_file_path(token: &str) -> bool {
1384    let token = token.trim_start_matches(|c: char| {
1385        matches!(
1386            c,
1387            '"' | '\'' | '`' | '(' | ')' | '[' | ']' | '{' | '}' | ',' | ';'
1388        )
1389    });
1390    let token = token.trim_end_matches(|c: char| {
1391        matches!(
1392            c,
1393            '"' | '\'' | '`' | '(' | ')' | '[' | ']' | '{' | '}' | ',' | ';' | '.'
1394        )
1395    });
1396    let path = if let Some(angle_path) = token.strip_prefix('<') {
1397        let Some(close) = angle_path.rfind('>') else {
1398            return false;
1399        };
1400        if !is_line_location_suffix(&angle_path[close + 1..]) {
1401            return false;
1402        }
1403        &angle_path[..close]
1404    } else if let Some((path, suffix)) = token.rsplit_once(':') {
1405        if is_line_location_suffix(suffix) {
1406            path
1407        } else {
1408            token
1409        }
1410    } else {
1411        token
1412    };
1413
1414    if path.contains("://")
1415        || !path.contains('/')
1416        || !path
1417            .bytes()
1418            .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'/' | b'.' | b'_' | b'-' | b'~'))
1419    {
1420        return false;
1421    }
1422
1423    let segment_count = path
1424        .split('/')
1425        .filter(|segment| !segment.is_empty())
1426        .count();
1427    segment_count >= 2 || (path.starts_with('/') && segment_count == 1)
1428}
1429
1430fn is_line_location_suffix(suffix: &str) -> bool {
1431    if suffix.is_empty() {
1432        return true;
1433    }
1434    let suffix = suffix.strip_prefix(':').unwrap_or(suffix);
1435    let suffix = suffix.strip_prefix('~').unwrap_or(suffix);
1436    let mut parts = suffix.split('-');
1437    let Some(start) = parts.next() else {
1438        return false;
1439    };
1440    !start.is_empty()
1441        && start.bytes().all(|b| b.is_ascii_digit())
1442        && parts
1443            .next()
1444            .is_none_or(|end| !end.is_empty() && end.bytes().all(|b| b.is_ascii_digit()))
1445        && parts.next().is_none()
1446}
1447
1448/// `true` when concatenating consecutive pure-hex runs in `token` — splitting
1449/// on every non-alphanumeric character and dropping the separators
1450/// themselves — reaches one of [`HEX_CREDENTIAL_LENGTHS`].
1451///
1452/// Closes the separator-dilution bypass (#1062) where a credential-length
1453/// hex payload is spread across multiple runs each individually below
1454/// [`MIN_ENTROPY_LEN`]: `0123456789abcdef0123/456789abcdef01234567` is two
1455/// 20-char hex runs that never individually reach 24 chars or a
1456/// credential-length boundary, but normalize to one 40-char hex sequence.
1457/// A non-hex, non-empty run resets the running sum — this only bridges
1458/// ADJACENT hex runs, not hex fragments scattered across unrelated filler.
1459fn contains_normalized_hex_credential(token: &str) -> bool {
1460    let mut concatenated_len = 0usize;
1461    for run in token.split(|c: char| !c.is_ascii_alphanumeric()) {
1462        if run.is_empty() {
1463            continue;
1464        }
1465        if is_hex_run(run) {
1466            concatenated_len += run.len();
1467            if HEX_CREDENTIAL_LENGTHS.contains(&concatenated_len) {
1468                return true;
1469            }
1470        } else {
1471            concatenated_len = 0;
1472        }
1473    }
1474    false
1475}
1476
1477/// `true` when the gap `text[gap_start..gap_end]` between two adjacent
1478/// tokenizer tokens holds no ASCII alphanumeric character — the shape a
1479/// tokenizer-delimiting separator (ASCII whitespace, or a non-ASCII
1480/// character such as U+200B; see the tokenizer comment in
1481/// [`check_entropy_heuristic`]) leaves behind when it splits one credential
1482/// payload into two tokens. Deliberately UNBOUNDED on gap byte length
1483/// (#1062: a byte-length bound here is defeated outright by
1484/// repeating the delimiter character) — [`bridge_fragment_chain`] is what
1485/// keeps the overall reconstruction bounded, via [`MAX_BRIDGE_FRAGMENTS`],
1486/// not this check. This still never bridges tokens separated by a genuine
1487/// word or sentence: any real word in the gap contains an ASCII alphanumeric
1488/// character and fails the check immediately.
1489fn adjacent_gap_is_bridgeable(text: &str, gap_start: usize, gap_end: usize) -> bool {
1490    gap_end >= gap_start && !text[gap_start..gap_end].contains(|c: char| c.is_ascii_alphanumeric())
1491}
1492
1493/// `true` when `s` is shaped like a plausible FRAGMENT of a separator-split
1494/// credential: alphanumeric-only and at least [`MIN_BRIDGE_FRAGMENT_LEN`]
1495/// bytes. Shared by the short-token anchor-admission check in
1496/// [`check_entropy_heuristic`] and by [`bridge_fragment_chain`]'s outward
1497/// walk. A long anchor can reach reconstruction without satisfying this
1498/// shape, but every neighboring fragment merged into its chain must satisfy
1499/// it. This stops the walk at a short trigger/glue word (`key`, `api`, `for`)
1500/// sitting immediately beside the real fragments (#1062).
1501fn is_bridge_fragment_shape(s: &str) -> bool {
1502    s.len() >= MIN_BRIDGE_FRAGMENT_LEN && s.bytes().all(|b| b.is_ascii_alphanumeric())
1503}
1504
1505/// `true` when `s` holds no ASCII alphanumeric character at all — the same
1506/// predicate [`adjacent_gap_is_bridgeable`] applies to the byte-range GAP
1507/// between two tokenizer tokens, applied here to a tokenizer TOKEN itself
1508/// (`s` is always non-empty: the tokenizer filters empty tokens). A
1509/// delimiter-only token such as `---` sitting between two Unicode-separator
1510/// gaps (#1062) carries none of a credential's own
1511/// characters — it is exactly as transparent to reconstruction as the
1512/// surrounding whitespace/Unicode gaps are, so [`bridge_fragment_chain`]
1513/// treats it as glue to walk across, not as a chain-terminating non-fragment
1514/// token. A token can never be both this and [`is_bridge_fragment_shape`]:
1515/// the latter requires only alphanumeric bytes, this requires none.
1516fn is_delimiter_only_token(s: &str) -> bool {
1517    !s.bytes().any(|b| b.is_ascii_alphanumeric())
1518}
1519
1520/// Looks outward from `tokens[edge]` in `dir` (`-1` = toward index 0, `+1` =
1521/// toward the end) for the next [`is_bridge_fragment_shape`] token, walking
1522/// transparently across up to [`MAX_BRIDGE_GLUE_TOKENS`] consecutive
1523/// [`is_delimiter_only_token`] glue tokens along the way. Every gap crossed
1524/// — including the ones on either side of a glue token — must be
1525/// [`adjacent_gap_is_bridgeable`]. Returns the found fragment's index, or
1526/// `None` if the walk runs off the end of `tokens`, meets a token that is
1527/// neither a fragment nor glue, meets a non-bridgeable gap, or exhausts the
1528/// glue budget before finding a fragment.
1529fn probe_bridge_fragment(
1530    tokens: &[(usize, &str)],
1531    text: &str,
1532    edge: usize,
1533    dir: isize,
1534) -> Option<usize> {
1535    let mut i = edge;
1536    let mut glue_skipped = 0usize;
1537    loop {
1538        let next_i = i.checked_add_signed(dir)?;
1539        if next_i >= tokens.len() {
1540            return None;
1541        }
1542        let (lo, hi) = if dir < 0 { (next_i, i) } else { (i, next_i) };
1543        let (lo_offset, lo_raw) = tokens[lo];
1544        let (hi_offset, _) = tokens[hi];
1545        let gap_start = lo_offset + lo_raw.len();
1546        if !adjacent_gap_is_bridgeable(text, gap_start, hi_offset) {
1547            return None;
1548        }
1549        let candidate = strip_delimiters(tokens[next_i].1);
1550        if is_bridge_fragment_shape(candidate) {
1551            return Some(next_i);
1552        }
1553        if is_delimiter_only_token(candidate) && glue_skipped < MAX_BRIDGE_GLUE_TOKENS {
1554            glue_skipped += 1;
1555            i = next_i;
1556            continue;
1557        }
1558        return None;
1559    }
1560}
1561
1562/// Reconstructs the bounded chain of tokenizer fragments containing
1563/// `tokens[anchor_idx]`, by walking outward in both directions via
1564/// [`probe_bridge_fragment`] until the chain has reached
1565/// [`MAX_BRIDGE_FRAGMENTS`] real fragments or neither direction can extend
1566/// further. Returns each REAL fragment's [`strip_delimiters`]-ed body, in
1567/// document order, for the caller to recombine — any delimiter-only glue
1568/// tokens absorbed along the way (#1062) are dropped from the
1569/// result entirely, so a caller joining fragments with a space
1570/// ([`contains_normalized_hex_credential`]) or concatenating them directly
1571/// (the generic entropy check) sees only the genuine fragments, exactly as
1572/// if the glue were more gap. Extends both directions every iteration so a
1573/// credential split with fragments on both sides of the anchor (e.g. the
1574/// anchor is the MIDDLE fragment of a three-way split) is fully
1575/// reconstructed, not just one side of it. A length-1 result means no
1576/// extension was possible — callers should skip further work in that case.
1577/// The anchor itself is included without a fragment-shape check; only outward
1578/// extensions are admitted through [`probe_bridge_fragment`].
1579fn bridge_fragment_chain<'a>(
1580    tokens: &[(usize, &'a str)],
1581    text: &str,
1582    anchor_idx: usize,
1583) -> Vec<&'a str> {
1584    let mut start = anchor_idx;
1585    let mut end = anchor_idx;
1586    let mut fragment_count = 1usize;
1587
1588    loop {
1589        let mut extended = false;
1590        if fragment_count < MAX_BRIDGE_FRAGMENTS && start > 0 {
1591            if let Some(new_start) = probe_bridge_fragment(tokens, text, start, -1) {
1592                start = new_start;
1593                fragment_count += 1;
1594                extended = true;
1595            }
1596        }
1597        if fragment_count < MAX_BRIDGE_FRAGMENTS && end + 1 < tokens.len() {
1598            if let Some(new_end) = probe_bridge_fragment(tokens, text, end, 1) {
1599                end = new_end;
1600                fragment_count += 1;
1601                extended = true;
1602            }
1603        }
1604        if !extended {
1605            break;
1606        }
1607    }
1608
1609    tokens[start..=end]
1610        .iter()
1611        .map(|&(_, raw)| strip_delimiters(raw))
1612        .filter(|stripped| !is_delimiter_only_token(stripped))
1613        .collect()
1614}
1615
1616/// Returns `true` when `low_window` contains `needle` as a standalone word —
1617/// bounded on both sides by a character outside the word-char set (or
1618/// start/end of string) — rather than merely as a substring.
1619/// `underscore_is_word_char` selects the boundary rule the caller needs; see
1620/// `docs/api/secret_gate.md#contains_word` for the two deliberately different
1621/// rules and why each caller needs its own.
1622fn contains_word(low_window: &str, needle: &str, underscore_is_word_char: bool) -> bool {
1623    let is_word_char = |c: char| c.is_ascii_alphanumeric() || (underscore_is_word_char && c == '_');
1624    let mut start = 0;
1625    while let Some(rel) = low_window[start..].find(needle) {
1626        let abs = start + rel;
1627        let before_ok = abs == 0
1628            || low_window[..abs]
1629                .chars()
1630                .next_back()
1631                .is_none_or(|c| !is_word_char(c));
1632        let after_end = abs + needle.len();
1633        let after_ok = after_end >= low_window.len()
1634            || low_window[after_end..]
1635                .chars()
1636                .next()
1637                .is_none_or(|c| !is_word_char(c));
1638        if before_ok && after_ok {
1639            return true;
1640        }
1641        start = abs + needle.len().max(1);
1642    }
1643    false
1644}
1645
1646/// Returns `true` when `low_window` contains the bare trigger word `needle`
1647/// as a standalone word, with underscore treated as a BOUNDARY (see
1648/// [`contains_word`]) — so `secret_key=…`/`auth_token=…`/`signing_key=…`
1649/// still match (on the `secret`/`auth`/`key` half), while pure letter-joined
1650/// collisions like `authorized`/`authentication`/`monkey`/`keyword` do not.
1651fn contains_bounded_word(low_window: &str, needle: &str) -> bool {
1652    contains_word(low_window, needle, false)
1653}
1654
1655/// Returns `true` when a compound credential label begins at an identifier
1656/// boundary. The trailing edge is deliberately unbounded so version suffixes
1657/// and larger underscore-composed labels remain protected.
1658fn contains_compound_trigger(low_text: &str) -> bool {
1659    COMPOUND_TRIGGER_WORDS.iter().any(|needle| {
1660        let mut start = 0;
1661        while let Some(rel) = low_text[start..].find(needle) {
1662            let abs = start + rel;
1663            let before_ok = abs == 0
1664                || low_text[..abs]
1665                    .chars()
1666                    .next_back()
1667                    .is_none_or(|c| !c.is_ascii_alphanumeric());
1668            if before_ok {
1669                return true;
1670            }
1671            start = abs + needle.len();
1672        }
1673        false
1674    })
1675}
1676
1677/// Returns `true` when `text` contains a boundary-delimited credential trigger.
1678fn contains_trigger(text: &str) -> bool {
1679    let low = text.to_ascii_lowercase();
1680    TRIGGER_WORDS
1681        .iter()
1682        .any(|tw| contains_bounded_word(&low, tw))
1683        || contains_compound_trigger(&low)
1684        || has_standalone_token(&low)
1685        || has_token_assignment(&low)
1686        || has_assignment_credential_trigger(&low)
1687}
1688
1689/// Detect a credential-bearing assignment label before an `=` or `:`.
1690///
1691/// The separator may be preceded by whitespace or a JSON quote. Compound
1692/// triggers deliberately retain substring matching inside the label so common
1693/// version suffixes such as `api_keyv2` remain protected.
1694fn has_assignment_credential_trigger(low_text: &str) -> bool {
1695    low_text.char_indices().any(|(index, ch)| {
1696        if !matches!(ch, '=' | ':') {
1697            return false;
1698        }
1699        let before =
1700            low_text[..index].trim_end_matches(|c: char| !c.is_ascii_alphanumeric() && c != '_');
1701        let label = before
1702            .rsplit(|c: char| !c.is_ascii_alphanumeric() && c != '_')
1703            .next()
1704            .unwrap_or_default();
1705        COMPOUND_TRIGGER_WORDS
1706            .iter()
1707            .any(|needle| label.contains(needle))
1708            || TRIGGER_WORDS
1709                .iter()
1710                .any(|tw| contains_bounded_word(label, tw))
1711            || label == "token"
1712    })
1713}
1714
1715/// Detect credential labels embedded in the same whitespace token as a value.
1716///
1717/// The surrounding-context scan deliberately excludes the candidate token so
1718/// a trigger word inside a path cannot make that path self-trigger. Credential
1719/// assignments still need to fire when no whitespace separates label and
1720/// value, including JSON-like forms. Underscore-delimited config identifiers
1721/// without an assignment are retained for compatibility with shapes such as
1722/// `session_secret_<value>`.
1723fn has_inline_credential_trigger(raw_token: &str) -> bool {
1724    let low = raw_token.to_ascii_lowercase();
1725
1726    if has_assignment_credential_trigger(&low) {
1727        return true;
1728    }
1729
1730    !low.contains(['/', '-', '.'])
1731        && low.contains('_')
1732        && (COMPOUND_TRIGGER_WORDS
1733            .iter()
1734            .any(|needle| low.contains(needle))
1735            || TRIGGER_WORDS
1736                .iter()
1737                .any(|tw| contains_bounded_word(&low, tw)))
1738}
1739
1740/// Returns `true` when `low_window` contains the word `token` as a standalone
1741/// word, with underscore treated as a WORD CHARACTER / continuation (see
1742/// [`contains_word`]) — but NOT as part of compound identifiers such as
1743/// `tokenizer`, `token_count`, or `next_token`. This underscore-as-
1744/// continuation rule is deliberately different from
1745/// [`contains_bounded_word`]: `token` alone is not a
1746/// credential trigger (it fires on too many benign technical terms), so it
1747/// needs the narrower, underscore-inclusive standalone-word definition,
1748/// whereas the bare `TRIGGER_WORDS` need underscore-joined compounds like
1749/// `secret_key` to still register.
1750fn has_standalone_token(low_window: &str) -> bool {
1751    contains_word(low_window, "token", true)
1752}
1753
1754/// Returns `true` when `low_window` contains the assignment form `token=` or
1755/// `token:` where the `token` identifier has a word boundary BEFORE it.
1756///
1757/// This is boundary-aware so that compound identifiers like `next_token:` or
1758/// `pagination_token=` do NOT trigger — only a standalone `token=`/`token:`
1759/// at the start of a field name does.
1760///
1761/// Examples that return `true`:  `token=<value>`, `token: <value>`,
1762///   `"token": "<value>"` (JSON key-value pairs).
1763/// Examples that return `false`: `next_token: <value>`,
1764///   `pagination_token=<value>`, `token_count: <value>`.
1765fn has_token_assignment(low_window: &str) -> bool {
1766    let needle = "token";
1767    let mut start = 0;
1768    while let Some(rel) = low_window[start..].find(needle) {
1769        let abs = start + rel;
1770        // Require a word boundary BEFORE `token`.
1771        let before_ok = abs == 0
1772            || low_window[..abs]
1773                .chars()
1774                .next_back()
1775                .is_none_or(|c| !c.is_ascii_alphanumeric() && c != '_');
1776        let after_end = abs + needle.len();
1777        // Require `=` or `:` immediately after `token` (possibly with surrounding
1778        // whitespace or quotes stripped by the time we see the lowercased window).
1779        let after_char = low_window[after_end..].chars().next();
1780        let after_is_assign = matches!(after_char, Some('=') | Some(':'));
1781        if before_ok && after_is_assign {
1782            return true;
1783        }
1784        start = abs + needle.len().max(1);
1785    }
1786    false
1787}
1788
1789// ─── Allowlist helpers ───────────────────────────────────────────────────────
1790
1791/// Returns `true` for pure-hex tokens (case-insensitive, optional `0x`/`0X` prefix,
1792/// 8–128 chars) — git SHAs, checksum digests, uuid-hex without hyphens.
1793///
1794/// This helper is used with context: pure-hex tokens near credential trigger words
1795/// are NOT allowlisted (see `check_entropy_heuristic`).  Only call this function
1796/// when you have already confirmed no trigger context is nearby.
1797fn is_pure_hex(token: &str) -> bool {
1798    let hex_part = token
1799        .strip_prefix("0x")
1800        .or(token.strip_prefix("0X"))
1801        .unwrap_or(token);
1802    hex_part.len() >= 8 && hex_part.len() <= 128 && hex_part.bytes().all(|b| b.is_ascii_hexdigit())
1803}
1804
1805/// Returns `true` for tokens that are unambiguous base64/base64url content
1806/// hashes with an explicit `sha<N>-` prefix (SRI hash, npm lockfile integrity).
1807/// Bare base64 of the same length WITHOUT the prefix is NOT allowlisted — see
1808/// `docs/api/secret_gate.md#is_base64_content_hash` for the full criteria list and
1809/// why the explicit prefix is required.
1810fn is_base64_content_hash(token: &str) -> bool {
1811    // Known vendor prefixes — never allowlist even if they look like base64.
1812    // Includes bare `sk-` to prevent OpenAI-shaped tokens from being allowlisted.
1813    const VENDOR_PREFIXES: &[&str] = &[
1814        "sk-",
1815        "rk_live_",
1816        "fm2_",
1817        "vercel_",
1818        "xoxb-",
1819        "xoxa-",
1820        "xoxp-",
1821        "xoxr-",
1822        "xoxs-",
1823        "ghp_",
1824        "gho_",
1825        "ghu_",
1826        "ghs_",
1827        "ghr_",
1828        "github_pat_",
1829        "AKIA",
1830        "ASIA",
1831        "AGE-SECRET-KEY-",
1832        "FlyV1",
1833    ];
1834    if VENDOR_PREFIXES.iter().any(|p| token.starts_with(p)) {
1835        return false;
1836    }
1837    // Require an explicit SRI `sha[0-9]+-` prefix.  Bare base64 at sha-length
1838    // is NOT allowlisted — it is indistinguishable from a real API token.
1839    let body = if let Some(rest) = token.strip_prefix("sha") {
1840        // rest starts with digits followed by '-'
1841        let dash = rest.find('-').unwrap_or(rest.len());
1842        let digits = &rest[..dash];
1843        if !digits.is_empty() && digits.bytes().all(|b| b.is_ascii_digit()) && dash < rest.len() {
1844            &rest[dash + 1..] // everything after "sha<digits>-"
1845        } else {
1846            return false; // no valid sha<N>- prefix → not a known content hash
1847        }
1848    } else {
1849        return false; // no sha prefix → not allowlisted
1850    };
1851    // Strip optional padding (at most 2 `=`).
1852    let stripped = body.trim_end_matches('=');
1853    let pad_removed = body.len() - stripped.len();
1854    if pad_removed > 2 {
1855        return false;
1856    }
1857    // Accept only SHA-family content-hash lengths (43, 64, 86–88 chars unpadded).
1858    let n = stripped.len();
1859    if n != 43 && n != 64 && !(86..=88).contains(&n) {
1860        return false;
1861    }
1862    // Accept both standard-base64 and URL-safe-base64 alphabets.
1863    stripped
1864        .bytes()
1865        .all(|b| b.is_ascii_alphanumeric() || b == b'+' || b == b'/' || b == b'-' || b == b'_')
1866}
1867
1868/// Structural separators that gate entry into [`is_structured_identifier`]
1869/// (rule 1: the token must contain at least one of these). The actual run
1870/// decomposition (rule 2) splits on every non-alphanumeric character, not
1871/// just these four — see the doc comment on `is_structured_identifier`.
1872const STRUCTURAL_SEPARATORS: [char; 4] = ['/', '-', '_', '.'];
1873
1874/// Largest length a single path/branch/identifier segment (a "run" between
1875/// separators) may have and still be considered word-shaped.
1876const MAX_RUN_LEN: usize = 24;
1877
1878/// Runs whose letter portion is at or below this length skip the
1879/// case-transition-density check: density is not a meaningful signal on very
1880/// short runs (e.g. `R1`, `v2`, `ADR`).
1881const DENSITY_EXEMPT_LETTER_LEN: usize = 4;
1882
1883/// Maximum case-transition density (transitions divided by letter_count - 1)
1884/// a run's letter portion may have and still be considered word-shaped.
1885const MAX_CASE_TRANSITION_DENSITY: f64 = 0.3;
1886
1887/// Returns `true` when `token` is shaped like a file path, branch name, or
1888/// other structured identifier rather than a high-entropy secret (word-shaped
1889/// runs separated by `/`, `-`, `_`, `.`). Exempts from the entropy heuristic
1890/// ONLY outside trigger context — see the module doc and
1891/// `docs/api/secret_gate.md#is_structured_identifier` for the run-shape criteria.
1892fn is_structured_identifier(token: &str) -> bool {
1893    if !token.contains(|c: char| STRUCTURAL_SEPARATORS.contains(&c)) {
1894        return false;
1895    }
1896    let runs: Vec<&str> = token
1897        .split(|c: char| !c.is_ascii_alphanumeric())
1898        .filter(|r| !r.is_empty())
1899        .collect();
1900    runs.len() >= 2 && runs.iter().all(|run| is_word_shaped_run(run))
1901}
1902
1903/// A single run (segment between structural separators) is word-shaped when
1904/// it matches `[A-Za-z]+[0-9]*` or `[0-9]+`, is at most [`MAX_RUN_LEN`] chars,
1905/// and (for the letters-then-digits form) its letter portion has a low
1906/// case-transition density.
1907fn is_word_shaped_run(run: &str) -> bool {
1908    if run.is_empty() || run.len() > MAX_RUN_LEN {
1909        return false;
1910    }
1911    let bytes = run.as_bytes();
1912    if bytes.iter().all(|b| b.is_ascii_digit()) {
1913        return true;
1914    }
1915    let letter_end = bytes
1916        .iter()
1917        .position(|b| !b.is_ascii_alphabetic())
1918        .unwrap_or(bytes.len());
1919    // A run that does not start with a letter, and is not pure digits (ruled
1920    // out above), mixes digits and letters in a shape other than
1921    // letters-then-digits — not word-shaped.
1922    if letter_end == 0 {
1923        return false;
1924    }
1925    // Everything after the leading letters must be digits only (no further
1926    // letters), else the run is not the `[A-Za-z]+[0-9]*` shape.
1927    if !bytes[letter_end..].iter().all(|b| b.is_ascii_digit()) {
1928        return false;
1929    }
1930    case_transition_density_ok(&run[..letter_end])
1931}
1932
1933/// `true` when the case-transition density of `letters` (an all-ASCII-letter
1934/// string) is at or below [`MAX_CASE_TRANSITION_DENSITY`]. A transition is an
1935/// adjacent letter pair where one side is uppercase and the other is not.
1936/// Runs with few enough letters pass automatically (see
1937/// [`DENSITY_EXEMPT_LETTER_LEN`]) since density is noisy on short strings.
1938fn case_transition_density_ok(letters: &str) -> bool {
1939    let chars: Vec<char> = letters.chars().collect();
1940    if chars.len() <= DENSITY_EXEMPT_LETTER_LEN {
1941        return true;
1942    }
1943    let transitions = chars
1944        .windows(2)
1945        .filter(|w| w[0].is_ascii_uppercase() != w[1].is_ascii_uppercase())
1946        .count();
1947    let density = transitions as f64 / (chars.len() - 1) as f64;
1948    density <= MAX_CASE_TRANSITION_DENSITY
1949}
1950
1951/// `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
1952fn is_uuid_canonical(s: &str) -> bool {
1953    let b = s.as_bytes();
1954    if b.len() != 36 {
1955        return false;
1956    }
1957    b[8] == b'-'
1958        && b[13] == b'-'
1959        && b[18] == b'-'
1960        && b[23] == b'-'
1961        && b[..8].iter().all(|c| c.is_ascii_hexdigit())
1962        && b[9..13].iter().all(|c| c.is_ascii_hexdigit())
1963        && b[14..18].iter().all(|c| c.is_ascii_hexdigit())
1964        && b[19..23].iter().all(|c| c.is_ascii_hexdigit())
1965        && b[24..].iter().all(|c| c.is_ascii_hexdigit())
1966}
1967
1968/// Strip common wrapping characters (`"`, `'`, `` ` ``, `:`, `=`) from both ends.
1969fn strip_delimiters(s: &str) -> &str {
1970    s.trim_matches(|c| matches!(c, '"' | '\'' | '`' | ':' | '=' | ',' | ';'))
1971}
1972
1973/// Strip `{}()[]"'.,;` from both ends of `s`, repeatedly (JSON nests one
1974/// wrapper inside another).
1975fn strip_wrappers(s: &str) -> &str {
1976    s.trim_matches(|c: char| {
1977        matches!(
1978            c,
1979            '{' | '}' | '(' | ')' | '[' | ']' | '"' | '\'' | '`' | '.' | ',' | ';'
1980        )
1981    })
1982}
1983
1984fn wrapper_strip_repeated(token: &str) -> &str {
1985    let mut cur = token;
1986    loop {
1987        let next = strip_wrappers(cur);
1988        if next == cur {
1989            return cur;
1990        }
1991        cur = next;
1992    }
1993}
1994
1995/// Yields every candidate value an assignment/wrapper-glued token could
1996/// contain, for the near-trigger UUID/content-hash exact-shape checks only.
1997/// See `docs/api/secret_gate.md#value_candidates` for why every `=`/`:` suffix
1998/// must be tried rather than just the first or last.
1999fn value_candidates(token: &str) -> impl Iterator<Item = &str> {
2000    let cur = wrapper_strip_repeated(token);
2001    std::iter::once(cur).chain(cur.char_indices().filter_map(move |(i, c)| {
2002        if c == '=' || c == ':' {
2003            let after = strip_wrappers(&cur[i + c.len_utf8()..]);
2004            if !after.is_empty() {
2005                return Some(after);
2006            }
2007        }
2008        None
2009    }))
2010}
2011
2012// ─── Utilities ───────────────────────────────────────────────────────────────
2013
2014/// Extract a contiguous token (non-whitespace chars) starting at the beginning of `s`.
2015fn extract_token(s: &str) -> &str {
2016    let end = s
2017        .find(|c: char| c.is_whitespace() || c == '\n' || c == '\r')
2018        .unwrap_or(s.len());
2019    &s[..end]
2020}
2021
2022/// Shannon entropy in bits per character.
2023///
2024/// H = -∑ p_i log2(p_i)
2025fn shannon_entropy(bytes: &[u8]) -> f64 {
2026    if bytes.is_empty() {
2027        return 0.0;
2028    }
2029    let mut counts = [0u32; 256];
2030    for &b in bytes {
2031        counts[b as usize] += 1;
2032    }
2033    let len = bytes.len() as f64;
2034    counts
2035        .iter()
2036        .filter(|&&c| c > 0)
2037        .map(|&c| {
2038            let p = c as f64 / len;
2039            -p * p.log2()
2040        })
2041        .sum()
2042}
2043
2044/// Build a `SecretMatch` from a detector name and the candidate string.
2045///
2046/// The masked excerpt is: first 6 chars + "..." + total length.
2047/// Never includes more than 6 chars of the actual value.
2048fn build_match(detector: &'static str, candidate: &str) -> SecretMatch {
2049    let chars: Vec<char> = candidate.chars().collect();
2050    let preview: String = chars.iter().take(6).collect();
2051    let masked = format!("{}...{}chars", preview, chars.len());
2052    SecretMatch { detector, masked }
2053}
2054
2055// ─── Tests ───────────────────────────────────────────────────────────────────
2056
2057#[cfg(test)]
2058mod tests {
2059    use super::*;
2060
2061    #[test]
2062    fn blocks_aws_akia() {
2063        // FAKE key: prefix is real shape, 16-char suffix invented.
2064        let fake = "AKIAFAKEKEY1234567890";
2065        assert!(scan(fake).is_some(), "AKIA must be caught");
2066        let m = scan(fake).unwrap();
2067        assert_eq!(m.detector, "aws-access-key-id");
2068        // Masked excerpt must not echo the full key.
2069        assert!(
2070            !m.masked.contains("FAKEKEY1234567890"),
2071            "must not echo the secret: {}",
2072            m.masked
2073        );
2074    }
2075
2076    #[test]
2077    fn blocks_aws_asia() {
2078        let fake = "ASIAFAKEKEY00000000000";
2079        let m = scan(fake);
2080        assert!(m.is_some(), "ASIA must be caught");
2081        assert_eq!(m.unwrap().detector, "aws-access-key-id");
2082    }
2083
2084    #[test]
2085    fn blocks_github_ghp() {
2086        // 36 chars total to pass min_len.
2087        let fake = "ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
2088        assert!(scan(fake).is_some(), "ghp_ must be caught");
2089    }
2090
2091    #[test]
2092    fn blocks_github_gho() {
2093        let fake = "gho_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB";
2094        assert!(scan(fake).is_some(), "gho_ must be caught");
2095    }
2096
2097    #[test]
2098    fn blocks_github_pat() {
2099        let fake = "github_pat_AAAAAABBBBBBCCCCCC";
2100        assert!(scan(fake).is_some(), "github_pat_ must be caught");
2101    }
2102
2103    #[test]
2104    fn blocks_openai_sk() {
2105        let fake = "sk-aaaaaabbbbbbccccccddddddeeeeeeffffgg";
2106        assert!(scan(fake).is_some(), "sk- must be caught");
2107    }
2108
2109    #[test]
2110    fn blocks_anthropic_sk_ant() {
2111        let fake = "sk-ant-api03-AAAAAAAAAAAAAAA";
2112        assert!(scan(fake).is_some(), "sk-ant- must be caught");
2113        assert_eq!(scan(fake).unwrap().detector, "anthropic-api-key");
2114    }
2115
2116    #[test]
2117    fn blocks_stripe_live() {
2118        let fake = "sk_live_FAKESTRIPE0000000000000"; // gitleaks:allow
2119        assert!(scan(fake).is_some(), "sk_live_ must be caught");
2120        assert_eq!(scan(fake).unwrap().detector, "stripe-secret-key");
2121    }
2122
2123    #[test]
2124    fn blocks_stripe_restricted() {
2125        let fake = "rk_live_FAKESTRIPE0000000000000"; // gitleaks:allow
2126        assert!(scan(fake).is_some(), "rk_live_ must be caught");
2127        assert_eq!(scan(fake).unwrap().detector, "stripe-restricted-key");
2128    }
2129
2130    #[test]
2131    fn blocks_fly_flyv1() {
2132        let fake = "FlyV1 FAKEFLYTOKEN000000000000000000";
2133        assert!(scan(fake).is_some(), "FlyV1 must be caught");
2134        assert_eq!(scan(fake).unwrap().detector, "fly-token");
2135    }
2136
2137    #[test]
2138    fn blocks_fly_fm2() {
2139        let fake = "fm2_FAKEFLYTOKEN00000000000000000";
2140        assert!(scan(fake).is_some(), "fm2_ must be caught");
2141        assert_eq!(scan(fake).unwrap().detector, "fly-token");
2142    }
2143
2144    #[test]
2145    fn blocks_vercel_token() {
2146        let fake = "vercel_FAKETOKEN00000000000000000";
2147        assert!(scan(fake).is_some(), "vercel_ must be caught");
2148        assert_eq!(scan(fake).unwrap().detector, "vercel-token");
2149    }
2150
2151    #[test]
2152    fn prefix_detectors_allow_lowercase_source_filenames() {
2153        let filename_body = "provider_integration_monitoring_adapter_configuration.py";
2154
2155        for &(_, needle, min_len) in PREFIX_DETECTORS {
2156            let candidate = format!("{needle}{filename_body}");
2157            assert!(
2158                candidate.len() >= min_len,
2159                "negative control must exercise {needle}'s length tier"
2160            );
2161            assert!(
2162                find_prefix_token(&candidate, needle, min_len).is_none(),
2163                "lowercase source filename must not match prefix {needle}: {candidate}"
2164            );
2165            assert!(
2166                check(&candidate).is_ok(),
2167                "lowercase source filename must pass the canonical scanner: {candidate}, got {:?}",
2168                scan(&candidate)
2169            );
2170        }
2171    }
2172
2173    #[test]
2174    fn prefix_detectors_keep_value_shaped_payloads_with_source_suffixes() {
2175        for &(_, needle, min_len) in PREFIX_DETECTORS {
2176            let required_payload_len = min_len.saturating_sub(needle.len()).max(2);
2177            let value_payload = "A1".repeat(required_payload_len.div_ceil(2));
2178            let candidate = format!("{needle}{value_payload}.py");
2179            assert!(
2180                find_prefix_token(&candidate, needle, min_len).is_some(),
2181                "uppercase/digit value evidence must preserve prefix {needle}: {candidate}"
2182            );
2183        }
2184    }
2185
2186    #[test]
2187    fn prefix_detectors_keep_lowercase_single_run_payloads_with_source_suffixes() {
2188        for &(_, needle, min_len) in PREFIX_DETECTORS {
2189            let required_payload_len = min_len.saturating_sub(needle.len()).max(24);
2190            let value_payload = "a".repeat(required_payload_len);
2191            let candidate = format!("{needle}{value_payload}.py");
2192            assert!(
2193                find_prefix_token(&candidate, needle, min_len).is_some(),
2194                "an extension alone must not exempt prefix {needle}: {candidate}"
2195            );
2196        }
2197    }
2198
2199    #[test]
2200    fn allows_vercel_prefixed_source_filename_on_every_scanner_surface() {
2201        let content = "review `vercel_deployment_monitoring_adapter.py` before release";
2202
2203        assert!(check(content).is_ok(), "write gate must allow filename");
2204        assert!(scan(content).is_none(), "scanner must not report filename");
2205        assert_eq!(
2206            mask_secrets(content).as_ref(),
2207            content,
2208            "masking surface must preserve the filename byte-for-byte"
2209        );
2210    }
2211
2212    #[test]
2213    fn blocks_slack_xoxb() {
2214        let fake = "xoxb-FAKE-SLACKTOKEN-000000000000000000000000";
2215        assert!(scan(fake).is_some(), "xoxb- must be caught");
2216        assert_eq!(scan(fake).unwrap().detector, "slack-token");
2217    }
2218
2219    #[test]
2220    fn blocks_pem_private_key() {
2221        // Split the header so the literal detector-trigger string is not present
2222        // verbatim in source — pre-commit's detect-private-key hook would fire.
2223        // The gate detects it at runtime because scan() sees the assembled string.
2224        let header = ["-----BEGIN RSA", " PRIVATE KEY-----"].concat(); // gitleaks:allow
2225        let fake = format!("{}\nMIIEo\u{2026}\n-----END RSA PRIVATE KEY-----", header);
2226        assert!(scan(&fake).is_some(), "PEM private key must be caught");
2227        assert_eq!(scan(&fake).unwrap().detector, "pem-private-key");
2228    }
2229
2230    #[test]
2231    fn blocks_pem_ec_private_key() {
2232        let header = ["-----BEGIN EC", " PRIVATE KEY-----"].concat(); // gitleaks:allow
2233        let fake = format!("{}\nMHQCAQEE\u{2026}\n-----END EC PRIVATE KEY-----", header);
2234        assert!(scan(&fake).is_some(), "EC PEM must be caught");
2235    }
2236
2237    #[test]
2238    fn blocks_age_secret_key() {
2239        // AGE-SECRET-KEY- followed by 59 base32 chars (Bech32m body).
2240        let fake = "AGE-SECRET-KEY-1QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ";
2241        assert!(scan(fake).is_some(), "AGE-SECRET-KEY- must be caught");
2242        assert_eq!(scan(fake).unwrap().detector, "age-secret-key");
2243    }
2244
2245    #[test]
2246    fn blocks_jwt_triple() {
2247        // Synthetic JWT structure: header.payload.signature (no real key).
2248        let fake = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.FAKE_SIG_XXXXXXXXXXXX"; // gitleaks:allow
2249        assert!(scan(fake).is_some(), "JWT triple must be caught");
2250        assert_eq!(scan(fake).unwrap().detector, "jwt");
2251    }
2252
2253    #[test]
2254    fn blocks_url_userinfo() {
2255        let fake = "postgresql://dbuser:S3cr3tP4ss@db.example.com:5432/mydb";
2256        assert!(scan(fake).is_some(), "URL userinfo must be caught");
2257        assert_eq!(scan(fake).unwrap().detector, "url-userinfo");
2258    }
2259
2260    #[test]
2261    fn blocks_and_masks_url_userinfo_with_short_passwords() {
2262        for password in ["a", "ab", "abc"] {
2263            let content = format!(
2264                "gate backend probe failed: postgres://svc:{password}@internal-host refused"
2265            );
2266
2267            let detected = scan(&content).expect("short URL password must be detected");
2268            assert_eq!(detected.detector, "url-userinfo");
2269            assert!(
2270                check(&content).is_err(),
2271                "write gate must block {content:?}"
2272            );
2273            assert_eq!(
2274                bounded_masked_log_text(&content),
2275                "gate backend probe failed: ***MASKED*** refused",
2276                "log boundary must mask {content:?}"
2277            );
2278        }
2279    }
2280
2281    #[test]
2282    fn keeps_url_without_userinfo() {
2283        let content = "gate backend probe failed: postgres://host:8080/path refused";
2284
2285        assert!(check(content).is_ok(), "host:port is not URL userinfo");
2286        assert_eq!(bounded_masked_log_text(content), content);
2287    }
2288
2289    #[test]
2290    fn blocks_and_masks_empty_username_url_passwords() {
2291        // Standard empty-user connection strings: the password is the
2292        // credential whether or not a username precedes the colon.
2293        for password in ["a", "ab", "%40", "密码"] {
2294            let content =
2295                format!("gate backend probe failed: redis://:{password}@internal-host refused");
2296
2297            let detected = scan(&content).expect("empty-username URL password must be detected");
2298            assert_eq!(detected.detector, "url-userinfo");
2299            assert!(
2300                check(&content).is_err(),
2301                "write gate must block {content:?}"
2302            );
2303            assert_eq!(
2304                bounded_masked_log_text(&content),
2305                "gate backend probe failed: ***MASKED*** refused",
2306                "log boundary must mask {content:?}"
2307            );
2308        }
2309    }
2310
2311    #[test]
2312    fn keeps_colon_at_pairs_outside_the_authority() {
2313        // An `@` past the authority boundary is path/query/fragment text,
2314        // not userinfo: `host/a:x@next` must not read as user `host/a` with
2315        // password `x`.
2316        for content in [
2317            "see https://host/a:x@next for details",
2318            "see https://host?time=12:30@zone for details",
2319            "see https://host#frag:1@anchor for details",
2320        ] {
2321            assert!(
2322                check(content).is_ok(),
2323                "path/query/fragment `:`+`@` text is not userinfo: {content:?}"
2324            );
2325            assert_eq!(bounded_masked_log_text(content), content);
2326        }
2327    }
2328
2329    #[test]
2330    fn blocks_high_entropy_near_bearer_word() {
2331        // 32 random-looking base64 chars adjacent to the word "bearer".
2332        let fake = "Bearer token: Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM"; // gitleaks:allow
2333        assert!(
2334            scan(fake).is_some(),
2335            "high-entropy value near 'bearer' must be caught"
2336        );
2337        assert_eq!(scan(fake).unwrap().detector, "high-entropy-token");
2338    }
2339
2340    #[test]
2341    fn blocks_high_entropy_near_secret_word() {
2342        let fake = "secret=Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM"; // gitleaks:allow
2343        assert!(
2344            scan(fake).is_some(),
2345            "high-entropy value near 'secret' must be caught"
2346        );
2347    }
2348
2349    #[test]
2350    fn error_message_masks_secret() {
2351        let fake = "ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
2352        let m = scan(fake).unwrap();
2353        // Masked form: first 6 chars + "...N chars".
2354        // Must NOT contain the full suffix.
2355        let masked = &m.masked;
2356        assert!(
2357            !masked.contains("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"),
2358            "mask must not echo the full secret value; got: {masked}"
2359        );
2360        // Must start with "ghp_AA" (first 6 chars of the token).
2361        assert!(
2362            masked.starts_with("ghp_AA"),
2363            "mask must show first 6 chars; got: {masked}"
2364        );
2365    }
2366
2367    // ── False-positive suite ─────────────────────────────────────────────────
2368
2369    #[test]
2370    fn allows_sha256_hex() {
2371        // 64-char lowercase hex — typical sha256 digest.
2372        let sha = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
2373        assert!(
2374            scan(sha).is_none(),
2375            "sha256 hex must pass (allowlisted); fired: {:?}",
2376            scan(sha)
2377        );
2378    }
2379
2380    #[test]
2381    fn allows_uuid() {
2382        let uuid = "550e8400-e29b-41d4-a716-446655440000";
2383        assert!(
2384            scan(uuid).is_none(),
2385            "UUID must pass; fired: {:?}",
2386            scan(uuid)
2387        );
2388    }
2389
2390    #[test]
2391    fn allows_git_sha() {
2392        // 40-char lowercase git SHA.
2393        let sha = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
2394        assert!(
2395            scan(sha).is_none(),
2396            "git SHA must pass; fired: {:?}",
2397            scan(sha)
2398        );
2399    }
2400
2401    #[test]
2402    fn allows_normal_prose() {
2403        let prose =
2404            "The FlashAttention paper introduces IO-aware tiling for transformer self-attention.";
2405        assert!(scan(prose).is_none(), "normal prose must pass");
2406    }
2407
2408    #[test]
2409    fn allows_code_snippet() {
2410        let code = r#"fn create_entity(name: &str, kind: &str) -> RuntimeResult<Entity> {
2411    self.validate_entity_kind(kind)?;
2412    Ok(Entity::new("local", kind, name))
2413}"#;
2414        assert!(
2415            scan(code).is_none(),
2416            "code snippet must pass; fired: {:?}",
2417            scan(code)
2418        );
2419    }
2420
2421    #[test]
2422    fn allows_long_url_without_credentials() {
2423        let url = "https://docs.example.com/api/v2/entities?kind=concept&limit=100";
2424        assert!(scan(url).is_none(), "URL without userinfo must pass");
2425    }
2426
2427    #[test]
2428    fn allows_base64_image_stub() {
2429        // Realistic short base64 data URI stub — no trigger words, below threshold length.
2430        let b64 = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVQI12NgAAIABQ";
2431        assert!(
2432            scan(b64).is_none(),
2433            "base64 image stub without trigger word must pass; fired: {:?}",
2434            scan(b64)
2435        );
2436    }
2437
2438    #[test]
2439    fn allows_long_plain_url() {
2440        let url = "https://api.github.com/repos/ohdearquant/khive/pulls/76/comments?per_page=100";
2441        assert!(
2442            scan(url).is_none(),
2443            "plain URL must pass; fired: {:?}",
2444            scan(url)
2445        );
2446    }
2447
2448    #[test]
2449    fn allows_manifest_content_hash() {
2450        // A string like what appears in Cargo.lock or npm lockfiles.
2451        let line =
2452            "checksum = \"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\"";
2453        assert!(
2454            scan(line).is_none(),
2455            "manifest content hash line must pass; fired: {:?}",
2456            scan(line)
2457        );
2458    }
2459
2460    #[test]
2461    fn masked_excerpt_format() {
2462        let fake = "AKIAFAKEKEY1234567890";
2463        let m = scan(fake).unwrap();
2464        // Format: first6...Nchars
2465        assert!(m.masked.contains("..."), "masked must contain '...'");
2466        assert!(m.masked.ends_with("chars"), "masked must end with 'chars'");
2467    }
2468
2469    // ── Gate function ────────────────────────────────────────────────────────
2470
2471    #[test]
2472    fn check_returns_ok_for_safe_content() {
2473        assert!(check("A normal memory note about LoRA.").is_ok());
2474    }
2475
2476    #[test]
2477    fn check_returns_err_for_secret() {
2478        let fake = "AKIAFAKEKEY1234567890";
2479        let result = check(fake);
2480        assert!(result.is_err(), "check must fail for AKIA key");
2481        let err = result.unwrap_err();
2482        assert!(
2483            matches!(err, RuntimeError::SecretDetected(_)),
2484            "error variant must be SecretDetected"
2485        );
2486    }
2487
2488    // ── Entropy helpers ──────────────────────────────────────────────────────
2489
2490    #[test]
2491    fn entropy_of_uniform_string_is_zero() {
2492        let s = "aaaaaaaaaaaaaaaa";
2493        assert!(shannon_entropy(s.as_bytes()) < 0.01);
2494    }
2495
2496    #[test]
2497    fn entropy_of_random_bytes_is_high() {
2498        // A truly random-looking string should exceed 4.5 bits/char.
2499        let s = b"X9kZ2vQpLrT8nJwYuAeHfBsDcGiONvM1"; // 32 mixed base64 chars
2500        assert!(shannon_entropy(s) > 4.5, "entropy={}", shannon_entropy(s));
2501    }
2502
2503    #[test]
2504    fn cjk_prose_near_trigger_is_not_flagged() {
2505        // Regression: a multibyte CJK run (~19 chars = 57 bytes) clears the
2506        // byte-length floor, and `shannon_entropy` over UTF-8 bytes reads it as
2507        // high-entropy — so a Chinese title near the `auth` trigger word used to
2508        // false-positive as `high-entropy-token`.  Non-ASCII tokens are now
2509        // skipped by the entropy heuristic: real base64/hex credentials are
2510        // ASCII, so this cannot hide a secret.
2511        let content = "更新 auth 配置数据库连接管理系统核心模块设计文档";
2512        assert!(
2513            check(content).is_ok(),
2514            "CJK prose near a trigger word must not be flagged as a secret"
2515        );
2516    }
2517
2518    #[test]
2519    fn ascii_secret_near_trigger_still_flagged() {
2520        // The non-ASCII skip must NOT weaken detection of genuine ASCII
2521        // high-entropy credentials near a trigger word.
2522        let content = "api_key X9kZ2vQpLrT8nJwYuAeHfBsDcGiONvM1";
2523        assert!(
2524            check(content).is_err(),
2525            "ASCII high-entropy token near a trigger word must still be blocked"
2526        );
2527    }
2528
2529    #[test]
2530    fn ascii_secret_in_cjk_context_does_not_panic_and_is_flagged() {
2531        // The ±120-byte trigger window around an ASCII token can land in the
2532        // middle of a multibyte CJK character when the token is embedded in
2533        // non-Latin prose.  Slicing on a non-char-boundary would panic — the
2534        // window bounds are snapped via `floor_char_boundary`.  Detection of
2535        // the genuine ASCII secret must still fire.
2536        let cjk = "数据库连接管理系统核心模块设计文档".repeat(6); // 17 chars × 6 = 306 bytes
2537                                                                  // The leading single-byte `x` breaks 3-byte CJK alignment so the window
2538                                                                  // start (token_offset - 120) lands mid-character without the snap.
2539        let content = format!("{cjk}x api_key X9kZ2vQpLrT8nJwYuAeHfBsDcGiONvM1 {cjk}");
2540        assert!(
2541            check(&content).is_err(),
2542            "ASCII secret in CJK context must still be blocked (and must not panic)"
2543        );
2544    }
2545
2546    #[test]
2547    fn ascii_secret_glued_to_cjk_is_still_flagged() {
2548        // Regression: a prefixless high-entropy credential glued (no ASCII
2549        // whitespace) to CJK text, CJK brackets/quotes, a fullwidth space, or a
2550        // fullwidth colon used to slip through, because the whole whitespace token
2551        // contained a non-ASCII byte and was skipped wholesale.  Non-ASCII is now
2552        // a token delimiter, so the ASCII credential run is isolated and
2553        // entropy-checked while the surrounding ±120-byte window still sees the
2554        // trigger word.
2555        let secret = "X9kZ2vQpLrT8nJwYuAeHfBsDcGiONvM1"; // gitleaks:allow
2556        let cases = [
2557            format!("api_key {secret}数据"),     // CJK suffix glued to the token
2558            format!("api_key 「{secret}」"),     // CJK brackets wrap the token
2559            format!("api_key {secret}"),        // U+3000 ideographic space separator
2560            format!("api_key:{secret}"),        // U+FF1A fullwidth colon separator
2561            format!("数据{secret}更新 api_key"), // CJK-glued prefix, trigger after
2562        ];
2563        for content in &cases {
2564            assert!(
2565                check(content).is_err(),
2566                "ASCII secret glued to CJK must be blocked: {content:?}"
2567            );
2568        }
2569    }
2570
2571    #[test]
2572    fn high_entropy_ascii_run_without_trigger_is_not_flagged() {
2573        // The non-ASCII-as-delimiter change must not weaken the trigger-context
2574        // discipline: a high-entropy ASCII run isolated from CJK prose but NOT
2575        // near a credential trigger word is still allowed (only the tokenizer
2576        // changed, not the `near_trigger` gate).
2577        let secret = "X9kZ2vQpLrT8nJwYuAeHfBsDcGiONvM1"; // gitleaks:allow
2578        let content = format!("数据库连接{secret}核心模块设计文档");
2579        assert!(
2580            check(&content).is_ok(),
2581            "high-entropy ASCII run with no trigger word must not be flagged"
2582        );
2583    }
2584
2585    #[test]
2586    fn known_prefix_secret_glued_after_cjk_is_still_flagged() {
2587        // A Layer-1 known-prefix secret glued directly after
2588        // CJK prose (no ASCII whitespace) was missed, because the prefix boundary
2589        // check used `is_alphanumeric` — which Rust counts true for CJK — so the
2590        // preceding ideograph was not treated as a delimiter.  These credentials
2591        // must be caught with no nearby ASCII trigger word, on the left side too.
2592        let cases = [
2593            "数据AKIAIOSFODNN7EXAMPLE",             // gitleaks:allow
2594            "令牌github_pat_11ABCDEFG0HIJKLMNOPQR", // gitleaks:allow
2595            "密钥sk-ant-api03-AAAAAAAAAAAAAAAAAA",  // gitleaks:allow
2596            "配置FlyV1 fm2_AAAABBBBCCCCDDDD",       // gitleaks:allow
2597        ];
2598        for content in cases {
2599            assert!(
2600                check(content).is_err(),
2601                "known-prefix secret glued after CJK must be blocked: {content:?}"
2602            );
2603        }
2604    }
2605
2606    #[test]
2607    fn url_userinfo_after_cjk_does_not_panic_and_is_flagged() {
2608        // A credential URL glued after CJK prose panicked,
2609        // because scheme_start was (separator byte index + 1) — one byte into a
2610        // multibyte CJK separator — and the slice fell on a non-char boundary.
2611        // The public check() API must return a controlled error, never panic.
2612        let cases = [
2613            "数据postgresql://dbuser:S3cr3tP4ss@db.example.com/db", // gitleaks:allow
2614            "配置mysql://root:hunter2pw@10.0.0.1:3306/app",         // gitleaks:allow
2615            "连接redis://svc:V3ryS3cretPw@cache.internal:6379",     // gitleaks:allow
2616        ];
2617        for content in cases {
2618            assert!(
2619                check(content).is_err(),
2620                "credential URL after CJK must be blocked, not panic: {content:?}"
2621            );
2622        }
2623    }
2624
2625    #[test]
2626    fn non_ascii_glued_token_trigger_is_still_flagged() {
2627        // `token=`/`token:`/standalone `token` glued directly
2628        // after non-ASCII prose was missed because has_standalone_token /
2629        // has_token_assignment used is_alphanumeric for the word boundary — CJK,
2630        // accented letters, and fullwidth digits all count as alphanumeric in
2631        // Rust, so the preceding char was not seen as a boundary and the `token`
2632        // trigger was suppressed, leaving the high-entropy value unflagged.
2633        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
2634        let blocked = [
2635            format!("数据token={opaque}"),    // CJK + assignment form, ASCII '='
2636            format!("配置token: {opaque}"),   // CJK + assignment form, ASCII ':'
2637            format!("密钥token {opaque}"),    // CJK + standalone-word form
2638            format!("résumétoken: {opaque}"), // accented letter before `token`
2639            format!("1token: {opaque}"),     // fullwidth digit before `token`
2640        ];
2641        for content in &blocked {
2642            assert!(
2643                check(content).is_err(),
2644                "non-ASCII-glued token trigger must flag the value: {content:?}"
2645            );
2646        }
2647        // Compound identifiers stay excluded — the `_` boundary rule is unchanged
2648        // and an ASCII letter before `token` is still a continuation, so these
2649        // (including the pure-ASCII `servicetoken:`) must still pass.
2650        let allowed = [
2651            format!("数据next_token: {opaque}"),
2652            format!("数据token_count: {opaque}"),
2653            format!("servicetoken: {opaque}"),
2654        ];
2655        for content in &allowed {
2656            assert!(
2657                check(content).is_ok(),
2658                "compound token identifier must not be flagged: {content:?}"
2659            );
2660        }
2661    }
2662
2663    #[test]
2664    fn allowlist_passes_sha256() {
2665        // A plain sha256 hex digest passes via `is_pure_hex` (not `is_allowlisted`
2666        // because hex is now context-dependent; this tests the primitive directly).
2667        let sha = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
2668        assert!(is_pure_hex(sha));
2669    }
2670
2671    #[test]
2672    fn allowlist_passes_uuid_canonical() {
2673        assert!(is_uuid_canonical("550e8400-e29b-41d4-a716-446655440000"));
2674    }
2675
2676    #[test]
2677    fn allowlist_does_not_pass_mixed_token() {
2678        // A token that starts with letters but mixes in non-hex chars.
2679        assert!(!is_pure_hex("sk-aaaaaabbbbbbccccccddddddeeeeeeffffgg"));
2680    }
2681
2682    // ── Structured-field gate helpers ────────────────────────────────────────
2683
2684    #[test]
2685    fn check_json_blocks_secret_in_object_value() {
2686        let props = serde_json::json!({ "api_key": "AKIAFAKEKEY1234567890" });
2687        assert!(
2688            check_json(&props).is_err(),
2689            "secret in properties object value must be blocked"
2690        );
2691    }
2692
2693    #[test]
2694    fn check_json_blocks_secret_in_nested_object() {
2695        let props = serde_json::json!({ "credentials": { "token": "sk-proj-FAKEKEY00000000000000000000000000000000" } }); // gitleaks:allow
2696        assert!(
2697            check_json(&props).is_err(),
2698            "secret in nested properties object must be blocked"
2699        );
2700    }
2701
2702    #[test]
2703    fn check_json_blocks_secret_in_array() {
2704        let props = serde_json::json!(["normal", "AKIAFAKEKEY1234567890"]);
2705        assert!(
2706            check_json(&props).is_err(),
2707            "secret in JSON array must be blocked"
2708        );
2709    }
2710
2711    // ── Reserved secret-gate property key (ADR-115 Amendment 1) ─────────────
2712
2713    #[test]
2714    fn reject_reserved_key_passes_absent_properties() {
2715        assert!(reject_reserved_secret_gate_property(None).is_ok());
2716    }
2717
2718    #[test]
2719    fn reject_reserved_key_passes_unrelated_properties() {
2720        let props = serde_json::json!({"name": "value", "tags": ["a", "b"]});
2721        assert!(reject_reserved_secret_gate_property(Some(&props)).is_ok());
2722    }
2723
2724    #[test]
2725    fn reject_reserved_key_passes_non_object_properties() {
2726        // Non-object properties cannot name a top-level key at all.
2727        let props = serde_json::json!("just a string");
2728        assert!(reject_reserved_secret_gate_property(Some(&props)).is_ok());
2729        let arr = serde_json::json!(["a", "b"]);
2730        assert!(reject_reserved_secret_gate_property(Some(&arr)).is_ok());
2731    }
2732
2733    #[test]
2734    fn reject_reserved_key_blocks_top_level_key_creation() {
2735        let props = serde_json::json!({"khive:secret_gate": "exempted:content-sha256-manifest-v1"});
2736        let err = reject_reserved_secret_gate_property(Some(&props)).unwrap_err();
2737        assert!(
2738            matches!(err, RuntimeError::InvalidInput(ref msg) if msg.contains("khive:secret_gate") && msg.contains("runtime-owned")),
2739            "unexpected error: {err:?}"
2740        );
2741    }
2742
2743    #[test]
2744    fn reject_reserved_key_blocks_regardless_of_value_shape() {
2745        // Presence alone is rejected — arbitrary value, null (explicit removal
2746        // shape), and a value that happens to match the real stamp format are
2747        // all rejected identically; a caller can never legitimately write this
2748        // key by any value.
2749        for value in [
2750            serde_json::json!(null),
2751            serde_json::json!(42),
2752            serde_json::json!({"nested": "object"}),
2753            serde_json::json!("exempted:content-sha256-manifest-v1"),
2754        ] {
2755            let props = serde_json::json!({"khive:secret_gate": value});
2756            assert!(
2757                reject_reserved_secret_gate_property(Some(&props)).is_err(),
2758                "must reject value shape: {props:?}"
2759            );
2760        }
2761    }
2762
2763    #[test]
2764    fn reject_reserved_key_allows_nested_non_top_level_occurrence() {
2765        // The same spelling nested inside a value is ordinary content, not a
2766        // posture mutation — only the exact top-level key is reserved.
2767        let props = serde_json::json!({"notes": {"khive:secret_gate": "not-a-stamp"}});
2768        assert!(reject_reserved_secret_gate_property(Some(&props)).is_ok());
2769    }
2770
2771    #[test]
2772    fn reject_reserved_key_blocks_alongside_other_legitimate_keys() {
2773        let props = serde_json::json!({
2774            "name": "value",
2775            "khive:secret_gate": "exempted:content-sha256-manifest-v1",
2776        });
2777        assert!(reject_reserved_secret_gate_property(Some(&props)).is_err());
2778    }
2779
2780    #[test]
2781    fn check_json_passes_safe_properties() {
2782        let props = serde_json::json!({
2783            "domain": "attention",
2784            "status": "researched",
2785            "year": 2024
2786        });
2787        assert!(
2788            check_json(&props).is_ok(),
2789            "normal properties must pass; fired: {:?}",
2790            check_json(&props).err()
2791        );
2792    }
2793
2794    #[test]
2795    fn check_tags_blocks_credential_tag() {
2796        let tags = vec![
2797            "type:concept".to_string(),
2798            "AKIAFAKEKEY1234567890".to_string(),
2799        ];
2800        assert!(
2801            check_tags(&tags).is_err(),
2802            "credential-shaped tag must be blocked"
2803        );
2804    }
2805
2806    #[test]
2807    fn check_tags_passes_normal_tags() {
2808        let tags = vec!["type:concept".to_string(), "domain:attention".to_string()];
2809        assert!(
2810            check_tags(&tags).is_ok(),
2811            "normal tags must pass; fired: {:?}",
2812            check_tags(&tags).err()
2813        );
2814    }
2815
2816    // ── False-positive: sk-learn and scikit-learn slugs ──────────────────────
2817
2818    #[test]
2819    fn allows_sk_learn_prose() {
2820        // scikit-learn slug used as an entity name or knowledge atom.
2821        let texts = &[
2822            "sk-learn is a Python machine learning library",
2823            "sk-learn-compatible transformer pipeline reference",
2824            "sk-learn scikit-learn estimator interface",
2825        ];
2826        for t in texts {
2827            assert!(
2828                scan(t).is_none(),
2829                "sk-learn prose must pass; fired: {:?} on {:?}",
2830                scan(t),
2831                t
2832            );
2833        }
2834    }
2835
2836    #[test]
2837    fn blocks_openai_sk_proj_not_confused_with_sk_learn() {
2838        // Real OpenAI key shape must still be caught.
2839        let fake = "sk-proj-FAKEKEY00000000000000000000000000000000"; // gitleaks:allow
2840        assert!(
2841            scan(fake).is_some(),
2842            "sk-proj- key must still be caught after sk-learn exemption"
2843        );
2844    }
2845
2846    // ── False-positive: SRI / tokenizer hash metadata ────────────────────────
2847
2848    #[test]
2849    fn blocks_sri_hash_near_key_word_accepted_fp() {
2850        // SRI hash as used in HTML integrity attributes (sha384, base64-encoded),
2851        // placed directly beside the trigger word "key". The content-hash
2852        // allowlist is a prose-context exemption, not unconditional: near a
2853        // credential trigger, a sha-prefixed hash falls through to the explicit
2854        // near-trigger content-hash detector like any other high-entropy
2855        // candidate. This is an accepted false positive on a real but rare
2856        // shape (an integrity hash literally next to the word "key").
2857        let line = "integrity key: sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC";
2858        assert!(
2859            scan(line).is_some(),
2860            "SRI hash near trigger word 'key' must now be blocked (accepted FP); passed unexpectedly"
2861        );
2862    }
2863
2864    #[test]
2865    fn allows_base64_tokenizer_hash_metadata() {
2866        // Tokenizer metadata containing a base64 hash near technical keywords.
2867        let line = "tokenizer_vocab_hash: Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM"; // gitleaks:allow
2868        assert!(
2869            scan(line).is_none(),
2870            "tokenizer hash metadata must pass; fired: {:?}",
2871            scan(line)
2872        );
2873    }
2874
2875    #[test]
2876    fn allows_npm_lockfile_integrity() {
2877        // npm lockfile integrity line with sha512 base64url hash (86 base64 chars + ==).
2878        // sha512 digest = 64 bytes → base64 = 88 chars (86 unpadded + ==).
2879        let body_86 = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM1234567890abcdefghijklmnopqrstuvwxABCDEFGHIJKLMNOPQRST";
2880        assert_eq!(body_86.len(), 86, "test body must be exactly 86 chars");
2881        let line = format!(
2882            "resolved: https://registry.npmjs.org/foo/-/foo-1.0.0.tgz\nintegrity: sha512-{body_86}=="
2883        );
2884        assert!(
2885            scan(&line).is_none(),
2886            "npm lockfile integrity must pass; fired: {:?}",
2887            scan(&line)
2888        );
2889    }
2890
2891    // ── False-positive: tokenizer vs token trigger word ─────────────────────
2892
2893    #[test]
2894    fn allows_tokenizer_vocab_hash_no_block() {
2895        // `tokenizer_vocab_hash` contains the substring "token" but NOT as a
2896        // standalone word (followed by 'i' which is alphanumeric), so the
2897        // standalone-token boundary check must not fire here.
2898        let line = "tokenizer_vocab_hash = Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM"; // gitleaks:allow
2899        assert!(
2900            scan(line).is_none(),
2901            "tokenizer_vocab_hash must pass; 'token' is only standalone-word matched; fired: {:?}",
2902            scan(line)
2903        );
2904    }
2905
2906    // ── True-positives: bare base64 at sha-lengths near trigger words ────────
2907
2908    #[test]
2909    fn blocks_bare_base64url_43chars_near_key() {
2910        // A 43-char base64url token (= sha256 body length) near the word "key".
2911        // Without a sha<N>- prefix this MUST be caught, not allowlisted.
2912        let token_43 = "wJalrXUtnFEMI-K7MDENGbPxRfiCYEXAMPLEKEYX123"; // gitleaks:allow
2913        assert_eq!(token_43.len(), 43, "test token must be exactly 43 chars");
2914        let line = format!("api key {token_43}");
2915        assert!(
2916            scan(&line).is_some(),
2917            "43-char base64url token near 'key' must be caught (no sha-prefix = not a hash); fired: {:?}",
2918            scan(&line)
2919        );
2920    }
2921
2922    #[test]
2923    fn blocks_bare_base64url_64chars_near_secret() {
2924        // A 64-char base64url token (= sha384 body length) near "secret".
2925        // Must be caught without sha<N>- prefix.
2926        let token_64 = "wJalrXUtnFEMI-K7MDENGbPxRfiCYEXAMPLEKEYX123wJalrXUtnFEMI-K7MDENa"; // gitleaks:allow
2927        assert_eq!(token_64.len(), 64, "test token must be exactly 64 chars");
2928        let line = format!("secret: {token_64}");
2929        assert!(
2930            scan(&line).is_some(),
2931            "64-char base64url token near 'secret' must be caught; got: {:?}",
2932            scan(&line)
2933        );
2934    }
2935
2936    #[test]
2937    fn blocks_bare_base64url_86chars_near_auth() {
2938        // An 86-char base64url token (= sha512 body length) near "auth".
2939        // Must be caught without sha<N>- prefix.
2940        let token_86 = "wJalrXUtnFEMI-K7MDENGbPxRfiCYEXAMPLEKEYX123wJalrXUtnFEMI-K7MDENwJalrXUtnFEMI-K7MDENabc"; // gitleaks:allow
2941        assert_eq!(token_86.len(), 86, "test token must be exactly 86 chars");
2942        let line = format!("auth header {token_86}");
2943        assert!(
2944            scan(&line).is_some(),
2945            "86-char base64url token near 'auth' must be caught; got: {:?}",
2946            scan(&line)
2947        );
2948    }
2949
2950    // ── True-positives: standalone `token` trigger ───────────────────────────
2951
2952    #[test]
2953    fn blocks_service_token_opaque_value() {
2954        // "service token <opaque-high-entropy>" — `token` as a standalone word
2955        // with a high-entropy value must be caught.
2956        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
2957        assert!(
2958            opaque.len() >= 24,
2959            "opaque must be long enough for entropy check"
2960        );
2961        let line = format!("service token {opaque}");
2962        assert!(
2963            scan(&line).is_some(),
2964            "service token <opaque> must be caught by standalone 'token' check; got: {:?}",
2965            scan(&line)
2966        );
2967    }
2968
2969    #[test]
2970    fn blocks_token_equals_credential() {
2971        // `token=<high-entropy>` (assignment form) must be caught via has_token_assignment.
2972        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
2973        let line = format!("token={opaque}");
2974        assert!(
2975            scan(&line).is_some(),
2976            "token=<value> must be caught via token= trigger; got: {:?}",
2977            scan(&line)
2978        );
2979    }
2980
2981    #[test]
2982    fn blocks_token_colon_credential() {
2983        // `token: <high-entropy>` (key-value form) must be caught via has_token_assignment.
2984        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
2985        let line = format!("token: {opaque}");
2986        assert!(
2987            scan(&line).is_some(),
2988            "token: <value> must be caught via token: trigger; got: {:?}",
2989            scan(&line)
2990        );
2991    }
2992
2993    #[test]
2994    fn allows_next_token_technical_context() {
2995        // `next_token` is a technical term; the high-entropy value here has low
2996        // entropy anyway, so it must pass.
2997        let line = "next_token: cursor-page-2-abcdef12345678";
2998        assert!(
2999            scan(line).is_none(),
3000            "next_token technical context must not be blocked; fired: {:?}",
3001            scan(line)
3002        );
3003    }
3004
3005    // ── Boundary-aware token= / token: (compound identifiers must pass) ─────
3006
3007    #[test]
3008    fn allows_next_token_high_entropy_cursor() {
3009        // `next_token:` with a realistic high-entropy pagination cursor must NOT be
3010        // blocked.  `next_token` has `_token` suffix — not a standalone assignment form.
3011        let cursor = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
3012        let line = format!("next_token: {cursor}");
3013        assert!(
3014            scan(&line).is_none(),
3015            "next_token with high-entropy cursor must pass (compound identifier); fired: {:?}",
3016            scan(&line)
3017        );
3018    }
3019
3020    #[test]
3021    fn allows_token_count_high_entropy() {
3022        // `token_count:` with a high-entropy value must NOT be blocked.
3023        // `token_count` has `token_` prefix — the word boundary after `token` is `_`,
3024        // which is excluded by has_token_assignment.
3025        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
3026        let line = format!("token_count: {opaque}");
3027        assert!(
3028            scan(&line).is_none(),
3029            "token_count with high-entropy value must pass; fired: {:?}",
3030            scan(&line)
3031        );
3032    }
3033
3034    // ── Hex allowlist is not applied when trigger context is present ────────
3035    // Pure hex tops out at log2(16) = 4.0 bits/char, below ENTROPY_THRESHOLD (4.5), so
3036    // the entropy heuristic alone never flags it. The hex allowlist must only apply
3037    // when NOT near a trigger; the tests below guard that ordering.
3038
3039    #[test]
3040    fn hex_near_key_blocked_in_credential_context() {
3041        // A pure-hex 32-char token near "api key" is a credential-shaped hex
3042        // token in trigger context.  Entropy alone cannot flag it (hex max =
3043        // 4.0 < 4.5 threshold), but the explicit hex-credential-token path
3044        // must catch it.
3045        let hex32 = "4f9c2e8a1d3b5c7e9f0a2b4d6e8c0a2b";
3046        assert_eq!(hex32.len(), 32);
3047        let line = format!("api key {hex32}");
3048        assert!(
3049            scan(&line).is_some(),
3050            "32-char pure hex near 'api key' must be blocked; got None"
3051        );
3052    }
3053
3054    #[test]
3055    fn hex_credential_lengths_blocked_near_trigger() {
3056        // Verify all four credential-shaped lengths are caught near a trigger.
3057        let hex40 = "a3f5c2e9d1b8047e63a1f4c2d5b6e8f1a9c3d2e4";
3058        let hex64 = "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b";
3059        let hex128 = format!("{hex64}{hex64}");
3060        assert_eq!(hex40.len(), 40);
3061        assert_eq!(hex64.len(), 64);
3062        assert_eq!(hex128.len(), 128);
3063
3064        for (label, hex) in &[
3065            ("hex40", hex40),
3066            ("hex64", hex64),
3067            ("hex128", hex128.as_str()),
3068        ] {
3069            let line = format!("secret key: {hex}");
3070            assert!(
3071                scan(&line).is_some(),
3072                "{label} near 'secret key' must be blocked; got None"
3073            );
3074        }
3075    }
3076
3077    #[test]
3078    fn hex_blocked_when_trigger_and_hash_word_coexist() {
3079        // Credential trigger dominates: adding "hash" or "sha" to the window does
3080        // not rescue a pure-hex token when a credential trigger is also present.
3081        // An attacker controlling the prose could otherwise bypass the gate with
3082        // one extra word, so the hash-word exception must NOT apply in trigger context.
3083        let hex32 = "4f9c2e8a1d3b5c7e9f0a2b4d6e8c0a2b";
3084        let key_hash_line = format!("api key hash {hex32}");
3085        let secret_sha_line = format!("secret sha {hex32}");
3086        assert!(
3087            scan(&key_hash_line).is_some(),
3088            "'api key hash <hex32>' must be blocked; got None"
3089        );
3090        assert!(
3091            scan(&secret_sha_line).is_some(),
3092            "'secret sha <hex32>' must be blocked; got None"
3093        );
3094    }
3095
3096    #[test]
3097    fn hex_near_sha_context_word_allowed() {
3098        // A 40-char hex with "sha" or "commit" in the window — but no credential
3099        // trigger — must be allowed (git SHA or content hash in normal prose).
3100        let hex40 = "da39a3ee5e6b4b0d3255bfef95601890afd80709";
3101        let sha_line = format!("sha1: {hex40}");
3102        let commit_line = format!("commit sha {hex40}");
3103        assert!(
3104            scan(&sha_line).is_none(),
3105            "hex40 near 'sha1' context must be allowed; fired: {:?}",
3106            scan(&sha_line)
3107        );
3108        assert!(
3109            scan(&commit_line).is_none(),
3110            "hex40 near 'commit sha' context must be allowed; fired: {:?}",
3111            scan(&commit_line)
3112        );
3113    }
3114
3115    #[test]
3116    fn allows_git_revision_reference_near_ordinary_key_and_token_prose() {
3117        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3118        let contents = [
3119            format!("the primary key behavior is pinned to commit {revision}"),
3120            format!("revision: {revision} emits one extra token"),
3121            format!("primary key behavior at revision:{revision};"),
3122            format!("configuration key\n\nrev {revision}."),
3123            format!("one extra token was introduced by sha: {revision}"),
3124        ];
3125        for content in &contents {
3126            assert!(
3127                check(content).is_ok(),
3128                "git revision reference in technical prose must pass: {content:?}, got {:?}",
3129                scan(content)
3130            );
3131        }
3132    }
3133
3134    #[test]
3135    fn git_revision_reference_does_not_exempt_credential_assignments() {
3136        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3137        for content in [
3138            format!("api_key={revision}"),
3139            format!("secret key: {revision}"),
3140            format!("token={revision}"),
3141            format!("api key hash {revision}"),
3142        ] {
3143            assert!(
3144                check(&content).is_err(),
3145                "credential assignment must remain blocked: {content:?}"
3146            );
3147        }
3148    }
3149
3150    #[test]
3151    fn blocks_forty_hex_after_credential_phrase_with_vcs_marker() {
3152        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3153        for content in [
3154            format!("api key value is commit {revision}"),
3155            format!("api key value is revision {revision}"),
3156            format!("the secret is rev {revision}"),
3157            format!("token value sha {revision}"),
3158        ] {
3159            assert_eq!(
3160                scan(&content).map(|matched| matched.detector),
3161                Some("hex-credential-token"),
3162                "a credential phrase must not be hidden by connector words before \
3163                 a VCS marker: {content:?}"
3164            );
3165        }
3166    }
3167
3168    #[test]
3169    fn blocks_unicode_punctuation_between_vcs_marker_and_forty_hex() {
3170        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3171        let content = format!("api_key value commit\u{200B}{revision}");
3172        assert!(
3173            check(&content).is_err(),
3174            "a zero-width space between marker and value must not rescue a \
3175             labeled credential: {content:?}, got {:?}",
3176            scan(&content)
3177        );
3178    }
3179
3180    #[test]
3181    fn blocks_slash_bearing_base64_credential_in_value_syntax() {
3182        // 40-char standard-base64-alphabet value whose `/` splits it into two
3183        // runs (19 and 20 bytes) each below MIN_ENTROPY_LEN — per-run checks
3184        // never see it, so the block must come from refusing the path
3185        // exemption for a credential-value clause and applying whole-token
3186        // entropy.
3187        let content = "api key value is Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh";
3188        assert_eq!(
3189            scan(content).map(|matched| matched.detector),
3190            Some("high-entropy-token"),
3191            "slash-bearing base64 credential in value syntax must be blocked"
3192        );
3193    }
3194
3195    #[test]
3196    fn blocks_angle_bracket_line_range_base64_credential_in_value_syntax() {
3197        let content = "api key value is <Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh>:~97-103";
3198        assert_eq!(
3199            scan(content).map(|matched| matched.detector),
3200            Some("high-entropy-token"),
3201            "angle-bracket/line-range dressing must not exempt a credential in \
3202             value syntax"
3203        );
3204    }
3205
3206    #[test]
3207    fn blocks_split_hex_credential_with_marker_adjacent_fragment() {
3208        // A 64-hex credential split 40+24 by a zero-width space, with the
3209        // first fragment hiding behind a VCS marker. The marker-adjacent
3210        // fragment is exempt as its own anchor, but the second fragment
3211        // anchors its own reconstruction chain, walks back across the gap,
3212        // and accumulates 40+24=64 — the symmetric-anchor property the
3213        // vcs-exempt bridge skip relies on.
3214        let content = concat!(
3215            "api token context: commit ",
3216            "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf",
3217            "\u{200B}",
3218            "0123456789abcdef01234567"
3219        );
3220        assert_eq!(
3221            scan(content).map(|matched| matched.detector),
3222            Some("hex-credential-token"),
3223            "split credential with a marker-adjacent fragment must be blocked"
3224        );
3225    }
3226
3227    #[test]
3228    fn blocks_forty_hex_behind_qualified_label_with_delimiter() {
3229        // A label with qualifier words the connector set cannot enumerate
3230        // ("for deploy") followed by a value delimiter is assignment syntax:
3231        // once the walk crosses the `:`/`=`, every label-side identifier is
3232        // stepped over until the trigger word.
3233        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3234        for content in [
3235            format!("api key for deploy: commit {revision}"),
3236            format!("prod api key for deploy = commit {revision}"),
3237        ] {
3238            assert_eq!(
3239                scan(&content).map(|matched| matched.detector),
3240                Some("hex-credential-token"),
3241                "a qualified label before a value delimiter must not be \
3242                 hidden from the exemption guard: {content:?}"
3243            );
3244        }
3245    }
3246
3247    #[test]
3248    fn blocks_slash_base64_behind_qualified_label_with_delimiter() {
3249        let content = "api key for deploy: Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh";
3250        assert_eq!(
3251            scan(content).map(|matched| matched.detector),
3252            Some("high-entropy-token"),
3253            "a qualified label before a value delimiter must refuse the path \
3254             exemption for a slash-bearing base64 credential"
3255        );
3256    }
3257
3258    #[test]
3259    fn blocks_forty_hex_behind_versioned_label() {
3260        // `v1.2` splits into version fragments under identifier extraction;
3261        // the intra-token dot must not read as a sentence boundary and the
3262        // fragments must be stepped over like connector words.
3263        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3264        let content = format!("api key v1.2 value is commit {revision}");
3265        assert_eq!(
3266            scan(&content).map(|matched| matched.detector),
3267            Some("hex-credential-token"),
3268            "a versioned credential label must stay reachable through its \
3269             version fragments: {content:?}"
3270        );
3271    }
3272
3273    #[test]
3274    fn blocks_labeled_inline_marker_split_credential() {
3275        // The r2 medium probes: `marker:value` inline forms carrying a split
3276        // credential, with a credential label ahead of a value delimiter.
3277        // The clause guard disables the VCS exemption, and whole-token
3278        // normalized-hex accumulation fires on the fused token.
3279        for content in [
3280            concat!(
3281                "api token context: rev:",
3282                "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf",
3283                "\u{200B}",
3284                "0123456789abcdef01234567"
3285            )
3286            .to_string(),
3287            concat!(
3288                "api token context: ",
3289                "0123456789abcdef01234567",
3290                "\u{200B}",
3291                "rev:d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf"
3292            )
3293            .to_string(),
3294        ] {
3295            assert!(
3296                check(&content).is_err(),
3297                "a labeled inline-marker split credential must be blocked: \
3298                 {content:?}, got {:?}",
3299                scan(&content)
3300            );
3301        }
3302    }
3303
3304    #[test]
3305    fn blocks_forty_hex_behind_multiword_label_and_marker_delimiter() {
3306        // Coverage: qualifier nouns beyond the two-word case are
3307        // reachable once prepositions/possessives read as glue, and a
3308        // delimiter attached to the VCS marker itself ("deploy sha: <hex>")
3309        // is assignment syntax like any other delimiter.
3310        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3311        for content in [
3312            format!("api key for deploy sha: {revision}"),
3313            format!("prod api key for deploy sha: {revision}"),
3314            format!("api key for production deploy: commit {revision}"),
3315        ] {
3316            assert_eq!(
3317                scan(&content).map(|matched| matched.detector),
3318                Some("hex-credential-token"),
3319                "a natural multiword credential label must not be hidden by \
3320                 glue words or a marker-attached delimiter: {content:?}"
3321            );
3322        }
3323    }
3324
3325    #[test]
3326    fn blocks_slash_base64_behind_possessive_qualified_label() {
3327        let content = "api key for our production deploy: Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh";
3328        assert_eq!(
3329            scan(content).map(|matched| matched.detector),
3330            Some("high-entropy-token"),
3331            "possessive-qualified credential label must refuse the path \
3332             exemption"
3333        );
3334    }
3335
3336    #[test]
3337    fn blocks_forty_hex_behind_participial_adjective_qualifier() {
3338        // Coverage: a past-participle word in ADJECTIVE position
3339        // (followed by a content noun: "shared deploy", "encrypted backup")
3340        // is a label qualifier, not verb-phrase prose, and must not end the
3341        // walk.
3342        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3343        let content = format!("api key for shared deploy: commit {revision}");
3344        assert_eq!(
3345            scan(&content).map(|matched| matched.detector),
3346            Some("hex-credential-token"),
3347            "a participial-adjective label qualifier must stay walkable: \
3348             {content:?}"
3349        );
3350    }
3351
3352    #[test]
3353    fn blocks_slash_base64_behind_participial_adjective_qualifier() {
3354        let content = "api key for encrypted backup: Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh";
3355        assert_eq!(
3356            scan(content).map(|matched| matched.detector),
3357            Some("high-entropy-token"),
3358            "a participial-adjective label qualifier must refuse the path \
3359             exemption"
3360        );
3361    }
3362
3363    #[test]
3364    fn blocks_forty_hex_behind_chained_qualifier_label() {
3365        // Coverage: a chain of qualifiers between the value and
3366        // the trigger ("shared encrypted deploy") must not exhaust the walk
3367        // before the label head is reached. Any per-clause content-word cap
3368        // re-admits this bypass one qualifier past the cap.
3369        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3370        let content = format!("api key for shared encrypted deploy: commit {revision}");
3371        assert_eq!(
3372            scan(&content).map(|matched| matched.detector),
3373            Some("hex-credential-token"),
3374            "a chained-qualifier credential label must stay walkable: \
3375             {content:?}"
3376        );
3377    }
3378
3379    #[test]
3380    fn blocks_slash_base64_behind_chained_qualifier_label() {
3381        let content =
3382            "api key for shared encrypted deploy: Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh";
3383        assert_eq!(
3384            scan(content).map(|matched| matched.detector),
3385            Some("high-entropy-token"),
3386            "a chained-qualifier credential label must refuse the path \
3387             exemption"
3388        );
3389    }
3390
3391    #[test]
3392    fn blocks_over_limit_qualified_label_fails_closed() {
3393        // Coverage: labels whose clause exhausts the walk budget
3394        // (a marker, an extra qualifier, or an interleaved glue word pushes
3395        // the trigger past the limit). Exhaustion after a value delimiter
3396        // fails closed — clause length must not launder a labeled credential
3397        // into the exemptions.
3398        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3399        let opaque = "Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh";
3400        for content in [
3401            format!("api key for the new shared encrypted staging deploy: commit {revision}"),
3402            format!("api key for the new shared encrypted regional staging deploy: {opaque}"),
3403            format!("api key for the new shared and encrypted staging deploy: {opaque}"),
3404            format!(
3405                "api key for the new shared encrypted regional staging deploy: commit {revision}"
3406            ),
3407            format!("api key for the new shared and encrypted staging deploy: commit {revision}"),
3408            format!("api key for the new shared encrypted staging deploy: {opaque}"),
3409        ] {
3410            assert!(
3411                check(&content).is_err(),
3412                "an over-limit qualified credential label must fail closed: \
3413                 {content:?}, got {:?}",
3414                scan(&content)
3415            );
3416        }
3417    }
3418
3419    #[test]
3420    fn accepted_false_positive_topical_trigger_before_delimited_path() {
3421        // The clause walk treats ANY reachable pre-delimiter trigger as a
3422        // credential label — it has no grammar to tell a label head ("api
3423        // key ...") from a topical object ("testing auth against parser").
3424        // Distinguishing them would reopen the labeled-value bypasses, so
3425        // this ordinary prose shape blocks. Accepted false positive,
3426        // conservative direction; documented in docs/api/secret_gate.md.
3427        let content = "results from testing auth against parser: \
3428             internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md";
3429        assert!(
3430            check(content).is_err(),
3431            "accepted-FP contract changed: topical trigger before a \
3432             delimited path no longer blocks — update the docs if deliberate"
3433        );
3434    }
3435
3436    #[test]
3437    fn blocks_participle_before_trigger_word() {
3438        // Ordering contract: a past-participle word BEFORE the trigger never
3439        // matters — the walk reaches the trigger first. Pinned so the
3440        // verb-position rule cannot regress into shielding these labels.
3441        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3442        let opaque = "Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh";
3443        for content in [
3444            format!("shared key: {revision}"),
3445            format!("generated api key: {revision}"),
3446            format!("encrypted token = {opaque}"),
3447        ] {
3448            assert!(
3449                check(&content).is_err(),
3450                "a participle before the trigger word must not shield the \
3451                 label: {content:?}, got {:?}",
3452                scan(&content)
3453            );
3454        }
3455    }
3456
3457    #[test]
3458    fn accepted_false_positive_docs_path_behind_attributive_trigger_and_delimiter() {
3459        // "auth setup: <path>" carries a trigger word in clause range ahead
3460        // of a value delimiter; the walk cannot distinguish an attributive
3461        // trigger ("auth setup") from a label head ("api key ...") without
3462        // reopening the labeled-value bypasses, so this ordinary prose shape
3463        // blocks. Accepted false positive — conservative direction under the
3464        // threat model; documented in docs/api/secret_gate.md.
3465        let content = "see the docs for auth setup: \
3466             internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md";
3467        assert!(
3468            check(content).is_err(),
3469            "accepted-FP contract changed: attributive trigger before a \
3470             delimited path no longer blocks — update the docs if deliberate"
3471        );
3472    }
3473
3474    #[test]
3475    fn allows_verb_phrase_prose_with_delimiter_before_trigger_word() {
3476        // Past-participle content words are verb-phrase evidence: the clause
3477        // narrates an action on the value instead of labeling it. These are
3478        // the false-positive shapes the exemptions exist for, and they must
3479        // survive the marker-attached-delimiter and glue-word widenings.
3480        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3481        for content in [
3482            format!("one extra token was introduced by sha: {revision}"),
3483            format!("the api key was rotated. deploy notes reference commit {revision}"),
3484            format!("api key updated: commit {revision}"),
3485        ] {
3486            assert!(
3487                check(&content).is_ok(),
3488                "verb-phrase prose must keep the VCS exemption: {content:?}, \
3489                 got {:?}",
3490                scan(&content)
3491            );
3492        }
3493    }
3494
3495    #[test]
3496    fn allows_unlabeled_unknown_connector_without_delimiter() {
3497        // VCS coordinates retain the strict no-delimiter tier: an identifier
3498        // outside the connector set ends the walk. The bounded bridge used by
3499        // file paths must not re-block this ordinary revision prose.
3500        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3501        for content in [
3502            format!("the key changes are in commit {revision}"),
3503            format!("deployed at commit {revision}"),
3504        ] {
3505            assert!(
3506                check(&content).is_ok(),
3507                "prose without a value delimiter must keep the VCS exemption: \
3508                 {content:?}, got {:?}",
3509                scan(&content)
3510            );
3511        }
3512    }
3513
3514    #[test]
3515    fn blocks_direct_no_delimiter_labels_for_both_file_path_value_families() {
3516        let values = [
3517            "Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh",
3518            "internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md",
3519        ];
3520
3521        for value in values {
3522            for label in ["api key found", "auth scanner found", "secret note"] {
3523                let content = format!("{label} {value}");
3524                assert!(
3525                    check(&content).is_err(),
3526                    "a direct no-delimiter label must refuse the file-path exemption: \
3527                     {content:?}, got {:?}",
3528                    scan(&content)
3529                );
3530            }
3531        }
3532    }
3533
3534    #[test]
3535    fn blocks_direct_gerund_and_see_labels_for_both_file_path_value_families() {
3536        let values = [
3537            "Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh",
3538            "internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md",
3539        ];
3540
3541        for value in values {
3542            for label in [
3543                "api key handling",
3544                "auth scanner handling",
3545                "api key see",
3546                "key: see",
3547            ] {
3548                let content = format!("{label} {value}");
3549                assert!(
3550                    check(&content).is_err(),
3551                    "narrative-looking adjacency must not shield a direct credential label: \
3552                     {content:?}, got {:?}",
3553                    scan(&content)
3554                );
3555            }
3556        }
3557    }
3558
3559    #[test]
3560    fn blocks_direct_participle_labels_for_both_file_path_value_families() {
3561        let values = [
3562            "Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh",
3563            "internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md",
3564        ];
3565
3566        for value in values {
3567            for label in ["api key leaked", "auth scanner leaked"] {
3568                let content = format!("{label} {value}");
3569                assert!(
3570                    check(&content).is_err(),
3571                    "step-zero participle adjacency must not shield a direct credential label: \
3572                     {content:?}, got {:?}",
3573                    scan(&content)
3574                );
3575            }
3576        }
3577    }
3578
3579    #[test]
3580    fn allows_no_delimiter_narrative_file_path_prose() {
3581        // The value-side `file`/`this` identifiers provide real walk context
3582        // before `flagged`; the step-zero direct-label tightening must not
3583        // remove this required narrative exemption.
3584        let content = "the auth scanner flagged this file \
3585            internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md";
3586
3587        assert!(
3588            check(content).is_ok(),
3589            "a regular participle in narrative position must preserve the path: got {:?}",
3590            scan(content)
3591        );
3592    }
3593
3594    #[test]
3595    fn suffix_word_hundred_is_not_a_narrative_participle() {
3596        assert!(is_clause_narrative_participle("flagged"));
3597        assert!(is_clause_narrative_participle("INTRODUCED"));
3598        assert!(!is_clause_narrative_participle("found"));
3599        assert!(!is_clause_narrative_participle("hundred"));
3600        assert!(is_clause_narrative_gerund("HANDLING"));
3601        assert!(!is_clause_narrative_gerund("found"));
3602
3603        for value in [
3604            "Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh",
3605            "internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md",
3606        ] {
3607            let content = format!("api key hundred: {value}");
3608            assert!(
3609                check(&content).is_err(),
3610                "a lexical -ed suffix must not shield a credential label: \
3611                 {content:?}, got {:?}",
3612                scan(&content)
3613            );
3614        }
3615    }
3616
3617    #[test]
3618    fn allows_vcs_reference_with_prose_boundary_before_trigger_word() {
3619        // A sentence or paragraph boundary between a trigger word and the
3620        // marker/value clause means the trigger is prose context, not this
3621        // value's label — the clause walk must stop at the boundary.
3622        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3623        for content in [
3624            format!("configuration key\n\nrev {revision}."),
3625            format!("rotate the api key. the fix is commit {revision}"),
3626        ] {
3627            assert!(
3628                check(&content).is_ok(),
3629                "boundary-separated trigger prose must not block a VCS \
3630                 reference: {content:?}, got {:?}",
3631                scan(&content)
3632            );
3633        }
3634    }
3635
3636    #[test]
3637    fn blocks_sha_revision_marker_immediately_labeled_as_api_key() {
3638        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3639        let content = format!("api_key sha:{revision}");
3640
3641        assert!(
3642            check(&content).is_err(),
3643            "credential-labeled SHA value must remain blocked: {content:?}"
3644        );
3645    }
3646
3647    #[test]
3648    fn blocks_rev_revision_marker_immediately_labeled_as_token() {
3649        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
3650        let content = format!("token rev:{revision}");
3651
3652        assert!(
3653            check(&content).is_err(),
3654            "credential-labeled revision value must remain blocked: {content:?}"
3655        );
3656    }
3657
3658    #[test]
3659    fn hex64_near_hash_context_allowed() {
3660        // A 64-char hex near "sha256" or "hash" — with no credential trigger —
3661        // must be allowed (content digest in normal prose).
3662        let hex64 = "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b";
3663        let sha_line = format!("sha256: {hex64}");
3664        let hash_line = format!("hash value {hex64}");
3665        assert!(
3666            scan(&sha_line).is_none(),
3667            "hex64 near 'sha256' must be allowed; fired: {:?}",
3668            scan(&sha_line)
3669        );
3670        assert!(
3671            scan(&hash_line).is_none(),
3672            "hex64 near 'hash' must be allowed; fired: {:?}",
3673            scan(&hash_line)
3674        );
3675    }
3676
3677    #[test]
3678    fn blocks_high_entropy_hex_like_token_near_key() {
3679        // A token whose character set exceeds pure hex (contains mixed-case, digits,
3680        // and non-hex chars) that ALSO passes `is_pure_hex = false` AND has high
3681        // entropy AND appears near "key" MUST be caught.  This is the realistic
3682        // real-world case: hex-looking API tokens often mix case and non-hex chars.
3683        // Example: a 32-char mixed-charset token near "api key".
3684        let mixed = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM"; // gitleaks:allow — not pure hex
3685        assert!(!is_pure_hex(mixed), "test token must not be pure hex");
3686        let line = format!("api key {mixed}");
3687        assert!(
3688            scan(&line).is_some(),
3689            "mixed-charset high-entropy token near 'api key' must be caught; got: {:?}",
3690            scan(&line)
3691        );
3692    }
3693
3694    #[test]
3695    fn allows_hex40_without_trigger() {
3696        // 40-char hex string in a neutral context (no trigger word) must still pass —
3697        // it's likely a git commit SHA or content hash.
3698        let hex40 = "da39a3ee5e6b4b0d3255bfef95601890afd80709";
3699        let line = format!("commit: {hex40}");
3700        assert!(
3701            scan(&line).is_none(),
3702            "40-char hex without trigger word must pass; fired: {:?}",
3703            scan(&line)
3704        );
3705    }
3706
3707    // ── check_json scans object keys ─────────────────────────────────────────
3708
3709    #[test]
3710    fn check_json_blocks_secret_in_object_key() {
3711        // A credential used as a JSON object key (not a value) must be caught.
3712        let props = serde_json::json!({ "ghp_FakeGitHubToken0000000000000000000": "redacted" }); // gitleaks:allow
3713        assert!(
3714            check_json(&props).is_err(),
3715            "credential as JSON object key must be blocked"
3716        );
3717    }
3718
3719    #[test]
3720    fn check_json_blocks_nested_secret_key() {
3721        // Nested credential key must be caught.
3722        let props = serde_json::json!({
3723            "metadata": {
3724                "AKIAFAKEKEY000000000": "value" // gitleaks:allow
3725            }
3726        });
3727        assert!(
3728            check_json(&props).is_err(),
3729            "nested credential as JSON object key must be blocked"
3730        );
3731    }
3732
3733    // ── PEM masking format ───────────────────────────────────────────────────
3734
3735    #[test]
3736    fn pem_masked_excerpt_reflects_block_length_not_rest_of_string() {
3737        let header = ["-----BEGIN RSA", " PRIVATE KEY-----"].concat(); // gitleaks:allow
3738        let fake = format!(
3739            "{}\nMIIEo\u{2026}\n-----END RSA PRIVATE KEY-----\nsome trailing text that is very long",
3740            header
3741        );
3742        let m = scan(&fake).unwrap();
3743        assert_eq!(m.detector, "pem-private-key");
3744        // The masked length should reflect only the key block, not the whole string.
3745        // "some trailing text that is very long" is ~37 chars; total string is much longer.
3746        // The block ends after "-----END RSA PRIVATE KEY-----\n".
3747        // We just verify it is shorter than the full string length.
3748        let full_len = fake.chars().count();
3749        let reported_len: usize = m
3750            .masked
3751            .trim_end_matches("chars")
3752            .rsplit("...")
3753            .next()
3754            .and_then(|s| s.parse().ok())
3755            .unwrap_or(full_len + 1);
3756        assert!(
3757            reported_len < full_len,
3758            "masked length ({reported_len}) should be less than full string length ({full_len})"
3759        );
3760    }
3761
3762    // ── UTF-8 char-boundary reproduction tests ───────────────────────────────
3763    //
3764    // These tests verify that no code path in secret_gate panics when multibyte
3765    // UTF-8 characters (emoji, CJK, accented Latin) appear at positions where
3766    // byte-level slicing could land mid-codepoint.  Each test targets a specific
3767    // code path.  A panic means the bug is live; a pass means the path is safe.
3768
3769    /// `build_match` masked preview: if the detected candidate starts with
3770    /// multibyte chars the "first 6 chars" preview must not slice on a byte
3771    /// boundary that falls mid-codepoint.  build_match already uses
3772    /// `chars().take(6)`, but we exercise it with emoji-prefixed candidates.
3773    #[test]
3774    fn utf8_build_match_preview_multibyte_prefix_no_panic() {
3775        // "🔑" = 4 bytes; repeat 3 times = 12 bytes for only 3 chars.
3776        // A ghp_-prefixed token with an emoji: let's construct a scenario where
3777        // a known-prefix secret is immediately adjacent to multibyte content so
3778        // that build_match receives a slice starting at a multibyte char.
3779        // PEM block with multibyte chars in the body exercises build_match on a
3780        // candidate that may contain non-ASCII.
3781        let header = ["-----BEGIN RSA", " PRIVATE KEY-----"].concat(); // gitleaks:allow
3782        let fake = format!("{}\n🔑密钥\n-----END RSA PRIVATE KEY-----", header);
3783        // Must not panic; mask must not echo full body.
3784        let m = scan(&fake);
3785        assert!(m.is_some(), "PEM with emoji body must still be caught");
3786        let m = m.unwrap();
3787        assert!(
3788            !m.masked.contains("🔑密钥"),
3789            "mask must not echo the emoji body"
3790        );
3791    }
3792
3793    /// `extract_token` called with a string starting with multibyte chars:
3794    /// the FlyV1 handler calls `extract_token(&text[payload_start..])` where
3795    /// `payload_start` is just past "FlyV1 " (ASCII).  If the payload is ASCII
3796    /// this is trivially safe, but we verify it cannot panic when the rest of
3797    /// the text after the payload contains multibyte chars.
3798    #[test]
3799    fn utf8_extract_token_multibyte_suffix_no_panic() {
3800        // "FlyV1 ABCDEFGHIJ密钥" — the payload is "ABCDEFGHIJ密钥"; extract_token
3801        // must stop at the ideographic chars (which are NOT ASCII whitespace) and
3802        // return the whole glued run without panicking.
3803        let text = "FlyV1 ABCDEFGHIJ密钥";
3804        // scan() must not panic.
3805        let _ = scan(text);
3806    }
3807
3808    /// `find_prefix_token` with multibyte chars immediately before and after
3809    /// the known prefix: checks text[..abs] boundary slices and
3810    /// extract_token(&text[abs..]) do not panic.
3811    #[test]
3812    fn utf8_prefix_detector_multibyte_adjacent_no_panic() {
3813        // 🔑 (4 bytes) immediately before AKIA: boundary at abs = 4, which is a
3814        // valid char boundary (end of the emoji).  extract_token sees ASCII from abs.
3815        let text = "🔑AKIAFAKEKEY00000000000000";
3816        let _ = scan(text); // must not panic
3817
3818        // é (U+00E9 = 2 bytes) immediately before ghp_:
3819        let text2 = "éghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
3820        let _ = scan(text2); // must not panic
3821
3822        // Emoji immediately after the token — extract_token ends at the emoji
3823        // (non-whitespace, but non-ASCII acts as delimiter in entropy heuristic).
3824        // For prefix tokens extract_token stops at ASCII whitespace only, so the
3825        // emoji would be included in the token length measurement.
3826        let text3 = "AKIAFAKEKEY00000000000000🔑";
3827        let _ = scan(text3); // must not panic
3828    }
3829
3830    /// `find_jwt` with multibyte chars as "whitespace" adjacent to a JWT-like
3831    /// candidate: `i = end + 1` could skip into a multibyte char if `end`
3832    /// pointed at a non-ASCII byte.  The position() search only looks for ASCII
3833    /// whitespace bytes, so a multibyte space (U+3000) is NOT found — `end`
3834    /// equals bytes.len() and `i = bytes.len() + 1` exits the loop.  Still
3835    /// verify no panic on CJK-surrounded JWT-like content.
3836    #[test]
3837    fn utf8_jwt_multibyte_adjacent_no_panic() {
3838        // A (fake) JWT-like triple surrounded by CJK text.
3839        let jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.FAKE_SIG_XXXXXXXXXXXX"; // gitleaks:allow
3840        let text = format!("数据{jwt}密钥");
3841        let _ = scan(&text); // must not panic
3842
3843        // JWT followed by ideographic space (U+3000 = 3 bytes 0xE3 0x80 0x80) —
3844        // not matched by the ASCII-whitespace position() search.
3845        let text2 = format!("{jwt}\u{3000}morecontent");
3846        let _ = scan(&text2); // must not panic
3847
3848        // JWT followed by emoji
3849        let text3 = format!("{jwt}🔑");
3850        let _ = scan(&text3); // must not panic
3851    }
3852
3853    /// `find_url_userinfo` with multibyte chars between "://" and "@":
3854    /// `at_pos` from `rest.find('@')` and `colon` from `userinfo.find(':')` are
3855    /// ASCII markers (char boundaries), but `scheme_start` calculation uses
3856    /// char_indices().rev() which must handle multibyte chars in the scheme
3857    /// prefix correctly.
3858    #[test]
3859    fn utf8_url_userinfo_multibyte_scheme_no_panic() {
3860        // CJK glued to a credential URL — the scheme_start walker must not place
3861        // the start inside a multibyte codepoint.
3862        let cases = [
3863            "🔑postgresql://dbuser:S3cr3tP4ss@db.example.com/db", // gitleaks:allow
3864            "密钥mysql://root:hunter2pw@10.0.0.1:3306/app",       // gitleaks:allow
3865            "éredis://svc:V3ryS3cretPw@cache.internal:6379",      // gitleaks:allow
3866        ];
3867        for text in &cases {
3868            // Must not panic and must detect the credential.
3869            let result = scan(text);
3870            assert!(
3871                result.is_some(),
3872                "URL credential after multibyte must be caught: {text:?}"
3873            );
3874        }
3875    }
3876
3877    /// `check_entropy_heuristic` window slicing with multibyte content at the
3878    /// ±TRIGGER_WINDOW boundary: `floor_char_boundary` must prevent slicing
3879    /// on a non-char boundary.
3880    #[test]
3881    fn utf8_entropy_window_multibyte_boundary_no_panic() {
3882        // Construct content where the TRIGGER_WINDOW (120 bytes) boundary falls
3883        // inside a 3-byte CJK character.  Repeat "数" (U+6570 = 3 bytes) to fill
3884        // exactly 119 bytes, then add an ASCII trigger word + high-entropy token.
3885        // Window start: token_offset - 120 = lands inside one of the CJK chars.
3886        let cjk_fill = "数".repeat(39); // 39 × 3 = 117 bytes
3887        assert_eq!(cjk_fill.len(), 117);
3888        // Pad with 2 more ASCII chars ("xy") so that the 120-byte window lands at
3889        // byte 119 which is the second byte of the 40th "数" — mid-multibyte.
3890        let secret = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM1"; // gitleaks:allow
3891        let content = format!("{cjk_fill}xy key {secret}");
3892        let _ = scan(&content); // must not panic
3893
3894        // Also test the right edge: token ends at byte offset, window_end =
3895        // token_offset + raw_token.len() + 120 may land mid-multibyte.
3896        let content2 = format!("key {secret}{cjk_fill}xy");
3897        let _ = scan(&content2); // must not panic
3898    }
3899
3900    /// `check()` top-level fuzz: a large batch of inputs with multibyte
3901    /// characters at various offsets to catch any remaining panic sites.
3902    /// All results must be either Ok or Err (not a panic).
3903    #[test]
3904    fn utf8_no_panic_property_test() {
3905        let multibyte_items = [
3906            "🔑",       // 4-byte emoji
3907            "密",       // 3-byte CJK
3908            "é",        // 2-byte accented Latin
3909            "\u{3000}", // 3-byte ideographic space
3910            "🇺🇸",       // 8-byte emoji flag (two surrogate-like scalars)
3911        ];
3912        let secrets = [
3913            "AKIAFAKEKEY00000000000000",
3914            "ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
3915            "sk-ant-api03-AAAAAAAAAAAAAAA",
3916            "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM1",
3917            "FlyV1 fm2_AAAABBBBCCCCDDDDEEEEFFFF",
3918        ];
3919        for mb in &multibyte_items {
3920            for secret in &secrets {
3921                for sep in &["", " ", "\n"] {
3922                    // multibyte before secret
3923                    let s = format!("{mb}{sep}{secret}");
3924                    let _ = check(&s);
3925                    // multibyte after secret
3926                    let s = format!("{secret}{sep}{mb}");
3927                    let _ = check(&s);
3928                    // multibyte both sides
3929                    let s = format!("{mb}{sep}{secret}{sep}{mb}");
3930                    let _ = check(&s);
3931                    // repeated multibyte filling TRIGGER_WINDOW boundary
3932                    let fill = mb.repeat(50);
3933                    let s = format!("{fill} api_key {secret} {fill}");
3934                    let _ = check(&s);
3935                }
3936            }
3937        }
3938    }
3939
3940    // ── mask_secrets: in-place redaction reusing the canonical detector ───────
3941
3942    #[test]
3943    fn bounded_masked_log_text_masks_connection_string_credentials() {
3944        let raw =
3945            "gate backend probe failed: postgres://svc:not-a-real-secret@internal-host refused"; // gitleaks:allow
3946        let rendered = bounded_masked_log_text(raw);
3947        assert!(
3948            !rendered.contains("not-a-real-secret"),
3949            "credential must be masked: {rendered:?}"
3950        );
3951        assert!(
3952            rendered.contains("***MASKED***"),
3953            "masked marker must record that detail was redacted: {rendered:?}"
3954        );
3955        assert!(
3956            rendered.contains("gate backend probe failed"),
3957            "non-secret diagnostic prose must survive: {rendered:?}"
3958        );
3959    }
3960
3961    #[test]
3962    fn bounded_masked_log_text_bounds_pathological_input() {
3963        let raw = "x".repeat(MAX_LOG_TEXT_OUTPUT_CHARS + 500);
3964        let rendered = bounded_masked_log_text(&raw);
3965        assert!(
3966            rendered.chars().count() <= MAX_LOG_TEXT_OUTPUT_CHARS + 1,
3967            "output must be bounded: {} chars",
3968            rendered.chars().count()
3969        );
3970        assert!(
3971            rendered.ends_with('…'),
3972            "truncated output must declare its own truncation"
3973        );
3974
3975        let short = "gate policy file unreadable";
3976        assert_eq!(
3977            bounded_masked_log_text(short),
3978            short,
3979            "short clean text passes through unchanged"
3980        );
3981    }
3982
3983    #[test]
3984    fn bounded_masked_log_text_masks_low_entropy_password_past_old_truncation_bound() {
3985        // Regression: masking used to run AFTER truncating the raw input to a
3986        // few KB, so a connection string whose password ran past that bound
3987        // lost its terminating `@` before the url-userinfo detector (a
3988        // shape match, not an entropy one) ever saw it — a low-entropy
3989        // password can't trip the entropy heuristic either, so it leaked
3990        // verbatim into the log. Masking now runs on the full input first,
3991        // so a password far longer than the old 4096-char bound is still
3992        // caught.
3993        let long_low_entropy_password = "a".repeat(5_000);
3994        let raw = format!(
3995            "gate backend probe failed: postgres://svc:{long_low_entropy_password}@internal-host refused"
3996        );
3997        let rendered = bounded_masked_log_text(&raw);
3998        assert!(
3999            !rendered.contains(&"a".repeat(50)),
4000            "long low-entropy password must not survive in the log: {rendered:?}"
4001        );
4002        assert!(
4003            rendered.contains("***MASKED***"),
4004            "masked marker must record that the credential was redacted: {rendered:?}"
4005        );
4006    }
4007
4008    /// Regression for the crossing-boundary leak: a password longer than
4009    /// [`MAX_LOG_TEXT_MASK_INPUT_CHARS`] never gets a chance to show its
4010    /// terminating `@` to `find_url_userinfo` inside the truncated scan
4011    /// input, so the shape detector alone can never catch it — and it's
4012    /// deliberately low-entropy so the entropy heuristic can't catch it
4013    /// either. Only `redact_crossing_boundary_url_userinfo` can close this.
4014    #[test]
4015    fn bounded_masked_log_text_redacts_password_crossing_mask_input_cap() {
4016        let huge_low_entropy_password = "a".repeat(MAX_LOG_TEXT_MASK_INPUT_CHARS + 1000);
4017        let raw =
4018            format!("gate backend probe failed: postgres://svc:{huge_low_entropy_password}@internal-host refused");
4019        let rendered = bounded_masked_log_text(&raw);
4020        assert!(
4021            !rendered.contains(&"a".repeat(50)),
4022            "no password fragment may survive when the password crosses the mask-input cap: {rendered:?}"
4023        );
4024        assert!(
4025            rendered.contains("***MASKED***"),
4026            "mask marker must record that the credential was redacted: {rendered:?}"
4027        );
4028        assert!(
4029            rendered.ends_with('…'),
4030            "truncated record must declare its own incompleteness: {rendered:?}"
4031        );
4032    }
4033
4034    /// Regression: the crossing fallback follows the same empty-username
4035    /// rule as the canonical detector — `redis://:<password>` with the
4036    /// terminating `@` beyond the mask-input cap must still be redacted.
4037    #[test]
4038    fn bounded_masked_log_text_redacts_crossing_empty_username_password() {
4039        let huge_low_entropy_password = "b".repeat(MAX_LOG_TEXT_MASK_INPUT_CHARS + 1000);
4040        let raw = format!(
4041            "gate backend probe failed: redis://:{huge_low_entropy_password}@internal-host refused"
4042        );
4043        let rendered = bounded_masked_log_text(&raw);
4044        assert!(
4045            !rendered.contains(&"b".repeat(50)),
4046            "no empty-username password fragment may survive the cap crossing: {rendered:?}"
4047        );
4048        assert!(
4049            rendered.contains("***MASKED***"),
4050            "mask marker must record that the credential was redacted: {rendered:?}"
4051        );
4052    }
4053
4054    /// Regression: the crossing fallback shares the canonical detector's
4055    /// authority boundary — a colon after `/`, `?`, or `#` is path/query
4056    /// text, so a capped input whose only colon-at pair sits in the path
4057    /// must NOT be masked even when the `@` lies beyond the cap.
4058    #[test]
4059    fn bounded_masked_log_text_keeps_path_colon_text_crossing_the_cap() {
4060        let filler = "z".repeat(MAX_LOG_TEXT_MASK_INPUT_CHARS + 1000);
4061        let raw = format!("see https://host/a:x{filler}@next for details");
4062        let rendered = bounded_masked_log_text(&raw);
4063        assert!(
4064            !rendered.contains("***MASKED***"),
4065            "path-colon text must not read as a crossing credential: {rendered:?}"
4066        );
4067        assert!(
4068            rendered.starts_with("see https://host/a:x"),
4069            "the non-credential prefix must survive verbatim: {rendered:?}"
4070        );
4071    }
4072
4073    /// Regression: a crossing password that itself contains `://` must not
4074    /// let the fallback anchor at that nested delimiter. Anchoring at the
4075    /// last `://` would redact only from the nested span onward, leaving
4076    /// the real `user:<password prefix>` before it in the emitted log. The
4077    /// fallback must anchor at the earliest unterminated credential
4078    /// opening, so zero password characters survive.
4079    #[test]
4080    fn bounded_masked_log_text_redacts_crossing_password_containing_nested_scheme() {
4081        let mut password = "a".repeat(1000);
4082        password.push_str("://h:");
4083        password.push_str(&"b".repeat(MAX_LOG_TEXT_MASK_INPUT_CHARS + 1000));
4084        let raw =
4085            format!("gate backend probe failed: postgres://svc:{password}@internal-host refused");
4086        let rendered = bounded_masked_log_text(&raw);
4087        assert!(
4088            !rendered.contains(&"a".repeat(50)),
4089            "password prefix before the nested delimiter must not survive: {rendered:?}"
4090        );
4091        assert!(
4092            !rendered.contains(&"b".repeat(50)),
4093            "password tail after the nested delimiter must not survive: {rendered:?}"
4094        );
4095        assert!(
4096            rendered.contains("***MASKED***"),
4097            "mask marker must record that the credential was redacted: {rendered:?}"
4098        );
4099    }
4100
4101    /// Regression: a complete URL earlier in the text must not stop the
4102    /// fallback from catching a later credential run that crosses the cap.
4103    /// The earlier URL's span terminates inside the text (whitespace after
4104    /// it), so it is skipped; the later unterminated `user:<password-run>`
4105    /// is the one redacted.
4106    #[test]
4107    fn bounded_masked_log_text_redacts_crossing_credential_after_complete_url() {
4108        let huge_low_entropy_password = "c".repeat(MAX_LOG_TEXT_MASK_INPUT_CHARS + 1000);
4109        let raw = format!(
4110            "probe of https://ok-host/health failed; retry hit postgres://svc:{huge_low_entropy_password}@internal-host refused"
4111        );
4112        let rendered = bounded_masked_log_text(&raw);
4113        assert!(
4114            rendered.contains("ok-host"),
4115            "the earlier complete URL must survive untouched: {rendered:?}"
4116        );
4117        assert!(
4118            !rendered.contains(&"c".repeat(50)),
4119            "no password fragment may survive: {rendered:?}"
4120        );
4121        assert!(
4122            rendered.contains("***MASKED***"),
4123            "mask marker must record that the credential was redacted: {rendered:?}"
4124        );
4125    }
4126
4127    /// Regression: the crossing-boundary fallback must not fire when the
4128    /// password's terminating `@` sits safely inside the (untruncated)
4129    /// bounded input — the existing `find_url_userinfo` arm alone must
4130    /// still catch and mask it, with exactly one mask marker.
4131    #[test]
4132    fn bounded_masked_log_text_masks_password_just_under_cap_with_terminating_at() {
4133        let password_under_cap = "a".repeat(MAX_LOG_TEXT_MASK_INPUT_CHARS - 1000);
4134        let raw = format!(
4135            "gate backend probe failed: postgres://svc:{password_under_cap}@internal-host refused"
4136        );
4137        assert!(
4138            raw.chars().count() < MAX_LOG_TEXT_MASK_INPUT_CHARS,
4139            "test precondition: whole input must stay under the mask-input cap so no truncation occurs"
4140        );
4141        let rendered = bounded_masked_log_text(&raw);
4142        assert!(
4143            !rendered.contains(&"a".repeat(50)),
4144            "terminated credential must still be masked normally: {rendered:?}"
4145        );
4146        assert_eq!(
4147            rendered.matches("***MASKED***").count(),
4148            1,
4149            "exactly one mask marker — the crossing fallback must not fire early: {rendered:?}"
4150        );
4151    }
4152
4153    /// Regression: giant truncated text with no `://user:` shape at all must
4154    /// pass through unmodified by the crossing-boundary fallback — it must
4155    /// not manufacture a false redaction out of ordinary non-credential
4156    /// prose that happens to be long enough to hit the mask-input cap.
4157    #[test]
4158    fn bounded_masked_log_text_giant_non_credential_text_unaffected_by_crossing_fallback() {
4159        let raw = "x".repeat(MAX_LOG_TEXT_MASK_INPUT_CHARS + 1000);
4160        let rendered = bounded_masked_log_text(&raw);
4161        assert!(
4162            !rendered.contains("***MASKED***"),
4163            "non-credential text must never be redacted: {rendered:?}"
4164        );
4165        assert!(
4166            rendered.ends_with('…'),
4167            "truncated record must still declare its own incompleteness: {rendered:?}"
4168        );
4169        assert!(
4170            rendered.starts_with("xxxx"),
4171            "non-credential content must survive verbatim up to the output bound: {rendered:?}"
4172        );
4173    }
4174
4175    /// Regression: an ordinary short connection string (well under both
4176    /// caps) must keep being masked exactly as before — the crossing
4177    /// fallback is gated on truncation and must never touch this path.
4178    #[test]
4179    fn bounded_masked_log_text_masks_ordinary_short_connection_string() {
4180        let raw = "gate backend probe failed: postgres://svc:hunter2pw@internal-host refused"; // gitleaks:allow
4181        let rendered = bounded_masked_log_text(raw);
4182        assert!(
4183            !rendered.contains("hunter2pw"),
4184            "credential must be masked: {rendered:?}"
4185        );
4186        assert_eq!(
4187            rendered.matches("***MASKED***").count(),
4188            1,
4189            "exactly one mask marker for the one credential: {rendered:?}"
4190        );
4191        assert!(
4192            !rendered.ends_with('…'),
4193            "short untruncated text must not declare truncation: {rendered:?}"
4194        );
4195    }
4196
4197    #[test]
4198    fn bounded_masked_log_text_neutralizes_ascii_control_chars() {
4199        let raw = "line one\r\ninjected: \u{1b}[31mFAKE ALERT\u{1b}[0m line two";
4200        let rendered = bounded_masked_log_text(raw);
4201        assert!(
4202            !rendered.contains('\r') && !rendered.contains('\n'),
4203            "CR/LF must be neutralized so a single log line cannot be split/forged: {rendered:?}"
4204        );
4205        assert!(
4206            !rendered.contains('\u{1b}'),
4207            "ESC control character must be neutralized: {rendered:?}"
4208        );
4209        assert!(
4210            rendered.contains("line one") && rendered.contains("line two"),
4211            "surrounding prose must survive neutralization: {rendered:?}"
4212        );
4213    }
4214
4215    #[test]
4216    fn bounded_masked_log_text_neutralizes_each_unsafe_unicode_category() {
4217        let cases = [
4218            ("Cc", '\u{1b}', "\\u{001b}"),
4219            ("Cf", '\u{202e}', "\\u{202e}"),
4220            ("Zl", '\u{2028}', "\\u{2028}"),
4221            ("Zp", '\u{2029}', "\\u{2029}"),
4222        ];
4223
4224        for (category, unsafe_char, escaped) in cases {
4225            let raw = format!("before{unsafe_char}after");
4226            assert_eq!(
4227                bounded_masked_log_text(&raw),
4228                format!("before{escaped}after"),
4229                "Unicode category {category} must be neutralized"
4230            );
4231        }
4232    }
4233
4234    #[test]
4235    fn bounded_masked_log_text_keeps_space_separators_tabs_accented_and_cjk_text() {
4236        let raw = "ordinary whitespace\tcafé résumé 日本語のテキスト\u{3000}数据库连接管理";
4237        assert_eq!(
4238            bounded_masked_log_text(raw),
4239            raw,
4240            "ordinary whitespace, Zs separators, accented text, and CJK prose must pass through unmodified"
4241        );
4242    }
4243
4244    #[test]
4245    fn mask_secrets_borrows_clean_text() {
4246        let clean = "The FlashAttention paper introduces IO-aware tiling.";
4247        let masked = mask_secrets(clean);
4248        assert!(
4249            matches!(masked, std::borrow::Cow::Borrowed(_)),
4250            "clean text must not allocate"
4251        );
4252        assert_eq!(masked, clean);
4253    }
4254
4255    #[test]
4256    fn mask_secrets_redacts_shapes_the_old_mirror_regex_missed() {
4257        // These are exactly the detectors the session mirror's previous local
4258        // regex did NOT cover, which is why it now shares this masker.
4259        let cases = [
4260            "key: sk-proj-FAKEKEY00000000000000000000000000000000", // gitleaks:allow
4261            "cred ASIAFAKEKEY00000000000",                          // gitleaks:allow
4262            "stripe sk_live_FAKESTRIPE0000000000000",               // gitleaks:allow
4263            "db postgresql://dbuser:S3cr3tP4ss@db.example.com/db",  // gitleaks:allow
4264        ];
4265        for c in &cases {
4266            let masked = mask_secrets(c);
4267            assert!(
4268                masked.contains(REDACTION_MARKER),
4269                "must redact: {c:?} -> {masked:?}"
4270            );
4271        }
4272    }
4273
4274    #[test]
4275    fn mask_secrets_redacts_every_span_and_keeps_prose() {
4276        let line =
4277            "first sk-ant-api03-AAAAAAAAAAAAAAA then ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA end";
4278        let masked = mask_secrets(line);
4279        assert!(
4280            !masked.contains("sk-ant-api03") && !masked.contains("ghp_AAAA"),
4281            "no secret may survive: {masked}"
4282        );
4283        assert_eq!(
4284            masked.matches(REDACTION_MARKER).count(),
4285            2,
4286            "both secrets must be redacted: {masked}"
4287        );
4288        assert!(masked.starts_with("first "), "prose preserved: {masked}");
4289        assert!(masked.ends_with(" end"), "prose preserved: {masked}");
4290    }
4291
4292    #[test]
4293    fn mask_secrets_output_passes_check() {
4294        // The masked output must itself be clean — no credential left for the
4295        // write-time gate to catch.
4296        let line = "token=ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA and AKIAFAKEKEY1234567890";
4297        let masked = mask_secrets(line).into_owned();
4298        assert!(
4299            check(&masked).is_ok(),
4300            "masked output must pass the gate: {masked}"
4301        );
4302    }
4303
4304    #[test]
4305    fn mask_secrets_redacts_entropy_secret_left_of_known_secret() {
4306        // Cross-layer leftmost regression: a Layer-2 entropy secret sits to the
4307        // LEFT of a Layer-1 known-prefix secret. A scan that short-circuits on
4308        // the first known match (or returns first-by-detector-priority) would
4309        // redact `ghp_…` and copy the entropy token before it verbatim — leaking
4310        // it. `scan_match` must fold both layers through leftmost selection.
4311        let line =
4312            "secret=Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM and ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"; // gitleaks:allow
4313        let masked = mask_secrets(line).into_owned();
4314        assert!(
4315            !masked.contains("Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM") && !masked.contains("ghp_AAAA"),
4316            "neither the entropy secret nor the known secret may survive: {masked}"
4317        );
4318        assert_eq!(
4319            masked.matches(REDACTION_MARKER).count(),
4320            2,
4321            "both secrets must be redacted exactly once: {masked}"
4322        );
4323        assert!(
4324            check(&masked).is_ok(),
4325            "masked output must pass the gate: {masked}"
4326        );
4327    }
4328
4329    #[test]
4330    fn github_app_token_families_are_masked() {
4331        // ghu_ (user-to-server), ghs_ (server-to-server), and ghr_ (refresh)
4332        // GitHub App tokens are real credential families. They are
4333        // context-free: no trigger word needed.
4334        let cases = [
4335            "ghu_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", // gitleaks:allow
4336            "ghs_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",  // gitleaks:allow
4337            "ghr_CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC",  // gitleaks:allow
4338        ];
4339        for token in &cases {
4340            assert!(
4341                check(token).is_err(),
4342                "gate must hard-block GitHub App token {token}"
4343            );
4344            let line = format!("auth: {token} trailing");
4345            let masked = mask_secrets(&line).into_owned();
4346            assert!(
4347                !masked.contains(token),
4348                "GitHub App token must not survive masking: {masked}"
4349            );
4350            assert!(
4351                check(&masked).is_ok(),
4352                "masked output must pass the gate: {masked}"
4353            );
4354        }
4355    }
4356
4357    #[test]
4358    fn mask_secrets_redacts_entropy_token_whose_trigger_is_left_of_earlier_secret() {
4359        // The entropy detector only fires near a
4360        // trigger word. When the trigger (`api_key`) sits to the LEFT of an
4361        // earlier known-prefix secret (`ghp_…`), a masker that rescans only the
4362        // suffix after each redaction loses that context and leaks the later
4363        // high-entropy token. Spans must be discovered against the ORIGINAL text.
4364        let line =
4365            "api_key ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM1"; // gitleaks:allow
4366        let masked = mask_secrets(line).into_owned();
4367        assert!(
4368            !masked.contains("ghp_AAAA"),
4369            "the known secret must be redacted: {masked}"
4370        );
4371        assert!(
4372            !masked.contains("Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM1"),
4373            "the later entropy token must be redacted even though its trigger \
4374             word sits left of the earlier redaction: {masked}"
4375        );
4376        assert_eq!(
4377            masked.matches(REDACTION_MARKER).count(),
4378            2,
4379            "both secrets must be redacted exactly once: {masked}"
4380        );
4381        assert!(
4382            check(&masked).is_ok(),
4383            "masked output must pass the gate: {masked}"
4384        );
4385    }
4386
4387    // ── Structured identifiers: file paths / branch names ───────────────────
4388
4389    #[test]
4390    fn allows_high_entropy_file_path_near_secret_word() {
4391        let content =
4392            "workspace path fable-ops/ADR-DRAFT-adr079-slices234.md for the secret gate bug";
4393        assert!(
4394            check(content).is_ok(),
4395            "structured file path in technical prose must pass; got {:?}",
4396            scan(content)
4397        );
4398    }
4399
4400    #[test]
4401    fn allows_high_entropy_workspace_path_before_later_key_word() {
4402        let content =
4403            "see internal/workspaces/20260701/adr079-slices234/PACKET.md for the key behavior";
4404        assert!(
4405            check(content).is_ok(),
4406            "a path before a later topical key word must pass; got {:?}",
4407            scan(content)
4408        );
4409    }
4410
4411    #[test]
4412    fn allows_high_entropy_short_run_path_near_auth_word() {
4413        let content =
4414            "auth work saved at internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md";
4415        assert!(
4416            check(content).is_ok(),
4417            "path with a short run in technical prose must pass; got {:?}",
4418            scan(content)
4419        );
4420    }
4421
4422    #[test]
4423    fn allows_branch_and_review_filename_near_key_word() {
4424        let content =
4425            "branch feat-session-mirror pushed, see release_notes_v2.md for the key findings";
4426        assert!(
4427            check(content).is_ok(),
4428            "branch name and review filename near 'key' must not be blocked; fired: {:?}",
4429            scan(content)
4430        );
4431    }
4432
4433    #[test]
4434    fn allows_adr_doc_path_near_password_word() {
4435        let content = "password reset doc: docs/adr/ADR-055-epistemic-edge-relations.md";
4436        assert!(
4437            check(content).is_ok(),
4438            "ADR doc path near 'password' must not be blocked; fired: {:?}",
4439            scan(content)
4440        );
4441    }
4442
4443    #[test]
4444    fn allows_source_file_path_near_credential_word() {
4445        let content = "credential handling code crates/khive-pack-session/src/mirror/ingest.rs";
4446        assert!(
4447            check(content).is_ok(),
4448            "source file path near 'credential' must not be blocked; fired: {:?}",
4449            scan(content)
4450        );
4451    }
4452
4453    #[test]
4454    fn allows_long_snake_case_identifier_near_key_word() {
4455        let content = "api key handling lives in check_entropy_heuristic_impl";
4456        assert!(
4457            check(content).is_ok(),
4458            "snake_case identifier near 'key' must not be blocked; fired: {:?}",
4459            scan(content)
4460        );
4461    }
4462
4463    // ── Structured-identifier exemption: catch-suite regression ─────────────
4464
4465    #[test]
4466    fn hyphenated_random_secret_is_not_a_structured_identifier() {
4467        // Same token as `blocks_bare_base64url_43chars_near_key`: hyphenated
4468        // but not word-shaped. The second run exceeds the 24-char run cap,
4469        // and the first run's case-transition density (~0.42) exceeds the
4470        // 0.3 threshold on its own, so this must not be exempted and the
4471        // existing catch-suite test must keep blocking it.
4472        assert!(!is_structured_identifier(
4473            "wJalrXUtnFEMI-K7MDENGbPxRfiCYEXAMPLEKEYX123"
4474        ));
4475        let line = "api key wJalrXUtnFEMI-K7MDENGbPxRfiCYEXAMPLEKEYX123";
4476        assert!(
4477            scan(line).is_some(),
4478            "hyphenated random secret must still be blocked; got: {:?}",
4479            scan(line)
4480        );
4481    }
4482
4483    // ── Structured-identifier exemption: direct unit tests ───────────────────
4484
4485    #[test]
4486    fn structured_identifier_true_for_repro_paths() {
4487        let paths = [
4488            "fable-ops/ADR-DRAFT-adr079-slices234.md",
4489            "internal/workspaces/20260701/adr079-slices234/PACKET.md",
4490            "internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md",
4491            "release_notes_v2.md",
4492            "docs/adr/ADR-055-epistemic-edge-relations.md",
4493            "crates/khive-pack-session/src/mirror/ingest.rs",
4494            "check_entropy_heuristic_impl",
4495        ];
4496        for p in paths {
4497            assert!(
4498                is_structured_identifier(p),
4499                "expected structured identifier: {p}"
4500            );
4501        }
4502    }
4503
4504    #[test]
4505    fn structured_identifier_false_without_separator() {
4506        // No `/`, `-`, `_`, or `.` present — fails rule 1 outright.
4507        assert!(!is_structured_identifier(
4508            "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM"
4509        ));
4510    }
4511
4512    #[test]
4513    fn structured_identifier_false_for_leetspeak_digit_interleaving() {
4514        // Digits interleaved with letters within a run (not a trailing digit
4515        // suffix) fail the `[A-Za-z]+[0-9]*` / `[0-9]+` shape check.
4516        assert!(!is_structured_identifier("S3cr3t-P4ssw0rd-t0ken-here!"));
4517    }
4518
4519    #[test]
4520    fn structured_identifier_false_for_run_over_length_cap() {
4521        // A 26-char single alphabetic run between separators fails the
4522        // 24-char per-run length cap even though it is otherwise trivially
4523        // word-shaped (uniform lowercase, zero case transitions).
4524        let long_run = "a".repeat(26);
4525        let token = format!("prefix-{long_run}-suffix");
4526        assert!(!is_structured_identifier(&token));
4527    }
4528
4529    // ── Credential-labeled structured identifiers remain blocked ────────────
4530    // Shannon entropy over an attacker-chosen run boundary cannot distinguish an
4531    // English word from adversarially-chosen letters at the same length ceiling
4532    // (log2(run_len)), so no run-shape exemption is sound near a trigger. File paths
4533    // are exempt only after their runs pass the entropy/hex checks AND the path is
4534    // not immediately labeled as a credential value. The tests below guard that
4535    // credential-label boundary.
4536
4537    #[test]
4538    fn blocks_separator_secret_access_key_bypass() {
4539        // Adversarial bypass shape: an AWS-secret-key-like value split into
4540        // separator-delimited word-shaped runs to dodge the entropy check.
4541        let content = "secret_access_key abcdefghij/klmnopqrst/uvwxyzabcd/efghijk";
4542        assert!(
4543            check(content).is_err(),
4544            "AWS Secret Access Key shaped bypass must be blocked: {:?}",
4545            scan(content)
4546        );
4547    }
4548
4549    #[test]
4550    fn blocks_adversarial_lowercase_only_separator_token_near_access_key() {
4551        let content = "access_key qrstuvwxyz/abcdefghij/klmnopqrst/uvwxyzab";
4552        assert!(
4553            check(content).is_err(),
4554            "lowercase-only separator-delimited high-entropy token near \
4555             'access_key' must be blocked: {:?}",
4556            scan(content)
4557        );
4558    }
4559
4560    #[test]
4561    fn blocks_adversarial_digit_and_word_mixed_token_near_api_key() {
4562        // A mix of pure-digit runs and letters-then-digits runs (both
4563        // individually word-shaped) whose combined alphabet diversity crosses
4564        // the entropy threshold.
4565        let content = "api_key attaycofrsm827/festwqjhc493/8261947350/qwikjzx982";
4566        assert!(
4567            check(content).is_err(),
4568            "digit-and-word-mixed high-entropy token near 'api_key' must be blocked: {:?}",
4569            scan(content)
4570        );
4571    }
4572
4573    #[test]
4574    fn blocks_adversarial_token_assignment_separator_delimited_secret() {
4575        let content = "token=zxkqwmvbpl/trfhysjgnc/dweiaoutkz-mnbvcxzlk";
4576        assert!(
4577            check(content).is_err(),
4578            "token= with lowercase-only separator-delimited high-entropy value \
4579             must be blocked: {:?}",
4580            scan(content)
4581        );
4582    }
4583
4584    #[test]
4585    fn blocks_extension_suffix_bypass_secret_access_key() {
4586        // A file-extension check alone would exempt this: appending `.md`
4587        // to a random credential must not bypass detection.
4588        let content = "secret_access_key abcdefghij/klmnopqrst/uvwxyzabcd/efghijk.md";
4589        assert!(
4590            check(content).is_err(),
4591            "extension-suffixed AWS Secret Access Key shaped bypass must be blocked: {:?}",
4592            scan(content)
4593        );
4594    }
4595
4596    #[test]
4597    fn blocks_extension_suffix_bypass_token_assignment() {
4598        let content = "token=zxkqwmvbpl/trfhysjgnc/dweiaoutkz-mnbvcxzlk.rs";
4599        assert!(
4600            check(content).is_err(),
4601            "extension-suffixed token= bypass must be blocked: {:?}",
4602            scan(content)
4603        );
4604    }
4605
4606    #[test]
4607    fn blocks_unsuffixed_separator_split_credential_bypasses() {
4608        let cases = [
4609            "secret_access_key abcdefghij/klmnopqrst/uvwxyzabcd/efghijk",
4610            "token=zxkqwmvbpl/trfhysjgnc/dweiaoutkz-mnbvcxzlk",
4611        ];
4612        for content in cases {
4613            assert!(
4614                check(content).is_err(),
4615                "bypass string must still be blocked: {content:?}, got: {:?}",
4616                scan(content)
4617            );
4618        }
4619    }
4620
4621    #[test]
4622    fn blocks_digit_run_suffix_bypass_attempt() {
4623        let cases = [
4624            "secret_access_key abcdefghij/klmnopqrst/uvwxyzabcd/efghijk2024",
4625            "secret_access_key abcdefghij2024/klmnopqrst/uvwxyzabcd/efghijk.md",
4626        ];
4627        for content in cases {
4628            assert!(
4629                check(content).is_err(),
4630                "digit-run-suffixed bypass attempt must be blocked: {content:?}, got: {:?}",
4631                scan(content)
4632            );
4633        }
4634    }
4635
4636    #[test]
4637    fn blocks_low_entropy_padding_run_bypass_attempts() {
4638        // A low-entropy padding run (`aaaa`) inserted before short/digit-shaped
4639        // runs would drag any AVERAGE per-run entropy signal below its
4640        // threshold. With the exemption dropped entirely, these must be
4641        // blocked purely on full-token entropy, same as any other
4642        // near-trigger high-entropy token.
4643        let cases = [
4644            "secret_access_key abcdefghij/klmnopqrst/uvwxyzabcd/efghijk/aaaa/R1.md",
4645            "token=zxkqwmvbpl/trfhysjgnc/dweiaoutkz/mnbvcxzlk/aaaa/R1.rs",
4646            "secret_access_key abcdefghij/klmnopqrst/uvwxyzabcd/efghijk/aaaa/bbbb/R1.md",
4647            "token=zxkqwmvbpl/trfhysjgnc/dweiaoutkz/mnbvcxzlk/aaaa/bbbb/R1.rs",
4648        ];
4649        for content in cases {
4650            assert!(
4651                check(content).is_err(),
4652                "padding-run bypass attempt must be blocked: {content:?}, got: {:?}",
4653                scan(content)
4654            );
4655        }
4656    }
4657
4658    #[test]
4659    fn blocks_run_splitting_bypass_attempts() {
4660        // Splitting a credential into short (4-6 char) runs drives EVERY
4661        // run's own letters-only entropy toward log2(run_len), which ordinary
4662        // short English path words already sit at or near: this is exactly
4663        // why any per-run entropy ceiling is unsound as an exemption signal.
4664        // With the exemption dropped, these are blocked on full-token entropy
4665        // regardless of run shape.
4666        let cases = [
4667            "secret_access_key abcd/efgh/ijkl/mnop/qrst/uvwx/yzab/cdef.md",
4668            "secret_access_key abcde/fghij/klmno/pqrst/uvwxy/zabcd.md",
4669            "secret_access_key abcdef/ghijkl/mnopqr/stuvwx/yzabcd.md",
4670        ];
4671        for content in cases {
4672            assert!(
4673                check(content).is_err(),
4674                "run-splitting bypass attempt must be blocked: {content:?}, got: {:?}",
4675                scan(content)
4676            );
4677        }
4678    }
4679
4680    #[test]
4681    fn blocks_separator_split_generic_hex_credential_ascii() {
4682        // Two 20-char hex runs joined by `/` — individually
4683        // below MIN_ENTROPY_LEN (24) and neither is a HEX_CREDENTIAL_LENGTHS
4684        // length on its own; the whole token is not pure hex (the `/` breaks
4685        // it) and its entropy is capped below ENTROPY_THRESHOLD by the
4686        // 17-symbol hex-plus-separator alphabet, so none of the prior checks
4687        // caught it. Concatenating the two runs (dropping the separator)
4688        // normalizes to one 40-char hex sequence — a HEX_CREDENTIAL_LENGTHS
4689        // value.
4690        let content = "api key 0123456789abcdef0123/456789abcdef01234567";
4691        assert!(
4692            check(content).is_err(),
4693            "separator-split hex credential must be blocked: got {:?}",
4694            scan(content)
4695        );
4696    }
4697
4698    #[test]
4699    fn blocks_separator_split_generic_hex_credential_unicode_separator() {
4700        // Same shape as above, but the separator is a non-ASCII character
4701        // (U+200B zero-width space) instead of `/`: the tokenizer treats
4702        // every non-ASCII character as a delimiter (see the tokenizer
4703        // comment in `check_entropy_heuristic`), so this splits the payload
4704        // into TWO tokens rather than leaving it inside one — the
4705        // intra-token concatenation above never sees both halves together.
4706        // The adjacent-token bridge must catch it the same way.
4707        let content = "api key 0123456789abcdef0123\u{200B}456789abcdef01234567";
4708        assert!(
4709            check(content).is_err(),
4710            "Unicode-separator split hex credential must be blocked: got {:?}",
4711            scan(content)
4712        );
4713    }
4714
4715    #[test]
4716    fn blocks_unicode_split_hex_credential_with_path_shaped_anchor() {
4717        let content =
4718            "api key handling uses source/x/0123456789abcdef0123\u{200B}456789abcdef01234567";
4719        let tokens: Vec<(usize, &str)> = content
4720            .split(|c: char| c.is_ascii_whitespace() || !c.is_ascii())
4721            .filter(|token| !token.is_empty())
4722            .map(|token| (token.as_ptr() as usize - content.as_ptr() as usize, token))
4723            .collect();
4724        let anchor = tokens
4725            .iter()
4726            .position(|(_, token)| token.starts_with("source/"))
4727            .expect("path anchor must be tokenized");
4728        assert!(is_plausible_file_path(tokens[anchor].1));
4729        let fragments = bridge_fragment_chain(&tokens, content, anchor);
4730        assert_eq!(fragments.len(), 2);
4731        assert!(contains_normalized_hex_credential(&fragments.join(" ")));
4732        assert!(
4733            check(content).is_err(),
4734            "path-shaped anchor must not bypass fragment reconstruction: got {:?}",
4735            scan(content)
4736        );
4737    }
4738
4739    #[test]
4740    fn blocks_separator_split_hex_credential_repeated_unicode_gap() {
4741        // Three U+200B zero-width spaces in a row
4742        // (9 bytes) would exceed a fixed byte-length gap bound (e.g. 8 bytes),
4743        // leaving the two 20-char hex halves unbridged. The fragment-chain
4744        // bridge is bounded by fragment COUNT (MAX_BRIDGE_FRAGMENTS), not
4745        // gap byte length, so repeating the delimiter buys an attacker
4746        // nothing: the gap between the two fragments still contains zero
4747        // ASCII alphanumeric characters, so it is still one bridgeable gap
4748        // regardless of how many times the delimiter repeats inside it.
4749        let content = "api key 0123456789abcdef0123\u{200B}\u{200B}\u{200B}456789abcdef01234567";
4750        assert!(
4751            check(content).is_err(),
4752            "repeated-Unicode-gap split hex credential must be blocked: got {:?}",
4753            scan(content)
4754        );
4755    }
4756
4757    #[test]
4758    fn blocks_separator_split_three_way_hex_credential_mixed_case() {
4759        // A 40-char mixed-case hex credential split
4760        // into THREE tokens by two single-U+200B gaps. Bridging only one
4761        // adjacent pair (`idx` with `idx + 1`, or `idx` with
4762        // `idx - 1`) would never reach the full
4763        // 40 chars. `bridge_fragment_chain` walks a bounded chain in both
4764        // directions, so starting from the first fragment reconstructs all
4765        // three. `is_ascii_hexdigit` accepts both cases, so the mixed-case
4766        // split (`AAAA...` alongside lowercase `cccc...`) must still
4767        // normalize to one 40-char hex sequence.
4768        let content = "api key AAAA1111bbbb22\u{200B}22cccc3333ddd\u{200B}d4444eeee5555";
4769        assert!(
4770            check(content).is_err(),
4771            "three-way mixed-case Unicode-split hex credential must be blocked: got {:?}",
4772            scan(content)
4773        );
4774    }
4775
4776    #[test]
4777    fn blocks_separator_split_base64_like_unicode_credential() {
4778        // A base64-like credential (mixed-case
4779        // alphanumeric, not hex) split by one U+200B into two 20-char
4780        // halves. A hex-only bridge candidacy gate would only admit pure-hex
4781        // short tokens, so neither half here (mixed-case, non-hex letters
4782        // like `X`, `k`, `Z`) ever reached the near-trigger bridge checks at
4783        // all. `is_bridge_candidate` now admits any short alphanumeric
4784        // token, and the reconstructed chain is checked against the SAME
4785        // whole-token entropy decision a genuine single-token high-entropy
4786        // candidate must clear — closing the hex-only gap without widening
4787        // detection to non-alphanumeric noise.
4788        let content = "api key Xk9mZ2vQpLrT8nJwYuAe\u{200B}HfBsDcGiONvMabcdefgh";
4789        assert!(
4790            check(content).is_err(),
4791            "base64-like Unicode-split credential must be blocked: got {:?}",
4792            scan(content)
4793        );
4794    }
4795
4796    #[test]
4797    fn blocks_punctuation_glue_between_two_unicode_gaps() {
4798        // Two 20-char hex fragments separated by a punctuation-only token (`---`)
4799        // sandwiched between two U+200B gaps: `is_delimiter_only_token` must let the
4800        // walk absorb `---` as glue (without counting it against MAX_BRIDGE_FRAGMENTS)
4801        // rather than stopping at it as a non-fragment token.
4802        let content = "api key 0123456789abcdef0123\u{200B}---\u{200B}456789abcdef01234567";
4803        assert!(
4804            check(content).is_err(),
4805            "punctuation-glue split hex credential between two Unicode gaps must be \
4806             blocked: got {:?}",
4807            scan(content)
4808        );
4809    }
4810
4811    #[test]
4812    fn allows_seven_way_hex_split_beyond_fragment_cap_documented_limitation() {
4813        // A 64-hex credential split into SEVEN
4814        // Unicode-separated fragments (each meeting MIN_BRIDGE_FRAGMENT_LEN)
4815        // exceeds MAX_BRIDGE_FRAGMENTS (6), so no chain the walk can build
4816        // ever reconstructs the full 64 chars. This is an ACCEPTED RESIDUAL
4817        // of the local-neighborhood bound, not a defect to fix here: per
4818        // ADR-096 / ADR-115 the secret gate is accidental-persistence
4819        // hygiene on a single-principal same-uid host, not defense against a
4820        // same-uid adversary hand-splitting a credential to evade it — that
4821        // adversary could write the DB directly instead. This test pins the
4822        // boundary so a future reader does not mistake it for an
4823        // unaddressed bypass.
4824        let content = "api key 012345678\u{200B}9abcdef01\u{200B}23456789a\u{200B}bcdef0123\u{200B}456789abc\u{200B}def012345\u{200B}6789abcdef";
4825        assert!(
4826            check(content).is_ok(),
4827            "seven-way hex split beyond MAX_BRIDGE_FRAGMENTS is a documented residual \
4828             limitation and must stay allowed: got {:?}",
4829            scan(content)
4830        );
4831    }
4832
4833    #[test]
4834    fn allows_six_way_sub_floor_hex_split_documented_limitation() {
4835        // A 40-hex credential split into six
4836        // Unicode-separated fragments each individually below
4837        // MIN_BRIDGE_FRAGMENT_LEN (8) — 7/7/7/7/6/6 characters. Every
4838        // fragment fails `is_bridge_candidate`, so none ever reaches
4839        // `bridge_fragment_chain` in the first place. Same accepted-residual
4840        // rationale as the seven-way split above: a same-uid adversary
4841        // splitting fragments this small to evade the gate can equally
4842        // write the DB directly. This test pins the boundary.
4843        let content = "api key 0123456\u{200B}789abcd\u{200B}ef01234\u{200B}56789ab\u{200B}cdef01\u{200B}234567";
4844        assert!(
4845            check(content).is_ok(),
4846            "six-way sub-MIN_BRIDGE_FRAGMENT_LEN hex split is a documented residual \
4847             limitation and must stay allowed: got {:?}",
4848            scan(content)
4849        );
4850    }
4851
4852    #[test]
4853    fn allows_unrelated_short_fragments_cited_near_a_trigger_word() {
4854        // False-positive guard: ordinary prose
4855        // citing two SEPARATE short hex/base64-ish identifiers (e.g. two
4856        // unrelated git SHA prefixes) near a trigger word must NOT combine
4857        // into a block just because a delimiter-only gap between them makes
4858        // them bridge-eligible. Each fragment is well under
4859        // MIN_BRIDGE_FRAGMENT_LEN's credential-length neighborhood, and the
4860        // reconstructed concatenation (16 chars) is neither a
4861        // HEX_CREDENTIAL_LENGTHS value nor at MIN_ENTROPY_LEN (24), so it
4862        // must stay allowed exactly like a real single fragment that short
4863        // would.
4864        let content = "api key: see commits abc12345, def67890 for the fix";
4865        assert!(
4866            check(content).is_ok(),
4867            "unrelated short fragments cited near a trigger word must stay allowed: \
4868             fired {:?}",
4869            scan(content)
4870        );
4871    }
4872
4873    #[test]
4874    fn allows_unrelated_short_base64_like_fragments_cited_near_a_trigger_word() {
4875        // Same guard as above, for the newly-widened non-hex/base64-like
4876        // bridge path specifically: two short mixed-case alphanumeric build
4877        // identifiers separated by a plain space near a trigger word.
4878        // Reconstructed length (12 chars) is far under MIN_ENTROPY_LEN (24),
4879        // so the generic entropy reconstruction must not fire.
4880        let content = "api key: build ids Ab3Kf9 and Xy7Lm2 do not match";
4881        assert!(
4882            check(content).is_ok(),
4883            "unrelated short base64-like fragments cited near a trigger word must \
4884             stay allowed: fired {:?}",
4885            scan(content)
4886        );
4887    }
4888
4889    #[test]
4890    fn allows_scattered_short_hex_runs_that_do_not_sum_to_a_credential_length() {
4891        // False-positive guard: short hex-looking runs
4892        // that happen to sit near a trigger word must NOT be flagged just
4893        // because they exist — only when their normalized concatenation
4894        // actually lands on a HEX_CREDENTIAL_LENGTHS value. Three
4895        // independent 8-char runs (running total 8, 16, 24) never hit
4896        // 32/40/64/128, and the whole-token entropy check that follows stays
4897        // below ENTROPY_THRESHOLD for this path-shaped content.
4898        let content = "auth config lives in abc12345/de678901/fa234567.md";
4899        assert!(
4900            check(content).is_ok(),
4901            "scattered short hex runs that never sum to a credential length \
4902             must stay allowed: fired {:?}",
4903            scan(content)
4904        );
4905    }
4906
4907    #[test]
4908    fn allows_fp_paths_whose_full_token_entropy_is_already_below_threshold() {
4909        // 4 of the 7 original FP-repro paths stay OK near a trigger word even
4910        // with NO structured-identifier exemption at all, because their own
4911        // full-token Shannon entropy already reads below ENTROPY_THRESHOLD
4912        // (4.5) — the exemption was never load-bearing for these regardless
4913        // of which version of it existed.
4914        let paths = [
4915            "release_notes_v2.md",
4916            "docs/adr/ADR-055-epistemic-edge-relations.md",
4917            "crates/khive-pack-session/src/mirror/ingest.rs",
4918            "check_entropy_heuristic_impl",
4919        ];
4920        for p in paths {
4921            let content = format!("api_key handling in {p}");
4922            assert!(
4923                check(&content).is_ok(),
4924                "{p} must stay allowed near 'api_key' (full-token entropy already \
4925                 below threshold): fired {:?}",
4926                scan(&content)
4927            );
4928        }
4929    }
4930
4931    #[test]
4932    fn allows_adr_draft_path_near_trigger() {
4933        let content = "api_key handling in fable-ops/ADR-DRAFT-adr079-slices234.md";
4934        assert!(
4935            check(content).is_ok(),
4936            "ADR-DRAFT path in technical prose must pass; got {:?}",
4937            scan(content)
4938        );
4939    }
4940
4941    #[test]
4942    fn allows_workspace_packet_path_near_trigger() {
4943        let content = "api_key handling in internal/workspaces/20260701/adr079-slices234/PACKET.md";
4944        assert!(
4945            check(content).is_ok(),
4946            "workspace path in technical prose must pass; got {:?}",
4947            scan(content)
4948        );
4949    }
4950
4951    #[test]
4952    fn allows_high_entropy_repo_audit_path_near_api_key() {
4953        let content =
4954            "api_key handling in internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md";
4955        assert!(
4956            check(content).is_ok(),
4957            "repository path in technical prose must pass; got {:?}",
4958            scan(content)
4959        );
4960    }
4961
4962    #[test]
4963    fn allows_source_paths_near_ordinary_key_and_token_prose() {
4964        let contents = [
4965            "see <a/path/to/file.py>:~97-103 lists it as a real checkpoint-supplied key",
4966            "see <a/path/to/file.py>:~97-103 emits one extra token",
4967            "see /workspace/src/checkpoint_loader.rs:97-103\n\nconfiguration key behavior",
4968            "the token behavior is implemented in src/runtime/secret_gate.rs:618-914.",
4969        ];
4970        for content in contents {
4971            assert!(
4972                check(content).is_ok(),
4973                "source path in technical prose must pass: {content:?}, got {:?}",
4974                scan(content)
4975            );
4976        }
4977    }
4978
4979    #[test]
4980    fn allows_adr_authorization_path_in_markdown_ingest() {
4981        let content =
4982            "- Evidence: `docs/adr/C-ADR-007-authorization-server.md:70` defines token handling.";
4983        assert!(
4984            check(content).is_ok(),
4985            "ADR path citation in technical markdown must pass: got {:?}",
4986            scan(content)
4987        );
4988    }
4989
4990    #[test]
4991    fn blocks_markdown_ingest_bare_opaque_value_near_token() {
4992        let content = concat!(
4993            "- Review evidence for token handling: ",
4994            "Xk9mZ2vQpLrT8nJwYuAeHfBs",
4995            "DcGiONvM1qPrStUvWxYz23456789"
4996        );
4997        assert_eq!(
4998            scan(content).map(|matched| matched.detector),
4999            Some("high-entropy-token"),
5000            "bare opaque value near token must remain blocked"
5001        );
5002    }
5003
5004    // ── UUID / content-hash allowlists are prose-context only ───────────────
5005
5006    #[test]
5007    fn blocks_uuid_directly_labeled_as_api_key() {
5008        let content = "api_key 550e8400-e29b-41d4-a716-446655440000";
5009        assert!(
5010            check(content).is_err(),
5011            "UUID-shaped token labeled api_key must be blocked; got {:?}",
5012            scan(content)
5013        );
5014    }
5015
5016    #[test]
5017    fn blocks_sha256_content_hash_labeled_as_secret() {
5018        let content = "secret sha256-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopq";
5019        assert!(
5020            check(content).is_err(),
5021            "sha256-prefixed hash labeled secret must be blocked; got {:?}",
5022            scan(content)
5023        );
5024    }
5025
5026    #[test]
5027    fn blocks_sha384_content_hash_labeled_as_api_key() {
5028        let content =
5029            "api_key sha384-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
5030        assert!(
5031            check(content).is_err(),
5032            "sha384-prefixed hash labeled api_key must be blocked; got {:?}",
5033            scan(content)
5034        );
5035    }
5036
5037    #[test]
5038    fn blocks_sha512_content_hash_labeled_as_auth() {
5039        let content = "auth sha512-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/ABCDEFGHIJKLMNOPQRSTUV";
5040        assert!(
5041            check(content).is_err(),
5042            "sha512-prefixed hash labeled auth must be blocked; got {:?}",
5043            scan(content)
5044        );
5045    }
5046
5047    #[test]
5048    fn allows_uuid_with_no_trigger_within_window() {
5049        // Common benign shape: a UUID (e.g. an internal record id) with no
5050        // credential trigger word anywhere in the surrounding window stays
5051        // allowed — the allowlist still applies outside trigger context.
5052        let content =
5053            "task 550e8400-e29b-41d4-a716-446655440000 was created and assigned to the team";
5054        assert!(
5055            check(content).is_ok(),
5056            "UUID with no nearby trigger word must stay allowed; got {:?}",
5057            scan(content)
5058        );
5059    }
5060
5061    #[test]
5062    fn allows_area_id_uuid_near_authorized_substring() {
5063        // An internal task `area_id` UUID field sitting within the trigger
5064        // window of the SUBSTRING "auth" inside
5065        // `authorized_write_requires_dominance` is not a genuine mention of
5066        // the word "auth": it is a pure substring collision with
5067        // "authorized". Bare trigger words match at a word boundary (see
5068        // `contains_bounded_word`), so `auth` does not match inside
5069        // `authorized`; this UUID has no trigger in its window and passes via
5070        // the ordinary out-of-context UUID allowlist.
5071        let content = "area_id: cfcea31d-6f50-4fd1-ad6d-5f160de1694c\n\n## Problem\nReduce Lion microkernel axioms. Converted authorized_write_requires_dominance from axiom to theorem.";
5072        assert!(
5073            check(content).is_ok(),
5074            "internal area_id UUID near the 'authorized' substring \
5075             (not a genuine 'auth' mention) must now pass; got {:?}",
5076            scan(content)
5077        );
5078    }
5079
5080    // ── UUID/hash value extraction from assignment and wrapper syntax ───────
5081
5082    #[test]
5083    fn blocks_uuid_glued_to_assignment_equals() {
5084        let content = "api_key=550e8400-e29b-41d4-a716-446655440000";
5085        assert!(
5086            check(content).is_err(),
5087            "UUID glued via '=' to a trigger word must be blocked; got {:?}",
5088            scan(content)
5089        );
5090    }
5091
5092    #[test]
5093    fn blocks_uuid_with_trailing_sentence_period() {
5094        let content = "api_key 550e8400-e29b-41d4-a716-446655440000.";
5095        assert!(
5096            check(content).is_err(),
5097            "UUID with a trailing sentence period near a trigger must be blocked; got {:?}",
5098            scan(content)
5099        );
5100    }
5101
5102    #[test]
5103    fn blocks_uuid_wrapped_in_parens() {
5104        let content = "api_key (550e8400-e29b-41d4-a716-446655440000)";
5105        assert!(
5106            check(content).is_err(),
5107            "UUID wrapped in parens near a trigger must be blocked; got {:?}",
5108            scan(content)
5109        );
5110    }
5111
5112    #[test]
5113    fn blocks_uuid_in_json_object() {
5114        let content = "{\"api_key\":\"550e8400-e29b-41d4-a716-446655440000\"}";
5115        assert!(
5116            check(content).is_err(),
5117            "UUID in a JSON-ish object near a trigger key must be blocked; got {:?}",
5118            scan(content)
5119        );
5120    }
5121
5122    #[test]
5123    fn blocks_content_hash_glued_to_assignment_equals() {
5124        let content = "secret=sha256-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopq";
5125        assert!(
5126            check(content).is_err(),
5127            "sha256-prefixed hash glued via '=' to a trigger word must be blocked; \
5128             got {:?}",
5129            scan(content)
5130        );
5131    }
5132
5133    #[test]
5134    fn blocks_content_hash_with_trailing_sentence_period() {
5135        let content = "secret sha256-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopq.";
5136        assert!(
5137            check(content).is_err(),
5138            "sha256-prefixed hash with a trailing period near a trigger must be \
5139             blocked; got {:?}",
5140            scan(content)
5141        );
5142    }
5143
5144    #[test]
5145    fn blocks_content_hash_wrapped_in_parens() {
5146        let content = "secret (sha256-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopq)";
5147        assert!(
5148            check(content).is_err(),
5149            "sha256-prefixed hash wrapped in parens near a trigger must be blocked; \
5150             got {:?}",
5151            scan(content)
5152        );
5153    }
5154
5155    #[test]
5156    fn blocks_content_hash_in_json_object() {
5157        let content = "{\"secret\":\"sha256-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopq\"}";
5158        assert!(
5159            check(content).is_err(),
5160            "sha256-prefixed hash in a JSON-ish object near a trigger key must be \
5161             blocked; got {:?}",
5162            scan(content)
5163        );
5164    }
5165
5166    #[test]
5167    fn allows_uuid_wrapped_in_parens_with_no_trigger_nearby() {
5168        // Control: the prose allowlist must survive for wrapper syntax when
5169        // there is no credential trigger word anywhere in the window — only
5170        // the trigger-context extraction changed, not the outside-context
5171        // allowlist itself.
5172        let content = "wrapper (550e8400-e29b-41d4-a716-446655440000) present";
5173        assert!(
5174            check(content).is_ok(),
5175            "UUID wrapped in parens with no trigger word nearby must stay allowed; \
5176             got {:?}",
5177            scan(content)
5178        );
5179    }
5180
5181    #[test]
5182    fn blocks_padded_content_hash_glued_to_assignment_with_trailing_period() {
5183        // A padded base64 value ends in its own `=`, which is also a valid
5184        // separator character — `value_candidates` must enumerate the
5185        // suffix after every `=`/`:`, not assume any single separator
5186        // position, so the true value is recovered regardless of which
5187        // separator happens to sit where.
5188        let content = "secret=sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=.";
5189        assert!(
5190            check(content).is_err(),
5191            "padded sha256 hash glued via '=' with a trailing period must be \
5192             blocked; got {:?}",
5193            scan(content)
5194        );
5195    }
5196
5197    #[test]
5198    fn blocks_padded_content_hash_in_json_object() {
5199        let content = "{\"secret\":\"sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=\"}";
5200        assert!(
5201            check(content).is_err(),
5202            "padded sha256 hash in a JSON-ish object near a trigger key must be \
5203             blocked; got {:?}",
5204            scan(content)
5205        );
5206    }
5207
5208    #[test]
5209    fn blocks_uuid_when_json_label_itself_contains_colon() {
5210        // The label can itself contain the separator character
5211        // (`"api:key"` rather than `"api_key"`); the first `:` after
5212        // wrapper-stripping then lands inside the label, not at the
5213        // label/value boundary. value_candidates must still surface the
5214        // bare UUID as a later suffix candidate.
5215        let content = "{\"api:key\":\"550e8400-e29b-41d4-a716-446655440000\"}";
5216        assert!(
5217            check(content).is_err(),
5218            "UUID must be blocked even when the JSON label contains ':'; got {:?}",
5219            scan(content)
5220        );
5221    }
5222
5223    #[test]
5224    fn blocks_uuid_when_json_label_itself_contains_equals() {
5225        let content = "{\"api=key\":\"550e8400-e29b-41d4-a716-446655440000\"}";
5226        assert!(
5227            check(content).is_err(),
5228            "UUID must be blocked even when the JSON label contains '='; got {:?}",
5229            scan(content)
5230        );
5231    }
5232
5233    #[test]
5234    fn blocks_uuid_behind_doubled_assignment() {
5235        // key=label=value: the first `=` lands between two labels, not at
5236        // the true value boundary.
5237        let content = "api_key=label=550e8400-e29b-41d4-a716-446655440000"; // gitleaks:allow
5238        assert!(
5239            check(content).is_err(),
5240            "UUID must be blocked behind a doubled assignment; got {:?}",
5241            scan(content)
5242        );
5243    }
5244
5245    #[test]
5246    fn blocks_padded_content_hash_behind_doubled_assignment_equals() {
5247        let content = "secret=label=sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=.";
5248        assert!(
5249            check(content).is_err(),
5250            "padded content hash must be blocked behind a doubled '=' assignment; \
5251             got {:?}",
5252            scan(content)
5253        );
5254    }
5255
5256    #[test]
5257    fn blocks_padded_content_hash_behind_doubled_assignment_colon() {
5258        let content = "secret:label=sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=.";
5259        assert!(
5260            check(content).is_err(),
5261            "padded content hash must be blocked behind a doubled ':'+'=' \
5262             assignment; got {:?}",
5263            scan(content)
5264        );
5265    }
5266
5267    #[test]
5268    fn allows_benign_url_with_scheme_and_path_separators() {
5269        // `value_candidates`'s any-suffix semantics must not block ordinary
5270        // URLs, whose `://` and `/` characters produce several suffix
5271        // candidates but none of them are UUID- or content-hash-shaped.
5272        // Placed near a real trigger word ("key") so the check actually
5273        // exercises the trigger-context path rather than being skipped
5274        // outright.
5275        let content = "api_key endpoint=https://example.test/resource/for/testing";
5276        assert!(
5277            check(content).is_ok(),
5278            "a benign URL near a trigger word must stay allowed; got {:?}",
5279            scan(content)
5280        );
5281    }
5282
5283    // ── Trigger word-boundary matching ──────────────────────────────────────
5284
5285    #[test]
5286    fn allows_trigger_substrings_inside_benign_path_slugs() {
5287        let paths = [
5288            "docs/_archive/adr_v0/ADR-051-cli-auth-and-kg-git-workflow.md",
5289            "docs/platform/oauth-callback-docs-and-redirect-handling-v2.md",
5290            "docs/research/author-attribution-and-collaboration-notes.md",
5291            "docs/security/passwordless-authentication-overview-v3.md",
5292            "docs/platform/private_keynote-authoring-guide-v2.md",
5293        ];
5294        for path in paths {
5295            assert!(
5296                check(path).is_ok(),
5297                "trigger substring inside a benign path slug must not make the path \
5298                 its own credential context: {path:?}, got {:?}",
5299                scan(path)
5300            );
5301        }
5302    }
5303
5304    #[test]
5305    fn blocks_inline_auth_assignment_with_high_entropy_value() {
5306        let content = "auth=Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
5307        assert!(
5308            check(content).is_err(),
5309            "auth=<high-entropy-value> must still be blocked; got {:?}",
5310            scan(content)
5311        );
5312    }
5313
5314    #[test]
5315    fn blocks_suffix_bearing_compound_credential_assignments() {
5316        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
5317        let cases = [
5318            format!("api_keyv2={opaque}"),
5319            format!("access_keyv2={opaque}"),
5320            format!("private_keyv2={opaque}"),
5321            format!("API_KEYV2={opaque}"),
5322            format!(r#"{{"private_keyv2":"{opaque}"}}"#),
5323        ];
5324        for content in &cases {
5325            assert!(
5326                check(content).is_err(),
5327                "suffix-bearing compound credential assignment must be blocked: \
5328                 {content:?}, got {:?}",
5329                scan(content)
5330            );
5331        }
5332    }
5333
5334    #[test]
5335    fn blocks_spaced_suffix_bearing_compound_credential_assignments() {
5336        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
5337        for label in ["api_keyv2", "access_keyv2", "private_keyv2"] {
5338            let cases = [
5339                format!("{label} = {opaque}"),
5340                format!("{label} : {opaque}"),
5341                format!(r#"{{"{label}": "{opaque}"}}"#),
5342            ];
5343            for content in &cases {
5344                assert!(
5345                    check(content).is_err(),
5346                    "spaced suffix-bearing compound credential assignment must be \
5347                     blocked: {content:?}, got {:?}",
5348                    scan(content)
5349                );
5350            }
5351        }
5352    }
5353
5354    #[test]
5355    fn blocks_suffix_bearing_compound_credentials_without_assignment_separator() {
5356        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
5357        for label in ["api_keyv2", "access_keyv2", "private_keyv2"] {
5358            let cases = [format!("{label} {opaque}"), format!("{label}{opaque}")];
5359            for content in &cases {
5360                assert!(
5361                    check(content).is_err(),
5362                    "suffix-bearing compound credential without an assignment separator must be \
5363                     blocked: {content:?}, got {:?}",
5364                    scan(content)
5365                );
5366                assert!(
5367                    mask_secrets(content).contains(REDACTION_MARKER),
5368                    "shared secret masker must redact separator-free compound credential: \
5369                     {content:?}"
5370                );
5371            }
5372        }
5373
5374        let prefixed = "xapi_keyv2=Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
5375        assert!(
5376            check(prefixed).is_err(),
5377            "prefix-bearing compound credential assignment must be blocked: \
5378             {prefixed:?}, got {:?}",
5379            scan(prefixed)
5380        );
5381    }
5382
5383    #[test]
5384    fn allows_authorized_and_authentication_prose_near_uuid() {
5385        // The word-boundary fix directly: "auth" no longer matches the
5386        // substring inside "authorized"/"authentication", so ordinary prose
5387        // using those words does not poison the trigger window for a nearby
5388        // UUID or other allowlisted shape.
5389        let cases = [
5390            "authorized_write_requires_dominance was converted from axiom to theorem, id 550e8400-e29b-41d4-a716-446655440000",
5391            "authentication flow diagram lives at 550e8400-e29b-41d4-a716-446655440000",
5392        ];
5393        for content in cases {
5394            assert!(
5395                check(content).is_ok(),
5396                "'authorized'/'authentication' substring must not trigger the \
5397                 entropy heuristic: {content:?}, got {:?}",
5398                scan(content)
5399            );
5400        }
5401    }
5402
5403    #[test]
5404    fn allows_turkey_monkey_keyword_prose_near_uuid() {
5405        // Other bare-word substring collisions in TRIGGER_WORDS ("key") must
5406        // likewise not fire on ordinary English words that merely contain it.
5407        let cases = [
5408            "the turkey and monkey story references id 550e8400-e29b-41d4-a716-446655440000",
5409            "keyword research doc: 550e8400-e29b-41d4-a716-446655440000",
5410        ];
5411        for content in cases {
5412            assert!(
5413                check(content).is_ok(),
5414                "'turkey'/'monkey'/'keyword' substring must not trigger the \
5415                 entropy heuristic: {content:?}, got {:?}",
5416                scan(content)
5417            );
5418        }
5419    }
5420
5421    #[test]
5422    fn blocks_opaque_tokens_near_standalone_trigger_words() {
5423        // Word-boundary matching only removes SUBSTRING collisions; a genuine
5424        // standalone trigger word must still dominate exactly as before.
5425        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
5426        let cases = [
5427            format!("auth header {opaque}"),
5428            format!("the key is {opaque}"),
5429            format!("secret value: {opaque}"),
5430        ];
5431        for content in &cases {
5432            assert!(
5433                check(content).is_err(),
5434                "a genuine standalone trigger word must still block: {content:?}, \
5435                 got {:?}",
5436                scan(content)
5437            );
5438        }
5439    }
5440
5441    #[test]
5442    fn accepted_false_positive_workspace_artifact_path_behind_attributive_trigger() {
5443        // "secret gate false positive repro: <path>" carries a trigger word
5444        // in clause range ahead of a value delimiter. The clause walk no
5445        // longer caps content words after a delimiter (any cap re-admits the
5446        // chained-qualifier labeled-value bypass), so this meta-prose shape
5447        // blocks. Accepted false positive — same attributive-trigger class
5448        // as the auth-setup docs path; documented in docs/api/secret_gate.md.
5449        let content = "writing up the secret gate false positive repro: \
5450             .workspace/20260101/fix-secret-gate-trigger-false-positive/MEASUREMENT_REPORT.md";
5451        assert!(
5452            check(content).is_err(),
5453            "accepted-FP contract changed: attributive trigger before a \
5454             delimited path no longer blocks — update the docs if deliberate"
5455        );
5456    }
5457
5458    #[test]
5459    fn accepted_false_positive_archive_doc_path_behind_attributive_trigger() {
5460        // "secret scanner archive notes: <path>" — attributive trigger two
5461        // qualifiers ahead of the delimiter. Same accepted-FP class as
5462        // above; the walk cannot tell an attributive trigger from a label
5463        // head without reopening the chained-qualifier bypass.
5464        let content =
5465            "secret scanner archive notes: docs/_archive/ADR051-TenantEncryption-v2Notes.md";
5466        assert!(
5467            check(content).is_err(),
5468            "accepted-FP contract changed: attributive trigger before a \
5469             delimited path no longer blocks — update the docs if deliberate"
5470        );
5471    }
5472
5473    #[test]
5474    fn allows_absolute_path_near_standalone_auth() {
5475        let content = "the auth scanner flagged this file: /home/user/projects/workspace/SessionNotes20260107/AuthGateFollowup2.md";
5476        assert!(
5477            check(content).is_ok(),
5478            "absolute path in technical prose must pass; got {:?}",
5479            scan(content)
5480        );
5481    }
5482
5483    #[test]
5484    fn blocks_assignment_shaped_credential_disguised_as_path_near_api_key() {
5485        // Adversarial negative: a credential-shaped value glued via '='
5486        // directly to a trigger word must not be exempted just because it is
5487        // path-shaped (separator-delimited, word-shaped runs) and looks
5488        // superficially like the technical paths above. The compound label
5489        // `api_key` makes this a credential value, so it must block.
5490        let content = "api_key=/home/user/workspaces/2026/topic-name-example/SECRET_VALUE_HERE.md";
5491        assert!(
5492            check(content).is_err(),
5493            "assignment-shaped credential disguised as a path must still be \
5494             blocked: {content:?}, got {:?}",
5495            scan(content)
5496        );
5497    }
5498
5499    #[test]
5500    fn blocks_separator_split_secret_access_key_compound() {
5501        // Adversarial negative: a separator-split bypass shape must still be
5502        // blocked. The `secret` and `key` entries both match because underscore
5503        // is a boundary for bare `TRIGGER_WORDS`. This asserts the end-to-end
5504        // outcome.
5505        let content = "secret_access_key abcdefghij/klmnopqrst/uvwxyzabcd/efghijk.md";
5506        assert!(
5507            check(content).is_err(),
5508            "secret_access_key bypass shape must still be blocked: {content:?}, \
5509             got {:?}",
5510            scan(content)
5511        );
5512    }
5513
5514    // ── Underscore is a BOUNDARY for bare TRIGGER_WORDS, not a continuation ─
5515    // Opposite of `has_standalone_token`'s rule for `token`: treating underscore as a
5516    // boundary here is what keeps `SECRET_KEY=`/`auth_token=`/`signing_key=` detected
5517    // (`contains_word`'s `underscore_is_word_char` parameter controls this per caller).
5518
5519    #[test]
5520    fn blocks_secret_key_assignment_when_underscore_bounds_trigger() {
5521        // `SECRET_KEY=<value>` must block via the plain-substring `secret`
5522        // trigger even though `secret` is followed by `_` rather than a
5523        // non-word-char boundary.
5524        let content = "SECRET_KEY=dGhpc2lzYXNlY3JldGtleXZhbHVlMTIzNDU2Nzg5MA=="; // gitleaks:allow
5525        assert!(
5526            check(content).is_err(),
5527            "SECRET_KEY=<value> (Django/Flask-style config) must still be \
5528             blocked: {content:?}, got {:?}",
5529            scan(content)
5530        );
5531    }
5532
5533    #[test]
5534    fn blocks_auth_token_assignment_when_underscore_bounds_trigger() {
5535        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
5536        let content = format!("auth_token={opaque}");
5537        assert!(
5538            check(&content).is_err(),
5539            "auth_token=<value> must still be blocked: {content:?}, got {:?}",
5540            scan(&content)
5541        );
5542    }
5543
5544    #[test]
5545    fn blocks_underscore_joined_session_secret_and_signing_key_compounds() {
5546        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
5547        let cases = [
5548            format!("session_secret_{opaque}"),
5549            format!("signing_key={opaque}"),
5550        ];
5551        for content in &cases {
5552            assert!(
5553                check(content).is_err(),
5554                "underscore-joined credential compound must still be blocked: \
5555                 {content:?}, got {:?}",
5556                scan(content)
5557            );
5558        }
5559    }
5560
5561    #[test]
5562    fn allows_letter_joined_trigger_substrings_in_benign_prose() {
5563        // The letter-joined substring-collision exemption must survive the
5564        // underscore-as-boundary change, since that change only affects the
5565        // underscore character, not letter-joined words.
5566        let cases = [
5567            "authorized_write_requires_dominance was converted from axiom to theorem, id 550e8400-e29b-41d4-a716-446655440000",
5568            "authentication flow diagram lives at 550e8400-e29b-41d4-a716-446655440000",
5569            "the turkey and monkey story references id 550e8400-e29b-41d4-a716-446655440000",
5570            "keyword research doc: 550e8400-e29b-41d4-a716-446655440000",
5571        ];
5572        for content in cases {
5573            assert!(
5574                check(content).is_ok(),
5575                "letter-joined substring collision must stay exempt: \
5576                 {content:?}, got {:?}",
5577                scan(content)
5578            );
5579        }
5580    }
5581
5582    #[test]
5583    fn block_message_carries_actionable_guidance() {
5584        let fake = "AKIAFAKEKEY1234567890";
5585        let m = scan(fake).unwrap();
5586        let rendered = m.to_string();
5587        assert!(
5588            rendered.contains("real credential"),
5589            "block message must carry actionable guidance: {rendered}"
5590        );
5591    }
5592
5593    #[test]
5594    fn block_message_shape_guidance_mentions_rewording() {
5595        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
5596        let content = format!("auth header {opaque}");
5597        let m = scan(&content).unwrap();
5598        let rendered = m.to_string();
5599        assert!(
5600            rendered.contains("reword") || rendered.contains("own line"),
5601            "shape-based detector guidance must suggest rewording/splitting: {rendered}"
5602        );
5603    }
5604}
5605
5606// ─── Corpus replay harness (manual, opt-in) ─────────────────────────────────
5607//
5608// Measures how many real note/entity strings the gate blocks, so a detector
5609// change can be evaluated against production content rather than intuition
5610// (see the module doc). Opens the target database
5611// STRICTLY read-only (`SQLITE_OPEN_READ_ONLY`) and never mutates it. Point
5612// `KHIVE_REPLAY_DB` at a copy or a live KG database file path; the harness
5613// never writes, locks aggressively, or deletes anything.
5614//
5615// Run with: `KHIVE_REPLAY_DB=/path/to/khive.db cargo test -p khive-runtime \
5616//   --release -- --ignored --nocapture corpus_replay`
5617#[cfg(test)]
5618mod corpus_replay {
5619    use super::*;
5620    use rusqlite::{Connection, OpenFlags};
5621
5622    // ── Whole-token-average entropy dilution (issue #1044, false-negative) ──
5623
5624    #[test]
5625    fn blocks_hex_credential_diluted_by_filler_path_segments() {
5626        // A real 40-char hex credential as one path segment among low-entropy
5627        // filler segments. Whole-token-average entropy is diluted below
5628        // ENTROPY_THRESHOLD, and the whole token is not pure hex (it has `/`
5629        // and `.` in it), so neither the whole-token entropy check nor the
5630        // whole-token hex-credential-token check catches it — only a per-run
5631        // check does.
5632        let line = "api key vault/9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c/rotate.md";
5633        let m = scan(line);
5634        assert!(
5635            m.is_some(),
5636            "hex credential diluted by filler path segments must be blocked; got None"
5637        );
5638        assert_eq!(m.unwrap().detector, "hex-credential-token");
5639    }
5640
5641    #[test]
5642    fn blocks_chopped_secret_padded_by_filler_runs() {
5643        // A random high-entropy run planted among short filler runs. Whole-
5644        // token-average entropy is diluted below threshold by the filler.
5645        let line = "secret path a/b/c/d/Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM/e/f.rs"; // gitleaks:allow
5646        let m = scan(line);
5647        assert!(
5648            m.is_some(),
5649            "chopped/padded secret among filler runs must be blocked; got None"
5650        );
5651        assert_eq!(m.unwrap().detector, "high-entropy-token");
5652    }
5653
5654    #[test]
5655    fn allows_real_paths_with_no_run_reaching_min_entropy_len() {
5656        // Regression guard: the #1040 measurement corpus's real path false
5657        // positives never contain a single run >= MIN_ENTROPY_LEN, so the new
5658        // per-run check introduced for #1044 must not newly block them.
5659        let contents = [
5660            "branch feat-session-mirror pushed, see release_notes_v2.md for the key findings",
5661            "password reset doc: docs/adr/ADR-055-epistemic-edge-relations.md",
5662            "credential handling code crates/khive-pack-session/src/mirror/ingest.rs",
5663            "api key handling lives in check_entropy_heuristic_impl",
5664        ];
5665        for content in contents {
5666            assert!(
5667                check(content).is_ok(),
5668                "real path with no long run must still pass; fired: {:?}",
5669                scan(content)
5670            );
5671        }
5672    }
5673
5674    #[test]
5675    #[ignore]
5676    fn replay_against_corpus() {
5677        let db_path = std::env::var("KHIVE_REPLAY_DB")
5678            .expect("set KHIVE_REPLAY_DB=/path/to/khive.db to run the corpus replay (read-only)");
5679        let conn = Connection::open_with_flags(
5680            &db_path,
5681            OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
5682        )
5683        .expect("open corpus DB read-only");
5684
5685        let mut total = 0usize;
5686        let mut blocked = 0usize;
5687        let mut samples: Vec<String> = Vec::new();
5688
5689        let mut collect = |sql: &str| {
5690            let mut stmt = conn.prepare(sql).expect("prepare replay query");
5691            let mut rows = stmt.query([]).expect("query replay rows");
5692            while let Some(row) = rows.next().expect("read replay row") {
5693                let content: Option<String> = row.get(0).unwrap_or(None);
5694                let Some(content) = content else { continue };
5695                if content.is_empty() {
5696                    continue;
5697                }
5698                total += 1;
5699                if let Some(m) = scan(&content) {
5700                    blocked += 1;
5701                    if samples.len() < 30 {
5702                        samples.push(format!(
5703                            "{} :: {}",
5704                            m,
5705                            content.chars().take(160).collect::<String>()
5706                        ));
5707                    }
5708                }
5709            }
5710        };
5711
5712        collect("SELECT content FROM notes WHERE deleted_at IS NULL");
5713        collect("SELECT description FROM entities WHERE deleted_at IS NULL");
5714
5715        eprintln!("corpus replay: {blocked}/{total} strings blocked");
5716        for s in &samples {
5717            eprintln!("  BLOCKED: {s}");
5718        }
5719    }
5720
5721    /// Generates the sanitized corpus manifest at
5722    /// `tests/data/secret_gate_corpus_manifest.md`: per-detector block counts plus a
5723    /// sha256 of each blocked candidate, never the candidate text itself. Point-in-time
5724    /// generator, not a CI check — re-run manually (`KHIVE_REPLAY_DB=... cargo test -p
5725    /// khive-runtime --release -- --ignored --nocapture generate_corpus_manifest`) and
5726    /// hand-update the checked-in file when the detector set changes.
5727    #[test]
5728    #[ignore]
5729    fn generate_corpus_manifest() {
5730        use sha2::{Digest, Sha256};
5731        use std::collections::BTreeMap;
5732
5733        let db_path = std::env::var("KHIVE_REPLAY_DB")
5734            .expect("set KHIVE_REPLAY_DB=/path/to/khive.db to run the corpus replay (read-only)");
5735        let conn = Connection::open_with_flags(
5736            &db_path,
5737            OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
5738        )
5739        .expect("open corpus DB read-only");
5740
5741        let mut total = 0usize;
5742        let mut counts_by_detector: BTreeMap<&'static str, usize> = BTreeMap::new();
5743        let mut hashes_by_detector: BTreeMap<&'static str, Vec<String>> = BTreeMap::new();
5744        let mut max_run_reaching_min_entropy_len = 0usize;
5745
5746        let mut collect = |sql: &str| {
5747            let mut stmt = conn.prepare(sql).expect("prepare replay query");
5748            let mut rows = stmt.query([]).expect("query replay rows");
5749            while let Some(row) = rows.next().expect("read replay row") {
5750                let content: Option<String> = row.get(0).unwrap_or(None);
5751                let Some(content) = content else { continue };
5752                if content.is_empty() {
5753                    continue;
5754                }
5755                total += 1;
5756                // Track the #1040 soundness claim directly against the same
5757                // corpus this replay scans: the longest run any path-shaped
5758                // token contributes, so the "no real path false positive
5759                // reaches MIN_ENTROPY_LEN" claim is checked against actual
5760                // data rather than asserted.
5761                for token in content.split_whitespace() {
5762                    for run in token.split(|c: char| !c.is_ascii_alphanumeric()) {
5763                        max_run_reaching_min_entropy_len =
5764                            max_run_reaching_min_entropy_len.max(run.len());
5765                    }
5766                }
5767                if let Some(m) = scan(&content) {
5768                    *counts_by_detector.entry(m.detector).or_insert(0) += 1;
5769                    let hash = format!("{:x}", Sha256::digest(content.as_bytes()));
5770                    hashes_by_detector.entry(m.detector).or_default().push(hash);
5771                }
5772            }
5773        };
5774
5775        collect("SELECT content FROM notes WHERE deleted_at IS NULL");
5776        collect("SELECT description FROM entities WHERE deleted_at IS NULL");
5777
5778        let blocked: usize = counts_by_detector.values().sum();
5779        println!("total_scanned: {total}");
5780        println!("total_blocked: {blocked}");
5781        println!("longest_alphanumeric_run_in_corpus: {max_run_reaching_min_entropy_len}");
5782        println!("counts_by_detector:");
5783        for (detector, count) in &counts_by_detector {
5784            println!("  {detector}: {count}");
5785        }
5786        println!("blocked_content_sha256_by_detector:");
5787        for (detector, hashes) in &hashes_by_detector {
5788            println!("  {detector}:");
5789            for hash in hashes {
5790                println!("    {hash}");
5791            }
5792        }
5793    }
5794}