{"id":13482610,"url":"https://github.com/ssbc/secret-stack","last_synced_at":"2025-03-27T13:32:13.832Z","repository":{"id":35329847,"uuid":"39591868","full_name":"ssbc/secret-stack","owner":"ssbc","description":"connect peers to each other using secret-handshakes","archived":false,"fork":false,"pushed_at":"2024-01-08T09:20:20.000Z","size":268,"stargazers_count":90,"open_issues_count":11,"forks_count":20,"subscribers_count":19,"default_branch":"main","last_synced_at":"2024-04-14T08:48:37.372Z","etag":null,"topics":["muxrpc","secret-handshakes"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ssbc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-07-23T20:48:58.000Z","updated_at":"2024-03-18T16:14:07.000Z","dependencies_parsed_at":"2024-01-16T03:45:35.658Z","dependency_job_id":"4ff0f77f-47ec-4ecb-a636-253923d6de47","html_url":"https://github.com/ssbc/secret-stack","commit_stats":null,"previous_names":["ssb-js/secret-stack"],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssbc%2Fsecret-stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssbc%2Fsecret-stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssbc%2Fsecret-stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssbc%2Fsecret-stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ssbc","download_url":"https://codeload.github.com/ssbc/secret-stack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245277415,"owners_count":20589152,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["muxrpc","secret-handshakes"],"created_at":"2024-07-31T17:01:03.722Z","updated_at":"2025-03-27T13:32:13.803Z","avatar_url":"https://github.com/ssbc.png","language":"JavaScript","funding_links":[],"categories":["Modules","JavaScript"],"sub_categories":[],"readme":"# secret-stack\n\ncreate secure peer to peer networks using secret-handshakes.\n\nThis provides a framework to make building secure, decentralized systems easier.\n(such as [ssb-server](https://github.com/ssbc/ssb-server) which this was refactored out of ;)\n\nThis module:\n\n* uses [secret-handshake](https://github.com/auditdrivencrypto/secret-handshake) to set up a shared key for use between two peers with public / private keys (and verify the other peer)\n* uses [multiserver](https://github.com/ssb-js/multiserver) to handle different ways of connecting to other peers over different protocols (who you then handshake with)\n* uses [muxrpc](https://github.com/ssb-js/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.\n* provides a plugin stack which allows you to\n    - add new protocols to multiserver\n    - add muxrpc methods\n    - add plugins which persist state (like ssb-db, which when you add it essentially turns this into secure-scuttlebutt)\n    - add plugins which let you listen and automate some things (eg replicate my friends when I connect to nicoth)\n\n## Example\n\n``` js\nvar SecretStack = require('secret-stack')\nvar databasePlugin = require('./some-database')\nvar bluetoothPlugin = require('./bluetooth')\nvar config = require('./some-config')\n\nvar App = SecretStack({ global: { appKey: '1KHLiKZvAvjbY1ziZEHMXawbCEIM6qwjCDm3VYRan/s=' } })\n  .use(databasePlugin)\n  .use(bluetoothPlugin)\n\nvar app = App(config)\n```\n\nFor documentation on plugins, see [PLUGINS.md](./PLUGINS.md).\n\n\n## API\n\n### `SecretStack(opts) =\u003e App`\n\nInitialize a new app factory.\n\n`opts` is an Object with properties:\n- `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.\n- `permissions` - _Object_ (optional), you can set default permissions which will be the foundation for all permissions subsequently added. See [muxrpc permissions](https://github.com/ssb-js/muxrpc#permissions)\n\nNOTE - 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)`)\n\n\n### `App.use(plugin) =\u003e App`\n\nAdd a plugin to the factory. See [PLUGINS.md](PLUGINS.md) for more details.\n\nReturns the App (with plugin now installed)\n\n### `App(config) =\u003e app`\n\nStart the app and returns an EventEmitter with methods (core and plugin) attached.\n\n`config` is an (optional) Object with:\n- `config.global` - an object containing data available for all plugins\n  - `config.global.keys` - _String_ a sodium ed25519 key pair\n- `config[pluginName]` - an object containing data only available to the plugin with name `pluginName`. Note that `pluginName` is the camelCase of `plugin.name`.\n\n`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), with only `config.global` and `config[pluginName]` available to each plugin.\n\nThis `app` as an EventEmitter emits the following events:\n\n- `'multiserver:listening'`: emitted once the app's multiserver server is set up successfully, with no arguments\n- `'rpc:connect'`: emitted every time a peer has been successfully connected with us, with the arguments:\n  - `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)\n  - `isClient`: a boolean indicating whether we are the client (true) or the server (false)\n- `'close'`: emitted once `app.close()` has finished teardown logic, with the arguments:\n  - `err`: if there was any error during closing\n\n### app.getAddress()\n\nget a string representing the address of this node.\nit will be `ip:port:\u003cbase64:pubkey\u003e`.\n\n### app.connect(address, cb)\n\ncreate a rpc connection to another instance.\nAddress should be the form returned by `getAddress`\n\n### app.auth(publicKey, cb)\n\nQuery what permissions a given public key is assigned.\nit's not intended for this to be exposed over the network,\nbut rather to extend this method to create plugable permissions systems.\n\n``` js\napp.auth.hook(function (auth, args) {\n  var pub = args[0]\n  var cb = args[1]\n  //call the first auth fn, and then hook the callback.\n  auth(pub, function (err, perms) {\n    if(err)  cb(err)\n    //optionally set your own perms for this pubkey.\n    else if(accepted)\n       cb(null, permissions)\n\n    //or if you wish to reject them\n    else if(rejected)\n      cb(new Error('reject'))\n\n    //fallback to default (the next hook, or the anonymous config, if defined)\n    else\n      cb()\n  })\n})\n```\n\n### `app.close()`\n\nclose the app!\n\nOptionally takes `(err, callback)`\n\n----\n\n## TODO document\n\n\u003e mix: I think some of these are exposed over muxrpc (as they're in the manifest)\nand some can only be run locally if you have access to the instance of `app` you\ngot returned after initialising it.\n\n### `app.id =\u003e String`  (alias `publicKey`)\n\n### `app.getManifest() =\u003e Object` (alias: `manifest`)\n\n\n### `auth: 'async'`\n### `address: 'sync'`\n### `config =\u003e Object'`\n### `multiserver.parse: 'sync',`\n### `multiserver.address: 'sync'`\n### `multiserver.transport: 'sync'`\n### `multiserver.transform: 'sync'`\n\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fssbc%2Fsecret-stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fssbc%2Fsecret-stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fssbc%2Fsecret-stack/lists"}