failproofai 1.0.2-beta.7 → 1.0.2-beta.9

package/src/hooks/pack-failclosed.ts

@@ -59,16 +59,40 @@ export const PERMANENT_LOAD_FAILURES: ReadonlySet<string> = new Set([
   "path_missing",
 ]);
 
+/**
+ * A declared list, or null when it cannot be read as one.
+ *
+ * Null means UNKNOWN, and unknown has to widen the deny rather than narrow it —
+ * this whole function exists to say where a missing guard applied, and a
+ * narrowing derived from metadata nobody can parse says nothing true.
+ *
+ * A malformed list is not hypothetical: `match` was validated only as
+ * `typeof === "object"`, so a manifest declaring `events: "PreToolUse"` reached
+ * here as a STRING, was iterated character by character, and narrowed the
+ * fail-closed deny to `["P","r","e","T","o","l","U","s"]` — a set matching no
+ * event that exists. The pack failed to load, the guard fired on nothing, and
+ * the machine went on running unguarded with a deny it never used. `events: 5`
+ * was worse still: `for (const e of 5)` throws, on the hook path.
+ */
+function declaredList(value: unknown): string[] | null {
+  if (value === undefined || value === null) return null;
+  if (!Array.isArray(value)) return null;
+  if (value.some((entry) => typeof entry !== "string" || entry.length === 0)) return null;
+  return value as string[];
+}
+
 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 declaredEvents = declaredList(m?.events);
+    const declaredTools = declaredList(m?.toolNames);
+    if (!declaredEvents || declaredEvents.length === 0) anyEvent = true;
+    else for (const e of declaredEvents) events.add(e as HookEventType);
+    if (!declaredTools || declaredTools.length === 0) anyTool = true;
+    else for (const t of declaredTools) toolNames.add(t);
   }
   const scoped: PolicyMatcher = {};
   // Every declared event is kept, INCLUDING UserPromptSubmit. This says where
@@ -88,6 +112,26 @@ function unionMatch(matchers: PolicyMatcher[]): PolicyMatcher {
  * 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>`.
  */
+/**
+ * True when a pack scoped to specific agents does not cover the one running.
+ *
+ * The registration path already skips a pack whose `clis` excludes this agent;
+ * the fail-closed path did not, so a pack scoped to `codex` that failed to load
+ * denied on `claude` too — locking an agent out over enforcement it was never
+ * configured to have, until a human repaired a pack it does not use. `null` or
+ * absent means every agent, as it does everywhere else.
+ */
+function outOfScope(clis: string[] | null | undefined, cli: string | undefined): boolean {
+  if (!cli) return false;
+  // `Array.isArray`, not truthiness. A `clis` of `"codex"` is a truthy value
+  // with a `length` and an `includes`, so a string scope silently narrowed this
+  // to nothing and skipped the guard for every agent — a check meant to stop
+  // over-denying turning into the thing that under-denies. Unreadable scope
+  // means every agent, exactly as an unreadable `match` means every event.
+  if (!Array.isArray(clis) || clis.length === 0) return false;
+  return !clis.every((c) => typeof c === "string") ? false : !clis.includes(cli);
+}
+
 export function missingGuards(input: {
   errors: PackError[];
   packs: ResolvedPack[];
@@ -96,6 +140,8 @@ export function missingGuards(input: {
   /** Packs handed to the loader whose entry artifact failed to import. */
   failed: Map<string, PolicyLoadFailure>;
   disabled: ReadonlySet<string>;
+  /** The agent this evaluation is for, so a pack scoped away from it stays quiet. */
+  cli?: string;
 }): MissingGuard[] {
   const out: MissingGuard[] = [];
 
@@ -104,6 +150,7 @@ export function missingGuards(input: {
     // An observe pack denying on failure would deny for something that, had it
     // loaded, would have allowed.
     if (err.effect === "observe") continue;
+    if (outOfScope(err.clis, input.cli)) continue;
     const declared = err.declared ?? [];
     out.push({
       packId: err.id ?? "(unnamed pack)",
@@ -119,6 +166,7 @@ export function missingGuards(input: {
   // (c) Resolved, but registered less than it declared.
   for (const pack of input.packs) {
     if (pack.effect === "observe") continue;
+    if (outOfScope(pack.clis, input.cli)) 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);
@@ -172,6 +220,54 @@ export function missingGuards(input: {
  * because the agent cannot run it: `block-failproofai-commands` denies every
  * `failproofai` invocation from a tool call, deliberately and unconditionally.
  */
+/**
+ * One matcher covering every missing guard, for the single policy that stands
+ * in for all of them.
+ *
+ * Narrow only where EVERY guard is narrow: a guard that declared no events
+ * applied everywhere, so a union that dropped it would deny less than the packs
+ * did. Both axes by the same rule — `toolNames` used to be left out of the
+ * combined object entirely, which reads as "every tool", so two failed packs
+ * each scoped to Bash denied Write and Read as well. One failed pack narrowed
+ * correctly and two widened to everything, which is the wrong way round:
+ * combining two limited scopes cannot produce a larger one.
+ */
+/**
+ * True when at least one guard actually applied to this event and tool.
+ *
+ * `combinedGuardMatch` unions the two axes independently, and the registry ANDs
+ * them — so guards scoped to (PreToolUse, Bash) and (PostToolUse, Write) produce
+ * a matcher that also catches (PreToolUse, Write) and (PostToolUse, Bash), pairs
+ * neither pack ever asked to guard. The union cannot be tightened without
+ * losing dispatch: the matcher has to be a SUPERSET or the policy is never
+ * reached. So the matcher stays wide enough to be called, and the pairing is
+ * checked here, where the real event and tool are known.
+ */
+export function guardsCover(
+  guards: MissingGuard[],
+  eventType: string,
+  toolName: string | undefined,
+): boolean {
+  return guards.some((g) => {
+    const events = g.match.events;
+    if (events && events.length > 0 && !events.includes(eventType as (typeof events)[number])) {
+      return false;
+    }
+    const tools = g.match.toolNames;
+    if (tools && tools.length > 0 && (!toolName || !tools.includes(toolName))) return false;
+    return true;
+  });
+}
+
+export function combinedGuardMatch(guards: MissingGuard[]): PolicyMatcher {
+  if (guards.length === 1) return guards[0].match;
+  const axis = <K extends "events" | "toolNames">(key: K): PolicyMatcher[K] | undefined =>
+    guards.every((g) => g.match[key]?.length)
+      ? ([...new Set(guards.flatMap((g) => g.match[key] ?? []))] as PolicyMatcher[K])
+      : undefined;
+  return { events: axis("events"), toolNames: axis("toolNames") };
+}
+
 export function packFailureReason(guards: MissingGuard[]): string {
   const named = guards
     .map((g) => {

package/src/hooks/pack-manifest.ts

@@ -54,6 +54,24 @@ const SHA256_RE = /^[a-f0-9]{64}$/;
 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}$/;
+/**
+ * The git commit a pack was built from — PROVENANCE, and deliberately not the
+ * same thing as `sha256`.
+ *
+ * `sha256` is the digest of the entry artifact: the security pin, re-verified
+ * before every import, and the reason a pack cannot change under a machine
+ * after it was installed. This answers a different question — WHICH SOURCE
+ * produced that artifact — which no digest can, because the digest is of the
+ * bundled output and the output names no input.
+ *
+ * Always optional. A pack published from a directory that is not a git checkout
+ * has no commit, and that is a supported way to publish, so every surface that
+ * reads this must render its absence rather than treat it as a defect.
+ *
+ * Abbreviated forms are accepted from 7 characters, which is what `git log`
+ * prints and therefore what somebody copying one will have.
+ */
+export const PACK_COMMIT_RE = /^[0-9a-f]{7,40}$/;
 /**
  * A pack policy's own name. `/` is REFUSED, and that is the important character:
  * `normalizePolicyName` passes any name containing one straight through, and
@@ -72,6 +90,8 @@ export interface InstalledPackRecord {
   /** Path to the single entry artifact, relative to `packsDir()`. */
   entry: string;
   sha256: string;
+  /** The git commit this pack was built from, when its publisher had one. */
+  commit?: string;
   effect?: string;
   policies?: unknown;
   /**
@@ -106,6 +126,8 @@ export interface ResolvedPack {
   /** Absolute, real, verified-to-be-inside-the-root path to the entry module. */
   path: string;
   sha256: string;
+  /** The git commit this pack was built from, when its publisher had one. */
+  commit?: string;
   effect: PolicyEffect;
   /** The pack's own catalog, in declared order. */
   policies: PolicyCatalogEntry[];
@@ -135,6 +157,14 @@ export interface PackError {
    * Lets the deny name what is missing instead of being blanket.
    */
   declared?: PolicyCatalogEntry[];
+  /**
+   * The agents this pack was scoped to, when the manifest got far enough to say.
+   *
+   * Carried for the same reason `effect` is. A pack scoped to one CLI that fails
+   * to load must not deny on the others: they were never guarded by it, so a
+   * deny on their behalf locks an agent out over enforcement it never had.
+   */
+  clis?: string[] | null;
 }
 
 export interface PackReadResult {
@@ -152,7 +182,8 @@ export function parsePackIdentity(value: {
   id?: unknown;
   version?: unknown;
   effect?: unknown;
-}): { id: string; version: string; effect: PolicyEffect } {
+  commit?: unknown;
+}): { id: string; version: string; effect: PolicyEffect; commit?: string } {
   if (typeof value.id !== "string" || !PACK_ID_RE.test(value.id)) {
     throw new Error(`unsafe pack id ${JSON.stringify(value.id)}`);
   }
@@ -162,10 +193,20 @@ export function parsePackIdentity(value: {
   if (value.effect !== undefined && value.effect !== "enforce" && value.effect !== "observe") {
     throw new Error(`unknown effect ${JSON.stringify(value.effect)} for pack ${value.id}`);
   }
+  // Malformed provenance is DROPPED, never fatal. It is a label on the artifact,
+  // not part of what makes it safe to run — so a publisher who wrote something
+  // odd here gets a pack that installs and simply says nothing about its
+  // origin, rather than a pack nobody can install. The digest still decides
+  // whether the bytes are the ones that were published.
+  const commit =
+    typeof value.commit === "string" && PACK_COMMIT_RE.test(value.commit.trim().toLowerCase())
+      ? value.commit.trim().toLowerCase()
+      : undefined;
   return {
     id: value.id,
     version: value.version,
     effect: (value.effect as PolicyEffect | undefined) ?? "enforce",
+    ...(commit ? { commit } : {}),
   };
 }
 
@@ -220,6 +261,19 @@ export function parsePackPolicy(packId: string, value: unknown, index: number):
   if (!raw.match || typeof raw.match !== "object") {
     throw new Error(`${where} is missing a match`);
   }
+  // The SHAPE, not just the presence. `match` was accepted as any object, so a
+  // manifest declaring `events: "PreToolUse"` installed cleanly and then
+  // narrowed the fail-closed deny to the letters of that string — a guard
+  // matching no event that exists. Refused at install now, where the publisher
+  // can still fix it, rather than surviving as metadata nothing can read.
+  const matchShape = raw.match as { events?: unknown; toolNames?: unknown };
+  for (const key of ["events", "toolNames"] as const) {
+    const value = matchShape[key];
+    if (value === undefined) continue;
+    if (!Array.isArray(value) || value.some((e) => typeof e !== "string" || e.length === 0)) {
+      throw new Error(`${where} has a match.${key} that is not a list of names`);
+    }
+  }
   return raw as unknown as PolicyCatalogEntry;
 }
 
@@ -357,6 +411,14 @@ export function readInstalledPacks(): PackReadResult {
         // 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) } : {}),
+        // A list of names, or nothing. Anything else is unreadable scope, and
+        // unreadable scope has to mean "every agent" — the same reasoning that
+        // widens an unreadable `match`: a narrowing nobody can parse says
+        // nothing true, and here the narrowing would be the thing that lets an
+        // unguarded agent through.
+        ...(Array.isArray(rec?.clis) && rec.clis.every((c) => typeof c === "string")
+          ? { clis: rec.clis }
+          : {}),
       });
     }
   }

package/src/hooks/pack-param-key.ts

@@ -0,0 +1,36 @@
+/**
+ * The config key a pack policy's parameters are stored under.
+ *
+ * A LEAF module on purpose: no imports at all, so it can be reached from the
+ * browser. `packPolicyParamKey` used to live in `policy-evaluator.ts`, which
+ * the dashboard's client component then imported — dragging `pack-store` and
+ * its `node:fs` into the browser bundle and failing the Next build with
+ * `Module not found: Can't resolve 'fs/promises'`. The key is pure string
+ * formatting and belongs where both sides can have it.
+ *
+ * VERSION-LESS, and that is the whole design. A pack policy registers as
+ * `pack/<id>@<version>/<name>`, so a key carrying the version would be orphaned
+ * by the publisher's next release — a parameter somebody set would silently
+ * revert to its default on upgrade, which is the same failure `enabled` avoids
+ * by outliving the version it was chosen against.
+ */
+export function packPolicyParamKey(packId: string, policyName: string): string {
+  return `pack/${packId}/${policyName}`;
+}
+
+/** `pack/<id>@<version>/<name>` split back into the parts a key is built from,
+ *  or null when the name is not a pack policy's. */
+export function parsePackPolicyName(
+  canonicalName: string,
+): { packId: string; name: string } | null {
+  if (!canonicalName.startsWith("pack/")) return null;
+  const rest = canonicalName.slice("pack/".length);
+  const slash = rest.lastIndexOf("/");
+  if (slash <= 0) return null;
+  const idWithVersion = rest.slice(0, slash);
+  const at = idWithVersion.lastIndexOf("@");
+  return {
+    packId: at > 0 ? idWithVersion.slice(0, at) : idWithVersion,
+    name: rest.slice(slash + 1),
+  };
+}