failproofai 1.0.4-beta.8 → 1.0.4

package/src/audit/leak-scan.ts

@@ -1,268 +0,0 @@
-/**
- * Pulling credential VALUES out of a tool event.
- *
- * The audit already replays every event through the policy engine, but
- * `ReplayHit` carries `{policyName, decision, reason}` and no matched text —
- * the engine answers "did a rule fire", not "on what". That is the right answer
- * for enforcement and the wrong one for a leak report, which has to say *which*
- * key, so this walks the event itself.
- *
- * Running beside the replay rather than inside it is also what the pattern
- * census concluded independently: detection wants a vocabulary tuned for
- * PRECISION (a false positive becomes an email to a customer about a key that
- * never leaked), while the redactor's vocabulary is tuned for RECALL (a false
- * positive costs a few characters in a digest). Sharing one list would drag one
- * of them to the other's error costs — measured, importing the detector's names
- * into the redactor stopped 305 of 646 currently-masked names from being masked.
- *
- * ## Where it looks, and why both directions matter
- *
- * Tool INPUT and tool RESULT are separate exposures with separate remedies. An
- * input is what the agent SENT — deniable at PreToolUse on all 12 CLIs, and
- * 39.5% of measured credential appearances live there. A result is what the
- * agent RECEIVED, blockable on 2 of 12 and only after the fact. The record keeps
- * them apart so the report can tell a user which of the two happened.
- */
-import { SECRET_PATTERNS } from "../hooks/builtin-policies";
-
-/**
- * Cache key for the credential detector.
- *
- * The transcript cache used to key only on builtin policies and behavioural
- * audit detectors. Changing THIS scanner therefore kept serving the old
- * `result.leaks` forever, which made a precision fix appear to do nothing on a
- * warm machine. Bump this whenever matching or suppression semantics change.
- */
-export const LEAK_SCAN_VERSION = 6;
-
-/** One credential value found in one event. */
-export interface SecretMatch {
-  /** The raw value. Held in memory only — the caller fingerprints it and must
-   *  never persist or transmit this. */
-  value: string;
-  /** The identifier it was assigned to, when a recognized shaped value also
-   *  appeared in an assignment. Used only as an actionable label. */
-  name: string | null;
-  /** Which recognizable credential shape found it. */
-  rule: string;
-  /** Whether the value carried a recognised vendor shape. Drives the record's
-   *  confidence, and therefore whether an alert may name a console. */
-  shaped: boolean;
-}
-
-/**
- * `NAME=value` in its four real spellings.
- *
- * Kept in step with `redact-example.ts`'s ASSIGNMENT_RE — same four shapes, same
- * scheme guard — because a value the DETECTOR can report but the REDACTOR
- * cannot mask is a leak in the report itself. The redactor may be broader; it
- * must never be narrower. `__tests__/audit/leak-scan.test.ts` asserts that
- * direction explicitly.
- */
-/**
- * The identifier is BOUNDED, and the bound is load-bearing rather than tidy.
- *
- * Unbounded (`[A-Za-z0-9_]*`), this is quadratic on a long unbroken token: the
- * engine starts at every one of n positions, consumes the whole run, then
- * backtracks a character at a time looking for the `=` or `:` that never comes.
- * Measured on a plain 300 KB base64 blob — `"A".repeat(300000)` — it ran for
- * over 20 SECONDS on one string. That is not an exotic input: agent transcripts
- * carry base64 images, minified bundles and whole file contents as single
- * lines, and the audit reads every one of them. A scheduled scan hitting a few
- * of these would stall for minutes with nobody watching.
- *
- * 128 characters is far past any real environment-variable or field name, so
- * bounding it costs nothing that exists and makes the scan linear in n.
- */
-const ASSIGNMENT_RE =
-  /(["']?)\b([A-Za-z_][A-Za-z0-9_]{0,127})\1([ \t]*(?::(?!\/\/)|=)[ \t]*)("[^"]*"|'[^']*'|[^\s;|&"']+)/g;
-
-/** Strip one layer of surrounding quotes. */
-function unquote(v: string): string {
-  return (v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))
-    ? v.slice(1, -1)
-    : v;
-}
-
-/**
- * SHA-256 of credentials the vendors themselves publish in their documentation.
- *
- * The single highest-value refuter in the whole detector, and the only one that
- * is decisive rather than heuristic. Measured on the real corpus: **456 of 457
- * `AKIA` matches were AWS's own documentation literal** — 99.8% of that
- * pattern's entire output, and 232 findings collapsing to zero. Across the
- * pattern census, 44 of 113 patterns with five or more hits were at least 85%
- * one literal, and 30 fired on nothing else at all.
- *
- * Stored as hashes so this file does not itself contain the values — a
- * denylist written in plaintext is a file our own scanner flags, and one that
- * lands in the corpus of every machine that installs us.
- *
- * A hash comparison cannot false-positive: either the value is byte-identical
- * to a published sample or it is not. That is what makes this worth more than
- * any amount of pattern tuning.
- */
-const DOCS_LITERALS = new Set([
-  "1a5d44a2dca19669d72edf4c4f1c27c4c1ca4b4408fbb17f6ce4ad452d78ddb3", // AWS access key ID
-  "78314b11be2e581549ac1c4f616563fad3fdf0c3b71678f6e2299182080e0598", // AWS secret access key
-  "cb20d34a7adda2f5d2043836051e242fd4c2b233e02c80c91fe9d5af9b100574", // AWS temporary key ID
-  "3543c50b0cb9cea8e55eb1f529b79f043cb250d485fde7b66cabbb5183add7da", // GitHub PAT sample
-  "1fae28c1b317300acfd90078c973567c8159015822b0c8b81508a5ec40517d20", // Google API key sample
-  "23219833092a3136d7ad178ccb62ebd6ac8cba54ff24c2cfcd37b84aba9e95cf", // SendGrid key sample
-  "872db7f4419592e397ef45230f910e06b48c36ed9970cf1f9e4fb896e69f129c", // Slack bot token sample
-  "78a08441f4314f0a2833cfe58c62e555a162264206982cda39f6804f5048f570", // Stripe live key sample
-  "2cafc0970149a84f3b9e62eaf169f36f59907a3b3e31f7b82e68c69cd27f7326", // Stripe test key sample
-  "b363ade84d56c43bebbc9339b4971e340e3f13f7f8d45580b53373d2763e9e33", // Twilio account SID sample
-]);
-
-/** True when the value is a credential a vendor published on purpose. */
-export function isDocsLiteral(value: string): boolean {
-  // Required lazily so this module stays importable from the browser bundle.
-  const { createHash } = require("node:crypto") as typeof import("node:crypto");
-  return DOCS_LITERALS.has(createHash("sha256").update(value).digest("hex"));
-}
-
-/**
- * Text that is failproofai's OWN output being replayed back at us.
- *
- * Auditing for secrets writes secrets into the corpus the next audit reads.
- * That is measured, not theoretical: the single largest organic cluster in
- * 1.6 GB of transcripts was one file — a previous secret-audit run quoting back
- * the credentials it had found (123 Atlassian tokens, 26 Telegram, 25 Slack,
- * 18 GitHub) — and 108 of the 161 patterns that matched anything matched ONLY
- * inside the investigation's own transcripts.
- *
- * Left unhandled the count climbs every scan, each report inflating the next.
- * These markers appear in our own rendered output and essentially nowhere else.
- */
-const SELF_OUTPUT_MARKERS = [
-  "[REDACTED:",
-  "[redacted:",
-  "failproofai audit",
-  "assigned secret]",
-];
-
-/** True when this text is our own report, not a transcript of real work. */
-export function isSelfOutput(text: string): boolean {
-  return SELF_OUTPUT_MARKERS.some((m) => text.includes(m));
-}
-
-/**
- * Literal prefixes that must appear before any vendor regex is worth running.
- *
- * A prefilter, and it is not an optimisation — it is what makes the pattern set
- * shippable at all. The census measured the cost as LINEAR in pattern count:
- * ~0.095s per pattern per 6 MB, so 288 patterns over a 1.6 GB corpus is roughly
- * two hours, while the handful that ever match take five seconds. Scanning is
- * already the audit's slowest phase and the whole point of adding vendors is
- * that most of them never fire on any given machine.
- *
- * So: one cheap pass over the text asking "does any prefix appear at all", and
- * the regexes only run when one does. Derived from `SECRET_PATTERNS` at module
- * load rather than hand-maintained, because a hand-copied list that drifts from
- * its source silently stops matching — the exact failure class this repo already
- * has a tripwire test for elsewhere.
- *
- * Patterns with no literal prefix (a bare JWT, a connection string, the Telegram
- * `\d{8,10}:` shape) yield no gate token and are always run; they are few, and
- * a pattern that cannot be prefiltered is one whose cost has to be paid.
- */
-function literalPrefixOf(source: string): string | null {
-  // Walk the regex source until the first construct that is not a plain
-  // literal. Anything before that is text the input must contain verbatim.
-  let out = "";
-  for (let i = 0; i < source.length; i++) {
-    const c = source[i];
-    if (c === "\\") {
-      // An escape: only a handful are literal characters we can rely on.
-      const next = source[i + 1];
-      if (next === undefined) break;
-      if (/[dwsSDWbB]/.test(next)) break; // a class, not a literal
-      out += next;
-      i++;
-      continue;
-    }
-    if ("[](){}|?*+^$.".includes(c)) break;
-    out += c;
-  }
-  // Two characters is the shortest gate worth having: shorter than that and the
-  // prefilter matches nearly every input and buys nothing.
-  return out.length >= 2 ? out : null;
-}
-
-/** Built once. Each entry is `[pattern, label, gate]`; a null gate always runs. */
-const GATED_PATTERNS: ReadonlyArray<readonly [RegExp, string, string | null]> =
-  SECRET_PATTERNS.map(([re, label]) => [re, label, literalPrefixOf(re.source)] as const);
-
-/** Patterns worth running against this text. */
-function applicablePatterns(text: string): ReadonlyArray<readonly [RegExp, string, string | null]> {
-  return GATED_PATTERNS.filter(([, , gate]) => gate === null || text.includes(gate));
-}
-
-/**
- * Every credential value in one blob of text.
- *
- * Vendor SHAPES first, then secret-NAMED assignments, deduped by value so one
- * key matched by both layers is reported once — under its vendor label, which
- * is the one that can carry a revocation link. The two layers are near-disjoint
- * in practice: 55.9% of real vendor-shaped credentials in the corpus have no
- * secret-ish word within 60 characters, and 230 of 237 secret-named assignments
- * match no vendor pattern at all.
- *
- * Both refuters run before anything is reported: our own replayed output is
- * dropped whole, and every published documentation sample is dropped by hash.
- */
-export function findSecrets(text: string): SecretMatch[] {
-  if (!text) return [];
-  // Our own report replayed into a transcript is not a leak — see isSelfOutput.
-  if (isSelfOutput(text)) return [];
-  const byValue = new Map<string, SecretMatch>();
-
-  for (const [pattern, label] of applicablePatterns(text)) {
-    const re = new RegExp(pattern.source, pattern.flags.includes("g") ? pattern.flags : pattern.flags + "g");
-    for (const m of text.matchAll(re)) {
-      const value = m[0];
-      if (isDocsLiteral(value)) continue;
-      if (!byValue.has(value)) byValue.set(value, { value, name: null, rule: label, shaped: true });
-    }
-  }
-
-  // Names annotate a value the shape layer already proved; they no longer
-  // create findings. Even after increasingly elaborate value heuristics, the
-  // name-only lane still produced hundreds of code literals and test fixtures
-  // on the measured machine. The product now deliberately prefers missing an
-  // unrecognisable first-party password over telling somebody they leaked 500
-  // credentials they do not have.
-  for (const m of text.matchAll(ASSIGNMENT_RE)) {
-    const name = m[2];
-    const value = unquote(m[4]);
-    const existing = byValue.get(value);
-    if (existing) existing.name ??= name;
-  }
-
-  return [...byValue.values()];
-}
-
-/**
- * Serialize a tool input for scanning.
- *
- * Every string leaf, not just `command`: the measured surface includes file
- * bodies on Write, replacement text on Edit, headers on WebFetch and arbitrary
- * MCP payloads. `JSON.stringify` would work but escapes quotes, which breaks
- * the assignment grammar on exactly the JSON-config shape that carries most
- * first-party keys — so the leaves are joined raw.
- */
-export function flattenToolInput(input: unknown, depth = 0): string {
-  if (depth > 6 || input == null) return "";
-  if (typeof input === "string") return input;
-  if (typeof input === "number" || typeof input === "boolean") return String(input);
-  if (Array.isArray(input)) return input.map((v) => flattenToolInput(v, depth + 1)).join("\n");
-  if (typeof input === "object") {
-    return Object.entries(input as Record<string, unknown>)
-      // Keep the key adjacent to the value so `{"api_key": "…"}` still reads as
-      // an assignment to the grammar above.
-      .map(([k, v]) => `${k}=${flattenToolInput(v, depth + 1)}`)
-      .join("\n");
-  }
-  return "";
-}

package/src/audit/leak-store.ts

@@ -1,220 +0,0 @@
-/**
- * Persistence for the leak record.
- *
- * Two files, because the data has two different reset semantics and one class
- * cannot be right for both — the same lesson `fp-home.ts` learned when
- * `session.json` moved into a directory classified wholesale as `derived`:
- *
- *   audit/leaks.json          derived   — every finding is reproducible by
- *                                          rescanning, so losing it costs a scan
- *   audit/leak-identity.json  identity  — the HMAC salt and the user's
- *                                          dismissals, neither of which any
- *                                          rescan can recreate
- *
- * Regenerate the salt and every finding id changes, so a machine that has been
- * quiet for months re-alerts for every credential at once. Drop the dismissals
- * and findings a human already judged not-a-secret come back, which is worse
- * than a missed alert: it teaches them the tool does not listen.
- *
- * ## Never throws
- *
- * A scan must not fail because a cache file is corrupt, unreadable, or written
- * by a newer version. Every read degrades to "no record yet" and every write
- * degrades to a no-op with a logged reason. The audit's job is to find leaks,
- * and refusing to run because its own bookkeeping is damaged would be the
- * failure mode that matters least causing the one that matters most.
- */
-import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
-import { dirname } from "node:path";
-
-import { auditLeaksFile, auditLeakIdentityFile } from "../hooks/fp-home";
-import { writeJsonAtomically } from "../../lib/atomic-write";
-import {
-  emptyRecord,
-  pruneRecord,
-  LEAK_RECORD_SCHEMA_VERSION,
-  type LeakRecord,
-  type LeakFinding,
-  type LeakSighting,
-} from "./leak-record";
-import { isFindingId } from "./leak-fingerprint";
-
-interface LeakIdentity {
-  /** Hex HMAC salt. Generated once, never transmitted, never derived from
-   *  anything guessable — see `fingerprintId`. */
-  salt: string;
-  /** Finding ids the user has said are not secrets. */
-  dismissed: string[];
-}
-
-/** Mode for both files. They carry no credential, but they do carry a machine
- *  salt and a map of which projects leaked what — not world-readable. */
-const FILE_MODE = 0o600;
-
-function readJson<T>(path: string): T | null {
-  try {
-    if (!existsSync(path)) return null;
-    return JSON.parse(readFileSync(path, "utf8")) as T;
-  } catch {
-    // Corrupt, truncated by a crash, or written by a version we cannot read.
-    // Treated as absent: the next write replaces it.
-    return null;
-  }
-}
-
-/**
- * The machine's leak identity, minting a salt on first use.
- *
- * `randomBytes(32)`, not a hash of anything about the machine. A salt derived
- * from a hostname or a uid would be reproducible by anyone who knows those, and
- * the whole point of salting the fingerprint is that a third party holding a
- * guessable candidate cannot confirm it by recomputing the digest.
- */
-export function readLeakIdentity(home?: string): LeakIdentity {
-  const existing = readJson<Partial<LeakIdentity>>(auditLeakIdentityFile(home));
-  if (existing && typeof existing.salt === "string" && existing.salt.length >= 32) {
-    return {
-      salt: existing.salt,
-      dismissed: existing.dismissed ?? [],
-    };
-  }
-  const minted: LeakIdentity = { salt: randomBytes(32).toString("hex"), dismissed: [] };
-  writeLeakIdentity(minted, home);
-  return minted;
-}
-
-export function writeLeakIdentity(identity: LeakIdentity, home?: string): boolean {
-  const path = auditLeakIdentityFile(home);
-  try {
-    mkdirSync(dirname(path), { recursive: true });
-    writeJsonAtomically(path, identity, { mode: FILE_MODE });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Load the record, or an empty one.
- *
- * A record written by a NEWER schema is discarded rather than migrated or
- * partially read: this file is a cache of derived findings, so throwing it away
- * costs one rescan, while guessing at an unknown shape risks reporting a
- * fingerprint built by rules we no longer understand.
- */
-/**
- * Drop a finding this build cannot render, and repair one it can.
- *
- * `leaks.json` is a file on disk. It can be truncated by a full disk mid-write,
- * edited by hand, or written by a NEWER build whose findings carry a shape this
- * one does not expect — and the envelope check below cannot see any of that,
- * because it only looks at `schemaVersion` and `findings` being an array.
- *
- * The failure that motivated this was not hypothetical in its consequences: one
- * malformed entry made `selectLeaks` dereference `undefined`, which threw out
- * of `buildHarmReport`, which sits OUTSIDE `reportHarm`'s try — so a scheduled
- * run that scanned correctly and wrote its cache correctly still exited 1, and
- * would keep doing so on every run until somebody opened the file.
- *
- * A bad SIGHTING loses the sighting, not the finding: the credential is the
- * thing that needs rotating, and "seen in a transcript" with no detail beats
- * silence about a leaked key.
- */
-function sanitizeFinding(raw: unknown): LeakFinding | null {
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
-  const f = raw as Record<string, unknown>;
-  // The id becomes a filename in the macOS notification queue, so anything
-  // that is not the exact minted shape disqualifies the whole entry.
-  if (typeof f.id !== "string" || !isFindingId(f.id)) return null;
-
-  const fp = f.fingerprint as Record<string, unknown> | undefined;
-  if (!fp || typeof fp !== "object" || typeof fp.display !== "string" || typeof fp.label !== "string") {
-    return null; // with no way to name it, a row would say nothing at all
-  }
-
-  const sightings = Array.isArray(f.sightings)
-    ? (f.sightings as unknown[]).filter((s): s is LeakSighting => {
-        if (!s || typeof s !== "object") return false;
-        const m = (s as Record<string, unknown>).mechanism as Record<string, unknown> | undefined;
-        return !!m && typeof m === "object" && typeof m.summary === "string";
-      })
-    : [];
-
-  return {
-    ...(f as unknown as LeakFinding),
-    fingerprint: {
-      display: fp.display,
-      label: fp.label,
-      length: typeof fp.length === "number" && Number.isFinite(fp.length) ? fp.length : 0,
-      attributed: fp.attributed === true,
-    },
-    name: typeof f.name === "string" ? f.name : null,
-    firstSeen: typeof f.firstSeen === "string" ? f.firstSeen : "",
-    lastSeen: typeof f.lastSeen === "string" ? f.lastSeen : "",
-    occurrences:
-      typeof f.occurrences === "number" && Number.isFinite(f.occurrences) ? f.occurrences : sightings.length,
-    sightings,
-  };
-}
-
-export function readLeakRecord(home?: string): LeakRecord {
-  const identity = readLeakIdentity(home);
-  const raw = readJson<LeakRecord>(auditLeaksFile(home));
-  if (!raw || raw.schemaVersion !== LEAK_RECORD_SCHEMA_VERSION || !Array.isArray(raw.findings)) {
-    return emptyRecord(identity.salt, new Date().toISOString());
-  }
-  // Every consumer — the digest, the dashboard, the notice guard — reads through
-  // here, so validating once at the gate is what keeps them all from each
-  // needing to defend against the same corrupt file.
-  const findings = (raw.findings as unknown[])
-    .map(sanitizeFinding)
-    .filter((f): f is LeakFinding => f !== null);
-  // The salt always comes from the identity file, never from the record — if
-  // the two ever disagree the identity file is authoritative, because it is the
-  // one classified to survive a reset.
-  return { ...raw, findings, salt: identity.salt };
-}
-
-/**
- * Persist the record, pruned.
- *
- * Pruning on WRITE rather than on read, so the bound is enforced exactly once
- * per scan and a reader never pays for it. Returns false on failure rather than
- * throwing — see the module header.
- */
-export function writeLeakRecord(record: LeakRecord, home?: string, nowMs = Date.now()): boolean {
-  const path = auditLeaksFile(home);
-  try {
-    mkdirSync(dirname(path), { recursive: true });
-    const pruned = pruneRecord(record, nowMs);
-    pruned.updatedAt = new Date(nowMs).toISOString();
-    writeJsonAtomically(path, pruned, { mode: FILE_MODE });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/** Mark a finding as not-a-secret. Survives a reset; see the module header. */
-export function dismissFinding(id: string, home?: string): boolean {
-  const identity = readLeakIdentity(home);
-  if (identity.dismissed.includes(id)) return true;
-  identity.dismissed.push(id);
-  return writeLeakIdentity(identity, home);
-}
-
-/**
- * Findings worth showing a human: undismissed, newest first.
- *
- * The dismissal list is applied HERE rather than at write time, so a dismissal
- * never destroys evidence — the finding stays in the record and simply stops
- * being surfaced. A user who dismisses by mistake has lost a row in a list, not
- * the fact that a credential leaked.
- */
-export function activeFindings(record: LeakRecord, home?: string): LeakRecord["findings"] {
-  const dismissed = new Set(readLeakIdentity(home).dismissed);
-  return record.findings
-    .filter((f) => !dismissed.has(f.id))
-    .sort((a, b) => (a.lastSeen < b.lastSeen ? 1 : a.lastSeen > b.lastSeen ? -1 : 0));
-}