secret-stack

create secure peer to peer networks using secret-handshakes.

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 ;)

Example

var SecretStack = require('secret-stack')
var databasePlugin = require('./some-database')
var bluetoothPlugin = require('./bluetooth')
var config = require('./some-config')

var App = SecretStack({ appKey: '1KHLiKZvAvjbY1ziZEHMXawbCEIM6qwjCDm3VYRan/s=' })
  .use(databasePlugin)
  .use(bluetoothPlugin)

var app = App(config)

For documentation on plugins, see PLUGINS.md.

API

SecretStack(opts) => App

Initialize a new app factory.

opts is an Object with properties:

• appKey - String, 32 bytes a high entropy (i.e. random) key which is fixed for your app. Actors who do not know this value will not be able to connect to instances of your app.
• permissions - Object (optional), you can set default permissions which will be the foundation for all permissions subsequently added

NOTE - you can also add other properties to opts. These will be merged with config later to form the final config passed to each plugin. (i.e. merge(opts, config))

App.use(plugin) => App

Add a plugin to the factory. See PLUGINS.md for more details.

Returns the App (with plugin now installed)

App(config) => app

Start the app and returns an EventEmitter with methods (core and plugin) attached.

config is an (optional) Object with any properties:

• keys - String a sodium ed25519 key pair
• ... - (optional)

config will be passed to each plugin as they're initialised (as merge(opts, config) which opts were those options SecretStack factory was initialised with).

This app as an EventEmitter emits the following events:

• 'multiserver:listening': emitted once the app's multiserver server is set up successfully, with no arguments
• 'rpc:connect': emitted every time a peer has been successfully connected with us, with the arguments:
  • rpc: the muxrpc object to call the peer's remote functions, includes rpc.stream and rpc.stream.address (the multiserver address for this remote peer)
  • isClient: a boolean indicating whether we are the client (true) or the server (false)
• 'close': emitted once app.close() has finished teardown logic, with the arguments:
  • err: if there was any error during closing

app.getAddress()

get a string representing the address of this node. it will be ip:port:<base64:pubkey>.

app.connect(address, cb)

create a rpc connection to another instance. Address should be the form returned by getAddress

app.auth(publicKey, cb)

Query what permissions a given public key is assigned. it's not intended for this to be exposed over the network, but rather to extend this method to create plugable permissions systems.

app.auth.hook(function (auth, args) {
  var pub = args[0]
  var cb = args[1]
  //call the first auth fn, and then hook the callback.
  auth(pub, function (err, perms) {
    if(err)  cb(err)
    //optionally set your own perms for this pubkey.
    else if(accepted)
       cb(null, permissions)

    //or if you wish to reject them
    else if(rejected)
      cb(new Error('reject'))

    //fallback to default (the next hook, or the anonymous config, if defined)
    else
      cb()
  })
})

app.close()

close the app!

Optionally takes (err, callback)

---

TODO document

mix: I think some of these are exposed over muxrpc (as they're in the manifest) and some can only be run locally if you have access to the instance of app you got returned after initialising it.

app.id => String (alias publicKey)

app.getManifest() => Object (alias: manifest)

auth: 'async'

address: 'sync'

config => Object'

multiserver.parse: 'sync',

multiserver.address: 'sync'

multiserver.transport: 'sync'

multiserver.transform: 'sync'

License

MIT