@crawlcheck/sdk 0.0.0-stage → 1.0.1

package/dist/gen/openapi.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,148 @@
+import type { paths, components } from "./gen/openapi.js";
+export type { paths, components };
+/** One verifier check. ok: true passed, false FAILED, null could not run (why says why) - never a pass. */
+export interface VerifyCheck {
+    id: string;
+    ok: boolean | null;
+    why: string;
+    [k: string]: unknown;
+}
+export interface BundleVerification {
+    verified: boolean;
+    summary: string;
+    report: {
+        id?: string;
+        domain?: string;
+        scanned_at?: string;
+    };
+    checks: VerifyCheck[];
+    experiences: number | null;
+    note: string;
+}
+export interface ReceiptVerification {
+    verified: boolean;
+    summary: string;
+    receipt: {
+        id: string;
+        domain: string;
+        verdict: string;
+        before: string;
+        after: string;
+    };
+    checks: VerifyCheck[];
+    note: string;
+}
+/** Verify an evidence bundle with no call to CrawlCheck (the same code as /crawlcheck-verify.mjs). */
+export declare const verifyBundle: (b: unknown) => Promise<BundleVerification>;
+/** Verify a remediation receipt with no call to CrawlCheck. */
+export declare const verifyReceipt: (rc: unknown) => Promise<ReceiptVerification>;
+export declare const canon: (v: unknown) => string;
+export declare const merkleRootHex: (hexLeaves: string[]) => Promise<string>;
+export declare const otsInspect: (u8: Uint8Array) => Promise<{
+    digest: string;
+    attestations: Array<{
+        kind: string;
+        [k: string]: unknown;
+    }>;
+}>;
+type S = components["schemas"];
+export type MachineRecordV1 = S["MachineRecordV1"];
+export type PublicReportV1 = S["PublicReportV1"];
+export type EvidenceBundleV1 = S["EvidenceBundleV1"];
+export type RemediationReceiptV1 = S["RemediationReceiptV1"];
+export type ErrorV1 = S["ErrorV1"];
+export type JsonObject = {
+    [k: string]: unknown;
+};
+type Op<P extends keyof paths, M extends "get" | "post"> = paths[P] extends {
+    [K in M]: infer O;
+} ? O : never;
+export type QueryOf<P extends keyof paths, M extends "get" | "post" = "get"> = Op<P, M> extends {
+    parameters: {
+        query?: infer Q;
+    };
+} ? NonNullable<Q> : Record<string, never>;
+export type ResponseOf<P extends keyof paths, M extends "get" | "post" = "get"> = Op<P, M> extends {
+    responses: {
+        200: {
+            content: {
+                "application/json": infer J;
+            };
+        };
+    };
+} ? (unknown extends J ? JsonObject : J) : JsonObject;
+export type BodyOf<P extends keyof paths> = Op<P, "post"> extends {
+    requestBody?: {
+        content: {
+            "application/json": infer B;
+        };
+    };
+} ? B : JsonObject;
+export interface ClientOptions {
+    /** Licence key (cc_ + 32 hex). Without one, licence-gated fields come back withheld, exactly as on the website. */
+    key?: string;
+    /** API origin. Default https://crawlcheck.io */
+    base?: string;
+    /** A fetch implementation (default: globalThis.fetch). */
+    fetch?: typeof fetch;
+    /** Extra headers for every request. */
+    headers?: Record<string, string>;
+}
+export declare class CrawlCheckError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    readonly path: string;
+    constructor(status: number, path: string, body: unknown);
+    /** true when the answer was "this needs a licence for the domain (or the owner's session)". */
+    get locked(): boolean;
+}
+export interface ConformanceResult {
+    name: string;
+    group: string;
+    ok: boolean;
+    diffs: string[];
+    must_reject: string | null;
+}
+export declare class CrawlCheck {
+    readonly base: string;
+    private readonly key?;
+    private readonly f;
+    private readonly extra;
+    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">>;
+    /** Any documented POST, typed from the OpenAPI document. */
+    post<P extends keyof paths>(path: P, body: BodyOf<P> | JsonObject, query?: QueryOf<P, "post">): Promise<ResponseOf<P, "post">>;
+    /** The whole observation in one shape: findings (gated like the site), trust, freshness, score ledger, evidence links. */
+    machineRecord(q: QueryOf<"/api/v1/machine-record">): Promise<MachineRecordV1>;
+    /** Scan a domain now (free lane without a key; the licensed lane with one). */
+    scan(domain: string): Promise<PublicReportV1>;
+    /** A stored report by id, in the public v1 shape. */
+    report(id: string): Promise<PublicReportV1>;
+    explain(q: QueryOf<"/api/explain">): Promise<JsonObject>;
+    impact(q: QueryOf<"/api/impact">): Promise<JsonObject>;
+    whatIf(q: QueryOf<"/api/whatif">): Promise<JsonObject>;
+    locate(q: QueryOf<"/api/locate">): Promise<JsonObject>;
+    /** Every server-side verifier on one record. */
+    verify(id: string): Promise<JsonObject>;
+    /** The evidence bundle (anonymous: subject and leaves withheld; with a licence for the domain: complete). */
+    bundle(id: string): Promise<EvidenceBundleV1>;
+    /** Download the bundle and verify it here, with the offline verifier: no trust in the API's own answer. */
+    verifyOffline(id: string): Promise<BundleVerification>;
+    /** A signed remediation receipt by its id (rc1:…). */
+    receipt(id: string): Promise<RemediationReceiptV1>;
+    /** Fetch a receipt and verify its hash and signature here. key_published stays null offline: compare the key id with publishedKeyIds(). */
+    verifyReceiptOffline(id: string): Promise<ReceiptVerification>;
+    /** The observer's published Ed25519 key ids (RFC 7638 thumbprints), to close the one check a verifier cannot do offline. */
+    publishedKeyIds(): Promise<string[]>;
+    receipts(domain: string): Promise<JsonObject>;
+    /** Run the published conformance fixtures through THIS package's verifier. Every result must be ok. */
+    conformance(): Promise<{
+        ok: boolean;
+        results: ConformanceResult[];
+        built_at: string;
+        verifier_sha256: string;
+    }>;
+    private req;
+}
+export default CrawlCheck;

package/dist/index.js

@@ -0,0 +1,128 @@
+import * as V from "./verify.js";
+/** Verify an evidence bundle with no call to CrawlCheck (the same code as /crawlcheck-verify.mjs). */
+export const verifyBundle = V.verifyBundle;
+/** Verify a remediation receipt with no call to CrawlCheck. */
+export const verifyReceipt = V.verifyReceipt;
+export const canon = V.canon;
+export const merkleRootHex = V.merkleRootHex;
+export const otsInspect = V.otsInspect;
+export class CrawlCheckError extends Error {
+    status;
+    body;
+    path;
+    constructor(status, path, body) {
+        const m = body && typeof body === "object" ? (body.error?.message ?? body.error ?? body.message) : null;
+        super("CrawlCheck " + path + " answered " + status + (m ? ": " + (typeof m === "string" ? m : JSON.stringify(m)) : ""));
+        this.name = "CrawlCheckError";
+        this.status = status;
+        this.body = body;
+        this.path = path;
+    }
+    /** true when the answer was "this needs a licence for the domain (or the owner's session)". */
+    get locked() { return this.status === 403; }
+}
+export class CrawlCheck {
+    base;
+    key;
+    f;
+    extra;
+    constructor(opts = {}) {
+        this.base = (opts.base ?? "https://crawlcheck.io").replace(/\/+$/, "");
+        this.key = opts.key;
+        this.extra = opts.headers ?? {};
+        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)");
+        this.f = f.bind(globalThis);
+    }
+    /** Any documented GET, typed from the OpenAPI document: client.get("/api/explain", { domain: "example.com" }). */
+    async get(path, query) {
+        return this.req("GET", path, query);
+    }
+    /** Any documented POST, typed from the OpenAPI document. */
+    async post(path, body, query) {
+        return this.req("POST", path, query, body);
+    }
+    // ── the records ──
+    /** The whole observation in one shape: findings (gated like the site), trust, freshness, score ledger, evidence links. */
+    machineRecord(q) { return this.get("/api/v1/machine-record", q); }
+    /** Scan a domain now (free lane without a key; the licensed lane with one). */
+    scan(domain) { return this.post("/api/v1/scan", { domain }); }
+    /** A stored report by id, in the public v1 shape. */
+    async report(id) { return this.req("GET", "/r/" + encodeURIComponent(id) + ".json"); }
+    // ── why ──
+    explain(q) { return this.get("/api/explain", q); }
+    impact(q) { return this.get("/api/impact", q); }
+    whatIf(q) { return this.get("/api/whatif", q); }
+    locate(q) { return this.get("/api/locate", q); }
+    // ── proof ──
+    /** Every server-side verifier on one record. */
+    verify(id) { return this.get("/api/verify", { id }); }
+    /** The evidence bundle (anonymous: subject and leaves withheld; with a licence for the domain: complete). */
+    bundle(id) { return this.get("/api/bundle", { id, download: "0" }); }
+    /** Download the bundle and verify it here, with the offline verifier: no trust in the API's own answer. */
+    async verifyOffline(id) { return verifyBundle(await this.bundle(id)); }
+    /** A signed remediation receipt by its id (rc1:…). */
+    async receipt(id) { const r = await this.get("/api/receipt", { id }); return r.receipt; }
+    /** Fetch a receipt and verify its hash and signature here. key_published stays null offline: compare the key id with publishedKeyIds(). */
+    async verifyReceiptOffline(id) { return verifyReceipt(await this.receipt(id)); }
+    /** The observer's published Ed25519 key ids (RFC 7638 thumbprints), to close the one check a verifier cannot do offline. */
+    async publishedKeyIds() {
+        const d = await this.req("GET", "/.well-known/http-message-signatures-directory");
+        const out = [];
+        for (const k of (d?.keys ?? [])) {
+            if (!k?.x)
+                continue;
+            const h = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify({ crv: k.crv, kty: k.kty, x: k.x }))));
+            let s = "";
+            for (const b of h)
+                s += String.fromCharCode(b);
+            out.push(btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""));
+        }
+        return out;
+    }
+    receipts(domain) { return this.get("/api/receipts", { domain }); }
+    // ── the suite ──
+    /** Run the published conformance fixtures through THIS package's verifier. Every result must be ok. */
+    async conformance() {
+        const ix = await this.req("GET", "/conformance/index.json");
+        const results = [];
+        for (const f of ix.fixtures) {
+            const doc = await this.req("GET", new URL(f.file).pathname + new URL(f.file).search);
+            const res = f.kind === "receipt" ? await verifyReceipt(doc) : await verifyBundle(doc);
+            const got = {};
+            for (const c of res.checks)
+                got[c.id] = c.ok;
+            const diffs = Object.keys(f.expected.checks).filter((k) => got[k] !== f.expected.checks[k]).map((k) => k + " expected " + f.expected.checks[k] + " got " + got[k]);
+            if (res.verified !== f.expected.verified)
+                diffs.push("verified expected " + f.expected.verified + " got " + res.verified);
+            results.push({ name: f.name, group: f.group, ok: diffs.length === 0, diffs, must_reject: f.must_reject ?? null });
+        }
+        return { ok: results.every((r) => r.ok), results, built_at: ix.built_at, verifier_sha256: ix.verifier.sha256 };
+    }
+    async req(method, path, query, body) {
+        const u = new URL(path, this.base + "/");
+        if (query)
+            for (const [k, v] of Object.entries(query))
+                if (v !== undefined && v !== null)
+                    u.searchParams.set(k, Array.isArray(v) ? v.join(",") : String(v));
+        const h = Object.assign({ accept: "application/json" }, this.extra);
+        if (this.key)
+            h["x-crawlcheck-key"] = this.key;
+        if (body !== undefined)
+            h["content-type"] = "application/json";
+        const r = await this.f(u.toString(), { method, headers: h, body: body === undefined ? undefined : JSON.stringify(body) });
+        const t = await r.text();
+        let j;
+        try {
+            j = t ? JSON.parse(t) : null;
+        }
+        catch {
+            j = t;
+        }
+        if (!r.ok)
+            throw new CrawlCheckError(r.status, u.pathname, j);
+        return j;
+    }
+}
+export default CrawlCheck;

package/dist/verify.d.ts

@@ -0,0 +1,27 @@
+export function canon(v: any): any;
+export function merkleRootHex(hexLeaves: any): Promise<any>;
+export function otsInspect(u8: any): Promise<{
+    digest: string;
+    attestations: any[];
+}>;
+export function verifyBundle(b: any): Promise<{
+    verified: boolean;
+    summary: string;
+    report: any;
+    checks: any[];
+    experiences: any;
+    note: string;
+}>;
+export function verifyReceipt(rc: any): Promise<{
+    verified: boolean;
+    summary: string;
+    receipt: {
+        id: any;
+        domain: any;
+        verdict: any;
+        before: any;
+        after: any;
+    };
+    checks: any[];
+    note: string;
+}>;

package/dist/verify.js

@@ -0,0 +1,345 @@
+// crawlcheck-verify.mjs — verifies a CrawlCheck evidence bundle with no call to crawlcheck.io.
+// Zero dependencies. Node 20+:  node crawlcheck-verify.mjs bundle.json
+// Browser or Node module:        import { verifyBundle } from "./crawlcheck-verify.mjs"
+//
+// Also verifies a remediation receipt (node crawlcheck-verify.mjs receipt.json): receipt_hash, key_id, signature, order.
+// What it checks, each from the bytes inside the bundle:
+//   manifest_hash      sha256(manifest.body) equals manifest.sha256
+//   key_id             the RFC 7638 thumbprint of the public key equals the signature's key id
+//   signature          Ed25519 over "crawlcheck-meg-manifest-v1\n" + manifest sha256
+//   subject_hash       sha256(record.subject) equals the record digest (the leaf)
+//   subject_binds      the subject names this report, and its meg field names this manifest
+//   merkle_path        the leaf folds along the path to the day's root
+//   ots_commits_root   the .ots file timestamps exactly that root
+//   ots_attestations   the op chain evaluated: pending calendars, or the Bitcoin block and the merkle root it commits to
+//   experience_root    (manifest v3) the manifest's sealed root over its fetches recomputes from the fetches it lists
+//   decision_root      (manifest v3) the sealed root over the decisions recomputes from the decision leaves (licence bundles)
+//   lineage_root       (manifest v3) the sealed root over the extracted business facts recomputes from their leaves (licence bundles)
+// A check that cannot run (a withheld subject, an unsealed day) is null with the reason, never a pass.
+// What it cannot do offline: read a Bitcoin block header. It prints the block height and the merkle root the
+// proof commits to; compare that value with any Bitcoin node or block explorer.
+const MEG_SIG_PREFIX = "crawlcheck-meg-manifest-v1\n";
+const OTS_MAGIC = [0x00, 0x4f, 0x70, 0x65, 0x6e, 0x54, 0x69, 0x6d, 0x65, 0x73, 0x74, 0x61, 0x6d, 0x70, 0x73, 0x00, 0x00, 0x50, 0x72, 0x6f, 0x6f, 0x66, 0x00, 0xbf, 0x89, 0xe2, 0xe8, 0x84, 0xe8, 0x92, 0x94];
+const TAG_BITCOIN = "0588960d73d71901", TAG_PENDING = "83dfe30d2ef90c8e", TAG_LITECOIN = "06869a0d73d71b45";
+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("");
+const unhex = (h) => { const s = String(h || ""); const o = new Uint8Array(s.length >> 1); for (let i = 0; i < o.length; i++)
+    o[i] = parseInt(s.substr(i * 2, 2), 16); return o; };
+const sha256 = async (u8) => new Uint8Array(await subtle.digest("SHA-256", u8));
+const b64 = (s) => { const t = String(s || "").replace(/-/g, "+").replace(/_/g, "/"); const p = t.padEnd(Math.ceil(t.length / 4) * 4, "="); const bin = atob(p); const o = new Uint8Array(bin.length); for (let i = 0; i < bin.length; i++)
+    o[i] = bin.charCodeAt(i); return o; };
+const b64u = (u8) => { let s = ""; for (const b of u8)
+    s += String.fromCharCode(b); return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""); };
+const cat = (a, b) => { const o = new Uint8Array(a.length + b.length); o.set(a, 0); o.set(b, a.length); return o; };
+// The same canonical JSON the observer hashes: keys sorted at every level, no whitespace, undefined as null.
+export function canon(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v === undefined ? null : v);
+    if (Array.isArray(v))
+        return "[" + v.map(canon).join(",") + "]";
+    return "{" + Object.keys(v).sort().map((k) => JSON.stringify(k) + ":" + canon(v[k])).join(",") + "}";
+}
+// The same Merkle tree the daily seal uses: leaves sorted as hex, parent = SHA-256(left || right), odd node paired with itself.
+export async function merkleRootHex(hexLeaves) {
+    if (!hexLeaves.length)
+        return "";
+    let level = hexLeaves.slice().sort();
+    while (level.length > 1) {
+        const next = [];
+        for (let i = 0; i < level.length; i += 2)
+            next.push(hex(await sha256(cat(unhex(level[i]), unhex(level[i + 1] === undefined ? level[i] : level[i + 1])))));
+        level = next;
+    }
+    return level[0];
+}
+const leafHex = async (o) => hex(await sha256(enc.encode(canon(o))));
+// ── OpenTimestamps: parse the detached proof and evaluate every branch ─────────
+function reader(u8) {
+    let i = 0;
+    return {
+        left: () => u8.length - i,
+        byte() { if (i >= u8.length)
+            throw new Error("ots: truncated"); return u8[i++]; },
+        bytes(n) { if (i + n > u8.length)
+            throw new Error("ots: truncated"); const o = u8.slice(i, i + n); i += n; return o; },
+        varuint() { let v = 0, s = 0, b; do {
+            b = this.byte();
+            v += (b & 0x7f) * Math.pow(2, s);
+            s += 7;
+        } while (b & 0x80); return v; },
+        varbytes() { return this.bytes(this.varuint()); }
+    };
+}
+async function otsBranch(rd, msg, out, depth) {
+    if (depth > 256)
+        throw new Error("ots: too deep");
+    const one = async (tag) => {
+        if (tag === 0x00) {
+            const t = hex(rd.bytes(8)), payload = rd.varbytes();
+            if (t === TAG_BITCOIN) {
+                const pr = reader(payload);
+                out.push({ kind: "bitcoin", height: pr.varuint(), commits_to_le: hex(msg), merkle_root: hex(msg.slice().reverse()) });
+            }
+            else if (t === TAG_PENDING) {
+                const pr = reader(payload);
+                out.push({ kind: "pending", calendar: new TextDecoder().decode(pr.varbytes()) });
+            }
+            else if (t === TAG_LITECOIN) {
+                const pr = reader(payload);
+                out.push({ kind: "litecoin", height: pr.varuint() });
+            }
+            else
+                out.push({ kind: "unknown", tag: t });
+            return;
+        }
+        let next;
+        if (tag === 0x08)
+            next = await sha256(msg);
+        else if (tag === 0xf0)
+            next = cat(msg, rd.varbytes());
+        else if (tag === 0xf1)
+            next = cat(rd.varbytes(), msg);
+        else if (tag === 0xf2)
+            next = msg.slice().reverse();
+        else if (tag === 0xf3)
+            next = enc.encode(hex(msg));
+        else
+            throw new Error("ots: op 0x" + tag.toString(16) + " is not supported by this verifier");
+        await otsBranch(rd, next, out, depth + 1);
+    };
+    let tag = rd.byte();
+    while (tag === 0xff) {
+        await one(rd.byte());
+        tag = rd.byte();
+    }
+    await one(tag);
+}
+export async function otsInspect(u8) {
+    const rd = reader(u8);
+    const magic = rd.bytes(OTS_MAGIC.length);
+    if (!OTS_MAGIC.every((b, i) => magic[i] === b))
+        throw new Error("not an OpenTimestamps proof (magic bytes differ)");
+    const version = rd.varuint();
+    if (version !== 1)
+        throw new Error("ots: unsupported version " + version);
+    const op = rd.byte();
+    if (op !== 0x08)
+        throw new Error("ots: file hash is not sha256");
+    const digest = rd.bytes(32);
+    const attestations = [];
+    await otsBranch(rd, digest, attestations, 0);
+    return { digest: hex(digest), attestations };
+}
+// ── the bundle ────────────────────────────────────────────────────────────────
+export async function verifyBundle(b) {
+    if (!subtle)
+        throw new Error("this runtime has no WebCrypto (crypto.subtle)");
+    const checks = [];
+    const C = (id, ok, why, extra) => checks.push(Object.assign({ id, ok, why }, extra || {}));
+    if (!b || b.kind !== "crawlcheck-evidence-bundle")
+        throw new Error("not a CrawlCheck evidence bundle");
+    const rep = b.report || {}, man = b.manifest || null, rec = b.record || {}, seal = b.seal || {};
+    // 1. manifest bytes
+    let manObj = null;
+    if (!man)
+        C("manifest_hash", null, "this record predates evidence manifests (2026-09-20)");
+    else if (!man.body)
+        C("manifest_hash", null, man.body_missing || "manifest body not included");
+    else {
+        const h = hex(await sha256(enc.encode(man.body)));
+        C("manifest_hash", h === man.sha256, h === man.sha256 ? "manifest body hashes to " + h.slice(0, 16) + "…" : "manifest body hashes to " + h + ", bundle says " + man.sha256);
+        try {
+            manObj = JSON.parse(man.body);
+        }
+        catch (e) {
+            manObj = null;
+        }
+    }
+    // 2. key id + signature
+    const sg = man && man.signature, key = man && man.key;
+    if (!sg)
+        C("key_id", null, "the manifest is unsigned (recorded before signing began, 2026-09-23)"), C("signature", null, "no signature to check");
+    else if (!key || !key.jwk)
+        C("key_id", null, "the signing key is not in the bundle (retired or unknown); look it up by id " + sg.kid), C("signature", null, "no key to check against");
+    else {
+        const thumb = b64u(await sha256(enc.encode(JSON.stringify({ crv: key.jwk.crv, kty: key.jwk.kty, x: key.jwk.x }))));
+        C("key_id", thumb === sg.kid, thumb === sg.kid ? "public key thumbprint (RFC 7638) is the key id " + sg.kid.slice(0, 12) + "…; the same id is published in " + (key.published_in || "the key directory") : "thumbprint " + thumb + " does not match key id " + sg.kid);
+        const msg = MEG_SIG_PREFIX + man.sha256;
+        if (sg.message && sg.message !== msg)
+            C("signature", false, "the signed message does not name this manifest");
+        else {
+            let ok = false;
+            try {
+                const pk = await subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: key.jwk.x }, { name: "Ed25519" }, false, ["verify"]);
+                ok = await subtle.verify({ name: "Ed25519" }, pk, b64(sg.sig), enc.encode(msg));
+            }
+            catch (e) {
+                C("signature", null, "this runtime cannot verify Ed25519: " + (e && e.message || e));
+                ok = null;
+            }
+            if (ok !== null)
+                C("signature", ok, ok ? "Ed25519 signature over the manifest digest verifies" : "signature does NOT verify");
+        }
+    }
+    // 3. subject
+    let subj = null;
+    if (!rec.digest)
+        C("subject_hash", null, "no record digest in the bundle");
+    else if (!rec.subject)
+        C("subject_hash", null, rec.subject_withheld || "subject not included");
+    else {
+        const h = hex(await sha256(enc.encode(rec.subject)));
+        C("subject_hash", h === rec.digest, h === rec.digest ? "the sealed subject hashes to the record digest" : "subject hashes to " + h + ", digest is " + rec.digest);
+        try {
+            subj = JSON.parse(rec.subject);
+        }
+        catch (e) {
+            subj = null;
+        }
+    }
+    if (!subj)
+        C("subject_binds", null, "needs the subject");
+    else {
+        const idOk = !rep.id || subj.id === rep.id, domOk = !rep.domain || subj.domain === rep.domain;
+        const mOk = man ? subj.meg === man.sha256 : !("meg" in subj);
+        C("subject_binds", idOk && domOk && mOk, (idOk ? "names report " + subj.id : "names report " + subj.id + ", bundle says " + rep.id) + (domOk ? ", domain " + subj.domain : ", domain mismatch") +
+            (man ? (mOk ? ", and commits to this manifest" : ", but its meg field " + subj.meg + " is not this manifest") : ""));
+    }
+    // 4. merkle path
+    if (seal.state !== "sealed")
+        C("merkle_path", null, "the day is not sealed: " + (seal.why || seal.state || "unknown"));
+    else {
+        let h = unhex(rec.digest);
+        for (const s of seal.path || [])
+            h = await sha256(s.side === "right" ? cat(h, unhex(s.hash)) : cat(unhex(s.hash), h));
+        const got = hex(h);
+        C("merkle_path", got === seal.root, got === seal.root ? "the digest folds to the root of " + seal.day + " (" + (seal.path || []).length + " steps, " + (seal.leaves_that_day || "?") + " leaves that day)" : "the path folds to " + got + ", not the root " + seal.root);
+    }
+    // 5. timestamp
+    let att = [];
+    if (seal.state !== "sealed")
+        C("ots_commits_root", null, "no seal yet"), C("ots_attestations", null, "no seal yet");
+    else if (!seal.ots_base64)
+        C("ots_commits_root", null, "the day's .ots bytes are not in the bundle"), C("ots_attestations", null, "no .ots");
+    else {
+        try {
+            const o = await otsInspect(b64(seal.ots_base64));
+            att = o.attestations;
+            C("ots_commits_root", o.digest === seal.root, o.digest === seal.root ? "the timestamp proof is over exactly this root" : "the .ots timestamps " + o.digest + ", not the root " + seal.root);
+            const btc = att.filter((a) => a.kind === "bitcoin"), pend = att.filter((a) => a.kind === "pending");
+            if (btc.length)
+                C("ots_attestations", true, "anchored in Bitcoin block " + Array.from(new Set(btc.map((a) => a.height))).join(", ") + "; the proof commits the root into merkle root " + btc[0].merkle_root + " - compare it with that block's header on any Bitcoin node", { bitcoin: btc });
+            else if (pend.length)
+                C("ots_attestations", null, "submitted to " + pend.map((a) => a.calendar).join(", ") + ", not yet confirmed in a Bitcoin block (usually within a few hours); download the bundle again later", { pending: pend });
+            else
+                C("ots_attestations", false, "the proof carries no attestation");
+        }
+        catch (e) {
+            C("ots_commits_root", false, String(e && e.message || e));
+            C("ots_attestations", null, "could not parse the proof");
+        }
+    }
+    // 6. sealed roots (manifest v3)
+    const roots = manObj && manObj.roots;
+    const rootCheck = async (id, label, sealed, objs, missingWhy) => {
+        if (!roots)
+            return C(id, null, "the manifest predates sealed roots (manifest v3, 2026-09-30)");
+        if (!sealed)
+            return C(id, null, "the manifest carries no " + label + " root");
+        if (!Array.isArray(objs))
+            return C(id, null, missingWhy);
+        const got = await merkleRootHex(await Promise.all(objs.map(leafHex)));
+        const want = sealed.root || "";
+        C(id, got === want && objs.length === sealed.n, got === want && objs.length === sealed.n ? objs.length + " " + label + " leaves recompute to the sealed root" : "the " + label + " leaves give " + (got || "(empty)").slice(0, 16) + "… over " + objs.length + ", the manifest sealed " + want.slice(0, 16) + "… over " + sealed.n);
+    };
+    await rootCheck("experience_root", "fetch", roots && roots.experiences, manObj && Array.isArray(manObj.experiences) ? manObj.experiences : null, "the manifest body is not in the bundle");
+    await rootCheck("decision_root", "decision", roots && roots.decisions, rec.decision_leaves, rec.leaves_withheld || "decision leaves not included");
+    await rootCheck("lineage_root", "lineage", roots && roots.lineage, rec.lineage_leaves, rec.leaves_withheld || "lineage leaves not included");
+    const ran = checks.filter((c) => c.ok !== null), failed = checks.filter((c) => c.ok === false);
+    return {
+        verified: ran.length > 0 && failed.length === 0,
+        summary: failed.length ? failed.length + " check(s) FAILED" : ran.length + " of " + checks.length + " checks ran and passed; " + (checks.length - ran.length) + " could not run (reasons given)",
+        report: rep, checks,
+        experiences: manObj && Array.isArray(manObj.experiences) ? manObj.experiences.length : null,
+        note: "Every check above used only bytes inside the bundle. Only the Bitcoin block header has to come from outside, and from any source you trust."
+    };
+}
+// ── remediation receipts ─────────────────────────────────────────────────────────────────────────────────
+// A receipt joins the record before a fix, the declared fix, when it went live, the record after it and the
+// verification verdict, and is signed with the observer's Ed25519 key over sha256(canonical JSON of everything but
+// receipt_id and signature). Change any field and receipt_hash fails; swap the key and key_id fails.
+const RCPT_SIG_PREFIX = "crawlcheck-receipt-v1\n";
+export async function verifyReceipt(rc) {
+    if (!subtle)
+        throw new Error("this runtime has no WebCrypto (crypto.subtle)");
+    const checks = [];
+    const C = (id, ok, why) => checks.push({ id, ok, why });
+    if (!rc || rc.kind !== "crawlcheck-remediation-receipt" || !rc.signature)
+        throw new Error("not a CrawlCheck remediation receipt");
+    const body = {};
+    for (const k of Object.keys(rc))
+        if (k !== "receipt_id" && k !== "signature")
+            body[k] = rc[k];
+    const sha = hex(await sha256(enc.encode(canon(body))));
+    C("receipt_hash", sha === rc.signature.receipt_sha256 && rc.receipt_id === "rc1:" + sha, sha === rc.signature.receipt_sha256 ? "the receipt hashes to its id " + sha.slice(0, 16) + "…" : "the receipt hashes to " + sha + ", it claims " + rc.signature.receipt_sha256 + " - a field was changed");
+    const jwk = rc.issuer && rc.issuer.key && rc.issuer.key.jwk;
+    if (!jwk || !jwk.x) {
+        C("key_id", null, "no key in the receipt");
+        C("signature", null, "no key to check against");
+    }
+    else {
+        const thumb = b64u(await sha256(enc.encode(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x }))));
+        C("key_id", thumb === rc.signature.kid, thumb === rc.signature.kid ? "public key thumbprint (RFC 7638) is the key id " + thumb.slice(0, 12) + "…; the same id is published in " + (rc.issuer.key.published_in || "the key directory") : "thumbprint " + thumb + " does not match key id " + rc.signature.kid);
+        const msg = RCPT_SIG_PREFIX + sha;
+        let ok = null;
+        try {
+            const pk = await subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, { name: "Ed25519" }, false, ["verify"]);
+            ok = rc.signature.message === msg && await subtle.verify({ name: "Ed25519" }, pk, b64(rc.signature.sig), enc.encode(msg));
+        }
+        catch (e) {
+            ok = null;
+            C("signature", null, "this runtime cannot verify Ed25519: " + (e && e.message || e));
+        }
+        if (ok !== null)
+            C("signature", ok, ok ? "Ed25519 signature over the receipt digest verifies" : "signature does NOT verify over this content");
+    }
+    C("key_published", null, "offline this cannot be decided: compare key id " + (rc.signature.kid || "?") + " with the ids published at " + ((rc.issuer && rc.issuer.key && rc.issuer.key.published_in) || "the key directory") + " (a receipt re-signed with any other key passes every other check here)");
+    const b = rc.before || {}, a = rc.after || {};
+    C("order", !!(b.scanned_at && a.scanned_at && Date.parse(b.scanned_at) < Date.parse(a.scanned_at)), b.scanned_at && a.scanned_at ? "before " + b.scanned_at + " precedes after " + a.scanned_at : "a scan time is missing");
+    const ran = checks.filter((c) => c.ok !== null), failed = checks.filter((c) => c.ok === false);
+    return { verified: ran.length > 0 && failed.length === 0, summary: failed.length ? failed.length + " check(s) FAILED" : ran.length + " of " + checks.length + " checks ran and passed",
+        receipt: { id: rc.receipt_id, domain: rc.subject && rc.subject.domain, verdict: rc.verification && rc.verification.verdict, before: b.report_id, after: a.report_id }, checks,
+        note: "Every check used only the receipt itself. To confirm the key is CrawlCheck's, compare its id with " + ((rc.issuer && rc.issuer.key && rc.issuer.key.published_in) || "the published key directory") + "; to see the evidence behind each side, verify the two reports' bundles." };
+}
+// ── command line ─────────────────────────────────────────────────────────────
+// Run as a script under ANY file name (a browser saves a second download as "crawlcheck-verify (1).mjs"); imported, it
+// stays a library. The old test matched the file name only, so a renamed copy exited 0 having checked nothing.
+const isMain = typeof process !== "undefined" && !!(process.argv && process.argv[1]) && await (async () => { try {
+    const { pathToFileURL } = await import("node:url");
+    const { realpathSync } = await import("node:fs");
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+}
+catch (e) {
+    return false;
+} })();
+if (isMain) {
+    const f = process.argv[2];
+    if (!f) {
+        console.log("usage: node crawlcheck-verify.mjs <bundle.json>");
+        process.exit(2);
+    }
+    const { readFile } = await import("node:fs/promises");
+    const doc = JSON.parse(await readFile(f, "utf8"));
+    const isRc = doc && (doc.kind === "crawlcheck-remediation-receipt" || (doc.receipt && doc.receipt.kind === "crawlcheck-remediation-receipt"));
+    const res = isRc ? await verifyReceipt(doc.kind ? doc : doc.receipt) : await verifyBundle(doc);
+    const mark = (ok) => ok === true ? "PASS" : ok === false ? "FAIL" : " -- ";
+    if (isRc)
+        console.log("CrawlCheck remediation receipt: " + (res.receipt.id || "?") + " " + (res.receipt.domain || "") + " verdict " + (res.receipt.verdict || "?"));
+    else
+        console.log("CrawlCheck evidence bundle: " + (res.report.id || "?") + " " + (res.report.domain || "") + " scanned " + (res.report.scanned_at || "?"));
+    for (const c of res.checks)
+        console.log(mark(c.ok) + "  " + c.id.padEnd(18) + c.why);
+    console.log(res.summary);
+    process.exit(res.checks.some((c) => c.ok === false) ? 1 : 0);
+}