@crawlcheck/sdk 1.15.0 → 1.15.2

package/dist/index.d.ts

@@ -1136,3 +1136,5 @@ export interface LangChainToolsModule {
  * Same three tools as agentTools(); each returns its result as a JSON string; they fail closed. */
 export declare function langchainTools(cc: CrawlCheck, lc: LangChainToolsModule, opts?: AgentToolOptions): unknown[];
 export default CrawlCheck;
+/** Headers guardedFetch still sends after a redirect leaves the origin the caller named. Everything else stays behind. */
+export declare const GUARDED_SAFE_HEADERS: string[];

package/dist/index.js

@@ -495,7 +495,8 @@ export class CrawlCheck {
         const action = opts.action ?? "read", max = opts.maxHops ?? 10, f = opts.fetch ? opts.fetch.bind(globalThis) : this.f;
         const init = Object.assign({}, opts.init || {}), method = String(init.method || "GET").toUpperCase();
         const hops = [], seen = new Map();
-        let cur = url;
+        let cur = url, origin0 = "";
+        try { origin0 = new URL(url).origin; } catch { origin0 = ""; }
         for (let n = 0; n <= max; n++) {
             let u;
             try {
@@ -519,7 +520,10 @@ export class CrawlCheck {
             hops.push(hop);
             if (!g.proceed)
                 return { proceed: false, response: null, url: cur, hops, why: [dom + ": " + (g.why.join("; ") || "refused")] };
-            const h = new Headers(init.headers || {});
+            // hdr1 (1.15.2): caller headers stay on the origin the caller named; elsewhere only the allowlist travels
+            const sameOrigin = u.origin === origin0;
+            const h = new Headers();
+            new Headers(init.headers || {}).forEach((v, k) => { if (sameOrigin || GUARDED_SAFE_HEADERS.includes(k.toLowerCase())) h.set(k, v); });
             if (g.header)
                 for (const [k, v] of Object.entries(g.header))
                     h.set(k, v);
@@ -791,3 +795,5 @@ export function langchainTools(cc, lc, opts = {}) {
     return agentTools(cc, opts).map((t) => lc.tool(async (input) => JSON.stringify(await t.execute(input ?? {})), { name: t.name, description: t.description, schema: t.parameters }));
 }
 export default CrawlCheck;
+/** Headers guardedFetch still sends after a redirect leaves the origin the caller named. */
+export const GUARDED_SAFE_HEADERS = ["accept", "accept-language", "accept-encoding", "user-agent", "cache-control", "pragma"];

package/dist/tsd.js

@@ -75,6 +75,9 @@ export async function toolSetDigest(tools, opts = {}) {
   const out = { spec: TSD_SPEC, contract: null, extras: null };
   if (opts.partial) { out.contract = { error: "TSD-PAGE" }; out.extras = { error: "TSD-PAGE" }; return out; }
   if (!Array.isArray(tools)) { out.contract = { error: "TSD-TOOL" }; out.extras = { error: "TSD-TOOL" }; return out; }
+  // Section 10: a set-level fault (TSD-TOOL) is found before any value is written, so it wins over TSD-TEXT / TSD-NUMBER in an earlier entry.
+  try { for (const item of tools) toolObject(item); }
+  catch (e) { if (!(e instanceof ToolSetDigestError)) throw e; const r = e.tool ? { error: e.code, tool: e.tool } : { error: e.code }; out.contract = r; out.extras = Object.assign({}, r); return out; }
   for (const [kind, fn] of [["contract", contractOf], ["extras", extrasDigestOf]]) {
     try { out[kind] = await fn(tools); }
     catch (e) { if (!(e instanceof ToolSetDigestError)) throw e; out[kind] = e.tool ? { error: e.code, tool: e.tool } : { error: e.code }; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crawlcheck/sdk",
-  "version": "1.15.0",
+  "version": "1.15.2",
   "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/fixtures/tool-set-digest-vectors.json

@@ -2,7 +2,7 @@
   "format": "mcp-tool-set-digest/1 test vectors",
   "specification": "../SPEC.md",
   "licence": "Apache-2.0 OR MIT",
-  "how": "tools is JSON text. Parse it and compute the contract digest (SPEC.md sections 4 to 7) and the extras digest (section 8). Each of contract and extras is {digest, hex, canonical}, where digest is the SRI form, hex the same hash as sha256:<hex> and canonical the text that is hashed; or {error} with the code of section 10; extras is {digest: null} when no tool carries a member outside the contract. equal and differ name pairs of vectors whose digests of the named kind must match or must not.",
+  "how": "tools is JSON text. Parse it and compute the contract digest (SPEC.md sections 4 to 7) and the extras digest (section 8). Each of contract and extras is {digest, hex, canonical}, where digest is the SRI form, hex the same hash as sha256:<hex> and canonical the text that is hashed; or {error} with the code of section 10 (where several codes apply, the one section 10 says to report); extras is {digest: null} when no tool carries a member outside the contract. equal and differ name pairs of vectors whose digests of the named kind must match or must not.",
   "vectors": [
     {
       "id": "empty",
@@ -702,6 +702,36 @@
         "canonical": "{\"tools\":{\"read_file\":{\"annotations\":{\"readOnlyHint\":true},\"title\":\"Read file\"}}}"
       }
     },
+    {
+      "id": "annotation-read-only-true",
+      "note": "A tool declares readOnlyHint true.",
+      "tools": "[{\"name\":\"read_file\",\"description\":\"Read a file.\",\"inputSchema\":{\"type\":\"object\"},\"annotations\":{\"readOnlyHint\":true}}]",
+      "contract": {
+        "digest": "sha256-EElRjaxCDoKPx+5Pggp+uMlPBOZmDDmKR+jzQQr0WHI=",
+        "hex": "sha256:1049518dac420e828fc7ee4f820a7eb8c94f04e6660c398a47e8f3410af45872",
+        "canonical": "[{\"description\":\"Read a file.\",\"inputSchema\":{\"type\":\"object\"},\"name\":\"read_file\"}]"
+      },
+      "extras": {
+        "digest": "sha256-FVPy/LHwESgNQH8PzbY0n/dTpoAdDJ0krCgoTwQrbKY=",
+        "hex": "sha256:1553f2fcb1f011280d407f0fcdb6349ff753a6801d0c9d24ac28284f042b6ca6",
+        "canonical": "{\"tools\":{\"read_file\":{\"annotations\":{\"readOnlyHint\":true}}}}"
+      }
+    },
+    {
+      "id": "annotation-read-only-false",
+      "note": "Only readOnlyHint changes to false: the contract digest stays equal and the extras digest changes.",
+      "tools": "[{\"name\":\"read_file\",\"description\":\"Read a file.\",\"inputSchema\":{\"type\":\"object\"},\"annotations\":{\"readOnlyHint\":false}}]",
+      "contract": {
+        "digest": "sha256-EElRjaxCDoKPx+5Pggp+uMlPBOZmDDmKR+jzQQr0WHI=",
+        "hex": "sha256:1049518dac420e828fc7ee4f820a7eb8c94f04e6660c398a47e8f3410af45872",
+        "canonical": "[{\"description\":\"Read a file.\",\"inputSchema\":{\"type\":\"object\"},\"name\":\"read_file\"}]"
+      },
+      "extras": {
+        "digest": "sha256-p9clya9gL1QRbgrZodGLEAIPJIQUO5ZkgO6V4uuksE8=",
+        "hex": "sha256:a7d725c9af602f54116e0ad9a1d18b10020f2484143b966480ee95e2eba4b04f",
+        "canonical": "{\"tools\":{\"read_file\":{\"annotations\":{\"readOnlyHint\":false}}}}"
+      }
+    },
     {
       "id": "extras-numbers-as-written",
       "note": "Numbers in extras, in forms JSON allows.",
@@ -803,6 +833,32 @@
         "error": "TSD-NAME"
       }
     },
+    {
+      "id": "duplicate-names-before-lone-surrogate",
+      "note": "Two tools share a name, both carry extras, and the first listed holds a lone surrogate in them: TSD-NAME and TSD-TEXT both apply, and section 10 reports TSD-NAME.",
+      "tools": "[{\"name\":\"search\",\"description\":\"Search the web.\",\"title\":\"Web \\ud800 search\"},{\"name\":\"search\",\"description\":\"Search the docs.\",\"title\":\"Docs search\"}]",
+      "contract": {
+        "digest": "sha256-+KFZbT1NAvgwjx+ZGq/rkpRMzXZRftl4baxdoEbNKEk=",
+        "hex": "sha256:f8a1596d3d4d02f8308f1f991aafeb92944ccd76517ed9786dac5da046cd2849",
+        "canonical": "[{\"description\":\"Search the docs.\",\"inputSchema\":{},\"name\":\"search\"},{\"description\":\"Search the web.\",\"inputSchema\":{},\"name\":\"search\"}]"
+      },
+      "extras": {
+        "error": "TSD-NAME"
+      }
+    },
+    {
+      "id": "duplicate-names-before-number-overflow",
+      "note": "The same with a number that has no double in the first one's extras: TSD-NAME and TSD-NUMBER both apply, and section 10 reports TSD-NAME.",
+      "tools": "[{\"name\":\"search\",\"description\":\"Search the web.\",\"_meta\":{\"limit\":1e400}},{\"name\":\"search\",\"description\":\"Search the docs.\",\"title\":\"Docs search\"}]",
+      "contract": {
+        "digest": "sha256-+KFZbT1NAvgwjx+ZGq/rkpRMzXZRftl4baxdoEbNKEk=",
+        "hex": "sha256:f8a1596d3d4d02f8308f1f991aafeb92944ccd76517ed9786dac5da046cd2849",
+        "canonical": "[{\"description\":\"Search the docs.\",\"inputSchema\":{},\"name\":\"search\"},{\"description\":\"Search the web.\",\"inputSchema\":{},\"name\":\"search\"}]"
+      },
+      "extras": {
+        "error": "TSD-NAME"
+      }
+    },
     {
       "id": "tool-is-string",
       "note": "An entry that is not an object.",
@@ -879,6 +935,17 @@
       "extras": {
         "error": "TSD-TOOL"
       }
+    },
+    {
+      "id": "lone-surrogate-before-bad-entry",
+      "note": "A lone surrogate in the first tool and an entry with an empty name after it: TSD-TOOL and TSD-TEXT both apply, and section 10 reports TSD-TOOL for both digests.",
+      "tools": "[{\"name\":\"read\",\"description\":\"x\\ud800y\"},{\"name\":\"\"}]",
+      "contract": {
+        "error": "TSD-TOOL"
+      },
+      "extras": {
+        "error": "TSD-TOOL"
+      }
     }
   ],
   "equal": [
@@ -973,6 +1040,13 @@
       ],
       "digest": "extras"
     },
+    {
+      "ids": [
+        "annotation-read-only-true",
+        "annotation-read-only-false"
+      ],
+      "digest": "contract"
+    },
     {
       "ids": [
         "extras-numbers-as-written",
@@ -1059,6 +1133,13 @@
       ],
       "digest": "contract"
     },
+    {
+      "ids": [
+        "annotation-read-only-true",
+        "annotation-read-only-false"
+      ],
+      "digest": "extras"
+    },
     {
       "ids": [
         "extras-present",

package/test/guarded-headers.test.js

@@ -0,0 +1,32 @@
+// hdr1: caller headers stay on the origin the caller named; after a redirect to another origin only the allowlist travels.
+import test from "node:test"; import assert from "node:assert/strict";
+import { CrawlCheck, GUARDED_SAFE_HEADERS } from "../dist/index.js";
+function client() { const cc = new CrawlCheck(); cc.guard = async () => ({ proceed: true, why: [], receipt: { decision: "allow" }, header: { "crawlcheck-receipt": "r" } }); return cc; }
+function recorder(map) { const seen = []; const f = async (u, init) => { seen.push({ url: String(u), headers: Object.fromEntries(new Headers(init.headers).entries()) }); const to = map[String(u)]; return to ? new Response(null, { status: 302, headers: { location: to } }) : new Response("ok", { status: 200 }); }; return { f, seen }; }
+const H = { authorization: "Bearer secret", cookie: "sid=1", "x-api-key": "k", accept: "text/html", "user-agent": "t/1" };
+test("another host: Authorization, Cookie and custom headers are dropped; the allowlist and the receipt stay", async () => {
+  const { f, seen } = recorder({ "https://a.example/x": "https://b.example/y" });
+  const r = await client().guardedFetch("https://a.example/x", { init: { headers: H }, fetch: f });
+  assert.equal(r.proceed, true); assert.equal(seen.length, 2);
+  assert.equal(seen[0].headers.authorization, "Bearer secret"); assert.equal(seen[0].headers.cookie, "sid=1");
+  for (const k of ["authorization", "cookie", "x-api-key"]) assert.equal(seen[1].headers[k], undefined, k + " crossed origins");
+  assert.equal(seen[1].headers.accept, "text/html"); assert.equal(seen[1].headers["user-agent"], "t/1"); assert.equal(seen[1].headers["crawlcheck-receipt"], "r");
+});
+test("same origin: every caller header is kept", async () => {
+  const { f, seen } = recorder({ "https://a.example/x": "https://a.example/y" });
+  await client().guardedFetch("https://a.example/x", { init: { headers: H }, fetch: f });
+  assert.equal(seen[1].headers.authorization, "Bearer secret"); assert.equal(seen[1].headers["x-api-key"], "k");
+});
+test("scheme downgrade and port change count as another origin", async () => {
+  for (const to of ["http://a.example/y", "https://a.example:8443/y"]) {
+    const { f, seen } = recorder({ "https://a.example/x": to });
+    await client().guardedFetch("https://a.example/x", { init: { headers: H }, fetch: f });
+    assert.equal(seen[1].headers.authorization, undefined, to); assert.equal(seen[1].headers.cookie, undefined, to);
+  }
+});
+test("back to the first origin: headers return", async () => {
+  const { f, seen } = recorder({ "https://a.example/x": "https://b.example/y", "https://b.example/y": "https://a.example/z" });
+  await client().guardedFetch("https://a.example/x", { init: { headers: H }, fetch: f });
+  assert.equal(seen[1].headers.authorization, undefined); assert.equal(seen[2].headers.authorization, "Bearer secret");
+});
+test("the allowlist holds no credential header", () => { for (const k of ["authorization", "cookie", "proxy-authorization"]) assert.equal(GUARDED_SAFE_HEADERS.includes(k), false); });

package/test/tsd.test.js

@@ -1,4 +1,4 @@
-// mcp-tool-set-digest/1: the 68 published vectors (github.com/alexar76/mcp-tool-set-digest, Apache-2.0 OR MIT), every
+// mcp-tool-set-digest/1: the 73 published vectors (github.com/alexar76/mcp-tool-set-digest, Apache-2.0 OR MIT), every
 // canonical text they carry, and the equal / differ pairs. Then the relation to jcs-v1: equal in the ordinary case.
 import { test } from "node:test";
 import assert from "node:assert/strict";
@@ -7,7 +7,7 @@ import { toolSetDigest, tsdCanonical, ToolSetDigestError, jcsV1, TSD_SPEC } from
 const V = JSON.parse(fs.readFileSync(new URL("./fixtures/tool-set-digest-vectors.json", import.meta.url), "utf8"));
 const key = (side) => (side.error ? "E:" + side.error : String(side.digest));
 const got = {};
-test("the fixture is the published set", () => { assert.equal(V.vectors.length, 68); assert.equal(TSD_SPEC, "mcp-tool-set-digest/1"); });
+test("the fixture is the published set", () => { assert.equal(V.vectors.length, 73); assert.equal(TSD_SPEC, "mcp-tool-set-digest/1"); });
 for (const v of V.vectors) test("vector " + v.id, async () => {
   const r = (got[v.id] = await toolSetDigest(JSON.parse(v.tools)));
   for (const k of ["contract", "extras"]) {