@crawlcheck/sdk 1.2.0 → 1.4.0

package/dist/index.js

@@ -2,12 +2,14 @@ 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) {
+function withTrust(v, kid, published, related = []) {
     let checks = v.checks;
     let issuer = null;
     if (published) {
-        issuer = !!kid && published.includes(kid);
-        const kc = { id: "key_published", ok: issuer, why: issuer ? "key id " + kid + " is in the published key directory" : "key id " + (kid || "?") + " is NOT in the published key directory - reject this document" };
+        // kp3: keys are separated by purpose, so a decision's resolve answer or an answer's log head can carry another key; every one must be published
+        const miss = related.filter((k) => k !== kid && !published.includes(k));
+        issuer = !!kid && published.includes(kid) && miss.length === 0;
+        const kc = { id: "key_published", ok: issuer, why: issuer ? "key id " + kid + " is in the published key directory" + (related.length ? ", and so is every key it leans on" : "") : miss.length && kid && published.includes(kid) ? "the document leans on key " + miss.join(", ") + ", which is NOT published - reject this document" : "key id " + (kid || "?") + " is NOT in the published key directory - reject this document" };
         checks = checks.some((c) => c.id === "key_published") ? checks.map((c) => c.id === "key_published" ? kc : c) : checks.concat([kc]);
     }
     const ran = checks.filter((c) => c.ok !== null), failed = checks.filter((c) => c.ok === false);
@@ -257,7 +259,7 @@ export class CrawlCheck {
     }
     /** 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);
+        return withTrust(await V.verifyDataDoc(doc), doc?.signature?.kid, onlineKeys ? await this.publishedKeyIds() : null, V.relatedKids(doc));
     }
     /**
      * Preflight, verify the receipt, check it is for THIS operation, and decide. Proceeds on allow; warn only with allowWarn;
@@ -285,7 +287,7 @@ export class CrawlCheck {
             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);
+            verification = withTrust(await V.verifyDataDoc(receipt), receipt?.signature?.kid, online ? await this.publishedKeyIds() : opts.publishedKids, V.relatedKids(receipt));
         }
         catch (e) {
             return no(["the receipt could not be verified: " + (e?.message || e)].concat(scope.why), receipt);

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/dist/verify.d.ts

@@ -19,7 +19,8 @@ export function verifyThresholdSigners(x: any): Promise<{
     values_match: boolean;
     why: never[];
 }[]>;
-export function trustOf(res: any, kid: any, publishedKids: any): any;
+export function relatedKids(x: any): any[];
+export function trustOf(res: any, kid: any, publishedKids: any, related: 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>;

package/dist/verify.js

@@ -654,7 +654,7 @@ async function verifyDataDoc0(x) {
     }
     if (x.kind === "crawlcheck-decision") {
         const r = x.resolve || {};
-        C("resolve_bound", /^[0-9a-f]{64}$/.test(String(r.sha256 || "")) && r.kid === x.signature.kid, /^[0-9a-f]{64}$/.test(String(r.sha256 || "")) ? "the decision names the resolve answer it was made from (" + String(r.sha256).slice(0, 16) + "…), signed by the same key" : "the decision does not name a resolve answer digest");
+        C("resolve_bound", /^[0-9a-f]{64}$/.test(String(r.sha256 || "")) && typeof r.kid === "string" && r.kid.length > 0, /^[0-9a-f]{64}$/.test(String(r.sha256 || "")) ? "the decision names the resolve answer it was made from (" + String(r.sha256).slice(0, 16) + "…), signed by key " + String(r.kid).slice(0, 12) + "… (online, it must be a published key)" : "the decision does not name a resolve answer digest");
         C("decision_known", ["allow", "warn", "require_confirmation", "block", "unsupported"].indexOf(x.decision) >= 0, "decision is " + x.decision);
     }
     if (x.kind === "crawlcheck-snapshot") {
@@ -678,7 +678,7 @@ async function verifyDataDoc0(x) {
             catch (e) {
                 sv = null;
             }
-            const same = !x.signature || !t.sth.signature || t.sth.signature.kid === x.signature.kid;
+            const same = true; // kp3: the log head may be signed by the log key; online, its key must be published (trustOf)
             C("log_head_signature", !!(sv && sv.verified) && t.sth.kind === "crawlcheck-log-sth" && t.sth.batch === t.batch && same, sv && sv.verified ? "batch " + t.batch + "'s signed tree head verifies (tree size " + t.sth.tree_size + ", chained to " + String(t.sth.prev_sth_sha256 || "genesis").slice(0, 16) + "…)" : "the signed tree head does NOT verify");
         }
         else
@@ -728,13 +728,41 @@ async function verifyDataDoc0(x) {
 // Run as a script under ANY file name (a browser saves a second download as "crawlcheck-verify (1).mjs"); imported, it
 // stays a library. The old test matched the file name only, so a renamed copy exited 0 having checked nothing.
 // vt1: integrity, issuer trust and completeness, reported apart. Same semantics as @crawlcheck/sdk and the Python package.
-export function trustOf(res, kid, publishedKids) {
+// kp3 (2026-10-10): keys a document leans on besides its own signer (the resolve answer a decision names, the log head
+// an answer carries). Since keys are separated by purpose these can differ; online, every one must be published.
+export function relatedKids(x) {
+    const out = [];
+    try {
+        if (x && x.kind === "crawlcheck-decision" && x.resolve && x.resolve.kid)
+            out.push(x.resolve.kid);
+        const t = x && x.transparency;
+        if (t && t.sth && t.sth.signature && t.sth.signature.kid)
+            out.push(t.sth.signature.kid);
+        if (x && x.kind === "crawlcheck-resolve-as-of") {
+            if (x.answer && x.answer.signature && x.answer.signature.kid)
+                out.push(x.answer.signature.kid);
+            const p = x.log_inclusion;
+            if (p && p.sth && p.sth.signature && p.sth.signature.kid)
+                out.push(p.sth.signature.kid);
+        }
+    }
+    catch (e) { }
+    return out.filter((k, i) => typeof k === "string" && out.indexOf(k) === i);
+}
+export function trustOf(res, kid, publishedKids, related) {
     let checks = Array.isArray(res && res.checks) ? res.checks : [];
     let issuer = null;
     if (Array.isArray(publishedKids)) {
-        issuer = !!kid && publishedKids.indexOf(kid) > -1;
-        const kc = { id: "key_published", ok: issuer, why: issuer ? "key id " + kid + " is in the published key directory" : !kid ? "this document carries no signature, so its issuer cannot be authenticated" : "key id " + kid + " is NOT in the published key directory: reject this document" };
-        checks = checks.some((c) => c.id === "key_published") ? checks.map((c) => c.id === "key_published" ? kc : c) : checks.concat([kc]);
+        const __rel = (related || []).filter((k) => k !== kid), __miss = __rel.filter((k) => publishedKids.indexOf(k) < 0);
+        issuer = !!kid && publishedKids.indexOf(kid) > -1 && __miss.length === 0;
+        if (!!kid && publishedKids.indexOf(kid) > -1 && __miss.length) {
+            const kc0 = { id: "key_published", ok: false, why: "the document is signed by a published key, but it leans on key " + __miss.join(", ") + ", which is NOT published: reject this document" };
+            checks = checks.some((c) => c.id === "key_published") ? checks.map((c) => c.id === "key_published" ? kc0 : c) : checks.concat([kc0]);
+        }
+        else {
+            const kc = { id: "key_published", ok: issuer, why: issuer ? "key id " + kid + " is in the published key directory" : !kid ? "this document carries no signature, so its issuer cannot be authenticated" : "key id " + kid + " is NOT in the published key directory: reject this document" };
+            checks = checks.some((c) => c.id === "key_published") ? checks.map((c) => c.id === "key_published" ? kc : c) : checks.concat([kc]);
+        }
     }
     const ran = checks.filter((c) => c.ok !== null), failed = checks.filter((c) => c.ok === false);
     const unavailable = checks.filter((c) => c.ok === null && c.id !== "key_published").map((c) => c.id);
@@ -795,7 +823,7 @@ async function verifyDnsTxt0(txt) {
     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); }
+export async function verifyDataDoc(x, opts) { return trustOf(await verifyDataDoc0(x), kidOf(x), opts && opts.publishedKids, relatedKids(x)); }
 const isMain = typeof process !== "undefined" && !!(process.argv && process.argv[1]) && await (async () => { try {
     const { pathToFileURL } = await import("node:url");
     const { realpathSync } = await import("node:fs");

package/package.json

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