@crawlcheck/sdk 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -36,6 +36,32 @@ export interface ReceiptVerification {
 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 interface DocumentVerification {
+    verified: boolean;
+    summary: string;
+    document: {
+        kind: string;
+        domain?: string;
+        sha256: string;
+    };
+    checks: VerifyCheck[];
+}
+/** Verify a signed resolve answer, preflight decision receipt, data inventory, export part or deletion record offline. */
+export declare const verifyDocument: (doc: unknown) => Promise<DocumentVerification>;
+/** Verify a signed evidence export (and every bundle and receipt inside it) offline. */
+export declare const verifyExport: (x: unknown) => Promise<{
+    verified: boolean;
+    summary: string;
+    checks: VerifyCheck[];
+    [k: string]: unknown;
+}>;
+/** Verify a signed dispute resolution offline (re-runs the published decision table over the recorded readings). */
+export declare const verifyResolution: (x: unknown) => Promise<{
+    verified: boolean;
+    summary: string;
+    checks: VerifyCheck[];
+    [k: string]: unknown;
+}>;
 export declare const canon: (v: unknown) => string;
 export declare const merkleRootHex: (hexLeaves: string[]) => Promise<string>;
 export declare const otsInspect: (u8: Uint8Array) => Promise<{
@@ -78,6 +104,48 @@ export type BodyOf<P extends keyof paths> = Op<P, "post"> extends {
         };
     };
 } ? B : JsonObject;
+export type Action = "read" | "cite" | "connect" | "transact" | "administer";
+export type Decision = "allow" | "warn" | "require_confirmation" | "block" | "unsupported";
+export interface PreflightPolicy {
+    max_age_hours?: number;
+    on_warn?: "warn" | "require_confirmation" | "block";
+    require_entity?: boolean;
+    human_approval?: Action[];
+    allow?: Action[];
+    deny?: Action[];
+    [k: string]: unknown;
+}
+export interface PreflightOptions {
+    agent?: string;
+    template?: string;
+    policy?: PreflightPolicy;
+}
+/** A signed crawlcheck-decision receipt. Verify it with verifyDocument (or let guard() do it). */
+export interface DecisionReceipt {
+    kind: "crawlcheck-decision";
+    domain: string;
+    action: Action;
+    decision: Decision;
+    sha256: string;
+    signature: {
+        kid: string;
+        [k: string]: unknown;
+    };
+    resolve?: {
+        sha256: string;
+        kid: string;
+    };
+    alternatives?: JsonObject[];
+    [k: string]: unknown;
+}
+export interface GuardOptions extends PreflightOptions {
+    /** Proceed on "warn" too. Default false: warn does not proceed. */
+    allowWarn?: boolean;
+    /** Called on "require_confirmation"; proceed only if it resolves true. Without it, require_confirmation does not proceed. */
+    confirm?: (receipt: DecisionReceipt) => boolean | Promise<boolean>;
+    /** Also require the signing key to be in the published key directory (default true). */
+    onlineKeys?: boolean;
+}
 export interface ClientOptions {
     /** Licence key (cc_ + 32 hex). Without one, licence-gated fields come back withheld, exactly as on the website. */
     key?: string;
@@ -113,6 +181,29 @@ export declare class CrawlCheck {
     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 signed ResolveV1 answer: crawl policy, delivery, machine files, capabilities, entity, findings, freshness and a decision per action. */
+    resolve(domain: string): Promise<JsonObject>;
+    /** Up to 100 domains in one call; each answer is a full signed ResolveV1 document. */
+    resolveBatch(domains: string[]): Promise<JsonObject>;
+    /** 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. */
+    verifyDocument(doc: unknown, onlineKeys?: boolean): Promise<DocumentVerification>;
+    /** Preflight, verify the receipt, and decide. Proceeds on allow; warn only with allowWarn; require_confirmation only if confirm() says yes; block and unsupported never. */
+    guard(domain: string, action?: Action, opts?: GuardOptions): Promise<{
+        proceed: boolean;
+        receipt: DecisionReceipt;
+        verification: DocumentVerification;
+    }>;
+    /** Signed change feed (what changed since a time, optionally for one domain). */
+    changes(q?: QueryOf<"/api/v1/changes">): Promise<JsonObject>;
+    /** Report what happened after acting. Outcomes are kept apart from the signed record and never rewrite it. */
+    outcome(body: JsonObject & {
+        domain: string;
+        action: Action;
+    }): Promise<JsonObject>;
+    /** The registry record (RDAP) and lifecycle of a domain. */
+    domain(domain: string): Promise<JsonObject>;
     /** 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). */

package/dist/index.js

@@ -3,6 +3,12 @@ import * as V from "./verify.js";
 export const verifyBundle = V.verifyBundle;
 /** Verify a remediation receipt with no call to CrawlCheck. */
 export const verifyReceipt = V.verifyReceipt;
+/** Verify a signed resolve answer, preflight decision receipt, data inventory, export part or deletion record offline. */
+export const verifyDocument = V.verifyDataDoc;
+/** Verify a signed evidence export (and every bundle and receipt inside it) offline. */
+export const verifyExport = V.verifyExport;
+/** Verify a signed dispute resolution offline (re-runs the published decision table over the recorded readings). */
+export const verifyResolution = V.verifyResolution;
 export const canon = V.canon;
 export const merkleRootHex = V.merkleRootHex;
 export const otsInspect = V.otsInspect;
@@ -43,6 +49,51 @@ export class CrawlCheck {
     async post(path, body, query) {
         return this.req("POST", path, query, body);
     }
+    // ── read before acting ──
+    /** The signed ResolveV1 answer: crawl policy, delivery, machine files, capabilities, entity, findings, freshness and a decision per action. */
+    resolve(domain) { return this.get("/api/v1/resolve", { domain }); }
+    /** Up to 100 domains in one call; each answer is a full signed ResolveV1 document. */
+    resolveBatch(domains) { return this.post("/api/v1/resolve", { domains }); }
+    /** 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 };
+        if (opts.agent)
+            b.agent = opts.agent;
+        if (opts.template)
+            b.template = opts.template;
+        if (opts.policy)
+            b.policy = opts.policy;
+        return this.post("/api/v1/preflight", b);
+    }
+    /** Verify a signed document here. With onlineKeys (default), its signing key must also be in the published directory. */
+    async verifyDocument(doc, onlineKeys = true) {
+        const v = await verifyDocument(doc);
+        if (!onlineKeys)
+            return v;
+        const kid = doc?.signature?.kid;
+        const ok = !!kid && (await this.publishedKeyIds()).includes(kid);
+        const checks = v.checks.map((c) => c.id === "key_published" ? { id: c.id, ok, why: ok ? "key id " + kid + " is in the published key directory" : "key id " + kid + " is NOT in the published key directory" } : c);
+        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", document: v.document, checks };
+    }
+    /** Preflight, verify the receipt, and decide. Proceeds on allow; warn only with allowWarn; require_confirmation only if confirm() says yes; block and unsupported never. */
+    async guard(domain, action = "read", opts = {}) {
+        const receipt = await this.preflight(domain, action, opts);
+        const verification = await this.verifyDocument(receipt, opts.onlineKeys ?? true);
+        if (!verification.verified)
+            return { proceed: false, receipt, verification };
+        const d = receipt.decision;
+        let proceed = d === "allow" || (d === "warn" && !!opts.allowWarn);
+        if (d === "require_confirmation" && opts.confirm)
+            proceed = !!(await opts.confirm(receipt));
+        return { proceed, receipt, verification };
+    }
+    /** Signed change feed (what changed since a time, optionally for one domain). */
+    changes(q = {}) { return this.get("/api/v1/changes", q); }
+    /** Report what happened after acting. Outcomes are kept apart from the signed record and never rewrite it. */
+    outcome(body) { return this.post("/api/v1/outcome", body); }
+    /** The registry record (RDAP) and lifecycle of a domain. */
+    domain(domain) { return this.get("/api/v1/domain", { domain }); }
     // ── 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); }

package/dist/verify.d.ts

@@ -25,3 +25,67 @@ export function verifyReceipt(rc: any): Promise<{
     checks: any[];
     note: string;
 }>;
+export function verifyExport(x: any): Promise<{
+    verified: boolean;
+    summary: string;
+    export: {
+        domain: any;
+        window: any;
+        records: number;
+        receipts: number;
+        generated_at: any;
+    };
+    checks: any[];
+    records: ({
+        id: any;
+        verified: null;
+        failed: never[];
+        why: any;
+        scanned_at?: undefined;
+        ran?: undefined;
+    } | {
+        id: any;
+        scanned_at: any;
+        verified: boolean | null;
+        failed: any[];
+        ran: number;
+        why: string | null;
+    })[];
+    receipts: {
+        id: any;
+        verified: boolean | null;
+        failed: any[];
+        why: string | null;
+    }[];
+    note: string;
+}>;
+export function dspVerdict(m: any): {
+    verdict: string;
+    effect: string;
+    rule: string;
+};
+export function verifyResolution(x: any): Promise<{
+    verified: boolean;
+    summary: string;
+    resolution: {
+        id: any;
+        dispute: any;
+        domain: any;
+        code: any;
+        verdict: any;
+        effect: any;
+        observers: any;
+    };
+    checks: any[];
+    note: string;
+}>;
+export function verifyDataDoc(x: any): Promise<{
+    verified: boolean;
+    summary: string;
+    document: {
+        kind: any;
+        domain: any;
+        sha256: any;
+    };
+    checks: any[];
+}>;

package/dist/verify.js

@@ -2,7 +2,11 @@
 // 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.
+// Also verifies a remediation receipt (node crawlcheck-verify.mjs receipt.json): receipt_hash, key_id, signature, order;
+// and an evidence export (node crawlcheck-verify.mjs export.json): export_hash, key_id, signature, then every bundle and receipt inside it.
+// And a dispute resolution (node crawlcheck-verify.mjs resolution.json): resolution_hash, key_id, signature,
+// verdict_derivable (re-runs the published decision table over the recorded readings), readings_after_dispute.
+// And a data inventory, export part or deletion record (node crawlcheck-verify.mjs deletion.json): document_hash, key_id, signature.
 // 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
@@ -312,6 +316,228 @@ export async function verifyReceipt(rc) {
         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." };
 }
+// ── evidence exports ─────────────────────────────────────────────────────────────────────────────────────
+// An export is one signed file for a domain and a period: records[] each carrying a full evidence bundle,
+// receipts[], the certificate days and the seals. The file is signed over sha256(canonical JSON of everything but
+// export_sha256 and signature); then every bundle and every receipt inside it is verified exactly as it would be on
+// its own. One altered byte anywhere fails export_hash; one altered bundle fails its own checks.
+const EXPORT_SIG_PREFIX = "crawlcheck-evidence-export-v1\n";
+export async function verifyExport(x) {
+    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 (!x || x.kind !== "crawlcheck-evidence-export")
+        throw new Error("not a CrawlCheck evidence export");
+    const body = {};
+    for (const k of Object.keys(x))
+        if (k !== "export_sha256" && k !== "signature")
+            body[k] = x[k];
+    const sha = hex(await sha256(enc.encode(canon(body))));
+    if (!x.signature) {
+        C("export_hash", sha === x.export_sha256, sha === x.export_sha256 ? "the file hashes to its stated digest " + sha.slice(0, 16) + "…" : "the file hashes to " + sha + ", it states " + x.export_sha256 + " - a field was changed");
+        C("signature", null, "the export is unsigned (the observer had no signing key when it was made)");
+    }
+    else {
+        C("export_hash", sha === x.export_sha256 && x.signature.export_sha256 === sha, sha === x.export_sha256 ? "the file hashes to its stated digest " + sha.slice(0, 16) + "…" : "the file hashes to " + sha + ", it states " + x.export_sha256 + " - a field was changed");
+        const jwk = x.signature.key && x.signature.key.jwk;
+        if (!jwk || !jwk.x) {
+            C("key_id", null, "no key in the export");
+            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 === x.signature.kid, thumb === x.signature.kid ? "public key thumbprint (RFC 7638) is the key id " + thumb.slice(0, 12) + "…; the same id is published in " + (x.signature.key.published_in || "the key directory") : "thumbprint " + thumb + " does not match key id " + x.signature.kid);
+            const msg = EXPORT_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 = x.signature.message === msg && await subtle.verify({ name: "Ed25519" }, pk, b64(x.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 export digest verifies" : "signature does NOT verify over this content");
+        }
+        C("key_published", null, "offline this cannot be decided: compare key id " + (x.signature.kid || "?") + " with the ids published at " + ((x.signature.key && x.signature.key.published_in) || "the key directory"));
+    }
+    const records = [];
+    for (const rec of (Array.isArray(x.records) ? x.records : [])) {
+        if (!rec || !rec.bundle) {
+            records.push({ id: rec && rec.id, verified: null, failed: [], why: (rec && rec.missing) || "no bundle" });
+            continue;
+        }
+        let v = null, why = null;
+        try {
+            v = await verifyBundle(rec.bundle);
+        }
+        catch (e) {
+            why = String(e && e.message || e);
+        }
+        const same = !!(v && rec.bundle.report && rec.bundle.report.id === rec.id && rec.bundle.report.domain === x.domain);
+        records.push({ id: rec.id, scanned_at: rec.scanned_at, verified: v ? (v.verified && same) : null, failed: v ? v.checks.filter((c) => c.ok === false).map((c) => c.id).concat(same ? [] : ["bundle_names_another_record"]) : [], ran: v ? v.checks.filter((c) => c.ok !== null).length : 0, why });
+    }
+    const receipts = [];
+    for (const rc of (Array.isArray(x.receipts) ? x.receipts : [])) {
+        let v = null, why = null;
+        try {
+            v = await verifyReceipt(rc);
+        }
+        catch (e) {
+            why = String(e && e.message || e);
+        }
+        receipts.push({ id: rc && rc.receipt_id, verified: v ? v.verified : null, failed: v ? v.checks.filter((c) => c.ok === false).map((c) => c.id) : [], why });
+    }
+    const rf = records.filter((r) => r.verified === false).length, cf = receipts.filter((r) => r.verified === false).length;
+    C("records", records.length ? rf === 0 : null, records.length ? (rf ? rf + " of " + records.length + " bundles FAILED" : records.length + " bundle" + (records.length === 1 ? "" : "s") + " inside the file verified on their own (" + records.filter((r) => r.verified === true).length + " fully, " + records.filter((r) => r.verified === null).length + " with checks that could not run)") : "the file carries no records");
+    C("receipts", receipts.length ? cf === 0 : null, receipts.length ? (cf ? cf + " of " + receipts.length + " receipts FAILED" : receipts.length + " receipt" + (receipts.length === 1 ? "" : "s") + " verified") : "the file carries no receipts");
+    const cnt = x.counts || {};
+    C("counts", (Array.isArray(x.records) ? x.records.length : 0) === ((cnt.records || 0) + (cnt.missing || 0)) && (Array.isArray(x.receipts) ? x.receipts.length : 0) === (cnt.receipts || 0), "the file's own counts match what it carries (" + (Array.isArray(x.records) ? x.records.length : 0) + " records, " + (Array.isArray(x.receipts) ? x.receipts.length : 0) + " receipts)");
+    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",
+        export: { domain: x.domain, window: x.window, records: records.length, receipts: receipts.length, generated_at: x.generated_at }, checks, records, receipts,
+        note: "Every check used only the file itself. To confirm the key is CrawlCheck's, compare its id with " + ((x.signature && x.signature.key && x.signature.key.published_in) || "the published key directory") + "." };
+}
+// ── dispute resolutions ──────────────────────────────────────────────────────────────────────────────────
+// A resolution records a dispute against one finding, the three readings that settled it (the rule replayed over
+// the disputed record's sealed bytes, the primary observer's fresh audit, every independent observer's reading) and
+// the verdict. It is signed like a receipt. verdict_derivable runs the published decision table (dspVerdict, the
+// same function the Worker runs) over the recorded readings: a resolution whose verdict was edited, or whose
+// readings were edited to fit it, fails here even before the signature does.
+const DSP_SIG_PREFIX = "crawlcheck-dispute-resolution-v1\n";
+export function dspVerdict(m) {
+    // The published decision table. Inputs are only what the resolution itself records, so a verifier can re-derive
+    // the verdict from the record: replay of the rule over the bytes the disputed scan received, the primary
+    // observer's fresh re-measurement, and every independent observer's reading after the dispute was filed.
+    const rp = m && m.replay ? m.replay.reproduces : null;
+    const obs = (m && Array.isArray(m.observers)) ? m.observers : [];
+    const prim = obs.filter(function (o) { return o && o.role === "primary"; })[0] || null;
+    const ind = obs.filter(function (o) { return o && o.role === "independent"; });
+    if (rp === false)
+        return { verdict: "corrected", effect: "withdrawn", rule: "the rule, run again over the exact bytes the disputed scan received, does not hold: the finding was wrong when it was made" };
+    if (!prim || prim.finding_present === null || prim.finding_present === undefined)
+        return { verdict: "inconclusive", effect: "stands_unresolved", rule: "the primary observer could not re-measure the site" };
+    const decided = ind.filter(function (o) { return o.finding_present === true || o.finding_present === false; });
+    const agreeIn = ind.filter(function (o) { return o.finding_present !== true && o.finding_present !== false && o.inputs_agree === true; });
+    const differIn = ind.filter(function (o) { return o.finding_present !== true && o.finding_present !== false && o.inputs_agree === false; });
+    if (!decided.length && !agreeIn.length && !differIn.length)
+        return { verdict: "inconclusive", effect: "stands_unresolved", rule: "no independent observer gave a usable reading before the deadline" };
+    if (decided.some(function (o) { return o.finding_present !== prim.finding_present; }) || differIn.length)
+        return { verdict: "vantage_dependent", effect: "stands_with_scope", rule: "an independent network received something different from the primary observer: the finding holds only for the network that saw it" };
+    if (prim.finding_present === true)
+        return { verdict: "upheld", effect: "stands", rule: "the rule holds over the original bytes and the condition is still present from every network that re-measured it" };
+    if (rp === true)
+        return { verdict: "fixed_since", effect: "stands_for_record", rule: "the rule holds over the original bytes, and every network now finds the condition gone: correct when made, fixed since" };
+    return { verdict: "no_longer_observed", effect: "stands_for_record", rule: "every network now finds the condition gone, and the original bytes could not be re-checked, so whether it was ever wrong cannot be decided" };
+}
+export async function verifyResolution(x) {
+    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 (!x || x.kind !== "crawlcheck-dispute-resolution" || !x.signature)
+        throw new Error("not a CrawlCheck dispute resolution");
+    const body = {};
+    for (const k of Object.keys(x))
+        if (k !== "resolution_id" && k !== "signature")
+            body[k] = x[k];
+    const sha = hex(await sha256(enc.encode(canon(body))));
+    C("resolution_hash", sha === x.signature.resolution_sha256 && x.resolution_id === "dr1:" + sha, sha === x.signature.resolution_sha256 ? "the resolution hashes to its id " + sha.slice(0, 16) + "…" : "the resolution hashes to " + sha + ", it claims " + x.signature.resolution_sha256 + " - a field was changed");
+    const jwk = x.issuer && x.issuer.key && x.issuer.key.jwk;
+    if (!jwk || !jwk.x) {
+        C("key_id", null, "no key in the resolution");
+        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 === x.signature.kid, thumb === x.signature.kid ? "public key thumbprint (RFC 7638) is the key id " + thumb.slice(0, 12) + "…; the same id is published in " + (x.issuer.key.published_in || "the key directory") : "thumbprint " + thumb + " does not match key id " + x.signature.kid);
+        const msg = DSP_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 = x.signature.message === msg && await subtle.verify({ name: "Ed25519" }, pk, b64(x.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 resolution digest verifies" : "signature does NOT verify over this content");
+    }
+    C("key_published", null, "offline this cannot be decided: compare key id " + (x.signature.kid || "?") + " with the ids published at " + ((x.issuer && x.issuer.key && x.issuer.key.published_in) || "the key directory"));
+    const dv = dspVerdict(x.remeasurement || {});
+    const said = x.decision || {};
+    C("verdict_derivable", dv.verdict === said.verdict && dv.effect === said.effect, "the decision table over the recorded readings gives " + dv.verdict + " / " + dv.effect + "; the record says " + (said.verdict || "?") + " / " + (said.effect || "?"));
+    const obs = (x.remeasurement && x.remeasurement.observers) || [];
+    const t0 = x.dispute && Date.parse(x.dispute.ownership && x.dispute.ownership.at || x.dispute.filed_at);
+    const late = obs.filter((o) => o && o.at && isFinite(t0) && Date.parse(o.at) < t0);
+    C("readings_after_dispute", obs.length ? late.length === 0 : null, obs.length ? (late.length ? late.length + " reading(s) predate the dispute: a re-measurement must come after it" : "every reading (" + obs.length + ") was taken after the dispute was accepted") : "no readings recorded");
+    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",
+        resolution: { id: x.resolution_id, dispute: x.dispute_id, domain: x.subject && x.subject.domain, code: x.subject && x.subject.finding && x.subject.finding.code, verdict: said.verdict, effect: said.effect, observers: obs.map((o) => o.observer_id + "@" + (o.network_class || "?")) }, checks,
+        note: "Every check used only the resolution itself. To confirm the key is CrawlCheck's, compare its id with " + ((x.issuer && x.issuer.key && x.issuer.key.published_in) || "the published key directory") + "; to check a reading, open the record or the signed observation it links." };
+}
+// ── data inventories, export parts and deletion records ─────────────────────────────────────────────────────────
+// Signed over sha256(canonical JSON of every field except sha256 and signature) with the prefix below. A deletion
+// record carries counts per family and the digest of the sorted deleted-key list, never the data.
+const DATA_SIG_PREFIX = "crawlcheck-data-v1\n";
+export async function verifyDataDoc(x) {
+    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 (!x || !/^crawlcheck-(data-inventory|data-export-part|deletion-record|resolve|decision)$/.test(String(x.kind)) || !x.signature)
+        throw new Error("not a CrawlCheck data inventory, export part, deletion record, resolve answer or decision receipt");
+    const body = {};
+    for (const k of Object.keys(x))
+        if (k !== "sha256" && k !== "signature")
+            body[k] = x[k];
+    const sha = hex(await sha256(enc.encode(canon(body))));
+    C("document_hash", sha === x.sha256, sha === x.sha256 ? "the document hashes to its stated digest " + sha.slice(0, 16) + "…" : "the document hashes to " + sha + ", it states " + x.sha256 + " - a field was changed");
+    const jwk = x.signature.key && x.signature.key.jwk;
+    if (!jwk || !jwk.x) {
+        C("key_id", null, "no key in the document");
+        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 === x.signature.kid, thumb === x.signature.kid ? "public key thumbprint (RFC 7638) is the key id " + thumb.slice(0, 12) + "…" : "thumbprint " + thumb + " does not match key id " + x.signature.kid);
+        const msg = DATA_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 = x.signature.message === msg && await subtle.verify({ name: "Ed25519" }, pk, b64(x.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 document digest verifies" : "signature does NOT verify over this content");
+    }
+    C("key_published", null, "offline this cannot be decided: compare key id " + (x.signature.kid || "?") + " with the ids published at " + ((x.signature.key && x.signature.key.published_in) || "the key directory"));
+    if (x.kind === "crawlcheck-data-export-part" && x.inventory) {
+        let iv = null;
+        try {
+            iv = await verifyDataDoc(x.inventory);
+        }
+        catch (e) {
+            iv = null;
+        }
+        C("inventory", !!(iv && iv.verified && x.inventory.sha256 === x.inventory_sha256), iv && iv.verified ? "the part carries the signed inventory it names" : "the inventory inside this part does not verify or is not the one named");
+    }
+    if (x.kind === "crawlcheck-decision") {
+        const r = x.resolve || {};
+        C("resolve_bound", /^[0-9a-f]{64}$/.test(String(r.sha256 || "")) && r.kid === x.signature.kid, /^[0-9a-f]{64}$/.test(String(r.sha256 || "")) ? "the decision names the resolve answer it was made from (" + String(r.sha256).slice(0, 16) + "…), signed by the same key" : "the decision does not name a resolve answer digest");
+        C("decision_known", ["allow", "warn", "require_confirmation", "block", "unsupported"].indexOf(x.decision) >= 0, "decision is " + x.decision);
+    }
+    if (x.kind === "crawlcheck-deletion-record")
+        C("counts", (x.deleted || []).reduce((a, f) => a + (f.keys || 0), 0) === x.deleted_total, "the per-family counts add up to deleted_total (" + x.deleted_total + ")");
+    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", document: { kind: x.kind, domain: x.domain, sha256: x.sha256 }, checks };
+}
 // ── 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.
@@ -326,20 +552,35 @@ catch (e) {
 if (isMain) {
     const f = process.argv[2];
     if (!f) {
-        console.log("usage: node crawlcheck-verify.mjs <bundle.json>");
+        console.log("usage: node crawlcheck-verify.mjs <bundle.json | receipt.json | export.json | resolution.json | deletion.json | answer.json | decision.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 isEx = doc && doc.kind === "crawlcheck-evidence-export";
+    const isDr = doc && doc.kind === "crawlcheck-dispute-resolution";
+    const isDt = doc && /^crawlcheck-(data-inventory|data-export-part|deletion-record|resolve|decision)$/.test(String(doc.kind));
+    const res = isDt ? await verifyDataDoc(doc) : isDr ? await verifyResolution(doc) : isEx ? await verifyExport(doc) : isRc ? await verifyReceipt(doc.kind ? doc : doc.receipt) : await verifyBundle(doc);
     const mark = (ok) => ok === true ? "PASS" : ok === false ? "FAIL" : " -- ";
-    if (isRc)
+    if (isDt)
+        console.log("CrawlCheck " + doc.kind.replace("crawlcheck-", "").replace(/-/g, " ") + ": " + (doc.domain || "?") + " " + String(doc.sha256 || "").slice(0, 16) + "…");
+    else if (isDr)
+        console.log("CrawlCheck dispute resolution: " + (res.resolution.id || "?").slice(0, 24) + "… " + (res.resolution.domain || "") + " " + (res.resolution.code || "") + " verdict " + (res.resolution.verdict || "?"));
+    else if (isEx)
+        console.log("CrawlCheck evidence export: " + (res.export.domain || "?") + " " + (res.export.window ? res.export.window.from + " to " + res.export.window.to : "") + " (" + res.export.records + " records, " + res.export.receipts + " receipts)");
+    else 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(mark(c.ok) + "  " + c.id.padEnd(23) + c.why);
+    if (isEx)
+        for (const r of res.records)
+            console.log(mark(r.verified) + "    record " + String(r.id || "?").padEnd(14) + (r.failed && r.failed.length ? "failed: " + r.failed.join(", ") : (r.why || (r.ran + " checks ran"))));
+    if (isEx)
+        for (const r of res.receipts)
+            console.log(mark(r.verified) + "    receipt " + String(r.id || "?").slice(0, 20) + (r.failed && r.failed.length ? " failed: " + r.failed.join(", ") : ""));
     console.log(res.summary);
     process.exit(res.checks.some((c) => c.ok === false) ? 1 : 0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crawlcheck/sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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",
@@ -21,6 +21,14 @@
   },
   "sideEffects": false,
   "homepage": "https://crawlcheck.io/sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emmanuelorta/crawlcheck.git",
+    "directory": "sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/emmanuelorta/crawlcheck/issues"
+  },
   "keywords": [
     "crawlcheck",
     "verification",
@@ -34,4 +42,4 @@
   "scripts": {
     "test": "node --test test/*.test.js"
   }
-}
+}

package/test/sdk.test.js

@@ -1,6 +1,6 @@
 // Runs against the live API. npm test
 import test from "node:test"; import assert from "node:assert/strict";
-import { CrawlCheck, verifyBundle, verifyReceipt, CrawlCheckError } from "../dist/index.js";
+import { CrawlCheck, verifyBundle, verifyReceipt, CrawlCheckError, verifyDocument } from "../dist/index.js";
 const c = new CrawlCheck();
 
 test("conformance: every published fixture gives its expected output through this package's verifier", async () => {
@@ -43,3 +43,21 @@ test("a tampered live bundle fails offline", async () => {
 test("locked data surfaces as a typed error, not a crash", async () => {
   await assert.rejects(c.impact({ domain: "wikipedia.org" }), (e) => e instanceof CrawlCheckError && e.locked === true && e.status === 403);
 });
+
+test("live preflight: the decision receipt verifies offline, its key is published, a changed decision fails, guard agrees", async () => {
+  const rc = await c.preflight("example.com", "read");
+  assert.equal(rc.kind, "crawlcheck-decision");
+  assert.ok(["allow", "warn", "require_confirmation", "block", "unsupported"].includes(rc.decision));
+  const v = await c.verifyDocument(rc);
+  assert.equal(v.verified, true, JSON.stringify(v.checks));
+  for (const id of ["document_hash", "key_id", "signature", "key_published", "resolve_bound", "decision_known"]) assert.equal(v.checks.find((c) => c.id === id)?.ok, true, id);
+  const forged = JSON.parse(JSON.stringify(rc)); forged.decision = rc.decision === "allow" ? "block" : "allow";
+  const f = await verifyDocument(forged);
+  assert.equal(f.verified, false);
+  assert.equal(f.checks.find((c) => c.id === "document_hash").ok, false);
+  const g = await c.guard("example.com", "read");
+  assert.equal(g.verification.verified, true);
+  assert.equal(g.proceed, g.receipt.decision === "allow");
+  const r = await c.resolve("example.com");
+  assert.equal((await verifyDocument(r)).verified, true);
+});