@crawlcheck/sdk 1.3.0 → 1.4.0

package/dist/mcp.d.ts

@@ -30,8 +30,9 @@ export function mcpPreflight(cc: any, opts?: {}): {
     /** 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;
+    beforeToolCall(name: any, annotations: any, tool: any): Promise<{
+        receipt: any;
+        tool_receipt: any;
     }>;
 };
 /**

package/dist/mcp.js

@@ -10,10 +10,13 @@
 //   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.
+//   per call:  (1.4.0) a tool call gets a receipt of its own, scoped to that tool (name, digest of its definition, opts.scopes),
+//              so a connect receipt never stands in for a call to a tool that changed. opts.toolReceipts: "write" (default:
+//              every tool not annotated readOnlyHint), "all", or "none".
 // 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";
+import { checkLock, toolOperation } 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; }
 }
@@ -103,7 +106,7 @@ export function mcpPreflight(cc, opts = {}) {
             return lc;
         },
         /** Before tools/call. */
-        async beforeToolCall(name, annotations) {
+        async beforeToolCall(name, annotations, tool) {
             if (state.host && !fresh())
                 await decide(state.host);
             if (state.approved && !state.approved.has(name))
@@ -113,7 +116,16 @@ export function mcpPreflight(cc, opts = {}) {
                 if (!ok)
                     throw new McpPreflightRefused("tools/call", "tool " + name + " is annotated destructive and no human confirmed", { receipt: state.receipt });
             }
-            return { receipt: state.receipt };
+            const mode = opts.toolReceipts || "write", ro = !!(annotations && annotations.readOnlyHint === true);
+            let callReceipt = null;
+            if (state.host && (mode === "all" || (mode === "write" && !ro))) { // op1/mcp: a receipt for this exact tool call
+                const op = tool ? await toolOperation(tool, opts.scopes) : Object.assign({ tool: String(name) }, opts.scopes && opts.scopes.length ? { scopes: opts.scopes.slice() } : {});
+                const g = await cc.guard(state.host, "connect", { template, policy: opts.policy, agent: opts.agent, confirm: opts.confirm, allowWarn: !!opts.allowWarn, onlineKeys: opts.onlineKeys, operation: op });
+                if (!g.proceed)
+                    throw new McpPreflightRefused("tools/call", "no receipt for tool " + name + ": " + ((g.why || []).join("; ") || "refused"), { receipt: g.receipt, verification: g.verification });
+                callReceipt = g.receipt;
+            }
+            return { receipt: callReceipt || state.receipt, tool_receipt: callReceipt };
         }
     };
 }
@@ -129,7 +141,7 @@ export function withPreflight(client, cc, opts = {}) {
     client.connect = async function (transport, ...rest) {
         await pf.beforeConnect(opts.serverUrl || transportUrl(transport));
         const r = await connect(transport, ...rest);
-        if (opts.lock || opts.confirmDestructive) {
+        if (opts.lock || opts.confirmDestructive || (opts.toolReceipts || "write") !== "none") {
             let list = [];
             try {
                 const t = typeof client.listTools === "function" ? await client.listTools() : null;
@@ -140,23 +152,24 @@ export function withPreflight(client, cc, opts = {}) {
             }
             list.forEach(function (t) { if (t && t.name)
                 tools[t.name] = t; });
-            try {
-                await pf.afterConnect(list);
-            }
-            catch (e) {
+            if (opts.lock || opts.confirmDestructive)
                 try {
-                    if (typeof client.close === "function")
-                        await client.close();
+                    await pf.afterConnect(list);
+                }
+                catch (e) {
+                    try {
+                        if (typeof client.close === "function")
+                            await client.close();
+                    }
+                    catch (e2) { }
+                    throw e;
                 }
-                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);
+        await pf.beforeToolCall(name, tools[name] && tools[name].annotations, tools[name]);
         return callTool(params, ...rest);
     };
     client.preflight = pf;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crawlcheck/sdk",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "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",

package/test/mcp.test.js

@@ -5,7 +5,7 @@ import { withPreflight, mcpPreflight, McpPreflightRefused, transportUrl, lockFro
 function cc(table) {
   const calls = [];
   return { calls, async guard(host, action, opts) {
-    calls.push({ host, action, template: opts.template });
+    calls.push({ host, action, template: opts.template, tool: opts.operation && opts.operation.tool, op: opts.operation });
     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);
@@ -79,3 +79,23 @@ test("bare hooks work without a client object", async () => {
   const r = await h.beforeConnect("https://good.example/mcp"); assert.equal(r.host, "good.example");
   assert.equal((await h.beforeToolCall("search")).receipt.decision, "allow");
 });
+
+test("1.4.0: a write tool call gets its own receipt, scoped to the tool's definition; a read-only one reuses connect", async () => {
+  const { lockToolHash } = await import("../dist/index.js");
+  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" }); await c.callTool({ name: "delete_repo" });
+  const per = k.calls.filter((x) => x.tool);
+  assert.deepEqual(per.map((x) => x.tool), ["delete_repo"]);
+  assert.equal(per[0].op.tool_schema_sha256, await lockToolHash(TOOLS[1]));
+});
+test("1.4.0: a refused tool receipt stops tools/call; toolReceipts none skips it", async () => {
+  const k = cc({ "good.example": "allow" }); const orig = k.guard;
+  k.guard = async (h, a, o) => o.operation ? { proceed: false, receipt: null, verification: null, why: ["the receipt is for another operation"] } : orig(h, a, o);
+  const cl = mcpClient(TOOLS); const c = withPreflight(cl, k);
+  await c.connect(T("https://good.example/mcp"));
+  await assert.rejects(() => c.callTool({ name: "delete_repo" }), (e) => e.stage === "tools/call" && /another operation/.test(e.why));
+  assert.ok(!cl.sent.includes("tools/call delete_repo"));
+  const k2 = cc({ "good.example": "allow" }); const c2 = withPreflight(mcpClient(TOOLS), k2, { toolReceipts: "none" });
+  await c2.connect(T("https://good.example/mcp")); await c2.callTool({ name: "delete_repo" });
+  assert.equal(k2.calls.filter((x) => x.tool).length, 0);
+});