@polygraphso/litmus 0.2.0

package/dist/docker/sinkhole.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Egress sinkhole. Runs inside the egress-sniff container on an `--internal`
+ * Docker network. DNS answers every query with the sink's own IP, so the target
+ * dials back to us; the entrypoint's iptables REDIRECT funnels all inbound TCP
+ * (any port) to our listener, where we log `{host, port, firstBytes}` and drop
+ * the connection — never completing it. One `EGRESS {json}` line per attempt.
+ *
+ * KNOWN LIMIT (documented, v1): capture is DNS-ROUTED. A target that connects to
+ * a hard-coded IP literal — or uses DoH/DoT to a hard-coded resolver IP — issues
+ * no sinkholed lookup, so its packet is dropped by the `--internal` network and
+ * never reaches this listener: C-02 then reads as a false "no egress" pass. The
+ * real data still never leaves the box. Closing it needs DNS-independent capture
+ * (sink as default gateway + DNAT all egress) — roadmap. See
+ * docs/litmus-test-v1.md §7.
+ */
+
+import dgram from "node:dgram";
+import net from "node:net";
+
+const TCP_SINK_PORT = 8443;
+const emit = (rec) => process.stdout.write("EGRESS " + JSON.stringify(rec) + "\n");
+
+function ipBytes() {
+  const parts = (process.env.SINK_IP || "203.0.113.1").trim().split(".").map((n) => parseInt(n, 10) & 0xff);
+  return parts.length === 4 && parts.every((n) => Number.isFinite(n)) ? parts : [203, 0, 113, 1];
+}
+
+// ── DNS (UDP 53): log the queried name, answer A with the sink's IP. ──────────
+const udp = dgram.createSocket("udp4");
+udp.on("message", (msg, rinfo) => {
+  try {
+    const name = decodeQName(msg, 12);
+    if (name) emit({ kind: "dns", host: name });
+    udp.send(dnsAnswer(msg), rinfo.port, rinfo.address);
+  } catch {
+    /* ignore malformed query */
+  }
+});
+udp.on("error", () => {});
+udp.bind(53);
+
+// ── TCP: all inbound TCP REDIRECTed here; log first bytes + sniffed host. ─────
+const srv = net.createServer((sock) => {
+  sock.setTimeout(2000, () => sock.destroy());
+  sock.once("data", (buf) => {
+    emit({ kind: "tcp", host: sniffHost(buf), port: sock.localPort, firstBytes: printable(buf.subarray(0, 64)) });
+    sock.destroy();
+  });
+  sock.on("error", () => {});
+});
+srv.on("error", () => {});
+srv.listen(TCP_SINK_PORT, "0.0.0.0");
+process.stdout.write("EGRESS-SINK ready\n");
+
+function printable(b) {
+  return b.toString("latin1").replace(/[^\x20-\x7e]/g, ".");
+}
+
+function decodeQName(msg, off) {
+  const labels = [];
+  let i = off;
+  while (i < msg.length) {
+    const len = msg[i];
+    if (len === 0 || (len & 0xc0) === 0xc0) break;
+    labels.push(msg.toString("ascii", i + 1, i + 1 + len));
+    i += 1 + len;
+  }
+  return labels.join(".");
+}
+
+function dnsAnswer(query) {
+  const id = query.subarray(0, 2);
+  const question = query.subarray(12); // question section (single-question queries)
+  const header = Buffer.from([id[0], id[1], 0x81, 0x80, 0x00, 0x01, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00]);
+  const [a, b, c, d] = ipBytes();
+  const answer = Buffer.from([0xc0, 0x0c, 0x00, 0x01, 0x00, 0x01, 0x00, 0x00, 0x00, 0x1e, 0x00, 0x04, a, b, c, d]);
+  return Buffer.concat([header, question, answer]);
+}
+
+function sniffHost(buf) {
+  const s = buf.toString("latin1");
+  const http = s.match(/host:\s*([^\r\n]+)/i);
+  if (http) return http[1].trim();
+  if (buf[0] === 0x16) {
+    const sni = s.match(/[a-z0-9-]+(?:\.[a-z0-9-]+)+\.[a-z]{2,}/i); // best-effort SNI
+    if (sni) return sni[0];
+  }
+  return undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1,594 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { z } from 'zod';
+
+/**
+ * Shared contract types for the litmus MVP. Web3-free.
+ *
+ * In-memory / evidence-bundle types are camelCase to match the canonical
+ * bundle JSON in `docs/onchain-proof-spec.md` §2. (Postgres row types added
+ * later for the discovery DB will be snake_case, mirroring the columns.)
+ */
+/** 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";
+/** 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";
+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";
+type CategoryStatus = "pass" | "fail" | "skipped";
+type ProbeStatus = "pass" | "fail" | "skipped" | "partial";
+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";
+interface Finding {
+    kind: FindingKind;
+    severity: Severity;
+    /** The matched substring (or a hex dump, for invisible characters). */
+    match: string;
+    /** Byte offset where the match starts, when applicable. */
+    offset?: number;
+    /** Offending tool name, when the finding is tied to one. */
+    tool?: string;
+    host?: string;
+    port?: number;
+    firstBytes?: string;
+}
+interface ProbeResult {
+    id: ProbeId;
+    status: ProbeStatus;
+    findings: Finding[];
+    /** Skip/partial reason, when status is `skipped` or `partial`. */
+    reason?: string | null;
+}
+interface CategoryResult {
+    code: CategoryCode;
+    status: CategoryStatus;
+    reason?: string | null;
+    probes: ProbeResult[];
+}
+type TargetKind = "stdio" | "http";
+interface TargetDescriptor {
+    kind: TargetKind;
+    /** stdio: the launched command (e.g. `npx -y <pkg>`). */
+    command?: string | null;
+    /** http: the remote MCP URL. */
+    url?: string | null;
+}
+/** The canonicalized fields of a tool that the fingerprint hashes. */
+interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+}
+interface HarnessInfo {
+    package: string;
+    version: string;
+    node: string;
+    /** Governs C-02 / probe 4.2 applicability. */
+    dockerAvailable: boolean;
+    /** How a stdio target was executed (bundle 1.1.0). Set for stdio targets,
+     *  omitted for http. "docker" = the target ran only inside the hardened
+     *  container; "none" = launched on the host (the self-run default). */
+    stdioIsolation?: "docker" | "none";
+}
+interface EvidenceBundle {
+    schemaVersion: string;
+    methodologyVersion: string;
+    /** Canonical, versionless identity (serverKey). */
+    serverRef: string;
+    /** The exact version actually run. */
+    resolvedVersion: string | null;
+    target: TargetDescriptor;
+    /** sha256 of the canonical tool surface → `0x` + 64 hex (bytes32). */
+    toolDefsFingerprint: string;
+    /** The canonicalized {name, description, inputSchema} that was hashed. */
+    toolDefs: ToolDef[];
+    ranAt: string;
+    harness: HarnessInfo;
+    categories: CategoryResult[];
+    grade: LitmusGrade;
+    gradeRationale: string;
+    disclaimer: string;
+}
+
+/**
+ * Server-identity helpers for refs of the form `{registry}/{owner}/{name}@{version}`.
+ *
+ * Vendored verbatim from the `core` repo (`packages/core/src/identity.ts`) so
+ * this standalone repo has no cross-repo dependency. Keep in sync if core's
+ * parser changes.
+ *
+ * Examples:
+ *   npm/@modelcontextprotocol/server-filesystem@0.4.2   (scoped npm)
+ *   npm/lodash@4.17.21                                  (unscoped npm)
+ *   pypi/mcp-server-git@1.0.0                           (pypi — no owner)
+ *   github/anthropic/mcp-server-foo@v0.1.3              (github — owner required)
+ *
+ * Owner rules per registry:
+ *   - npm: optional (scoped packages have `@scope` as owner; unscoped omit it)
+ *   - pypi: always absent (PyPI packages are flat — no owner namespacing)
+ *   - github: required (always `{owner}/{repo}`)
+ *
+ * npm scopes are preserved (the `@` in `@modelcontextprotocol` belongs to the
+ * scope, not the version delimiter).
+ */
+
+interface ParsedServerRef {
+    registry: Registry;
+    /** Null for unscoped npm and for all pypi refs; required for github. */
+    owner: string | null;
+    name: string;
+    version: string | null;
+}
+declare class ServerRefParseError extends Error {
+    constructor(ref: string, reason: string);
+}
+/**
+ * Parse a server ref. Version is optional; if present it must follow the final `@`.
+ * The owner segment may itself start with `@` (npm scope).
+ */
+declare function parseServerRef(ref: string): ParsedServerRef;
+declare function formatServerRef(parts: ParsedServerRef): string;
+/** Identity of a server without a version pin. */
+declare function serverKey(parts: Pick<ParsedServerRef, "registry" | "owner" | "name">): string;
+
+/**
+ * Deterministic JSON for content-addressing the evidence bundle
+ * (onchain-proof-spec §2). Object keys are sorted lexicographically (recursively)
+ * so the same bundle always serializes to the same bytes → the same CID. Array
+ * order is preserved (the bundle already fixes it: categories by code, probes by
+ * ID). Raw string bytes are preserved (hidden-Unicode tampering must change the
+ * hash).
+ */
+declare function canonicalStringify(value: unknown): string;
+
+/**
+ * Connect to a target MCP server the way an agent would (technical-design §3).
+ *
+ * - a local package ref (`npm/…`, `pypi/…`) is launched as a subprocess over
+ *   **stdio** (`npx -y` / `uvx`);
+ * - a remote `https://` URL is reached over **Streamable HTTP**;
+ * - an explicit `{command,args}` (for in-repo demo servers and tests) launches
+ *   over stdio directly.
+ *
+ * Returns the connected `Client`, a descriptor for the evidence bundle, and a
+ * teardown. The normal MCP handshake (`initialize`) happens inside `connect()`.
+ */
+
+interface StdioCommand$1 {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    /** Friendly identity for the evidence bundle (defaults to the command line). */
+    serverRef?: string;
+}
+/** A litmus target: a server ref string, an https URL, or an explicit stdio command. */
+type TargetInput = string | StdioCommand$1;
+interface ConnectedTarget {
+    client: Client;
+    kind: TargetKind;
+    descriptor: TargetDescriptor;
+    /** Canonical versionless identity (serverKey), the URL, or the command line. */
+    serverRef: string;
+    resolvedVersion: string | null;
+    teardown: () => Promise<void>;
+}
+interface ConnectOptions {
+    /** Env to seed into a locally-launched server (e.g. canaries for C-03). */
+    seedEnv?: Record<string, string>;
+    /** Working directory to launch a local stdio server in (e.g. a canary-seeded cwd for C-03 4.1). */
+    seedCwd?: string;
+    /**
+     * HTTP request headers for a remote (`https://`) target — e.g.
+     * `{ Authorization: "Bearer …" }` to reach an OAuth-gated MCP server. Ignored
+     * for stdio targets (those authenticate via env). Sent only to the target
+     * origin (see `sameOriginAuthFetch`).
+     */
+    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
+     * throws IsolationUnsupportedError for any other stdio kind. http targets are
+     * unaffected (isolation is stdio-only).
+     */
+    isolation?: "none" | "docker";
+    /** Label every docker resource created here, so a killed parent can sweep. */
+    runLabel?: string;
+}
+declare function connectTarget(input: TargetInput, opts?: ConnectOptions): Promise<ConnectedTarget>;
+
+/**
+ * The harness orchestrator (technical-design §3): connect → fingerprint →
+ * probes → grade → bundle. Public entry point: `runLitmus`.
+ */
+
+/** Caller-supplied knobs for a litmus run. */
+interface RunLitmusOptions {
+    /**
+     * HTTP request headers for a remote (`https://`) target — e.g. an
+     * `Authorization: Bearer …` to grade an OAuth-gated MCP server. Ignored for
+     * stdio targets.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Actively call state-changing tools (`send`/`swap`/`sign`/`delete` …) too.
+     * Off by default: those tools are skipped from bait calls so the harness
+     * can't move money or mutate state on an authenticated server.
+     */
+    allowStateChanging?: boolean;
+    /**
+     * stdio execution mode. "docker" runs an npm target ONLY inside the hardened
+     * container and fails the run on any isolation failure (no fallback to host
+     * exec, no B-cap). Default: "docker" when `LITMUS_STDIO_ISOLATION=docker`,
+     * else "none".
+     */
+    isolation?: "none" | "docker";
+    /** Override the baked bundle disclaimer (e.g. the hosted operator-run string). */
+    disclaimer?: string;
+    /** Label every docker resource created by this run, so a killed parent can sweep. */
+    runLabel?: string;
+    /**
+     * Overall wall-clock ceiling (ms) for the whole probe sequence after connect.
+     * The per-step timeouts (connect, listTools, each tool call) bound individual
+     * calls, but their SUM is attacker-controlled: a hostile server can declare up
+     * to MAX_TOOLS tools and hang each call to its per-call timeout. This caps the
+     * aggregate so the in-process (`https`) path can't pin the caller for hours.
+     * Unset ⇒ no aggregate bound (the npm path is already bounded by the scrubbed
+     * child's process-group SIGKILL in executeRun). On timeout the run rejects and
+     * the `finally` tears the connection down, settling any in-flight calls.
+     */
+    timeoutMs?: number;
+}
+declare function runLitmus(target: TargetInput, opts?: RunLitmusOptions): Promise<EvidenceBundle>;
+
+/**
+ * Tool-surface fingerprint (litmus-test-v1 §6, technical-design §3).
+ *
+ * Canonicalize the tool surface from `tools/list` and hash it to a bytes32:
+ *   - keep {name, description, inputSchema} per tool
+ *   - sort tools by name; recursively sort object keys
+ *   - normalize ASCII whitespace in descriptions (trim/collapse) but KEEP raw
+ *     Unicode — hidden-character injection must change the hash
+ *   - JSON.stringify → sha256 → `0x` + 64 hex
+ *
+ * The grade certifies *this exact surface*; the consuming agent recomputes the
+ * live fingerprint before paying and refuses on any mismatch (rug-pull guard).
+ */
+
+interface FingerprintResult {
+    /** `0x` + 64 lowercase hex (bytes32). */
+    fingerprint: string;
+    /** The canonicalized tool defs that were hashed (also stored in the bundle). */
+    canonical: ToolDef[];
+}
+declare function fingerprintToolDefs(tools: readonly ToolDef[]): FingerprintResult;
+
+/**
+ * Grading rubric (litmus-test-v1 §5). A single letter A–F, always with a
+ * rationale (never a bare letter).
+ *
+ *   F — any C-01 or C-03 failure (injection or data leak)
+ *   D — C-02 failure (unexpected egress), no C-01/C-03 failure
+ *   A — all three categories pass
+ *   B — C-01 & C-03 pass, C-02 skipped (no sandbox / remote target)
+ *
+ * Robust to categories that haven't run yet (early milestones): if nothing
+ * failed and C-01 passed but some categories were skipped, it reports B and
+ * names what was not verified.
+ */
+
+interface Grade {
+    grade: LitmusGrade;
+    rationale: string;
+}
+declare function gradeFromCategories(categories: readonly CategoryResult[]): Grade;
+
+/**
+ * Assemble the canonical evidence bundle (onchain-proof-spec §2).
+ *
+ * Content-addressed: its CID is its hash, so the `reportCID` in the attestation
+ * pins this exact document. Canonicalization (sorted keys etc.) is applied when
+ * it's serialized for pinning; here we build the in-memory shape.
+ */
+
+interface BundleInput {
+    serverRef: string;
+    resolvedVersion: string | null;
+    target: TargetDescriptor;
+    toolDefsFingerprint: string;
+    toolDefs: ToolDef[];
+    categories: CategoryResult[];
+    grade: Grade;
+    ranAt: string;
+    dockerAvailable: boolean;
+    /** How a stdio target was executed (bundle 1.1.0). Set for stdio targets;
+     *  omitted for http (isolation is stdio-only). */
+    stdioIsolation?: "docker" | "none";
+    /** Override the baked disclaimer (e.g. the hosted operator-run string). The
+     *  local self-run default is used when this is absent. */
+    disclaimer?: string;
+}
+declare function assembleBundle(input: BundleInput): EvidenceBundle;
+
+/**
+ * Shared detection primitives for C-01 (injection) and C-03 (canaries),
+ * implemented once and applied uniformly (litmus-test-v1 §3). Pure functions
+ * over text — independently unit-testable; the place new failure modes are added.
+ *
+ * Each returns structured `Finding`s; probes decide pass/fail from severity.
+ */
+
+declare function invisibleUnicode(text: string): Finding[];
+declare function instructionMimicry(text: string): Finding[];
+declare function markdownTricks(text: string): Finding[];
+/**
+ * Exact and lightly-obfuscated match of planted canaries (litmus-v1 §3:
+ * "exact and lightly-obfuscated (case, whitespace, simple encodings)"). Beyond
+ * exact + case-insensitive, it defeats whitespace-splitting and simple encodings
+ * (base64/hex/url) by re-checking decoded/normalized views of the text. False
+ * positives are bounded by requiring the *full, distinctive* canary to appear in
+ * a view — random base64/hex won't decode to a `POLYGRAPH-CANARY-<uuid>`.
+ */
+declare function canaryMatch(text: string, canaries: readonly string[]): Finding[];
+/** True if any finding is high-severity (the C-01 fail bar). */
+declare function hasHighSeverity(findings: readonly Finding[]): boolean;
+
+/**
+ * Tool-safety classification (litmus-test-v1 §C-01/§C-03 safety note).
+ *
+ * The dynamic probes (C-01 1.2, C-03 4.1) call tools with bait inputs. Against
+ * an authenticated server that can move money or mutate state — a wallet's
+ * `send`/`swap`/`sign`, a database's `delete` — that is unacceptable. So by
+ * default we do NOT actively call tools classified as state-changing: they are
+ * still fingerprinted and statically scanned (1.1), but recorded as skipped,
+ * not exercised. `--allow-state-changing` opts back into full exercise.
+ *
+ * Classification is conservative (prefer skipping a safe tool over calling a
+ * dangerous one) and uses, in order: MCP tool annotations, then a verb
+ * heuristic on the name/description.
+ */
+/** The MCP tool annotation hints we read (a subset of the spec's annotations). */
+interface ToolAnnotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+}
+interface ToolSafetyInput {
+    name: string;
+    description?: string;
+    annotations?: ToolAnnotations | null;
+}
+interface ToolSafety {
+    stateChanging: boolean;
+    /** Why it was classified state-changing (for the probe's skip reason). */
+    reason?: string;
+}
+/** Classify whether a tool should be skipped from active (bait-call) exercise. */
+declare function classifyTool(tool: ToolSafetyInput): ToolSafety;
+/** Names of the tools in a surface that are state-changing (skipped by default). */
+declare function stateChangingToolNames(tools: readonly ToolSafetyInput[]): Set<string>;
+
+/** What every probe receives: the live client, the tool surface, planted canaries. */
+interface ProbeContext {
+    client: Client;
+    tools: ToolDef[];
+    /** Per-run unique canary strings (planted by C-03; available to all probes). */
+    canaries: string[];
+    /** Whether a network sandbox is available (governs C-02 / probe 4.2). */
+    dockerAvailable: boolean;
+    /**
+     * Tool names classified as state-changing (e.g. `send`/`swap`/`delete`). The
+     * dynamic probes skip actively calling these unless `allowStateChanging` is
+     * set — they still get the static scan (1.1). See `tool-safety.ts`.
+     */
+    stateChangingTools: ReadonlySet<string>;
+    /** When true, exercise every tool including state-changing ones. */
+    allowStateChanging: boolean;
+}
+
+/**
+ * Network constants (onchain-proof-spec §4). EAS contracts are OP-Stack
+ * predeploys — identical on Base and Base Sepolia. The schema UID is filled
+ * per-network after registration (env / web/lib).
+ */
+type Network = "base-sepolia" | "base";
+interface NetworkConfig {
+    chainId: number;
+    rpc: string;
+    eas: string;
+    schemaRegistry: string;
+    easscan: string;
+}
+declare const NETWORKS: Record<Network, NetworkConfig>;
+declare function selectedNetwork(): Network;
+declare function networkConfig(net?: Network): NetworkConfig;
+/**
+ * The RPC URL for a network, honoring the per-network env override
+ * (`BASE_MAINNET_RPC_URL` for base, `BASE_SEPOLIA_RPC_URL` otherwise) when set
+ * and non-empty, else the baked public default. A hosted service needs its own
+ * RPC; `readAttestation` (read) goes through here.
+ */
+declare function rpcUrl(net?: Network): string;
+
+/**
+ * EAS attestation encoding for litmus grades (onchain-proof-spec §3).
+ *
+ * One schema, registered once per network; each litmus result is one attestation
+ * referencing the bundle CID. The heavy evidence stays off-chain (pinned by
+ * reportCID); on-chain we keep the fingerprint, per-category uint8 verdicts, the
+ * letter grade, the methodology version, and the resolved version the grade was
+ * run against (empty string when the target had no resolvable version).
+ */
+
+declare const LITMUS_SCHEMA = "string serverRef,bytes32 toolDefsFingerprint,uint8 gradeC01,uint8 gradeC02,uint8 gradeC03,string overallGrade,string reportCID,string methodologyVersion,uint64 ranAt,string resolvedVersion";
+interface LitmusAttestationFields {
+    serverRef: string;
+    toolDefsFingerprint: string;
+    gradeC01: number;
+    gradeC02: number;
+    gradeC03: number;
+    overallGrade: string;
+    reportCID: string;
+    methodologyVersion: string;
+    ranAt: bigint;
+    resolvedVersion: string;
+}
+declare function litmusFields(bundle: EvidenceBundle, reportCID: string): LitmusAttestationFields;
+/** ABI-encode the attestation data for `eas.attest({ data })`. No network. */
+declare function encodeLitmusAttestation(bundle: EvidenceBundle, reportCID: string): string;
+declare function decodeLitmusAttestation(encoded: string): Record<string, unknown>;
+
+/**
+ * Read a litmus attestation from chain (the trust-critical read — onchain-proof
+ * §7). Needs an RPC + a registered schema; the agent-gate calls this, then
+ * re-checks the live fingerprint before paying.
+ *
+ * [verify] eas-sdk EAS.getAttestation return shape (uid / data / revocationTime).
+ */
+/** The registered litmus schema UID for the selected network (from env). */
+declare function litmusSchemaUID(): string;
+interface OnchainLitmusAttestation {
+    uid: string;
+    serverRef: string;
+    toolDefsFingerprint: string;
+    overallGrade: string;
+    reportCID: string;
+    /** The version the grade was run against; null for HTTP/unresolved targets
+     *  (the on-chain empty-string sentinel is normalized to null here). */
+    resolvedVersion: string | null;
+    revoked: boolean;
+    /** Account that signed the attestation (self-mint model: any address). */
+    attester: string;
+    /** EAS expiry in unix seconds; 0n = no expiration. */
+    expirationTime: bigint;
+}
+declare function readAttestation(uid: string): Promise<OnchainLitmusAttestation | null>;
+
+/**
+ * The agent payment-gate (technical-design §6, onchain-proof-spec §7).
+ *
+ * Before an agent trusts (and pays) an MCP server, it checks the polygraph
+ * cheapest-first:
+ *   1. no attestation → refuse
+ *   2. server-ref binding — the attestation must be FOR this server, not a
+ *      grade-A attestation minted over a *different* server → refuse on mismatch
+ *   3. live-fingerprint check — recompute the live tool surface; if it ≠ the
+ *      attested fingerprint → refuse (rug pull): the surface changed since it
+ *      was graded
+ *   4. grade check — a failing grade → refuse, 0 spent
+ * All pass → pay.
+ *
+ * `gateDecision` is pure and unit-tested; `liveFingerprint` reuses the harness
+ * and returns the connected server's canonical ref so the binding compares
+ * apples to apples.
+ */
+
+interface AttestationView {
+    /** Canonical ref the attestation was minted for (binds grade↔server). */
+    serverRef: string;
+    toolDefsFingerprint: string;
+    overallGrade: string;
+    /**
+     * The version the grade was run against, surfaced for the human/agent log.
+     * ADVISORY ONLY: there is no trustworthy live-version oracle, so this never
+     * affects the decision — the fingerprint is the sole cryptographic anchor.
+     */
+    resolvedVersion?: string | null;
+    revoked?: boolean;
+    /** EAS expiry in unix seconds; 0n / undefined = no expiration. */
+    expirationTime?: bigint;
+}
+interface LiveTarget {
+    fingerprint: string;
+    serverRef: string;
+}
+type GateAction = "pay" | "refuse";
+interface GateDecision {
+    action: GateAction;
+    reason: string;
+}
+/** Grades an agent will transact with. F (injection/leak) and D (egress) are out. */
+declare const DEFAULT_PASSING: Set<string>;
+declare function gateDecision(attestation: AttestationView | null, live: LiveTarget, passing?: Set<string>, now?: bigint): GateDecision;
+/**
+ * Recompute the live tool-surface fingerprint of a target (the mandatory
+ * call-time check) and return the connected server's canonical ref alongside it,
+ * so the gate can bind the attestation to the actual server.
+ */
+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.
+ *
+ * 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.
+ */
+
+declare const RUN_LITMUS_TOOL_NAME = "run_litmus";
+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 }: {
+    server_ref: string;
+    pin?: boolean;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    isError: true;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+
+/**
+ * `polygraphso litmus <ref | https-url | path-to-mcp>` — run the behavioral
+ * 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[];
+    serverRef?: string;
+};
+interface ParsedLitmusFlags {
+    /** HTTP headers for a remote target (e.g. `Authorization: Bearer …`). */
+    headers: Record<string, string>;
+    /** Whether to actively call state-changing tools (opt-in). */
+    allowStateChanging: boolean;
+    /** Non-flag arguments, in order (positionals[0] is the target). */
+    positionals: string[];
+}
+/**
+ * Parse the litmus flags into HTTP headers + the state-changing opt-in, and
+ * separate out the positional target. Proper parsing (not just "first non-flag
+ * arg") matters because `--bearer <token>` takes a value that must not be
+ * mistaken for the target.
+ *
+ * Authorization precedence (last wins): `LITMUS_BEARER` < `--bearer` < `--header`.
+ */
+declare function parseAuthFlags(args: readonly string[], env?: NodeJS.ProcessEnv): ParsedLitmusFlags;
+/** A target is an https URL, a local MCP entry file, or a registry ref. */
+declare function resolveTarget(target: string): string | StdioCommand;
+
+export { type AttestationView, BUNDLE_SCHEMA_VERSION, type BundleInput, CATEGORY_STATUS_UINT8, type CategoryCode, type CategoryResult, type CategoryStatus, type ConnectOptions, type ConnectedTarget, DEFAULT_PASSING, type EvidenceBundle, type Finding, type FindingKind, type FingerprintResult, type GateAction, type GateDecision, type Grade, type HarnessInfo, LITMUS_SCHEMA, type LitmusAttestationFields, type LitmusGrade, type RunLitmusOptions as LitmusOptions, METHODOLOGY_VERSION, NETWORKS, type Network, type NetworkConfig, type OnchainLitmusAttestation, type ParsedLitmusFlags, type ParsedServerRef, type ProbeContext, type ProbeId, type ProbeResult, type ProbeStatus, RUN_LITMUS_TOOL_DESCRIPTION, RUN_LITMUS_TOOL_NAME, RUN_LITMUS_TOOL_TITLE, type Registry, type RunLitmusOptions, ServerRefParseError, type Severity, type StdioCommand, type TargetDescriptor, type TargetInput, type TargetKind, type ToolAnnotations, type ToolDef, type ToolSafety, 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 };