@crawlcheck/sdk 1.0.2 → 1.0.4

package/README.md

@@ -16,6 +16,8 @@ const { proceed, receipt } = await cc.guard("example.com", "read", { agent: "MyA
 // The receipt is a signed crawlcheck-decision; guard() verified it here and checked its key against the published directory.
 ```
 
+Every verification returns `integrity_valid`, `issuer_trusted` and `accepted`. Act on `accepted`: it needs the signing key to be one CrawlCheck publishes, so a document someone signed with their own key is `verified` offline but never `accepted`. The client methods (`verifyDocument`, `verifyOffline`, `verifyReceiptOffline`, `guard`) check the published key directory for you.
+
 `preflight(domain, action, { agent, template, policy })` returns the signed receipt without deciding for you; `verifyDocument(doc)` verifies any signed resolve answer or decision receipt offline. `resolve(domain)` returns the full signed ResolveV1 answer.
 
 ## Read a record

package/dist/index.d.ts

@@ -7,7 +7,17 @@ export interface VerifyCheck {
     why: string;
     [k: string]: unknown;
 }
-export interface BundleVerification {
+/**
+ * Three separate answers. integrity_valid: hashes and the signature agree with the document. issuer_trusted: the
+ * signing key is one CrawlCheck publishes (null offline: not decided). accepted: both - the only field to act on.
+ * A document someone else signed with their own key is verified: true offline and accepted: false.
+ */
+export interface Trust {
+    integrity_valid: boolean;
+    issuer_trusted: boolean | null;
+    accepted: boolean;
+}
+export interface BundleVerification extends Partial<Trust> {
     verified: boolean;
     summary: string;
     report: {
@@ -19,7 +29,7 @@ export interface BundleVerification {
     experiences: number | null;
     note: string;
 }
-export interface ReceiptVerification {
+export interface ReceiptVerification extends Partial<Trust> {
     verified: boolean;
     summary: string;
     receipt: {
@@ -36,7 +46,7 @@ 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 {
+export interface DocumentVerification extends Partial<Trust> {
     verified: boolean;
     summary: string;
     document: {
@@ -47,7 +57,7 @@ export interface DocumentVerification {
     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>;
+export declare const verifyDocument: (doc: unknown) => Promise<DocumentVerification & Trust>;
 /** Verify a signed evidence export (and every bundle and receipt inside it) offline. */
 export declare const verifyExport: (x: unknown) => Promise<{
     verified: boolean;
@@ -105,6 +115,29 @@ export type BodyOf<P extends keyof paths> = Op<P, "post"> extends {
     };
 } ? B : JsonObject;
 export type Action = "read" | "cite" | "connect" | "transact" | "administer";
+/** The header an agent sends with its request so the site can see it checked CrawlCheck first. */
+export declare const RECEIPT_HEADER = "CrawlCheck-Receipt";
+/** The domain the way CrawlCheck hashes and stores it: lowercased, no scheme, no leading www., no path or port. "" when not a domain. */
+export declare function normalizeDomain(v: string): string;
+/** { "CrawlCheck-Receipt": "v=1; sha256=..." } for a decision receipt. Send it only to the domain the receipt names, before expires_at. */
+export declare function receiptHeader(receipt: {
+    sha256: string;
+}): Record<string, string>;
+export interface PrivateLookup {
+    found: boolean;
+    ready: boolean;
+    in_bucket: number | null;
+    answer: JsonObject | null;
+    verification: (DocumentVerification & Trust) | null;
+    accepted: boolean;
+    why?: string;
+}
+export interface ReceiptCheck {
+    accept: boolean;
+    why: string;
+    check: JsonObject | null;
+    verification: (DocumentVerification & Trust) | null;
+}
 export type Decision = "allow" | "warn" | "require_confirmation" | "block" | "unsupported";
 export interface PreflightPolicy {
     max_age_hours?: number;
@@ -188,13 +221,18 @@ export declare class CrawlCheck {
     /** 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>;
+    verifyDocument(doc: unknown, onlineKeys?: boolean): Promise<DocumentVerification & Trust>;
     /** 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;
+        verification: DocumentVerification & Trust;
+        header: Record<string, string> | null;
     }>;
+    /** Look a domain up without sending it: only the first prefixLen hex characters of sha256(domain) leave this process. found false with ready true means no public measurement. */
+    resolvePrivate(domain: string, prefixLen?: number): Promise<PrivateLookup>;
+    /** For sites: check a CrawlCheck-Receipt header received with a request to host. accept only when the receipt is held, names host, has not expired, decided allow or warn, and verifies with a published key. */
+    checkReceiptHeader(headerValue: string, host: string): Promise<ReceiptCheck>;
     /** 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. */
@@ -219,11 +257,11 @@ export declare class CrawlCheck {
     /** 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>;
+    verifyOffline(id: string): Promise<BundleVerification & Trust>;
     /** 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>;
+    verifyReceiptOffline(id: string): Promise<ReceiptVerification & Trust>;
     /** 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>;

package/dist/index.js

@@ -1,10 +1,24 @@
 import * as V from "./verify.js";
+function withTrust(v, kid, published) {
+    let checks = v.checks;
+    let issuer = null;
+    if (published) {
+        issuer = !!kid && published.includes(kid);
+        const kc = { id: "key_published", ok: issuer, why: issuer ? "key id " + kid + " is in the published key directory" : "key id " + (kid || "?") + " is NOT in the published key directory - reject this document" };
+        checks = checks.some((c) => c.id === "key_published") ? checks.map((c) => c.id === "key_published" ? kc : c) : checks.concat([kc]);
+    }
+    const ran = checks.filter((c) => c.ok !== null), failed = checks.filter((c) => c.ok === false);
+    const verified = ran.length > 0 && failed.length === 0;
+    const integrity_valid = checks.filter((c) => c.id !== "key_published").every((c) => c.ok !== false);
+    return Object.assign({}, v, { checks, verified, summary: failed.length ? failed.length + " check(s) FAILED" : ran.length + " of " + checks.length + " checks ran and passed",
+        integrity_valid, issuer_trusted: issuer, accepted: verified && issuer === true });
+}
 /** 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;
 /** Verify a signed resolve answer, preflight decision receipt, data inventory, export part or deletion record offline. */
-export const verifyDocument = V.verifyDataDoc;
+export const verifyDocument = async (doc) => withTrust(await V.verifyDataDoc(doc), doc?.signature?.kid, null);
 /** 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). */
@@ -12,6 +26,19 @@ export const verifyResolution = V.verifyResolution;
 export const canon = V.canon;
 export const merkleRootHex = V.merkleRootHex;
 export const otsInspect = V.otsInspect;
+/** The header an agent sends with its request so the site can see it checked CrawlCheck first. */
+export const RECEIPT_HEADER = "CrawlCheck-Receipt";
+/** The domain the way CrawlCheck hashes and stores it: lowercased, no scheme, no leading www., no path or port. "" when not a domain. */
+export function normalizeDomain(v) {
+    const d = String(v ?? "").trim().toLowerCase().replace(/^https?:\/\//, "").replace(/^www\./, "").replace(/[\/?#].*$/, "").replace(/:\d+$/, "");
+    return /^[a-z0-9-]+(\.[a-z0-9-]+)+$/.test(d) ? d : "";
+}
+/** { "CrawlCheck-Receipt": "v=1; sha256=..." } for a decision receipt. Send it only to the domain the receipt names, before expires_at. */
+export function receiptHeader(receipt) { return { [RECEIPT_HEADER]: "v=1; sha256=" + receipt.sha256 }; }
+async function sha256Hex(s) {
+    const b = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(s));
+    return Array.from(new Uint8Array(b), (x) => x.toString(16).padStart(2, "0")).join("");
+}
 export class CrawlCheckError extends Error {
     status;
     body;
@@ -67,26 +94,62 @@ export class CrawlCheck {
     }
     /** 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 };
+        return withTrust(await V.verifyDataDoc(doc), doc?.signature?.kid, onlineKeys ? await this.publishedKeyIds() : null);
     }
     /** 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.accepted && (opts.onlineKeys ?? true))
+            return { proceed: false, receipt, verification, header: null };
         if (!verification.verified)
-            return { proceed: false, receipt, verification };
+            return { proceed: false, receipt, verification, header: null };
         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 };
+        return { proceed, receipt, verification, header: proceed ? receiptHeader(receipt) : null };
+    }
+    /** Look a domain up without sending it: only the first prefixLen hex characters of sha256(domain) leave this process. found false with ready true means no public measurement. */
+    async resolvePrivate(domain, prefixLen = 2) {
+        const d = normalizeDomain(domain);
+        if (!d)
+            throw new Error("not a domain name: " + domain);
+        if (prefixLen < 2 || prefixLen > 8)
+            throw new Error("prefixLen must be 2 to 8");
+        const h = await sha256Hex(d);
+        let r;
+        try {
+            r = await this.req("GET", "/api/v1/resolve-prefix/" + h.slice(0, prefixLen));
+        }
+        catch (e) {
+            if (e instanceof CrawlCheckError && e.status === 503)
+                return { found: false, ready: false, in_bucket: null, answer: null, verification: null, accepted: false, why: "the prefix index is not built yet" };
+            throw e;
+        }
+        const hit = (r.answers || []).find((a) => a.domain_sha256 === h);
+        if (!hit)
+            return { found: false, ready: true, in_bucket: r.in_bucket ?? null, answer: null, verification: null, accepted: false };
+        const verification = await this.verifyDocument(hit.answer);
+        return { found: true, ready: true, in_bucket: r.in_bucket ?? null, answer: hit.answer, verification, accepted: !!verification.accepted && normalizeDomain(hit.answer.domain) === d };
+    }
+    /** For sites: check a CrawlCheck-Receipt header received with a request to host. accept only when the receipt is held, names host, has not expired, decided allow or warn, and verifies with a published key. */
+    async checkReceiptHeader(headerValue, host) {
+        const m = String(headerValue || "").match(/sha256=([0-9a-fA-F]{64})/) || String(headerValue || "").trim().match(/^([0-9a-fA-F]{64})$/);
+        if (!m)
+            return { accept: false, why: "no receipt digest in the header", check: null, verification: null };
+        const sha = m[1].toLowerCase(), h = normalizeDomain(host);
+        let r;
+        try {
+            r = await this.req("GET", "/api/v1/decisions/" + sha, { host: h });
+        }
+        catch (e) {
+            if (e instanceof CrawlCheckError && e.status === 404)
+                return { accept: false, why: "CrawlCheck holds no receipt with that digest", check: e.body, verification: null };
+            throw e;
+        }
+        const rc = r.receipt || {}, verification = await this.verifyDocument(rc);
+        return { accept: !!r.accept && !!verification.accepted && rc.sha256 === sha && normalizeDomain(rc.domain) === h, why: r.reason, check: r, verification };
     }
     /** Signed change feed (what changed since a time, optionally for one domain). */
     changes(q = {}) { return this.get("/api/v1/changes", q); }
@@ -112,11 +175,11 @@ export class CrawlCheck {
     /** 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)); }
+    async verifyOffline(id) { const b = await this.bundle(id); return withTrust(await verifyBundle(b), b?.manifest?.signature?.kid, await this.publishedKeyIds()); }
     /** 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)); }
+    async verifyReceiptOffline(id) { const rc = await this.receipt(id); return withTrust(await verifyReceipt(rc), rc?.signature?.kid, await this.publishedKeyIds()); }
     /** 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");

package/dist/verify.d.ts

@@ -4,88 +4,15 @@ 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;
-}>;
-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[];
-}>;
+export function trustOf(res: any, kid: any, publishedKids: any): any;
+export function publishedKeyIds(base: any): Promise<string[]>;
+export function verifyBundle(b: any, opts: any): Promise<any>;
+export function verifyReceipt(rc: any, opts: any): Promise<any>;
+export function verifyExport(x: any, opts: any): Promise<any>;
+export function verifyResolution(x: any, opts: any): Promise<any>;
+export function verifyDataDoc(x: any, opts: any): Promise<any>;

package/dist/verify.js

@@ -20,6 +20,14 @@
 //   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.
+// Every result also separates the questions a single "verified" used to answer at once (vt1, 2026-10-06):
+//   integrity_valid   no check over the bytes failed (hashes, signature, proof paths)
+//   issuer_trusted    the signing key is in CrawlCheck's published key directory: true / false, or null offline
+//   accepted          integrity_valid AND issuer_trusted === true. Act on this, never on verified alone.
+//   accepted_strict   accepted AND every check ran (legacy and pre-manifest records stay false: less was sealed)
+//   assurance         "complete" or "partial", with unavailable[] naming the checks that could not run
+// Offline, issuer_trusted is null and accepted is false. Close it with --online (fetches the key directory) or
+// pass the published key ids yourself: verifyReceipt(doc, { publishedKids: [...] }).
 // 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";
@@ -136,7 +144,7 @@ export async function otsInspect(u8) {
     return { digest: hex(digest), attestations };
 }
 // ── the bundle ────────────────────────────────────────────────────────────────
-export async function verifyBundle(b) {
+async function verifyBundle0(b) {
     if (!subtle)
         throw new Error("this runtime has no WebCrypto (crypto.subtle)");
     const checks = [];
@@ -274,7 +282,7 @@ export async function verifyBundle(b) {
 // 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) {
+async function verifyReceipt0(rc) {
     if (!subtle)
         throw new Error("this runtime has no WebCrypto (crypto.subtle)");
     const checks = [];
@@ -322,7 +330,7 @@ export async function verifyReceipt(rc) {
 // 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) {
+async function verifyExport0(x) {
     if (!subtle)
         throw new Error("this runtime has no WebCrypto (crypto.subtle)");
     const checks = [];
@@ -432,7 +440,7 @@ export function dspVerdict(m) {
         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) {
+async function verifyResolution0(x) {
     if (!subtle)
         throw new Error("this runtime has no WebCrypto (crypto.subtle)");
     const checks = [];
@@ -483,13 +491,13 @@ export async function verifyResolution(x) {
 // 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) {
+async function verifyDataDoc0(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");
+    if (!x || !/^crawlcheck-(data-inventory|data-export-part|deletion-record|resolve|decision|snapshot)$/.test(String(x.kind)) || !x.signature)
+        throw new Error("not a CrawlCheck data inventory, export part, deletion record, resolve answer, decision receipt or snapshot manifest");
     const body = {};
     for (const k of Object.keys(x))
         if (k !== "sha256" && k !== "signature")
@@ -533,6 +541,10 @@ export async function verifyDataDoc(x) {
         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-snapshot") {
+        const ps = Array.isArray(x.parts) ? x.parts : [];
+        C("parts", ps.length > 0 && ps.every((p) => /^part-\d{4}\.ndjson\.gz$/.test(String(p.path)) && /^[0-9a-f]{64}$/.test(String(p.sha256)) && p.records > 0) && ps.reduce((a, p) => a + p.records, 0) === x.records, ps.reduce((a, p) => a + (p.records || 0), 0) === x.records ? ps.length + " parts, " + x.records + " records; check each downloaded part with sha256sum against its sha256, then each line with this tool" : "the parts' record counts do not add up to records (" + x.records + ")");
+    }
     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);
@@ -541,6 +553,43 @@ export async function verifyDataDoc(x) {
 // ── 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.
+// vt1: integrity, issuer trust and completeness, reported apart. Same semantics as @crawlcheck/sdk and the Python package.
+export function trustOf(res, kid, publishedKids) {
+    let checks = Array.isArray(res && res.checks) ? res.checks : [];
+    let issuer = null;
+    if (Array.isArray(publishedKids)) {
+        issuer = !!kid && publishedKids.indexOf(kid) > -1;
+        const kc = { id: "key_published", ok: issuer, why: issuer ? "key id " + kid + " is in the published key directory" : !kid ? "this document carries no signature, so its issuer cannot be authenticated" : "key id " + kid + " is NOT in the published key directory: reject this document" };
+        checks = checks.some((c) => c.id === "key_published") ? checks.map((c) => c.id === "key_published" ? kc : c) : checks.concat([kc]);
+    }
+    const ran = checks.filter((c) => c.ok !== null), failed = checks.filter((c) => c.ok === false);
+    const unavailable = checks.filter((c) => c.ok === null && c.id !== "key_published").map((c) => c.id);
+    const verified = ran.length > 0 && failed.length === 0;
+    const integrity_valid = ran.some((c) => c.id !== "key_published") && checks.filter((c) => c.id !== "key_published").every((c) => c.ok !== false);
+    const accepted = integrity_valid && issuer === true;
+    return Object.assign({}, res, { checks, verified, summary: failed.length ? failed.length + " check(s) FAILED" : ran.length + " of " + checks.length + " checks ran and passed",
+        integrity_valid, issuer_trusted: issuer, accepted, accepted_strict: accepted && unavailable.length === 0,
+        assurance: unavailable.length ? "partial" : "complete", unavailable });
+}
+// The published Ed25519 key ids (RFC 7638 thumbprints) from the observer's key directory.
+export async function publishedKeyIds(base) {
+    const r = await fetch(String(base || "https://crawlcheck.io").replace(/\/+$/, "") + "/.well-known/http-message-signatures-directory");
+    if (!r.ok)
+        throw new Error("key directory answered HTTP " + r.status);
+    const d = await r.json(), out = [];
+    for (const k of (d && d.keys) || []) {
+        if (!k || !k.x)
+            continue;
+        out.push(b64u(await sha256(enc.encode(JSON.stringify({ crv: k.crv, kty: k.kty, x: k.x })))));
+    }
+    return out;
+}
+const kidOf = (o) => (o && o.signature && o.signature.kid) || (o && o.manifest && o.manifest.signature && o.manifest.signature.kid) || undefined;
+export async function verifyBundle(b, opts) { return trustOf(await verifyBundle0(b), b && b.manifest && b.manifest.signature && b.manifest.signature.kid, opts && opts.publishedKids); }
+export async function verifyReceipt(rc, opts) { return trustOf(await verifyReceipt0(rc), rc && rc.signature && rc.signature.kid, opts && opts.publishedKids); }
+export async function verifyExport(x, opts) { return trustOf(await verifyExport0(x), kidOf(x), opts && opts.publishedKids); }
+export async function verifyResolution(x, opts) { return trustOf(await verifyResolution0(x), kidOf(x), opts && opts.publishedKids); }
+export async function verifyDataDoc(x, opts) { return trustOf(await verifyDataDoc0(x), kidOf(x), opts && opts.publishedKids); }
 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");
@@ -550,9 +599,10 @@ catch (e) {
     return false;
 } })();
 if (isMain) {
-    const f = process.argv[2];
+    const online = process.argv.includes("--online");
+    const f = process.argv.slice(2).filter((a) => a !== "--online")[0];
     if (!f) {
-        console.log("usage: node crawlcheck-verify.mjs <bundle.json | receipt.json | export.json | resolution.json | deletion.json | answer.json | decision.json>");
+        console.log("usage: node crawlcheck-verify.mjs <bundle.json | receipt.json | export.json | resolution.json | deletion.json | answer.json | decision.json | manifest.json>");
         process.exit(2);
     }
     const { readFile } = await import("node:fs/promises");
@@ -560,8 +610,18 @@ if (isMain) {
     const isRc = doc && (doc.kind === "crawlcheck-remediation-receipt" || (doc.receipt && doc.receipt.kind === "crawlcheck-remediation-receipt"));
     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 isDt = doc && /^crawlcheck-(data-inventory|data-export-part|deletion-record|resolve|decision|snapshot)$/.test(String(doc.kind));
+    let kids;
+    if (online) {
+        try {
+            kids = await publishedKeyIds();
+        }
+        catch (e) {
+            console.log("could not read the published key directory: " + e.message);
+        }
+    }
+    const vo = { publishedKids: kids };
+    const res = isDt ? await verifyDataDoc(doc, vo) : isDr ? await verifyResolution(doc, vo) : isEx ? await verifyExport(doc, vo) : isRc ? await verifyReceipt(doc.kind ? doc : doc.receipt, vo) : await verifyBundle(doc, vo);
     const mark = (ok) => ok === true ? "PASS" : ok === false ? "FAIL" : " -- ";
     if (isDt)
         console.log("CrawlCheck " + doc.kind.replace("crawlcheck-", "").replace(/-/g, " ") + ": " + (doc.domain || "?") + " " + String(doc.sha256 || "").slice(0, 16) + "…");
@@ -582,5 +642,7 @@ if (isMain) {
         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);
+    console.log("integrity " + (res.integrity_valid ? "valid" : "NOT valid") + " · issuer " + (res.issuer_trusted === true ? "trusted (key published)" : res.issuer_trusted === false ? "NOT trusted (key not published)" : "not checked offline: run with --online") + " · assurance " + res.assurance + (res.unavailable.length ? " (" + res.unavailable.join(", ") + " could not run)" : ""));
+    console.log(res.accepted ? (res.accepted_strict ? "ACCEPTED" : "ACCEPTED, partial assurance") : "NOT ACCEPTED" + (res.integrity_valid && res.issuer_trusted === null ? ": issuer unknown offline" : ""));
     process.exit(res.checks.some((c) => c.ok === false) ? 1 : 0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crawlcheck/sdk",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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/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, verifyDocument } from "../dist/index.js";
+import { CrawlCheck, verifyBundle, verifyReceipt, CrawlCheckError, verifyDocument, normalizeDomain, receiptHeader } from "../dist/index.js";
 const c = new CrawlCheck();
 
 test("conformance: every published fixture gives its expected output through this package's verifier", async () => {
@@ -59,5 +59,30 @@ test("live preflight: the decision receipt verifies offline, its key is publishe
   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);
+  const off = await verifyDocument(r);
+  assert.equal(off.verified, true); assert.equal(off.issuer_trusted, null); assert.equal(off.accepted, false, "offline is never accepted");
+  assert.equal((await c.verifyDocument(r)).accepted, true);
+  const ids = await c.publishedKeyIds();
+  const ix = await (await fetch(c.base + "/conformance/index.json")).json();
+  const foreign = await (await fetch(ix.fixtures.find((x) => x.name === "receipt-foreign-key").file)).json();
+  assert.equal((await verifyReceipt(foreign)).verified, true, "self-consistent offline");
+  assert.ok(!ids.includes(foreign.signature.kid), "but not a CrawlCheck key, so never accepted");
+});
+
+test("receipt header: a site accepts the receipt for its own host only", async () => {
+  const rc = await c.preflight("github.com", "read", { agent: "crawlcheck-sdk-test" });
+  const hv = receiptHeader(rc)["CrawlCheck-Receipt"];
+  assert.match(hv, /^v=1; sha256=[0-9a-f]{64}$/);
+  const ok = await c.checkReceiptHeader(hv, "https://www.github.com/x");
+  assert.equal(ok.accept, rc.decision === "allow" || rc.decision === "warn", JSON.stringify(ok.why));
+  assert.equal((await c.checkReceiptHeader(hv, "gitlab.com")).accept, false);
+  assert.equal((await c.checkReceiptHeader("v=1; sha256=" + "c".repeat(64), "github.com")).accept, false);
 });
+
+test("private lookup sends only a hash prefix and verifies what it finds", async () => {
+  const r = await c.resolvePrivate("github.com");
+  assert.ok(r.ready === true || r.ready === false);
+  if (r.found) { assert.equal(r.accepted, true); assert.equal(r.answer.domain, "github.com"); }
+  assert.equal(normalizeDomain("HTTPS://WWW.Example.com:443/a?b"), "example.com");
+});
+