@crawlcheck/sdk 1.0.7 → 1.0.9

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

@@ -356,6 +356,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;

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;
@@ -83,6 +84,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;

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,163 @@
+// 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 why = g.split_view ? "the transparency log showed two histories; no answer is trusted" : !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;
+}

package/dist/verify.d.ts

@@ -10,10 +10,20 @@ export function dspVerdict(m: any): {
     rule: string;
 };
 export function rfcRootV(leafHex: any, index: any, size: any, path: any): Promise<string | null>;
+export function tvReachV(envelope: any): any;
+export function verifyThresholdSigners(x: any): Promise<{
+    observer_id: any;
+    network: any;
+    signature: boolean;
+    binding: boolean;
+    values_match: boolean;
+    why: never[];
+}[]>;
 export function trustOf(res: any, kid: any, publishedKids: any): any;
 export function publishedKeyIds(base: any): Promise<string[]>;
 export function verifyBundle(b: any, opts: any): Promise<any>;
 export function verifyReceipt(rc: any, opts: any): Promise<any>;
 export function verifyExport(x: any, opts: any): Promise<any>;
 export function verifyResolution(x: any, opts: any): Promise<any>;
+export function verifyDnsTxt(txt: any, opts: any): Promise<any>;
 export function verifyDataDoc(x: any, opts: any): Promise<any>;

package/dist/verify.js

@@ -519,6 +519,90 @@ export async function rfcRootV(leafHex, index, size, path) {
     }
     return sn === 0 ? hex(r) : null;
 }
+// tv1: threshold-signed verdicts. Every signer is checked on its own: its Ed25519 signature over its envelope, the
+// binding of its key to its identity (GitHub's RS256 token, a self-signed enrolment, or the published key directory),
+// and the field values recomputed from its envelope. The verdict holds when signers on at least k distinct networks pass.
+const TV_OBS_PREFIX = "crawlcheck-observation-v1\n", TV_ENROL_PREFIX = "crawlcheck-observer-enrol-v1\n";
+function tvFinalV(u) { try {
+    const x = new URL(u);
+    return x.hostname.toLowerCase().replace(/^www\./, "") + (x.pathname.replace(/\/+$/, "") || "/");
+}
+catch (e) {
+    return null;
+} }
+export function tvReachV(envelope) {
+    return (envelope && Array.isArray(envelope.fetches) ? envelope.fetches : []).map((f) => ({ identity: String(f.identity), status: typeof f.status === "number" ? f.status : null, final: f.url_final ? tvFinalV(f.url_final) : null, failed: !!f.error }))
+        .sort((a, b) => (a.identity < b.identity ? -1 : a.identity > b.identity ? 1 : 0));
+}
+async function tvEd(x, msg, sig) { try {
+    const pk = await subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x }, { name: "Ed25519" }, false, ["verify"]);
+    return await subtle.verify({ name: "Ed25519" }, pk, b64(sig), enc.encode(msg));
+}
+catch (e) {
+    return null;
+} }
+async function tvJwt(token, jwk) {
+    const p = String(token || "").split(".");
+    if (p.length !== 3 || !jwk || jwk.kty !== "RSA")
+        return { ok: false };
+    let h, c;
+    try {
+        h = JSON.parse(new TextDecoder().decode(b64(p[0])));
+        c = JSON.parse(new TextDecoder().decode(b64(p[1])));
+    }
+    catch (e) {
+        return { ok: false };
+    }
+    if (h.alg !== "RS256" || (jwk.kid && h.kid !== jwk.kid))
+        return { ok: false, claims: c };
+    try {
+        const k = await subtle.importKey("jwk", { kty: "RSA", n: jwk.n, e: jwk.e, alg: "RS256", ext: true }, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["verify"]);
+        return { ok: await subtle.verify("RSASSA-PKCS1-v1_5", k, b64(p[2]), enc.encode(p[0] + "." + p[1])), claims: c, kid: h.kid };
+    }
+    catch (e) {
+        return { ok: null, claims: c };
+    }
+}
+export async function verifyThresholdSigners(x) {
+    const st = x.statement || {}, want = canon(st.values || []), rows = [];
+    for (const s of Array.isArray(x.signers) ? x.signers : []) {
+        const r = { observer_id: s.observer_id, network: s.network && s.network.class || null, signature: false, binding: false, values_match: false, why: [] };
+        const ev = s.envelope || {}, key = ev.key || {};
+        r.signature = !!(await tvEd(key.x, TV_OBS_PREFIX + canon(ev), s.sig));
+        if (!r.signature)
+            r.why.push("signature does not verify under the envelope key");
+        const b = s.binding || {};
+        if (b.kind === "github_oidc") {
+            const j = await tvJwt(b.token, b.github_key), c = j.claims || {};
+            const aud = "crawlcheck-observer:" + b64u(await sha256(b64(key.x || "")));
+            r.binding = j.ok === true && c.iss === "https://token.actions.githubusercontent.com" && c.repository === b.repository && String(c.job_workflow_ref || c.workflow_ref || "").indexOf(b.workflow_ref_prefix || "\u0000") === 0 && (Array.isArray(c.aud) ? c.aud : [c.aud]).includes(aud) && (!c.runner_environment || c.runner_environment === "github-hosted");
+            r.github_kid = j.kid || null;
+            if (!r.binding)
+                r.why.push("GitHub token does not bind this key to the observer workflow");
+        }
+        else if (b.kind === "enrolled_ed25519") {
+            const q = b.enrolment && b.enrolment.request;
+            r.binding = !!(b.key && b.key.x === key.x && q && q.observer_id === s.observer_id && q.key && q.key.x === key.x && await tvEd(key.x, TV_ENROL_PREFIX + canon(q), b.enrolment.sig));
+            if (!r.binding)
+                r.why.push("the key is not the one this observer enrolled with");
+        }
+        else if (b.kind === "published_key_directory") {
+            const thumb = b64u(await sha256(enc.encode(JSON.stringify({ crv: "Ed25519", kty: "OKP", x: key.x }))));
+            r.binding = thumb === b.kid && thumb === (x.signature && x.signature.kid);
+            r.kid = thumb;
+            if (!r.binding)
+                r.why.push("key thumbprint is not the stated (published) key id");
+        }
+        else
+            r.why.push("unknown binding " + b.kind);
+        r.values_match = canon(tvReachV(ev)) === want;
+        if (!r.values_match)
+            r.why.push("the values in this envelope differ from the statement");
+        r.passes = r.signature && r.binding && r.values_match;
+        rows.push(r);
+    }
+    return rows;
+}
 // ── data inventories, export parts and deletion records ─────────────────────────────────────────────────────────
 // Signed over sha256(canonical JSON of every field except sha256 and signature) with the prefix below. A deletion
 // record carries counts per family and the digest of the sorted deleted-key list, never the data.
@@ -528,7 +612,7 @@ async function verifyDataDoc0(x) {
         throw new Error("this runtime has no WebCrypto (crypto.subtle)");
     const checks = [];
     const C = (id, ok, why) => checks.push({ id, ok, why });
-    if (!x || !/^crawlcheck-(data-inventory|data-export-part|deletion-record|resolve|decision|snapshot|visitor|conduct|traffic-index|anchor|anchor-check|content-clock|origin|claims|read-equivalence|rights|rights-feed|mcp-scan|mcp-lock|mcp-lock-check|mcp-shadow|mcp-auth|impersonation|task-canaries|incident|revocations|high-risk|log-sth)$/.test(String(x.kind)) || !x.signature)
+    if (!x || !/^crawlcheck-(data-inventory|data-export-part|deletion-record|resolve|decision|snapshot|visitor|conduct|traffic-index|anchor|anchor-check|content-clock|origin|claims|read-equivalence|rights|rights-feed|mcp-scan|mcp-lock|mcp-lock-check|mcp-shadow|mcp-auth|impersonation|task-canaries|agent-safety-benchmark|compliance-pack|share-of-preflight|incident|revocations|high-risk|log-sth|threshold-verdict|resolve-as-of)$/.test(String(x.kind)) || !x.signature)
         throw new Error("not a CrawlCheck data inventory, export part, deletion record, resolve answer, decision receipt, snapshot manifest, visitor verdict, conduct record, traffic index, citation anchor, content clock, origin decision, claim ledger, read-equivalence certificate, rights answer, rights-feed manifest, MCP tool scan, MCP lockfile or lockfile check");
     const body = {};
     for (const k of Object.keys(x))
@@ -577,6 +661,10 @@ async function verifyDataDoc0(x) {
         const ps = Array.isArray(x.parts) ? x.parts : [];
         C("parts", ps.length > 0 && ps.every((p) => /^part-\d{4}\.ndjson\.gz$/.test(String(p.path)) && /^[0-9a-f]{64}$/.test(String(p.sha256)) && p.records > 0) && ps.reduce((a, p) => a + p.records, 0) === x.records, ps.reduce((a, p) => a + (p.records || 0), 0) === x.records ? ps.length + " parts, " + x.records + " records; check each downloaded part with sha256sum against its sha256, then each line with this tool" : "the parts' record counts do not add up to records (" + x.records + ")");
     }
+    if (x.kind === "crawlcheck-resolve" && Array.isArray(x.absences)) { // sa1: every absence states what was checked, from where and when
+        const bad = x.absences.filter((a) => !(a && a.what && (a.result === "absent" || a.result === "none") && a.at && !isNaN(Date.parse(a.at)) && a.from && a.from.observer && typeof a.scope === "string" && Array.isArray(a.checked) && a.checked.length && a.checked.every((c) => c && c.method && (a.result !== "absent" || c.status === undefined || c.status === 404 || c.status === 410))));
+        C("absences_scoped", bad.length === 0, x.absences.length + " absence record(s)" + (x.absences.length ? " (" + x.absences.map((a) => a.what).join(", ") + ")" : "") + (bad.length ? "; " + bad.length + " lack a definite check, a time, a vantage or a scope" : ", each naming what was requested, the answer, the vantage and the time"));
+    }
     if (x.kind === "crawlcheck-resolve" && x.transparency) { // tl1: the answer's place in the Resolve transparency log
         const t = x.transparency, leaf = hex(await sha256(cat(new Uint8Array([0]), enc.encode(canon(tlContentV(x))))));
         C("log_leaf", leaf === t.leaf_hash, leaf === t.leaf_hash ? "the answer's decision content hashes to its log leaf " + leaf.slice(0, 16) + "…" : "the decision content hashes to " + leaf + ", the answer names " + t.leaf_hash);
@@ -596,6 +684,41 @@ async function verifyDataDoc0(x) {
         else
             C("log_inclusion", null, "pending: the leaf is queued and merged within " + (t.merged_within_minutes || 30) + " minutes; fetch the proof at " + (t.proof || "the log"));
     }
+    if (x.kind === "crawlcheck-resolve-as-of") { // ah1: the answer in force at as_of, as signed then
+        let av = null;
+        try {
+            av = await verifyDataDoc0(x.answer);
+        }
+        catch (e) {
+            av = null;
+        }
+        C("answer_signature", !!(av && av.verified) && !!x.answer && x.answer.kind === "crawlcheck-resolve" && x.answer.domain === x.domain, av && av.verified ? "the archived answer verifies on its own (signed " + (x.answer.signature && x.answer.signature.signed_at) + ")" : "the archived answer does NOT verify");
+        const leaf = x.answer ? hex(await sha256(cat(new Uint8Array([0]), enc.encode(canon(tlContentV(x.answer)))))) : null;
+        C("answer_leaf", leaf === x.leaf_hash, leaf === x.leaf_hash ? "the answer's decision content is leaf " + String(leaf).slice(0, 16) + "…" : "the answer's content hashes to " + leaf + ", not the stated leaf");
+        const w = x.in_force || {}, t = Date.parse(x.as_of);
+        C("in_force_window", Date.parse(w.from) <= t && (w.until == null || t < Date.parse(w.until)), "as_of " + x.as_of + " falls in [" + w.from + ", " + (w.until || "now") + ")");
+        const pr = x.log_inclusion;
+        if (pr && pr.sth) {
+            const root = await rfcRootV(x.leaf_hash, pr.index, pr.batch_size, pr.path || []);
+            let sv = null;
+            try {
+                sv = await verifyDataDoc0(pr.sth);
+            }
+            catch (e) {
+                sv = null;
+            }
+            C("log_inclusion", root !== null && root === pr.sth.batch_root && !!(sv && sv.verified), root === pr.sth.batch_root ? "the leaf is in batch " + pr.batch + " of the signed log (head created " + pr.sth.created_at + ")" : "the inclusion proof does NOT reach the signed batch root");
+        }
+        else
+            C("log_inclusion", null, "not merged into the log yet; merged within 30 minutes of first appearing");
+    }
+    if (x.kind === "crawlcheck-threshold-verdict") { // tv1
+        const rows = await verifyThresholdSigners(x), k = x.threshold && x.threshold.k || 2;
+        rows.forEach((r) => C("signer:" + r.observer_id, r.passes, r.passes ? "signature, key binding (" + (x.signers.find((s) => s.observer_id === r.observer_id).binding.kind) + ") and recomputed " + (x.statement && x.statement.family) + " values all check (network " + r.network + ")" : r.why.join("; ")));
+        const nets = new Set(rows.filter((r) => r.passes).map((r) => r.network));
+        C("threshold", nets.size >= k, nets.size + " distinct network(s) signed identical values (" + [...nets].join(", ") + "); the verdict needs " + k);
+        C("key_bindings_online", null, "offline the bindings are checked against keys the document carries; online, compare the GitHub key id with " + "https://token.actions.githubusercontent.com/.well-known/jwks and enrolled keys with https://crawlcheck.io/.well-known/crawlcheck-observers.json");
+    }
     if (x.kind === "crawlcheck-deletion-record")
         C("counts", (x.deleted || []).reduce((a, f) => a + (f.keys || 0), 0) === x.deleted_total, "the per-family counts add up to deleted_total (" + x.deleted_total + ")");
     const ran = checks.filter((c) => c.ok !== null), failed = checks.filter((c) => c.ok === false);
@@ -640,6 +763,38 @@ export async function verifyBundle(b, opts) { return trustOf(await verifyBundle0
 export async function verifyReceipt(rc, opts) { return trustOf(await verifyReceipt0(rc), rc && rc.signature && rc.signature.kid, opts && opts.publishedKids); }
 export async function verifyExport(x, opts) { return trustOf(await verifyExport0(x), kidOf(x), opts && opts.publishedKids); }
 export async function verifyResolution(x, opts) { return trustOf(await verifyResolution0(x), kidOf(x), opts && opts.publishedKids); }
+// dns1: a Resolve-over-DNS TXT record (ccr1). Strings joined without spaces; quotes from dig output are stripped.
+async function verifyDnsTxt0(txt) {
+    if (!subtle)
+        throw new Error("this runtime has no WebCrypto (crypto.subtle)");
+    const checks = [], C = (id, ok, why) => checks.push({ id, ok, why });
+    const t = String(txt || "").trim().replace(/"\s*"/g, "").replace(/^"|"$/g, "").replace(/\;/g, ";");
+    const i = t.lastIndexOf(";s="), body = i > 0 ? t.slice(0, i) : "", sig = i > 0 ? t.slice(i + 3) : "";
+    const f = {};
+    body.split(";").forEach((p) => { const j = p.indexOf("="); if (j > 0)
+        f[p.slice(0, j)] = p.slice(j + 1); });
+    C("format", f.v === "ccr1" && !!f.d && !!f.k && !!f.x && !!sig, f.v === "ccr1" ? "ccr1 record for " + (f.d || "?") + " (" + (f.st || "?") + ")" : "not a ccr1 record");
+    if (f.x && f.k) {
+        const thumb = b64u(await sha256(enc.encode(JSON.stringify({ crv: "Ed25519", kty: "OKP", x: f.x }))));
+        C("key_id", thumb === f.k, thumb === f.k ? "public key thumbprint (RFC 7638) is the key id " + thumb.slice(0, 12) + "…" : "thumbprint " + thumb + " does not match key id " + f.k);
+        let ok = null;
+        try {
+            const pk = await subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: f.x }, { name: "Ed25519" }, false, ["verify"]);
+            ok = await subtle.verify({ name: "Ed25519" }, pk, b64(sig), enc.encode("crawlcheck-dns-v1\n" + body));
+        }
+        catch (e) {
+            ok = null;
+            C("signature", null, "this runtime cannot verify Ed25519: " + (e && e.message || e));
+        }
+        if (ok !== null)
+            C("signature", ok, ok ? "Ed25519 signature over the record verifies" : "signature does NOT verify over this record");
+    }
+    const fu = Date.parse(f.f || "");
+    C("fresh", isFinite(fu) ? fu > Date.now() : false, isFinite(fu) ? (fu > Date.now() ? "fresh until " + f.f : "expired at " + f.f + ": ask again") : "no fresh_until");
+    C("key_published", null, "offline this cannot be decided: compare key id " + (f.k || "?") + " with the ids published at https://crawlcheck.io/.well-known/http-message-signatures-directory");
+    return { record: f, decisions: { read: f.read || null, cite: f.cite || null, connect: f.connect || null, transact: f.transact || null }, checks };
+}
+export async function verifyDnsTxt(txt, opts) { const r = await verifyDnsTxt0(txt); return trustOf(r, r.record && r.record.k, opts && opts.publishedKids); }
 export async function verifyDataDoc(x, opts) { return trustOf(await verifyDataDoc0(x), kidOf(x), opts && opts.publishedKids); }
 const isMain = typeof process !== "undefined" && !!(process.argv && process.argv[1]) && await (async () => { try {
     const { pathToFileURL } = await import("node:url");
@@ -651,9 +806,32 @@ catch (e) {
 } })();
 if (isMain) {
     const online = process.argv.includes("--online");
+    if (process.argv.includes("--dns")) { // dns1: a Resolve-over-DNS TXT record
+        let txt = process.argv.slice(2).filter((a) => a !== "--online" && a !== "--dns").join(" ");
+        if (!txt) {
+            const { readFileSync } = await import("node:fs");
+            txt = readFileSync(0, "utf8");
+        }
+        let kd;
+        if (online) {
+            try {
+                kd = await publishedKeyIds();
+            }
+            catch (e) {
+                console.log("could not read the published key directory: " + e.message);
+            }
+        }
+        const r = await verifyDnsTxt(txt, { publishedKids: kd });
+        console.log("CrawlCheck Resolve over DNS: " + (r.record.d || "?") + " " + (r.record.st || "?") + " · read " + r.decisions.read + " · cite " + r.decisions.cite + " · connect " + r.decisions.connect + " · transact " + r.decisions.transact);
+        for (const c of r.checks)
+            console.log((c.ok === true ? "PASS" : c.ok === false ? "FAIL" : " -- ") + "  " + c.id.padEnd(23) + c.why);
+        console.log(r.summary);
+        console.log(r.accepted ? "ACCEPTED" : "NOT ACCEPTED" + (r.integrity_valid && r.issuer_trusted === null ? ": issuer unknown offline (run with --online)" : ""));
+        process.exit(r.checks.some((c) => c.ok === false) ? 1 : 0);
+    }
     const f = process.argv.slice(2).filter((a) => a !== "--online")[0];
     if (!f) {
-        console.log("usage: node crawlcheck-verify.mjs <bundle.json | receipt.json | export.json | resolution.json | deletion.json | answer.json | decision.json | manifest.json>");
+        console.log("usage: node crawlcheck-verify.mjs [--online] [--dns \"<ccr1 TXT record>\"] <bundle.json | receipt.json | export.json | resolution.json | deletion.json | answer.json | decision.json | manifest.json>");
         process.exit(2);
     }
     const { readFile } = await import("node:fs/promises");
@@ -661,7 +839,7 @@ if (isMain) {
     const isRc = doc && (doc.kind === "crawlcheck-remediation-receipt" || (doc.receipt && doc.receipt.kind === "crawlcheck-remediation-receipt"));
     const isEx = doc && doc.kind === "crawlcheck-evidence-export";
     const isDr = doc && doc.kind === "crawlcheck-dispute-resolution";
-    const isDt = doc && /^crawlcheck-(data-inventory|data-export-part|deletion-record|resolve|decision|snapshot|visitor|conduct|traffic-index|anchor|anchor-check|content-clock|origin|claims|read-equivalence|rights|rights-feed|mcp-scan|mcp-lock|mcp-lock-check|mcp-shadow|mcp-auth|impersonation|task-canaries|incident|revocations|high-risk|log-sth)$/.test(String(doc.kind));
+    const isDt = doc && /^crawlcheck-(data-inventory|data-export-part|deletion-record|resolve|decision|snapshot|visitor|conduct|traffic-index|anchor|anchor-check|content-clock|origin|claims|read-equivalence|rights|rights-feed|mcp-scan|mcp-lock|mcp-lock-check|mcp-shadow|mcp-auth|impersonation|task-canaries|agent-safety-benchmark|compliance-pack|share-of-preflight|incident|revocations|high-risk|log-sth|threshold-verdict|resolve-as-of)$/.test(String(doc.kind));
     let kids;
     if (online) {
         try {

package/examples/mcp-preflight-demo.mjs

@@ -0,0 +1,33 @@
+// Preflight as an MCP client extension: the official MCP TypeScript client, wrapped so `connect` and `callTool` are
+// decided before anything is sent. Run: node mcp-preflight-demo.mjs (needs @modelcontextprotocol/sdk and @crawlcheck/sdk).
+//
+//   1. A server on a domain nothing vouches for -> the connect is refused; no packet leaves the client.
+//   2. CrawlCheck's own MCP server (connect = require_confirmation) -> refused when nobody confirms, connected when a
+//      person says yes; the signed receipt is shown and verifies offline.
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { CrawlCheck, withPreflight, McpPreflightRefused } from "@crawlcheck/sdk";
+
+const cc = new CrawlCheck();
+const sent = [];
+const watchedFetch = async (u, init) => { sent.push((init && init.method || "GET") + " " + String(u)); return fetch(u, init); };   // every request the transport makes
+
+async function attempt(label, url, opts) {
+  const client = withPreflight(new Client({ name: "preflight-demo", version: "1.0.0" }), cc, opts);
+  const before = sent.length;
+  try {
+    await client.connect(new StreamableHTTPClientTransport(new URL(url), { fetch: watchedFetch }));
+    const tools = await client.listTools();
+    console.log(label + ": CONNECTED, " + tools.tools.length + " tools listed; receipt " + client.preflight.state.receipt.decision + " sha256 " + client.preflight.state.receipt.sha256.slice(0, 16));
+    await client.close();
+  } catch (e) {
+    if (!(e instanceof McpPreflightRefused)) throw e;
+    console.log(label + ": REFUSED at " + e.stage + " - " + e.why);
+    console.log("   decision " + (e.receipt && e.receipt.decision) + ", receipt sha256 " + (e.receipt && e.receipt.sha256 && e.receipt.sha256.slice(0, 16)) + ", verifies offline: " + (e.verification && e.verification.verified));
+  }
+  console.log("   requests the MCP transport sent: " + (sent.length - before));
+}
+
+await attempt("1. mcp.example.com (no record)", "https://mcp.example.com/mcp", {});
+await attempt("2a. crawlcheck.io/mcp, nobody to confirm", "https://crawlcheck.io/mcp", {});
+await attempt("2b. crawlcheck.io/mcp, a person confirms", "https://crawlcheck.io/mcp", { confirm: async (r) => { console.log("   confirm? " + r.decision + ": " + ((r.steps || [])[0] || {}).why); return true; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crawlcheck/sdk",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Typed client for the CrawlCheck API (generated from its OpenAPI document) and the zero-dependency offline verifier for evidence bundles and remediation receipts.",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,6 +14,7 @@
   "files": [
     "dist",
     "test",
+    "examples",
     "README.md"
   ],
   "engines": {

package/test/mcp.test.js

@@ -0,0 +1,81 @@
+import test from "node:test"; import assert from "node:assert/strict";
+import { withPreflight, mcpPreflight, McpPreflightRefused, transportUrl, lockFromTools } from "../dist/index.js";
+
+// A CrawlCheck client double: guard() answers from a table, no network.
+function cc(table) {
+  const calls = [];
+  return { calls, async guard(host, action, opts) {
+    calls.push({ host, action, template: opts.template });
+    const d = table[host] || "unsupported";
+    const receipt = { kind: "crawlcheck-decision", domain: host, action, decision: d, expires_at: new Date(Date.now() + 3600e3).toISOString(), steps: [{ why: "table" }], sha256: "x", signature: { kid: "k" } };
+    let proceed = d === "allow" || (d === "warn" && !!opts.allowWarn);
+    if (d === "require_confirmation" && opts.confirm) proceed = !!(await opts.confirm(receipt));
+    return { proceed, receipt, verification: { verified: true, accepted: true, integrity_valid: true, issuer_trusted: true } };
+  } };
+}
+// An MCP client double with the official Client's surface.
+function mcpClient(tools) {
+  const sent = [];
+  return { sent, closed: false,
+    async connect(transport) { sent.push("initialize " + transportUrl(transport)); },
+    async listTools() { return { tools }; },
+    async callTool(p) { sent.push("tools/call " + p.name); return { content: [] }; },
+    async close() { this.closed = true; } };
+}
+const T = (url) => ({ _url: new URL(url) });
+const TOOLS = [{ name: "search", description: "find", inputSchema: { type: "object" }, annotations: { readOnlyHint: true } }, { name: "delete_repo", description: "rm", inputSchema: { type: "object" }, annotations: { destructiveHint: true } }];
+
+test("connect to a host nothing vouches for is refused before initialize", async () => {
+  const c = withPreflight(mcpClient(TOOLS), cc({}));
+  await assert.rejects(() => c.connect(T("https://mcp.example.com/mcp")), (e) => e instanceof McpPreflightRefused && e.stage === "connect" && /nothing vouches/.test(e.why) && e.receipt.decision === "unsupported");
+  assert.deepEqual(c.sent, []);   // no packet left the client
+});
+test("block refuses the connect", async () => {
+  const c = withPreflight(mcpClient(TOOLS), cc({ "evil.example": "block" }));
+  await assert.rejects(() => c.connect(T("https://evil.example/mcp")), (e) => e.stage === "connect" && e.receipt.decision === "block");
+  assert.deepEqual(c.sent, []);
+});
+test("allow connects; the host is decided once with the safe_mcp_tool template", async () => {
+  const k = cc({ "good.example": "allow" }); const c = withPreflight(mcpClient(TOOLS), k);
+  await c.connect(T("https://good.example/mcp"));
+  await c.callTool({ name: "search", arguments: {} });
+  assert.deepEqual(c.sent, ["initialize https://good.example/mcp", "tools/call search"]);
+  assert.equal(k.calls.length, 1); assert.equal(k.calls[0].template, "safe_mcp_tool"); assert.equal(k.calls[0].action, "connect");
+});
+test("require_confirmation: refused without a confirm, connects when a person says yes", async () => {
+  const k = cc({ "ask.example": "require_confirmation" });
+  await assert.rejects(() => withPreflight(mcpClient(TOOLS), k).connect(T("https://ask.example/mcp")), (e) => /human must confirm/.test(e.why));
+  let seen = null; const c = withPreflight(mcpClient(TOOLS), k, { confirm: async (r) => { seen = r; return true; } });
+  await c.connect(T("https://ask.example/mcp")); assert.equal(seen.decision, "require_confirmation"); assert.equal(c.sent.length, 1);
+});
+test("lockfile: changed tools close the client again; a tool outside the lock is refused", async () => {
+  const lock = await lockFromTools([TOOLS[0]]);
+  const c = withPreflight(mcpClient(TOOLS), cc({ "good.example": "allow" }), { lock });
+  await assert.rejects(() => c.connect(T("https://good.example/mcp")), (e) => e.stage === "connect" && /differ from the approved lockfile/.test(e.why) && e.lock.added.includes("delete_repo"));
+  assert.equal(c.closed, true);
+  const c2 = withPreflight(mcpClient([TOOLS[0]]), cc({ "good.example": "allow" }), { lock });
+  await c2.connect(T("https://good.example/mcp")); await c2.callTool({ name: "search" });
+  await assert.rejects(() => c2.callTool({ name: "delete_repo" }), (e) => e.stage === "tools/call" && /not in the approved lockfile/.test(e.why));
+  assert.deepEqual(c2.sent, ["initialize https://good.example/mcp", "tools/call search"]);
+});
+test("destructive tool asks for confirmation", async () => {
+  const c = withPreflight(mcpClient(TOOLS), cc({ "good.example": "allow" }), { confirmDestructive: true, confirm: async (r) => r.tool !== "delete_repo" });
+  await c.connect(T("https://good.example/mcp"));
+  await c.callTool({ name: "search" });
+  await assert.rejects(() => c.callTool({ name: "delete_repo" }), (e) => /annotated destructive/.test(e.why));
+  assert.deepEqual(c.sent, ["initialize https://good.example/mcp", "tools/call search"]);
+});
+test("expired connect receipt is decided again before the next call", async () => {
+  const k = cc({ "good.example": "allow" }); const c = withPreflight(mcpClient(TOOLS), k, { maxAgeMs: 1 });
+  await c.connect(T("https://good.example/mcp")); await new Promise((r) => setTimeout(r, 5));
+  await c.callTool({ name: "search" }); assert.equal(k.calls.length, 2);
+});
+test("local stdio server: allowed by default, refusable", async () => {
+  const c = withPreflight(mcpClient(TOOLS), cc({})); await c.connect({ kind: "stdio" }); assert.equal(c.preflight.state.host, null);
+  await assert.rejects(() => withPreflight(mcpClient(TOOLS), cc({}), { local: "refuse" }).connect({ kind: "stdio" }), (e) => /local/.test(e.why));
+});
+test("bare hooks work without a client object", async () => {
+  const h = mcpPreflight(cc({ "good.example": "allow" }));
+  const r = await h.beforeConnect("https://good.example/mcp"); assert.equal(r.host, "good.example");
+  assert.equal((await h.beforeToolCall("search")).receipt.decision, "allow");
+});