broadcast-encryption 1.1.1

package/README.md

@@ -0,0 +1,75 @@
+# broadcast-encryption
+
+Distribute encryption keys to a dynamic set of receivers
+
+## Usage
+
+```js
+const core = new Hypercore(storage)
+const broadcast = new BroadcastEncryption(core, { keyPair })
+
+const encryptionKey = Buffer.alloc(32)
+
+// distribute key to everyone
+await broadcast.update(encryptionKey, [peer1, peer2, peer3])
+
+encryptionKey.fill(0xff) // update encryption key
+
+// distribute new key to everyone except peer3
+await broadcast.update(encryptionKey, [peer1, peer2])
+
+await broadcast.get(id) // get the encryption key corresponding to id
+```
+
+## API
+
+#### `const broadcast = new BroadcastEncryption(core, opts)`
+
+Instantiate a new broadcast instance.
+
+`opts` include:
+
+```
+{
+  keyPair, // receiver key pair used for decryption
+  bootstrap // initial key information to use
+}
+```
+
+#### `const current = broadcast.id()`
+
+The current encryption key id.
+
+#### `await broadcast.update(key, recipients)`
+
+Distribute the updated `key` to all members of `recipients`.
+
+#### `const { id, encryptionKey } = await broadcast.get(id)`
+
+Get the encryption key corresponding to `id`.
+
+If `id` is passed as `-1`, the latest encryption key shall be returned.
+
+#### `const encryption = await broadcast.createEncryptionProvider(opts)`
+
+Create a [`HypercoreEncryption`](https://github.com/holepunchto/hypercore-encryption) provider to pass to a hypercore.
+
+#### `broadcast.on('update', (id) => {})`
+
+An `update` event is emitted when a new encryption key is loaded.
+
+#### `const payload = BroadcastEncryption.encrypt(data, recipients)`
+
+Static helper to broadcast encrypt a message.
+
+#### `const data = BroadcastEncryption.decrypt(payload, recipientSecretKey)`
+
+Static helper to decrypt a broadcast encrypted message.
+
+#### `const payload = BroadcastEncryption.verify(payload, data, recipients)`
+
+Static helper to verify a `payload`. Returns true if all members on `recipients` can decrypt `data`.
+
+## License
+
+Apache-2.0

package/index.js

@@ -0,0 +1,291 @@
+const sodium = require('sodium-universal')
+const ReadyResource = require('ready-resource')
+const crypto = require('hypercore-crypto')
+const c = require('compact-encoding')
+const safetyCatch = require('safety-catch')
+const b4a = require('b4a')
+const rrp = require('resolve-reject-promise')
+
+const schema = require('./spec/broadcast-encryption')
+
+const [DEFAULT_NAMESPACE, GENESIS_ENTROPY, NS_NONCE, NS_KEYPAIR_SEED, NS_SYMMETRIC_NONCE] =
+  crypto.namespace('broadcast-encryption', 5)
+
+// ephemeral state
+const nonce = b4a.alloc(sodium.crypto_stream_NONCEBYTES)
+const hash = nonce.subarray(0, sodium.crypto_generichash_BYTES_MIN)
+const secretKey = b4a.alloc(sodium.crypto_box_SECRETKEYBYTES)
+const publicKey = b4a.alloc(sodium.crypto_box_PUBLICKEYBYTES)
+const recipientKey = b4a.alloc(sodium.crypto_box_PUBLICKEYBYTES)
+const symmetricKey = b4a.alloc(sodium.crypto_secretbox_KEYBYTES)
+
+const BroadcastPayload = schema.resolveStruct('@broadcast/payload')
+const BroadcastMessage = schema.resolveStruct('@broadcast/message')
+
+module.exports = class BroadcastEncryption extends ReadyResource {
+  constructor(core, opts = {}) {
+    super()
+
+    this.core = core
+    this.keyPair = opts.keyPair || null
+
+    this._bootstrap = opts.bootstrap || null
+    this._latest = 0
+  }
+
+  async _open() {
+    await this.core.ready()
+
+    this.core.on('append', this.refresh.bind(this))
+  }
+
+  _close() {
+    return this.core.close()
+  }
+
+  id() {
+    return this.core ? this.core.length : 0
+  }
+
+  async refresh() {
+    let key = null
+    try {
+      key = await this._getLatestKey()
+    } catch (err) {
+      safetyCatch(err)
+    }
+
+    if (!key || key.id < this._latest) return
+
+    this._latest = key.id
+    this.emit('update', key.id)
+  }
+
+  async append(payload) {
+    await this._append({ payload, pointer: null })
+    const id = this.core.length
+
+    await this.point(id - 2) // point to previous key
+
+    return id
+  }
+
+  async update(key, recipients) {
+    const payload = await BroadcastEncryption.encrypt(key, recipients)
+    return this.append(payload)
+  }
+
+  async point(to) {
+    // first pointer is null to maintain offset
+    if (to < 0) {
+      return this._append({ pointer: null, payload: null })
+    }
+
+    const [old, current] = await Promise.all([this.get(to), this._getLatestKey()])
+
+    const buffer = encryptPointer(old.encryptionKey, current.encryptionKey, nonce)
+    const pointer = { to: old.id, from: current.id, nonce, buffer }
+
+    return this._append({ payload: null, pointer })
+  }
+
+  async _get(index, opts) {
+    return this.core.get(index, { ...opts, valueEncoding: BroadcastMessage })
+  }
+
+  async _append({ pointer, payload }) {
+    return this.core.append(c.encode(BroadcastMessage, { version: 0, pointer, payload }))
+  }
+
+  async _getLatestKey(opts) {
+    let id = this.core.length
+
+    while (id > 0) {
+      const block = await this._get(id - 1, opts)
+
+      if (block && block.payload) {
+        // use bootstrap if we have it
+        if (this._bootstrap && this._bootstrap.id === id) {
+          return this._bootstrap
+        }
+
+        const key = {
+          id,
+          encryptionKey: this._unpack(block.payload)
+        }
+
+        return key
+      }
+
+      id--
+    }
+
+    return { id: 0, encryptionKey: null }
+  }
+
+  async get(id, opts) {
+    if (id === -1) {
+      return this._getLatestKey()
+    }
+
+    if (id === 0) {
+      return { id: 0, encryptionKey: null }
+    }
+
+    if (this._bootstrap && this._bootstrap.id === id) {
+      return this._bootstrap
+    }
+
+    const block = await this._get(id - 1, opts)
+    if (!block) return null // no key in core
+
+    let encryptionKey = null
+
+    try {
+      encryptionKey = this._unpack(block.payload)
+    } catch (err) {
+      encryptionKey = await this._getByPointer(id)
+      if (!encryptionKey) throw err
+    }
+
+    const key = { id, encryptionKey }
+
+    return key
+  }
+
+  bootstrap(key) {
+    if (!this._bootstrap || this._bootstrap.id < key.id) {
+      this._bootstrap = key
+      this.emit('update', key.id)
+    }
+  }
+
+  async getBootstrap() {
+    return this._getLatestKey()
+  }
+
+  async _getByPointer(target) {
+    const bootstrap = await this._getLatestKey()
+    if (!bootstrap || bootstrap.id < target) return null
+
+    let id = null
+
+    let seq = bootstrap.id
+    let key = bootstrap.encryptionKey
+
+    while (seq > target) {
+      const block = await this._get(seq--)
+
+      if (block.pointer === null) continue
+
+      id = block.pointer.to
+      key = decryptPointer(block.pointer.buffer, block.pointer.nonce, key)
+
+      if (key === null) return null
+    }
+
+    return id === null ? null : key
+  }
+
+  _unpack(block) {
+    if (!this.keyPair) throw new Error('No key pair provided')
+
+    const encryptionKey = BroadcastEncryption.decrypt(block, this.keyPair.secretKey)
+    if (!encryptionKey) throw new Error('Broadcast decryption failed')
+
+    return encryptionKey
+  }
+
+  static PayloadEncoding = BroadcastPayload
+
+  static encrypt(data, recipients) {
+    const seed = crypto.hash([NS_KEYPAIR_SEED, data])
+
+    sodium.crypto_box_seed_keypair(publicKey, secretKey, seed)
+    sodium.crypto_generichash_batch(nonce, [NS_NONCE, publicKey])
+
+    const broadcast = {
+      publicKey,
+      payload: []
+    }
+
+    for (const recipient of recipients) {
+      if (recipient === null) continue
+
+      const enc = b4a.alloc(data.byteLength + sodium.crypto_box_MACBYTES)
+
+      sodium.crypto_sign_ed25519_pk_to_curve25519(recipientKey, recipient)
+      sodium.crypto_box_easy(enc, data, nonce, recipientKey, secretKey)
+
+      broadcast.payload.push(enc)
+    }
+
+    return broadcast
+  }
+
+  static decrypt(broadcast, recipientSecretKey) {
+    const { publicKey, payload } = broadcast
+
+    const data = b4a.alloc(payload[0].byteLength - sodium.crypto_box_MACBYTES)
+
+    sodium.crypto_generichash_batch(nonce, [NS_NONCE, publicKey])
+    sodium.crypto_sign_ed25519_sk_to_curve25519(secretKey, recipientSecretKey)
+
+    try {
+      for (const ciphertext of payload) {
+        if (sodium.crypto_box_open_easy(data, ciphertext, nonce, publicKey, secretKey)) {
+          return data
+        }
+      }
+    } finally {
+      b4a.fill(secretKey, 0)
+    }
+
+    return null
+  }
+
+  static verify(ciphertext, data, recipients) {
+    const seed = crypto.hash([NS_KEYPAIR_SEED, data])
+
+    sodium.crypto_box_seed_keypair(publicKey, secretKey, seed)
+    sodium.crypto_generichash_batch(nonce, [NS_NONCE, publicKey])
+
+    if (!b4a.equals(publicKey, ciphertext.publicKey)) return false
+
+    const expected = b4a.alloc(data.byteLength + sodium.crypto_box_MACBYTES)
+
+    for (const target of recipients) {
+      sodium.crypto_sign_ed25519_pk_to_curve25519(recipientKey, target)
+      sodium.crypto_box_easy(expected, data, nonce, recipientKey, secretKey)
+
+      let found = false
+
+      for (const buffer of ciphertext.payload) {
+        if (b4a.equals(buffer, expected)) {
+          found = true
+          break
+        }
+      }
+
+      if (!found) return false
+    }
+
+    return true
+  }
+}
+
+function encryptPointer(to, from, nonce) {
+  const buffer = b4a.alloc(to.byteLength + sodium.crypto_secretbox_MACBYTES)
+
+  sodium.crypto_generichash_batch(nonce, [NS_SYMMETRIC_NONCE, to])
+  sodium.crypto_secretbox_easy(buffer, to, nonce, from)
+
+  return buffer
+}
+
+function decryptPointer(data, nonce, key) {
+  const buffer = b4a.alloc(data.byteLength - sodium.crypto_secretbox_MACBYTES)
+  if (!sodium.crypto_secretbox_open_easy(buffer, data, nonce, key)) return null
+
+  return buffer
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "broadcast-encryption",
+  "version": "1.1.1",
+  "description": "Distribute encryption keys to a dynamic set of receivers",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "spec/*"
+  ],
+  "scripts": {
+    "format": "prettier --write .",
+    "test": "prettier --check . && node test/*.js"
+  },
+  "keywords": [],
+  "author": "Holepunch Inc.",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "b4a": "^1.7.3",
+    "compact-encoding": "^2.17.0",
+    "hypercore": "^11.18.2",
+    "hyperschema": "^1.16.0",
+    "ready-resource": "^1.2.0",
+    "resolve-reject-promise": "^1.1.0",
+    "safety-catch": "^1.0.2",
+    "sodium-universal": "^5.0.1"
+  },
+  "devDependencies": {
+    "brittle": "^3.19.0",
+    "corestore": "^7.5.0",
+    "hypercore-crypto": "^3.6.1",
+    "prettier": "^3.6.2",
+    "prettier-config-holepunch": "^2.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/holepunchto/broadcast-encryption.git"
+  },
+  "bugs": {
+    "url": "https://github.com/holepunchto/broadcast-encryption/issues"
+  },
+  "homepage": "https://github.com/holepunchto/broadcast-encryption#readme"
+}

package/spec/broadcast-encryption/index.js

@@ -0,0 +1,165 @@
+// This file is autogenerated by the hyperschema compiler
+// Schema Version: 2
+/* eslint-disable camelcase */
+/* eslint-disable quotes */
+/* eslint-disable space-before-function-paren */
+
+const { c } = require('hyperschema/runtime')
+
+const VERSION = 2
+
+// eslint-disable-next-line no-unused-vars
+let version = VERSION
+
+// @broadcast/payload.payload
+const encoding0_1 = c.array(c.buffer)
+
+// @broadcast/payload
+const encoding0 = {
+  preencode(state, m) {
+    c.fixed32.preencode(state, m.publicKey)
+    encoding0_1.preencode(state, m.payload)
+  },
+  encode(state, m) {
+    c.fixed32.encode(state, m.publicKey)
+    encoding0_1.encode(state, m.payload)
+  },
+  decode(state) {
+    const r0 = c.fixed32.decode(state)
+    const r1 = encoding0_1.decode(state)
+
+    return {
+      publicKey: r0,
+      payload: r1
+    }
+  }
+}
+
+// @broadcast/pointer
+const encoding1 = {
+  preencode(state, m) {
+    c.uint.preencode(state, m.to)
+    c.uint.preencode(state, m.from)
+    c.buffer.preencode(state, m.nonce)
+    c.buffer.preencode(state, m.buffer)
+  },
+  encode(state, m) {
+    c.uint.encode(state, m.to)
+    c.uint.encode(state, m.from)
+    c.buffer.encode(state, m.nonce)
+    c.buffer.encode(state, m.buffer)
+  },
+  decode(state) {
+    const r0 = c.uint.decode(state)
+    const r1 = c.uint.decode(state)
+    const r2 = c.buffer.decode(state)
+    const r3 = c.buffer.decode(state)
+
+    return {
+      to: r0,
+      from: r1,
+      nonce: r2,
+      buffer: r3
+    }
+  }
+}
+
+// @broadcast/message.payload
+const encoding2_1 = c.frame(encoding0)
+// @broadcast/message.pointer
+const encoding2_2 = c.frame(encoding1)
+
+// @broadcast/message
+const encoding2 = {
+  preencode(state, m) {
+    c.uint.preencode(state, m.version)
+    state.end++ // max flag is 2 so always one byte
+
+    if (m.payload) encoding2_1.preencode(state, m.payload)
+    if (m.pointer) encoding2_2.preencode(state, m.pointer)
+  },
+  encode(state, m) {
+    const flags = (m.payload ? 1 : 0) | (m.pointer ? 2 : 0)
+
+    c.uint.encode(state, m.version)
+    c.uint.encode(state, flags)
+
+    if (m.payload) encoding2_1.encode(state, m.payload)
+    if (m.pointer) encoding2_2.encode(state, m.pointer)
+  },
+  decode(state) {
+    const r0 = c.uint.decode(state)
+    const flags = c.uint.decode(state)
+
+    return {
+      version: r0,
+      payload: (flags & 1) !== 0 ? encoding2_1.decode(state) : null,
+      pointer: (flags & 2) !== 0 ? encoding2_2.decode(state) : null
+    }
+  }
+}
+
+function setVersion(v) {
+  version = v
+}
+
+function encode(name, value, v = VERSION) {
+  version = v
+  return c.encode(getEncoding(name), value)
+}
+
+function decode(name, buffer, v = VERSION) {
+  version = v
+  return c.decode(getEncoding(name), buffer)
+}
+
+function getEnum(name) {
+  switch (name) {
+    default:
+      throw new Error('Enum not found ' + name)
+  }
+}
+
+function getEncoding(name) {
+  switch (name) {
+    case '@broadcast/payload':
+      return encoding0
+    case '@broadcast/pointer':
+      return encoding1
+    case '@broadcast/message':
+      return encoding2
+    default:
+      throw new Error('Encoder not found ' + name)
+  }
+}
+
+function getStruct(name, v = VERSION) {
+  const enc = getEncoding(name)
+  return {
+    preencode(state, m) {
+      version = v
+      enc.preencode(state, m)
+    },
+    encode(state, m) {
+      version = v
+      enc.encode(state, m)
+    },
+    decode(state) {
+      version = v
+      return enc.decode(state)
+    }
+  }
+}
+
+const resolveStruct = getStruct // compat
+
+module.exports = {
+  resolveStruct,
+  getStruct,
+  getEnum,
+  getEncoding,
+  encode,
+  decode,
+  setVersion,
+  version
+}

package/spec/broadcast-encryption/schema.json

@@ -0,0 +1,84 @@
+{
+  "version": 2,
+  "schema": [
+    {
+      "name": "payload",
+      "namespace": "broadcast",
+      "compact": false,
+      "flagsPosition": -1,
+      "fields": [
+        {
+          "name": "publicKey",
+          "required": true,
+          "type": "fixed32",
+          "version": 1
+        },
+        {
+          "name": "payload",
+          "required": true,
+          "array": true,
+          "type": "buffer",
+          "version": 1
+        }
+      ]
+    },
+    {
+      "name": "pointer",
+      "namespace": "broadcast",
+      "compact": false,
+      "flagsPosition": -1,
+      "fields": [
+        {
+          "name": "to",
+          "required": true,
+          "type": "uint",
+          "version": 1
+        },
+        {
+          "name": "from",
+          "required": true,
+          "type": "uint",
+          "version": 1
+        },
+        {
+          "name": "nonce",
+          "required": true,
+          "type": "buffer",
+          "version": 1
+        },
+        {
+          "name": "buffer",
+          "required": true,
+          "type": "buffer",
+          "version": 2
+        }
+      ]
+    },
+    {
+      "name": "message",
+      "namespace": "broadcast",
+      "compact": false,
+      "flagsPosition": 1,
+      "fields": [
+        {
+          "name": "version",
+          "required": true,
+          "type": "uint",
+          "version": 1
+        },
+        {
+          "name": "payload",
+          "required": false,
+          "type": "@broadcast/payload",
+          "version": 1
+        },
+        {
+          "name": "pointer",
+          "required": false,
+          "type": "@broadcast/pointer",
+          "version": 1
+        }
+      ]
+    }
+  ]
+}