# envelope-js

> new private message format for ssb

Latest version **1.3.2** (published 2022-07-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install envelope-js
pnpm add envelope-js
yarn add envelope-js
bun add envelope-js
```

## 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 | 1.3.2 |
| Published | 2022-07-14 |
| First published | 2020-03-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 41.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 13 |
| Author | Dominic Tarr @EMovhfIrFk4NihAKnRNhrfRaqIhBv1Wj8pTxJNgvCCY=.ed25519 |
| Maintainers | arj03, chereseeriepa, happy0, staltz, pfrazee, mixmix, cel, christianbundy |

## Links

- npm: https://www.npmjs.com/package/envelope-js
- Repository: https://github.com/ssbc/envelope-js
- Issues: https://github.com/ssbc/envelope-js/issues
- npm.io page: https://npm.io/package/envelope-js

## Dependencies (5)

- [ssb-bfe](https://npm.io/package/ssb-bfe.md) ^3.3.0
- [buffer-xor](https://npm.io/package/buffer-xor.md) ^2.0.2
- [futoin-hkdf](https://npm.io/package/futoin-hkdf.md) ^1.5.1
- [envelope-spec](https://npm.io/package/envelope-spec.md) ^1.0.0
- [sodium-universal](https://npm.io/package/sodium-universal.md) ^3.1.0

## Recent versions

- 1.3.2 (latest) — 2022-07-14
- 1.3.1 — 2022-06-27
- 1.3.0 — 2022-05-22
- 1.2.0 — 2021-10-28
- 1.1.2 — 2021-08-16
- 1.1.1 — 2021-08-09
- 1.1.0 — 2021-08-02
- 1.0.0 — 2020-09-14
- 0.1.3 — 2020-08-28
- 0.1.2 — 2020-06-22
- 0.1.1 — 2020-06-02
- 0.1.0 — 2020-06-01
- 0.0.2 — 2020-03-05
- 0.0.1 — 2020-03-05

## README

# envelope-js

A javascript tool for cryptographically "boxing" and "unboxing" messages
following the [envelope spec](https://github.com/ssbc/envelope-spec).

envelope supports encryption to individuals and groups

## Example Usage

```js
var { box, unbox, CloakedMsgId } = require('envelope-js')
```

...

## API

### `box(plain_text, feed_id, prev_msg_id, msg_key, recp_keys) => ciphertext`

where:
- `plain_text` *Buffer* is the content to be "enveloped"
- `feed_id` *Buffer* is a type-format-key (TFK) encoded value for the feed authoring a message
- `prev_msg_id` *Buffer* is a TFK encoded value of the id of last message of this feeds chain
- `msg_key` *Buffer* a randomised 32 Bytes which will be the unique key for this message
- `recps_keys` *Array* is a collection of items of form `{ key, scheme }`, where
    - `key` *Buffer* is the key the particular recipient
    - `scheme` *String|Buffer* is the type of key / the key management scheme for this recipient


### `unbox(ciphertext, feed_id, prev_msg_id, trial_keys, max_attempts) => plain_text | null`

where:
- `ciphertext` *Buffer* is envelope
- `feed_id` *Buffer* is a type-format-key (TFK) encoded value for the feed authoring a message
- `prev_msg_id` *Buffer* is a TFK encoded value of the id of last message of this feeds chain
- `trial_keys` *Array* is a collection of items of form `{ key, scheme }`, where
    - `key` *Buffer* is the key the particular recipient
    - `scheme` *String|Buffer* is the type of key / the key management scheme for this recipient
- `max_attempts` *Integer* (default: 8) how many key_slots you want to assume the envelope has
- `plain_text` *Buffer* the envelope contents

NOTE: we also expose `unboxKey` and `unboxBody` for convenience.

### `DeriveSecret(feed_id, prev_msg_id) => derive`

Used for taking a `msg_key` (the one-time key for a particular envelope) and deriving other keys used in the envelope (e.g. `read_key`)

where:
- `feed_id` *Buffer* is a TFK encoded id for the feed the envelope is part of
- `prev_msg_id` *Buffer* is a TFK encoded id for the message prior to one where our envelope is
    - NOTE if this is the first message, then the K part of `prev_msg_id`'s TFK is a zero-filled Buffer.
- `derive(key, labels) => new_key` *function* where:
    - `key` *Buffer* is a seed key which we're going to derive from
    - `labels` *Array* is a an array of *String*s which help define a derivation


### `new CloakedMsgId(public_msg_id, read_key) => cloakedMsgId`

Determine a cloaked message id for a published message following the `envelope-spec/cloaked_msg_id/README.md`

where:
- `public_msg_id` *Buffer* is the id of a enveloped message that's been published (it has an id as it's part of a feed / chain)
- `read_key` *Buffer* is the read capability (NOT the `msg_key`) for this message envelope
- `cloakedMsgId` is an instance with methods:
  - `toBuffer() => Buffer` which returns the cloaked id key as a Buffer
  - `toString(encoding) => String` which returns the cloaked id key as a Buffer (encoding defaults to 'base64')
  - `mock() => cloakedMsgId` a method for testing. populates the id with random content. if using this, instantiate with no args.


### `slp.encode(info) => Buffer`

where `info` is an Array of Buffers.

This is "short length-prefixed encoding", see https://github.com/ssbc/envelope-spec/blob/master/encoding/slp.md

...

## License

MIT

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