@pryv/encryption 3.10.0

package/src/lib/md5.js

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/**
+ * Minimal, dependency-free MD5 over bytes.
+ *
+ * ⚠ This exists SOLELY to reproduce the OpenSSL EVP_BytesToKey key derivation
+ * used by the legacy `aes-text-base64` decrypt-only method (MD5 is not part of
+ * WebCrypto). MD5 is cryptographically broken — it MUST NOT be used for
+ * anything other than reading pre-existing legacy ciphertext. Do not reach for
+ * it for hashing, integrity, or any new derivation.
+ *
+ * Implements RFC 1321. Operates on and returns `Uint8Array`; no `Buffer`, so it
+ * runs unchanged in the browser and in Node.js.
+ */
+
+function toUint32 (n) { return n >>> 0; }
+function rotl (x, c) { return toUint32((x << c) | (x >>> (32 - c))); }
+
+const S = [
+  7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22,
+  5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20,
+  4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23,
+  6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21
+];
+
+// K[i] = floor(2^32 * abs(sin(i + 1))), precomputed at load.
+const K = new Uint32Array(64);
+for (let i = 0; i < 64; i++) {
+  K[i] = toUint32(Math.floor(Math.abs(Math.sin(i + 1)) * 0x100000000));
+}
+
+/**
+ * Compute the MD5 digest of the given bytes.
+ * @param {Uint8Array} message
+ * @returns {Uint8Array} 16-byte digest.
+ */
+function md5 (message) {
+  const originalLenBits = message.length * 8;
+
+  // Pad: append 0x80, then zeros, until length ≡ 56 (mod 64), then 64-bit length.
+  const paddedLen = ((message.length + 8) >> 6 << 6) + 64;
+  const bytes = new Uint8Array(paddedLen);
+  bytes.set(message);
+  bytes[message.length] = 0x80;
+
+  // 64-bit little-endian bit length (low 32 bits, then high 32 bits).
+  const lenLow = toUint32(originalLenBits);
+  const lenHigh = Math.floor(originalLenBits / 0x100000000) >>> 0;
+  bytes[paddedLen - 8] = lenLow & 0xff;
+  bytes[paddedLen - 7] = (lenLow >>> 8) & 0xff;
+  bytes[paddedLen - 6] = (lenLow >>> 16) & 0xff;
+  bytes[paddedLen - 5] = (lenLow >>> 24) & 0xff;
+  bytes[paddedLen - 4] = lenHigh & 0xff;
+  bytes[paddedLen - 3] = (lenHigh >>> 8) & 0xff;
+  bytes[paddedLen - 2] = (lenHigh >>> 16) & 0xff;
+  bytes[paddedLen - 1] = (lenHigh >>> 24) & 0xff;
+
+  let a0 = 0x67452301;
+  let b0 = 0xefcdab89;
+  let c0 = 0x98badcfe;
+  let d0 = 0x10325476;
+
+  const M = new Uint32Array(16);
+  for (let offset = 0; offset < paddedLen; offset += 64) {
+    for (let j = 0; j < 16; j++) {
+      const k = offset + j * 4;
+      M[j] = toUint32(bytes[k] | (bytes[k + 1] << 8) | (bytes[k + 2] << 16) | (bytes[k + 3] << 24));
+    }
+
+    let A = a0;
+    let B = b0;
+    let C = c0;
+    let D = d0;
+
+    for (let i = 0; i < 64; i++) {
+      let F;
+      let g;
+      if (i < 16) {
+        F = (B & C) | (~B & D);
+        g = i;
+      } else if (i < 32) {
+        F = (D & B) | (~D & C);
+        g = (5 * i + 1) % 16;
+      } else if (i < 48) {
+        F = B ^ C ^ D;
+        g = (3 * i + 5) % 16;
+      } else {
+        F = C ^ (B | (~D >>> 0));
+        g = (7 * i) % 16;
+      }
+      F = toUint32(F + A + K[i] + M[g]);
+      A = D;
+      D = C;
+      C = B;
+      B = toUint32(B + rotl(F, S[i]));
+    }
+
+    a0 = toUint32(a0 + A);
+    b0 = toUint32(b0 + B);
+    c0 = toUint32(c0 + C);
+    d0 = toUint32(d0 + D);
+  }
+
+  const out = new Uint8Array(16);
+  const words = [a0, b0, c0, d0];
+  for (let i = 0; i < 4; i++) {
+    out[i * 4] = words[i] & 0xff;
+    out[i * 4 + 1] = (words[i] >>> 8) & 0xff;
+    out[i * 4 + 2] = (words[i] >>> 16) & 0xff;
+    out[i * 4 + 3] = (words[i] >>> 24) & 0xff;
+  }
+  return out;
+}
+
+module.exports = { md5 };

package/src/methods/aes-256-gcm.js

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/**
+ * Built-in `aes-256-gcm` encryption method.
+ *
+ * Wire format of `content.payload`:
+ *   base64( iv (12 bytes) || ciphertext || gcm-auth-tag (16 bytes) )
+ *
+ * WebCrypto's `subtle.encrypt` appends the 16-byte GCM authentication tag to
+ * the ciphertext it returns, so the payload is simply the random IV followed
+ * by that output, base64-encoded.
+ *
+ * Key material is accepted as a 32-byte `Uint8Array`, a base64 string of 32
+ * bytes, or an already-imported AES-GCM `CryptoKey`.
+ */
+const { bytesToBase64, base64ToBytes } = require('../lib/base64');
+
+const ALGORITHM = 'AES-GCM';
+const IV_LENGTH = 12; // bytes — the recommended GCM nonce length
+const KEY_LENGTH = 32; // bytes — AES-256
+
+/**
+ * Normalise supported key-material shapes into an AES-GCM CryptoKey.
+ * @param {Uint8Array|string|CryptoKey} key
+ * @returns {Promise<CryptoKey>}
+ */
+async function importKey (key) {
+  if (typeof CryptoKey !== 'undefined' && key instanceof CryptoKey) return key;
+
+  let raw;
+  if (key instanceof Uint8Array) {
+    raw = key;
+  } else if (key instanceof ArrayBuffer) {
+    raw = new Uint8Array(key);
+  } else if (typeof key === 'string') {
+    raw = base64ToBytes(key);
+  } else {
+    throw new Error('aes-256-gcm: unsupported key material (expected Uint8Array, base64 string or CryptoKey)');
+  }
+
+  if (raw.length !== KEY_LENGTH) {
+    throw new Error(`aes-256-gcm: key must be ${KEY_LENGTH} bytes, got ${raw.length}`);
+  }
+  return globalThis.crypto.subtle.importKey('raw', raw, ALGORITHM, false, ['encrypt', 'decrypt']);
+}
+
+/**
+ * Encrypt raw bytes into the method's payload byte layout:
+ *   iv (12 bytes) || ciphertext || gcm-auth-tag (16 bytes)
+ * These are exactly the bytes that Base64-decoding a `content.payload` yields.
+ * The input is not mutated.
+ * @param {Uint8Array} bytes - plaintext bytes to encrypt.
+ * @param {Uint8Array|string|CryptoKey} key
+ * @returns {Promise<Uint8Array>}
+ */
+async function encryptBytes (bytes, key) {
+  const cryptoKey = await importKey(key);
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+  const cipherBuffer = await globalThis.crypto.subtle.encrypt({ name: ALGORITHM, iv }, cryptoKey, bytes);
+  const cipherBytes = new Uint8Array(cipherBuffer);
+
+  const out = new Uint8Array(iv.length + cipherBytes.length);
+  out.set(iv, 0);
+  out.set(cipherBytes, iv.length);
+  return out;
+}
+
+/**
+ * Decrypt the method's payload byte layout back into raw plaintext bytes.
+ * Throws on any failure (bad key, tampered tag, truncated input).
+ * @param {Uint8Array} bytes - `iv || ciphertext || gcm-tag`.
+ * @param {Uint8Array|string|CryptoKey} key
+ * @returns {Promise<Uint8Array>}
+ */
+async function decryptBytes (bytes, key) {
+  if (bytes.length <= IV_LENGTH) {
+    throw new Error('aes-256-gcm: payload too short');
+  }
+  const cryptoKey = await importKey(key);
+  const iv = bytes.slice(0, IV_LENGTH);
+  const cipherBytes = bytes.slice(IV_LENGTH);
+  const plainBuffer = await globalThis.crypto.subtle.decrypt({ name: ALGORITHM, iv }, cryptoKey, cipherBytes);
+  return new Uint8Array(plainBuffer);
+}
+
+/**
+ * Encrypt a material object into an event `content`. Thin wrapper over
+ * {@link encryptBytes}: `payload = base64(encryptBytes(utf8(JSON.stringify(material))))`.
+ * @param {Object} material - the object to serialise + encrypt.
+ * @param {Uint8Array|string|CryptoKey} key
+ * @returns {Promise<{ payload: string }>}
+ */
+async function encrypt (material, key) {
+  const plaintext = new TextEncoder().encode(JSON.stringify(material));
+  const out = await encryptBytes(plaintext, key);
+  return { payload: bytesToBase64(out) };
+}
+
+/**
+ * Decrypt an event `content` back into its material object. Thin wrapper over
+ * {@link decryptBytes}. Throws on any failure (bad key, tampered tag, malformed /
+ * truncated payload, or non-JSON plaintext).
+ * @param {{ payload: string }} content
+ * @param {Uint8Array|string|CryptoKey} key
+ * @returns {Promise<Object>}
+ */
+async function decrypt (content, key) {
+  if (content == null || typeof content.payload !== 'string') {
+    throw new Error('aes-256-gcm: content.payload must be a base64 string');
+  }
+  const plainBytes = await decryptBytes(base64ToBytes(content.payload), key);
+  return JSON.parse(new TextDecoder().decode(plainBytes));
+}
+
+module.exports = { encrypt, decrypt, encryptBytes, decryptBytes };

package/src/methods/aes-text-base64.js

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/**
+ * Legacy, decrypt-only `aes-text-base64` method.
+ *
+ * Reads the historical ciphertext format 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 AES key and 16-byte IV are derived from the passphrase STRING and
+ * the salt via OpenSSL's EVP_BytesToKey (MD5, one iteration). The cipher is
+ * AES-256-CBC with PKCS#7 padding, which WebCrypto's `AES-CBC` handles natively.
+ *
+ * Key material for THIS method is the passphrase STRING itself — not base64 of
+ * key bytes (unlike `aes-256-gcm`). See the component README.
+ *
+ * This method is decrypt-only: there is no `encrypt`. It exists to read
+ * pre-existing legacy events; new events must use a modern method.
+ */
+const { base64ToBytes } = require('../lib/base64');
+const { md5 } = require('../lib/md5');
+
+const SALTED_MAGIC = [0x53, 0x61, 0x6c, 0x74, 0x65, 0x64, 0x5f, 0x5f]; // "Salted__"
+const SALT_LENGTH = 8;
+const KEY_LENGTH = 32; // AES-256
+const IV_LENGTH = 16; // CBC block size
+
+/**
+ * OpenSSL EVP_BytesToKey with MD5 and a single hashing chain (count = 1).
+ * @param {Uint8Array} passphrase - UTF-8 bytes of the passphrase string.
+ * @param {Uint8Array} salt - 8 salt bytes.
+ * @returns {{ key: Uint8Array, iv: Uint8Array }}
+ */
+function evpBytesToKey (passphrase, salt) {
+  const needed = KEY_LENGTH + IV_LENGTH;
+  const derived = new Uint8Array(needed);
+  let filled = 0;
+  let block = new Uint8Array(0);
+  while (filled < needed) {
+    const input = new Uint8Array(block.length + passphrase.length + salt.length);
+    input.set(block, 0);
+    input.set(passphrase, block.length);
+    input.set(salt, block.length + passphrase.length);
+    block = md5(input);
+    const take = Math.min(block.length, needed - filled);
+    derived.set(block.subarray(0, take), filled);
+    filled += take;
+  }
+  return { key: derived.slice(0, KEY_LENGTH), iv: derived.slice(KEY_LENGTH, KEY_LENGTH + IV_LENGTH) };
+}
+
+/**
+ * Decrypt a legacy `aes-text-base64` `content` back into its material object.
+ * Throws on any failure (missing/short payload, absent "Salted__" prefix, wrong
+ * passphrase / bad padding, or non-JSON plaintext).
+ * @param {{ payload: string }} content
+ * @param {string} key - the passphrase STRING.
+ * @returns {Promise<Object>}
+ */
+async function decrypt (content, key) {
+  if (content == null || typeof content.payload !== 'string') {
+    throw new Error('aes-text-base64: content.payload must be a base64 string');
+  }
+  if (typeof key !== 'string') {
+    throw new Error('aes-text-base64: key material must be the passphrase string');
+  }
+
+  const blob = base64ToBytes(content.payload);
+  if (blob.length < SALTED_MAGIC.length + SALT_LENGTH + IV_LENGTH) {
+    throw new Error('aes-text-base64: payload too short');
+  }
+  for (let i = 0; i < SALTED_MAGIC.length; i++) {
+    if (blob[i] !== SALTED_MAGIC[i]) {
+      throw new Error('aes-text-base64: missing "Salted__" prefix');
+    }
+  }
+
+  const salt = blob.slice(SALTED_MAGIC.length, SALTED_MAGIC.length + SALT_LENGTH);
+  const ciphertext = blob.slice(SALTED_MAGIC.length + SALT_LENGTH);
+
+  const passphrase = new TextEncoder().encode(key);
+  const { key: keyBytes, iv } = evpBytesToKey(passphrase, salt);
+
+  const cryptoKey = await globalThis.crypto.subtle.importKey('raw', keyBytes, 'AES-CBC', false, ['decrypt']);
+  const plainBuffer = await globalThis.crypto.subtle.decrypt({ name: 'AES-CBC', iv }, cryptoKey, ciphertext);
+  return JSON.parse(new TextDecoder().decode(plainBuffer));
+}
+
+module.exports = { decrypt };

package/src/methods/ecies-aes-256-gcm.js

@@ -0,0 +1,232 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/**
+ * Asymmetric `ecies-aes-256-gcm` method (ECIES over NIST P-256 + AES-256-GCM).
+ *
+ * A sender encrypts to a recipient's PUBLIC key; only the holder of the matching
+ * PRIVATE key can decrypt. This enables sharing an encrypted event with someone
+ * without ever moving a shared secret.
+ *
+ * Wire format of `content.payload` (FROZEN — published in the event-type
+ * registry):
+ *
+ *   base64( ephemeralPublicKey[65, SEC1 uncompressed 0x04||X||Y]
+ *           || iv[12] || ciphertext || gcm-tag[16] )
+ *
+ * Scheme:
+ *   1. Generate an ephemeral P-256 key pair.
+ *   2. ECDH(ephemeral private, recipient public) -> 32-byte shared secret.
+ *   3. HKDF-SHA-256(secret, salt = <empty>, info = ASCII "encrypted/ecies-aes-256-gcm"),
+ *      32 bytes -> AES-256-GCM key.
+ *   4. AES-256-GCM(UTF-8 JSON of the material, key, random 12-byte IV).
+ *      WebCrypto appends the 16-byte tag to the ciphertext it returns.
+ *
+ * Key material (see the component README):
+ *   - decrypt: recipient PRIVATE key as a CryptoKey (ECDH), a JWK (has `d`), or
+ *     base64 / Uint8Array PKCS#8.
+ *   - encrypt: recipient PUBLIC key as a CryptoKey, a JWK (no `d`), a raw
+ *     65-byte Uint8Array (SEC1 uncompressed) or its base64.
+ *   - either operation also accepts a `{ publicKey, privateKey }` pair object
+ *     holding any of the above; the side the operation needs is picked.
+ */
+const { bytesToBase64, base64ToBytes } = require('../lib/base64');
+
+const CURVE = 'P-256';
+const ALGORITHM = { name: 'ECDH', namedCurve: CURVE };
+const INFO = 'encrypted/ecies-aes-256-gcm';
+const EPH_PUB_LENGTH = 65; // SEC1 uncompressed: 0x04 || X(32) || Y(32)
+const IV_LENGTH = 12;
+const GCM_TAG_LENGTH = 16;
+
+/**
+ * Mint a fresh recipient key pair as exportable JWK objects.
+ * @returns {Promise<{ publicKey: Object, privateKey: Object }>}
+ */
+async function generateKeyPair () {
+  const subtle = globalThis.crypto.subtle;
+  const pair = await subtle.generateKey(ALGORITHM, true, ['deriveBits']);
+  return {
+    publicKey: await subtle.exportKey('jwk', pair.publicKey),
+    privateKey: await subtle.exportKey('jwk', pair.privateKey)
+  };
+}
+
+/**
+ * Normalise any accepted key-material shape into an ECDH CryptoKey.
+ * @param {*} material - CryptoKey, JWK, raw/PKCS#8 Uint8Array, base64 string, or a `{ publicKey, privateKey }` pair.
+ * @param {'encrypt'|'decrypt'} usage - `encrypt` needs the PUBLIC key, `decrypt` the PRIVATE key.
+ * @returns {Promise<CryptoKey>}
+ */
+async function normalizeKey (material, usage) {
+  if (usage !== 'encrypt' && usage !== 'decrypt') {
+    throw new Error(`ecies-aes-256-gcm: unknown usage "${usage}"`);
+  }
+  if (material == null) {
+    throw new Error('ecies-aes-256-gcm: key material is required');
+  }
+  const wantPrivate = usage === 'decrypt';
+  const subtle = globalThis.crypto.subtle;
+
+  // Pair object: pick the side the operation needs.
+  if (isPair(material)) {
+    const side = wantPrivate ? material.privateKey : material.publicKey;
+    if (side == null) {
+      throw new Error(`ecies-aes-256-gcm: pair object has no ${wantPrivate ? 'privateKey' : 'publicKey'}`);
+    }
+    return normalizeKey(side, usage);
+  }
+
+  // Already a CryptoKey — trust it.
+  if (typeof CryptoKey !== 'undefined' && material instanceof CryptoKey) {
+    return material;
+  }
+
+  // JWK object.
+  if (typeof material === 'object' && !(material instanceof Uint8Array) &&
+      !(material instanceof ArrayBuffer) && material.kty != null) {
+    const isPrivateJwk = material.d != null;
+    if (wantPrivate && !isPrivateJwk) {
+      throw new Error('ecies-aes-256-gcm: decrypt requires a private key (JWK with "d")');
+    }
+    return subtle.importKey('jwk', material, ALGORITHM, false, wantPrivate ? ['deriveBits'] : []);
+  }
+
+  // Raw bytes: PKCS#8 for private, SEC1 raw (65 bytes) for public.
+  let bytes;
+  if (material instanceof Uint8Array) {
+    bytes = material;
+  } else if (material instanceof ArrayBuffer) {
+    bytes = new Uint8Array(material);
+  } else if (typeof material === 'string') {
+    bytes = base64ToBytes(material);
+  } else {
+    throw new Error('ecies-aes-256-gcm: unsupported key material');
+  }
+
+  if (wantPrivate) {
+    return subtle.importKey('pkcs8', bytes, ALGORITHM, false, ['deriveBits']);
+  }
+  if (bytes.length !== EPH_PUB_LENGTH || bytes[0] !== 0x04) {
+    throw new Error('ecies-aes-256-gcm: public key must be a 65-byte SEC1 uncompressed point (0x04 || X || Y)');
+  }
+  return subtle.importKey('raw', bytes, ALGORITHM, false, []);
+}
+
+/**
+ * Derive the AES-256-GCM key from an ECDH shared secret via HKDF-SHA-256.
+ * @param {Uint8Array} secret - the 32-byte ECDH shared secret.
+ * @param {string[]} usages
+ * @returns {Promise<CryptoKey>}
+ */
+async function deriveAesKey (secret, usages) {
+  const subtle = globalThis.crypto.subtle;
+  const hkdfKey = await subtle.importKey('raw', secret, 'HKDF', false, ['deriveBits']);
+  const aesBits = await subtle.deriveBits(
+    { name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(0), info: new TextEncoder().encode(INFO) },
+    hkdfKey,
+    256
+  );
+  return subtle.importKey('raw', new Uint8Array(aesBits), 'AES-GCM', false, usages);
+}
+
+/**
+ * Encrypt raw bytes to the recipient's public key, producing the method's
+ * payload byte layout:
+ *   ephemeralPublicKey[65] || iv[12] || ciphertext || gcm-tag[16]
+ * These are exactly the bytes that Base64-decoding a `content.payload` yields.
+ * The input is not mutated.
+ * @param {Uint8Array} bytes - plaintext bytes to encrypt.
+ * @param {*} key - recipient public key in any accepted shape (or a pair object).
+ * @returns {Promise<Uint8Array>}
+ */
+async function encryptBytes (bytes, key) {
+  const subtle = globalThis.crypto.subtle;
+  const recipientPublic = await normalizeKey(key, 'encrypt');
+
+  const ephemeral = await subtle.generateKey(ALGORITHM, true, ['deriveBits']);
+  const secretBits = await subtle.deriveBits({ name: 'ECDH', public: recipientPublic }, ephemeral.privateKey, 256);
+  const aesKey = await deriveAesKey(new Uint8Array(secretBits), ['encrypt']);
+
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+  const cipherBuffer = await subtle.encrypt({ name: 'AES-GCM', iv }, aesKey, bytes);
+  const cipherBytes = new Uint8Array(cipherBuffer);
+
+  const ephRaw = new Uint8Array(await subtle.exportKey('raw', ephemeral.publicKey));
+
+  const out = new Uint8Array(ephRaw.length + iv.length + cipherBytes.length);
+  out.set(ephRaw, 0);
+  out.set(iv, ephRaw.length);
+  out.set(cipherBytes, ephRaw.length + iv.length);
+  return out;
+}
+
+/**
+ * Decrypt the method's payload byte layout back into raw plaintext bytes with
+ * the recipient's private key. Throws on any failure (short input, bad key,
+ * tampered tag).
+ * @param {Uint8Array} bytes - `ephemeralPublicKey[65] || iv[12] || ciphertext || gcm-tag[16]`.
+ * @param {*} key - recipient private key in any accepted shape (or a pair object).
+ * @returns {Promise<Uint8Array>}
+ */
+async function decryptBytes (bytes, key) {
+  const subtle = globalThis.crypto.subtle;
+  if (bytes.length < EPH_PUB_LENGTH + IV_LENGTH + GCM_TAG_LENGTH) {
+    throw new Error('ecies-aes-256-gcm: payload too short');
+  }
+
+  const ephRaw = bytes.slice(0, EPH_PUB_LENGTH);
+  const iv = bytes.slice(EPH_PUB_LENGTH, EPH_PUB_LENGTH + IV_LENGTH);
+  const cipherBytes = bytes.slice(EPH_PUB_LENGTH + IV_LENGTH);
+
+  const recipientPrivate = await normalizeKey(key, 'decrypt');
+  const ephemeralPublic = await subtle.importKey('raw', ephRaw, ALGORITHM, false, []);
+  const secretBits = await subtle.deriveBits({ name: 'ECDH', public: ephemeralPublic }, recipientPrivate, 256);
+  const aesKey = await deriveAesKey(new Uint8Array(secretBits), ['decrypt']);
+
+  const plainBuffer = await subtle.decrypt({ name: 'AES-GCM', iv }, aesKey, cipherBytes);
+  return new Uint8Array(plainBuffer);
+}
+
+/**
+ * Encrypt a material object to the recipient's public key. Thin wrapper over
+ * {@link encryptBytes}: `payload = base64(encryptBytes(utf8(JSON.stringify(material))))`.
+ * @param {Object} material - the object to serialise + encrypt.
+ * @param {*} key - recipient public key in any accepted shape (or a pair object).
+ * @returns {Promise<{ payload: string }>}
+ */
+async function encrypt (material, key) {
+  const plaintext = new TextEncoder().encode(JSON.stringify(material));
+  const out = await encryptBytes(plaintext, key);
+  return { payload: bytesToBase64(out) };
+}
+
+/**
+ * Decrypt an event `content` with the recipient's private key. Thin wrapper over
+ * {@link decryptBytes}. Throws on any failure (missing/short payload, bad key,
+ * tampered tag, non-JSON).
+ * @param {{ payload: string }} content
+ * @param {*} key - recipient private key in any accepted shape (or a pair object).
+ * @returns {Promise<Object>}
+ */
+async function decrypt (content, key) {
+  if (content == null || typeof content.payload !== 'string') {
+    throw new Error('ecies-aes-256-gcm: content.payload must be a base64 string');
+  }
+  const plainBytes = await decryptBytes(base64ToBytes(content.payload), key);
+  return JSON.parse(new TextDecoder().decode(plainBytes));
+}
+
+/**
+ * @param {*} m
+ * @returns {boolean} true when `m` is a `{ publicKey, privateKey }` pair object (not a JWK).
+ */
+function isPair (m) {
+  return m != null && typeof m === 'object' && m.kty == null &&
+    !(m instanceof Uint8Array) && !(m instanceof ArrayBuffer) &&
+    (typeof CryptoKey === 'undefined' || !(m instanceof CryptoKey)) &&
+    (m.publicKey != null || m.privateKey != null);
+}
+
+module.exports = { encrypt, decrypt, encryptBytes, decryptBytes, generateKeyPair, normalizeKey };

package/src/methods/index.js

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/**
+ * Registry of built-in encryption methods, keyed by their method name (the
+ * suffix of an `encrypted/<method>` event type).
+ */
+const aes256gcm = require('./aes-256-gcm');
+const aesTextBase64 = require('./aes-text-base64');
+const eciesAes256gcm = require('./ecies-aes-256-gcm');
+
+module.exports = {
+  'aes-256-gcm': aes256gcm,
+  'aes-text-base64': aesTextBase64,
+  'ecies-aes-256-gcm': eciesAes256gcm
+};

package/test/aes-256-gcm.test.js

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, expect */
+
+const aes = require('../src/methods/aes-256-gcm');
+const { base64ToBytes, bytesToBase64 } = require('../src/lib/base64');
+const vector = require('./fixtures/aes-256-gcm.json');
+
+describe('[ENCA] aes-256-gcm method', function () {
+  describe('[ENCAV] fixed test vector', function () {
+    it('[ENCAVA] payload byte-layout matches iv || subtle-ciphertext (deterministic vector)', async function () {
+      // Rebuild the payload independently, with the SAME fixed key + IV, using raw
+      // WebCrypto — proves the committed vector is byte-exact and format-stable.
+      const keyBytes = base64ToBytes(vector.keyBase64);
+      const iv = base64ToBytes(vector.ivBase64);
+      const key = await globalThis.crypto.subtle.importKey('raw', keyBytes, 'AES-GCM', false, ['encrypt', 'decrypt']);
+      const pt = new TextEncoder().encode(vector.plaintextJson);
+      const cipherBuf = await globalThis.crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, pt);
+      const cipherBytes = new Uint8Array(cipherBuf);
+      const out = new Uint8Array(iv.length + cipherBytes.length);
+      out.set(iv, 0);
+      out.set(cipherBytes, iv.length);
+      expect(bytesToBase64(out)).to.equal(vector.payload);
+    });
+
+    it('[ENCAVB] decrypt() of the committed vector yields the exact plaintext object', async function () {
+      const material = await aes.decrypt({ payload: vector.payload }, vector.keyBase64);
+      expect(material).to.deep.equal(vector.plaintextObject);
+    });
+  });
+
+  describe('[ENCAR] round-trips (random IV)', function () {
+    const rawKey = base64ToBytes(vector.keyBase64);
+
+    it('[ENCARA] encrypt then decrypt returns the original material (Uint8Array key)', async function () {
+      const material = { type: 'note/txt', content: 'round trip', extra: [1, 2, 3] };
+      const content = await aes.encrypt(material, rawKey);
+      expect(content).to.have.property('payload').that.is.a('string');
+      const back = await aes.decrypt(content, rawKey);
+      expect(back).to.deep.equal(material);
+    });
+
+    it('[ENCARB] two encryptions of the same material produce different payloads (random IV)', async function () {
+      const material = { type: 'note/txt', content: 'nonce check' };
+      const a = await aes.encrypt(material, rawKey);
+      const b = await aes.encrypt(material, rawKey);
+      expect(a.payload).to.not.equal(b.payload);
+    });
+
+    it('[ENCARC] accepts a base64 string key', async function () {
+      const material = { type: 'note/txt', content: 'string key' };
+      const content = await aes.encrypt(material, vector.keyBase64);
+      const back = await aes.decrypt(content, vector.keyBase64);
+      expect(back).to.deep.equal(material);
+    });
+
+    it('[ENCARD] accepts a CryptoKey', async function () {
+      const cryptoKey = await globalThis.crypto.subtle.importKey('raw', rawKey, 'AES-GCM', false, ['encrypt', 'decrypt']);
+      const material = { type: 'note/txt', content: 'crypto key' };
+      const content = await aes.encrypt(material, cryptoKey);
+      const back = await aes.decrypt(content, cryptoKey);
+      expect(back).to.deep.equal(material);
+    });
+  });
+
+  describe('[ENCAN] negative cases (must reject)', function () {
+    const rawKey = base64ToBytes(vector.keyBase64);
+
+    it('[ENCANA] wrong key fails authentication', async function () {
+      const wrong = new Uint8Array(32).fill(9);
+      let threw = false;
+      try {
+        await aes.decrypt({ payload: vector.payload }, wrong);
+      } catch (e) { threw = true; }
+      expect(threw).to.equal(true);
+    });
+
+    it('[ENCANB] truncated payload rejects', async function () {
+      const truncated = vector.payload.slice(0, 20);
+      let threw = false;
+      try {
+        await aes.decrypt({ payload: truncated }, rawKey);
+      } catch (e) { threw = true; }
+      expect(threw).to.equal(true);
+    });
+
+    it('[ENCANC] corrupted auth tag rejects', async function () {
+      const bytes = base64ToBytes(vector.payload);
+      bytes[bytes.length - 1] ^= 0xff; // flip the last tag byte
+      let threw = false;
+      try {
+        await aes.decrypt({ payload: bytesToBase64(bytes) }, rawKey);
+      } catch (e) { threw = true; }
+      expect(threw).to.equal(true);
+    });
+
+    it('[ENCAND] key of wrong length rejects', async function () {
+      const short = new Uint8Array(16).fill(1);
+      let threw = false;
+      try {
+        await aes.encrypt({ type: 'a', content: 'b' }, short);
+      } catch (e) { threw = true; }
+      expect(threw).to.equal(true);
+    });
+  });
+});