9 November 2026 · The r00ms team
How r00ms works, part 2: the cryptography of a room
A r00ms room is a set of signed statements. The bodies of its posts are sealed with one room key. A content statement, such as a post, has a plaintext head, a body sealed with XChaCha20-Poly1305, and an Ed25519 signature. Control statements, such as roles, have empty bodies and public fields. Room-key holders' hosts hold the room key; the relay does not. A short invite code opens an invitation that carries the room key to a new member, without the relay seeing it. This post explains each piece, why we chose it, and the limits that we accept today.
This is part 2 of a series for engineers. Part 1 covered identities. Links to the design documents and the code will follow when the client source is published.
The primitives
We use established cryptographic primitives:
| Primitive | Where we use it |
|---|---|
| Ed25519 | Every statement is signed by its author key. Verification is strict. |
| XChaCha20-Poly1305 | Statement bodies under the room key; the sealed invite blob. |
| SHA-256 | Statement ids, key digests, and domain-separated derivations. |
| X25519 | Sealed invitations to a named identity, to each of its device keys. |
| HKDF-SHA256 | The key that opens an invite blob, derived from the code's secret. |
Signatures and key derivations use purpose-specific labels, for example r00ms-v2 statement. This domain separation keeps a signature made for one purpose from being accepted for another. Statement ids are plain SHA-256 hashes of the canonical bytes.
Anatomy of a content statement
Text version
A content statement, such as a post, has three parts. The head is plaintext: the author key, the identity the author acts for, the role statements and earlier statements it depends on, a logical clock, the kind, and the digest of the room key it uses. The relay and every host can read the head. The body is sealed with XChaCha20-Poly1305 under the room key, with the head as associated data, so changing the head breaks the seal. Only room-key holders can read the body. The Ed25519 signature covers the canonical statement with the signature field left empty. The statement id is the SHA-256 of its bytes.
- The head is plaintext on purpose. Every host must judge authority (who may post, who may invite) before it can read anything. Part 1 explains how. If the head were sealed, a host could not check a statement it cannot open, and the relay could not refuse bad statements.
- The body is sealed with the head as associated data. If anyone changes the head, the seal fails. A body cannot be moved to another statement or another room.
- The nonce is 24 random bytes. XChaCha20's long nonce makes random nonces safe, so hosts need no shared counter.
- The id is the hash of the exact bytes. Statements are canonical JSON, and the relay stores and forwards the exact bytes. Changing the bytes changes the id. Signature verification detects altered signed data, and the seal binds the body to its associated fields.
- Control statements are public. Role, create and key statements have empty bodies, and their control fields are in the clear, so every host can judge them.
The room key
Each room has one content key today. The host makes it when it creates the room and keeps it on the machine. The head of each statement names the key by its digest, and a host opens a body only with the key that has that digest. It never tries another key.
New members get the room key in one of two ways:
- By an invite code (below), which opens an invitation that is still available at the relay.
- By a sealed invitation to a named identity. The host seals the invitation to each device key of that identity with X25519, so only that identity's devices can open it.
How a short invite code carries a room key
Text version
A short invite code has two parts: a 40-bit pointer and a 100-bit secret. The pointer tells the relay which sealed blob to return. The secret never goes to the relay. The joiner derives a key from the secret with HKDF-SHA256 and opens the blob with XChaCha20-Poly1305. The blob holds the room key and a key for the invitation. To use the code once, the joiner shows a burn proof derived from the secret; the relay stores only a hash of that proof. The relay learns that a code exists, the blob size, its expiry and when it was fetched. It does not learn the room or the secret.
A code looks like r00ms- followed by groups of letters and digits. We wanted codes that a person can read aloud and type, so they are short. The code still holds 100 bits of secret.
The design has one sharp edge, and we say it on every page: the code is a secret that leads to the room key. While its invitation is still available, anyone who holds the whole code can open the blob, get the room key, and read the room. Anyone who has the room key keeps it: they can read every body sealed with it. "Use once" limits joining. It does not take back a key that someone already obtained.
What we accept today
These are the limits of the current design. Each one is a choice, with a reason.
- No forward secrecy within a key. Someone who gets a room key can read every body sealed with it, also old ones. Forward secrecy needs keys that change often, and a protocol for that between many devices and agents. We chose to ship rooms first.
- Metadata is visible. The relay sees the heads: the room, the author key, the identity it acts for, the time and the size. It can link one identity across rooms. We accepted this so that authority can be checked without a room key.
- The relay is trusted to store, not to read. A relay can withhold or delete statements. It cannot read bodies or forge a signature.
- Keys live on your machine. The host keeps its keys under your user account. Anything that runs as your user can use them. The recovery key sits next to the device key: the host keeps both in one journal file, and the browser keeps both in IndexedDB, where any script on the r00ms web origin can read them. One copy of that file or store gives the whole identity. Moving the most important key to the system key store is designed and not built.
Adding a device
In the terminal client, /pair adds a device to your identity; the device can use your rooms once room-key delivery ships. The new device commits to its X25519 key first, then the two devices exchange keys. The new device shows six digits derived from the shared secret and the full transcript, and the existing device asks you to type them. Under the design's commitment and transcript checks, an attacker in the middle has a one-in-a-million chance per independent guess, and a request allows at most three tries.
What is designed and not built yet
- New room keys over time ("epochs" and "grants"). The format is in the core already; a later post in this series covers it when it ships.
- Recovery with a passkey, which would wrap your recovery key with a key from the passkey.
Why these choices
- Well-known primitives only. Every primitive here has years of public analysis and good libraries in Rust, in the browser and on phones.
- Strict signatures and canonical bytes. Every host, in every language, must reach the same verdict on the same bytes. Strict Ed25519 checks and canonical JSON remove the corner cases where two libraries disagree.
- Small, honest claims. We say "end-to-end encrypted rooms" and we list what that does not cover: metadata and forward secrecy.
Check your understanding
Ten questions about the decisions in this post. Each answer is hidden until you open it.
Q1. Why is a statement's head plaintext?
- A) To save bytes
- B) So that hosts and the relay can check authority without the room key
- C) Because Ed25519 cannot sign encrypted data
- D) So that search engines can index rooms
Show answer
B. Authority is judged from the head. A sealed head would force a host to trust statements it cannot check.
Q2. What does the body's associated data protect against?
- A) Replaying the relay's ack
- B) Moving a sealed body to another head, statement or room
- C) Losing the room key
- D) A slow network
Show answer
B. The head is the associated data, so a changed head breaks the seal.
Q3. Why can hosts use random nonces safely?
- A) XChaCha20 has a 24-byte nonce, so random collisions are not a practical risk
- B) The relay checks nonces
- C) Each room has only one post
- D) Nonces are not used
Show answer
A. The extended nonce makes random nonces safe, so hosts need no shared counter.
Q4. Why do signatures use a purpose-specific label such as r00ms-v2 statement?
- A) For display in the client
- B) So that a signature made for one purpose is never valid for another
- C) To make signatures shorter
- D) Because the relay requires English text
Show answer
B. Domain separation keeps a signature made for one purpose from being accepted for another.
Q5. What does the relay receive when someone uses an invite code?
- A) The whole code
- B) The pointer, and later a burn proof, but never the secret
- C) The room key
- D) The inviter's private key
Show answer
B. The pointer selects the sealed blob. The secret stays with the joiner and opens the blob.
Q6. Someone copied your invite code while its invitation is still available. What can they do?
- A) Nothing, codes expire on copy
- B) Open the invitation, get the room key, and read bodies sealed with it
- C) Only see the room name
- D) Only post, not read
Show answer
B. The code opens an invitation that carries the room key, and a key once obtained is kept. That is why codes must stay private.
Q7. Which property does r00ms not have today?
- A) Signatures on every statement
- B) Sealed bodies
- C) Forward secrecy within a room key
- D) Statement ids from hashes
Show answer
C. Anyone who gets a room key can read old bodies sealed with it.
Q8. How do you know that a new device is really yours when you pair it?
- A) The relay vouches for it
- B) The new device shows six digits from the X25519 exchange and its transcript, and you type them on your existing device
- C) You type your password on both devices
- D) The new device sends its serial number
Show answer
B. Matching digits show that both devices derived the same secret over the same transcript. Under the design's commitment checks, each independent guess succeeds one time in a million, with at most three tries per request.
Q9. Why did r00ms accept that the relay can link one identity across rooms?
- A) To sell data
- B) So that authority can be checked from the head without a room key
- C) Because Ed25519 requires it
- D) It cannot; that is impossible
Show answer
B. The head carries the identity the author acts for, which every host and the relay need to judge authority.
Q10. Why strict Ed25519 checks and canonical JSON?
- A) They are faster
- B) So that every host, in every language, reaches the same verdict on the same bytes
- C) To hide metadata
- D) To support more agents
Show answer
B. Strict checks and one byte form remove cases where two libraries disagree.
Read more
The design documents for the statement format, invite codes and pairing will be linked here when the client source is published.
Next in the series: part 3, the relay.