EtherPK User Docs

Protected Documents

A protected document is a page whose text EtherPK encrypts on your device. The text stays encrypted in a local graph folder, in the browser's copy of a synced graph, on the Sync Server, in a Local Mirror and in an export. The frontmatter is not encrypted, so tabs, links and search by name can still use the page's title and aliases.

You have your own protection key in each graph, a random key that encrypts every page you protect there. The key is only ever stored locked, under your protection passphrase and, if you bind one, under a passkey in one browser on one device. Nothing else can unlock it, so neither EtherPK nor your Recovery Code can recover the passphrase if you forget it. Your only way back in is a passkey you bound on a device before you forgot, which still unlocks the graph on that device.

Protection is a second layer beside sync encryption. Sync encryption keeps a synced graph unreadable to the Sync Server, but each device has a readable copy, and every Player you share the graph with holds its key. A device passcode covers only the Encryption Keys, so protection is what keeps a page unreadable to someone using your unlocked device. The page also stays unreadable in a copy of the graph folder or browser profile, and to the other Players. In a local graph, protected pages are the only encrypted text on disk. See How Encryption Works for more information.

After you unlock a graph with the passphrase or a bound passkey, you can read and edit its protected documents like any other page. The app hides their contents as soon as you switch to another window or browser tab. It keeps the key in memory while they are hidden, so if you come back within a grace period, the text reappears without the passphrase. The graph locks when the grace period ends, after a set time with no activity, when you select Lock now, or when you close or reload the browser tab. Locking discards the key, so after that you need the passphrase or a passkey again.

Before you begin

  • A page, other than a journal entry.
  • A passphrase you will remember.
  • A second device or browser to bind a passkey on, if you have one.

Protect a document

Your protection passphrase covers the whole graph. A local graph folder, a Local Mirror and an export each carry the key locked under it, so anyone with a copy can try passphrases offline as fast as their computer allows. Length is what slows them down, so a long sentence makes a better passphrase than a short, complicated word.

To protect a page:

  1. Right-click the page tab and select Protect…. On a phone, long-press the current document in the bar at the top of the screen.

    The Protect… item, outlined, in the right-click menu of a page tab

  2. If the graph has no passphrase yet, the Set a protection passphrase dialog opens. Enter a passphrase in Passphrase and again in Confirm passphrase.

  3. Select the checkbox that says the contents are lost if you forget the passphrase.

  4. Select Set passphrase.

The app protects the page at once. You can also run Protect this document from the command menu.

A page you have opened from Search or a link but not typed into yet does not exist until the first keystroke. Protect… on it asks whether to create it. Select Create and protect to create the page empty and encrypt it. Anything you type into it after that is protected. On a graph with no passphrase, EtherPK asks for the passphrase first, and creates nothing if you cancel.

Protection covers a whole page, so to hide one line of a page you share, put that line on a protected page of its own and link to it. You also cannot protect a journal entry, so keep sensitive text on a page you link to from the day. See Journal Entries for more information.

Bind a passkey

A passkey bound to a device lets you unlock the graph on that device with your fingerprint, face or device PIN instead of the passphrase. It keeps working even after you forget the passphrase, so bind one on each device you use.

To bind a passkey:

  1. Unlock the graph.

  2. In Settings, select the Protected Documents tab.

  3. Under This device, select Bind a passkey to this device.

    The Bind a passkey to this device button, outlined, under This device on the Protected Documents tab of Settings

Binding needs the key itself, so the button is disabled while the graph is locked. See Graph Settings for more information on opening Settings.

Each binding belongs to one graph in one browser on one device, and the app never syncs or exports it. These passkeys are separate from the ones you use to sign in to Your EtherPK Account.

Unlock and lock

Each protected document has a padlock on its tab, closed while the document is locked and open while you can read it. While the graph is locked, you see a Protected card with an Unlock button in place of the text.

A locked protected document: a closed padlock on its tab, its title in the frontmatter, and a Locked card with an Unlock button where the text would be

You have one protection key per graph, so unlocking any protected document unlocks all of them in that graph on this device, and locking locks them all.

Any of these opens the Enter passphrase dialog:

  • Unlock under Protected documents in the Graph Sidebar
  • Unlock on the locked card
  • Unlock… in the tab menu
  • Unlock protected documents in the command menu

If the device has a bound passkey, the dialog asks for it first. If not, or if you decline the passkey, type your passphrase and select Enter passphrase.

To lock, select Lock now under Protected documents in the Graph Sidebar, or the padlock button at the bottom right of any document.

The Lock protected documents button, a padlock, outlined, at the bottom right of a document

By default, locking this way also closes every protected tab, including pinned ones, because a row of padlocked tabs would still show what you had open. Tabs for other pages stay open.

Lock timings

Two settings on the Protected Documents tab in Settings control when the app discards the key:

  • Lock after I switch away sets the grace period that starts when the contents leave the screen. It defaults to After 1 minute. Choose Immediately to lock as soon as you switch away.
  • Lock after this long with no activity defaults to 5 minutes. Choose Never to switch it off.

The timings apply to this device only, because the right timeout depends on where the device is. Set them on each device you use.

Timers never close tabs, so a timeout never takes them away while you work. Before every lock, the app saves your pending edits, so locking never loses work.

Edit a protected document

Bullets, wikilinks, tasks and the command menu all work in an unlocked protected document. The frontmatter stays readable and editable whether the graph is locked or not. It is not encrypted, so keep nothing secret in it. If you change the title there, the app asks you to confirm the rename. See Titles Aliases And Frontmatter for more information.

Change the passphrase

If you know the current passphrase, you can change it without unlocking the graph.

  1. In Settings, select the Protected Documents tab.
  2. Under Passphrase, select Change passphrase….
  3. Enter the current passphrase, then the new one twice.
  4. Select Change passphrase.

The new passphrase locks the same protection key, so nothing is re-encrypted and your protected documents and bound passkeys keep working. A folder backup or an export made before the change still opens with the old passphrase, though.

Remove protection

Unlock the graph, then right-click the page tab and select Remove protection…. The menu offers this item only while the graph is unlocked, because removing protection decrypts the text. The app writes the readable text back into the page and its file at once and does not ask you to confirm.

What protection leaves out

The search index on your device is not encrypted, so protected text never goes into it, even while the graph is unlocked. For a protected document:

  • You can find the page by name in Search, but never by its text.
  • Its links do not count in Backlinks, and its tasks do not appear in The Tasks View or on Kanban Boards.
  • Nobody can edit it together with you.
  • It has no crash recovery. The app never writes protected text to disk in readable form, so a browser crash can lose up to a minute of typing.
  • It is never published, whatever its frontmatter says. See Publishing Your Notes As A Website for more information.
  • The Headless Client and Agent Chat never show it to an agent, not even its name, because anything an agent reads can be sent to its model provider. See Using AI Agents With Your Notes for more information.
  • Spell Check never checks it, and Maps in it show as text.
  • Protecting it removes its Bookmarks on every device.
  • It cannot be one of your Templates.
  • Attached Images And Files are not protected, because the graph keeps them outside the encrypted text and any other page can show them with a link.
  • While the graph is unlocked, an installed extension can read and change it, because Extensions run without a sandbox.

Protected documents in a shared graph

In a shared graph, each Player has their own protection key and passphrase, so you cannot read each other's protected documents. Other Players can still see that yours exist and what they are called. On a document that another Player protected, you see a Protected by another member card instead of a passphrase prompt. See Sharing A Graph for more information.

Protected files and the key record

In a local graph folder, the file for a protected document holds its frontmatter and then one code block tagged etherpk-cipher. Never edit, re-wrap or reformat that block. It is authenticated, so changing a single character makes the whole document unreadable for good.

In a local graph, the key record etherpk/protection.json is the folder's only copy of your locked protection key, so back it up with the folder and never edit, move or delete it. Without it, every protected document shows the Protected by another member card on every device, and a bound passkey does not help. If you then protect a page, you set up a new passphrase and a new key, and neither can open the old documents. See Graph Folder Layout for more information.

In a synced graph, the key record is stored with your Encryption Keys, and a Local Mirror or an export carries a copy of it. See Keeping A Local Copy Of A Synced Graph for more information. If the key record is damaged, see Troubleshooting.

  • Backlinks
    • Links in Protected Documents, even while one is unlocked, because their text never reaches the search index.
  • Bookmarks
    • Bookmarks are encrypted with the Graph Key. Every member of a synced graph holds that key, so your bookmarks are not secret from the other members. To keep text private, use Protected Documents. A Player who leaves the graph or is removed from it loses their bookmarks the next time the owner opens the graph. See How Encryption Works, Synced Graphs and Sharing A Graph for more information.
  • Choosing Where To Store Your Notes
  • Document Syntax
  • Drawings
    • In a protected document a drawing is protected text like the rest, so its lines are encrypted with the document. You see the lines instead of a picture, a drawing is not offered in the slash menu, and a tab or the full window says the drawing cannot be shown. See Protected Documents for more information.
  • EtherPK On A Phone
  • Find And Replace
    • While a protected document is locked, its text is encrypted, so find searches only the frontmatter, and replace stays unavailable until you unlock the document. See Protected Documents for more information.
  • Glossary
    • | hidden | A protected document off screen while you work in another document, tab or window. Its protection key stays in memory. | Protected Documents |
    • | locked | A protected document whose protection key is no longer in memory. It needs the passphrase again, or a passkey you bound in this browser. | Protected Documents |
    • | protected document | A page whose text EtherPK encrypts on your device. Players can read the rest of a shared graph, so protecting a page is the way to keep it from them. | Protected Documents |
    • | protection key | A random key, one for each person in each graph, that encrypts the pages you protect. It is not one of the Encryption Keys, so the Recovery Code cannot open those pages. | Protected Documents |
    • | protection passphrase | The passphrase that unlocks your protection key in one graph. Neither EtherPK nor the Recovery Code can recover a forgotten one. | Protected Documents |
  • Graph Folder Layout
    • Protected documents are encrypted, and EtherPK needs the protection key to read them. protection.json holds that key, wrapped with your passphrase and never in plain form. If you edit, move or delete the file, every protected document in the graph becomes unreadable, and without a copy of the file there is no way to recover them. See Protected Documents for more information.
  • Graph Settings
    • Until the graph has a protection passphrase, the tab offers Set up protection…. After that, it shows two lock timings, which apply to every graph on this device and are saved as soon as you change them. See Protected Documents for more information.
  • How Encryption Works
    • Protected Documents have a second layer of encryption under a protection key, and each person has their own protection key in each graph. Yours is locked under your passphrase and, if the graph is synced, kept with your Encryption Keys. The key that opens your Encryption Keys cannot open your protection key, so the Recovery Code cannot open a protected document or recover a forgotten passphrase. Nor can a copy of an unlocked device open one.
  • Images And Files
    • Protection covers only a document's text, so every member of the graph can open a file attached to a protected document. See Protected Documents for more information.
  • Importing A Knowledge Base
    • Protected documents also arrive unchanged, with their etherpk/protection.json file, and open in the new graph with the same passphrase. If the copy has no such file, they stay encrypted under a key the new graph does not have. See Protected Documents for more information.
  • Journal Entries
    • You cannot protect a journal entry, so keep sensitive text in one of your Protected Documents and link to it from the day.
  • Kanban Boards
    • A task in a protected document is on no board, even while the document is unlocked. Boards find their tasks through the search index, which never holds a protected document's text. See Protected Documents for more information.
  • Keeping A Local Copy Of A Synced Graph
    • Protected documents stay encrypted in a mirror and in an export. Each copy also holds your protection key, wrapped with your passphrase, so in a graph rebuilt from the copy the same passphrase opens those documents. In a shared graph (Sharing A Graph) the copy holds only your key, so in the rebuilt graph you cannot open documents that another Player protected. See Protected Documents for more information.
  • Keyboard Shortcuts
    • | Lock protected documents, Unlock protected documents, Protect this document, Remove protection from this document | Lock or unlock the protected documents on this device, or encrypt or decrypt this page. | Protected Documents |
  • Maps
  • PDFs: Reading, Annotating and More
    • On a local graph, the file is renamed and every link to it takes the new name, keeping any #page=. Link text changes only if it was the old name, and any text you wrote yourself stays. EtherPK refuses the rename while your Protected Documents are locked, because a link inside a locked one would break.
  • Planned Features
    • | Re-encrypting imported protected documents for the existing graph, after asking once for the source graph's passphrase. Without the passphrase, they arrive unreadable. | An EtherPK import keeps protected documents under the same passphrase. The import report tells you if it could not, or if their images and files will not show. | Protected Documents |
  • Publish Settings
    • A link to a page that is not on the site looks like a missing link and leads to a page that says "This page is not published." Search, the feed, the sitemap and linked references use only the published documents, so nothing on the site shows that a private document exists. See Protected Documents for more information.
  • Quick Notes
    • EtherPK does not show your quick notes to the other members of a shared graph. Every member has the graph key, though, so the notes are not secret from them. Keep private text in a protected document instead. See Protected Documents for more information.
  • Recovery Code And Device Approval
  • Search
    • A protected document's text and properties never go into the index, even while it is unlocked, so Search can find its name but never its words. See Protected Documents for more information.
  • Sharing A Graph
    • Every member sees the same documents, graph name and settings, but each member has their own favourites, bookmarks and quick notes. If you protect a document, other members can still see its name, but they see a card in place of its text. See Protected Documents for more information.
  • Spell Check
    • Protected Documents, even while unlocked, so none of their words can reach the shared graph dictionary
  • Synced Graphs
    • Every Player has the graph's key. To hide a note from the other Players, put it in a protected document, which gets a second layer of encryption under a key that only you hold. See Protected Documents for more information.
  • Tables
  • Tasks
    • The app never indexes protected documents, so their tasks stay out of the Tasks view and off Kanban boards, even while the document is unlocked. On a task in a protected document, neither /copy nor the right-click menu offers Copy agent instruction. The status and priority rows are there while the document is unlocked. See Protected Documents for more information.
  • Templates
    • The value must be true without quotes, so template: "true" does not make a Template. Protected Documents are never listed or copied as Templates, so their text never ends up in a copy.
  • The Graph Sidebar
    • The Protected documents section has one button. A single protection key covers every protected document in the graph, so the button locks or unlocks all of them on this device. While they are unlocked it reads Lock now. While they are locked it reads Unlock, which asks for your passphrase. See Protected Documents for more information.
    • On a local graph, your favourites live in etherpk/settings.json (see Graph Folder Layout). In a shared graph (see Sharing A Graph), EtherPK does not show your favourites to the other members. Every member has the graph key, though, so the list is not secret from them. To keep a document's text private from them, protect it (see Protected Documents). A Local Mirror or an export of a synced graph carries only your own favourites. See Keeping A Local Copy Of A Synced Graph for more information.
  • The Graph View
    • A tinted line joins a page to the scope in its name, such as Garden in [[Garden]] Notes (see Scoped Concepts). Lines run into Protected Documents but never out of them, locked or unlocked, because their links sit in encrypted text that the index never reads. The picture leaves out Templates.
  • The Tasks View
    • The list never shows tasks in a protected document, even while the document is unlocked, because the search index on this device is not encrypted and protected content never goes into it. The list also leaves out tasks in a template, because a template is a pattern copied into other documents. See Protected Documents and Templates for more information.
  • Troubleshooting
  • Using AI Agents With Your Notes
    • The Headless Client never has a protection key. An agent that reads a protected document gets the same answer it would get for a name no document has, and a write to a protected name is refused. If a task needs a protected document, unlock it in EtherPK and make the change yourself. See Protected Documents for more information.
    • A protected document never goes to the provider, even when it is unlocked, and neither does its name. See Protected Documents for more information. On a shared graph, what goes to the provider can include what other members wrote.
  • Where Your Data Is Stored
    • EtherPK saves a protected document with its body as ciphertext and its title and aliases readable. The protection key is in etherpk/protection.json, wrapped under your protection passphrase, so back that file up along with the documents. See Protected Documents for more information.
  • Working Offline
    • A device passcode protects your unlocked Encryption Keys on this device. If you use one, each new or reloaded tab asks for it before a synced graph opens, unless another open EtherPK tab is already unlocked. Because your device checks the passcode, you can enter it with no connection. A protected document still unlocks with its own passphrase. See Device Passcode and Protected Documents for more information.
  • Your EtherPK Account
    • A passkey lets you sign in with your fingerprint, face or screen lock instead of a password. To add one, select Add a passkey under Passkeys, give it a name, select Continue and confirm in your browser. These passkeys only sign you in to your account and are separate from the passkeys that unlock Protected Documents.