Engineering Blog · November 5, 2026 · 12 min read
How I Built End-to-End Encryption into WOYM
The keys, how entries and photos are sealed, how a new device gets in, and how sharing one entry works without the server ever reading it.
WOYM now encrypts a journal on your own devices before it syncs, so our server stores only locked boxes and I can’t read a word of it. This post walks through how I built that: the keys, how entries and photos are sealed, how a new phone or a browser gets in, and how sharing one entry with a friend works without the server ever seeing it.
A journal is the most private thing most people write. Encryption at rest and HTTPS protect it from outsiders, but not from whoever runs the server: me, a leaked database backup, or a bug in a query. End-to-end encryption closes that gap. It is opt-in, part of Cloud Sync in Premium, and comes in version 1.10.0 of the iPhone, iPad and Mac app and on woym.app.
The same formats are written twice: in Dart for the app, using CryptoKit on Apple devices, and in TypeScript for the web, using WebCrypto plus @noble/curves for X25519. Both are tested against each other byte for byte.
What the server can and can’t see
The server sees that an entry exists and when it was written, but not what it says. I drew the line by asking what sync needs to work, and sealed everything else.
| Sealed on the device | Still visible to the server |
|---|---|
| Entry text, mood, tags, place, weather, background | Account id, row ids, entry dates, created and updated times |
| Photo, video, recording and handwritten page files | File sizes, and which entry has files |
| File names and handwritten page text | Deleted flags |
| The key that opens a shared entry | Who an entry is shared with (their email), read receipts |
| Habit and todo names, notes, how often, a todo's day, time and whether it's done | That some habit was ticked on a day, and how many times |
Habits and todos are sealed the same way, once your app is up to date. Their ticks stay readable, because each tick is stored by habit and day; without the habit’s name, a tick only says that some habit was ticked that day. A few things stay outside the boundary on purpose. The AI features (Polish Writing, dictation, handwriting scan) still send what they work on to be processed, and it is never stored. Reading a handwritten page into searchable text is switched off while encryption is on, so page images never go to the server for that.
The server is not trusted to read, but it is trusted to stay up. It could still refuse service, or hand back an older copy of a row. It cannot read content or forge it: every sealed box is tied to its row, so a swapped or edited box fails to open.
The keys
Everything hangs off one random 32-byte journal key per account, and it never leaves your devices unlocked. The other keys are either worked out from it or locked by it.
- Journal key. 32 random bytes, used with AES-256. One per account.
- Entry keys. Each entry’s key is worked out when needed and never stored. Sharing one entry hands over only that entry’s key, which opens nothing else.
- MAC key. Also derived from the journal key, with a different info string, so no entry id can ever produce it. It vouches for shares (more below).
- Account key pair (X25519). The public half sits on the server so others can lock things for you. The private half is sealed with the journal key before it is stored.
- Recovery key. 24 characters of Crockford base32 (120 random bits), shown as six groups of four. It locks a copy of the journal key that lives on the server, for the day you lose every device. The alphabet has no I, L, O or U, and case and dashes don’t matter when you type it.
entryKey = HKDF-SHA256(journalKey, salt = entryId, info = "woym-entry-v1")
macKey = HKDF-SHA256(journalKey, salt = purpose, info = "woym-mac-v1")The journal key is stored per account id, not per email. On iPhone, iPad and Mac it lives in iCloud Keychain, so your other Apple devices open the journal on their own. In the browser it lives in IndexedDB as non-extractable WebCrypto keys, so page scripts can’t read the raw bytes, and it is wiped at sign-out.
Sealing entries and files
Every private field is sealed with AES-256-GCM, and every box names the row it belongs to, so a box moved to another row fails to open. A sealed box is a version byte, a nonce, the ciphertext and GCM’s tag. The “additional data” (AAD) that GCM checks but doesn’t encrypt is a label tied to the row:
box = 01 | nonce (12 bytes) | ciphertext | tag (16 bytes)| What is sealed | AAD | Key |
|---|---|---|
| An entry's text, mood, tags, place, weather, background | woym:entry:<entryId> | that entry's key |
| A file's name and a page's text | woym:media:<mediaId> | the entry's key |
| A photo, video, recording, page or own background photo, as raw bytes | woym:file:<mediaId> | the entry's key |
| The key of a shared entry | woym:share:<entryId> | sealed for the recipient |
| The account's private key | woym:private-key | the journal key |
An entry’s private fields go into one sealed JSON blob in a sealed column, and the plain columns are emptied. A sealed file is uploaded to a path ending .e2ee.
The database refuses to go backwards. For an account with keys, triggers on entries and media raise encryption_required on a new readable row, on a sealed row being made readable, or on any change to a readable row’s private fields. A storage policy only accepts .e2ee uploads into that account’s folder. So an old app version, or a bug, can’t quietly write plaintext. Each device also remembers that the account is encrypted, and refuses to write readable data if the server later claims encryption is off.
Turning it on
Turning encryption on happens in the app, and the hard part isn’t making keys: it’s sealing a journal that is already on the server without losing an edit.
- The app checks the server first. If another device already turned it on, it stops, because the recovery key it just made would never work.
- It makes the journal key, the recovery key and the X25519 pair, then shows Save your recovery key. Nothing is turned on until you confirm you saved it.
- Before talking to the server, it writes a “reseal needed” flag and a local-only pending copy of the key. A lost reply or a closed app then can’t leave the server holding keys that no device has.
- It sends the server the public key, the sealed private key and the journal key locked by the recovery key. The same call empties Recently Deleted, since those rows would stay readable.
- The key moves to iCloud Keychain, and resealing starts.
Resealing is a loop. The server lists the ids still readable, up to 500 of each kind per call. The app marks those entries changed (moving their edit time forward by 1 ms, so they don’t beat newer edits from another device), seals them on the next push, re-uploads files to .e2ee paths, and asks again 5 seconds later. Settings shows Encrypting your journal with a progress bar and the count left, and you can keep writing meanwhile. Every unlocked device checks once per launch, so another device can finish the job if the first one is lost.
Opening the journal on a new device
A new device gets the journal key from a device you already hold, through the server, sealed so the server can’t open it.
- The new device (say, woym.app in a browser) makes a one-time X25519 key pair and a random secret.
- It posts its public key, a device name and a place to the server, which keeps them for 10 minutes.
- It shows a QR code holding the request id, the public key and the secret. The secret exists only in that code, never on the server.
- You scan it on your phone. The phone shows which device and place is asking, then seals the journal key for that public key, with the secret inside the AAD.
- The new device fetches the box, opens it with its private key and the secret, and the server row is deleted.
The secret is what stops a dishonest server. If the server swapped in its own public key, it still couldn’t make or open a box whose AAD includes a secret it never saw.
Each device linked this way shows under Linked browsers and devices on the Encryption screen, with when it was linked and last opened. Remove one and, the next time it opens WOYM, it deletes its copy of the key and signs out. That’s a request the device honours, not a lock: anything it already downloaded could still be read on it. Cutting a device off for good would take a new journal key and re-encrypting everything, which WOYM doesn’t do yet. iPhones, iPads and Macs get the key through iCloud Keychain, so they don’t show in that list.
No other device to hand? Type the recovery key. The device fetches the locked copy of the journal key and opens it. Lose the recovery key and every device, and nobody, me included, can open the journal. The app, the FAQ and the privacy policy all say so plainly.
Sharing one entry
To share an entry with Priya, my phone locks that one entry’s key with Priya’s public key; the server carries the locked key but can’t open it.
Why not just send Priya the locked entry? Because the entry is already sealed with its entry key, and her app needs that key to open it. Locking the entry key for her means the entry itself stays exactly as stored, edits keep syncing to her, and nothing else of mine is exposed.
When you tap Share, your device:
- Vouches for the share. It computes an HMAC-SHA256 over the share id, the entry id and Priya’s email with the MAC key, from its own local values, never ones echoed back by the server. The server can’t make this tag, so it can’t invent a share and trick your devices into handing out a key.
- Works out the entry key from the journal key and the entry id.
- Checks Priya’s public key against the one pinned for her email. The first key seen for an email is pinned (trust on first use), and a different key later is refused. The server is still trusted for whose key that first one is, and Settings says so.
- Seals the entry key for Priya with X25519: a fresh ephemeral key pair, its shared secret through HKDF into an AES key, AAD
woym:share:<entryId>.
tag = HMAC-SHA256(macKey, shareId | entryId | email)
sealed = 02 | ephemeral public key (32 bytes) | boxOn Priya’s side, her private key opens the entry key, her app keeps it locally, and it opens the entry and its files.
If Priya hasn’t turned encryption on yet, she has no public key, so the share waits. On every sync your devices look for waiting shares and seal the key once she has one, but only if the tag checks out, the entry is your own, and her key matches the pin.
Shares made before you turned encryption on are never trusted silently. A Keep sharing with these people? sheet lists them by person, and nothing is sent until you choose Keep sharing; Stop sharing removes them.
A Journal Only You Can Read
Turn on end-to-end encryption and WOYM syncs your journal as locked boxes. Start free today.
Stopping a share, honestly
Stopping a share cuts Priya off in practice, but it can’t take back a key she already received.
When you stop sharing, the server marks the share revoked and stops sending her the entry, its edits and its files. On her next sync, her app deletes its copy of the entry and its files.
The limit: the entry key never changes, because it is derived from the journal key and the entry’s id. A modified app that kept the key could still open later versions of that entry, if something handed her the locked rows: a misbehaving server or a leaked database. That key opens only that one entry, and whatever she already read she could have screenshotted anyway. Real revocation would mean giving the entry a new key, which my derived-key design can’t do without a new entry id. One more cleanup is on my list: her app should also delete the stored entry key when a share is removed, not just the entry.
Trade-offs, and what I chose not to do
Every choice here gave something up; these are the ones worth knowing.
| Choice | What it buys | What it costs |
|---|---|---|
| Entry keys derived from the entry id, not random | Nothing extra to store or sync per entry; sharing exposes one entry only | An entry can't be re-keyed, so a share can't be fully revoked |
| Recovery key is 120 random bits, no password | No slow hash needed; can't be guessed | You must save 24 characters; lose it and every device, and the journal is gone |
| Keys in iCloud Keychain | Your other Apple devices just open | Trust in Apple's Keychain sync |
| Web keeps the key only until sign-out | Nothing left behind on a shared computer | Scan a code again after each sign-in (passkeys are a later idea) |
| Trust on first use for share keys | No key verification screen to explain | The server is trusted for the first key it shows for an email |
| Opt-in, and can't be turned off in the app | Normal accounts pay no cost; no quiet downgrade | One more setting to explain |
| Whole files sealed in memory | Simple, and the same on every platform | The web can't open sealed files over 150 MB yet |