@sanning/proof 0.14.0 → 0.15.0

package/dist/cli.d.ts

@@ -1,6 +1,4 @@
 #!/usr/bin/env node
-import { type WitnessLine } from "./case.js";
-import { type CachedWitnessTime, type WitnessTimeAnswer, type WitnessTimeCheck } from "./witness-cache.js";
 interface Cli {
     out: (s: string) => void;
     err: (s: string) => void;
@@ -106,46 +104,6 @@ export declare function readFileEntry(entry: TreeEntry, key: string): Promise<Ui
  */
 export declare function treeFromArguments(paths: readonly string[]): Promise<Map<string, TreeEntry>>;
 export declare const CASE_USAGE: string;
-interface OnChainRow {
-    ref: string;
-    witnesses: number;
-    confirmed: number;
-    mismatched: number;
-    unreachable: number;
-    not_checked: number;
-    /** Present only where the pack caches a witness time (5.6.6, v1.25, A30). */
-    witness_times?: WitnessTimeRow[];
-}
-interface WitnessTimeRow {
-    stamp_ref: string;
-    cached: {
-        block_height: number;
-        block_time: number;
-    };
-    outcome: WitnessTimeCheck["outcome"];
-    answers: {
-        gateway: string;
-        outcome: WitnessTimeAnswer["outcome"];
-        block_height: number | null;
-        block_time: number | null;
-    }[];
-}
-interface OnChainHalf {
-    /** Present only where a lookup ran: each gateway that answered, in the order given. */
-    answered?: string[];
-    checked: boolean;
-    gateways: string[];
-    packs: OnChainRow[];
-    verdict: "not_checked" | "confirmed" | "failed" | "undetermined";
-}
-/**
- * `cached` is every witness time the packs cache (5.6.6, v1.25, A30). Where no
- * lookup ran, each is printed labelled not checked. Where one ran, each time
- * the public record matched is printed as the record's, each time no lookup
- * settled stays labelled not checked, and a time the record contradicts is the
- * reason the line reads `differs`.
- */
-export declare function witnessLine(onChain: OnChainHalf, cached?: readonly CachedWitnessTime[]): WitnessLine;
 /**
  * The case verdict's code, moved only by an on-chain half that was asked for:
  * a witness that does not match is a failure whatever the reading said, and an

package/dist/cli.js

@@ -48,7 +48,7 @@ import { basename, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isAgentProofSpec, verifyAgentProof } from "./agent-proof.js";
 import { CHAIN_READING_SCOPE, readChains, renderChainFinding } from "./chain.js";
-import { VERDICT_DISPLAY_TITLES, WITNESS_NOT_LOOKED_UP, caseReliance, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
+import { VERDICT_DISPLAY_TITLES, caseReliance, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
 import { CASE_FILE_INDEX_NAME, jsonDepthExceeds, readCaseFileIndex, renderCaseFileFinding, } from "./case-file.js";
 import { ZipReadError, readZip } from "./zip-reader.js";
 import { composeExport } from "./compose.js";
@@ -56,7 +56,13 @@ import { isHexField, sha256Hex, utf8 } from "./crypto.js";
 import { verifyEvidenceBundle } from "./evidence.js";
 import { DuplicateKeyError, parseRefusingDuplicates } from "./verifier.js";
 import { fileMatchToJson, matchCaseFiles, matchFiles, renderFileMatch } from "./file-match.js";
-import { WITNESS_CACHE_NAME, checkWitnessCache, readWitnessCache, renderWitnessTime, } from "./witness-cache.js";
+import { WITNESS_CACHE_NAME, readWitnessCache, } from "./witness-cache.js";
+// The public-record (witness) lookup this command runs with `--gateways`:
+// moved to its own pure module (proof#200) so a consumer that is not this CLI,
+// the verify page, can call the SAME implementation. `onChainHalf` and
+// `witnessLine` are this command's own two building blocks, unchanged; see
+// `./witness-lookup.ts` for the exported entry point, `lookupPublicRecord`.
+import { onChainHalf, witnessLine } from "./witness-lookup.js";
 import { checkDeclaration, renderDeclarationSummary, renderNote } from "./declaration.js";
 import { completenessNotes, gradePack, renderCause } from "./grading.js";
 import { EXIT_CODES_HELP, EXIT_FAILED, EXIT_MALFORMED, EXIT_UNDETERMINED, EXIT_VERIFIED, exitCodeFor, } from "./exit-codes.js";
@@ -1744,162 +1750,6 @@ function sortKeys(v) {
 function jsonText(v) {
     return JSON.stringify(sortKeys(v), null, 2);
 }
-function witnessTimeRow(t) {
-    return {
-        stamp_ref: t.cached.stampRef,
-        cached: { block_height: t.cached.blockHeight, block_time: t.cached.blockTime },
-        outcome: t.outcome,
-        answers: t.answers.map((a) => ({
-            gateway: a.gateway,
-            outcome: a.outcome,
-            block_height: a.blockHeight,
-            block_time: a.blockTime,
-        })),
-    };
-}
-// Each pack's witnesses, re-fetched through `verifyEvidenceBundle`. Outside the
-// case reading on purpose: `readCase` makes no network call, and neither does
-// the verify page's case reading, so the case verdict stays the one both
-// surfaces compute. This adds the half the reading names as not checked.
-async function onChainHalf(packs, gateways, io) {
-    if (gateways.length === 0)
-        return { checked: false, gateways: [], packs: [], verdict: "not_checked" };
-    const rows = [];
-    const answered = new Set();
-    for (const [ref, bundle, cached] of packs) {
-        const result = await verifyEvidenceBundle(bundle, {
-            gateways,
-            ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
-        });
-        const witnesses = [...result.checkpoints, ...(result.stamps ?? [])];
-        const row = {
-            ref,
-            witnesses: witnesses.length,
-            confirmed: 0,
-            mismatched: 0,
-            unreachable: 0,
-            not_checked: 0,
-        };
-        for (const w of witnesses) {
-            const rollup = w.onChain?.rollup ?? null;
-            if (rollup === "confirm")
-                row.confirmed++;
-            else if (rollup === "mismatch")
-                row.mismatched++;
-            else if (rollup === "unreachable")
-                row.unreachable++;
-            else
-                row.not_checked++;
-        }
-        // The witness times the pack's witness-cache.json gives, looked up where
-        // it gives any (5.6.6, v1.25, A30). A pack with no cache gets no key and
-        // no request.
-        const times = await checkWitnessCache(cached, gateways, io.fetchImpl ?? fetch);
-        if (times.length > 0)
-            row.witness_times = times.map(witnessTimeRow);
-        rows.push(row);
-        for (const w of witnesses) {
-            for (const outcome of w.onChain?.perGateway ?? []) {
-                if (outcome.outcome === "confirm" || outcome.outcome === "mismatch") {
-                    answered.add(outcome.gateway);
-                }
-            }
-        }
-        for (const t of times) {
-            for (const a of t.answers) {
-                if (a.outcome === "matches" || a.outcome === "differs")
-                    answered.add(a.gateway);
-            }
-        }
-    }
-    const verdict = rows.some((r) => r.mismatched > 0 || (r.witness_times ?? []).some((t) => t.outcome === "differs"))
-        ? "failed"
-        : rows.some((r) => r.witnesses === 0 || r.unreachable > 0 || r.not_checked > 0)
-            ? "undetermined"
-            : "confirmed";
-    return {
-        answered: gateways.filter((g) => answered.has(g)),
-        checked: true,
-        gateways: [...gateways],
-        packs: rows,
-        verdict,
-    };
-}
-/**
- * The witness line (evidence-bundle 5.5.6 v1.20, A24, D7) from the on-chain
- * half: `confirmed` is `confirmed`, `not_checked` and `undetermined` are
- * `not_checked` with the reason, and `failed` is `differs`. It never moves the
- * headline.
- */
-// Distinct `[blockHeight, blockTime]` pairs, in time order.
-function distinctTimes(times) {
-    const seen = new Map();
-    for (const [h, t] of times)
-        seen.set(`${h}:${t}`, [h, t]);
-    return [...seen.values()].sort((a, b) => a[1] - b[1] || a[0] - b[0]);
-}
-// Only the keys that carry something: a line with no cached or recorded time
-// is the line 0.13.0 printed, field for field.
-function withTimes(line, cached, recorded) {
-    return {
-        ...line,
-        ...(cached.length > 0 ? { cached } : {}),
-        ...(recorded.length > 0 ? { recorded } : {}),
-    };
-}
-/**
- * `cached` is every witness time the packs cache (5.6.6, v1.25, A30). Where no
- * lookup ran, each is printed labelled not checked. Where one ran, each time
- * the public record matched is printed as the record's, each time no lookup
- * settled stays labelled not checked, and a time the record contradicts is the
- * reason the line reads `differs`.
- */
-export function witnessLine(onChain, cached = []) {
-    if (!onChain.checked) {
-        return withTimes({
-            state: WITNESS_NOT_LOOKED_UP.state,
-            reasons: [...WITNESS_NOT_LOOKED_UP.reasons],
-            services: [...WITNESS_NOT_LOOKED_UP.services],
-        }, distinctTimes(cached.map((c) => [c.blockHeight, c.blockTime])), []);
-    }
-    const services = [...(onChain.answered ?? [])];
-    const rows = onChain.packs;
-    const times = rows.flatMap((r) => r.witness_times ?? []);
-    const unsettled = distinctTimes(times
-        .filter((t) => t.outcome === "not_checked")
-        .map((t) => [t.cached.block_height, t.cached.block_time]));
-    const recorded = distinctTimes(times
-        .filter((t) => t.outcome === "matches")
-        .flatMap((t) => t.answers.filter((a) => a.outcome === "matches"))
-        .map((a) => [a.block_height, a.block_time]));
-    const contradicted = [];
-    for (const t of times) {
-        if (t.outcome !== "differs")
-            continue;
-        const a = t.answers.find((x) => x.outcome === "differs");
-        const reason = `a pack dates the witness ${renderWitnessTime(t.cached.block_height, t.cached.block_time)}` +
-            `, and the public record dates it ${renderWitnessTime(a.block_height, a.block_time)}`;
-        if (!contradicted.includes(reason))
-            contradicted.push(reason);
-    }
-    if (onChain.verdict === "failed") {
-        return withTimes({ state: "differs", reasons: contradicted, services }, unsettled, recorded);
-    }
-    if (onChain.verdict === "confirmed") {
-        return withTimes({ state: "confirmed", reasons: [], services }, unsettled, recorded);
-    }
-    const reasons = [];
-    if (rows.some((r) => r.witnesses === 0))
-        reasons.push("a pack names no witness");
-    if (rows.some((r) => r.unreachable > 0)) {
-        reasons.push("a lookup did not settle: the service could not be reached, or it " +
-            "holds no such witness yet");
-    }
-    if (rows.some((r) => r.not_checked > 0)) {
-        reasons.push("no lookup is made for a witness kind a pack names");
-    }
-    return withTimes({ state: "not_checked", reasons, services }, unsettled, recorded);
-}
 /**
  * The case verdict's code, moved only by an on-chain half that was asked for:
  * a witness that does not match is a failure whatever the reading said, and an
@@ -2137,7 +1987,7 @@ async function caseCommand(argv, io) {
     for (const [p, bundle] of bundles) {
         caches.push(readWitnessCache(bundle, await witnessCacheBytes(tree, split, p)));
     }
-    const onChain = await onChainHalf(bundles.map(([p, bundle], i) => [p.ref, bundle, caches[i]]), gateways, io);
+    const onChain = await onChainHalf(bundles.map(([p, bundle], i) => [p.ref, bundle, caches[i]]), gateways, { ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}) });
     const witness = witnessLine(onChain, caches.flat());
     const code = caseExitCode(reading.verdict, onChain.verdict);
     const nil = (v) => (v === undefined ? null : v);

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export type { DeclarationCheck, DeclarationClaims, DeclarationContentFinding, De
 export { CASE_BODY_TYPES, CASE_EXCEPTION_KINDS, CASE_QUARANTINED_PROFILES, CASE_RECORD_PROFILES, CASE_NOTE_KINDS, CASE_RELIANCE, CASE_RELIANCE_HANDOFF_CLAUSE, CASE_VERDICTS, CONTENT_WITHHELD_BY_DECLARATION, CO_SIGNATURES_PRESENT, VERDICT_DISPLAY_TITLES, WITNESS_NOT_LOOKED_UP, WITNESS_STATES, WITNESS_TIME_CACHED, WITNESS_TIME_RECORDED, caseReliance, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
 export { MAX_BLOCK_TIME, MAX_WITNESS_CACHE_DEPTH, WITNESS_CACHE_NAME, WITNESS_CACHE_VERSION, checkWitnessCache, formatBlockTime, readWitnessCache, renderWitnessTime, witnessTimeQuery, } from "./witness-cache.js";
 export type { CachedWitnessTime, WitnessTimeAnswer, WitnessTimeCheck } from "./witness-cache.js";
+export { lookupPublicRecord, onChainHalf, witnessLine } from "./witness-lookup.js";
+export type { OnChainHalf, OnChainRow, PublicRecordPack, PublicRecordResult, PublicRecordState, WitnessLookupOptions, WitnessTimeRow, } from "./witness-lookup.js";
 export type { CaseException, CaseExceptionKind, CaseNote, CaseNoteKind, CasePack, CasePackReading, CaseReading, CaseRecordReading, CaseVerdict, WitnessLine, WitnessState, } from "./case.js";
 export { CASE_FILE_FINDING_KINDS, CASE_FILE_INDEX_NAME, CASE_FILE_VERSION, HOW_TO_VERIFY_NAME, REPORT_README_FIRST_LINE, howToVerifyText, isPackRef, readCaseFileIndex, renderCaseFileFinding, } from "./case-file.js";
 export type { CaseFileFinding, CaseFileFindingKind, CaseFileIndexReading, } from "./case-file.js";

package/dist/index.js

@@ -89,6 +89,21 @@ export { CASE_BODY_TYPES, CASE_EXCEPTION_KINDS, CASE_QUARANTINED_PROFILES, CASE_
 // The witnessed-time cache (evidence-bundle 5.6.6, v1.25, A30): read it, look it
 // up, print it. Never an input to a verdict.
 export { MAX_BLOCK_TIME, MAX_WITNESS_CACHE_DEPTH, WITNESS_CACHE_NAME, WITNESS_CACHE_VERSION, checkWitnessCache, formatBlockTime, readWitnessCache, renderWitnessTime, witnessTimeQuery, } from "./witness-cache.js";
+// The public-record (witness) lookup the CLI runs with `--gateways`
+// (src/witness-lookup.ts, proof#200): moved out of the CLI so a consumer
+// that is not the CLI, the verify page, calls the SAME implementation
+// rather than keeping its own copy (verify-page#70). Pure kernel scope: the
+// one network call lives in `lookupPublicRecord` and `onChainHalf`, runs
+// only when a caller hands in a gateway, and goes through `options.fetchImpl`
+// where a caller supplies one (a browser page's own `fetch`) or the ambient
+// global `fetch` otherwise, so this export runs in a browser exactly as it
+// runs in Node. `onChainHalf` and `witnessLine` are the CLI's own unchanged
+// building blocks; `lookupPublicRecord` is the new one-call, four-state entry
+// point a page wants, additive over both. `confirmed` from
+// `lookupPublicRecord` is a claim about the BYTES only, never about whether
+// the pack itself verifies, and a caller must never show it apart from the
+// pack's own verdict.
+export { lookupPublicRecord, onChainHalf, witnessLine } from "./witness-lookup.js";
 // The case file's index (src/case-file.ts, evidence-bundle.md §5.6, A25):
 // compared with the drop it describes, with NO verdict contribution. The index
 // is never an input to `readCase`. Pure: bytes and a file list in.

package/dist/witness-lookup.d.ts

@@ -0,0 +1,112 @@
+import type { WitnessLine, WitnessState } from "./case.js";
+import { type CachedWitnessTime, type WitnessTimeAnswer, type WitnessTimeCheck } from "./witness-cache.js";
+/** The seam every network call in this module goes through: used where given, else the ambient global `fetch`. */
+export interface WitnessLookupOptions {
+    fetchImpl?: typeof fetch;
+}
+export interface OnChainRow {
+    ref: string;
+    witnesses: number;
+    confirmed: number;
+    mismatched: number;
+    unreachable: number;
+    not_checked: number;
+    /** Present only where the pack caches a witness time (5.6.6, v1.25, A30). */
+    witness_times?: WitnessTimeRow[];
+}
+export interface WitnessTimeRow {
+    stamp_ref: string;
+    cached: {
+        block_height: number;
+        block_time: number;
+    };
+    outcome: WitnessTimeCheck["outcome"];
+    answers: {
+        gateway: string;
+        outcome: WitnessTimeAnswer["outcome"];
+        block_height: number | null;
+        block_time: number | null;
+    }[];
+}
+export interface OnChainHalf {
+    /** Present only where a lookup ran: each gateway that answered, in the order given. */
+    answered?: string[];
+    checked: boolean;
+    gateways: string[];
+    packs: OnChainRow[];
+    verdict: "not_checked" | "confirmed" | "failed" | "undetermined";
+}
+/**
+ * Each pack's witnesses, re-fetched through `verifyEvidenceBundle`. Outside
+ * the case reading on purpose: `readCase` makes no network call, and neither
+ * does the verify page's case reading, so the case verdict stays the one both
+ * surfaces compute. This adds the half the reading names as not checked.
+ *
+ * Moved from `cli.ts` unchanged, apart from taking `fetchImpl` directly
+ * instead of a `Cli` stream (`io.fetchImpl ?? fetch`, the same fallback the
+ * CLI already applied at its own call site).
+ */
+export declare function onChainHalf(packs: readonly (readonly [string, unknown, readonly CachedWitnessTime[]])[], gateways: readonly string[], options?: WitnessLookupOptions): Promise<OnChainHalf>;
+/**
+ * `cached` is every witness time the packs cache (5.6.6, v1.25, A30). Where no
+ * lookup ran, each is printed labelled not checked. Where one ran, each time
+ * the public record matched is printed as the record's, each time no lookup
+ * settled stays labelled not checked, and a time the record contradicts is the
+ * reason the line reads `differs`.
+ *
+ * Moved from `cli.ts` unchanged: same inputs, same three states
+ * (`WitnessState`), same rendering. The CLI's `case` command still calls this
+ * exact function, so its witness line is unchanged.
+ */
+export declare function witnessLine(onChain: OnChainHalf, cached?: readonly CachedWitnessTime[]): WitnessLine;
+/** The four states this export's result can carry. The CLI's own `WitnessState` plus `no_public_record`. */
+export type PublicRecordState = WitnessState | "no_public_record";
+/**
+ * One pack, as this lookup needs it: the parsed `bundle.json` and, where the
+ * pack carries one, the RAW BYTES of its `witness-cache.json`, read as part
+ * of the pack, per proof#200's acceptance criteria, rather than as a
+ * separately-loaded side file. `null` and `undefined` both mean "this pack has
+ * no witness-cache.json", the same reading `readWitnessCache` gives a missing
+ * file.
+ */
+export interface PublicRecordPack {
+    /** How this pack is named in the result; carries no meaning beyond that. */
+    ref: string;
+    bundle: unknown;
+    witnessCache?: Uint8Array | null;
+}
+export interface PublicRecordResult {
+    state: PublicRecordState;
+    reasons: string[];
+    services: string[];
+    /** Witness times a pack caches that no lookup settled (5.6.6, v1.25, A30). */
+    cached?: [number, number][];
+    /** Witness times the public record returned that matched a pack's cache. */
+    recorded?: [number, number][];
+    /** The line as both the CLI and a page print it, one string, kernel words. */
+    rendered: string;
+}
+/**
+ * The public-record lookup the CLI runs with `--gateways`, exported so a
+ * consumer that is not the CLI can run the SAME lookup rather than copy it
+ * (proof#200; the copy this closes is verify-page#70's `src/lib/verify.ts`).
+ *
+ * `packs` is every pack in the drop being read; `gateways` is empty for an
+ * offline reading, which never makes a network call and always answers
+ * `not_checked` or `no_public_record`. `options.fetchImpl` is the one seam a
+ * network call goes through, a browser page supplies its own `fetchImpl`;
+ * with none given this falls back to the ambient global `fetch`, so a
+ * browser page and a test can each supply their own and Node's `fetch` is
+ * never assumed where a caller passed something else.
+ *
+ * `state` is `confirmed` only about the BYTES: the public record holds what a
+ * pack names. It says nothing about whether the pack itself verifies (its
+ * wrapper signature, its `body_hash`), and a caller must never show
+ * `confirmed` apart from the pack's own verdict (proof#201).
+ *
+ * Never throws. Every input, including a malformed pack, a non-string
+ * gateway, or a `fetchImpl` that itself misbehaves, is read as untrusted, and
+ * anything this function or what it calls cannot make sense of settles as
+ * `not_checked` rather than escape as an exception.
+ */
+export declare function lookupPublicRecord(packs: readonly PublicRecordPack[], gateways: readonly string[], options?: WitnessLookupOptions): Promise<PublicRecordResult>;