@crawlcheck/sdk 1.0.6 → 1.0.8

package/README.md

@@ -37,6 +37,19 @@ await cc.get("/api/explain", { domain: "example.com", code: "NO_LLMS_TXT" });
 await cc.get("/api/explain", { website: "x" });   // compile error: not a parameter of this operation
 ```
 
+## Use the site's staple
+
+A site can serve its own signed verdict in the `CrawlCheck-Staple` header (and at `/.well-known/crawlcheck-staple.json`). `resolveFor` uses it when it verifies, with no request to CrawlCheck, and falls back to a signed lookup when it is missing, expired, for another domain or tampered:
+
+```js
+const res = await fetch("https://shop.example.com/");
+const v = await client.resolveFor("shop.example.com", { response: res });
+v.source;              // "staple" or "network"
+v.decisions.transact;  // allow | warn | require_confirmation | block | unsupported
+```
+
+`stapleCheck(record, { host, publishedKids })` does the offline check on its own. Spec: https://crawlcheck.io/spec/staple
+
 ## Do not trust the API: check the evidence yourself
 
 ```js

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { paths, components } from "./gen/openapi.js";
+import * as S from "./staple.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 {
@@ -328,6 +329,33 @@ export declare const verifyWitnessToken: (token: string, sthSha256: string, jwks
     claims?: JsonObject;
 }>;
 export declare const GITHUB_OIDC_JWKS = "https://token.actions.githubusercontent.com/.well-known/jwks";
+export type StapleDecisions = {
+    read: string | null;
+    cite: string | null;
+    connect: string | null;
+    transact: string | null;
+};
+export interface StapleCheck {
+    valid: boolean;
+    reason: string | null;
+    expired: boolean;
+    record: Record<string, string> | null;
+    decisions: StapleDecisions | null;
+}
+/** Parse a ccr1 record (CrawlCheck-Staple header value or <domain>._v.crawlcheck.io TXT). */
+export declare const parseStaple: (record: string) => {
+    fields: Record<string, string>;
+    body: string;
+    sig: string;
+};
+/** The CrawlCheck-Staple header of a response (fetch Response, Headers or a plain header map), or null. */
+export declare const stapleFromResponse: (res: unknown) => string | null;
+/** Verify a staple offline: published key, signature, the record names opts.host (or a parent), fresh_until in the future. Expired or foreign staples are never valid. */
+export declare const stapleCheck: (record: string, opts: {
+    host: string;
+    publishedKids: string[];
+    now?: number;
+}) => Promise<StapleCheck>;
 export interface ClientOptions {
     /** Licence key (cc_ + 32 hex). Without one, licence-gated fields come back withheld, exactly as on the website. */
     key?: string;
@@ -369,6 +397,23 @@ export declare class CrawlCheck {
     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<ResponseOf<"/api/v1/resolve", "get">>;
+    private kidCache;
+    /** The key ids CrawlCheck publishes (/.well-known/http-message-signatures-directory), cached for an hour. */
+    publishedKids(): Promise<string[]>;
+    /**
+     * The verdict for a domain, preferring a valid staple the site sent (opts.staple, or opts.response's CrawlCheck-Staple
+     * header): no request to CrawlCheck is made when the staple verifies. An expired, foreign or invalid staple is ignored
+     * and the signed answer is fetched instead; source says which was used and staple says why.
+     */
+    resolveFor(domain: string, opts?: {
+        staple?: string | null;
+        response?: unknown;
+    }): Promise<{
+        source: "staple" | "network";
+        decisions: StapleDecisions;
+        staple: StapleCheck | null;
+        answer?: unknown;
+    }>;
     /** Up to 100 domains in one call; each answer is a full signed ResolveV1 document. */
     resolveBatch(domains: string[]): Promise<any>;
     /** Split-view check: the current head, GitHub's witness co-signature on the last witnessed head, and the chain from it down to every head this client holds. Reports the heads it holds to /api/v1/log/gossip unless report is false. */

package/dist/index.js

@@ -1,5 +1,6 @@
 import * as V from "./verify.js";
 import * as L from "./log.js";
+import * as S from "./staple.js";
 function withTrust(v, kid, published) {
     let checks = v.checks;
     let issuer = null;
@@ -76,6 +77,12 @@ export const logGossip = L.logGossip;
 /** Verify the outside witness's co-signature: a GitHub OIDC JWT (RS256) whose audience is crawlcheck-sth:<head sha256>. */
 export const verifyWitnessToken = L.verifyWitnessToken;
 export const GITHUB_OIDC_JWKS = "https://token.actions.githubusercontent.com/.well-known/jwks";
+/** Parse a ccr1 record (CrawlCheck-Staple header value or <domain>._v.crawlcheck.io TXT). */
+export const parseStaple = S.parseStaple;
+/** The CrawlCheck-Staple header of a response (fetch Response, Headers or a plain header map), or null. */
+export const stapleFromResponse = S.stapleFromResponse;
+/** Verify a staple offline: published key, signature, the record names opts.host (or a parent), fresh_until in the future. Expired or foreign staples are never valid. */
+export const stapleCheck = S.stapleCheck;
 export class CrawlCheckError extends Error {
     status;
     body;
@@ -123,6 +130,41 @@ export class CrawlCheck {
         await logObserveAnswer(this.log, a).catch(() => null); // a head that contradicts one this client already holds is recorded in this.log.forks
         return a;
     }
+    kidCache = null;
+    /** The key ids CrawlCheck publishes (/.well-known/http-message-signatures-directory), cached for an hour. */
+    async publishedKids() {
+        if (this.kidCache && Date.now() - this.kidCache.at < 3600e3)
+            return this.kidCache.kids;
+        const r = await this.f(this.base + "/.well-known/http-message-signatures-directory", { headers: { accept: "application/json" } });
+        const j = await r.json();
+        const kids = ((j && j.keys) || []).map((k) => k.kid).filter(Boolean);
+        this.kidCache = { at: Date.now(), kids };
+        return kids;
+    }
+    /**
+     * The verdict for a domain, preferring a valid staple the site sent (opts.staple, or opts.response's CrawlCheck-Staple
+     * header): no request to CrawlCheck is made when the staple verifies. An expired, foreign or invalid staple is ignored
+     * and the signed answer is fetched instead; source says which was used and staple says why.
+     */
+    async resolveFor(domain, opts = {}) {
+        const rec = opts.staple || (opts.response ? stapleFromResponse(opts.response) : null);
+        let chk = null;
+        if (rec) {
+            let kids = [];
+            try {
+                kids = await this.publishedKids();
+            }
+            catch {
+                kids = [];
+            }
+            chk = await stapleCheck(rec, { host: normalizeDomain(domain), publishedKids: kids });
+            if (chk.valid && chk.decisions)
+                return { source: "staple", decisions: chk.decisions, staple: chk };
+        }
+        const a = await this.resolve(domain);
+        const act = (k) => (a && a.actions && a.actions[k] && a.actions[k].decision) || null;
+        return { source: "network", decisions: { read: act("read"), cite: act("cite"), connect: act("connect"), transact: act("transact") }, staple: chk, answer: a };
+    }
     /** Up to 100 domains in one call; each answer is a full signed ResolveV1 document. */
     async resolveBatch(domains) {
         const r = await this.post("/api/v1/resolve", { domains });

package/dist/staple.d.ts

@@ -0,0 +1,21 @@
+/** Parse a ccr1 record ("v=ccr1;d=...;s=..."); quoted TXT strings from dig are joined. */
+export function parseStaple(record: any): {
+    fields: {};
+    body: string;
+    sig: string;
+};
+/** The staple a response carries, if any (a fetch Response, a Headers object or a plain header map). */
+export function stapleFromResponse(res: any): any;
+/**
+ * Check a staple offline. opts.host: the host the agent is talking to (required for a usable result);
+ * opts.publishedKids: the key ids CrawlCheck publishes (from /.well-known/http-message-signatures-directory);
+ * opts.now: epoch ms (default Date.now()).
+ * Returns { valid, reason, expired, record, decisions } and never throws.
+ */
+export function stapleCheck(record: any, opts?: {}): Promise<{
+    valid: boolean;
+    reason: null;
+    expired: boolean;
+    record: null;
+    decisions: null;
+}>;

package/dist/staple.js

@@ -0,0 +1,88 @@
+// Stapled Resolve and Resolve over DNS: the compact ccr1 record a site sends in the CrawlCheck-Staple header (or that
+// <domain>._v.crawlcheck.io TXT carries). Verified offline: key id = RFC 7638 thumbprint of the public key, the key is
+// one CrawlCheck publishes, the Ed25519 signature covers the record, the record names the host (or a parent domain),
+// and fresh_until is in the future. An expired or foreign staple is never used.
+const STAPLE_PREFIX = "crawlcheck-dns-v1\n";
+const te = new TextEncoder();
+function b64uToBytes(s) { s = String(s || "").replace(/-/g, "+").replace(/_/g, "/"); s += "===".slice((s.length + 3) % 4); const b = atob(s), u = new Uint8Array(b.length); for (let i = 0; i < b.length; i++)
+    u[i] = b.charCodeAt(i); return u; }
+function bytesToB64u(u) { let s = ""; for (let i = 0; i < u.length; i++)
+    s += String.fromCharCode(u[i]); return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""); }
+/** Parse a ccr1 record ("v=ccr1;d=...;s=..."); quoted TXT strings from dig are joined. */
+export function parseStaple(record) {
+    const t = String(record || "").trim().replace(/"\s*"/g, "").replace(/^"|"$/g, "");
+    const i = t.lastIndexOf(";s=");
+    const body = i > 0 ? t.slice(0, i) : "", sig = i > 0 ? t.slice(i + 3) : "";
+    const f = {};
+    body.split(";").forEach((p) => { const j = p.indexOf("="); if (j > 0)
+        f[p.slice(0, j)] = p.slice(j + 1); });
+    return { fields: f, body, sig };
+}
+/** The staple a response carries, if any (a fetch Response, a Headers object or a plain header map). */
+export function stapleFromResponse(res) {
+    const h = res && (res.headers || res);
+    if (!h)
+        return null;
+    if (typeof h.get === "function")
+        return h.get("crawlcheck-staple");
+    for (const k of Object.keys(h))
+        if (k.toLowerCase() === "crawlcheck-staple")
+            return h[k];
+    return null;
+}
+/**
+ * Check a staple offline. opts.host: the host the agent is talking to (required for a usable result);
+ * opts.publishedKids: the key ids CrawlCheck publishes (from /.well-known/http-message-signatures-directory);
+ * opts.now: epoch ms (default Date.now()).
+ * Returns { valid, reason, expired, record, decisions } and never throws.
+ */
+export async function stapleCheck(record, opts = {}) {
+    const out = { valid: false, reason: null, expired: false, record: null, decisions: null };
+    try {
+        const { fields: f, body, sig } = parseStaple(record);
+        out.record = f;
+        if (f.v !== "ccr1" || !f.d || !f.k || !f.x || !sig) {
+            out.reason = "not a ccr1 record";
+            return out;
+        }
+        out.decisions = { read: f.read || null, cite: f.cite || null, connect: f.connect || null, transact: f.transact || null };
+        const now = opts.now || Date.now(), fu = Date.parse(f.f || "");
+        if (!isFinite(fu) || fu <= now) {
+            out.expired = true;
+            out.reason = "expired at " + (f.f || "?") + ": ask CrawlCheck instead";
+            return out;
+        }
+        const host = String(opts.host || "").toLowerCase().replace(/^www\./, "").replace(/\.$/, "");
+        const d = String(f.d).toLowerCase();
+        if (!host) {
+            out.reason = "no host given: a staple is only valid for the host it was served by";
+            return out;
+        }
+        if (host !== d && !host.endsWith("." + d)) {
+            out.reason = "the staple names " + d + ", not " + host;
+            return out;
+        }
+        const thumb = bytesToB64u(new Uint8Array(await crypto.subtle.digest("SHA-256", te.encode(JSON.stringify({ crv: "Ed25519", kty: "OKP", x: f.x })))));
+        if (thumb !== f.k) {
+            out.reason = "key id does not match the public key";
+            return out;
+        }
+        if (!Array.isArray(opts.publishedKids) || opts.publishedKids.indexOf(f.k) < 0) {
+            out.reason = Array.isArray(opts.publishedKids) ? "key " + f.k + " is not one CrawlCheck publishes" : "no published key list given (opts.publishedKids)";
+            return out;
+        }
+        const pk = await crypto.subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: f.x }, { name: "Ed25519" }, false, ["verify"]);
+        const ok = await crypto.subtle.verify({ name: "Ed25519" }, pk, b64uToBytes(sig), te.encode(STAPLE_PREFIX + body));
+        if (!ok) {
+            out.reason = "signature does not verify";
+            return out;
+        }
+        out.valid = true;
+        out.reason = "valid until " + f.f;
+        return out;
+    }
+    catch (e) {
+        out.reason = "could not check: " + (e && e.message || e);
+        return out;
+    }
+}

package/dist/verify.d.ts

@@ -10,10 +10,20 @@ export function dspVerdict(m: any): {
     rule: string;
 };
 export function rfcRootV(leafHex: any, index: any, size: any, path: any): Promise<string | null>;
+export function tvReachV(envelope: any): any;
+export function verifyThresholdSigners(x: any): Promise<{
+    observer_id: any;
+    network: any;
+    signature: boolean;
+    binding: boolean;
+    values_match: boolean;
+    why: never[];
+}[]>;
 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 verifyDnsTxt(txt: any, opts: any): Promise<any>;
 export function verifyDataDoc(x: any, opts: any): Promise<any>;

package/dist/verify.js

@@ -519,6 +519,90 @@ export async function rfcRootV(leafHex, index, size, path) {
     }
     return sn === 0 ? hex(r) : null;
 }
+// tv1: threshold-signed verdicts. Every signer is checked on its own: its Ed25519 signature over its envelope, the
+// binding of its key to its identity (GitHub's RS256 token, a self-signed enrolment, or the published key directory),
+// and the field values recomputed from its envelope. The verdict holds when signers on at least k distinct networks pass.
+const TV_OBS_PREFIX = "crawlcheck-observation-v1\n", TV_ENROL_PREFIX = "crawlcheck-observer-enrol-v1\n";
+function tvFinalV(u) { try {
+    const x = new URL(u);
+    return x.hostname.toLowerCase().replace(/^www\./, "") + (x.pathname.replace(/\/+$/, "") || "/");
+}
+catch (e) {
+    return null;
+} }
+export function tvReachV(envelope) {
+    return (envelope && Array.isArray(envelope.fetches) ? envelope.fetches : []).map((f) => ({ identity: String(f.identity), status: typeof f.status === "number" ? f.status : null, final: f.url_final ? tvFinalV(f.url_final) : null, failed: !!f.error }))
+        .sort((a, b) => (a.identity < b.identity ? -1 : a.identity > b.identity ? 1 : 0));
+}
+async function tvEd(x, msg, sig) { try {
+    const pk = await subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x }, { name: "Ed25519" }, false, ["verify"]);
+    return await subtle.verify({ name: "Ed25519" }, pk, b64(sig), enc.encode(msg));
+}
+catch (e) {
+    return null;
+} }
+async function tvJwt(token, jwk) {
+    const p = String(token || "").split(".");
+    if (p.length !== 3 || !jwk || jwk.kty !== "RSA")
+        return { ok: false };
+    let h, c;
+    try {
+        h = JSON.parse(new TextDecoder().decode(b64(p[0])));
+        c = JSON.parse(new TextDecoder().decode(b64(p[1])));
+    }
+    catch (e) {
+        return { ok: false };
+    }
+    if (h.alg !== "RS256" || (jwk.kid && h.kid !== jwk.kid))
+        return { ok: false, claims: c };
+    try {
+        const k = await subtle.importKey("jwk", { kty: "RSA", n: jwk.n, e: jwk.e, alg: "RS256", ext: true }, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["verify"]);
+        return { ok: await subtle.verify("RSASSA-PKCS1-v1_5", k, b64(p[2]), enc.encode(p[0] + "." + p[1])), claims: c, kid: h.kid };
+    }
+    catch (e) {
+        return { ok: null, claims: c };
+    }
+}
+export async function verifyThresholdSigners(x) {
+    const st = x.statement || {}, want = canon(st.values || []), rows = [];
+    for (const s of Array.isArray(x.signers) ? x.signers : []) {
+        const r = { observer_id: s.observer_id, network: s.network && s.network.class || null, signature: false, binding: false, values_match: false, why: [] };
+        const ev = s.envelope || {}, key = ev.key || {};
+        r.signature = !!(await tvEd(key.x, TV_OBS_PREFIX + canon(ev), s.sig));
+        if (!r.signature)
+            r.why.push("signature does not verify under the envelope key");
+        const b = s.binding || {};
+        if (b.kind === "github_oidc") {
+            const j = await tvJwt(b.token, b.github_key), c = j.claims || {};
+            const aud = "crawlcheck-observer:" + b64u(await sha256(b64(key.x || "")));
+            r.binding = j.ok === true && c.iss === "https://token.actions.githubusercontent.com" && c.repository === b.repository && String(c.job_workflow_ref || c.workflow_ref || "").indexOf(b.workflow_ref_prefix || "\u0000") === 0 && (Array.isArray(c.aud) ? c.aud : [c.aud]).includes(aud) && (!c.runner_environment || c.runner_environment === "github-hosted");
+            r.github_kid = j.kid || null;
+            if (!r.binding)
+                r.why.push("GitHub token does not bind this key to the observer workflow");
+        }
+        else if (b.kind === "enrolled_ed25519") {
+            const q = b.enrolment && b.enrolment.request;
+            r.binding = !!(b.key && b.key.x === key.x && q && q.observer_id === s.observer_id && q.key && q.key.x === key.x && await tvEd(key.x, TV_ENROL_PREFIX + canon(q), b.enrolment.sig));
+            if (!r.binding)
+                r.why.push("the key is not the one this observer enrolled with");
+        }
+        else if (b.kind === "published_key_directory") {
+            const thumb = b64u(await sha256(enc.encode(JSON.stringify({ crv: "Ed25519", kty: "OKP", x: key.x }))));
+            r.binding = thumb === b.kid && thumb === (x.signature && x.signature.kid);
+            r.kid = thumb;
+            if (!r.binding)
+                r.why.push("key thumbprint is not the stated (published) key id");
+        }
+        else
+            r.why.push("unknown binding " + b.kind);
+        r.values_match = canon(tvReachV(ev)) === want;
+        if (!r.values_match)
+            r.why.push("the values in this envelope differ from the statement");
+        r.passes = r.signature && r.binding && r.values_match;
+        rows.push(r);
+    }
+    return rows;
+}
 // ── 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.
@@ -528,7 +612,7 @@ async function verifyDataDoc0(x) {
         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|snapshot|visitor|conduct|traffic-index|anchor|anchor-check|content-clock|origin|claims|read-equivalence|rights|rights-feed|mcp-scan|mcp-lock|mcp-lock-check|mcp-shadow|mcp-auth|impersonation|task-canaries|incident|revocations|high-risk|log-sth)$/.test(String(x.kind)) || !x.signature)
+    if (!x || !/^crawlcheck-(data-inventory|data-export-part|deletion-record|resolve|decision|snapshot|visitor|conduct|traffic-index|anchor|anchor-check|content-clock|origin|claims|read-equivalence|rights|rights-feed|mcp-scan|mcp-lock|mcp-lock-check|mcp-shadow|mcp-auth|impersonation|task-canaries|agent-safety-benchmark|compliance-pack|share-of-preflight|incident|revocations|high-risk|log-sth|threshold-verdict|resolve-as-of)$/.test(String(x.kind)) || !x.signature)
         throw new Error("not a CrawlCheck data inventory, export part, deletion record, resolve answer, decision receipt, snapshot manifest, visitor verdict, conduct record, traffic index, citation anchor, content clock, origin decision, claim ledger, read-equivalence certificate, rights answer, rights-feed manifest, MCP tool scan, MCP lockfile or lockfile check");
     const body = {};
     for (const k of Object.keys(x))
@@ -577,6 +661,10 @@ async function verifyDataDoc0(x) {
         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-resolve" && Array.isArray(x.absences)) { // sa1: every absence states what was checked, from where and when
+        const bad = x.absences.filter((a) => !(a && a.what && (a.result === "absent" || a.result === "none") && a.at && !isNaN(Date.parse(a.at)) && a.from && a.from.observer && typeof a.scope === "string" && Array.isArray(a.checked) && a.checked.length && a.checked.every((c) => c && c.method && (a.result !== "absent" || c.status === undefined || c.status === 404 || c.status === 410))));
+        C("absences_scoped", bad.length === 0, x.absences.length + " absence record(s)" + (x.absences.length ? " (" + x.absences.map((a) => a.what).join(", ") + ")" : "") + (bad.length ? "; " + bad.length + " lack a definite check, a time, a vantage or a scope" : ", each naming what was requested, the answer, the vantage and the time"));
+    }
     if (x.kind === "crawlcheck-resolve" && x.transparency) { // tl1: the answer's place in the Resolve transparency log
         const t = x.transparency, leaf = hex(await sha256(cat(new Uint8Array([0]), enc.encode(canon(tlContentV(x))))));
         C("log_leaf", leaf === t.leaf_hash, leaf === t.leaf_hash ? "the answer's decision content hashes to its log leaf " + leaf.slice(0, 16) + "…" : "the decision content hashes to " + leaf + ", the answer names " + t.leaf_hash);
@@ -596,6 +684,41 @@ async function verifyDataDoc0(x) {
         else
             C("log_inclusion", null, "pending: the leaf is queued and merged within " + (t.merged_within_minutes || 30) + " minutes; fetch the proof at " + (t.proof || "the log"));
     }
+    if (x.kind === "crawlcheck-resolve-as-of") { // ah1: the answer in force at as_of, as signed then
+        let av = null;
+        try {
+            av = await verifyDataDoc0(x.answer);
+        }
+        catch (e) {
+            av = null;
+        }
+        C("answer_signature", !!(av && av.verified) && !!x.answer && x.answer.kind === "crawlcheck-resolve" && x.answer.domain === x.domain, av && av.verified ? "the archived answer verifies on its own (signed " + (x.answer.signature && x.answer.signature.signed_at) + ")" : "the archived answer does NOT verify");
+        const leaf = x.answer ? hex(await sha256(cat(new Uint8Array([0]), enc.encode(canon(tlContentV(x.answer)))))) : null;
+        C("answer_leaf", leaf === x.leaf_hash, leaf === x.leaf_hash ? "the answer's decision content is leaf " + String(leaf).slice(0, 16) + "…" : "the answer's content hashes to " + leaf + ", not the stated leaf");
+        const w = x.in_force || {}, t = Date.parse(x.as_of);
+        C("in_force_window", Date.parse(w.from) <= t && (w.until == null || t < Date.parse(w.until)), "as_of " + x.as_of + " falls in [" + w.from + ", " + (w.until || "now") + ")");
+        const pr = x.log_inclusion;
+        if (pr && pr.sth) {
+            const root = await rfcRootV(x.leaf_hash, pr.index, pr.batch_size, pr.path || []);
+            let sv = null;
+            try {
+                sv = await verifyDataDoc0(pr.sth);
+            }
+            catch (e) {
+                sv = null;
+            }
+            C("log_inclusion", root !== null && root === pr.sth.batch_root && !!(sv && sv.verified), root === pr.sth.batch_root ? "the leaf is in batch " + pr.batch + " of the signed log (head created " + pr.sth.created_at + ")" : "the inclusion proof does NOT reach the signed batch root");
+        }
+        else
+            C("log_inclusion", null, "not merged into the log yet; merged within 30 minutes of first appearing");
+    }
+    if (x.kind === "crawlcheck-threshold-verdict") { // tv1
+        const rows = await verifyThresholdSigners(x), k = x.threshold && x.threshold.k || 2;
+        rows.forEach((r) => C("signer:" + r.observer_id, r.passes, r.passes ? "signature, key binding (" + (x.signers.find((s) => s.observer_id === r.observer_id).binding.kind) + ") and recomputed " + (x.statement && x.statement.family) + " values all check (network " + r.network + ")" : r.why.join("; ")));
+        const nets = new Set(rows.filter((r) => r.passes).map((r) => r.network));
+        C("threshold", nets.size >= k, nets.size + " distinct network(s) signed identical values (" + [...nets].join(", ") + "); the verdict needs " + k);
+        C("key_bindings_online", null, "offline the bindings are checked against keys the document carries; online, compare the GitHub key id with " + "https://token.actions.githubusercontent.com/.well-known/jwks and enrolled keys with https://crawlcheck.io/.well-known/crawlcheck-observers.json");
+    }
     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);
@@ -640,6 +763,38 @@ export async function verifyBundle(b, opts) { return trustOf(await verifyBundle0
 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); }
+// dns1: a Resolve-over-DNS TXT record (ccr1). Strings joined without spaces; quotes from dig output are stripped.
+async function verifyDnsTxt0(txt) {
+    if (!subtle)
+        throw new Error("this runtime has no WebCrypto (crypto.subtle)");
+    const checks = [], C = (id, ok, why) => checks.push({ id, ok, why });
+    const t = String(txt || "").trim().replace(/"\s*"/g, "").replace(/^"|"$/g, "").replace(/\;/g, ";");
+    const i = t.lastIndexOf(";s="), body = i > 0 ? t.slice(0, i) : "", sig = i > 0 ? t.slice(i + 3) : "";
+    const f = {};
+    body.split(";").forEach((p) => { const j = p.indexOf("="); if (j > 0)
+        f[p.slice(0, j)] = p.slice(j + 1); });
+    C("format", f.v === "ccr1" && !!f.d && !!f.k && !!f.x && !!sig, f.v === "ccr1" ? "ccr1 record for " + (f.d || "?") + " (" + (f.st || "?") + ")" : "not a ccr1 record");
+    if (f.x && f.k) {
+        const thumb = b64u(await sha256(enc.encode(JSON.stringify({ crv: "Ed25519", kty: "OKP", x: f.x }))));
+        C("key_id", thumb === f.k, thumb === f.k ? "public key thumbprint (RFC 7638) is the key id " + thumb.slice(0, 12) + "…" : "thumbprint " + thumb + " does not match key id " + f.k);
+        let ok = null;
+        try {
+            const pk = await subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: f.x }, { name: "Ed25519" }, false, ["verify"]);
+            ok = await subtle.verify({ name: "Ed25519" }, pk, b64(sig), enc.encode("crawlcheck-dns-v1\n" + body));
+        }
+        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 record verifies" : "signature does NOT verify over this record");
+    }
+    const fu = Date.parse(f.f || "");
+    C("fresh", isFinite(fu) ? fu > Date.now() : false, isFinite(fu) ? (fu > Date.now() ? "fresh until " + f.f : "expired at " + f.f + ": ask again") : "no fresh_until");
+    C("key_published", null, "offline this cannot be decided: compare key id " + (f.k || "?") + " with the ids published at https://crawlcheck.io/.well-known/http-message-signatures-directory");
+    return { record: f, decisions: { read: f.read || null, cite: f.cite || null, connect: f.connect || null, transact: f.transact || null }, checks };
+}
+export async function verifyDnsTxt(txt, opts) { const r = await verifyDnsTxt0(txt); return trustOf(r, r.record && r.record.k, 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");
@@ -651,9 +806,32 @@ catch (e) {
 } })();
 if (isMain) {
     const online = process.argv.includes("--online");
+    if (process.argv.includes("--dns")) { // dns1: a Resolve-over-DNS TXT record
+        let txt = process.argv.slice(2).filter((a) => a !== "--online" && a !== "--dns").join(" ");
+        if (!txt) {
+            const { readFileSync } = await import("node:fs");
+            txt = readFileSync(0, "utf8");
+        }
+        let kd;
+        if (online) {
+            try {
+                kd = await publishedKeyIds();
+            }
+            catch (e) {
+                console.log("could not read the published key directory: " + e.message);
+            }
+        }
+        const r = await verifyDnsTxt(txt, { publishedKids: kd });
+        console.log("CrawlCheck Resolve over DNS: " + (r.record.d || "?") + " " + (r.record.st || "?") + " · read " + r.decisions.read + " · cite " + r.decisions.cite + " · connect " + r.decisions.connect + " · transact " + r.decisions.transact);
+        for (const c of r.checks)
+            console.log((c.ok === true ? "PASS" : c.ok === false ? "FAIL" : " -- ") + "  " + c.id.padEnd(23) + c.why);
+        console.log(r.summary);
+        console.log(r.accepted ? "ACCEPTED" : "NOT ACCEPTED" + (r.integrity_valid && r.issuer_trusted === null ? ": issuer unknown offline (run with --online)" : ""));
+        process.exit(r.checks.some((c) => c.ok === false) ? 1 : 0);
+    }
     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 | manifest.json>");
+        console.log("usage: node crawlcheck-verify.mjs [--online] [--dns \"<ccr1 TXT record>\"] <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");
@@ -661,7 +839,7 @@ 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|snapshot|visitor|conduct|traffic-index|anchor|anchor-check|content-clock|origin|claims|read-equivalence|rights|rights-feed|mcp-scan|mcp-lock|mcp-lock-check|mcp-shadow|mcp-auth|impersonation|task-canaries|incident|revocations|high-risk|log-sth)$/.test(String(doc.kind));
+    const isDt = doc && /^crawlcheck-(data-inventory|data-export-part|deletion-record|resolve|decision|snapshot|visitor|conduct|traffic-index|anchor|anchor-check|content-clock|origin|claims|read-equivalence|rights|rights-feed|mcp-scan|mcp-lock|mcp-lock-check|mcp-shadow|mcp-auth|impersonation|task-canaries|agent-safety-benchmark|compliance-pack|share-of-preflight|incident|revocations|high-risk|log-sth|threshold-verdict|resolve-as-of)$/.test(String(doc.kind));
     let kids;
     if (online) {
         try {

package/package.json

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

package/test/fixtures/staple.json

@@ -0,0 +1,7 @@
+{
+ "kid": "pH8ZDz3tgRtZvHTZdqEmYHGpPI72pmDrjFpMSrNt3VA",
+ "valid": "v=ccr1;d=example.com;st=measured;read=allow;cite=warn;connect=require_confirmation;transact=block;o=2026-10-07T00:00:00.000Z;f=2099-01-01T00:00:00.000Z;l=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa;k=pH8ZDz3tgRtZvHTZdqEmYHGpPI72pmDrjFpMSrNt3VA;x=ozx_4zIp-D-K_X4h1VRwWAMfOnzsBchF2lImNSJPMSY;s=7UNCtVpvzFOPfXFrWh1TzhjtWty_DE9CcKEQmFTRdY83b2fKPMNYLfn0aHV4-5ja8Pm0OfgkptK8wzoHSpa_Cw",
+ "expired": "v=ccr1;d=example.com;st=measured;read=allow;cite=warn;connect=require_confirmation;transact=block;o=2026-10-07T00:00:00.000Z;f=2020-01-01T00:00:00.000Z;l=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa;k=pH8ZDz3tgRtZvHTZdqEmYHGpPI72pmDrjFpMSrNt3VA;x=ozx_4zIp-D-K_X4h1VRwWAMfOnzsBchF2lImNSJPMSY;s=cZTwNwGE2j88S1Q7em7FRQrCv66v0mATGMd1zXt55fcDX77MEmB1IJzCG88HkPtLQvy1cGv_zHg4D974Yx40DQ",
+ "foreign": "v=ccr1;d=other.example;st=measured;read=allow;cite=warn;connect=require_confirmation;transact=block;o=2026-10-07T00:00:00.000Z;f=2099-01-01T00:00:00.000Z;l=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa;k=pH8ZDz3tgRtZvHTZdqEmYHGpPI72pmDrjFpMSrNt3VA;x=ozx_4zIp-D-K_X4h1VRwWAMfOnzsBchF2lImNSJPMSY;s=rUaiUZvO9JpJ4SJbTV_37-e5NbLhhcV0rQ7XrsQlSkjy8vzdETGIWNiohxq0BzmQ0U7vI8NeC3Gh48BBEFOSAw",
+ "tampered": "v=ccr1;d=example.com;st=measured;read=allow;cite=warn;connect=require_confirmation;transact=allow;o=2026-10-07T00:00:00.000Z;f=2099-01-01T00:00:00.000Z;l=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa;k=pH8ZDz3tgRtZvHTZdqEmYHGpPI72pmDrjFpMSrNt3VA;x=ozx_4zIp-D-K_X4h1VRwWAMfOnzsBchF2lImNSJPMSY;s=7UNCtVpvzFOPfXFrWh1TzhjtWty_DE9CcKEQmFTRdY83b2fKPMNYLfn0aHV4-5ja8Pm0OfgkptK8wzoHSpa_Cw"
+}

package/test/staple.test.js

@@ -0,0 +1,14 @@
+import test from "node:test"; import assert from "node:assert/strict"; import fs from "node:fs";
+import { stapleCheck, stapleFromResponse, CrawlCheck } from "../dist/index.js";
+const F = JSON.parse(fs.readFileSync(new URL("./fixtures/staple.json", import.meta.url), "utf8"));
+const kids = [F.kid];
+test("valid staple verifies offline", async () => { const c = await stapleCheck(F.valid, { host: "example.com", publishedKids: kids }); assert.equal(c.valid, true); assert.equal(c.decisions.transact, "block"); });
+test("subdomain of the stapled domain is covered", async () => { assert.equal((await stapleCheck(F.valid, { host: "shop.example.com", publishedKids: kids })).valid, true); });
+test("expired staple is ignored", async () => { const c = await stapleCheck(F.expired, { host: "example.com", publishedKids: kids }); assert.equal(c.valid, false); assert.equal(c.expired, true); });
+test("staple for another domain is refused", async () => { assert.equal((await stapleCheck(F.foreign, { host: "example.com", publishedKids: kids })).valid, false); });
+test("tampered staple fails the signature", async () => { const c = await stapleCheck(F.tampered, { host: "example.com", publishedKids: kids }); assert.equal(c.valid, false); assert.match(c.reason, /signature/); });
+test("unpublished key is refused", async () => { assert.equal((await stapleCheck(F.valid, { host: "example.com", publishedKids: ["someone-else"] })).valid, false); });
+test("header is read from a response", () => { assert.equal(stapleFromResponse({ headers: new Headers({ "CrawlCheck-Staple": F.valid }) }), F.valid); assert.equal(stapleFromResponse({ "crawlcheck-staple": "x" }), "x"); });
+function mockClient(calls) { return new CrawlCheck({ fetch: async (u) => { calls.push(String(u)); if (String(u).includes("signatures-directory")) return new Response(JSON.stringify({ keys: [{ kid: F.kid }] })); return new Response(JSON.stringify({ kind: "crawlcheck-resolve", actions: { read: { decision: "warn" }, cite: { decision: "warn" }, connect: { decision: "unsupported" }, transact: { decision: "require_confirmation" } } })); } }); }
+test("resolveFor prefers a valid staple and makes no resolve request", async () => { const calls = []; const r = await mockClient(calls).resolveFor("example.com", { staple: F.valid }); assert.equal(r.source, "staple"); assert.equal(calls.some((u) => u.includes("/api/v1/resolve")), false); });
+test("resolveFor ignores an expired staple and asks CrawlCheck", async () => { const calls = []; const r = await mockClient(calls).resolveFor("example.com", { staple: F.expired }); assert.equal(r.source, "network"); assert.equal(r.decisions.read, "warn"); assert.equal(r.staple.expired, true); assert.equal(calls.some((u) => u.includes("/api/v1/resolve")), true); });