enigma-memory 0.1.18 → 0.1.22

package/packages/vault/src/e2ee.mjs

@@ -0,0 +1,393 @@
+/**
+ * Enigma recipient-to-recipient end-to-end encryption (E2EE), ZK-bound.
+ *
+ * Non-circular ZK binding (v2, supersedes the noteCommit-in-AAD design):
+ * the ciphertext AAD can never commit to the final circuit note, because
+ * note = Poseidon([ownerKey, rho, payloadCommit]) and payloadCommit exists
+ * only AFTER encryption. The binding is therefore staged:
+ *
+ *   1. PRE-ENCRYPTION — noteContext (client-side, Poseidon):
+ *        scopeCommit = Poseidon([fieldFromScope(scope)])
+ *        noteContext = Poseidon([ownerKey, rho, scopeCommit])
+ *      fieldFromScope(scope) = BigInt('0x' + sha256(utf8(scope))) mod r.
+ *      noteContext is known before encryption and is what the AAD binds.
+ *
+ *   2. ENCRYPTION — per-note random DEK (32 bytes, CSPRNG); payload encrypted
+ *      with XChaCha20-Poly1305 under (DEK, random 24-byte nonce). AAD:
+ *        AAD = utf8(SCHEMA) || 0x00 || utf8(scope) || 0x00 || noteContext32BE
+ *      The DEK is wrapped once per recipient with RFC 9180 HPKE base mode
+ *      DHKEM(X25519, HKDF-SHA256) + ChaCha20Poly1305; the same AAD is passed
+ *      to each HPKE seal/open, binding every envelope to (schema, scope,
+ *      noteContext). Recipient keypairs are fresh X25519 keys generated and
+ *      stored independently — NEVER derived from a Solana wallet secret.
+ *
+ *   3. POST-ENCRYPTION — payloadCommit (ZK-facing contract; consumed by the
+ *      action_transition circuit as a private input):
+ *        ctSha256       = sha256(ciphertext)                 // raw 32 bytes
+ *        envelopeSha256 = sha256(canonicalJson(envelopes))   // raw 32 bytes
+ *        payloadCommit  = BigInt('0x' + hex(sha256(
+ *                             utf8('enigma.e2ee.v1')
+ *                             || noteContext32BE              // raw 32 bytes
+ *                             || nonce                        // raw 24 bytes
+ *                             || ctSha256
+ *                             || envelopeSha256))) mod r
+ *      The nonce is INSIDE the commitment, so payloadCommit binds the full
+ *      AEAD parameters, the AAD context (via noteContext), and every
+ *      recipient envelope. r = BN254 scalar field
+ *      0x30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000001.
+ *      canonicalJson sorts object keys recursively and preserves array order
+ *      (envelope order = recipient order given at encryption).
+ *
+ *   4. FINAL NOTE — deriveFinalNote (matches witness.mjs / the circuit):
+ *        note = Poseidon([ownerKey, rho, payloadCommit])
+ *      This is the leaf appended to the note tree; the circuit constrains the
+ *      same relation in both append and revoke modes.
+ *
+ * All field elements cross the API as decimal strings (snarkjs convention);
+ * normalizeFieldElement32 also accepts 0x-hex strings and 32-byte BE bytes.
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+import { CipherSuite, DhkemX25519HkdfSha256, HkdfSha256 } from '@hpke/core';
+import { Chacha20Poly1305 } from '@hpke/chacha20poly1305';
+import { xchacha20poly1305 } from '@noble/ciphers/chacha.js';
+import { x25519 } from '@noble/curves/ed25519.js';
+import { buildPoseidon } from 'circomlibjs';
+
+export const E2EE_SCHEMA = 'enigma.e2ee.v1';
+export const PAYLOAD_COMMIT_DOMAIN = 'enigma.e2ee.v1';
+export const HPKE_WRAP_INFO = 'enigma.e2ee.v1/hpke-wrap';
+
+/** BN254 (alt_bn128) scalar field modulus. */
+export const BN254_SCALAR_FIELD = BigInt(
+  '0x30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000001',
+);
+
+const DEK_BYTES = 32;
+const NONCE_BYTES = 24; // XChaCha20-Poly1305 extended nonce.
+const X25519_KEY_BYTES = 32;
+
+const textEncoder = new TextEncoder();
+
+const poseidonC = await buildPoseidon();
+const poseidonF = poseidonC.F;
+
+/** Poseidon hash over an array of bigint field elements → bigint. */
+export function poseidon(inputs) {
+  return poseidonF.toObject(poseidonC(inputs.map((x) => poseidonF.e(BigInt(x)))));
+}
+
+function sha256(...chunks) {
+  const hash = createHash('sha256');
+  for (const chunk of chunks) hash.update(chunk);
+  return hash.digest();
+}
+
+function toBytes(value, label) {
+  if (value instanceof Uint8Array) return value;
+  if (typeof value === 'string') return textEncoder.encode(value);
+  throw new TypeError(`${label} must be a string or Uint8Array`);
+}
+
+function b64encode(bytes) {
+  return Buffer.from(bytes).toString('base64');
+}
+
+function b64decode(value, label) {
+  if (value instanceof Uint8Array) return value;
+  if (typeof value !== 'string') throw new TypeError(`${label} must be a base64 string`);
+  return new Uint8Array(Buffer.from(value, 'base64'));
+}
+
+function toField(value, label) {
+  let v;
+  try {
+    v = BigInt(value);
+  } catch {
+    throw new TypeError(`${label} must be a field element (bigint/number/decimal string)`);
+  }
+  if (v < 0n || v >= BN254_SCALAR_FIELD) {
+    throw new RangeError(`${label} out of range (< BN254 scalar field r required)`);
+  }
+  return v;
+}
+
+/**
+ * Deterministic JSON: object keys sorted recursively, array order preserved,
+ * no whitespace. Used to hash the recipient envelope set.
+ */
+export function canonicalJson(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+}
+
+/**
+ * Normalize a field element to its canonical 32-byte big-endian form.
+ * Accepts:
+ *   - Uint8Array/Buffer of exactly 32 bytes (already big-endian), or
+ *   - '0x'-prefixed 1..64-hex-char big-endian string, or
+ *   - decimal string of a BN254 field element (< r).
+ */
+export function normalizeFieldElement32(value) {
+  if (value instanceof Uint8Array) {
+    if (value.length !== 32) {
+      throw new RangeError('field element bytes must be exactly 32 bytes');
+    }
+    return new Uint8Array(value);
+  }
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError('field element must be a 32-byte Uint8Array, 0x-hex string, or decimal string');
+  }
+  let v;
+  if (/^0x[0-9a-fA-F]{1,64}$/.test(value) || /^[0-9]+$/.test(value)) {
+    v = BigInt(value);
+  } else {
+    throw new TypeError('field element string must be 0x-hex or decimal');
+  }
+  if (v < 0n || v >= BN254_SCALAR_FIELD) {
+    throw new RangeError('field element out of range (< BN254 scalar field r required)');
+  }
+  const out = new Uint8Array(32);
+  let rest = v;
+  for (let i = 31; i >= 0; i -= 1) {
+    out[i] = Number(rest & 0xffn);
+    rest >>= 8n;
+  }
+  return out;
+}
+
+/** scopeCommit = Poseidon([BigInt('0x' + sha256(utf8(scope))) mod r]) → decimal string. */
+export function deriveScopeCommit(scope) {
+  if (typeof scope !== 'string' || scope.length === 0) {
+    throw new TypeError('scope must be a non-empty string');
+  }
+  const field = BigInt(`0x${sha256(textEncoder.encode(scope)).toString('hex')}`) % BN254_SCALAR_FIELD;
+  return poseidon([field]).toString(10);
+}
+
+/**
+ * noteContext = Poseidon([ownerKey, rho, scopeCommit]) → decimal string.
+ * Computed client-side BEFORE encryption; this is what the payload AAD binds.
+ */
+export function deriveNoteContext({ ownerKey, rho, scope }) {
+  const scopeCommit = deriveScopeCommit(scope);
+  return poseidon([
+    toField(ownerKey, 'ownerKey'),
+    toField(rho, 'rho'),
+    BigInt(scopeCommit),
+  ]).toString(10);
+}
+
+/** AAD = utf8(schema) || 0x00 || utf8(scope) || 0x00 || noteContext32BE. */
+export function deriveAad({ schema = E2EE_SCHEMA, scope, noteContext }) {
+  if (typeof scope !== 'string' || scope.length === 0) {
+    throw new TypeError('scope must be a non-empty string');
+  }
+  const schemaBytes = textEncoder.encode(schema);
+  const scopeBytes = textEncoder.encode(scope);
+  const contextBytes = normalizeFieldElement32(noteContext);
+  const aad = new Uint8Array(schemaBytes.length + 1 + scopeBytes.length + 1 + 32);
+  aad.set(schemaBytes, 0);
+  aad[schemaBytes.length] = 0;
+  aad.set(scopeBytes, schemaBytes.length + 1);
+  aad[schemaBytes.length + 1 + scopeBytes.length] = 0;
+  aad.set(contextBytes, schemaBytes.length + 1 + scopeBytes.length + 1);
+  return aad;
+}
+
+function createSuite() {
+  return new CipherSuite({
+    kem: new DhkemX25519HkdfSha256(),
+    kdf: new HkdfSha256(),
+    aead: new Chacha20Poly1305(),
+  });
+}
+
+/**
+ * Generate a fresh X25519 recipient keypair, independent of any wallet key.
+ * Returns raw 32-byte keys and their base64 forms.
+ */
+export function generateRecipientKeyPair() {
+  const secretKey = x25519.utils.randomSecretKey();
+  const publicKey = x25519.getPublicKey(secretKey);
+  return {
+    secretKey,
+    publicKey,
+    secretKeyB64: b64encode(secretKey),
+    publicKeyB64: b64encode(publicKey),
+  };
+}
+
+/**
+ * ZK-facing payload commitment (see module header for the binding derivation).
+ * Binds noteContext (AAD context), the AEAD nonce, the ciphertext, and the
+ * canonical recipient envelope set. Returns the decimal-string field element.
+ */
+export function derivePayloadCommit({ noteContext, nonceB64, ciphertextB64, envelopes }) {
+  const contextBytes = normalizeFieldElement32(noteContext);
+  const nonce = b64decode(nonceB64, 'nonceB64');
+  if (nonce.length !== NONCE_BYTES) {
+    throw new RangeError('nonce must be 24 bytes (XChaCha20-Poly1305)');
+  }
+  const ciphertext = b64decode(ciphertextB64, 'ciphertextB64');
+  if (!Array.isArray(envelopes)) throw new TypeError('envelopes must be an array');
+  const ctSha256 = sha256(ciphertext);
+  const envelopeSha256 = sha256(textEncoder.encode(canonicalJson(envelopes)));
+  const digest = sha256(
+    textEncoder.encode(PAYLOAD_COMMIT_DOMAIN),
+    contextBytes,
+    nonce,
+    ctSha256,
+    envelopeSha256,
+  );
+  const field = BigInt(`0x${digest.toString('hex')}`) % BN254_SCALAR_FIELD;
+  return field.toString(10);
+}
+
+/**
+ * Final circuit note = Poseidon([ownerKey, rho, payloadCommit]) → decimal
+ * string. Identical relation to witness.mjs buildActionWitness and the
+ * ActionTransition circuit's note well-formedness constraint.
+ */
+export function deriveFinalNote({ ownerKey, rho, payloadCommit }) {
+  return poseidon([
+    toField(ownerKey, 'ownerKey'),
+    toField(rho, 'rho'),
+    toField(payloadCommit, 'payloadCommit'),
+  ]).toString(10);
+}
+
+/**
+ * Encrypt a payload to one or more recipients.
+ *
+ * @param {object} params
+ * @param {string|Uint8Array} params.plaintext
+ * @param {Array<string|Uint8Array>} params.recipients - X25519 public keys (base64 or raw 32B).
+ * @param {string} params.scope - binding scope string (e.g. 'memory/note').
+ * @param {string|Uint8Array} params.noteContext - deriveNoteContext output
+ *   (decimal/0x-hex string or 32B BE); bound into the AAD and payloadCommit.
+ * @returns {{ciphertextB64: string, nonceB64: string,
+ *   envelopes: Array<{recipientPubB64: string, encB64: string, ctB64: string}>,
+ *   payloadCommit: string}}
+ */
+export async function e2eeEncrypt({ plaintext, recipients, scope, noteContext }) {
+  if (!Array.isArray(recipients) || recipients.length === 0) {
+    throw new TypeError('recipients must be a non-empty array of X25519 public keys');
+  }
+  const plaintextBytes = toBytes(plaintext, 'plaintext');
+  const aad = deriveAad({ scope, noteContext });
+  const dek = randomBytes(DEK_BYTES);
+  try {
+    const nonce = randomBytes(NONCE_BYTES);
+    const ciphertext = xchacha20poly1305(new Uint8Array(dek), new Uint8Array(nonce), aad)
+      .encrypt(plaintextBytes);
+
+    const suite = createSuite();
+    const info = textEncoder.encode(HPKE_WRAP_INFO);
+    const envelopes = [];
+    for (const recipient of recipients) {
+      const recipientPub = b64decode(recipient, 'recipient public key');
+      if (recipientPub.length !== X25519_KEY_BYTES) {
+        throw new RangeError('recipient public key must be 32 bytes (X25519)');
+      }
+      const recipientPublicKey = await suite.kem.importKey('raw', recipientPub, true);
+      const sender = await suite.createSenderContext({ recipientPublicKey, info });
+      const wrappedDek = await sender.seal(new Uint8Array(dek), aad);
+      envelopes.push({
+        recipientPubB64: b64encode(recipientPub),
+        encB64: b64encode(new Uint8Array(sender.enc)),
+        ctB64: b64encode(new Uint8Array(wrappedDek)),
+      });
+    }
+
+    const ciphertextB64 = b64encode(ciphertext);
+    const nonceB64 = b64encode(nonce);
+    return {
+      ciphertextB64,
+      nonceB64,
+      envelopes,
+      payloadCommit: derivePayloadCommit({ noteContext, nonceB64, ciphertextB64, envelopes }),
+    };
+  } finally {
+    dek.fill(0);
+  }
+}
+
+/**
+ * Decrypt a payload as one of its recipients.
+ *
+ * @param {object} params
+ * @param {string} params.ciphertextB64
+ * @param {string} params.nonceB64
+ * @param {Array<{recipientPubB64: string, encB64: string, ctB64: string}>} params.envelopes
+ * @param {string|Uint8Array} params.recipientSecretKey - base64 or raw 32B X25519 secret key.
+ * @param {string} params.scope - must match the scope used at encryption (AAD).
+ * @param {string|Uint8Array} params.noteContext - must match encryption (AAD).
+ * @param {string} [params.payloadCommit] - optional; verified when supplied.
+ * @returns {Uint8Array} the plaintext bytes.
+ * @throws if the key has no envelope, the envelope fails HPKE open, the
+ *   payload fails AEAD verification (wrong AAD / tampering), or a supplied
+ *   payloadCommit does not match.
+ */
+export async function e2eeDecrypt({
+  ciphertextB64,
+  nonceB64,
+  envelopes,
+  recipientSecretKey,
+  scope,
+  noteContext,
+  payloadCommit,
+}) {
+  const ciphertext = b64decode(ciphertextB64, 'ciphertextB64');
+  const nonce = b64decode(nonceB64, 'nonceB64');
+  if (nonce.length !== NONCE_BYTES) {
+    throw new RangeError('nonce must be 24 bytes (XChaCha20-Poly1305)');
+  }
+  if (!Array.isArray(envelopes)) throw new TypeError('envelopes must be an array');
+  const secretKey = new Uint8Array(b64decode(recipientSecretKey, 'recipientSecretKey'));
+  let dek;
+  try {
+    if (secretKey.length !== X25519_KEY_BYTES) {
+      throw new RangeError('recipientSecretKey must be 32 bytes (X25519)');
+    }
+    const aad = deriveAad({ scope, noteContext });
+
+    if (payloadCommit !== undefined) {
+      const expected = derivePayloadCommit({ noteContext, nonceB64, ciphertextB64, envelopes });
+      if (expected !== String(payloadCommit)) {
+        throw new Error('payloadCommit mismatch: ciphertext or envelopes were tampered');
+      }
+    }
+
+    const publicKeyB64 = b64encode(x25519.getPublicKey(secretKey));
+    const envelope = envelopes.find((env) => env && env.recipientPubB64 === publicKeyB64);
+    if (!envelope) {
+      throw new Error('no envelope for this recipient key (wrong recipient)');
+    }
+
+    const suite = createSuite();
+    const info = textEncoder.encode(HPKE_WRAP_INFO);
+    const recipientKey = await suite.kem.importKey('raw', secretKey, false);
+    try {
+      const recipient = await suite.createRecipientContext({
+        recipientKey,
+        enc: b64decode(envelope.encB64, 'envelope encB64'),
+        info,
+      });
+      dek = new Uint8Array(await recipient.open(b64decode(envelope.ctB64, 'envelope ctB64'), aad));
+    } catch (err) {
+      throw new Error(`HPKE envelope open failed: ${err.message}`);
+    }
+
+    try {
+      return xchacha20poly1305(dek, nonce, aad).decrypt(ciphertext);
+    } catch (err) {
+      throw new Error(`payload AEAD open failed: ${err.message}`);
+    }
+  } finally {
+    dek?.fill(0);
+    secretKey.fill(0);
+  }
+}