npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ssb-keys

v8.5.0

Published

keyfile operations for ssb

Downloads

1,457

Readme

SSB-Keys

supplies key loading and other cryptographic functions needed in secure-scuttlebutt apps.

var ssbKeys = require("ssb-keys");

// Load or create keys in this way:
var keys = ssbKeys.loadOrCreateSync("<path-to-file>");
/* keys =>
  {
    "curve": "ed25519",
    "public": "cFVodZoKwLcmXbM6UeASdl8+7+Uo8PNOuFnlcqk7qUc=.ed25519",
    "private": "lUqlXYxjkM0/ljtGnwoM0CfP6ORA2DKZnzsQ4dJ1tKJwVWh1mgrAtyZdszpR4BJ2Xz7v5Sjw8064WeVyqTupRw==.ed25519",
    "id": "@cFVodZoKwLcmXbM6UeASdl8+7+Uo8PNOuFnlcqk7qUc=.ed25519"
  }
*/

// `.generate()` is useful for testing purposes.
var keys = ssbKeys.generate();
/* keys =>
  {
    "curve": "ed25519",
    "public": "YSa2zbx07RNKQrrFX1vS5mFN+Pbnul61hd9GGymao1o=.ed25519",
    "private": "XhEkyFWb0TkhRU5t/yDTCI6Q9gwhsJM/SpL02UUwVtZhJrbNvHTtE0pCusVfW9LmYU349ue6XrWF30YbKZqjWg==.ed25519",
    "id": "@YSa2zbx07RNKQrrFX1vS5mFN+Pbnul61hd9GGymao1o=.ed25519"
  }
*/

// hmac_key` is a shared secret between two peers used to authenticate the sent
// data and can be an empty 32-byte Buffer:
var hmac_key = Buffer.alloc(32);
// Or a random Crypto buffer:
var hmac_key = crypto.randomBytes(32);
// Or a 32-byte Buffer as base-64 string:
var hmac_key = Buffer.from("7b6m0wZtYR0TevSgeNstWZUZam3IIG2B").toString(
  "base64"
);

// The `hmac_key` is a fixed value that applies to _THIS_ signature and is used
// to authenticate the data, `k` is the sender keys
var obj = ssbKeys.signObj(k, hmac_key, { foo: "bar" });
/* obj =>
  {
    "foo": "bar",
    "signature": "H39taOYa2emULWa1YDEaoLJBrbZ2GHsuVA6VsE9A1hbtpMcWpqXmZisH+nItx8BQR6JOO58K/uohMJkCrUKABQ==.sig.ed25519"
  }
*/

// Share your `hmac_key` with the message receiver so it can verify it.
ssbKeys.verifyObj(k, hmac_key, obj); // => true

api

keys

in the below methods, keys is an object of the following form:

{
  "curve": "ed25519",
  "public": "<base64_public_key>.ed25519",
  "private": "<base64_private_key>.ed25519",
  "id": "@<base64_public_key>.ed25519"
}

The format of the id feed is described in the protocol guide - keys and identities

when stored in a file, the file also contains a comment warning the reader about safe private key security. Comment lines are prefixed with # after removing them the result is valid JSON.

hash (data, encoding) => id

Returns the sha256 hash of a given data. If encoding is not provided then it is assumed to be binary.

getTag (ssb_id) => tag

The SSB ids contain a tag at the end. This function returns it. So if you have a string like @gaQw6zD4pHrg8zmrqku24zTSAINhRg=.ed25519 this function would return ed25519. This is useful as SSB start providing features for different encryption methods and cyphers.

loadOrCreateSync (filename) => keys

Load a file containing the your private key. the file will also contain a comment with a warning about keeping the file secret.

Works in the browser, or stores the keys is localStorage in the browser. (web apps should be hosted a secure way, for example web-bootloader) In the browser, the filename is used as the localStorage key. (note: web workers do not support localStorage, so the browser storage localtion will likely be changed to indexeddb in the future)

If the file does not exist it will be created. there is also variations and parts loadOrCreate (async), load, create createSync loadSync. But since you only need to load once, using the combined function is easiest.

keys is an object as described in keys section.

loadOrCreate (filename, cb)

If a sync file access method is not available, loadOrCreate can be called with a callback. that callback will be called with cb(null, keys). If loading the keys errored, new keys are created.

generate(curve, seed, feedFormat) => keys

generate a key, with optional seed (which should be a 32 byte buffer, but can be a string of any length which is then converted to a 32 byte buffer).

curve defaults to ed25519 (and no other type is currently supported)

feedFormat can be either classic, bendybutt-v1, gabbygrove-v1, buttwoo-v1, or indexed-v1. By default it's "classic".

keys is an object as described in keys section. keys.id is an @ sigil ID in the case of classic feed format and it's an SSB URI otherwise.

sign(keys, hmac_key?, str)

signs a string str, and returns the signature string.

verify(keys, sig, hmac_key?, str)

verifies a signature sig of the original content str by the author known by keys.

signObj(keys, hmac_key?, obj)

signs a javascript object, and then adds a signature property to it.

If hmac_key is provided, the object is hmaced before signing, which means it cannot be verified without the correct hmac_key. If each way that signatures are used in your application use a different hmac key, it means that a signature intended for one use cannot be reused in another (chosen protocol attack)

The fine details of the signature format are described in the protocol guide

verifyObj(keys, hmac_key?, obj)

verify a signed object. hmac_key must be the same value as passed to signObj.

box(content, recipients) => boxed

encrypt a message content to many recipients. msg will be JSON encoded, then encrypted with private-box

recipients must be an array of feed ids. your own feed id should be included.

the encryption format is described in the protocol guide - encrypting

unbox (boxed, keys) => content

decrypt a message encrypted with box. If the boxed successfully decrypted, the parsed JSON is returned, if not, undefined is returned.

the decryption process is described in the protocol guide - decrypting

unboxKey (boxed, keys) => msg_key

extract the msg_key used to encrypt this message, or null if it cannot be decrypted. the msg_key if not null, can then be passed to unboxBody

unboxBody (boxed, msg_key) => content

decrypt a message content with a msg_key. returns the plaintext message content or null if this is not the correct msg_key. The purpose of unboxBody and unboxKey is so support messages that are shared then later revealed.

secretBox (obj, key) => boxed

symmetrically encrypt an object with key (a buffer)

secretUnbox (boxed, key) => obj

symmetrically decrypt an object with key (a buffer)

ssbSecretKeyToPrivateBoxSecret(keys)

Convert from the ed25519 secret key (ssb secret key type) to the curve25519 key type that is used by private-box.

LICENSE

MIT