request for docs

[mixmix]

How can we help? Tell us about what you'd like to be able to do

[nichoth]

Yikes I didn't realize this issue was created, apologies.

But since it was, and i got a response… From the readme:

SecretStack is built on secret-handshake and muxrpc. This provides a framework to make building secure, decentralized systems easier. (such as ssb-server which this was refactored out of ;)

What does it do with secret-handshake and muxrpc? Essentially it would be nice to have a written explanation of what this module does. From the outside it looks like just kind of a strange way of structuring your dependencies.

Thanks @mixmix

[mixmix]

Great question.

My understanding is that secret stack :

• uses secret-handshake to set up a shared key for use between two peers with public / private keys (and verify the other peer)
• uses multiserver to handle different ways of connecting to other peers over different protocols (who you then handshake with)
• uses muxrpc to provide a remote process call (rpc) interface to peers who have authenticated and connected allowing them to call methods on each other (like "please give me all mix's messages since yesterday"). This is all encrypted with the shared key set up by secret handshake.
• provides a plugin stack which allows you to
  • add new protocols to multiserver
  • add muxrpc methods
  • add plugins which persist state (like ssb-db, which when you add it essentially turns this into secure-scuttlebutt)
  • add plugins which let you listen and automate some things (eg replicate my friends when I connect to nicoth)

[nichoth]

Thanks. This is kind of getting into the weeds… but I can't see how secret-handshake comes into play. It's not listed as a dependency.

[mixmix]

Run npm ls secret-handshake after coming the module down Shows where it is in dep tree

[austinfrey]

hi @nichoth , it's pull in via a multiserver plugin

[nichoth]

Thanks @mixmix & all; I'm resuming my figuring out of this module.

uses muxrpc to provide a remote process call (rpc) interface to peers who have authenticated and connected allowing them to call methods on each other (like "please give me all mix's messages since yesterday"). This is all encrypted with the shared key set up by secret handshake.

app.getAddress() get a string representing the address of this node. it will be ip:port:.

app.connect(address, cb)

So how is the connection here made? There must be a protocol, for example websockets.

---

At a high level then, this module is responsible for creating a server via multiserver, a handshake, and RPC via muxrpc.

[mixmix]

How the connection is made depends on the peer. There are things called multi-server addresss, these can point to a peer via "net" (http i presume) or websocket, or socket (Linux and Unix only)

[nichoth]

https://github.com/ssb-js/multiserver#address-format

https://github.com/ssbc/multiserver-address

OK thanks. So the address is connected to via the first string section in the multi-address. For example

net:wx.larpa.net:8008~shs:DTNmX+4SjsgZ7xyDh5xxmNtFqa6pWi5Qtw7cE8aR9TQ=

And it seems as though secret-stack will return an object that can then be passed to muxrpc -- like in my use here: https://github.com/nichoth/eventual-gram-ssb-old/blob/main/src/server/index.js#L176

You pass an sbot to muxrpc, and the sbot is what uses the secret-stack module.

---

hmm I think I still don't totally get it. I would think that from the README in here you would want to call app.connect(address, cb), and that would create a muxrpc connection with another instance…

[mixmix]

Secret stack contains muxrpc and multi server. Secret stack provides that stuff, along with an API for mounting plugins.

The classic ssb-server for example is secret stack and ssb-db (which adds db methods accessible via muxrpc calls) and a host of other common plugins (ssb-backlinks, ssb-query, ssb-friends etc)

[mixmix]

You are correct, connect does connect you with another peer.

Typically plugins listen to the event app.on('rpc:connect', (peerApp) => {})

(or something like this) and then trigger different replication calls from there