# ssb-npm-registry

Serve an npm registry server backed by SSB.

## Install

```
BLOB_ID="$(sbot links2.read --query '[{"$filter":{"rel":["mentions",{"$prefix":"npm:ssb-npm-registry:"}]}}, {"$map":"dest"} ]'|grep -o '&.*sha256'|tail -n 1)" &&
sbot plugins.install ssb-npm-registry --from "http://localhost:8989/blobs/get/$BLOB_ID" &&
sbot plugins.enable ssb-npm-registry
# restart sbot
```

## Develop

### Install with git-ssb:

As a scuttlebot plugin:
```
git clone ssb://#ssb-npm-registry ~/.ssb/node_modules/ssb-npm-registry
sbot plugins.enable ssb-npm-registry
# restart sbot
```

Or run standalone with [ssb-party](%bS/WGqQrhQfH8eoyWieK+9M56DjJ8Q4ulkvb6sXZwPo=.sha256):
```
git clone ssb://#ssb-npm-registry
ssb-party \#ssb-npm-registry
```

Set ssb-npm-registry as your default registry server:
```
npm config set registry http://localhost:8043
```

## Config

`~/.ssb/config` example:
```
{
  "npm": {
    "host": "localhost",
    "port": 8043,
    "autoAuth": true,
    "fetchAll": true
  }
}
```
- `config.npm.host`: hostname to listen on. default is "localhost"
- `config.npm.port`: hostname to listen on. default is 8043
- `config.npm.autoAuth`: whether to automatically update `~/.npmrc` to add
- `config.npm.fetchAll`: whether to fetch blobs for all versions of a package,
  to populate package metadata, for a request to a `/<package>` path. Most npm
  clients require this. default is `true`

## API

```
var Registry = require('ssb-npm-registry')
```

### `var serve = Registry.respond(sbot, config)`

Embed ssb-npm-registry into other applications using the `respond` method
which returns a `(req, res)` HTTP handler function, which can be passed to a
HTTP server:

```
var server = require('http').createServer(serve)
```

When using this method, the config properties `npm.host`, `npm.port` and
`npm.autoAuth` do not have an effect, and `~/.npmrc` is not modified.

### `Registry.publishPkgMentions(sbot, mentions, cb(err, msgs))`

Publish the given npm package mentions as one or more messages.

If given exactly one package mention, this will also calculate and add
dependency and version graph information to the message.

### `Registry.expandPkgMentions(sbot, mentions, props, cb(err, mentions))`

For each package mention, fetch the tarball, extract the given
properties from its `package.json` and add them to the mention object.

## Routes

In addition to the npm registry routes, ssb-npm-registry's web server (and
`respond` method) serve the following additional routes:

### `/-/prebuild/:name` - Prebuild blobs

`name` should be the name of a blob in the format
`{name}-v{version}-{runtime}-v{abi}-{platform}{libc}-{arch}.tar.gz`.

This route looks up mentions for blobs with the given name prefixed by
`"prebuild:"`. If the name maps to exactly one blob, the route redirects to the
local ssb-ws URL for that blob.

Example:

- npm installs leveldown v1.9.0 on node v57 on linux, arm
- [`prebuild-install`][] fetches `http://localhost:8043/-/prebuild/leveldown-v1.9.0-node-v57-linux-arm.tar.gz`
- `ssb-npm-registry` queries mentions of name `prebuild:leveldown-v1.9.0-node-v57-linux-arm.tar.gz`
  and then redirects to `http://localhost:8989/blobs/get/&wSehVYRREEqZhZgpMk82CHcXVNcPqXDacgj3Tit7TMc=.sha256`

[`prebuild-install`]: https://github.com/prebuild/prebuild-install

### Message scope

Requests to the registry server can be scoped to a message by prefixing the request pathname with a directory part with a url-encoded message id. You can make such requests by including that prefix in the registry URL. i.e. `npm --registry=http://localhost:8043/<MsgIdEnc>/ ...`

If a request is scoped to a message, the registry server will answer the request using information contained in that message or messages that it links to (recursively), instead of by using `sbot`'s links indexes. Fetching messages for a message-scoped request will be done using [`ssb-ooo`][] if that sbot plugin is available.

A message-scoped request allows you to install a package without having to replicate the feeds of the authors of the package or its dependencies, since the information needed to install the package is referenced by message id.

[`ssb-ooo`]: %AlNuRW5JCvClmCcdnHVt5vMHegdn43dFw0kCBI1c+CI=.sha256

## Bootstrapping Scuttlebot

This plugin includes a script for securely bootstrapping an npm-installation of scuttlebot from your machine to a peer's machine.

Steps for bootstrapping:

- Find your local IP.
- In your web browser, go to your IP, port 8043 (or other port, if you set
    `config.npm.port`).
- Click the "bootstrap" link.
- Send that URL to your peer.
- Check that your peer sees the same hash on the bootstrap page as you do.
- While you are still online, have your peer run the script on that page.
- When your peer's sbot is running, verify that they have the same hash at
    their `http://localhost:8043/bootstrap` page.
- Proceed with gossip/pub onboarding.

Note about prebuilds: the bootstrap npm registry server script serves prebuilds
as blobs from your npm prebuilds cache directory at `~/.npm/_prebuilds/`.
Therefore, if you use the bootstrap script to install scuttlebot to a machine
with a different architecture or node API, it might not fetch all of the host's
prebuilds. In this case, the new node may have to compile modules, and it may
result in a different bootstrap hash from the node that served the bootstrap
sript.

## License

Copyright (C) 2017 Secure Scuttlebutt Consortium

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.