failproofai 1.0.0 → 1.0.1-beta.0

package/src/audit/harm-report.ts

@@ -0,0 +1,260 @@
+/**
+ * Turning an audit result into a harm report the api-server can act on.
+ *
+ * Runs only after a SCHEDULED scan (`failproofai audit --scheduled`), only when
+ * the user has switched emailed reports on, and only ever from the audit child —
+ * never the daemon, which holds no human credential precisely so that refresh
+ * rotation stays inside the audit lock. See `crates/failproofaid/src/audit_lane.rs`.
+ *
+ * ## What counts as harm
+ *
+ * The policies the engine would have BLOCKED, plus the ones that caught a secret
+ * on its way into the model's context. In terms of `severityForBuiltin`, that is
+ * `deny` and `sanitize` — `block-*` and `sanitize-*` — and NOT `warn-`,
+ * `prefer-` or `require-`, which are hygiene.
+ *
+ * One name is added by hand, and it is worth explaining rather than hiding:
+ * `severityForBuiltin` derives severity from the NAME PREFIX, so
+ * `protect-env-vars` reads as `warn` despite being a policy that blocks `env` /
+ * `printenv` outright. Its whole subject is an agent reaching for the
+ * environment, which is the "read my keys" case this feature exists to report.
+ * Inheriting a scoring heuristic's blind spot into a security digest would be
+ * the wrong kind of consistency.
+ *
+ * ## The window, and the trap in `--since`
+ *
+ * `RunAuditOptions.since` filters on transcript MTIME, and that is right for
+ * what it does — it decides which files to open. It is WRONG as a window for
+ * this: a session left open for a month has a fresh mtime, so `--since 7d`
+ * hands back that whole transcript including month-old events, and the first
+ * digest would report everything the agent has ever done as though it happened
+ * this week.
+ *
+ * So the window is applied HERE, per event, against the timestamps `AuditCount`
+ * already carries — `lastSeen` to decide whether a policy fired in the window at
+ * all, and each example's own `timestamp` to decide which examples belong to it.
+ * The scan itself stays unfiltered.
+ *
+ * ## Counts are approximate; the window boundary is not
+ *
+ * `AuditCount.hits` is a total over everything scanned, and there is no
+ * per-event breakdown to subtract from it — the cache stores counts, not event
+ * lists. Rather than report a total that spans the wrong period, a policy whose
+ * activity straddles the window boundary reports the number of EXAMPLES that
+ * fall inside it, which is a real count of real events even though it is capped
+ * at three. A policy entirely inside the window reports its true total. The
+ * server's threshold reads these, so undercounting is the safe direction: it can
+ * delay a digest, never invent one.
+ */
+import type { AuditCount, AuditResult } from "./types";
+import { redactExample } from "./redact-example";
+
+/** Severities that mean "the engine would have stopped this". */
+const HARMFUL_SEVERITIES = new Set(["deny", "sanitize"]);
+
+/**
+ * Policies whose severity misreads their intent. See the module docs.
+ *
+ * Kept as an explicit list rather than by rewriting `severityForBuiltin`,
+ * because that function feeds the SCORE's gentle/medium buckets and changing it
+ * would silently move every historical score.
+ */
+const ALSO_HARMFUL = new Set(["protect-env-vars"]);
+
+/** One policy's harmful activity inside the window, as the wire expects it. */
+export interface ReportedPolicy {
+  policy: string;
+  category: string;
+  title: string;
+  hits: number;
+  first_seen?: string;
+  last_seen?: string;
+  examples: string[];
+}
+
+export interface HarmReport {
+  window_from?: string;
+  window_to: string;
+  harmful: ReportedPolicy[];
+}
+
+/** `failproofai/block-rm-rf` → `block-rm-rf`. */
+function shortName(name: string): string {
+  const slash = name.indexOf("/");
+  return slash === -1 ? name : name.slice(slash + 1);
+}
+
+export function isHarmful(count: AuditCount): boolean {
+  if (count.source !== "builtin") return false;
+  const short = shortName(count.name);
+  return HARMFUL_SEVERITIES.has(count.severity) || ALSO_HARMFUL.has(short);
+}
+
+/** Parse an ISO timestamp, or null if it is absent or unusable. */
+function ts(value: string | undefined): number | null {
+  if (!value) return null;
+  const n = Date.parse(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * Select the harmful policies whose activity falls inside `[from, to]`.
+ *
+ * `from` undefined means "everything up to `to`", which is now only reachable
+ * by an explicit caller — `buildHarmReport` always supplies a bound. See the
+ * note there for why.
+ *
+ * `includeUnplaceable` decides what happens to a policy with NO usable
+ * timestamps. It cannot be placed, and the two failure directions are not
+ * equal: on a first report, dropping it loses a real finding; on a later one,
+ * including it re-reports something already covered. Silence about something
+ * new is the worse of the two and repetition is merely annoying, so each window
+ * gets the answer that fails the way it can afford to.
+ */
+export function selectHarmful(
+  result: AuditResult,
+  from: Date | undefined,
+  to: Date,
+  opts: { includeUnplaceable?: boolean } = {},
+): ReportedPolicy[] {
+  const includeUnplaceable = opts.includeUnplaceable ?? from === undefined;
+  const fromMs = from ? from.getTime() : null;
+  const toMs = to.getTime();
+  const out: ReportedPolicy[] = [];
+
+  for (const count of result.results) {
+    if (!isHarmful(count)) continue;
+
+    const last = ts(count.lastSeen);
+    const first = ts(count.firstSeen);
+
+    // Nothing since the watermark — this policy's whole history predates the
+    // window.
+    if (fromMs !== null && last !== null && last <= fromMs) continue;
+    // Fired entirely after the window closed (a clock skew, or a scan that
+    // raced an event). It belongs to the next report, not this one.
+    if (first !== null && first > toMs) continue;
+
+    const inWindow = count.examples.filter((e) => {
+      const at = ts(e.timestamp);
+      if (at === null) return includeUnplaceable;
+      if (fromMs !== null && at <= fromMs) return false;
+      return at <= toMs;
+    });
+
+    const unplaceable = last === null && first === null;
+    if (unplaceable && !includeUnplaceable) continue;
+
+    // Wholly inside the window → the real total. Straddling EITHER edge → the
+    // examples that actually fall inside, which undercounts but never invents.
+    //
+    // Both edges, and the upper one is not symmetry for its own sake. This used
+    // to test the lower bound alone, so a policy that started inside the window
+    // and was still firing after it closed reported `count.hits` — every hit,
+    // including the ones after `to`, while its examples were filtered to the
+    // window. Those hits then fell inside the NEXT report's window too, since
+    // the watermark advances to `to`, and were counted a second time. A digest
+    // that reports tomorrow's findings today and again tomorrow is worse than
+    // one that is late.
+    //
+    // An UNPLACEABLE policy that survived the check above reports its full
+    // count: there is nothing to narrow it with, and having decided to include
+    // it, reporting zero would be a row claiming nothing happened. It is only
+    // reachable on a first report, where over-reporting is the direction that
+    // was chosen deliberately.
+    const afterLowerEdge = fromMs === null || (first !== null && first > fromMs);
+    const beforeUpperEdge = last !== null && last <= toMs;
+    const wholly = unplaceable || (afterLowerEdge && beforeUpperEdge);
+    // A straddling policy falls back to its in-window EXAMPLES, and the audit
+    // keeps at most three of them per policy, chosen in whatever order the
+    // transcripts happened to be walked. On a machine that has been running
+    // agents for months those three are routinely all old — so a policy that
+    // fired an hour ago scored zero and was dropped, and because `firstSeen`
+    // stays before the watermark forever, it was dropped from every later report
+    // too. Not a delayed digest: a feature that goes quiet on exactly the
+    // machines with the most to report.
+    //
+    // `beforeUpperEdge` having survived the `last <= fromMs` skip above means
+    // `lastSeen` itself sits inside the window, and that timestamp IS a real
+    // event. One is the floor it proves, which keeps the "never invent a hit"
+    // rule intact while making the row exist.
+    const floor = beforeUpperEdge ? 1 : 0;
+    const hits = wholly ? count.hits : Math.max(inWindow.length, floor);
+    if (hits <= 0) continue;
+
+    out.push({
+      policy: shortName(count.name),
+      category: count.category,
+      title: count.displayTitle ?? "",
+      hits,
+      first_seen: count.firstSeen,
+      last_seen: count.lastSeen,
+      examples: inWindow.map((e) => redactExample(e.example)).filter((e) => e.length > 0),
+    });
+  }
+
+  // Most active first, so a digest truncated by anything downstream keeps the
+  // rows that matter.
+  out.sort((a, b) => b.hits - a.hits);
+  return out;
+}
+
+/**
+ * Build the report body for one scan.
+ *
+ * `window_to` is the scan's own `scannedAt` rather than "now": it is the instant
+ * the evidence was gathered, and using a later clock reading would advance the
+ * watermark past events that happened while the scan was still running — events
+ * no report would ever cover.
+ *
+ * ## A first report is bounded to one interval, not to all of history
+ *
+ * With no watermark the obvious window is "everything", and that is what this
+ * did until it was run against a real machine: the first report covered 230
+ * sessions and 22,059 tool calls and came out at **5,815 findings**. Every
+ * number in it was true and the digest was still wrong — somebody's first email
+ * would describe their agent's entire recorded history as though it were this
+ * week's news, and would trip the critical bypass on day one for essentially
+ * everyone.
+ *
+ * A digest is a statement about RECENT behaviour, so the first one covers the
+ * same period every later one does: `interval_days` back from the scan. The
+ * older findings are not lost, they are simply not news — they are on the
+ * dashboard, which is where a full history belongs.
+ *
+ * `includeUnplaceable` still follows "is this the first report", not "is there a
+ * lower bound", so a policy carrying no usable timestamps is reported once on a
+ * new machine rather than silently dropped by the bound this now always sets.
+ */
+export function buildHarmReport(
+  result: AuditResult,
+  lastReportedAt: string | undefined,
+  intervalDays: number,
+): HarmReport {
+  const to = new Date(Date.parse(result.scannedAt));
+  const windowTo = Number.isFinite(to.getTime()) ? to : new Date();
+  const watermark = ts(lastReportedAt);
+  const isFirstReport = watermark === null;
+
+  const oneInterval = Math.max(1, intervalDays) * 86_400_000;
+  const fallbackFrom = windowTo.getTime() - oneInterval;
+
+  // The watermark is the SERVER's clock; `windowTo` is this machine's. A
+  // backwards jump between them — NTP correcting a fast RTC, a VM restored from
+  // a snapshot, a dual-boot machine that wrote localtime to the hardware clock
+  // — leaves `from` LATER than `to`, and `selectHarmful` then matches nothing
+  // at all. That drops every finding silently and permanently: the watermark
+  // only ever moves forward, so the window never re-opens, while the run's
+  // outcome line still reads normal. The scheduling lane already repairs this
+  // class of jump; the reporting half did not. One interval back is a digest
+  // that is narrower than it should be, rather than one that is empty forever.
+  const from = new Date(
+    isFirstReport || watermark >= windowTo.getTime() ? fallbackFrom : watermark,
+  );
+
+  return {
+    window_from: from.toISOString(),
+    window_to: windowTo.toISOString(),
+    harmful: selectHarmful(result, from, windowTo, { includeUnplaceable: isFirstReport }),
+  };
+}

package/src/audit/machine-store.ts

@@ -0,0 +1,120 @@
+/**
+ * `~/.failproofai/audit/machine.json` — this machine's report identity.
+ *
+ * Two fields, and they are together because they share one property: both must
+ * outlive a sign-out.
+ *
+ *  - `machine_id` is what the api-server keys reports on. Regenerate it and the
+ *    server sees a brand-new machine, which burns a slot off the account's cap
+ *    on every logout and splits one box's history into two.
+ *  - `last_reported_at` is how far the last digest reached. Reset it and the
+ *    next report re-covers months of history, and the user gets a digest of
+ *    everything that ever happened as though it just did.
+ *
+ * That is why this is a separate file from `session.json` rather than two more
+ * keys in it: signing out deletes the session, and neither of these may go with
+ * it. `HOME_CLASSES` classifies this `identity` — never deleted, alongside
+ * `cursors/` and the telemetry id — while the tokens beside it are `user-typed`
+ * and come and go.
+ *
+ * ## The id is minted here, not borrowed
+ *
+ * `state/telemetry-id` is already a stable per-machine random id and would have
+ * been free to reuse. It is deliberately not reused: that id is the anonymous
+ * PostHog person, and sending it alongside a verified email address would link
+ * the two the moment somebody turns emailed reports on. Opting into a digest
+ * should not de-anonymise telemetry, so this feature gets its own id and the
+ * two never meet.
+ */
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { hostname } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { writeJsonAtomically } from "../../lib/atomic-write";
+import { auditMachineFile } from "../hooks/fp-home";
+
+export interface MachineIdentity {
+  /** Random, minted on first use. Opaque to the server. */
+  machine_id: string;
+  /** ISO-8601. Absent until the first digest is delivered. */
+  last_reported_at?: string;
+  /** When this id was minted. Diagnostics only. */
+  created_at: string;
+}
+
+export function readMachineIdentity(home?: string): MachineIdentity | null {
+  const path = auditMachineFile(home);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<MachineIdentity>;
+    if (typeof parsed.machine_id !== "string" || !parsed.machine_id) return null;
+    return {
+      machine_id: parsed.machine_id,
+      last_reported_at:
+        typeof parsed.last_reported_at === "string" ? parsed.last_reported_at : undefined,
+      created_at: typeof parsed.created_at === "string" ? parsed.created_at : new Date(0).toISOString(),
+    };
+  } catch {
+    // Absent, unreadable and malformed all read as "no identity yet". The caller
+    // mints a new one, which costs a slot off the cap and a re-covered window —
+    // bad, but recoverable, and strictly better than refusing to report at all
+    // because one file got truncated.
+    return null;
+  }
+}
+
+/**
+ * Read the identity, creating it on first call.
+ *
+ * Only ever called from the reporting path, so a machine that never opts into
+ * emailed reports never gets an id at all — there is nothing to mint one for.
+ */
+export function ensureMachineIdentity(home?: string): MachineIdentity {
+  const existing = readMachineIdentity(home);
+  if (existing) return existing;
+  const fresh: MachineIdentity = {
+    machine_id: randomUUID(),
+    created_at: new Date().toISOString(),
+  };
+  writeJsonAtomically(auditMachineFile(home), fresh);
+  return fresh;
+}
+
+/**
+ * Record how far the last DELIVERED digest reached.
+ *
+ * The value is the server's `next_window_from`, not the window this run
+ * scanned. The server is authoritative because it knows which reports actually
+ * produced an email — a report held by the cooldown, or one whose send failed,
+ * must not advance the watermark or its findings are silently dropped from every
+ * future digest.
+ */
+export function recordReportWatermark(nextWindowFrom: string, home?: string): void {
+  const current = ensureMachineIdentity(home);
+  writeJsonAtomically(auditMachineFile(home), {
+    ...current,
+    last_reported_at: nextWindowFrom,
+  } satisfies MachineIdentity);
+}
+
+export function deleteMachineIdentity(home?: string): void {
+  const path = auditMachineFile(home);
+  if (existsSync(path)) rmSync(path, { force: true });
+}
+
+/**
+ * A display name for this machine — its hostname.
+ *
+ * Shown in the digest so somebody with three boxes can tell which one is
+ * misbehaving, which is the whole reason it is sent. Falls back to `undefined`
+ * rather than a placeholder: the server keeps whatever label it already has when
+ * one is omitted, so guessing here would overwrite a good name with a bad one.
+ */
+export function machineLabel(): string | undefined {
+  try {
+    const h = hostname().trim();
+    return h.length > 0 ? h : undefined;
+  } catch {
+    return undefined;
+  }
+}