@sanning/proof 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -2,16 +2,22 @@ export { ACCEPTED_SPEC_MAJORS, contentHashes, jcs, specVersionSupported, verifyE
 export { bytesToHex, deriveOperatorAddress, ed25519Verify, hexToBytes, sha256Bytes, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
 export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyInclusion, } from "./merkle.js";
 export type { ContentRole, Envelope, Subject, VerificationResult, VerifyOptions } from "./types.js";
-export { ACCEPTED_EVIDENCE_MAJORS, ANCHOR_TRACE_BODY_TYPE, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, STAMP_EVIDENCE_BODY_TYPE, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
+export { ACCEPTED_EVIDENCE_MAJORS, ANCHOR_TRACE_BODY_TYPE, CO_SIGNATURES_NOTE, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, STAMP_EVIDENCE_BODY_TYPE, coSignaturesPresent, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
 export type { AnchorTraceBody, AttestationPayload, AttestationRecord, AttestationResult, CheckpointResult, ComposeVerdictResult, DisclosedContentResult, DisclosedEventContent, DisclosureStatus, EvidenceBundle, EvidenceBundleResult, EvidenceIssuer, EvidenceStatus, EvidenceVerdict, EventResult, ExportBody, ExportResult, OnChainOutcome, OnChainResult, PerGatewayOutcome, AnchorRef, StampBody, StampEntry, StampResult, StampSubtree, StampSubtreeResult, StampTraceBody, StampEvidenceBody, StampEvidenceEvent, StampEvidenceInclusion, TraceCheckpoint, TraceEvent, TraceInclusion, VerdictAttestation, VerdictCheckpoint, VerdictEvent, VerdictObject, VerdictOnChain, VerdictOnChainGateway, VerifyEvidenceOptions, } from "./evidence.js";
 export { PACK_GRADE_CAUSE_KINDS, PACK_VERDICTS, accountDisclosure, completenessNotes, gradeCauses, gradePack, renderCause, signedLeafCount, } from "./grading.js";
 export type { CompletenessNote, DisclosureAccount, GradeInput, PackGrade, PackGradeCause, PackGradeCauseKind, PackVerdict, } from "./grading.js";
 export { DECLARATION_CONTENT_KINDS, DECLARATION_DEVIATION_KINDS, DECLARATION_NOTE_KINDS, DECLARATION_ROLES, DECLARATION_VERDICTS, DECLARATION_VERSION, DECLARATION_VERSION_V2, DECLARATION_VERSIONS, checkDeclaration, declarationClaims, packRecords, renderContentFinding, renderDeclarationSummary, renderDeviation, renderNote, } from "./declaration.js";
 export type { DeclarationCheck, DeclarationClaims, DeclarationContentFinding, DeclarationContentKind, DeclarationDeviation, DeclarationDeviationKind, DeclarationNote, DeclarationNoteKind, DeclarationRole, DeclarationVerdict, PackRecord, } from "./declaration.js";
-export { CASE_BODY_TYPES, CASE_EXCEPTION_KINDS, CASE_QUARANTINED_PROFILES, CASE_RECORD_PROFILES, CASE_NOTE_KINDS, CASE_RELIANCE, CASE_VERDICTS, CONTENT_WITHHELD_BY_DECLARATION, VERDICT_DISPLAY_TITLES, WITNESS_NOT_LOOKED_UP, WITNESS_STATES, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
+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";
+export { FILE_MATCH_SCOPE, NOT_READ_REASONS, fileMatchToJson, matchCaseFiles, matchFiles, renderFileMatch, } from "./file-match.js";
+export type { FileCommitment, FileMatchPack, FileMatchReading, MatchedFile, NotRead, NotReadReason, OfferedFile, UnmatchedFile, } from "./file-match.js";
 export { ADAPTER_CHAIN_NAMESPACES, CHAIN_READING_SCOPE, readChains, renderChainFinding, } from "./chain.js";
 export type { ChainFinding, ChainFindingKind, ChainReading, ChainSource, ChainSummary, } from "./chain.js";
 export { EXIT_CODES, EXIT_CODES_HELP, EXIT_FAILED, EXIT_MALFORMED, EXIT_MIXED, EXIT_UNDETERMINED, EXIT_VERIFIED, exitCodeFor, } from "./exit-codes.js";

package/dist/index.js

@@ -34,7 +34,7 @@ export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyI
 // files that failed verification on genuine evidence. This hands back DECODED
 // bytes, and only for events whose verification bound them to the committed
 // content_hash. Additive; verifyEvidenceBundle's behavior is unchanged.
-export { ACCEPTED_EVIDENCE_MAJORS, ANCHOR_TRACE_BODY_TYPE, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, STAMP_EVIDENCE_BODY_TYPE, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
+export { ACCEPTED_EVIDENCE_MAJORS, ANCHOR_TRACE_BODY_TYPE, CO_SIGNATURES_NOTE, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, STAMP_EVIDENCE_BODY_TYPE, coSignaturesPresent, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
 // Pack grading (src/grading.ts): what a verification SURFACE may claim about a
 // pack — the signed bundle PLUS whatever disclosed bytes travelled beside it.
 //
@@ -85,11 +85,33 @@ export { DECLARATION_CONTENT_KINDS, DECLARATION_DEVIATION_KINDS, DECLARATION_NOT
 //
 // Pure: data in, data out, no I/O. Additive: a new module, no existing export
 // changes, and no new verdict word anywhere.
-export { CASE_BODY_TYPES, CASE_EXCEPTION_KINDS, CASE_QUARANTINED_PROFILES, CASE_RECORD_PROFILES, CASE_NOTE_KINDS, CASE_RELIANCE, CASE_VERDICTS, CONTENT_WITHHELD_BY_DECLARATION, VERDICT_DISPLAY_TITLES, WITNESS_NOT_LOOKED_UP, WITNESS_STATES, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
+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";
+// 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.
 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";
+// Files handed in beside a pack (src/file-match.ts, evidence-bundle.md §5.7,
+// A29, proof#92): each file's SHA-256 matched against the commitments the
+// pack's SIGNED records make, by hash alone. Never moves a verdict.
+export { FILE_MATCH_SCOPE, NOT_READ_REASONS, fileMatchToJson, matchCaseFiles, matchFiles, renderFileMatch, } from "./file-match.js";
 // Chain reading (src/chain.ts): following the pointer every sanning.events/v2
 // record carries to the record before it, over the records ONE bundle presents.
 //

package/dist/message-parts.d.ts

@@ -118,12 +118,18 @@ export declare const REFUSAL_ORDER: readonly ["bytes_for_unknown_part", "conflic
 export declare const MESSAGE_RESULT_ORDER: readonly ["parts_not_an_array"];
 /**
  * The keys that make a part carry its content INLINE, in the order they are
- * read. Named rather than inferred: `bytes`, `data` and `content` are the
- * spellings in the wild. None is A2A 1.0.0's: its `Part` has no `kind` and
+ * read. Settled at `bytes` alone (envelope-spec §4.1, A31, proof#163): that
+ * is A2A's spelling, the one the wedge actually emits, and it is the only
+ * inline spelling either reference kernel has read from a real producer.
+ * `content` and `data` were added on inference rather than on an observed
+ * wire shape, and sanning-io/anchor's `filePart()` and `file_part()` SDK
+ * helpers, the only producer this plane ships, confirm the inference was
+ * wrong: both emit a descriptor part, `kind: "file"` plus `content_hash` and
+ * `content_length`, and neither ever writes a `content` or `data` wire key
+ * for inline bytes. None is A2A 1.0.0's either: its `Part` has no `kind` and
  * carries a file as `raw` or `url`, so a literal A2A part reads
- * `part_not_a_file` (envelope-spec §4.1, A19). The FIRST of them present with
- * a value that is not `null` is the inline content, so a part spelling it
- * twice reads one way in both kernels.
+ * `part_not_a_file` (envelope-spec §4.1, A19). The one key present with a
+ * value that is not `null` is the inline content.
  *
  * A key present with `null` is an ABSENT inline value, on A14's ruling that an
  * absent value and one written as `null` name one thing. That matters: a
@@ -132,7 +138,7 @@ export declare const MESSAGE_RESULT_ORDER: readonly ["parts_not_an_array"];
  * (proof#156 gate). Such a part falls through to the descriptor rule, which is
  * what it is.
  */
-export declare const INLINE_BYTES_KEYS: readonly ["bytes", "content", "data"];
+export declare const INLINE_BYTES_KEYS: readonly ["bytes"];
 /**
  * The largest integer a double carries exactly, the same bound section 4.1 puts
  * on `event.sequence`: a `content_length` outside it is a value the two kernels

package/dist/message-parts.js

@@ -262,12 +262,18 @@ const HELD_UNCHECKED_RESULTS = [
 ];
 /**
  * The keys that make a part carry its content INLINE, in the order they are
- * read. Named rather than inferred: `bytes`, `data` and `content` are the
- * spellings in the wild. None is A2A 1.0.0's: its `Part` has no `kind` and
+ * read. Settled at `bytes` alone (envelope-spec §4.1, A31, proof#163): that
+ * is A2A's spelling, the one the wedge actually emits, and it is the only
+ * inline spelling either reference kernel has read from a real producer.
+ * `content` and `data` were added on inference rather than on an observed
+ * wire shape, and sanning-io/anchor's `filePart()` and `file_part()` SDK
+ * helpers, the only producer this plane ships, confirm the inference was
+ * wrong: both emit a descriptor part, `kind: "file"` plus `content_hash` and
+ * `content_length`, and neither ever writes a `content` or `data` wire key
+ * for inline bytes. None is A2A 1.0.0's either: its `Part` has no `kind` and
  * carries a file as `raw` or `url`, so a literal A2A part reads
- * `part_not_a_file` (envelope-spec §4.1, A19). The FIRST of them present with
- * a value that is not `null` is the inline content, so a part spelling it
- * twice reads one way in both kernels.
+ * `part_not_a_file` (envelope-spec §4.1, A19). The one key present with a
+ * value that is not `null` is the inline content.
  *
  * A key present with `null` is an ABSENT inline value, on A14's ruling that an
  * absent value and one written as `null` name one thing. That matters: a
@@ -276,11 +282,13 @@ const HELD_UNCHECKED_RESULTS = [
  * (proof#156 gate). Such a part falls through to the descriptor rule, which is
  * what it is.
  */
-// A conformant DESCRIPTOR part that also carries a `content` or `data` key
-// meaning something else (a filename, a metadata blob) is reclassified by this
-// list and never checked against supplied bytes. That is inside section 4.1's
-// stated rule, and whether these parts ought to fall into it is proof#163.
-export const INLINE_BYTES_KEYS = ["bytes", "content", "data"];
+// Before A31 this list also carried `content` and `data`, and a conformant
+// DESCRIPTOR part that happened to carry either key meaning something else (a
+// filename, a caption) was silently reclassified as inline and never checked
+// against supplied bytes: the swapped-bytes check A18 exists to run
+// (proof#145) never ran on it. proof#163 is resolved by narrowing to `bytes`
+// alone, closing that gap.
+export const INLINE_BYTES_KEYS = ["bytes"];
 const HEX64 = /^[0-9a-fA-F]{64}$/;
 const HEX_CHARSET = /^[0-9a-fA-F]+$/;
 const LOWER_HEX = "0123456789abcdef";

package/dist/verifier.d.ts

@@ -8,11 +8,13 @@ export declare function jcs(value: unknown): string;
  * twin is `jcs_loads` in `src/sanning_proof/canonicalize.py`, and every site in
  * either kernel that reads bytes a producer signed goes through one of the two.
  *
- * ONE RULE, SPELLED OUT, BECAUSE TWO BUILT-INS ARE NOT ONE RULE. Four checks
+ * ONE RULE, SPELLED OUT, BECAUSE TWO BUILT-INS ARE NOT ONE RULE. Five checks
  * carry it, none of them left to a decoder's defaults: strict UTF-8, no leading
  * byte-order mark, no non-finite literal (this kernel's `JSON.parse` rejects
  * `NaN`, `Infinity` and `-Infinity` natively, and Python names them in a
- * `parse_constant` hook), and no unpaired surrogate in the parsed value.
+ * `parse_constant` hook), no object that repeats a member name
+ * (`DuplicateKeyError`, proof#144), and no unpaired surrogate in the parsed
+ * value.
  *
  * THE FOURTH CHECK IS NOT THE FIRST ONE TWICE. The strict decode refuses a
  * surrogate written as raw bytes; it cannot see one written as the ASCII
@@ -46,6 +48,56 @@ export declare function jcs(value: unknown): string;
  */
 export declare function utf8Strict(bytes: Uint8Array): string;
 export declare function jcsParse(bytes: Uint8Array): unknown;
+/**
+ * A JSON object that names one member twice (I-JSON, RFC 7493 section 2.3).
+ * The Python twin is `DuplicateKey` in `canonicalize.py`, and the message is
+ * the same kernel wording in both: `duplicate key ` and the name as
+ * `renderKey` spells it.
+ *
+ * JCS (RFC 8785) is defined over I-JSON, and I-JSON forbids duplicate member
+ * names, so bytes that repeat a name are MALFORMED rather than another spelling
+ * of the last value. `JSON.parse` and Python's `json.loads` both keep the last
+ * value and say nothing, which let a bundle carrying `"spec_version":"junk"`
+ * before its real `spec_version` read `verified` in both kernels (proof#144).
+ */
+export declare class DuplicateKeyError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+/**
+ * A member name as a quoted, pure-ASCII string, identically in both kernels
+ * (`render_key` in the Python twin). Printable ASCII other than `"` and `\` is
+ * kept; `"` and `\` are backslash-escaped; every other UTF-16 code unit is
+ * `\uXXXX` in lower-case hex. A rendering longer than 64 characters is cut
+ * there and `...` follows the closing quote.
+ */
+export declare function renderKey(key: string): string;
+/**
+ * `JSON.parse(text)`, refusing an object that repeats a member name. The Python
+ * twin is `loads_refusing_duplicates` in `canonicalize.py`.
+ *
+ * `JSON.parse` cannot see a repeat, because it keeps the last value, so the
+ * text is scanned once more AFTER it parsed. The parse runs first, so text
+ * that is not JSON at all fails as JSON and never as a duplicate, as it does in
+ * the Python twin. Throws `DuplicateKeyError`.
+ */
+export declare function parseRefusingDuplicates(text: string): unknown;
+/**
+ * The repeated member name to report for text `JSON.parse` has already
+ * accepted, or `undefined` when no object repeats one.
+ *
+ * WHICH ONE, because both kernels must name the same one. Objects are checked
+ * as they CLOSE, innermost first, which is the order Python's
+ * `object_pairs_hook` sees them in; inside one object the name reported is the
+ * first whose repeat comes earliest. Names compare after unescaping, so `"a"`
+ * and `"\u0061"` are one name, as they are to both parsers.
+ *
+ * ITERATIVE, with an explicit stack, for the reason `rejectUnpairedSurrogates`
+ * is: this walks bytes a producer wrote. It relies on the text being valid
+ * JSON, which is why it runs only after `JSON.parse` succeeded: outside a
+ * string, only `{`, `[`, `}`, `]`, `,` and `"` change what comes next.
+ */
+export declare function firstDuplicateKey(text: string): string | undefined;
 export declare function specVersionSupported(specVersion: string, accepted?: readonly string[]): boolean;
 export declare function isRfc3339UtcInstant(value: unknown): boolean;
 export declare function contentHashes(env: Envelope): {

package/dist/verifier.js

@@ -187,11 +187,13 @@ const JCS_BOM = "";
  * twin is `jcs_loads` in `src/sanning_proof/canonicalize.py`, and every site in
  * either kernel that reads bytes a producer signed goes through one of the two.
  *
- * ONE RULE, SPELLED OUT, BECAUSE TWO BUILT-INS ARE NOT ONE RULE. Four checks
+ * ONE RULE, SPELLED OUT, BECAUSE TWO BUILT-INS ARE NOT ONE RULE. Five checks
  * carry it, none of them left to a decoder's defaults: strict UTF-8, no leading
  * byte-order mark, no non-finite literal (this kernel's `JSON.parse` rejects
  * `NaN`, `Infinity` and `-Infinity` natively, and Python names them in a
- * `parse_constant` hook), and no unpaired surrogate in the parsed value.
+ * `parse_constant` hook), no object that repeats a member name
+ * (`DuplicateKeyError`, proof#144), and no unpaired surrogate in the parsed
+ * value.
  *
  * THE FOURTH CHECK IS NOT THE FIRST ONE TWICE. The strict decode refuses a
  * surrogate written as raw bytes; it cannot see one written as the ASCII
@@ -230,10 +232,139 @@ export function jcsParse(bytes) {
     const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
     if (text.startsWith(JCS_BOM))
         throw new Error("jcsParse: leading byte-order mark");
-    const value = JSON.parse(text);
+    const value = parseRefusingDuplicates(text);
     rejectUnpairedSurrogates(value);
     return value;
 }
+/**
+ * A JSON object that names one member twice (I-JSON, RFC 7493 section 2.3).
+ * The Python twin is `DuplicateKey` in `canonicalize.py`, and the message is
+ * the same kernel wording in both: `duplicate key ` and the name as
+ * `renderKey` spells it.
+ *
+ * JCS (RFC 8785) is defined over I-JSON, and I-JSON forbids duplicate member
+ * names, so bytes that repeat a name are MALFORMED rather than another spelling
+ * of the last value. `JSON.parse` and Python's `json.loads` both keep the last
+ * value and say nothing, which let a bundle carrying `"spec_version":"junk"`
+ * before its real `spec_version` read `verified` in both kernels (proof#144).
+ */
+export class DuplicateKeyError extends Error {
+    key;
+    constructor(key) {
+        super(`duplicate key ${renderKey(key)}`);
+        this.key = key;
+    }
+}
+// The longest rendered name a message carries, in characters, before it is
+// cut. The rendering is pure ASCII, so the cut lands on the same character in
+// both kernels.
+const RENDERED_KEY_MAX = 64;
+/**
+ * A member name as a quoted, pure-ASCII string, identically in both kernels
+ * (`render_key` in the Python twin). Printable ASCII other than `"` and `\` is
+ * kept; `"` and `\` are backslash-escaped; every other UTF-16 code unit is
+ * `\uXXXX` in lower-case hex. A rendering longer than 64 characters is cut
+ * there and `...` follows the closing quote.
+ */
+export function renderKey(key) {
+    let body = "";
+    for (let i = 0; i < key.length; i++) {
+        const c = key.charCodeAt(i);
+        const ch = key[i];
+        if (ch === '"' || ch === "\\")
+            body += "\\" + ch;
+        else if (c >= 0x20 && c <= 0x7e)
+            body += ch;
+        else
+            body += "\\u" + c.toString(16).padStart(4, "0");
+    }
+    if (body.length > RENDERED_KEY_MAX)
+        return `"${body.slice(0, RENDERED_KEY_MAX)}"...`;
+    return `"${body}"`;
+}
+/**
+ * `JSON.parse(text)`, refusing an object that repeats a member name. The Python
+ * twin is `loads_refusing_duplicates` in `canonicalize.py`.
+ *
+ * `JSON.parse` cannot see a repeat, because it keeps the last value, so the
+ * text is scanned once more AFTER it parsed. The parse runs first, so text
+ * that is not JSON at all fails as JSON and never as a duplicate, as it does in
+ * the Python twin. Throws `DuplicateKeyError`.
+ */
+export function parseRefusingDuplicates(text) {
+    const value = JSON.parse(text);
+    const dup = firstDuplicateKey(text);
+    if (dup !== undefined)
+        throw new DuplicateKeyError(dup);
+    return value;
+}
+/**
+ * The repeated member name to report for text `JSON.parse` has already
+ * accepted, or `undefined` when no object repeats one.
+ *
+ * WHICH ONE, because both kernels must name the same one. Objects are checked
+ * as they CLOSE, innermost first, which is the order Python's
+ * `object_pairs_hook` sees them in; inside one object the name reported is the
+ * first whose repeat comes earliest. Names compare after unescaping, so `"a"`
+ * and `"\u0061"` are one name, as they are to both parsers.
+ *
+ * ITERATIVE, with an explicit stack, for the reason `rejectUnpairedSurrogates`
+ * is: this walks bytes a producer wrote. It relies on the text being valid
+ * JSON, which is why it runs only after `JSON.parse` succeeded: outside a
+ * string, only `{`, `[`, `}`, `]`, `,` and `"` change what comes next.
+ */
+export function firstDuplicateKey(text) {
+    // `names` is null for an array. `expectName` is true where the next string
+    // is a member name rather than a value.
+    const stack = [];
+    const n = text.length;
+    let i = 0;
+    while (i < n) {
+        const c = text.charCodeAt(i);
+        if (c === 0x22) {
+            let j = i + 1;
+            for (;;) {
+                const d = text.charCodeAt(j);
+                if (d === 0x5c)
+                    j += 2;
+                else if (d === 0x22)
+                    break;
+                else
+                    j++;
+            }
+            const top = stack[stack.length - 1];
+            if (top !== undefined && top.names !== null && top.expectName) {
+                const name = JSON.parse(text.slice(i, j + 1));
+                if (top.names.has(name)) {
+                    if (top.dup === undefined)
+                        top.dup = name;
+                }
+                else {
+                    top.names.add(name);
+                }
+                top.expectName = false;
+            }
+            i = j + 1;
+            continue;
+        }
+        if (c === 0x7b)
+            stack.push({ names: new Set(), expectName: true });
+        else if (c === 0x5b)
+            stack.push({ names: null, expectName: false });
+        else if (c === 0x7d || c === 0x5d) {
+            const closed = stack.pop();
+            if (closed?.dup !== undefined)
+                return closed.dup;
+        }
+        else if (c === 0x2c) {
+            const top = stack[stack.length - 1];
+            if (top !== undefined && top.names !== null)
+                top.expectName = true;
+        }
+        i++;
+    }
+    return undefined;
+}
 /**
  * Refuse a parsed value carrying an unpaired surrogate, in a key or a value, at
  * any depth. The Python twin is `_reject_unpaired_surrogates`, and the two name
@@ -396,8 +527,69 @@ function skeletonFieldErrors(env) {
     if (environment !== undefined && environment !== "dev" && environment !== "production") {
         out.push('malformed environment: not "dev" or "production" (envelope-spec §2)');
     }
+    out.push(...identityFieldErrors(own));
+    return out;
+}
+// The four fields envelope-spec §2 types and A23 pins (proof#97, proof#155).
+// Every pattern is anchored at both ends with no `m` flag, so `$` never matches
+// before a trailing newline, and uses ASCII classes only.
+//
+// `event_id`: "UUID v4, lowercase", the pattern both SDKs already refuse to
+// sign anything else under (`UUID_V4_RE` in `@sanning/anchor`, `_UUID_V4_RE` in
+// `sanning-anchor`); the Go agent's `uuid.NewString` emits the same.
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+// `payload_hash`: sha256-hex, which invariant 2 defines as lowercase hex with no
+// `0x`. Lower case is pinned here, unlike `public_key`, because every kernel
+// compares the value against a digest it recomputes in lower case: an
+// upper-case `payload_hash` already failed wherever there was material.
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+// `payload_ref`: §2 says "string (URI)" and names no grammar, so this pins what
+// both SDKs emit: an ASCII scheme, a colon, then RFC 3986 unreserved, reserved
+// and percent-encoded characters, at most 2048 of them in all (`REF_RE` and
+// `MAX_REF_LEN` in `@sanning/anchor`'s `ref.ts`).
+const URI_REF = /^[A-Za-z][A-Za-z0-9+.-]*:[A-Za-z0-9\-._~:/?#[\]@!$&'()*+,;=%]*$/;
+const MAX_URI_REF = 2048;
+// `subject`: "string fields <=128 chars matching `^[A-Za-z0-9_.:-]+$`".
+const SUBJECT_FIELD = /^[A-Za-z0-9_.:-]{1,128}$/;
+// `event_id`, `payload_hash`, `payload_ref` and `subject` (A23). Each is checked
+// only when present, and present includes a JSON null, as for `signed_at`.
+// `payload_hash` is the exception: only a STRING is checked here, because a
+// missing or non-string one is already `missing payload_hash` below, and naming
+// it twice would state one fact in two sets of words. `subject` fixes only its
+// STRING members: §2 types no other, so a member of another type is left as it
+// was. Own members only, as everywhere in this file. The messages are
+// byte-identical to the Python and Go kernels'.
+function identityFieldErrors(own) {
+    const out = [];
+    const eventId = own("event_id");
+    if (eventId !== undefined && !(typeof eventId === "string" && UUID_V4.test(eventId))) {
+        out.push("malformed event_id: not a lowercase UUID v4 (envelope-spec §2)");
+    }
+    const payloadHash = own("payload_hash");
+    if (typeof payloadHash === "string" && !SHA256_HEX.test(payloadHash)) {
+        out.push("malformed payload_hash: not 64 lowercase hex characters (envelope-spec §2)");
+    }
+    const payloadRef = own("payload_ref");
+    if (payloadRef !== undefined &&
+        !(typeof payloadRef === "string" && payloadRef.length <= MAX_URI_REF && URI_REF.test(payloadRef))) {
+        out.push("malformed payload_ref: not a URI of at most 2048 RFC 3986 characters (envelope-spec §2)");
+    }
+    const subject = own("subject");
+    if (subject !== undefined && !isWellFormedSubject(subject)) {
+        out.push("malformed subject: not an object whose string fields are 1 to 128 characters of [A-Za-z0-9_.:-] (envelope-spec §2)");
+    }
     return out;
 }
+function isWellFormedSubject(subject) {
+    if (typeof subject !== "object" || subject === null || Array.isArray(subject))
+        return false;
+    for (const key of Object.keys(subject)) {
+        const v = subject[key];
+        if (typeof v === "string" && !SUBJECT_FIELD.test(v))
+            return false;
+    }
+    return true;
+}
 // The content hash(es) an envelope commits to, by event type — the values a
 // reverse lookup can match the user's in-browser file hash against.
 //   asset_registered -> payload.hash            (the registered, known-good bytes)

package/dist/witness-cache.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The last second a block time can name and still be printed the same way by
+ * both kernels: 9999-12-31T23:59:59Z. A larger value is a cache entry this
+ * reader cannot print, and reads as none.
+ */
+export declare const MAX_BLOCK_TIME = 253402300799;
+/** The file's name, beside `bundle.json` in the pack's folder (5.6.1). */
+export declare const WITNESS_CACHE_NAME = "witness-cache.json";
+/**
+ * The dispatch key: a file whose `cache_version` is absent or any other value
+ * reads as no cache.
+ */
+export declare const WITNESS_CACHE_VERSION = "sanning.witness-cache/v1";
+/**
+ * How deep `[` and `{` may nest in the file before it is refused unread: the
+ * limit `bundle.json` and `contents.json` are read under.
+ */
+export declare const MAX_WITNESS_CACHE_DEPTH = 512;
+/**
+ * One `cache.witnessed[]` entry that reads, joined to the stamp it names.
+ * `witnessKind` and `witnessId` are the stamp's own `anchor_ref`, read from the
+ * signed body, never from the cache: the cache says WHEN, and the body alone
+ * says WHICH witness it is about.
+ */
+export interface CachedWitnessTime {
+    stampRef: string;
+    blockHeight: number;
+    blockTime: number;
+    witnessKind: string;
+    witnessId: string;
+}
+/**
+ * One gateway's answer for one cached time. `matches`: the gateway named the
+ * cached block height and block time. `differs`: it named a block, and the
+ * block is not the cached one. `unreachable`: it named no block (a transport
+ * failure, a refusal, an answer that is not one, or a witness not yet in a
+ * block).
+ */
+export interface WitnessTimeAnswer {
+    gateway: string;
+    outcome: "matches" | "differs" | "unreachable";
+    blockHeight: number | null;
+    blockTime: number | null;
+}
+/**
+ * One cached time, and what the public record said about it: `differs` when
+ * any gateway named a different block, otherwise `matches` when any gateway
+ * named the cached one, otherwise `not_checked`. The same worst-answer-wins
+ * order as the byte lookup.
+ */
+export interface WitnessTimeCheck {
+    cached: CachedWitnessTime;
+    outcome: "matches" | "differs" | "not_checked";
+    answers: WitnessTimeAnswer[];
+}
+/**
+ * The cached witness times the `witness-cache.json` bytes `raw` give for the
+ * signed `bundle` beside them, in the order the file lists them. `raw` is
+ * `null` where the pack has no such file. Pure, and never throws. The file
+ * reads only where it is a JSON object whose `cache_version` is
+ * `WITNESS_CACHE_VERSION` and whose `witnessed` is a list. An entry reads only
+ * where it is an object whose `stamp_ref` is 64 lowercase hex characters naming
+ * exactly one stamp of the signed body that has an `anchor_ref`, whose
+ * `block_height` is a non-negative safe integer, and whose `block_time` is a
+ * whole number of seconds since 1970-01-01T00:00:00Z from 0 to
+ * `MAX_BLOCK_TIME`. A `stamp_ref` two entries name reads for neither.
+ * Everything else reads as no cache for the stamp it would have spoken for.
+ */
+export declare function readWitnessCache(bundle: unknown, raw: Uint8Array | null | undefined): CachedWitnessTime[];
+/** A block time as RFC 3339 UTC to the second, the way both kernels print it: `2026-09-08T12:10:07Z`. */
+export declare function formatBlockTime(seconds: number): string;
+/** `block 1996701 at 2026-09-08T12:10:07Z`. */
+export declare function renderWitnessTime(blockHeight: number, blockTime: number): string;
+/**
+ * The request body the lookup sends: one GraphQL query for one transaction's
+ * block, as JCS, so both kernels send the same bytes.
+ */
+export declare function witnessTimeQuery(witnessId: string): string;
+/**
+ * Look each cached time up on every gateway, in order. With no gateways or no
+ * `fetchImpl`, nothing is looked up and every time is `not_checked`. A witness
+ * that is not `arweave`, or whose id is not a 43-character base64url
+ * transaction id, is never looked up.
+ */
+export declare function checkWitnessCache(cached: readonly CachedWitnessTime[], gateways: readonly string[], fetchImpl: typeof fetch | undefined): Promise<WitnessTimeCheck[]>;