@polygraphso/litmus 0.2.1 → 0.4.0

package/README.md

@@ -5,9 +5,8 @@ The behavioral **litmus** harness for MCP servers, from [polygraph.so](https://p
 It connects to an MCP server the way an agent would, fingerprints its exact tool
 surface, and runs three probe categories — **C-01** tool-output injection, **C-02**
 permission/egress (in a hardened default-deny Docker sandbox), **C-03**
-sensitive-data handling (planted canaries) — then grades the server **A–F**. With
-an API URL configured it pins a deterministic evidence bundle and hands off to a
-browser flow where you sign an onchain EAS attestation on Base.
+sensitive-data handling (planted canaries) — then grades the server **A–F** and
+produces a deterministic, content-addressed evidence bundle.
 
 A passing grade is a measurement, not a guarantee. The methodology and its
 disclosed limits live at [polygraph.so](https://polygraph.so).
@@ -29,7 +28,6 @@ and the grade is capped at **B** for that run.
 ```bash
 polygraphso-litmus litmus <registry-ref | https-url | path-to-mcp>   # grade a server
 polygraphso-litmus litmus --json <ref>                              # machine-readable evidence bundle
-polygraphso-litmus challenge <attestation-uid> <ref>                # re-run to dispute a published grade
 polygraphso-litmus check <ref>                                      # look up a published grade
 ```
 
@@ -41,7 +39,9 @@ polygraphso-litmus litmus https://example.com/mcp
 ```
 
 The `litmus` command exits non-zero on a failing grade (D/F), so it scripts in CI.
-Set `POLYGRAPH_API_URL` to pin the evidence bundle and print a mint hand-off link.
+
+To dispute a published grade, just re-run `litmus` against the same server: the harness is
+open and deterministic, so a re-run reproduces the grade — or refutes it.
 
 ## Use it from an AI agent (MCP server)
 
@@ -49,13 +49,13 @@ The package ships a stdio MCP server, `polygraphso-litmus-mcp`, so it works in a
 MCP-capable client. It exposes two tools:
 
 - **`run_litmus`** — actively grade a server *now* (runs the harness end-to-end),
-  and return the grade, the evidence, and a mint hand-off URL.
+  and return the grade and the evidence.
 - **`verify_attestation`** — passively read a server's *already-published* grade
   before trusting or paying it.
 
 **Prerequisites:** Node ≥ 18. Docker is optional (without it, C-02 egress is
-skipped and the grade caps at B). Set `POLYGRAPH_API_URL=https://polygraph.so` to
-enable the pin + mint hand-off.
+skipped and the grade caps at B). Set `POLYGRAPH_API_URL=https://polygraph.so` so
+`verify_attestation` can resolve a server's published grade.
 
 Add the server once, then just talk to your agent.
 
@@ -90,15 +90,12 @@ claude mcp add polygraph-litmus -e POLYGRAPH_API_URL=https://polygraph.so \
 > Run polygraph against `npm/@modelcontextprotocol/server-filesystem` and tell me the grade.
 
 The agent calls **`run_litmus`**, which launches that server in the harness, runs
-C-01/C-02/C-03, and returns the **grade (A–F)**, the per-category results, the
-tool-surface fingerprint, and — when `POLYGRAPH_API_URL` is set — a **`mint` URL**.
-Open that URL in a browser, connect your wallet, and sign to publish the grade
-onchain as an EAS attestation. Signing is intentionally **not** headless: the agent
-does the work, you approve the mint. Use **`verify_attestation`** instead to read a
-grade that's already published.
+C-01/C-02/C-03, and returns the **grade (A–F)**, the per-category results, and the
+tool-surface fingerprint. Use **`verify_attestation`** instead to read a grade
+that's already published.
 
 `run_litmus` launches the target server's code to exercise it (egress-sandboxed
-when Docker is present). It needs no wallet or RPC; only minting does.
+when Docker is present). It needs no wallet or RPC.
 
 ## Library
 

package/dist/{chunk-SAZKXB35.js → chunk-K7UEK2BA.js}

@@ -1,6 +1,6 @@
 // ../core/src/types.ts
-var METHODOLOGY_VERSION = "litmus-v2";
-var BUNDLE_SCHEMA_VERSION = "1.1.0";
+var METHODOLOGY_VERSION = "litmus-v3";
+var BUNDLE_SCHEMA_VERSION = "1.2.0";
 var CATEGORY_STATUS_UINT8 = {
   pass: 0,
   fail: 1,

package/dist/{chunk-2K6T4FZX.js → chunk-MB5EPL2V.js}

@@ -3,10 +3,10 @@ import {
   METHODOLOGY_VERSION,
   parseServerRef,
   serverKey
-} from "./chunk-SAZKXB35.js";
+} from "./chunk-K7UEK2BA.js";
 
 // ../probes/src/harness.ts
-import { execFile as execFile2 } from "child_process";
+import { execFile as execFile3 } from "child_process";
 
 // ../probes/src/connect/index.ts
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -138,7 +138,7 @@ function resolveDockerDir() {
   }
   return fileURLToPath(new URL("../../docker", import.meta.url));
 }
-var RESOLVER_SCRIPT = `const p=require("path");const d="/stage/node_modules/"+process.argv[1];let j;try{j=require(d+'/package.json')}catch{}let entry=null;if(j){const b=j.bin;const r=typeof b==="string"?b:(b&&Object.values(b)[0]);if(r)entry=p.join(d,r);}const version=j&&j.version?j.version:null;process.stdout.write(JSON.stringify({entry,version}));`;
+var RESOLVER_SCRIPT = `const p=require("path");const n=process.argv[1];const d="/stage/node_modules/"+n;let j;try{j=require(d+'/package.json')}catch{}let bins={};if(j){const b=j.bin;if(typeof b==="string"){bins[n.replace(/^@[^/]+\\//,"")]=p.join(d,b);}else if(b){for(const k in b){bins[k]=p.join(d,b[k]);}}}const version=j&&j.version?j.version:null;let declaredEgress=[];if(j&&j.polygraph&&Array.isArray(j.polygraph.egress)){declaredEgress=j.polygraph.egress.filter(function(x){return typeof x==="string"});}process.stdout.write(JSON.stringify({bins,version,declaredEgress}));`;
 function labelFlags(runLabel) {
   return runLabel ? ["--label", `${LABEL_KEY}=${runLabel}`] : [];
 }
@@ -211,12 +211,16 @@ function resolverRunArgs(vol, image, pkgName, runLabel, runtime) {
 function parseResolverOutput(output) {
   try {
     const rec = JSON.parse(output);
-    return {
-      entry: typeof rec.entry === "string" ? rec.entry : null,
-      version: typeof rec.version === "string" ? rec.version : null
-    };
+    const bins = {};
+    if (rec.bins && typeof rec.bins === "object" && !Array.isArray(rec.bins)) {
+      for (const [k, v] of Object.entries(rec.bins)) {
+        if (typeof v === "string") bins[k] = v;
+      }
+    }
+    const declaredEgress = Array.isArray(rec.declaredEgress) ? rec.declaredEgress.filter((x) => typeof x === "string") : [];
+    return { bins, version: typeof rec.version === "string" ? rec.version : null, declaredEgress };
   } catch {
-    return { entry: null, version: null };
+    return { bins: {}, version: null, declaredEgress: [] };
   }
 }
 function buildImageArgs(pull) {
@@ -250,13 +254,13 @@ async function stageInto(vol, image, spec, pkgName, opts) {
   try {
     await docker(stageInstallArgs(vol, image, spec, opts.runLabel, runtime), 18e4);
     const resolved = parseResolverOutput((await docker(resolverRunArgs(vol, image, pkgName, opts.runLabel, runtime))).trim());
-    if (!resolved.entry) {
+    if (Object.keys(resolved.bins).length === 0) {
       await cleanup();
       throw new Error(
         `target package ${pkgName} exposes no launchable bin under the sandbox policy (install scripts are skipped)`
       );
     }
-    return { volume: vol, entry: resolved.entry, resolvedVersion: resolved.version, cleanup };
+    return { volume: vol, bins: resolved.bins, resolvedVersion: resolved.version, declaredEgress: resolved.declaredEgress, cleanup };
   } catch (err) {
     await cleanup();
     throw err;
@@ -397,125 +401,228 @@ function resolveStagedVersion(requested, staged) {
   return staged;
 }
 
+// ../probes/src/connect/bin-candidates.ts
+var MCP_NAME = /mcp/i;
+function orderBinCandidates(binNames, pkgName) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  const take = (name) => {
+    if (!seen.has(name)) {
+      seen.add(name);
+      out.push(name);
+    }
+  };
+  for (const n of binNames) if (MCP_NAME.test(n)) take(n);
+  for (const n of binNames) if (n === pkgName) take(n);
+  for (const n of binNames) take(n);
+  return out;
+}
+function parseNpmBins(stdout, pkgName) {
+  const trimmed = stdout.trim();
+  if (!trimmed) return [];
+  let v;
+  try {
+    v = JSON.parse(trimmed);
+  } catch {
+    return [];
+  }
+  if (typeof v === "string") return [pkgName];
+  if (v && typeof v === "object" && !Array.isArray(v)) return Object.keys(v);
+  return [];
+}
+var NoMcpBinError = class extends Error {
+  constructor(ref, tried) {
+    super(
+      `${ref}: no bin spoke MCP \u2014 tried ${tried.length ? tried.join(", ") : "no launchable bins"}. The target must be an MCP server; a CLI-only package can't be graded.`
+    );
+    this.name = "NoMcpBinError";
+  }
+};
+async function probeForMcpBin(ref, candidates, attempt) {
+  for (const bin of candidates) {
+    const result = await attempt(bin);
+    if (result !== null) return { bin, result };
+  }
+  throw new NoMcpBinError(ref, candidates);
+}
+
 // ../probes/src/connect/index.ts
+import { execFile as execFile2 } from "child_process";
+import { promisify } from "util";
 import { randomUUID as randomUUID3 } from "crypto";
+var execFileP = promisify(execFile2);
 var CLIENT_INFO = { name: "polygraph-litmus", version: "0.0.0" };
 async function connectTarget(input, opts = {}) {
   const isolated = opts.isolation === "docker";
-  let kind;
-  let descriptor;
-  let serverRef;
-  let resolvedVersion = null;
-  let transport;
-  const teardownExtra = [];
   if (typeof input !== "string") {
     if (isolated) {
       throw new IsolationUnsupportedError(
         "docker isolation is unsupported for an explicit stdio command \u2014 only an npm ref can be containerized"
       );
     }
-    kind = "stdio";
-    transport = new StdioClientTransport({
+    const transport2 = new StdioClientTransport({
       command: input.command,
       args: input.args ?? [],
       env: { ...getDefaultEnvironment(), ...opts.seedEnv ?? {}, ...input.env ?? {} },
       ...input.cwd ?? opts.seedCwd ? { cwd: input.cwd ?? opts.seedCwd } : {}
     });
     const cmdline = [input.command, ...input.args ?? []].join(" ");
-    descriptor = { kind, command: cmdline, url: null };
-    serverRef = input.serverRef ?? cmdline;
-  } else if (/^https?:\/\//i.test(input)) {
-    kind = "http";
+    const client2 = await connectOrThrow(transport2);
+    return makeResult(client2, "stdio", { kind: "stdio", command: cmdline, url: null }, input.serverRef ?? cmdline, null, []);
+  }
+  if (/^https?:\/\//i.test(input)) {
     await assertPublicHttpUrl(input);
     const headers = opts.httpHeaders && Object.keys(opts.httpHeaders).length > 0 ? opts.httpHeaders : void 0;
-    transport = new StreamableHTTPClientTransport(
+    const transport2 = new StreamableHTTPClientTransport(
       new URL(input),
       headers ? { requestInit: { headers }, fetch: sameOriginAuthFetch(input, headers) } : void 0
     );
-    descriptor = { kind, command: null, url: input };
-    serverRef = input;
-  } else {
-    const parsed = parseServerRef(input);
-    kind = "stdio";
-    if (isolated) {
-      if (parsed.registry !== "npm") {
-        throw new IsolationUnsupportedError(
-          `docker isolation is unsupported for ${parsed.registry} refs \u2014 only npm refs can be containerized`
-        );
-      }
-      const spec = (parsed.owner ? `${parsed.owner}/${parsed.name}` : parsed.name) + (parsed.version ? `@${parsed.version}` : "");
-      const stageOpts = opts.runLabel ? { runLabel: opts.runLabel } : {};
-      await ensureImage();
-      let staged = null;
-      let seed = null;
-      try {
-        staged = await stageNpmPackage(spec, stageOpts);
-        if (!opts.seedCwd) {
-          throw new Error("docker isolation requires a canary seed directory (seedCwd)");
-        }
-        seed = await prepareSeedVolume(opts.seedCwd, stageOpts);
-        const launch = containerLaunch({
-          entry: staged.entry,
-          stageVolume: staged.volume,
-          seedVolume: seed.volume,
-          // Canaries travel INTO the container via -e, NOT via the docker CLI's
-          // own env (the CLI runs on the secrets-bearing host).
-          canaryEnv: opts.seedEnv ?? {},
-          ...opts.runLabel ? { runLabel: opts.runLabel } : {},
-          ...process.env.LITMUS_DOCKER_RUNTIME ? { runtime: process.env.LITMUS_DOCKER_RUNTIME } : {}
-        });
-        const containerName = `pg-connect-${randomUUID3().slice(0, 8)}`;
-        const namedArgs = [launch.args[0], "--name", containerName, ...launch.args.slice(1)];
-        transport = new StdioClientTransport({
-          command: launch.command,
-          args: namedArgs,
-          // Default env only: no host secrets, no canaries (those are -e args).
-          env: getDefaultEnvironment()
-        });
-        descriptor = {
-          kind,
-          command: recordedContainerCommand(launch.command, launch.args, {
-            stageVolume: staged.volume,
-            seedVolume: seed.volume
-          }),
-          url: null
-        };
-        resolvedVersion = resolveStagedVersion(parsed.version, staged.resolvedVersion);
-        const stagedCleanup = staged.cleanup;
-        const seedCleanup = seed.cleanup;
-        teardownExtra.push(
-          () => docker(["rm", "-f", containerName]).then(() => {
-          }).catch(() => {
-          }),
-          stagedCleanup,
-          seedCleanup
-        );
-      } catch (err) {
-        if (seed) await seed.cleanup();
-        if (staged) await staged.cleanup();
-        throw err;
-      }
-      serverRef = serverKey(parsed);
-    } else {
-      const launch = launchForRef(parsed);
-      resolvedVersion = parsed.version ?? null;
-      transport = new StdioClientTransport({
+    const client2 = await connectOrThrow(transport2);
+    return makeResult(client2, "http", { kind: "http", command: null, url: input }, input, null, []);
+  }
+  const parsed = parseServerRef(input);
+  if (isolated) {
+    if (parsed.registry !== "npm") {
+      throw new IsolationUnsupportedError(
+        `docker isolation is unsupported for ${parsed.registry} refs \u2014 only npm refs can be containerized`
+      );
+    }
+    return connectIsolatedNpm(input, parsed, opts);
+  }
+  if (parsed.registry === "npm") {
+    return connectHostNpm(input, parsed, opts);
+  }
+  const launch = launchForRef(parsed);
+  const transport = new StdioClientTransport({
+    command: launch.command,
+    args: launch.args,
+    env: { ...getDefaultEnvironment(), ...opts.seedEnv ?? {} },
+    ...opts.seedCwd ? { cwd: opts.seedCwd } : {}
+  });
+  const client = await connectOrThrow(transport);
+  return makeResult(
+    client,
+    "stdio",
+    { kind: "stdio", command: [launch.command, ...launch.args].join(" "), url: null },
+    serverKey(parsed),
+    parsed.version ?? null,
+    []
+  );
+}
+async function connectHostNpm(ref, parsed, opts) {
+  const spec = (parsed.owner ? `${parsed.owner}/${parsed.name}` : parsed.name) + (parsed.version ? `@${parsed.version}` : "");
+  const serverRefVal = serverKey(parsed);
+  const resolvedVersion = parsed.version ?? null;
+  const env = { ...getDefaultEnvironment(), ...opts.seedEnv ?? {} };
+  const cwd = opts.seedCwd ? { cwd: opts.seedCwd } : {};
+  const binNames = await fetchNpmBins(spec, parsed.name);
+  if (!binNames || binNames.length === 0) {
+    const args = ["-y", spec];
+    const transport = new StdioClientTransport({ command: "npx", args, env, ...cwd });
+    const client = await connectOrThrow(transport);
+    return makeResult(client, "stdio", { kind: "stdio", command: ["npx", ...args].join(" "), url: null }, serverRefVal, resolvedVersion, []);
+  }
+  const candidates = orderBinCandidates(binNames, parsed.name);
+  const { result } = await probeForMcpBin(ref, candidates, async (bin) => {
+    const args = ["-y", "-p", spec, bin];
+    const transport = new StdioClientTransport({ command: "npx", args, env, ...cwd });
+    const client = await tryConnect(transport);
+    return client ? { client, descriptor: { kind: "stdio", command: ["npx", ...args].join(" "), url: null } } : null;
+  });
+  return makeResult(result.client, "stdio", result.descriptor, serverRefVal, resolvedVersion, []);
+}
+async function connectIsolatedNpm(ref, parsed, opts) {
+  const spec = (parsed.owner ? `${parsed.owner}/${parsed.name}` : parsed.name) + (parsed.version ? `@${parsed.version}` : "");
+  const stageOpts = opts.runLabel ? { runLabel: opts.runLabel } : {};
+  await ensureImage();
+  let staged = null;
+  let seed = null;
+  try {
+    staged = await stageNpmPackage(spec, stageOpts);
+    if (!opts.seedCwd) {
+      throw new Error("docker isolation requires a canary seed directory (seedCwd)");
+    }
+    seed = await prepareSeedVolume(opts.seedCwd, stageOpts);
+    const resolvedVersion = resolveStagedVersion(parsed.version, staged.resolvedVersion);
+    const stagedPkg = staged;
+    const seedVol = seed;
+    const candidates = orderBinCandidates(Object.keys(stagedPkg.bins), parsed.name);
+    const { result } = await probeForMcpBin(ref, candidates, async (binName) => {
+      const launch = containerLaunch({
+        entry: stagedPkg.bins[binName],
+        stageVolume: stagedPkg.volume,
+        seedVolume: seedVol.volume,
+        // Canaries travel INTO the container via -e, NOT via the docker CLI's own env.
+        canaryEnv: opts.seedEnv ?? {},
+        ...opts.runLabel ? { runLabel: opts.runLabel } : {},
+        ...process.env.LITMUS_DOCKER_RUNTIME ? { runtime: process.env.LITMUS_DOCKER_RUNTIME } : {}
+      });
+      const containerName = `pg-connect-${randomUUID3().slice(0, 8)}`;
+      const namedArgs = [launch.args[0], "--name", containerName, ...launch.args.slice(1)];
+      const transport = new StdioClientTransport({
         command: launch.command,
-        args: launch.args,
-        env: { ...getDefaultEnvironment(), ...opts.seedEnv ?? {} },
-        ...opts.seedCwd ? { cwd: opts.seedCwd } : {}
+        args: namedArgs,
+        env: getDefaultEnvironment()
+        // default env only: no host secrets, no canaries
       });
-      descriptor = { kind, command: [launch.command, ...launch.args].join(" "), url: null };
-      serverRef = serverKey(parsed);
-    }
+      const client = await tryConnect(transport);
+      if (!client) {
+        await docker(["rm", "-f", containerName]).then(() => {
+        }).catch(() => {
+        });
+        return null;
+      }
+      const descriptor = {
+        kind: "stdio",
+        command: recordedContainerCommand(launch.command, launch.args, {
+          stageVolume: stagedPkg.volume,
+          seedVolume: seedVol.volume
+        }),
+        url: null
+      };
+      return { client, descriptor, containerName };
+    });
+    const teardownExtra = [
+      () => docker(["rm", "-f", result.containerName]).then(() => {
+      }).catch(() => {
+      }),
+      staged.cleanup,
+      seed.cleanup
+    ];
+    return makeResult(result.client, "stdio", result.descriptor, serverKey(parsed), resolvedVersion, teardownExtra);
+  } catch (err) {
+    if (seed) await seed.cleanup();
+    if (staged) await staged.cleanup();
+    throw err;
+  }
+}
+async function fetchNpmBins(spec, pkgName) {
+  try {
+    const { stdout } = await execFileP("npm", ["view", spec, "bin", "--json"], { timeout: 2e4 });
+    return parseNpmBins(stdout, pkgName);
+  } catch {
+    return null;
   }
+}
+async function tryConnect(transport) {
   const client = new Client(CLIENT_INFO, { capabilities: {} });
   try {
     await withConnectTimeout(client.connect(transport), transport);
-  } catch (err) {
-    for (const c of teardownExtra) await c();
-    throw err;
+    return client;
+  } catch {
+    try {
+      await client.close();
+    } catch {
+    }
+    return null;
   }
+}
+async function connectOrThrow(transport) {
+  const client = new Client(CLIENT_INFO, { capabilities: {} });
+  await withConnectTimeout(client.connect(transport), transport);
+  return client;
+}
+function makeResult(client, kind, descriptor, serverRef, resolvedVersion, teardownExtra) {
   return {
     client,
     kind,
@@ -549,10 +656,6 @@ async function withConnectTimeout(connecting, transport) {
   }
 }
 function launchForRef(p) {
-  if (p.registry === "npm") {
-    const spec = (p.owner ? `${p.owner}/${p.name}` : p.name) + (p.version ? `@${p.version}` : "");
-    return { command: "npx", args: ["-y", spec] };
-  }
   if (p.registry === "pypi") {
     return { command: "uvx", args: [p.version ? `${p.name}@${p.version}` : p.name] };
   }
@@ -929,9 +1032,29 @@ async function c01Injection(ctx) {
 
 // ../probes/src/docker/egress-runner.ts
 import { randomUUID as randomUUID4 } from "crypto";
+
+// ../probes/src/probes/host-match.ts
+function normalizeHost(h) {
+  let s = h.trim().toLowerCase();
+  const colon = s.indexOf(":");
+  if (colon !== -1) s = s.slice(0, colon);
+  if (s.endsWith(".")) s = s.slice(0, -1);
+  return s;
+}
+function hostMatchesPattern(host, pattern) {
+  const h = normalizeHost(host);
+  const p = pattern.trim().toLowerCase();
+  if (p.startsWith("*.")) {
+    const suffix = p.slice(1);
+    return h.endsWith(suffix) && h.length > suffix.length;
+  }
+  return h === p;
+}
+
+// ../probes/src/docker/egress-runner.ts
 var IMAGE_TAG3 = "polygraph-egress-sniff:latest";
 function notRan(reason) {
-  return { ran: false, reason, attempts: [] };
+  return { ran: false, reason, attempts: [], declaredEgress: [], baselineAllowlist: [] };
 }
 function parseSinkholeOutput(output) {
   const attempts = [];
@@ -963,6 +1086,40 @@ function egressToFindings(attempts) {
     ...a.firstBytes !== void 0 ? { firstBytes: a.firstBytes } : {}
   }));
 }
+function correlateEgress(attempts) {
+  const pendingDnsHosts = [];
+  const out = [];
+  for (const a of attempts) {
+    if (a.kind === "dns") {
+      out.push({ ...a, hostSource: a.host ? "given" : "none" });
+      if (a.host) pendingDnsHosts.push(a.host);
+    } else if (a.host) {
+      out.push({ ...a, hostSource: "given" });
+    } else {
+      const host = pendingDnsHosts.shift();
+      out.push({ ...a, ...host ? { host } : {}, hostSource: host ? "dns-correlation" : "none" });
+    }
+  }
+  return out;
+}
+function classifyEgress(correlated, allowlist) {
+  return correlated.map((c) => {
+    if (c.host !== void 0) {
+      const matchedPattern = allowlist.find((p) => hostMatchesPattern(c.host, p));
+      return matchedPattern ? { ...c, allowed: true, matchedPattern } : { ...c, allowed: false };
+    }
+    return { ...c, allowed: false };
+  });
+}
+function egressAllowedFindings(classified) {
+  return classified.filter((c) => c.allowed).map((c) => ({
+    kind: "egress-allowed",
+    severity: "low",
+    match: `${c.host ?? "?"}${c.port ? `:${c.port}` : ""} (allowed: ${c.matchedPattern ?? "?"})`,
+    ...c.host !== void 0 ? { host: c.host } : {},
+    ...c.port !== void 0 ? { port: c.port } : {}
+  }));
+}
 function egressCanaryFindings(attempts, canaries) {
   const findings = [];
   for (const a of attempts) {
@@ -1041,7 +1198,8 @@ async function runEgressProbe(ref, opts) {
       if (msg.includes("exposes no launchable bin")) return notRan(msg);
       throw err;
     }
-    const { volume: vol, entry } = staged;
+    const vol = staged.volume;
+    const entry = staged.bins[orderBinCandidates(Object.keys(staged.bins), parsed.name)[0]];
     await docker(["network", "create", "--internal", ...label, net]);
     await docker([
       "run",
@@ -1081,7 +1239,13 @@ async function runEgressProbe(ref, opts) {
       await conn.teardown();
     }
     const logs = await docker(["logs", sink]);
-    return { ran: true, reason: null, attempts: parseSinkholeOutput(logs) };
+    return {
+      ran: true,
+      reason: null,
+      attempts: parseSinkholeOutput(logs),
+      declaredEgress: staged.declaredEgress,
+      baselineAllowlist: opts.baselineAllowlist ?? []
+    };
   } catch (err) {
     return notRan(`egress sandbox unavailable: ${err instanceof Error ? err.message : String(err)}`);
   } finally {
@@ -1095,6 +1259,28 @@ async function runEgressProbe(ref, opts) {
   }
 }
 
+// ../probes/src/probes/egress-allowlist.ts
+var DEFAULT_EGRESS_BASELINE = [];
+function normalizePattern(p) {
+  return p.trim().toLowerCase();
+}
+function parseAllowlistEnv(raw) {
+  if (!raw) return [];
+  return raw.split(",").map(normalizePattern).filter((s) => s.length > 0);
+}
+function effectiveAllowlist(baseline, declared) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const p of [...baseline, ...declared]) {
+    const n = normalizePattern(p);
+    if (n.length > 0 && !seen.has(n)) {
+      seen.add(n);
+      out.push(n);
+    }
+  }
+  return out;
+}
+
 // ../probes/src/probes/c02-egress.ts
 function probe21Declaration(tools) {
   const findings = [];
@@ -1113,8 +1299,18 @@ function probe21Declaration(tools) {
 }
 function probe22Egress(egress) {
   if (!egress.ran) return { id: "2.2", status: "skipped", findings: [], reason: egress.reason };
-  const findings = egressToFindings(egress.attempts);
-  return { id: "2.2", status: findings.length > 0 ? "fail" : "pass", findings };
+  const allowlist = effectiveAllowlist(egress.baselineAllowlist, egress.declaredEgress);
+  const classified = classifyEgress(correlateEgress(egress.attempts), allowlist);
+  const overreach = classified.filter((c) => !c.allowed);
+  const allowed = classified.filter((c) => c.allowed);
+  const findings = [...egressToFindings(overreach), ...egressAllowedFindings(allowed)];
+  if (overreach.length > 0) return { id: "2.2", status: "fail", findings };
+  return {
+    id: "2.2",
+    status: "pass",
+    findings,
+    reason: allowed.length > 0 ? `${allowed.length} declared/baseline egress attempt(s) permitted; 0 overreach` : null
+  };
 }
 function c02Permission(declaration, egress) {
   const egressProbe = probe22Egress(egress);
@@ -1245,11 +1441,14 @@ function gradeFromCategories(categories) {
   if (c02?.status === "fail") {
     return {
       grade: "D",
-      rationale: "Unexpected egress (C-02 failed); no injection or data leak. Egress is serious but not proven exfiltration, so the grade caps at D."
+      rationale: "Egress overreach (C-02 failed): reached a host outside its declared/baseline allowlist (or mislabeled a tool). No injection or data leak, so the grade caps at D."
     };
   }
   if (c01?.status === "pass" && c02?.status === "pass" && c03?.status === "pass") {
-    return { grade: "A", rationale: "All three categories passed. No injection, no unexpected egress, no data leak." };
+    return {
+      grade: "A",
+      rationale: "All three categories passed. No injection, no data leak, and no egress overreach \u2014 declared/baseline egress, if any, was permitted (A means no overreach, not no network)."
+    };
   }
   if (c01?.status === "pass") {
     const note = skipped.length ? ` Not verified: ${skipped.join(", ")} (${skipped.map((c) => byCode(c)?.reason).filter(Boolean).join("; ")}).` : "";
@@ -1304,6 +1503,7 @@ function assembleBundle(input) {
 async function runLitmus(target, opts = {}) {
   const isolation = opts.isolation ?? (process.env.LITMUS_STDIO_ISOLATION === "docker" ? "docker" : "none");
   const ranAt = (/* @__PURE__ */ new Date()).toISOString();
+  const baselineAllowlist = [...DEFAULT_EGRESS_BASELINE, ...parseAllowlistEnv(process.env.LITMUS_EGRESS_ALLOWLIST)];
   const dockerAvailable = await checkDocker();
   const canaries = mintCanaries();
   const seedEnv = canaryEnv(canaries);
@@ -1344,10 +1544,12 @@ async function runLitmus(target, opts = {}) {
         stateChangingTools,
         allowStateChanging: opts.allowStateChanging ?? false
       };
-      const egress = dockerAvailable && typeof target === "string" && !/^https?:\/\//i.test(target) ? await runEgressProbe(target, { canaryEnv: seedEnv, ...opts.runLabel ? { runLabel: opts.runLabel } : {} }) : {
+      const egress = dockerAvailable && typeof target === "string" && !/^https?:\/\//i.test(target) ? await runEgressProbe(target, { canaryEnv: seedEnv, baselineAllowlist, ...opts.runLabel ? { runLabel: opts.runLabel } : {} }) : {
         ran: false,
         reason: dockerAvailable ? "egress not run for this target" : "no sandbox (Docker unavailable)",
-        attempts: []
+        attempts: [],
+        declaredEgress: [],
+        baselineAllowlist: []
       };
       assertEgressRanUnderIsolation(egress, isolation, isStdio);
       const categories = [
@@ -1359,7 +1561,9 @@ async function runLitmus(target, opts = {}) {
       return assembleBundle({
         serverRef: conn.serverRef,
         resolvedVersion: conn.resolvedVersion,
-        target: conn.descriptor,
+        // Surface the server's declared egress in the bundle (disclosure: a
+        // declaration is not exoneration — the consumer/agent-gate can judge).
+        target: egress.declaredEgress.length ? { ...conn.descriptor, declaredEgress: egress.declaredEgress } : conn.descriptor,
         toolDefsFingerprint: fingerprint,
         toolDefs: canonical,
         categories,
@@ -1437,7 +1641,7 @@ function withTimeout(p, ms, label) {
 }
 function checkDocker() {
   return new Promise((resolve) => {
-    const child = execFile2("docker", ["info"], { timeout: 4e3 }, (err) => resolve(!err));
+    const child = execFile3("docker", ["info"], { timeout: 4e3 }, (err) => resolve(!err));
     child.on("error", () => resolve(false));
   });
 }

package/dist/{chunk-MQC54LFV.js → chunk-UA4BIHP4.js}

@@ -1,15 +1,13 @@
 import {
-  mintUrl,
-  pinBundle,
   resolveTarget
-} from "./chunk-6QM4RK25.js";
+} from "./chunk-WBXHDYIV.js";
 import {
   runLitmus
-} from "./chunk-2K6T4FZX.js";
+} from "./chunk-MB5EPL2V.js";
 import {
   CATEGORY_STATUS_UINT8,
   METHODOLOGY_VERSION
-} from "./chunk-SAZKXB35.js";
+} from "./chunk-K7UEK2BA.js";
 
 // ../onchain/src/networks.ts
 var NETWORKS = {
@@ -137,44 +135,23 @@ var RUN_LITMUS_TOOL_DESCRIPTION = [
   "for egress when Docker is available). It is not a passive lookup \u2014 for that,",
   "use `verify_attestation`. It needs no wallet or RPC.",
   "",
-  "When POLYGRAPH_API_URL is configured the evidence is pinned and the result",
-  "includes a `mint` URL: open it in a browser, connect a wallet, and sign to",
-  "publish the grade onchain as an EAS attestation. Signing is intentionally not",
-  "headless.",
-  "",
   "Input: server_ref \u2014 a registry ref (npm/@scope/server), an https:// MCP URL,",
   "or a local path to an MCP entry file. If Docker is unavailable, C-02 is",
   "skipped and the grade is capped at B for that run."
 ].join("\n");
 var runLitmusInputShape = {
-  server_ref: z.string().min(1).max(512).describe("What to grade: a registry ref (npm/@scope/server), an https:// MCP URL, or a local path to an MCP entry file."),
-  pin: z.boolean().optional().describe("When true (default) and POLYGRAPH_API_URL is set, pin the evidence and return a mint hand-off URL. Set false to grade only.")
+  server_ref: z.string().min(1).max(512).describe("What to grade: a registry ref (npm/@scope/server), an https:// MCP URL, or a local path to an MCP entry file.")
 };
-async function handleRunLitmus({ server_ref, pin }) {
+async function handleRunLitmus({ server_ref }) {
   try {
     const bundle = await runLitmus(resolveTarget(server_ref));
-    const payload = { ...summarize(bundle), mint: await mintHandoff(bundle, pin) };
+    const payload = summarize(bundle);
     return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return { isError: true, content: [{ type: "text", text: `run_litmus failed: ${message}` }] };
   }
 }
-async function mintHandoff(bundle, pin) {
-  if (pin === false || !process.env.POLYGRAPH_API_URL) {
-    return { available: false, reason: "Set POLYGRAPH_API_URL to pin the evidence and get a mint hand-off URL." };
-  }
-  try {
-    const cid = await pinBundle(bundle);
-    return {
-      url: mintUrl({ cid, ref: bundle.serverRef, fp: bundle.toolDefsFingerprint, ver: bundle.resolvedVersion }),
-      cid,
-      instruction: "Open this URL in a browser, connect your wallet, and sign to mint the onchain EAS attestation. Signing cannot be done headlessly."
-    };
-  } catch (err) {
-    return { available: false, reason: `pin failed: ${err instanceof Error ? err.message : String(err)}` };
-  }
-}
 function summarize(b) {
   const find = (code) => b.categories.find((c) => c.code === code);
   const categories = ["C-01", "C-02", "C-03"].map((code) => {

package/dist/{chunk-6QM4RK25.js → chunk-WBXHDYIV.js}

@@ -1,6 +1,6 @@
 import {
   canonicalStringify
-} from "./chunk-SAZKXB35.js";
+} from "./chunk-K7UEK2BA.js";
 
 // ../cli/src/litmus.ts
 import { existsSync } from "fs";
@@ -33,39 +33,6 @@ function truncate(s, n) {
   return s.length > n ? `${s.slice(0, n)}\u2026` : s;
 }
 
-// ../cli/src/api.ts
-var DEFAULT_BASE = "https://polygraph.so";
-function apiBaseUrl() {
-  const override = process.env.POLYGRAPH_API_URL;
-  if (!override || override.length === 0) return DEFAULT_BASE;
-  const trimmed = override.replace(/\/+$/, "");
-  let u;
-  try {
-    u = new URL(trimmed);
-  } catch {
-    throw new Error(`POLYGRAPH_API_URL is not a valid URL: ${override}`);
-  }
-  const isLoopback = u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "::1";
-  if (u.protocol !== "https:" && !(u.protocol === "http:" && isLoopback)) {
-    throw new Error(`POLYGRAPH_API_URL must use https (http allowed only for localhost): ${override}`);
-  }
-  return trimmed;
-}
-function pinUrl() {
-  return `${apiBaseUrl()}/api/pin`;
-}
-function attestationsUrl() {
-  return `${apiBaseUrl()}/api/attestations`;
-}
-function mintUrl(params) {
-  const u = new URL(`${apiBaseUrl()}/mint`);
-  u.searchParams.set("cid", params.cid);
-  u.searchParams.set("ref", params.ref);
-  u.searchParams.set("fp", params.fp);
-  if (params.ver) u.searchParams.set("ver", params.ver);
-  return u.toString();
-}
-
 // ../cli/src/litmus.ts
 async function runLitmusCli(args) {
   const json = args.includes("--json");
@@ -77,12 +44,11 @@ async function runLitmusCli(args) {
     );
     return 2;
   }
-  const { runLitmus } = await import("./src-XIEFSTXC.js");
+  const { runLitmus } = await import("./src-PTK3WEGQ.js");
   const input = resolveTarget(target);
   try {
     const bundle = await runLitmus(input, { headers, allowStateChanging });
     process.stdout.write(json ? canonicalStringify(bundle) + "\n" : formatBundle(bundle));
-    await maybePin(bundle, json);
     return bundle.grade === "D" || bundle.grade === "F" ? 1 : 0;
   } catch (err) {
     process.stderr.write(`\u2192 litmus failed: ${err instanceof Error ? err.message : String(err)}
@@ -144,37 +110,9 @@ function tsxCli() {
   const rel = typeof bin === "string" ? bin : bin.tsx ?? "./dist/cli.mjs";
   return path.join(dir, rel);
 }
-async function maybePin(bundle, json = false) {
-  if (!process.env.POLYGRAPH_API_URL) return;
-  const note = (line) => (json ? process.stderr : process.stdout).write(line);
-  try {
-    const cid = await pinBundle(bundle);
-    note(`\u2192 pinned ${cid}
-`);
-    note(`\u2192 mint ${mintUrl({ cid, ref: bundle.serverRef, fp: bundle.toolDefsFingerprint, ver: bundle.resolvedVersion })}
-`);
-  } catch (err) {
-    note(`\u2192 pin skipped: ${err instanceof Error ? err.message : String(err)}
-`);
-  }
-}
-async function pinBundle(bundle) {
-  const res = await fetch(pinUrl(), {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: canonicalStringify(bundle)
-  });
-  if (!res.ok) throw new Error(`pin endpoint returned ${res.status}`);
-  const data = await res.json();
-  if (!data.cid) throw new Error("pin response missing cid");
-  return data.cid;
-}
 
 export {
-  attestationsUrl,
-  mintUrl,
   runLitmusCli,
   parseAuthFlags,
-  resolveTarget,
-  pinBundle
+  resolveTarget
 };

package/dist/cli.js

@@ -1,18 +1,39 @@
 #!/usr/bin/env node
 import {
-  attestationsUrl,
   runLitmusCli
-} from "./chunk-6QM4RK25.js";
+} from "./chunk-WBXHDYIV.js";
 import {
   parseServerRef,
   serverKey
-} from "./chunk-SAZKXB35.js";
+} from "./chunk-K7UEK2BA.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
 
+// ../cli/src/api.ts
+var DEFAULT_BASE = "https://polygraph.so";
+function apiBaseUrl() {
+  const override = process.env.POLYGRAPH_API_URL;
+  if (!override || override.length === 0) return DEFAULT_BASE;
+  const trimmed = override.replace(/\/+$/, "");
+  let u;
+  try {
+    u = new URL(trimmed);
+  } catch {
+    throw new Error(`POLYGRAPH_API_URL is not a valid URL: ${override}`);
+  }
+  const isLoopback = u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "::1";
+  if (u.protocol !== "https:" && !(u.protocol === "http:" && isLoopback)) {
+    throw new Error(`POLYGRAPH_API_URL must use https (http allowed only for localhost): ${override}`);
+  }
+  return trimmed;
+}
+function attestationsUrl() {
+  return `${apiBaseUrl()}/api/attestations`;
+}
+
 // ../cli/src/check.ts
 function checkQuery(rawRef) {
   try {

package/dist/index.d.ts

@@ -11,13 +11,16 @@ import { z } from 'zod';
 /** Package registries a server ref can name. */
 type Registry = "npm" | "pypi" | "github";
 /** The methodology this build implements; embedded in every bundle + attestation.
- *  v2 adds C-02 probe 2.1 (declared-permission honesty), a new fail condition —
- *  a pass/fail-semantics change, so the version bumps per litmus-test §8. */
-declare const METHODOLOGY_VERSION: "litmus-v2";
+ *  v3 reframes C-02 probe 2.2 from default-deny (any egress fails) to OVERREACH:
+ *  egress to a host the server declared (`polygraph.egress`) or on the operator
+ *  baseline allowlist is permitted; only egress beyond that union fails. A
+ *  pass/fail-semantics change → version bumps per litmus-test §8. NOTE: under v3,
+ *  grade "A" means "no overreach", NOT "no network". (v2 added probe 2.1.) */
+declare const METHODOLOGY_VERSION: "litmus-v3";
 /** Evidence-bundle format version (owned by onchain-proof-spec §2).
- *  1.1.0 adds the optional `harness.stdioIsolation` field and permits the
- *  disclaimer to vary by run mode; 1.0.0 bundles remain valid. */
-declare const BUNDLE_SCHEMA_VERSION: "1.1.0";
+ *  1.2.0 adds the optional `target.declaredEgress` field and the `egress-allowed`
+ *  finding kind (litmus-v3); 1.1.0 adds `harness.stdioIsolation`; older remain valid. */
+declare const BUNDLE_SCHEMA_VERSION: "1.2.0";
 type CategoryCode = "C-01" | "C-02" | "C-03" | "C-04";
 /** Probe IDs carry their family number (1=injection, 2=permission, 4=sensitive). */
 type ProbeId = "1.1" | "1.2" | "2.1" | "2.2" | "4.1" | "4.2";
@@ -27,7 +30,7 @@ type LitmusGrade = "A" | "B" | "C" | "D" | "F";
 type Severity = "low" | "medium" | "high";
 /** uint8 encoding for per-category verdicts on the attestation (onchain-proof-spec §5). */
 declare const CATEGORY_STATUS_UINT8: Record<CategoryStatus, number>;
-type FindingKind = "invisible-unicode" | "instruction-mimicry" | "markdown-trick" | "canary" | "egress" | "permission-mislabel";
+type FindingKind = "invisible-unicode" | "instruction-mimicry" | "markdown-trick" | "canary" | "egress" | "egress-allowed" | "permission-mislabel";
 interface Finding {
     kind: FindingKind;
     severity: Severity;
@@ -61,6 +64,9 @@ interface TargetDescriptor {
     command?: string | null;
     /** http: the remote MCP URL. */
     url?: string | null;
+    /** The server's declared egress host patterns (`polygraph.egress`, C-02
+     *  litmus-v3). Present only when non-empty. Disclosure, not exoneration. */
+    declaredEgress?: string[];
 }
 /** The canonicalized fields of a tool that the fingerprint hashes. */
 interface ToolDef {
@@ -159,6 +165,11 @@ declare function canonicalStringify(value: unknown): string;
  * - an explicit `{command,args}` (for in-repo demo servers and tests) launches
  *   over stdio directly.
  *
+ * For an npm ref the package may ship several bins (e.g. a CLI plus a `*-mcp`
+ * server) or a default bin that isn't an MCP server. We enumerate the bins and
+ * PROBE them in order (mcp-named first), keeping the first that completes the MCP
+ * handshake — so a CLI-first or multi-bin package still grades.
+ *
  * Returns the connected `Client`, a descriptor for the evidence bundle, and a
  * teardown. The normal MCP handshake (`initialize`) happens inside `connect()`.
  */
@@ -196,7 +207,7 @@ interface ConnectOptions {
     httpHeaders?: Record<string, string>;
     /**
      * stdio execution mode. "none" (default) launches the target on the host;
-     * "docker" runs an npm target ONLY inside the hardened container (§2.6) and
+     * "docker" runs an npm target ONLY inside the hardened container and
      * throws IsolationUnsupportedError for any other stdio kind. http targets are
      * unaffected (isolation is stdio-only).
      */
@@ -527,13 +538,12 @@ declare function liveFingerprint(target: TargetInput): Promise<LiveTarget>;
 
 /**
  * `run_litmus` — run the open behavioral harness end-to-end against an MCP
- * server and return the grade, the evidence, and (when an API URL is set) a mint
- * hand-off URL. Brand-voiced: plain, exact, no overclaim.
+ * server and return the grade and the evidence. Brand-voiced: plain, exact, no
+ * overclaim.
  *
  * Unlike `verify_attestation` (a passive onchain read), this tool LAUNCHES the
  * target server's code to exercise it — sandboxed for egress when Docker is
- * present. It needs no wallet or RPC; only minting (which the human does in a
- * browser via the returned URL) requires a wallet.
+ * present. It needs no wallet or RPC.
  */
 
 declare const RUN_LITMUS_TOOL_NAME = "run_litmus";
@@ -541,11 +551,9 @@ declare const RUN_LITMUS_TOOL_TITLE = "Run a behavioral litmus on an MCP server"
 declare const RUN_LITMUS_TOOL_DESCRIPTION: string;
 declare const runLitmusInputShape: {
     server_ref: z.ZodString;
-    pin: z.ZodOptional<z.ZodBoolean>;
 };
-declare function handleRunLitmus({ server_ref, pin }: {
+declare function handleRunLitmus({ server_ref }: {
     server_ref: string;
-    pin?: boolean;
 }): Promise<{
     content: {
         type: "text";
@@ -565,7 +573,6 @@ declare function handleRunLitmus({ server_ref, pin }: {
  * harness locally and print the grade. The heavy harness (`@polygraph/probes`)
  * is loaded lazily so the zero-dep `check`/`list` fast path stays intact.
  */
-
 type StdioCommand = {
     command: string;
     args: string[];

package/dist/index.js

@@ -14,11 +14,11 @@ import {
   rpcUrl,
   runLitmusInputShape,
   selectedNetwork
-} from "./chunk-MQC54LFV.js";
+} from "./chunk-UA4BIHP4.js";
 import {
   parseAuthFlags,
   resolveTarget
-} from "./chunk-6QM4RK25.js";
+} from "./chunk-WBXHDYIV.js";
 import {
   assembleBundle,
   canaryMatch,
@@ -32,7 +32,7 @@ import {
   markdownTricks,
   runLitmus,
   stateChangingToolNames
-} from "./chunk-2K6T4FZX.js";
+} from "./chunk-MB5EPL2V.js";
 import {
   BUNDLE_SCHEMA_VERSION,
   CATEGORY_STATUS_UINT8,
@@ -42,7 +42,7 @@ import {
   formatServerRef,
   parseServerRef,
   serverKey
-} from "./chunk-SAZKXB35.js";
+} from "./chunk-K7UEK2BA.js";
 
 // ../agent/src/gate.ts
 function sameServer(a, b) {

package/dist/mcp.js

@@ -7,13 +7,13 @@ import {
   readAttestation,
   runLitmusInputShape,
   selectedNetwork
-} from "./chunk-MQC54LFV.js";
-import "./chunk-6QM4RK25.js";
-import "./chunk-2K6T4FZX.js";
+} from "./chunk-UA4BIHP4.js";
+import "./chunk-WBXHDYIV.js";
+import "./chunk-MB5EPL2V.js";
 import {
   parseServerRef,
   serverKey
-} from "./chunk-SAZKXB35.js";
+} from "./chunk-K7UEK2BA.js";
 
 // src/mcp.ts
 import { realpathSync } from "fs";

package/dist/{src-XIEFSTXC.js → src-PTK3WEGQ.js}

@@ -11,8 +11,8 @@ import {
   markdownTricks,
   runLitmus,
   stateChangingToolNames
-} from "./chunk-2K6T4FZX.js";
-import "./chunk-SAZKXB35.js";
+} from "./chunk-MB5EPL2V.js";
+import "./chunk-K7UEK2BA.js";
 export {
   assembleBundle,
   canaryMatch,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@polygraphso/litmus",
-  "version": "0.2.1",
-  "description": "Behavioral litmus harness for MCP servers — grade a server A–F (tool-output injection, egress, sensitive-data), then hand off to mint an onchain attestation. Ships a CLI and an MCP server with a run_litmus tool for AI agents.",
+  "version": "0.4.0",
+  "description": "Behavioral litmus harness for MCP servers — grade a server A–F (tool-output injection, egress, sensitive-data) with reproducible, content-addressed evidence. Ships a CLI and an MCP server with a run_litmus tool for AI agents.",
   "license": "Apache-2.0",
   "homepage": "https://polygraph.so",
   "repository": {
@@ -59,9 +59,9 @@
     "vitest": "^2.1.0",
     "@polygraph/core": "0.0.0",
     "@polygraph/probes": "0.0.0",
-    "@polygraph/agent": "0.0.0",
     "@polygraph/onchain": "0.0.0",
     "@polygraph/mcp": "0.0.0",
+    "@polygraph/agent": "0.0.0",
     "@polygraph/cli": "0.0.0"
   },
   "publishConfig": {