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.

Your device holds the readable entry. The server holds a sealed box plus the dates and ids sync needs.Your devicesWOYM's serverTue, 4 Nov · 9:14 pmFinally said it out loudTold Priya about the new job.She was happier than I was.photoMood: Good#work · HomeReadable only heresealedon deviceid 8f3c21a0-…date 2026-11-04updated 21:14:07sealed 01|q9VfK1xR8mZt B4cHc7pLw2NsE0…file …/4b1e.e2eeGrey: what sync needs. Boxed: sealed.
What crosses to the server is already sealed; the grey lines are the metadata sync still needs.
Sealed on the deviceStill visible to the server
Entry text, mood, tags, place, weather, backgroundAccount id, row ids, entry dates, created and updated times
Photo, video, recording and handwritten page filesFile sizes, and which entry has files
File names and handwritten page textDeleted flags
The key that opens a shared entryWho 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 doneThat 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.

The recovery key unlocks a copy of the journal key. Entry keys and the MAC key are worked out from the journal key with HKDF; the account's private key is sealed with it.Recovery key24 characters you savesix groups of fourJournal key32 random bytesone per accountunlocksHKDF + entry idHKDFsealsEntry keysone per entry, never storedopen its text and filesMAC keyvouches for shareswoym-mac-v1Private keyX25519, kept sealedopens what others lockPublic keyon the serverSharing one entry hands overonly that entry's key.
The recovery key unlocks the journal key; everything below it is worked out from it or sealed with 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 sealedAADKey
An entry's text, mood, tags, place, weather, backgroundwoym:entry:<entryId>that entry's key
A file's name and a page's textwoym:media:<mediaId>the entry's key
A photo, video, recording, page or own background photo, as raw byteswoym:file:<mediaId>the entry's key
The key of a shared entrywoym:share:<entryId>sealed for the recipient
The account's private keywoym:private-keythe 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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.

1. The new device makes a one-time key pair and a secret, and posts the public key to the server. Its QR code carries the public key and the secret to your phone, never through the server. 2. Your phone seals the journal key for that public key, with the secret inside the box's label. 3. The new device opens it, and the server deletes the request.New devicewoym.app in a browserWOYM's serverkeeps a request for 10 minYour phonealready has the journal key1Asks to joinMakes a one-time key pairand a random secret, thenshows a QR code.Keeps the requestpublic key, device, placepub keyQR code: public key + secret2You scan itShows who's asking, thenseals the journal key forthat key, secret in the label.Holds the sealed boxIt can't open it.boxsealed box3Opens the journalPrivate key + secret openthe box. The request isdeleted from the server.
The dashed line is the QR code going from screen to camera, so the secret never reaches the server.
  1. The new device (say, woym.app in a browser) makes a one-time X25519 key pair and a random secret.
  2. It posts its public key, a device name and a place to the server, which keeps them for 10 minutes.
  3. 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.
  4. 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.
  5. 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.

1. Priya turns on encryption and the server keeps her public key. 2. Your phone tags the share, works out the entry's key, checks Priya's pinned key and locks the entry key for her. 3. The server stores the share and the locked key and can't open them. 4. Priya's private key opens the entry key, which opens the entry.Your phonehas your journal keyWOYM's servercarries everything, opens nothingPriya's phonehas her private key1Priya turns on encryptionHer phone makes a padlock andthe only key that opens it.Keeps Priya's padlockIt can lock things for her.It can never open them.padlockPriya's padlock2You tap Share• tags the share with your MAC key, so the server can't invent one• works out this entry's key• checks Priya's pinned key• locks the entry key for hershare + tag+ locked entry key3Stores the share02|q9VfK1xR8mZtB4…01|Hc7pLw2NsE0aYd…Locked boxes only. It can'tread the key or the entry.locked entry key+ locked entry4Priya reads itHer private key opens theentry key. The entry keyopens the entry.
Only your phone and Priya's phone ever hold the entry key unlocked; the server passes along boxes it can't open.

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:

  1. 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.
  2. Works out the entry key from the journal key and the entry id.
  3. 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.
  4. 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) | box

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

ChoiceWhat it buysWhat it costs
Entry keys derived from the entry id, not randomNothing extra to store or sync per entry; sharing exposes one entry onlyAn entry can't be re-keyed, so a share can't be fully revoked
Recovery key is 120 random bits, no passwordNo slow hash needed; can't be guessedYou must save 24 characters; lose it and every device, and the journal is gone
Keys in iCloud KeychainYour other Apple devices just openTrust in Apple's Keychain sync
Web keeps the key only until sign-outNothing left behind on a shared computerScan a code again after each sign-in (passkeys are a later idea)
Trust on first use for share keysNo key verification screen to explainThe server is trusted for the first key it shows for an email
Opt-in, and can't be turned off in the appNormal accounts pay no cost; no quiet downgradeOne more setting to explain
Whole files sealed in memorySimple, and the same on every platformThe web can't open sealed files over 150 MB yet
Get the app