@crawlcheck/sdk 1.11.0 → 1.13.0

package/README.md

@@ -160,6 +160,51 @@ const client = withPreflight(new Client(...), new CrawlCheck(), {
 
 The default policy (`CONTINUITY_DEFAULT_POLICY`) pauses added, changed-description, changed-schema and changed-annotation tools, refreshes expired evidence, pauses on an unreachable server or service, a truncated or unreadable tool list, a stale baseline or an unexpected policy version, and denies on an invalid signature, an unpublished or retired key, or a different server. Override any effect; the integrity classes stay `deny` unless you set `allow_integrity_override`, and the record says so. Exceptions (`{ tool, class, until, by, reason }`) proceed as `proceed_recorded`, never as an ordinary pass. Every record (`crawlcheck-continuity-record`) names the baseline, what was observed, each event, the policy's sha256, the mode, the outcome and its own `record_sha256`. It states interface continuity at the check point: not code attestation, not a judgement that a tool is harmless, not user authorisation. `continuityCheck(lock, tools, opts)` and `continuityFailure(cls, opts)` run the same logic without a client; the Python SDK reproduces every record byte for byte (shared golden file `test/fixtures/continuity.json`). Other client stacks use the bare hooks: `mcpPreflight(cc, opts)` returns `beforeConnect`, `afterConnect` and `beforeToolCall`. A runnable demo is in `examples/mcp-preflight-demo.mjs`.
 
+### Continuity in your agent framework (1.12.0)
+
+The same check where the framework fetches an MCP server's tool list, against your approved lockfile. No CrawlCheck call, no key, no new dependency: each adapter uses the framework you already have.
+
+```js
+import { withContinuity, loadMcpToolsWithContinuity } from "@crawlcheck/sdk";
+
+// OpenAI Agents SDK (@openai/agents)
+const server = new MCPServerStreamableHttp({ url });
+await server.connect();
+const agent = new Agent({ name: "a", instructions: "...", mcpServers: [withContinuity(server, lock, { mode: "observe" })] });
+
+// LangChain (@langchain/mcp-adapters)
+const client = new MultiServerMCPClient({ mcpServers: { shop: { url } } });
+const tools = await loadMcpToolsWithContinuity("shop", client, lock, { mode: "observe" });
+```
+
+`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

@@ -0,0 +1,62 @@
+export declare class ContinuityRefused extends Error {
+    why: any;
+    record: any;
+    tool: any;
+    constructor(why: any, record?: null, tool?: null);
+}
+/** The shared gate. lock: an approved mcp-lockfile (with lock.parts so a change can be named). */
+export declare function continuityGate(lock: any, opts?: {}): {
+    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;
+};
+/** 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.
+ *   const guarded = withContinuity(server, lock, { mode: "observe" });  new Agent({ name, instructions, mcpServers: [guarded] })
+ * The records are at guarded.continuity.records.
+ */
+export declare function withContinuity(server: any, lock: any, opts?: {}): any;
+/**
+ * LangChain (@langchain/mcp-adapters): loadMcpTools with the continuity check.
+ *   const tools = await loadMcpToolsWithContinuity("shop", client, lock, { mode: "observe" })
+ * client: a MultiServerMCPClient (its connection for serverName is used) or a connected MCP SDK Client. The list is read
+ * once (every page) and the LangChain tools are converted from exactly the definitions that were compared.
+ * opts.adapters: the @langchain/mcp-adapters module (default: imported on first use); opts.loadOptions: its
+ * LoadMcpToolsOptions. The gate (records) is opts.gate, or read them from opts.onRecord.
+ */
+export declare function loadMcpToolsWithContinuity(serverName: any, client: any, lock: any, opts?: {}): Promise<any>;

package/dist/frameworks.js

@@ -0,0 +1,267 @@
+// Tool-interface continuity for agent frameworks (1.12.0, https://crawlcheck.io/spec/continuity). The same contract as the
+// Python package's continuity_gate.py and its openai_agents / langchain / crewai adapters.
+//
+// The check runs where the framework fetches an MCP server's tool list, against the lockfile the operator approved:
+//   observe  every difference is recorded (gate.records, onRecord, console.warn unless log: false) and the tools pass
+//            through unchanged. Nothing is blocked.
+//   review   any difference pauses the whole server until confirm() says yes; integrity failures are denied.
+//   enforce  the policy applies: by default a changed or new tool is withheld from the agent (pause_tool) until confirm()
+//            re-approves it; a whole-server pause or refresh asks confirm() once; deny throws ContinuityRefused.
+// 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.
+// 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) {
+        super("CrawlCheck continuity refused" + (tool ? " tool " + tool : "") + ": " + why);
+        this.name = "ContinuityRefused";
+        this.why = why;
+        this.record = record;
+        this.tool = tool;
+    }
+}
+const pick = (t) => ({ name: t?.name, description: t?.description, inputSchema: t?.inputSchema ?? t?.input_schema, annotations: t?.annotations });
+/** The shared gate. lock: an approved mcp-lockfile (with lock.parts so a change can be named). */
+export function continuityGate(lock, opts = {}) {
+    const mode = opts.mode || "observe";
+    if (["observe", "review", "enforce"].indexOf(mode) < 0)
+        throw new Error("mode must be observe, review or enforce");
+    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, 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(), baseline: null, ready: null,
+        get refused() { return refused; },
+        async keepRecord(rec) {
+            gate.record = rec;
+            gate.records = gate.records.concat([rec]).slice(-keep);
+            const changed = rec.events.some((e) => e.class !== "unchanged");
+            if (changed && opts.log !== false)
+                (opts.logger || console).warn("crawlcheck continuity " + rec.mode + " " + (rec.server || "-") + ": would " + rec.would + ", outcome " + rec.outcome + ": " + rec.why.join("; "));
+            if (opts.onRecord) {
+                try {
+                    await opts.onRecord(rec);
+                }
+                catch (e) { /* recording never breaks the agent */ }
+            }
+            return rec;
+        },
+        async ask(req) {
+            if (!opts.confirm)
+                return false;
+            try {
+                return !!(await opts.confirm(req));
+            }
+            catch {
+                return false;
+            }
+        },
+        /** 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(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;
+            else {
+                lastKey = key;
+                await gate.keepRecord(rec);
+            }
+            if (mode === "observe") {
+                gate.paused = new Set();
+                return rec;
+            }
+            if (rec.outcome === "deny")
+                throw new ContinuityRefused(rec.why.join("; "), rec);
+            if (rec.outcome === "pause" || rec.outcome === "refresh") {
+                if (!okLists.has(key)) {
+                    if (!(await gate.ask({ continuity: rec })))
+                        throw new ContinuityRefused(rec.why.join("; "), rec);
+                    okLists.add(key);
+                }
+                gate.paused = new Set();
+                return rec;
+            }
+            const byName = {};
+            for (const r of Array.isArray(rows) ? rows : [])
+                byName[String(r.name ?? "").slice(0, 120)] = canon(r);
+            const paused = new Set();
+            for (const n of rec.paused_tools) {
+                const k = n + "\n" + (byName[n] ?? "");
+                if (okTools.has(k) || (await gate.ask({ tool: n, continuity: rec })))
+                    okTools.add(k);
+                else
+                    paused.add(n);
+            }
+            gate.paused = paused;
+            return rec;
+        },
+        /** 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);
+            if (mode !== "observe" && rec.outcome !== "proceed")
+                throw new ContinuityRefused(rec.why.join("; "), rec);
+            return rec;
+        },
+        /** The tools the agent may see: all of them in observe mode, else without the paused ones. */
+        allowed(tools, nameOf = (t) => t?.name) { return mode === "observe" || !gate.paused.size ? tools.slice() : tools.filter((t) => !gate.paused.has(nameOf(t))); },
+        /** Refuse a call to a paused tool (a framework that cached an earlier list could still try it). */
+        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)
+            return p.url;
+    return null;
+};
+/**
+ * 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.
+ *   const guarded = withContinuity(server, lock, { mode: "observe" });  new Agent({ name, instructions, mcpServers: [guarded] })
+ * The records are at guarded.continuity.records.
+ */
+export function withContinuity(server, lock, opts = {}) {
+    const gate = opts.gate || continuityGate(lock, Object.assign({ server: opts.serverUrl ?? urlOf(server) ?? undefined }, opts));
+    const listTools = async (...a) => {
+        let tools;
+        try {
+            tools = await server.listTools(...a);
+        }
+        catch (e) {
+            await gate.fail("server_unavailable", e && e.message);
+            throw e;
+        }
+        await gate.check(tools, { complete: true }); // the Agents SDK reads every page or throws
+        return gate.allowed(tools);
+    };
+    const callTool = async (name, ...a) => { gate.callOk(name); return server.callTool(name, ...a); };
+    const callToolResult = server.callToolResult ? async (name, ...a) => { gate.callOk(name); return server.callToolResult(name, ...a); } : undefined;
+    return new Proxy(server, {
+        get(target, k) {
+            if (k === "listTools")
+                return listTools;
+            if (k === "callTool")
+                return callTool;
+            if (k === "callToolResult" && callToolResult)
+                return callToolResult;
+            if (k === "continuity")
+                return gate;
+            const v = Reflect.get(target, k, target);
+            return typeof v === "function" ? v.bind(target) : v; // bound: the servers keep private (#) state
+        },
+    });
+}
+async function listAll(client) {
+    const out = [];
+    let cursor, pages = 0;
+    for (;;) {
+        const r = await client.listTools(cursor ? { cursor } : undefined);
+        out.push(...(r?.tools ?? []));
+        const next = r?.nextCursor;
+        if (!next)
+            return { tools: out, complete: true };
+        if (++pages >= 1000 || next === cursor)
+            return { tools: out, complete: false };
+        cursor = next;
+    }
+}
+/**
+ * LangChain (@langchain/mcp-adapters): loadMcpTools with the continuity check.
+ *   const tools = await loadMcpToolsWithContinuity("shop", client, lock, { mode: "observe" })
+ * client: a MultiServerMCPClient (its connection for serverName is used) or a connected MCP SDK Client. The list is read
+ * once (every page) and the LangChain tools are converted from exactly the definitions that were compared.
+ * opts.adapters: the @langchain/mcp-adapters module (default: imported on first use); opts.loadOptions: its
+ * LoadMcpToolsOptions. The gate (records) is opts.gate, or read them from opts.onRecord.
+ */
+export async function loadMcpToolsWithContinuity(serverName, client, lock, opts = {}) {
+    const lc = opts.adapters || (await import("@langchain/mcp-adapters"));
+    let mcp = client;
+    if (client && typeof client.getClient === "function" && typeof client.callTool !== "function") {
+        mcp = await client.getClient(serverName);
+        if (!mcp)
+            throw new Error("no connected MCP server named " + serverName);
+    }
+    let conn = null;
+    try {
+        const c = client && client !== mcp ? client.config : null;
+        conn = c ? ((c.servers || c.mcpServers || {})[serverName] ?? null) : null;
+    }
+    catch {
+        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);
+    }
+    catch (e) {
+        await gate.fail("server_unavailable", e && e.message);
+        throw e;
+    }
+    await gate.check(structuredClone(listed.tools), { complete: listed.complete });
+    const allowed = gate.allowed(listed.tools);
+    const pinned = new Proxy(mcp, {
+        get(target, k) {
+            if (k === "listTools")
+                return async () => ({ tools: allowed });
+            if (k === "callTool")
+                return async (params, ...a) => { gate.callOk(params && params.name); return target.callTool(params, ...a); };
+            const v = Reflect.get(target, k, target);
+            return typeof v === "function" ? v.bind(target) : v;
+        },
+    });
+    const tools = await lc.loadMcpTools(serverName, pinned, opts.loadOptions);
+    Object.defineProperty(tools, "continuity", { value: gate, enumerable: false });
+    return tools;
+}