Aral Balkan

Mastodon icon RSS feed icon

Hypha Spike: Multiwriter 2



Following on from Hypha Spike: Multiwriter 1 this spike aims to:


Screenshot of an authorisation request. Message: Authorise node Firefox on Ubuntu 64-bit? Button with label: Authorise

Peer-to-peer node authorisation: early proof of concept.

This is the onboarding and new node authorisation (sign up/sign in) flow:

  1. Person signs up either via a native app or the web. The app or the browser becomes the origin node. The database is only writable on this node at this point.

  2. Person signs in using their password on a second node (either native or web). A database is created on this node and replicates with the origin database but it is read only at creation. The person is asked to sign into an existing node and approve the new node.

    Description is in the caption

    Whiteboard sketch showing sign up (origin node) and sign in (read-only node) and the means available for peer-to-peer authorisation request of nodes via an encrypted ephemeral messaging channel.

  3. The second node uses an encrypted ephemeral messaging channel extension to the Dat protocol to ask for authorisation. This request is sent browser-to-browser via WebRTC, native-to-native via TCP, and browser-to-native and native-to-browser via WebSocket (the always-on node proxies the requests via WebSocket but it cannot see the contents of the messages as it is an unprivileged node and doesn’t have the secret key).

  4. On the origin node (or, later, on any other authorised node), the person is prompted to authorise the new node. When they do, the new node becomes able to both read and write to the common database.

Iteration plan

  1. ✔ Refactor to create reproducible local writers
  2. ✔ (tag) Authenticate (manually) using the node name and reproducing the remote node’s local keys
  3. ✔ (pull request) Update DEP-0000: Ephemeral Message (Extension Message) to support hyperdb.
  4. ✔ (tag) Implement an ephemeral messaging channel between nodes and use a JSON request to ask for authorisation of new nodes (WebRTC)
  5. ✔ Also add the ephemeral messaging channel to replication over WebSocket
  6. ✔ (tag) Also add the ephemeral messaging channel to replication over TCP
  7. ✔ (tag) Add ephemeral message deduplication to the browser and native clients as messages may be received more than once due to the always-on node relay.
  8. ✔ (source) Implement a secure ephemeral messaging channel as a Dat extension based on DEP-0000: Ephemeral Message (Extension Message).
  9. ✔ (tag) Implement the secure ephemeral messaging channel in the spike. (Currently only on WebRTC replication.)
  10. ✔ (tag) Extend the secure ephemeral messaging channel to support unprivileged relay nodes (the always-on nodes).
  11. ✔ (tag) Implement secure ephemeral messaging channel on WebSocket connection. (Encrypted messages are now relayed by the always-on node.)
  12. ✔ Update the native app (mock) to accept a secret key and set up the secure ephemeral messaging channel over a TCP connection.
  13. ✔ (tag) Fix: allow any authorised node to authorise any other node.

Pushed to later spikes:

  1. Create a higher level Hypha authentication library with a simpler API that abstracts away the messaging aspect (@hypha/auth)
  2. Add options to interface to selectively enable replication over WebSocket or WebRTC or both for testing.
  3. Clean up the interface and carry out some general housekeeping on the code.

Future plans

Release the authentication functionality as a stand-alone module that can be used across projects – e.g., @hypha/auth

Upcoming spikes

Security considerations


In this spike, I added hyperdb support to Paul Frazee’s dat-ephemeral-ext-msg module and created an end-to-end encrypted secure messaging channel for use between nodes owned by the name person: secure-ephemeral-messaging-channel.

Any authenticated node can now securely authorise any other node as a writer.

Up to this point, the spikes have been using random-access-memory as the storage layer. In the next spike, I will expore persistence. My plan is to then look at the auth module refactor once the sign up/sign in process more closely implements real-world behaviour.


Heartbeat was the initial precursor to Hypha. We were limited by lack of control over the replication engine we had chosen ­(syncthing). Other limitations were: it was single writer/device, it had a privileged centralised signalling server. That said, it basically used kappa architecture (although the term was independently being coined at about the same time) and did solve some of the same challenges we need to solve now using the Dat protocol/ecosystem. The design is very close to that of Cabal but with the addition of authentication and private messaging.