---
title: "How r00ms works, part 2: the cryptography of a room"
description: "Which primitives r00ms uses and why: Ed25519 statements, XChaCha20-Poly1305 bodies, invite codes that carry a room key, and the limits we accept today."
slug: /blog/crypto
date: 2026-11-09
author: The r00ms team
status: published
sources_read: 2026-11-06, r00kery-node at 054bedb
---

# 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

![Anatomy of a content statement](/blog/crypto/statement.svg)

*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 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

![How a short invite code carries a room key](/blog/crypto/invite-code.svg)

*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.

- **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

> **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

> **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

> **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

> **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

> **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

> **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

> **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

> **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

> **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

> **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.
