@cirvix_ai/agent-control 0.1.3 → 0.2.0

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 } });

package/src/core/graph.mjs

@@ -0,0 +1,270 @@
+/**
+ * The multi-agent relationship graph.
+ *
+ * delegation.mjs already records every edge — each grant is "issuer delegated
+ * this scope to subject" — but only ever answers one question: may THIS call
+ * proceed. That is the right question at execution time and the wrong one
+ * afterwards, when somebody is trying to find out how an agent nobody
+ * provisioned for production ended up able to reach it.
+ *
+ * This module answers the second kind of question. It reads the broker's
+ * inventory and nothing else, so it cannot disagree with enforcement about who
+ * delegated what — there is one source of edges.
+ *
+ * TENANCY IS A CONSTRUCTOR ARGUMENT, NOT A FILTER YOU REMEMBER TO APPLY
+ * --------------------------------------------------------------------
+ * buildGraph() takes the tenant and drops everything else before any query
+ * runs. A graph is exactly the shape of an answer to "what can reach
+ * production", so a traversal that wanders into another tenant's edges does
+ * not leak a row — it leaks the topology of someone else's estate, which is
+ * worse and harder to notice. Filtering at construction means no query can
+ * forget to do it, and the tests assert a cross-tenant edge is absent from the
+ * graph rather than merely excluded from the result.
+ *
+ * NOT A GRAPH DATABASE
+ * --------------------
+ * Adjacency maps over an array that is already in memory. These estates are
+ * tens to low thousands of edges; a traversal over that is microseconds, and
+ * introducing a graph store would add an operational dependency to answer
+ * questions a Map already answers.
+ */
+
+import { scopePermits, intersectScopes } from "./delegation.mjs";
+
+/**
+ * Builds a directed graph from a broker inventory.
+ *
+ * Revoked and expired grants are excluded by default: an edge that cannot
+ * authorise anything is not a path, and including it would make every query
+ * over-report. `includeInactive` keeps them for forensics, where "who COULD
+ * have reached this last Tuesday" is the actual question.
+ */
+export function buildGraph(inventory = [], { tenant = undefined, includeInactive = false, now = Date.now() } = {}) {
+  const scoped = inventory.filter((g) => {
+    if (tenant !== undefined && g.tenant !== tenant) return false;
+    if (includeInactive) return true;
+    if (g.revoked) return false;
+    if (g.expiresAt && Date.parse(g.expiresAt) <= now) return false;
+    return true;
+  });
+
+  const nodes = new Map();
+  const node = (id) => {
+    if (!id) return null;
+    if (!nodes.has(id)) nodes.set(id, { id, tenant: tenant === undefined ? null : tenant, roots: 0, out: [], in: [] });
+    return nodes.get(id);
+  };
+
+  const edges = [];
+  for (const g of scoped) {
+    const subject = node(g.subject);
+    if (!subject) continue;
+    if (g.issuer === null) {
+      // A root grant is authority the platform handed the agent directly. It
+      // is a property of the node, not an edge from nobody.
+      subject.roots += 1;
+      subject.rootScope = subject.rootScope ? intersectScopes(subject.rootScope, g.scope) : g.scope;
+      continue;
+    }
+    const issuer = node(g.issuer);
+    const edge = {
+      id: g.id, from: g.issuer, to: g.subject, scope: g.scope,
+      depth: g.depth, revoked: Boolean(g.revoked), expiresAt: g.expiresAt ?? null,
+    };
+    edges.push(edge);
+    issuer.out.push(edge);
+    subject.in.push(edge);
+  }
+
+  return { tenant: tenant === undefined ? null : tenant, nodes, edges };
+}
+
+/**
+ * Everything `from` can reach, and by which path.
+ *
+ * Breadth-first so the first path found to a node is the shortest one, which
+ * is the path a reader wants to see. Scope is intersected along the way: an
+ * agent two delegations deep holds the intersection of both, never the union,
+ * which is the same rule enforcement applies.
+ */
+export function reach(graph, from, { maxDepth = 8 } = {}) {
+  const start = graph.nodes.get(from);
+  if (!start) return [];
+
+  const seen = new Set([from]);
+  const out = [];
+  let frontier = [{ id: from, path: [], scope: start.rootScope ?? null }];
+
+  for (let depth = 0; depth < maxDepth && frontier.length; depth++) {
+    const next = [];
+    for (const cur of frontier) {
+      const node = graph.nodes.get(cur.id);
+      if (!node) continue;
+      for (const edge of node.out) {
+        if (seen.has(edge.to)) continue;
+        seen.add(edge.to);
+        const scope = cur.scope ? intersectScopes(cur.scope, edge.scope) : edge.scope;
+        const entry = { agent: edge.to, depth: depth + 1, path: [...cur.path, edge.id], via: [...cur.path, edge.id].length, scope };
+        out.push(entry);
+        next.push({ id: edge.to, path: entry.path, scope });
+      }
+    }
+    frontier = next;
+  }
+  return out;
+}
+
+/**
+ * The scope actually held at the end of a specific path.
+ *
+ * Intersected edge by edge, starting from the origin's root authority, which
+ * is the same narrowing enforcement applies.
+ */
+export function scopeAlong(graph, origin, path) {
+  let scope = graph.nodes.get(origin)?.rootScope ?? null;
+  for (const edgeId of path) {
+    const edge = graph.edges.find((e) => e.id === edgeId);
+    if (!edge) return null;
+    scope = scope ? intersectScopes(scope, edge.scope) : edge.scope;
+  }
+  return scope;
+}
+
+/**
+ * Which agents can reach this action/resource, directly or by delegation.
+ *
+ * WHY THIS ENUMERATES EVERY PATH RATHER THAN USING reach()
+ * -------------------------------------------------------
+ * reach() is breadth-first with one `seen` set, so an agent is claimed by
+ * whichever path arrives first — the SHORTEST one. For "how do I get there"
+ * that is the right answer. For "can this agent reach production" it is
+ * actively wrong, because the shortest path is not the most permissive one.
+ *
+ * The estate in the tests has exactly this shape: deployer is reachable at
+ * depth 2 through researcher (fs.read only) and through coder (which carries
+ * deploy.production). Breadth-first found the researcher path first, computed
+ * a scope without deploy.production, and concluded deployer could not reach
+ * production. It can. A security query that under-reports is worse than one
+ * that is slow, so this walks every path and asks whether ANY of them still
+ * permits the call after all its narrowings.
+ */
+export function whoCanReach(graph, { action, resource }) {
+  const hits = [];
+  for (const [id, node] of graph.nodes) {
+    if (node.rootScope && scopePermits(node.rootScope, { action, resource })) {
+      hits.push({ agent: id, via: "root", depth: 0, path: [] });
+      continue;
+    }
+    let best = null;
+    for (const [origin, originNode] of graph.nodes) {
+      if (origin === id || !originNode.rootScope) continue;
+      for (const path of paths(graph, origin, id)) {
+        const scope = scopeAlong(graph, origin, path);
+        if (!scope || !scopePermits(scope, { action, resource })) continue;
+        /* Report the shortest permitting path, not merely the first found —
+           it is the one someone has to go and revoke. */
+        if (!best || path.length < best.path.length) best = { agent: id, via: origin, depth: path.length, path };
+      }
+    }
+    if (best) hits.push(best);
+  }
+  return hits;
+}
+
+/**
+ * Delegation paths from `from` to `to`.
+ *
+ * All of them, not the shortest. Two routes to the same authority is exactly
+ * the finding worth surfacing — revoking one and believing the path is closed
+ * is how an estate keeps a capability nobody thinks it has.
+ */
+export function paths(graph, from, to, { maxDepth = 8 } = {}) {
+  const found = [];
+  const walk = (cur, trail, visited) => {
+    if (trail.length > maxDepth) return;
+    if (cur === to && trail.length) { found.push([...trail]); return; }
+    const node = graph.nodes.get(cur);
+    if (!node) return;
+    for (const edge of node.out) {
+      if (visited.has(edge.to)) continue;      // no cycles
+      visited.add(edge.to);
+      walk(edge.to, [...trail, edge.id], visited);
+      visited.delete(edge.to);
+    }
+  };
+  walk(from, [], new Set([from]));
+  return found;
+}
+
+/**
+ * Agents that share a capability, grouped by the capability.
+ *
+ * "Which agents share a sensitive capability" — the shared-credential
+ * question. Only capabilities held by more than one agent are returned;
+ * a capability with a single holder is not a sharing risk and would bury
+ * the ones that are.
+ */
+export function sharedCapability(graph) {
+  const holders = new Map();
+  const note = (cap, agent) => {
+    if (!holders.has(cap)) holders.set(cap, new Set());
+    holders.get(cap).add(agent);
+  };
+  /* A scope is {actions, resources}, NOT a flat list of capability strings.
+     Iterating the scope object directly yielded nothing and, worse, passing a
+     flat array anywhere near normalizeScope() turns it into ["*"] on BOTH
+     axes — absent means unconstrained — so an array-shaped scope reads as
+     unlimited authority. Actions are the axis that names a capability. */
+  const actionsOf = (scope) => (Array.isArray(scope?.actions) ? scope.actions : []);
+  for (const [id, node] of graph.nodes) {
+    for (const cap of actionsOf(node.rootScope)) note(String(cap), id);
+  }
+  for (const e of graph.edges) for (const cap of actionsOf(e.scope)) note(String(cap), e.to);
+
+  return [...holders.entries()]
+    .filter(([, set]) => set.size > 1)
+    .map(([capability, set]) => ({ capability, agents: [...set].sort() }))
+    .sort((a, b) => b.agents.length - a.agents.length || a.capability.localeCompare(b.capability));
+}
+
+/** Who delegated authority to this agent, nearest first. */
+export function delegatedBy(graph, agent) {
+  const node = graph.nodes.get(agent);
+  if (!node) return [];
+  return node.in.map((e) => ({ from: e.from, grant: e.id, scope: e.scope, depth: e.depth }));
+}
+
+/**
+ * Graphviz export, for the CLI and for anyone who wants a picture.
+ *
+ * Machine-readable is `summary()`; this is the human one. Root authority is
+ * drawn as a node attribute rather than an edge from a phantom node, because
+ * inventing a "platform" node would put something in the picture that does not
+ * exist in the model.
+ */
+export function toDot(graph, { title = "cirvix agents" } = {}) {
+  const esc = (s) => String(s).replace(/"/g, '\\"');
+  const lines = [`digraph "${esc(title)}" {`, "  rankdir=LR;", '  node [shape=box, style=rounded, fontname="monospace"];'];
+  for (const [id, node] of graph.nodes) {
+    const rooted = node.roots > 0;
+    lines.push(`  "${esc(id)}" [label="${esc(id)}${rooted ? "\\n(root authority)" : ""}"${rooted ? ', peripheries=2' : ""}];`);
+  }
+  for (const e of graph.edges) {
+    const label = (e.scope?.actions ?? []).join(", ");
+    lines.push(`  "${esc(e.from)}" -> "${esc(e.to)}" [label="${esc(label)}"${e.revoked ? ", style=dashed" : ""}];`);
+  }
+  lines.push("}");
+  return lines.join("\n");
+}
+
+/** A compact machine-readable view for the API and the dashboard. */
+export function summary(graph) {
+  return {
+    tenant: graph.tenant,
+    agents: [...graph.nodes.values()].map((n) => ({
+      id: n.id, rootAuthority: n.roots > 0, delegationsIn: n.in.length, delegationsOut: n.out.length,
+    })),
+    edges: graph.edges.map((e) => ({ from: e.from, to: e.to, grant: e.id, scope: e.scope, revoked: e.revoked })),
+    shared: sharedCapability(graph),
+  };
+}