# ssb-ws

> websocket & http server for ssb

Latest version **6.2.3** (published 2019-06-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install ssb-ws
pnpm add ssb-ws
yarn add ssb-ws
bun add ssb-ws
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 6.2.3 |
| Published | 2019-06-19 |
| First published | 2016-07-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 8.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 10 |
| Author | 'Dominic Tarr' |
| Maintainers | ahdinosaur, aljoscha-meyer, andregarzia, arj03, cel, christianbundy, cryp7ix, dominictarr, happy0, kyphae, mixmix, mmckegg, noffle, pfrazee, pietgeursen, regular, staltz, substack, vtduncan |

## Links

- npm: https://www.npmjs.com/package/ssb-ws
- Repository: https://github.com/dominictarr/ssb-ws
- Issues: https://github.com/dominictarr/ssb-ws/issues
- npm.io page: https://npm.io/package/ssb-ws

## Dependencies (7)

- [stack](https://npm.io/package/stack.md) ^0.1.0
- [ssb-ref](https://npm.io/package/ssb-ref.md) ^2.3.0
- [multiserver](https://npm.io/package/multiserver.md) ^3.0.2
- [pull-stream](https://npm.io/package/pull-stream.md) ^3.6.9
- [emoji-server](https://npm.io/package/emoji-server.md) ^1.0.0
- [multiblob-http](https://npm.io/package/multiblob-http.md) ^1.0.0
- [pull-box-stream](https://npm.io/package/pull-box-stream.md) ^1.0.13

## Recent versions

- 6.2.3 (latest) — 2019-06-19
- 6.2.2 — 2019-06-06
- 6.2.1 — 2019-05-31
- 6.2.0 — 2019-04-27
- 6.1.0 — 2019-04-19
- 6.0.0 — 2019-03-04
- 5.1.1 — 2018-11-16
- 5.1.0 — 2018-11-16
- 5.0.0 — 2018-11-16
- 3.0.2 — 2018-11-01
- 4.0.1 — 2018-10-29
- 4.0.0 — 2018-10-27
- 3.0.0 — 2018-10-11
- 2.1.1 — 2018-04-11
- 2.1.0 — 2018-03-03
- … 32 more at https://npm.io/package/ssb-ws/versions

## README

# ssb-ws

**Creates a web server for ssb clients**

It is used by ssb clients, in [scuttle-shell ](https://github.com/ssbc/scuttle-shell) which is required for [Patchfox](https://github.com/soapdog/patchfox), and in web projects like [secret-islands](https://github.com/dangerousbeans/secret-islands).

Peers can replicate over ws, if a pub exposes a ws address and this enables sbot peers running in a browser (WIP).

Since ssb-ws creates a web server, it also exposes an interface that allows plugins to expose things over http. Blobs and emoji are provided via this plugin too.

### usage

``` js
sbot plugins.install ssb-ws
```

best configured via [connections config](https://github.com/ssbc/ssb-config#connections)

``` json
"connections": {
  "incoming": {
    "ws": [{
      "scope": ["public", "local", "device"],
      "port": 9000,
      "transform": "shs",
      "http": true // serve http, see ws.use(handler)
    }]
  }
}
```

you can have more than one ws server if desired.
you can also disable hosting of http handlers
by setting `web:false` on the config item,
`connections.incoming.ws[N].web = false`

# Api
## noauth

given the flexibility of multiserver, you may want to run
this with noauth config locally. However this is ***not recommended***
until ssb-ws prevents [dns rebinding attacks](https://medium.com/@brannondorsey/attacking-private-networks-from-the-internet-with-dns-rebinding-ea7098a2d325)
and websocket connections from locally open websites.

If used with a [secure transport](https://github.com/auditdrivencrypto/secret-handshake),
that authenticates the client `"transport": "shs"`
then this is not a problem.

## ws.use(handler) - http handlers

sometimes you need to do http, but if every plugin that did that
created it's own servers there would be mass panic.
But never fear, with ssb-ws, you can add http handlers
as [connect style middleware](https://www.npmjs.com/package/stack).

Here is an example sbot plugin that
adds a single route: to output the current sbot address.

``` js
require('scuttlebot')
  .use(require('ssb-ws'))
  .use({
    name: 'test123',
    version: '1.0.0',
    init: function (sbot) {
      sbot.ws.use(function (req, res, next) {
        if(req.url == '/get-address')
          res.end(sbot.getAddress('device'))
        else next()
      })
    }
  })
```

http hosting on a particular multiserver address can be disabled
using `{http:false}` in the incoming multiserver config.

## License

MIT

---
_Source: https://npm.io/package/ssb-ws · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._