@crawlcheck/sdk 1.0.5 → 1.0.6

package/README.md

@@ -66,6 +66,23 @@ suite.ok;                              // every fixture gave exactly its expecte
 
 `npm test` in the installed package runs the conformance suite and live checks against crawlcheck.io.
 
+## Catch a split view
+
+Every Resolve answer names its leaf in CrawlCheck's transparency log and, once merged, carries the signed tree head of its batch. The client keeps every head it sees in `client.log` (plain JSON) and checks each new one against its neighbours: two heads for one batch, or a head that does not chain to the one before, is a **fork**, kept with both signed heads as proof. `guard()` refuses to proceed while the client holds one.
+
+```js
+import fs from "node:fs";
+import { CrawlCheck, newLogStore } from "@crawlcheck/sdk";
+const store = fs.existsSync("cc-log.json") ? JSON.parse(fs.readFileSync("cc-log.json", "utf8")) : newLogStore();
+const client = new CrawlCheck({ logStore: store });
+await client.resolve("example.com");                 // the answer's head is checked against the store
+const r = await client.logCheck();                   // current head + GitHub's witness co-signature + the chain down to your heads
+console.log(r.summary);                              // "consistent: ..." or "SPLIT VIEW: ..."
+fs.writeFileSync("cc-log.json", JSON.stringify(client.log));
+```
+
+`logCheck` verifies the outside witness: a GitHub Actions run re-checks the chain and co-signs the newest head with a GitHub OIDC token (RS256, GitHub's key) whose audience is the head's digest. A head the witness's chain does not contain shows up as a fork. Heads newer than the witnessed one are listed as `unwitnessed`. Clients can also swap heads directly: `logHeads(store)` on one side, `client.logGossip(heads)` on the other. Forks are reported to `/api/v1/log/gossip` (pass `{ report: false }` to skip).
+
 ## Errors
 
 A refused request throws `CrawlCheckError` with `status`, `body` and `locked` (true for "this needs a licence for the domain").

package/dist/index.d.ts

@@ -222,6 +222,112 @@ export interface GuardOptions extends PreflightOptions {
     /** Also require the signing key to be in the published key directory (default true). */
     onlineKeys?: boolean;
 }
+export interface LogHead {
+    kind: "crawlcheck-log-sth";
+    log_id: string;
+    batch: number;
+    first_index: number;
+    batch_size: number;
+    tree_size: number;
+    batch_root: string;
+    prev_sth_sha256: string | null;
+    created_at: string;
+    sha256: string;
+    signature: JsonObject;
+    [k: string]: unknown;
+}
+export interface LogFork {
+    kind: "two_heads_for_one_batch" | "chain_break" | "size_mismatch" | "inconsistent_head";
+    batch: number;
+    why: string;
+    a: LogHead;
+    b: LogHead;
+    detected_at: string;
+    proof: string;
+}
+export interface LogStore {
+    v: 1;
+    log_id: string;
+    heads: Record<string, {
+        batch: number;
+        sha256: string;
+        first_index: number;
+        batch_size: number;
+        tree_size: number;
+        prev_sth_sha256: string | null;
+        created_at: string | null;
+        sth: LogHead;
+    }>;
+    forks: LogFork[];
+    witnessed: {
+        batch: number;
+        sha256: string;
+        at: string | null;
+        run_id: string | null;
+    } | null;
+}
+export interface LogObservation {
+    state: "new" | "known" | "fork" | "invalid" | "none";
+    why?: string;
+    fork?: LogFork;
+}
+export interface LogCheckResult {
+    consistent: boolean;
+    forks: LogFork[];
+    all_forks: number;
+    witnessed: {
+        batch: number;
+        sha256: string;
+        at: string | null;
+        run_id: string | null;
+        token: boolean | null;
+        why: string;
+        observed: string;
+        warning?: string;
+    } | null;
+    unwitnessed: {
+        batch: number;
+        sha256: string;
+        created_at: string | null;
+    }[];
+    stale_unwitnessed: {
+        batch: number;
+        sha256: string;
+        created_at: string | null;
+    }[];
+    summary: string;
+}
+export declare const LOG_ID: string;
+/** A new, empty transparency-log store (plain JSON: persist it between runs). */
+export declare const newLogStore: () => LogStore;
+/** Check one signed tree head against the store and keep it. A fork carries both contradicting signed heads. */
+export declare const logObserve: (store: LogStore, sth: unknown, opts?: {
+    publishedKids?: string[];
+    maxHeads?: number;
+}) => Promise<LogObservation>;
+/** Check the head inside a Resolve answer (transparency.sth), if it carries one. */
+export declare const logObserveAnswer: (store: LogStore, answer: unknown, opts?: {
+    publishedKids?: string[];
+}) => Promise<LogObservation>;
+/** The signed heads a store holds, newest first: what a client sends its peers. */
+export declare const logHeads: (store: LogStore, limit?: number) => LogHead[];
+/** Gossip: check another client's heads against this store. */
+export declare const logGossip: (store: LogStore, sths: unknown[], opts?: {
+    publishedKids?: string[];
+}) => Promise<{
+    forks: LogFork[];
+    results: (LogObservation & {
+        batch: number;
+        sha256: string;
+    })[];
+}>;
+/** Verify the outside witness's co-signature: a GitHub OIDC JWT (RS256) whose audience is crawlcheck-sth:<head sha256>. */
+export declare const verifyWitnessToken: (token: string, sthSha256: string, jwks: unknown) => Promise<{
+    ok: boolean | null;
+    why: string;
+    claims?: JsonObject;
+}>;
+export declare const GITHUB_OIDC_JWKS = "https://token.actions.githubusercontent.com/.well-known/jwks";
 export interface ClientOptions {
     /** Licence key (cc_ + 32 hex). Without one, licence-gated fields come back withheld, exactly as on the website. */
     key?: string;
@@ -231,6 +337,8 @@ export interface ClientOptions {
     fetch?: typeof fetch;
     /** Extra headers for every request. */
     headers?: Record<string, string>;
+    /** Transparency-log store (newLogStore()). Every Resolve answer's signed tree head is checked against it; keep it across runs to catch a split view. Default: a fresh in-memory store. */
+    logStore?: LogStore;
 }
 export declare class CrawlCheckError extends Error {
     readonly status: number;
@@ -252,15 +360,31 @@ export declare class CrawlCheck {
     private readonly key?;
     private readonly f;
     private readonly extra;
+    /** The transparency-log store this client checks every signed tree head against. Persist it (JSON) between runs. */
+    readonly log: LogStore;
     constructor(opts?: ClientOptions);
     /** Any documented GET, typed from the OpenAPI document: client.get("/api/explain", { domain: "example.com" }). */
     get<P extends keyof paths>(path: P, query?: QueryOf<P, "get">): Promise<ResponseOf<P, "get">>;
     /** Any documented POST, typed from the OpenAPI document. */
     post<P extends keyof paths>(path: P, body: BodyOf<P> | JsonObject, query?: QueryOf<P, "post">): Promise<ResponseOf<P, "post">>;
     /** The signed ResolveV1 answer: crawl policy, delivery, machine files, capabilities, entity, findings, freshness and a decision per action. */
-    resolve(domain: string): Promise<JsonObject>;
+    resolve(domain: string): Promise<ResponseOf<"/api/v1/resolve", "get">>;
     /** Up to 100 domains in one call; each answer is a full signed ResolveV1 document. */
-    resolveBatch(domains: string[]): Promise<JsonObject>;
+    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. */
+    logCheck(opts?: {
+        report?: boolean;
+        maxWalk?: number;
+        maxUnwitnessedMinutes?: number;
+    }): Promise<LogCheckResult>;
+    /** Check heads another client sent (logHeads on their side) against this client's store. */
+    logGossip(sths: unknown[]): Promise<{
+        forks: LogFork[];
+        results: (LogObservation & {
+            batch: number;
+            sha256: string;
+        })[];
+    }>;
     /** 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. */
@@ -271,6 +395,7 @@ export declare class CrawlCheck {
         receipt: DecisionReceipt;
         verification: DocumentVerification & Trust;
         header: Record<string, string> | null;
+        split_view?: LogFork[];
     }>;
     /** 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. */
     /** Make a signed lockfile for an MCP server (CrawlCheck reads tools/list; no tool is called). Save it; check with checkLock before every connect. */

package/dist/index.js

@@ -1,4 +1,5 @@
 import * as V from "./verify.js";
+import * as L from "./log.js";
 function withTrust(v, kid, published) {
     let checks = v.checks;
     let issuer = null;
@@ -61,6 +62,20 @@ export async function checkLock(lock, tools) {
     const same = lock?.tools_sha256 === now.tools_sha256 && !added.length && !removed.length && !modified.length;
     return { verdict: same ? "unchanged" : "changed", decision: same ? "connect" : "block", approved_tools_sha256: lock?.tools_sha256 ?? "", current_tools_sha256: now.tools_sha256, added, removed, modified };
 }
+export const LOG_ID = L.LOG_ID;
+/** A new, empty transparency-log store (plain JSON: persist it between runs). */
+export const newLogStore = L.newLogStore;
+/** Check one signed tree head against the store and keep it. A fork carries both contradicting signed heads. */
+export const logObserve = L.logObserve;
+/** Check the head inside a Resolve answer (transparency.sth), if it carries one. */
+export const logObserveAnswer = L.logObserveAnswer;
+/** The signed heads a store holds, newest first: what a client sends its peers. */
+export const logHeads = L.logHeads;
+/** Gossip: check another client's heads against this store. */
+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";
 export class CrawlCheckError extends Error {
     status;
     body;
@@ -81,10 +96,13 @@ export class CrawlCheck {
     key;
     f;
     extra;
+    /** The transparency-log store this client checks every signed tree head against. Persist it (JSON) between runs. */
+    log;
     constructor(opts = {}) {
         this.base = (opts.base ?? "https://crawlcheck.io").replace(/\/+$/, "");
         this.key = opts.key;
         this.extra = opts.headers ?? {};
+        this.log = opts.logStore ?? newLogStore();
         const f = opts.fetch ?? globalThis.fetch;
         if (typeof f !== "function")
             throw new Error("no fetch available: pass { fetch } (Node 18+ and every browser have one)");
@@ -100,9 +118,27 @@ export class CrawlCheck {
     }
     // ── 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 }); }
+    async resolve(domain) {
+        const a = await this.get("/api/v1/resolve", { domain });
+        await logObserveAnswer(this.log, a).catch(() => null); // a head that contradicts one this client already holds is recorded in this.log.forks
+        return a;
+    }
     /** Up to 100 domains in one call; each answer is a full signed ResolveV1 document. */
-    resolveBatch(domains) { return this.post("/api/v1/resolve", { domains }); }
+    async resolveBatch(domains) {
+        const r = await this.post("/api/v1/resolve", { domains });
+        for (const a of (r && r.answers) || [])
+            await logObserveAnswer(this.log, a).catch(() => null);
+        return r;
+    }
+    /** 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. */
+    async logCheck(opts = {}) {
+        const kids = await this.publishedKeyIds();
+        return L.logCheck(this.log, (p) => this.req("GET", p), { publishedKids: kids, maxWalk: opts.maxWalk, maxUnwitnessedMinutes: opts.maxUnwitnessedMinutes,
+            fetchJwks: async () => { const r = await this.f(GITHUB_OIDC_JWKS); return r.ok ? r.json() : null; },
+            post: opts.report === false ? undefined : (p, b) => this.req("POST", p, undefined, b) });
+    }
+    /** Check heads another client sent (logHeads on their side) against this client's store. */
+    logGossip(sths) { return logGossip(this.log, sths); }
     /** 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 };
@@ -121,6 +157,10 @@ export class CrawlCheck {
     /** 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);
+        if (this.log.forks.length) { // the log has shown this client two contradicting histories: no answer from it is trusted for action
+            const verification = await this.verifyDocument(receipt, opts.onlineKeys ?? true);
+            return { proceed: false, receipt, verification, header: null, split_view: this.log.forks.slice() };
+        }
         const verification = await this.verifyDocument(receipt, opts.onlineKeys ?? true);
         if (!verification.accepted && (opts.onlineKeys ?? true))
             return { proceed: false, receipt, verification, header: null };

package/dist/log.d.ts

@@ -0,0 +1,141 @@
+/** A new, empty store. It is plain JSON: keep it across runs (a file, a KV value) so later heads are checked against earlier ones. */
+export function newLogStore(): {
+    v: number;
+    log_id: string;
+    heads: {};
+    forks: never[];
+    witnessed: null;
+};
+/**
+ * Check one signed tree head (kind crawlcheck-log-sth) against everything the store already holds, then keep it.
+ * Returns { state: "new" | "known" | "fork" | "invalid", why?, fork? }. invalid means the document is not a head
+ * CrawlCheck signed (it proves nothing either way); fork means two signed heads that contradict each other.
+ * opts.publishedKids: key ids from the published directory; a head signed by another key is invalid.
+ */
+export function logObserve(store: any, sth: any, opts?: {}): Promise<{
+    state: string;
+    fork: {
+        kind: any;
+        batch: any;
+        why: any;
+        a: any;
+        b: any;
+        detected_at: string;
+        proof: string;
+    };
+} | {
+    state: string;
+    why: string;
+} | {
+    state: string;
+    why?: undefined;
+}>;
+/** Observe the head inside a Resolve answer (transparency.sth), if it has one. */
+export function logObserveAnswer(store: any, answer: any, opts?: {}): Promise<{
+    state: string;
+    fork: {
+        kind: any;
+        batch: any;
+        why: any;
+        a: any;
+        b: any;
+        detected_at: string;
+        proof: string;
+    };
+} | {
+    state: string;
+    why: string;
+} | {
+    state: string;
+    why?: undefined;
+} | {
+    state: string;
+}>;
+/** The signed heads this store holds, newest first: what a client sends its peers. */
+export function logHeads(store: any, limit?: number): any[];
+/** Gossip: check heads another client holds against this store. Returns { forks, results }. */
+export function logGossip(store: any, sths: any, opts?: {}): Promise<{
+    forks: any;
+    results: (({
+        batch: any;
+        sha256: any;
+    } & {
+        state: string;
+        fork: {
+            kind: any;
+            batch: any;
+            why: any;
+            a: any;
+            b: any;
+            detected_at: string;
+            proof: string;
+        };
+    }) | ({
+        batch: any;
+        sha256: any;
+    } & {
+        state: string;
+        why: string;
+    }) | ({
+        batch: any;
+        sha256: any;
+    } & {
+        state: string;
+        why?: undefined;
+    }))[];
+}>;
+/**
+ * Verify a witness co-signature: the JWT's RS256 signature against GitHub's published keys (jwks: the JSON from
+ * https://token.actions.githubusercontent.com/.well-known/jwks), its issuer, repository, workflow and audience
+ * crawlcheck-sth:<sthSha256>. exp is not checked: the token is a record of what the witness saw when it ran.
+ * Returns { ok: true | false | null, why, claims? }; null when GitHub no longer publishes the key that signed it.
+ */
+export function verifyWitnessToken(token: any, sthSha256: any, jwks: any): Promise<{
+    ok: boolean;
+    why: string;
+    claims?: undefined;
+} | {
+    ok: null;
+    why: string;
+    claims: any;
+} | {
+    ok: boolean;
+    why: string;
+    claims: any;
+}>;
+/**
+ * Online check of a store against the log and its outside witness. get(path) must return parsed JSON from
+ * https://crawlcheck.io (the SDK clients pass their own). Steps: observe the current head; fetch the last witnessed
+ * head and verify GitHub's co-signature; walk the chain from the witnessed head down to the oldest head this store
+ * holds (at most opts.maxWalk batches), observing every link, so any head this client was shown that the witness's
+ * chain does not contain surfaces as a fork. Heads newer than the witnessed one are listed as unwitnessed.
+ */
+export function logCheck(store: any, get: any, opts?: {}): Promise<{
+    consistent: boolean;
+    forks: any;
+    all_forks: any;
+    witnessed: {
+        batch: any;
+        sha256: any;
+        at: any;
+        run_id: any;
+        token: boolean | null;
+        why: string;
+        observed: string;
+    } | null;
+    unwitnessed: {
+        batch: number;
+        sha256: any;
+        created_at: any;
+    }[];
+    stale_unwitnessed: {
+        batch: number;
+        sha256: any;
+        created_at: any;
+    }[];
+    summary: string;
+}>;
+export const LOG_ID: "crawlcheck-resolve-log-v1";
+export const GITHUB_OIDC_ISSUER: "https://token.actions.githubusercontent.com";
+export const WITNESS_REPOSITORY: "emmanuelorta/crawlcheck";
+export const WITNESS_WORKFLOW_PREFIX: "emmanuelorta/crawlcheck/.github/workflows/log-witness.yml@refs/heads/";

package/dist/log.js

@@ -0,0 +1,194 @@
+// Split-view detection for the CrawlCheck Resolve transparency log.
+// A log that shows one client a different history than another (a "split view") has to sign two different heads for
+// the same batch, or a head that does not chain to the one before. Both are caught here, three ways:
+//   1. every head a client sees (in Resolve answers, from the log, from peers) is kept in a store and checked against
+//      its neighbours: same batch with two digests, a broken prev link, or broken size arithmetic is a fork;
+//   2. gossip: clients swap the signed heads they hold (logHeads / logGossip), so a head shown only to one of them
+//      collides with the other's store;
+//   3. the outside witness: a GitHub Actions run re-checks the chain and co-signs the newest head with a GitHub-signed
+//      OIDC token whose audience is that head's digest. GitHub's key, not CrawlCheck's. A client that walks the chain
+//      from the witnessed head back to its own heads detects any head the witness never saw.
+// A fork comes with both signed heads: two documents carrying CrawlCheck's own signature that cannot both be true.
+// Zero dependencies; WebCrypto only.
+import { verifyDataDoc } from "./verify.js";
+export const LOG_ID = "crawlcheck-resolve-log-v1";
+export const GITHUB_OIDC_ISSUER = "https://token.actions.githubusercontent.com";
+export const WITNESS_REPOSITORY = "emmanuelorta/crawlcheck";
+export const WITNESS_WORKFLOW_PREFIX = "emmanuelorta/crawlcheck/.github/workflows/log-witness.yml@refs/heads/";
+const MAX_HEADS = 2000;
+/** A new, empty store. It is plain JSON: keep it across runs (a file, a KV value) so later heads are checked against earlier ones. */
+export function newLogStore() { return { v: 1, log_id: LOG_ID, heads: {}, forks: [], witnessed: null }; }
+function brief(s) { return { batch: s.batch, sha256: s.sha256, first_index: s.first_index, batch_size: s.batch_size, tree_size: s.tree_size, prev_sth_sha256: s.prev_sth_sha256 ?? null, created_at: s.created_at ?? null }; }
+function forkOf(store, kind, batch, a, b, why) {
+    const f = { kind, batch, why, a: a, b: b, detected_at: new Date().toISOString(),
+        proof: "both documents carry CrawlCheck's own signature and cannot both belong to one append-only log; publish them or send them to " + "https://crawlcheck.io/api/v1/log/gossip" };
+    const key = kind + ":" + (a && a.sha256) + ":" + (b && b.sha256);
+    if (!store.forks.some((x) => x.kind + ":" + (x.a && x.a.sha256) + ":" + (x.b && x.b.sha256) === key))
+        store.forks.push(f);
+    return { state: "fork", fork: f };
+}
+/**
+ * Check one signed tree head (kind crawlcheck-log-sth) against everything the store already holds, then keep it.
+ * Returns { state: "new" | "known" | "fork" | "invalid", why?, fork? }. invalid means the document is not a head
+ * CrawlCheck signed (it proves nothing either way); fork means two signed heads that contradict each other.
+ * opts.publishedKids: key ids from the published directory; a head signed by another key is invalid.
+ */
+export async function logObserve(store, sth, opts = {}) {
+    if (!store || typeof store !== "object" || !store.heads)
+        throw new Error("pass a store from newLogStore()");
+    if (!sth || sth.kind !== "crawlcheck-log-sth" || !Number.isInteger(sth.batch) || sth.batch < 0)
+        return { state: "invalid", why: "not a signed tree head" };
+    let v = null;
+    try {
+        v = await verifyDataDoc(sth, opts.publishedKids ? { publishedKids: opts.publishedKids } : undefined);
+    }
+    catch (e) {
+        v = null;
+    }
+    if (!v || !v.verified)
+        return { state: "invalid", why: "the head does not verify" + (v ? ": " + v.summary : "") };
+    if (opts.publishedKids && !opts.publishedKids.includes(sth.signature && sth.signature.kid))
+        return { state: "invalid", why: "signed by a key CrawlCheck does not publish" };
+    if (sth.log_id !== (store.log_id || LOG_ID))
+        return { state: "invalid", why: "a head of another log (" + sth.log_id + ")" };
+    // A head CrawlCheck signed whose own numbers do not add up is itself misbehaviour.
+    const arith = Number.isInteger(sth.batch_size) && sth.batch_size > 0 && sth.tree_size === sth.first_index + sth.batch_size && (sth.batch > 0 || (sth.first_index === 0 && sth.prev_sth_sha256 == null)) && (sth.batch === 0 || /^[0-9a-f]{64}$/.test(String(sth.prev_sth_sha256)));
+    if (!arith)
+        return forkOf(store, "inconsistent_head", sth.batch, sth, sth, "batch " + sth.batch + ": a signed head whose sizes or chain link are malformed");
+    const k = sth.batch, have = store.heads[k];
+    if (have) {
+        if (have.sha256 === sth.sha256)
+            return { state: "known" };
+        return forkOf(store, "two_heads_for_one_batch", k, have.sth, sth, "batch " + k + " has two signed heads: " + have.sha256.slice(0, 16) + "… and " + sth.sha256.slice(0, 16) + "…");
+    }
+    const prev = store.heads[k - 1], next = store.heads[k + 1];
+    if (prev && sth.prev_sth_sha256 !== prev.sha256)
+        return forkOf(store, "chain_break", k, prev.sth, sth, "batch " + k + " does not chain to the batch " + (k - 1) + " head this client holds");
+    if (prev && sth.first_index !== prev.tree_size)
+        return forkOf(store, "size_mismatch", k, prev.sth, sth, "batch " + k + " starts at " + sth.first_index + ", batch " + (k - 1) + " ended at " + prev.tree_size);
+    if (next && next.prev_sth_sha256 !== sth.sha256)
+        return forkOf(store, "chain_break", k + 1, sth, next.sth, "the batch " + (k + 1) + " head this client holds does not chain to this batch " + k + " head");
+    if (next && next.first_index !== sth.tree_size)
+        return forkOf(store, "size_mismatch", k + 1, sth, next.sth, "batch " + (k + 1) + " starts at " + next.first_index + ", this head ends at " + sth.tree_size);
+    store.heads[k] = Object.assign(brief(sth), { sth });
+    const ks = Object.keys(store.heads).map(Number).sort((a, b) => a - b);
+    while (ks.length > (opts.maxHeads || MAX_HEADS))
+        delete store.heads[ks.shift()];
+    return { state: "new" };
+}
+/** Observe the head inside a Resolve answer (transparency.sth), if it has one. */
+export async function logObserveAnswer(store, answer, opts = {}) {
+    const t = answer && answer.transparency;
+    return t && t.state === "included" && t.sth ? logObserve(store, t.sth, opts) : { state: "none" };
+}
+/** The signed heads this store holds, newest first: what a client sends its peers. */
+export function logHeads(store, limit = 50) {
+    return Object.keys(store.heads).map(Number).sort((a, b) => b - a).slice(0, limit).map((k) => store.heads[k].sth);
+}
+/** Gossip: check heads another client holds against this store. Returns { forks, results }. */
+export async function logGossip(store, sths, opts = {}) {
+    const results = [], before = store.forks.length;
+    for (const s of Array.isArray(sths) ? sths : [])
+        results.push(Object.assign({ batch: s && s.batch, sha256: s && s.sha256 }, await logObserve(store, s, opts)));
+    return { forks: store.forks.slice(before), results };
+}
+// ── the outside witness: a GitHub Actions OIDC token whose audience is the head's digest ──
+const b64uBytes = (s) => { const t = String(s).replace(/-/g, "+").replace(/_/g, "/"); const b = atob(t + "=".repeat((4 - t.length % 4) % 4)); const o = new Uint8Array(b.length); for (let i = 0; i < b.length; i++)
+    o[i] = b.charCodeAt(i); return o; };
+/**
+ * Verify a witness co-signature: the JWT's RS256 signature against GitHub's published keys (jwks: the JSON from
+ * https://token.actions.githubusercontent.com/.well-known/jwks), its issuer, repository, workflow and audience
+ * crawlcheck-sth:<sthSha256>. exp is not checked: the token is a record of what the witness saw when it ran.
+ * Returns { ok: true | false | null, why, claims? }; null when GitHub no longer publishes the key that signed it.
+ */
+export async function verifyWitnessToken(token, sthSha256, jwks) {
+    const parts = String(token || "").split(".");
+    if (parts.length !== 3)
+        return { ok: false, why: "not a JWT" };
+    let h, c;
+    try {
+        h = JSON.parse(new TextDecoder().decode(b64uBytes(parts[0])));
+        c = JSON.parse(new TextDecoder().decode(b64uBytes(parts[1])));
+    }
+    catch (e) {
+        return { ok: false, why: "unreadable token" };
+    }
+    if (h.alg !== "RS256")
+        return { ok: false, why: "unexpected algorithm " + h.alg };
+    const jwk = (jwks && jwks.keys || []).find((k) => k.kid === h.kid);
+    if (!jwk)
+        return { ok: null, why: "GitHub no longer publishes key " + h.kid + "; the co-signature cannot be checked now", claims: c };
+    let sigOk = false;
+    try {
+        const key = await crypto.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"]);
+        sigOk = await crypto.subtle.verify("RSASSA-PKCS1-v1_5", key, b64uBytes(parts[2]), new TextEncoder().encode(parts[0] + "." + parts[1]));
+    }
+    catch (e) {
+        return { ok: null, why: "this runtime cannot verify RS256: " + (e && e.message || e), claims: c };
+    }
+    if (!sigOk)
+        return { ok: false, why: "GitHub's signature does NOT verify", claims: c };
+    if (c.iss !== GITHUB_OIDC_ISSUER)
+        return { ok: false, why: "issuer is " + c.iss, claims: c };
+    if (c.repository !== WITNESS_REPOSITORY || String(c.job_workflow_ref || "").indexOf(WITNESS_WORKFLOW_PREFIX) !== 0)
+        return { ok: false, why: "issued to " + c.job_workflow_ref + ", not the log-witness workflow", claims: c };
+    if (c.runner_environment && c.runner_environment !== "github-hosted")
+        return { ok: false, why: "not a GitHub-hosted runner", claims: c };
+    const aud = Array.isArray(c.aud) ? c.aud : [c.aud];
+    if (!aud.includes("crawlcheck-sth:" + sthSha256))
+        return { ok: false, why: "the token's audience does not name this head", claims: c };
+    return { ok: true, why: "GitHub signed a token for run " + c.run_id + " of the log-witness workflow, audience this head's digest", claims: c };
+}
+/**
+ * Online check of a store against the log and its outside witness. get(path) must return parsed JSON from
+ * https://crawlcheck.io (the SDK clients pass their own). Steps: observe the current head; fetch the last witnessed
+ * head and verify GitHub's co-signature; walk the chain from the witnessed head down to the oldest head this store
+ * holds (at most opts.maxWalk batches), observing every link, so any head this client was shown that the witness's
+ * chain does not contain surfaces as a fork. Heads newer than the witnessed one are listed as unwitnessed.
+ */
+export async function logCheck(store, get, opts = {}) {
+    const before = store.forks.length, o = { publishedKids: opts.publishedKids };
+    const log = await get("/api/v1/log");
+    if (log && log.head)
+        await logObserve(store, log.head, o);
+    let witnessed = null;
+    const w = await get("/api/v1/log/witness/latest").catch(() => null);
+    if (w && Number.isInteger(w.batch)) {
+        const doc = await get("/api/v1/log/sth/" + w.batch);
+        const sth = doc && doc.sth, rec = (doc && doc.witnesses || [])[0] || w;
+        const jwks = opts.jwks || (opts.fetchJwks ? await opts.fetchJwks() : null);
+        const tv = jwks ? await verifyWitnessToken(rec.token, sth && sth.sha256, jwks) : { ok: null, why: "no GitHub key set given" };
+        const r = sth ? await logObserve(store, sth, o) : { state: "invalid" };
+        witnessed = { batch: w.batch, sha256: sth && sth.sha256, at: rec.at || null, run_id: tv.claims ? tv.claims.run_id : (rec.run && rec.run.run_id) || null, token: tv.ok, why: tv.why, observed: r.state };
+        if (tv.ok === false)
+            witnessed.warning = "the witness record does not carry a valid GitHub co-signature for this head";
+        if (tv.ok === true && r.state !== "invalid")
+            store.witnessed = { batch: w.batch, sha256: sth.sha256, at: witnessed.at, run_id: witnessed.run_id };
+        const held = Object.keys(store.heads).map(Number).filter((k) => k < w.batch);
+        const lo = held.length ? Math.max(Math.min(...held), w.batch - (opts.maxWalk || 200)) : w.batch;
+        for (let k = w.batch - 1; k >= lo; k--) {
+            const d = await get("/api/v1/log/sth/" + k).catch(() => null);
+            if (d && d.sth)
+                await logObserve(store, d.sth, o);
+        }
+    }
+    const wb = store.witnessed ? store.witnessed.batch : -1, now = Date.now(), maxAge = (opts.maxUnwitnessedMinutes || 120) * 60000;
+    const unwitnessed = Object.keys(store.heads).map(Number).filter((k) => k > wb).sort((a, b) => a - b).map((k) => ({ batch: k, sha256: store.heads[k].sha256, created_at: store.heads[k].created_at }));
+    const stale = unwitnessed.filter((u) => u.created_at && now - Date.parse(u.created_at) > maxAge);
+    const forks = store.forks.slice(before);
+    if (opts.post) { // tell CrawlCheck which heads this client was shown; a fork reported here is recorded publicly at /api/v1/log/gossip
+        const sths = logHeads(store, 20);
+        for (const f of forks) {
+            if (f.a)
+                sths.push(f.a);
+            if (f.b && f.b !== f.a)
+                sths.push(f.b);
+        }
+        try {
+            await opts.post("/api/v1/log/gossip", { sths: sths.slice(0, 50) });
+        }
+        catch (e) { }
+    }
+    return { consistent: store.forks.length === 0, forks, all_forks: store.forks.length, witnessed, unwitnessed, stale_unwitnessed: stale,
+        summary: store.forks.length ? "SPLIT VIEW: " + store.forks.length + " pair(s) of contradicting signed heads" : stale.length ? "no fork seen, but " + stale.length + " head(s) older than " + (opts.maxUnwitnessedMinutes || 120) + " min are not covered by a witness" : "consistent: every head this client holds is on one chain" + (witnessed && witnessed.token === true ? " up to the head GitHub's witness co-signed (batch " + witnessed.batch + ")" : "") };
+}

package/dist/verify.d.ts

@@ -9,6 +9,7 @@ export function dspVerdict(m: any): {
     effect: string;
     rule: string;
 };
+export function rfcRootV(leafHex: any, index: any, size: any, path: any): Promise<string | null>;
 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>;

package/dist/verify.js

@@ -487,6 +487,38 @@ async function verifyResolution0(x) {
         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." };
 }
+// tl1: the Resolve log's leaf content and RFC 9162 inclusion check (the same rules the log publishes).
+function tlContentV(doc) {
+    const a = doc && doc.actions || {}, acts = {};
+    Object.keys(a).sort().forEach((k) => { const x = a[k] || {}; acts[k] = { decision: x.decision || null, doubts: (Array.isArray(x.doubts) ? x.doubts : []).slice().sort() }; });
+    return { log: "crawlcheck-resolve-log-v1", domain: doc && doc.domain || null, status: doc && doc.status || null, actions: acts,
+        report: doc && doc.evidence && doc.evidence.report || null, observed_at: doc && doc.freshness && doc.freshness.observed_at || null,
+        incident: doc && doc.incident && doc.incident.since || null, impersonation: doc && doc.impersonation && doc.impersonation.verdict === "suspected" ? "suspected" : null,
+        high_risk_pending: doc && doc.high_risk_fields && Array.isArray(doc.high_risk_fields.pending) ? doc.high_risk_fields.pending.map((p) => p.field).sort() : [] };
+}
+export async function rfcRootV(leafHex, index, size, path) {
+    if (!(size > 0) || !(index >= 0) || index >= size)
+        return null;
+    let fn = index, sn = size - 1, r = unhex(leafHex);
+    for (const p of path) {
+        if (sn === 0)
+            return null;
+        if ((fn & 1) === 1 || fn === sn) {
+            r = await sha256(cat(cat(new Uint8Array([1]), unhex(p)), r));
+            if ((fn & 1) === 0) {
+                while ((fn & 1) === 0 && fn !== 0) {
+                    fn >>= 1;
+                    sn >>= 1;
+                }
+            }
+        }
+        else
+            r = await sha256(cat(cat(new Uint8Array([1]), r), unhex(p)));
+        fn >>= 1;
+        sn >>= 1;
+    }
+    return sn === 0 ? hex(r) : null;
+}
 // ── 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.
@@ -496,7 +528,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)$/.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|incident|revocations|high-risk|log-sth)$/.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))
@@ -545,6 +577,25 @@ 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" && 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);
+        if (t.state === "included" && t.sth) {
+            const root = await rfcRootV(leaf, t.index, t.batch_size, t.path || []);
+            C("log_inclusion", root !== null && root === t.sth.batch_root, root === t.sth.batch_root ? "the leaf folds along its " + (t.path || []).length + "-step path to batch " + t.batch + "'s root (RFC 9162)" : "the inclusion path does NOT lead to the signed batch root");
+            let sv = null;
+            try {
+                sv = await verifyDataDoc0(t.sth);
+            }
+            catch (e) {
+                sv = null;
+            }
+            const same = !x.signature || !t.sth.signature || t.sth.signature.kid === x.signature.kid;
+            C("log_head_signature", !!(sv && sv.verified) && t.sth.kind === "crawlcheck-log-sth" && t.sth.batch === t.batch && same, sv && sv.verified ? "batch " + t.batch + "'s signed tree head verifies (tree size " + t.sth.tree_size + ", chained to " + String(t.sth.prev_sth_sha256 || "genesis").slice(0, 16) + "…)" : "the signed tree head does NOT verify");
+        }
+        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-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);
@@ -610,7 +661,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)$/.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|incident|revocations|high-risk|log-sth)$/.test(String(doc.kind));
     let kids;
     if (online) {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crawlcheck/sdk",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "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/split-view.json

@@ -0,0 +1 @@
+{"kid":"wlMUoXULLLsGJfT7xs0dC4rlNB6xckeP7Of-hL3fS8g","A":[{"kind":"crawlcheck-log-sth","v":1,"log_id":"crawlcheck-resolve-log-v1","batch":0,"first_index":0,"batch_size":3,"tree_size":3,"batch_root":"f5c7cf1ce5c25073318b00bc6c0dc78dee92e55a633f7c7bc5fc71e5d1e6f08c","prev_sth_sha256":null,"created_at":"2026-10-07T12:43:36.031Z","rules":{"leaf":"SHA-256(0x00 || canonical JSON of the answer's decision content)","tree":"RFC 9162 Merkle tree hash over this batch's leaf hashes, sorted","chain":"prev_sth_sha256 is the sha256 of the previous batch's signed tree head; batch numbers are consecutive and tree_size grows by batch_size"},"sha256":"7b92d6860b6e0b95e8ece2980ba7153a3c437e9b375f500289b1346bd639f744","signature":{"v":1,"alg":"Ed25519","kid":"wlMUoXULLLsGJfT7xs0dC4rlNB6xckeP7Of-hL3fS8g","over":"sha256","message":"crawlcheck-data-v1\n7b92d6860b6e0b95e8ece2980ba7153a3c437e9b375f500289b1346bd639f744","sig":"sFrMZhW3RhQfqKgkTVhzjrcvlxTikEuH9Hj8HxFMyD3P4aa53ix0aQoLmykCTBBmnDf1zKEfxCsUe27GnQSqDA","signed_at":"2026-10-07T12:43:36.031Z","key":{"kid":"wlMUoXULLLsGJfT7xs0dC4rlNB6xckeP7Of-hL3fS8g","jwk":{"kty":"OKP","crv":"Ed25519","x":"Ei2Hob8P3o4hhakpwltAFAesqr9N23RnBndK-h5Wkdc"},"published_in":"https://crawlcheck.io/.well-known/http-message-signatures-directory"},"canonical":"sha256 over canonical JSON of every field except sha256 and signature"}},{"kind":"crawlcheck-log-sth","v":1,"log_id":"crawlcheck-resolve-log-v1","batch":1,"first_index":3,"batch_size":1,"tree_size":4,"batch_root":"0ca77e88d0074680c0ed45ab5ef88ab99a6f4f23533e58cbb8fad46625c3e98a","prev_sth_sha256":"7b92d6860b6e0b95e8ece2980ba7153a3c437e9b375f500289b1346bd639f744","created_at":"2026-10-07T12:43:36.034Z","rules":{"leaf":"SHA-256(0x00 || canonical JSON of the answer's decision content)","tree":"RFC 9162 Merkle tree hash over this batch's leaf hashes, sorted","chain":"prev_sth_sha256 is the sha256 of the previous batch's signed tree head; batch numbers are consecutive and tree_size grows by batch_size"},"sha256":"865b63bd6fba326a5dcdfa5c58d46817a6a163209ba7a7357e091f522af8a4b7","signature":{"v":1,"alg":"Ed25519","kid":"wlMUoXULLLsGJfT7xs0dC4rlNB6xckeP7Of-hL3fS8g","over":"sha256","message":"crawlcheck-data-v1\n865b63bd6fba326a5dcdfa5c58d46817a6a163209ba7a7357e091f522af8a4b7","sig":"oB5mXAvuYKReLJLosI06hxajPW4L8sbnCnJTtdRlFuOi2XyuOm13V60BfNI27uHUL7vJqV6dPwkf2PBVSWMvAQ","signed_at":"2026-10-07T12:43:36.034Z","key":{"kid":"wlMUoXULLLsGJfT7xs0dC4rlNB6xckeP7Of-hL3fS8g","jwk":{"kty":"OKP","crv":"Ed25519","x":"Ei2Hob8P3o4hhakpwltAFAesqr9N23RnBndK-h5Wkdc"},"published_in":"https://crawlcheck.io/.well-known/http-message-signatures-directory"},"canonical":"sha256 over canonical JSON of every field except sha256 and signature"}},{"kind":"crawlcheck-log-sth","v":1,"log_id":"crawlcheck-resolve-log-v1","batch":2,"first_index":4,"batch_size":1,"tree_size":5,"batch_root":"18af4f71e5ff99faf5e0cbe20dfd6f226a26318a95785017257376639535f802","prev_sth_sha256":"865b63bd6fba326a5dcdfa5c58d46817a6a163209ba7a7357e091f522af8a4b7","created_at":"2026-10-07T12:43:36.036Z","rules":{"leaf":"SHA-256(0x00 || canonical JSON of the answer's decision content)","tree":"RFC 9162 Merkle tree hash over this batch's leaf hashes, sorted","chain":"prev_sth_sha256 is the sha256 of the previous batch's signed tree head; batch numbers are consecutive and tree_size grows by batch_size"},"sha256":"091d4d852dd45ae637d93368c0bf1602465cd50d0f4a81a225cb0b6f65833d6f","signature":{"v":1,"alg":"Ed25519","kid":"wlMUoXULLLsGJfT7xs0dC4rlNB6xckeP7Of-hL3fS8g","over":"sha256","message":"crawlcheck-data-v1\n091d4d852dd45ae637d93368c0bf1602465cd50d0f4a81a225cb0b6f65833d6f","sig":"gfifnwojp5ep9a6DpqWPlFXuNd1h1jQ1-ZvS_FsRKIl3m6U6cyjZfuDcDGx29Ej4I_GpH8GE75QzjwxZAXhrCQ","signed_at":"2026-10-07T12:43:36.037Z","key":{"kid":"wlMUoXULLLsGJfT7xs0dC4rlNB6xckeP7Of-hL3fS8g","jwk":{"kty":"OKP","crv":"Ed25519","x":"Ei2Hob8P3o4hhakpwltAFAesqr9N23RnBndK-h5Wkdc"},"published_in":"https://crawlcheck.io/.well-known/http-message-signatures-directory"},"canonical":"sha256 over canonical JSON of every field except sha256 and signature"}}],"B":[{"kind":"crawlcheck-log-sth","v":1,"log_id":"crawlcheck-resolve-log-v1","batch":0,"first_index":0,"batch_size":3,"tree_size":3,"batch_root":"f5c7cf1ce5c25073318b00bc6c0dc78dee92e55a633f7c7bc5fc71e5d1e6f08c","prev_sth_sha256":null,"created_at":"2026-10-07T12:43:36.031Z","rules":{"leaf":"SHA-256(0x00 || canonical JSON of the answer's decision content)","tree":"RFC 9162 Merkle tree hash over this batch's leaf hashes, sorted","chain":"prev_sth_sha256 is the sha256 of the previous batch's signed tree head; batch numbers are consecutive and tree_size grows by batch_size"},"sha256":"7b92d6860b6e0b95e8ece2980ba7153a3c437e9b375f500289b1346bd639f744","signature":{"v":1,"alg":"Ed25519","kid":"wlMUoXULLLsGJfT7xs0dC4rlNB6xckeP7Of-hL3fS8g","over":"sha256","message":"crawlcheck-data-v1\n7b92d6860b6e0b95e8ece2980ba7153a3c437e9b375f500289b1346bd639f744","sig":"sFrMZhW3RhQfqKgkTVhzjrcvlxTikEuH9Hj8HxFMyD3P4aa53ix0aQoLmykCTBBmnDf1zKEfxCsUe27GnQSqDA","signed_at":"2026-10-07T12:43:36.031Z","key":{"kid":"wlMUoXULLLsGJfT7xs0dC4rlNB6xckeP7Of-hL3fS8g","jwk":{"kty":"OKP","crv":"Ed25519","x":"Ei2Hob8P3o4hhakpwltAFAesqr9N23RnBndK-h5Wkdc"},"published_in":"https://crawlcheck.io/.well-known/http-message-signatures-directory"},"canonical":"sha256 over canonical JSON of every field except sha256 and signature"}},{"kind":"crawlcheck-log-sth","v":1,"log_id":"crawlcheck-resolve-log-v1","batch":1,"first_index":3,"batch_size":1,"tree_size":4,"batch_root":"1421832f5ae223370e493d079607cf891dffef5b1a21f73834dfdd600a5305b5","prev_sth_sha256":"7b92d6860b6e0b95e8ece2980ba7153a3c437e9b375f500289b1346bd639f744","created_at":"2026-10-07T12:43:36.039Z","rules":{"leaf":"SHA-256(0x00 || canonical JSON of the answer's decision content)","tree":"RFC 9162 Merkle tree hash over this batch's leaf hashes, sorted","chain":"prev_sth_sha256 is the sha256 of the previous batch's signed tree head; batch numbers are consecutive and tree_size grows by batch_size"},"sha256":"2b816b346f43a05913a1a6426c1e2d5a59e8d2a6bb03c520a44936035f0bf75f","signature":{"v":1,"alg":"Ed25519","kid":"wlMUoXULLLsGJfT7xs0dC4rlNB6xckeP7Of-hL3fS8g","over":"sha256","message":"crawlcheck-data-v1\n2b816b346f43a05913a1a6426c1e2d5a59e8d2a6bb03c520a44936035f0bf75f","sig":"x_wDhe08acY2zWMcztpnCx3jguE7Vtap7_8jel8mTIPixsh1VEIYcqsl971sdQSImi1ypU9OFyzy3Hf-o9fbCQ","signed_at":"2026-10-07T12:43:36.039Z","key":{"kid":"wlMUoXULLLsGJfT7xs0dC4rlNB6xckeP7Of-hL3fS8g","jwk":{"kty":"OKP","crv":"Ed25519","x":"Ei2Hob8P3o4hhakpwltAFAesqr9N23RnBndK-h5Wkdc"},"published_in":"https://crawlcheck.io/.well-known/http-message-signatures-directory"},"canonical":"sha256 over canonical JSON of every field except sha256 and signature"}},{"kind":"crawlcheck-log-sth","v":1,"log_id":"crawlcheck-resolve-log-v1","batch":2,"first_index":4,"batch_size":1,"tree_size":5,"batch_root":"05b87125340036bc8c40639ee045cf93e7614a2f70cb6738775bbd08b6abbef1","prev_sth_sha256":"2b816b346f43a05913a1a6426c1e2d5a59e8d2a6bb03c520a44936035f0bf75f","created_at":"2026-10-07T12:43:36.041Z","rules":{"leaf":"SHA-256(0x00 || canonical JSON of the answer's decision content)","tree":"RFC 9162 Merkle tree hash over this batch's leaf hashes, sorted","chain":"prev_sth_sha256 is the sha256 of the previous batch's signed tree head; batch numbers are consecutive and tree_size grows by batch_size"},"sha256":"316bf3e517d3d02615bd6bc0d49699324ef63951b710c72f42b14ca4e63324d4","signature":{"v":1,"alg":"Ed25519","kid":"wlMUoXULLLsGJfT7xs0dC4rlNB6xckeP7Of-hL3fS8g","over":"sha256","message":"crawlcheck-data-v1\n316bf3e517d3d02615bd6bc0d49699324ef63951b710c72f42b14ca4e63324d4","sig":"9fmnQ9AikQJQluM6BICr9lnhvlfUCiqJMPv7LSdX62Yn2eMMfiIeLV4dkCn-Cul2k_teq0QV3ZjySgOA-vObDQ","signed_at":"2026-10-07T12:43:36.041Z","key":{"kid":"wlMUoXULLLsGJfT7xs0dC4rlNB6xckeP7Of-hL3fS8g","jwk":{"kty":"OKP","crv":"Ed25519","x":"Ei2Hob8P3o4hhakpwltAFAesqr9N23RnBndK-h5Wkdc"},"published_in":"https://crawlcheck.io/.well-known/http-message-signatures-directory"},"canonical":"sha256 over canonical JSON of every field except sha256 and signature"}}],"jwks":{"keys":[{"key_ops":["verify"],"ext":true,"alg":"RS256","kty":"RSA","n":"xJlkjrfM9UG4lgK5lTiBodFR9xMTojA_h45ndmTqFe_WOd_c8g8z-f9vXdgaZhXEDBzTdAA-ln1vuE04Xwxl2nQQpK-8pJkKyUTm5ONlf0a1vUUioWVhaUisEcxkpELFDq42D9StkrMi8S6y9Q9AYwXCsmgzLGFLG665Z9udOpHhH6SKHt0_C8RU9Tqxhi9CHttpiVfKENssB25lskvezm4e698G2O-Bb4xKHKEGgqTq7NeX3uw7aUKMXOZNucvOEjYteZMLzFchmops2BrTyjrCw1zu7QEsX-myjNJ_KIrGUVhkCADmFOKnFkM6Qh7UezFgdWSs708zh5z6H7Qspw","e":"AQAB","kid":"test-gh","use":"sig"}]},"witness":{"batch":2,"sth_sha256":"091d4d852dd45ae637d93368c0bf1602465cd50d0f4a81a225cb0b6f65833d6f","at":"2026-10-07T12:43:36.119Z","witness":"github-actions:test","run":{"run_id":"424242"},"token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QtZ2gifQ.eyJpc3MiOiJodHRwczovL3Rva2VuLmFjdGlvbnMuZ2l0aHVidXNlcmNvbnRlbnQuY29tIiwiYXVkIjoiY3Jhd2xjaGVjay1zdGg6MDkxZDRkODUyZGQ0NWFlNjM3ZDkzMzY4YzBiZjE2MDI0NjVjZDUwZDBmNGE4MWEyMjVjYjBiNmY2NTgzM2Q2ZiIsInJlcG9zaXRvcnkiOiJlbW1hbnVlbG9ydGEvY3Jhd2xjaGVjayIsImpvYl93b3JrZmxvd19yZWYiOiJlbW1hbnVlbG9ydGEvY3Jhd2xjaGVjay8uZ2l0aHViL3dvcmtmbG93cy9sb2ctd2l0bmVzcy55bWxAcmVmcy9oZWFkcy9tYWluIiwicnVubmVyX2Vudmlyb25tZW50IjoiZ2l0aHViLWhvc3RlZCIsInJ1bl9pZCI6IjQyNDI0MiIsImlhdCI6MSwiZXhwIjoyfQ.WxmmvJMCe5vK41vSzLd84uIy69wxOni4NICfCh19aaFUoZylcYxf1z7s_8LdyEIItHaSmf6paHNgxo7kpaFUviJqH9pRW1evOikoluiYVEWzjIgrBvS5rk1QbT_YokSNuN1HXuliYLQu1KCWzWe8bA8C1jUprTETpWd2bUGHQMsSGH3MkCTH4NpZwTTxFCNU1Dhk0QZQASNmz0gPXEWmnGoYNvfqbVAjENo1wT4P9p4ZaQ2YXwC25jHTMPVBKdIVkqpdfTxwEGKd6PtOD83oRqZI32gdiVGmUPlfmJKbWfcXkUW2cL3kxQTPVEMbwZ4scly55-c6uIEJbhbfWAv0Cg"}}

package/test/split-view.test.js

@@ -0,0 +1,34 @@
+// Split-view detection: a forced fork of the Resolve transparency log (one signing key, two histories, made by the
+// Worker's own log code in a test harness) must be detected offline, and the live log must check out consistent.
+import test from "node:test"; import assert from "node:assert/strict"; import fs from "node:fs";
+import { CrawlCheck, newLogStore, logObserve, logGossip, logHeads, verifyWitnessToken, verifyDocument } from "../dist/index.js";
+const F = JSON.parse(fs.readFileSync(new URL("./fixtures/split-view.json", import.meta.url), "utf8"));
+
+test("a forked log is detected by gossip: two signed heads for one batch", async () => {
+  const a = newLogStore(), b = newLogStore();
+  for (const s of F.A) assert.equal((await logObserve(a, s, { publishedKids: [F.kid] })).state, "new");
+  for (const s of F.B) await logObserve(b, s, { publishedKids: [F.kid] });
+  assert.equal(a.forks.length + b.forks.length, 0, "each history alone is consistent");
+  const g = await logGossip(a, logHeads(b), { publishedKids: [F.kid] });
+  assert.deepEqual(g.forks.map((f) => f.kind + "@" + f.batch).sort(), ["two_heads_for_one_batch@1", "two_heads_for_one_batch@2"]);
+  assert.ok((await verifyDocument(g.forks[0].a)).verified && (await verifyDocument(g.forks[0].b)).verified, "both heads of the proof verify on their own");
+});
+test("a head that does not chain to one held is a fork", async () => {
+  const c = newLogStore(); await logObserve(c, F.A[1]);
+  const r = await logObserve(c, F.B[2]);
+  assert.equal(r.state, "fork"); assert.equal(r.fork.kind, "chain_break");
+});
+test("a tampered head proves nothing (invalid, not a fork)", async () => {
+  const s = Object.assign({}, F.B[1], { batch_root: "0".repeat(64) });
+  assert.equal((await logObserve(newLogStore(), s)).state, "invalid");
+});
+test("the witness token binds one head: valid for it, refused for the forked head", async () => {
+  assert.equal((await verifyWitnessToken(F.witness.token, F.A[2].sha256, F.jwks)).ok, true);
+  assert.equal((await verifyWitnessToken(F.witness.token, F.B[2].sha256, F.jwks)).ok, false);
+});
+test("live: the production log is consistent and GitHub's witness co-signature verifies", async () => {
+  const c = new CrawlCheck(); await c.resolve("github.com");
+  const r = await c.logCheck({ report: false });
+  assert.equal(r.consistent, true, r.summary);
+  assert.ok(r.witnessed && r.witnessed.token === true, JSON.stringify(r.witnessed));
+});