failproofai 1.0.4-beta.1 → 1.0.4-beta.4

package/src/audit/index.ts

@@ -16,6 +16,11 @@ import { INTEGRATION_TYPES, type IntegrationType } from "../hooks/types";
 import { ADAPTERS } from "./cli-adapters";
 import { AUDIT_DETECTORS } from "./detectors";
 import { severityForBuiltin } from "./features";
+import { findSecrets, flattenToolInput } from "./leak-scan";
+import { fingerprintSecret, fingerprintId } from "./leak-fingerprint";
+import { readLeakIdentity, readLeakRecord, writeLeakRecord } from "./leak-store";
+import { upsertFinding, describeMechanism, emptyRecord } from "./leak-record";
+import { shortenPaths } from "./redact-example";
 import { readCachedTranscript, writeCachedTranscriptResult } from "./cache";
 import { initReplay, replayEvent, restoreReplay } from "./replay";
 import {
@@ -32,6 +37,64 @@ import {
 
 const TRANSCRIPT_CONCURRENCY = 8;
 
+/**
+ * Raw transcript bytes allowed in flight at once.
+ *
+ * The concurrency above counts FILES, which is the wrong unit. `streamEventsFrom`
+ * returns an array — despite the name it materialises every event of a
+ * transcript into JS objects — and a 57 MB JSONL becomes several hundred MB of
+ * them. On a real 1.15 GB corpus, 7 files hold 224 MB and the largest is
+ * 57.5 MB, so eight workers could put a quarter of the corpus in memory
+ * simultaneously. That machine printed `Aborted(OOM)` 22 times in one run.
+ *
+ * This is NOT what fixed those lines, and the distinction is worth keeping
+ * honest: they were measured at ~22 per run, appear within the first two
+ * seconds, are unchanged by this budget at 48 MB or at 16 MB, and do not fail
+ * the run — its counts come back correct. Their source is still unidentified.
+ * This bounds a real and separate failure mode (eight of the seven largest
+ * files in flight at once); it should not be read as having fixed the other.
+ *
+ * 48 MB of raw input is the budget because the expansion factor from JSONL to
+ * parsed objects is roughly 5-10x, which keeps the peak inside a default heap
+ * with room for the eight small-file workers this is meant not to slow down.
+ * Chosen to bound memory, not to be exactly right: the failure it prevents is a
+ * crash, and the cost of being conservative is that one very large file scans
+ * alone for a moment.
+ */
+const TRANSCRIPT_BYTE_BUDGET = 48 * 1024 * 1024;
+
+/**
+ * Admission control by weight, so a worker waits for MEMORY as well as a slot.
+ *
+ * A file bigger than the whole budget is admitted alone rather than refused —
+ * otherwise the largest transcript on the machine could never be scanned, which
+ * is precisely the one most likely to hold something.
+ */
+class ByteGate {
+  private inFlight = 0;
+  private waiting: Array<() => void> = [];
+
+  constructor(private readonly budget: number) {}
+
+  async acquire(bytes: number): Promise<void> {
+    const want = Math.max(0, bytes);
+    while (this.inFlight > 0 && this.inFlight + want > this.budget) {
+      await new Promise<void>((resolve) => this.waiting.push(resolve));
+    }
+    this.inFlight += want;
+  }
+
+  release(bytes: number): void {
+    this.inFlight -= Math.max(0, bytes);
+    if (this.inFlight < 0) this.inFlight = 0;
+    // Wake everyone and let each re-test its own weight: a small task behind a
+    // large one should not be held by a queue position it does not need.
+    const waiters = this.waiting;
+    this.waiting = [];
+    for (const wake of waiters) wake();
+  }
+}
+
 /** Canonicalize a policy name to its short, qualified form for display
  *  (`failproofai/foo` → `foo`). */
 function shortPolicyName(name: string): string {
@@ -113,6 +176,50 @@ interface ScanOutcome {
   resumed: boolean;
 }
 
+const CREDENTIAL_RESEARCH_MARKERS: ReadonlyArray<RegExp> = [
+  /\b(?:secret|credential)[-_ ](?:scanner|detection|detector|pattern|regex|corpus)\b/i,
+  /\b(?:trufflehog|trufflesecurity|gitleaks|detect-secrets|secret-detection-rules)\b/i,
+  /\b(?:SECRET_PATTERNS|findSecrets|isDocsLiteral|leak-scan)\b/,
+  /\b(?:fixture|placeholder|synthetic|sample) (?:api )?(?:key|token|secret|credential)s?\b/i,
+  /\b(?:grep|rg|ripgrep|scan|hunt|search)\b[^\n]{0,240}\b(?:secret|credential|token)s?\b/i,
+];
+
+const CREDENTIAL_RESEARCH_PURPOSE =
+  /\b(?:hunt|scan|search|research|test)(?:ing)?\b[^\n]{0,80}\b(?:secret|credential|token)s?\b|\b(?:secret|credential|token)s?\b[^\n]{0,80}\b(?:scanner|detector|detection|research|fixtures?|corpus)\b/i;
+
+/**
+ * Deliberate secret-detector research is full of realistic fake credentials.
+ * Reporting those as leaks is the feedback loop that made one measured session
+ * contribute 455 of the 500 rows in its own audit.
+ *
+ * Require independent signals across tool INPUTS. Results are excluded from
+ * classification: a normal command can print hostile text, while commands and
+ * URLs state what the agent intentionally set out to inspect. Two signals keep
+ * an ordinary discussion that happens to say "secret scanner" from silencing a
+ * session; dedicated detector/test work reliably carries several.
+ */
+export function isCredentialResearchSession(
+  events: NormalizedToolEvent[],
+  sessionDescription?: string,
+): boolean {
+  if (sessionDescription && CREDENTIAL_RESEARCH_PURPOSE.test(sessionDescription)) return true;
+  const matched = new Set<number>();
+  let evidenceEvents = 0;
+  for (const event of events) {
+    const intent = flattenToolInput(event.toolInput);
+    let eventMatched = false;
+    for (let i = 0; i < CREDENTIAL_RESEARCH_MARKERS.length; i++) {
+      if (CREDENTIAL_RESEARCH_MARKERS[i].test(intent)) {
+        matched.add(i);
+        eventMatched = true;
+      }
+    }
+    if (eventMatched) evidenceEvents++;
+    if (matched.size >= 2 || evidenceEvents >= 3) return true;
+  }
+  return false;
+}
+
 async function scanOneTranscript(
   meta: TranscriptMetadata,
   resume?: { fromByte: number; detectorState: DetectorSessionState },
@@ -181,21 +288,27 @@ async function scanOneTranscript(
   // Capture the session's cwd from the first event that carried one — every
   // event in a single transcript shares the same cwd by construction.
   result.cwd = result.cwd || events[0].cwd || "";
+  const suppressLeakScan = isCredentialResearchSession(events, meta.sessionDescription);
+  if (suppressLeakScan) result.leakScanSuppressed = "credential-research";
 
   for (const event of events) {
-    // Run audit detectors first (stateful, must see every event).
-    for (const detector of AUDIT_DETECTORS) {
-      const hit = detector.detect(event, sessionState);
-      if (!hit) continue;
-      recordHit(
-        result,
-        detector.name,
-        event.timestamp,
-        event.cwd,
-        truncateExample(hit.example),
-      );
-    }
-    // Then replay through every builtin policy.
+    // The 8 behavioural detectors are switched off with the rest of the old
+    // audit — see the header of `src/audit/scoring.ts`. The modules and their
+    // unit tests are untouched; nothing calls them. `sessionState` is still
+    // threaded through so a resumed scan keeps its shape and restoring this
+    // loop needs no plumbing.
+    // for (const detector of AUDIT_DETECTORS) {
+    //   const hit = detector.detect(event, sessionState);
+    //   if (!hit) continue;
+    //   recordHit(
+    //     result,
+    //     detector.name,
+    //     event.timestamp,
+    //     event.cwd,
+    //     truncateExample(hit.example),
+    //   );
+    // }
+    // Replay through every builtin policy.
     let replayHits;
     try {
       replayHits = await replayEvent(event);
@@ -212,11 +325,129 @@ async function scanOneTranscript(
         truncateExample(example),
       );
     }
+
+    // Credential VALUES, which the replay above cannot report: it returns a
+    // decision per policy, never the text that matched. Scanned separately so
+    // the leak report can name WHICH key, and so detection can be tuned for
+    // precision without dragging the redactor's recall down with it.
+    if (!suppressLeakScan) recordLeaks(result, event);
   }
 
   return { result, bytesScanned, detectorState: sessionState, resumed };
 }
 
+/**
+ * Fingerprint every credential in one event and attach the sightings.
+ *
+ * The raw value exists only inside this function. It is read out of the event,
+ * hashed into a salted id, rendered into a mask, and dropped — nothing that
+ * leaves here can reconstruct it.
+ *
+ * Input and result are scanned separately and tagged, because they are
+ * different exposures: an input is what the agent SENT (deniable at PreToolUse
+ * on 12/12 CLIs, and 39.5% of measured appearances) while a result is what it
+ * RECEIVED (blockable on 2/12, and only after the fact).
+ */
+function recordLeaks(result: TranscriptAuditResult, event: NormalizedToolEvent): void {
+  const salt = leakSalt();
+  if (!salt) return;
+
+  const filePath = (event.toolInput as { file_path?: unknown }).file_path;
+  const shortPath = typeof filePath === "string" ? shortenPaths(filePath) : null;
+
+  const scan = (text: string, direction: "input" | "result"): void => {
+    for (const match of findSecrets(text)) {
+      (result.leaks ??= []).push({
+        id: fingerprintId(match.value, salt),
+        fingerprint: fingerprintSecret(match.value, match.rule),
+        name: match.name,
+        rule: match.rule,
+        shaped: match.shaped,
+        timestamp: event.timestamp,
+        cwd: event.cwd,
+        toolName: event.toolName,
+        direction,
+        path: shortPath,
+      });
+    }
+  };
+
+  scan(flattenToolInput(event.toolInput), "input");
+  if (event.toolResultText !== undefined) scan(event.toolResultText, "result");
+}
+
+/**
+ * The machine's HMAC salt, read once per process.
+ *
+ * Cached because `scanOneTranscript` runs this per EVENT — 340,918 of them on
+ * the measured corpus — and re-reading a file that many times would dominate
+ * the scan. `null` when the store is unreadable, which disables leak recording
+ * rather than failing the audit: a scan that cannot fingerprint is still a scan
+ * that can count.
+ */
+let cachedSalt: string | null | undefined;
+function leakSalt(): string | null {
+  if (cachedSalt === undefined) {
+    try {
+      cachedSalt = readLeakIdentity().salt;
+    } catch {
+      cachedSalt = null;
+    }
+  }
+  return cachedSalt;
+}
+
+/**
+ * Merge this scan's sightings into `~/.failproofai/audit/leaks.json`.
+ *
+ * Returns the ids seen for the FIRST time, which is the set worth telling a
+ * human about. Never throws: a scan that finds leaks it cannot write down has
+ * still found them, and the caller reports on the in-memory result either way.
+ */
+export function persistLeaks(perTranscript: TranscriptAuditResult[], replaceExisting: boolean): string[] {
+  const fresh: string[] = [];
+  try {
+    const previous = readLeakRecord();
+    const previousIds = new Set(previous.findings.map((f) => f.id));
+    // A successful all-history scan is authoritative. Rebuilding is what lets
+    // detector precision fixes remove findings they now reject; merging made
+    // every false positive live for 90 days even after the code was fixed.
+    // Scoped or incomplete scans still merge because absence outside their
+    // coverage says nothing.
+    const record = replaceExisting
+      ? emptyRecord(previous.salt, new Date().toISOString())
+      : previous;
+    for (const t of perTranscript) {
+      for (const leak of t.leaks ?? []) {
+        const { isNew } = upsertFinding(record, {
+          id: leak.id,
+          fingerprint: leak.fingerprint,
+          name: leak.name,
+          rule: leak.rule,
+          // A vendor shape is what licenses an alert to name a console; a
+          // name-only match knows something leaked, not who issued it.
+          confidence: leak.shaped ? "doc-verified" : "name-only",
+          sighting: {
+            cli: t.cli,
+            sessionId: t.sessionId,
+            cwd: shortenPaths(leak.cwd),
+            at: leak.timestamp,
+            mechanism: describeMechanism(leak.toolName, leak.direction, leak.path),
+          },
+        });
+        // During an authoritative rebuild every insertion is new to the empty
+        // record, but only ids absent from the previous record are new to the
+        // HUMAN and eligible for a notification.
+        if (isNew && !previousIds.has(leak.id)) fresh.push(leak.id);
+      }
+    }
+    writeLeakRecord(record);
+  } catch {
+    // Bookkeeping failure must not fail the audit — see leak-store.ts.
+  }
+  return fresh;
+}
+
 function formatPolicyExample(_policyName: string, event: NormalizedToolEvent): string {
   if (event.toolName === "Bash") {
     const command = (event.toolInput as { command?: unknown }).command;
@@ -236,7 +467,7 @@ function formatPolicyExample(_policyName: string, event: NormalizedToolEvent): s
  * came from the FIRST event in the file and the tail's came from the first
  * event after the offset, so the older one wins.
  */
-function mergeIncremental(
+export function mergeIncremental(
   cached: TranscriptAuditResult,
   tail: TranscriptAuditResult,
 ): TranscriptAuditResult {
@@ -250,6 +481,12 @@ function mergeIncremental(
     examplesByName: {},
     rangeByName: { ...cached.rangeByName },
   };
+  if (cached.leakScanSuppressed || tail.leakScanSuppressed) {
+    out.leakScanSuppressed = "credential-research";
+    out.leaks = [];
+  } else {
+    out.leaks = [...(cached.leaks ?? []), ...(tail.leaks ?? [])];
+  }
   for (const [name, list] of Object.entries(cached.examplesByName)) {
     out.examplesByName[name] = [...list];
   }
@@ -432,18 +669,22 @@ async function runAuditInner(opts: RunAuditOptions, startedAt: number): Promise<
 
   // 1. Discover transcripts across all selected CLIs.
   const allTranscripts: TranscriptMetadata[] = [];
+  let discoveryErrors = 0;
   for (const cli of clis) {
     const adapter = ADAPTERS[cli];
     let list: TranscriptMetadata[];
     try {
       list = await adapter.listTranscripts({ projects: opts.projects, sinceMs });
     } catch {
+      discoveryErrors++;
       continue; // adapter failures shouldn't kill the whole audit
     }
     allTranscripts.push(...list);
   }
 
-  // 2. Scan each transcript (cache-aware), 8 in parallel.
+  // 2. Scan each transcript (cache-aware), 8 at a time and within a memory
+  // budget — see TRANSCRIPT_BYTE_BUDGET for why a file count is the wrong unit.
+  const gate = new ByteGate(TRANSCRIPT_BYTE_BUDGET);
   let skipped = 0;
   let errors = 0;
   const tasks = allTranscripts.map((meta) => async (): Promise<TranscriptAuditResult> => {
@@ -457,6 +698,9 @@ async function runAuditInner(opts: RunAuditOptions, startedAt: number): Promise<
         : undefined;
       cachedPrefix = found?.kind === "resume" ? found.result : null;
     }
+    // Memory admission. Taken AFTER the cache check above, so a cache hit — the
+    // common case on a warm machine — never waits for a slot it does not use.
+    await gate.acquire(meta.sizeBytes);
     try {
       const scan = await scanOneTranscript(meta, resume);
       // A resumed scan produced hits for the TAIL only; the cached result holds
@@ -500,6 +744,11 @@ async function runAuditInner(opts: RunAuditOptions, startedAt: number): Promise<
         examplesByName: {},
         rangeByName: {},
       };
+    } finally {
+      // Released on every path, including the error one — a task that threw
+      // still freed its memory, and holding its weight would shrink the budget
+      // permanently over a long scan until nothing could be admitted at all.
+      gate.release(meta.sizeBytes);
     }
   });
 
@@ -527,8 +776,28 @@ async function runAuditInner(opts: RunAuditOptions, startedAt: number): Promise<
     eventsScanned += t.eventsScanned ?? 0;
   }
 
+  // Fold every sighting into the persistent record. This is the ONLY place the
+  // leak record is written: `scanOneTranscript` runs 8-way concurrent and a
+  // per-transcript write would be eight processes racing one file — the exact
+  // shape that lost updates when it was measured (2 concurrent writers, 5/5
+  // trials, the loser's entry gone permanently).
+  //
+  // `newFindingIds` is what a notice keys on: an id already in the record must
+  // not alert again however many fresh sightings it accumulates, and a
+  // credential seen for the first time must alert even though its rule has
+  // fired a thousand times before.
+  const coversAllHistory =
+    opts.clis === undefined &&
+    opts.projects === undefined &&
+    opts.since === undefined &&
+    discoveryErrors === 0 &&
+    errors === 0 &&
+    skipped === 0;
+  const newFindingIds = persistLeaks(perTranscript, coversAllHistory);
+
   const auditResult: AuditResult = {
     version: 2,
+    newLeakIds: newFindingIds,
     scannedAt: new Date(startedAt).toISOString(),
     scope: {
       cli: clis,

package/src/audit/leak-fingerprint.ts

@@ -0,0 +1,200 @@
+/**
+ * How a leaked credential is NAMED once it leaves the machine.
+ *
+ * Every other redactor in this codebase exists to destroy a value. This one
+ * exists to describe one, because the leak report has the opposite job: a
+ * finding the reader cannot tie to a row in a vendor console is a finding they
+ * cannot act on. `[REDACTED: GitHub token]` tells you nothing you can revoke.
+ *
+ * The rule is: **enough to identify, never enough to use.**
+ *
+ * ## Why the mask character matters, which is not obvious
+ *
+ * The three most natural masking characters — `X`, `x` and `0` — RE-MATCH every
+ * vendor prefix pattern we ship. `AKIA` + sixteen `X`s satisfies
+ * `AKIA[A-Z0-9]{16}`, so a masked AWS key is reported by failproofai as a live
+ * AWS key on the next scan. The same holds for a masked connection string,
+ * whose pattern keys on `://…@` and does not care what sits between. So the
+ * mask is `•` (U+2022), which is in no credential charset anywhere, and the
+ * unit tests assert that every masked form fails to re-match.
+ *
+ * That is not a hypothetical: this product measured its own audit output
+ * feeding back into its own corpus, one leaked credential becoming seven
+ * reported findings across four sessions.
+ *
+ * ## Why the last four, and why not always
+ *
+ * Last-4 is what vendor consoles display next to a key, so it is the token that
+ * lets a human find the right row and press revoke. But it is only safe when
+ * what remains is genuinely unguessable. For a 40-character GitHub token,
+ * showing `ghp_` and four trailing characters leaves ~32 unknown base62
+ * characters — no help to anyone. For a 13-character human-chosen password,
+ * last-4 is nearly a third of the secret, and the corpus's one confirmed-live
+ * password was exactly 13 characters at 3.19 bits per character.
+ *
+ * So the tail is shown only when the value clears BOTH bars: a recognised
+ * public vendor prefix (which proves it is a minted token, not a typed
+ * password) AND enough residual length. Everything else is described by class
+ * and length alone.
+ */
+
+/** The mask glyph. Never `X`, `x` or `0` — see the module header. */
+const MASK_CHAR = "•";
+
+/** Longest run of mask glyphs rendered, so a 200-char token stays readable. */
+const MAX_MASK_RUN = 8;
+
+/**
+ * Minimum total length before any trailing characters are shown.
+ *
+ * 24 is chosen so that even the shortest minted token we recognise keeps well
+ * over 100 bits of residual entropy after the prefix and tail are removed.
+ * Human-chosen passwords essentially never reach it, which is the point.
+ */
+const MIN_LEN_FOR_TAIL = 24;
+
+/** How many trailing characters a vendor console typically shows. */
+const TAIL_CHARS = 4;
+
+/**
+ * Public, minted prefixes — the part of a credential that carries no secret.
+ *
+ * Each of these is published by its issuer and identical across every key they
+ * mint, so showing it discloses nothing while telling the reader which console
+ * to open. Ordered longest-first, so `sk-ant-api03-` wins over `sk-ant-` and
+ * `sk-`; the first match is the one rendered.
+ *
+ * Deliberately NOT the full detection vocabulary. This list only has to be
+ * right about what is safe to PRINT — a prefix missing from it costs a less
+ * specific label, never a disclosure.
+ */
+const PUBLIC_PREFIXES: ReadonlyArray<readonly [string, string]> = [
+  ["sk-ant-api03-", "Anthropic API key"],
+  ["sk-ant-oat01-", "Anthropic OAuth token"],
+  ["sk-ant-", "Anthropic key"],
+  ["sk-proj-", "OpenAI project key"],
+  ["sk-svcacct-", "OpenAI service-account key"],
+  ["sk-admin-", "OpenAI admin key"],
+  ["sk-or-v1-", "OpenRouter key"],
+  ["github_pat_", "GitHub fine-grained token"],
+  ["ghp_", "GitHub personal access token"],
+  ["gho_", "GitHub OAuth token"],
+  ["ghu_", "GitHub user-to-server token"],
+  ["ghs_", "GitHub server-to-server token"],
+  ["ghr_", "GitHub refresh token"],
+  ["glpat-", "GitLab personal access token"],
+  ["xoxb-", "Slack bot token"],
+  ["xoxp-", "Slack user token"],
+  ["xapp-", "Slack app-level token"],
+  ["sk_live_", "Stripe live secret key"],
+  ["sk_test_", "Stripe test secret key"],
+  ["rk_live_", "Stripe restricted key"],
+  ["AKIA", "AWS access key ID"],
+  ["ASIA", "AWS temporary access key ID"],
+  ["AIza", "Google API key"],
+  ["hf_", "Hugging Face token"],
+  ["gsk_", "Groq API key"],
+  ["r8_", "Replicate token"],
+  ["xai-", "xAI key"],
+  ["npm_", "npm access token"],
+  ["dop_v1_", "DigitalOcean token"],
+  ["shpat_", "Shopify access token"],
+  ["sbp_", "Supabase token"],
+];
+
+export interface LeakFingerprint {
+  /** What the reader sees: `ghp_••••••••4f2a` or `[13-char password]`. */
+  display: string;
+  /** Human label for the class, e.g. "GitHub personal access token". */
+  label: string;
+  /** Total character length of the original value. */
+  length: number;
+  /** True when a minted public prefix was recognised — i.e. we can name a
+   *  console to revoke at. False means "we know it leaked, not who issued it". */
+  attributed: boolean;
+}
+
+/** The recognised public prefix for a value, longest match first. */
+function matchPublicPrefix(value: string): readonly [string, string] | null {
+  for (const entry of PUBLIC_PREFIXES) {
+    if (value.startsWith(entry[0])) return entry;
+  }
+  return null;
+}
+
+/**
+ * Render a credential as something a human can recognise and nobody can use.
+ *
+ * `fallbackLabel` names the class when no public prefix is recognised — pass
+ * the detecting rule's own label (e.g. "assigned secret", "database password")
+ * so an unattributed finding still says what KIND of thing leaked.
+ */
+export function fingerprintSecret(value: string, fallbackLabel = "secret"): LeakFingerprint {
+  const length = value.length;
+  const matched = matchPublicPrefix(value);
+
+  if (!matched) {
+    // No minted prefix: this is a password, a first-party key, or a format we
+    // do not recognise. Nothing but the class and the length is safe to print,
+    // and the length is what lets the owner recognise their own value.
+    return {
+      display: `[${length}-char ${fallbackLabel}]`,
+      label: fallbackLabel,
+      length,
+      attributed: false,
+    };
+  }
+
+  const [prefix, label] = matched;
+  const bodyLength = length - prefix.length;
+  const run = MASK_CHAR.repeat(Math.max(1, Math.min(MAX_MASK_RUN, bodyLength)));
+
+  // The tail is the actionable half — but only when what stays hidden is
+  // genuinely unguessable. See the module header.
+  if (length >= MIN_LEN_FOR_TAIL && bodyLength > TAIL_CHARS * 2) {
+    return {
+      display: `${prefix}${run}${value.slice(-TAIL_CHARS)}`,
+      label,
+      length,
+      attributed: true,
+    };
+  }
+
+  return { display: `${prefix}${run}`, label, length, attributed: true };
+}
+
+/**
+ * A stable identity for one distinct credential, for deduping across scans.
+ *
+ * Salted with a per-machine secret so the digest cannot be used as a lookup
+ * oracle: without the salt, an attacker holding a guessable candidate (and the
+ * corpus is full of dictionary passwords) could confirm it by comparing
+ * hashes. With it, the id is meaningful only on the machine that produced it.
+ *
+ * The salt therefore forecloses cross-machine dedupe until an org-scoped key
+ * exists — a deliberate trade recorded here so nobody reads a per-machine salt
+ * as an oversight.
+ */
+/**
+ * Every id `fingerprintId` can produce, and nothing else.
+ *
+ * Ids become FILENAMES — one marker file per notified finding, one queue file
+ * per pending macOS banner — so an id is a path component, and a path component
+ * built from unvalidated input is a directory traversal. Measured: passing
+ * `"../../../../tmp/PWNED"` to `markLeakNoticeDelivered` created that file.
+ *
+ * Ids are HMAC hex today, so nothing in a normal run can carry a `/`. That is
+ * not the same as safe: the record is JSON read off disk, and `leaks.json` is a
+ * file a user (or anything running as them) can edit. The guard is one regex
+ * and it makes the property structural instead of incidental.
+ */
+export function isFindingId(id: string): boolean {
+  return /^[0-9a-f]{16}$/.test(id);
+}
+
+export function fingerprintId(value: string, machineSalt: string): string {
+  // Lazily required so this module stays importable in the browser bundle,
+  // where the dashboard renders findings but never computes ids.
+  const { createHmac } = require("node:crypto") as typeof import("node:crypto");
+  return createHmac("sha256", machineSalt).update(value).digest("hex").slice(0, 16);
+}