@shomra/agent 0.3.9 → 0.3.10

package/guard-ledger.mjs

@@ -0,0 +1,239 @@
+/**
+ * ─── THE FAIL-OPEN LEDGER (client half) ─────────────────────────────────────
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────
+ *
+ * The pre-tool-call guard FAILS OPEN, and it has to: an agent that hard-stops
+ * because a SaaS backend is unreachable is an agent nobody keeps installed. The
+ * breaker in `shomra.mjs` makes that cheap — once the backend times out, the
+ * next calls skip the round-trip entirely for a cooldown window.
+ *
+ * ⚠ THE CONSEQUENCE IS THAT AN OUTAGE IS INVISIBLE ON THE SERVER. Every runtime
+ * claim Shomra makes counts rows the backend WROTE, so a breaker-open window
+ * produces no rows at all — byte-for-byte what a quiet, clean window produces.
+ * "The guard was down for six hours" and "the guard saw nothing dangerous" are
+ * the same evidence, and a reader takes the reassuring one.
+ *
+ * This module is the other end of `src/gate/enforcement-availability.ts` in the
+ * backend. It remembers what this machine did while it was blind, and hands it
+ * over on the next call that gets through — turning an absence of evidence into
+ * evidence of an absence.
+ *
+ * ── ⚠ THE RULES ─────────────────────────────────────────────────────────────
+ *
+ * 1. **The envelope is sent ALWAYS, even empty.** Its PRESENCE is what tells the
+ *    backend this client is CAPABLE of reporting an outage. An old client sends
+ *    nothing, and nothing is also what a healthy client would send if this were
+ *    "optimised" to omit the empty case — at which point every healthy estate
+ *    becomes indistinguishable from an unobservable one. That change would look
+ *    like a bandwidth win in review. It is the whole feature.
+ *
+ * 2. **Only calls that WOULD have been screened are counted.** A call the guard
+ *    deliberately never escalates (benign, locally cleared, not policy-relevant
+ *    — the bulk of them) is a stated design boundary, not a gap. Counting those
+ *    would report every healthy machine as ~90% blind and the number would be
+ *    ignored within a week.
+ *
+ * 3. **Counts are LOWER BOUNDS and are allowed to be.** Hooks run as concurrent
+ *    short-lived processes, so two of them can read-modify-write this file at
+ *    once and lose an increment. The backend already treats every count here as
+ *    a floor for exactly this reason. ⚠ Do not "fix" that by making the writes
+ *    heavier — a lock on the firewall's hot path costs more than the precision
+ *    is worth, and the number is a floor either way.
+ *
+ * 4. **A window we cannot attest the END of closes as `null`, never as now().**
+ *    If this machine slept, crashed, or was rebooted mid-outage, the window on
+ *    disk is stale and we genuinely do not know when it ended. `closedAt: null`
+ *    is the backend's "we were never told it ended" — which it grades as
+ *    unmeasurable rather than as a zero-length blip.
+ *
+ * 5. **Nothing is ever DROPPED to stay under the cap.** Over the limit, the
+ *    oldest windows MERGE into one aggregate that keeps their summed counts and
+ *    spans their range. Truncating the list instead would silently delete
+ *    evidence of blindness, which is the one direction this file must never
+ *    fail in.
+ *
+ * PURE state machine + thin file I/O, split so the state rules are testable
+ * without a filesystem (`tests/guard-ledger.test.mjs`).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Max gaps in one envelope. Matches `@ArrayMaxSize(50)` on the backend DTO. */
+export const MAX_GAPS = 50;
+
+/**
+ * How long an open window may sit on disk before we stop claiming to know when
+ * it ended. Six hours: comfortably longer than any real outage a 30s breaker
+ * cooldown produces, and short enough that a laptop closed overnight does not
+ * come back claiming a 14-hour measured blackout.
+ */
+export const STALE_WINDOW_MS = 6 * 60 * 60 * 1000;
+
+/** The empty ledger. */
+export const emptyLedger = () => ({ open: null, pending: [] });
+
+/* ── The state machine (pure) ───────────────────────────────────────────── */
+
+/**
+ * Begin a window, or leave an already-open one alone.
+ *
+ * ⚠ IDEMPOTENT ON PURPOSE. The breaker trips on every failed call, not just the
+ * first, so a naive implementation would start a fresh window per call and
+ * report a 200-call outage as 200 one-call outages — each with a tiny count,
+ * none of them showing the real shape. The FIRST failure owns the window.
+ */
+export function openWindow(state, { at, reason }) {
+  const s = state ?? emptyLedger();
+  if (s.open) return s;
+  return { ...s, open: { openedAt: at, reason: String(reason || 'unknown').slice(0, 200), unscreened: 0, local: 0 } };
+}
+
+/**
+ * Record one call that ran without a server verdict.
+ *
+ * `kind` is `'local'` when the on-machine Tier-0 engine screened it (a weaker
+ * screen — no org policy, no identity, no flow, no supply chain, no intent) and
+ * `'unscreened'` when nothing did.
+ *
+ * ⚠ IT OPENS A WINDOW IF NONE IS OPEN. A count with nowhere to live would be
+ * dropped, and the paths that skip the round-trip (`breakerOpen()`) do not
+ * themselves fail, so they never call `openWindow` on their own.
+ */
+export function countCall(state, { at, kind, reason }) {
+  const s = openWindow(state, { at, reason: reason || 'breaker-open' });
+  const open = { ...s.open };
+  if (kind === 'unscreened') open.unscreened += 1;
+  else open.local += 1;
+  return { ...s, open };
+}
+
+/**
+ * End the open window and move it to the outbox.
+ *
+ * ⚠ A window that recorded NOTHING is discarded rather than reported. A breaker
+ * that tripped on a call and healed before the next one cost no coverage, and a
+ * zero-call gap row would be noise that makes the real ones harder to see.
+ */
+export function closeWindow(state, { at, staleMs = STALE_WINDOW_MS } = {}) {
+  const s = state ?? emptyLedger();
+  if (!s.open) return s;
+  const { openedAt, reason, unscreened, local } = s.open;
+  if (!unscreened && !local) return { ...s, open: null };
+  // Rule 4: too old to attest an end for.
+  const stale = at - openedAt > staleMs;
+  const gap = {
+    opened_at: new Date(openedAt).toISOString(),
+    ...(stale ? {} : { closed_at: new Date(at).toISOString() }),
+    unscreened_calls: unscreened,
+    locally_decided_calls: local,
+    reason: stale ? `${reason} (end not observed)` : reason,
+  };
+  return { open: null, pending: compact([...s.pending, gap]) };
+}
+
+/**
+ * Rule 5 — keep the list bounded WITHOUT losing counts.
+ *
+ * ⚠ The merged row deliberately carries `closed_at` only when every window it
+ * absorbed had one. An aggregate spanning a window we could not attest the end
+ * of is itself unattestable, and inventing a boundary for it would launder an
+ * unmeasurable outage into a measured one.
+ */
+export function compact(gaps, max = MAX_GAPS) {
+  if (gaps.length <= max) return gaps;
+  const overflow = gaps.slice(0, gaps.length - max + 1);
+  const kept = gaps.slice(gaps.length - max + 1);
+  const anyOpen = overflow.some((g) => !g.closed_at);
+  const lastClose = overflow.reduce((acc, g) => (g.closed_at && (!acc || g.closed_at > acc) ? g.closed_at : acc), null);
+  const merged = {
+    opened_at: overflow[0].opened_at,
+    ...(anyOpen || !lastClose ? {} : { closed_at: lastClose }),
+    unscreened_calls: overflow.reduce((n, g) => n + (g.unscreened_calls || 0), 0),
+    locally_decided_calls: overflow.reduce((n, g) => n + (g.locally_decided_calls || 0), 0),
+    reason: `${overflow.length} earlier windows, merged`,
+  };
+  return [merged, ...kept];
+}
+
+/**
+ * The envelope to attach to a request.
+ *
+ * ⚠ ALWAYS AN OBJECT, and `gaps` is always an array — see rule 1. Returning
+ * `undefined` when there is nothing to report is the single change that would
+ * silently break the whole design.
+ */
+export function envelope(state, { version } = {}) {
+  const s = state ?? emptyLedger();
+  return { gaps: s.pending.slice(0, MAX_GAPS), ...(version ? { client_version: String(version).slice(0, 40) } : {}) };
+}
+
+/**
+ * Drop the gaps a request confirmed delivery of.
+ *
+ * ⚠ Matched by `opened_at`, not by index or by count. A concurrent hook process
+ * can append a new gap between building the envelope and acking it, and an
+ * index-based drop would silently discard that one unreported. Re-sending a gap
+ * the backend already has is free — it dedupes on (org, machine, openedAt).
+ */
+export function ack(state, sent) {
+  const s = state ?? emptyLedger();
+  const done = new Set((sent ?? []).map((g) => g.opened_at));
+  return { ...s, pending: s.pending.filter((g) => !done.has(g.opened_at)) };
+}
+
+/* ── File I/O (thin) ────────────────────────────────────────────────────── */
+
+/**
+ * ⚠ EVERY OPERATION BELOW IS BEST-EFFORT AND SWALLOWS. This runs inside the
+ * PreToolUse hook: a ledger that threw would break a tool call the guard had
+ * already correctly allowed, which is a worse outcome than losing a count. The
+ * counts are lower bounds by rule 3 regardless.
+ */
+export function makeLedgerStore(configDir, { version } = {}) {
+  const file = path.join(configDir, 'guard-ledger.json');
+
+  const read = () => {
+    try {
+      const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+      return { open: raw.open ?? null, pending: Array.isArray(raw.pending) ? raw.pending : [] };
+    } catch {
+      return emptyLedger();
+    }
+  };
+
+  const write = (state) => {
+    try {
+      fs.mkdirSync(configDir, { recursive: true });
+      // ⚠ Atomic rename, not a bare write. Two hook processes writing this file
+      // concurrently can lose an increment (rule 3, accepted) — but a torn file
+      // would lose the WHOLE ledger, including windows already closed and
+      // waiting to be reported. `.tmp` is per-process so the two cannot collide.
+      const tmp = `${file}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(state));
+      fs.renameSync(tmp, file);
+    } catch {
+      /* best-effort */
+    }
+  };
+
+  const update = (fn) => {
+    const next = fn(read());
+    write(next);
+    return next;
+  };
+
+  return {
+    file,
+    read,
+    write,
+    /** A call ran with no server verdict. */
+    count: (kind, reason) => update((s) => countCall(s, { at: Date.now(), kind, reason })),
+    /** The backend answered — close any window and hand back what to send. */
+    close: () => update((s) => closeWindow(s, { at: Date.now() })),
+    /** The envelope for this request. Always present (rule 1). */
+    envelope: () => envelope(read(), { version }),
+    /** Confirm delivery. */
+    ack: (sent) => update((s) => ack(s, sent)),
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shomra/agent",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "Shomra — adversarial assurance for AI agents, as a local-first CLI. Blocks dangerous tool-calls before they run, attacks your own guardrails to prove they hold, and gates AI artifacts in your editor and CI.",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "shomra.mjs",
     "discovery.mjs",
     "guard-signals.mjs",
+    "guard-ledger.mjs",
     "code-sast.mjs",
     "model-refs.mjs",
     "ai-usage.mjs",

package/shomra.mjs

@@ -19,6 +19,7 @@ import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { discoverAll } from './discovery.mjs';
 import { localScan, localGate, grade, downrankCodeContext, SECRET_PATTERNS, INVISIBLE_CHARS_RE } from './guard-signals.mjs';
+import { makeLedgerStore } from './guard-ledger.mjs';
 import { scanSourceFile, isScannableSource, isModelConfig } from './code-sast.mjs';
 import { scanModelRefs, isModelRefScannable } from './model-refs.mjs';
 import { scanAiUsage, isAiUsageScannable, KNOWN_AI_PACKAGES, AI_USAGE_CATEGORY_LABEL } from './ai-usage.mjs';
@@ -139,6 +140,14 @@ function breakerReset() {
     /* ignore */
   }
 }
+
+// ── the fail-open ledger ─────────────────────────────────────────────
+// The breaker above is what MAKES failing open cheap; this is what makes it
+// VISIBLE. A breaker-open window produces no rows on the backend, which is
+// byte-for-byte what a quiet, clean window produces — so without this, "the
+// guard was unreachable" and "the guard found nothing" are the same evidence.
+// See guard-ledger.mjs, and src/gate/enforcement-availability.ts in the backend.
+const guardLedger = makeLedgerStore(CONFIG_DIR, { version: VERSION });
 // Machine identity attached to gate / guard / proxy calls so the backend can
 // attribute the activity to this enrolled machine. Unlike machineInfo() it does
 // NOT generate/persist a machineId — an unenrolled machine simply reports none,
@@ -3452,6 +3461,21 @@ function envFlag(name) {
   return ['1', 'true', 'yes', 'on'].includes(String(process.env[name] ?? '').toLowerCase());
 }
 
+/**
+ * Why a guard call did not reach a verdict, in the vocabulary the backend's
+ * availability view groups on. ⚠ Coarse ON PURPOSE: this string is stored and
+ * shown to an operator, and an error message can carry a proxy URL, an internal
+ * hostname, or a token in a query string. `e.message` never goes in it.
+ */
+function guardFailureReason(e) {
+  const name = String(e?.name ?? '');
+  const msg = String(e?.message ?? '');
+  if (name === 'AbortError' || /abort|timeout/i.test(msg)) return 'timeout';
+  const http = msg.match(/^HTTP (\d{3})$/);
+  if (http) return `http-${http[1]}`;
+  return 'network';
+}
+
 /** The gate/tool-call request body, optionally carrying the Tier-0 verdict. */
 function buildGuardBody(norm, agent, clientDecision, clientReason) {
   return {
@@ -3463,6 +3487,13 @@ function buildGuardBody(norm, agent, clientDecision, clientReason) {
     env: detectEnv(),
     agent,
     ...(clientDecision ? { client_decision: clientDecision, client_reason: clientReason } : {}),
+    // ⚠ UNCONDITIONAL, INCLUDING WHEN IT IS EMPTY. The envelope's PRESENCE is
+    // what tells the backend this client is capable of reporting an outage at
+    // all; its contents are the outages themselves. Omitting it when there is
+    // nothing to report — which reads as an obvious optimisation — makes a
+    // healthy machine indistinguishable from one that could never have spoken,
+    // and drops the whole estate to NOT_ATTEMPTABLE. See guard-ledger.mjs rule 1.
+    guard_ledger: guardLedger.envelope(),
   };
 }
 
@@ -3576,7 +3607,17 @@ async function cmdToolGuard(flags) {
 
   // Breaker: skip the round-trip while the backend is known-down (fail-open —
   // Tier 0 already caught the dangerous cases). Strict opts out to stay closed.
-  if (!strict && breakerOpen()) process.exit(0);
+  //
+  // ⚠ THIS IS THE FAIL-OPEN WINDOW, and it is the one that costs the most
+  // coverage: it is silent, instant, and lasts a whole cooldown. The call is
+  // about to run having been screened by Tier 0 alone (no org policy, no
+  // identity, no flow, no supply chain, no intent) — or by nothing at all if
+  // the local engine is switched off. Record which, so the backend can tell an
+  // outage from a quiet afternoon.
+  if (!strict && breakerOpen()) {
+    guardLedger.count(localOff ? 'unscreened' : 'local', 'breaker-open');
+    process.exit(0);
+  }
 
   const body = buildGuardBody(
     norm,
@@ -3605,6 +3646,12 @@ async function cmdToolGuard(flags) {
       // on its own, so it gets a visible line rather than a 30s breaker cooldown
       // that would hide it (and skip even this warning on the calls after it).
       if (r.status === 401 || r.status === 403) {
+        // ⚠ An unenforced call, and the stderr line below already says so — but
+        // a warning nobody is reading is not evidence. It accrues to the ledger
+        // like any other window; it simply cannot be FLUSHED until the key is
+        // fixed, which is the correct behaviour: the gap persists exactly as
+        // long as the misconfiguration does.
+        guardLedger.count(localOff ? 'unscreened' : 'local', `auth-${r.status}`);
         process.stderr.write(
           `[shomra] guard NOT enforced: the backend rejected this API key (HTTP ${r.status}). ` +
             `Local Tier-0 screening still ran; org policy, agent identity and flow control did not. ` +
@@ -3617,8 +3664,19 @@ async function cmdToolGuard(flags) {
     }
     res = await r.json();
     breakerReset(); // healthy response — clear any tripped breaker
+    // ⚠ ACK BEFORE CLOSE, and both only after a 2xx. `ack` drops what THIS
+    // request carried (matched by opened_at, so a gap a concurrent hook appended
+    // meanwhile survives); `close` then seals any window this success just
+    // ended. Reversed, the window closed here would be added to `pending` and
+    // then immediately acked away without ever having been sent.
+    guardLedger.ack(body.guard_ledger?.gaps);
+    guardLedger.close();
   } catch (e) {
     breakerTrip(); // remember this failure so the next calls skip the wait
+    // The first failure of a window, and every subsequent one that still pays
+    // the timeout. `countCall` opens the window on the first and leaves it
+    // alone after — one outage is one row, not one row per call.
+    guardLedger.count(localOff ? 'unscreened' : 'local', guardFailureReason(e));
     if (strict) emitGuardDeny(agent, `Shomra guard could not be reached (${e.message}); blocked by fail-closed policy.`);
     process.exit(0); // fail-open (Tier 0 already screened the dangerous patterns)
   }
@@ -3718,6 +3776,13 @@ async function cmdResultGuard(flags) {
     // parse cleanly and `res.decision` would be undefined → silent fail-open.
     if (!r.ok) {
       if (r.status === 401 || r.status === 403) {
+        // ⚠ DELIBERATELY NOT COUNTED IN THE FAIL-OPEN LEDGER, though it is just
+        // as unenforced. That ledger's denominator is GateEvent — the tool-CALL
+        // channel — and this guard posts to /gate/tool-result, which writes no
+        // GateEvent. Folding it in would put a numerator from one population
+        // over a denominator from another and publish the quotient, which is the
+        // exact error the availability module refuses elsewhere. The result
+        // channel needs its own ledger, not a share of this one.
         process.stderr.write(
           `[shomra] result-guard NOT enforced: the backend rejected this API key (HTTP ${r.status}). ` +
             `Local Tier-0 screening still ran; server-side flow taint did not. ` +
@@ -3851,6 +3916,10 @@ async function cmdPromptGuard(flags) {
     process.exit(0);
   }
   if (!strict && breakerOpen()) {
+    // The prompt channel posts to /gate/tool-call and therefore writes a
+    // GateEvent, so an unscreened submission belongs in the same ledger and the
+    // same denominator as an unscreened tool call.
+    guardLedger.count(localOff ? 'unscreened' : 'local', 'breaker-open');
     if (injection.length) emitPromptContext(agent, promptInjectionNote(injection));
     process.exit(0);
   }
@@ -3858,18 +3927,27 @@ async function cmdPromptGuard(flags) {
   // ── Tier 2: org policy on the prompt channel (DLP-shaped rules the local floor
   // deliberately doesn't carry — customer identifiers, regulated data classes).
   let res;
+  // Built once and held, so the ack below drops exactly the gaps THIS request
+  // carried rather than whatever the file happens to hold afterwards.
+  const promptBody = buildPromptGuardBody(norm, agent);
   try {
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), guardTimeoutMs());
     const r = await fetch(`${url}/gate/tool-call`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json', 'X-Shomra-Key': apiKey, Connection: 'close' },
-      body: JSON.stringify(buildPromptGuardBody(norm, agent)),
+      body: JSON.stringify(promptBody),
       signal: ctrl.signal,
     });
     clearTimeout(timer);
     if (!r.ok) {
       if (r.status === 401 || r.status === 403) {
+        // ⚠ An unenforced call, and the stderr line below already says so — but
+        // a warning nobody is reading is not evidence. It accrues to the ledger
+        // like any other window; it simply cannot be FLUSHED until the key is
+        // fixed, which is the correct behaviour: the gap persists exactly as
+        // long as the misconfiguration does.
+        guardLedger.count(localOff ? 'unscreened' : 'local', `auth-${r.status}`);
         process.stderr.write(`[shomra] prompt-guard NOT enforced: the backend rejected this API key (HTTP ${r.status}). Local screening still ran.\n`);
         if (strict) emitPromptDeny(agent, `Shomra prompt-guard could not authenticate (HTTP ${r.status}); blocked by fail-closed policy.`);
         process.exit(0);
@@ -3878,8 +3956,11 @@ async function cmdPromptGuard(flags) {
     }
     res = await r.json();
     breakerReset();
+    guardLedger.ack(promptBody.guard_ledger?.gaps);
+    guardLedger.close();
   } catch (e) {
     breakerTrip();
+    guardLedger.count(localOff ? 'unscreened' : 'local', guardFailureReason(e));
     if (injection.length) emitPromptContext(agent, promptInjectionNote(injection));
     if (strict) emitPromptDeny(agent, `Shomra prompt-guard could not be reached (${e.message}); blocked by fail-closed policy.`);
     process.exit(0);
@@ -3906,6 +3987,10 @@ function promptInjectionNote(injection) {
  *  speaks — so it lands in Gate Activity with no schema change. */
 function buildPromptGuardBody(norm, agent, clientDecision, clientReason) {
   return {
+    // Same channel as the tool firewall (/gate/tool-call), so the same envelope
+    // rides along — a machine whose operator only ever submits prompts still
+    // needs its capability witness stamped, or its silence is unreadable.
+    guard_ledger: guardLedger.envelope(),
     tool_name: 'UserPromptSubmit',
     tool_input: { prompt: norm.prompt },
     cwd: norm.cwd,