failproofai 1.0.7-beta.2 → 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-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 [

package/src/hooks/handler.ts

@@ -38,7 +38,13 @@ import type { JevActivityFields } from "./semantic/combine";
 import type { JevConfig } from "./semantic/jev-config";
 import { clearPolicies, registerPolicy, getPoliciesForEvent } from "./policy-registry";
 import { loadAllCustomHooks } from "./custom-hooks-loader";
-import { authorityDeclarationFor, resolvePolicyAuthority, warnAuthority } from "./policy-authority";
+import { contestedReviewerNames, effectiveReviewerNames } from "./effective-reviewers";
+import {
+  authorityDeclarationFor,
+  refusedAuthorityWarning,
+  resolvePolicyAuthority,
+  warnAuthority,
+} from "./policy-authority";
 import type { CustomHook } from "./policy-types";
 import { persistHookActivity } from "./hook-activity-store";
 import { deliveryHealth, deliveryHealthLine } from "./delivery-health";
@@ -277,7 +283,10 @@ async function readJevConfig(): Promise<{ config: JevConfig; defaultMode: TwoTie
     if (!existsSync(jevConfigFile())) return null;
     const { loadJevConfig, DEFAULT_JEV_MODE } = await import("./semantic/jev-config");
     const config = loadJevConfig();
-    return config ? { config, defaultMode: DEFAULT_JEV_MODE } : null;
+    // `loadJevConfig` never returns a switched-off config; this says so again at
+    // the one place it matters, because an `off` that got through would fall to
+    // the default mode below — which is `enforce`.
+    return config && config.mode !== "off" ? { config, defaultMode: DEFAULT_JEV_MODE } : null;
   } catch (err) {
     hookLogInfo(
       `Jev config could not be read (${err instanceof Error ? err.message : String(err)}); the regex engine decides alone`,
@@ -534,7 +543,7 @@ export async function evaluateHookEvent(
     } else {
       // Load enabled policies (merge across project/local/global scopes)
       config = readMergedHooksConfig(session.cwd);
-      clearPolicies();
+      clearPolicies(cli);
 
       // A session pause suspends LOCAL policy only, for a bounded time. Cloud
       // assignments are exempt below for the same reason `disabledCustomPolicies`
@@ -791,8 +800,13 @@ export async function evaluateHookEvent(
         // aloud when a `reviewable` claim is refused and Jev is configured, so
         // an author is not left wondering why Jev never clears it.
         const authority = authorityDeclarationFor(hook, { cloudManaged, pack });
-        const refused = resolvePolicyAuthority(authority).downgraded;
-        if (refused) warnAuthority(`${registeredName} asks to be reviewable, but ${refused} — it stays hard`);
+        // Against the same set `registerPolicy` judges it by, or this warning
+        // describes a different machine than the registry does: a pack that
+        // ships its own semantic checks registers reviewable and was told, on
+        // every one of those policies, that it stays hard. `effectiveReviewerNames`
+        // is cached for the registration pass, so this costs nothing extra.
+        const refused = resolvePolicyAuthority(authority, effectiveReviewerNames(), contestedReviewerNames()).downgraded;
+        if (refused) warnAuthority(refusedAuthorityWarning(registeredName, refused));
         registerPolicy(
           registeredName,
           hook.description ?? "",
@@ -914,6 +928,21 @@ export async function evaluateHookEvent(
           releaseRegistry: opts?.releaseRegistry,
         })
       : await evaluatePolicies(canonicalEventType, parsed, session, config);
+    // Shadow mode: what Jev WOULD have done, filed where observe-mode policies
+    // file theirs, so the "would have" view counts it with no second channel.
+    // `semantic/<check>` cannot be mistaken for a cloud policy — cloud ids
+    // carry no `/` (`POLICY_ID_RE` in cloud-managed-policies.ts) — and the
+    // version is a Jev model id or `jev`, never a deployment number. Only on
+    // the two-tier path, so an unconfigured row is untouched.
+    const shadowVerdict = result.twoTier?.shadowVerdict;
+    if (shadowVerdict) {
+      observedResults.push({
+        policyId: shadowVerdict.policyName,
+        version: shadowVerdict.version,
+        decision: shadowVerdict.decision,
+        reason: shadowVerdict.reason,
+      });
+    }
     const durationMs = Math.round(performance.now() - startTime);
     hookLogInfo(`result=${result.decision} policy=${result.policyName ?? "none"} duration=${durationMs}ms`);
 
@@ -928,6 +957,11 @@ export async function evaluateHookEvent(
       matchedBeforeRelease ??
       getPoliciesForEvent(canonicalEventType, parsed.tool_name as string | undefined).map((p) => p.name);
 
+    // The pack a deciding Jev check came from, recorded as a pack's regex
+    // verdict records its own. The evaluator already resolved it, so the hook
+    // path never loads the Jev resolver (pack-semantic-import-boundary).
+    const jevOrigin = result.policyName && result.twoTier?.decidedByJev ? result.twoTier.jevOrigin : undefined;
+
     // Persist activity to disk (visible in /policies activity tab)
     const activityEntry = {
       timestamp: Date.now(),
@@ -950,8 +984,11 @@ export async function evaluateHookEvent(
       // Attribution. A builtin is anything registered that is not in the map,
       // so its absence is meaningful rather than missing — but only when a
       // policy actually decided; a plain allow names nobody. When Jev's own
-      // verdict decided, no registered policy did: `evaluator` + `jevDecision`
-      // say so, and claiming "builtin" here would be false.
+      // verdict decided, no registered policy did, and claiming "builtin" here
+      // would be false — so it is attributed to Jev itself. Leaving it out
+      // instead filed every Jev block under "unattributed" on FailproofAI
+      // Cloud's policy page, beside rows written before attribution existed.
+      ...(result.policyName && result.twoTier?.decidedByJev ? { policySource: "jev" as const, ...jevOrigin } : {}),
       ...(result.policyName && !result.twoTier?.decidedByJev
         ? (() => {
             const attribution = policyAttribution.get(result.policyName);

package/src/hooks/hook-activity-store.ts

@@ -126,15 +126,19 @@ export interface HookActivityEntry {
    * Where the policy that DECIDED came from. Absent when nothing decided (a
    * plain allow) and on rows written before this existed — so, like
    * `matchedPolicies`, `undefined` means "unknown", not "builtin".
+   *
+   * `jev`: no registered policy decided — Jev's own verdict did (enforce mode;
+   * `policyName` is then `semantic/<check>`). Rows written before this value
+   * existed leave it out on such calls.
    */
-  policySource?: "builtin" | "custom" | "convention" | "cloud" | "pack";
+  policySource?: "builtin" | "custom" | "convention" | "cloud" | "pack" | "jev";
   /** Cloud policy id of the decider. Present only when `policySource` is "cloud". */
   cloudPolicyId?: string;
   /** Immutable version of that policy — the half of attribution that identifies WHICH version ran. */
   cloudVersion?: number;
   /**
-   * Pack id and version of the decider. Present only when `policySource` is
-   * "pack", and here for the same reason the cloud pair is: the display name
+   * Pack id and version of the decider. Present when `policySource` is "pack",
+   * or "jev" when the deciding check came from a pack; and here for the same reason the cloud pair is: the display name
    * encodes both ("pack/acme/finance@1.2.0/…") but only as a string, so without
    * these the question "which pack, which version decided this" could only be
    * answered by re-parsing our own label.
@@ -154,10 +158,14 @@ export interface HookActivityEntry {
    * record is the entire point of observe mode: without it the row is
    * indistinguishable from one where the policy never matched, and the rollout
    * being trialled is unmeasurable.
+   *
+   * Jev in shadow mode files its own deny/instruct here too, as
+   * `{policyId: "semantic/<check>", version: <Jev model id or "jev">}`: the
+   * same question — what would this have done — for the same reader.
    */
   observed?: Array<{
     policyId: string;
-    /** A cloud deployment number, or a pack's version string. */
+    /** A cloud deployment number, a pack's version string, or a Jev model id (`jev` when unknown). */
     version: string | number;
     decision: "deny" | "instruct";
     reason: string | null;
@@ -175,7 +183,7 @@ export interface HookActivityFilters {
    * organization's policies decided" is the question cloud rollout reporting
    * is built on, and it is unanswerable without this.
    */
-  source?: "builtin" | "custom" | "convention" | "cloud" | "pack";
+  source?: "builtin" | "custom" | "convention" | "cloud" | "pack" | "jev";
 }
 
 export interface HookActivityStats {