@crawlcheck/sdk 1.1.0 → 1.2.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

@@ -65,6 +65,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 +89,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,6 +251,8 @@ 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. */
@@ -270,7 +277,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;
@@ -330,10 +337,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/package.json

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