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 internally. Its display names the rule and trigger
6//! without echoing any candidate text.
7//!
8//! Scope: **credentials only** — API keys, tokens, private keys, passwords,
9//! and connection strings with embedded credentials. General PII (emails,
10//! phone numbers, company names) is intentionally NOT blocked.
11//!
12//! Detection is layered, cheap-first:
13//! 1. **Known-prefix / known-shape patterns** — AWS AKIA/ASIA, GitHub tokens,
14//! OpenAI `sk-proj-`, Anthropic `sk-ant-`, Stripe live keys, Fly.io tokens,
15//! Vercel secrets, Slack `xox*`, JWT triples, PEM private-key headers, Age
16//! secret keys, URL userinfo (`scheme://user:pass@`).
17//! 2. **High-entropy token heuristic** — base64/hex/base64url runs ≥ 24 chars
18//! near a trigger word (key, secret, password, credential, bearer, auth,
19//! apikey, api_key, access_key, private_key). A standalone `token` still
20//! triggers opaque entropy detection, but does not by itself label a UUID
21//! as a credential; compound identifiers such as `tokenizer_*` and
22//! `token_count` remain excluded.
23//!
24//! Credential-shaped labels and assignments dominate the allowlist below.
25//! Public VCS revisions and plausible file paths remain exempt in ordinary
26//! technical prose, while path segments are still scanned independently.
27//!
28//! Full exemption rules (hex/UUID/SRI-hash passes, non-ASCII token
29//! delimiting, structured-identifier decomposition, trigger word-boundary
30//! matching, the underscore-boundary asymmetry between bare trigger words and
31//! the word `token`, and the adversarial-corpus rationale for why some
32//! false positives are accepted) are documented in full in
33//! `docs/api/secret_gate.md#module-level-detection-algorithm` — read that before
34//! changing any detection or exemption logic in this file.
35//!
36//! The caller-visible block message (`SecretMatch`'s `Display` impl) also
37//! carries actionable guidance (`block_guidance`) to split or reword the
38//! flagged token.
39//!
40//! A production-corpus replay harness (`corpus_replay`, `#[ignore]`d, run via
41//! `KHIVE_REPLAY_DB=<path> cargo test ... -- --ignored --nocapture`) measures
42//! the detector's block rate against real note/entity content; see the
43//! harness's own output for current numbers rather than a point-in-time count
44//! here, which would drift as the corpus changes. A checked-in, sanitized
45//! snapshot of that replay (per-detector block counts and sha256 digests of
46//! blocked content, never the content itself) lives at
47//! `tests/data/secret_gate_corpus_manifest.md`, generated by
48//! `corpus_replay::generate_corpus_manifest`.
49//! A replay that is identical before and after a change certifies preservation
50//! on the corpus population only, never on the shape class the change opens;
51//! that class needs its own before/after arms.
52
53use crate::error::{RuntimeError, RuntimeResult};
54
55mod bridge_fragments;
56mod credential_triggers;
57mod entropy;
58mod escaped_json;
59mod false_positive_filters;
60mod known_patterns;
61mod masking;
62mod submitted_atom_digest;
63
64use bridge_fragments::{
65 bridge_fragment_chain, contains_bounded_word, contains_word, is_bridge_fragment_shape,
66 trailing_bridge_fragment_cut,
67};
68use credential_triggers::{
69 assignment_credential_trigger, build_match, extract_token, find_trigger,
70 inline_credential_trigger, is_assignment_label_gap, is_base64_content_hash,
71 is_credential_token_label, is_lookup_key_label, is_pure_hex, is_structured_identifier,
72 is_uuid_canonical, shannon_entropy, strip_delimiters, value_candidates, wrapper_strip_repeated,
73};
74#[cfg(test)]
75use credential_triggers::{LOOKUP_KEY_LABELS, POSITION_TOKEN_LABELS, RECEIPT_TOKEN_LABELS};
76#[cfg(test)]
77use entropy::TRIGGER_WINDOW;
78use entropy::{
79 check_entropy_heuristic, tokenize_entropy_tokens, EntropyScanContext, COMPOUND_TRIGGER_WORDS,
80 ENTROPY_THRESHOLD, HEX_CREDENTIAL_LENGTHS, MAX_BRIDGE_FRAGMENTS, MAX_BRIDGE_GLUE_TOKENS,
81 MIN_BRIDGE_FRAGMENT_LEN, MIN_ENTROPY_LEN, TRIGGER_WORDS,
82};
83use false_positive_filters::{
84 after_last_sentence_boundary, before_first_sentence_boundary,
85 has_clause_credential_label_with_inline, has_direct_repository_credential_label_with_inline,
86 has_immediate_credential_label, is_aws_resource_name, is_environment_name,
87 is_git_revision_reference, is_labeled_sha256_digest, is_latex_fragment_without_credential_run,
88 is_latex_prose_macro, is_plausible_file_path, is_prose_code_reference,
89 is_repository_revision_reference, is_vcs_marker_before_hex, normalized_hex_credential_span,
90 ClauseValueKind,
91};
92#[cfg(test)]
93use false_positive_filters::{is_clause_narrative_gerund, is_clause_narrative_participle};
94use known_patterns::check_known_patterns;
95#[cfg(doc)]
96use known_patterns::find_url_userinfo;
97#[cfg(test)]
98use known_patterns::{find_prefix_token, is_filename_shaped_prefix_match, PREFIX_DETECTORS};
99pub use masking::{
100 bounded_masked_log_text, mask_bounded, mask_secrets, BoundedMask, MASK_WINDOW_CHARS,
101};
102#[cfg(test)]
103use masking::{collect_mask_spans, MAX_LOG_TEXT_OUTPUT_CHARS, TRUNCATION_MARKER};
104use masking::{extend_across_invisible_bridge, MAX_LOG_TEXT_MASK_INPUT_CHARS};
105
106pub use submitted_atom_digest::masked_submitted_atom_digest_v1;
107
108// ─── Public API ──────────────────────────────────────────────────────────────
109
110/// Returned when a write would store credential-looking content.
111///
112/// Carries the detector name and a masked excerpt (`first6...Nchars`). The
113/// full candidate is never stored in the error.
114#[derive(Debug, Clone, PartialEq, Eq)]
115pub struct SecretMatch {
116 /// Human-readable name of the detector that fired.
117 pub detector: &'static str,
118 /// Canonical trigger from the matched context; known-prefix rules need none.
119 pub trigger: Option<&'static str>,
120 /// `first6...N` — the first 6 chars of the match followed by the total length.
121 pub masked: String,
122 /// Which record and field the match came from. `None` only where the
123 /// caller scanned exactly one string and nothing else, so there is one
124 /// candidate. A single-record verb that scans several fields still needs
125 /// this: the writer sees one refusal and cannot tell whether it was the
126 /// name, the content, a tag or a property that matched.
127 pub location: Option<String>,
128}
129
130impl std::fmt::Display for SecretMatch {
131 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
132 write!(f, "content matches secret pattern {}", self.detector)?;
133 if let Some(trigger) = self.trigger {
134 write!(f, " near '{trigger}'")?;
135 }
136 if let Some(location) = &self.location {
137 write!(f, " in {location}")?;
138 }
139 write!(f, ". {}", block_guidance(self.detector))
140 }
141}
142
143/// Actionable, caller-visible guidance for a hard block, keyed by detector
144/// name. If the content genuinely is a credential, remove it. If it
145/// is not — the common case for the detectors below, which key off SHAPE
146/// near a trigger word rather than a known credential prefix — the fix is to
147/// break up the flagged token so it no longer reads as one contiguous
148/// high-entropy value: separate it from words like key/secret/auth/token with
149/// a sentence or paragraph boundary, or use an explicit repository revision
150/// reference for a source hash.
151fn block_guidance(detector: &'static str) -> &'static str {
152 match detector {
153 "url-userinfo" => {
154 "Placeholders in URL credential positions still match this pattern. \
155 Replace the whole URL with an environment-variable name or config key, \
156 or remove the entire user/password segment before writing."
157 }
158 "high-entropy-token"
159 | "uuid-near-trigger"
160 | "content-hash-near-trigger"
161 | "hex-credential-token" => {
162 "If this is a real credential, remove it before writing. If it is not \
163 (e.g. a file path, UUID, or hash that happens to sit near a word like \
164 key/secret/auth/token), put the candidate in a separate sentence or \
165 paragraph from those words, or express a source hash as an explicit \
166 commit/revision reference."
167 }
168 "nested-escaped-json" => {
169 "This value holds JSON text with escaped strings nested deeper than the \
170 gate decodes. Store the inner document unescaped, or flatten the nesting, \
171 before writing."
172 }
173 _ => {
174 "If this is a real credential, remove it before writing; store secrets \
175 in an env var or secrets manager instead."
176 }
177 }
178}
179
180/// Hard-block content from being written.
181///
182/// Returns `Err(RuntimeError::SecretDetected)` on the first match found, or
183/// `Ok(())` if no secret pattern fires.
184pub fn check(content: &str) -> RuntimeResult<()> {
185 check_decoded(content, 0)
186}
187
188/// JSON documents nested inside escaped string values deeper than this are
189/// refused rather than passed unread.
190const MAX_ESCAPED_JSON_DEPTH: usize = 8;
191
192fn check_decoded(content: &str, depth: usize) -> RuntimeResult<()> {
193 if let Some(m) = scan(content) {
194 return Err(RuntimeError::SecretDetected(m));
195 }
196 for decoded in escaped_json::escaped_strings(content) {
197 if depth == MAX_ESCAPED_JSON_DEPTH {
198 return Err(RuntimeError::SecretDetected(build_match(
199 "nested-escaped-json",
200 &decoded,
201 )));
202 }
203 check_decoded(&decoded, depth + 1)?;
204 }
205 Ok(())
206}
207
208/// Recursively scan a JSON value for credential-shaped strings.
209///
210/// Walks every string leaf (object values, array elements, nested objects).
211/// Returns `Err(RuntimeError::SecretDetected)` on the first match found.
212/// `None` / null / numeric / boolean JSON values are skipped.
213pub fn check_json(value: &serde_json::Value) -> RuntimeResult<()> {
214 scan_json_value(value)
215}
216
217/// Scan a string-tagged slice (entity/note tags).
218///
219/// Each tag string is scanned individually.
220pub fn check_tags(tags: &[String]) -> RuntimeResult<()> {
221 for tag in tags {
222 check(tag)?;
223 }
224 Ok(())
225}
226
227/// Name the scope and field a refusal came from.
228///
229/// A batch verb scans each record and returns on the first refusal, so the
230/// caller gets ONE error for N records. Without this the error names only the
231/// matched text, which by construction is text the caller cannot find: it sits
232/// in whichever sibling record refused, and every other record in the call is
233/// rejected with it (khive #2605). Pass through anything that is not a gate
234/// refusal unchanged — this adds identity, it does not reclassify.
235///
236/// `record` names the record the field belongs to, as the caller submitted it:
237/// `entity`, `note`, `task`, `proposal`, `message`, indexed when it came from a
238/// batch (`note[2]`). It answers where in the submitted payload the writer
239/// should look, which is the question a refused writer actually asks.
240pub fn locate<T>(result: RuntimeResult<T>, record: &str, field: &str) -> RuntimeResult<T> {
241 result.map_err(|error| match error {
242 RuntimeError::SecretDetected(matched) => RuntimeError::SecretDetected(SecretMatch {
243 location: Some(format!("{record}.{field}")),
244 ..matched
245 }),
246 other => other,
247 })
248}
249
250/// `check` that names where it looked. `record` is the record noun the caller
251/// submitted, indexed inside a batch; `field` is the field of it that was scanned.
252pub fn check_at(content: &str, record: &str, field: &str) -> RuntimeResult<()> {
253 locate(check(content), record, field)
254}
255
256/// `check_json` that names where it looked. The location is the field holding
257/// the JSON, not the path of the string leaf that matched inside it.
258pub fn check_json_at(value: &serde_json::Value, record: &str, field: &str) -> RuntimeResult<()> {
259 locate(check_json(value), record, field)
260}
261
262/// Scan the supplied note fields in content, name, then properties order.
263///
264/// Returns the first refusal unchanged, located under `record` (for example,
265/// `note[2].properties`). Optional fields are scanned only when present; JSON
266/// scanning uses the same structured-value rules as [`check_json_at`].
267///
268/// This is field scanning only. Callers retain responsibility for property
269/// derivation, reserved-key checks, embedding inputs, and write admission, in
270/// their existing order.
271pub fn check_note_fields_at(
272 content: &str,
273 name: Option<&str>,
274 properties: Option<&serde_json::Value>,
275 record: &str,
276) -> RuntimeResult<()> {
277 check_at(content, record, "content")?;
278 if let Some(name) = name {
279 check_at(name, record, "name")?;
280 }
281 if let Some(properties) = properties {
282 check_json_at(properties, record, "properties")?;
283 }
284 Ok(())
285}
286
287/// `check_tags` that names where it looked.
288pub fn check_tags_at(tags: &[String], record: &str, field: &str) -> RuntimeResult<()> {
289 locate(check_tags(tags), record, field)
290}
291
292// ─── Reserved property keys ──────────────────────────────────────────────────
293
294/// Top-level JSON property key reserved for runtime-owned exemption state.
295///
296/// No caller may create, replace, merge, or remove this key through any
297/// properties-bearing write path — ADR-115 Amendment 1 §3. Reservation binds
298/// unconditionally: the runtime does not yet stamp any record with this key
299/// (the finalizer that would do so is a separate, later increment), so no
300/// caller-supplied occurrence of it can ever be a legitimate echo of
301/// persisted state. Only the exact top-level key is reserved; the same
302/// spelling nested inside an object *value* is ordinary content and remains
303/// subject to [`check_json`], never a posture mutation.
304pub const RESERVED_SECRET_GATE_KEY: &str = "khive:secret_gate";
305pub const RESERVED_WEB_RECEIPT_KEY: &str = "khive:web_receipt";
306pub const WEB_RECEIPT_PROVENANCE_VALUE: &str = "v1";
307
308/// Reject a caller-supplied top-level `khive:secret_gate` property key.
309///
310/// Call this before any diff, merge, or storage preparation touches
311/// caller-supplied `properties` on any properties-bearing write path —
312/// create, patch update, or full replace. Returns `Ok(())` when `properties`
313/// is absent, is not a JSON object, or does not name the reserved key at the
314/// top level.
315///
316/// This is the shared validator for both the ADR-115 reservation and web
317/// receipt provenance. Every properties-bearing generic write path calls it
318/// before a merge or full-row replacement.
319pub fn reject_reserved_secret_gate_property(
320 properties: Option<&serde_json::Value>,
321) -> RuntimeResult<()> {
322 if let Some(serde_json::Value::Object(map)) = properties {
323 if let Some(key) = RESERVED_PROPERTY_KEYS
324 .into_iter()
325 .find(|key| map.contains_key(*key))
326 {
327 return Err(reserved_property_error(key));
328 }
329 }
330 Ok(())
331}
332
333/// The top-level property keys no caller may set, in the order their refusals are reported.
334pub(crate) const RESERVED_PROPERTY_KEYS: [&str; 2] =
335 [RESERVED_SECRET_GATE_KEY, RESERVED_WEB_RECEIPT_KEY];
336
337fn reserved_property_error(key: &str) -> RuntimeError {
338 let owner = if key == RESERVED_WEB_RECEIPT_KEY {
339 "web-pack-owned"
340 } else {
341 "runtime-owned"
342 };
343 RuntimeError::InvalidInput(format!(
344 "property key `{key}` is {owner} and cannot be created, replaced, merged, or removed by \
345 callers"
346 ))
347}
348
349/// ADR-115 §4 for a whole-map property write against a persisted row.
350///
351/// An incoming reserved key whose value is byte-identical to the persisted value is an echo
352/// of runtime state and is removed from `incoming`. A reserved key the row does not carry, or
353/// one whose value differs (`null` included), is refused. Omitting a reserved key from a
354/// whole map is not a removal: whether the persisted value carries forward is the caller's
355/// decision, conditioned on the exempted bytes (see [`reserved_properties`]).
356pub(crate) fn strip_reserved_echo(
357 incoming: &mut serde_json::Value,
358 persisted: Option<&serde_json::Value>,
359) -> RuntimeResult<()> {
360 let Some(map) = incoming.as_object_mut() else {
361 return Ok(());
362 };
363 let persisted = persisted.and_then(serde_json::Value::as_object);
364 for key in RESERVED_PROPERTY_KEYS {
365 let Some(value) = map.get(key) else {
366 continue;
367 };
368 let echo = persisted
369 .and_then(|row| row.get(key))
370 .is_some_and(|stored| same_bytes(stored, value));
371 if !echo {
372 return Err(reserved_property_error(key));
373 }
374 map.remove(key);
375 }
376 Ok(())
377}
378
379fn same_bytes(left: &serde_json::Value, right: &serde_json::Value) -> bool {
380 matches!(
381 (serde_json::to_vec(left), serde_json::to_vec(right)),
382 (Ok(left), Ok(right)) if left == right
383 )
384}
385
386/// The reserved entries a persisted property map carries, in [`RESERVED_PROPERTY_KEYS`] order.
387pub(crate) fn reserved_properties(
388 properties: Option<&serde_json::Value>,
389) -> Vec<(&'static str, serde_json::Value)> {
390 let Some(map) = properties.and_then(serde_json::Value::as_object) else {
391 return Vec::new();
392 };
393 RESERVED_PROPERTY_KEYS
394 .into_iter()
395 .filter_map(|key| map.get(key).map(|value| (key, value.clone())))
396 .collect()
397}
398
399/// `properties` with the reserved keys removed: the part of a property map the secret gate
400/// scans, and so the part an exemption stamp vouches for.
401pub(crate) fn without_reserved_properties(
402 properties: Option<&serde_json::Value>,
403) -> Option<serde_json::Value> {
404 let mut properties = properties.cloned();
405 if let Some(serde_json::Value::Object(map)) = properties.as_mut() {
406 for key in RESERVED_PROPERTY_KEYS {
407 map.remove(key);
408 }
409 }
410 properties
411}
412
413/// The write-site check for ADR-115 §4 on a whole-row replace of a row that may carry a
414/// reserved key. A reserved value may reach the row only as a byte-identical carry of the
415/// value `persisted` already holds, and only while the bytes it vouches for are unchanged
416/// (`vouched_unchanged`). Every such write site calls this immediately before it builds the
417/// write, whatever its preparation checked, so a preparation that drifts cannot persist a
418/// stamp over bytes it never covered.
419pub(crate) fn check_reserved_carry_forward(
420 persisted: Option<&serde_json::Value>,
421 outgoing: Option<&serde_json::Value>,
422 vouched_unchanged: bool,
423) -> RuntimeResult<()> {
424 let persisted = reserved_properties(persisted);
425 for (key, value) in reserved_properties(outgoing) {
426 let carried = persisted
427 .iter()
428 .any(|(stored_key, stored)| *stored_key == key && same_bytes(stored, &value));
429 if !carried || !vouched_unchanged {
430 return Err(reserved_property_error(key));
431 }
432 }
433 Ok(())
434}
435
436fn scan_json_value(value: &serde_json::Value) -> RuntimeResult<()> {
437 match value {
438 serde_json::Value::String(s) => check(s),
439 serde_json::Value::Array(arr) => {
440 for v in arr {
441 scan_json_value(v)?;
442 }
443 Ok(())
444 }
445 serde_json::Value::Object(map) => {
446 for (k, v) in map {
447 // Scan both the key (a credential can appear as a JSON key name)
448 // and the value recursively.
449 check(k)?;
450 scan_json_value(v)?;
451 }
452 Ok(())
453 }
454 _ => Ok(()),
455 }
456}
457
458// ─── Scanner ─────────────────────────────────────────────────────────────────
459
460/// Marker substituted for a detected secret span by [`mask_secrets`].
461const REDACTION_MARKER: &str = "***MASKED***";
462
463/// Maximum cumulative bytes revisited by the per-pass detector sweeps while masking
464/// one input. Entropy tokens are materialized once, but resuming inside a token
465/// rebuilds its member candidates and revisits their context, so that token's
466/// full prefix is also charged. This permits two full-size passes over the 1 MiB
467/// ASCII log-input case; the first pass is always allowed for larger or multibyte
468/// callers. Once exhausted, the remainder is redacted wholesale.
469const MAX_MASK_SCAN_WORK_BYTES: usize = MAX_LOG_TEXT_MASK_INPUT_CHARS * 2;
470
471#[cfg(test)]
472thread_local! {
473 static ENTROPY_TOKENIZATION_COUNT: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
474}
475
476/// Return the LEFTMOST secret in `text` as `(matched_slice, detector)`.
477///
478/// The matched slice borrows from `text`, so the caller can recover its byte
479/// span via pointer arithmetic — this is what lets [`mask_secrets`] redact in
480/// place while [`scan`] only needs the masked excerpt.
481///
482/// "Leftmost" (smallest start offset), NOT first-by-detector-priority, is the
483/// load-bearing contract: [`mask_secrets`] copies the text *before* each match
484/// verbatim, so a non-leftmost match would leak an earlier secret detected by a
485/// lower-priority detector (e.g. an `sk-ant-` key sitting to the left of a
486/// `ghp_` token). Both detector layers are folded through [`keep_leftmost`].
487#[cfg(test)]
488fn scan_match(text: &str) -> Option<(&str, &'static str)> {
489 let context = EntropyScanContext::new(text);
490 scan_from(text, 0, &context)
491}
492
493/// Like [`scan_match`], but only returns secrets whose span starts at or after
494/// `from`, while still evaluating Layer-2 trigger context against the FULL
495/// `text`. [`mask_secrets`] calls this with an advancing `from` so that an
496/// entropy token is detected even when its only trigger word sits to the left of
497/// an already-redacted earlier secret. Layer-1 known patterns are context-free,
498/// so scanning the `&text[from..]` suffix is equivalent; offsets recovered via
499/// pointer arithmetic against the original `text` base stay absolute. The
500/// pre-tokenized entropy view is shared by all passes.
501fn scan_from<'a>(
502 text: &'a str,
503 from: usize,
504 context: &EntropyScanContext<'a>,
505) -> Option<(&'a str, &'static str)> {
506 scan_from_with_trigger(text, from, context).map(|(slice, detector, _)| (slice, detector))
507}
508
509fn scan_from_with_trigger<'a>(
510 text: &'a str,
511 from: usize,
512 context: &EntropyScanContext<'a>,
513) -> Option<(&'a str, &'static str, Option<&'static str>)> {
514 let mut best =
515 check_known_patterns(&text[from..]).map(|(slice, detector)| (slice, detector, None));
516 if let Some(candidate) = check_entropy_heuristic(text, from, context) {
517 if best
518 .as_ref()
519 .is_none_or(|current| candidate.0.as_ptr() < current.0.as_ptr())
520 {
521 best = Some(candidate);
522 }
523 }
524 best
525}
526
527/// Replace `best` with `cand` when `cand` starts earlier in the original text
528/// (`base` is the start address of that text). On a tie the incumbent wins, so
529/// callers offer more-specific detectors first. This is what makes
530/// [`check_known_patterns`] and [`scan_match`] return the leftmost secret span
531/// rather than the first detector that happens to match anywhere.
532fn keep_leftmost<'a>(
533 best: &mut Option<(&'a str, &'static str)>,
534 cand: Option<(&'a str, &'static str)>,
535 base: usize,
536) {
537 if let Some((slice, name)) = cand {
538 let start = slice.as_ptr() as usize - base;
539 let replace = match *best {
540 Some((incumbent, _)) => start < (incumbent.as_ptr() as usize - base),
541 None => true,
542 };
543 if replace {
544 *best = Some((slice, name));
545 }
546 }
547}
548
549/// Return the first `SecretMatch` found in `text`, or `None`.
550fn scan(text: &str) -> Option<SecretMatch> {
551 let context = EntropyScanContext::new(text);
552 scan_from_with_trigger(text, 0, &context).map(|(slice, detector, trigger)| {
553 let mut matched = build_match(detector, slice);
554 matched.trigger = trigger;
555 matched
556 })
557}
558
559/// A named redact-not-block surface whose contract is intentionally separate
560/// from manifest-backed write admission (ADR-115 Amendment 2).
561#[derive(Debug, Clone, Copy, PartialEq, Eq)]
562pub enum RedactionSurface {
563 /// Git ingestion stores only masked commit, issue, and pull-request text.
564 GitIngest,
565 /// Session mirroring stores only masked `text` and `raw` projections.
566 SessionMirror,
567 /// Workspace mirroring stores masked document descriptions.
568 WorkspaceMirror,
569 /// MCP diagnostics are bounded caller-visible transport data, not records.
570 McpDiagnostic,
571 /// The kg `scan` verb's masked preview: caller-visible, never stored.
572 GateProbe,
573}
574
575/// Whether a redaction surface can consume a secret-gate exemption.
576#[derive(Debug, Clone, Copy, PartialEq, Eq)]
577pub enum RedactionSurfaceMode {
578 /// Always apply the canonical masker; never synthesize a stamp or event.
579 PermanentMaskOnly,
580}
581
582/// Machine-readable contract for a named redaction surface.
583#[derive(Debug, Clone, Copy, PartialEq, Eq)]
584pub struct RedactionSurfaceContract {
585 pub mode: RedactionSurfaceMode,
586 /// Durable target containing the masked result, if this is a write surface.
587 pub final_stored_target: Option<&'static str>,
588 /// Reserved stamp location; absent for permanent mask-only surfaces.
589 pub stamp_property: Option<&'static str>,
590 /// Atomic exemption-success event; absent when admission cannot occur.
591 pub atomic_success_event: Option<&'static str>,
592}
593
594/// Final stored target for [`RedactionSurface::GitIngest`] — see
595/// [`redaction_surface_contract`].
596pub const GIT_INGEST_STORED_TARGET: &str = "final git-ingest entity/note fields";
597
598/// Final stored target for [`RedactionSurface::SessionMirror`] — see
599/// [`redaction_surface_contract`]. Names every column the session mirror
600/// writes a masked provider-export projection into, not just the message
601/// body columns. `cwd`/`git_branch` live only on `sessions`, keyed per
602/// session — `session_messages` carries no such columns of its own (see the
603/// `session_messages` DDL in `khive-pack-session`).
604pub const SESSION_MIRROR_STORED_TARGET: &str =
605 "session_messages.text, session_messages.raw, sessions.cwd, sessions.git_branch, \
606 and sessions.slug";
607
608/// Final stored target for [`RedactionSurface::WorkspaceMirror`] — see
609/// [`redaction_surface_contract`]. The mirror passes masked text into the
610/// document entity's `description`; source URI, type, and checksum are separate.
611pub const WORKSPACE_MIRROR_STORED_TARGET: &str = "workspace mirror document.description";
612
613/// Return the closed contract for a named redact-not-block surface.
614pub const fn redaction_surface_contract(surface: RedactionSurface) -> RedactionSurfaceContract {
615 let final_stored_target = match surface {
616 RedactionSurface::GitIngest => Some(GIT_INGEST_STORED_TARGET),
617 RedactionSurface::SessionMirror => Some(SESSION_MIRROR_STORED_TARGET),
618 RedactionSurface::WorkspaceMirror => Some(WORKSPACE_MIRROR_STORED_TARGET),
619 RedactionSurface::McpDiagnostic | RedactionSurface::GateProbe => None,
620 };
621
622 RedactionSurfaceContract {
623 mode: RedactionSurfaceMode::PermanentMaskOnly,
624 final_stored_target,
625 stamp_property: None,
626 atomic_success_event: None,
627 }
628}
629
630/// Apply the canonical detector to a named permanent mask-only surface.
631///
632/// This wrapper makes the non-admission decision executable at each call site:
633/// it has no manifest input, cannot return an exemption outcome, and cannot
634/// synthesize the runtime-owned `khive:secret_gate` property or success event.
635pub fn mask_for_redaction_surface(
636 surface: RedactionSurface,
637 text: &str,
638) -> std::borrow::Cow<'_, str> {
639 match redaction_surface_contract(surface).mode {
640 RedactionSurfaceMode::PermanentMaskOnly => mask_secrets(text),
641 }
642}
643
644#[cfg(test)]
645#[path = "secret_gate/issue_2655_tests.rs"]
646mod issue_2655_tests;
647
648#[cfg(test)]
649#[path = "secret_gate/note_fields_tests.rs"]
650mod note_fields_tests;
651
652#[cfg(test)]
653#[path = "secret_gate/escaped_json_tests.rs"]
654mod escaped_json_tests;
655
656// ─── Tests ───────────────────────────────────────────────────────────────────
657
658#[cfg(test)]
659#[path = "secret_gate_tests.rs"]
660mod tests;
661
662// ─── Corpus replay harness (manual, opt-in) ─────────────────────────────────
663//
664// Measures how many real note/entity strings the gate blocks, so a detector
665// change can be evaluated against production content rather than intuition
666// (see the module doc). Opens the target database
667// STRICTLY read-only (`SQLITE_OPEN_READ_ONLY`) and never mutates it. Point
668// `KHIVE_REPLAY_DB` at a copy or a live KG database file path; the harness
669// never writes, locks aggressively, or deletes anything.
670//
671// Run with: `KHIVE_REPLAY_DB=/path/to/khive.db cargo test -p khive-runtime \
672// --release -- --ignored --nocapture corpus_replay`
673#[cfg(test)]
674#[path = "secret_gate/corpus_replay_tests.rs"]
675mod corpus_replay;