@crawlcheck/sdk 1.13.0 → 1.14.0

package/README.md

@@ -205,6 +205,19 @@ const gate = await openContinuityGate(signed, { mode: "enforce", operatorKeys: [
 
 `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.
 
+### Compare on jcs-v1 (1.14.0)
+
+Every lockfile from `cc.mcpLock(url)` / `GET /api/v1/mcp/lock` since 2026-11-07 carries `jcs_v1`: RFC 8785 digests of each tool's contract (`name`, `description`, `inputSchema`, `outputSchema`) and of everything else it carries (`title`, `annotations`, `icons`, `_meta`, vendor members). The SDK now computes the same digests offline, byte for byte:
+
+```js
+import { jcsV1 } from "@crawlcheck/sdk";
+const d = await jcsV1(tools);   // { tools_sha256: "sha256-…", extras_sha256: "sha256-…", count, tools: [{ name, contract, extras }] }
+```
+
+When the approved lockfile carries `jcs_v1`, `continuityCheck` and every gate compare on it, over every tool: a moved contract is named `description_changed` or `schema_changed` (from `parts`), a moved extras digest `annotations_changed`, and any other change (a new `title`, `outputSchema`, `_meta`) `tool_changed` with a `detail`. Records say `baseline.alg: "jcs-v1"`. Pass `digest: "lk-v1"` to compare on the v1 hashes instead. A missing `description` and `""` are the same contract under jcs-v1 (see the spec's notes on empty fields).
+
+Nothing is cut silently. `withPreflight` follows `nextCursor` to the last page; a list whose pages could not all be read is `tool_list_truncated` (and a v1 lockfile refuses it). A v1 lockfile hashes at most `LOCK_V1_MAX_TOOLS` (300) tools: past that, `lockFromTools` returns `complete: false` with `offered`, `checkLock` answers `verdict: "incomplete"`, `decision: "block"`, and a v1 continuity check raises `tool_list_truncated`. jcs-v1 has no cap.
+
 ## Do not trust the API: check the evidence yourself
 
 ```js

package/dist/continuity.d.ts

@@ -36,8 +36,11 @@ export declare function lockToolParts(t: any): Promise<{
     schema_sha256: string;
     annotations_sha256: string;
 }>;
-/** parts for a lockfile: { [tool name]: lockToolParts(tool) }. Store it as lock.parts next to lock.tools. */
+/** parts for a lockfile: { [tool name]: lockToolParts(tool) }, for every tool given. Store it as lock.parts next to lock.tools. */
 export declare function lockParts(tools: any): Promise<{}>;
+/** The most tools a v1 (lk) lockfile hashes; CrawlCheck's lockfile endpoint hashes the same. A longer list is compared on
+ * its first LOCK_V1_MAX_TOOLS tools and the read is marked incomplete (tool_list_truncated), never cut silently. */
+export declare const LOCK_V1_MAX_TOOLS = 300;
 /** The policy in force: the default with the operator's values over it, and its sha256 (what the record names). */
 export declare function continuityPolicy(p: any): Promise<{
     v: number;
@@ -74,7 +77,9 @@ export declare function continuityPolicy(p: any): Promise<{
  * Compare the offered tools with the approved baseline (an mcp-lockfile, ideally with lock.parts) and apply the policy.
  * opts: mode ("observe" | "review" | "enforce", default "enforce"), policy, exceptions [{tool, class, until, by, reason}],
  * complete (false when tools/list returned a nextCursor you did not follow), server (the URL checked), serverIdentity
- * (the URL the baseline was approved for; differs -> server_identity_mismatch), expectPolicySha256, now (ms).
+ * (the URL the baseline was approved for; differs -> server_identity_mismatch), expectPolicySha256, now (ms), digest
+ * ("lk-v1" to compare on the v1 hashes even when the lockfile carries jcs_v1; by default a lockfile with jcs_v1 is
+ * compared on jcs-v1, over every tool). A v1 comparison of more than LOCK_V1_MAX_TOOLS tools is marked incomplete.
  */
 export declare function continuityCheck(lock: any, tools: any, opts?: {}): Promise<any>;
 /** A record for a check that could not compare anything (the server, the evidence or the service failed). cls: one of CONTINUITY_FAILURE_CLASSES. */

package/dist/continuity.js

@@ -16,6 +16,7 @@
 // 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, keyPolicyCheck } from "./verify.js";
+import { jcsV1 } from "./jcs.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("");
@@ -57,9 +58,17 @@ export async function lockToolParts(t) {
     const schema = t?.inputSchema ?? t?.input_schema ?? null;
     return { description_sha256: await sha256Hex(canon(t?.description ?? null)), schema_sha256: await sha256Hex(canon(schema)), annotations_sha256: await sha256Hex(canon(t?.annotations ?? null)) };
 }
-/** parts for a lockfile: { [tool name]: lockToolParts(tool) }. Store it as lock.parts next to lock.tools. */
-export async function lockParts(tools) { const o = {}; for (const t of (tools ?? []).slice(0, 300))
+/** parts for a lockfile: { [tool name]: lockToolParts(tool) }, for every tool given. Store it as lock.parts next to lock.tools. */
+export async function lockParts(tools) { const o = {}; for (const t of (tools ?? []))
     o[String(t?.name ?? "").slice(0, 120)] = await lockToolParts(t); return o; }
+/** The most tools a v1 (lk) lockfile hashes; CrawlCheck's lockfile endpoint hashes the same. A longer list is compared on
+ * its first LOCK_V1_MAX_TOOLS tools and the read is marked incomplete (tool_list_truncated), never cut silently. */
+export const LOCK_V1_MAX_TOOLS = 300;
+/** The lockfile's jcs-v1 block when it can be compared on (a digest, and a per-tool row for every tool it counted). */
+function jcsBaseline(lock) {
+    const J = lock && lock.jcs_v1;
+    return J && typeof J === "object" && J.alg === "jcs-v1" && typeof J.tools_sha256 === "string" && J.tools_sha256 && Array.isArray(J.tools) && J.tools.length === J.count ? J : null;
+}
 async function toolHash(t) { return sha256Hex(canon({ name: t?.name ?? null, description: t?.description ?? null, inputSchema: t?.inputSchema ?? t?.input_schema ?? null, annotations: t?.annotations ?? null })); }
 /** The policy in force: the default with the operator's values over it, and its sha256 (what the record names). */
 export async function continuityPolicy(p) {
@@ -123,7 +132,9 @@ function ev(rec, pol, mode, cls, tool, exceptions, now, detail) {
  * Compare the offered tools with the approved baseline (an mcp-lockfile, ideally with lock.parts) and apply the policy.
  * opts: mode ("observe" | "review" | "enforce", default "enforce"), policy, exceptions [{tool, class, until, by, reason}],
  * complete (false when tools/list returned a nextCursor you did not follow), server (the URL checked), serverIdentity
- * (the URL the baseline was approved for; differs -> server_identity_mismatch), expectPolicySha256, now (ms).
+ * (the URL the baseline was approved for; differs -> server_identity_mismatch), expectPolicySha256, now (ms), digest
+ * ("lk-v1" to compare on the v1 hashes even when the lockfile carries jcs_v1; by default a lockfile with jcs_v1 is
+ * compared on jcs-v1, over every tool). A v1 comparison of more than LOCK_V1_MAX_TOOLS tools is marked incomplete.
  */
 export async function continuityCheck(lock, tools, opts = {}) {
     const mode = opts.mode || "enforce";
@@ -135,8 +146,12 @@ export async function continuityCheck(lock, tools, opts = {}) {
         ev(rec, pol, mode, "response_malformed", null, X, now);
         return finish(rec, mode);
     }
+    const J = opts.digest === "lk-v1" ? null : jcsBaseline(lock);
+    if (J)
+        return jcsCheck(rec, pol, mode, lock, J, tools, opts, X, now);
+    const capped = tools.length > LOCK_V1_MAX_TOOLS, complete = opts.complete !== false && !capped;
     const rows = [];
-    for (const t of tools.slice(0, 300))
+    for (const t of tools.slice(0, LOCK_V1_MAX_TOOLS))
         rows.push({ name: String(t?.name ?? "").slice(0, 120), sha256: await toolHash(t), t });
     const cur = {};
     rows.forEach((r) => { cur[r.name] = r; });
@@ -145,7 +160,9 @@ export async function continuityCheck(lock, tools, opts = {}) {
     (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), trust: opts.baselineTrust ?? null };
-    rec.observed = { tools_sha256: listHash, count: rows.length, complete: opts.complete !== false };
+    rec.observed = { tools_sha256: listHash, count: rows.length, complete };
+    if (capped)
+        rec.observed.offered = tools.length;
     if (opts.expectPolicySha256 && opts.expectPolicySha256 !== pol.sha256)
         ev(rec, pol, mode, "policy_version_mismatch", null, X, now, "expected " + opts.expectPolicySha256 + ", in force " + pol.sha256);
     const want = opts.serverIdentity ?? lock?.server?.url ?? null;
@@ -153,11 +170,11 @@ export async function continuityCheck(lock, tools, opts = {}) {
         ev(rec, pol, mode, "server_identity_mismatch", null, X, now, "baseline approved for " + want + ", checked " + opts.server);
     if (rec.baseline.age_days !== null && rec.baseline.age_days > pol.max_baseline_age_days)
         ev(rec, pol, mode, "baseline_stale", null, X, now, rec.baseline.age_days + " days old; the policy allows " + pol.max_baseline_age_days);
-    if (opts.complete === false)
-        ev(rec, pol, mode, "tool_list_truncated", null, X, now);
+    if (!complete)
+        ev(rec, pol, mode, "tool_list_truncated", null, X, now, capped ? "the server offers " + tools.length + " tools; a v1 lockfile hashes the first " + LOCK_V1_MAX_TOOLS : undefined);
     for (const n of Object.keys(cur).filter((n) => !(n in was)).sort())
         ev(rec, pol, mode, "tool_added", n, X, now);
-    if (opts.complete !== false)
+    if (complete)
         for (const n of Object.keys(was).filter((n) => !(n in cur)).sort())
             ev(rec, pol, mode, "tool_removed", n, X, now);
     for (const n of Object.keys(cur).filter((n) => n in was && was[n] !== cur[n].sha256).sort()) {
@@ -187,6 +204,75 @@ export async function continuityCheck(lock, tools, opts = {}) {
         rec.events.push({ class: "unchanged", tool: null, why: "the offered tools match the approved baseline", policy_effect: pol.effects.unchanged, effect: modeEffect(mode, "unchanged", pol.effects.unchanged) });
     return finish(rec, mode);
 }
+// 1.14.0: the comparison on jcs-v1 (https://crawlcheck.io/spec/mcp-lockfile#jcs-v1), used when the lockfile carries a
+// jcs_v1 block (every CrawlCheck lockfile since 2026-11-07). Every tool is digested (no cap). A moved contract digest is
+// named description_changed / schema_changed from lock.parts when it has them; a moved extras digest is
+// annotations_changed when the annotations moved, otherwise tool_changed (title, icons, _meta or another member).
+async function jcsCheck(rec, pol, mode, lock, J, tools, opts, X, now) {
+    const complete = opts.complete !== false, cj = await jcsV1(tools, { partial: false });
+    const approvedAt = Date.parse(lock?.approved_at ?? "");
+    rec.baseline = { alg: "jcs-v1", tools_sha256: J.tools_sha256, extras_sha256: J.extras_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 = { alg: "jcs-v1", tools_sha256: cj.tools_sha256, extras_sha256: cj.tools_sha256 === null ? null : cj.extras_sha256, count: Array.isArray(tools) ? tools.length : 0, complete };
+    if (opts.expectPolicySha256 && opts.expectPolicySha256 !== pol.sha256)
+        ev(rec, pol, mode, "policy_version_mismatch", null, X, now, "expected " + opts.expectPolicySha256 + ", in force " + pol.sha256);
+    const want = opts.serverIdentity ?? lock?.server?.url ?? null;
+    if (want && opts.server && String(want).replace(/\/+$/, "") !== String(opts.server).replace(/\/+$/, ""))
+        ev(rec, pol, mode, "server_identity_mismatch", null, X, now, "baseline approved for " + want + ", checked " + opts.server);
+    if (rec.baseline.age_days !== null && rec.baseline.age_days > pol.max_baseline_age_days)
+        ev(rec, pol, mode, "baseline_stale", null, X, now, rec.baseline.age_days + " days old; the policy allows " + pol.max_baseline_age_days);
+    if (cj.tools_sha256 === null) {
+        ev(rec, pol, mode, "response_malformed", null, X, now, "the tool list has no jcs-v1 digest: " + cj.reason);
+        return finish(rec, mode);
+    }
+    const names = cj.tools.map((r) => r.name), dups = names.filter((n, i) => i > 0 && names[i - 1] === n).filter((n, i, a) => a.indexOf(n) === i);
+    if (dups.length) {
+        ev(rec, pol, mode, "response_malformed", null, X, now, "the tool list names a tool more than once: " + dups.slice(0, 10).join(", "));
+        return finish(rec, mode);
+    }
+    if (!complete)
+        ev(rec, pol, mode, "tool_list_truncated", null, X, now);
+    const was = {}, cur = {}, raw = {};
+    J.tools.forEach((r) => { if (r && typeof r.name === "string")
+        was[r.name] = r; });
+    cj.tools.forEach((r) => { cur[r.name] = r; });
+    tools.forEach((t) => { raw[t.name] = t; });
+    const n0 = rec.events.length;
+    for (const n of Object.keys(cur).filter((n) => !(n in was)).sort())
+        ev(rec, pol, mode, "tool_added", n, X, now);
+    if (complete)
+        for (const n of Object.keys(was).filter((n) => !(n in cur)).sort())
+            ev(rec, pol, mode, "tool_removed", n, X, now);
+    for (const n of Object.keys(cur).filter((n) => n in was).sort()) {
+        const a = was[n], b = cur[n], dc = a.contract !== b.contract, dx = a.extras !== b.extras;
+        if (!dc && !dx)
+            continue;
+        const P = lock && lock.parts && lock.parts[n], q = P ? await lockToolParts(raw[n]) : null, moved = [];
+        if (dc && P && q.description_sha256 !== P.description_sha256) {
+            ev(rec, pol, mode, "description_changed", n, X, now);
+            moved.push("d");
+        }
+        if (dc && P && q.schema_sha256 !== P.schema_sha256) {
+            ev(rec, pol, mode, "schema_changed", n, X, now);
+            moved.push("s");
+        }
+        if (dx && P && q.annotations_sha256 !== P.annotations_sha256) {
+            ev(rec, pol, mode, "annotations_changed", n, X, now);
+            moved.push("a");
+        }
+        const rest = [];
+        if (dc && !moved.some((m) => m === "d" || m === "s"))
+            rest.push(P ? "the contract changed outside description and inputSchema (outputSchema)" : "the contract (description, inputSchema or outputSchema) changed");
+        if (dx && moved.indexOf("a") < 0)
+            rest.push(P ? "a member outside the contract changed (title, icons, _meta or another; not annotations)" : "a member outside the contract changed (title, annotations, icons, _meta or another)");
+        if (rest.length)
+            ev(rec, pol, mode, "tool_changed", n, X, now, rest.join("; "));
+    }
+    if (complete && rec.events.length === n0 && (cj.tools_sha256 !== J.tools_sha256 || (cj.extras_sha256 || "") !== (J.extras_sha256 || "")))
+        ev(rec, pol, mode, "response_malformed", null, X, now, "the tool set's jcs-v1 digest differs from the approved one, but no single tool's does");
+    if (!rec.events.length)
+        rec.events.push({ class: "unchanged", tool: null, why: "the offered tools match the approved baseline", policy_effect: pol.effects.unchanged, effect: modeEffect(mode, "unchanged", pol.effects.unchanged) });
+    return finish(rec, mode);
+}
 /** A record for a check that could not compare anything (the server, the evidence or the service failed). cls: one of CONTINUITY_FAILURE_CLASSES. */
 export async function continuityFailure(cls, opts = {}) {
     if (CONTINUITY_FAILURE_CLASSES.indexOf(cls) < 0)

package/dist/index.d.ts

@@ -59,6 +59,8 @@ export interface ContinuityRecord {
     };
     claims: string;
     baseline: {
+        alg?: "jcs-v1";
+        extras_sha256?: string | null;
         tools_sha256: string | null;
         approved_at: string | null;
         age_days: number | null;
@@ -67,9 +69,12 @@ export interface ContinuityRecord {
         trust: BaselineTrust["trust"] | null;
     } | null;
     observed: {
-        tools_sha256: string;
+        alg?: "jcs-v1";
+        extras_sha256?: string | null;
+        tools_sha256: string | null;
         count: number;
-        complete: boolean;
+        complete: boolean; /** 1.14.0: the number of tools offered, when more than a v1 lockfile hashes (the read is then incomplete). */
+        offered?: number;
     } | null;
     events: ContinuityEvent[];
     would: ContinuityEffect;
@@ -89,7 +94,8 @@ export interface ContinuityOptions {
     expectPolicySha256?: string;
     now?: number;
     detail?: string; /** 1.13.0: the result of verifyLockBaseline, named in record.baseline.trust. */
-    baselineTrust?: BaselineTrust["trust"];
+    baselineTrust?: BaselineTrust["trust"]; /** 1.14.0: "lk-v1" compares on the v1 hashes even when the lockfile carries jcs_v1 (default: jcs-v1 when present). */
+    digest?: "lk-v1" | "jcs-v1";
 }
 export declare const CONTINUITY_DEFAULT_POLICY: {
     v: 1;
@@ -113,6 +119,34 @@ export declare const lockToolParts: (t: McpTool) => Promise<{
     schema_sha256: string;
     annotations_sha256: string;
 }>;
+export interface JcsV1 {
+    alg: "jcs-v1";
+    spec: string;
+    count?: number;
+    tools_sha256: string | null;
+    extras_sha256?: string;
+    tools?: {
+        name: string;
+        contract: string;
+        extras: string;
+    }[];
+    reason?: string;
+}
+/** jcs-v1 contract and extras digests of a tools/list result (every page; no cap). Equals lock.jcs_v1 from /api/v1/mcp/lock. */
+export declare const jcsV1: (tools: McpTool[], opts?: {
+    partial?: boolean;
+}) => Promise<JcsV1>;
+/** RFC 8785 canonical JSON. */
+export declare const jcsCanon: (v: unknown) => string;
+export declare const jcsContract: (t: McpTool) => {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    outputSchema?: unknown;
+};
+export declare const jcsExtras: (t: McpTool) => Record<string, unknown>;
+/** The most tools a v1 lockfile hashes; a longer list is compared on that many and marked incomplete. */
+export declare const LOCK_V1_MAX_TOOLS: number;
 export declare const lockParts: (tools: McpTool[]) => Promise<Record<string, {
     description_sha256: string;
     schema_sha256: string;
@@ -437,16 +471,26 @@ export interface McpLock {
     [k: string]: unknown;
 }
 export interface McpLockCheck {
-    verdict: "unchanged" | "changed";
+    verdict: "unchanged" | "changed" | "incomplete";
     decision: "connect" | "block";
     approved_tools_sha256: string;
     current_tools_sha256: string;
     added: string[];
     removed: string[];
-    modified: string[];
+    modified: string[]; /** 1.14.0: the jcs-v1 comparison, when the lockfile carries jcs_v1. */
+    jcs_v1?: {
+        alg: "jcs-v1";
+        current_tools_sha256: string | null;
+        current_extras_sha256: string | null;
+        approved_tools_sha256?: string;
+        contract_unchanged?: boolean;
+        extras_unchanged?: boolean;
+    } | null; /** 1.14.0: more tools than a v1 lockfile hashes were offered. */
+    offered?: number;
 }
 export declare function lockToolHash(t: McpTool): Promise<string>;
 /** Hash a tools/list result the way a lockfile does: per tool, and the sorted per-tool hashes joined by \n. No network, no key. */
+/** 1.14.0: also jcs_v1 (the jcs-v1 digests over every tool), and complete: false with offered when the list is longer than a v1 lockfile hashes (LOCK_V1_MAX_TOOLS). */
 export declare function lockFromTools(tools: McpTool[]): Promise<{
     tools: {
         name: string;
@@ -454,6 +498,9 @@ export declare function lockFromTools(tools: McpTool[]): Promise<{
     }[];
     tools_sha256: string;
     count: number;
+    complete: boolean;
+    offered?: number;
+    jcs_v1: JcsV1;
 }>;
 /** Compare a lockfile with the tools a server lists now. Anything added, removed or changed means "block" until a person re-approves. Offline. */
 export declare function checkLock(lock: McpLock, tools: McpTool[]): Promise<McpLockCheck>;

package/dist/index.js

@@ -5,6 +5,7 @@ import * as M from "./mcp.js";
 import * as R from "./revocations.js";
 import * as C from "./continuity.js";
 import * as F from "./frameworks.js";
+import * as J from "./jcs.js";
 export const CONTINUITY_DEFAULT_POLICY = C.CONTINUITY_DEFAULT_POLICY;
 export const CONTINUITY_CHANGE_CLASSES = C.CONTINUITY_CHANGE_CLASSES;
 export const CONTINUITY_FAILURE_CLASSES = C.CONTINUITY_FAILURE_CLASSES;
@@ -16,6 +17,14 @@ export const continuityFailure = C.continuityFailure;
 export const continuityPolicy = C.continuityPolicy;
 /** Per-part hashes (description, schema, annotations) so a change can be named. Store lockParts(tools) as lock.parts. */
 export const lockToolParts = C.lockToolParts;
+/** jcs-v1 contract and extras digests of a tools/list result (every page; no cap). Equals lock.jcs_v1 from /api/v1/mcp/lock. */
+export const jcsV1 = J.jcsV1;
+/** RFC 8785 canonical JSON. */
+export const jcsCanon = J.jcsCanon;
+export const jcsContract = J.jcsContract;
+export const jcsExtras = J.jcsExtras;
+/** The most tools a v1 lockfile hashes; a longer list is compared on that many and marked incomplete. */
+export const LOCK_V1_MAX_TOOLS = C.LOCK_V1_MAX_TOOLS;
 export const lockParts = C.lockParts;
 /** The separate acceptance questions for one decision receipt. Act on policy_result, never on integrity_valid alone. */
 /** Which continuity failure class a refused guard() result is. */
@@ -93,12 +102,16 @@ export async function lockToolHash(t) {
     return sha256Hex(V.canon({ name: t?.name ?? null, description: t?.description ?? null, inputSchema: t?.inputSchema ?? t?.input_schema ?? null, annotations: t?.annotations ?? null }));
 }
 /** Hash a tools/list result the way a lockfile does: per tool, and the sorted per-tool hashes joined by \n. No network, no key. */
+/** 1.14.0: also jcs_v1 (the jcs-v1 digests over every tool), and complete: false with offered when the list is longer than a v1 lockfile hashes (LOCK_V1_MAX_TOOLS). */
 export async function lockFromTools(tools) {
-    const rows = [];
-    for (const t of (tools ?? []).slice(0, 300))
+    const rows = [], all = tools ?? [];
+    for (const t of all.slice(0, LOCK_V1_MAX_TOOLS))
         rows.push({ name: String(t?.name ?? "").slice(0, 120), sha256: await lockToolHash(t) });
     rows.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : a.sha256 < b.sha256 ? -1 : 1));
-    return { tools: rows, tools_sha256: await sha256Hex(rows.map((r) => r.sha256).sort().join("\n")), count: rows.length };
+    const out = { tools: rows, tools_sha256: await sha256Hex(rows.map((r) => r.sha256).sort().join("\n")), count: rows.length, complete: all.length <= LOCK_V1_MAX_TOOLS, jcs_v1: await jcsV1(all) };
+    if (!out.complete)
+        out.offered = all.length;
+    return out;
 }
 /** Compare a lockfile with the tools a server lists now. Anything added, removed or changed means "block" until a person re-approves. Offline. */
 export async function checkLock(lock, tools) {
@@ -109,7 +122,16 @@ export async function checkLock(lock, tools) {
     now.tools.forEach((r) => { cur[r.name] = r.sha256; });
     const added = Object.keys(cur).filter((n) => !(n in was)), removed = Object.keys(was).filter((n) => !(n in cur)), modified = Object.keys(cur).filter((n) => n in was && was[n] !== cur[n]);
     const same = lock?.tools_sha256 === now.tools_sha256 && !added.length && !removed.length && !modified.length;
-    return { verdict: same ? "unchanged" : "changed", decision: same ? "connect" : "block", approved_tools_sha256: lock?.tools_sha256 ?? "", current_tools_sha256: now.tools_sha256, added, removed, modified };
+    const a = lock?.jcs_v1, b = now.jcs_v1;
+    const jc = { alg: "jcs-v1", current_tools_sha256: b.tools_sha256 ?? null, current_extras_sha256: b.tools_sha256 === null ? null : b.extras_sha256 ?? null };
+    if (a && typeof a.tools_sha256 === "string" && a.tools_sha256) {
+        jc.approved_tools_sha256 = a.tools_sha256;
+        jc.contract_unchanged = !!b.tools_sha256 && a.tools_sha256 === b.tools_sha256;
+        jc.extras_unchanged = (a.extras_sha256 || null) === (b.extras_sha256 || null);
+    }
+    if (!now.complete)
+        return { verdict: "incomplete", decision: "block", approved_tools_sha256: lock?.tools_sha256 ?? "", current_tools_sha256: now.tools_sha256, added, removed: [], modified, jcs_v1: jc, offered: now.offered }; // never connect on part of a list
+    return { verdict: same ? "unchanged" : "changed", decision: same ? "connect" : "block", approved_tools_sha256: lock?.tools_sha256 ?? "", current_tools_sha256: now.tools_sha256, added, removed, modified, jcs_v1: jc };
 }
 /** The operation for calling an MCP tool: its name, the sha256 of its definition (as in the lockfile) and the scopes you will use. */
 export async function toolOperation(tool, scopes) { const o = { tool: String(tool?.name ?? ""), tool_schema_sha256: await lockToolHash(tool) }; if (scopes && scopes.length)

package/dist/jcs.d.ts

@@ -0,0 +1,37 @@
+export declare const JCS_V1_SPEC = "https://crawlcheck.io/spec/mcp-lockfile#jcs-v1";
+/** RFC 8785 canonical JSON (keys in UTF-16 code-unit order, ECMAScript number form, no whitespace). Throws on a non-finite number. */
+export declare function jcsCanon(v: any): any;
+/** A tool's contract: what the model reads and the call takes or returns. */
+export declare function jcsContract(t: any): {
+    name: any;
+    description: any;
+    inputSchema: any;
+};
+/** A tool's extras: every member beyond name, description, inputSchema and outputSchema. */
+export declare function jcsExtras(t: any): any;
+/**
+ * The jcs-v1 digests of a tools/list result (every page). opts.partial: true when a page was not read (the list is then
+ * not digested). Returns { alg, spec, count, tools_sha256, extras_sha256, tools: [{name, contract, extras}] } or
+ * { alg, spec, tools_sha256: null, reason }.
+ */
+export declare function jcsV1(tools: any, opts?: {}): Promise<{
+    alg: string;
+    spec: string;
+    tools_sha256: null;
+    reason: string;
+    count?: undefined;
+    extras_sha256?: undefined;
+    tools?: undefined;
+} | {
+    reason?: undefined;
+    alg: string;
+    spec: string;
+    count: number;
+    tools_sha256: string;
+    extras_sha256: string;
+    tools: {
+        name: any;
+        contract: string;
+        extras: string;
+    }[];
+}>;

package/dist/jcs.js

@@ -0,0 +1,131 @@
+// jcs-v1 tool-list digests (https://crawlcheck.io/spec/mcp-lockfile#jcs-v1), 1.14.0. The same construction the lockfile
+// endpoint publishes as lock.jcs_v1, step for step, so a digest computed here equals the signed one byte for byte.
+//
+//   contract  {name, description, inputSchema, outputSchema}: description "" when absent or not a string, inputSchema {}
+//             when absent or not an object, outputSchema only when the server sent an object. RFC 8785, SHA-256 (hex).
+//   extras    every other member (title, annotations, icons, execution, _meta, vendor members), strings cleaned (NUL and
+//             unpaired surrogates -> U+FFFD), nesting past 12 levels -> "…". RFC 8785, SHA-256 (hex).
+//   tools_sha256   SRI sha256 over the RFC 8785 array of contracts sorted by name (UTF-16 code units; ties by bytes).
+//   extras_sha256  SRI sha256 over {"tools": {name: extras}} for the tools that carry extras ("" when none do), with
+//                  "oversized" (one tool's extras > 16,384 bytes) and "omitted" (past 262,144 bytes in all).
+// A tool with no name, or a number with no IEEE 754 double, makes the list not digestible: tools_sha256 null and a reason.
+// No list is cut: every tool given is digested and listed.
+const enc = new TextEncoder();
+const subtle = globalThis.crypto && globalThis.crypto.subtle;
+const hex = (u8) => Array.from(u8, (b) => b.toString(16).padStart(2, "0")).join("");
+const b64 = (u8) => { let s = ""; for (let i = 0; i < u8.length; i++)
+    s += String.fromCharCode(u8[i]); return btoa(s); };
+const sha = async (bytes) => new Uint8Array(await subtle.digest("SHA-256", bytes));
+export const JCS_V1_SPEC = "https://crawlcheck.io/spec/mcp-lockfile#jcs-v1";
+/** RFC 8785 canonical JSON (keys in UTF-16 code-unit order, ECMAScript number form, no whitespace). Throws on a non-finite number. */
+export function jcsCanon(v) {
+    if (v === null || typeof v === "boolean" || typeof v === "string")
+        return JSON.stringify(v);
+    if (typeof v === "number") {
+        if (!isFinite(v))
+            throw new Error("a number with no IEEE 754 double");
+        return JSON.stringify(v);
+    }
+    if (Array.isArray(v))
+        return "[" + v.map(jcsCanon).join(",") + "]";
+    if (typeof v === "object")
+        return "{" + Object.keys(v).filter((k) => v[k] !== undefined).sort().map((k) => JSON.stringify(k) + ":" + jcsCanon(v[k])).join(",") + "}";
+    throw new Error("not a JSON value");
+}
+const isObj = (x) => !!x && typeof x === "object" && !Array.isArray(x);
+/** A tool's contract: what the model reads and the call takes or returns. */
+export function jcsContract(t) {
+    const o = { name: t.name, description: typeof t.description === "string" ? t.description : "", inputSchema: isObj(t.inputSchema) ? t.inputSchema : {} };
+    if (isObj(t.outputSchema))
+        o.outputSchema = t.outputSchema;
+    return o;
+}
+const cleanS = (s) => String(s).replace(/\u0000/g, "�").replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "�");
+function clean(v, d) {
+    if (d > 12)
+        return "…";
+    if (typeof v === "string")
+        return cleanS(v);
+    if (Array.isArray(v))
+        return v.map((x) => clean(x, d + 1));
+    if (v && typeof v === "object") {
+        const o = {};
+        Object.keys(v).forEach((k) => { o[cleanS(k)] = clean(v[k], d + 1); });
+        return o;
+    }
+    return v;
+}
+/** A tool's extras: every member beyond name, description, inputSchema and outputSchema. */
+export function jcsExtras(t) {
+    const o = {};
+    Object.keys(t || {}).forEach((k) => { if (k !== "name" && k !== "description" && k !== "inputSchema" && k !== "outputSchema")
+        o[k] = t[k]; });
+    return clean(o, 0);
+}
+const cpCmp = (a, b) => { const x = Array.from(a), y = Array.from(b), n = Math.min(x.length, y.length); for (let i = 0; i < n; i++) {
+    const c = x[i].codePointAt(0) - y[i].codePointAt(0);
+    if (c)
+        return c;
+} return x.length - y.length; };
+const byteCmp = (a, b) => { const n = Math.min(a.length, b.length); for (let i = 0; i < n; i++)
+    if (a[i] !== b[i])
+        return a[i] - b[i]; return a.length - b.length; };
+async function extrasSet(tools) {
+    const per = {};
+    for (const t of tools || []) {
+        if (!t || typeof t.name !== "string" || !t.name)
+            continue;
+        const x = jcsExtras(t);
+        if (Object.keys(x).length)
+            per[cleanS(t.name)] = x;
+    }
+    const names = Object.keys(per).sort(cpCmp);
+    if (!names.length)
+        return "";
+    const body = { tools: {} }, over = {}, omit = [];
+    let used = 0;
+    for (const n of names) {
+        const sz = enc.encode(jcsCanon(per[n])).length;
+        if (sz > 16384) {
+            over[n] = sz;
+            continue;
+        }
+        if (used + sz > 262144) {
+            omit.push(n);
+            continue;
+        }
+        body.tools[n] = per[n];
+        used += sz;
+    }
+    if (Object.keys(over).length)
+        body.oversized = over;
+    if (omit.length)
+        body.omitted = omit;
+    return "sha256-" + b64(await sha(enc.encode(jcsCanon(body))));
+}
+/**
+ * The jcs-v1 digests of a tools/list result (every page). opts.partial: true when a page was not read (the list is then
+ * not digested). Returns { alg, spec, count, tools_sha256, extras_sha256, tools: [{name, contract, extras}] } or
+ * { alg, spec, tools_sha256: null, reason }.
+ */
+export async function jcsV1(tools, opts = {}) {
+    if (opts.partial)
+        return { alg: "jcs-v1", spec: JCS_V1_SPEC, tools_sha256: null, reason: "the tool list has more pages than were read; a partial list is not digested" };
+    try {
+        const rows = [];
+        for (const t of tools || []) {
+            if (!t || typeof t.name !== "string" || !t.name)
+                return { alg: "jcs-v1", spec: JCS_V1_SPEC, tools_sha256: null, reason: "a tool has no name" };
+            const cj = jcsCanon(jcsContract(t)), cb = enc.encode(cj);
+            rows.push({ name: t.name, cj, cb, contract: hex(await sha(cb)), extras: hex(await sha(enc.encode(jcsCanon(jcsExtras(t))))) });
+        }
+        rows.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : byteCmp(a.cb, b.cb)));
+        return { alg: "jcs-v1", spec: JCS_V1_SPEC, count: rows.length,
+            tools_sha256: "sha256-" + b64(await sha(enc.encode("[" + rows.map((r) => r.cj).join(",") + "]"))),
+            extras_sha256: await extrasSet(tools),
+            tools: rows.map((r) => ({ name: r.name, contract: r.contract, extras: r.extras })) };
+    }
+    catch (e) {
+        return { alg: "jcs-v1", spec: JCS_V1_SPEC, tools_sha256: null, reason: String((e && e.message) || e).slice(0, 120) };
+    }
+}

package/dist/mcp.js

@@ -17,6 +17,8 @@
 // request is never sent.
 import { normalizeDomain } from "./index.js";
 import { checkLock, toolOperation } from "./index.js";
+/** The most tools/list pages read before the list is called incomplete (tool_list_truncated). */
+const MAX_TOOL_PAGES = 1000;
 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; }
@@ -106,11 +108,8 @@ export function mcpPreflight(cc, opts = {}) {
     // vantage and the signed receipt names the endpoint and tool state it covered (a changed list comes back as block).
     const mcpScope = function () { if (!state.url || !/^https:/i.test(state.url))
         return undefined; const h = opts.lock && typeof opts.lock.tools_sha256 === "string" ? opts.lock.tools_sha256 : null; return h ? { url: state.url, tools_sha256: h } : { url: state.url }; };
-    const decide = async function (host) {
+    const checkConnect = async function (host) {
         const g = await cc.guard(host, "connect", { template, policy: opts.policy, agent: opts.agent, confirm: opts.confirm, allowWarn: !!opts.allowWarn, onlineKeys: opts.onlineKeys, mcp: mcpScope() });
-        state.receipt = g.receipt;
-        state.verification = g.verification;
-        state.decidedAt = Date.now();
         if (!g.proceed && CO) {
             const rec = await keep(await continuityFailure(continuityClassOf(g), coOpts({ detail: (g.why || []).join("; ").slice(0, 300) })));
             if (rec.outcome === "proceed")
@@ -136,6 +135,19 @@ export function mcpPreflight(cc, opts = {}) {
         }
         return g;
     };
+    const decide = async function (host) {
+        const url = state.url;
+        state.receipt = null;
+        state.verification = null;
+        const result = await checkConnect(host);
+        if (state.url !== url)
+            throw new McpPreflightRefused("connect", "the server URL changed during preflight");
+        // A refusal may include a valid-looking receipt. Only a completed gate can cache it.
+        state.receipt = result.receipt;
+        state.verification = result.verification;
+        state.decidedAt = Date.now();
+        return result;
+    };
     return {
         state,
         /** Before initialize. url: the server URL (a stdio/local server has none and is not decided; pass opts.local = "allow" | "refuse", default allow). */
@@ -186,6 +198,8 @@ export function mcpPreflight(cc, opts = {}) {
                 state.approved = null;
                 return null;
             }
+            if (meta && meta.nextCursor)
+                throw new McpPreflightRefused("connect", "the server's tool list could not be read in full (a further page was not read); nothing is approved on part of a list", { receipt: state.receipt });
             const lc = await checkLock(baseLock, tools || []);
             state.lockCheck = lc;
             state.approved = new Set((opts.lock.tools || []).map(function (t) { return t.name; }));
@@ -247,12 +261,27 @@ export function withPreflight(client, cc, opts = {}) {
         if (opts.lock || opts.confirmDestructive || (opts.toolReceipts || "write") !== "none") {
             let list = [];
             let meta = null, bad = false;
-            try {
-                const t = typeof client.listTools === "function" ? await client.listTools() : null;
-                list = (t && t.tools) || [];
-                meta = t ? { nextCursor: t.nextCursor || null } : null;
-                if (t && !Array.isArray(t.tools))
-                    bad = true;
+            try { // 1.14.0: every page (nextCursor followed); a list whose pages could not all be read is marked incomplete
+                if (typeof client.listTools === "function") {
+                    let cursor = null;
+                    const seen = new Set();
+                    for (;;) {
+                        const t = await client.listTools(cursor ? { cursor } : undefined);
+                        if (!t)
+                            break;
+                        if (!Array.isArray(t.tools)) {
+                            bad = true;
+                            break;
+                        }
+                        list = list.concat(t.tools);
+                        const next = t.nextCursor || null;
+                        meta = { nextCursor: next };
+                        if (!next || seen.has(next) || seen.size >= MAX_TOOL_PAGES - 1)
+                            break;
+                        seen.add(next);
+                        cursor = next;
+                    }
+                }
             }
             catch (e) {
                 list = [];