failproofai 1.0.1 → 1.0.2-beta.0

package/src/hooks/pack-failclosed.ts

@@ -0,0 +1,189 @@
+/**
+ * What a machine does when a pack it was told to enforce will not load.
+ *
+ * ## Why this exists at all
+ *
+ * Every content-load failure in this codebase fails OPEN, and that was sound
+ * only while the builtin policies shipped compiled in and kept enforcing
+ * underneath. Once the builtins ARE a pack, the same behaviour becomes zero
+ * enforcement at exit 0 on a machine that reports healthy — so the layer that
+ * used to be allowed to degrade quietly now has to deny.
+ *
+ * ## The line: recorded expectation, never an empty manifest
+ *
+ * A machine with no packs is a fresh machine, not a broken one. `installed.json`
+ * being ABSENT is silence; being present and unreadable is a failure. So the
+ * trigger is always "something was declared and is not running", never
+ * "nothing is running".
+ *
+ * ## Why the deny is narrow
+ *
+ * An unreachable daemon denies everything, correctly: no evaluation happened, so
+ * nothing can be known safe. An unloadable pack is different — the missing
+ * guards are ENUMERABLE, because every declared policy must carry a `match`. So
+ * the deny matches only the events and tools those policies claimed, and
+ * `getPoliciesForEvent` narrows it for free.
+ *
+ * `UserPromptSubmit` is exempt no matter what a missing policy declared, and
+ * instructs instead. handler.ts records why from a real machine: a blanket deny
+ * takes `UserPromptSubmit` with it and locks the user out of their agent
+ * entirely. The one event that can tell a human what happened is the one event
+ * that must never deny.
+ */
+import type { PackError, ResolvedPack } from "./pack-manifest";
+import type { PolicyLoadFailure } from "./custom-hooks-loader";
+import type { HookEventType } from "./types";
+import type { PolicyMatcher } from "./policy-types";
+
+/** A guard that was expected to run and did not. */
+export interface MissingGuard {
+  packId: string;
+  packVersion: string | null;
+  policies: string[];
+  match: PolicyMatcher;
+  reason: string;
+}
+
+/**
+ * Load classifications that are PERMANENT, and so may deny.
+ *
+ * `load_timeout` is deliberately absent. It is transient and load-dependent, and
+ * a machine-wide deny triggered by one slow disk moment persists until a human
+ * intervenes — in the warm worker, where every evaluation is serialized behind
+ * one queue, the denials themselves add load. Timeouts warn and are recorded.
+ */
+export const PERMANENT_LOAD_FAILURES: ReadonlySet<string> = new Set([
+  "module_not_found",
+  "syntax_error",
+  "runtime_error",
+  "path_missing",
+]);
+
+function unionMatch(matchers: PolicyMatcher[]): PolicyMatcher {
+  const events = new Set<HookEventType>();
+  const toolNames = new Set<string>();
+  let anyEvent = false;
+  let anyTool = false;
+  for (const m of matchers) {
+    if (!m.events || m.events.length === 0) anyEvent = true;
+    else for (const e of m.events) events.add(e);
+    if (!m.toolNames || m.toolNames.length === 0) anyTool = true;
+    else for (const t of m.toolNames) toolNames.add(t);
+  }
+  const scoped: PolicyMatcher = {};
+  // Every declared event is kept, INCLUDING UserPromptSubmit. This says where
+  // the missing guards applied; how to answer there is the caller's decision —
+  // and on UserPromptSubmit the answer is `instruct`, so the human is told
+  // without being locked out of the agent that could fix it. Filtering the event
+  // out here instead made that branch unreachable.
+  if (!anyEvent) scoped.events = [...events];
+  if (!anyTool) scoped.toolNames = [...toolNames];
+  return scoped;
+}
+
+/**
+ * Work out which guards a machine expected and is not running.
+ *
+ * `enabledFor` answers "did the user actually take this policy" — a pack the
+ * user took 3 of 40 from is not a failure because the other 37 did not load.
+ * `disabled` is the `disabledCustomPolicies` set, keyed `pack:<id>@<ver>:<name>`.
+ */
+export function missingGuards(input: {
+  errors: PackError[];
+  packs: ResolvedPack[];
+  /** Policy names a pack registered, keyed by pack id. */
+  registered: Map<string, Set<string>>;
+  /** Packs handed to the loader whose entry artifact failed to import. */
+  failed: Map<string, PolicyLoadFailure>;
+  disabled: ReadonlySet<string>;
+}): MissingGuard[] {
+  const out: MissingGuard[] = [];
+
+  // (a) Declared in installed.json, never resolved.
+  for (const err of input.errors) {
+    // An observe pack denying on failure would deny for something that, had it
+    // loaded, would have allowed.
+    if (err.effect === "observe") continue;
+    const declared = err.declared ?? [];
+    out.push({
+      packId: err.id ?? "(unnamed pack)",
+      packVersion: null,
+      policies: declared.map((p) => p.name),
+      // No declared policies means nothing to narrow with, so this one is
+      // unavoidably blanket — minus the never-deny events.
+      match: declared.length > 0 ? unionMatch(declared.map((p) => p.match)) : unionMatch([{}]),
+      reason: err.reason,
+    });
+  }
+
+  // (c) Resolved, but registered less than it declared.
+  for (const pack of input.packs) {
+    if (pack.effect === "observe") continue;
+    const loadFailure = input.failed.get(pack.id);
+    if (loadFailure && PERMANENT_LOAD_FAILURES.has(loadFailure.type)) {
+      const taken = pack.enabled ?? pack.policies.map((p) => p.name);
+      const unavailable = pack.policies.filter(
+        (p) =>
+          taken.includes(p.name) &&
+          !input.disabled.has(`pack:${pack.id}@${pack.version}:${p.name}`),
+      );
+      if (unavailable.length > 0) {
+        out.push({
+          packId: pack.id,
+          packVersion: pack.version,
+          policies: unavailable.map((p) => p.name),
+          match: unionMatch(unavailable.map((p) => p.match)),
+          reason: `artifact failed to load: ${loadFailure.reason}`,
+        });
+      }
+      continue;
+    }
+    const registered = input.registered.get(pack.id);
+    // A pack absent from both maps was never handed to the loader at all.
+    // Guessing failure from "no registrations" cannot distinguish that from a
+    // pause skip or a pack that legitimately registers nothing.
+    if (!registered) continue;
+
+    const taken = pack.enabled ?? pack.policies.map((p) => p.name);
+    const missing = pack.policies.filter(
+      (p) =>
+        taken.includes(p.name) &&
+        !registered.has(p.name) &&
+        !input.disabled.has(`pack:${pack.id}@${pack.version}:${p.name}`),
+    );
+    if (missing.length === 0) continue;
+    out.push({
+      packId: pack.id,
+      packVersion: pack.version,
+      policies: missing.map((p) => p.name),
+      match: unionMatch(missing.map((p) => p.match)),
+      reason: `declared ${missing.length} polic${missing.length === 1 ? "y" : "ies"} its artifact did not register`,
+    });
+  }
+
+  // A guard that ended up matching no event at all cannot say anything.
+  return out.filter((g) => !(g.match.events && g.match.events.length === 0));
+}
+
+/**
+ * The message a human reads.
+ *
+ * Recovery is a HUMAN terminal action and the text has to name the command,
+ * because the agent cannot run it: `block-failproofai-commands` denies every
+ * `failproofai` invocation from a tool call, deliberately and unconditionally.
+ */
+export function packFailureReason(guards: MissingGuard[]): string {
+  const named = guards
+    .map((g) => {
+      const where = g.packVersion ? `${g.packId}@${g.packVersion}` : g.packId;
+      const what = g.policies.length > 0 ? `: ${g.policies.slice(0, 4).join(", ")}` : "";
+      return `${where} (${g.reason})${what}`;
+    })
+    .join("; ");
+  return (
+    `Blocked because a policy pack this machine is configured to enforce is not running — ${named}. ` +
+    `Enforcement you were told you had is missing, so this is refused rather than allowed silently. ` +
+    `A human needs to run: failproofai pack list, then failproofai pack add <source> (or failproofai config). ` +
+    `The agent cannot run those itself.`
+  );
+}

package/src/hooks/pack-manifest.ts

@@ -0,0 +1,344 @@
+/**
+ * Reads the installed policy packs a machine has on disk.
+ *
+ * A pack is the delivery unit for policies that did not ship compiled into this
+ * build: `failproofai pack add` writes the artifact and records it here, and the
+ * loader imports it through the same path custom policies already use.
+ *
+ * ## Why this is not `cloud-managed-policies.ts`
+ *
+ * It is modelled on it closely — same content-addressed artifacts, same
+ * verify-immediately-before-import boundary, same shared `resolveManagedPath`.
+ * Three things differ, each for a reason:
+ *
+ * - **Failure is PER PACK, not per manifest.** The cloud reader throws on the
+ *   first bad entry, which is right for a fleet deployment: a manifest the
+ *   server sent is one unit and half of it is not a deployment. Packs come from
+ *   unrelated publishers, so one malformed third-party pack must not switch off
+ *   every other pack on the machine.
+ * - **It never throws.** A caller gets `{packs, errors}`. See the fail-open note
+ *   below — it is a load-bearing assumption, not a convenience.
+ * - **Two refusals cloud does not need**, both closing silent failures:
+ *   a pack may not claim `alwaysOn`, and a pack policy name may not contain `/`.
+ *
+ * ## Fail-open, and the condition that makes it sound
+ *
+ * An unreadable manifest, a bad digest or a corrupt artifact yields zero packs
+ * and a recorded error — it does not deny. That is only defensible **while the
+ * builtin policies still ship compiled into the package and keep enforcing
+ * underneath**. The day builtins become a fetched pack, this exact behaviour
+ * becomes "zero enforcement on a machine reporting healthy", and this comment is
+ * the reason that must be revisited rather than inherited.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { packsDir, packsInstalledFile } from "./fp-home";
+import { resolveManagedPath } from "./cloud-managed-policies";
+import type { PolicyCatalogEntry } from "./policy-types";
+import type { PolicyEffect } from "./cloud-managed-policies";
+
+/** Manifest schemas this reader accepts. */
+const ACCEPTED_PACK_SCHEMA_VERSIONS: readonly number[] = [1];
+
+const SHA256_RE = /^[a-f0-9]{64}$/;
+/** `<publisher>/<name>`, the shape a marketplace id takes. */
+export const PACK_ID_RE = /^[A-Za-z0-9._-]{1,64}\/[A-Za-z0-9._-]{1,64}$/;
+/** A version string, kept loose enough for semver and a tag. */
+export const PACK_VERSION_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/;
+/**
+ * A pack policy's own name. `/` is REFUSED, and that is the important character:
+ * `normalizePolicyName` passes any name containing one straight through, and
+ * `registerPolicy` REPLACES by canonical name — so a pack shipping a policy
+ * literally called `failproofai/block-sudo` would silently overwrite the
+ * compiled builtin with its own code. Names here are prefixed by the loader
+ * instead, which is what keeps a pack unable to reach the builtin namespace.
+ */
+const PACK_POLICY_NAME_RE = /^[A-Za-z0-9._-]{1,128}$/;
+
+export interface InstalledPackRecord {
+  id: string;
+  version: string;
+  /** Where it came from, verbatim, e.g. `github:acme/pack@v2.1.0`. */
+  source: string;
+  /** Path to the single entry artifact, relative to `packsDir()`. */
+  entry: string;
+  sha256: string;
+  effect?: string;
+  policies?: unknown;
+  /**
+   * Which of the pack's policies to register. Absent means ALL of them.
+   *
+   * Stored here rather than as `disabledCustomPolicies` entries because those
+   * are keyed by `pack:<id>@<version>:<name>` — so an upgrade to a new version
+   * stops matching and everything the user opted out of silently comes back on.
+   * A choice about what to take from a pack has to outlive the version it was
+   * made against.
+   */
+  enabled?: string[];
+}
+
+export interface ResolvedPack {
+  id: string;
+  version: string;
+  source: string;
+  /** Absolute, real, verified-to-be-inside-the-root path to the entry module. */
+  path: string;
+  sha256: string;
+  effect: PolicyEffect;
+  /** The pack's own catalog, in declared order. */
+  policies: PolicyCatalogEntry[];
+  /** Selected policy names, or null when the user took the whole pack. */
+  enabled: string[] | null;
+}
+
+export interface PackError {
+  /** The pack's id when it was readable enough to have one. */
+  id: string | null;
+  reason: string;
+  /**
+   * The effect the failed pack asked for, when it got far enough to say.
+   *
+   * Carried because an `observe` pack that fails to load must NOT make the
+   * machine deny: an observe pack evaluates and discards by construction, so
+   * denying on its behalf denies for something that would have allowed. Effect
+   * is validated BEFORE the digest check, so for every failure at or after that
+   * point it was already known — and was previously thrown away with the
+   * exception.
+   */
+  effect?: PolicyEffect;
+  /**
+   * Policy names the entry declared, when it parsed far enough to list them.
+   * Lets the deny name what is missing instead of being blanket.
+   */
+  declared?: PolicyCatalogEntry[];
+}
+
+export interface PackReadResult {
+  packs: ResolvedPack[];
+  /** Every pack that was declared and refused, and why. Never silently dropped. */
+  errors: PackError[];
+}
+
+export function packsRoot(): string {
+  return process.env.FAILPROOFAI_PACK_DIR ?? packsDir();
+}
+
+/** Validate the identity fields shared by installed and incoming manifests. */
+export function parsePackIdentity(value: {
+  id?: unknown;
+  version?: unknown;
+  effect?: unknown;
+}): { id: string; version: string; effect: PolicyEffect } {
+  if (typeof value.id !== "string" || !PACK_ID_RE.test(value.id)) {
+    throw new Error(`unsafe pack id ${JSON.stringify(value.id)}`);
+  }
+  if (typeof value.version !== "string" || !PACK_VERSION_RE.test(value.version)) {
+    throw new Error(`invalid version for pack ${value.id}`);
+  }
+  if (value.effect !== undefined && value.effect !== "enforce" && value.effect !== "observe") {
+    throw new Error(`unknown effect ${JSON.stringify(value.effect)} for pack ${value.id}`);
+  }
+  return {
+    id: value.id,
+    version: value.version,
+    effect: (value.effect as PolicyEffect | undefined) ?? "enforce",
+  };
+}
+
+/**
+ * Whether this machine has any pack installed at all.
+ *
+ * Cheap on purpose — the hook path asks this on every event to decide whether it
+ * still needs the migration shim, and reading + verifying every artifact digest
+ * to answer "is there one" would be the wrong price.
+ */
+export function hasInstalledPacks(): boolean {
+  try {
+    const raw = JSON.parse(readFileSync(installedFilePath(), "utf8")) as { packs?: unknown };
+    return Array.isArray(raw.packs) && raw.packs.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function installedFilePath(): string {
+  return process.env.FAILPROOFAI_PACK_DIR
+    ? resolve(process.env.FAILPROOFAI_PACK_DIR, "installed.json")
+    : packsInstalledFile();
+}
+
+/** Validate one serialized catalog entry carried by a pack. */
+export function parsePackPolicy(packId: string, value: unknown, index: number): PolicyCatalogEntry {
+  const where = `${packId} policy #${index}`;
+  if (!value || typeof value !== "object") throw new Error(`${where} is not an object`);
+  const raw = value as Record<string, unknown>;
+
+  const name = raw.name;
+  if (typeof name !== "string" || !PACK_POLICY_NAME_RE.test(name)) {
+    throw new Error(`${where} has an unsafe name ${JSON.stringify(name)}`);
+  }
+  if ("alwaysOn" in raw) {
+    // `alwaysOn` means "registers regardless of the enabled set, and cannot be
+    // disabled or paused". It is reserved for the guard that stops an agent
+    // switching failproofai off, which ships compiled in. A pack granting it to
+    // itself would be a downloaded file that no local command can turn off.
+    throw new Error(`${where} declares alwaysOn, which packs may not set`);
+  }
+  if (typeof raw.description !== "string" || raw.description.length === 0) {
+    throw new Error(`${where} is missing a description`);
+  }
+  if (typeof raw.category !== "string" || raw.category.length === 0) {
+    throw new Error(`${where} is missing a category`);
+  }
+  if (typeof raw.defaultEnabled !== "boolean") {
+    throw new Error(`${where} is missing defaultEnabled`);
+  }
+  if (!raw.match || typeof raw.match !== "object") {
+    throw new Error(`${where} is missing a match`);
+  }
+  return raw as unknown as PolicyCatalogEntry;
+}
+
+function parsePack(root: string, value: unknown): ResolvedPack {
+  if (!value || typeof value !== "object") throw new Error("pack entry is not an object");
+  const raw = value as InstalledPackRecord;
+
+  const identity = parsePackIdentity(raw);
+  if (typeof raw.source !== "string" || raw.source.length === 0) {
+    throw new Error(`pack ${raw.id} has no source`);
+  }
+  if (typeof raw.sha256 !== "string" || !SHA256_RE.test(raw.sha256)) {
+    throw new Error(`invalid SHA-256 for pack ${raw.id}`);
+  }
+  // Recorded before anything that can fail, so a later throw can still say what
+  // this pack was for.
+  const effect = identity.effect;
+
+  const path = resolveManagedPath(root, raw.entry);
+  const actual = createHash("sha256").update(readFileSync(path)).digest("hex");
+  if (actual !== raw.sha256) {
+    throw new Error(
+      `pack ${raw.id} failed integrity verification: expected ${raw.sha256}, got ${actual}`,
+    );
+  }
+
+  if (!Array.isArray(raw.policies)) throw new Error(`pack ${raw.id} policies is not an array`);
+  const policies = raw.policies.map((p, i) => parsePackPolicy(raw.id, p, i));
+  const names = new Set<string>();
+  for (const p of policies) {
+    if (names.has(p.name)) throw new Error(`pack ${raw.id} declares ${p.name} twice`);
+    names.add(p.name);
+  }
+
+  let enabled: string[] | null = null;
+  if (raw.enabled !== undefined) {
+    if (!Array.isArray(raw.enabled) || raw.enabled.some((n) => typeof n !== "string")) {
+      throw new Error(`pack ${raw.id} enabled is not an array of names`);
+    }
+    // A name here that the pack no longer declares is not an error — a publisher
+    // may have removed a policy between versions — but it must not silently
+    // become "select nothing", so unknown names are simply dropped.
+    enabled = raw.enabled.filter((n) => names.has(n));
+  }
+
+  return {
+    id: identity.id,
+    version: identity.version,
+    source: raw.source,
+    path,
+    sha256: raw.sha256,
+    effect,
+    policies,
+    enabled,
+  };
+}
+
+/**
+ * Read every installed pack, verifying each artifact's digest immediately before
+ * its path is handed to a caller that will import it.
+ *
+ * Never throws. A pack that fails any check is omitted and recorded in `errors`;
+ * a manifest that cannot be read at all yields no packs and one error.
+ */
+export function readInstalledPacks(): PackReadResult {
+  const manifestPath = installedFilePath();
+  if (!existsSync(manifestPath)) return { packs: [], errors: [] };
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (err) {
+    return {
+      packs: [],
+      errors: [{ id: null, reason: `unreadable pack manifest: ${errText(err)}` }],
+    };
+  }
+  if (!raw || typeof raw !== "object") {
+    return { packs: [], errors: [{ id: null, reason: "pack manifest is not an object" }] };
+  }
+  const manifest = raw as { schemaVersion?: unknown; packs?: unknown };
+  if (!ACCEPTED_PACK_SCHEMA_VERSIONS.includes(manifest.schemaVersion as number)) {
+    return {
+      packs: [],
+      errors: [
+        {
+          id: null,
+          reason:
+            `unsupported pack manifest schema ${String(manifest.schemaVersion)} ` +
+            `(supported: ${ACCEPTED_PACK_SCHEMA_VERSIONS.join(", ")})`,
+        },
+      ],
+    };
+  }
+  if (!Array.isArray(manifest.packs)) {
+    return { packs: [], errors: [{ id: null, reason: "pack manifest packs is not an array" }] };
+  }
+
+  const root = packsRoot();
+  const packs: ResolvedPack[] = [];
+  const errors: PackError[] = [];
+  const seen = new Set<string>();
+
+  for (const entry of manifest.packs) {
+    const declaredId =
+      entry && typeof entry === "object" && typeof (entry as InstalledPackRecord).id === "string"
+        ? (entry as InstalledPackRecord).id
+        : null;
+    try {
+      const pack = parsePack(root, entry);
+      if (seen.has(pack.id)) throw new Error(`duplicate pack id ${pack.id}`);
+      seen.add(pack.id);
+      packs.push(pack);
+    } catch (err) {
+      const rec = entry as InstalledPackRecord | null;
+      const declaredEffect =
+        rec && (rec.effect === "observe" || rec.effect === "enforce") ? rec.effect : "enforce";
+      errors.push({
+        id: declaredId,
+        reason: errText(err),
+        effect: declaredEffect,
+        // Best effort: an entry too malformed to list policies yields nothing
+        // here, and a deny built from it is unavoidably blanket.
+        ...(Array.isArray(rec?.policies) ? { declared: safeDeclared(rec.policies) } : {}),
+      });
+    }
+  }
+  return { packs, errors };
+}
+
+/** Policy entries that at least carry a name and a match, for narrowing a deny. */
+function safeDeclared(raw: unknown[]): PolicyCatalogEntry[] {
+  const out: PolicyCatalogEntry[] = [];
+  for (const value of raw) {
+    if (!value || typeof value !== "object") continue;
+    const p = value as Record<string, unknown>;
+    if (typeof p.name !== "string" || !p.match || typeof p.match !== "object") continue;
+    out.push(p as unknown as PolicyCatalogEntry);
+  }
+  return out;
+}
+
+function errText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}