RFC-0010: Capsule File Format

Status: Last Call · Date: 2026-07-17 · Editors: Untilum project — hello@untilum.com

Part of the TSP RFC series; see the series index for the Last Call window and how to comment. 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.

Abstract

This document requires every capsule-creating application to deliver one and the same file format — the UDDP container — and to form it byte-identically across implementations. It specifies the pinned opener-template mechanism that makes cross-implementation identity achievable despite compiled-bundle irreproducibility, and the conformance rules F1–F5 that keep the guarantee testable in CI.

1. Principle

Every application that creates capsules — the web app, the desktop application, the CLIs, the SDKs, third-party tools — MUST hand the user one and the same file format: the UDDP container (normative wire format: uddp-v1.md). A capsule is a 50–100 year promise; the file the user archives must not depend on which of our applications produced it, because by opening day none of them may exist. One format means one set of recovery instructions, one opener, one thing for archives and heirs to recognize.

A bare capsule.json remains the normative protocol artifact (RFC-0009; uddp-v1.md §1.2) and implementations MAY additionally expose it for interoperability and debugging — but the default deliverable to an end user is the container: capsule + embedded opener + instructions + specifications, in one file.

2. Identical formation across implementations

It is not enough that every application emits a UDDP file; they MUST emit the same UDDP file. For one capsule document (identical capsule.json bytes), one embedded beacon, and one opener-template version, every conforming generator — TypeScript, Rust, or independent — MUST produce a byte-identical container.

Why this is a protocol requirement and not a nicety:

• Tamper evidence. Byte-identical generation is what makes the reproducibility defense of uddp-v1.md §8.2 real across the ecosystem: anyone can regenerate a suspect container with any conforming implementation and diff it.
• Storage deduplication. The same capsule pinned to permanent storage by two applications yields one object, one hash, one transaction — not divergent copies.
• Conformance is testable. Cross-implementation identity is a single CI assertion (SHA-256(container_A) == SHA-256(container_B)), which keeps the guarantee from silently rotting.

3. The opener template

The only part of a container an implementation cannot independently reproduce is OPEN-ME.html: it embeds a compiled JavaScript bundle, and byte-identical bundles cannot be rebuilt from source across toolchains. Therefore:

• The opener is built once, in the reference repository’s CI, as a versioned template artifact — OPEN-ME.html with defined placeholders (title, unlock date, round, the capsule block, the runtime config) instead of capsule data.
• Each template version is published with its SHA-256. Implementations treat the template as a pinned input, exactly like a beacon group key: they substitute placeholders; they never rebuild or modify the template.
• Generating a container is then pure data assembly — placeholder substitution, README rendering from capsule fields, deterministic ZIP writing — all of which is specified byte-exactly, so any language reaches the same output.
• The template itself remains subject to every OPEN-ME.html rule of uddp-v1.md §4 (self-containment, pinned-key verification, KAT self-test, emergency appendix). A new template version is a normal artifact release: reviewed, hashed, changelogged.

4. Conformance

• F1 — Applications creating capsules MUST offer the UDDP container as the default (or only) capsule file given to the user, and MUST NOT invent application-specific capsule file formats.
• F2 — Given identical inputs (capsule bytes, beacon, title, template version, spec set), two conforming generators MUST produce byte-identical containers.
• F3 — Generators MUST NOT modify template bytes outside the defined placeholders, and MUST NOT modify capsule.json bytes at all (uddp-v1.md §1.2).
• F4 — The reference repository publishes each opener-template version with its hash; generators SHOULD record the template version they used (the container’s manifest.json already hashes OPEN-ME.html, which pins it implicitly).
• F5 — Cross-implementation identity (F2) is asserted in CI whenever two or more implementations coexist; a divergence is a release blocker (RFC-0009 §R4 discipline applied to packaging).

5. Relationship to other documents

• Wire format of the container: uddp-v1.md (normative).
• The capsule inside remains governed by capsule-v1.md / tsp-v1.md; this RFC adds no capsule fields.
• Platform-independent opening: RFC-0001 §G2; storage independence: RFC-0004 (a container is an ordinary stored object); verification: RFC-0007 (a receipt MAY reference the container hash alongside the capsule hash).

6. Security Considerations

Byte-identical formation (F2) is a tamper-evidence mechanism: any conforming implementation can regenerate a suspect container and diff it, so a modified container cannot hide among legitimate variation — there is none. The pinned opener template is the counterpart supply-chain control (RFC-0002 §T8): implementations substitute placeholders and never rebuild the template, so a single reviewed, hashed artifact — carrying its own KAT self-test — is what every user receives, and F3’s no-modification rule keeps generators from becoming silent template editors.

7. References

7.1. Normative

• [RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997.
• [RFC8174] Leiba, B., “Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words”, BCP 14, RFC 8174, May 2017.
• [UDDP-V1] “UDDP container — wire format”, ../spec/uddp-v1.md.
• [CAPSULE-V1] “Capsule v1 — wire format”, ../spec/capsule-v1.md.
• [TSP-V1] “Untilum Protocol (TSP) — Version 1”, ../spec/tsp-v1.md.

7.2. Informative

• RFC-0001, RFC-0004, RFC-0007, RFC-0009 — this series.

Editors’ Addresses

Untilum project — Editors of the TSP RFC series Email: hello@untilum.com · Issues: https://github.com/untilum/protocol/issues

Revision History

Date	Status	Change
2026-07-14	Draft	Initial version.
2026-07-17	Last Call	Publication pass: BCP 14 boilerplate, Abstract, Security Considerations, References, Revision History added; no normative changes. Entered Last Call per RFC-0008 §4.