@crawlcheck/sdk 1.4.0 → 1.5.0

package/README.md

@@ -50,6 +50,27 @@ v.decisions.transact;  // allow | warn | require_confirmation | block | unsuppor
 
 `stapleCheck(record, { host, publishedKids })` does the offline check on its own. Spec: https://crawlcheck.io/spec/staple
 
+## Hold the revocation list offline
+
+CrawlCheck signs a list of domains whose connect or transact decision is block now: an owner-declared incident, a suspected impersonation of a top-10,000 brand, or an unconfirmed change to a payment, checkout, wallet, login, mail or MCP field. `syncRevocations()` fetches it (a `?since=` delta after the first sync), checks the signature and the published key, and applies it. From then on `guard()` refuses a listed domain for a listed action with no request at all, so it keeps working with the network cut:
+
+```js
+import fs from "node:fs";
+import { CrawlCheck, newRevocationStore } from "@crawlcheck/sdk";
+const store = fs.existsSync("cc-revocations.json") ? JSON.parse(fs.readFileSync("cc-revocations.json", "utf8")) : newRevocationStore();
+const client = new CrawlCheck({ revocationStore: store });
+await client.syncRevocations();                 // every poll_seconds (60), and before going offline
+fs.writeFileSync("cc-revocations.json", JSON.stringify(client.revocations));
+const g = await client.guard("pay.example.com", "transact");
+g.revoked;                                      // set when the held list refused it: { domain, actions, causes, since }
+```
+
+`revokedFor(store, domain, action)` is the same check on its own. Reading and citing are never revoked by this list.
+
+## Look up without naming the domain
+
+`new CrawlCheck({ privateLookups: true })` makes `resolve()` and `resolveFor()` send only the first 2 hex characters of sha256(domain); the signed answer is picked out of the bucket and verified locally. A domain CrawlCheck has never measured raises a 404 instead of a just-in-time answer, because making one would name it. `preflight()` and `guard()` still send the domain: a receipt is bound to it.
+
 ## Preflight inside your MCP client
 
 Wrap the official MCP client so `connect` and `callTool` are decided before anything is sent ([proposal](https://crawlcheck.io/spec/mcp-preflight)):

package/dist/index.d.ts

@@ -265,7 +265,8 @@ export interface GuardResult {
     verification: (DocumentVerification & Trust) | null;
     header: Record<string, string> | null;
     why: string[];
-    split_view?: LogFork[];
+    split_view?: LogFork[]; /** Set when the domain was refused from the held revocation list, with no network call. */
+    revoked?: RevokedEntry;
 }
 export interface GuardedFetchOptions extends GuardOptions {
     action?: Action;
@@ -421,6 +422,46 @@ export declare const stapleCheck: (record: string, opts: {
     publishedKids: string[];
     now?: number;
 }) => Promise<StapleCheck>;
+export interface RevokedEntry {
+    domain?: string;
+    actions: string[];
+    causes: string[];
+    state: string | null;
+    since: string | null;
+    updated_at: string | null;
+}
+/** The signed revocation list held locally (plain JSON: persist it between runs). */
+export interface RevocationStore {
+    v: 1;
+    generated_at: string | null;
+    seq: string | null;
+    synced_at: string | null;
+    revoked: Record<string, RevokedEntry>;
+}
+export interface RevocationSync {
+    applied: boolean;
+    full: boolean;
+    added: number;
+    removed: number;
+    reason: string | null;
+    total: number;
+    generated_at: string | null;
+    verification?: DocumentVerification & Trust;
+}
+/** A new, empty revocation store. */
+export declare const newRevocationStore: () => RevocationStore;
+/** Apply a VERIFIED crawlcheck-revocations document (full list or ?since= delta) to a store. */
+export declare const applyRevocations: (store: RevocationStore, doc: unknown, now?: number) => {
+    applied: boolean;
+    full: boolean;
+    added: number;
+    removed: number;
+    reason: string | null;
+};
+/** The entry that revokes this domain (or a parent domain) for this action, or null. Offline. */
+export declare const revokedFor: (store: RevocationStore, domain: string, action?: string) => (RevokedEntry & {
+    domain: string;
+}) | null;
 export interface McpPreflightOptions extends PreflightOptions {
     /** Proceed on warn too (default false). */
     allowWarn?: boolean;
@@ -497,6 +538,10 @@ export interface ClientOptions {
     headers?: Record<string, string>;
     /** Transparency-log store (newLogStore()). Every Resolve answer's signed tree head is checked against it; keep it across runs to catch a split view. Default: a fresh in-memory store. */
     logStore?: LogStore;
+    /** Revocation store (newRevocationStore()). syncRevocations() fills it; guard() refuses a listed domain for a listed action without a network call. Default: a fresh, empty store. */
+    revocationStore?: RevocationStore;
+    /** Private mode: resolve() and resolveFor() send only a 2-hex prefix of sha256(domain) (resolvePrivate), never the domain. A domain with no public measurement then raises a 404 CrawlCheckError instead of a just-in-time answer, which would name it. preflight() and guard() still name the domain: a receipt is bound to it. */
+    privateLookups?: boolean;
 }
 export declare class CrawlCheckError extends Error {
     readonly status: number;
@@ -520,6 +565,10 @@ export declare class CrawlCheck {
     private readonly extra;
     /** The transparency-log store this client checks every signed tree head against. Persist it (JSON) between runs. */
     readonly log: LogStore;
+    /** The signed revocation list this client holds. Persist it (JSON) between runs; syncRevocations() keeps it current. */
+    readonly revocations: RevocationStore;
+    /** Private mode (ClientOptions.privateLookups). */
+    readonly privateLookups: boolean;
     constructor(opts?: ClientOptions);
     /** Any documented GET, typed from the OpenAPI document: client.get("/api/explain", { domain: "example.com" }). */
     get<P extends keyof paths>(path: P, query?: QueryOf<P, "get">): Promise<ResponseOf<P, "get">>;
@@ -560,6 +609,14 @@ export declare class CrawlCheck {
             sha256: string;
         })[];
     }>;
+    /**
+     * Fetch the signed revocation list (a ?since= delta when the store already holds one), verify it (integrity and a
+     * published signing key) and apply it. A delta that no longer reaches back is replaced by the full list. Nothing is
+     * applied from a document that does not verify. Call it on a timer (poll_seconds, 60) and before going offline.
+     */
+    syncRevocations(opts?: {
+        full?: boolean;
+    }): Promise<RevocationSync>;
     /** The policy engine: a signed decision receipt (allow | warn | require_confirmation | block | unsupported). A policy can only make the decision stricter. */
     preflight(domain: string, action?: Action, opts?: PreflightOptions): Promise<DecisionReceipt>;
     /** Verify a signed document here. With onlineKeys (default), its signing key must also be in the published directory. */

package/dist/index.js

@@ -2,6 +2,7 @@ import * as V from "./verify.js";
 import * as L from "./log.js";
 import * as S from "./staple.js";
 import * as M from "./mcp.js";
+import * as R from "./revocations.js";
 function withTrust(v, kid, published, related = []) {
     let checks = v.checks;
     let issuer = null;
@@ -136,6 +137,12 @@ export const parseStaple = S.parseStaple;
 export const stapleFromResponse = S.stapleFromResponse;
 /** Verify a staple offline: published key, signature, the record names opts.host (or a parent), fresh_until in the future. Expired or foreign staples are never valid. */
 export const stapleCheck = S.stapleCheck;
+/** A new, empty revocation store. */
+export const newRevocationStore = R.newRevocationStore;
+/** Apply a VERIFIED crawlcheck-revocations document (full list or ?since= delta) to a store. */
+export const applyRevocations = R.applyRevocations;
+/** The entry that revokes this domain (or a parent domain) for this action, or null. Offline. */
+export const revokedFor = R.revokedFor;
 /** Thrown by the hooks when a connect or tools/call is refused; the request was never sent. */
 export const McpPreflightRefused = M.McpPreflightRefused;
 /** The two hooks (beforeConnect, beforeToolCall) plus afterConnect for lockfiles, for any MCP client stack. */
@@ -166,11 +173,17 @@ export class CrawlCheck {
     extra;
     /** The transparency-log store this client checks every signed tree head against. Persist it (JSON) between runs. */
     log;
+    /** The signed revocation list this client holds. Persist it (JSON) between runs; syncRevocations() keeps it current. */
+    revocations;
+    /** Private mode (ClientOptions.privateLookups). */
+    privateLookups;
     constructor(opts = {}) {
         this.base = (opts.base ?? "https://crawlcheck.io").replace(/\/+$/, "");
         this.key = opts.key;
         this.extra = opts.headers ?? {};
         this.log = opts.logStore ?? newLogStore();
+        this.revocations = opts.revocationStore ?? newRevocationStore();
+        this.privateLookups = !!opts.privateLookups;
         const f = opts.fetch ?? globalThis.fetch;
         if (typeof f !== "function")
             throw new Error("no fetch available: pass { fetch } (Node 18+ and every browser have one)");
@@ -187,6 +200,17 @@ export class CrawlCheck {
     // ── read before acting ──
     /** The signed ResolveV1 answer: crawl policy, delivery, machine files, capabilities, entity, findings, freshness and a decision per action. */
     async resolve(domain) {
+        if (this.privateLookups) { // pfx2: only the hash prefix leaves this process
+            const p = await this.resolvePrivate(domain);
+            if (!p.ready)
+                throw new CrawlCheckError(503, "/api/v1/resolve-prefix", { error: p.why || "the prefix index is not built yet" });
+            if (!p.found)
+                throw new CrawlCheckError(404, "/api/v1/resolve-prefix", { error: "CrawlCheck holds no public measurement of " + domain + "; in private mode the domain is never sent, so no just-in-time answer is made" });
+            if (!p.accepted)
+                throw new CrawlCheckError(502, "/api/v1/resolve-prefix", { error: "the answer in the bucket did not verify: " + (p.verification ? p.verification.summary : "no verification") });
+            await logObserveAnswer(this.log, p.answer).catch(() => null);
+            return p.answer;
+        }
         const a = await this.get("/api/v1/resolve", { domain });
         await logObserveAnswer(this.log, a).catch(() => null); // a head that contradicts one this client already holds is recorded in this.log.forks
         return a;
@@ -242,6 +266,29 @@ export class CrawlCheck {
     }
     /** Check heads another client sent (logHeads on their side) against this client's store. */
     logGossip(sths) { return logGossip(this.log, sths); }
+    /**
+     * Fetch the signed revocation list (a ?since= delta when the store already holds one), verify it (integrity and a
+     * published signing key) and apply it. A delta that no longer reaches back is replaced by the full list. Nothing is
+     * applied from a document that does not verify. Call it on a timer (poll_seconds, 60) and before going offline.
+     */
+    async syncRevocations(opts = {}) {
+        const st = this.revocations;
+        const get = async (since) => (await this.req("GET", "/api/v1/revocations", since ? { since } : undefined));
+        let doc = await get(opts.full || !st.generated_at ? null : st.generated_at);
+        const verify = async (d) => this.verifyDocument(d, true);
+        let v = await verify(doc);
+        if (!v.accepted)
+            return { applied: false, full: false, added: 0, removed: 0, reason: "the revocation list did not verify: " + v.summary, total: Object.keys(st.revoked).length, generated_at: st.generated_at, verification: v };
+        let r = applyRevocations(st, doc);
+        if (!r.applied && doc && doc.since) {
+            doc = await get(null);
+            v = await verify(doc);
+            if (!v.accepted)
+                return { applied: false, full: true, added: 0, removed: 0, reason: "the full revocation list did not verify: " + v.summary, total: Object.keys(st.revoked).length, generated_at: st.generated_at, verification: v };
+            r = applyRevocations(st, doc);
+        }
+        return Object.assign({}, r, { total: Object.keys(st.revoked).length, generated_at: st.generated_at, verification: v });
+    }
     /** The policy engine: a signed decision receipt (allow | warn | require_confirmation | block | unsupported). A policy can only make the decision stricter. */
     async preflight(domain, action = "read", opts = {}) {
         const b = { domain, action };
@@ -270,6 +317,9 @@ 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 });
+        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 });
         let receipt;
         try {
             receipt = await this.preflight(domain, action, Object.assign({}, opts, { nonce }));

package/dist/revocations.d.ts

@@ -0,0 +1,25 @@
+/** An empty store. */
+export function newRevocationStore(): {
+    v: number;
+    generated_at: null;
+    seq: null;
+    synced_at: null;
+    revoked: {};
+};
+/**
+ * Apply a verified crawlcheck-revocations document. A full list (since null) replaces the store; a delta replaces each
+ * revoked entry it carries and removes each cleared or lifted one. A delta that is not complete (delta_complete false),
+ * or one older than the store, is refused: fetch the full list instead. Returns { applied, full, added, removed, reason }.
+ */
+export function applyRevocations(store: any, doc: any, now: any): {
+    applied: boolean;
+    full: boolean;
+    added: number;
+    removed: number;
+    reason: null;
+};
+/**
+ * Is this domain (or a parent domain) revoked for this action in the store? Returns the entry with the domain that
+ * matched, or null. Reading and citing are never revoked by this list.
+ */
+export function revokedFor(store: any, domain: any, action: any): any;

package/dist/revocations.js

@@ -0,0 +1,75 @@
+// Offline revocations (rvd1): hold CrawlCheck's signed revocation list and refuse a listed domain for a listed action
+// with no network call. A store is plain JSON; persist it between runs. Only a document whose signature was checked
+// should be applied (the client's syncRevocations does that). https://crawlcheck.io/docs/api#revocations
+/** An empty store. */
+export function newRevocationStore() { return { v: 1, generated_at: null, seq: null, synced_at: null, revoked: {} }; }
+function norm(d) { return String(d || "").toLowerCase().trim().replace(/\.$/, "").replace(/^www\./, ""); }
+/**
+ * Apply a verified crawlcheck-revocations document. A full list (since null) replaces the store; a delta replaces each
+ * revoked entry it carries and removes each cleared or lifted one. A delta that is not complete (delta_complete false),
+ * or one older than the store, is refused: fetch the full list instead. Returns { applied, full, added, removed, reason }.
+ */
+export function applyRevocations(store, doc, now) {
+    const out = { applied: false, full: false, added: 0, removed: 0, reason: null };
+    if (!store || store.v !== 1) {
+        out.reason = "not a revocation store (newRevocationStore())";
+        return out;
+    }
+    if (!doc || doc.kind !== "crawlcheck-revocations" || !Array.isArray(doc.revoked)) {
+        out.reason = "not a crawlcheck-revocations document";
+        return out;
+    }
+    if (store.generated_at && doc.generated_at && Date.parse(doc.generated_at) < Date.parse(store.generated_at)) {
+        out.reason = "older than the list already held";
+        return out;
+    }
+    const full = !doc.since;
+    if (!full && doc.delta_complete === false) {
+        out.reason = "the delta does not reach back to " + doc.since + ": fetch the full list";
+        return out;
+    }
+    if (!full && store.generated_at && Date.parse(doc.since) > Date.parse(store.generated_at)) {
+        out.reason = "the delta starts after the list held (" + store.generated_at + "): fetch the full list";
+        return out;
+    }
+    const next = full ? {} : Object.assign({}, store.revoked);
+    for (const l of doc.cleared || []) {
+        const d = norm(l && l.domain);
+        if (d && next[d]) {
+            delete next[d];
+            out.removed++;
+        }
+    }
+    for (const e of doc.revoked) {
+        const d = norm(e && e.domain);
+        if (!d || !Array.isArray(e.actions))
+            continue;
+        if (!next[d])
+            out.added++;
+        next[d] = { actions: e.actions.slice(), causes: Array.isArray(e.causes) ? e.causes.slice() : [], state: e.state || null, since: e.since || null, updated_at: e.updated_at || null };
+    }
+    if (full)
+        out.removed = Math.max(0, Object.keys(store.revoked).filter((d) => !next[d]).length);
+    store.revoked = next;
+    store.generated_at = doc.generated_at || null;
+    store.seq = doc.seq != null ? String(doc.seq) : null;
+    store.synced_at = new Date(now || Date.now()).toISOString();
+    out.applied = true;
+    out.full = full;
+    return out;
+}
+/**
+ * Is this domain (or a parent domain) revoked for this action in the store? Returns the entry with the domain that
+ * matched, or null. Reading and citing are never revoked by this list.
+ */
+export function revokedFor(store, domain, action) {
+    if (!store || !store.revoked)
+        return null;
+    const labels = norm(domain).split(".");
+    for (let i = 0; i < labels.length - 1; i++) {
+        const d = labels.slice(i).join("."), e = store.revoked[d];
+        if (e && (!action || e.actions.indexOf(action) >= 0))
+            return Object.assign({ domain: d }, e);
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crawlcheck/sdk",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Typed client for the CrawlCheck API (generated from its OpenAPI document) and the zero-dependency offline verifier for evidence bundles and remediation receipts.",
   "type": "module",
   "main": "./dist/index.js",

package/test/fixtures/revocations.json

@@ -0,0 +1,483 @@
+{
+ "note": "made by the Worker's own code in a test harness with a throwaway key (rvd1)",
+ "full": {
+  "kind": "crawlcheck-revocations",
+  "v": 1,
+  "generated_at": "2026-10-11T13:14:55.824Z",
+  "seq": "0.1",
+  "since": null,
+  "revoked": [
+   {
+    "domain": "shop.example",
+    "state": "automated",
+    "actions": [
+     "transact"
+    ],
+    "decision": "block",
+    "causes": [
+     "high_risk_field_changed"
+    ],
+    "since": "2026-10-11T13:14:55.703Z",
+    "updated_at": "2026-10-11T13:14:55.703Z",
+    "observed_at": "2026-10-11T13:14:55.702Z",
+    "detail": {
+     "high_risk_field_changed": {
+      "fields": [
+       "checkout_host"
+      ],
+      "changed_at": "2026-10-11T12:14:55.702Z",
+      "block_lifts_by": "2026-10-18T12:14:55.702Z"
+     }
+    },
+    "check": "https://crawlcheck.io/api/v1/resolve?domain=shop.example"
+   },
+   {
+    "domain": "xn--pple-43d.com",
+    "state": "automated",
+    "actions": [
+     "connect",
+     "transact"
+    ],
+    "decision": "block",
+    "causes": [
+     "impersonation_suspected"
+    ],
+    "since": "2026-10-11T13:14:55.703Z",
+    "updated_at": "2026-10-11T13:14:55.703Z",
+    "observed_at": "2026-10-11T13:14:55.702Z",
+    "detail": {
+     "impersonation_suspected": {
+      "brand": "apple.com",
+      "technique": "idn_homoglyph"
+     }
+    },
+    "check": "https://crawlcheck.io/api/v1/resolve?domain=xn--pple-43d.com"
+   }
+  ],
+  "active_total": 2,
+  "cleared": [],
+  "delta_complete": true,
+  "automated_built_at": "2026-10-11T13:14:55.703Z",
+  "by_cause": {
+   "high_risk_field_changed": 1,
+   "impersonation_suspected": 1
+  },
+  "reading": "Domains whose connect or transact decision is block now, for one of three causes: the owner declared an incident (owner_incident), CrawlCheck suspects an impersonation of a top-10,000 brand (impersonation_suspected: connect and transact), or a high-risk field (payment processor, checkout host, wallet, OAuth server, mail host, MCP endpoint) changed and the owner has not confirmed it within 7 days (high_risk_field_changed: transact). Hold this list and refuse those actions offline. With ?since=<generated_at> you get only what was added or changed since (revoked: replace your entry for that domain) and what left the list since (cleared, lifted: remove it); when delta_complete is false the logs no longer reach back that far, so fetch the full list.",
+  "poll_seconds": 60,
+  "rebuilt": "owner incidents within a minute; automated entries every batch window (:02, :32, :47 UTC)",
+  "sdk": "syncRevocations() / sync_revocations() hold it; guard() refuses a listed domain for a listed action with no network call",
+  "code": {
+   "version_id": null,
+   "script_sha16": null,
+   "state": "unknown",
+   "deployed": null,
+   "build_log_entry": null,
+   "score_version": 31,
+   "scoring_policy_sha256": "86898d2a8c88d6b56e6710f3aadf4375cbb5342d4a2f9aa017b536d95602d671",
+   "decision_rules_sha256": "18dd5636e0896692ab518050cb401744edea2e6f1086dff94fead314959bdc3e",
+   "check": "https://crawlcheck.io/api/v1/builds"
+  },
+  "sha256": "13c782666de404f8c170232769a127acbd34d38c250b90c1ac3b6320b01c56b2",
+  "signature": {
+   "v": 1,
+   "alg": "Ed25519",
+   "kid": "m3JoWSDhN2k3t9MQL11mlWNGm5O5JEJ5dE8ekCIP5ss",
+   "over": "sha256",
+   "message": "crawlcheck-data-v1\n13c782666de404f8c170232769a127acbd34d38c250b90c1ac3b6320b01c56b2",
+   "sig": "-kn4YOROgiDc2Fk8eMjSdRB6nG6SlsVsB-6b6xkrsrJFPtsksirHHiin7cJa9RD9If4vDB-9Fn8hkJ65Xr5JCA",
+   "signed_at": "2026-10-11T13:14:55.869Z",
+   "key": {
+    "kid": "m3JoWSDhN2k3t9MQL11mlWNGm5O5JEJ5dE8ekCIP5ss",
+    "jwk": {
+     "kty": "OKP",
+     "crv": "Ed25519",
+     "x": "3MSOmtiA71yc0dqVVi2S6abJYKX65mFsosURtK0B0c0"
+    },
+    "published_in": "https://crawlcheck.io/.well-known/http-message-signatures-directory"
+   },
+   "canonical": "sha256 over canonical JSON of every field except sha256 and signature"
+  }
+ },
+ "delta": {
+  "kind": "crawlcheck-revocations",
+  "v": 1,
+  "generated_at": "2026-10-11T13:14:55.917Z",
+  "seq": "0.2",
+  "since": "2026-10-11T13:14:55.824Z",
+  "revoked": [
+   {
+    "domain": "paypa1.com",
+    "state": "automated",
+    "actions": [
+     "connect",
+     "transact"
+    ],
+    "decision": "block",
+    "causes": [
+     "impersonation_suspected"
+    ],
+    "since": "2026-10-11T13:14:55.915Z",
+    "updated_at": "2026-10-11T13:14:55.915Z",
+    "observed_at": "2026-10-11T13:14:55.914Z",
+    "detail": {
+     "impersonation_suspected": {
+      "brand": "paypal.com",
+      "technique": "character_swap"
+     }
+    },
+    "check": "https://crawlcheck.io/api/v1/resolve?domain=paypa1.com"
+   }
+  ],
+  "active_total": 2,
+  "cleared": [
+   {
+    "domain": "shop.example",
+    "state": "lifted",
+    "causes": [
+     "high_risk_field_changed"
+    ],
+    "actions": [
+     "transact"
+    ],
+    "since": "2026-10-11T13:14:55.703Z",
+    "at": "2026-10-11T13:14:55.915Z",
+    "lifted_at": "2026-10-11T13:14:55.915Z"
+   }
+  ],
+  "delta_complete": true,
+  "automated_built_at": "2026-10-11T13:14:55.915Z",
+  "by_cause": {
+   "impersonation_suspected": 2
+  },
+  "reading": "Domains whose connect or transact decision is block now, for one of three causes: the owner declared an incident (owner_incident), CrawlCheck suspects an impersonation of a top-10,000 brand (impersonation_suspected: connect and transact), or a high-risk field (payment processor, checkout host, wallet, OAuth server, mail host, MCP endpoint) changed and the owner has not confirmed it within 7 days (high_risk_field_changed: transact). Hold this list and refuse those actions offline. With ?since=<generated_at> you get only what was added or changed since (revoked: replace your entry for that domain) and what left the list since (cleared, lifted: remove it); when delta_complete is false the logs no longer reach back that far, so fetch the full list.",
+  "poll_seconds": 60,
+  "rebuilt": "owner incidents within a minute; automated entries every batch window (:02, :32, :47 UTC)",
+  "sdk": "syncRevocations() / sync_revocations() hold it; guard() refuses a listed domain for a listed action with no network call",
+  "code": {
+   "version_id": null,
+   "script_sha16": null,
+   "state": "unknown",
+   "deployed": null,
+   "build_log_entry": null,
+   "score_version": 31,
+   "scoring_policy_sha256": "86898d2a8c88d6b56e6710f3aadf4375cbb5342d4a2f9aa017b536d95602d671",
+   "decision_rules_sha256": "18dd5636e0896692ab518050cb401744edea2e6f1086dff94fead314959bdc3e",
+   "check": "https://crawlcheck.io/api/v1/builds"
+  },
+  "sha256": "1ec217b19ac2ccfebff6cc03a3d0ed8745d77b90ef27698b65b819421c552a76",
+  "signature": {
+   "v": 1,
+   "alg": "Ed25519",
+   "kid": "m3JoWSDhN2k3t9MQL11mlWNGm5O5JEJ5dE8ekCIP5ss",
+   "over": "sha256",
+   "message": "crawlcheck-data-v1\n1ec217b19ac2ccfebff6cc03a3d0ed8745d77b90ef27698b65b819421c552a76",
+   "sig": "dh_oCZPp7-uM1xPVxJLTwOx_Spo5kWxGfZjCnst0OPm6v3-iYG2QnAm9MfwkaH-zxF1tiL0UD_NcJ6Pd2F0vCg",
+   "signed_at": "2026-10-11T13:14:55.918Z",
+   "key": {
+    "kid": "m3JoWSDhN2k3t9MQL11mlWNGm5O5JEJ5dE8ekCIP5ss",
+    "jwk": {
+     "kty": "OKP",
+     "crv": "Ed25519",
+     "x": "3MSOmtiA71yc0dqVVi2S6abJYKX65mFsosURtK0B0c0"
+    },
+    "published_in": "https://crawlcheck.io/.well-known/http-message-signatures-directory"
+   },
+   "canonical": "sha256 over canonical JSON of every field except sha256 and signature"
+  }
+ },
+ "resolve": {
+  "kind": "crawlcheck-resolve",
+  "v": 1,
+  "schema": "https://crawlcheck.io/schemas/resolve.json",
+  "domain": "example-shop.com",
+  "answered_at": "2026-10-11T13:14:55.930Z",
+  "reading": "Each section is declared (what the site says about itself), observed (what CrawlCheck was served) or not_measured, with when it was observed. There is no overall score: decide on the section your action depends on.",
+  "impersonation": {
+   "state": "unread",
+   "why": "the impersonation check could not be read just now (fetch failed)"
+  },
+  "status": "partial",
+  "basis": {
+   "kind": "just_in_time",
+   "measured_at": "2026-10-11T13:14:55.932Z",
+   "budget_ms": 1000,
+   "took_ms": 30,
+   "not_read_in_budget": [],
+   "scope": "read live the moment this domain was first asked about: DNS, the TLS connection, the homepage as a browser and 2 AI identities, robots.txt, the sitemap and 6 machine files, all inside one 1000 ms budget. Anything listed in not_read_in_budget was not read and is not reported absent. No findings, no grade, no capability invoked."
+  },
+  "subject": {
+   "domain": "example-shop.com",
+   "host": "example-shop.com"
+  },
+  "freshness": {
+   "observed_at": "2026-10-11T13:14:55.932Z",
+   "age_hours": 0,
+   "source": "just_in_time",
+   "last_verified_at": "2026-10-11T13:14:55.932Z",
+   "fresh_until": "2026-10-18T13:14:55.932Z",
+   "stale": false,
+   "fresh_policy": "an answer is fresh for 168 hours after observed_at; each action below has its own maximum age. last_verified_at is the latest reading of this domain by any enrolled observer."
+  },
+  "observers": {
+   "primary": {
+    "version_tag": null,
+    "vantage": null
+   },
+   "independent_readings": 0,
+   "by_field": "https://crawlcheck.io/api/corroboration?domain=example-shop.com",
+   "directory": "https://crawlcheck.io/.well-known/crawlcheck-observers.json",
+   "samples_by_network": {
+    "networks": 0,
+    "samples": 0,
+    "groups": [],
+    "window": "the latest 12 independent readings kept for this domain; the primary scan (Cloudflare) is not counted here"
+   }
+  },
+  "crawl_policy": {
+   "state": "not_measured",
+   "observed_at": "2026-10-11T13:14:55.932Z",
+   "why": "robots.txt was not read"
+  },
+  "delivery": {
+   "state": "observed",
+   "observed_at": "2026-10-11T13:14:55.932Z",
+   "url": "https://example-shop.com/",
+   "identity_basis": "every identity was sent by CrawlCheck from its own network; none is the named operator's own crawler",
+   "identities": [
+    {
+     "identity": "browser",
+     "label": "Mobile browser",
+     "status": null,
+     "bytes": null,
+     "html": false,
+     "final_host": null,
+     "sha256": null
+    },
+    {
+     "identity": "gptbot",
+     "label": "GPTBot",
+     "status": null,
+     "bytes": null,
+     "html": false,
+     "final_host": null,
+     "sha256": null
+    },
+    {
+     "identity": "claudebot",
+     "label": "ClaudeBot",
+     "status": null,
+     "bytes": null,
+     "html": false,
+     "final_host": null,
+     "sha256": null
+    }
+   ],
+   "same_bytes_for_every_identity": false
+  },
+  "machine_files": {
+   "state": "not_measured",
+   "observed_at": "2026-10-11T13:14:55.932Z",
+   "why": "no machine file was read"
+  },
+  "capabilities": {
+   "state": "observed",
+   "observed_at": "2026-10-11T13:14:55.932Z",
+   "declared": 0,
+   "by_safety_class": {},
+   "verified": 0,
+   "mismatches": 0,
+   "invocation_rule": "capabilities are read from declarations only; nothing is invoked. Later verification may call read_only_public operations alone; every other class needs the site owner's authorisation and a test account, and unknown is never called",
+   "certificate": null,
+   "items": null,
+   "declared_files": [],
+   "note": "the census records whether a capability file is present; nothing was invoked or verified. A full scan verifies declared capabilities."
+  },
+  "entity": {
+   "state": "not_measured",
+   "observed_at": "2026-10-11T13:14:55.932Z",
+   "why": "the census carries no entity reading"
+  },
+  "findings": {
+   "access": "public",
+   "rule": null,
+   "items": [],
+   "summary": null,
+   "withheld": null,
+   "note": "a census record carries readings, not findings"
+  },
+  "confidence": {
+   "identities_answered": 0,
+   "vantages": 1,
+   "note": "one vantage, one pass, read under a time budget"
+  },
+  "contradictions": null,
+  "evidence": {
+   "scan": "POST https://crawlcheck.io/api/scan {\"domain\":\"example-shop.com\"}",
+   "offline_verifier": "https://crawlcheck.io/crawlcheck-verify.mjs?v=454ff4ba84bef41b",
+   "verify_this_answer": "save it as answer.json, then: node crawlcheck-verify.mjs answer.json"
+  },
+  "assurance": "degraded",
+  "dns": {
+   "state": "not_measured",
+   "observed_at": "2026-10-11T13:14:55.932Z",
+   "why": "the DNS lookup did not answer within the budget (fetch failed)"
+  },
+  "tls": {
+   "state": "observed",
+   "observed_at": "2026-10-11T13:14:55.932Z",
+   "https": false,
+   "url": "https://example-shop.com/",
+   "error": "fetch failed",
+   "certificate": "the HTTPS connection failed: fetch failed"
+  },
+  "upgrade": {
+   "state": "queued",
+   "to": "full",
+   "expected": "at the next cron window (:02, :17, :32 or :47 UTC), usually within 30 minutes",
+   "how": "a full scan is queued; when it lands this answer is replaced and the change appears on https://crawlcheck.io/api/v1/changes?domain=example-shop.com as section assurance, partial → full",
+   "scan_now": "POST https://crawlcheck.io/api/scan {\"domain\":\"example-shop.com\"}"
+  },
+  "actions": {
+   "v": 1,
+   "decisions": "allow | warn | require_confirmation | block | unsupported",
+   "rule": "decided from this answer's own sections at signing time; an agent's own policy may be stricter, never looser. This is a partial (just-in-time) answer: only what it read live counts, so cite, connect and transact cannot reach their assurance until the full scan lands",
+   "read": {
+    "decision": "warn",
+    "minimum_assurance": "reachable",
+    "assurance_found": [],
+    "needs": "robots.txt lets AI agents read the path, and the page was served to at least one AI-crawler identity",
+    "why": "no robots.txt policy was read, so permission is unknown; the impersonation check could not be read",
+    "doubts": [
+     "no_policy",
+     "impersonation_unread"
+    ],
+    "max_age_hours": 168
+   },
+   "cite": {
+    "decision": "warn",
+    "minimum_assurance": "reachable + entity observed",
+    "assurance_found": [],
+    "needs": "everything read needs, plus an observed entity and no contradiction the site makes with itself",
+    "scope": {
+     "covers": [
+      "access: robots.txt and what was actually served to AI-crawler identities",
+      "permissions: the rights and content signals the site declares",
+      "identity: the entity the site declares and who has proven control of the domain",
+      "provenance: when, from where and by whom it was observed, signed and logged"
+     ],
+     "does_not_cover": "whether the content is true, accurate, current or complete; a cite decision says the source may be cited and attributed, not that what it says is right"
+    },
+    "why": "no robots.txt policy was read, so permission is unknown; the publisher's identity was not observed, so attribution is unconfirmed; the impersonation check could not be read",
+    "doubts": [
+     "no_policy",
+     "entity_unobserved",
+     "read_equivalence_unmeasured",
+     "impersonation_unread"
+    ],
+    "max_age_hours": 168
+   },
+   "connect": {
+    "decision": "unsupported",
+    "minimum_assurance": "conformant",
+    "assurance_found": [],
+    "needs": "a declared capability that CrawlCheck invoked read-only and found to behave as declared",
+    "why": "the site declares no capability to connect to",
+    "doubts": [],
+    "max_age_hours": 72
+   },
+   "transact": {
+    "decision": "require_confirmation",
+    "minimum_assurance": "action_ready",
+    "assurance_found": [],
+    "needs": "owner-verified identity and an action-ready capability; CrawlCheck does not certify transactions, so a human confirms",
+    "why": "CrawlCheck does not certify transactions; a human confirms every financial, identity or irreversible action; the impersonation check could not be read",
+    "doubts": [
+     "impersonation_unread"
+    ],
+    "max_age_hours": 24
+   },
+   "administer": {
+    "decision": "block",
+    "minimum_assurance": "never automatic",
+    "assurance_found": [],
+    "needs": "high-privilege operations are never authorised by a public record",
+    "why": "never authorised by a public record",
+    "doubts": [],
+    "max_age_hours": 0
+   }
+  },
+  "absences": [],
+  "control": {
+   "state": "unproven",
+   "proofs": [],
+   "organization": null,
+   "claim": "https://crawlcheck.io/registry/example-shop.com/claim",
+   "why": "nobody has proven control of example-shop.com to CrawlCheck, so who stands behind the site is unconfirmed",
+   "note": "control says who answers for the domain, not whether it is safe; it does not change any decision in this answer"
+  },
+  "transparency": {
+   "state": "pending",
+   "log_id": "crawlcheck-resolve-log-v1",
+   "leaf_hash": "b9d19de859df75cf0147379e15a08fdf227082104a4198073150d9d15a0f079b",
+   "queued_at": "2026-10-11T13:14:55.965Z",
+   "merged_within_minutes": 30,
+   "proof": "https://crawlcheck.io/api/v1/log/proof?leaf=b9d19de859df75cf0147379e15a08fdf227082104a4198073150d9d15a0f079b"
+  },
+  "degraded": {
+   "sources": [
+    {
+     "source": "impersonation",
+     "why": "the impersonation check could not be read just now (fetch failed)"
+    }
+   ],
+   "reading": "These sources could not be read when this answer was made. Everything else in it was read as usual; each action that depends on a missing source is decided by the failure policy (fail closed where the missing source could hold a block). Ask again shortly for a complete answer.",
+   "policy": "https://crawlcheck.io/spec/failure-policy",
+   "policy_v": 1
+  },
+  "code": {
+   "version_id": null,
+   "script_sha16": null,
+   "state": "unknown",
+   "deployed": null,
+   "build_log_entry": null,
+   "score_version": 31,
+   "scoring_policy_sha256": "86898d2a8c88d6b56e6710f3aadf4375cbb5342d4a2f9aa017b536d95602d671",
+   "decision_rules_sha256": "18dd5636e0896692ab518050cb401744edea2e6f1086dff94fead314959bdc3e",
+   "check": "https://crawlcheck.io/api/v1/builds"
+  },
+  "sha256": "dec5472e7a7c0445fe70b3b0232807cb9cb87effc1d20f1275a981b70607403d",
+  "signature": {
+   "v": 1,
+   "alg": "Ed25519",
+   "kid": "m3JoWSDhN2k3t9MQL11mlWNGm5O5JEJ5dE8ekCIP5ss",
+   "over": "sha256",
+   "message": "crawlcheck-data-v1\ndec5472e7a7c0445fe70b3b0232807cb9cb87effc1d20f1275a981b70607403d",
+   "sig": "0Q1u0ObSS2AzsH0O_enyJQfFK8XrXXUf4xZet1RHuUKF91p3ImkQd7G81LCF8BgfUxFTQd4_Rhibt5RUJq_GAw",
+   "signed_at": "2026-10-11T13:14:55.966Z",
+   "key": {
+    "kid": "m3JoWSDhN2k3t9MQL11mlWNGm5O5JEJ5dE8ekCIP5ss",
+    "jwk": {
+     "kty": "OKP",
+     "crv": "Ed25519",
+     "x": "3MSOmtiA71yc0dqVVi2S6abJYKX65mFsosURtK0B0c0"
+    },
+    "published_in": "https://crawlcheck.io/.well-known/http-message-signatures-directory"
+   },
+   "canonical": "sha256 over canonical JSON of every field except sha256 and signature"
+  }
+ },
+ "directory": {
+  "keys": [
+   {
+    "kty": "OKP",
+    "crv": "Ed25519",
+    "x": "3MSOmtiA71yc0dqVVi2S6abJYKX65mFsosURtK0B0c0",
+    "kid": "m3JoWSDhN2k3t9MQL11mlWNGm5O5JEJ5dE8ekCIP5ss",
+    "use": "sig",
+    "alg": "EdDSA",
+    "crawlcheck_purpose": "requests and documents",
+    "nbf": 1791724495
+   }
+  ]
+ }
+}

package/test/revocations.test.js

@@ -0,0 +1,77 @@
+// Offline revocations (rvd1): the client syncs the signed list and its ?since= delta, and guard() refuses a listed
+// domain for a listed action with the network cut. Fixtures are signed by the Worker's own code with a throwaway key.
+import test from "node:test"; import assert from "node:assert/strict"; import fs from "node:fs";
+import { CrawlCheck, newRevocationStore, applyRevocations, revokedFor } from "../dist/index.js";
+const F = JSON.parse(fs.readFileSync(new URL("./fixtures/revocations.json", import.meta.url), "utf8"));
+
+function fakeFetch(state) {
+  return async (u) => {
+    const url = new URL(String(u));
+    if (state.cut) throw new TypeError("fetch failed (network cut)");
+    state.calls.push(url.pathname + url.search);
+    const body = url.pathname === "/.well-known/http-message-signatures-directory" ? F.directory
+      : url.pathname === "/api/v1/revocations" ? (url.searchParams.get("since") ? (state.delta || F.delta) : F.full) : null;
+    return new Response(body ? JSON.stringify(body) : "{}", { status: body ? 200 : 404, headers: { "content-type": "application/json" } });
+  };
+}
+
+test("sync: the full list, then the delta (added, lifted), then guard refuses offline", async () => {
+  const state = { calls: [], cut: false };
+  const cc = new CrawlCheck({ fetch: fakeFetch(state) });
+  const a = await cc.syncRevocations();
+  assert.equal(a.applied, true, a.reason); assert.equal(a.full, true); assert.equal(a.total, 2);
+  assert.ok(revokedFor(cc.revocations, "shop.example", "transact"));
+  assert.equal(revokedFor(cc.revocations, "shop.example", "connect"), null, "a high-risk field change revokes transact only");
+  const b = await cc.syncRevocations();
+  assert.equal(b.applied, true, b.reason); assert.equal(b.full, false); assert.equal(b.added, 1); assert.equal(b.removed, 1);
+  assert.ok(state.calls.some((c) => c.startsWith("/api/v1/revocations?since=")), "the second sync asked for a delta");
+  assert.equal(revokedFor(cc.revocations, "shop.example", "transact"), null, "lifted");
+  assert.ok(revokedFor(cc.revocations, "paypa1.com", "connect"));
+  state.cut = true; const n = state.calls.length;
+  const g = await cc.guard("checkout.paypa1.com", "transact");
+  assert.equal(g.proceed, false); assert.equal(g.revoked.domain, "paypa1.com"); assert.match(g.why[0], /revocation list/);
+  const g2 = await cc.guard("xn--pple-43d.com", "connect");
+  assert.equal(g2.proceed, false); assert.deepEqual(g2.revoked.causes, ["impersonation_suspected"]);
+  assert.equal(state.calls.length, n, "no request was made for a revoked domain");
+  const g3 = await cc.guard("paypa1.com", "read");
+  assert.equal(g3.proceed, false); assert.equal(g3.revoked, undefined, "read is never revoked by the list; with the network cut guard still fails closed");
+});
+
+test("a tampered list is never applied", async () => {
+  const bad = JSON.parse(JSON.stringify(F.full)); bad.revoked = [];
+  const state = { calls: [], cut: false };
+  const cc = new CrawlCheck({ fetch: async (u) => { const p = new URL(String(u)).pathname; return new Response(JSON.stringify(p === "/api/v1/revocations" ? bad : F.directory), { status: 200 }); } });
+  const r = await cc.syncRevocations();
+  assert.equal(r.applied, false); assert.match(r.reason, /did not verify/); assert.equal(r.total, 0);
+});
+
+test("a delta that does not reach back is refused; a store persists as JSON", () => {
+  const st = newRevocationStore();
+  assert.equal(applyRevocations(st, F.full).applied, true);
+  const copy = JSON.parse(JSON.stringify(st));
+  assert.ok(revokedFor(copy, "www.shop.example", "transact"), "parent-domain and www match");
+  const inc = Object.assign({}, F.delta, { delta_complete: false });
+  assert.equal(applyRevocations(copy, inc).applied, false);
+  const late = Object.assign({}, F.delta, { since: "2999-01-01T00:00:00.000Z", generated_at: "2999-01-02T00:00:00.000Z" });
+  assert.match(applyRevocations(copy, late).reason, /starts after/);
+  const old = Object.assign({}, F.full, { generated_at: "2000-01-01T00:00:00.000Z" });
+  assert.match(applyRevocations(copy, old).reason, /older/);
+});
+
+test("private mode: resolve sends only a hash prefix, verifies the bucket's answer, and never names the domain", async () => {
+  const crypto = await import("node:crypto");
+  const h = crypto.createHash("sha256").update("example-shop.com").digest("hex");
+  const calls = [];
+  const bucket = { kind: "crawlcheck-resolve-prefix", prefix: h.slice(0, 2), in_bucket: 2, answers: [{ domain_sha256: "0".repeat(64), answer: {} }, { domain_sha256: h, answer: F.resolve }] };
+  const cc = new CrawlCheck({ privateLookups: true, fetch: async (u) => { const p = new URL(String(u)); calls.push(p.pathname + p.search);
+    const b = p.pathname === "/.well-known/http-message-signatures-directory" ? F.directory : p.pathname.startsWith("/api/v1/resolve-prefix/") ? bucket : null;
+    return new Response(JSON.stringify(b || {}), { status: b ? 200 : 404 }); } });
+  const a = await cc.resolve("example-shop.com");
+  assert.equal(a.domain, "example-shop.com");
+  assert.ok(calls.includes("/api/v1/resolve-prefix/" + h.slice(0, 2)));
+  assert.ok(calls.every((c) => !c.includes("example-shop")), "the domain never left the process: " + calls.join(" "));
+  const v = await cc.resolveFor("example-shop.com");
+  assert.equal(v.source, "network"); assert.ok(v.decisions.read);
+  await assert.rejects(cc.resolve("not-in-bucket.com"), (e) => e.status === 404 && /never sent/.test(e.message));
+  assert.ok(calls.every((c) => !c.includes("not-in-bucket")));
+});