The portable audit bundle standard

.h33bundle v1

Standard: .h33bundle · Version: v1 · Status: Locked

One drag-droppable artifact bundles the receipts, envelopes, proofs, and parameter captures produced by a Federal L5 session window, with file-level SHA3-512 integrity hashes and registry-bound product_id / bundle_id attribution.

A recipient feeds the bundle to one verifier instead of routing the component artifacts through five different binaries.

Trust model

Bundle integrity stands on hash cryptography alone.

The verifier rejects any drift in:

· a file's SHA3-512 (file-level mutation)
· a receipt's canonical SHA3-256 (= its receipt_id — field-level mutation)
· the registry mapping (product_id must exist; bundle_id, when set, must reference a real bundle)
· the manifest's file enumeration (no extra files, no missing files)

No encryption, no signing, no remote calls in v1. Signing under ML-DSA-87 lands when the production key ceremony closes. Encryption is out of v1 scope.

At a glance

Container

Uncompressed POSIX tar

USTAR / PAX-compatible. No gzip, no zstd, no encryption. Inspect with tar -tvf bundle.h33bundle — no H33 binary required.

File hash

SHA3-512 per file

128 hex chars, lowercase. One hash per file in manifest.files[].

Receipt hash

SHA3-256 canonical

Receipt filename must equal its canonical receipt_id. Drift is fatal.

Encryption

None in v1

Receipts already carry commitments, not plaintexts.

Signing

None in v1

ML-DSA-87 authenticity lands after the production key ceremony closes.

Network

Offline verifier

No remote calls. Hard gate; tested.

Section 1 — On-wire format

File-tree layout

A .h33bundle is an uncompressed POSIX tar archive. The recipient can inspect contents without any H33 binary present.

h33bundle/ ├── manifest.json # Required. One file. UTF-8 JSON. Schema in §2. ├── INSTRUCTIONS.md # Required. Human-readable verifier guide. ├── receipts/ │ └── <receipt_id>.json # One file per receipt. UTF-8 JSON. ├── envelopes/ │ └── <receipt_id>.json # H33-PQ-1 envelope, one per receipt. ├── proofs/ # Optional. Present when ZK proofs ride along. │ └── <receipt_id>.bin # bincode-encoded ZkProofBundle. └── artifacts/ # Optional. Present when FHE commitments ride along. └── <receipt_id>.json # Ciphertext commitments — NOT plaintexts.

manifest.json is at the root of the bundle tree. The verifier asserts:

✓ manifest.json exists, parses, and conforms to §2's schema.
✓ Every file listed in manifest.files exists at the path stated.
✓ No file outside manifest.files exists in the archive (explicit extra-file failure).
✓ INSTRUCTIONS.md exists.

Path constraints

· All paths are relative, no leading /, no ...
· All paths use forward slash / separators.
· Receipt files MUST be named <receipt_id>.json (lowercase hex).
· The verifier rejects symlinks, hardlinks, and special files.

Section 2 — manifest.json schema

UTF-8, compact JSON. Field order = struct order.

{ "format": "h33bundle", "version": "v1", "created_at": 1781040351, "customer_id": "e2etest", "session_window": { "start": 1781040000, "end": 1781041000 }, "files": [ { "path": "receipts/a54225cd...adea8.json", "kind": "receipt", "sha3_512": "<128 hex chars>" } ], "receipts": [ { "receipt_id": "a54225cd...", "product_id": "ckks-256", "bundle_id": "federal-integrity-suite", "engine_id": "ckks-256", "operation": "keygen", "status": "success" } ] }

Self-referential hash handling

The manifest cannot directly contain its own SHA3-512. v1 handles this by:

The builder writes files[] with one entry whose kind: "manifest" and sha3_512: "" (empty string).
The bytes serialized at that point ARE the canonical manifest.
The builder rewrites the empty sha3_512 field with the actual hex of SHA3-512(canonical_bytes).
The verifier re-derives the canonical by setting the manifest's own sha3_512 field to "", re-serializing in struct order, and computing SHA3-512.

Sections 3 & 4 — receipt and envelope format

Receipts and envelopes ride unchanged.

Receipts (§3) are byte-equivalent to what GET /v1/fhe/l5/receipts/<id> returns. The bundle adds no envelope around the receipt; the file IS the receipt. The canonical SHA3-256 (= receipt_id) MUST match the file's base name. A mismatch is an explicit receipt-id-mismatch failure.

Envelopes (§4) carry the H33PqEnvelope JSON that the receipt's envelope_hash field commits to. The verifier recomputes envelope_hash(env) and compares to the receipt's envelope_hash. Any mismatch is an envelope-mismatch failure.

Section 7 — CLI surface

Create and verify.

h33 bundle create

$ h33 bundle create \ --customer-id <id> \ --receipts <dir> # Directory containing receipt JSON files --envelopes <dir> # Directory containing envelope JSON files --proofs <dir> # Optional --artifacts <dir> # Optional --output <path> # Path to write the .h33bundle

Output: a .h33bundle file at --output. Exit 0 on success, non-zero on any input validation failure.

h33 bundle verify

$ h33 bundle verify <bundle.h33bundle> ✓ h33bundle v1 verified customer_id: e2etest receipts: 3 (3 success, 0 failure) files: 9 (all SHA3-512 match) session: [1781040000 ..= 1781041000]

Stderr on failure: a single explicit reason and a non-zero exit code.

Section 8 — hard verification gates

Sixteen gates. No warnings. Each is fatal.

The verifier returns non-zero on any of the following. There is no warning state; a v1 bundle either passes every gate or it does not verify.

Gate	Reason code
Tarball cannot be opened	tar-open-failed
`manifest.json` missing	manifest-missing
`manifest.json` malformed	manifest-malformed
`manifest.format != "h33bundle"`	format-mismatch
`manifest.version != "v1"`	version-unsupported
File listed in manifest not present in tar	file-missing
File present in tar not listed in manifest	extra-file
File's actual SHA3-512 ≠ manifest hash	file-hash-mismatch
Receipt file name ≠ receipt's canonical SHA3-256	receipt-id-mismatch
Receipt canonical recomputed ≠ stated `receipt_id`	receipt-canonical-fail
Envelope hash recomputed ≠ receipt's `envelope_hash`	envelope-mismatch
Manifest `receipts[]` summary ≠ receipt file fields	receipt-summary-drift
Receipt's `product_id` not in canonical registry	unknown-product
Receipt's `bundle_id` not in canonical bundles	unknown-bundle
`INSTRUCTIONS.md` missing	instructions-missing
Manifest self-hash recipe (§2.2) doesn't recover	manifest-self-hash-fail

Section 9 — non-goals for v1 (explicit)

What v1 is deliberately not doing.

Each non-goal is a v2 conversation, not a v1 omission to argue with.

No signing

Authenticity lands with ML-DSA-87 activation, after the production key ceremony closes.

No encryption

Receipts already carry commitments, not plaintexts.

No compression

Bit-identity across builder implementations matters more than archive size.

No remote calls

Verifier MUST run offline. Hard gate; tested.

No proof re-verification

v1 verifier checks hash integrity, not STARK soundness. Replay is ZK-256 verifier's job.

No live attestation

.h33bundle is a snapshot of a session window, not a continuous stream. Continuous attestation lives on H33-PQ Verified.

.h33bundle v1

Bundle integrity stands on hash cryptography alone.

File-tree layout

Path constraints

UTF-8, compact JSON. Field order = struct order.

Self-referential hash handling

Receipts and envelopes ride unchanged.

Create and verify.

h33 bundle create

h33 bundle verify

Sixteen gates. No warnings. Each is fatal.

What v1 is deliberately not doing.

Where .h33bundle sits in the stack.