@strixgov/mcp-proxy 0.2.1 → 0.2.2

package/test/shadow-discovery-e2e.test.mjs

@@ -0,0 +1,185 @@
+/**
+ * End-to-end shadow discovery through startProxy (GSD-1 Phase 4).
+ *
+ * Same two-InMemoryTransport-pair harness as proxy-end-to-end.test.mjs:
+ *
+ *   [Test Client] ─in-memory─▶ [Proxy as Server]
+ *                              [Proxy as Client] ─in-memory─▶ [Fake Upstream]
+ *
+ * The upstream advertises one tool the companion capability list has
+ * classified and one it has NOT (`mystery_tool`). The suite drives real
+ * MCP traffic and asserts shadow discovery reports the delta — without
+ * perturbing the governance pipeline (verdicts, receipts) it observes.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { startProxy, SHADOW_MEASUREMENT_DISCLAIMER } from "../src/index.mjs";
+
+const SAMPLE_CAPS = [
+  { id: "mcp.demo.read_thing", name: "read_thing", risk: "LOW", mode: "READ" },
+  { id: "mcp.demo.write_thing", name: "write_thing", risk: "MEDIUM", mode: "WRITE" },
+];
+
+async function buildFakeUpstream() {
+  const upstreamServer = new Server(
+    { name: "fake-upstream", version: "0.0.1" },
+    { capabilities: { tools: {} } },
+  );
+  upstreamServer.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      { name: "read_thing", description: "Read a thing", inputSchema: { type: "object" } },
+      { name: "write_thing", description: "Write a thing", inputSchema: { type: "object" } },
+      { name: "mystery_tool", description: "Unclassified surface", inputSchema: { type: "object" } },
+    ],
+  }));
+  upstreamServer.setRequestHandler(CallToolRequestSchema, async (request) => ({
+    content: [{ type: "text", text: `executed ${request.params.name}` }],
+  }));
+
+  const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
+  await upstreamServer.connect(serverSide);
+  const upstreamClient = new Client(
+    { name: "test-upstream-client", version: "0.0.1" },
+    { capabilities: {} },
+  );
+  await upstreamClient.connect(clientSide);
+  return { upstreamServer, upstreamClient };
+}
+
+async function startTestProxy({ shadowDiscovery, storagePath } = {}) {
+  const auditLog = [];
+  const receipts = [];
+  const upstream = await buildFakeUpstream();
+  const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
+  const consumerClient = new Client(
+    { name: "test-consumer", version: "0.0.1" },
+    { capabilities: {} },
+  );
+
+  const resolvedStoragePath =
+    storagePath === undefined
+      ? await fs.mkdtemp(path.join(os.tmpdir(), "strix-shadow-e2e-"))
+      : storagePath;
+
+  const handle = await startProxy({
+    serverId: "demo",
+    capabilities: SAMPLE_CAPS,
+    // ALLOW everything so the governed pipeline exercises real calls;
+    // mystery_tool has no capability row and rides the gateway's
+    // generic classification — exactly the case shadow discovery exists
+    // to surface.
+    policy: {
+      rules: {
+        "mcp.demo.read_thing": "ALLOW",
+        "mcp.demo.write_thing": "ALLOW",
+        "mcp.demo.mystery_tool": "ALLOW",
+      },
+      default: "ALLOW",
+    },
+    storagePath: resolvedStoragePath,
+    shadowDiscovery,
+    onReceipt: (r) => receipts.push(r),
+    onAudit: (e) => auditLog.push(e),
+    transport: {
+      kind: "test",
+      upstreamClient: upstream.upstreamClient,
+      serverTransport: serverSide,
+    },
+  });
+  await consumerClient.connect(clientSide);
+
+  return {
+    consumer: consumerClient,
+    proxy: handle,
+    auditLog,
+    receipts,
+    storagePath: resolvedStoragePath,
+    cleanup: async () => {
+      try { await consumerClient.close(); } catch { /* */ }
+      try { await handle.stop(); } catch { /* */ }
+      try { await upstream.upstreamServer.close(); } catch { /* */ }
+      if (resolvedStoragePath) {
+        try { await fs.rm(resolvedStoragePath, { recursive: true, force: true }); } catch { /* */ }
+      }
+    },
+  };
+}
+
+test("startup seed records the upstream's unclassified surface", async () => {
+  const t = await startTestProxy();
+  try {
+    const snap = t.proxy.shadowDiscovery.snapshot();
+    assert.equal(snap.advertisedToolCount, 3);
+    assert.deepEqual(snap.unclassifiedAdvertised, ["mystery_tool"]);
+    assert.equal(snap.measurement, SHADOW_MEASUREMENT_DISCLAIMER);
+    // The startup seed already audited the unclassified tool.
+    const seeded = t.auditLog.filter((e) => e.kind === "shadow.unclassified-tools");
+    assert.equal(seeded.length, 1);
+    assert.deepEqual(seeded[0].detail.tools, ["mystery_tool"]);
+  } finally {
+    await t.cleanup();
+  }
+});
+
+test("real MCP traffic through the proxy lands in the shadow report", async () => {
+  const t = await startTestProxy();
+  try {
+    await t.consumer.listTools();
+    await t.consumer.callTool({ name: "read_thing", arguments: {} });
+    await t.consumer.callTool({ name: "read_thing", arguments: {} });
+    await t.consumer.callTool({ name: "mystery_tool", arguments: {} });
+
+    const snap = t.proxy.shadowDiscovery.snapshot();
+    assert.deepEqual(snap.callCounts, { read_thing: 2, mystery_tool: 1 });
+    assert.deepEqual(snap.unclassifiedCallCounts, { mystery_tool: 1 });
+
+    // The shadow JSONL exists under the receipt store and every line is
+    // measurement-stamped.
+    const raw = await fs.readFile(t.proxy.shadowDiscoveryLogPath, "utf8");
+    const lines = raw.trim().split("\n").map((l) => JSON.parse(l));
+    assert.ok(lines.length >= 2);
+    for (const line of lines) {
+      assert.equal(line.measurement, SHADOW_MEASUREMENT_DISCLAIMER);
+    }
+  } finally {
+    await t.cleanup();
+  }
+});
+
+test("observation never perturbs governance: receipts still flow for governed calls", async () => {
+  const t = await startTestProxy();
+  try {
+    await t.consumer.callTool({ name: "write_thing", arguments: { v: 1 } });
+    assert.ok(t.receipts.length >= 1, "governed call should still emit a receipt");
+    // ...and the receipt pipeline's output is not shadow-shaped.
+    assert.equal("measurement" in t.receipts[0], false);
+  } finally {
+    await t.cleanup();
+  }
+});
+
+test("shadowDiscovery: false opts out cleanly", async () => {
+  const t = await startTestProxy({ shadowDiscovery: false });
+  try {
+    assert.equal(t.proxy.shadowDiscovery, null);
+    assert.equal(t.proxy.shadowDiscoveryLogPath, null);
+    // Traffic still flows.
+    const out = await t.consumer.callTool({ name: "read_thing", arguments: {} });
+    assert.ok(out);
+  } finally {
+    await t.cleanup();
+  }
+});

package/test/shadow-discovery.test.mjs

@@ -0,0 +1,137 @@
+/**
+ * Unit tests for shadow discovery (GSD-1 Phase 4) — the runtime
+ * reconciliation layer over static governed-surface discovery.
+ *
+ * The two honesty rules under test:
+ *   1. Observation only — the recorder never throws into the call path.
+ *   2. Unsigned measurement, never proof — every snapshot and every log
+ *      line carries the disclaimer and nothing receipt-shaped.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+import {
+  createShadowDiscovery,
+  SHADOW_LOG_BASENAME,
+  SHADOW_MEASUREMENT_DISCLAIMER,
+} from "../src/shadow-discovery.mjs";
+
+const CAPS = [
+  { id: "mcp.demo.read_thing", name: "read_thing", risk: "LOW", mode: "READ" },
+  { id: "mcp.demo.write_thing", name: "write_thing", risk: "MEDIUM", mode: "WRITE" },
+];
+
+test("advertised tools split into classified vs unclassified", () => {
+  const shadow = createShadowDiscovery({ serverId: "demo", capabilities: CAPS });
+  shadow.recordToolList([
+    { name: "read_thing", description: "classified" },
+    { name: "write_thing", description: "classified" },
+    { name: "mystery_tool", description: "nobody classified this" },
+  ]);
+  const snap = shadow.snapshot();
+  assert.equal(snap.advertisedToolCount, 3);
+  assert.equal(snap.classifiedCapabilityCount, 2);
+  assert.deepEqual(snap.unclassifiedAdvertised, ["mystery_tool"]);
+});
+
+test("calls are counted; unclassified calls surface separately", () => {
+  const shadow = createShadowDiscovery({ serverId: "demo", capabilities: CAPS });
+  shadow.recordCall("read_thing");
+  shadow.recordCall("read_thing");
+  shadow.recordCall("mystery_tool");
+  const snap = shadow.snapshot();
+  assert.deepEqual(snap.callCounts, { read_thing: 2, mystery_tool: 1 });
+  assert.deepEqual(snap.unclassifiedCallCounts, { mystery_tool: 1 });
+});
+
+test("audit events fire once per unclassified tool, not per call", () => {
+  const events = [];
+  const shadow = createShadowDiscovery({
+    serverId: "demo",
+    capabilities: CAPS,
+    onAudit: (e) => events.push(e),
+  });
+  shadow.recordCall("mystery_tool");
+  shadow.recordCall("mystery_tool");
+  shadow.recordCall("mystery_tool");
+  const unclassified = events.filter((e) => e.kind === "shadow.unclassified-call");
+  assert.equal(unclassified.length, 1);
+  assert.equal(unclassified[0].detail.tool, "mystery_tool");
+});
+
+test("every snapshot carries the measurement disclaimer and nothing receipt-shaped", () => {
+  const shadow = createShadowDiscovery({ serverId: "demo", capabilities: CAPS });
+  shadow.recordCall("mystery_tool");
+  const snap = shadow.snapshot();
+  assert.equal(snap.measurement, SHADOW_MEASUREMENT_DISCLAIMER);
+  for (const forbidden of ["signature", "signingKeyId", "kid", "canonical", "receiptId"]) {
+    assert.equal(forbidden in snap, false, `snapshot must not carry ${forbidden}`);
+  }
+});
+
+test("JSONL shadow log is written under storagePath with the disclaimer on every line", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "strix-shadow-test-"));
+  const shadow = createShadowDiscovery({
+    serverId: "demo",
+    capabilities: CAPS,
+    storagePath: dir,
+    now: () => "2026-07-12T00:00:00.000Z",
+  });
+  shadow.recordToolList([{ name: "mystery_tool" }]);
+  shadow.recordCall("mystery_tool");
+
+  assert.equal(shadow.logPath, path.join(dir, SHADOW_LOG_BASENAME));
+  const lines = (await fs.readFile(shadow.logPath, "utf8")).trim().split("\n");
+  assert.equal(lines.length, 2);
+  const parsed = lines.map((l) => JSON.parse(l));
+  for (const entry of parsed) {
+    assert.equal(entry.measurement, SHADOW_MEASUREMENT_DISCLAIMER);
+    assert.equal(entry.serverId, "demo");
+    assert.equal(entry.at, "2026-07-12T00:00:00.000Z");
+  }
+  assert.equal(parsed[0].kind, "tool-list");
+  assert.deepEqual(parsed[0].unclassified, ["mystery_tool"]);
+  assert.equal(parsed[1].kind, "unclassified-call");
+  assert.equal(parsed[1].tool, "mystery_tool");
+
+  await fs.rm(dir, { recursive: true, force: true });
+});
+
+test("no storagePath → no log file, snapshot still works", () => {
+  const shadow = createShadowDiscovery({ serverId: "demo", capabilities: CAPS });
+  assert.equal(shadow.logPath, null);
+  shadow.recordCall("mystery_tool");
+  assert.equal(shadow.snapshot().unclassifiedCallCounts.mystery_tool, 1);
+});
+
+test("recorder is defensive: malformed input never throws", () => {
+  const shadow = createShadowDiscovery({ serverId: "demo" });
+  shadow.recordToolList(undefined);
+  shadow.recordToolList([{ notAName: true }, null, { name: "" }]);
+  shadow.recordCall(undefined);
+  shadow.recordCall("");
+  shadow.recordCall(42);
+  const snap = shadow.snapshot();
+  assert.equal(snap.advertisedToolCount, 0);
+  assert.deepEqual(snap.callCounts, {});
+});
+
+test("a throwing onAudit handler never propagates into the call path", () => {
+  const shadow = createShadowDiscovery({
+    serverId: "demo",
+    onAudit: () => {
+      throw new Error("audit handler bug");
+    },
+  });
+  assert.doesNotThrow(() => shadow.recordCall("mystery_tool"));
+});
+
+test("no capabilities configured → every tool reports unclassified", () => {
+  const shadow = createShadowDiscovery({ serverId: "demo" });
+  shadow.recordToolList([{ name: "a" }, { name: "b" }]);
+  assert.deepEqual(shadow.snapshot().unclassifiedAdvertised, ["a", "b"]);
+});

package/test/webhook-approver.test.mjs

@@ -0,0 +1,197 @@
+/**
+ * Webhook approval channel — the Slack-compatible notification adapter on
+ * top of the gateway's file approver.
+ *
+ * Pins the load-bearing failure semantics:
+ *   - a delivered notification carries the Slack `text` + structured
+ *     `strix` block, and the decision STILL flows through the response
+ *     file (approve + deny);
+ *   - an unreachable webhook endpoint never approves and never
+ *     auto-denies — the file decision path keeps working;
+ *   - bad config (missing/invalid webhookUrl) fails at construction,
+ *     not at first call.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import http from "node:http";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { buildWebhookPayload, webhookApprover } from "../src/webhook-approver.mjs";
+
+const CAP = { id: "notion.pages.create", name: "Create page", risk: "MEDIUM", mode: "APPROVAL_REQUIRED" };
+const INV = { capabilityId: "notion.pages.create", action: "call", args: { title: "hi" }, actorId: "agent-1" };
+
+async function tmpDir() {
+  return await fs.mkdtemp(path.join(os.tmpdir(), "strix-webhook-approver-"));
+}
+
+/** Start a capture server on 127.0.0.1; returns { url, bodies, close }. */
+function captureServer() {
+  const bodies = [];
+  const server = http.createServer((req, res) => {
+    let raw = "";
+    req.on("data", (c) => (raw += c));
+    req.on("end", () => {
+      bodies.push(JSON.parse(raw));
+      res.writeHead(200).end("ok");
+    });
+  });
+  return new Promise((resolve) => {
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      resolve({
+        url: `http://127.0.0.1:${port}/hook`,
+        bodies,
+        close: () => new Promise((r) => server.close(r)),
+      });
+    });
+  });
+}
+
+/** Watch requestDir for the request file, then write the response file. */
+async function respondWhenAsked(requestDir, response, { pollMs = 25, timeoutMs = 5_000 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const entries = await fs.readdir(requestDir).catch(() => []);
+    const req = entries.find((e) => e.endsWith(".request.json"));
+    if (req) {
+      const requestId = req.replace(".request.json", "");
+      await fs.writeFile(
+        path.join(requestDir, `${requestId}.response.json`),
+        JSON.stringify(response),
+      );
+      return requestId;
+    }
+    await new Promise((r) => setTimeout(r, pollMs));
+  }
+  throw new Error("no request file appeared");
+}
+
+test("buildWebhookPayload is Slack-compatible and carries the structured strix block", () => {
+  const payload = buildWebhookPayload({
+    requestId: "abc123",
+    serverId: "notion",
+    capability: CAP,
+    invocation: INV,
+  });
+  assert.equal(typeof payload.text, "string"); // Slack incoming-webhook contract
+  assert.match(payload.text, /approval required/i);
+  assert.match(payload.text, /notion\.pages\.create/);
+  assert.match(payload.text, /guard approve abc123/);
+  assert.match(payload.text, /guard deny abc123/);
+  assert.deepEqual(payload.strix, {
+    kind: "approval.requested",
+    requestId: "abc123",
+    serverId: "notion",
+    capabilityId: "notion.pages.create",
+    risk: "MEDIUM",
+    action: "call",
+  });
+});
+
+test("notifies the webhook and approves via the response file", async () => {
+  const hook = await captureServer();
+  const requestDir = await tmpDir();
+  const events = [];
+  try {
+    const prompt = webhookApprover({
+      webhookUrl: hook.url,
+      serverId: "notion",
+      requestDir,
+      timeoutMs: 5_000,
+      pollIntervalMs: 25,
+      onAudit: (e) => events.push(e),
+    });
+
+    const responder = respondWhenAsked(requestDir, { approved: true, approvedBy: "alice" });
+    const result = await prompt(CAP, INV, {});
+    await responder;
+
+    assert.equal(result.approved, true);
+    assert.equal(result.approvedBy, "alice");
+
+    assert.equal(hook.bodies.length, 1);
+    assert.match(hook.bodies[0].text, /notion\.pages\.create/);
+    assert.equal(hook.bodies[0].strix.serverId, "notion");
+    assert.ok(events.some((e) => e.kind === "approval.webhook.notified"));
+  } finally {
+    await hook.close();
+    await fs.rm(requestDir, { recursive: true, force: true });
+  }
+});
+
+test("denies via the response file (webhook delivered)", async () => {
+  const hook = await captureServer();
+  const requestDir = await tmpDir();
+  try {
+    const prompt = webhookApprover({
+      webhookUrl: hook.url,
+      requestDir,
+      timeoutMs: 5_000,
+      pollIntervalMs: 25,
+    });
+    const responder = respondWhenAsked(requestDir, { approved: false });
+    const result = await prompt(CAP, INV, {});
+    await responder;
+    assert.equal(result.approved, false);
+    assert.equal(result.reason, "USER_DENIED");
+  } finally {
+    await hook.close();
+    await fs.rm(requestDir, { recursive: true, force: true });
+  }
+});
+
+test("unreachable webhook never approves and never auto-denies — file decision still works", async () => {
+  const requestDir = await tmpDir();
+  const events = [];
+  try {
+    const prompt = webhookApprover({
+      // Nothing listens here — connection refused on first packet.
+      webhookUrl: "http://127.0.0.1:1/hook",
+      requestDir,
+      timeoutMs: 5_000,
+      pollIntervalMs: 25,
+      onAudit: (e) => events.push(e),
+    });
+    const responder = respondWhenAsked(requestDir, { approved: true, approvedBy: "bob" });
+    const result = await prompt(CAP, INV, {});
+    await responder;
+    // The human decision carried the day despite the lost notification.
+    assert.equal(result.approved, true);
+    assert.ok(events.some((e) => e.kind === "approval.webhook.notify_failed"));
+  } finally {
+    await fs.rm(requestDir, { recursive: true, force: true });
+  }
+});
+
+test("times out to DENY when nobody responds (decision semantics unchanged)", async () => {
+  const hook = await captureServer();
+  const requestDir = await tmpDir();
+  try {
+    const prompt = webhookApprover({
+      webhookUrl: hook.url,
+      requestDir,
+      timeoutMs: 300,
+      pollIntervalMs: 25,
+    });
+    const result = await prompt(CAP, INV, {});
+    assert.equal(result.approved, false);
+  } finally {
+    await hook.close();
+    await fs.rm(requestDir, { recursive: true, force: true });
+  }
+});
+
+test("fails at construction on missing or non-http(s) webhookUrl", () => {
+  assert.throws(() => webhookApprover({ requestDir: "." }), /requires approval\.webhookUrl/);
+  assert.throws(
+    () => webhookApprover({ webhookUrl: "not a url", requestDir: "." }),
+    /not a valid URL/,
+  );
+  assert.throws(
+    () => webhookApprover({ webhookUrl: "ftp://example.com/x", requestDir: "." }),
+    /must be http\(s\)/,
+  );
+});