Papyr Write together in Markdown. The server can't read it. Try it GitHub

How Papyr works

The design, for anyone who wants to understand it before reading the code. The exact rules are in spec/; each section links to its part.

Papyr is a relay: the clients merge, the server only relays

Collaborative editors must resolve conflicts when two people type at once. Etherpad and Google Docs do it on the server, so the server reads every edit.

Papyr moves that job to the clients. Each browser holds the whole document as a Yjs CRDT, a data structure where edits apply in any order and every copy ends up the same. The server never has to understand an edit, only deliver it. That makes end-to-end encryption possible, and it makes the server cheap: no merging, no document model, no rendering.

 browser A                         Papyr server                         browser B
 ─────────                         ─────────────                        ─────────
 edit ─▶ Yjs update ─▶ encrypt ─▶  number it (seq 42)       ─▶ forward ─▶ decrypt ─▶ Yjs merges
                                   append to the room's log
                       ◀─ "accepted 42"
                       ◀─ "durable up to 42"   (after the next flush to disk)

Rooms and keys

A room is a 32-byte secret. The browser derives two keys from it with HKDF-SHA-256:

  • the content key, which encrypts every message with AES-256-GCM and never leaves the browser;
  • the access key, which the browser sends when it connects. The server hashes it to get the room id it stores the room under.

The server cannot go from the access key to the content key, so it admits people to a room it cannot read. The secret lives in the URL fragment (/r#s.<secret>), which browsers never send, so it is in no request, access log or referrer.

An open room (/r#notes) uses the hash of its name as the secret, so anyone who can guess the name can derive the keys. privacy.md says what that means; relay-protocol.md, “Rooms and keys”, has the derivations.

Can a room be guessed?

  • Sealed room (/r#s.<secret>): no. The secret is 32 random bytes from the browser’s secure random source, 2^256 possibilities; nothing can be tried, by anyone, the operator included.
  • Open room (/r#notes): yes, by design. The key is the hash of the name, so whoever knows or guesses the name is a member. A generated name (quiet-amber-otter-k7q2) is one of about 2^41: joining them all from one address takes centuries and the server limits connections and new rooms per address, but the operator can hash names and compare them with the room ids on disk, which takes hours on one graphics card. A short name falls at once.
  • Password room (/r#p.<salt>): the link holds a random salt, not the secret. See below.

Is the password stored?

No. The browser derives the room’s secret from the link’s 32-byte salt and the password with PBKDF2-HMAC-SHA-256 at 600,000 rounds. Neither password nor salt is sent to the server, and the browser’s recent rooms keep the link only. Without the link nobody can test a guess; with it, a guess costs 600,000 rounds on the guesser’s own computer, about ten thousand a second on a graphics card. What that means for choosing a password: privacy.md. The derivation: relay-protocol.md, “Sealed rooms and open rooms”.

What the server keeps

Per room: its id, the encrypted snapshot and the encrypted updates after it, the size on disk and the time of the last write. It counts IP addresses in memory for its limits and writes none; its log holds at most the first 8 characters of a room id. Each stored update carries a per-page-load number (the nonce’s sender), which groups updates and shows roughly how active a page was. Nothing rotates a room’s key and a member cannot be removed: to cut someone off, start a new room. The server cannot read, change or forge a message, but it can drop or delay messages and serve a joining client an older stored state.

A connection

  1. The page opens a WebSocket to /relay (the same path for every room) and sends a hello with the access key.
  2. The server answers with the room’s stored state: the latest snapshot and the updates after it, then a marker that the join is complete.
  3. The page then sends updates (edits: stored and numbered) and ephemeral messages (presence: name, colour, caret; relayed, never stored). The server forwards both to everyone else in the room.
  4. For each update the sender gets accepted (stored, with its sequence number) and later durable (flushed to disk, every 5 seconds by default). Until then the page keeps the update and sends it again after a reconnect, so a crash of the server loses nothing a page still holds.

The wire format is in relay-protocol.md, with test vectors in protocol-vectors.json. A client written from those two alone must work, and one was: tests/web/independent/.

Snapshots keep rooms small

When a room’s stored updates pass half of a limit, the server asks the clients for a snapshot: one of them encrypts the whole document and sends it, and the server drops the updates it covers. Joining is then one snapshot plus a few recent updates, whatever the room’s age.

Storage

Each room is two files in the data directory (room-files.md): an update log, appended before anything is sent on, so an accepted update is never lost to a crash of the process, and a snapshot file, replaced atomically. Both carry the room’s epoch, a random number naming one stored life of the room, so a client notices when a room was reset (restored, expired, removed) and sends what it has again. A torn end after a crash is dropped on load; anything damaged stops the room instead of guessing. There is no database; a backup is a tar of the files.

Images

An image is a separate encrypted file, not part of the document. The browser seals the picture under a key derived from the room’s secret, uploads the ciphertext after the room is stored, and writes a reference, ![alt](papyr:<id>), into the text. The id is a hash of the encrypted bytes. A browser that shows the reference fetches the file by that id, checks its hash, opens it and shows it from a local blob: address. The server keeps the files in blobs/, beside the rooms’ files; its routes exist only when the operator has turned images on (self-hosting.md, “Images”). What the server can see of them is in privacy.md; the wire format is in relay-protocol.md, “Blobs”.

Inside the server

.NET 11 on ASP.NET Core and Kestrel, compiled ahead of time to one native binary.

  • One writer per room, no thread per room. Operations queue on the room, and whichever thread posts first drains the queue. Each connection has at most one operation outstanding, which bounds the queue (relay-server.md, “Rooms”).
  • Feeds and cursors. A room writes outgoing messages once, into feeds of 16 KiB blocks; every connection reads them through its own cursor. A slow reader falls behind in the feed instead of costing memory per message, and is closed when it falls too far.
  • Snapshots stream from disk. A loaded room keeps no snapshot in memory, so memory does not grow with document size.
  • Limits everywhere. Message and room sizes, connections, loaded and stored rooms, and per source address the connections, rooms and new rooms an hour. Each is a setting (configuration.md).
  • Rooms load on demand and unload when the last connection leaves.
Project What it is
src/Papyr The relay’s core: rooms, feeds, limits, room files. No ASP.NET.
src/Papyr.AspNetCore The WebSocket endpoint and the admin API, behind three extension methods (hosting.md).
src/Papyr.Server The app: settings, TLS, the pages and static files.

The web client

Plain JavaScript modules, no build step, no framework; Yjs and a CodeMirror 6 bundle are vendored. The protocol code (js/relay/) touches no DOM, so another editor could reuse it. Encryption is WebCrypto, which browsers offer only on HTTPS and localhost: that is why every room needs HTTPS.

Undo covers your own edits only. Authorship colours and up to 20 saved versions live inside the room’s document, encrypted with the text (web-clients.md).

What it is built on

Few parts, each pinned to an exact version and checked into the repository, so everything a server delivers can be rebuilt from it:

Part Depends on
The server .NET 11 and nothing else at run time but Microsoft.AspNetCore.OpenApi, which describes the admin API. No database, no cache, no other service.
The pages Yjs (with lib0, the one package it uses), which merges the edits, and a bundle of CodeMirror 6 (its editor packages, the Lezer parsers, y-codemirror.next). Both are vendored: the server delivers them itself, no CDN. The Markdown preview, the QR code and the rest are Papyr’s own; the encryption is the browser’s WebCrypto.
PlantUML diagrams Optional and off by default: the engine comes from cdn.jsdelivr.net at a pinned version, checked by hash (configuration.md, Papyr:Web:PlantUml).
The command line ycs, a C# port of Yjs, and .NET. One binary, no runtime to install.

Node.js and npm build the vendored bundles and minify the scripts when the server is published; nothing of them runs in the server or the page.

How it is checked

  • 100 % line and branch coverage of src/, and a mutation score (Stryker) of at least 90 %.
  • Every analyzer rule on, warnings are errors, no trim or AOT warning.
  • No reflection, no runtime code generation, no unsafe code; JSON and logging use source generators.
  • The JavaScript has Node unit tests, browser tests in headless Chromium, a fuzzer and an independent client.
  • Every change to the relay is measured (performance.md).

AGENTS.md has the rules the code is written by.