failproofai 1.0.7 → 1.0.8-beta.0

package/src/hooks/fp-config.ts

@@ -22,7 +22,19 @@
  * someone opens when something is wrong. That guidance now lives in
  * `failproofai config --status` and the docs, which is a worse place for it.
  */
-import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  closeSync,
+  constants as fsConstants,
+  existsSync,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname } from "node:path";
 import { version as cliVersion } from "../../package.json";
 import {
@@ -753,6 +765,26 @@ export interface FpCredentials {
   org?: { id?: string; slug?: string; name?: string };
   ingest?: { url: string; key: string };
   auth?: { baseUrl?: string; sessionToken?: string; expiresAt?: number; email?: string };
+  /**
+   * The key Jev's FailproofAI Cloud route sends, and the Cloud ORIGIN it was
+   * verified against. Written by connect only when introspect reports
+   * `jev:evaluate`; cleared by disconnect. See {@link readJevCloudCredential}.
+   *
+   * A slot of its own, not a reuse of `[cloud]` or `[ingest]`, although it holds
+   * the same key today: those two are written under their own permission checks
+   * and can hold DIFFERENT keys (see `cloud-connection.ts`), and "which of the
+   * two backs Jev" is a question nobody reading the file should have to answer.
+   * One slot per capability keeps revoking one from ever silently re-routing
+   * another.
+   */
+  jev?: JevCloudCredential;
+}
+
+/** The `jev` slot of `credentials.json`. */
+export interface JevCloudCredential {
+  /** The Cloud origin the key was verified against, e.g. `https://app.befailproof.ai`. */
+  url: string;
+  key: string;
 }
 
 /**
@@ -775,6 +807,8 @@ const OWNED_CREDENTIAL_KEYS: readonly (readonly string[])[] = [
   ["org", "name"],
   ["ingest", "url"],
   ["ingest", "key"],
+  ["jev", "url"],
+  ["jev", "key"],
   ["auth", "base_url"],
   ["auth", "session_token"],
   ["auth", "expires_at"],
@@ -843,6 +877,8 @@ export function projectCredentials(parsed: Record<string, unknown>): FpCredentia
     if (ingest && typeof ingest.url === "string" && typeof ingest.key === "string" && ingest.url && ingest.key) {
       out.ingest = { url: ingest.url, key: ingest.key };
     }
+    const jev = projectJevSlot(parsed.jev);
+    if (jev) out.jev = jev;
     if (auth) {
       out.auth = {
         baseUrl: typeof auth.base_url === "string" ? auth.base_url : undefined,
@@ -876,6 +912,9 @@ export function writeCredentials(creds: FpCredentials, raw?: Record<string, unkn
   if (creds.ingest) {
     out.ingest = { url: creds.ingest.url, key: creds.ingest.key };
   }
+  if (creds.jev) {
+    out.jev = { url: creds.jev.url, key: creds.jev.key };
+  }
   if (creds.org && (creds.org.id || creds.org.slug || creds.org.name)) {
     out.org = {
       ...(creds.org.id ? { id: creds.org.id } : {}),
@@ -920,6 +959,232 @@ export function hasCloudCredentials(): boolean {
   return Boolean(c.cloud || c.ingest);
 }
 
+// ── The Jev slot ─────────────────────────────────────────────────────────────
+//
+// The one credential in this file that a HOOK reads. Everything else here is
+// read by the daemon or a CLI command; this is read by `inspectJevConfig` on
+// every gated tool call of a machine whose `jev.json` names the FailproofAI
+// Cloud provider — and the key it yields is what lets Jev's answers clear a
+// deny. So it is read the way `jev.json` itself is (`semantic/jev-config.ts`),
+// not the way `readCredentials` reads: a file or directory other users could
+// have written is REFUSED rather than read, because a routing credential for a
+// tier that can clear denies must not be one somebody else chose.
+//
+// And only from `credentialsFile()`, never from `FAILPROOFAI_CLOUD_CREDENTIALS`.
+// That override relocates the policy credential for the daemon and CI; honoured
+// here it would be an environment variable choosing the key Jev spends, which a
+// repository's `.claude/settings.json` can set for a session. `FAILPROOFAI_HOME`
+// is not an exception to that rule for the reason `jev-config.ts` gives: it
+// moves the whole layout, `jev.json` included.
+//
+// # A slot counts only while the connection it came with is still there
+//
+// The slot is written by `config --token` and cleared by `config --disconnect`
+// — by THIS build. An older one (1.0.7-beta.2 and before) knows nothing about
+// it: its disconnect clears `[cloud]` and `[ingest]` and carries the `jev`
+// table over as a key it does not own. So downgrade, disconnect, upgrade, and
+// a machine its owner disconnected would find a Cloud key and a Cloud
+// `jev.json` both still in place, and Jev would start spending on an org the
+// machine had left. So the slot is read as usable only when a FailproofAI Cloud
+// connection on the SAME origin — a policy (`[cloud]`) or reporting
+// (`[ingest]`) credential — is in the same file. A key carrying `jev:evaluate`
+// always carries `events:add` and `policies:pull` too (the server refuses it
+// otherwise), so a live Jev connection always has one of them.
+//
+// And that connection must hold the SAME KEY. The origin alone does not say
+// whose connection it is: on hosted FailproofAI Cloud every organisation shares
+// one origin. An older build's `config --token` with another org's key
+// rewrites `[cloud]` and `[ingest]` to that key and carries the `jev` table
+// over untouched, so the origin still matches while the machine now reports
+// into the other org — and Jev would go on spending the first org's budget.
+// This build's connect writes one key to all three (a partial connect may
+// leave one of `[cloud]`/`[ingest]` holding an earlier key, never both), so a
+// live slot always has a same-origin credential holding its key.
+//
+// Only from this file, for the reason above: under `FAILPROOFAI_CLOUD_CREDENTIALS`
+// the policy credential lives elsewhere, and an environment variable must not
+// be able to re-arm a slot either. The reporting credential is always here,
+// and connecting a Jev key writes it.
+
+/** Same bound `jev.json` gets; no legitimate `credentials.json` is near it. */
+const MAX_CREDENTIALS_BYTES = 64 * 1024;
+/**
+ * Non-blocking, so a FIFO in the file's place cannot hang a hook in `open()`.
+ * A function, not a module-level constant: this module is imported everywhere,
+ * and reading `fs.constants` at import time would make every importer depend on
+ * it — including test doubles of `node:fs` that never needed it before.
+ */
+const credentialsOpenFlags = (): number => fsConstants.O_RDONLY | (fsConstants.O_NONBLOCK ?? 0);
+/** Group- or world-WRITE bits on the directory: whoever has them can replace the file. */
+const DIR_WRITABLE_BY_OTHERS = 0o022;
+
+export type JevCloudCredentialRead =
+  | { status: "ok"; path: string; credential: JevCloudCredential }
+  /**
+   * No usable Jev credential: no file, no `jev` slot, or a slot no live
+   * connection backs (see "A slot counts only while…" above).
+   */
+  | {
+      status: "absent";
+      path: string;
+      /**
+       * This machine IS connected to FailproofAI Cloud — a policy or reporting
+       * credential is stored — just not with a Jev key. Tells "connected, but
+       * the key does not carry Jev" apart from "not connected at all".
+       */
+      connected: boolean;
+      /** A `jev` slot is there, but no connection on its origin holding its key is: it is ignored. */
+      orphaned?: true;
+    }
+  | {
+      status: "refused";
+      path: string;
+      /** The file's permission bits, when they are the reason. */
+      mode: number | null;
+      reason: "too-open" | "unreadable" | "too-large" | "not-json";
+      problem: string;
+      /** The command that fixes it, when one does. */
+      fix?: string;
+    };
+
+/** A `jev` table with two non-empty strings, or null. Shape only; `jev-config.ts` validates the values. */
+function projectJevSlot(raw: unknown): JevCloudCredential | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const { url, key } = raw as Record<string, unknown>;
+  return typeof url === "string" && url && typeof key === "string" && key ? { url, key } : null;
+}
+
+/**
+ * The `jev` slot, read owner-only.
+ *
+ * The file is opened once and every check runs against that descriptor, so the
+ * permissions checked are the permissions of the bytes read — the same shape
+ * as `inspectJevConfig`, for the same reason. Never throws.
+ */
+export function readJevCloudCredential(): JevCloudCredentialRead {
+  const path = credentialsFile();
+  let fd: number;
+  try {
+    fd = openSync(path, credentialsOpenFlags());
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") return { status: "absent", path, connected: false };
+    return { status: "refused", path, mode: null, reason: "unreadable", problem: `cannot open ${path} (${code ?? "error"})` };
+  }
+  let text: string;
+  try {
+    const st = fstatSync(fd);
+    if (!st.isFile()) return { status: "refused", path, mode: null, reason: "unreadable", problem: `${path} is not a regular file` };
+    // On Windows `mode` is synthesized and would refuse every file while
+    // protecting nothing; Jev setup is refused there anyway.
+    const meaningful = process.platform !== "win32";
+    const mode = st.mode & 0o777;
+    if (meaningful && (mode & 0o077) !== 0) {
+      return {
+        status: "refused",
+        path,
+        mode,
+        reason: "too-open",
+        problem:
+          `${path} is ${mode.toString(8).padStart(4, "0")}; it holds the key Jev sends to FailproofAI Cloud, ` +
+          `so it must be owner-only (chmod 600 ${path})`,
+        fix: `chmod 600 ${path}`,
+      };
+    }
+    if (meaningful) {
+      let dirMode: number | null = null;
+      try {
+        const m = statSync(dirname(path)).mode & 0o777;
+        if ((m & DIR_WRITABLE_BY_OTHERS) !== 0) dirMode = m;
+      } catch {
+        // No permission to stat it: the read below reports what it can.
+      }
+      if (dirMode !== null) {
+        return {
+          status: "refused",
+          path,
+          mode,
+          reason: "too-open",
+          problem:
+            `its directory ${dirname(path)} is ${dirMode.toString(8).padStart(4, "0")} — other users can write there, ` +
+            `so they can put their own credentials in its place; it must be owner-only (chmod 700 ${dirname(path)})`,
+          fix: `chmod 700 ${dirname(path)}`,
+        };
+      }
+    }
+    if (st.size > MAX_CREDENTIALS_BYTES) {
+      return { status: "refused", path, mode, reason: "too-large", problem: `${path} is larger than ${MAX_CREDENTIALS_BYTES} bytes` };
+    }
+    const buf = Buffer.alloc(st.size);
+    let off = 0;
+    while (off < buf.length) {
+      const n = readSync(fd, buf, off, buf.length - off, off);
+      if (n === 0) break;
+      off += n;
+    }
+    text = buf.subarray(0, off).toString("utf8");
+  } catch (err) {
+    return { status: "refused", path, mode: null, reason: "unreadable", problem: `cannot read ${path} (${(err as NodeJS.ErrnoException).code ?? "error"})` };
+  } finally {
+    try {
+      closeSync(fd);
+    } catch {
+      // Nothing useful to do.
+    }
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { status: "refused", path, mode: null, reason: "not-json", problem: `${path} is not valid JSON` };
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { status: "refused", path, mode: null, reason: "not-json", problem: `${path} does not hold a JSON object` };
+  }
+  const fields = parsed as Record<string, unknown>;
+  // The same projection `readCredentials` uses, so "a cloud block without a
+  // token is not a cloud block" means the same thing here as everywhere else.
+  const others = projectCredentials(fields);
+  const connections = [
+    others.cloud ? { origin: originOrNull(others.cloud.url), key: others.cloud.token } : null,
+    others.ingest ? { origin: originOrNull(others.ingest.url), key: others.ingest.key } : null,
+  ].filter((c): c is { origin: string; key: string } => c !== null && c.origin !== null);
+  const connected = connections.length > 0;
+  const credential = projectJevSlot(fields.jev);
+  if (!credential) return { status: "absent", path, connected };
+  const slotOrigin = originOrNull(credential.url);
+  // The same origin AND the same key: see "A slot counts only while…" above.
+  const backed = slotOrigin !== null && connections.some((c) => c.origin === slotOrigin && c.key === credential.key);
+  if (!backed) return { status: "absent", path, connected, orphaned: true };
+  return { status: "ok", path, credential };
+}
+
+/** A URL's origin, or null for a missing or unparseable one. */
+function originOrNull(url: string | undefined): string | null {
+  if (!url) return null;
+  try {
+    const origin = new URL(url).origin;
+    return origin === "null" ? null : origin;
+  } catch {
+    return null;
+  }
+}
+
+/** Store the `jev` slot (0600, owner-only home), keeping every other credential. */
+export function writeJevCloudCredential(credential: JevCloudCredential): string {
+  writeCredentials({ ...readCredentials(), jev: { url: credential.url, key: credential.key } });
+  return credentialsFile();
+}
+
+/** Remove the `jev` slot. True if there was one. Every other credential stays. */
+export function clearJevCloudCredential(): boolean {
+  const current = readCredentials();
+  if (!current.jev) return false;
+  const { jev: _dropped, ...rest } = current;
+  writeCredentials(rest);
+  return true;
+}
+
 function writeFileAt(path: string, contents: string): void {
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, contents, "utf8");

package/src/hooks/fp-home.ts

@@ -51,6 +51,7 @@
  *   VERSION                  layout / cli / daemon versions
  *   config.json       0644   non-secret: mode, daemon, collector prefs
  *   credentials.json  0600   every token
+ *   jev.json          0600   the customer's own Jev endpoint + key (BYOK opt-in)
  *   policies-config.json     the builtin enable/disable set + params
  *   bin/                     downloaded daemon binaries, one per version
  *   policies/                every policy: the user's *.mjs sit directly here
@@ -148,6 +149,14 @@ export const configFile = (home?: string) => atHome(home, "config.json");
  */
 export const credentialsFile = (home?: string) => atHome(home, "credentials.json");
 
+/**
+ * The customer's own Jev endpoint and key (BYOK), owner-only. Its presence is
+ * the whole opt-in to the two-tier evaluator: absent, hooks run the regex
+ * engine exactly as before. GLOBAL only — a repository can never set it. See
+ * `src/hooks/semantic/jev-config.ts`.
+ */
+export const jevConfigFile = (home?: string) => atHome(home, "jev.json");
+
 // ── Daemon binaries ──────────────────────────────────────────────────────────
 
 export const binDir = (home?: string) => atHome(home, "bin");
@@ -389,6 +398,12 @@ export const failedDir = (home?: string) => resolve(stateDir(home), "failed");
 export const collectorHealthFile = (home?: string) => resolve(stateDir(home), "collector-health.json");
 /** Per-session enforcement pauses, keyed by a hash of the session id. */
 export const sessionPauseDir = () => resolve(stateDir(), "sessions");
+/**
+ * The semantic (Jev) evaluator's local state: `sessions/<id>.json` holds the
+ * human prompts recorded at `UserPromptSubmit`, and `verdicts.jsonl` one row
+ * per semantic evaluation. Written only when a Jev config (BYOK) is present.
+ */
+export const semanticDir = () => resolve(stateDir(), "semantic");
 /**
  * When the scheduled audit last ran, and when the next one is due.
  *
@@ -554,6 +569,9 @@ export const HOME_CLASSES: readonly { path: (home?: string) => string; class: Da
   // policy silently — it keeps enforcing whatever it last had, reports healthy,
   // and never reconciles again. Nothing re-derives a token.
   { path: credentialsFile, class: "user-typed" },
+  // The Jev BYOK config. A person typed the key; nothing regenerates it, and
+  // losing it silently turns the two-tier evaluator off.
+  { path: jevConfigFile, class: "user-typed" },
   // Holds `daemon.configured` (the flag that makes the machine fail closed),
   // the collector preferences, `[audit] auto`, the telemetry opt-out, and
   // `collector.sources.*.extra_paths` — the entire output of `harness add-path`.
@@ -642,6 +660,11 @@ export const HOME_CLASSES: readonly { path: (home?: string) => string; class: Da
   { path: codexSessionPathsFile, class: "derived" },
   { path: shimsDir, class: "derived" },
   { path: sessionPauseDir, class: "derived" },
+  // Recorded prompts (a six-hour window that only ever lets Jev clear a
+  // reviewable policy) and a local diagnostic log of semantic verdicts that is
+  // never shipped. Losing either costs a clear and some history, never
+  // enforcement.
+  { path: semanticDir, class: "derived" },
   { path: logsDir, class: "derived" },
   { path: lastVersionFile, class: "derived" },
   { path: launcherMarker, class: "derived" },

package/src/hooks/fp-reset.ts

@@ -97,6 +97,7 @@ import {
   daemonVersionSkew,
   isDaemonSupportedPlatform,
   probeDaemonEndToEnd,
+  type DaemonServiceStatus,
 } from "./daemon-service";
 
 export interface ResetOutcome {
@@ -1094,7 +1095,24 @@ async function drainSpoolAfterMigrating(): Promise<number> {
   }
 }
 
-export async function checkLayoutForCli(): Promise<LayoutCheck> {
+/**
+ * Injectable for tests, matching `refreshDaemonToCliVersion`'s shape in
+ * `daemon-service.ts`.
+ *
+ * `healDaemonFlag` asks systemd whether the unit is installed, and on a machine
+ * with no unit that call blocks for seconds before answering. Two tests here
+ * set `daemon.configured` and so reach it, and they were timing out at vitest's
+ * 5 s default against the real service manager — a check about what this command
+ * PRINTS, failing on how long the host takes to say "not-installed". A
+ * `vi.spyOn` cannot intercept it either: this module calls its own local
+ * binding, so without a seam a stub is ignored and the test passes or fails for
+ * the wrong reason.
+ */
+export interface LayoutCheckDeps {
+  daemonStatus?: () => DaemonServiceStatus;
+}
+
+export async function checkLayoutForCli(deps: LayoutCheckDeps = {}): Promise<LayoutCheck> {
   const state = detectLayout();
 
   if (state.kind === "future") {
@@ -1220,7 +1238,7 @@ export async function checkLayoutForCli(): Promise<LayoutCheck> {
     state,
     fatal: false,
     didReset: false,
-    lines: [...(await healDaemonFlag()), ...staleDaemonHint()],
+    lines: [...(await healDaemonFlag(deps)), ...staleDaemonHint()],
   };
 }
 
@@ -1239,13 +1257,13 @@ export async function checkLayoutForCli(): Promise<LayoutCheck> {
  * downgrade a healthy machine to the in-process path — trading a loud, correct
  * failure for a quiet, wrong one.
  */
-async function healDaemonFlag(): Promise<string[]> {
+async function healDaemonFlag(deps: LayoutCheckDeps = {}): Promise<string[]> {
   try {
     const cfg = readConfig();
     if (!cfg.daemon.configured) return [];
     if (!isDaemonSupportedPlatform()) return [];
 
-    const status = daemonServiceStatus();
+    const status = (deps.daemonStatus ?? daemonServiceStatus)();
     if (status === "not-installed") {
       updateConfig({ daemon: { configured: false } });
       return [