@sanning/proof 0.6.0 → 0.7.0

package/src/evidence.ts

@@ -73,6 +73,33 @@ export const ANCHOR_TRACE_BODY_TYPES = [
 // 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";
+
 // ---- Wire types (evidence-bundle.md §2 + §5.1) ------------------------------
 
 export interface EvidenceIssuer {
@@ -160,6 +187,64 @@ export interface AnchorTraceBody {
   events: TraceEvent[];
 }
 
+// ---- `sanning.stamp.trace/v1` wire types (evidence-bundle.md §5.2) ---------
+
+/**
+ * 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;
@@ -265,6 +350,56 @@ export interface EventResult {
   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;
   // The wrapper: accepted major, body_hash recompute, Ed25519 wrapper signature.
@@ -284,6 +419,12 @@ export interface EvidenceBundleResult {
   // above are the recomputed SOURCE-bundle results in that case. Absent for a
   // plain anchor-trace bundle — additive, backward-compatible.
   export?: ExportResult;
+  // Present ONLY for a `sanning.stamp.trace/v1` body (evidence-bundle.md §5.2):
+  // the per-stamp recomputed results. `checkpoints`/`events` stay empty for
+  // such a bundle — a stamp body carries neither, and reporting an empty list
+  // as "nothing was wrong" is the exact confusion `partial` exists to prevent.
+  // Absent for every other body — additive, backward-compatible.
+  stamps?: StampResult[];
   errors: string[];
 }
 
@@ -572,6 +713,13 @@ export async function verifyEvidenceBundle(
     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,
@@ -1117,6 +1265,332 @@ async function verifyAnchorTrace(
   };
 }
 
+// ===========================================================================
+// `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: unknown, nibbles?: number): s is string {
+  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: unknown): n is number {
+  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: unknown,
+  seen: Set<string>,
+): Promise<StampResult> {
+  const errors: string[] = [];
+  const base: StampResult = {
+    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 as Partial<StampEntry> & Record<string, unknown>;
+
+  // --- 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: Uint8Array;
+  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: StampBody;
+  try {
+    const parsed: unknown = 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 as StampBody;
+    // 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 as unknown as Record<string, unknown>) !== 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"] as const) {
+    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: StampBody, out: StampResult, errors: string[]): boolean {
+  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: StampSubtreeResult[] = [];
+  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 as Partial<StampSubtree>;
+    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 as number,
+      leafCount: s.leaf_count as number,
+      root: s.root as string,
+    });
+  }
+  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: EvidenceBundle,
+  specVersionOk: boolean,
+  assertedStatus: string | null,
+  errors: string[],
+): Promise<EvidenceBundleResult> {
+  const body = b.body as StampTraceBody;
+  if (!Array.isArray(body?.stamps)) {
+    return malformed(`${STAMP_TRACE_BODY_TYPE} body must have stamps[]`, true);
+  }
+
+  const seen = new Set<string>();
+  const stamps: StampResult[] = [];
+  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: EvidenceStatus;
+  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,
+  };
+}
+
 // ===========================================================================
 // Ingest: materializing the disclosed raw bytes (evidence-bundle.md §5.1).
 //
@@ -1306,7 +1780,13 @@ export async function disclosedContent(
 // 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: unknown): TraceEvent[] | undefined {
+//
+// 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: unknown): TraceEvent[] | undefined {
   let cur: unknown = bundle;
   for (let depth = 0; depth < MAX_EXPORT_UNWRAP; depth++) {
     if (cur === null || typeof cur !== "object" || Array.isArray(cur)) return undefined;

package/src/index.ts

@@ -64,6 +64,8 @@ export {
   ANCHOR_TRACE_BODY_TYPE_V1,
   ANCHOR_TRACE_BODY_TYPES,
   EXPORT_BODY_TYPE,
+  STAMP_BODY_VERSION,
+  STAMP_TRACE_BODY_TYPE,
   disclosedContent,
   recomputeExportVerdict,
   verifyEvidenceBundle,
@@ -90,6 +92,12 @@ export type {
   OnChainResult,
   PerGatewayOutcome,
   AnchorRef,
+  StampBody,
+  StampEntry,
+  StampResult,
+  StampSubtree,
+  StampSubtreeResult,
+  StampTraceBody,
   TraceCheckpoint,
   TraceCheckpointV1,
   TraceEvent,
@@ -136,6 +144,40 @@ export type {
   PackVerdict,
 } 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";
+export type {
+  ChainFinding,
+  ChainFindingKind,
+  ChainReading,
+  ChainSource,
+  ChainSummary,
+} 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/src/verifier.ts

@@ -228,6 +228,20 @@ export async function verifyEnvelope(
     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: string[] = [];
 
@@ -313,19 +327,47 @@ export async function verifyEnvelope(
   let contentHashOk: boolean | null = null;
   let contentRole: ContentRole | null = 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,