@cirvix_ai/agent-control 0.1.2 → 0.1.5

package/src/core/evidence.mjs

@@ -0,0 +1,212 @@
+/**
+ * Evidence packs.
+ *
+ * The primitives already existed — prove.mjs signs a decision, the audit chain
+ * verifies, buildPassport describes an agent. What did not exist was the thing
+ * a security reviewer actually asks for: one bundle, for one scope, that
+ * answers "show me this agent was controlled" without the reviewer having to
+ * know which four commands to run.
+ *
+ * THE ONE RULE THIS FILE EXISTS TO ENFORCE
+ * ---------------------------------------
+ * A pack maps controls. It never claims compliance.
+ *
+ * "SOC 2 CC6.1" appearing next to a decision means Cirvix believes this
+ * evidence is relevant to that control. It does not mean the control is met,
+ * that an auditor agreed, or that anybody is certified. The vocabulary below
+ * has no word for "compliant" and a test asserts it never acquires one —
+ * because the moment a generated PDF says "SOC 2 compliant", somebody forwards
+ * it to a customer and the claim is ours.
+ *
+ * WHAT NEVER GOES IN
+ * ------------------
+ * Arguments and results are excluded wholesale rather than redacted. A
+ * redactor is a filter that has to be right every time; an exclusion is right
+ * by construction. The pack carries what was decided, under which rule, and
+ * whether the chain verifies — none of which needs the payload.
+ */
+
+import { createHash } from "node:crypto";
+import { canonicalJson } from "./audit.mjs";
+
+export const EVIDENCE_VERSION = 1;
+
+/**
+ * Coverage vocabulary. Deliberately has no "pass" and no "compliant".
+ *
+ * `mapped` is the strongest word available and it only means evidence exists.
+ * Adding a stronger term is the one change to this file that would turn a
+ * useful artifact into a liability.
+ */
+export const COVERAGE = Object.freeze({
+  MAPPED: "mapped",           // evidence exists and is attached
+  PARTIAL: "partial",         // some evidence, with a stated gap
+  NOT_COVERED: "not_covered", // in scope, nothing found
+  OUT_OF_SCOPE: "out_of_scope",
+});
+
+/**
+ * Control mappings. Intentionally few, and each says what it is evidenced BY.
+ *
+ * A long list of frameworks would look more impressive and mean less: every
+ * row Cirvix cannot actually evidence is a row a reviewer will find empty.
+ */
+const CONTROLS = [
+  { id: "SOC2.CC6.1", framework: "SOC 2", title: "Logical access controls restrict access to protected resources",
+    evidencedBy: "decisions" },
+  { id: "SOC2.CC6.3", framework: "SOC 2", title: "Access is removed or modified when no longer appropriate",
+    evidencedBy: "policyVersions" },
+  { id: "SOC2.CC7.2", framework: "SOC 2", title: "Anomalies are identified and analysed",
+    evidencedBy: "denials" },
+  { id: "SOC2.CC7.3", framework: "SOC 2", title: "Security events are evaluated and acted upon",
+    evidencedBy: "approvals" },
+  { id: "ISO27001.A.8.16", framework: "ISO/IEC 27001:2022", title: "Monitoring activities",
+    evidencedBy: "decisions" },
+  { id: "ISO27001.A.5.15", framework: "ISO/IEC 27001:2022", title: "Access control",
+    evidencedBy: "policyVersions" },
+  { id: "NIST.AI.RMF.MEASURE.2.7", framework: "NIST AI RMF", title: "AI system security and resilience are evaluated",
+    evidencedBy: "denials" },
+  { id: "NIST.AI.RMF.MANAGE.4.1", framework: "NIST AI RMF", title: "Post-deployment monitoring plans are implemented",
+    evidencedBy: "chain" },
+];
+
+/** Fields that may appear on a decision inside a pack. Everything else is dropped. */
+const DECISION_FIELDS = [
+  "decision_id", "ts", "agent", "action", "tool", "resource", "destination",
+  "verdict", "decision", "rule", "reason", "risk", "environment", "run_id", "hash", "prev_hash",
+];
+
+function slimDecision(record) {
+  const out = {};
+  for (const f of DECISION_FIELDS) if (record[f] !== undefined) out[f] = record[f];
+  return out;
+}
+
+/**
+ * Assembles a pack.
+ *
+ * `records` are audit records already read from the chain — this function does
+ * no I/O, so it is testable and so the caller decides what it is allowed to
+ * read.
+ */
+export function buildEvidencePack({
+  records = [],
+  agent = null,
+  org = null,
+  from = null,
+  to = null,
+  passport = null,
+  policyVersions = [],
+  proofs = [],
+  approvals = [],
+  chain = null,
+  now = () => new Date().toISOString(),
+} = {}) {
+  const inWindow = (r) => {
+    const t = r.ts ?? r.timestamp;
+    if (from && t && t < from) return false;
+    if (to && t && t > to) return false;
+    return true;
+  };
+  const scoped = records
+    .filter((r) => (agent ? r.agent === agent : true))
+    .filter(inWindow);
+
+  const decisions = scoped.map(slimDecision);
+  const denials = decisions.filter((d) => d.verdict === "deny" || d.decision === "deny");
+  const held = decisions.filter((d) => d.decision === "require_approval" || d.verdict === "hold");
+
+  const evidence = {
+    decisions: decisions.length,
+    denials: denials.length,
+    approvals: approvals.length,
+    policyVersions: policyVersions.length,
+    chain: chain?.ok === true ? 1 : 0,
+  };
+
+  const coverage = CONTROLS.map((c) => {
+    const n = evidence[c.evidencedBy] ?? 0;
+    return {
+      control: c.id,
+      framework: c.framework,
+      title: c.title,
+      coverage: n > 0 ? COVERAGE.MAPPED : COVERAGE.NOT_COVERED,
+      evidence: `${n} ${c.evidencedBy}`,
+    };
+  });
+
+  const pack = {
+    v: EVIDENCE_VERSION,
+    kind: "evidence_pack",
+    generatedAt: now(),
+    scope: { agent, org, from, to },
+    summary: {
+      decisions: decisions.length,
+      denied: denials.length,
+      heldForApproval: held.length,
+      distinctRules: [...new Set(decisions.map((d) => d.rule).filter(Boolean))].length,
+      chainVerified: chain?.ok === true,
+      chainRecords: chain?.records ?? null,
+      chainHead: chain?.head ?? null,
+    },
+    passport: passport ?? null,
+    policyVersions: policyVersions.map((p) => ({ version: p.version ?? null, hash: p.hash ?? null, publishedAt: p.publishedAt ?? null })),
+    decisions,
+    approvals: approvals.map((a) => ({ id: a.id ?? null, decidedBy: a.decidedBy ?? null, decision: a.decision ?? null, at: a.at ?? null })),
+    proofs: proofs.map((p) => (typeof p === "string" ? { token: p } : { token: p.token ?? null, decisionId: p.decisionId ?? null })),
+    controlMapping: coverage,
+    /* Load-bearing. Read by humans who will forward this onward. */
+    disclaimer:
+      "This pack maps evidence to control identifiers. It is not an audit, a certification, " +
+      "or a statement of compliance. No control is asserted to be met, and no framework " +
+      "listed here has assessed this system. Coverage of 'mapped' means only that relevant " +
+      "evidence is attached.",
+  };
+
+  pack.digest = "sha256:" + createHash("sha256").update(canonicalJson({ ...pack, digest: undefined })).digest("hex");
+  return pack;
+}
+
+/** The human-readable report. Plain text so it survives every pipeline. */
+export function renderEvidenceReport(pack) {
+  const s = pack.summary;
+  const lines = [
+    "CIRVIX EVIDENCE PACK",
+    "",
+    `Generated    ${pack.generatedAt}`,
+    `Agent        ${pack.scope.agent ?? "(all agents)"}`,
+    `Window       ${pack.scope.from ?? "(open)"} → ${pack.scope.to ?? "(open)"}`,
+    `Digest       ${pack.digest}`,
+    "",
+    "SUMMARY",
+    `  Decisions recorded     ${s.decisions}`,
+    `  Denied                 ${s.denied}`,
+    `  Held for approval      ${s.heldForApproval}`,
+    `  Distinct rules applied ${s.distinctRules}`,
+    `  Audit chain            ${s.chainVerified ? `verified, ${s.chainRecords} records` : "NOT VERIFIED"}`,
+    "",
+  ];
+
+  if (pack.passport?.trust) {
+    const t = pack.passport.trust;
+    lines.push("TRUST", `  Score  ${t.score ?? "unscored"}${t.band ? ` (${t.band})` : ""}`, "");
+  }
+
+  lines.push("CONTROL MAPPING", "");
+  for (const c of pack.controlMapping) {
+    lines.push(`  ${c.coverage === COVERAGE.MAPPED ? "▪" : "·"} ${c.control.padEnd(28)} ${c.coverage.padEnd(12)} ${c.evidence}`);
+  }
+  lines.push("", "  " + pack.disclaimer.replace(/(.{1,72})(\s|$)/g, "$1\n  ").trim(), "");
+  return lines.join("\n");
+}
+
+/**
+ * Re-derives the digest.
+ *
+ * A pack that has been edited after generation fails here. The digest is over
+ * the canonical form minus itself, so it is stable across serialisation.
+ */
+export function verifyEvidencePack(pack) {
+  const expected = "sha256:" + createHash("sha256").update(canonicalJson({ ...pack, digest: undefined })).digest("hex");
+  return { ok: expected === pack.digest, expected, actual: pack.digest };
+}

package/src/core/format.mjs

@@ -26,6 +26,33 @@ export const red = wrap(31, 39);
 export const green = wrap(32, 39);
 export const amber = wrap(33, 39);
 export const blue = wrap(34, 39);
+export const cyan = wrap(36, 39);
+export const gray = wrap(90, 39);
+export const white = wrap(97, 39);
+
+/** Strip ANSI escape sequences for width calculation and secret checks. */
+export function stripAnsi(s) {
+  return String(s).replace(/\u001b\[[0-9;]*m/g, "");
+}
+
+/** Visible character width, ignoring ANSI. */
+export function visibleWidth(s) {
+  return stripAnsi(String(s)).length;
+}
+
+/** True when output should be decorated (TTY, not NO_COLOR, not dumb, not CI unless forced). */
+export function isInteractive() {
+  if (disabled) return false;
+  if (process.env.CI !== undefined && !forced) return false;
+  return Boolean(process.stdout.isTTY);
+}
+
+/** Whether unicode box-drawing is safe. ASCII fallback when TERM=dumb or CIRVIX_ASCII=1. */
+export function supportsUnicode() {
+  if (process.env.CIRVIX_ASCII === "1") return false;
+  if (process.env.TERM === "dumb") return false;
+  return true;
+}
 
 /** "1 server" / "3 servers" — avoids the "1 servers" that reads as a bug. */
 export function plural(n, noun, pluralForm) {

package/src/core/gateway.mjs

@@ -42,17 +42,6 @@
  *   the only point in the process where a credential exists inside a request,
  *   and it sits downstream of the decision that authorized it. See
  *   `./secrets.mjs`.
- *
- * WHAT THE GATEWAY DOES NOT GOVERN.
- *
- * The gateway governs traffic actually routed through it — every `tools/call`,
- * `resources/read`, `resources/subscribe`, `prompts/get`, `completion/complete`,
- * and unmodeled method crossing this process is evaluated before anything
- * executes, and unknown methods are default-denied. What never enters this
- * process is never evaluated: a direct MCP server entry in the agent's config,
- * the runtime's built-in tools, a subprocess the agent spawns, a socket the
- * agent opens itself. Those are routes around the boundary, not through it,
- * and no userspace gateway can interpose on them.
  */
 
 import { spawn } from "node:child_process";
@@ -66,6 +55,7 @@ const GATEWAY_VERSION = JSON.parse(
 
 import { Guard, actionForTool, destinationFor, resourceForCall } from "./guard.mjs";
 import { HttpUpstream } from "./http-transport.mjs";
+import { prepareSpawn, killProcessTree } from "./windows.mjs";
 import { DECISION } from "./decisions.mjs";
 import {
   ERROR_CODE,
@@ -137,28 +127,12 @@ class Upstream {
 
   start() {
     const { command, args = [], env = {} } = this.spec;
-    // Windows: Node >= 18.20 throws EINVAL when spawning .cmd/.bat shims
-    // (npm, npx, pnpm) without a shell (CVE-2024-27980 mitigation). MCP configs
-    // name such shims constantly. Going through the shell only for shims keeps
-    // POSIX behaviour unchanged; with shell:true Node joins argv verbatim, so
-    // every argument is quoted here to survive spaces and metacharacters.
-    const isWindowsShim =
-      process.platform === "win32" && /\.(cmd|bat)$/i.test(command);
-    const quoted = args.map((a) =>
-      /[\s"^&|<>]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a,
-    );
-    this.proc = isWindowsShim
-      ? spawn([command, ...quoted].join(" "), {
-          stdio: ["pipe", "pipe", "pipe"],
-          env: { ...process.env, ...env },
-          shell: true,
-          windowsHide: true,
-        })
-      : spawn(command, args, {
-          stdio: ["pipe", "pipe", "pipe"],
-          env: { ...process.env, ...env },
-          shell: false,
-        });
+    const prepared = prepareSpawn(command, args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, ...env },
+      shell: false,
+    });
+    this.proc = spawn(prepared.command, prepared.args, prepared.options);
 
     this.alive = true;
 
@@ -235,7 +209,7 @@ class Upstream {
   stop() {
     this.alive = false;
     try {
-      this.proc?.kill();
+      if (this.proc) killProcessTree(this.proc);
     } catch {
       /* already gone */
     }
@@ -476,15 +450,10 @@ export class Gateway {
   /* ---------------------------------------------------------------------- */
 
   async handleClientMessage(message) {
-    // Notifications carry no id and expect no answer, but they still reach
-    // upstream processes — so they still cross the boundary. A small set of
-    // lifecycle notifications is benign plumbing; anything else is evaluated
-    // like any other call, and dropped unless permitted. Previously every
-    // notification was broadcast to ALL upstreams unevaluated, so a
-    // tools/call-shaped action framed as a notification bypassed the engine
-    // entirely, with no decision and no audit record.
+    // Notifications are forwarded to every upstream and never answered.
     if (message.id === undefined && message.method) {
-      return this.#handleNotification(message);
+      for (const up of this.upstreams.values()) up.send(message);
+      return;
     }
 
     switch (message.method) {
@@ -541,173 +510,11 @@ export class Gateway {
         this.write({ jsonrpc: "2.0", id: message.id, result: {} });
         return;
 
-      /*
-       * `prompts/get` returns server-authored text that enters the model's
-       * context with instruction-level authority — the same reason tool
-       * definitions are pinned. It was falling through to the default branch
-       * and reaching the agent with no rule consulted and no decision
-       * recorded. It is now evaluated as a read of the named prompt.
-       */
-      case "prompts/get":
-        return this.#handlePromptsGet(message);
-
-      /*
-       * `completion/complete` asks an upstream to complete an argument value.
-       * Low-risk content, but still upstream-influenced text entering the
-       * agent loop — evaluated, then forwarded on permit.
-       */
-      case "completion/complete":
-        return this.#handleCompletion(message);
-
-      /*
-       * `logging/setLevel` carries no content and executes nothing: it asks
-       * upstreams to adjust log verbosity. Forwarded as benign plumbing, and
-       * reported on the protocol sink (not the decision sink) so it can never
-       * be mistaken for a policy decision.
-       */
-      case "logging/setLevel":
-        this.onDecision({ kind: "protocol", method: message.method, action: "forward" });
-        this.log(`forward ${message.method} (benign protocol plumbing)`);
-        return this.#forwardToAny(message);
-
       default:
-        // Default-deny applies to methods, not just tools. Anything the
-        // gateway does not model is evaluated as `mcp.<method>` against the
-        // active policy and forwarded only on an explicit permit — previously
-        // this branch forwarded to the first live upstream unevaluated and
-        // unrecorded, which made every unmodeled method a full bypass.
-        return this.#rejectUnknown(message);
-    }
-  }
-
-  /* Allowlisted lifecycle notifications: session plumbing with no content and
-   * no upstream side effect beyond what the protocol requires. Reported on
-   * the protocol sink, never the decision sink. */
-  static #BENIGN_NOTIFICATIONS = new Set([
-    "notifications/initialized",
-    "notifications/cancelled",
-    "notifications/progress",
-  ]);
-
-  async #handleNotification(message) {
-    if (Gateway.#BENIGN_NOTIFICATIONS.has(message.method)) {
-      this.onDecision({ kind: "protocol", method: message.method, action: "forward" });
-      for (const up of this.upstreams.values()) up.send(message);
-      return;
-    }
-    const { decision } = await this.guard.authorize({
-      tool: `mcp.notification.${message.method}`,
-      server: null,
-      args: message.params ?? {},
-      ...callerIdentity(message.params),
-    });
-    this.stats = this.guard.stats;
-    if (decision.verdict !== "permit") {
-      this.log(`DROP notification ${message.method} (${decision.rule ?? "default-deny"})`);
-      return;
-    }
-    this.onDecision({ kind: "protocol", method: message.method, action: "forward", decision: decision.decisionId });
-    for (const up of this.upstreams.values()) up.send(message);
-  }
-
-  async #handlePromptsGet(message) {
-    const fullName = message.params?.name ?? "";
-    const sep = fullName.indexOf(NS);
-    const server = sep === -1 ? null : fullName.slice(0, sep);
-    const promptName = sep === -1 ? fullName : fullName.slice(sep + NS.length);
-    const up = server ? this.upstreams.get(server) : null;
-
-    if (!up || !up.alive) {
-      this.write(
-        errorResponse(
-          message.id,
-          ERROR_CODE.UPSTREAM_UNAVAILABLE,
-          `No registered server for prompt "${fullName}".`,
-        ),
-      );
-      return;
-    }
-
-    const { agent: callerAgent, delegation } = callerIdentity(message.params);
-    const { decision } = await this.guard.authorize({
-      tool: "prompts.get",
-      server,
-      args: { name: promptName, ...(message.params?.arguments ?? {}) },
-      agent: callerAgent,
-      delegation,
-    });
-    this.stats = this.guard.stats;
-
-    if (decision.verdict === "deny") {
-      this.log(`DENY prompts/get ${promptName} (${decision.rule})`);
-      this.write(deniedToolResult(message.id, decision));
-      return;
-    }
-    if (decision.verdict === "hold") {
-      decision.approvalId = `apr_${String(decision.decisionId).slice(4, 12)}`;
-      this.log(`HOLD prompts/get ${promptName} (${decision.rule})`);
-      this.write(heldToolResult(message.id, decision));
-      return;
-    }
-
-    const gatewayId = `gw-${this.nextGatewayId++}`;
-    this.inflight.set(gatewayId, { clientId: message.id, upstream: up, decision });
-    up.send({
-      jsonrpc: "2.0",
-      id: gatewayId,
-      method: "prompts/get",
-      params: { ...message.params, name: promptName },
-    });
-  }
-
-  async #handleCompletion(message) {
-    const ref = message.params?.ref ?? {};
-    const target = typeof ref.name === "string" && ref.name
-      ? ref.name
-      : typeof ref.uri === "string" ? ref.uri : "";
-    const { agent: callerAgent, delegation } = callerIdentity(message.params);
-    const { decision } = await this.guard.authorize({
-      tool: "completion.complete",
-      server: null,
-      args: { ref: target, argument: message.params?.argument ?? {} },
-      agent: callerAgent,
-      delegation,
-    });
-    this.stats = this.guard.stats;
-
-    if (decision.verdict === "deny") {
-      this.log(`DENY completion/complete ${target} (${decision.rule})`);
-      this.write(deniedToolResult(message.id, decision));
-      return;
-    }
-    if (decision.verdict === "hold") {
-      decision.approvalId = `apr_${String(decision.decisionId).slice(4, 12)}`;
-      this.log(`HOLD completion/complete ${target} (${decision.rule})`);
-      this.write(heldToolResult(message.id, decision));
-      return;
-    }
-    return this.#forwardToAny(message);
-  }
-
-  async #rejectUnknown(message) {
-    const method = message.method ?? "(missing)";
-    const { agent: callerAgent, delegation } = callerIdentity(message.params);
-    const { decision } = await this.guard.authorize({
-      tool: `mcp.${method}`,
-      server: null,
-      args: message.params ?? {},
-      agent: callerAgent,
-      delegation,
-    });
-    this.stats = this.guard.stats;
-
-    if (decision.verdict !== "permit") {
-      this.log(`DENY ${method} (${decision.rule ?? "default-deny"}) — unmodeled method, no explicit permit`);
-      this.write(deniedToolResult(message.id, decision));
-      return;
+        // Anything else is broadcast to the first live upstream. The gateway
+        // deliberately does not invent behaviour for methods it doesn't model.
+        return this.#forwardToAny(message);
     }
-    this.log(`PERMIT ${method} (${decision.rule}) — explicitly permitted unmodeled method`);
-    return this.#forwardToAny(message);
   }
 
   #handleInitialize(message) {
@@ -853,11 +660,8 @@ export class Gateway {
     }
 
     // Unsubscribing is always permitted: refusing to let an agent stop
-    // receiving something is not a security property. Reported on the
-    // protocol sink so the forward is visible without fabricating a policy
-    // decision that never happened.
+    // receiving something is not a security property.
     if (message.method === "resources/unsubscribe") {
-      this.onDecision({ kind: "protocol", method: message.method, action: "forward" });
       const gatewayId = `gw-${this.nextGatewayId++}`;
       this.inflight.set(gatewayId, { clientId: message.id, upstream: up });
       up.send({ jsonrpc: "2.0", id: gatewayId, method: message.method, params: { ...message.params, uri } });