@polygraphso/litmus 0.2.0

package/dist/chunk-6QM4RK25.js

@@ -0,0 +1,180 @@
+import {
+  canonicalStringify
+} from "./chunk-SAZKXB35.js";
+
+// ../cli/src/litmus.ts
+import { existsSync } from "fs";
+import { createRequire } from "module";
+import * as path from "path";
+
+// ../cli/src/format.ts
+function formatBundle(b) {
+  const status = (code) => b.categories.find((c) => c.code === code)?.status ?? "?";
+  const lines = [];
+  lines.push(`\u2192 ${b.methodologyVersion} \xB7 ${b.serverRef}`);
+  if (b.resolvedVersion) lines.push(`\u2192 version ${b.resolvedVersion}`);
+  lines.push(`\u2192 C-01 ${status("C-01")} \xB7 C-02 ${status("C-02")} \xB7 C-03 ${status("C-03")}`);
+  const c01 = b.categories.find((c) => c.code === "C-01");
+  if (c01?.status === "fail") {
+    const highs = c01.probes.flatMap((p) => p.findings).filter((f) => f.severity === "high");
+    for (const f of highs.slice(0, 3)) {
+      lines.push(`   \u26A0 ${f.tool ?? "?"}: ${f.kind} \u2014 ${truncate(f.match, 64)}`);
+    }
+  }
+  lines.push(`\u2192 fingerprint ${shortFp(b.toolDefsFingerprint)}`);
+  lines.push(`\u2192 grade: ${b.grade}`);
+  lines.push(`   ${b.gradeRationale}`);
+  return lines.join("\n") + "\n";
+}
+function shortFp(fp) {
+  return fp.length > 14 ? `${fp.slice(0, 6)}\u2026${fp.slice(-4)}` : fp;
+}
+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");
+  const { headers, allowStateChanging, positionals } = parseAuthFlags(args);
+  const target = positionals[0];
+  if (!target) {
+    process.stderr.write(
+      'usage: polygraphso litmus [--json] [--bearer <token>] [--header "Key: Value"] [--allow-state-changing] <registry-ref | https-url | path-to-mcp>\n'
+    );
+    return 2;
+  }
+  const { runLitmus } = await import("./src-XIEFSTXC.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)}
+`);
+    return 1;
+  }
+}
+function parseAuthFlags(args, env = process.env) {
+  const headers = {};
+  const headerArgs = [];
+  let allowStateChanging = false;
+  let bearer = env.LITMUS_BEARER || void 0;
+  const positionals = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--json") continue;
+    if (a === "--allow-state-changing") {
+      allowStateChanging = true;
+    } else if (a === "--bearer") {
+      bearer = args[++i] ?? bearer;
+    } else if (a.startsWith("--bearer=")) {
+      bearer = a.slice("--bearer=".length);
+    } else if (a === "--header") {
+      const v = args[++i];
+      if (v) headerArgs.push(v);
+    } else if (a.startsWith("--header=")) {
+      headerArgs.push(a.slice("--header=".length));
+    } else if (a.startsWith("--")) {
+    } else {
+      positionals.push(a);
+    }
+  }
+  if (bearer) headers["Authorization"] = `Bearer ${bearer}`;
+  for (const h of headerArgs) {
+    const idx = h.indexOf(":");
+    if (idx === -1) continue;
+    const key = h.slice(0, idx).trim();
+    const value = h.slice(idx + 1).trim();
+    if (key) headers[key] = value;
+  }
+  return { headers, allowStateChanging, positionals };
+}
+function resolveTarget(target) {
+  if (/^https?:\/\//i.test(target)) return target;
+  if (existsSync(target)) {
+    const abs = path.resolve(target);
+    if (abs.endsWith(".ts") || abs.endsWith(".mts") || abs.endsWith(".cts")) {
+      return { command: process.execPath, args: [tsxCli(), abs], serverRef: target };
+    }
+    return { command: process.execPath, args: [abs], serverRef: target };
+  }
+  return target;
+}
+function tsxCli() {
+  const require2 = createRequire(import.meta.url);
+  const pkgJsonPath = require2.resolve("tsx/package.json");
+  const dir = path.dirname(pkgJsonPath);
+  const bin = require2(pkgJsonPath).bin;
+  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
+};

package/dist/chunk-MQC54LFV.js

@@ -0,0 +1,218 @@
+import {
+  mintUrl,
+  pinBundle,
+  resolveTarget
+} from "./chunk-6QM4RK25.js";
+import {
+  runLitmus
+} from "./chunk-2K6T4FZX.js";
+import {
+  CATEGORY_STATUS_UINT8,
+  METHODOLOGY_VERSION
+} from "./chunk-SAZKXB35.js";
+
+// ../onchain/src/networks.ts
+var NETWORKS = {
+  "base-sepolia": {
+    chainId: 84532,
+    rpc: "https://sepolia.base.org",
+    eas: "0x4200000000000000000000000000000000000021",
+    schemaRegistry: "0x4200000000000000000000000000000000000020",
+    easscan: "https://base-sepolia.easscan.org"
+  },
+  base: {
+    chainId: 8453,
+    rpc: "https://mainnet.base.org",
+    eas: "0x4200000000000000000000000000000000000021",
+    schemaRegistry: "0x4200000000000000000000000000000000000020",
+    easscan: "https://base.easscan.org"
+  }
+};
+function selectedNetwork() {
+  return process.env.NEXT_PUBLIC_POLYGRAPH_NETWORK === "base" ? "base" : "base-sepolia";
+}
+function networkConfig(net = selectedNetwork()) {
+  return NETWORKS[net];
+}
+function rpcUrl(net = selectedNetwork()) {
+  const override = net === "base" ? process.env.BASE_MAINNET_RPC_URL : process.env.BASE_SEPOLIA_RPC_URL;
+  return override && override.length > 0 ? override : NETWORKS[net].rpc;
+}
+
+// ../onchain/src/eas-sdk.ts
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+var sdk = require2(
+  "@ethereum-attestation-service/eas-sdk"
+);
+var { EAS, SchemaEncoder, SchemaRegistry } = sdk;
+
+// ../onchain/src/eas.ts
+var LITMUS_SCHEMA = "string serverRef,bytes32 toolDefsFingerprint,uint8 gradeC01,uint8 gradeC02,uint8 gradeC03,string overallGrade,string reportCID,string methodologyVersion,uint64 ranAt,string resolvedVersion";
+function categoryUint8(bundle, code) {
+  const status = bundle.categories.find((c) => c.code === code)?.status;
+  return status ? CATEGORY_STATUS_UINT8[status] : CATEGORY_STATUS_UINT8.skipped;
+}
+function litmusFields(bundle, reportCID) {
+  return {
+    serverRef: bundle.serverRef,
+    toolDefsFingerprint: bundle.toolDefsFingerprint,
+    gradeC01: categoryUint8(bundle, "C-01"),
+    gradeC02: categoryUint8(bundle, "C-02"),
+    gradeC03: categoryUint8(bundle, "C-03"),
+    overallGrade: bundle.grade,
+    reportCID,
+    methodologyVersion: bundle.methodologyVersion || METHODOLOGY_VERSION,
+    ranAt: BigInt(Math.floor(Date.parse(bundle.ranAt) / 1e3)),
+    resolvedVersion: bundle.resolvedVersion ?? ""
+  };
+}
+function encodeLitmusAttestation(bundle, reportCID) {
+  const f = litmusFields(bundle, reportCID);
+  const enc = new SchemaEncoder(LITMUS_SCHEMA);
+  return enc.encodeData([
+    { name: "serverRef", value: f.serverRef, type: "string" },
+    { name: "toolDefsFingerprint", value: f.toolDefsFingerprint, type: "bytes32" },
+    { name: "gradeC01", value: f.gradeC01, type: "uint8" },
+    { name: "gradeC02", value: f.gradeC02, type: "uint8" },
+    { name: "gradeC03", value: f.gradeC03, type: "uint8" },
+    { name: "overallGrade", value: f.overallGrade, type: "string" },
+    { name: "reportCID", value: f.reportCID, type: "string" },
+    { name: "methodologyVersion", value: f.methodologyVersion, type: "string" },
+    { name: "ranAt", value: f.ranAt, type: "uint64" },
+    { name: "resolvedVersion", value: f.resolvedVersion, type: "string" }
+  ]);
+}
+function decodeLitmusAttestation(encoded) {
+  const enc = new SchemaEncoder(LITMUS_SCHEMA);
+  const out = {};
+  for (const item of enc.decodeData(encoded)) {
+    out[item.name] = item.value.value;
+  }
+  return out;
+}
+
+// ../onchain/src/read.ts
+import { JsonRpcProvider, ZeroHash } from "ethers";
+function litmusSchemaUID() {
+  const uid = process.env.NEXT_PUBLIC_EAS_SCHEMA_UID;
+  if (!uid) throw new Error("NEXT_PUBLIC_EAS_SCHEMA_UID is required \u2014 register the schema first.");
+  return uid;
+}
+async function readAttestation(uid) {
+  const cfg = networkConfig();
+  const provider = new JsonRpcProvider(rpcUrl(), cfg.chainId);
+  const eas = new EAS(cfg.eas);
+  eas.connect(provider);
+  const att = await eas.getAttestation(uid);
+  if (!att || att.uid === ZeroHash) return null;
+  if (String(att.schema).toLowerCase() !== litmusSchemaUID().toLowerCase()) return null;
+  const d = decodeLitmusAttestation(att.data);
+  return {
+    uid: att.uid,
+    serverRef: String(d.serverRef),
+    toolDefsFingerprint: String(d.toolDefsFingerprint),
+    overallGrade: String(d.overallGrade),
+    reportCID: String(d.reportCID),
+    resolvedVersion: d.resolvedVersion || null,
+    revoked: att.revocationTime > 0n,
+    attester: String(att.attester),
+    expirationTime: BigInt(att.expirationTime ?? 0n)
+  };
+}
+
+// src/tools/run-litmus.ts
+import { z } from "zod";
+var RUN_LITMUS_TOOL_NAME = "run_litmus";
+var RUN_LITMUS_TOOL_TITLE = "Run a behavioral litmus on an MCP server";
+var RUN_LITMUS_TOOL_DESCRIPTION = [
+  `Run the open behavioral litmus (${METHODOLOGY_VERSION}) against an MCP server and return`,
+  "its grade. The harness connects like an agent would, fingerprints the tool",
+  "surface, and runs three probe categories: C-01 tool-output injection, C-02",
+  "permission overreach (egress in a hardened default-deny Docker sandbox, plus a",
+  "declared-permission honesty check), and C-03 sensitive-data handling (planted",
+  "canaries). It grades A\u2013F.",
+  "",
+  "This is ACTIVE: it launches the target server's code to exercise it (sandboxed",
+  "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.")
+};
+async function handleRunLitmus({ server_ref, pin }) {
+  try {
+    const bundle = await runLitmus(resolveTarget(server_ref));
+    const payload = { ...summarize(bundle), mint: await mintHandoff(bundle, pin) };
+    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) => {
+    const c = find(code);
+    const findings = c?.status === "fail" ? c.probes.flatMap((p) => p.findings).filter((f) => f.severity === "high").slice(0, 5).map((f) => ({ tool: f.tool, kind: f.kind, match: truncate(f.match, 120), host: f.host, port: f.port })) : [];
+    return { code, status: c?.status ?? "unknown", reason: c?.reason ?? null, findings };
+  });
+  const dockerSkipped = !b.harness.dockerAvailable || find("C-02")?.status === "skipped";
+  return {
+    grade: b.grade,
+    gradeRationale: b.gradeRationale,
+    fingerprint: b.toolDefsFingerprint,
+    serverRef: b.serverRef,
+    resolvedVersion: b.resolvedVersion,
+    ranAt: b.ranAt,
+    methodologyVersion: b.methodologyVersion,
+    categories,
+    ...dockerSkipped ? { dockerSkipped: "C-02 (egress) was not run because Docker was unavailable; the grade is capped at B for this run." } : {}
+  };
+}
+function truncate(s, n) {
+  return s.length > n ? `${s.slice(0, n)}\u2026` : s;
+}
+
+export {
+  NETWORKS,
+  selectedNetwork,
+  networkConfig,
+  rpcUrl,
+  LITMUS_SCHEMA,
+  litmusFields,
+  encodeLitmusAttestation,
+  decodeLitmusAttestation,
+  litmusSchemaUID,
+  readAttestation,
+  RUN_LITMUS_TOOL_NAME,
+  RUN_LITMUS_TOOL_TITLE,
+  RUN_LITMUS_TOOL_DESCRIPTION,
+  runLitmusInputShape,
+  handleRunLitmus
+};

package/dist/chunk-SAZKXB35.js

@@ -0,0 +1,120 @@
+// ../core/src/types.ts
+var METHODOLOGY_VERSION = "litmus-v2";
+var BUNDLE_SCHEMA_VERSION = "1.1.0";
+var CATEGORY_STATUS_UINT8 = {
+  pass: 0,
+  fail: 1,
+  skipped: 2
+};
+
+// ../core/src/identity.ts
+var REGISTRIES = /* @__PURE__ */ new Set(["npm", "pypi", "github"]);
+var OWNER_RE = /^@?[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var VERSION_RE = /^[A-Za-z0-9][A-Za-z0-9.+_-]*$/;
+var ServerRefParseError = class extends Error {
+  constructor(ref, reason) {
+    super(`Invalid server ref "${ref}": ${reason}`);
+    this.name = "ServerRefParseError";
+  }
+};
+function parseServerRef(ref) {
+  const firstSlash = ref.indexOf("/");
+  if (firstSlash === -1) {
+    throw new ServerRefParseError(ref, "expected `{registry}/...`");
+  }
+  const registry = ref.slice(0, firstSlash);
+  if (!REGISTRIES.has(registry)) {
+    throw new ServerRefParseError(
+      ref,
+      `unknown registry "${registry}" (expected one of: ${[...REGISTRIES].join(", ")})`
+    );
+  }
+  const rest = ref.slice(firstSlash + 1);
+  const versionAt = rest.lastIndexOf("@");
+  let pathPart;
+  let version;
+  if (versionAt > 0) {
+    pathPart = rest.slice(0, versionAt);
+    version = rest.slice(versionAt + 1);
+    if (version.length === 0) {
+      throw new ServerRefParseError(ref, "empty version after `@`");
+    }
+    if (!VERSION_RE.test(version)) {
+      throw new ServerRefParseError(ref, "version contains disallowed characters");
+    }
+  } else {
+    pathPart = rest;
+    version = null;
+  }
+  const lastSlash = pathPart.lastIndexOf("/");
+  let owner;
+  let name;
+  if (lastSlash === -1) {
+    if (registry === "github") {
+      throw new ServerRefParseError(ref, "github requires `{owner}/{repo}`");
+    }
+    owner = null;
+    name = pathPart;
+    if (!name) {
+      throw new ServerRefParseError(ref, "empty name segment");
+    }
+  } else {
+    owner = pathPart.slice(0, lastSlash);
+    name = pathPart.slice(lastSlash + 1);
+    if (!owner || !name) {
+      throw new ServerRefParseError(ref, "empty owner or name segment");
+    }
+  }
+  if (owner !== null && !OWNER_RE.test(owner)) {
+    throw new ServerRefParseError(ref, "owner contains disallowed characters");
+  }
+  if (!NAME_RE.test(name)) {
+    throw new ServerRefParseError(ref, "name contains disallowed characters");
+  }
+  return { registry, owner, name, version };
+}
+function formatServerRef(parts) {
+  const base = parts.owner ? `${parts.registry}/${parts.owner}/${parts.name}` : `${parts.registry}/${parts.name}`;
+  return parts.version ? `${base}@${parts.version}` : base;
+}
+function serverKey(parts) {
+  return parts.owner ? `${parts.registry}/${parts.owner}/${parts.name}` : `${parts.registry}/${parts.name}`;
+}
+
+// ../core/src/canonical.ts
+function canonicalStringify(value) {
+  return JSON.stringify(sortDeep(value));
+}
+var MAX_CANONICAL_DEPTH = 200;
+function sortDeep(value, depth = 0) {
+  if (depth > MAX_CANONICAL_DEPTH) {
+    throw new RangeError(`value nesting exceeds ${MAX_CANONICAL_DEPTH} levels`);
+  }
+  if (Array.isArray(value)) return value.map((v) => sortDeep(v, depth + 1));
+  if (value && typeof value === "object") {
+    const src = value;
+    const out = {};
+    for (const k of Object.keys(src).sort()) {
+      Object.defineProperty(out, k, {
+        value: sortDeep(src[k], depth + 1),
+        enumerable: true,
+        writable: true,
+        configurable: true
+      });
+    }
+    return out;
+  }
+  return value;
+}
+
+export {
+  METHODOLOGY_VERSION,
+  BUNDLE_SCHEMA_VERSION,
+  CATEGORY_STATUS_UINT8,
+  ServerRefParseError,
+  parseServerRef,
+  formatServerRef,
+  serverKey,
+  canonicalStringify
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import {
+  attestationsUrl,
+  runLitmusCli
+} from "./chunk-6QM4RK25.js";
+import {
+  parseServerRef,
+  serverKey
+} from "./chunk-SAZKXB35.js";
+
+// src/cli.ts
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+// ../cli/src/check.ts
+function checkQuery(rawRef) {
+  try {
+    const parsed = parseServerRef(rawRef);
+    return { ref: serverKey(parsed), ver: parsed.version };
+  } catch {
+    return { ref: rawRef, ver: null };
+  }
+}
+async function runCheck(args) {
+  const rawRef = args[0];
+  if (!rawRef) {
+    process.stderr.write("usage: polygraphso check <registry-ref[@version]>\n");
+    return 2;
+  }
+  const { ref, ver } = checkQuery(rawRef);
+  try {
+    const query = `?ref=${encodeURIComponent(ref)}${ver ? `&ver=${encodeURIComponent(ver)}` : ""}`;
+    const res = await fetch(`${attestationsUrl()}${query}`);
+    if (res.ok) {
+      const row = await res.json();
+      if (row?.attestation_uid) {
+        const version = row.resolved_version ? ` \xB7 version ${row.resolved_version}` : "";
+        process.stdout.write(
+          [
+            `\u2192 ${rawRef}`,
+            `\u2192 polygraph: ${row.grade ?? "?"}${version} \xB7 ${easscan(row.network, row.attestation_uid)}`,
+            ""
+          ].join("\n")
+        );
+        return 0;
+      }
+    }
+  } catch {
+  }
+  process.stdout.write(
+    [
+      `\u2192 ${rawRef}`,
+      "\u2192 polygraph: not yet available",
+      `\u2192 run a behavioral litmus: polygraphso litmus ${rawRef}`,
+      ""
+    ].join("\n")
+  );
+  return 0;
+}
+function easscan(network, uid) {
+  const host = network === "base" ? "base.easscan.org" : "base-sepolia.easscan.org";
+  return `https://${host}/attestation/view/${uid}`;
+}
+
+// ../cli/src/list.ts
+async function runList(_args) {
+  process.stdout.write("\u2192 no published grades yet (discovery lands in M3)\n");
+  return 0;
+}
+
+// src/cli.ts
+var HELP = `polygraphso-litmus \u2014 behavioral litmus grades for MCP servers.
+
+usage:
+  polygraphso-litmus litmus    [--json] <registry-ref | https-url | path-to-mcp>
+  polygraphso-litmus check     <registry-ref>
+  polygraphso-litmus list
+  polygraphso-litmus --version
+  polygraphso-litmus --help
+
+examples:
+  polygraphso-litmus litmus npm/@modelcontextprotocol/server-filesystem
+  polygraphso-litmus litmus --json npm/@modelcontextprotocol/server-filesystem
+
+Set POLYGRAPH_API_URL to pin the evidence and get a mint hand-off link.
+More at https://polygraph.so
+`;
+function readVersion() {
+  try {
+    const path = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    return JSON.parse(readFileSync(path, "utf8")).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+async function main(argv) {
+  const cmd = argv[0];
+  if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (cmd === "--version" || cmd === "-v") {
+    process.stdout.write(readVersion() + "\n");
+    return 0;
+  }
+  if (cmd === "litmus") return runLitmusCli(argv.slice(1));
+  if (cmd === "check") return runCheck(argv.slice(1));
+  if (cmd === "list") return runList(argv.slice(1));
+  process.stderr.write(`polygraphso-litmus: unknown command "${cmd}".
+
+${HELP}`);
+  return 2;
+}
+main(process.argv.slice(2)).then((code) => process.exit(code)).catch((err) => {
+  process.stderr.write(`polygraphso-litmus: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});

package/dist/docker/egress-sniff.Dockerfile

@@ -0,0 +1,13 @@
+# Egress-sniff image — used for BOTH the sinkhole (--entrypoint /sink-entrypoint.sh,
+# with NET_ADMIN) and the target run (--entrypoint npx, all caps dropped).
+FROM node:22-slim
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends iptables iproute2 ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY sinkhole.mjs /sinkhole.mjs
+COPY sink-entrypoint.sh /sink-entrypoint.sh
+RUN chmod +x /sink-entrypoint.sh
+
+# No default CMD/ENTRYPOINT: callers set it (sink vs target) at `docker run`.

package/dist/docker/sink-entrypoint.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Sinkhole entrypoint. Runs with --cap-add=NET_ADMIN (the sink is trusted; the
+# TARGET runs with all caps dropped). Redirect all inbound TCP to the sink port,
+# then run the sinkhole with our own IP so DNS answers point back here.
+set -e
+SINK_IP="$(hostname -i 2>/dev/null | awk '{print $1}')"
+export SINK_IP
+iptables -t nat -A PREROUTING -p tcp -j REDIRECT --to-port 8443 2>/dev/null || true
+exec node /sinkhole.mjs