@crawlcheck/sdk 1.12.0 → 1.13.0

package/dist/mcp.js

@@ -17,7 +17,7 @@
 // request is never sent.
 import { normalizeDomain } from "./index.js";
 import { checkLock, toolOperation } from "./index.js";
-import { continuityCheck, continuityFailure, continuityClassOf } from "./continuity.js";
+import { continuityCheck, continuityFailure, continuityClassOf, verifyLockBaseline, baselineRefusal } from "./continuity.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; }
 }
@@ -62,6 +62,36 @@ export function mcpPreflight(cc, opts = {}) {
         catch (e) { }
     } return rec; };
     const coOpts = function (extra) { return Object.assign({ mode: CO.mode, policy: CO.policy, exceptions: CO.exceptions, server: state.url }, extra || {}); };
+    // 1.13.0 signed baseline: the lockfile's signature is checked once, now, before anything is compared against it. Options
+    // (in opts.continuity, or top level without continuity): operatorKeys, keyPolicy, publishedKids, trustedKids,
+    // requireSignedBaseline. A bad or forged signature (or an unsigned lockfile when one is required) refuses the connect
+    // outside observe; observe records baseline_untrusted and goes on.
+    let baseLock = opts.lock || null, baseRefused = null;
+    state.baseline = null;
+    state.ready = !opts.lock ? Promise.resolve(null) : (async () => {
+        const bo = Object.assign({}, opts, CO || {}), req = bo.requireSignedBaseline ?? !!(bo.operatorKeys && bo.operatorKeys.length);
+        let b;
+        try {
+            b = await verifyLockBaseline(opts.lock, bo);
+        }
+        catch (e) {
+            b = { trust: "invalid", signer: null, kid: null, why: "the baseline could not be checked: " + (e && e.message || e), parts_used: false, lock: opts.lock };
+        }
+        state.baseline = { trust: b.trust, signer: b.signer, kid: b.kid, why: b.why, parts_used: b.parts_used };
+        baseLock = b.lock || opts.lock;
+        const bad = baselineRefusal(b, req);
+        if (bad && CO) {
+            const rec = await keep(await continuityFailure("baseline_untrusted", coOpts({ detail: String(bad).slice(0, 300) })));
+            if (rec.outcome !== "proceed")
+                baseRefused = new McpPreflightRefused("connect", rec.why.join("; ") + ": " + bad, { lock: rec });
+        }
+        else if (bad)
+            baseRefused = new McpPreflightRefused("connect", "the approved lockfile is not trusted: " + bad);
+        return state.baseline;
+    })();
+    state.ready.catch(function () { });
+    const baseOk = async function () { await state.ready; if (baseRefused)
+        throw baseRefused; };
     const fresh = function () {
         if (!state.receipt)
             return false;
@@ -110,6 +140,7 @@ export function mcpPreflight(cc, opts = {}) {
         state,
         /** Before initialize. url: the server URL (a stdio/local server has none and is not decided; pass opts.local = "allow" | "refuse", default allow). */
         async beforeConnect(url) {
+            await baseOk();
             if (!url) {
                 if (opts.local === "refuse")
                     throw new McpPreflightRefused("connect", "a local (stdio) server cannot be resolved and opts.local is refuse");
@@ -127,8 +158,9 @@ export function mcpPreflight(cc, opts = {}) {
         },
         /** After initialize, with the tools the server lists. Refuses (and the wrapper closes the client) when they differ from the approved lockfile. */
         async afterConnect(tools, meta) {
+            await baseOk();
             if (CO && opts.lock) { // 1.11.0: classify, apply the operator's policy, keep the record
-                const rec = await keep(await continuityCheck(opts.lock, tools, coOpts({ complete: !(meta && meta.nextCursor) })));
+                const rec = await keep(await continuityCheck(baseLock, tools, coOpts({ complete: !(meta && meta.nextCursor), baselineTrust: state.baseline && state.baseline.trust })));
                 state.lockCheck = rec;
                 state.approved = null;
                 state.pausedTools = new Set(rec.paused_tools);
@@ -154,7 +186,7 @@ export function mcpPreflight(cc, opts = {}) {
                 state.approved = null;
                 return null;
             }
-            const lc = await checkLock(opts.lock, tools || []);
+            const lc = await checkLock(baseLock, tools || []);
             state.lockCheck = lc;
             state.approved = new Set((opts.lock.tools || []).map(function (t) { return t.name; }));
             if (lc.decision !== "connect")
@@ -163,6 +195,7 @@ export function mcpPreflight(cc, opts = {}) {
         },
         /** Before tools/call. */
         async beforeToolCall(name, annotations, tool) {
+            await baseOk();
             if (state.host && !fresh())
                 await decide(state.host);
             if (state.pausedTools && state.pausedTools.has(name)) { // 1.11.0: a changed or new tool waits for a person; the others stay usable

package/package.json

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

package/test/baseline.test.js

@@ -0,0 +1,93 @@
+// Signed baseline (1.13.0): the lockfile's signature is checked once, when a gate is created, before anything is compared
+// against it. The cases are in the shared golden file (baseline_cases); the Python SDK must reproduce each one exactly.
+import test from "node:test"; import assert from "node:assert/strict";
+import fs from "node:fs";
+import { verifyLockBaseline, signLock, newOperatorKey, keyPolicyFrom, continuityGate, openContinuityGate, ContinuityRefused, withPreflight, McpPreflightRefused, CONTINUITY_FAILURE_CLASSES, CONTINUITY_DEFAULT_POLICY, canon } from "../dist/index.js";
+const G = JSON.parse(fs.readFileSync(new URL("./fixtures/continuity.json", import.meta.url), "utf8"));
+const keyDir = G.key_directory;
+const sha = async (s) => Buffer.from(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(s))).toString("hex");
+const B = (n) => G.baseline_cases.find((c) => c.name === n);
+const quiet = { log: false };
+const opts = async (o) => { const x = Object.assign({}, o); if (x.keyPolicyDirectory) { delete x.keyPolicyDirectory; x.keyPolicy = await keyPolicyFrom(keyDir); } return x; };
+
+for (const c of G.baseline_cases) test("golden baseline: " + c.name, async () => {
+  const r = await verifyLockBaseline(c.lock, await opts(c.opts)); const { lock, ...rest } = r;
+  assert.deepEqual(rest, c.expect); assert.equal(await sha(canon(lock)), c.used_sha256);
+});
+test("golden: signLock is deterministic and matches the fixture", async () => {
+  assert.deepEqual(await signLock(G.lock, G.operator.privateKey), G.operator.signed_lock);
+});
+test("baseline_untrusted is the 14th failure class, deny by default, and an integrity class", async () => {
+  assert.equal(CONTINUITY_FAILURE_CLASSES.length, 14); assert.equal(CONTINUITY_FAILURE_CLASSES[13], "baseline_untrusted");
+  assert.equal(CONTINUITY_DEFAULT_POLICY.effects.baseline_untrusted, "deny");
+  for (const m of ["review", "enforce"]) assert.equal(G.failures.find((f) => f.cls === "baseline_untrusted" && f.opts.mode === m).expect.outcome, "deny");
+  assert.equal(G.failures.find((f) => f.cls === "baseline_untrusted" && f.opts.mode === "observe").expect.outcome, "proceed");
+});
+
+test("gate, enforce: a lockfile edited after CrawlCheck signed it fails at startup", async () => {
+  const L = B("edited_after_signing").lock;
+  await assert.rejects(() => openContinuityGate(L, Object.assign({ mode: "enforce" }, quiet)), (e) => e instanceof ContinuityRefused && /baseline_untrusted|not trusted/.test(e.message) && e.record.events[0].class === "baseline_untrusted");
+  const g = continuityGate(L, Object.assign({ mode: "enforce" }, quiet)); await g.ready;
+  assert.equal(g.baseline.trust, "invalid"); assert.equal(g.records.length, 1);
+  await assert.rejects(() => g.check(G.tools_v1), ContinuityRefused);
+});
+test("gate, enforce: a lockfile re-signed with a foreign key fails at startup", async () => {
+  await assert.rejects(() => openContinuityGate(B("forged_foreign_key").lock, Object.assign({ mode: "enforce" }, quiet)), /not a CrawlCheck key/);
+});
+test("gate, observe: an untrusted baseline is recorded and passes", async () => {
+  const g = await openContinuityGate(B("edited_after_signing").lock, Object.assign({ mode: "observe" }, quiet));
+  assert.equal(g.records[0].events[0].class, "baseline_untrusted"); assert.equal(g.records[0].outcome, "proceed");
+  const r = await g.check([]); assert.equal(r.outcome, "proceed"); assert.equal(r.baseline.trust, "invalid");
+});
+test("gate: a CrawlCheck-signed lockfile is verified and named in every record", async () => {
+  const L = B("crawlcheck_signed").lock;
+  const g = await openContinuityGate(L, Object.assign({ mode: "enforce" }, quiet));
+  assert.equal(g.baseline.trust, "verified"); assert.equal(g.records.length, 0);
+  const r = await g.check([]); assert.equal(r.baseline.trust, "verified"); assert.equal(r.baseline.per_part, true);
+});
+test("gate: parts added after signing are not used for the comparison", async () => {
+  const g = await openContinuityGate(B("parts_added_after_signing").lock, Object.assign({ mode: "enforce" }, quiet));
+  assert.equal(g.baseline.trust, "verified"); assert.equal(g.baseline.parts_used, false);
+  const r = await g.check([]); assert.equal(r.baseline.per_part, false);
+});
+test("gate: unsigned passes unless a signed baseline is required; operator keys require one by default", async () => {
+  const g = await openContinuityGate(G.lock, Object.assign({ mode: "enforce" }, quiet)); assert.equal(g.baseline.trust, "unsigned");
+  await assert.rejects(() => openContinuityGate(G.lock, Object.assign({ mode: "enforce", requireSignedBaseline: true }, quiet)), /unsigned and a signed one is required/);
+  await assert.rejects(() => openContinuityGate(G.lock, Object.assign({ mode: "enforce", operatorKeys: [G.operator.publicKey] }, quiet)), /unsigned/);
+  await openContinuityGate(G.lock, Object.assign({ mode: "enforce", operatorKeys: [G.operator.publicKey], requireSignedBaseline: false }, quiet));
+});
+test("gate: an operator-signed lockfile with the operator key is operator_signed; with another key it is refused", async () => {
+  const g = await openContinuityGate(G.operator.signed_lock, Object.assign({ mode: "enforce", operatorKeys: [G.operator.publicKey] }, quiet));
+  assert.equal(g.baseline.trust, "operator_signed"); const r = await g.check(G.tools_v1); assert.equal(r.outcome, "proceed"); assert.equal(r.baseline.trust, "operator_signed");
+  await assert.rejects(() => openContinuityGate(G.operator.signed_lock, Object.assign({ mode: "enforce", operatorKeys: [G.operator.other_publicKey] }, quiet)), /not one of the operator keys/);
+});
+test("gate: an attacker who edits the operator-signed baseline to approve a new tool is refused at startup", async () => {
+  const L = structuredClone(G.operator.signed_lock); L.tools.push({ name: "export", sha256: "e".repeat(64) });
+  await assert.rejects(() => openContinuityGate(L, Object.assign({ mode: "enforce", operatorKeys: [G.operator.publicKey] }, quiet)), /changed after the operator signed it/);
+  const R = structuredClone(L); delete R.operator_signature;   // stripping the signature instead: unsigned, refused because a key is configured
+  await assert.rejects(() => openContinuityGate(R, Object.assign({ mode: "enforce", operatorKeys: [G.operator.publicKey] }, quiet)), /unsigned/);
+});
+test("verified at startup, not per call: check() does not verify again", async () => {
+  let calls = 0; const g = continuityGate(B("crawlcheck_signed").lock, Object.assign({ mode: "enforce" }, quiet)); await g.ready;
+  const orig = crypto.subtle.verify; crypto.subtle.verify = async (...a) => { calls++; return orig.apply(crypto.subtle, a); };
+  try { for (let i = 0; i < 3; i++) await g.check([]); } finally { crypto.subtle.verify = orig; }
+  assert.equal(calls, 0);
+});
+test("newOperatorKey + signLock round trip", async () => {
+  const k = await newOperatorKey(); const s = await signLock(G.lock, k.privateKey);
+  assert.equal((await verifyLockBaseline(s, { operatorKeys: [k.publicKey] })).trust, "operator_signed");
+  assert.equal(s.operator_signature.kid, k.kid);
+});
+function cc() { return { async guard(host, action) { return { proceed: true, receipt: { kind: "crawlcheck-decision", decision: "allow", expires_at: new Date(Date.now() + 3600e3).toISOString() }, verification: { verified: true }, why: [] }; } }; }
+test("withPreflight: an untrusted baseline refuses the connect before a byte is sent", async () => {
+  const sent = []; const c = { async connect() { sent.push("initialize"); }, async listTools() { return { tools: G.tools_v1 }; }, async callTool() { sent.push("call"); } };
+  withPreflight(c, cc(), { lock: B("edited_after_signing").lock, continuity: { mode: "enforce" } });
+  await assert.rejects(() => c.connect({ url: "https://mcp.example.com/mcp" }), (e) => e instanceof McpPreflightRefused && /baseline/.test(e.message));
+  assert.deepEqual(sent, []);
+  const c2 = { async connect() { sent.push("initialize"); }, async listTools() { return { tools: G.tools_v1 }; }, async callTool() { } };
+  withPreflight(c2, cc(), { lock: B("forged_foreign_key").lock });   // without continuity too
+  await assert.rejects(() => c2.connect({ url: "https://mcp.example.com/mcp" }), /lockfile is not trusted/);
+  const c3 = { async connect() { sent.push("initialize"); }, async listTools() { return { tools: G.tools_v1 }; }, async callTool() { } };
+  withPreflight(c3, cc(), { lock: G.operator.signed_lock, continuity: { mode: "enforce", operatorKeys: [G.operator.publicKey] }, toolReceipts: "none" });
+  await c3.connect({ url: "https://mcp.example.com/mcp" }); assert.equal(c3.preflight.state.baseline.trust, "operator_signed");
+});

package/test/fixtures/continuity-gen.mjs

@@ -2,7 +2,9 @@
 // Both SDKs must reproduce every expected field, including record_sha256, byte for byte.
 import fs from "node:fs";
 import * as C from "../../dist/continuity.js";
-import { lockFromTools } from "../../dist/index.js";
+import { canon } from "../../dist/verify.js";
+import { lockFromTools, keyPolicyFrom } from "../../dist/index.js";
+const rd = (f) => JSON.parse(fs.readFileSync(new URL("./" + f, import.meta.url), "utf8"));
 const NOW = Date.parse("2026-11-07T16:00:00Z");
 const v1 = [
   { name: "search", description: "Search the catalogue.", inputSchema: { type: "object", properties: { q: { type: "string" } }, required: ["q"] }, annotations: { readOnlyHint: true } },
@@ -36,11 +38,58 @@ const cases = [
   ["review_mode_change", lock, schemaChanged, { mode: "review" }],
   ["approved_exception", lock, descChanged, { exceptions: [{ tool: "search", class: "description_changed", by: "ops@example.com", reason: "vendor release 2.4 reviewed", until: "2026-12-01T00:00:00Z" }] }],
   ["expired_exception", lock, descChanged, { exceptions: [{ tool: "search", class: "description_changed", by: "ops@example.com", reason: "old", until: "2026-11-01T00:00:00Z" }] }],
-  ["operator_policy_blocks_additions", lock, added, { policy: { id: "acme-strict", effects: { tool_added: "deny" } } }]
+  ["operator_policy_blocks_additions", lock, added, { policy: { id: "acme-strict", effects: { tool_added: "deny" } } }],
+  ["baseline_trust_named", lock, v1, { baselineTrust: "operator_signed" }]
 ].map(([name, L, tools, o]) => ({ name, lock: L, tools, opts: Object.assign({ now: NOW, server: S }, o) }));
 for (const c of cases) c.expect = await C.continuityCheck(c.lock, c.tools, c.opts);
 const failures = [];
 for (const cls of C.CONTINUITY_FAILURE_CLASSES) for (const mode of ["observe", "review", "enforce"]) { const o = { now: NOW, server: S, mode }; failures.push({ cls, opts: o, expect: await C.continuityFailure(cls, o) }); }
+// 1.13.0 signed baseline. Real CrawlCheck-signed lockfiles (GET /api/v1/mcp/lock?url=https://crawlcheck.io/mcp on 2026-11-07,
+// one before and one after the signed lockfile gained parts), the key directory read the same day, and a TEST operator key
+// derived from a public seed (never use it for anything real).
+const signed = rd("lock-signed.json"), signedNoParts = rd("lock-signed-noparts.json"), keyDir = rd("key-directory-20261107.json");
+const b64e = (u8) => Buffer.from(u8).toString("base64url");
+const seedKey = async (label) => {
+  const seed = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(label)));
+  const pk = await crypto.subtle.importKey("pkcs8", Buffer.concat([Buffer.from("302e020100300506032b657004220420", "hex"), Buffer.from(seed)]), { name: "Ed25519" }, true, ["sign"]);
+  const j = await crypto.subtle.exportKey("jwk", pk); return { seed_hex: Buffer.from(seed).toString("hex"), privateKey: { kty: "OKP", crv: "Ed25519", x: j.x, d: j.d }, publicKey: { kty: "OKP", crv: "Ed25519", x: j.x }, key: pk };
+};
+const opKey = await seedKey("crawlcheck continuity fixture: TEST operator key, public, never use"), otherKey = await seedKey("crawlcheck continuity fixture: TEST other operator key"), forger = await seedKey("crawlcheck continuity fixture: TEST forger key");
+const sha = async (s) => Buffer.from(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(s))).toString("hex");
+const forged = clone(signed); forged.tools[0].sha256 = "f".repeat(64);
+{ const body = {}; for (const k of Object.keys(forged)) if (k !== "sha256" && k !== "signature") body[k] = forged[k];
+  const d = await sha(canon(body)), msg = "crawlcheck-data-v1\n" + d, kid = b64e(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify({ crv: "Ed25519", kty: "OKP", x: forger.publicKey.x })))));
+  forged.sha256 = d; forged.signature = Object.assign({}, forged.signature, { kid, message: msg, sig: b64e(new Uint8Array(await crypto.subtle.sign({ name: "Ed25519" }, forger.key, new TextEncoder().encode(msg)))), key: Object.assign({}, forged.signature.key, { kid, jwk: forger.publicKey }) }); }
+const opSigned = await C.signLock(lock, opKey.privateKey), opOverCc = await C.signLock(signed, opKey.privateKey);
+const edited = (L, f) => { const x = clone(L); f(x); return x; };
+const OK = [opKey.publicKey];
+const baselines = [
+  ["crawlcheck_signed", signed, {}],
+  ["crawlcheck_signed_key_policy", signed, { keyPolicyDirectory: true }],
+  ["crawlcheck_signed_other_trusted_kids", signed, { trustedKids: ["not-a-crawlcheck-key"] }],
+  ["edited_after_signing", edited(signed, (x) => { x.tools[0].sha256 = "0".repeat(64); }), {}],
+  ["parts_edited_after_signing", edited(signed, (x) => { x.parts[Object.keys(x.parts)[0]].description_sha256 = "0".repeat(64); }), {}],
+  ["parts_added_after_signing", Object.assign(clone(signedNoParts), { parts: { best_source: { description_sha256: "0".repeat(64), schema_sha256: "0".repeat(64), annotations_sha256: "0".repeat(64) } } }), {}],
+  ["forged_foreign_key", forged, {}],
+  ["foreign_scheme", Object.assign(clone(lock), { signature: { kid: "x", message: "something-else\n00", sig: "AA" } }), {}],
+  ["operator_signed", opSigned, { operatorKeys: OK }],
+  ["operator_signed_key_as_x", opSigned, { operatorKeys: [opKey.publicKey.x] }],
+  ["operator_wrong_key", opSigned, { operatorKeys: [otherKey.publicKey] }],
+  ["operator_edited_after_signing", edited(opSigned, (x) => { x.tools.pop(); }), { operatorKeys: OK }],
+  ["operator_bad_signature", edited(opSigned, (x) => { x.operator_signature.sig = opOverCc.operator_signature.sig; }), { operatorKeys: OK }],
+  ["operator_no_key_given", opSigned, {}],
+  ["operator_over_crawlcheck_no_key_given", opOverCc, {}],
+  ["operator_over_crawlcheck", opOverCc, { operatorKeys: OK }],
+  ["unsigned", lock, {}],
+  ["not_a_lockfile", { tools_sha256: "x" }, {}]
+];
+const baselineCases = [];
+for (const [name, L, o] of baselines) {
+  const oo = Object.assign({}, o); if (oo.keyPolicyDirectory) { delete oo.keyPolicyDirectory; oo.keyPolicy = await keyPolicyFrom(keyDir); }
+  const r = await C.verifyLockBaseline(L, oo); const { lock: used, ...expect } = r;
+  baselineCases.push({ name, lock: L, opts: o, expect, used_sha256: await sha(canon(used)) });
+}
+const operator = { warning: "TEST KEY derived from a public seed. Never use it for anything real.", seed_hex: opKey.seed_hex, privateKey: opKey.privateKey, publicKey: opKey.publicKey, other_publicKey: otherKey.publicKey, signed_lock: opSigned };
 // acceptance: the split for one receipt
 const F = { kind_ok: true, domain_matches: true, action_matches: true, times_present: true, not_expired: true, not_future: true, lifetime_ok: true, decision_known: true, resolve_bound: true };
 const V = { integrity_valid: true, issuer_trusted: true, key_policy_valid: true, unavailable: [] };
@@ -63,6 +112,7 @@ const acc = [
   ["baseline_changed_in_receipt", R("allow", { assessed: { expected_tools_sha256: "b".repeat(64), tools_sha256: "c".repeat(64), matches: false } }), V, F, {}],
   ["partial_assessment", R("allow", { resolve: { sha256: "a".repeat(64), status: "partial" } }), Object.assign({}, V, { unavailable: ["ots_attestations"] }), F, {}]
 ].map(([name, receipt, verification, fields, opts]) => ({ name, receipt, verification, scope: { fields }, opts, expect: C.acceptanceOf(receipt, verification, { fields }, opts) }));
-const out = { v: 1, generated_by: "sdk/test/fixtures/continuity-gen.mjs", now: NOW, default_policy_sha256: (await C.continuityPolicy()).sha256, lock, tools_v1: v1, cases, failures, acceptance: acc };
+const out = { v: 1, generated_by: "sdk/test/fixtures/continuity-gen.mjs", now: NOW, default_policy_sha256: (await C.continuityPolicy()).sha256, lock, tools_v1: v1, cases, failures, acceptance: acc, baseline_cases: baselineCases, operator, key_directory: keyDir };
 fs.writeFileSync(new URL("./continuity.json", import.meta.url), JSON.stringify(out, null, 1) + "\n");
-console.log("cases", cases.length, "failures", failures.length, "acceptance", acc.length);
+console.log("cases", cases.length, "failures", failures.length, "acceptance", acc.length, "baseline", baselineCases.length);
+for (const b of baselineCases) console.log(" ", b.name.padEnd(40), b.expect.trust.padEnd(16), b.expect.why.slice(0, 90));