failproofai 1.0.11 → 1.0.12-beta.1

package/src/hooks/cloud-managed-policies.ts

@@ -5,9 +5,10 @@
  * before import so the worker never knowingly executes modified bytes.
  */
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
-import { cloudPoliciesDir } from "./fp-home";
+import { cloudPoliciesDir, configFile } from "./fp-home";
+import { agentTargetsMatch, parseAgentTargets, type AgentIdentity, type AgentTarget } from "./agent-targets";
 import { authorityFieldsOf } from "./policy-authority";
 import type { PolicyAuthority } from "./policy-types";
 
@@ -22,10 +23,10 @@ import type { PolicyAuthority } from "./policy-types";
  * enforced while every other signal says the machine is healthy. Reproduced
  * exactly that way while syncing this with AgentEye#559.
  *
- * 1 is accepted for files a pre-rename beta daemon left behind; 2 is what is
- * written now.
+ * 1 is accepted for files a pre-rename beta daemon left behind; 2 is
+ * unscoped and 3 is targeted. An old hook must reject 3.
  */
-const ACCEPTED_ACTIVE_SCHEMA_VERSIONS: readonly number[] = [1, 2];
+const ACCEPTED_ACTIVE_SCHEMA_VERSIONS: readonly number[] = [1, 2, 3];
 const SHA256_RE = /^[a-f0-9]{64}$/;
 const POLICY_ID_RE = /^[A-Za-z0-9._-]{1,128}$/;
 
@@ -59,6 +60,7 @@ export interface CloudManagedPolicyArtifact {
   authority?: PolicyAuthority;
   /** The semantic policies that must all be asked and none answer `deny`; see `authority`. */
   reviewedBy?: string[];
+  agentTargets?: AgentTarget[];
 }
 
 interface ActiveManifest {
@@ -72,6 +74,7 @@ interface ActiveManifest {
     path: string;
     authority?: unknown;
     reviewedBy?: unknown;
+    agentTargets?: unknown;
   }>;
 }
 
@@ -82,6 +85,24 @@ export function cloudManagedPolicyRoot(): string {
   );
 }
 
+/**
+ * An explicit disconnect vetoes an old deployment even when an operator's
+ * overridden policy directory is shared and therefore cannot be cleaned up.
+ * Missing or unreadable config does not veto older enrolled machines; this
+ * mirrors the daemon's `disconnected_by_config` rule.
+ */
+function disconnectedByConfig(): boolean {
+  try {
+    const raw: unknown = JSON.parse(readFileSync(configFile(), "utf8"));
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return false;
+    const mode = (raw as { mode?: unknown }).mode;
+    return !!mode && typeof mode === "object" && !Array.isArray(mode) &&
+      (mode as { kind?: unknown }).kind === "oss";
+  } catch {
+    return false;
+  }
+}
+
 /**
  * A version-1 manifest, in the spelling a pre-rename daemon actually wrote.
  *
@@ -148,11 +169,18 @@ export function resolveManagedPath(root: string, candidate: string): string {
 /**
  * Stop enforcing cloud-managed policies on this machine.
  *
- * Removes `active.json` and the cached `desired-state.json`: a stopped daemon
- * must not rebuild a deployment after the machine disconnects. The deployment
- * directories and content-addressed artifacts are left
- * alone: they are large, hash-verified on use, and inert once nothing points
- * at them, so keeping them makes a reconnect cheap and offline-safe.
+ * Removes `desired-state.json` FIRST, then `active.json` — the manifest that
+ * says which deployment is live — both error reports and the Jev budget record.
+ * The content-addressed artifacts are left alone: they are large, hash-verified
+ * on use, and inert once nothing points at them, so keeping them makes a
+ * reconnect cheap.
+ *
+ * The snapshot has to go, and before the pointer. It is what the daemon's
+ * maintenance lane rebuilds a lost `active.json` from, and it used to be left
+ * behind: within one interval of `--disconnect` the old org's JS policies and
+ * Jev mode were back, on a machine whose owner had left (the daemon
+ * also refuses to rebuild on a machine that is not enrolled now, so neither
+ * half alone decides it).
  *
  * Called by `--disconnect`, which without it did not disconnect. Clearing the
  * credential stops the daemon REFRESHING policy; every artifact already on disk
@@ -164,36 +192,365 @@ export function resolveManagedPath(root: string, candidate: string): string {
  * Returns true when a manifest was actually removed.
  */
 export function clearActiveCloudManagedPolicies(): boolean {
+  // An override can point to a shared directory with unrelated files named
+  // active.json or errors.json. Never delete from a path the CLI does not own.
+  // `mode: oss` independently stops the hook from reading retained artifacts.
+  if (process.env.FAILPROOFAI_CLOUD_POLICY_DIR !== undefined) return false;
+  const root = cloudManagedPolicyRoot();
+  // The snapshot first, so nothing can rebuild the pointer from it in between.
+  // The error reports go too: they describe a deployment this machine no
+  // longer has, and a reconnect (possibly to another organisation) must not
+  // open by reporting the old one's problems. The Cloud Jev mode lives IN
+  // active.json, so removing it clears that too.
+  // Either manifest counts as a removed deployment: a stopped daemon would
+  // rebuild `active.json` from the snapshot alone.
   let removed = false;
-  for (const name of ["active.json", "desired-state.json"]) {
-    const path = resolve(cloudManagedPolicyRoot(), name);
+  for (const name of [DESIRED_STATE_FILE, CLOUD_POLICY_ERRORS_FILE, DAEMON_POLICY_ERRORS_FILE, JEV_BUDGET_FILE, "load-checked.json", "active.json"]) {
+    const path = resolve(root, name);
     if (!existsSync(path)) continue;
     try {
       rmSync(path, { force: true });
-      removed = true;
+      if (name === DESIRED_STATE_FILE || name === "active.json") removed = true;
     } catch {
-      // Try both independently: a failure removing one must not leave the
-      // other referenced merely because it came later in the list.
+      // Best-effort and independent: a failure removing one file must not leave
+      // the others in place. `--disconnect` still clears the credentials, and
+      // reporting one failed removal would obscure that the rest succeeded.
     }
   }
+  // The org's policy source goes too (B15): the content-addressed artifacts
+  // are the departed organisation's code, and nothing on a disconnected
+  // machine may use them; a reconnect downloads what its deployment names.
+  // Only here, in the directory the CLI owns (an override returned above).
+  try {
+    rmSync(resolve(root, "artifacts"), { recursive: true, force: true });
+  } catch {
+    // Best-effort, like the files above.
+  }
   return removed;
 }
 
-export function readActiveCloudManagedPolicies(): CloudManagedPolicyArtifact[] {
+/** The daemon's snapshot of the last desired state (`PolicyStore::desired_state_path`). */
+export const DESIRED_STATE_FILE = "desired-state.json";
+/** The CLI's error report, beside `active.json`. See `cloud-policy-errors.ts`. */
+export const CLOUD_POLICY_ERRORS_FILE = "errors.json";
+/** The daemon's own reconcile error state (`PolicyStore::daemon_errors_path`). */
+export const DAEMON_POLICY_ERRORS_FILE = "daemon-errors.json";
+/**
+ * Installed packs' Jev checks FailproofAI Cloud dropped from a request for the
+ * question budget, kept for the deployment they happened under so the report
+ * does not flap with each tool call's selection. See `cloud-policy-errors.ts`.
+ */
+export const JEV_BUDGET_FILE = "jev-budget.json";
+
+// ── FailproofAI Cloud Jev (CONTRACT C10) ─────────────────────────────────────
+//
+// Jev policies, and the Jev half of `both` policies, live ONLY on FailproofAI
+// Cloud: nothing but the MODE reaches this machine. `active.json` carries
+// `jevMode` (`off | observe | enforce`, or absent), and a `both` policy's JS
+// half carries `authority: "reviewable"` with `reviewedBy` = the names of its
+// own Cloud checks. With `observe`/`enforce` the hook path sends every gated
+// tool call to FailproofAI Cloud, which asks the checks deployed to this
+// machine and returns their verdict (`semantic/cloud-jev.ts`).
+
+/** The Jev modes Cloud may set. `local` never reaches a machine (stored NULL). */
+export type CloudJevMode = "off" | "observe" | "enforce";
+
+/** What `errors.json` reports, one entry per problem (CONTRACT C4/C6). */
+export type CloudPolicyErrorKind = "regex" | "jev" | "both" | "daemon";
+export interface CloudPolicyError {
+  id: string;
+  version: number | null;
+  kind: CloudPolicyErrorKind;
+  message: string;
+}
+
+/** What this machine knows about FailproofAI Cloud's Jev: the mode, and nothing else. */
+export interface CloudJevState {
+  /** Cloud's Jev mode, or null when Cloud does not set one (or there is no deployment). */
+  jevMode: CloudJevMode | null;
+  /** The deployment `active.json` names, or null without one. */
+  deployment: number | null;
+  /** A `jevMode` this build cannot read, reported rather than guessed at. */
+  errors: CloudPolicyError[];
+}
+
+const noCloudJev = (): CloudJevState => ({ jevMode: null, deployment: null, errors: [] });
+
+function parseCloudJevMode(raw: unknown): CloudJevMode | null {
+  return raw === "off" || raw === "observe" || raw === "enforce" ? raw : null;
+}
+
+/** Whether Cloud's mode sends this machine's gated tool calls to FailproofAI Cloud Jev. */
+export function cloudJevAsks(mode: CloudJevMode | null): mode is "observe" | "enforce" {
+  return mode === "observe" || mode === "enforce";
+}
+
+// ── Read once per change ─────────────────────────────────────────────────────
+//
+// The hook path asks about this deployment several times per event — the JS
+// reader, the reviewer set, the Jev mode — and the warm worker does that on
+// every tool call of every session. So `active.json` is parsed once per CHANGE
+// of the file, keyed on its identity and version: device, inode, mode, size,
+// and modification and change times to the nanosecond.
+//
+// Sound for this file in particular. The daemon writes it by rename, so a new
+// deployment is a new inode, and an edit in place moves the change time, which
+// nothing short of the system clock can set back.
+
+/** A file's identity and version, or null when it does not exist. Throws on anything else. */
+function fileVersion(path: string): string | null {
+  try {
+    const s = statSync(path, { bigint: true });
+    return `${s.dev}:${s.ino}:${s.mode}:${s.size}:${s.mtimeNs}:${s.ctimeNs}`;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") return null;
+    throw err;
+  }
+}
+
+let activeJsonCache: { path: string; version: string; value: unknown } | null = null;
+
+/**
+ * `active.json` parsed, once per change of the file — or `undefined` when
+ * there is none (a file holding `null` is a bad manifest, not an absent one).
+ * Throws on a file that cannot be read or is not JSON (not cached: the next
+ * call tries again). Callers must not mutate what it returns.
+ */
+function readActiveJson(): unknown {
+  if (disconnectedByConfig()) {
+    activeJsonCache = null;
+    return undefined;
+  }
+  const path = resolve(cloudManagedPolicyRoot(), "active.json");
+  const version = fileVersion(path);
+  if (version === null) {
+    activeJsonCache = null;
+    return undefined;
+  }
+  if (activeJsonCache && activeJsonCache.path === path && activeJsonCache.version === version) return activeJsonCache.value;
+  const value: unknown = JSON.parse(readFileSync(path, "utf8"));
+  activeJsonCache = { path, version, value };
+  return value;
+}
+
+/** Forget every cached read. Tests only: a test that rewrites a file in place can beat the clock's granularity. */
+export function _resetCloudManagedCachesForTest(): void {
+  activeJsonCache = null;
+}
+
+/** `active.json` as untyped JSON, schema-checked, or null when there is none. Throws on a bad one. */
+function readActiveRaw(): Record<string, unknown> | null {
+  const raw = readActiveJson();
+  if (raw === undefined) return null;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("active manifest is not an object");
+  const record = raw as Record<string, unknown>;
+  if (!ACCEPTED_ACTIVE_SCHEMA_VERSIONS.includes(record.schemaVersion as number)) {
+    throw new Error(`unsupported active manifest schema ${String(record.schemaVersion)}`);
+  }
+  return record;
+}
+
+/** Schema 3 means at least one machine assignment is targeted, including a
+ * Jev-only one whose JS policies array is empty. Never reads any artifact. */
+export function readCloudAgentScopeRequired(): boolean {
+  try {
+    return readActiveRaw()?.schemaVersion === 3;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Cloud's Jev mode from `active.json`, or null — no deployment, no mode, or a
+ * file that cannot be read (which is then simply not a mode: the local
+ * `jev.json` decides, as it does on a machine Cloud never touched). Cheap and
+ * never throws: the hook path asks on every gate event.
+ */
+export function readCloudJevMode(): CloudJevMode | null {
+  try {
+    return parseCloudJevMode(readActiveRaw()?.jevMode);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The Cloud Jev state `active.json` carries: the mode, the deployment it came
+ * with, and a report of a mode this build cannot read. Never throws; an
+ * unreadable manifest is reported by the JS reader (and the handler files it),
+ * so it is not reported twice here.
+ */
+export function readCloudJevState(): CloudJevState {
+  let active: Record<string, unknown> | null;
+  try {
+    active = readActiveRaw();
+  } catch {
+    return noCloudJev();
+  }
+  if (!active) return noCloudJev();
+  const rawMode = active.jevMode;
+  const jevMode = parseCloudJevMode(rawMode);
+  const errors: CloudPolicyError[] = [];
+  if (rawMode !== undefined && rawMode !== null && jevMode === null) {
+    // The daemon refuses such a state, so this is a hand-edited or foreign file.
+    errors.push({ id: "jevMode", version: null, kind: "daemon", message: `unknown Jev mode ${JSON.stringify(rawMode)} ignored` });
+  }
+  const deployment = Number.isSafeInteger(active.deployment) ? (active.deployment as number) : null;
+  return { jevMode, deployment, errors };
+}
+
+// ── `both` policies: reviewed by their OWN Cloud checks ─────────────────────
+
+/**
+ * The reviewer name a FailproofAI Cloud policy's `reviewedBy` entry stands for
+ * on this machine: `cloud:<policyId>/<name>`. Pack check names cannot contain
+ * `:` or `/`, so this can never be a pack's check — and the Cloud review files
+ * a Cloud check's outcome under the same key (`toReview`, `jev-review.ts`),
+ * built from the outcome's own `origin.cloudPolicyId`. So a `both` policy's
+ * verdict can be cleared by exactly that policy's Cloud checks and nothing
+ * else: never by an installed pack's check of the same name (CONTRACT C10.5,
+ * C9.4), never by another Cloud policy's.
+ */
+export function cloudReviewerName(policyId: string, name: string): string {
+  return `cloud:${policyId}/${name}`;
+}
+
+/** The authority fields of one Cloud JS assignment, as `active.json` carries them. */
+export interface CloudAuthorityInput {
+  id: string;
+  effect?: PolicyEffect;
+  authority?: PolicyAuthority;
+  reviewedBy?: string[];
+  agentTargets?: AgentTarget[];
+}
+
+/** A name {@link cloudReviewerName} already made (a Jev check name can contain neither `:` nor `/`). */
+const CLOUD_REVIEWER_RE = /^cloud:[^/]+\/./;
+
+/**
+ * The authority a Cloud JS policy registers with on this machine:
+ *
+ * - declared `hard` (or nothing): as declared;
+ * - an `observe` assignment: `hard`, silently. FailproofAI Cloud does not ask
+ *   an observe `both` policy's Jev half (C9.3), and an observe policy blocks
+ *   nothing anyway;
+ * - Cloud's Jev mode is not `observe`/`enforce`: `hard`, silently. Nothing on
+ *   this machine can ask a Cloud check, and that is the org's own choice, so
+ *   it is not a warning;
+ * - otherwise `reviewable`, by its `reviewedBy` names as {@link cloudReviewerName}s
+ *   (a name already translated is kept, so applying this twice is harmless).
+ *
+ * Pure. The handler applies it to every assignment BEFORE the loader merges
+ * two assignments that share one artifact — so each name keeps the policy it
+ * came from — and the reviewer set (`effective-reviewers.ts`) and the
+ * reviewability survey use it too, so none of them can disagree.
+ */
+export function cloudAuthorityDeclaration(
+  policy: CloudAuthorityInput,
+  mode: CloudJevMode | null,
+): { authority?: PolicyAuthority; reviewedBy?: string[] } {
+  if (policy.authority !== "reviewable") return policy.authority ? { authority: policy.authority } : {};
+  if (policy.effect === "observe" || !cloudJevAsks(mode)) return { authority: "hard" };
+  return {
+    authority: "reviewable",
+    reviewedBy: (policy.reviewedBy ?? []).map((n) => (CLOUD_REVIEWER_RE.test(n) ? n : cloudReviewerName(policy.id, n))),
+  };
+}
+
+/**
+ * A Cloud JS assignment as this machine registers it: its `authority` and
+ * `reviewedBy` replaced by {@link cloudAuthorityDeclaration}'s. Pure.
+ */
+export function withCloudAuthority<T extends CloudAuthorityInput>(policy: T, mode: CloudJevMode | null): T {
+  const { authority: _authority, reviewedBy: _reviewedBy, ...rest } = policy;
+  void _authority;
+  void _reviewedBy;
+  return { ...rest, ...cloudAuthorityDeclaration(policy, mode) } as T;
+}
+
+/**
+ * Every reviewer name the deployment's `both` policies may be cleared by on
+ * this machine — empty unless Cloud's Jev mode asks. Pure.
+ */
+export function cloudReviewerNames(policies: ReadonlyArray<CloudAuthorityInput>, mode: CloudJevMode | null): string[] {
+  const out: string[] = [];
+  for (const policy of policies) {
+    const declared = cloudAuthorityDeclaration(policy, mode);
+    if (declared.authority === "reviewable") out.push(...(declared.reviewedBy ?? []));
+  }
+  return out;
+}
+
+/**
+ * The Cloud JS assignments' authority fields, read off the cached `active.json`
+ * parse — no artifact is read or hashed, so this is cheap enough for the
+ * reviewer set, which is rebuilt on every event. Never throws: an unreadable
+ * manifest has no assignments here (the JS reader reports it).
+ */
+export function readCloudAuthorityInputs(agent: AgentIdentity | null = null): CloudAuthorityInput[] {
+  try {
+    const raw = readActiveJson();
+    if (raw === undefined) return [];
+    const manifest = parseManifest(raw);
+    return manifest.policies.flatMap((policy) => {
+      if (typeof policy.id !== "string") return [];
+      const targets = parseAgentTargets(policy.agentTargets, manifest.schemaVersion);
+      if (!agentTargetsMatch(targets, agent)) return [];
+      return [{
+        id: policy.id,
+        effect: policy.effect === "observe" ? "observe" : "enforce",
+        ...(targets ? { agentTargets: targets } : {}),
+        ...authorityFieldsOf(policy as unknown as Record<string, unknown>),
+      } satisfies CloudAuthorityInput];
+    });
+  } catch {
+    // A malformed selector invalidates the entire active manifest for the JS
+    // loader too. Do not keep reviewers from a partial set of that manifest:
+    // Cloud's JS has not loaded, and a subset would claim otherwise.
+    return [];
+  }
+}
+
+/**
+ * Every Cloud JS assignment in the deployment, whatever agent it targets — for
+ * LISTING only (`failproofai policies`), never for import: the hook path scopes
+ * with {@link readActiveCloudManagedPolicies} before any artifact is read.
+ * A listing that applied a hook's scope with no agent hid every agent-scoped
+ * policy (B4). Each artifact is still digest-checked, so a row is never shown
+ * for bytes that would be refused.
+ */
+export function listActiveCloudManagedPolicies(): CloudManagedPolicyArtifact[] {
+  return readActiveCloudManagedPoliciesFor(() => true);
+}
+
+export function readActiveCloudManagedPolicies(agent: AgentIdentity | null = null): CloudManagedPolicyArtifact[] {
+  return readActiveCloudManagedPoliciesFor((targets) => agentTargetsMatch(targets, agent));
+}
+
+function readActiveCloudManagedPoliciesFor(
+  applies: (targets: ReturnType<typeof parseAgentTargets>) => boolean,
+): CloudManagedPolicyArtifact[] {
   const root = cloudManagedPolicyRoot();
-  const activePath = resolve(root, "active.json");
-  if (!existsSync(activePath)) return [];
 
+  // Parsed once per change of the file (`readActiveJson`). Each JS artifact is
+  // still read and hashed HERE, on every call: the loader imports what this
+  // returns, and the digest check is kept immediately before that import.
   let raw: unknown;
   try {
-    raw = JSON.parse(readFileSync(activePath, "utf8"));
+    raw = readActiveJson();
   } catch (err) {
     throw new Error(`failed to read cloud-managed active manifest: ${err instanceof Error ? err.message : String(err)}`);
   }
+  if (raw === undefined) return [];
   const manifest = parseManifest(raw);
+  // Scope before reading or importing any artifact: a foreign agent must not
+  // execute policy code even to discover that it does not apply.
+  const applicable = manifest.policies.filter((policy) =>
+    applies(parseAgentTargets(policy.agentTargets, manifest.schemaVersion)));
   const seen = new Set<string>();
 
-  return manifest.policies.map((policy) => {
+  return applicable.map((policy) => {
     if (!POLICY_ID_RE.test(policy.id) || policy.id === "." || policy.id === "..") {
       throw new Error(`unsafe cloud-managed policy id ${JSON.stringify(policy.id)}`);
     }
@@ -227,6 +584,9 @@ export function readActiveCloudManagedPolicies(): CloudManagedPolicyArtifact[] {
       sha256: policy.sha256,
       path,
       deployment: manifest.deployment,
+      ...(parseAgentTargets(policy.agentTargets, manifest.schemaVersion)
+        ? { agentTargets: parseAgentTargets(policy.agentTargets, manifest.schemaVersion) }
+        : {}),
       // Unlike `effect`, a malformed authority is dropped rather than refused:
       // dropping it makes this policy `hard`, the default that keeps enforcing,
       // while refusing would take the whole deployment down over an optional