@crawlcheck/sdk 1.12.0 → 1.13.0

package/README.md

@@ -179,6 +179,32 @@ const tools = await loadMcpToolsWithContinuity("shop", client, lock, { mode: "ob
 
 `observe` records every difference (`console.warn`, `onRecord`, `server.continuity.records` / `tools.continuity.records`) and passes the tools through. `review` pauses the whole server on any change until `confirm` says yes. `enforce` applies the policy: a changed or new tool is withheld from the agent, and a call to it is refused, until `confirm({ tool, continuity })` re-approves it; the rest stay usable. A refusal throws `ContinuityRefused` (with `.record`). A yes is remembered for that exact definition, so a framework that lists tools every turn does not ask twice. For CrewAI, use the Python package (`crawlcheck.crewai.with_continuity`).
 
+### Check the baseline before trusting it (1.13.0)
+
+Whoever can edit your approved lockfile can approve their own tools. So every gate (`withPreflight` with `lock`, `continuityGate`, `withContinuity`, `loadMcpToolsWithContinuity`) checks the lockfile's signature once, when it is created, before it compares anything against it:
+
+| `baseline.trust` | meaning |
+|---|---|
+| `verified` | signed by CrawlCheck (`cc.mcpLock(url)` / `GET /api/v1/mcp/lock`) with a CrawlCheck key. The package ships the published key ids (`CRAWLCHECK_LOCK_KIDS`); pass `keyPolicy: await cc.publishedKeyPolicy()` to follow a key rotation. These lockfiles carry `parts` inside the signature; `parts` added afterwards are not used. |
+| `operator_signed` | you signed it with `signLock` and passed your public key in `operatorKeys`. Use this when you edit a lockfile yourself, for example to drop a tool. |
+| `unsigned` | no signature. Accepted unless `requireSignedBaseline` (on by default once you pass `operatorKeys`). |
+| `invalid` | the signature does not verify, the file was changed after signing, or the key is neither CrawlCheck's nor one of yours. |
+
+`invalid`, or `unsigned` when a signed one is required, is the failure class `baseline_untrusted`: `enforce` and `review` refuse (`ContinuityRefused` / `McpPreflightRefused`), `observe` records it and goes on. `openContinuityGate(lock, opts)` throws at startup; `continuityGate` exposes `gate.ready` and `gate.baseline`. Every record names the result in `baseline.trust`. Nothing is verified per call.
+
+Sign your own lockfile, with no command line:
+
+```js
+import { newOperatorKey, signLock, openContinuityGate } from "@crawlcheck/sdk";
+
+const key = await newOperatorKey();                 // once; store key.privateKey where the agent cannot read it
+const signed = await signLock(lock, key.privateKey); // after you review (or edit) the lockfile; save signed
+// at startup, with only the public key:
+const gate = await openContinuityGate(signed, { mode: "enforce", operatorKeys: [key.publicKey] });
+```
+
+`verifyLockBaseline(lock, opts)` runs the same check on its own. The signature is Ed25519 over `"crawlcheck-lock-operator-v1\n" + sha256(canonical JSON of the lockfile without operator_signature)`; the Python package signs and verifies byte for byte the same.
+
 ## Do not trust the API: check the evidence yourself
 
 ```js

package/dist/continuity.d.ts

@@ -27,6 +27,7 @@ export declare const CONTINUITY_DEFAULT_POLICY: Readonly<{
         check_timeout: "pause";
         service_unavailable: "pause";
         decision_refused: "deny";
+        baseline_untrusted: "deny";
     }>;
 }>;
 /** Per-part hashes of one tool, so a change can be named (description, schema, annotations). */
@@ -63,6 +64,7 @@ export declare function continuityPolicy(p: any): Promise<{
         check_timeout: "pause";
         service_unavailable: "pause";
         decision_refused: "deny";
+        baseline_untrusted: "deny";
     }>;
     allow_integrity_override: boolean;
 } & {
@@ -103,3 +105,45 @@ export declare function acceptanceOf(receipt: any, verification: any, scope: any
 };
 /** Which failure class a refused guard() result is (for continuityFailure). */
 export declare function continuityClassOf(g: any): "check_timeout" | "decision_refused" | "evidence_expired" | "key_retired" | "key_unknown" | "response_malformed" | "server_identity_mismatch" | "service_unavailable" | "signature_invalid";
+/** CrawlCheck's lockfile signing keys (RFC 7638 thumbprints), as published at /.well-known/http-message-signatures-directory on 2026-11-07. */
+export declare const CRAWLCHECK_LOCK_KIDS: readonly string[];
+/** The operator's signature over the canonical lockfile (every field but operator_signature). privateKey: an Ed25519 private JWK ({kty, crv, x, d}). */
+export declare function signLock(lock: any, privateKey: any): Promise<{
+    operator_signature: {
+        v: number;
+        alg: string;
+        kid: string;
+        message: string;
+        sig: string;
+    };
+}>;
+/** A new operator signing key: { privateKey (JWK, keep it out of the agent's reach), publicKey ({kty, crv, x}: pass it as operatorKeys) }. */
+export declare function newOperatorKey(): Promise<{
+    privateKey: {
+        kty: string;
+        crv: string;
+        x: string | undefined;
+        d: string | undefined;
+    };
+    publicKey: {
+        kty: string;
+        crv: string;
+        x: string | undefined;
+    };
+    kid: string;
+}>;
+/**
+ * Is this baseline the one CrawlCheck or the operator signed? opts: operatorKeys (public JWKs or their x), keyPolicy,
+ * publishedKids, trustedKids. Returns { trust: verified | operator_signed | unsigned | invalid, signer, kid, why, parts_used,
+ * lock } where lock is the baseline to compare against (without unsigned parts). Offline; no network.
+ */
+export declare function verifyLockBaseline(lock: any, opts?: {}): Promise<{
+    trust: any;
+    signer: any;
+    kid: any;
+    why: any;
+    parts_used: boolean;
+    lock: any;
+}>;
+/** Why a baseline is refused (null when it is accepted). */
+export declare function baselineRefusal(b: any, requireSigned: any): any;

package/dist/continuity.js

@@ -15,15 +15,19 @@
 //   enforce   the policy's effects apply as written
 // Effects, weakest to strongest: proceed, proceed_recorded (an approved exception), refresh, pause_tool, pause, deny.
 // A failed exact comparison is never overridden by an interpretive assessment: nothing here reads descriptions for intent.
-import { canon } from "./verify.js";
+import { canon, keyPolicyCheck } from "./verify.js";
 const subtle = globalThis.crypto && globalThis.crypto.subtle;
 const enc = new TextEncoder();
 const hex = (u8) => Array.from(u8, (b) => b.toString(16).padStart(2, "0")).join("");
 async function sha256Hex(s) { return hex(new Uint8Array(await subtle.digest("SHA-256", enc.encode(s)))); }
+const b64d = (s) => { const t = String(s || "").replace(/-/g, "+").replace(/_/g, "/"); const bin = atob(t.padEnd(Math.ceil(t.length / 4) * 4, "=")); const o = new Uint8Array(bin.length); for (let i = 0; i < bin.length; i++)
+    o[i] = bin.charCodeAt(i); return o; };
+const b64e = (u8) => { let s = ""; for (const b of u8)
+    s += String.fromCharCode(b); return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""); };
 export const CONTINUITY_EFFECTS = ["proceed", "proceed_recorded", "refresh", "pause_tool", "pause", "deny"];
 export const CONTINUITY_CHANGE_CLASSES = ["tool_added", "tool_removed", "description_changed", "schema_changed", "annotations_changed", "tool_changed"];
-export const CONTINUITY_FAILURE_CLASSES = ["evidence_expired", "signature_invalid", "key_unknown", "key_retired", "server_identity_mismatch", "server_unavailable", "tool_list_truncated", "response_malformed", "baseline_stale", "policy_version_mismatch", "check_timeout", "service_unavailable", "decision_refused"];
-const INTEGRITY = ["signature_invalid", "key_unknown", "key_retired", "server_identity_mismatch"];
+export const CONTINUITY_FAILURE_CLASSES = ["evidence_expired", "signature_invalid", "key_unknown", "key_retired", "server_identity_mismatch", "server_unavailable", "tool_list_truncated", "response_malformed", "baseline_stale", "policy_version_mismatch", "check_timeout", "service_unavailable", "decision_refused", "baseline_untrusted"];
+const INTEGRITY = ["signature_invalid", "key_unknown", "key_retired", "server_identity_mismatch", "baseline_untrusted"];
 /** The default operator policy. Every value can be overridden; the record names the policy's sha256, so what decided is attributable. */
 export const CONTINUITY_DEFAULT_POLICY = Object.freeze({
     v: 1, id: "crawlcheck-continuity-default", max_baseline_age_days: 90,
@@ -31,7 +35,8 @@ export const CONTINUITY_DEFAULT_POLICY = Object.freeze({
         unchanged: "proceed", tool_added: "pause_tool", tool_removed: "proceed", description_changed: "pause_tool", schema_changed: "pause_tool",
         annotations_changed: "pause_tool", tool_changed: "pause_tool", evidence_expired: "refresh", signature_invalid: "deny", key_unknown: "deny",
         key_retired: "deny", server_identity_mismatch: "deny", server_unavailable: "pause", tool_list_truncated: "pause", response_malformed: "pause",
-        baseline_stale: "pause", policy_version_mismatch: "pause", check_timeout: "pause", service_unavailable: "pause", decision_refused: "deny"
+        baseline_stale: "pause", policy_version_mismatch: "pause", check_timeout: "pause", service_unavailable: "pause", decision_refused: "deny",
+        baseline_untrusted: "deny"
     })
 });
 const WHY = {
@@ -44,7 +49,8 @@ const WHY = {
     tool_list_truncated: "the tool list is incomplete (a further page was not read)", response_malformed: "the tool list could not be parsed",
     baseline_stale: "the approved baseline is older than the policy allows", policy_version_mismatch: "the policy in force is not the version the deployment expects",
     check_timeout: "the check did not finish in time", service_unavailable: "the verification service could not be reached; the local fallback applies",
-    decision_refused: "CrawlCheck's signed decision for the server's host did not allow the connection"
+    decision_refused: "CrawlCheck's signed decision for the server's host did not allow the connection",
+    baseline_untrusted: "the approved baseline is not trusted: its signature does not verify, its key is neither CrawlCheck's nor a given operator key, or it is unsigned where a signed one is required"
 };
 /** Per-part hashes of one tool, so a change can be named (description, schema, annotations). */
 export async function lockToolParts(t) {
@@ -138,7 +144,7 @@ export async function continuityCheck(lock, tools, opts = {}) {
     const was = {};
     (lock?.tools ?? []).forEach((r) => { was[r.name] = r.sha256; });
     const approvedAt = Date.parse(lock?.approved_at ?? "");
-    rec.baseline = { tools_sha256: lock?.tools_sha256 ?? null, approved_at: lock?.approved_at ?? null, age_days: isFinite(approvedAt) ? Math.floor((now - approvedAt) / 864e5) : null, server: lock?.server?.url ?? null, per_part: !!(lock && lock.parts) };
+    rec.baseline = { tools_sha256: lock?.tools_sha256 ?? null, approved_at: lock?.approved_at ?? null, age_days: isFinite(approvedAt) ? Math.floor((now - approvedAt) / 864e5) : null, server: lock?.server?.url ?? null, per_part: !!(lock && lock.parts), trust: opts.baselineTrust ?? null };
     rec.observed = { tools_sha256: listHash, count: rows.length, complete: opts.complete !== false };
     if (opts.expectPolicySha256 && opts.expectPolicySha256 !== pol.sha256)
         ev(rec, pol, mode, "policy_version_mismatch", null, X, now, "expected " + opts.expectPolicySha256 + ", in force " + pol.sha256);
@@ -282,3 +288,127 @@ export function continuityClassOf(g) {
         return "response_malformed";
     return "decision_refused";
 }
+// ── signed baseline (1.13.0) ───────────────────────────────────────────────────────────────────────────────────────
+// Whoever can edit the approved lockfile can approve their own tools. So the baseline's signature is checked once, when a
+// gate is created (startup), before anything is compared against it:
+//   verified         signed by CrawlCheck (/api/v1/mcp/lock, kind crawlcheck-mcp-lock, scheme crawlcheck-data-v1) with a
+//                    CrawlCheck key: the pinned ids below, opts.publishedKids, or opts.keyPolicy (keyPolicyFrom /
+//                    publishedKeyPolicy, which follows rotation). lock.parts added after signing is not covered: dropped.
+//   operator_signed  signed with signLock() by a key in opts.operatorKeys (the operator's Ed25519 public keys).
+//   unsigned         no signature. Accepted unless requireSignedBaseline (default: on when operatorKeys are given).
+//   invalid          a signature that does not verify, a changed lockfile, or a key that is neither: baseline_untrusted.
+/** CrawlCheck's lockfile signing keys (RFC 7638 thumbprints), as published at /.well-known/http-message-signatures-directory on 2026-11-07. */
+export const CRAWLCHECK_LOCK_KIDS = Object.freeze(["1hHmE3fo1rg5Ig70wuFtJ5wBc7G-sUTgUJkxyPWFRps", "hcIAczGf-8EFBnkunmZlvFWnD2nHHeHeC9cM4BTiBVo"]);
+const DATA_PREFIX = "crawlcheck-data-v1\n", OP_PREFIX = "crawlcheck-lock-operator-v1\n";
+async function thumbOf(x) { return b64e(new Uint8Array(await subtle.digest("SHA-256", enc.encode(JSON.stringify({ crv: "Ed25519", kty: "OKP", x: String(x) }))))); }
+async function edVerify(x, msg, sig) {
+    try {
+        const k = await subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: String(x) }, { name: "Ed25519" }, false, ["verify"]);
+        return await subtle.verify({ name: "Ed25519" }, k, b64d(sig), enc.encode(msg));
+    }
+    catch (e) {
+        return /not supported|unrecognized|unknown algorithm|NotSupported/i.test(String(e && (e.name + " " + e.message))) ? null : false;
+    }
+}
+const without = (o, keys) => { const b = {}; for (const k of Object.keys(o))
+    if (keys.indexOf(k) < 0)
+        b[k] = o[k]; return b; };
+const xOf = (k) => (typeof k === "string" ? k : k && typeof k.x === "string" ? k.x : null);
+/** The operator's signature over the canonical lockfile (every field but operator_signature). privateKey: an Ed25519 private JWK ({kty, crv, x, d}). */
+export async function signLock(lock, privateKey) {
+    if (!lock || typeof lock !== "object" || !Array.isArray(lock.tools))
+        throw new Error("lock must be an mcp-lockfile (an object with a tools array)");
+    const j = privateKey || {};
+    if (typeof j.d !== "string" || typeof j.x !== "string")
+        throw new Error("privateKey must be an Ed25519 private JWK with d and x (see newOperatorKey)");
+    const body = without(lock, ["operator_signature"]), message = OP_PREFIX + (await sha256Hex(canon(body)));
+    const k = await subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: j.x, d: j.d }, { name: "Ed25519" }, false, ["sign"]);
+    const sig = b64e(new Uint8Array(await subtle.sign({ name: "Ed25519" }, k, enc.encode(message))));
+    return Object.assign(body, { operator_signature: { v: 1, alg: "Ed25519", kid: await thumbOf(j.x), message, sig } });
+}
+/** A new operator signing key: { privateKey (JWK, keep it out of the agent's reach), publicKey ({kty, crv, x}: pass it as operatorKeys) }. */
+export async function newOperatorKey() {
+    const kp = await subtle.generateKey({ name: "Ed25519" }, true, ["sign", "verify"]), j = await subtle.exportKey("jwk", kp.privateKey);
+    return { privateKey: { kty: "OKP", crv: "Ed25519", x: j.x, d: j.d }, publicKey: { kty: "OKP", crv: "Ed25519", x: j.x }, kid: await thumbOf(j.x) };
+}
+/**
+ * Is this baseline the one CrawlCheck or the operator signed? opts: operatorKeys (public JWKs or their x), keyPolicy,
+ * publishedKids, trustedKids. Returns { trust: verified | operator_signed | unsigned | invalid, signer, kid, why, parts_used,
+ * lock } where lock is the baseline to compare against (without unsigned parts). Offline; no network.
+ */
+export async function verifyLockBaseline(lock, opts = {}) {
+    const R = (trust, signer, kid, why, L) => ({ trust, signer, kid, why, parts_used: !!(L && L.parts && typeof L.parts === "object" && !Array.isArray(L.parts) && Object.keys(L.parts).length > 0), lock: L || lock });
+    if (!lock || typeof lock !== "object" || !Array.isArray(lock.tools))
+        return R("invalid", null, null, "the baseline is not an mcp-lockfile (an object with a tools array)", null);
+    const op = lock.operator_signature, okeys = (opts.operatorKeys || []).map(xOf).filter(Boolean);
+    if (op !== undefined && op !== null && (okeys.length || !lock.signature)) {
+        if (!okeys.length)
+            return R("invalid", null, null, "the baseline carries an operator signature, but no operator key was given to check it", null);
+        if (!op || typeof op !== "object" || op.alg !== "Ed25519" || typeof op.kid !== "string" || typeof op.sig !== "string" || typeof op.message !== "string")
+            return R("invalid", null, null, "the operator signature is malformed", null);
+        let x = null;
+        for (const k of okeys)
+            if ((await thumbOf(k)) === op.kid)
+                x = k;
+        if (!x)
+            return R("invalid", null, op.kid, "the operator signature is by key " + op.kid + ", which is not one of the operator keys given", null);
+        const sha = await sha256Hex(canon(without(lock, ["operator_signature"])));
+        if (op.message !== OP_PREFIX + sha)
+            return R("invalid", "operator", op.kid, "the baseline was changed after the operator signed it (it hashes to " + sha + ")", null);
+        const ok = await edVerify(x, op.message, op.sig);
+        if (ok === null)
+            return R("invalid", "operator", op.kid, "this runtime cannot verify Ed25519", null);
+        if (!ok)
+            return R("invalid", "operator", op.kid, "the operator signature does not verify", null);
+        return R("operator_signed", "operator", op.kid, "signed by operator key " + op.kid, lock);
+    }
+    const s = lock.signature;
+    if (s === undefined || s === null)
+        return R("unsigned", null, null, "the baseline carries no signature", lock);
+    if (lock.kind !== "crawlcheck-mcp-lock" || typeof s !== "object" || String(s.message || "").indexOf(DATA_PREFIX) !== 0)
+        return R("invalid", null, null, "the signature is not a CrawlCheck lockfile signature (kind crawlcheck-mcp-lock, scheme crawlcheck-data-v1)", null);
+    const kid = typeof s.kid === "string" ? s.kid : null;
+    let L = lock, sha = await sha256Hex(canon(without(lock, ["sha256", "signature", "operator_signature"])));
+    if (sha !== lock.sha256 && lock.parts !== undefined) {
+        const sha2 = await sha256Hex(canon(without(lock, ["sha256", "signature", "operator_signature", "parts"])));
+        if (sha2 === lock.sha256) {
+            sha = sha2;
+            L = without(lock, ["parts"]);
+        }
+    }
+    if (sha !== lock.sha256)
+        return R("invalid", "crawlcheck", kid, "the baseline was changed after it was signed (it hashes to " + sha + ", the signature covers " + (lock.sha256 == null ? "null" : String(lock.sha256)) + ")", null);
+    if (s.message !== DATA_PREFIX + lock.sha256)
+        return R("invalid", "crawlcheck", kid, "the signature does not cover this baseline's digest", null);
+    const jx = s.key && s.key.jwk && s.key.jwk.x;
+    if (typeof jx !== "string")
+        return R("invalid", "crawlcheck", kid, "the signature carries no key", null);
+    if ((await thumbOf(jx)) !== kid)
+        return R("invalid", "crawlcheck", kid, "the signing key's thumbprint is not its stated key id", null);
+    const ok = await edVerify(jx, s.message, s.sig);
+    if (ok === null)
+        return R("invalid", "crawlcheck", kid, "this runtime cannot verify Ed25519", null);
+    if (!ok)
+        return R("invalid", "crawlcheck", kid, "the signature does not verify", null);
+    if (opts.keyPolicy != null) {
+        const kp = keyPolicyCheck(lock, opts.keyPolicy);
+        if (kp.ok !== true)
+            return R("invalid", "crawlcheck", kid, "the key policy rejects the signing key: " + kp.why, null);
+    }
+    else {
+        const ids = opts.publishedKids ?? opts.trustedKids ?? CRAWLCHECK_LOCK_KIDS;
+        if (ids.indexOf(kid) < 0)
+            return R("invalid", "crawlcheck", kid, "the baseline is signed by key " + kid + ", which is not a CrawlCheck key", null);
+    }
+    return R("verified", "crawlcheck", kid, "signed by CrawlCheck key " + kid + (L !== lock ? "; lock.parts was added after signing and is not used" : ""), L);
+}
+/** Why a baseline is refused (null when it is accepted). */
+export function baselineRefusal(b, requireSigned) {
+    if (!b)
+        return "the baseline was not checked";
+    if (b.trust === "invalid")
+        return b.why;
+    if (b.trust === "unsigned" && requireSigned)
+        return "the baseline is unsigned and a signed one is required";
+    return null;
+}

package/dist/frameworks.d.ts

@@ -10,6 +10,9 @@ export declare function continuityGate(lock: any, opts?: {}): {
     records: never[];
     record: null;
     paused: Set<any>;
+    baseline: null;
+    ready: null;
+    readonly refused: any;
     keepRecord(rec: any): Promise<any>;
     ask(req: any): Promise<boolean>;
     /** Compare the offered tools with the lock and apply the mode. Returns the record; throws ContinuityRefused. */
@@ -21,6 +24,26 @@ export declare function continuityGate(lock: any, opts?: {}): {
     /** Refuse a call to a paused tool (a framework that cached an earlier list could still try it). */
     callOk(name: any): boolean;
 };
+/** continuityGate, checked at startup: resolves to the gate once the baseline verifies, throws ContinuityRefused when it does not (outside observe). */
+export declare function openContinuityGate(lock: any, opts?: {}): Promise<{
+    mode: any;
+    records: never[];
+    record: null;
+    paused: Set<any>;
+    baseline: null;
+    ready: null;
+    readonly refused: any;
+    keepRecord(rec: any): Promise<any>;
+    ask(req: any): Promise<boolean>;
+    /** Compare the offered tools with the lock and apply the mode. Returns the record; throws ContinuityRefused. */
+    check(tools: any, meta?: {}): Promise<any>;
+    /** Record a check that could not compare anything. Throws ContinuityRefused outside observe. */
+    fail(cls: any, detail: any): Promise<any>;
+    /** The tools the agent may see: all of them in observe mode, else without the paused ones. */
+    allowed(tools: any, nameOf?: (t: any) => any): any;
+    /** Refuse a call to a paused tool (a framework that cached an earlier list could still try it). */
+    callOk(name: any): boolean;
+}>;
 /**
  * OpenAI Agents SDK (@openai/agents): wrap an MCP server (MCPServerStdio, MCPServerStreamableHttp, MCPServerSSE or your
  * own MCPServer) so every listTools() the SDK makes is checked against lock. Everything else is the server's own.

package/dist/frameworks.js

@@ -10,7 +10,11 @@
 // confirm(request) may return a promise; request is { continuity: record } for the server or { tool, continuity } for one
 // tool. A yes is remembered for that exact definition, so a framework that lists tools every turn does not ask twice.
 // No framework is a dependency of this package: each adapter imports its framework only when called.
-import { continuityCheck, continuityFailure } from "./continuity.js";
+// 1.13.0 signed baseline: when the gate is created it checks the lockfile's signature (verifyLockBaseline) before trusting
+// it. opts.operatorKeys, keyPolicy, publishedKids, trustedKids, requireSignedBaseline. A bad or forged signature, or an
+// unsigned lockfile when requireSignedBaseline, is recorded as baseline_untrusted; outside observe every check then throws.
+// await gate.ready (or use openContinuityGate) to fail at startup.
+import { continuityCheck, continuityFailure, verifyLockBaseline, baselineRefusal } from "./continuity.js";
 import { canon } from "./verify.js";
 export class ContinuityRefused extends Error {
     constructor(why, record = null, tool = null) {
@@ -30,10 +34,12 @@ export function continuityGate(lock, opts = {}) {
     if (!lock || !Array.isArray(lock.tools))
         throw new Error("lock must be an approved mcp-lockfile (an object with a tools array); see https://crawlcheck.io/spec/mcp-lockfile");
     const keep = opts.keep ?? 50, okTools = new Set(), okLists = new Set();
-    let lastKey = null;
+    let lastKey = null, base = lock, refused = null;
     const co = { mode, policy: opts.policy, exceptions: opts.exceptions, server: opts.server ?? undefined, serverIdentity: opts.serverIdentity, expectPolicySha256: opts.expectPolicySha256 };
+    const requireSigned = opts.requireSignedBaseline ?? !!(opts.operatorKeys && opts.operatorKeys.length);
     const gate = {
-        mode, records: [], record: null, paused: new Set(),
+        mode, records: [], record: null, paused: new Set(), baseline: null, ready: null,
+        get refused() { return refused; },
         async keepRecord(rec) {
             gate.record = rec;
             gate.records = gate.records.concat([rec]).slice(-keep);
@@ -60,9 +66,12 @@ export function continuityGate(lock, opts = {}) {
         },
         /** Compare the offered tools with the lock and apply the mode. Returns the record; throws ContinuityRefused. */
         async check(tools, meta = {}) {
+            await gate.ready;
+            if (refused)
+                throw refused;
             const complete = meta.complete !== false;
             const rows = Array.isArray(tools) ? tools.map(pick) : tools;
-            let rec = await continuityCheck(lock, rows, Object.assign({}, co, { complete }));
+            let rec = await continuityCheck(base, rows, Object.assign({}, co, { complete, baselineTrust: gate.baseline && gate.baseline.trust }));
             const key = (rec.observed?.tools_sha256 ?? "") + "|" + complete;
             if (lastKey === key && gate.record)
                 rec = gate.record;
@@ -101,6 +110,9 @@ export function continuityGate(lock, opts = {}) {
         },
         /** Record a check that could not compare anything. Throws ContinuityRefused outside observe. */
         async fail(cls, detail) {
+            await gate.ready;
+            if (refused)
+                throw refused;
             const rec = await continuityFailure(cls, Object.assign({}, co, { detail: detail ? String(detail).slice(0, 300) : undefined }));
             lastKey = null;
             await gate.keepRecord(rec);
@@ -114,8 +126,36 @@ export function continuityGate(lock, opts = {}) {
         callOk(name) { if (mode !== "observe" && gate.paused.has(name))
             throw new ContinuityRefused("tool " + name + " changed since it was approved (or is new) and no person re-approved it", gate.record, name); return true; },
     };
+    gate.ready = (async () => {
+        let b;
+        try {
+            b = await verifyLockBaseline(lock, opts);
+        }
+        catch (e) {
+            b = { trust: "invalid", signer: null, kid: null, why: "the baseline could not be checked: " + (e && e.message || e), parts_used: false, lock };
+        }
+        gate.baseline = { trust: b.trust, signer: b.signer, kid: b.kid, why: b.why, parts_used: b.parts_used };
+        base = b.lock || lock;
+        const bad = baselineRefusal(b, requireSigned);
+        if (bad) {
+            const rec = await continuityFailure("baseline_untrusted", Object.assign({}, co, { detail: String(bad).slice(0, 300) }));
+            await gate.keepRecord(rec);
+            if (mode !== "observe" && rec.outcome !== "proceed")
+                refused = new ContinuityRefused(rec.why.join("; ") + ": " + bad, rec);
+        }
+        return gate.baseline;
+    })();
+    gate.ready.catch(() => { }); // a bad policy is thrown by check(), which awaits ready
     return gate;
 }
+/** continuityGate, checked at startup: resolves to the gate once the baseline verifies, throws ContinuityRefused when it does not (outside observe). */
+export async function openContinuityGate(lock, opts = {}) {
+    const g = continuityGate(lock, opts);
+    await g.ready;
+    if (g.refused)
+        throw g.refused;
+    return g;
+}
 const urlOf = (s) => {
     for (const p of [s && s.params, s && s.underlying && s.underlying.params, s && s.options])
         if (p && typeof p.url === "string" && p.url)
@@ -198,6 +238,9 @@ export async function loadMcpToolsWithContinuity(serverName, client, lock, opts
         conn = null;
     }
     const gate = opts.gate || continuityGate(lock, Object.assign({ server: opts.serverUrl ?? (conn && conn.url) ?? undefined }, opts));
+    await gate.ready;
+    if (gate.refused)
+        throw gate.refused; // 1.13.0: an untrusted baseline fails before the server is read
     let listed;
     try {
         listed = await listAll(mcp);

package/dist/index.d.ts

@@ -63,7 +63,8 @@ export interface ContinuityRecord {
         approved_at: string | null;
         age_days: number | null;
         server: string | null;
-        per_part: boolean;
+        per_part: boolean; /** 1.13.0: verified | operator_signed | unsigned | invalid (null when the caller did not check). */
+        trust: BaselineTrust["trust"] | null;
     } | null;
     observed: {
         tools_sha256: string;
@@ -87,7 +88,8 @@ export interface ContinuityOptions {
     serverIdentity?: string;
     expectPolicySha256?: string;
     now?: number;
-    detail?: string;
+    detail?: string; /** 1.13.0: the result of verifyLockBaseline, named in record.baseline.trust. */
+    baselineTrust?: BaselineTrust["trust"];
 }
 export declare const CONTINUITY_DEFAULT_POLICY: {
     v: 1;
@@ -126,7 +128,66 @@ export declare const acceptanceOf: (receipt: unknown, verification: unknown, sco
     confirmed?: boolean | null;
     lock?: unknown;
 }) => Acceptance;
-export interface ContinuityGateOptions extends ContinuityOptions {
+/** An Ed25519 public key ({kty: "OKP", crv: "Ed25519", x}) or its x. */
+export type OperatorKey = {
+    kty?: "OKP";
+    crv?: "Ed25519";
+    x: string;
+} | string;
+export interface BaselineOptions {
+    /** The operator's Ed25519 public keys; a lockfile signed with signLock by one of them is operator_signed. */
+    operatorKeys?: OperatorKey[];
+    /** keyPolicyFrom(directory) / publishedKeyPolicy(): CrawlCheck's keys with purposes and rotation, instead of the pinned ids. */
+    keyPolicy?: unknown;
+    /** CrawlCheck key ids to accept instead of the pinned CRAWLCHECK_LOCK_KIDS (publishedKeyIds()). */
+    publishedKids?: string[];
+    trustedKids?: string[];
+    /** Refuse an unsigned lockfile (default: true when operatorKeys are given). */
+    requireSignedBaseline?: boolean;
+}
+export interface BaselineTrust {
+    trust: "verified" | "operator_signed" | "unsigned" | "invalid";
+    signer: "crawlcheck" | "operator" | null;
+    kid: string | null;
+    why: string;
+    parts_used: boolean;
+}
+export declare const CRAWLCHECK_LOCK_KIDS: readonly string[];
+/** Is this the lockfile CrawlCheck or the operator signed? Offline. lock is the baseline to compare against (unsigned parts removed). */
+export declare const verifyLockBaseline: (lock: unknown, opts?: BaselineOptions) => Promise<BaselineTrust & {
+    lock: McpLock;
+}>;
+/** Sign a lockfile you approved (or edited) with your own Ed25519 key, over its canonical JSON. Returns a copy with operator_signature. */
+export declare const signLock: <T extends McpLock>(lock: T, privateKey: {
+    kty?: "OKP";
+    crv?: "Ed25519";
+    x: string;
+    d: string;
+}) => Promise<T & {
+    operator_signature: {
+        v: 1;
+        alg: "Ed25519";
+        kid: string;
+        message: string;
+        sig: string;
+    };
+}>;
+/** A new operator key: keep privateKey away from the agent; pass publicKey in operatorKeys. */
+export declare const newOperatorKey: () => Promise<{
+    privateKey: {
+        kty: "OKP";
+        crv: "Ed25519";
+        x: string;
+        d: string;
+    };
+    publicKey: {
+        kty: "OKP";
+        crv: "Ed25519";
+        x: string;
+    };
+    kid: string;
+}>;
+export interface ContinuityGateOptions extends ContinuityOptions, BaselineOptions {
     /** A person's re-approval: { continuity } for the server, { tool, continuity } for one tool. Remembered per definition. */
     confirm?: (request: {
         tool?: string;
@@ -143,7 +204,10 @@ export interface ContinuityGate {
     mode: "observe" | "review" | "enforce";
     records: ContinuityRecord[];
     record: ContinuityRecord | null;
-    paused: Set<string>;
+    paused: Set<string>; /** 1.13.0: the startup check of the lockfile's signature. */
+    ready: Promise<BaselineTrust>;
+    baseline: BaselineTrust | null;
+    readonly refused: Error | null;
     check(tools: McpTool[], meta?: {
         complete?: boolean;
     }): Promise<ContinuityRecord>;
@@ -159,6 +223,8 @@ export declare const ContinuityRefused: new (why: string, record?: ContinuityRec
 };
 /** The shared gate behind the framework adapters. Default mode observe. */
 export declare const continuityGate: (lock: McpLock, opts?: ContinuityGateOptions) => ContinuityGate;
+/** 1.13.0: continuityGate that fails at startup: throws ContinuityRefused when the baseline is untrusted (outside observe). */
+export declare const openContinuityGate: (lock: McpLock, opts?: ContinuityGateOptions) => Promise<ContinuityGate>;
 /** @openai/agents: wrap an MCP server so every listTools() is checked against lock. Records at server.continuity. */
 export declare const withContinuity: <S extends {
     listTools: (...a: any[]) => Promise<any[]>;
@@ -707,7 +773,7 @@ export declare const applyRevocations: (store: RevocationStore, doc: unknown, no
 export declare const revokedFor: (store: RevocationStore, domain: string, action?: string) => (RevokedEntry & {
     domain: string;
 }) | null;
-export interface McpPreflightOptions extends PreflightOptions {
+export interface McpPreflightOptions extends PreflightOptions, BaselineOptions {
     /** Proceed on warn too (default false). */
     allowWarn?: boolean;
     /** Called on require_confirmation (and, with confirmDestructive, before a destructive tool call); the connect or call proceeds only if it resolves true. */
@@ -726,7 +792,7 @@ export interface McpPreflightOptions extends PreflightOptions {
     /** The server URL when the transport does not expose it. */
     serverUrl?: string;
     /** 1.11.0: tool-interface continuity with lock. mode observe (record only), review (changes go to confirm), enforce (the policy applies). Every check is kept in state.records and passed to onRecord. https://crawlcheck.io/spec/continuity */
-    continuity?: ContinuityOptions & {
+    continuity?: ContinuityOptions & BaselineOptions & {
         onRecord?: (record: ContinuityRecord) => unknown;
     };
     onlineKeys?: boolean;
@@ -741,7 +807,9 @@ export interface McpPreflightState {
     approved: Set<string> | null;
     continuity: ContinuityRecord | null;
     records: ContinuityRecord[];
-    pausedTools: Set<string> | null;
+    pausedTools: Set<string> | null; /** 1.13.0 */
+    baseline: BaselineTrust | null;
+    ready: Promise<BaselineTrust | null>;
 }
 export interface McpPreflightHooks {
     state: McpPreflightState;

package/dist/index.js

@@ -21,10 +21,19 @@ export const lockParts = C.lockParts;
 /** Which continuity failure class a refused guard() result is. */
 export const continuityClassOf = C.continuityClassOf;
 export const acceptanceOf = C.acceptanceOf;
+export const CRAWLCHECK_LOCK_KIDS = C.CRAWLCHECK_LOCK_KIDS;
+/** Is this the lockfile CrawlCheck or the operator signed? Offline. lock is the baseline to compare against (unsigned parts removed). */
+export const verifyLockBaseline = C.verifyLockBaseline;
+/** Sign a lockfile you approved (or edited) with your own Ed25519 key, over its canonical JSON. Returns a copy with operator_signature. */
+export const signLock = C.signLock;
+/** A new operator key: keep privateKey away from the agent; pass publicKey in operatorKeys. */
+export const newOperatorKey = C.newOperatorKey;
 /** Thrown in review/enforce when a record's outcome is pause, refresh or deny and nobody re-approved (or a paused tool is called). */
 export const ContinuityRefused = F.ContinuityRefused;
 /** The shared gate behind the framework adapters. Default mode observe. */
 export const continuityGate = F.continuityGate;
+/** 1.13.0: continuityGate that fails at startup: throws ContinuityRefused when the baseline is untrusted (outside observe). */
+export const openContinuityGate = F.openContinuityGate;
 /** @openai/agents: wrap an MCP server so every listTools() is checked against lock. Records at server.continuity. */
 export const withContinuity = F.withContinuity;
 /** @langchain/mcp-adapters: loadMcpTools with the check. client: a MultiServerMCPClient or a connected MCP SDK Client. */