@sanning/proof 0.4.1 → 0.5.0

package/README.md

@@ -111,6 +111,33 @@ result.events[0].contentOk; // true | false | null
 
 In-body `events[].content` (signed) takes precedence over the side input; if both are present for an event and disagree, the event fails.
 
+### …and get those raw logs back out (ingest)
+
+`events[].content` rides as **lowercase hex** — JSON cannot carry arbitrary bytes. To *materialize* a received bundle's logs (serve them, write pack files, hand them on), use `disclosedContent` rather than decoding that field yourself:
+
+```ts
+import { disclosedContent } from "@sanning/proof";
+
+const result = await disclosedContent(bundle); // verifies, then decodes
+
+for (const [eventId, bytes] of result.content) {
+  await writeFile(`logs/${eventId}.json`, bytes); // Uint8Array — write it as-is
+}
+```
+
+**Verify-then-return:** `disclosedContent` runs the full `verifyEvidenceBundle` (same options) and hands back bytes **only** for events whose chain verified *and* whose disclosed bytes hash to the committed `content_hash`. There is no path through it that yields bytes that are not the committed ones — and `result.verification` carries the whole `EvidenceBundleResult`, so you verify once and render the verdict from the same call.
+
+Every event also appears in `result.events`, in body order, with a status that never lets "nothing was disclosed" pass for "empty":
+
+| `status` | `bytes` | Meaning |
+|---|---|---|
+| `verified` | the bytes | Decoded **and** bound to the committed `content_hash` — safe to write as-is. May be zero-length: an empty payload is real, verifiable content. |
+| `not_disclosed` | `null` | Minimal disclosure — the hash was committed, the bytes were not shared. Nothing to write, and not an error. |
+| `undetermined` | `null` | Bytes were disclosed but there is nothing to bind them to (withheld record, or no committed `content_hash`). Withheld rather than returned. |
+| `failed` | `null` | The event's own proof chain failed, or the disclosure did not bind or did not decode. `errors` says which. |
+
+Bytes come back as `Uint8Array`, never a string: the spec commits to **raw bytes**, and a UTF-8 decode is lossy for any payload that is not valid UTF-8 — re-encoding such a string would change the bytes and break the hash. Decode to text yourself if you know your payload is text.
+
 ## Verify a Merkle inclusion proof
 
 Agents close daily checkpoints over per-cycle leaves (RFC 9162, §2.1 domain separation — not the Bitcoin duplicate-leaf variant). Verify a leaf's inclusion against an anchored root:
@@ -133,6 +160,7 @@ const ok = await verifyInclusion(
 |---|---|
 | `verifyEnvelope(env, optionsOrContentHash?)` | The three load-bearing checks (spec-version registry, payload-hash recompute, Ed25519 over the signed scope) + optional content bind. Pass `{ payloadBytes }` for external-commitment envelopes. Returns `VerificationResult`. |
 | `verifyEvidenceBundle(bundle, { gateways?, fetchImpl? })` | Verify a signed `sanning.evidence/v1` / `sanning.anchor.trace/v1` bundle: wrapper signature + `body_hash` + every checkpoint + every event's inclusion, offline (optional on-chain re-fetch). Returns `EvidenceBundleResult`. Powers the `npx @sanning/proof verify` CLI. |
+| `disclosedContent(bundle, { gateways?, content?, fetchImpl? })` | **Ingest:** verify a bundle, then hand back the DECODED raw bytes (`Uint8Array`) of every event whose disclosure bound to its committed `content_hash` — so materializing a received pack never means re-implementing the hex convention. Returns `DisclosedContentResult` (`content` map + per-event `verified` / `not_disclosed` / `undetermined` / `failed`, plus the full `verification`). |
 | `verifyAgentProofBundle(bundle, { gateways?, fetchImpl? })` / `isAgentProofSpec(v)` | Verify the agent producer's `sanning.agent.proof/v1` inclusion bundle. |
 | `contentHashes(env)` | The content hash(es) an envelope commits to, by event type — the reverse-provenance join keys. |
 | `specVersionSupported(v)` | Fail-closed accept-check: `sanning.agent/v1` and additive minors (`sanning.agent/v1.<n>`). Unknown majors/profiles are rejected. |

package/dist/cli.js

@@ -57,8 +57,11 @@ export async function runCli(argv, io) {
         io.out("@sanning/proof verify CLI");
         return EXIT_VERIFIED;
     }
-    if (command === "export") {
-        return runExport(rest, io);
+    // `bundle` is the customer-facing verb (proof#19: one artifact, one word).
+    // `export` is kept working as a QUIET alias — it shipped and is published, so
+    // it is not broken abruptly; it is simply no longer taught anywhere.
+    if (command === "bundle" || command === "export") {
+        return runBundle(rest, io);
     }
     if (command !== "verify") {
         io.err(`unknown command: ${command}`);
@@ -164,7 +167,8 @@ export async function runCli(argv, io) {
     });
     return reportEvidence(result, bundlePath, gateways, io);
 }
-// `proof export <source-bundle.json> --attestations <f> --key <f> [-o <out>]`
+// `proof bundle <source-bundle.json> --attestations <f> --key <f> [-o <out>]`
+// (`proof export` still reaches this, undocumented — see the dispatch above.)
 //
 // Compose a signed, offline-verifiable sanning.evidence.export/v1 artifact from a
 // source sanning.anchor.trace/v1 bundle + operator attestation records + an exporter
@@ -175,7 +179,7 @@ export async function runCli(argv, io) {
 // forged/mis-bound attestation — the composer refuses to emit a green artifact
 // over failing evidence) · 2 usage / malformed input (missing flag, unreadable
 // or non-JSON input, bad exporter key, malformed attestation record).
-async function runExport(rest, io) {
+async function runBundle(rest, io) {
     let attestationsPath;
     let keyPath;
     let outPath;
@@ -296,7 +300,7 @@ async function runExport(rest, io) {
     return composed.status === "failed" ? EXIT_FAILED : EXIT_VERIFIED;
 }
 function usageExport(io) {
-    io.out("Usage: npx @sanning/proof export <source-bundle.json> --attestations <file> --key <file> [-o <out.json>]");
+    io.out("Usage: npx @sanning/proof bundle <source-bundle.json> --attestations <file> --key <file> [-o <out.json>]");
     io.out("");
     io.out("Compose a signed, offline-verifiable sanning.evidence.export/v1 artifact from an");
     io.out("sanning.anchor.trace/v1 source bundle + operator attestation records + an exporter");
@@ -390,8 +394,8 @@ function printUsage(io) {
     io.out("Usage: npx @sanning/proof <command> [args]");
     io.out("");
     io.out("Commands:");
-    io.out("  verify <bundle.json> [gateways] [--logs <logs.json>]   Verify a bundle/export");
-    io.out("  export <source.json> --attestations <f> --key <f> [-o] Compose an attested export");
+    io.out("  verify <bundle.json> [gateways] [--logs <logs.json>]   Verify a bundle");
+    io.out("  bundle <source.json> --attestations <f> --key <f> [-o] Create an attested bundle");
     io.out("");
     io.out("Verify a sanning.evidence/v1 (sanning.anchor.trace/v1) bundle, an");
     io.out("sanning.evidence.export/v1 attested export, or a sanning.agent.proof/v1");

package/dist/evidence.d.ts

@@ -205,6 +205,35 @@ export interface VerifyEvidenceOptions {
     fetchImpl?: typeof fetch;
 }
 export declare function verifyEvidenceBundle(bundle: unknown, options?: VerifyEvidenceOptions): Promise<EvidenceBundleResult>;
+export type DisclosureStatus = "verified" | "not_disclosed" | "undetermined" | "failed";
+export interface DisclosedEventContent {
+    eventId: string;
+    status: DisclosureStatus;
+    bytes: Uint8Array | null;
+    errors: string[];
+}
+export interface DisclosedContentResult {
+    status: EvidenceStatus;
+    verification: EvidenceBundleResult;
+    events: DisclosedEventContent[];
+    content: Map<string, Uint8Array>;
+    errors: string[];
+}
+/**
+ * Materialize the disclosed raw bytes of a received bundle (evidence-bundle §5.1).
+ *
+ * Verify-then-return: the bundle is verified with {@link verifyEvidenceBundle}
+ * (same options — gateways, out-of-band `content`, `fetchImpl`), and an event's
+ * bytes are returned ONLY when that verification bound them to the committed
+ * `content_hash`. There is no path through this function that yields bytes
+ * whose SHA-256 is not the commitment.
+ *
+ * Returns `Uint8Array`, never a string: the spec commits to raw bytes, and a
+ * UTF-8 decode is lossy for any payload that is not valid UTF-8 — re-encoding
+ * such a string would produce different bytes and a different hash. Callers who
+ * know their payload is text decode it themselves and own that assumption.
+ */
+export declare function disclosedContent(bundle: unknown, options?: VerifyEvidenceOptions): Promise<DisclosedContentResult>;
 export interface ComposeVerdictResult {
     verdict: VerdictObject;
     sourceStatus: EvidenceStatus;

package/dist/evidence.js

@@ -341,29 +341,12 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
                     committed.push(c.hash.toLowerCase());
             }
             // Disclosed bytes, precedence: in-body (signed) → side input. A string
-            // side input is hex; a Uint8Array is used as-is.
-            let inBody;
-            if (typeof ev.content === "string") {
-                try {
-                    inBody = hexToBytes(ev.content);
-                }
-                catch (e) {
-                    evErrors.push(`event content is not hex: ${stringifyErr(e)}`);
-                }
-            }
-            let side;
-            const sideRaw = options.content?.[eventId];
-            if (sideRaw instanceof Uint8Array) {
-                side = sideRaw;
-            }
-            else if (typeof sideRaw === "string") {
-                try {
-                    side = hexToBytes(sideRaw);
-                }
-                catch (e) {
-                    evErrors.push(`supplied content for ${eventId} is not hex: ${stringifyErr(e)}`);
-                }
-            }
+            // side input is hex; a Uint8Array is used as-is. Resolved by the SHARED
+            // selector so `disclosedContent` hands a consumer the very bytes bound
+            // here — one decode, not two that can drift apart.
+            const selection = selectDisclosedBytes(ev, eventId, options.content);
+            const { inBody, side } = selection;
+            evErrors.push(...selection.errors);
             if (inBody !== undefined && side !== undefined && !bytesEqual(inBody, side)) {
                 // Two disclosures that disagree: a genuine conflict, not undetermined.
                 contentOk = false;
@@ -473,6 +456,144 @@ async function verifyAnchorTrace(b, bodyType, specVersionOk, assertedStatus, err
         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
+// independently bounded rather than trusting that it ran first.
+const MAX_EXPORT_UNWRAP = 4;
+/**
+ * Materialize the disclosed raw bytes of a received bundle (evidence-bundle §5.1).
+ *
+ * Verify-then-return: the bundle is verified with {@link verifyEvidenceBundle}
+ * (same options — gateways, out-of-band `content`, `fetchImpl`), and an event's
+ * bytes are returned ONLY when that verification bound them to the committed
+ * `content_hash`. There is no path through this function that yields bytes
+ * whose SHA-256 is not the commitment.
+ *
+ * Returns `Uint8Array`, never a string: the spec commits to raw bytes, and a
+ * UTF-8 decode is lossy for any payload that is not valid UTF-8 — re-encoding
+ * such a string would produce different bytes and a different hash. Callers who
+ * know their payload is text decode it themselves and own that assumption.
+ */
+export async function disclosedContent(bundle, options = {}) {
+    const verification = await verifyEvidenceBundle(bundle, options);
+    const events = [];
+    const content = new Map();
+    const errors = [];
+    const empty = () => ({
+        status: verification.status,
+        verification,
+        events: [],
+        content: new Map(),
+        errors: [...errors, ...verification.errors],
+    });
+    const traceEvents = resolveTraceEvents(bundle);
+    if (traceEvents === undefined) {
+        errors.push(`no ${ANCHOR_TRACE_BODY_TYPE} body to materialize content from ` +
+            `(body_type ${JSON.stringify(verification.bodyType)})`);
+        return empty();
+    }
+    // Fail closed on any drift between the body we are decoding and the results
+    // we are trusting. Both must be the same events in the same order, or the
+    // "these bytes are the bytes that verified" guarantee is void — which is the
+    // only guarantee this function makes. A broken wrapper lands here too:
+    // verifyEvidenceBundle returns zero event results, so nothing is emitted.
+    if (traceEvents.length !== verification.events.length) {
+        errors.push("the bundle did not verify far enough to materialize content: " +
+            `${verification.events.length} verified event result(s) for ${traceEvents.length} body event(s)`);
+        return empty();
+    }
+    for (let i = 0; i < traceEvents.length; i++) {
+        const te = traceEvents[i];
+        const envelope = te !== null && typeof te === "object" ? te.envelope : undefined;
+        if (getEventId(envelope) !== verification.events[i].eventId) {
+            errors.push(`event alignment drift at index ${i}: the body event and its verification result ` +
+                "are not the same event; refusing to hand back any content");
+            return empty();
+        }
+    }
+    for (let i = 0; i < traceEvents.length; i++) {
+        const ev = traceEvents[i];
+        const res = verification.events[i];
+        const selection = selectDisclosedBytes(ev, res.eventId, options.content);
+        const bytes = selection.inBody ?? selection.side;
+        const evErrors = [];
+        let status;
+        if (!res.ok || res.contentOk === false) {
+            // The event itself is not trustworthy (bad signature, broken inclusion,
+            // unbound checkpoint) or its disclosure contradicts the commitment.
+            status = "failed";
+            evErrors.push(res.contentOk === false
+                ? "disclosed content does not bind to the committed content_hash — withheld"
+                : "the event's own proof chain did not verify — nothing here is safe to materialize");
+            evErrors.push(...res.errors);
+        }
+        else if (!selection.offered) {
+            // Minimal disclosure: the committed hash is there, the bytes are not.
+            // Distinct from empty bytes, and never an error.
+            status = "not_disclosed";
+        }
+        else if (bytes === undefined) {
+            status = "failed";
+            evErrors.push("content was disclosed for this event but is not a decodable lowercase-hex string");
+            evErrors.push(...selection.errors);
+        }
+        else if (res.contentOk !== true) {
+            // Disclosed and decodable, but there is no commitment to check it against
+            // (withheld record, or a record committing no content_hash). Unbound
+            // bytes are exactly what a consumer must not silently write out.
+            status = "undetermined";
+            evErrors.push("disclosed bytes are not bound to any committed content_hash — withheld rather than returned");
+            evErrors.push(...res.errors);
+        }
+        else {
+            status = "verified";
+        }
+        const verified = status === "verified" && bytes !== undefined;
+        if (verified) {
+            if (content.has(res.eventId)) {
+                errors.push(`duplicate event_id ${JSON.stringify(res.eventId)}: the content map keeps the first ` +
+                    "occurrence — read events[] for every event");
+            }
+            else {
+                content.set(res.eventId, bytes);
+            }
+        }
+        events.push({
+            eventId: res.eventId,
+            status,
+            bytes: verified ? bytes : null,
+            errors: evErrors,
+        });
+    }
+    return { status: verification.status, verification, events, content, errors };
+}
+// The anchor-trace events a bundle carries, unwrapping any evidence-export
+// 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) {
+    let cur = bundle;
+    for (let depth = 0; depth < MAX_EXPORT_UNWRAP; depth++) {
+        if (cur === null || typeof cur !== "object" || Array.isArray(cur))
+            return undefined;
+        const b = cur;
+        const bodyType = typeof b.body_type === "string" ? b.body_type : null;
+        if (bodyType === ANCHOR_TRACE_BODY_TYPE) {
+            const body = b.body;
+            if (body === null || typeof body !== "object" || !Array.isArray(body.events))
+                return undefined;
+            return body.events;
+        }
+        if (bodyType !== EXPORT_BODY_TYPE)
+            return undefined;
+        const body = b.body;
+        if (body === null || typeof body !== "object")
+            return undefined;
+        cur = body.source_bundle;
+    }
+    return undefined;
+}
 // ===========================================================================
 // Attested-evidence-export verification (evidence-export.md §5, steps 3–9).
 // Reached from verifyEvidenceBundle AFTER the wrapper (Ed25519 issuer signature
@@ -1033,6 +1154,32 @@ function getEventId(env) {
     }
     return "<unknown>";
 }
+function selectDisclosedBytes(ev, eventId, sideContent) {
+    const errors = [];
+    let inBody;
+    if (typeof ev.content === "string") {
+        try {
+            inBody = hexToBytes(ev.content);
+        }
+        catch (e) {
+            errors.push(`event content is not hex: ${stringifyErr(e)}`);
+        }
+    }
+    let side;
+    const sideRaw = sideContent?.[eventId];
+    if (sideRaw instanceof Uint8Array) {
+        side = sideRaw;
+    }
+    else if (typeof sideRaw === "string") {
+        try {
+            side = hexToBytes(sideRaw);
+        }
+        catch (e) {
+            errors.push(`supplied content for ${eventId} is not hex: ${stringifyErr(e)}`);
+        }
+    }
+    return { inBody, side, offered: ev.content !== undefined || sideRaw !== undefined, errors };
+}
 function toHex(bytes) {
     let out = "";
     for (const x of bytes)

package/dist/index.d.ts

@@ -2,8 +2,8 @@ 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, EXPORT_BODY_TYPE, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
-export type { AnchorTraceBody, AttestationPayload, AttestationRecord, AttestationResult, CheckpointResult, ComposeVerdictResult, EvidenceBundle, EvidenceBundleResult, EvidenceIssuer, EvidenceStatus, EvidenceVerdict, EventResult, ExportBody, ExportResult, OnChainOutcome, OnChainResult, PerGatewayOutcome, TraceCheckpoint, TraceEvent, TraceInclusion, VerdictAttestation, VerdictCheckpoint, VerdictEvent, VerdictObject, VerdictOnChain, VerdictOnChainGateway, VerifyEvidenceOptions, } from "./evidence.js";
+export { ANCHOR_TRACE_BODY_TYPE, 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, TraceCheckpoint, TraceEvent, TraceInclusion, VerdictAttestation, VerdictCheckpoint, VerdictEvent, VerdictObject, VerdictOnChain, VerdictOnChainGateway, VerifyEvidenceOptions, } from "./evidence.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

@@ -26,7 +26,15 @@ export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyI
 // issuer-composed sanning.evidence.export/v1 body (specs/evidence-export.md) to
 // verifyExportBody (embedded RSA-PSS operator attestations + a recomputed §4
 // verdict object with per-gateway on-chain outcomes).
-export { ANCHOR_TRACE_BODY_TYPE, EXPORT_BODY_TYPE, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
+//
+// `disclosedContent` is the INGEST half of the same path (evidence-bundle
+// §5.1). A received bundle carries its disclosed raw bytes as lowercase hex, so
+// materializing them was, until now, every consumer re-implementing the
+// encoding convention — and a consumer that copied the field VERBATIM wrote
+// 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, EXPORT_BODY_TYPE, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanning/proof",
-  "version": "0.4.1",
+  "version": "0.5.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",

package/src/cli.ts

@@ -72,8 +72,11 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
     io.out("@sanning/proof verify CLI");
     return EXIT_VERIFIED;
   }
-  if (command === "export") {
-    return runExport(rest, io);
+  // `bundle` is the customer-facing verb (proof#19: one artifact, one word).
+  // `export` is kept working as a QUIET alias — it shipped and is published, so
+  // it is not broken abruptly; it is simply no longer taught anywhere.
+  if (command === "bundle" || command === "export") {
+    return runBundle(rest, io);
   }
   if (command !== "verify") {
     io.err(`unknown command: ${command}`);
@@ -184,7 +187,8 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
   return reportEvidence(result, bundlePath, gateways, io);
 }
 
-// `proof export <source-bundle.json> --attestations <f> --key <f> [-o <out>]`
+// `proof bundle <source-bundle.json> --attestations <f> --key <f> [-o <out>]`
+// (`proof export` still reaches this, undocumented — see the dispatch above.)
 //
 // Compose a signed, offline-verifiable sanning.evidence.export/v1 artifact from a
 // source sanning.anchor.trace/v1 bundle + operator attestation records + an exporter
@@ -195,7 +199,7 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
 // forged/mis-bound attestation — the composer refuses to emit a green artifact
 // over failing evidence) · 2 usage / malformed input (missing flag, unreadable
 // or non-JSON input, bad exporter key, malformed attestation record).
-async function runExport(rest: string[], io: Cli): Promise<number> {
+async function runBundle(rest: string[], io: Cli): Promise<number> {
   let attestationsPath: string | undefined;
   let keyPath: string | undefined;
   let outPath: string | undefined;
@@ -306,7 +310,7 @@ async function runExport(rest: string[], io: Cli): Promise<number> {
 
 function usageExport(io: Cli): number {
   io.out(
-    "Usage: npx @sanning/proof export <source-bundle.json> --attestations <file> --key <file> [-o <out.json>]",
+    "Usage: npx @sanning/proof bundle <source-bundle.json> --attestations <file> --key <file> [-o <out.json>]",
   );
   io.out("");
   io.out("Compose a signed, offline-verifiable sanning.evidence.export/v1 artifact from an");
@@ -399,8 +403,8 @@ function printUsage(io: Cli): void {
   io.out("Usage: npx @sanning/proof <command> [args]");
   io.out("");
   io.out("Commands:");
-  io.out("  verify <bundle.json> [gateways] [--logs <logs.json>]   Verify a bundle/export");
-  io.out("  export <source.json> --attestations <f> --key <f> [-o] Compose an attested export");
+  io.out("  verify <bundle.json> [gateways] [--logs <logs.json>]   Verify a bundle");
+  io.out("  bundle <source.json> --attestations <f> --key <f> [-o] Create an attested bundle");
   io.out("");
   io.out("Verify a sanning.evidence/v1 (sanning.anchor.trace/v1) bundle, an");
   io.out("sanning.evidence.export/v1 attested export, or a sanning.agent.proof/v1");

package/src/evidence.ts

@@ -699,26 +699,12 @@ async function verifyAnchorTrace(
       }
 
       // Disclosed bytes, precedence: in-body (signed) → side input. A string
-      // side input is hex; a Uint8Array is used as-is.
-      let inBody: Uint8Array | undefined;
-      if (typeof ev.content === "string") {
-        try {
-          inBody = hexToBytes(ev.content);
-        } catch (e) {
-          evErrors.push(`event content is not hex: ${stringifyErr(e)}`);
-        }
-      }
-      let side: Uint8Array | undefined;
-      const sideRaw = options.content?.[eventId];
-      if (sideRaw instanceof Uint8Array) {
-        side = sideRaw;
-      } else if (typeof sideRaw === "string") {
-        try {
-          side = hexToBytes(sideRaw);
-        } catch (e) {
-          evErrors.push(`supplied content for ${eventId} is not hex: ${stringifyErr(e)}`);
-        }
-      }
+      // side input is hex; a Uint8Array is used as-is. Resolved by the SHARED
+      // selector so `disclosedContent` hands a consumer the very bytes bound
+      // here — one decode, not two that can drift apart.
+      const selection = selectDisclosedBytes(ev, eventId, options.content);
+      const { inBody, side } = selection;
+      evErrors.push(...selection.errors);
 
       if (inBody !== undefined && side !== undefined && !bytesEqual(inBody, side)) {
         // Two disclosures that disagree: a genuine conflict, not undetermined.
@@ -832,6 +818,214 @@ async function verifyAnchorTrace(
   };
 }
 
+// ===========================================================================
+// Ingest: materializing the disclosed raw bytes (evidence-bundle.md §5.1).
+//
+// The receiving half of a handoff. `events[].content` rides as lowercase hex
+// (JSON cannot carry arbitrary bytes), and until now every consumer that wanted
+// the actual log bytes back had to know that and decode them itself —
+// re-implementing an encoding convention the kernel already applies internally.
+// A consumer that copied `content` VERBATIM into a file shipped packs that
+// failed verification on genuine, untampered evidence, because the hash of the
+// hex text is not the hash of the bytes it encodes.
+//
+// `disclosedContent` closes that gap with one rule: bytes come back only when
+// they are BOUND. It verifies the bundle first and hands back a decoded
+// Uint8Array only for events whose whole chain held AND whose disclosed bytes
+// hash to the committed `content_hash`. Everything else comes back as a status
+// with a reason and NO bytes — in particular a minimal-disclosure event reports
+// `not_disclosed` rather than empty bytes, because a caller that cannot tell
+// those apart writes an empty log file and believes it succeeded.
+// ===========================================================================
+
+// Per-event outcome of an ingest attempt. Only `verified` carries bytes.
+export type DisclosureStatus =
+  | "verified" // bytes decoded AND bound to the committed content_hash
+  | "not_disclosed" // nothing disclosed for this event — minimal disclosure, nothing to write
+  | "undetermined" // bytes disclosed but nothing to bind them to (record withheld / no commitment)
+  | "failed"; // the event's chain did not verify, or the disclosure did not bind/decode
+
+export interface DisclosedEventContent {
+  eventId: string;
+  status: DisclosureStatus;
+  // The decoded raw bytes. Non-null ONLY when status === "verified" — an
+  // unbound or unverified disclosure is withheld, never handed back.
+  bytes: Uint8Array | null;
+  // Why, whenever bytes are absent for a reason other than plain non-disclosure.
+  errors: string[];
+}
+
+export interface DisclosedContentResult {
+  // The bundle-level rollup, verbatim from verifyEvidenceBundle.
+  status: EvidenceStatus;
+  // The full verification result, so a caller verifies ONCE: render the verdict
+  // from this and materialize from `content` in the same pass.
+  verification: EvidenceBundleResult;
+  // One entry per event in the bundle body, in body order.
+  events: DisclosedEventContent[];
+  // event_id → verified raw bytes: the materialization map. Contains ONLY
+  // entries whose status is "verified", so `for (const [id, bytes] of
+  // result.content)` is always safe to write straight to disk.
+  content: Map<string, Uint8Array>;
+  // Bundle-level reasons no content could be materialized at all.
+  errors: string[];
+}
+
+// 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
+// independently bounded rather than trusting that it ran first.
+const MAX_EXPORT_UNWRAP = 4;
+
+/**
+ * Materialize the disclosed raw bytes of a received bundle (evidence-bundle §5.1).
+ *
+ * Verify-then-return: the bundle is verified with {@link verifyEvidenceBundle}
+ * (same options — gateways, out-of-band `content`, `fetchImpl`), and an event's
+ * bytes are returned ONLY when that verification bound them to the committed
+ * `content_hash`. There is no path through this function that yields bytes
+ * whose SHA-256 is not the commitment.
+ *
+ * Returns `Uint8Array`, never a string: the spec commits to raw bytes, and a
+ * UTF-8 decode is lossy for any payload that is not valid UTF-8 — re-encoding
+ * such a string would produce different bytes and a different hash. Callers who
+ * know their payload is text decode it themselves and own that assumption.
+ */
+export async function disclosedContent(
+  bundle: unknown,
+  options: VerifyEvidenceOptions = {},
+): Promise<DisclosedContentResult> {
+  const verification = await verifyEvidenceBundle(bundle, options);
+  const events: DisclosedEventContent[] = [];
+  const content = new Map<string, Uint8Array>();
+  const errors: string[] = [];
+  const empty = (): DisclosedContentResult => ({
+    status: verification.status,
+    verification,
+    events: [],
+    content: new Map(),
+    errors: [...errors, ...verification.errors],
+  });
+
+  const traceEvents = resolveTraceEvents(bundle);
+  if (traceEvents === undefined) {
+    errors.push(
+      `no ${ANCHOR_TRACE_BODY_TYPE} body to materialize content from ` +
+        `(body_type ${JSON.stringify(verification.bodyType)})`,
+    );
+    return empty();
+  }
+
+  // Fail closed on any drift between the body we are decoding and the results
+  // we are trusting. Both must be the same events in the same order, or the
+  // "these bytes are the bytes that verified" guarantee is void — which is the
+  // only guarantee this function makes. A broken wrapper lands here too:
+  // verifyEvidenceBundle returns zero event results, so nothing is emitted.
+  if (traceEvents.length !== verification.events.length) {
+    errors.push(
+      "the bundle did not verify far enough to materialize content: " +
+        `${verification.events.length} verified event result(s) for ${traceEvents.length} body event(s)`,
+    );
+    return empty();
+  }
+  for (let i = 0; i < traceEvents.length; i++) {
+    const te = traceEvents[i];
+    const envelope = te !== null && typeof te === "object" ? te.envelope : undefined;
+    if (getEventId(envelope) !== verification.events[i]!.eventId) {
+      errors.push(
+        `event alignment drift at index ${i}: the body event and its verification result ` +
+          "are not the same event; refusing to hand back any content",
+      );
+      return empty();
+    }
+  }
+
+  for (let i = 0; i < traceEvents.length; i++) {
+    const ev = traceEvents[i] as TraceEvent;
+    const res = verification.events[i]!;
+    const selection = selectDisclosedBytes(ev, res.eventId, options.content);
+    const bytes = selection.inBody ?? selection.side;
+    const evErrors: string[] = [];
+    let status: DisclosureStatus;
+
+    if (!res.ok || res.contentOk === false) {
+      // The event itself is not trustworthy (bad signature, broken inclusion,
+      // unbound checkpoint) or its disclosure contradicts the commitment.
+      status = "failed";
+      evErrors.push(
+        res.contentOk === false
+          ? "disclosed content does not bind to the committed content_hash — withheld"
+          : "the event's own proof chain did not verify — nothing here is safe to materialize",
+      );
+      evErrors.push(...res.errors);
+    } else if (!selection.offered) {
+      // Minimal disclosure: the committed hash is there, the bytes are not.
+      // Distinct from empty bytes, and never an error.
+      status = "not_disclosed";
+    } else if (bytes === undefined) {
+      status = "failed";
+      evErrors.push(
+        "content was disclosed for this event but is not a decodable lowercase-hex string",
+      );
+      evErrors.push(...selection.errors);
+    } else if (res.contentOk !== true) {
+      // Disclosed and decodable, but there is no commitment to check it against
+      // (withheld record, or a record committing no content_hash). Unbound
+      // bytes are exactly what a consumer must not silently write out.
+      status = "undetermined";
+      evErrors.push(
+        "disclosed bytes are not bound to any committed content_hash — withheld rather than returned",
+      );
+      evErrors.push(...res.errors);
+    } else {
+      status = "verified";
+    }
+
+    const verified = status === "verified" && bytes !== undefined;
+    if (verified) {
+      if (content.has(res.eventId)) {
+        errors.push(
+          `duplicate event_id ${JSON.stringify(res.eventId)}: the content map keeps the first ` +
+            "occurrence — read events[] for every event",
+        );
+      } else {
+        content.set(res.eventId, bytes);
+      }
+    }
+    events.push({
+      eventId: res.eventId,
+      status,
+      bytes: verified ? bytes : null,
+      errors: evErrors,
+    });
+  }
+
+  return { status: verification.status, verification, events, content, errors };
+}
+
+// The anchor-trace events a bundle carries, unwrapping any evidence-export
+// 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 {
+  let cur: unknown = bundle;
+  for (let depth = 0; depth < MAX_EXPORT_UNWRAP; depth++) {
+    if (cur === null || typeof cur !== "object" || Array.isArray(cur)) return undefined;
+    const b = cur as EvidenceBundle;
+    const bodyType = typeof b.body_type === "string" ? b.body_type : null;
+    if (bodyType === ANCHOR_TRACE_BODY_TYPE) {
+      const body = b.body as AnchorTraceBody | null | undefined;
+      if (body === null || typeof body !== "object" || !Array.isArray(body.events)) return undefined;
+      return body.events;
+    }
+    if (bodyType !== EXPORT_BODY_TYPE) return undefined;
+    const body = b.body as ExportBody | null | undefined;
+    if (body === null || typeof body !== "object") return undefined;
+    cur = body.source_bundle;
+  }
+  return undefined;
+}
+
 // ===========================================================================
 // Attested-evidence-export verification (evidence-export.md §5, steps 3–9).
 // Reached from verifyEvidenceBundle AFTER the wrapper (Ed25519 issuer signature
@@ -1478,6 +1672,53 @@ function getEventId(env: unknown): string {
   return "<unknown>";
 }
 
+// The disclosed bytes offered for ONE trace event (evidence-bundle §5.1),
+// decoded once. Shared by the verifier's content check and the `disclosedContent`
+// ingest API: the bytes a consumer receives are then, by construction, the bytes
+// the verifier hashed against the commitment rather than a second decode of the
+// same field that could drift from it.
+interface DisclosedSelection {
+  // In-body `events[].content` (the signed disclosure), when it decoded.
+  inBody?: Uint8Array;
+  // Out-of-band `options.content[eventId]`, when it decoded.
+  side?: Uint8Array;
+  // A disclosure was OFFERED for this event — in-body or side input — whether or
+  // not it decoded. This is what separates "minimal disclosure, nothing to
+  // materialize" from "disclosed, but unusable"; conflating those is how a
+  // consumer writes an empty log file and believes it succeeded.
+  offered: boolean;
+  // Decode failures, in the verifier's existing wording.
+  errors: string[];
+}
+
+function selectDisclosedBytes(
+  ev: TraceEvent,
+  eventId: string,
+  sideContent: VerifyEvidenceOptions["content"],
+): DisclosedSelection {
+  const errors: string[] = [];
+  let inBody: Uint8Array | undefined;
+  if (typeof ev.content === "string") {
+    try {
+      inBody = hexToBytes(ev.content);
+    } catch (e) {
+      errors.push(`event content is not hex: ${stringifyErr(e)}`);
+    }
+  }
+  let side: Uint8Array | undefined;
+  const sideRaw = sideContent?.[eventId];
+  if (sideRaw instanceof Uint8Array) {
+    side = sideRaw;
+  } else if (typeof sideRaw === "string") {
+    try {
+      side = hexToBytes(sideRaw);
+    } catch (e) {
+      errors.push(`supplied content for ${eventId} is not hex: ${stringifyErr(e)}`);
+    }
+  }
+  return { inBody, side, offered: ev.content !== undefined || sideRaw !== undefined, errors };
+}
+
 function toHex(bytes: Uint8Array): string {
   let out = "";
   for (const x of bytes) out += x.toString(16).padStart(2, "0");

package/src/index.ts

@@ -51,9 +51,18 @@ export type { ContentRole, Envelope, Subject, VerificationResult, VerifyOptions
 // issuer-composed sanning.evidence.export/v1 body (specs/evidence-export.md) to
 // verifyExportBody (embedded RSA-PSS operator attestations + a recomputed §4
 // verdict object with per-gateway on-chain outcomes).
+//
+// `disclosedContent` is the INGEST half of the same path (evidence-bundle
+// §5.1). A received bundle carries its disclosed raw bytes as lowercase hex, so
+// materializing them was, until now, every consumer re-implementing the
+// encoding convention — and a consumer that copied the field VERBATIM wrote
+// 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,
   EXPORT_BODY_TYPE,
+  disclosedContent,
   recomputeExportVerdict,
   verifyEvidenceBundle,
 } from "./evidence.js";
@@ -64,6 +73,9 @@ export type {
   AttestationResult,
   CheckpointResult,
   ComposeVerdictResult,
+  DisclosedContentResult,
+  DisclosedEventContent,
+  DisclosureStatus,
   EvidenceBundle,
   EvidenceBundleResult,
   EvidenceIssuer,