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

package/src/audit/redact-example.ts

@@ -42,6 +42,8 @@
  */
 import { homedir } from "node:os";
 
+import type { AuditResult } from "./types";
+
 import { SECRET_PATTERNS } from "../hooks/builtin-policies";
 
 /** Longest example we let through, after redaction. */
@@ -132,18 +134,77 @@ export function maskTruncatedSecret(input: string): string {
  * identifier, including the camelCase `_authToken` that `npm config set`
  * writes. `KEY`, `PASS`, `AUTH`, `PAT` and `SIG` are also fragments of ordinary
  * words — `MONKEY_COUNT`, `PASSENGERS`, `AUTHOR`, `PATH`, `SIGNAL` — so they
- * only count as a whole `_`-delimited component.
+ * only count as a whole component, where the components come from
+ * `identifierComponents` and include camelCase humps as well as `_`.
  */
 const SECRET_NAME_SUBSTRINGS = [
   "TOKEN",
   "SECRET",
   "PASSWORD",
   "PASSWD",
+  "PASSPHRASE",
   "CREDENTIAL",
   "APIKEY",
   "PRIVATEKEY",
 ];
-const SECRET_NAME_COMPONENTS = ["KEY", "PASS", "AUTH", "PAT", "SIG", "SIGNATURE", "SESSION", "COOKIE"];
+const SECRET_NAME_COMPONENTS = ["PASS", "AUTH", "PAT", "SIG", "SIGNATURE", "COOKIE"];
+
+/**
+ * Names that mean "credential" only inside a COMPOUND identifier.
+ *
+ * Every entry here was measured as a dominant false positive on a real 2,664-
+ * transcript corpus, and the reason they are demotions rather than deletions is
+ * that the SHAPE layer already catches real vendor keys regardless of what they
+ * are called. The name layer exists for FIRST-PARTY secrets with no recognisable
+ * format — and those essentially always carry a qualified name
+ * (`COMPOSIO_API_KEY`, `DB_PASSWORD`), never a bare one. So requiring a compound
+ * costs almost nothing real and removes most of the noise.
+ *
+ *   PWD      `MYSQL_PWD` is MySQL's documented password variable; a bare `PWD`
+ *            is the shell's working directory, on every second line of a
+ *            captured session.
+ *   KEY      a bare `key=` is a React list prop, a map entry, a sort field.
+ *            80 findings on the measured corpus, none of them credentials.
+ *
+ * `SIG` was demoted here too and put back: a bare `sig=` in a URL query IS a
+ * request signature, and an existing test says so. It also never appeared in
+ * the measured noise, unlike the two above — the rule is that a demotion needs
+ * evidence, not a plausible story.
+ *
+ * `SESSION` is REMOVED from both lists rather than demoted, and the difference
+ * matters: demoting it would have changed nothing, because
+ * `DBUS_SESSION_BUS_ADDRESS` is already a compound. It was the single largest
+ * source of noise measured — 254 of 500 findings, every one of them
+ * `DBUS_SESSION_BUS_ADDRESS`, `XDG_SESSION_TYPE`, `SESSION_MANAGER`,
+ * `session_id` or `sessionUpdate`. A session IDENTIFIER is not a rotatable
+ * credential; a session SECRET still matches through `SECRET`, `TOKEN`, or
+ * `KEY` in `sessionKey`.
+ */
+const COMPOUND_ONLY_COMPONENTS = ["PWD", "KEY"];
+
+/**
+ * Split an identifier into its uppercased components, on `_`, `-`, `.` AND
+ * camelCase humps.
+ *
+ * The humps are the point. Splitting on `_` alone means `sessionKey`, `dbPass`,
+ * `basicAuth` and `authCookie` decompose to a single component that matches
+ * nothing, so their values shipped to the digest verbatim — 203 such names on
+ * this machine's corpus. They are not exotic: camelCase is what an identifier
+ * looks like everywhere except a shell environment, and the redactor is applied
+ * to transcripts full of TypeScript, JSON and Python.
+ *
+ * The second replace splits an acronym from the word that follows it, so
+ * `APIKey` yields `API` + `KEY` rather than one run of capitals that matches
+ * neither.
+ */
+function identifierComponents(name: string): string[] {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+    .toUpperCase()
+    .split(/[_\-.]+/)
+    .filter(Boolean);
+}
 
 /**
  * `NAME=value`, with the value quoted or running to the next shell separator.
@@ -151,20 +212,158 @@ const SECRET_NAME_COMPONENTS = ["KEY", "PASS", "AUTH", "PAT", "SIG", "SIGNATURE"
  * The unquoted alternative excludes quotes as well as separators: a value that
  * runs to end-of-token inside an already-quoted string (`"…?sig=deadbeef"`)
  * would otherwise swallow the closing quote and leave the line unbalanced.
+ *
+ * Four shapes, because the first spelling of this pattern was `NAME=value` and
+ * only that — no whitespace around the `=`, no `:`, no quoted name — and the
+ * other three all reached the emailed digest UNREDACTED. `NAME = "value"` and
+ * `NAME: "value"` are what a config file, a YAML key and a JSON body look like,
+ * which is most of where credentials are actually written down; `"name": val`
+ * is the same line once an agent pretty-prints it. A value only survived that
+ * gap if it independently matched one of the vendor patterns in
+ * `SECRET_PATTERNS` — and 230 of 237 secret-named assignments measured across
+ * this machine's transcripts match none of them, so the assignment rule was the
+ * only thing standing between them and the digest.
+ *
+ * The separator is captured and re-emitted verbatim rather than normalised to
+ * `=`, so a redacted YAML line is still YAML and a redacted JSON line is still
+ * recognisable as the field it came from. Horizontal whitespace only: `\s`
+ * would let a `KEY:` at end-of-line swallow the newline and glue the next line
+ * onto the match.
+ *
+ * The `:` alternative refuses a `//` after it, because a URL scheme is the one
+ * `name:value` shape that is not an assignment. Without the guard `https` reads
+ * as the name and the rest of the URL as its value — and since a non-secret
+ * name returns the match UNCHANGED but still CONSUMES it, a `?token=…` sitting
+ * inside that URL was swallowed by the `https:` match and never examined. The
+ * failure mode is silent and inverted: adding a separator to catch more secrets
+ * stopped one already being caught.
+ */
+/**
+ * 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_]*)=("[^"]*"|'[^']*'|[^\s;|&"']+)/g;
+const ASSIGNMENT_RE =
+  /(["']?)\b([A-Za-z_][A-Za-z0-9_]{0,127})\1([ \t]*(?::(?!\/\/)|=)[ \t]*)("[^"]*"|'[^']*'|[^\s;|&"']+)/g;
 
 /** Credentials inline in a URL, on ANY scheme — `https://user:pass@host`. */
-const URL_CREDENTIALS_RE = /([a-z][a-z0-9+.\-]*:\/\/)[^\s/:@]+:[^\s/@]+@/gi;
+// Every quantifier here is BOUNDED, for the same reason ASSIGNMENT_RE's is.
+// Unbounded, `[a-z0-9+.\-]*` is quadratic on any long lowercase run: at each of
+// n positions it consumes to the end hunting for a `://` that is not there,
+// then backtracks a character at a time. Measured at 18 SECONDS on 100 KB of a
+// single repeated letter — and this one runs over the WHOLE text, on every
+// example the audit redacts. A URI scheme is at most a few characters (RFC 3986
+// allows more, but nothing real uses it), and userinfo that runs past 256 bytes
+// is not a credential anyone typed.
+const URL_CREDENTIALS_RE = /([a-z][a-z0-9+.\-]{0,31}:\/\/)[^\s/:@]{1,256}:[^\s/@]{1,256}@/gi;
 
 /** `curl -u user:pass`, in both spellings and both separators. */
 const BASIC_AUTH_FLAG_RE = /((?:^|\s)(?:-u|--user)[\s=])\S+:\S+/g;
 
 /** True when an identifier's name says its value is a credential. */
+/**
+ * Prefixes whose values a build tool INLINES INTO THE BROWSER BUNDLE.
+ *
+ * These are not conventionally public, they are mechanically public: Next.js,
+ * Vite, CRA, Expo, SvelteKit, Astro, Nuxt and Gatsby each substitute the value
+ * into the JavaScript they ship to every visitor. A credential named this way
+ * has already been published by the framework, to everyone, before failproofai
+ * ever saw it.
+ */
+const CLIENT_BUNDLE_PREFIXES = [
+  "NEXT_PUBLIC",
+  "VITE",
+  "REACT_APP",
+  "EXPO_PUBLIC",
+  "NUXT_PUBLIC",
+  "GATSBY",
+  "STORYBOOK",
+  "PUBLIC",
+];
+
+/** Markers that name a key as the publishable half of a pair. */
+const PUBLISHED_MARKERS = /PUBLISHABLE|(^|_)PUBLIC_KEY$|(^|_)ANON_KEY$/;
+
+/**
+ * True when the identifier says the value is meant to be public.
+ *
+ * `isSecretName` matches any component in `KEY`/`PASS`/`AUTH`/… — and EVERY
+ * publishable key on earth is named `*_KEY`. Measured before this existed, it
+ * returned true for all twelve of `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`,
+ * `NEXT_PUBLIC_SUPABASE_ANON_KEY`, `VAPID_PUBLIC_KEY`, `PUBLISHABLE_KEY` and
+ * friends — including the ones carrying the literal word PUBLIC.
+ *
+ * Over-redaction is usually cheap: masking something that might be secret costs
+ * readability. This case is different, because we can PROVE the value is not a
+ * secret — so masking it reports a credential exposure that did not happen, and
+ * a security tool crying wolf about a browser-bundled config value is not a
+ * cheap error. This repo's own committed PostHog `phc_` key, documented in
+ * source as "Write-only (safe to commit)", is masked as an "assigned secret" by
+ * the rule this vetoes.
+ *
+ * Deliberately narrow. The marker must be a PREFIX (so a mid-name `PUBLIC` in
+ * `MY_PUBLIC_FACING_SECRET` does not disarm it) or an explicit publishable
+ * suffix. Words like ANON, BROWSER and SITE are excluded on their own — only
+ * `ANON_KEY`, which is Supabase's documented browser key, qualifies.
+ */
+export function isPublishedByDesign(name: string): boolean {
+  const components = identifierComponents(name);
+  if (components.length === 0) return false;
+  const upper = components.join("_");
+  for (const prefix of CLIENT_BUNDLE_PREFIXES) {
+    if (upper === prefix || upper.startsWith(prefix + "_")) return true;
+  }
+  return PUBLISHED_MARKERS.test(upper);
+}
+
+/**
+ * How confidently the NAME alone says "credential".
+ *
+ * `strong` — the word means secret and nothing else: `DB_PASSWORD`,
+ * `STRIPE_SECRET`, `PRIVATE_KEY`. A short value here is still worth flagging;
+ * `hunter2` assigned to `PASSWORD` is a leaked password.
+ *
+ * `weak` — the word is ALSO ordinary programming vocabulary: `key`, `token`,
+ * `auth`, `sig`. Measured on a real 2,664-transcript machine these produced
+ * `keyType`, `tokenLimitCancelled`, `max_output_tokens`, `resultKey`,
+ * `configDirKey` — 394 findings from this layer, of which 389 had no vendor
+ * prefix and 227 were under 24 characters. Nothing that short is an API key.
+ * A weak name has to be backed by a value that actually looks like a secret.
+ */
+export type SecretNameStrength = "strong" | "weak" | "none";
+
+const STRONG_NAME_WORDS = ["SECRET", "PASSWORD", "PASSWD", "PASSPHRASE", "CREDENTIAL", "APIKEY", "PRIVATEKEY"];
+
+export function secretNameStrength(name: string): SecretNameStrength {
+  if (!isSecretName(name)) return "none";
+  const upper = name.toUpperCase();
+  if (STRONG_NAME_WORDS.some((w) => upper.includes(w))) return "strong";
+  // `API_KEY` / `apiKey` split into components rather than matching APIKEY as a
+  // substring, and they are as unambiguous as the substring form.
+  const parts = identifierComponents(name);
+  if (parts.includes("API") && parts.includes("KEY")) return "strong";
+  return "weak";
+}
+
 export function isSecretName(name: string): boolean {
+  // Runs first and beats every other signal: a value the framework compiles
+  // into the browser bundle is public no matter what the rest of the name says.
+  if (isPublishedByDesign(name)) return false;
   const upper = name.toUpperCase();
   if (SECRET_NAME_SUBSTRINGS.some((word) => upper.includes(word))) return true;
-  return upper.split("_").some((part) => SECRET_NAME_COMPONENTS.includes(part));
+  const components = identifierComponents(name);
+  if (components.some((part) => SECRET_NAME_COMPONENTS.includes(part))) return true;
+  return components.length > 1 && components.some((part) => COMPOUND_ONLY_COMPONENTS.includes(part));
 }
 
 /**
@@ -193,15 +392,18 @@ export function isSecretName(name: string): boolean {
  * is the actionable half of the finding.
  */
 export function maskAssignedSecrets(input: string): string {
-  let out = input.replace(ASSIGNMENT_RE, (match, name: string, value: string) => {
-    if (!isSecretName(name)) return match;
-    // An earlier pass already named this one, and it named it better.
-    // `export ANTHROPIC_API_KEY=sk-ant-…` is masked by the vendor pattern as
-    // "Anthropic API key"; re-masking it here would downgrade that to the
-    // generic label and strip the marker's own tail as it went.
-    if (value.startsWith("[REDACTED")) return match;
-    return `${name}=[REDACTED: assigned secret]`;
-  });
+  let out = input.replace(
+    ASSIGNMENT_RE,
+    (match, quote: string, name: string, separator: string, value: string) => {
+      if (!isSecretName(name)) return match;
+      // An earlier pass already named this one, and it named it better.
+      // `export ANTHROPIC_API_KEY=sk-ant-…` is masked by the vendor pattern as
+      // "Anthropic API key"; re-masking it here would downgrade that to the
+      // generic label and strip the marker's own tail as it went.
+      if (value.startsWith("[REDACTED")) return match;
+      return `${quote}${name}${quote}${separator}[REDACTED: assigned secret]`;
+    },
+  );
   out = out.replace(URL_CREDENTIALS_RE, "$1[REDACTED: URL credentials]@");
   out = out.replace(BASIC_AUTH_FLAG_RE, "$1[REDACTED: basic auth]");
   return out;
@@ -298,15 +500,120 @@ export function shortenPaths(input: string, home = homedir()): string {
  * digest as one row, and a raw newline there breaks the plain-text layout while
  * saying nothing the single line does not.
  */
+/**
+ * Mask every secret, and nothing else.
+ *
+ * The three masking passes of `redactExample` without the path shortening, the
+ * whitespace collapse or the length cap. This is what a LOCAL renderer wants:
+ * on your own machine your own paths are the useful half of an example, and
+ * `~/…/db.ts` costs readability for no gain — nobody is protected from their own
+ * directory names. A credential on screen is the other half of that trade: it is
+ * one screenshot, one pasted issue or one screen-share away from being published,
+ * and unlike the path it can never be un-leaked.
+ *
+ * So the split is deliberate: everything that LEAVES the machine goes through
+ * `redactExample`; the terminal gets this.
+ */
+export function maskSecretsOnly(input: string): string {
+  return maskAssignedSecrets(maskTruncatedSecret(maskSecrets(input)));
+}
+
 export function redactExample(input: string, home = homedir()): string {
   // Assignment masking runs LAST of the three, so the two pattern-based passes
   // get first refusal on anything they can name precisely. A vendor prefix
   // yields "[REDACTED: Anthropic API key]"; falling through to this one would
   // have said only "assigned secret", which is true but less useful to read.
-  const masked = maskAssignedSecrets(maskTruncatedSecret(maskSecrets(input)));
+  const masked = maskSecretsOnly(input);
   const shortened = shortenPaths(masked, home);
   const collapsed = shortened.replace(/\s+/g, " ").trim();
   return collapsed.length > REDACTED_EXAMPLE_MAX_CHARS
     ? `${collapsed.slice(0, REDACTED_EXAMPLE_MAX_CHARS - 1)}…`
     : collapsed;
 }
+
+/**
+ * Redact every free-text field of an `AuditResult` that could carry a secret or
+ * name someone's disk.
+ *
+ * The counts, titles, timestamps and policy names are the substance of a report
+ * and none of them come from user data. What DOES come from user data is the
+ * example strings (slices of real commands), the per-example `cwd`, and the
+ * project lists — which are the same three things `redactExample` was written
+ * for, applied to the whole structure instead of one row.
+ *
+ * Used by every renderer that produces an artifact which can travel:
+ * `formatMarkdown` (the file the CLI calls a "Shareable report") and
+ * `formatJson` (whatever the caller pipes it into). The emailed digest reaches
+ * the same guarantee by a different route — `harm-report.ts` redacts each
+ * example as it selects it, because it also has to apply the reporting window.
+ *
+ * Returns a NEW object. The caller's result is left alone, so the dashboard and
+ * the cache keep the unredacted values they need to render a local view.
+ */
+export function redactAuditResult(result: AuditResult, home = homedir()): AuditResult {
+  // Built field by field ON PURPOSE. This was `{...result}` plus three named
+  // rewrites, which meant it was a FIELD ALLOWLIST pretending to be a redactor:
+  // every field it did not name — including any field added later — passed
+  // through byte-identical, absolute home paths and all. It guards
+  // `formatJson`, i.e. an artifact the product invites the user to share.
+  //
+  // Enumerating every key means TypeScript rejects the build when `AuditResult`
+  // grows a field nobody decided about here, which is the only mechanism that
+  // survives a future contributor. `redactAuditResultKeys` in the tests reflects
+  // over the real object and fails if this list drifts, covering the case where
+  // a field is added as optional and the compiler stays quiet.
+  const redacted: AuditResult = {
+    // Scalars and counters: no paths, no user content, nothing to redact.
+    version: result.version,
+    scannedAt: result.scannedAt,
+    transcripts: result.transcripts,
+    totals: result.totals,
+    eventsScanned: result.eventsScanned,
+    enabledBuiltinNames: result.enabledBuiltinNames,
+    // Salted, machine-local ids. They carry no path and cannot be reversed to
+    // a credential, so they pass through — but the decision is recorded here
+    // rather than inherited from a spread.
+    newLeakIds: result.newLeakIds,
+
+    // Everything below carries a path or user content and is rewritten.
+    scope: {
+      cli: result.scope.cli,
+      since: result.scope.since,
+      projects: result.scope.projects === "all"
+        ? "all"
+        : result.scope.projects.map((p) => shortenPaths(p, home)),
+    },
+    results: result.results.map((row) => ({
+      ...row,
+      examples: row.examples.map((e) => ({
+        ...e,
+        example: redactExample(e.example, home),
+        cwd: shortenPaths(e.cwd, home),
+      })),
+    })),
+    projectsScanned: result.projectsScanned.map((p) => shortenPaths(p, home)),
+  };
+  return redacted;
+}
+
+/**
+ * Every top-level key `redactAuditResult` has consciously handled.
+ *
+ * The compiler catches a REQUIRED field added to `AuditResult`, because the
+ * object literal above would stop satisfying the type. It does not catch an
+ * OPTIONAL one — and the leak record is arriving as optional fields. So the
+ * test reflects over a real result and fails when a key appears here that is
+ * not in this list, which forces the decision to be made rather than defaulted.
+ */
+export const REDACTED_AUDIT_RESULT_KEYS: ReadonlyArray<keyof AuditResult> = [
+  "version",
+  "scannedAt",
+  "scope",
+  "transcripts",
+  "results",
+  "totals",
+  "projectsScanned",
+  "eventsScanned",
+  "enabledBuiltinNames",
+  "newLeakIds",
+];

package/src/audit/report-harm.ts

@@ -31,6 +31,7 @@ import { getValidAccessToken } from "../../lib/auth/auth-store";
 import { AuthApiError, submitAuditReport } from "../../lib/auth/api-server-client";
 import { readConfig } from "../hooks/fp-config";
 import { buildHarmReport } from "./harm-report";
+import { activeFindings, readLeakRecord } from "./leak-store";
 import {
   ensureMachineIdentity,
   machineLabel,
@@ -101,7 +102,16 @@ export async function reportHarm(result: AuditResult): Promise<HarmReportOutcome
     return { kind: "failed", error: err instanceof Error ? err.message : String(err) };
   }
 
-  const report = buildHarmReport(result, identity.last_reported_at, intervalDays);
+  // The leak record is read here rather than carried on the AuditResult: the
+  // digest wants every credential still live in this window, not only the ones
+  // this particular scan happened to re-encounter. A key that leaked last month
+  // and was not touched by today's transcripts is still a key to rotate.
+  const report = buildHarmReport(
+    result,
+    identity.last_reported_at,
+    intervalDays,
+    activeFindings(readLeakRecord()),
+  );
   const hits = report.harmful.reduce((n, p) => n + p.hits, 0);
 
   try {
@@ -112,6 +122,7 @@ export async function reportHarm(result: AuditResult): Promise<HarmReportOutcome
       window_from: report.window_from,
       window_to: report.window_to,
       harmful: report.harmful,
+      leaks: report.leaks,
     });
 
     // Persist whatever the server says the next window starts at, INCLUDING when

package/src/audit/report.ts

@@ -10,6 +10,7 @@
  * install command + report path + star link.
  */
 import type { AuditCount, AuditResult, RunAuditOptions } from "./types";
+import { maskSecretsOnly, redactAuditResult, redactExample, shortenPaths } from "./redact-example";
 
 const ANSI = {
   reset: "\x1B[0m",
@@ -105,7 +106,7 @@ function renderRow(r: AuditCount, opts: { showExamples?: boolean }): string[] {
     `        ${ANSI.dim}Last seen ${formatTimeAgo(r.lastSeen)} · ${r.projects} project${r.projects === 1 ? "" : "s"}${ANSI.reset}`,
   );
   if (opts.showExamples && r.examples[0]) {
-    out.push(`        ${ANSI.dim}Example: ${r.examples[0].example}${ANSI.reset}`);
+    out.push(`        ${ANSI.dim}Example: ${maskSecretsOnly(r.examples[0].example)}${ANSI.reset}`);
   }
   if (r.installHint) {
     const arrowColor = r.enabledInConfig ? ANSI.green : ANSI.cyan;
@@ -226,7 +227,7 @@ export function formatText(result: AuditResult, opts: RunAuditOptions = {}): str
 }
 
 export function formatJson(result: AuditResult): string {
-  return JSON.stringify(result, null, 2);
+  return JSON.stringify(redactAuditResult(result), null, 2);
 }
 
 /** Escape characters that would break a markdown table row. Pipes split
@@ -334,7 +335,9 @@ export function formatMarkdown(result: AuditResult): string {
         out.push("");
       }
       for (const e of r.examples) {
-        out.push(`- \`${escapeBackticks(e.example)}\` _(${e.cwd || "?"}, ${formatTimeAgo(e.timestamp)})_`);
+        out.push(
+          `- \`${escapeBackticks(redactExample(e.example))}\` _(${shortenPaths(e.cwd) || "?"}, ${formatTimeAgo(e.timestamp)})_`,
+        );
       }
       out.push("");
     }

package/src/audit/schedule-cli.ts

@@ -219,6 +219,14 @@ export function runScheduleStatus(): void {
   // so it is a destination in name only. Showing the address for one would tell
   // somebody their digests are going somewhere they are not.
   const live = auth && auth.refresh_expires_at * 1000 > Date.now() ? auth : null;
+  // Beside the schedule, because they are the two halves of "what does this
+  // machine do on its own" — one decides whether it scans, the other whether it
+  // is allowed to interrupt you about what it found.
+  detail.push([
+    "leak notifications",
+    config.audit.notify ? green("on") : dim("off  (failproofai audit --notify)"),
+  ]);
+
   detail.push(["reports to", live ? live.user.email : dim("— signed out")]);
   if (on && !live) {
     // The state the reporter surfaces as "signed-out". Named here for the same
@@ -346,3 +354,32 @@ export function asScheduleError(err: unknown): never {
   }
   throw err;
 }
+
+/**
+ * Turn the desktop banner on or off.
+ *
+ * A separate command from `--schedule` rather than a flag on it, because they
+ * are separate decisions with different lifetimes: somebody who wants the
+ * weekly scan and not the banner should not have to re-state their schedule to
+ * say so, and somebody silencing the banner in an annoyed moment should not
+ * discover they also turned off the scan.
+ *
+ * Writes the same `audit.notify` key the dashboard toggle writes and the audit
+ * child reads, so the two surfaces cannot disagree.
+ */
+export function runNotifyToggle(enable: boolean): void {
+  try {
+    updateConfig({ audit: { notify: enable } });
+  } catch (err) {
+    process.stderr.write(
+      `Could not update the setting: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    process.exit(1);
+  }
+  process.stdout.write(
+    enable
+      ? `\n${green("on")}  leak notifications — this machine will tell you when a scan finds a credential.\n\n`
+      : `\n${dim("off")} leak notifications — scans continue, and findings still appear in ` +
+          `\`failproofai audit\` and the emailed digest.\n\n`,
+  );
+}

package/src/audit/scoring.ts

@@ -1,6 +1,55 @@
 /**
  * Score derivation for the audit dashboard.
  *
+ * ## SWITCHED OFF — nothing in the product calls any of this (2026-09-07)
+ *
+ * Every function below is intact and still covered by
+ * `__tests__/audit/scoring.test.ts`, deliberately: the score is commented out at
+ * its call sites, not deleted, so restoring it is un-commenting rather than
+ * rewriting. The call sites, all commented and cross-referenced back to here:
+ * `audit-dashboard.tsx` (the four `useMemo`s, the poster/how-to-improve/
+ * come-back-better props, and the `score`/`grade` PostHog properties),
+ * `audit-poster.tsx` (the `.poster-score` block, the PNG filename, the share
+ * payload), `how-to-improve-section.tsx` (the projected sub-heading),
+ * `share-templates.ts` (19 of 20 templates interpolated the number).
+ *
+ * ### Why
+ *
+ * Two reasons, one product and one correctness.
+ *
+ * The product reason is the owner's: the audit tried to do too many things
+ * shallowly, and grading a machine 0-100 with a letter tier was not the half
+ * worth keeping.
+ *
+ * The correctness reason is worse and is the one to read before switching it
+ * back on. **`deriveScore` never reads `enabledInConfig`** — only
+ * `projectedScore` does, at the filter below. So the number the dashboard
+ * rendered as "enable all N → projected {score}" was undeliverable by
+ * construction: a user who took the prescription, enabled the policies and
+ * re-ran got the SAME score with the projection gone. Advertised up to +22,
+ * delivered 0. There is also no time window, so a hit denied today is counted
+ * against the machine forever.
+ *
+ * Two further things measured at the same time, neither of them the score's
+ * fault but both worth knowing if this comes back:
+ *
+ *  - `penaltyFor` consumes `row.hits`, i.e. OCCURRENCES. Occurrences amplify
+ *    against distinct values by 10.7x-41x and non-uniformly by class, so the
+ *    sum does not preserve rank order between classes. Fixing that needs a
+ *    per-distinct-value carrier, which `AuditCount` does not have.
+ *  - `syntheticRank`, `scoreToPercentile` and `COHORT_SIZE` had already lost
+ *    their last caller before this change — the cohort they describe does not
+ *    exist. They are dead either way.
+ *
+ * ### To restore
+ *
+ * Un-comment the call sites listed above (each carries its original inline) and
+ * put the score-bearing share copy back from the block at the bottom of
+ * `share-templates.ts`. Make `score`/`grade` required again in `ShareCtx` and in
+ * `audit-poster.tsx`'s `Props`, and the compiler will walk you through the rest.
+ * Fix the `enabledInConfig` defect first, or it will be advertising the same
+ * undeliverable number.
+ *
  * Score is on 0-100, mapped to letter grades that anchor the leaderboard
  * + tier prose. The thresholds match the reference design (assets/audit):
  *

package/src/audit/types.ts

@@ -45,6 +45,9 @@ export interface TranscriptMetadata {
   mtimeMs: number;
   /** Byte size of the transcript file. Used for cache invalidation. */
   sizeBytes: number;
+  /** Optional host-authored session purpose. Used only to distinguish
+   * deliberate credential-scanner research from evidence of a leak. */
+  sessionDescription?: string;
 }
 
 /** Per-session detector state. Detectors mutate this freely. */
@@ -119,6 +122,27 @@ export interface AuditCount {
 }
 
 /** Per-transcript scan result (also the per-transcript cache value). */
+/** One credential sighting, already fingerprinted. */
+export interface TranscriptLeak {
+  /** Salted, machine-local id for the DISTINCT value. */
+  id: string;
+  /** Masked rendering + class + length. Never the value. */
+  fingerprint: import("./leak-fingerprint").LeakFingerprint;
+  /** Identifier it was assigned to, when it came from an assignment. */
+  name: string | null;
+  /** Rule that found it. */
+  rule: string;
+  /** Whether a vendor shape matched — gates whether an alert may name a console. */
+  shaped: boolean;
+  timestamp: string;
+  cwd: string;
+  toolName: string;
+  /** Sent by the agent, or received by it. Different exposures, different fixes. */
+  direction: "input" | "result";
+  /** Home-shortened path the value was read from or written to, when there was one. */
+  path: string | null;
+}
+
 export interface TranscriptAuditResult {
   /** Cache key: matches TranscriptMetadata.transcriptPath. */
   transcriptPath: string;
@@ -140,6 +164,20 @@ export interface TranscriptAuditResult {
   hitsByName: Record<string, number>;
   /** Up to 3 example commands per policy/detector (later coalesced upstream). */
   examplesByName: Record<string, { timestamp: string; cwd: string; example: string }[]>;
+  /**
+   * Credentials found in this transcript, one entry per SIGHTING.
+   *
+   * Deliberately separate from `hitsByName`, which counts by RULE and cannot
+   * enumerate distinct values. These carry the fingerprint rather than the
+   * credential — the raw value never leaves `scanOneTranscript`.
+   *
+   * Optional so a cached result written before this field existed still parses;
+   * absent reads as "this transcript predates leak scanning", not "clean".
+   */
+  leaks?: TranscriptLeak[];
+  /** The session was explicitly generating/researching credential fixtures,
+   * so its matches are examples rather than evidence of user leakage. */
+  leakScanSuppressed?: "credential-research";
   /** First/last timestamp per name. */
   rangeByName: Record<string, { first: string; last: string }>;
 }
@@ -179,6 +217,15 @@ export interface AuditResult {
    *  Lets the dashboard answer "is this policy already on?" for
    *  detector-mapped policies that may not have hit during this audit. */
   enabledBuiltinNames: string[];
+  /**
+   * Ids of credentials seen for the FIRST time in this scan.
+   *
+   * What a notice keys on. Not "findings this scan saw" — a key already in the
+   * record must not re-alert however many fresh sightings it picks up, and one
+   * seen for the first time must alert even though its rule has fired before.
+   * Optional so a cached result predating leak scanning still parses.
+   */
+  newLeakIds?: string[];
 }
 
 /** CLI-supplied options for `runAudit()`. Set by `bin/failproofai.mjs`. */