failproofai 1.0.3 → 1.0.4-beta.2

package/src/audit/leak-store.ts

@@ -0,0 +1,217 @@
+/**
+ * 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 (notice markers, the macOS 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));
+}

package/src/audit/macos-notifier.ts

@@ -0,0 +1,310 @@
+/**
+ * Getting a notification onto a Mac's screen from a process that has no screen.
+ *
+ * On Linux the scheduled audit talks to the session bus directly and is done
+ * (`desktop-notify.ts`). macOS has no equivalent shortcut, and the reason is
+ * structural rather than a missing permission: launchd has two domains, and
+ * Notification Center lives in only one of them. `failproofaid` is installed as
+ * a **LaunchDaemon** — that is what makes it start at boot and survive logout,
+ * the property the whole daemon design turns on — so it and every child it
+ * spawns run in the *system* domain, outside the logged-in user's GUI session.
+ * A `display notification` from there posts into nothing. Apple's TN2083 draws
+ * exactly this line, and Time Machine ships the same split: a privileged daemon
+ * doing the work, an agent in the user's session doing the talking.
+ *
+ * So this module installs the second half — a **LaunchAgent**, which launchd
+ * starts inside the Aqua session, where Notification Center is reachable.
+ *
+ * ## Three choices worth stating, because the obvious alternative is wrong
+ *
+ * **`~/Library/LaunchAgents`, not `/Library/LaunchAgents`.** The per-user
+ * directory is owned by the user and writable without elevation, so installing
+ * this asks for nothing — no password, no second sudo prompt in a wizard that
+ * already spent its one. The system-wide agent directory would need admin and
+ * would install for every account on the box, which is not what a per-user
+ * notification is.
+ *
+ * **An app bundle, not a bare `osascript -e 'display notification'`.** A raw
+ * osascript notification is attributed to whatever host ran it — in practice
+ * "Script Editor" — so it inherits Script Editor's notification permission,
+ * appears under Script Editor in System Settings, and is indistinguishable from
+ * any other script on the machine. Compiling a tiny applet with `osacompile`
+ * gives it its own bundle identifier, so the banner says failproofai, and the
+ * user gets a real entry they can allow, silence or deny like any other app.
+ *
+ * **A watched drop directory, not a resident process.** The agent is not a
+ * daemon: `WatchPaths` makes launchd start it only when a file appears, and it
+ * exits as soon as the directory is empty. Nothing is resident, nothing polls,
+ * and a machine that never leaks a credential never runs it at all.
+ *
+ * ## What this does NOT claim
+ *
+ * That the user saw it. macOS can be in Do Not Disturb, the display can be
+ * asleep, and the user can deny the bundle in System Settings — none of which
+ * is visible from here. The banner is a prompt to look; the record on disk is
+ * the thing that lasts.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+import { runDir } from "../hooks/fp-home";
+import { isFindingId } from "./leak-fingerprint";
+
+/** The bundle identifier the banner is attributed to, and the agent's label. */
+export const MAC_NOTIFIER_LABEL = "ai.failproof.notifier";
+
+/** Where a queued notification waits for the agent to pick it up. */
+export const macNotifyDir = (home?: string) => resolve(runDir(home), "notify");
+
+/** The compiled applet. Under `~/.failproofai` rather than `/Applications`,
+ *  because it is a delivery mechanism, not something to launch. */
+export function macNotifierAppPath(home?: string): string {
+  return resolve(runDir(home), "..", "bin", "FailproofAI Notifier.app");
+}
+
+export function macNotifierPlistPath(): string {
+  return resolve(homedir(), "Library", "LaunchAgents", `${MAC_NOTIFIER_LABEL}.plist`);
+}
+
+function escapeXml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/**
+ * The AppleScript the applet runs: drain the directory, say each line, exit.
+ *
+ * Payload format is two lines — title, then body — chosen over JSON because
+ * AppleScript has no JSON parser and shelling out to one would put a second
+ * interpreter in the path of a two-field message.
+ *
+ * The file is REMOVED BEFORE the notification is posted, and that order is
+ * deliberate: `WatchPaths` fires on every change to the directory, so a file
+ * that cannot be displayed and is not removed would wake this agent forever.
+ * At-most-once is the right failure here because the caller has already claimed
+ * the finding on disk — a dropped banner costs one silent finding, a wake loop
+ * costs the machine.
+ */
+export function notifierScript(home?: string): string {
+  const dir = macNotifyDir(home);
+  return `on run
+	set dropDir to ${JSON.stringify(dir + "/")}
+	set listing to ""
+	try
+		set listing to do shell script "ls -1 " & quoted form of dropDir & " 2>/dev/null"
+	end try
+	repeat with entryName in paragraphs of listing
+		set entryPath to dropDir & (entryName as string)
+		if (entryName as string) is not "" then
+			try
+				set payload to do shell script "cat " & quoted form of entryPath & " 2>/dev/null"
+				do shell script "rm -f " & quoted form of entryPath
+				set lines_ to paragraphs of payload
+				if (count of lines_) is greater than 1 then
+					set noteTitle to item 1 of lines_
+					set noteBody to ""
+					repeat with i from 2 to (count of lines_)
+						if noteBody is not "" then set noteBody to noteBody & " "
+						set noteBody to noteBody & (item i of lines_)
+					end repeat
+					display notification noteBody with title noteTitle
+				end if
+			end try
+		end if
+	end repeat
+end run
+`;
+}
+
+/**
+ * Exported for the same reason `launchdPlistContents` is: it is the only way to
+ * assert this file's shape from a Linux CI runner, which is every CI runner we
+ * have.
+ */
+export function notifierPlistContents(appPath: string, watchDir: string): string {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${escapeXml(MAC_NOTIFIER_LABEL)}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${escapeXml(resolve(appPath, "Contents", "MacOS", "applet"))}</string>
+    </array>
+    <!-- Started only when something is queued, and it exits when the queue is
+         empty. RunAtLoad would fire it once at login with nothing to say. -->
+    <key>WatchPaths</key>
+    <array>
+        <string>${escapeXml(watchDir)}</string>
+    </array>
+    <key>RunAtLoad</key>
+    <false/>
+    <!-- Not a service: it does one pass and exits, and launchd must not treat
+         that as a crash to restart. -->
+    <key>KeepAlive</key>
+    <false/>
+    <key>ProcessType</key>
+    <string>Interactive</string>
+</dict>
+</plist>
+`;
+}
+
+export interface MacNotifierResult {
+  installed: boolean;
+  reason?: string;
+}
+
+/** Bounded, and never inherits a TTY — this runs from inside a wizard. */
+function run(cmd: string, args: string[]): void {
+  execFileSync(cmd, args, { stdio: "ignore", timeout: 20_000 });
+}
+
+/**
+ * Install the notifier, silently.
+ *
+ * Silent on purpose. An earlier draft printed "installing a small helper so we
+ * can notify you about leaks (macOS only)" during setup, which reads as an
+ * apology for something the user already asked for by running setup — every
+ * other app that can raise a notification installs its delivery path without
+ * narrating it. What the user is asked is the thing that matters (does this
+ * machine scan, and may it interrupt), and both of those are real settings.
+ *
+ * Returns rather than throws. Notifications are one channel of several, and a
+ * Mac that cannot compile an applet must still finish setting up its daemon,
+ * its hooks and its policies — the parts that actually enforce anything.
+ */
+export function installMacNotifier(home?: string): MacNotifierResult {
+  if (process.platform !== "darwin") return { installed: false, reason: "not macOS" };
+  try {
+    const app = macNotifierAppPath(home);
+    const watch = macNotifyDir(home);
+    mkdirSync(watch, { recursive: true, mode: 0o700 });
+    mkdirSync(resolve(app, ".."), { recursive: true });
+
+    const scriptPath = resolve(watch, "..", "notifier.applescript");
+    writeFileSync(scriptPath, notifierScript(home), { mode: 0o600 });
+    // osacompile refuses to overwrite an existing bundle, so a reinstall (a
+    // second `failproofai config`, or an upgrade) has to clear it first.
+    rmSync(app, { recursive: true, force: true });
+    run("osacompile", ["-o", app, scriptPath]);
+    rmSync(scriptPath, { force: true });
+
+    // Give the bundle its own identity, so the banner is attributed to
+    // failproofai instead of to whatever compiled it, and so the user gets one
+    // entry in System Settings > Notifications they can turn off themselves.
+    const plist = resolve(app, "Contents", "Info.plist");
+    run("defaults", ["write", plist, "CFBundleIdentifier", MAC_NOTIFIER_LABEL]);
+    run("defaults", ["write", plist, "CFBundleName", "failproofai"]);
+    // `defaults write` leaves the file 0600 and owned by us but in binary
+    // format; launchd and LaunchServices both read either, so no conversion.
+
+    mkdirSync(resolve(macNotifierPlistPath(), ".."), { recursive: true });
+    writeFileSync(macNotifierPlistPath(), notifierPlistContents(app, watch), { mode: 0o644 });
+
+    const target = `gui/${process.getuid?.() ?? 0}`;
+    // bootout first: bootstrap fails outright on an already-loaded label, and
+    // a reinstall must land the NEW plist rather than leave the old one live.
+    try {
+      run("launchctl", ["bootout", `${target}/${MAC_NOTIFIER_LABEL}`]);
+    } catch {
+      // Not loaded. That is the normal first-install case.
+    }
+    run("launchctl", ["bootstrap", target, macNotifierPlistPath()]);
+    return { installed: true };
+  } catch (err) {
+    return { installed: false, reason: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Remove the agent and the bundle.
+ *
+ * Called from `failproofai uninstall --purge`. Unconditional and quiet: an
+ * agent left behind after an uninstall is a plist launchd keeps trying to start
+ * from a path that no longer exists, which shows up in the user's log forever
+ * and is the exact class of leftover an uninstall exists to prevent.
+ */
+export function uninstallMacNotifier(home?: string): void {
+  if (process.platform !== "darwin") return;
+  try {
+    run("launchctl", ["bootout", `gui/${process.getuid?.() ?? 0}/${MAC_NOTIFIER_LABEL}`]);
+  } catch {
+    // Already gone, or never loaded.
+  }
+  rmSync(macNotifierPlistPath(), { force: true });
+  rmSync(macNotifierAppPath(home), { recursive: true, force: true });
+  rmSync(macNotifyDir(home), { recursive: true, force: true });
+}
+
+/**
+ * Queue one notification for the agent to deliver.
+ *
+ * Written to a sibling directory and RENAMED in, so the watcher never observes
+ * a half-written file: `WatchPaths` fires on the first byte, and a partial read
+ * would be a truncated banner that the agent then deletes.
+ *
+ * Returns whether the file landed — not whether anything was shown, which this
+ * side cannot know and does not claim.
+ */
+export function queueMacNotification(
+  id: string,
+  title: string,
+  body: string,
+  home?: string,
+): boolean {
+  // The id becomes a filename in a watched directory. Same guard, same reason
+  // as `markLeakNoticeDelivered` — see `isFindingId`.
+  if (!isFindingId(id)) return false;
+  const dir = macNotifyDir(home);
+  const tmp = resolve(dir, "..", `notify-${id}.tmp`);
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // One line each. Newlines inside either field would be read as extra body
+    // lines by the applet, so they are flattened here rather than there.
+    const payload = `${title.replace(/\s+/g, " ")}\n${body.replace(/\s+/g, " ")}\n`;
+    writeFileSync(tmp, payload, { mode: 0o600 });
+    renameSync(tmp, resolve(dir, id));
+    return true;
+  } catch {
+    // Clean up the staging file. Without this, every failed queue attempt left
+    // a `notify-*.tmp` beside the watched directory forever — invisible to the
+    // agent, which only reads inside it, and never collected by anything.
+    try {
+      rmSync(tmp, { force: true });
+    } catch { /* nothing left to do */ }
+    return false;
+  }
+}
+
+/** True when an agent is installed and could pick a queued file up. */
+export function macNotifierInstalled(home?: string): boolean {
+  return existsSync(macNotifierPlistPath()) && existsSync(macNotifierAppPath(home));
+}
+
+/**
+ * Drop anything the agent never collected.
+ *
+ * A machine that queued a banner while logged out, or with the agent removed,
+ * would otherwise show a pile of stale findings at the next login — "we found
+ * this key" for keys already rotated weeks ago.
+ */
+export function pruneMacNotifyQueue(home?: string, maxAgeMs = 7 * 86_400_000): void {
+  try {
+    const dir = macNotifyDir(home);
+    if (!existsSync(dir)) return;
+    const { statSync } = require("node:fs") as typeof import("node:fs");
+    for (const name of readdirSync(dir)) {
+      const path = resolve(dir, name);
+      try {
+        if (Date.now() - statSync(path).mtimeMs > maxAgeMs) rmSync(path, { force: true });
+      } catch {
+        // Raced with the agent collecting it. Nothing to do.
+      }
+    }
+  } catch {
+    // Housekeeping only.
+  }
+}