failproofai 1.0.4-beta.8 → 1.0.4

package/src/audit/leak-fingerprint.ts

@@ -1,198 +0,0 @@
-/**
- * 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 for pending macOS banners, so an id is a path component,
- * and a path component built from unvalidated input is a directory traversal.
- *
- * 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);
-}

package/src/audit/leak-record.ts

@@ -1,248 +0,0 @@
-/**
- * The per-credential record — what the audit knows that `AuditCount` cannot say.
- *
- * `AuditCount` aggregates BY RULE: it can report that `sanitize-api-keys` fired
- * 47 times and show three 80-character examples. It cannot enumerate 47 distinct
- * keys, say which of them is the same key seen twice, or answer "which CLI, in
- * which project, at what time, and how did it get there". Every surface the
- * narrowed product needs — the emailed digest, the dashboard's leak view, and
- * the once-per-finding notification guard — asks exactly those questions, so
- * none of them can be built on the rule-level record.
- *
- * ## Grouped by VALUE, not by occurrence — this is the whole bloat story
- *
- * The obvious shape is one row per sighting. Measured against the real corpus
- * that is 10,301 rows, against roughly 266 distinct values, against about 25
- * genuinely real credentials. Two orders of magnitude of duplication, because
- * one pasted key fans out across every session that touched it — the single
- * confirmed-live password in the corpus appeared in 11 files and 22 occurrences,
- * partly because Claude's own checkpoint records replay the prompt that carried
- * it.
- *
- * So the unit is the DISTINCT VALUE, with a bounded list of sightings attached
- * as evidence. A finding seen a thousand times costs the same on disk as one
- * seen twice: `MAX_SIGHTINGS` entries, plus a count. At the corpus's own numbers
- * that is roughly 130 KB for the whole file, which is why this is one file and
- * not a directory — a per-finding file would spend more on inodes and directory
- * entries than on the findings.
- *
- * ## What is deliberately NOT stored
- *
- * The credential itself, ever. The record holds a salted id (for dedupe across
- * scans) and a fingerprint (for a human to recognise the key in a console) and
- * nothing that could reconstruct the value. `~/.failproofai/` is a directory the
- * user did not ask for and cannot audit, so a leak scanner that caches the leaks
- * has made the problem worse rather than better.
- */
-import type { IntegrationType } from "../hooks/types";
-import type { LeakFingerprint } from "./leak-fingerprint";
-
-/** Sightings kept per distinct value. Enough to answer 5W1H for the first and
- *  most recent exposure without storing the long tail nobody reads. */
-export const MAX_SIGHTINGS = 5;
-
-/** Findings not seen in this many days are dropped on the next write. A key
- *  whose transcripts have aged out of the scan window is not evidence of
- *  anything current, and keeping it forever grows the file without bound. */
-export const FINDING_TTL_DAYS = 90;
-
-/** Cap on distinct findings retained, newest-first. A machine with more than
- *  this is not going to triage them, and the census measured a name-only rule
- *  emitting thousands — the cap is what stops a bad matcher filling the disk. */
-export const MAX_FINDINGS = 500;
-
-/**
- * How a credential came to be where it was found — the "how" of 5W1H.
- *
- * Derived from the tool event rather than authored, so it is always specific:
- * "read from ~/…/.env" beats "detected in a file operation". The path is
- * home-shortened by the caller before it reaches here.
- */
-export interface LeakMechanism {
-  /** Short past-tense phrase, e.g. "read from ~/…/.env". */
-  summary: string;
-  /** Canonical tool name (Bash, Read, Write, Edit…). */
-  toolName: string;
-  /** Where the value appeared: the tool's INPUT (the agent sent it) or its
-   *  RESULT (the agent received it). Different exposures with different
-   *  remedies — an input is deniable at PreToolUse, a result is not. */
-  direction: "input" | "result";
-}
-
-/** One exposure of one credential: the where/when/who of 5W1H. */
-export interface LeakSighting {
-  /** WHO — the harness whose transcript carried it. */
-  cli: IntegrationType;
-  /** WHERE — session and project. `cwd` is already home-shortened. */
-  sessionId: string;
-  cwd: string;
-  /** WHEN — ISO-8601, from the transcript line. */
-  at: string;
-  /** HOW. */
-  mechanism: LeakMechanism;
-}
-
-/** One distinct credential, however many times it was seen. */
-export interface LeakFinding {
-  /** Salted, machine-local, stable across scans. Never derived from the
-   *  fingerprint, which is not unique. */
-  id: string;
-  /** WHAT — the masked rendering, its class, and its length. */
-  fingerprint: LeakFingerprint;
-  /** The identifier it was assigned to, when it came from an assignment
-   *  (`COMPOSIO_API_KEY`). For the 230-of-237 first-party class this is the
-   *  only actionable field there is, since no vendor console exists. */
-  name: string | null;
-  /** Which rule found it, for explaining and for suppression. */
-  rule: string;
-  /** How much we trust the attribution — mirrors the pattern census's tiers. */
-  confidence: "doc-verified" | "source-verified" | "partner-corroborated" | "observed-only" | "name-only";
-  firstSeen: string;
-  lastSeen: string;
-  /** Total exposures, which is NOT `sightings.length` — see MAX_SIGHTINGS. */
-  occurrences: number;
-  /** Bounded evidence, oldest first. */
-  sightings: LeakSighting[];
-  /** Set when the user dismisses it. Dismissed findings are retained (so they
-   *  do not re-alert) but never notified about again. */
-  dismissedAt?: string;
-  /** Set when a notice for this finding has been delivered, so the next scan
-   *  stays quiet. The delivery guard itself is a separate O_EXCL marker; this
-   *  is the human-readable record of it. */
-  notifiedAt?: string;
-}
-
-export interface LeakRecord {
-  schemaVersion: number;
-  /** Per-machine HMAC salt for `fingerprintId`. Generated once, never sent. */
-  salt: string;
-  updatedAt: string;
-  findings: LeakFinding[];
-}
-
-export const LEAK_RECORD_SCHEMA_VERSION = 1;
-
-/**
- * Fold one new sighting into the record.
- *
- * Returns whether this is a **newly seen** credential, which is what the
- * notification guard keys on: a finding whose id is already present must not
- * alert again, however many new sightings it accumulates. Getting this backwards
- * is the failure the census measured — keying on the rule-level examples, which
- * `mergeIncremental` freezes at the first three, silently misses the arrival of
- * a brand-new key while re-alerting for old ones.
- */
-export function upsertFinding(
-  record: LeakRecord,
-  incoming: Omit<LeakFinding, "firstSeen" | "lastSeen" | "occurrences" | "sightings"> & {
-    sighting: LeakSighting;
-  },
-): { record: LeakRecord; isNew: boolean } {
-  const { sighting, ...rest } = incoming;
-  const existing = record.findings.find((f) => f.id === rest.id);
-
-  if (!existing) {
-    record.findings.push({
-      ...rest,
-      firstSeen: sighting.at,
-      lastSeen: sighting.at,
-      occurrences: 1,
-      sightings: [sighting],
-    });
-    return { record, isNew: true };
-  }
-
-  // Keep the earliest sighting AND the most recent evidence. The report/email
-  // promises the CLI and timestamp of the latest exposure; keeping only the
-  // first five made those fields stale forever after a busy credential crossed
-  // the cap. Middle sightings are the expendable ones.
-  const seen = existing.sightings.some(
-    (s) =>
-      s.sessionId === sighting.sessionId &&
-      s.at === sighting.at &&
-      s.mechanism.direction === sighting.mechanism.direction &&
-      s.mechanism.summary === sighting.mechanism.summary,
-  );
-  // Cached transcript results are folded through this function again. An
-  // identical sighting is therefore not a new exposure and must not inflate
-  // the count each time the same cache entry is reused.
-  if (seen) return { record, isNew: false };
-
-  existing.occurrences += 1;
-  if (sighting.at > existing.lastSeen) existing.lastSeen = sighting.at;
-  if (sighting.at < existing.firstSeen) existing.firstSeen = sighting.at;
-
-  existing.sightings.push(sighting);
-  existing.sightings.sort((a, b) => a.at.localeCompare(b.at));
-  if (existing.sightings.length > MAX_SIGHTINGS) {
-    existing.sightings.splice(1, existing.sightings.length - MAX_SIGHTINGS);
-  }
-  return { record, isNew: false };
-}
-
-/**
- * Drop what is no longer worth keeping, so the file cannot grow without bound.
- *
- * Order matters: age out first, then cap. Capping first would let a burst of
- * stale findings evict fresh ones.
- */
-export function pruneRecord(record: LeakRecord, nowMs: number): LeakRecord {
-  const cutoff = new Date(nowMs - FINDING_TTL_DAYS * 86_400_000).toISOString();
-  // A missing or malformed timestamp cannot be aged out safely. Keep it until
-  // the bounded-cap pass below rather than silently deleting a finding that the
-  // reporting path deliberately surfaces as having an unknown date.
-  const live = record.findings.filter(
-    (f) => !f.lastSeen || !Number.isFinite(Date.parse(f.lastSeen)) || f.lastSeen >= cutoff,
-  );
-  live.sort((a, b) => (a.lastSeen < b.lastSeen ? 1 : a.lastSeen > b.lastSeen ? -1 : 0));
-  record.findings = live.slice(0, MAX_FINDINGS);
-  return record;
-}
-
-/** An empty record, for a machine that has never scanned. */
-export function emptyRecord(salt: string, nowIso: string): LeakRecord {
-  return {
-    schemaVersion: LEAK_RECORD_SCHEMA_VERSION,
-    salt,
-    updatedAt: nowIso,
-    findings: [],
-  };
-}
-
-/**
- * Describe how a credential came to be in a tool event.
- *
- * Specific by construction: the path or command is what makes a finding
- * recognisable to the person who caused it, and a generic phrase ("detected in
- * tool input") is the kind of alert people learn to ignore.
- */
-export function describeMechanism(
-  toolName: string,
-  direction: "input" | "result",
-  shortPath: string | null,
-): LeakMechanism {
-  const where = shortPath ? ` ${shortPath}` : "";
-  let summary: string;
-  if (direction === "result") {
-    summary = shortPath ? `appeared in the output of reading${where}` : "appeared in tool output";
-  } else {
-    switch (toolName) {
-      case "Read":
-        summary = `read from${where || " a file"}`;
-        break;
-      case "Write":
-        summary = `written to${where || " a file"}`;
-        break;
-      case "Edit":
-      case "NotebookEdit":
-        summary = `edited into${where || " a file"}`;
-        break;
-      case "Bash":
-        summary = "passed in a shell command";
-        break;
-      default:
-        summary = `sent to the ${toolName} tool`;
-    }
-  }
-  return { summary, toolName, direction };
-}