EtherPK User Docs

Sharing A Graph

A shared graph is a synced graph that more than one EtherPK account can open and edit at the same time. As you type, your changes reach everyone else who has the graph open. Each shared graph has one owner, who decides who is in it. At first that is the person who created the graph. Anyone who accepts an invite to someone else's graph is a Player and can read and edit everything in it. Together, the owner and the Players are the graph's members.

Everything in the graph is encrypted with one key, the Graph Key. Every member has a copy, but the Sync Server never has one. An invite carries the Graph Key to the new Player sealed to their public key, so only their Encryption Keys can open it.

A security fingerprint is a short code made from a person's public keys. Your device gets those keys from the Sync Server, so to be sure a key is really theirs, compare fingerprints with them in person or on a call you trust. The owner checks the invited person's fingerprint before sending an invite, and the invited person checks the owner's before accepting it, because the invite is signed with the owner's key.

Storage and Players count against the owner's Sync+ plan, so Players need an EtherPK account but not Sync+.

A Player who leaves or is removed loses access at once but keeps whatever their devices already had. The graph then moves to a new Graph Key that only the remaining members receive.

Before you begin

  • The owner must have an active Sync+ subscription.
  • The person you invite must have Encryption Keys and an EtherPK account with a verified email address.
  • Your Encryption Keys must be unlocked on this device to send or accept an invite. Transfer ownership, Leave, Remove and Delete work even while they are locked.
  • You must be signed in to Managed Sync on this device.

Owner and Players

On the Graphs tab, each shared graph has an Owner or Player badge beside its name.

Action Owner Player
Read and edit every document Yes Yes
Invite and remove Players Yes No
Rotate key, Transfer ownership and Delete Yes No
Leave No Yes

A graph has exactly one owner, so an owner who wants to leave has to transfer ownership first. Only the owner can see the member list.

If the owner's Sync+ ends, a payment is overdue or the plan is not confirmed, the graph becomes Read-only and nobody can write to it. Invite is hidden while the graph is read-only, but the owner can still transfer ownership. See Your EtherPK Account for more information.

Invite a Player

  1. On the Graphs tab, select Invite next to the graph.
  2. In the Invite a player dialog, enter the person's address in Email address.
  3. Select Continue.
  4. Compare the security fingerprint in the dialog with theirs.
  5. If they match, select Fingerprint matches, send invite.

Until they accept, the member list shows the person as Invited, with Cancel invite beside them.

Accept an invite

Invites sent to you wait under Pending invites on the Graphs tab. Each one shows the sender's address, the date it was sent and the graph's name, or "a shared graph" while your Encryption Keys are locked.

  1. On the invite, select Accept.
  2. In the Accept invite dialog, compare the owner's security fingerprint with the one they see.
  3. If they match, select Fingerprint matches, accept.

The graph then appears in your list on this device under the name the owner gave it.

If this browser has held the graph before, accepting replaces the old copy with the one on the Sync Server. If the old copy has changes that never reached the Sync Server, a dialog first tells you how many documents they affect and offers Download unsent changes. Nothing is discarded until you confirm. Cancel keeps everything and leaves the invite waiting.

To turn an invite down, select Decline and confirm in the row. You cannot undo a decline, so to join later you need a new invite from the owner.

Compare security fingerprints

To see your own fingerprint, open the Sync tab and select Show my fingerprint under Your security fingerprint. If the fingerprints do not match, the Sync Server has handed over keys the other person does not hold, so do not send or accept the invite.

Once you confirm someone's fingerprint, every device you use shows them as Verified, and the dialogs offer Send invite and Accept without asking you to compare.

If the Sync Server later gives a different key for that person, you see a warning with the new fingerprint. Someone's key changes when they replace or reset their Encryption Keys. A key the Sync Server substituted would look no different, so compare the new fingerprint with theirs before you select It matches, trust the new key.

You can also verify a Player marked Unverified or Key changed in the member list. With your Encryption Keys unlocked, select Verify beside them, then compare fingerprints and confirm.

Work in a shared graph

If you edit while offline, your device keeps your edits and syncs and merges them when the connection returns. See Working Offline for more information.

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.

Remove a Player

  1. On the Graphs tab, in the member list, select Remove beside the Player.
  2. Select Remove again to confirm.

The Player loses access at once, and any tab where they have the graph open stops syncing and shows "You no longer have access to this graph". If your Encryption Keys are unlocked, this device makes the new Graph Key at the same time.

Their favourites, bookmarks and quick notes are deleted from the graph the next time you open it. If you invite them back, they start with empty lists.

Leave a graph

  1. On the Graphs tab, select Leave next to the graph.
  2. In the Leave graph dialog, select Leave graph.

You lose access until the owner invites you again, but the graph and its other members are not affected. Leaving deletes the copy in this browser, along with its search index, so the dialog warns you about any changes that have not reached the Sync Server. Select Download unsent changes to keep them, or Discard changes and leave.

If you only want to delete the copy on this device and stay a member, use Remove from this device instead. See Managing Your Graphs for more information.

Transfer ownership

  1. On the Graphs tab, select Transfer ownership next to the graph.
  2. Under New owner, choose a Player.
  3. Select Transfer ownership.

Only Players who have accepted their invite appear under New owner, because only they hold the Graph Key. After the transfer, the Player you chose becomes the owner and you become a Player.

The new owner needs Sync+ with room for one more graph and its storage. Ownership is a record on the Sync Server and no key moves with it, so a transfer re-encrypts nothing and works while your Encryption Keys are locked, even if you have lost your Recovery Code. See Recovery Code And Device Approval for more information.

Delete a shared graph

  1. On the Graphs tab, select Delete next to the graph.
  2. In the Delete graph dialog, type DELETE.
  3. Select Permanently delete.

The graph is deleted from the Sync Server for every member and cannot be recovered. The dialog tells you how many other members will lose access.

Deleting also removes the copy in this browser, so the dialog warns you about unsent changes and offers Download unsent changes. Files you mirrored to a local folder are kept. See Keeping A Local Copy Of A Synced Graph for more information.

Change the Graph Key

A graph moves to a new Graph Key when:

  • a Player leaves or is removed
  • an invite is cancelled or declined
  • a Player resets their Encryption Keys, or the owner replaces theirs
  • the owner selects Rotate key, which does not ask for confirmation

The owner's device makes the new key the next time the owner opens the Graphs tab or the graph with their Encryption Keys unlocked. No other device can make it, so until then new edits still use the old key.

Players do not need to do anything. Their devices pick up the new key, even in a graph that is already open. A device that does not have the key yet shows "Waiting for key". See Troubleshooting for more information.

If a member's security key has changed since the owner checked it, that member does not get the new key until the owner compares fingerprints and selects Verify beside them in the member list.

Former members keep the earlier keys, so if they get hold of the encrypted data, they can read anything written before the key changed but nothing written after. See How Encryption Works for more information.

  • 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
    • Only the owner of a synced graph can invite Players to it, by selecting Invite in its row on the Graphs page. See Sharing A Graph for more information.
  • Glossary
    • | Graph Key | The key a graph is encrypted with. Every member holds it, so every Player can read the whole graph. | Sharing A Graph |
    • | invite | The owner's signed request for another account to join a shared graph as a Player. It carries the Graph Key. | Sharing A Graph |
    • | owner | The account that holds a shared graph and decides who joins. A graph's members are its owner and its Players. | Sharing A Graph |
    • | Player | A person invited into someone else's synced graph, who can read and edit all of it. Players count against the owner's Sync+ plan, so they need an EtherPK Account but not Sync+. | Sharing A Graph |
    • | Rotate key | The owner's action that gives a graph a new Graph Key at once. Members receive the new key automatically. | Sharing A Graph |
    • | security fingerprint | A short code made from a person's public keys. You compare it with that person before you send or accept an invite. | Sharing A Graph |
    • | shared graph | A synced graph that more than one EtherPK Account opens and edits at the same time. | Sharing A Graph |
    • | Verified / Unverified / Key changed | Labels for a person whose fingerprint you confirmed, a person whose fingerprint you never compared, and a person whose key changed. While Key changed shows, the next Graph Key is held back until the owner selects Verify. | Sharing A Graph |
  • How Encryption Works
    • A shared graph's members are its owner and its Players, the people the owner invited (see Sharing A Graph). Every member holds the graph's single Graph Key, so every Player can read and change everything in the graph apart from protected documents, which are hidden from them.
  • Images And Files
    • Players removed from a synced graph can no longer fetch its files, but they keep any files they already downloaded. See Sharing A Graph 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.
  • Managing Your Graphs
    • Removing a synced graph deletes its copy in this browser, but the graph stays on the Sync Server and you can bring it back with Add to this device. Other members keep the graph, though the owner can delete it for everyone with Delete. See Sharing A Graph for more information.
  • Protected Documents
    • 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.
  • Quick Notes
    • The list is part of the graph, so it survives a reload and goes wherever the graph goes. In a local graph the list is a file in the graph folder. A synced graph shows the same list on every device you open it on, and in a shared graph each person has their own list. See Synced Graphs and Sharing A Graph for more information.
  • Recovery Code And Device Approval
    • Encryption Keys decrypt your synced graphs. They are a Graph Key for each synced graph you own or have joined, plus identity keys for invites, and they belong to your EtherPK Account, not to any one device. The owner of a shared graph and its Players, the people who joined it, hold the same Graph Key. See Sharing A Graph for more information.
    • You can transfer a shared graph even while locked out, because ownership is a record on the Sync Server and needs no keys. A graph with no other Player cannot be recovered, since nobody else holds its Graph Key. To transfer a graph, select Transfer ownership in its row on the Graphs tab, or Transfer… in the reset dialog, and follow the steps on Sharing A Graph.
  • Synced Graphs
    • A synced graph is a graph stored on Managed Sync, the Sync Server that EtherPK runs. You can open it on each of your devices and share it with other people, who join it as Players. Owning a synced graph takes a Sync+ subscription, but a Free account can join one that a Sync+ subscriber shares. See Sharing A Graph for more information.
    • Only the owner can delete a synced graph. Players see Leave instead. See Sharing A Graph for more information.
  • The Graph Sidebar
    • 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.
  • Troubleshooting
    • A local graph is a folder on your computer that the browser can reach with your permission. A synced graph is encrypted on your device with your Encryption Keys and stored on Managed Sync, and its owner can share it with other people, who join as Players (see Sharing A Graph). If something fails, a local graph keeps your edits in the open tab until EtherPK writes the file, and a synced graph keeps them on this device until the Sync Server accepts them. Until then, do not close the tab or clear the browser's site data.
    • See Sharing A Graph for more information.
    • See Sharing A Graph for more information.
    • See Sharing A Graph for more information.
    • See Your EtherPK Account and Sharing A Graph for more information.
  • Using AI Agents With Your Notes
    • On a shared graph, other members see the agent as Agent on followed by the device name. See Sharing A Graph for more information.
  • Working Offline
  • Your EtherPK Account
    • Joining someone else's graph costs you nothing, because the Players in a graph use its owner's allowance. See Sharing A Graph for more information.