@pryv/encryption 3.10.0

package/README.md

@@ -0,0 +1,256 @@
+# @pryv/encryption
+
+Client-side encryption and decryption of [Pryv.io](https://pryv.com) events.
+
+Events are encrypted **on the client** before they are sent to a Pryv.io core,
+and decrypted **on the client** after they are read back. The core stores and
+serves the encrypted form and never sees the key or the plaintext.
+
+An encrypted event keeps its envelope in plaintext and moves the sensitive
+`type` / `content` into an opaque payload:
+
+```jsonc
+{
+  "id": "ck…",
+  "streamIds": ["journal"],
+  "time": 1700000000,
+  "type": "encrypted/aes-256-gcm",
+  "content": { "payload": "…base64…", "keyRef": "journal-2026" }
+}
+```
+
+## Install
+
+```bash
+npm install @pryv/encryption
+```
+
+Requires Node.js >= 20 or a modern browser — it uses the standard WebCrypto API
+(`globalThis.crypto.subtle`) and has no runtime dependencies.
+
+## Usage
+
+```js
+const { EventsCipher, Keyring } = require('@pryv/encryption');
+
+// A Keyring holds key material and can defer to async resolvers.
+// Key material may be raw bytes (Uint8Array), a base64 string, or a CryptoKey.
+const keyring = new Keyring({ 'journal-2026': keyMaterial });
+
+// Optional: resolvers are tried, in registration order, when the store misses.
+keyring.use(async (method, keyRef, hint) => fetchKeySomehow(keyRef) /* or null */);
+
+const cipher = new EventsCipher(keyring, {
+  // optional; default is silent
+  onDecryptError: (event, error) => console.warn('could not decrypt', event.id, error)
+});
+
+// Encrypt before writing to a Pryv.io connection:
+const encrypted = await cipher.encryptEvent(
+  { streamIds: ['journal'], type: 'note/txt', content: 'a private note' },
+  { method: 'aes-256-gcm', keyRef: 'journal-2026' }
+);
+
+// Decrypt after reading:
+const decrypted = await cipher.decryptEvent(encrypted);
+// decrypted.type === 'note/txt', decrypted.content === 'a private note'
+// decrypted.decryptedFrom === encrypted (the original, untouched)
+
+// Batch, and streaming (forEachEvent) helpers:
+const all = await cipher.decryptEvents(events);
+const onEvent = cipher.wrapForEachEvent((event) => { /* receives decrypted events */ });
+
+// Recover the stored (encrypted) form of a decrypted event, e.g. before an update:
+const stored = cipher.stripDecrypted(decrypted); // === encrypted
+
+// Update an encrypted event: re-encrypt the new material, send it as the update
+// (updates are always full re-encryptions — see Limitations):
+const update = await cipher.encryptEventContent(
+  { type: 'note/txt', content: 'the edited note' },
+  { method: 'aes-256-gcm', keyRef: 'journal-2026' }
+);
+await conn.api([{ method: 'events.update', params: { id: stored.id, update } }]);
+```
+
+### Keyring
+
+- `new Keyring({ keyRef: material, … })` — seed the key/value store.
+- `keyring.set(keyRef, material)` — add/replace a key.
+- `keyring.use(resolver)` — append an async resolver
+  `(method, keyRef, hint) => material | null`.
+- `keyring.getKeyFor(method, keyRef, hint)` — resolve material: the store is
+  consulted first (by `keyRef`), then resolvers in registration order; the first
+  non-null result wins, otherwise `null`.
+
+### Decryption is non-destructive
+
+`decryptEvent` never throws and never drops an event:
+
+- If the event `type` is not `encrypted/<registered-method>`, the **same event
+  reference** is returned untouched.
+- On **any** failure — no key, a resolver throwing, a wrong key / tampered tag,
+  a malformed payload, or plaintext that is not JSON with `type` and `content` —
+  the **same event reference** is returned, and `onDecryptError(event, error)`
+  is called when provided.
+- On success a **new** object is returned: the envelope fields are preserved,
+  `type` / `content` are the decrypted values, and `decryptedFrom` points back
+  at the original encrypted event.
+
+`encryptEvent`, in contrast, **throws** on an unknown method or a missing key.
+
+### Methods
+
+Each method interprets **key material** in its own way — a keyring simply stores
+whatever material a method expects and hands it back untouched. The three
+built-in methods are:
+
+#### `aes-256-gcm` (symmetric, encrypt + decrypt)
+
+AES-256 in GCM mode. `content.payload` is `base64(iv ‖ ciphertext ‖ gcm-tag)`
+where the IV is 12 random bytes and the tag is the 16-byte GCM authentication
+tag. **Key material** is the 32 raw key bytes, accepted as a `Uint8Array`, a
+**base64 string of those 32 bytes**, or an AES-GCM `CryptoKey`.
+
+#### `aes-text-base64` (legacy, **decrypt-only**)
+
+Reads the historical ciphertext produced by
+`CryptoJS.AES.encrypt(text, passphrase).toString()` — the OpenSSL "salted"
+envelope `base64("Salted__" ‖ salt[8] ‖ AES-256-CBC(text, key, iv))`. The
+32-byte key and 16-byte IV are derived from the passphrase and salt via
+OpenSSL's `EVP_BytesToKey` (MD5, one iteration); the cipher is AES-256-CBC with
+PKCS#7 padding.
+
+**Key material for this method is the passphrase STRING itself** — *not* base64
+of key bytes (unlike `aes-256-gcm`). Put the passphrase directly into the
+keyring:
+
+```js
+const keyring = new Keyring({ 'legacy-2019': 'the original passphrase' });
+```
+
+This method has **no `encrypt`**: it exists only to read pre-existing legacy
+events, so `encryptEvent` / `encryptEventContent` throw for it. New events should
+use a modern method. (MD5 — required only to reproduce the legacy key
+derivation — is vendored internally; it is broken and is used for nothing else.)
+
+#### `ecies-aes-256-gcm` (asymmetric, encrypt + decrypt)
+
+ECIES over NIST P-256 with AES-256-GCM. A sender encrypts to a recipient's
+**public** key; only the holder of the matching **private** key can decrypt — so
+an encrypted event can be shared without ever moving a shared secret.
+
+`content.payload` is
+`base64(ephemeralPublicKey[65] ‖ iv[12] ‖ ciphertext ‖ gcm-tag[16])`, where the
+ephemeral public key is a fresh P-256 point in SEC1 uncompressed form
+(`0x04 ‖ X ‖ Y`). The AES-256-GCM key is
+`HKDF-SHA-256(ECDH(ephemeral, recipient), salt = <empty>, info = "encrypted/ecies-aes-256-gcm")`.
+
+**Key material** (each operation picks the side it needs):
+
+- to **encrypt** — the recipient PUBLIC key as a `CryptoKey`, a JWK (no `d`), a
+  raw 65-byte `Uint8Array` (SEC1 uncompressed) or its base64;
+- to **decrypt** — the recipient PRIVATE key as a `CryptoKey` (ECDH), a JWK
+  (has `d`), or base64 / `Uint8Array` PKCS#8;
+- either operation also accepts a `{ publicKey, privateKey }` pair object holding
+  any of the shapes above.
+
+Mint a key pair (exportable JWK objects) with the method's `generateKeyPair()`:
+
+```js
+const { methods } = require('@pryv/encryption');
+const { publicKey, privateKey } = await methods['ecies-aes-256-gcm'].generateKeyPair();
+
+// sender only needs the public key:
+const senderRing = new Keyring({ 'alice': publicKey });
+const enc = await senderCipher.encryptEvent(plain, { method: 'ecies-aes-256-gcm', keyRef: 'alice' });
+
+// alice decrypts with her private key (in her own keyring):
+const aliceRing = new Keyring({ 'alice': privateKey });
+const dec = await aliceCipher.decryptEvent(enc);
+```
+
+### Encrypted attachments
+
+An event's attached files are encrypted with the **same method and key as the
+event's `content`**, and stored as **raw binary in the method's payload byte
+layout** — i.e. exactly the bytes that Base64-decoding a `content.payload` would
+yield, but **without** the Base64 wrapping:
+
+- `aes-256-gcm` — `iv[12] ‖ ciphertext ‖ gcm-tag[16]`
+- `ecies-aes-256-gcm` — `ephemeralPublicKey[65] ‖ iv[12] ‖ ciphertext ‖ gcm-tag[16]`
+
+Two `EventsCipher` helpers move raw bytes:
+
+```js
+// Encrypt the file bytes with the SAME method/key as the event content:
+const cipherBytes = await cipher.encryptAttachmentData(fileBytes, {
+  method: 'aes-256-gcm', keyRef: 'journal-2026'
+});
+
+// Upload cipherBytes as the file body (isomorphic — a Blob works in Node >= 20
+// and the browser):
+const blob = new Blob([cipherBytes], { type: 'application/octet-stream' });
+const created = (await conn.createEventWithFileFromBuffer(encryptedEvent, blob, 'secret.bin')).event;
+
+// Download the raw bytes and decrypt them against the event they belong to:
+const att = created.attachments[0];
+const url = conn.endpoint + 'events/' + created.id + '/' + att.id + '?readToken=' + att.readToken;
+const downloaded = new Uint8Array(await (await fetch(url)).arrayBuffer());
+const fileBytesBack = await cipher.decryptAttachmentData(created, downloaded);
+```
+
+- `encryptAttachmentData(bytes, { method, keyRef, hint })` → `Uint8Array` —
+  resolves the key exactly like `encryptEventContent`. The input is not mutated.
+- `decryptAttachmentData(event, bytes)` → `Uint8Array` — derives the method from
+  the event's `encrypted/<method>` type and the key from its `content.keyRef` /
+  `content.hint`. `event` may be the encrypted event **or** an already-decrypted
+  one (carrying `decryptedFrom`); the encrypted form is used either way.
+
+**Throw asymmetry.** Unlike the passive, never-throw event decryption
+(`decryptEvent`), attachment decryption is an **explicit request** and
+**throws** on any failure (event not encrypted, unknown method, a method with no
+byte support, a missing key, or bad / tampered / truncated bytes). Both helpers
+throw on error, matching `encryptEvent`.
+
+**The legacy `aes-text-base64` method has no byte support** — there are no known
+legacy encrypted attachments, so it exposes neither `encryptBytes` nor
+`decryptBytes`, and both attachment helpers throw for it.
+
+The core stores the (already-encrypted) file verbatim and reports its **encrypted**
+size on `attachments[0].size` — it never sees the key or the plaintext.
+
+### Custom methods
+
+Register or override a method with:
+
+```js
+cipher.registerMethod('my-method', {
+  encrypt: async (material, key) => ({ payload: /* … */ }),
+  decrypt: async (content, key) => material,
+  // optional — enable encrypted attachments for this method; each returns the
+  // raw payload-layout / plaintext bytes as a Uint8Array:
+  encryptBytes: async (bytes, key) => /* Uint8Array */,
+  decryptBytes: async (bytes, key) => /* Uint8Array */
+});
+```
+
+`encryptBytes` / `decryptBytes` are optional; when present they must be
+functions (validated on registration). A method without them cannot encrypt or
+decrypt attachments.
+
+## Limitations
+
+- **Updates are full re-encryptions.** There is no partial/streaming update of
+  an encrypted `content`; changing it means encrypting the new value and
+  replacing the event's `content`.
+- **The server cannot query encrypted content.** Because `type` and `content`
+  are opaque to the core, server-side filtering, type queries, aggregation and
+  full-text search do not apply to encrypted fields. Envelope fields
+  (`streamIds`, `time`, …) stay in plaintext and remain queryable.
+- **Key management is the application's responsibility.** This library never
+  transmits, persists or derives keys; losing a key means losing access to the
+  data it protected.
+
+## License
+
+[BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@pryv/encryption",
+  "version": "3.10.0",
+  "description": "Client-side encryption and decryption of Pryv.io events",
+  "keywords": [
+    "Pryv",
+    "Pryv.io",
+    "Encryption",
+    "Decryption",
+    "Privacy"
+  ],
+  "homepage": "https://github.com/pryv/lib-js/tree/master/components/pryv-encryption#readme",
+  "bugs": {
+    "url": "https://github.com/pryv/lib-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/pryv/lib-js.git"
+  },
+  "license": "BSD-3-Clause",
+  "author": "Pryv <info@pryv.com> (https://pryv.com)",
+  "main": "src/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/EventsCipher.js

@@ -0,0 +1,259 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/**
+ * Encrypts and decrypts Pryv.io events.
+ *
+ * An encrypted event carries `type: "encrypted/<method>"` and a
+ * `content: { payload, keyRef?, hint? }`. All other envelope fields
+ * (id, streamIds, time, created, …) stay in plaintext.
+ *
+ * Decryption is defensive: any failure leaves the event untouched (the exact
+ * same reference is returned) and, when configured, is reported through
+ * `onDecryptError` — a failed decryption never throws and never drops an event.
+ * Encryption, by contrast, throws on error.
+ *
+ * Attachments are handled by the byte helpers `encryptAttachmentData` /
+ * `decryptAttachmentData`. An attachment is encrypted with the SAME method and
+ * key as its event's content, stored as the method's raw payload byte layout
+ * (WITHOUT Base64). Unlike passive event decryption, attachment decryption is an
+ * explicit request and THROWS on failure.
+ */
+const Keyring = require('./Keyring');
+const builtinMethods = require('./methods');
+
+const ENCRYPTED_TYPE_PREFIX = 'encrypted/';
+
+class EventsCipher {
+  /**
+   * @param {Keyring} keyring
+   * @param {Object} [options]
+   * @param {(event: Object, error: Error) => void} [options.onDecryptError] called on any decryption failure. Default: silent.
+   */
+  constructor (keyring, options = {}) {
+    if (!(keyring instanceof Keyring)) {
+      throw new Error('EventsCipher requires a Keyring');
+    }
+    this.keyring = keyring;
+    this.onDecryptError = (options && options.onDecryptError) || null;
+    // Clone the built-ins so registerMethod() never mutates the shared map.
+    this._methods = Object.assign({}, builtinMethods);
+  }
+
+  /**
+   * Register (or override) an encryption method. `decrypt` is required;
+   * `encrypt` is optional (a decrypt-only method supports reading existing
+   * encrypted events but cannot produce new ones).
+   * @param {string} name
+   * @param {{ decrypt: Function, encrypt?: Function }} method
+   * @returns {EventsCipher} this, for chaining.
+   */
+  registerMethod (name, method) {
+    if (!method || typeof method.decrypt !== 'function' ||
+        (method.encrypt != null && typeof method.encrypt !== 'function') ||
+        (method.encryptBytes != null && typeof method.encryptBytes !== 'function') ||
+        (method.decryptBytes != null && typeof method.decryptBytes !== 'function')) {
+      throw new Error('registerMethod expects a { decrypt } function and optional { encrypt, encryptBytes, decryptBytes } functions');
+    }
+    this._methods[name] = method;
+    return this;
+  }
+
+  /**
+   * Encrypt event material into the `{ type, content }` an implementer passes to
+   * an `events.create` / `events.update` call. Only the material's `type` and
+   * `content` are encrypted; any other fields are ignored. Throws on unknown or
+   * decrypt-only method, or on a missing key. The input is not mutated.
+   * @param {Object} material - `{ type, content, ... }` (same shape decryptEvent restores).
+   * @param {Object} params
+   * @param {string} params.method
+   * @param {string} [params.keyRef]
+   * @param {*} [params.hint]
+   * @returns {Promise<{ type: string, content: { payload: string, keyRef?: string, hint?: * } }>}
+   */
+  async encryptEventContent (material, params = {}) {
+    const { method: methodName, keyRef, hint } = params;
+    const method = this._methods[methodName];
+    if (!method) {
+      throw new Error(`Unknown encryption method: ${methodName}`);
+    }
+    if (typeof method.encrypt !== 'function') {
+      throw new Error(`Method "${methodName}" is decrypt-only and cannot encrypt`);
+    }
+    const key = await this.keyring.getKeyFor(methodName, keyRef, hint);
+    if (key == null) {
+      throw new Error(`No key available for method "${methodName}"${keyRef != null ? ` (keyRef "${keyRef}")` : ''}`);
+    }
+
+    const source = { type: material.type, content: material.content };
+    const content = await method.encrypt(source, key);
+    if (keyRef != null) content.keyRef = keyRef;
+    if (hint != null) content.hint = hint;
+
+    return { type: ENCRYPTED_TYPE_PREFIX + methodName, content };
+  }
+
+  /**
+   * Encrypt a plain event. Throws on unknown method or missing key.
+   * @param {Object} plainEvent
+   * @param {Object} params
+   * @param {string} params.method
+   * @param {string} [params.keyRef]
+   * @param {*} [params.hint]
+   * @returns {Promise<Object>} a new encrypted event (input is not mutated).
+   */
+  async encryptEvent (plainEvent, params = {}) {
+    const { type, content } = await this.encryptEventContent(plainEvent, params);
+    const encrypted = Object.assign({}, plainEvent);
+    encrypted.type = type;
+    encrypted.content = content;
+    return encrypted;
+  }
+
+  /**
+   * Decrypt a single event. Never throws.
+   * - Non-encrypted or unregistered-method events are returned untouched (same ref).
+   * - On any failure the original event is returned (same ref) and
+   *   `onDecryptError(event, error)` is called when configured.
+   * - On success a NEW object is returned with restored `type`/`content`,
+   *   preserved envelope fields, and a `decryptedFrom` back-reference.
+   * @param {Object} event
+   * @returns {Promise<Object>}
+   */
+  async decryptEvent (event) {
+    const methodName = methodNameFromType(event && event.type);
+    if (methodName == null) return event;
+    const method = this._methods[methodName];
+    if (!method) return event;
+
+    try {
+      const content = event.content || {};
+      const key = await this.keyring.getKeyFor(methodName, content.keyRef, content.hint);
+      if (key == null) {
+        throw new Error(`No key available for method "${methodName}"`);
+      }
+      const material = await method.decrypt(content, key);
+      if (material == null || material.type == null || material.content == null) {
+        throw new Error('Decrypted payload is missing "type" or "content"');
+      }
+      return Object.assign({}, event, material, { decryptedFrom: event });
+    } catch (error) {
+      if (this.onDecryptError) this.onDecryptError(event, error);
+      return event;
+    }
+  }
+
+  /**
+   * Decrypt an array of events. Never throws; failures pass through untouched.
+   * @param {Object[]} events
+   * @returns {Promise<Object[]>}
+   */
+  async decryptEvents (events) {
+    return Promise.all(events.map((event) => this.decryptEvent(event)));
+  }
+
+  /**
+   * Wrap a `forEachEvent`-style callback so each event is decrypted before it
+   * is forwarded to the user callback.
+   * @param {(event: Object) => *} callback
+   * @returns {(event: Object) => Promise<*>}
+   */
+  wrapForEachEvent (callback) {
+    return async (event) => {
+      const decrypted = await this.decryptEvent(event);
+      return callback(decrypted);
+    };
+  }
+
+  /**
+   * Encrypt raw attachment bytes with the SAME method and key an event's
+   * `content` uses. The result is the method's raw payload byte layout (exactly
+   * the bytes Base64-decoding a `content.payload` would yield, WITHOUT Base64) —
+   * upload it verbatim as the file's binary body. Like `encryptEventContent`,
+   * this THROWS on an unknown method, a method without byte support, or a missing
+   * key. The input bytes are not mutated.
+   * @param {Uint8Array} bytes - raw attachment bytes to encrypt.
+   * @param {Object} params
+   * @param {string} params.method
+   * @param {string} [params.keyRef]
+   * @param {*} [params.hint]
+   * @returns {Promise<Uint8Array>} raw payload-layout bytes.
+   */
+  async encryptAttachmentData (bytes, params = {}) {
+    const { method: methodName, keyRef, hint } = params;
+    const method = this._methods[methodName];
+    if (!method) {
+      throw new Error(`Unknown encryption method: ${methodName}`);
+    }
+    if (typeof method.encryptBytes !== 'function') {
+      throw new Error(`Method "${methodName}" does not support attachment (byte) encryption`);
+    }
+    const key = await this.keyring.getKeyFor(methodName, keyRef, hint);
+    if (key == null) {
+      throw new Error(`No key available for method "${methodName}"${keyRef != null ? ` (keyRef "${keyRef}")` : ''}`);
+    }
+    return method.encryptBytes(bytes, key);
+  }
+
+  /**
+   * Decrypt raw attachment bytes that belong to `event`. The method is derived
+   * from the event's `encrypted/<method>` type and the key from its
+   * `content.keyRef` / `content.hint` — the SAME material used for its content.
+   *
+   * `event` may be the encrypted event OR an already-decrypted one (carrying a
+   * `decryptedFrom` back-reference); the encrypted form is used either way.
+   *
+   * Unlike the passive, never-throw event decryption (`decryptEvent`),
+   * attachment decryption is an EXPLICIT request and THROWS on failure (event
+   * not encrypted, unknown method, no byte support, missing key, bad key /
+   * tampered / truncated bytes).
+   * @param {Object} event - the (encrypted or decrypted) event the attachment belongs to.
+   * @param {Uint8Array} bytes - raw payload-layout bytes downloaded from the core.
+   * @returns {Promise<Uint8Array>} raw plaintext bytes.
+   */
+  async decryptAttachmentData (event, bytes) {
+    const source = this.stripDecrypted(event);
+    const methodName = methodNameFromType(source && source.type);
+    if (methodName == null) {
+      throw new Error('Event is not encrypted (type is not "encrypted/<method>")');
+    }
+    const method = this._methods[methodName];
+    if (!method) {
+      throw new Error(`Unknown encryption method: ${methodName}`);
+    }
+    if (typeof method.decryptBytes !== 'function') {
+      throw new Error(`Method "${methodName}" does not support attachment (byte) decryption`);
+    }
+    const content = (source && source.content) || {};
+    const key = await this.keyring.getKeyFor(methodName, content.keyRef, content.hint);
+    if (key == null) {
+      throw new Error(`No key available for method "${methodName}"${content.keyRef != null ? ` (keyRef "${content.keyRef}")` : ''}`);
+    }
+    return method.decryptBytes(bytes, key);
+  }
+
+  /**
+   * Return the original encrypted event a decrypted event came from, or the
+   * event itself when it was never decrypted.
+   * @param {Object} event
+   * @returns {Object}
+   */
+  stripDecrypted (event) {
+    if (event && event.decryptedFrom != null) return event.decryptedFrom;
+    return event;
+  }
+}
+
+/**
+ * Extract the method name from an `encrypted/<method>` type, or null.
+ * @param {*} type
+ * @returns {?string}
+ */
+function methodNameFromType (type) {
+  if (typeof type !== 'string' || !type.startsWith(ENCRYPTED_TYPE_PREFIX)) return null;
+  const name = type.slice(ENCRYPTED_TYPE_PREFIX.length);
+  return name.length > 0 ? name : null;
+}
+
+module.exports = EventsCipher;

package/src/Keyring.js

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/**
+ * A key store with a pluggable chain of asynchronous resolvers.
+ *
+ * Resolution order for `getKeyFor(method, keyRef, hint)`:
+ *   1. the key/value store, looked up by `keyRef`;
+ *   2. each registered resolver, in registration order — the first one that
+ *      returns a non-null value wins.
+ *
+ * Key material is stored and returned as-is (raw `Uint8Array`, base64 string
+ * or `CryptoKey`); interpreting it is the encryption method's responsibility.
+ */
+class Keyring {
+  /**
+   * @param {Object<string, (Uint8Array|string|CryptoKey)>} [keys] initial keyRef → material map.
+   */
+  constructor (keys = {}) {
+    this._store = new Map();
+    if (keys != null) {
+      for (const keyRef of Object.keys(keys)) {
+        this._store.set(keyRef, keys[keyRef]);
+      }
+    }
+    this._resolvers = [];
+  }
+
+  /**
+   * Add or replace a key in the store.
+   * @param {string} keyRef
+   * @param {Uint8Array|string|CryptoKey} material
+   * @returns {Keyring} this, for chaining.
+   */
+  set (keyRef, material) {
+    this._store.set(keyRef, material);
+    return this;
+  }
+
+  /**
+   * Register an asynchronous resolver, tried after the store misses.
+   * @param {(method: string, keyRef: ?string, hint: *) => Promise<?(Uint8Array|string|CryptoKey)>} resolver
+   * @returns {Keyring} this, for chaining.
+   */
+  use (resolver) {
+    if (typeof resolver !== 'function') {
+      throw new Error('Keyring.use() expects a function');
+    }
+    this._resolvers.push(resolver);
+    return this;
+  }
+
+  /**
+   * Resolve key material for a given method / keyRef / hint.
+   * The store is consulted first, then each resolver in registration order.
+   * @param {string} method
+   * @param {?string} keyRef
+   * @param {*} [hint]
+   * @returns {Promise<?(Uint8Array|string|CryptoKey)>} resolved material, or null.
+   */
+  async getKeyFor (method, keyRef, hint) {
+    if (keyRef != null && this._store.has(keyRef)) {
+      return this._store.get(keyRef);
+    }
+    for (const resolver of this._resolvers) {
+      const material = await resolver(method, keyRef, hint);
+      if (material != null) return material;
+    }
+    return null;
+  }
+}
+
+module.exports = Keyring;

package/src/index.js

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/**
+ * @pryv/encryption — client-side encryption and decryption of Pryv.io events.
+ *
+ * - `Keyring`: a key store with a pluggable chain of async key resolvers.
+ * - `EventsCipher`: encrypts / decrypts events using registered methods.
+ * - `methods`: the built-in encryption methods (`aes-256-gcm`,
+ *   `aes-text-base64`, `ecies-aes-256-gcm`).
+ */
+const EventsCipher = require('./EventsCipher');
+const Keyring = require('./Keyring');
+const methods = require('./methods');
+
+module.exports = { EventsCipher, Keyring, methods };

package/src/lib/base64.js

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/**
+ * Isomorphic base64 helpers built on the standard `btoa`/`atob` globals,
+ * which are available in browsers and in Node.js (>= 16). No `Buffer`, so the
+ * same code path runs unchanged in both environments.
+ */
+
+/**
+ * Encode raw bytes to a standard (non-URL-safe) base64 string.
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+function bytesToBase64 (bytes) {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Decode a standard base64 string to raw bytes.
+ * @param {string} b64
+ * @returns {Uint8Array}
+ */
+function base64ToBytes (b64) {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+module.exports = { bytesToBase64, base64ToBytes };