@crawlcheck/sdk 1.1.0 → 1.3.0

package/dist/index.d.ts

@@ -196,8 +196,19 @@ export interface PreflightOptions {
     agent?: string;
     template?: string;
     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;
-}
+    nonce?: string; /** The exact operation this decision is for (method + url, or an MCP tool); signed into the receipt. */
+    operation?: Operation;
+}
+/** What a receipt can be scoped to. Send only the keys that apply; CrawlCheck signs them back exactly as sent. https://crawlcheck.io/spec/guard#operation */
+export interface Operation {
+    method?: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
+    url?: string;
+    tool?: string;
+    tool_schema_sha256?: string;
+    scopes?: string[];
+}
+/** The operation for calling an MCP tool: its name, the sha256 of its definition (as in the lockfile) and the scopes you will use. */
+export declare function toolOperation(tool: McpTool, scopes?: string[]): Promise<Operation>;
 /** A signed crawlcheck-decision receipt. Verify it with verifyDocument (or let guard() do it). */
 export interface DecisionReceipt {
     kind: "crawlcheck-decision";
@@ -237,6 +248,7 @@ export interface DecisionWant {
     action: Action | string;
     nonce?: string | null;
     now?: number;
+    operation?: Operation | null;
 }
 /**
  * Is this receipt about the operation you are about to perform? Checks the scope only (kind, domain, action, nonce,

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);
@@ -65,6 +67,9 @@ 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 operation for calling an MCP tool: its name, the sha256 of its definition (as in the lockfile) and the scopes you will use. */
+export async function toolOperation(tool, scopes) { const o = { tool: String(tool?.name ?? ""), tool_schema_sha256: await lockToolHash(tool) }; if (scopes && scopes.length)
+    o.scopes = scopes.slice(); return o; }
 /** 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). */
@@ -86,6 +91,8 @@ export function checkDecision(receipt, want) {
         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.operation && canon(r.operation ?? null) !== canon(want.operation))
+        why.push(r.operation ? "the receipt is for another operation (" + canon(r.operation).slice(0, 120) + ")" : "the receipt is not scoped to an operation, and this request named one");
     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;
@@ -246,11 +253,13 @@ export class CrawlCheck {
             b.policy = opts.policy;
         if (opts.nonce)
             b.nonce = opts.nonce;
+        if (opts.operation)
+            b.operation = opts.operation;
         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);
+        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;
@@ -270,7 +279,7 @@ export class CrawlCheck {
         }
         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 });
+        const scope = checkDecision(receipt, { domain, action, nonce, now: opts.now, operation: opts.operation });
         if (!receipt || typeof receipt !== "object")
             return no(scope.why);
         const online = opts.onlineKeys ?? true;
@@ -278,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);
@@ -330,10 +339,11 @@ export class CrawlCheck {
             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);
+            const op = { method: method, url: cur }; // op1: each hop's receipt names that exact request
+            let g = seen.get(method + " " + cur);
             if (!g) {
-                g = await this.guard(dom, action, opts);
-                seen.set(dom, g);
+                g = await this.guard(dom, action, Object.assign({}, opts, { operation: op }));
+                seen.set(method + " " + cur, g);
             }
             const hop = { url: cur, domain: dom, proceed: g.proceed, decision: g.receipt ? String(g.receipt.decision) : null, why: g.why };
             hops.push(hop);

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.1.0",
+  "version": "1.3.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",