UDDP Container v1 — Autonomous Capsule File Format (.uddp)

Status: Draft Date: 2026-07-14 Reference implementation: packages/decryptor (generateUddp), tests in packages/decryptor/src/uddp.test.ts Depends on: capsule-v1.md, tsp-v1.md (capsule wire formats — the container packages a capsule, it does not redefine one)

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals.

---

1. Purpose and model

A .uddp file is the distribution format of a sealed capsule: a single file the recipient can keep for decades and open with no software from this project — no web app, no CLI, no installed application. Everything needed travels inside:

• the capsule document (the normative JSON of capsule-v1.md / tsp-v1.md);
• a complete, dependency-free opener (OPEN-ME.html, all cryptography inlined);
• plain-text instructions and the protocol documents needed to re-implement an opener from scratch.

The design answer to “what if the program we made no longer exists?” is: a copy of the opener is inside every capsule file. The project dying cannot take the opener away from a recipient who holds the file.

1.1 Why a ZIP container

A proprietary extension and platform-independent opening pull in opposite directions: an OS with no registered handler opens .uddp with nothing. The resolution is the .docx/.epub/.jar pattern — an own extension over plain ZIP. ZIP has a 30+ year ubiquity record, a public specification, built-in readers in every OS file manager, and unmistakable magic bytes (PK): any technician confronted with an unknown file will identify and unpack it. The container’s job is to make sure what they find inside explains itself.

1.2 The authority rule

The container is packaging, not protocol. The embedded capsule.json is the sole normative artifact: the creator signature, the payload hash, and every verification claim are defined over the capsule JSON exactly as in the wire-format specs — never over the container or the opener. Consequences:

1. Extracting capsule.json and opening it with any conforming TSP opener MUST produce the identical plaintext.
2. Re-wrapping the same capsule.json in a newer container changes nothing normative, and MUST NOT modify its bytes.

1.3 The opening ladder (design requirement)

Rung	Requires	Mechanism
A — one click	our application installed	app registers .uddp; double-click opens directly
B — two steps	any OS + any ES2022 browser, offline	open/rename as ZIP → README.txt says: open OPEN-ME.html in a browser
C — extract & open elsewhere	any conforming TSP opener	unzip, take capsule.json
D — re-implement	a competent engineer, a text editor	README.txt + spec/ + test vector: rebuild an opener from documents alone

Rung A is the product; rungs B–D are the century insurance. A container that delivers A but not B–D is a demo, not a UDDP file.

2. Container format

• A .uddp file is a ZIP archive per the public ZIP APPNOTE specification.
• Compression: each entry MUST use store (0) or deflate (8) only. No encryption, no patented methods, no multi-volume. ZIP64 MAY be used only when an entry exceeds 4 GiB.
• Entry names: ASCII, forward slashes, no leading /, no .. segments.
• File extension: .uddp. MIME type: application/x-uddp. A renamed file MUST still open (the extension is a convention, not load-bearing).

2.1 Type detection (the mimetype entry)

Following the EPUB convention, the first entry in the archive MUST be named mimetype, stored uncompressed (method 0), no extra field, containing exactly the ASCII bytes:

application/x-uddp

This places the string at a fixed offset near the start of the file (local header 30 bytes + 8-byte name → content at offset 38), so file-style detectors identify a UDDP container from the first ~60 bytes without unpacking: PK\x03\x04 at offset 0, mimetype at offset 30, application/x-uddp at offset 38.

2.2 Layout

mimetype                # REQUIRED, first, stored — §2.1
capsule.json            # REQUIRED — the normative capsule document, byte-exact (§3)
OPEN-ME.html            # REQUIRED — self-contained offline opener (§4)
README.txt              # REQUIRED — plain-text instructions (§6)
spec/                   # REQUIRED — the protocol documents (§6)
  capsule-v1.md         #   (and/or tsp-v1.md — whichever governs this capsule)
  vectors/…             #   at least one known-answer test vector
payload.bin             # OPTIONAL — raw ciphertext bytes for large payloads (§7)
beacon.json             # OPTIONAL — pre-fetched round-R beacon, if available (§5)
manifest.json           # OPTIONAL — SHA-256 of every other entry (§8)

Unknown additional entries: readers MUST ignore entries they do not recognize (forward compatibility of packaging) — but the opener and extractors MUST take the capsule only from capsule.json, never from an unknown entry.

3. capsule.json (rung C — machine extraction)

• Contains the capsule document byte-exact as produced at seal time. Byte- exactness is what keeps the creator signature and the capsule hash verifiable after extraction — the entry MUST NOT be reformatted, re-encoded, or re-keyed.
• Exactly one capsule.json per container.
• A conforming extractor is: unzip, read capsule.json. Nothing else.

4. OPEN-ME.html (rung B — the embedded opener)

A single self-contained HTML5/UTF-8 document that opens from file://:

• Self-containment. MUST NOT reference any external resource — no external scripts, stylesheets, fonts, images, or imports. All dependencies (tlock/IBE, BLS12-381, Argon2id WASM as base64, HKDF, AES-GCM glue) are inlined (security invariant #5). The only permitted network use is fetching the beacon value (§5); the opener MUST work with zero network when the beacon is pasted or embedded.
• Runtime baseline. ES2022 or lower; only Web Crypto (crypto.subtle), WebAssembly, TextEncoder/TextDecoder, Uint8Array, DOM, and the File API (§7). SHOULD declare a <meta http-equiv="Content-Security-Policy"> forbidding everything except inline script/style and connect-src to the documented beacon endpoints.
• Embedded capsule. MUST embed a byte-identical copy of capsule.json (after the mandatory </script> → <\/script> escaping, which is reversed before use), so the HTML alone still opens the capsule if separated from the container. capsule.json remains the authority; a mismatch between the two copies MUST fail loudly if ever detected.
• Verification. MUST enforce the wire-format opening rules unchanged — in particular BLS verification of every beacon value against the pinned quicknet group key before use (invariant #7), regardless of source.
• Self-test. MUST include the embedded KAT (known capsule → known plaintext, from spec/vectors/) and run it before first decryption; a failing self-test blocks opening with an explanatory error — a silently miscomputing opener is worse than none.
• UI floor. Before any password entry, display: unlock date (UTC), round number, capsule hash, and whether the unlock date has arrived. The password MUST never leave the page: no form submission, no fetch containing password-derived material, no storage of secrets.
• Emergency appendix. A script-free plain-HTML section at the end (readable in a text editor) summarizing the opening algorithm and constants — a compact fallback if the HTML is separated from README.txt and spec/.

4.1 The opener template and cross-implementation identity

OPEN-ME.html embeds a compiled bundle that cannot be byte-identically rebuilt across toolchains, so it is produced once as a versioned template artifact (opener-template-v<N>.html, published with its SHA-256 — see RFC-0010 §3), and every generator produces the opener by single-pass placeholder substitution: the template is scanned for {{UNTILUM_[A-Z_]+}}; each match is replaced; substituted values are never re-scanned. Generators MUST NOT modify template bytes outside the placeholders.

Placeholder	Replacement
{{UNTILUM_TITLE}}	human title, HTML-escaped
{{UNTILUM_OPEN_DATE}}	unlock.at (ISO-8601 UTC), HTML-escaped
{{UNTILUM_ROUND}}	decimal round number
{{UNTILUM_CAPSULE_JSON}}	capsule JSON, byte-exact, then </script> → <\/script> (case-insensitive)
{{UNTILUM_CONFIG_JSON}}	the runtime config JSON (below), same </script> escaping

HTML-escaping: exactly &→&, <→<, >→>, "→", in that order, nothing else.

The runtime config is serialized with JSON.stringify semantics (no added whitespace, UTF-8 verbatim, standard escapes) and this exact key order:

{"capsuleJson": "<capsule JSON as a string>",
 "openDateIso": "<unlock.at>",
 "round": <round>,
 "beaconId": "<unlock.beacons[0].id>",
 "embeddedBeacon": null | {"round": …, "signature": "…", "randomness": "…"}}

beacon.json (§5) uses the same three-field key order. With the same inputs and the same template version, every conforming generator MUST produce a byte-identical container (RFC-0010 §F2); README.txt rendering follows the reference implementation byte-for-byte (packages/decryptor/src/uddp.ts).

5. Beacon acquisition

The opener MUST offer, in order of preference:

1. beacon.json / embedded — when the container was generated (or re-issued) after the unlock date, the round-R beacon MAY ride along; it is still BLS-verified at open time (embedding bypasses the fetch, never the verification).
2. Fetch — https://api.drand.sh/<chainHash>/public/<round> and the Cloudflare relay, as pinned constants.
3. Manual paste — a field accepting the beacon JSON or bare signature hex from any source (mirror, archive, another person), verified like all others.

README.txt MUST explain how to obtain a historical round if all listed URLs are dead (drand mirrors; the Arweave beacon archive when available).

6. README.txt and spec/ (rung D — re-implementation)

README.txt is plain ASCII/UTF-8 text, no markup dependency, and MUST contain:

1. What this file is — one paragraph; the unlock date (UTC) and round number.
2. How to open it — the two-step instruction (“this file is a ZIP archive; extract it and open OPEN-ME.html in any browser”), stated simply enough for a non-technical recipient.
3. The password rule — the password is held by the sender only; it was never stored and cannot be recovered by anyone, including the project.
4. The opening algorithm in brief — the envelope scheme of the spec governing the packaged capsule’s version (tlock-decrypt of tlsecret, Argon2id parameters, the version’s HKDF info strings — "untilum-v2" / "untilum-v2-meta" for v2, "capsule-v1" / "capsule-v1-meta" for v1 — AES-256-GCM layout) with all pinned quicknet constants, self-contained: correct even if every project URL is dead.
5. Pointers — canonical spec/RFC URLs and their Arweave txids.

spec/ MUST contain the wire-format specification governing this capsule’s version and at least one known-answer test vector, so a re-implementation can prove itself before touching the real capsule. This is RFC-0009 §6 made literal: the documents that guarantee resurrection ride inside every capsule file.

7. Large payloads (payload.bin)

• Inline default. Up to a generator-enforced threshold (RECOMMENDED: 25 MB of ciphertext), the ciphertext lives inside capsule.json per the wire format, and OPEN-ME.html carries it in its embedded copy.
• Container-local. Above the threshold, the raw ciphertext bytes SHOULD be stored as the payload.bin entry (stored, not deflated — ciphertext does not compress), with capsule.json referencing it by hash. This avoids base64 (+33%) and keeps the container fully autonomous. Because browsers do not allow file:// pages to read sibling files, OPEN-ME.html MUST provide a file picker (“select payload.bin from the extracted folder”) and MUST verify the selected bytes against payload.hash before decrypting.
• By-reference (last resort). A capsule whose ciphertext lives only on Arweave (txid + payload.hash) MAY be packaged without payload.bin; the opener and README.txt MUST say plainly that the bytes require storage liveness, and list the txid plus several gateway alternatives. Fetched bytes MUST be verified against payload.hash before decrypting.

8. Integrity and the tampered-wrapper problem

The creator signature covers the capsule JSON only (§1.2). The wrapper — opener, README, specs — is not covered: a party who can modify the file could replace OPEN-ME.html with one that exfiltrates the password. This is inherent to any self-executing container. Mitigations, in force order:

1. Storage pinning (primary). When the capsule is stored on Arweave, the stored object SHOULD be the entire .uddp file, so one transaction id immutably pins capsule and wrapper together. A recipient who fetches by txid holds a container nobody could alter after sealing.
2. Reproducible generation. Container generation SHOULD be deterministic — fixed entry order, zeroed timestamps, no extra fields, stable deflate settings — so the same capsule + the same generator version yields a byte-identical file that any third party can regenerate and diff.
3. Out-of-band hash. The receipt (RFC-0007 §4) SHOULD carry the SHA-256 of the full container alongside the capsule hash. The optional manifest.json (SHA-256 of every other entry) lets a reader localize which entry was altered — noting that a wrapper-tamperer can rewrite the manifest too; only the external pin (1) or hash (3) is load-bearing.
4. CSP + offline habit. The opener’s CSP and the documented advice to open offline bound what a tampered opener can do quietly.

None of these makes tampering impossible for an attacker who controls both the file copy and the recipient’s trust; they make it detectable by anyone who checks.

9. Versioning

• Container version: manifest.json carries {"uddp": 1, …} when present; otherwise the layout itself (§2.2) identifies v1. The capsule’s own v field governs everything normative (§1.2).
• A newer generator MAY re-wrap an old capsule at any time — e.g. a re-issue that adds beacon.json after the unlock date. Re-wrapping MUST NOT modify capsule.json bytes.
• Packaging evolves by adding entries (ignored by old readers, §2.2), never by changing the meaning of existing ones.

10. Conformance checklist

A file is a conforming UDDP v1 container iff:

1. Valid ZIP; first entry mimetype, stored, exactly application/x-uddp (§2.1).
2. Exactly one capsule.json, byte-exact as signed (§3).
3. OPEN-ME.html: self-contained, offline-capable, embeds a byte-identical capsule copy, BLS-verifies every beacon, runs the KAT self-test, leaks no secrets (§4).
4. All three beacon acquisition paths, all verified identically (§5).
5. README.txt with the two-step instruction, algorithm summary, and constants; spec/ with the governing spec and a test vector (§6).
6. Payload packaged per §7 with hash verification on every non-inline path.
7. Unlock date, round, and capsule hash displayed before password entry (§4).

10.1 Implementation status (informative)

Implemented in packages/decryptor (generateUddp): the deterministic store-only ZIP container with the mimetype convention (§2), byte-exact capsule.json (§3), OPEN-ME.html with the extractable untilum-capsule block, CSP declaration, and emergency appendix (§4), beacon.json embedding (§5), generated README.txt + spec/ packaging (§6), inline-ceiling enforcement (§7), and manifest.json (§8.3).

Not yet implemented: the payload.bin + file-picker flow for large payloads (§7 — the generator rejects ciphertext above the inline ceiling instead), the by-reference variant (§7), and .uddp registration in the desktop application (rung A of §1.3).

Revision History

Date	Change
2026-07-14	Initial version (as TDDP; renamed to UDDP 2026-07-16 with the project rename, same wire layout).
2026-07-17	Publication pass for the series Last Call: BCP 14 boilerplate.