@polygraphso/litmus 0.2.0

package/dist/index.js

@@ -0,0 +1,130 @@
+import {
+  LITMUS_SCHEMA,
+  NETWORKS,
+  RUN_LITMUS_TOOL_DESCRIPTION,
+  RUN_LITMUS_TOOL_NAME,
+  RUN_LITMUS_TOOL_TITLE,
+  decodeLitmusAttestation,
+  encodeLitmusAttestation,
+  handleRunLitmus,
+  litmusFields,
+  litmusSchemaUID,
+  networkConfig,
+  readAttestation,
+  rpcUrl,
+  runLitmusInputShape,
+  selectedNetwork
+} from "./chunk-MQC54LFV.js";
+import {
+  parseAuthFlags,
+  resolveTarget
+} from "./chunk-6QM4RK25.js";
+import {
+  assembleBundle,
+  canaryMatch,
+  classifyTool,
+  connectTarget,
+  fingerprintToolDefs,
+  gradeFromCategories,
+  hasHighSeverity,
+  instructionMimicry,
+  invisibleUnicode,
+  markdownTricks,
+  runLitmus,
+  stateChangingToolNames
+} from "./chunk-2K6T4FZX.js";
+import {
+  BUNDLE_SCHEMA_VERSION,
+  CATEGORY_STATUS_UINT8,
+  METHODOLOGY_VERSION,
+  ServerRefParseError,
+  canonicalStringify,
+  formatServerRef,
+  parseServerRef,
+  serverKey
+} from "./chunk-SAZKXB35.js";
+
+// ../agent/src/gate.ts
+function sameServer(a, b) {
+  return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+var DEFAULT_PASSING = /* @__PURE__ */ new Set(["A", "B", "C"]);
+function gateDecision(attestation, live, passing = DEFAULT_PASSING, now = BigInt(Math.floor(Date.now() / 1e3))) {
+  if (!attestation) {
+    return { action: "refuse", reason: "no attestation \u2014 unevaluated server" };
+  }
+  if (attestation.revoked) {
+    return { action: "refuse", reason: "attestation revoked" };
+  }
+  const exp = attestation.expirationTime ?? 0n;
+  if (exp !== 0n && now >= exp) {
+    return { action: "refuse", reason: "attestation expired" };
+  }
+  if (!sameServer(attestation.serverRef, live.serverRef)) {
+    return { action: "refuse", reason: "attestation is for a different server than the one being gated" };
+  }
+  if (attestation.toolDefsFingerprint.toLowerCase() !== live.fingerprint.toLowerCase()) {
+    return { action: "refuse", reason: "rug pull \u2014 live tool surface differs from the graded one" };
+  }
+  if (!passing.has(attestation.overallGrade)) {
+    return { action: "refuse", reason: `failing grade ${attestation.overallGrade}` };
+  }
+  const versionNote = attestation.resolvedVersion ? ` (graded version ${attestation.resolvedVersion})` : "";
+  return { action: "pay", reason: `grade ${attestation.overallGrade}; live fingerprint matches${versionNote}` };
+}
+async function liveFingerprint(target) {
+  const conn = await connectTarget(target);
+  try {
+    const { tools } = await conn.client.listTools();
+    const defs = (tools ?? []).map((t) => ({
+      name: t.name,
+      description: t.description ?? "",
+      inputSchema: t.inputSchema ?? null
+    }));
+    return { fingerprint: fingerprintToolDefs(defs).fingerprint, serverRef: conn.serverRef };
+  } finally {
+    await conn.teardown();
+  }
+}
+export {
+  BUNDLE_SCHEMA_VERSION,
+  CATEGORY_STATUS_UINT8,
+  DEFAULT_PASSING,
+  LITMUS_SCHEMA,
+  METHODOLOGY_VERSION,
+  NETWORKS,
+  RUN_LITMUS_TOOL_DESCRIPTION,
+  RUN_LITMUS_TOOL_NAME,
+  RUN_LITMUS_TOOL_TITLE,
+  ServerRefParseError,
+  assembleBundle,
+  canaryMatch,
+  canonicalStringify,
+  classifyTool,
+  connectTarget,
+  decodeLitmusAttestation,
+  encodeLitmusAttestation,
+  fingerprintToolDefs,
+  formatServerRef,
+  gateDecision,
+  gradeFromCategories,
+  handleRunLitmus,
+  hasHighSeverity,
+  instructionMimicry,
+  invisibleUnicode,
+  litmusFields,
+  litmusSchemaUID,
+  liveFingerprint,
+  markdownTricks,
+  networkConfig,
+  parseAuthFlags,
+  parseServerRef,
+  readAttestation,
+  resolveTarget,
+  rpcUrl,
+  runLitmus,
+  runLitmusInputShape,
+  selectedNetwork,
+  serverKey,
+  stateChangingToolNames
+};

package/dist/mcp.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * `polygraphso-litmus-mcp` — the polygraph litmus MCP server. Stdio transport.
+ * Exposes two tools to any MCP client (Claude Desktop, Cursor, …):
+ *
+ *   • `run_litmus`         — actively grade an MCP server A–F, then hand off to mint.
+ *   • `verify_attestation` — passively read a server's published onchain grade.
+ *
+ * Also exported as `@polygraphso/litmus/mcp` for embedding in a custom server.
+ */
+
+declare function buildServer(): McpServer;
+
+export { buildServer };

package/dist/mcp.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+import {
+  RUN_LITMUS_TOOL_DESCRIPTION,
+  RUN_LITMUS_TOOL_NAME,
+  RUN_LITMUS_TOOL_TITLE,
+  handleRunLitmus,
+  readAttestation,
+  runLitmusInputShape,
+  selectedNetwork
+} from "./chunk-MQC54LFV.js";
+import "./chunk-6QM4RK25.js";
+import "./chunk-2K6T4FZX.js";
+import {
+  parseServerRef,
+  serverKey
+} from "./chunk-SAZKXB35.js";
+
+// src/mcp.ts
+import { realpathSync } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport as StdioServerTransport2 } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// ../mcp/src/index.ts
+import { fileURLToPath } from "url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// ../mcp/src/tools/verify-attestation.ts
+import { z } from "zod";
+function canonicalRef(ref) {
+  try {
+    return serverKey(parseServerRef(ref)).toLowerCase();
+  } catch {
+    return ref.trim().toLowerCase();
+  }
+}
+var VERIFY_TOOL_NAME = "verify_attestation";
+var VERIFY_TOOL_TITLE = "Verify a server's polygraph attestation";
+var VERIFY_TOOL_DESCRIPTION = [
+  "Read the onchain polygraph (litmus) attestation for an MCP server before an",
+  "agent trusts \u2014 or, in agentic commerce, pays \u2014 it.",
+  "",
+  "Returns the behavioral grade (A\u2013F), the attestation UID, the evidence CID,",
+  "and the graded tool-surface fingerprint. The caller must still recompute the",
+  "LIVE fingerprint and require it to equal the attested one before paying \u2014 a",
+  "passing attestation can otherwise front for a tool surface the server no",
+  "longer serves (rug pull).",
+  "",
+  "Input: server_ref \u2014 e.g. npm/@modelcontextprotocol/server-filesystem. Returns",
+  "not_available when there is no attestation: treat that as unevaluated \u2014",
+  "neither safe nor unsafe."
+].join("\n");
+var verifyInputShape = {
+  server_ref: z.string().min(1).max(512).describe("Registry-prefixed server identifier, e.g. npm/@scope/server.")
+};
+async function handleVerify({ server_ref }) {
+  const uid = await resolveUid(server_ref);
+  const att = uid ? await readAttestation(uid) : null;
+  if (!att) {
+    return {
+      content: [{ type: "text", text: `not_available \u2014 no polygraph attestation for ${server_ref}` }]
+    };
+  }
+  if (canonicalRef(att.serverRef) !== canonicalRef(server_ref)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `not_available \u2014 the resolved attestation is for ${att.serverRef}, not ${server_ref} (discovery mismatch; treat as unevaluated)`
+        }
+      ]
+    };
+  }
+  const payload = {
+    status: "attested",
+    grade: att.overallGrade,
+    attestationUid: att.uid,
+    serverRef: att.serverRef,
+    // The version the grade was run against (null for HTTP/unresolved targets).
+    // Advisory: the live fingerprint, not this string, is the trust anchor.
+    resolvedVersion: att.resolvedVersion,
+    reportCID: att.reportCID,
+    toolDefsFingerprint: att.toolDefsFingerprint,
+    revoked: att.revoked,
+    network: selectedNetwork(),
+    liveFingerprintCheckRequired: "Recompute the live tool-surface fingerprint and require it to equal toolDefsFingerprint before paying."
+  };
+  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+}
+async function resolveUid(serverRef) {
+  const base = process.env.POLYGRAPH_API_URL ?? "https://polygraph.so";
+  try {
+    const res = await fetch(`${base}/api/attestations?ref=${encodeURIComponent(serverRef)}`);
+    if (!res.ok) return null;
+    const row = await res.json();
+    return row?.attestation_uid ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// ../mcp/src/index.ts
+function buildServer() {
+  const server = new McpServer(
+    { name: "polygraph", version: "0.0.0" },
+    {
+      instructions: [
+        "polygraph issues behavioral litmus grades for MCP servers, published",
+        "onchain. Use `verify_attestation` to read a server's grade before",
+        "recommending, installing, or paying it. A server with no attestation is",
+        "unevaluated \u2014 neither safe nor unsafe; say so."
+      ].join("\n")
+    }
+  );
+  server.registerTool(
+    VERIFY_TOOL_NAME,
+    {
+      title: VERIFY_TOOL_TITLE,
+      description: VERIFY_TOOL_DESCRIPTION,
+      inputSchema: verifyInputShape,
+      annotations: {
+        title: VERIFY_TOOL_TITLE,
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    handleVerify
+  );
+  return server;
+}
+async function main() {
+  const server = buildServer();
+  await server.connect(new StdioServerTransport());
+}
+var invokedDirectly = (() => {
+  try {
+    return process.argv[1] === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+if (invokedDirectly) {
+  main().catch((err) => {
+    process.stderr.write(`polygraph-mcp: fatal: ${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(1);
+  });
+}
+
+// src/mcp.ts
+function buildServer2() {
+  const server = new McpServer2(
+    { name: "polygraph-litmus", version: "0.1.0" },
+    {
+      instructions: [
+        "polygraph issues behavioral litmus grades (A\u2013F) for MCP servers.",
+        "",
+        "Use `run_litmus` to grade a server now: it runs the open harness against",
+        "the target and returns the grade, the evidence, and \u2014 when configured \u2014 a",
+        "mint hand-off URL the human opens to publish the grade onchain. It launches",
+        "the target's code (egress-sandboxed when Docker is present), so it is not a",
+        "passive read.",
+        "",
+        "Use `verify_attestation` to read a server's already-published grade before",
+        "recommending, installing, or paying it. A server with no attestation is",
+        "unevaluated \u2014 neither safe nor unsafe; say so."
+      ].join("\n")
+    }
+  );
+  server.registerTool(
+    RUN_LITMUS_TOOL_NAME,
+    {
+      title: RUN_LITMUS_TOOL_TITLE,
+      description: RUN_LITMUS_TOOL_DESCRIPTION,
+      inputSchema: runLitmusInputShape,
+      annotations: {
+        title: RUN_LITMUS_TOOL_TITLE,
+        readOnlyHint: false,
+        // launches the target server's code (and maybe Docker)
+        destructiveHint: false,
+        // sandboxed; does not intentionally mutate the user's system
+        idempotentHint: false,
+        // re-running re-spawns + re-pins
+        openWorldHint: true
+        // reaches arbitrary external servers
+      }
+    },
+    handleRunLitmus
+  );
+  server.registerTool(
+    VERIFY_TOOL_NAME,
+    {
+      title: VERIFY_TOOL_TITLE,
+      description: VERIFY_TOOL_DESCRIPTION,
+      inputSchema: verifyInputShape,
+      annotations: {
+        title: VERIFY_TOOL_TITLE,
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    handleVerify
+  );
+  return server;
+}
+async function main2() {
+  await buildServer2().connect(new StdioServerTransport2());
+}
+var invokedDirectly2 = (() => {
+  try {
+    return realpathSync(process.argv[1] ?? "") === fileURLToPath2(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+if (invokedDirectly2) {
+  main2().catch((err) => {
+    process.stderr.write(`polygraphso-litmus-mcp: fatal: ${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(1);
+  });
+}
+export {
+  buildServer2 as buildServer
+};

package/dist/src-XIEFSTXC.js

@@ -0,0 +1,29 @@
+import {
+  assembleBundle,
+  canaryMatch,
+  classifyTool,
+  connectTarget,
+  fingerprintToolDefs,
+  gradeFromCategories,
+  hasHighSeverity,
+  instructionMimicry,
+  invisibleUnicode,
+  markdownTricks,
+  runLitmus,
+  stateChangingToolNames
+} from "./chunk-2K6T4FZX.js";
+import "./chunk-SAZKXB35.js";
+export {
+  assembleBundle,
+  canaryMatch,
+  classifyTool,
+  connectTarget,
+  fingerprintToolDefs,
+  gradeFromCategories,
+  hasHighSeverity,
+  instructionMimicry,
+  invisibleUnicode,
+  markdownTricks,
+  runLitmus,
+  stateChangingToolNames
+};

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@polygraphso/litmus",
+  "version": "0.2.0",
+  "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.",
+  "license": "Apache-2.0",
+  "homepage": "https://polygraph.so",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/polygraphso/litmus.git",
+    "directory": "packages/litmus"
+  },
+  "bugs": "https://github.com/polygraphso/litmus/issues",
+  "keywords": [
+    "polygraph",
+    "mcp",
+    "model-context-protocol",
+    "trust",
+    "ai-agents",
+    "security",
+    "litmus"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js"
+    }
+  },
+  "bin": {
+    "polygraphso-litmus": "dist/cli.js",
+    "polygraphso-litmus-mcp": "dist/mcp.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@ethereum-attestation-service/eas-sdk": "^2.9.1",
+    "ethers": "^6.16.0",
+    "zod": "^3.23.8",
+    "tsx": "^4.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.0",
+    "@polygraph/core": "0.0.0",
+    "@polygraph/probes": "0.0.0",
+    "@polygraph/onchain": "0.0.0",
+    "@polygraph/agent": "0.0.0",
+    "@polygraph/mcp": "0.0.0",
+    "@polygraph/cli": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}