@crawlcheck/sdk 1.0.8 → 1.1.0

package/README.md

@@ -50,6 +50,25 @@ v.decisions.transact;  // allow | warn | require_confirmation | block | unsuppor
 
 `stapleCheck(record, { host, publishedKids })` does the offline check on its own. Spec: https://crawlcheck.io/spec/staple
 
+## Preflight inside your MCP client
+
+Wrap the official MCP client so `connect` and `callTool` are decided before anything is sent ([proposal](https://crawlcheck.io/spec/mcp-preflight)):
+
+```js
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { CrawlCheck, withPreflight, McpPreflightRefused } from "@crawlcheck/sdk";
+
+const client = withPreflight(new Client({ name: "my-agent", version: "1.0.0" }), new CrawlCheck(), {
+  confirm: async (receipt) => askTheUser(receipt),   // require_confirmation, and destructive tools with confirmDestructive
+  lock: approvedLock,                                 // optional: refuse a server whose tools changed, and any tool outside the lock
+});
+try { await client.connect(new StreamableHTTPClientTransport(new URL(url))); }
+catch (e) { if (e instanceof McpPreflightRefused) console.log(e.stage, e.why, e.receipt.decision); else throw e; }
+```
+
+`block`, `unsupported`, an unverifiable receipt, or `require_confirmation` with no yes refuse the connect before `initialize`. Other client stacks use the bare hooks: `mcpPreflight(cc, opts)` returns `beforeConnect`, `afterConnect` and `beforeToolCall`. A runnable demo is in `examples/mcp-preflight-demo.mjs`.
+
 ## Do not trust the API: check the evidence yourself
 
 ```js

package/dist/index.d.ts

@@ -195,7 +195,8 @@ export interface PreflightPolicy {
 export interface PreflightOptions {
     agent?: string;
     template?: string;
-    policy?: PreflightPolicy;
+    policy?: PreflightPolicy; /** 8-128 characters of A-Z a-z 0-9 . _ : - signed into the receipt (replay binding). guard() sends a fresh one when you give none. */
+    nonce?: string;
 }
 /** A signed crawlcheck-decision receipt. Verify it with verifyDocument (or let guard() do it). */
 export interface DecisionReceipt {
@@ -220,8 +221,60 @@ export interface GuardOptions extends PreflightOptions {
     allowWarn?: boolean;
     /** Called on "require_confirmation"; proceed only if it resolves true. Without it, require_confirmation does not proceed. */
     confirm?: (receipt: DecisionReceipt) => boolean | Promise<boolean>;
-    /** Also require the signing key to be in the published key directory (default true). */
+    /** Read the published key directory (default true). With false, pass publishedKids: a guard never accepts a receipt without checking who signed it. */
     onlineKeys?: boolean;
+    /** Pinned CrawlCheck key ids, for offline use with onlineKeys: false. */
+    publishedKids?: string[];
+    /** Testing clock (ms since epoch). Default Date.now(). */
+    now?: number;
+}
+/** The longest a receipt may stay valid, per action (seconds). A receipt that claims longer is refused. Published at https://crawlcheck.io/spec/guard */
+export declare const ACTION_MAX_LIFETIME_S: Record<string, number>;
+/** The most clock skew a receipt may claim (seconds). */
+export declare const MAX_CLOCK_SKEW_S = 300;
+export interface DecisionWant {
+    domain: string;
+    action: Action | string;
+    nonce?: string | null;
+    now?: number;
+}
+/**
+ * Is this receipt about the operation you are about to perform? Checks the scope only (kind, domain, action, nonce,
+ * time window, per-action lifetime, known decision, resolve binding); the signature and issuer are checked by
+ * verifyDocument. guard() runs both. https://crawlcheck.io/spec/guard
+ */
+export declare function checkDecision(receipt: unknown, want: DecisionWant): {
+    ok: boolean;
+    why: string[];
+};
+export interface GuardResult {
+    proceed: boolean;
+    receipt: DecisionReceipt | null;
+    verification: (DocumentVerification & Trust) | null;
+    header: Record<string, string> | null;
+    why: string[];
+    split_view?: LogFork[];
+}
+export interface GuardedFetchOptions extends GuardOptions {
+    action?: Action;
+    init?: RequestInit;
+    maxHops?: number;
+    fetch?: typeof fetch;
+}
+export interface GuardedHop {
+    url: string;
+    domain: string;
+    proceed: boolean;
+    decision: string | null;
+    why: string[];
+    status?: number;
+}
+export interface GuardedFetchResult {
+    proceed: boolean;
+    response: Response | null;
+    url: string;
+    hops: GuardedHop[];
+    why: string[];
 }
 export interface LogHead {
     kind: "crawlcheck-log-sth";
@@ -356,6 +409,71 @@ export declare const stapleCheck: (record: string, opts: {
     publishedKids: string[];
     now?: number;
 }) => Promise<StapleCheck>;
+export interface McpPreflightOptions extends PreflightOptions {
+    /** Proceed on warn too (default false). */
+    allowWarn?: boolean;
+    /** Called on require_confirmation (and, with confirmDestructive, before a destructive tool call); the connect or call proceeds only if it resolves true. */
+    confirm?: (receipt: DecisionReceipt & {
+        tool?: string;
+        annotations?: unknown;
+    }) => boolean | Promise<boolean>;
+    /** An approved lockfile (mcpLock / lockFromTools): the tools the server lists after connecting must match it, and only tools in it may be called. */
+    lock?: McpLock;
+    /** Ask confirm() before a tool annotated destructive (destructiveHint true, or readOnlyHint false with openWorldHint true). */
+    confirmDestructive?: boolean;
+    /** Re-decide the host when the cached connect receipt is older than this (default: until its expires_at). */
+    maxAgeMs?: number;
+    /** A local (stdio) server has no host to resolve: "allow" (default) or "refuse". */
+    local?: "allow" | "refuse";
+    /** The server URL when the transport does not expose it. */
+    serverUrl?: string;
+    onlineKeys?: boolean;
+}
+export interface McpPreflightState {
+    url: string | null;
+    host: string | null;
+    receipt: DecisionReceipt | null;
+    verification: (DocumentVerification & Trust) | null;
+    decidedAt: number;
+    lockCheck: McpLockCheck | null;
+    approved: Set<string> | null;
+}
+export interface McpPreflightHooks {
+    state: McpPreflightState;
+    beforeConnect(url: string | null | undefined): Promise<{
+        local: boolean;
+        host?: string;
+        receipt: DecisionReceipt | null;
+        verification?: DocumentVerification & Trust;
+    }>;
+    afterConnect(tools: McpTool[]): Promise<McpLockCheck | null>;
+    beforeToolCall(name: string, annotations?: unknown): Promise<{
+        receipt: DecisionReceipt | null;
+    }>;
+}
+/** Thrown by the hooks when a connect or tools/call is refused; the request was never sent. */
+export declare const McpPreflightRefused: new (stage: "connect" | "tools/call", why: string, detail?: {
+    receipt?: DecisionReceipt | null;
+    lock?: McpLockCheck | null;
+    verification?: unknown;
+}) => Error & {
+    stage: "connect" | "tools/call";
+    why: string;
+    receipt: DecisionReceipt | null;
+    lock: McpLockCheck | null;
+    verification: unknown;
+};
+/** The two hooks (beforeConnect, beforeToolCall) plus afterConnect for lockfiles, for any MCP client stack. */
+export declare const mcpPreflight: (cc: CrawlCheck, opts?: McpPreflightOptions) => McpPreflightHooks;
+/** Wrap an MCP client (the official @modelcontextprotocol/sdk Client, or anything with connect(transport) and callTool(params)) so both run the preflight first. Returns the same client with client.preflight set. */
+export declare const withPreflight: <C extends {
+    connect: (...a: any[]) => Promise<any>;
+    callTool: (...a: any[]) => Promise<any>;
+}>(client: C, cc: CrawlCheck, opts?: McpPreflightOptions) => C & {
+    preflight: McpPreflightHooks;
+};
+/** The server URL a transport will talk to, if it exposes one (Streamable HTTP and SSE transports do). */
+export declare const transportUrl: (transport: unknown) => string | null;
 export interface ClientOptions {
     /** Licence key (cc_ + 32 hex). Without one, licence-gated fields come back withheld, exactly as on the website. */
     key?: string;
@@ -434,14 +552,20 @@ export declare class CrawlCheck {
     preflight(domain: string, action?: Action, opts?: PreflightOptions): Promise<DecisionReceipt>;
     /** Verify a signed document here. With onlineKeys (default), its signing key must also be in the published directory. */
     verifyDocument(doc: unknown, onlineKeys?: boolean): Promise<DocumentVerification & Trust>;
-    /** Preflight, verify the receipt, and decide. Proceeds on allow; warn only with allowWarn; require_confirmation only if confirm() says yes; block and unsupported never. */
-    guard(domain: string, action?: Action, opts?: GuardOptions): Promise<{
-        proceed: boolean;
-        receipt: DecisionReceipt;
-        verification: DocumentVerification & Trust;
-        header: Record<string, string> | null;
-        split_view?: LogFork[];
-    }>;
+    /**
+     * Preflight, verify the receipt, check it is for THIS operation, and decide. Proceeds on allow; warn only with allowWarn;
+     * require_confirmation only if confirm() says yes; block, unsupported and every failure never (fail closed: an error,
+     * an unreachable CrawlCheck, a malformed, foreign, expired, replayed or out-of-scope receipt all return proceed false
+     * with why[]). Passes the acceptance suite at https://crawlcheck.io/spec/guard
+     */
+    guard(domain: string, action?: Action, opts?: GuardOptions): Promise<GuardResult>;
+    /**
+     * fetch() with the check where the action runs: guard() before the first request, and again before every redirect hop
+     * to a new domain. The site is contacted only after its domain proceeds; a refused hop is never requested. Redirects
+     * are followed by hand (GET/HEAD only), to http(s) only, at most maxHops (10). The receipt header is sent only to the
+     * domain it names. In a browser a cross-origin redirect hides its target, so it is refused rather than followed blind.
+     */
+    guardedFetch(url: string, opts?: GuardedFetchOptions): Promise<GuardedFetchResult>;
     /** Look a domain up without sending it: only the first prefixLen hex characters of sha256(domain) leave this process. found false with ready true means no public measurement. */
     /** Make a signed lockfile for an MCP server (CrawlCheck reads tools/list; no tool is called). Save it; check with checkLock before every connect. */
     mcpLock(url: string): Promise<McpLock & JsonObject>;

package/dist/index.js

@@ -1,6 +1,7 @@
 import * as V from "./verify.js";
 import * as L from "./log.js";
 import * as S from "./staple.js";
+import * as M from "./mcp.js";
 function withTrust(v, kid, published) {
     let checks = v.checks;
     let issuer = null;
@@ -37,6 +38,7 @@ export function normalizeDomain(v) {
 }
 /** { "CrawlCheck-Receipt": "v=1; sha256=..." } for a decision receipt. Send it only to the domain the receipt names, before expires_at. */
 export function receiptHeader(receipt) { return { [RECEIPT_HEADER]: "v=1; sha256=" + receipt.sha256 }; }
+function randomNonce() { const b = new Uint8Array(16); globalThis.crypto.getRandomValues(b); return Array.from(b, (x) => x.toString(16).padStart(2, "0")).join(""); }
 async function sha256Hex(s) {
     const b = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(s));
     return Array.from(new Uint8Array(b), (x) => x.toString(16).padStart(2, "0")).join("");
@@ -63,6 +65,50 @@ export async function checkLock(lock, tools) {
     const same = lock?.tools_sha256 === now.tools_sha256 && !added.length && !removed.length && !modified.length;
     return { verdict: same ? "unchanged" : "changed", decision: same ? "connect" : "block", approved_tools_sha256: lock?.tools_sha256 ?? "", current_tools_sha256: now.tools_sha256, added, removed, modified };
 }
+/** The longest a receipt may stay valid, per action (seconds). A receipt that claims longer is refused. Published at https://crawlcheck.io/spec/guard */
+export const ACTION_MAX_LIFETIME_S = { read: 86400, cite: 86400, connect: 3600, transact: 300, administer: 300 };
+/** The most clock skew a receipt may claim (seconds). */
+export const MAX_CLOCK_SKEW_S = 300;
+const DECISIONS = ["allow", "warn", "require_confirmation", "block", "unsupported"];
+/**
+ * Is this receipt about the operation you are about to perform? Checks the scope only (kind, domain, action, nonce,
+ * time window, per-action lifetime, known decision, resolve binding); the signature and issuer are checked by
+ * verifyDocument. guard() runs both. https://crawlcheck.io/spec/guard
+ */
+export function checkDecision(receipt, want) {
+    const why = [], r = receipt;
+    if (!r || typeof r !== "object" || Array.isArray(r))
+        return { ok: false, why: ["no receipt: CrawlCheck sent " + (r === null || r === undefined ? "nothing" : typeof r)] };
+    if (r.kind !== "crawlcheck-decision" || r.v !== 1)
+        why.push("not a v1 decision receipt (kind " + r.kind + ", v " + r.v + ")");
+    const wd = normalizeDomain(want.domain);
+    if (!wd || normalizeDomain(r.domain) !== wd)
+        why.push("the receipt is for " + r.domain + ", not " + want.domain);
+    if (String(r.action) !== String(want.action))
+        why.push("the receipt is for action " + r.action + ", not " + want.action);
+    if (want.nonce && r.nonce !== want.nonce)
+        why.push(r.nonce ? "the receipt carries another request's nonce (replayed)" : "the receipt does not carry the nonce this request sent");
+    const now = want.now ?? Date.now(), skew = Math.min(Math.max(Number(r.clock_skew_s) || 0, 0), MAX_CLOCK_SKEW_S) * 1000;
+    const at = Date.parse(r.decided_at), exp = Date.parse(r.expires_at);
+    if (!isFinite(at) || !isFinite(exp))
+        why.push("decided_at or expires_at missing");
+    else {
+        if (now > exp + skew)
+            why.push("expired at " + r.expires_at);
+        if (at > now + skew)
+            why.push("decided in the future (" + r.decided_at + "): check the clock");
+        const max = ACTION_MAX_LIFETIME_S[String(want.action)];
+        if (max === undefined)
+            why.push("unknown action " + want.action);
+        else if (exp - at > max * 1000 + 1000)
+            why.push("valid for " + Math.round((exp - at) / 1000) + " s; a " + want.action + " receipt may last at most " + max + " s");
+    }
+    if (DECISIONS.indexOf(r.decision) < 0)
+        why.push("unknown decision " + r.decision);
+    if (!r.resolve || !/^[0-9a-f]{64}$/.test(String(r.resolve.sha256 || "")))
+        why.push("the receipt names no resolve answer");
+    return { ok: why.length === 0, why };
+}
 export const LOG_ID = L.LOG_ID;
 /** A new, empty transparency-log store (plain JSON: persist it between runs). */
 export const newLogStore = L.newLogStore;
@@ -83,6 +129,14 @@ export const parseStaple = S.parseStaple;
 export const stapleFromResponse = S.stapleFromResponse;
 /** Verify a staple offline: published key, signature, the record names opts.host (or a parent), fresh_until in the future. Expired or foreign staples are never valid. */
 export const stapleCheck = S.stapleCheck;
+/** Thrown by the hooks when a connect or tools/call is refused; the request was never sent. */
+export const McpPreflightRefused = M.McpPreflightRefused;
+/** The two hooks (beforeConnect, beforeToolCall) plus afterConnect for lockfiles, for any MCP client stack. */
+export const mcpPreflight = M.mcpPreflight;
+/** Wrap an MCP client (the official @modelcontextprotocol/sdk Client, or anything with connect(transport) and callTool(params)) so both run the preflight first. Returns the same client with client.preflight set. */
+export const withPreflight = M.withPreflight;
+/** The server URL a transport will talk to, if it exposes one (Streamable HTTP and SSE transports do). */
+export const transportUrl = M.transportUrl;
 export class CrawlCheckError extends Error {
     status;
     body;
@@ -190,29 +244,122 @@ export class CrawlCheck {
             b.template = opts.template;
         if (opts.policy)
             b.policy = opts.policy;
+        if (opts.nonce)
+            b.nonce = opts.nonce;
         return this.post("/api/v1/preflight", b);
     }
     /** Verify a signed document here. With onlineKeys (default), its signing key must also be in the published directory. */
     async verifyDocument(doc, onlineKeys = true) {
         return withTrust(await V.verifyDataDoc(doc), doc?.signature?.kid, onlineKeys ? await this.publishedKeyIds() : null);
     }
-    /** Preflight, verify the receipt, and decide. Proceeds on allow; warn only with allowWarn; require_confirmation only if confirm() says yes; block and unsupported never. */
+    /**
+     * Preflight, verify the receipt, check it is for THIS operation, and decide. Proceeds on allow; warn only with allowWarn;
+     * require_confirmation only if confirm() says yes; block, unsupported and every failure never (fail closed: an error,
+     * an unreachable CrawlCheck, a malformed, foreign, expired, replayed or out-of-scope receipt all return proceed false
+     * with why[]). Passes the acceptance suite at https://crawlcheck.io/spec/guard
+     */
     async guard(domain, action = "read", opts = {}) {
-        const receipt = await this.preflight(domain, action, opts);
-        if (this.log.forks.length) { // the log has shown this client two contradicting histories: no answer from it is trusted for action
-            const verification = await this.verifyDocument(receipt, opts.onlineKeys ?? true);
-            return { proceed: false, receipt, verification, header: null, split_view: this.log.forks.slice() };
+        const nonce = opts.nonce || randomNonce();
+        const no = (why, receipt = null, verification = null) => ({ proceed: false, receipt, verification, header: null, why });
+        let receipt;
+        try {
+            receipt = await this.preflight(domain, action, Object.assign({}, opts, { nonce }));
+        }
+        catch (e) {
+            return no(["CrawlCheck did not give a decision: " + (e?.message || e)]);
         }
-        const verification = await this.verifyDocument(receipt, opts.onlineKeys ?? true);
-        if (!verification.accepted && (opts.onlineKeys ?? true))
-            return { proceed: false, receipt, verification, header: null };
-        if (!verification.verified)
-            return { proceed: false, receipt, verification, header: null };
+        if (this.log.forks.length)
+            return Object.assign(no(["the transparency log has shown this client two histories (split view)"], receipt), { split_view: this.log.forks.slice() });
+        const scope = checkDecision(receipt, { domain, action, nonce, now: opts.now });
+        if (!receipt || typeof receipt !== "object")
+            return no(scope.why);
+        const online = opts.onlineKeys ?? true;
+        if (!online && !(Array.isArray(opts.publishedKids) && opts.publishedKids.length))
+            return no(["onlineKeys is false and no publishedKids were pinned: the signer cannot be checked"], receipt);
+        let verification;
+        try {
+            verification = withTrust(await V.verifyDataDoc(receipt), receipt?.signature?.kid, online ? await this.publishedKeyIds() : opts.publishedKids);
+        }
+        catch (e) {
+            return no(["the receipt could not be verified: " + (e?.message || e)].concat(scope.why), receipt);
+        }
+        const why = scope.why.slice();
+        if (!verification.integrity_valid)
+            why.push("integrity failed: " + verification.checks.filter((c) => c.ok === false).map((c) => c.id).join(", "));
+        if (verification.issuer_trusted !== true)
+            why.push("signed by a key that is not in CrawlCheck's published key directory");
+        if (why.length)
+            return no(why, receipt, verification);
         const d = receipt.decision;
         let proceed = d === "allow" || (d === "warn" && !!opts.allowWarn);
-        if (d === "require_confirmation" && opts.confirm)
-            proceed = !!(await opts.confirm(receipt));
-        return { proceed, receipt, verification, header: proceed ? receiptHeader(receipt) : null };
+        if (d === "require_confirmation") {
+            if (opts.confirm) {
+                try {
+                    proceed = (await opts.confirm(receipt)) === true;
+                }
+                catch {
+                    proceed = false;
+                }
+            }
+        }
+        if (!proceed)
+            why.push(d === "warn" ? "decision is warn and allowWarn is not set" : d === "require_confirmation" ? (opts.confirm ? "a human did not confirm" : "decision is require_confirmation and no confirm() was given") : "decision is " + d);
+        return { proceed, receipt, verification, header: proceed ? receiptHeader(receipt) : null, why };
+    }
+    /**
+     * fetch() with the check where the action runs: guard() before the first request, and again before every redirect hop
+     * to a new domain. The site is contacted only after its domain proceeds; a refused hop is never requested. Redirects
+     * are followed by hand (GET/HEAD only), to http(s) only, at most maxHops (10). The receipt header is sent only to the
+     * domain it names. In a browser a cross-origin redirect hides its target, so it is refused rather than followed blind.
+     */
+    async guardedFetch(url, opts = {}) {
+        const action = opts.action ?? "read", max = opts.maxHops ?? 10, f = opts.fetch ? opts.fetch.bind(globalThis) : this.f;
+        const init = Object.assign({}, opts.init || {}), method = String(init.method || "GET").toUpperCase();
+        const hops = [], seen = new Map();
+        let cur = url;
+        for (let n = 0; n <= max; n++) {
+            let u;
+            try {
+                u = new URL(cur);
+            }
+            catch {
+                return { proceed: false, response: null, url: cur, hops, why: ["not a URL: " + cur] };
+            }
+            if (u.protocol !== "https:" && u.protocol !== "http:")
+                return { proceed: false, response: null, url: cur, hops, why: ["refused a " + u.protocol + " URL"] };
+            const dom = normalizeDomain(u.hostname);
+            if (!dom)
+                return { proceed: false, response: null, url: cur, hops, why: ["not a public domain name: " + u.hostname] };
+            let g = seen.get(dom);
+            if (!g) {
+                g = await this.guard(dom, action, opts);
+                seen.set(dom, g);
+            }
+            const hop = { url: cur, domain: dom, proceed: g.proceed, decision: g.receipt ? String(g.receipt.decision) : null, why: g.why };
+            hops.push(hop);
+            if (!g.proceed)
+                return { proceed: false, response: null, url: cur, hops, why: [dom + ": " + (g.why.join("; ") || "refused")] };
+            const h = new Headers(init.headers || {});
+            if (g.header)
+                for (const [k, v] of Object.entries(g.header))
+                    h.set(k, v);
+            const res = await f(cur, Object.assign({}, init, { headers: h, redirect: "manual" }));
+            hop.status = res.status;
+            if (res.type === "opaqueredirect")
+                return { proceed: false, response: null, url: cur, hops, why: ["the runtime hid the redirect target, so it cannot be checked"] };
+            const loc = res.headers.get("location");
+            if (![301, 302, 303, 307, 308].includes(res.status) || !loc)
+                return { proceed: true, response: res, url: cur, hops, why: [] };
+            if (method !== "GET" && method !== "HEAD")
+                return { proceed: true, response: res, url: cur, hops, why: ["redirect not followed for " + method] };
+            try {
+                cur = new URL(loc, cur).toString();
+            }
+            catch {
+                return { proceed: false, response: null, url: cur, hops, why: ["unreadable redirect target " + loc] };
+            }
+        }
+        return { proceed: false, response: null, url: cur, hops, why: ["more than " + max + " redirects"] };
     }
     /** Look a domain up without sending it: only the first prefixLen hex characters of sha256(domain) leave this process. found false with ready true means no public measurement. */
     /** Make a signed lockfile for an MCP server (CrawlCheck reads tools/list; no tool is called). Save it; check with checkLock before every connect. */

package/dist/mcp.d.ts

@@ -0,0 +1,50 @@
+/** The server URL a transport will talk to, if it can be read (Streamable HTTP and SSE transports keep it as _url or url). */
+export function transportUrl(transport: any): string | null;
+/**
+ * The two hooks. cc is a CrawlCheck client (from this SDK). opts: template (default safe_mcp_tool), policy, agent,
+ * confirm(receipt) for require_confirmation, allowWarn, lock (an approved McpLock), confirmDestructive, maxAgeMs for a
+ * cached connect receipt (default: until the receipt's expires_at).
+ */
+export function mcpPreflight(cc: any, opts?: {}): {
+    state: {
+        url: null;
+        host: null;
+        receipt: null;
+        verification: null;
+        decidedAt: number;
+        lockCheck: null;
+        approved: null;
+    };
+    /** Before initialize. url: the server URL (a stdio/local server has none and is not decided; pass opts.local = "allow" | "refuse", default allow). */
+    beforeConnect(url: any): Promise<{
+        local: boolean;
+        receipt: null;
+        host?: undefined;
+        verification?: undefined;
+    } | {
+        local: boolean;
+        host: string;
+        receipt: any;
+        verification: any;
+    }>;
+    /** After initialize, with the tools the server lists. Refuses (and the wrapper closes the client) when they differ from the approved lockfile. */
+    afterConnect(tools: any): Promise<import("./index.js").McpLockCheck | null>;
+    /** Before tools/call. */
+    beforeToolCall(name: any, annotations: any): Promise<{
+        receipt: null;
+    }>;
+};
+/**
+ * Wrap an MCP client in place: client.connect and client.callTool run the hooks first. Returns the same client, with
+ * client.preflight (the hooks and their state). Works on @modelcontextprotocol/sdk's Client and on anything with the same
+ * two methods; listTools() is used for the lockfile check when present.
+ */
+export function withPreflight(client: any, cc: any, opts?: {}): any;
+export class McpPreflightRefused extends Error {
+    constructor(stage: any, why: any, detail: any);
+    stage: any;
+    why: any;
+    receipt: any;
+    lock: any;
+    verification: any;
+}

package/dist/mcp.js

@@ -0,0 +1,164 @@
+// Preflight as an MCP client extension (https://crawlcheck.io/spec/mcp-preflight). Reference middleware: the check runs
+// in the protocol path, before `initialize` reaches a server and before every `tools/call`, instead of being a call the
+// agent remembers to make. It wraps any MCP client object that has connect(transport) and callTool(params) (the official
+// @modelcontextprotocol/sdk Client does), or is used as two bare hooks for other client stacks.
+//
+//   connect:   the server's host is resolved and the "connect" action decided (template safe_mcp_tool). block, unsupported
+//              and an unverifiable receipt refuse the connect before a byte is sent; require_confirmation asks opts.confirm.
+//              With opts.lock, the tools the server lists after connecting must match the approved lockfile, or the client
+//              is closed again.
+//   tools/call: the connect receipt must still be unexpired (else the host is decided again); a tool outside the approved
+//              lockfile is refused; a tool annotated destructive (destructiveHint true, or readOnlyHint false with
+//              openWorldHint true) asks opts.confirm when opts.confirmDestructive is set.
+// Nothing here calls a tool, reads arguments or alters the request; a refused call throws McpPreflightRefused and the
+// request is never sent.
+import { normalizeDomain } from "./index.js";
+import { checkLock } from "./index.js";
+export class McpPreflightRefused extends Error {
+    constructor(stage, why, detail) { super("MCP preflight refused " + stage + ": " + why); this.name = "McpPreflightRefused"; this.stage = stage; this.why = why; this.receipt = detail && detail.receipt || null; this.lock = detail && detail.lock || null; this.verification = detail && detail.verification || null; }
+}
+/** The server URL a transport will talk to, if it can be read (Streamable HTTP and SSE transports keep it as _url or url). */
+export function transportUrl(transport) {
+    if (!transport)
+        return null;
+    for (const k of ["_url", "url", "endpoint", "_endpoint"]) {
+        const v = transport[k];
+        if (v instanceof URL)
+            return v.toString();
+        if (typeof v === "string" && /^https?:\/\//i.test(v))
+            return v;
+    }
+    return null;
+}
+function hostOf(url) { try {
+    return normalizeDomain(new URL(url).hostname);
+}
+catch (e) {
+    return null;
+} }
+function destructive(ann) { if (!ann || typeof ann !== "object")
+    return false; if (ann.destructiveHint === true)
+    return true; return ann.readOnlyHint === false && ann.openWorldHint === true; }
+/**
+ * The two hooks. cc is a CrawlCheck client (from this SDK). opts: template (default safe_mcp_tool), policy, agent,
+ * confirm(receipt) for require_confirmation, allowWarn, lock (an approved McpLock), confirmDestructive, maxAgeMs for a
+ * cached connect receipt (default: until the receipt's expires_at).
+ */
+export function mcpPreflight(cc, opts = {}) {
+    const template = opts.template || "safe_mcp_tool";
+    const state = { url: null, host: null, receipt: null, verification: null, decidedAt: 0, lockCheck: null, approved: null };
+    const fresh = function () {
+        if (!state.receipt)
+            return false;
+        const exp = Date.parse(state.receipt.expires_at || "");
+        if (isFinite(exp) && Date.now() > exp)
+            return false;
+        if (opts.maxAgeMs && Date.now() - state.decidedAt > opts.maxAgeMs)
+            return false;
+        return true;
+    };
+    const decide = async function (host) {
+        const g = await cc.guard(host, "connect", { template, policy: opts.policy, agent: opts.agent, confirm: opts.confirm, allowWarn: !!opts.allowWarn, onlineKeys: opts.onlineKeys });
+        state.receipt = g.receipt;
+        state.verification = g.verification;
+        state.decidedAt = Date.now();
+        if (!g.proceed) {
+            const d = g.receipt && g.receipt.decision;
+            const decisionOnly = (g.why || []).every(function (w) { return /^decision is|a human did not confirm|no confirm\(\) was given|allowWarn is not set/.test(w); });
+            const why = g.split_view ? "the transparency log showed two histories; no answer is trusted" : !g.verification ? ((g.why || []).join("; ") || "no decision") : !g.verification.verified ? "the decision receipt did not verify" : g.verification.accepted === false ? "the receipt was signed with a key CrawlCheck does not publish" : !decisionOnly ? g.why.join("; ") : !g.verification.verified ? "the decision receipt did not verify" : g.verification.accepted === false ? "the receipt was signed with a key CrawlCheck does not publish" : d === "require_confirmation" ? "a human must confirm and none did" : d === "warn" ? "warn without allowWarn" : d === "unsupported" ? "nothing vouches for a connection to " + host + " (" + ((g.receipt.steps || [])[0] || {}).why + ")" : "decision " + d + (g.receipt.steps && g.receipt.steps[0] ? " (" + g.receipt.steps[0].why + ")" : "");
+            throw new McpPreflightRefused("connect", why, { receipt: g.receipt, verification: g.verification });
+        }
+        return g;
+    };
+    return {
+        state,
+        /** Before initialize. url: the server URL (a stdio/local server has none and is not decided; pass opts.local = "allow" | "refuse", default allow). */
+        async beforeConnect(url) {
+            if (!url) {
+                if (opts.local === "refuse")
+                    throw new McpPreflightRefused("connect", "a local (stdio) server cannot be resolved and opts.local is refuse");
+                state.url = null;
+                state.host = null;
+                return { local: true, receipt: null };
+            }
+            const host = hostOf(url);
+            if (!host)
+                throw new McpPreflightRefused("connect", "not a server URL: " + url);
+            state.url = url;
+            state.host = host;
+            const g = await decide(host);
+            return { local: false, host, receipt: g.receipt, verification: g.verification };
+        },
+        /** After initialize, with the tools the server lists. Refuses (and the wrapper closes the client) when they differ from the approved lockfile. */
+        async afterConnect(tools) {
+            if (!opts.lock) {
+                state.approved = null;
+                return null;
+            }
+            const lc = await checkLock(opts.lock, tools || []);
+            state.lockCheck = lc;
+            state.approved = new Set((opts.lock.tools || []).map(function (t) { return t.name; }));
+            if (lc.decision !== "connect")
+                throw new McpPreflightRefused("connect", "the server's tools differ from the approved lockfile (added " + lc.added.length + ", removed " + lc.removed.length + ", modified " + lc.modified.length + ")", { lock: lc });
+            return lc;
+        },
+        /** Before tools/call. */
+        async beforeToolCall(name, annotations) {
+            if (state.host && !fresh())
+                await decide(state.host);
+            if (state.approved && !state.approved.has(name))
+                throw new McpPreflightRefused("tools/call", "tool " + name + " is not in the approved lockfile", { lock: state.lockCheck, receipt: state.receipt });
+            if (opts.confirmDestructive && destructive(annotations)) {
+                const ok = opts.confirm ? await opts.confirm(Object.assign({}, state.receipt || {}, { tool: name, annotations })) : false;
+                if (!ok)
+                    throw new McpPreflightRefused("tools/call", "tool " + name + " is annotated destructive and no human confirmed", { receipt: state.receipt });
+            }
+            return { receipt: state.receipt };
+        }
+    };
+}
+/**
+ * Wrap an MCP client in place: client.connect and client.callTool run the hooks first. Returns the same client, with
+ * client.preflight (the hooks and their state). Works on @modelcontextprotocol/sdk's Client and on anything with the same
+ * two methods; listTools() is used for the lockfile check when present.
+ */
+export function withPreflight(client, cc, opts = {}) {
+    const pf = mcpPreflight(cc, opts);
+    const connect = client.connect.bind(client), callTool = client.callTool.bind(client);
+    const tools = {};
+    client.connect = async function (transport, ...rest) {
+        await pf.beforeConnect(opts.serverUrl || transportUrl(transport));
+        const r = await connect(transport, ...rest);
+        if (opts.lock || opts.confirmDestructive) {
+            let list = [];
+            try {
+                const t = typeof client.listTools === "function" ? await client.listTools() : null;
+                list = (t && t.tools) || [];
+            }
+            catch (e) {
+                list = [];
+            }
+            list.forEach(function (t) { if (t && t.name)
+                tools[t.name] = t; });
+            try {
+                await pf.afterConnect(list);
+            }
+            catch (e) {
+                try {
+                    if (typeof client.close === "function")
+                        await client.close();
+                }
+                catch (e2) { }
+                throw e;
+            }
+        }
+        return r;
+    };
+    client.callTool = async function (params, ...rest) {
+        const name = params && params.name;
+        await pf.beforeToolCall(name, tools[name] && tools[name].annotations);
+        return callTool(params, ...rest);
+    };
+    client.preflight = pf;
+    return client;
+}