@crawlcheck/sdk 1.0.8 → 1.1.0

package/test/guard-acceptance.test.js

@@ -0,0 +1,54 @@
+// The guard() acceptance suite (https://crawlcheck.io/spec/guard) against this SDK.
+// CC_SDK=<path or package name> runs it against another build (CI uses the copy installed from npm).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, existsSync } from "node:fs";
+const here = new URL(".", import.meta.url);
+const CASES = process.env.CC_GUARD_CASES || [new URL("../../spec/guard-acceptance/cases.json", here), new URL("./fixtures/guard-acceptance.json", here)].find((u) => existsSync(u));
+const suite = JSON.parse(readFileSync(CASES, "utf8"));
+const { CrawlCheck } = await import(process.env.CC_SDK || "../dist/index.js");
+const BASE = "https://cc.test";
+
+function fakeFetch(c, log) {
+  return async (url, init = {}) => {
+    url = String(url);
+    if (url.startsWith(BASE)) {
+      const p = new URL(url).pathname, cc = c.crawlcheck;
+      if (cc.unreachable) throw new TypeError("fetch failed");
+      if (p === "/.well-known/http-message-signatures-directory") return new Response(JSON.stringify(suite.directory), { headers: { "content-type": "application/json" } });
+      if (p === "/api/v1/preflight") {
+        const b = JSON.parse(init.body || "{}"); log.asked.push(b.domain);
+        if (cc.by_domain) { const r = cc.by_domain[b.domain]; return r ? new Response(JSON.stringify(r), { headers: { "content-type": "application/json" } }) : new Response("{\"error\":\"none\"}", { status: 404 }); }
+        return new Response(cc.text !== undefined ? cc.text : JSON.stringify(cc.body), { status: cc.status || 200, headers: { "content-type": "application/json" } });
+      }
+      return new Response("{}", { status: 404 });
+    }
+    log.fetched.push(url);
+    const h = new Headers(init.headers || {}); if (h.get("crawlcheck-receipt")) log.header_to.push(new URL(url).hostname);
+    const s = (c.sites || {})[url];
+    if (!s) return new Response("not in fixture", { status: 404 });
+    return new Response(s.body ?? null, { status: s.status, headers: s.location ? { location: s.location } : {} });
+  };
+}
+
+for (const c of suite.cases) {
+  test(c.id + ": " + c.title, async () => {
+    const log = { fetched: [], header_to: [], asked: [] };
+    const cc = new CrawlCheck({ base: BASE, fetch: fakeFetch(c, log) });
+    const q = c.request, opts = { nonce: q.nonce, now: Date.parse(q.now), allowWarn: q.allow_warn };
+    if (q.confirm !== null) opts.confirm = async () => q.confirm;
+    if (q.url) {
+      assert.equal(typeof cc.guardedFetch, "function", "this SDK has no guarded fetch, so nothing re-checks redirects");
+      const r = await cc.guardedFetch(q.url, Object.assign(opts, { action: q.action, maxHops: q.max_hops }));
+      assert.equal(r.proceed, c.expect.proceed, "proceed; why: " + r.why.join(" | "));
+      if (c.expect.fetched) assert.deepEqual(log.fetched, c.expect.fetched);
+      if (c.expect.fetched_count !== undefined) assert.equal(log.fetched.length, c.expect.fetched_count);
+      if (c.expect.receipt_header_to) assert.deepEqual(log.header_to, c.expect.receipt_header_to);
+    } else {
+      let r; try { r = await cc.guard(q.domain, q.action, opts); } catch (e) { r = { proceed: false, header: null, threw: String(e && e.message || e) }; }   // a throw is a refusal: the caller cannot act on it
+      assert.equal(r.proceed, c.expect.proceed, "proceed; why: " + (r.threw || (r.why || []).join(" | ")));
+      assert.equal(!!r.header, c.expect.proceed, "the receipt header is given only when it proceeds");
+      if (!r.proceed) assert.ok(r.threw || (r.why && r.why.length > 0), "a refusal says why");
+    }
+  });
+}

package/test/mcp.test.js

@@ -0,0 +1,81 @@
+import test from "node:test"; import assert from "node:assert/strict";
+import { withPreflight, mcpPreflight, McpPreflightRefused, transportUrl, lockFromTools } from "../dist/index.js";
+
+// A CrawlCheck client double: guard() answers from a table, no network.
+function cc(table) {
+  const calls = [];
+  return { calls, async guard(host, action, opts) {
+    calls.push({ host, action, template: opts.template });
+    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);
+    if (d === "require_confirmation" && opts.confirm) proceed = !!(await opts.confirm(receipt));
+    return { proceed, receipt, verification: { verified: true, accepted: true, integrity_valid: true, issuer_trusted: true } };
+  } };
+}
+// An MCP client double with the official Client's surface.
+function mcpClient(tools) {
+  const sent = [];
+  return { sent, closed: false,
+    async connect(transport) { sent.push("initialize " + transportUrl(transport)); },
+    async listTools() { return { tools }; },
+    async callTool(p) { sent.push("tools/call " + p.name); return { content: [] }; },
+    async close() { this.closed = true; } };
+}
+const T = (url) => ({ _url: new URL(url) });
+const TOOLS = [{ name: "search", description: "find", inputSchema: { type: "object" }, annotations: { readOnlyHint: true } }, { name: "delete_repo", description: "rm", inputSchema: { type: "object" }, annotations: { destructiveHint: true } }];
+
+test("connect to a host nothing vouches for is refused before initialize", async () => {
+  const c = withPreflight(mcpClient(TOOLS), cc({}));
+  await assert.rejects(() => c.connect(T("https://mcp.example.com/mcp")), (e) => e instanceof McpPreflightRefused && e.stage === "connect" && /nothing vouches/.test(e.why) && e.receipt.decision === "unsupported");
+  assert.deepEqual(c.sent, []);   // no packet left the client
+});
+test("block refuses the connect", async () => {
+  const c = withPreflight(mcpClient(TOOLS), cc({ "evil.example": "block" }));
+  await assert.rejects(() => c.connect(T("https://evil.example/mcp")), (e) => e.stage === "connect" && e.receipt.decision === "block");
+  assert.deepEqual(c.sent, []);
+});
+test("allow connects; the host is decided once with the safe_mcp_tool template", async () => {
+  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", arguments: {} });
+  assert.deepEqual(c.sent, ["initialize https://good.example/mcp", "tools/call search"]);
+  assert.equal(k.calls.length, 1); assert.equal(k.calls[0].template, "safe_mcp_tool"); assert.equal(k.calls[0].action, "connect");
+});
+test("require_confirmation: refused without a confirm, connects when a person says yes", async () => {
+  const k = cc({ "ask.example": "require_confirmation" });
+  await assert.rejects(() => withPreflight(mcpClient(TOOLS), k).connect(T("https://ask.example/mcp")), (e) => /human must confirm/.test(e.why));
+  let seen = null; const c = withPreflight(mcpClient(TOOLS), k, { confirm: async (r) => { seen = r; return true; } });
+  await c.connect(T("https://ask.example/mcp")); assert.equal(seen.decision, "require_confirmation"); assert.equal(c.sent.length, 1);
+});
+test("lockfile: changed tools close the client again; a tool outside the lock is refused", async () => {
+  const lock = await lockFromTools([TOOLS[0]]);
+  const c = withPreflight(mcpClient(TOOLS), cc({ "good.example": "allow" }), { lock });
+  await assert.rejects(() => c.connect(T("https://good.example/mcp")), (e) => e.stage === "connect" && /differ from the approved lockfile/.test(e.why) && e.lock.added.includes("delete_repo"));
+  assert.equal(c.closed, true);
+  const c2 = withPreflight(mcpClient([TOOLS[0]]), cc({ "good.example": "allow" }), { lock });
+  await c2.connect(T("https://good.example/mcp")); await c2.callTool({ name: "search" });
+  await assert.rejects(() => c2.callTool({ name: "delete_repo" }), (e) => e.stage === "tools/call" && /not in the approved lockfile/.test(e.why));
+  assert.deepEqual(c2.sent, ["initialize https://good.example/mcp", "tools/call search"]);
+});
+test("destructive tool asks for confirmation", async () => {
+  const c = withPreflight(mcpClient(TOOLS), cc({ "good.example": "allow" }), { confirmDestructive: true, confirm: async (r) => r.tool !== "delete_repo" });
+  await c.connect(T("https://good.example/mcp"));
+  await c.callTool({ name: "search" });
+  await assert.rejects(() => c.callTool({ name: "delete_repo" }), (e) => /annotated destructive/.test(e.why));
+  assert.deepEqual(c.sent, ["initialize https://good.example/mcp", "tools/call search"]);
+});
+test("expired connect receipt is decided again before the next call", async () => {
+  const k = cc({ "good.example": "allow" }); const c = withPreflight(mcpClient(TOOLS), k, { maxAgeMs: 1 });
+  await c.connect(T("https://good.example/mcp")); await new Promise((r) => setTimeout(r, 5));
+  await c.callTool({ name: "search" }); assert.equal(k.calls.length, 2);
+});
+test("local stdio server: allowed by default, refusable", async () => {
+  const c = withPreflight(mcpClient(TOOLS), cc({})); await c.connect({ kind: "stdio" }); assert.equal(c.preflight.state.host, null);
+  await assert.rejects(() => withPreflight(mcpClient(TOOLS), cc({}), { local: "refuse" }).connect({ kind: "stdio" }), (e) => /local/.test(e.why));
+});
+test("bare hooks work without a client object", async () => {
+  const h = mcpPreflight(cc({ "good.example": "allow" }));
+  const r = await h.beforeConnect("https://good.example/mcp"); assert.equal(r.host, "good.example");
+  assert.equal((await h.beforeToolCall("search")).receipt.decision, "allow");
+});