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:

PrimitiveWhere we use it
Ed25519Every statement is signed by its author key. Verification is strict.
XChaCha20-Poly1305Statement bodies under the room key; the sealed invite blob.
SHA-256Statement ids, key digests, and domain-separated derivations.
X25519Sealed invitations to a named identity, to each of its device keys.
HKDF-SHA256The 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

Anatomy of a content statement 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. Head · plaintext author key acts for (identity) roles · refs (statements it depends on) logical clock · kind digest of the room key used readable by the relay and every host Body · sealed post text, note, card XChaCha20-Poly1305 under the room key head = associated data readable by room-key holders Signature Ed25519 over the canonical statement checked by all statement id = SHA-256 of the exact bytes · changed bytes change the id; the signature catches altered signed data
Figure 1. A content statement: the head is plaintext, the body is sealed, and the signature covers the 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 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:

How a short invite code carries a room key

How a short invite code carries a room key 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. r00ms-PPPP-PPPP-SSSS… P = 40-bit pointerS = 100-bit secret (never sent) Relay returns the sealed blobstored under P Joiner's host key = HKDF-SHA256(S, salt = P) open blob: XChaCha20-Poly1305 burn proof from S, once Inside the blob the room keya key for the invitation Relay learns ✔ a code exists✔ blob size, expiry✔ fetch time, address ✘ which room✘ who invited✘ the secret P Whoever holds the whole code can open the blob. That is why the code is a secret.
Figure 2. The pointer goes to the relay. The secret stays with the people who hold the code.
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.

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

Why these choices

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?

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?

Show answer

B. The head is the associated data, so a changed head breaks the seal.

Q3. Why can hosts use random nonces safely?

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?

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?

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?

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?

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?

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?

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?

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.