@sanning/proof 0.6.0 → 0.7.0

package/dist/evidence.d.ts

@@ -12,6 +12,31 @@ export declare const ANCHOR_TRACE_BODY_TYPE_V1 = "sanning.anchor.trace/v1";
 /** Every anchor-trace body this kernel verifies. Order is newest-first. */
 export declare const ANCHOR_TRACE_BODY_TYPES: readonly ["sanning.anchor.trace/v2", "sanning.anchor.trace/v1"];
 export declare const EXPORT_BODY_TYPE = "sanning.evidence.export/v1";
+/**
+ * The Sanning-signed interval stamp body (evidence-bundle.md §5.2, DL-58).
+ *
+ * Its own `body_type` rather than a widened anchor-trace body, and the reason
+ * is the whole decision: an anchor-trace checkpoint carries a PRODUCER-signed
+ * `sanning.events/v1` envelope, and a stamp has no producer signature at all —
+ * Sanning places it, under DL-52, for a customer who holds no chain identity.
+ * The two rejected options were making `envelope` optional and synthesising an
+ * envelope that Sanning signs; the second would have made a Sanning
+ * attestation indistinguishable ON THE WIRE from a producer's, which is
+ * unrecoverable once witnessed.
+ */
+export declare const STAMP_TRACE_BODY_TYPE = "sanning.stamp.trace/v1";
+/**
+ * The version string INSIDE a witnessed stamp body — a different string from
+ * the `body_type` above, and the two are easy to confuse.
+ *
+ * `sanning.stamp.trace/v1` discriminates the BUNDLE BODY: it is the reader's
+ * dispatch key. `sanning.stamp/v1` is the control plane's own version of the
+ * bytes it hands a witness (`control-plane/src/stamp-tree.ts`,
+ * `STAMP_BODY_VERSION`). A `sanning.stamp.trace/v1` body pins the inner
+ * version to exactly this value: two answers to one question inside one
+ * signature is the §5.1.2 mixed-vocabulary reject, one layer down.
+ */
+export declare const STAMP_BODY_VERSION = "sanning.stamp/v1";
 export interface EvidenceIssuer {
     kind: string;
     tenant_id?: string;
@@ -85,6 +110,58 @@ export interface AnchorTraceBody {
     checkpoints: TraceCheckpoint[];
     events: TraceEvent[];
 }
+/**
+ * One sub-tree of a stamp, as the WITNESSED bytes carry it.
+ *
+ * Keyed in the body by a blinded reference (an HMAC under a per-org secret we
+ * never publish), so a reader learns that the org runs N agents and their
+ * relative volumes and learns no name. The RANGE is deliberately in the clear:
+ * it is what makes a later per-agent slice claim checkable by a third party
+ * without Sanning, and hiding it would put us back in the trust path.
+ */
+export interface StampSubtree {
+    first_leaf: number;
+    leaf_count: number;
+    /** Hex RFC-9162 root over this sub-tree's leaves alone. */
+    root: string;
+}
+/**
+ * The stamp body as the control plane witnesses it
+ * (`control-plane/src/stamp-tree.ts`, `StampBody`).
+ *
+ * Never read from the bundle directly — it is parsed out of `stamp_bytes`,
+ * which is the only authority. Present as a type so the parse has a shape.
+ */
+export interface StampBody {
+    stamp_version: string;
+    /** The org, BLINDED. Not an org id, and not reversible without the secret. */
+    org_ref: string;
+    interval_start: string;
+    interval_end: string;
+    merkle_root: string;
+    leaf_count: number;
+    subtrees: Record<string, StampSubtree>;
+}
+/** One entry of a `sanning.stamp.trace/v1` body's `stamps[]` (§5.2). */
+export interface StampEntry {
+    /**
+     * The stamp's identity within this bundle, DERIVED: hex SHA-256 of the
+     * DECODED `stamp_bytes`, not of the hex text. A verifier MUST recompute it.
+     */
+    stamp_ref: string;
+    /** Lowercase hex of the exact JCS bytes that were handed to the witness. */
+    stamp_bytes: string;
+    /**
+     * Where the stamp was witnessed, IF IT HAS BEEN (§5.1.1). Absent is honest:
+     * a sealed-but-unconfirmed stamp is witnessed by nobody, and an emitter that
+     * filled this in from a submission receipt would be claiming a chain
+     * position that does not exist yet.
+     */
+    anchor_ref?: AnchorRef;
+}
+export interface StampTraceBody {
+    stamps: StampEntry[];
+}
 export interface EvidenceBundle {
     spec_version: string;
     body_type: string;
@@ -149,6 +226,54 @@ export interface EventResult {
     ok: boolean;
     errors: string[];
 }
+/** One sub-tree's recomputed result (§5.2). */
+export interface StampSubtreeResult {
+    /** The blinded key the body spells it under. Meaningless without the org's secret. */
+    ref: string;
+    firstLeaf: number;
+    leafCount: number;
+    root: string;
+}
+/** One `stamps[]` entry's result (§5.2). */
+export interface StampResult {
+    /** The stamp's derived identity, as the bundle spells it. "" when unusable. */
+    stampRef: string;
+    /** The asserted `stamp_ref` equals SHA-256 of the decoded `stamp_bytes`. */
+    stampRefOk: boolean;
+    /**
+     * The witnessed bytes decoded, parsed, and re-canonicalized to themselves.
+     *
+     * The last clause is not pedantry. The plane stores these bytes as TEXT and
+     * replays them verbatim precisely because a round-trip through a normalizing
+     * serializer is not guaranteed to reproduce what was signed; a body that is
+     * not JCS-canonical is one that every re-deriving reader hashes differently.
+     */
+    bodyOk: boolean;
+    stampVersion: string | null;
+    intervalStart: string | null;
+    intervalEnd: string | null;
+    merkleRoot: string | null;
+    leafCount: number | null;
+    /**
+     * Every sub-tree range accounts for exactly one leaf of the stamp: the
+     * ranges sorted by `first_leaf` tile `[0, leaf_count)` with no gap and no
+     * overlap, and their counts sum to `leaf_count`.
+     */
+    subtreesOk: boolean;
+    subtrees: StampSubtreeResult[];
+    /**
+     * Where it was witnessed, or `null` for a stamp nothing has witnessed yet.
+     *
+     * `null` is NOT a failure and never an accusation — it is the honest state
+     * of every stamp for the first minutes of its life and the permanent state
+     * of every stamp when no witness is configured. It does hold the bundle at
+     * `partial`: a stamp is Sanning's own assertion until something independent
+     * carries it.
+     */
+    anchorRef: AnchorRef | null;
+    ok: boolean;
+    errors: string[];
+}
 export interface EvidenceBundleResult {
     status: EvidenceStatus;
     specVersionOk: boolean;
@@ -160,6 +285,7 @@ export interface EvidenceBundleResult {
     events: EventResult[];
     assertedStatus: string | null;
     export?: ExportResult;
+    stamps?: StampResult[];
     errors: string[];
 }
 export interface AttestationRecord {
@@ -304,6 +430,7 @@ export interface DisclosedContentResult {
  * know their payload is text decode it themselves and own that assumption.
  */
 export declare function disclosedContent(bundle: unknown, options?: VerifyEvidenceOptions): Promise<DisclosedContentResult>;
+export declare function resolveTraceEvents(bundle: unknown): TraceEvent[] | undefined;
 export interface ComposeVerdictResult {
     verdict: VerdictObject;
     sourceStatus: EvidenceStatus;

package/dist/evidence.js

@@ -48,6 +48,31 @@ export const ANCHOR_TRACE_BODY_TYPES = [
 // operator attestations. verifyEvidenceBundle dispatches on it to
 // verifyExportBody (§5).
 export const EXPORT_BODY_TYPE = "sanning.evidence.export/v1";
+/**
+ * The Sanning-signed interval stamp body (evidence-bundle.md §5.2, DL-58).
+ *
+ * Its own `body_type` rather than a widened anchor-trace body, and the reason
+ * is the whole decision: an anchor-trace checkpoint carries a PRODUCER-signed
+ * `sanning.events/v1` envelope, and a stamp has no producer signature at all —
+ * Sanning places it, under DL-52, for a customer who holds no chain identity.
+ * The two rejected options were making `envelope` optional and synthesising an
+ * envelope that Sanning signs; the second would have made a Sanning
+ * attestation indistinguishable ON THE WIRE from a producer's, which is
+ * unrecoverable once witnessed.
+ */
+export const STAMP_TRACE_BODY_TYPE = "sanning.stamp.trace/v1";
+/**
+ * The version string INSIDE a witnessed stamp body — a different string from
+ * the `body_type` above, and the two are easy to confuse.
+ *
+ * `sanning.stamp.trace/v1` discriminates the BUNDLE BODY: it is the reader's
+ * dispatch key. `sanning.stamp/v1` is the control plane's own version of the
+ * bytes it hands a witness (`control-plane/src/stamp-tree.ts`,
+ * `STAMP_BODY_VERSION`). A `sanning.stamp.trace/v1` body pins the inner
+ * version to exactly this value: two answers to one question inside one
+ * signature is the §5.1.2 mixed-vocabulary reject, one layer down.
+ */
+export const STAMP_BODY_VERSION = "sanning.stamp/v1";
 function isEvidenceMajorAccepted(specVersion) {
     if (typeof specVersion !== "string" || specVersion === "")
         return false;
@@ -164,6 +189,12 @@ export async function verifyEvidenceBundle(bundle, options = {}) {
     if (bodyType === EXPORT_BODY_TYPE) {
         return verifyExportBody(b, specVersionOk, assertedStatus, errors, options);
     }
+    // The Sanning-signed interval stamp body (evidence-bundle.md §5.2). The
+    // wrapper is authentic — and for this body that IS "Sanning signed it", since
+    // a stamp carries no second signature of its own inside the bundle.
+    if (bodyType === STAMP_TRACE_BODY_TYPE) {
+        return verifyStampTrace(b, specVersionOk, assertedStatus, errors);
+    }
     if (bodyType !== ANCHOR_TRACE_BODY_TYPE && bodyType !== ANCHOR_TRACE_BODY_TYPE_V1) {
         // The wrapper is authentic but we don't know this body's structure. Per
         // wrap-don't-merge, that is "partial" (cryptographically sound wrapper,
@@ -663,6 +694,305 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
         errors,
     };
 }
+// ===========================================================================
+// `sanning.stamp.trace/v1` — the Sanning-signed interval stamp (§5.2, DL-58)
+//
+// ── What this can prove, and what it deliberately does not claim ──
+//
+// A stamp is not a producer artifact. Under DL-52 the customer signs an
+// envelope and POSTs it; the commitment is witnessed later, on an interval, by
+// a stamp the customer never sees and holds no key for. So there is no
+// producer signature inside this body to check, and — this is the part worth
+// being precise about — there is no SECOND Sanning signature either. The
+// control plane stores the stamp's canonical bytes and hands them to a witness
+// as a signed chain data item; the signature lives on the chain, not in the
+// `stamps` table and not in this body.
+//
+// What "Sanning signed this" means for a stamp bundle is therefore exactly the
+// WRAPPER signature, verified generically before this function is reached. And
+// what makes the stamp evidence rather than an assertion is the witness, which
+// is on a chain and not checkable offline. Hence the rollup below: a stamp we
+// can read but nobody has witnessed holds the bundle at `partial`.
+//
+// So the checkable surface here is the stamp's INTERNAL consistency against
+// the one authority in the bundle — the witnessed bytes:
+//
+//   1. `stamp_ref` is SHA-256 of the DECODED bytes (derived, not asserted).
+//   2. Those bytes parse and re-canonicalize to themselves under JCS.
+//   3. Their `stamp_version` is the one this body_type pins.
+//   4. Every sub-tree range accounts for exactly one leaf of the stamp.
+//
+// (4) is the one that carries customer weight. R-8's whole per-agent story is
+// "prove this agent was under evidence over window W", answered by a
+// contiguous `first_leaf`/`leaf_count` slice of the org tree. Ranges that do
+// not tile `[0, leaf_count)` describe a partition that does not exist, so a
+// slice claim resting on them is unfounded — and unlike a bad signature,
+// nothing else in the stack would ever notice.
+// ===========================================================================
+/** Lowercase hex, even length, non-empty. The family's serialization rule. */
+function isLowerHex(s, nibbles) {
+    if (typeof s !== "string" || s.length === 0 || s.length % 2 !== 0)
+        return false;
+    if (nibbles !== undefined && s.length !== nibbles)
+        return false;
+    return /^[0-9a-f]+$/.test(s);
+}
+function isNonNegInt(n) {
+    return typeof n === "number" && Number.isInteger(n) && n >= 0;
+}
+/**
+ * Parse and check one stamp's witnessed bytes.
+ *
+ * Errors accumulate rather than short-circuit wherever a later check is still
+ * meaningful, so a bundle with two independent defects reports two — a
+ * verifier that stops at the first one turns a second fix into a second
+ * round-trip.
+ */
+async function verifyStampEntry(raw, seen) {
+    const errors = [];
+    const base = {
+        stampRef: "",
+        stampRefOk: false,
+        bodyOk: false,
+        stampVersion: null,
+        intervalStart: null,
+        intervalEnd: null,
+        merkleRoot: null,
+        leafCount: null,
+        subtreesOk: false,
+        subtrees: [],
+        anchorRef: null,
+        ok: false,
+        errors,
+    };
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        errors.push("stamp entry is not an object");
+        return base;
+    }
+    const e = raw;
+    // --- the witnessed bytes, which are the only authority in this body -------
+    if (!isLowerHex(e.stamp_bytes)) {
+        errors.push("stamp_bytes is missing or not lowercase hex");
+        return base;
+    }
+    let bytes;
+    try {
+        bytes = hexToBytes(e.stamp_bytes);
+    }
+    catch (err) {
+        errors.push(`stamp_bytes is not hex: ${stringifyErr(err)}`);
+        return base;
+    }
+    // --- the derived identity -------------------------------------------------
+    const derived = await sha256Hex(bytes);
+    if (typeof e.stamp_ref !== "string" || e.stamp_ref === "") {
+        errors.push("stamp entry missing stamp_ref");
+    }
+    else if (e.stamp_ref.toLowerCase() !== derived) {
+        // The bytes were edited and the label was not — or the label was edited
+        // and the bytes were not. Either way the bundle names a stamp it is not
+        // carrying, and quoting that name to a witness would resolve to something
+        // else entirely.
+        errors.push(`stamp_ref does not match SHA-256(stamp_bytes): claimed=${e.stamp_ref} derived=${derived}`);
+    }
+    else {
+        base.stampRefOk = true;
+        base.stampRef = derived;
+        if (seen.has(derived)) {
+            errors.push(`duplicate stamp_ref ${derived}`);
+            base.stampRefOk = false;
+        }
+        else {
+            seen.add(derived);
+        }
+    }
+    // --- the body itself ------------------------------------------------------
+    let body;
+    try {
+        const parsed = JSON.parse(new TextDecoder().decode(bytes));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            errors.push("stamp body is not a JSON object");
+            return base;
+        }
+        body = parsed;
+        // Re-canonicalize and compare. The plane replays these bytes verbatim on
+        // every submit attempt for exactly this reason: a non-canonical body makes
+        // a retry a DIFFERENT submission, and makes every independent re-derivation
+        // of the stamp disagree with the one that was witnessed.
+        if (jcs(body) !== new TextDecoder().decode(bytes)) {
+            errors.push("stamp_bytes are not JCS-canonical (RFC 8785)");
+            return base;
+        }
+    }
+    catch (err) {
+        errors.push(`stamp body is not JSON: ${stringifyErr(err)}`);
+        return base;
+    }
+    if (body.stamp_version !== STAMP_BODY_VERSION) {
+        // A `sanning.stamp.trace/v1` body whose inner version is something else is
+        // two answers to one question inside one signature. The body_type is the
+        // reader's dispatch key and it said v1; honouring the other spelling is
+        // how a reader half-parses a shape it does not know.
+        errors.push(`unsupported stamp_version ${JSON.stringify(body.stamp_version)} in a ` +
+            `${STAMP_TRACE_BODY_TYPE} body (expected ${STAMP_BODY_VERSION})`);
+        return base;
+    }
+    base.stampVersion = body.stamp_version;
+    base.bodyOk = true;
+    for (const f of ["org_ref", "interval_start", "interval_end"]) {
+        if (typeof body[f] !== "string" || body[f] === "") {
+            errors.push(`stamp body ${f} is missing or not a non-empty string`);
+            base.bodyOk = false;
+        }
+    }
+    base.intervalStart = typeof body.interval_start === "string" ? body.interval_start : null;
+    base.intervalEnd = typeof body.interval_end === "string" ? body.interval_end : null;
+    if (!isLowerHex(body.merkle_root, 64)) {
+        errors.push("stamp body merkle_root is not 64 lowercase hex characters");
+        base.bodyOk = false;
+    }
+    else {
+        base.merkleRoot = body.merkle_root;
+    }
+    if (!isNonNegInt(body.leaf_count)) {
+        errors.push("stamp body leaf_count is not a non-negative integer");
+        base.bodyOk = false;
+    }
+    else {
+        base.leafCount = body.leaf_count;
+    }
+    // --- the sub-tree ranges --------------------------------------------------
+    base.subtreesOk = checkSubtrees(body, base, errors);
+    base.anchorRef = parseAnchorRef(e.anchor_ref, errors);
+    base.ok =
+        base.stampRefOk && base.bodyOk && base.subtreesOk && errors.length === 0;
+    return base;
+}
+/**
+ * The range arithmetic (§5.2), and the reason it is a hard check.
+ *
+ * `buildStampTree` orders a stamp's leaves agent-major, which is the only
+ * reason `first_leaf` + `leaf_count` can describe an agent's slice at all: the
+ * ranges partition `[0, leaf_count)` exactly, by construction. A body whose
+ * ranges do not is either not a stamp this stack built or one built wrong, and
+ * in both cases the per-agent claim the ranges exist to support is unfounded.
+ *
+ * The sum is checked BEFORE the tiling and reports its own message, so a body
+ * that is merely short does not get filed under a gap it does not have.
+ */
+function checkSubtrees(body, out, errors) {
+    const raw = body.subtrees;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        errors.push("stamp body subtrees is not an object");
+        return false;
+    }
+    let shapeOk = true;
+    const subtrees = [];
+    for (const [ref, v] of Object.entries(raw)) {
+        if (v === null || typeof v !== "object" || Array.isArray(v)) {
+            errors.push(`sub-tree ${ref} is not an object`);
+            shapeOk = false;
+            continue;
+        }
+        const s = v;
+        if (!isNonNegInt(s.first_leaf)) {
+            errors.push(`sub-tree ${ref} first_leaf is not a non-negative integer`);
+            shapeOk = false;
+        }
+        // A zero-leaf sub-tree is not a slice of anything, and admitting one lets
+        // an arbitrary number of empty ranges sit inside a tiling that still adds
+        // up.
+        if (!isNonNegInt(s.leaf_count) || s.leaf_count === 0) {
+            errors.push(`sub-tree ${ref} leaf_count is not a positive integer`);
+            shapeOk = false;
+        }
+        if (!isLowerHex(s.root, 64)) {
+            errors.push(`sub-tree ${ref} root is not 64 lowercase hex characters`);
+            shapeOk = false;
+        }
+        if (!shapeOk)
+            continue;
+        subtrees.push({
+            ref,
+            firstLeaf: s.first_leaf,
+            leafCount: s.leaf_count,
+            root: s.root,
+        });
+    }
+    subtrees.sort((a, b) => a.firstLeaf - b.firstLeaf);
+    out.subtrees = subtrees;
+    if (!shapeOk)
+        return false;
+    const total = body.leaf_count;
+    if (!isNonNegInt(total))
+        return false; // already reported by the caller
+    const sum = subtrees.reduce((n, s) => n + s.leafCount, 0);
+    if (sum !== total) {
+        errors.push(`sub-tree leaf_count sum ${sum} does not equal the stamp's leaf_count ${total}`);
+        return false;
+    }
+    let next = 0;
+    for (const s of subtrees) {
+        if (s.firstLeaf !== next) {
+            errors.push(`sub-tree ranges do not tile [0, ${total}): expected a range at leaf ` +
+                `${next}, found one at ${s.firstLeaf}`);
+            return false;
+        }
+        next += s.leafCount;
+    }
+    return true;
+}
+async function verifyStampTrace(b, specVersionOk, assertedStatus, errors) {
+    const body = b.body;
+    if (!Array.isArray(body?.stamps)) {
+        return malformed(`${STAMP_TRACE_BODY_TYPE} body must have stamps[]`, true);
+    }
+    const seen = new Set();
+    const stamps = [];
+    for (const entry of body.stamps) {
+        stamps.push(await verifyStampEntry(entry, seen));
+    }
+    // --- Rollup ----------------------------------------------------------------
+    const anyHardFailure = stamps.some((s) => !s.ok);
+    const anyUnwitnessed = stamps.some((s) => s.anchorRef === null);
+    let status;
+    if (anyHardFailure) {
+        status = "failed";
+    }
+    else if (stamps.length === 0) {
+        // A bundle asserting nothing. Not a failure — nothing here is wrong — but
+        // it must never read `verified`, which a caller would take as a witness it
+        // does not have.
+        status = "partial";
+        errors.push(`${STAMP_TRACE_BODY_TYPE} body carries no stamps`);
+    }
+    else if (anyUnwitnessed) {
+        // The honest half of P-10, one layer up. A stamp with no `anchor_ref` is
+        // sealed and unwitnessed: `retained-by-sanning`, which is a statement about
+        // our coverage and never an accusation about their evidence. It is also not
+        // `verified`, because for a stamp the witness is the entire independent
+        // part — unlike an anchor-trace checkpoint, which still carries a producer
+        // signature and an inclusion proof that stand on their own offline.
+        status = "partial";
+        errors.push("one or more stamps carries no anchor_ref — sealed by Sanning, witnessed by nobody");
+    }
+    else {
+        status = "verified";
+    }
+    return {
+        status,
+        specVersionOk,
+        bodyHashOk: true,
+        signatureOk: true,
+        bodyType: STAMP_TRACE_BODY_TYPE,
+        onChainChecked: false,
+        checkpoints: [],
+        events: [],
+        assertedStatus,
+        stamps,
+        errors,
+    };
+}
 // How many `sanning.evidence.export/v1` wrappers deep the source bundle may be
 // nested before this path gives up. verifyEvidenceBundle's canonicalization
 // depth bound already rejects a pathological bundle, but the unwrap must be
@@ -779,7 +1109,13 @@ export async function disclosedContent(bundle, options = {}) {
 // wrapper(s) to the inline source bundle — mirroring how verifyEvidenceBundle
 // recurses into `source_bundle`, so the events line up with its results.
 // `undefined` when there is no anchor-trace body to materialize from.
-function resolveTraceEvents(bundle) {
+//
+// Exported for `chain.ts`, which needs the same descent and must not derive it
+// again: two answers to "which events is this bundle actually about" inside one
+// kernel is two implementations of one rule, and the one that drifted would be
+// the one nobody was looking at. Deliberately NOT re-exported from `index.ts` —
+// same posture as `side-content.ts`, internal and shared.
+export function resolveTraceEvents(bundle) {
     let cur = bundle;
     for (let depth = 0; depth < MAX_EXPORT_UNWRAP; depth++) {
         if (cur === null || typeof cur !== "object" || Array.isArray(cur))

package/dist/index.d.ts

@@ -2,10 +2,12 @@ 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 { ANCHOR_TRACE_BODY_TYPE, ANCHOR_TRACE_BODY_TYPE_V1, ANCHOR_TRACE_BODY_TYPES, EXPORT_BODY_TYPE, 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, TraceCheckpoint, TraceCheckpointV1, TraceEvent, TraceInclusion, VerdictAttestation, VerdictCheckpoint, VerdictEvent, VerdictObject, VerdictOnChain, VerdictOnChainGateway, VerifyEvidenceOptions, } from "./evidence.js";
+export { ANCHOR_TRACE_BODY_TYPE, ANCHOR_TRACE_BODY_TYPE_V1, ANCHOR_TRACE_BODY_TYPES, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, 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, TraceCheckpoint, TraceCheckpointV1, TraceEvent, TraceInclusion, VerdictAttestation, VerdictCheckpoint, VerdictEvent, VerdictObject, VerdictOnChain, VerdictOnChainGateway, VerifyEvidenceOptions, } from "./evidence.js";
 export { accountDisclosure, completenessNotes, gradeCauses, gradePack, renderCause, signedLeafCount, } from "./grading.js";
 export type { CompletenessNote, DisclosureAccount, GradeInput, PackGrade, PackGradeCause, PackGradeCauseKind, PackVerdict, } from "./grading.js";
+export { ADAPTER_CHAIN_NAMESPACES, CHAIN_READING_SCOPE, readChains, renderChainFinding, } from "./chain.js";
+export type { ChainFinding, ChainFindingKind, ChainReading, ChainSource, ChainSummary, } from "./chain.js";
 export { attestationSignatureToHex, composeExport } from "./compose.js";
 export type { ComposeExportOptions, ComposeExportResult, ExporterKey } from "./compose.js";
 export { AGENT_PROOF_SPEC_PREFIX, isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.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 { ANCHOR_TRACE_BODY_TYPE, ANCHOR_TRACE_BODY_TYPE_V1, ANCHOR_TRACE_BODY_TYPES, EXPORT_BODY_TYPE, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
+export { ANCHOR_TRACE_BODY_TYPE, ANCHOR_TRACE_BODY_TYPE_V1, ANCHOR_TRACE_BODY_TYPES, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, 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.
 //
@@ -51,6 +51,27 @@ export { ANCHOR_TRACE_BODY_TYPE, ANCHOR_TRACE_BODY_TYPE_V1, ANCHOR_TRACE_BODY_TY
 // derivation to it, and diff its copy against ours. Additive — no existing
 // export changes.
 export { accountDisclosure, completenessNotes, gradeCauses, gradePack, renderCause, signedLeafCount, } from "./grading.js";
+// Chain reading (src/chain.ts): following the pointer every sanning.events/v1
+// record carries to the record before it, over the records ONE bundle presents.
+//
+// Every anchored event has carried that pointer since the profile was ratified
+// and nothing we shipped read it, so a bundle with an event removed — and a
+// chain that restarted after a crash and now asserts two beginnings — passed
+// every check we had (proof#43). The verifier was right not to do this: it
+// verifies a single envelope and says so. Nothing above it did it either.
+//
+// Pure — data in, data out, no I/O — so the kernel's scope boundary
+// (specs/architecture.md §3) is unchanged, and the rule ships as
+// `vectors/chain-reading.json` beside the pack-grading table for the same
+// reason: a rule consumers must agree with needs a statement they can fetch.
+//
+// It returns FINDINGS, never a verdict, and it feeds no status. Chain links are
+// deletion/reorder-evidence for the events present and NOT a completeness proof
+// (`anchor/docs/profile-sanning.events-v1.md` §5) — drop the last N events of a
+// chain and nothing dangles. `CHAIN_READING_SCOPE` is that sentence, exported so
+// every surface prints the same limit rather than paraphrasing it into a claim.
+// Additive — no existing export changes.
+export { ADAPTER_CHAIN_NAMESPACES, CHAIN_READING_SCOPE, readChains, renderChainFinding, } from "./chain.js";
 // The `proof export` composer (specs/evidence-export.md §5, phase 2): produce a
 // signed, offline-verifiable sanning.evidence.export/v1 artifact from a source
 // anchor-trace bundle + operator attestations + an exporter Ed25519 key. The

package/dist/verifier.js

@@ -215,6 +215,18 @@ export async function verifyEnvelope(env, optionsOrContentHash) {
     const opts = typeof optionsOrContentHash === "string"
         ? { expectedContentHash: optionsOrContentHash }
         : (optionsOrContentHash ?? {});
+    // REFUSE an unknown option key rather than ignore it. `expected_content_hash`
+    // — the Python kernel's spelling — previously fell through as `undefined`, so
+    // the content bind silently never ran and the caller got a clean pass with no
+    // errors at all. A check that quietly does not happen is worse than one that
+    // fails: the caller believes they verified an artifact they never checked.
+    const KNOWN_VERIFY_OPTIONS = new Set(["payloadBytes", "expectedContentHash"]);
+    const unknownOptions = Object.keys(opts).filter((k) => !KNOWN_VERIFY_OPTIONS.has(k));
+    if (unknownOptions.length > 0) {
+        throw new TypeError(`verifyEnvelope: unknown option(s) ${unknownOptions.join(", ")}. ` +
+            `Did you mean ${[...KNOWN_VERIFY_OPTIONS].join(" / ")}? ` +
+            "Option keys are camelCase in the TypeScript kernel; the Python kernel uses snake_case.");
+    }
     const expectedContentHash = opts.expectedContentHash;
     const errors = [];
     // Guard a malformed input (null / non-object / array) up front — every field
@@ -296,18 +308,45 @@ export async function verifyEnvelope(env, optionsOrContentHash) {
     let contentHashOk = null;
     let contentRole = null;
     if (expectedContentHash !== undefined) {
-        const want = expectedContentHash.toLowerCase();
-        const match = contentHashes(env).find((c) => c.hash.toLowerCase() === want);
-        contentHashOk = match !== undefined;
-        contentRole = match ? match.role : null;
-        if (!contentHashOk) {
-            errors.push("provided content hash does not match any hash this envelope commits to");
+        const committed = contentHashes(env);
+        if (committed.length === 0) {
+            // UNDETERMINED, not failed. An external-commitment envelope
+            // (`sanning.events/v1`) has no inline payload, so it commits to no
+            // envelope-readable content hash and there is nothing here to compare
+            // against. Reporting that as a failure would render "we cannot check
+            // this" as "it did not match" — what P-10 and I-5 exist to prevent — and
+            // would fail every envelope on the DL-52 path.
+            //
+            // The caller is still told the check did not happen; silence would be
+            // worse than either verdict.
+            contentHashOk = null;
+            errors.push("this envelope commits to no readable content hash (external-commitment " +
+                "profile), so the provided content hash could not be checked — " +
+                "undetermined, not failed");
+        }
+        else {
+            const want = expectedContentHash.toLowerCase();
+            const match = committed.find((c) => c.hash.toLowerCase() === want);
+            contentHashOk = match !== undefined;
+            contentRole = match ? match.role : null;
+            if (!contentHashOk) {
+                errors.push("provided content hash does not match any hash this envelope commits to");
+            }
         }
     }
     return {
         // null (binding not checkable) does not fail the verdict — Python-kernel
         // parity: ok = spec && sig && payloadHashOk is not False.
-        ok: specVersionOk && signatureOk && payloadHashOk !== false,
+        // A supplied `expectedContentHash` that matches nothing this envelope
+        // commits to is a FAILING verdict, not a side note (proof#42). This is the
+        // check an external auditor runs — "does this file match what was
+        // anchored" — and reporting it only in `contentHashOk` meant the top-level
+        // verdict, the field a caller naturally reads, said pass over a file that
+        // does not match.
+        //
+        // Absence stays undetermined: `contentHashOk` is null when no hash was
+        // supplied, and null must not fail (P-10 — absence is not failure).
+        ok: specVersionOk && signatureOk && payloadHashOk !== false && contentHashOk !== false,
         specVersionOk,
         payloadHashOk,
         signatureOk,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanning/proof",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "TypeScript kernel of the Sanning verification stack: RFC 8785 (JCS) canonicalization, SHA-256, and Ed25519 verification for Verifiable Event Envelopes. Full-family verifier (inline + external commitment); accepts sanning.agent/v1, sanning.mlflow/v1, sanning.events/v1. Conformance-gated byte-for-byte against the test-vectors corpus.",
   "license": "MIT",
   "type": "module",