@crawlcheck/sdk 1.10.0 → 1.12.0

package/dist/frameworks.js

@@ -0,0 +1,224 @@
+// 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.
+import { continuityCheck, continuityFailure } 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;
+    const co = { mode, policy: opts.policy, exceptions: opts.exceptions, server: opts.server ?? undefined, serverIdentity: opts.serverIdentity, expectPolicySha256: opts.expectPolicySha256 };
+    const gate = {
+        mode, records: [], record: null, paused: new Set(),
+        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 = {}) {
+            const complete = meta.complete !== false;
+            const rows = Array.isArray(tools) ? tools.map(pick) : tools;
+            let rec = await continuityCheck(lock, rows, Object.assign({}, co, { complete }));
+            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) {
+            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; },
+    };
+    return gate;
+}
+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));
+    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;
+}

package/dist/index.d.ts

@@ -1,6 +1,183 @@
 import type { paths, components } from "./gen/openapi.js";
 import * as S from "./staple.js";
 export type { paths, components };
+export interface Acceptance {
+    integrity_valid: boolean;
+    issuer_trusted: boolean | null;
+    key_policy_valid: boolean | null;
+    freshness_valid: boolean;
+    subject_matches: boolean;
+    operation_matches: boolean | null;
+    replay_safe: boolean | null;
+    baseline_matches: boolean | null;
+    assessment_complete: boolean;
+    decision: string | null;
+    policy_source: string | null;
+    evidence_level: "A" | "B" | "C" | null;
+    policy_result: "proceed" | "pause" | "deny";
+    accepted: boolean;
+    why: string[];
+}
+export type ContinuityEffect = "proceed" | "proceed_recorded" | "refresh" | "pause_tool" | "pause" | "deny";
+export interface ContinuityPolicy {
+    v?: 1;
+    id?: string;
+    max_baseline_age_days?: number;
+    effects?: Partial<Record<string, ContinuityEffect>>;
+    allow_integrity_override?: boolean;
+}
+export interface ContinuityException {
+    tool?: string;
+    class: string;
+    until?: string;
+    by?: string;
+    reason?: string;
+}
+export interface ContinuityEvent {
+    class: string;
+    tool: string | null;
+    why: string;
+    policy_effect: ContinuityEffect;
+    effect: ContinuityEffect;
+    exception?: {
+        by: string | null;
+        reason: string | null;
+        until: string | null;
+    };
+    detail?: string;
+}
+export interface ContinuityRecord {
+    kind: "crawlcheck-continuity-record";
+    v: 1;
+    checked_at: string;
+    mode: "observe" | "review" | "enforce";
+    server: string | null;
+    policy: {
+        id: string;
+        sha256: string;
+        integrity_override: boolean;
+    };
+    claims: string;
+    baseline: {
+        tools_sha256: string | null;
+        approved_at: string | null;
+        age_days: number | null;
+        server: string | null;
+        per_part: boolean;
+    } | null;
+    observed: {
+        tools_sha256: string;
+        count: number;
+        complete: boolean;
+    } | null;
+    events: ContinuityEvent[];
+    would: ContinuityEffect;
+    enforced: boolean;
+    outcome: "proceed" | "refresh" | "pause" | "deny";
+    paused_tools: string[];
+    why: string[];
+    record_sha256: string;
+}
+export interface ContinuityOptions {
+    mode?: "observe" | "review" | "enforce";
+    policy?: ContinuityPolicy;
+    exceptions?: ContinuityException[];
+    complete?: boolean;
+    server?: string;
+    serverIdentity?: string;
+    expectPolicySha256?: string;
+    now?: number;
+    detail?: string;
+}
+export declare const CONTINUITY_DEFAULT_POLICY: {
+    v: 1;
+    id: string;
+    max_baseline_age_days: number;
+    effects: Record<string, ContinuityEffect>;
+};
+export declare const CONTINUITY_CHANGE_CLASSES: string[];
+export declare const CONTINUITY_FAILURE_CLASSES: string[];
+/** Compare offered tools with the approved baseline and apply the operator's policy; returns the record to keep. */
+export declare const continuityCheck: (lock: McpLock, tools: unknown, opts?: ContinuityOptions) => Promise<ContinuityRecord>;
+/** The record for a check that could not compare (server, evidence or service failed). */
+export declare const continuityFailure: (cls: string, opts?: ContinuityOptions) => Promise<ContinuityRecord>;
+/** The policy in force (default + yours) and its sha256. */
+export declare const continuityPolicy: (p?: ContinuityPolicy) => Promise<Required<ContinuityPolicy> & {
+    sha256: string;
+}>;
+/** Per-part hashes (description, schema, annotations) so a change can be named. Store lockParts(tools) as lock.parts. */
+export declare const lockToolParts: (t: McpTool) => Promise<{
+    description_sha256: string;
+    schema_sha256: string;
+    annotations_sha256: string;
+}>;
+export declare const lockParts: (tools: McpTool[]) => Promise<Record<string, {
+    description_sha256: string;
+    schema_sha256: string;
+    annotations_sha256: string;
+}>>;
+/** 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. */
+export declare const continuityClassOf: (g: GuardResult | null) => string;
+export declare const acceptanceOf: (receipt: unknown, verification: unknown, scope: {
+    fields?: unknown;
+} | null, opts?: {
+    allowWarn?: boolean;
+    confirmed?: boolean | null;
+    lock?: unknown;
+}) => Acceptance;
+export interface ContinuityGateOptions extends ContinuityOptions {
+    /** A person's re-approval: { continuity } for the server, { tool, continuity } for one tool. Remembered per definition. */
+    confirm?: (request: {
+        tool?: string;
+        continuity: ContinuityRecord;
+    }) => boolean | Promise<boolean>;
+    onRecord?: (record: ContinuityRecord) => unknown;
+    /** false: no console.warn on a change. */ log?: boolean;
+    logger?: {
+        warn: (msg: string) => unknown;
+    };
+    /** Records kept in gate.records (default 50). */ keep?: number;
+}
+export interface ContinuityGate {
+    mode: "observe" | "review" | "enforce";
+    records: ContinuityRecord[];
+    record: ContinuityRecord | null;
+    paused: Set<string>;
+    check(tools: McpTool[], meta?: {
+        complete?: boolean;
+    }): Promise<ContinuityRecord>;
+    fail(cls: string, detail?: string): Promise<ContinuityRecord>;
+    allowed<T>(tools: T[], nameOf?: (t: T) => string): T[];
+    callOk(name: string): true;
+}
+/** 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 declare const ContinuityRefused: new (why: string, record?: ContinuityRecord | null, tool?: string | null) => Error & {
+    why: string;
+    record: ContinuityRecord | null;
+    tool: string | null;
+};
+/** The shared gate behind the framework adapters. Default mode observe. */
+export declare const continuityGate: (lock: McpLock, opts?: ContinuityGateOptions) => 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[]>;
+    callTool: (...a: any[]) => Promise<any>;
+}>(server: S, lock: McpLock, opts?: ContinuityGateOptions & {
+    serverUrl?: string;
+    gate?: ContinuityGate;
+}) => S & {
+    continuity: ContinuityGate;
+};
+/** @langchain/mcp-adapters: loadMcpTools with the check. client: a MultiServerMCPClient or a connected MCP SDK Client. */
+export declare const loadMcpToolsWithContinuity: (serverName: string, client: unknown, lock: McpLock, opts?: ContinuityGateOptions & {
+    serverUrl?: string;
+    gate?: ContinuityGate;
+    adapters?: unknown;
+    loadOptions?: unknown;
+}) => Promise<any[] & {
+    continuity: ContinuityGate;
+}>;
 /** One verifier check. ok: true passed, false FAILED, null could not run (why says why) - never a pass. */
 export interface VerifyCheck {
     id: string;
@@ -180,7 +357,12 @@ export interface McpLock {
     tools: {
         name: string;
         sha256: string;
-    }[];
+    }[]; /** 1.11.0: per-part hashes (lockParts) so continuityCheck can name what changed. */
+    parts?: Record<string, {
+        description_sha256: string;
+        schema_sha256: string;
+        annotations_sha256: string;
+    }>;
     descriptions?: Record<string, string>;
     server?: {
         url?: string | null;
@@ -303,16 +485,31 @@ export interface DecisionWant {
  * time window, per-action lifetime, known decision, resolve binding); the signature and issuer are checked by
  * verifyDocument. guard() runs both. https://crawlcheck.io/spec/guard
  */
+export interface DecisionScopeFields {
+    kind_ok: boolean;
+    domain_matches: boolean;
+    action_matches: boolean;
+    operation_matches?: boolean;
+    nonce_matches?: boolean;
+    times_present: boolean;
+    not_expired: boolean;
+    not_future: boolean;
+    lifetime_ok: boolean;
+    decision_known: boolean;
+    resolve_bound: boolean;
+}
 export declare function checkDecision(receipt: unknown, want: DecisionWant): {
     ok: boolean;
     why: string[];
+    fields: DecisionScopeFields;
 };
 export interface GuardResult {
     proceed: boolean;
     receipt: DecisionReceipt | null;
     verification: (DocumentVerification & Trust) | null;
     header: Record<string, string> | null;
-    why: string[];
+    why: string[]; /** 1.11.0: the separate acceptance questions (integrity, issuer, key policy, freshness, subject, operation, replay, baseline, completeness) and policy_result. Null when no receipt came back. */
+    acceptance: Acceptance | null;
     split_view?: LogFork[]; /** Set when the domain was refused from the held revocation list, with no network call. */
     revoked?: RevokedEntry;
 }
@@ -528,6 +725,10 @@ export interface McpPreflightOptions extends PreflightOptions {
     local?: "allow" | "refuse";
     /** 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 & {
+        onRecord?: (record: ContinuityRecord) => unknown;
+    };
     onlineKeys?: boolean;
 }
 export interface McpPreflightState {
@@ -536,8 +737,11 @@ export interface McpPreflightState {
     receipt: DecisionReceipt | null;
     verification: (DocumentVerification & Trust) | null;
     decidedAt: number;
-    lockCheck: McpLockCheck | null;
+    lockCheck: McpLockCheck | ContinuityRecord | null;
     approved: Set<string> | null;
+    continuity: ContinuityRecord | null;
+    records: ContinuityRecord[];
+    pausedTools: Set<string> | null;
 }
 export interface McpPreflightHooks {
     state: McpPreflightState;
@@ -547,7 +751,9 @@ export interface McpPreflightHooks {
         receipt: DecisionReceipt | null;
         verification?: DocumentVerification & Trust;
     }>;
-    afterConnect(tools: McpTool[]): Promise<McpLockCheck | null>;
+    afterConnect(tools: McpTool[] | null, meta?: {
+        nextCursor?: string | null;
+    } | null): Promise<McpLockCheck | ContinuityRecord | null>;
     beforeToolCall(name: string, annotations?: unknown): Promise<{
         receipt: DecisionReceipt | null;
     }>;

package/dist/index.js

@@ -3,6 +3,32 @@ import * as L from "./log.js";
 import * as S from "./staple.js";
 import * as M from "./mcp.js";
 import * as R from "./revocations.js";
+import * as C from "./continuity.js";
+import * as F from "./frameworks.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;
+/** Compare offered tools with the approved baseline and apply the operator's policy; returns the record to keep. */
+export const continuityCheck = C.continuityCheck;
+/** The record for a check that could not compare (server, evidence or service failed). */
+export const continuityFailure = C.continuityFailure;
+/** The policy in force (default + yours) and its sha256. */
+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;
+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. */
+export const continuityClassOf = C.continuityClassOf;
+export const acceptanceOf = C.acceptanceOf;
+/** 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;
+/** @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. */
+export const loadMcpToolsWithContinuity = F.loadMcpToolsWithContinuity;
 /** The signing policy as data (https://crawlcheck.io/keys#policy): object purposes, purpose chains, start times. */
 export const KEY_POLICY = V.KEY_POLICY;
 /** Build the policy input from a key directory you hold and, optionally, the rotation record saved with it. */
@@ -84,46 +110,63 @@ export const ACTION_MAX_LIFETIME_S = { read: 86400, cite: 86400, connect: 3600,
 /** The most clock skew a receipt may claim (seconds). */
 export const MAX_CLOCK_SKEW_S = 300;
 const DECISIONS = ["allow", "warn", "require_confirmation", "block", "unsupported"];
-/**
- * Is this receipt about the operation you are about to perform? Checks the scope only (kind, domain, action, nonce,
- * time window, per-action lifetime, known decision, resolve binding); the signature and issuer are checked by
- * verifyDocument. guard() runs both. https://crawlcheck.io/spec/guard
- */
 export function checkDecision(receipt, want) {
     const why = [], r = receipt;
+    const f = { kind_ok: false, domain_matches: false, action_matches: false, times_present: false, not_expired: false, not_future: false, lifetime_ok: false, decision_known: false, resolve_bound: false };
+    if (want.operation)
+        f.operation_matches = false;
+    if (want.nonce)
+        f.nonce_matches = false;
     if (!r || typeof r !== "object" || Array.isArray(r))
-        return { ok: false, why: ["no receipt: CrawlCheck sent " + (r === null || r === undefined ? "nothing" : typeof r)] };
-    if (r.kind !== "crawlcheck-decision" || r.v !== 1)
+        return { ok: false, why: ["no receipt: CrawlCheck sent " + (r === null || r === undefined ? "nothing" : typeof r)], fields: f };
+    f.kind_ok = r.kind === "crawlcheck-decision" && r.v === 1;
+    if (!f.kind_ok)
         why.push("not a v1 decision receipt (kind " + r.kind + ", v " + r.v + ")");
     const wd = normalizeDomain(want.domain);
-    if (!wd || normalizeDomain(r.domain) !== wd)
+    f.domain_matches = !!wd && normalizeDomain(r.domain) === wd;
+    if (!f.domain_matches)
         why.push("the receipt is for " + r.domain + ", not " + want.domain);
-    if (String(r.action) !== String(want.action))
+    f.action_matches = String(r.action) === String(want.action);
+    if (!f.action_matches)
         why.push("the receipt is for action " + r.action + ", not " + want.action);
-    if (want.operation && canon(r.operation ?? null) !== canon(want.operation))
-        why.push(r.operation ? "the receipt is for another operation (" + canon(r.operation).slice(0, 120) + ")" : "the receipt is not scoped to an operation, and this request named one");
-    if (want.nonce && r.nonce !== want.nonce)
-        why.push(r.nonce ? "the receipt carries another request's nonce (replayed)" : "the receipt does not carry the nonce this request sent");
+    if (want.operation) {
+        f.operation_matches = canon(r.operation ?? null) === canon(want.operation);
+        if (!f.operation_matches)
+            why.push(r.operation ? "the receipt is for another operation (" + canon(r.operation).slice(0, 120) + ")" : "the receipt is not scoped to an operation, and this request named one");
+    }
+    if (want.nonce) {
+        f.nonce_matches = r.nonce === want.nonce;
+        if (!f.nonce_matches)
+            why.push(r.nonce ? "the receipt carries another request's nonce (replayed)" : "the receipt does not carry the nonce this request sent");
+    }
     const now = want.now ?? Date.now(), skew = Math.min(Math.max(Number(r.clock_skew_s) || 0, 0), MAX_CLOCK_SKEW_S) * 1000;
     const at = Date.parse(r.decided_at), exp = Date.parse(r.expires_at);
     if (!isFinite(at) || !isFinite(exp))
         why.push("decided_at or expires_at missing");
     else {
-        if (now > exp + skew)
+        f.times_present = true;
+        f.not_expired = !(now > exp + skew);
+        if (!f.not_expired)
             why.push("expired at " + r.expires_at);
-        if (at > now + skew)
+        f.not_future = !(at > now + skew);
+        if (!f.not_future)
             why.push("decided in the future (" + r.decided_at + "): check the clock");
         const max = ACTION_MAX_LIFETIME_S[String(want.action)];
         if (max === undefined)
             why.push("unknown action " + want.action);
-        else if (exp - at > max * 1000 + 1000)
-            why.push("valid for " + Math.round((exp - at) / 1000) + " s; a " + want.action + " receipt may last at most " + max + " s");
+        else {
+            f.lifetime_ok = !(exp - at > max * 1000 + 1000);
+            if (!f.lifetime_ok)
+                why.push("valid for " + Math.round((exp - at) / 1000) + " s; a " + want.action + " receipt may last at most " + max + " s");
+        }
     }
-    if (DECISIONS.indexOf(r.decision) < 0)
+    f.decision_known = DECISIONS.indexOf(r.decision) >= 0;
+    if (!f.decision_known)
         why.push("unknown decision " + r.decision);
-    if (!r.resolve || !/^[0-9a-f]{64}$/.test(String(r.resolve.sha256 || "")))
+    f.resolve_bound = !!(r.resolve && /^[0-9a-f]{64}$/.test(String(r.resolve.sha256 || "")));
+    if (!f.resolve_bound)
         why.push("the receipt names no resolve answer");
-    return { ok: why.length === 0, why };
+    return { ok: why.length === 0, why, fields: f };
 }
 export const LOG_ID = L.LOG_ID;
 /** A new, empty transparency-log store (plain JSON: persist it between runs). */
@@ -347,7 +390,8 @@ export class CrawlCheck {
      */
     async guard(domain, action = "read", opts = {}) {
         const nonce = opts.nonce || randomNonce();
-        const no = (why, receipt = null, verification = null) => ({ proceed: false, receipt, verification, header: null, why });
+        let scope = null;
+        const no = (why, receipt = null, verification = null) => ({ proceed: false, receipt, verification, header: null, why, acceptance: receipt && scope ? acceptanceOf(receipt, verification, scope, { allowWarn: !!opts.allowWarn }) : null });
         const rv = revokedFor(this.revocations, normalizeDomain(domain) || domain, action); // rvd1: refused offline, before any request
         if (rv)
             return Object.assign(no([rv.domain + " is on CrawlCheck's signed revocation list for " + action + " (" + (rv.causes.join(", ") || rv.state || "revoked") + (rv.since ? ", since " + rv.since : "") + "; list of " + this.revocations.generated_at + ")"]), { revoked: rv });
@@ -360,7 +404,7 @@ export class CrawlCheck {
         }
         if (this.log.forks.length)
             return Object.assign(no(["the transparency log has shown this client two histories (split view)"], receipt), { split_view: this.log.forks.slice() });
-        const scope = checkDecision(receipt, { domain, action, nonce, now: opts.now, operation: opts.operation });
+        scope = checkDecision(receipt, { domain, action, nonce, now: opts.now, operation: opts.operation });
         if (!receipt || typeof receipt !== "object")
             return no(scope.why);
         const online = opts.onlineKeys ?? true;
@@ -386,20 +430,21 @@ export class CrawlCheck {
         if (why.length)
             return no(why, receipt, verification);
         const d = receipt.decision;
-        let proceed = d === "allow" || (d === "warn" && !!opts.allowWarn);
+        let proceed = d === "allow" || (d === "warn" && !!opts.allowWarn), confirmed = null;
         if (d === "require_confirmation") {
             if (opts.confirm) {
                 try {
-                    proceed = (await opts.confirm(receipt)) === true;
+                    proceed = confirmed = (await opts.confirm(receipt)) === true;
                 }
                 catch {
-                    proceed = false;
+                    proceed = confirmed = false;
                 }
             }
         }
         if (!proceed)
             why.push(d === "warn" ? "decision is warn and allowWarn is not set" : d === "require_confirmation" ? (opts.confirm ? "a human did not confirm" : "decision is require_confirmation and no confirm() was given") : "decision is " + d);
-        return { proceed, receipt, verification, header: proceed ? receiptHeader(receipt) : null, why };
+        const acceptance = acceptanceOf(receipt, verification, scope, { allowWarn: !!opts.allowWarn, confirmed });
+        return { proceed: proceed && acceptance.accepted, receipt, verification, header: proceed && acceptance.accepted ? receiptHeader(receipt) : null, why, acceptance };
     }
     /**
      * fetch() with the check where the action runs: guard() before the first request, and again before every redirect hop