Protecting sensitive documents

Some documents - notes, in plain terms: a page or a journal entry - hold things you don't want anyone reading over your shoulder, or finding if your laptop is stolen: a router password, a recovery phrase, a letter from your doctor. Protection is for those.

A protected document is scrambled on disk. Only you can unscramble it, and only after you type your passphrase. Its name stays visible so you can still find it and link to it - only the contents are hidden.

Why this isn't the same as sync encryption

If you use a synced graph, everything is already encrypted before it leaves your device, and the sync service can never read it. That's true, and it stays true.

But it protects your documents from the service, not from your own machine. Once you've opened a synced graph, your browser keeps a working copy of your documents on your device so it can be fast and work offline. Anyone sitting at your unlocked laptop can read it.

Protection is the layer that fixes that. It also works for local graphs, where the files in your folder are ordinary readable markdown - a protected document is the one thing in that folder that isn't.

Setting it up

The first time you protect anything, you choose a protection passphrase for that graph.

Choose it carefully, because:

There is no way to recover it. Not by us, not by your recovery code, not by anything. If you forget it, the contents of every protected document in that graph are gone for good.
It should be long. A memorable sentence beats a short complicated word. Someone who gets hold of your exported folder can try guesses against it offline, as fast as their computer allows.

One passphrase covers the whole graph. Unlocking one protected document unlocks them all until it locks again.

Once protection is on, open Settings → Protected Documents and use Bind a passkey to this device. Do it on your phone or second computer too.

A bound device unlocks with your fingerprint, face or device PIN instead of the passphrase. And - importantly - if you ever forget the passphrase, a device that's already bound can still get in and let you set a new one. It's the closest thing to a backup that exists here, so it's worth the two minutes.

A binding is per device and per browser: it lives only on the device that made it and is never synced or exported, so a passkey bound in Chrome on your laptop does nothing for Safari on the same laptop, or for your phone - even when the passkey itself has synced there through your Apple or Google account. Bind each browser you use, from its own Settings.

If your browser doesn't support passkeys, the settings pane will say so, and unlocking there will always use the passphrase.

Protecting a document

Right-click the document in the sidebar and choose Protect…. That's it - the contents are scrambled straight away. The first time you do this in a graph, you'll be asked to set the passphrase.

A page has to exist before it can be protected. A page you've opened from Quick Find or a link but not typed into yet isn't a document until the first keystroke, so Protect… on it tells you so and asks you to add the content first. Type what you want kept private, then protect it.

To go back, right-click and choose Remove protection…. You'll need to be unlocked to do it.

Whole documents only

Protection is for a whole document. If one line on a page you share needs hiding, put it on its own protected page and link to it - that keeps the shared page shared and the secret secret. (Protecting part of a page was tried and taken out: a bullet's nested lines weren't covered, and moving lines in and out of a protected part is exactly where secrets leak.)

Spotting a protected document that's open

Protected documents carry a padlock on their tab: closed when locked, open when unlocked and readable. Handy for answering "have I left anything open?" at a glance. It's just a marker - clicking the tab switches to the document as usual.

The same padlock, always closed, marks protected documents in Search's Names results, in Quick Find, and in the sidebar's Favourites - so you can tell which ones are protected before you open them. It doesn't show locked or unlocked there; the tab does that. Protected documents never appear in Recents at all: it's a trail of what you've been reading, and that's not something a glance at the drawer should give away. Favourites are yours to pin, so they stay.

Locking and unlocking

Two different things happen, and it's worth knowing which is which.

Hidden. The moment you switch to another window, or click into another document, the contents disappear from the screen and a locked card takes their place. This is instant, so nothing shows in your phone's app switcher and nothing flashes up when you come back. Coming back within a minute - to the window, or to the protected document - just shows it again, no passphrase.

Locked. After a few minutes of no activity, or a minute after you've switched away, EtherPK throws the key out of memory entirely. Now there's no readable copy anywhere on the machine, and you'll need your passphrase (or your fingerprint, on a device you've set up) to get back in.

On a phone, the app is often paused entirely while it's in the background, and a paused app can't run its timer. That doesn't buy you extra time: the deadline is a fixed moment on the clock, and the first thing EtherPK does when you return is check it. If the minute has passed, it locks before anything is drawn - the only difference is that the key sat in memory, hidden, until you came back. If even that bothers you, set the hidden timing to Immediately.

You can lock immediately from the Protected documents button in the left drawer, just under the calendar - its padlock shows whether you're locked or unlocked, and clicking it does the other thing. The same is in the command menu as Lock protected documents (type / and then lock). Useful when you're getting up from your desk.

While you're unlocked, a padlock button also floats at the bottom right of every page you open - not just the protected ones (on a phone, just above the command buttons). Unlocking is graph-wide, so the reminder follows you to whatever you read next. It's there as a nudge: when you've finished, tap it and every protected document on this device locks, exactly as the drawer control does.

To unlock, use the same control, a locked document's Unlock button, or right-click a locked document's tab (long-press it on a phone) and choose Unlock…. All of them open the same Enter protected documents passphrase dialog - type the passphrase (or use your passkey) and press Enter passphrase.

One passphrase, one key, one state: unlocking anywhere unlocks every protected document on this device, and locking anywhere locks them all.

Locking yourself closes the tabs

When you lock - from the drawer button, a document's padlock or the command - EtherPK also closes every protected document you had open, pinned tabs included. A locked document's name is still visible on its tab, and if you've just locked because you're walking away, a row of padlocked tabs called things like "Passwords" says more than you'd like. Unprotected documents stay where they were, and so does anything else that was open.

The timeouts never do this. A timer running out while you're in the middle of something must not take your tabs away, so only a deliberate lock closes anything. If you'd rather your protected tabs stayed put either way, turn off Close protected documents when I lock now in Settings → Protected Documents.

Both timings and that switch live in Settings → Protected Documents, and they're set per device. That's deliberate: a desktop in a locked room and a laptop on a train deserve different answers. Set the first timing to Immediately if you want it to lock the moment you look away, or the second to Never on a machine you consider physically safe. They save as you change them - there's no Save button on that tab.

You can also bind a passkey and change your passphrase there. You'll type the new one twice.

What changing the passphrase does - and doesn't do

Your passphrase never scrambles a document directly. When you first protect something, EtherPK makes a random protection key, and it's that key which scrambles every protected document. The passphrase only locks the key itself. What the graph stores is the key, scrambled under your passphrase - never the key in the clear.

So changing the passphrase unlocks the key with the old passphrase and locks it again under the new one. The key is the same, so nothing is re-encrypted, every protected document stays readable, and a passkey you've bound keeps working. It's quick, however many documents you've protected.

A document's scrambled contents are only ever rewritten when you edit it while it's unlocked. Locking and unlocking a document you haven't touched leaves its stored contents exactly as they were.

The flip side: because the key doesn't change, changing the passphrase protects you going forward, not backward. If someone already has a copy of the graph and your old passphrase, that copy still opens with it. Treat a new passphrase as a fresh start, not as a way to revoke a copy that's already out of your hands.

Closing the tab locks outright, and pressing undo on a locked document brings nothing back: the contents you were looking at are gone from the page along with the key.

Nothing is lost when it locks

Whatever you'd typed is saved before the key is discarded. Locking never loses your work.

Images and files you attach

Protection covers the document's text and nothing else. A picture or file you drop into a protected document is stored by the graph, not inside the scrambled block:

On a local graph it's an ordinary file in the graph folder, readable by anyone with the folder.
On a synced graph it's encrypted for the graph like every other asset, so any member of the graph can open it - your protection passphrase doesn't come into it.

Either way, a link to that file from any other document shows it. The locked card says this so you don't have to remember it. Keep anything that must stay secret in the text.

While a protected document is locked you can put the cursor in its frontmatter and nowhere else - the locked contents aren't something you can type into.

What you give up

These features are by design:

Protected documents can't be found by search. Not by name-matching the contents, not at all, even while you're unlocked. If search could reach inside them, the search index would end up holding a readable copy on disk - which is the thing protection exists to prevent. You can still find the document by its name.
Backlinks and tasks inside them don't count. Same reason. A task written in a protected document won't appear in your task list.
Nobody can edit them with you. Working on a document together needs readable text, and only you can read this.
Journal entries can't be protected. Pages can. A day's entry is found by its date, so keep anything sensitive on a page and link to it from the day.

In a shared graph, your protection passphrase is yours alone. Other members never get it.

What they can see:

That the document exists, and what it's called.
Roughly when you last edited it.
They can delete it, even though they can't read it - the same as any other document in a graph you've shared.

If you open a document another member has protected, EtherPK will tell you so rather than asking for a passphrase. No passphrase of yours will ever open it.

Editing while unlocked

Once unlocked, protected content edits exactly like any other - bullets, wikilinks, tasks, / commands, all of it. There is no separate mode to enter and nothing to copy in and out.

One difference worth knowing: a protected document saves less often than an ordinary one (it waits for about 20 seconds of quiet, and at most a minute), and there's no crash recovery for it. If your browser dies mid-sentence you could lose up to a minute of typing. That's the price of EtherPK never writing a readable copy to disk.

The document's frontmatter - the title: block at the top - is not protected, and so it stays on screen whether the document is locked or unlocked, above the card or above the text. You can edit it there in either state, exactly as on any other document: change the title and you'll be asked to confirm the rename when you leave the block, change the aliases and they just apply (Titles Aliases And Frontmatter). None of it needs the passphrase. The one thing you can't do is delete the block from a protected document - without it the title line would be sealed in with the secret at the next save.

A protected document also never merges with another one. Renaming a page onto a name that's already taken normally joins the two, but joining a protected page with a readable one would leave the scrambled text sitting beside ordinary text, and at that point it isn't protected any more. So EtherPK refuses: you can't rename a protected document onto a name another page holds, and you can't rename another page - by the dialog or by typing in its frontmatter - onto a protected document's name. Pick a different name instead.

A synced document has no block until you type one. If you type one at the very top of a protected document while it's unlocked, it is frontmatter - readable, and shown above the card when the document locks - so don't put anything secret between those two --- lines.

Where the scrambled document actually lives

If you're curious, or you want to check: open a protected document's file in a text editor. You'll see something like this, and nothing else:

---
title: Router
---
```etherpk-cipher
AQQAAAGZaLmAAJmR3RhbXBsZS1jaXBoZXJ0ZXh0LWdvZXMtaGVyZQ
```

The title stays readable so links to the page keep working. Everything below it is the scrambled contents. That same block is what gets backed up, exported, mirrored to a folder and sent to the sync service - so it's protected everywhere, not just in the app.

If the key record is damaged

The wrapped key for a local graph lives in one small file, etherpk/protection.json, in the graph folder. If that file has been mangled - a merge left conflict markers in it, a copy was cut short, a disk filled up - EtherPK refuses to touch it and tells you:

etherpk/protection.json is damaged; restore it from a backup. Put the file back from a backup or from the other side of the merge. It's the only portable copy of the key, so EtherPK will never write a new one over it; Protect stays refused until the original is back.
etherpk/protection.json was written by a newer version of EtherPK; update EtherPK to use it. Another device on a newer build wrote it. Update this one and it'll read fine.

Neither message means anything has been lost. The scrambled documents are untouched, and a passkey you bound on this device still opens them once the record is readable again.