EtherPK User Docs

Protected Documents

Some documents hold things nobody should read over your shoulder, or find if your laptop is stolen: a router password, a recovery phrase, a letter from your doctor. Protection is for those.

A protected document is encrypted wherever it rests: in a local graph's folder, in a Local Mirror, in the browser's cache and on the Sync Server. Only you can read it, and only after you enter your passphrase or use a passkey. Its name stays visible so you can still find it and link to it; only the contents are hidden.

How this differs from sync encryption

In a synced graph everything is encrypted before it leaves your device, and the Sync Server can never read it. That protects your documents from the server, not from your own machine. When you have opened a synced graph, the browser keeps a working copy of your documents on the device so it can be fast and work offline, and anyone at your unlocked laptop can read that copy. Nor does sync encryption hide anything from the other members of a shared graph, who hold the same key.

Protection covers both gaps. It also works for local graphs, where the files in the folder are readable markdown; a protected document is the one thing in that folder that is not.

Set it up

The first time you protect anything in a graph, you choose a protection passphrase for that graph. Choose it carefully:

  • There is no way to recover it: not through EtherPK, not through your Recovery Code, not through 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 graph 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 they lock again.

Settings > Protected Documents is the feature's front door: on a graph with no passphrase yet it explains protection and offers to set it up.

Bind a passkey

Bind a passkey on every device you use. After protection is on, open Settings > Protected Documents and select Bind a passkey to this device; do it on your phone and second computer too.

A bound device unlocks with your fingerprint, face or device PIN instead of the passphrase. If you ever forget the passphrase, a device that is already bound can still get in and let you set a new one. It is the closest thing to a backup that exists here.

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 the browser does not support passkeys, the settings tab says so, and unlocking there always uses the passphrase.

Protect a document

Right-click the document's tab (long-press on a phone) and choose Protect…. The contents are encrypted straight away. The first time in a graph, you are asked to set the passphrase.

A page has to exist before it can be protected. A page you have opened from Quick Find or a link but not typed into yet is not a document until the first keystroke, so Protect… on it asks you to add the content first.

A protected document is never published. If the page is public, or a publication uses it as a snippet, EtherPK says so and asks whether to withdraw it: confirming removes its publishing keys and then protects it, so the next publish leaves it out; cancelling leaves the page as it was.

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

Whole documents only

Protection covers a whole document. If one line on a page you share needs hiding, put it on its own protected page and link to it. Protecting part of a page would leave a bullet's nested lines uncovered, and moving lines in and out of a protected part is exactly where secrets leak, so EtherPK does not offer it.

Only pages can be protected. A journal entry is found by its date, so keep anything sensitive on a page and link to it from the day.

Spotting a protected document

A protected document carries a padlock on its tab: closed when locked, open when unlocked and readable, so "have I left anything open?" is answered at a glance. Clicking the tab switches to the document as usual. The same spot shows a globe for a page a publication uses as a snippet; a page is never both.

The same padlock, always closed, marks protected documents in Search's name results, in Quick Find and in the sidebar's Favourites. Protected documents never appear in Recents: that is a trail of what you have been reading, and not something a glance at the drawer should give away.

Locking and unlocking

Two things happen, on two different clocks.

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 when you come back. Coming back within the grace period shows the document again with no passphrase.

Locked. After a period of no activity, or once the grace period after switching away has passed, EtherPK throws the key out of memory. There is then no readable copy anywhere on the machine, and you need the passphrase (or a passkey on a bound device) to get back in.

On a phone the app is often paused entirely in the background, and a paused app cannot run its timer. That does not buy 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 time has passed, it locks before anything is drawn. If even a hidden key in memory bothers you, set the hidden timing to Immediately.

Both timings live in Settings > Protected Documents and are set per device, because a desktop in a locked room and a laptop on a train deserve different answers. Set the first to Immediately 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.

Lock now

To lock at once, use any of:

  • the Protected documents control in the left sidebar, under the calendar. Its padlock shows whether you are locked or unlocked, and selecting it does the other thing;
  • the padlock that floats at the bottom right of every page while you are unlocked (above the command bar on a phone). Unlocking is graph-wide, so the reminder follows you to whatever you read next;
  • Lock protected documents in the command menu: type / and then lock.

To unlock, use the same control, a locked document's Unlock button, or right-click a locked document's tab (long-press 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 select Enter passphrase.

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

A deliberate lock closes the tabs

When you lock yourself, from the sidebar control, the floating 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 have locked because you are walking away, a row of padlocked tabs called things like "Passwords" says more than you would like. Unprotected documents stay where they were.

The timeouts never do this. A timer running out while you are in the middle of something must not take your tabs away, so only a deliberate lock closes anything. To keep protected tabs open either way, turn off Close protected documents when I lock now in Settings > Protected Documents.

Closing a tab locks outright, and undo on a locked document brings nothing back: the contents are gone from the page along with the key. Whatever you had typed is saved before the key is discarded, so locking never loses work.

Change the passphrase

Your passphrase never encrypts a document directly. When you first protect something, EtherPK makes a random protection key, and that key encrypts every protected document. The passphrase only locks the key. What the graph stores is the key, wrapped under your passphrase, never the key in the clear.

Changing the passphrase, from Settings > Protected Documents (you type the new one twice), unwraps the key with the old passphrase and wraps 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 have bound keeps working. It is quick however many documents you have protected.

Because the key does not change, a new passphrase protects you from now on, not retrospectively. 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 is already out of your hands.

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 encrypted block:

  • On a local graph it is an ordinary file in the graph folder, readable by anyone with the folder.
  • On a synced graph it is encrypted for the graph like every other asset, so any member of the graph can open it; the protection passphrase does not come into it.

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

What you give up

These limits are by design:

  • Protected documents cannot be found by search, not even while unlocked. If search could reach inside them, the search index would hold a readable copy on disk, which is the thing protection exists to prevent. The document is still found by its name.
  • Backlinks and tasks inside them do not count, for the same reason. A task written in a protected document does not appear in the Tasks view.
  • Nobody can edit them with you. Working on a document together needs readable text, and only you can read this.
  • They save less often. A protected document waits for about 20 seconds of quiet, and at most a minute, before writing, and has no crash recovery. If the browser dies mid-sentence you can lose up to a minute of typing. That is the price of never writing a readable copy to disk.
  • They are never published, whatever their frontmatter says, and never served to an agent.

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 is called;
  • roughly when you last edited it.

They can also delete it, even though they cannot read it, the same as any other document in a graph you have shared.

If you open a document another member has protected, EtherPK says so rather than asking for a passphrase. No passphrase of yours will 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.

The document's frontmatter, the title: block at the top, is not protected, so it stays on screen whether the document is locked or unlocked. You can edit it in either state, exactly as on any other document: change the title and you are asked to confirm the rename when you leave the block; change the aliases and they apply (Titles Aliases And Frontmatter). The one thing you cannot do is delete the block from a protected document: without it the title would be sealed in with the secret at the next save. While the document is locked, the frontmatter is the only place the cursor can go.

A protected document never merges with another one. Renaming a page onto a name that is already taken normally joins the two, but joining a protected page with a readable one would leave the encrypted text beside ordinary text, and at that point it is not protected. So EtherPK refuses: you cannot rename a protected document onto a name another page holds, and you cannot rename another page onto a protected document's name. Pick a different name.

A synced document has no frontmatter block until you type one. Anything between two --- lines at the very top of a protected document is frontmatter, readable and shown above the locked card, so do not put anything secret there.

Where the encrypted document lives

Open a protected document's file in a text editor and you see the frontmatter, then one fenced code block tagged etherpk-cipher holding a long line of letters and digits, and nothing else:

---
title: Router
---
(a code block tagged etherpk-cipher)
AQQAAAGZaLmAAJmR3RhbXBsZS1jaXBoZXJ0ZXh0LWdvZXMtaGVyZQ

The title stays readable so links to the page keep working. Everything below it is the encrypted contents. That tag is how EtherPK, a Local Mirror, the publisher and the Headless Client recognise a protected document, which is why the block is described here rather than shown: a page containing the tag on a line of its own is itself treated as protected and is never published. The same block is what gets backed up, mirrored to a folder and sent to the Sync Server, so the document is protected everywhere, not only in the app.

Never edit, re-wrap or reformat the block. The encryption is authenticated: one changed character makes the whole document unreadable, with no way back. The AGENTS.md EtherPK writes into a local graph tells coding agents the same (Using AI Agents With Your Notes).

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 says so:

  • 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 is the only portable copy of the key, so EtherPK never writes 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 reads fine.

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

On a synced graph the wrapped key lives in your account's encrypted key bundle instead, so it travels with the account to every device, unlocked by the same passphrase.