@lazyapps/encryption 0.0.0-init.0

package/README.md

@@ -0,0 +1,394 @@
+# @lazyapps/encryption
+
+Field-level encryption for event-sourced applications. Encrypts sensitive
+fields in events before storage and decrypts them on read, with envelope
+encryption (DEK/KEK separation), pluggable key stores, and built-in support
+for crypto-shredding (GDPR "right to be forgotten").
+
+## Quick Start
+
+```javascript
+import {
+  createEncryption,
+  defineEncryptionSchema,
+  inMemoryKeyStore,
+} from '@lazyapps/encryption';
+import { start } from '@lazyapps/bootstrap';
+
+const schema = defineEncryptionSchema({
+  CUSTOMER_CREATED: {
+    'payload.name': { context: 'personal', subjectField: 'aggregateId' },
+    'payload.email': { context: 'personal', subjectField: 'aggregateId' },
+  },
+});
+
+const encryption = createEncryption({
+  schema,
+  keyStore: inMemoryKeyStore({
+    personal: crypto.randomBytes(32),
+  }),
+  contexts: {
+    personal: { roles: ['admin', 'support', 'self'] },
+  },
+});
+
+start({
+  encryption,
+  commands: { /* ... */ },
+});
+```
+
+Bootstrap automatically wires encryption into the event store (encrypt on
+write, decrypt on replay) and event bus (encrypt before publish). No changes
+to aggregates, read model projections, or command handlers are needed.
+
+## How It Works
+
+### Envelope Encryption
+
+Each sensitive field is encrypted with its own **Data Encryption Key (DEK)**,
+unique per subject (e.g., per customer). DEKs are wrapped (encrypted) by a
+**Key Encryption Key (KEK)** managed by the key store. This two-layer design
+means:
+
+- Rotating a KEK does not require re-encrypting all data
+- Deleting a subject's DEKs renders their data permanently unreadable
+  (crypto-shredding)
+- Different encryption contexts can have different KEKs with different access
+  policies
+
+### Encrypted Field Format
+
+Encrypted fields in events are replaced with an envelope object:
+
+```javascript
+{
+  __encrypted: true,
+  alg: 'aes-256-gcm',
+  iv: '<base64>',
+  data: '<base64>',
+  tag: '<base64>',
+  ctx: 'personal',      // encryption context name
+  kid: '<subjectId>',   // which subject's DEK was used
+  kv: 1                 // DEK version
+}
+```
+
+**Type coercion note**: All values are converted to strings before encryption
+(`String(value)`). After decryption, fields always contain strings regardless of
+their original type. For example, the number `42` becomes the string `"42"`, and
+the boolean `true` becomes `"true"`. Applications must handle type coercion when
+consuming decrypted values.
+
+## Key Store Tiers
+
+The `keyStore` parameter controls where KEKs live and how DEKs are
+wrapped/unwrapped. Three tiers are available, each suited to different
+deployment scenarios.
+
+### Tier 1: In-Memory (Development / Testing)
+
+KEKs are provided directly as buffers. DEKs are stored in a local Map.
+Suitable for unit tests and single-process development.
+
+```javascript
+import { inMemoryKeyStore } from '@lazyapps/encryption';
+
+const keyStore = inMemoryKeyStore({
+  personal: crypto.randomBytes(32),
+  financial: crypto.randomBytes(32),
+});
+```
+
+### Tier 2: MongoDB (Self-Hosted Production)
+
+KEKs are derived from a root secret via HMAC-SHA256. DEKs are stored in a
+MongoDB collection. Suitable for deployments where a dedicated KMS is not
+available.
+
+```javascript
+import { mongoKeyStore } from '@lazyapps/encryption';
+
+const keyStore = mongoKeyStore({
+  url: process.env.MONGO_URL,
+  rootSecret: process.env.ENCRYPTION_ROOT_SECRET,
+  database: 'encryption-keys',
+  dekCollection: 'deks',
+});
+```
+
+**Security note**: The root secret is a single point of compromise. Any service
+with the root secret can derive all KEKs. Use environment variables or Docker
+secrets to provide it, and consider Tier 3 for production deployments with
+compliance requirements.
+
+### Tier 3: Vault / OpenBao (Production)
+
+KEKs live inside HashiCorp Vault (or OpenBao, the Apache 2.0 fork). All key
+wrapping and unwrapping happens inside Vault via the transit secrets engine.
+Services never see KEKs — they authenticate with AppRole credentials and Vault
+policies control which encryption contexts each service can access.
+
+```javascript
+import { vaultKeyStore, appRole } from '@lazyapps/encryption';
+
+const keyStore = vaultKeyStore({
+  vaultUrl: process.env.VAULT_ADDR,
+  authMethod: appRole({
+    roleId: process.env.VAULT_ROLE_ID,
+    secretId: process.env.VAULT_SECRET_ID,
+  }),
+});
+```
+
+Optionally, DEK metadata can be persisted to MongoDB instead of in-memory
+storage using the `dekBackend` option:
+
+```javascript
+const keyStore = vaultKeyStore({
+  vaultUrl: process.env.VAULT_ADDR,
+  authMethod: appRole({ roleId, secretId }),
+  dekBackend: {
+    url: process.env.MONGO_URL,
+    database: 'encryption-keys',
+    collection: 'deks',
+  },
+});
+```
+
+You can also authenticate with a token directly (useful for dev mode):
+
+```javascript
+const keyStore = vaultKeyStore({
+  vaultUrl: 'http://localhost:8200',
+  token: 'dev-root-token',
+});
+```
+
+## Schema Definition
+
+The encryption schema declares which event fields to encrypt, which encryption
+context protects them, and which event field identifies the subject (the entity
+whose data is being protected).
+
+```javascript
+import { defineEncryptionSchema } from '@lazyapps/encryption';
+
+const schema = defineEncryptionSchema({
+  CUSTOMER_CREATED: {
+    'payload.name': { context: 'personal', subjectField: 'aggregateId' },
+    'payload.location': { context: 'personal', subjectField: 'aggregateId' },
+  },
+  ORDER_CREATED: {
+    'payload.text': {
+      context: 'order-details',
+      subjectField: 'payload.customerId',
+    },
+  },
+});
+```
+
+- **Field paths** use dot notation (e.g., `'payload.name'`)
+- **`context`**: Names the encryption context (must match a key in the key
+  store and the `contexts` configuration)
+- **`subjectField`**: Dot-notation path to the field in the event that
+  identifies the data subject. The DEK is keyed by this value.
+
+## Encryption Contexts
+
+Contexts define access control — which roles can decrypt fields protected by
+each context:
+
+```javascript
+const contexts = {
+  personal: { roles: ['admin', 'support', 'self'] },
+  financial: { roles: ['admin', 'finance'] },
+  'order-details': { roles: ['admin', 'support', 'sales'] },
+};
+```
+
+The `'self'` role is special: it grants access when the requesting identity
+matches the data subject.
+
+## Bootstrap Integration
+
+Pass the `encryption` promise to `start()`. Bootstrap handles wiring:
+
+```javascript
+const encryption = createEncryption({ schema, keyStore, contexts });
+
+// Command processor: wraps eventStore (encrypt) and eventBus (encrypt)
+start({
+  encryption,
+  commands: { eventStore: mongodb(...), eventBus: rabbitMq(...), ... },
+});
+
+// Read model: wraps storage (encrypt on write) and creates projection decryptor
+start({
+  encryption,
+  readModels: {
+    role: 'customer-service',
+    storage: mongodb(...),
+    ...
+  },
+});
+```
+
+### What Bootstrap Does
+
+For command processors (`commands` config):
+- **Event store**: Events are encrypted before `addEvent` and decrypted during
+  `replay` (so aggregate projections see plaintext)
+- **Event bus**: Events are encrypted before `publishEvent` (if not already
+  encrypted by the event store wrapper)
+
+For read models (`readModels` config):
+- **Projection decryptor**: Created via `createProjectionDecryptor(role)`,
+  decrypts events before projection handlers see them. Falls back to
+  `'[deleted]'` if DEKs are unavailable (crypto-shredded)
+- **Storage**: If `readModelEncryption` is configured, wraps storage operations
+  to encrypt sensitive fields on write (insertOne, updateOne, etc.)
+
+## Read Model Encryption
+
+To encrypt fields stored in read model collections (not just event fields),
+provide a `readModelEncryption` configuration:
+
+```javascript
+const encryption = createEncryption({
+  schema,
+  keyStore,
+  contexts,
+  readModelEncryption: {
+    customers: {
+      name: { context: 'personal', subjectField: 'customerId' },
+      location: { context: 'personal', subjectField: 'customerId' },
+    },
+    orderSummaries: {
+      customerName: { context: 'personal', subjectField: 'customerId' },
+    },
+  },
+});
+```
+
+The storage wrapper intercepts `insertOne`, `updateOne`, `updateMany`,
+`findOneAndUpdate`, `findOneAndReplace`, and `bulkWrite` calls, encrypting the
+specified fields before they reach the database.
+
+## Crypto-Shredding (Forget Subject)
+
+To make a subject's data permanently unreadable, delete their DEKs:
+
+```javascript
+// Via the encryption module directly
+encryption.then((enc) => enc.forgetSubject(subjectId));
+```
+
+After DEK deletion:
+- Encrypted events in the event store become undecryptable
+- Projection handlers receive fallback values (`'[deleted]'` by default)
+- Read model queries return fallback values for encrypted fields
+
+### Integration with Event Sourcing
+
+The recommended pattern is a `FORGET_SUBJECT` command and `SUBJECT_FORGOTTEN`
+event. The encryption module's event store wrapper automatically deletes DEKs
+when it processes a `SUBJECT_FORGOTTEN` event. Read model projections should
+handle `SUBJECT_FORGOTTEN` by cleaning up the subject's records.
+
+```javascript
+// SubjectLifecycle aggregate
+export default {
+  initial: () => ({}),
+  commands: {
+    FORGET_SUBJECT: (aggregate, payload) => ({
+      type: 'SUBJECT_FORGOTTEN',
+      payload,
+    }),
+  },
+  projections: {
+    SUBJECT_FORGOTTEN: (aggregate) => ({ ...aggregate, forgotten: true }),
+  },
+};
+```
+
+## Key Rotation
+
+Vault key stores support KEK rotation:
+
+```javascript
+encryption.then((enc) => enc.rotateContextKey('personal'));
+```
+
+This rotates the transit key in Vault. New DEKs will be wrapped with the new
+key version. Existing wrapped DEKs can still be unwrapped (Vault supports key
+versioning).
+
+## API Reference
+
+### `createEncryption(options)`
+
+Returns a Promise that resolves to the encryption module.
+
+**Options**:
+- `schema` — Result of `defineEncryptionSchema()`
+- `keyStore` — Key store instance (`inMemoryKeyStore()`, `mongoKeyStore()`,
+  or `vaultKeyStore()`)
+- `contexts` — Object mapping context names to `{ roles: string[] }`
+- `readModelEncryption` — Optional read model field encryption config
+- `cache` — Optional `{ maxSize: number, ttlMs: number }` (default:
+  `{ maxSize: 10000, ttlMs: 300000 }`)
+- `fallbackValue` — Value used when decryption fails (default: `'[deleted]'`)
+
+**Resolved object methods**:
+- `wrapEventStore(eventStoreFactory)` — Returns a wrapped factory that
+  encrypts/decrypts events
+- `wrapEventBus(eventBusFactory)` — Returns a wrapped factory that encrypts
+  events before publishing
+- `createProjectionDecryptor(role)` — Returns `(event) => Promise<event>` that
+  decrypts event fields for the given role
+- `wrapStorage(storageFactory)` — Returns a wrapped factory that encrypts
+  read model fields on write
+- `createQueryDecryptor()` — Returns a decryptor for query results with
+  role-based access control
+- `forgetSubject(subjectId)` — Deletes all DEKs for a subject
+  (crypto-shredding)
+- `rotateContextKey(contextName)` — Rotates the KEK for a context (Vault only)
+- `getSchema()` — Returns the encryption schema
+- `getContexts()` — Returns the contexts configuration
+
+### `defineEncryptionSchema(schemaDef)`
+
+Validates and returns the schema definition. Throws if any field is missing
+`context` or `subjectField`.
+
+### `inMemoryKeyStore(initialKEKs)`
+
+Creates an in-memory key store. `initialKEKs` is an object mapping context
+names to 32-byte Buffer or base64-encoded key strings.
+
+### `mongoKeyStore(options)`
+
+Creates a MongoDB-backed key store.
+
+- `url` — MongoDB connection URL
+- `rootSecret` — 32-byte Buffer or base64 string used to derive KEKs
+- `database` — Database name (default: `'encryption-keys'`)
+- `dekCollection` — Collection name (default: `'deks'`)
+
+### `vaultKeyStore(options)`
+
+Creates a Vault/OpenBao-backed key store.
+
+- `vaultUrl` — Vault server URL
+- `token` — Direct token authentication (for dev mode)
+- `authMethod` — Authentication method (e.g., `appRole()`)
+- `dekBackend` — Optional `{ url, database, collection }` for MongoDB-backed
+  DEK storage
+
+### `appRole(options)`
+
+Creates an AppRole authentication method for Vault.
+
+- `roleId` — AppRole role ID
+- `secretId` — AppRole secret ID

package/encryption.js

@@ -0,0 +1,146 @@
+import { createFieldEncryptor } from './fieldEncryption.js';
+import { createEnvelopeManager } from './envelopeEncryption.js';
+import { createKeyCache } from './keyCache.js';
+import { createFallbackHandler } from './fallback.js';
+import { createStorageEncryptor } from './storageEncryption.js';
+import { createQueryDecryptor as createQueryDecryptorImpl } from './queryDecryptor.js';
+import { getLogger } from '@lazyapps/logger';
+
+export const createEncryption = ({
+  schema,
+  keyStore,
+  contexts,
+  readModelEncryption,
+  cache = { maxSize: 10000, ttlMs: 300000 },
+  fallbackValue = '[deleted]',
+}) => {
+  const log = getLogger('Encryption', 'INIT');
+
+  return keyStore
+    .initialize()
+    .then((ks) => createKeyCache(ks, cache))
+    .then((cachedKs) => {
+      const envelope = createEnvelopeManager(cachedKs, contexts);
+      const fieldEncryptor = createFieldEncryptor(envelope, schema);
+      const fallbackHandler = createFallbackHandler(schema, fallbackValue);
+
+      const decryptEventSafe = (event) =>
+        fieldEncryptor
+          .decryptEvent(event)
+          .catch(() => fallbackHandler.applyFallbacks(event));
+
+      log.info('Encryption service initialized');
+
+      return {
+        wrapEventStore:
+          (eventStoreFactory) =>
+          (...factoryArgs) =>
+            eventStoreFactory(...factoryArgs).then((store) => ({
+              addEvent: (correlationId) => (event) => {
+                const encLog = getLogger('Encryption/Store', correlationId);
+
+                const shredIfForget = (evt) =>
+                  evt.type === 'SUBJECT_FORGOTTEN'
+                    ? cachedKs
+                        .deleteKeysForSubject(evt.payload.subjectId)
+                        .then(() => evt)
+                    : Promise.resolve(evt);
+
+                return fieldEncryptor
+                  .encryptEvent(event)
+                  .then((encryptedEvent) => {
+                    encLog.debug(
+                      `Encrypted event type=${event.type} ` +
+                        `aggregate=${event.aggregateName}(${event.aggregateId})`,
+                    );
+                    return store
+                      .addEvent(correlationId)(encryptedEvent)
+                      .then(() => shredIfForget(event));
+                  });
+              },
+
+              // Wrap replay to decrypt events before aggregate
+              // projection. During command processor startup, replay
+              // reads encrypted events from the store and passes them
+              // to applyAggregateProjection which needs plaintext.
+              // The original replay uses collection.find().forEach()
+              // calling applyAggregateProjection(correlationId)(event).
+              // We intercept the cmdProcContext to wrap
+              // applyAggregateProjection with a decrypt step.
+              replay: (correlationId) => (cmdProcContext) => {
+                const wrappedContext = {
+                  ...cmdProcContext,
+                  aggregateStore: {
+                    ...cmdProcContext.aggregateStore,
+                    applyAggregateProjection: (corrId) => (event) =>
+                      decryptEventSafe(event).then((decrypted) =>
+                        cmdProcContext.aggregateStore.applyAggregateProjection(
+                          corrId,
+                        )(decrypted),
+                      ),
+                  },
+                };
+                return store.replay(correlationId)(wrappedContext);
+              },
+
+              close: store.close,
+            })),
+
+        wrapEventBus:
+          (eventBusFactory) =>
+          (...factoryArgs) =>
+            eventBusFactory(...factoryArgs).then((bus) => ({
+              ...bus,
+              publishEvent: (correlationId) => (event) => {
+                const busLog = getLogger('Encryption/Bus', correlationId);
+                return fieldEncryptor.hasEncryptedFields(event)
+                  ? bus.publishEvent(correlationId)(event)
+                  : fieldEncryptor.encryptEvent(event).then((encrypted) => {
+                      busLog.debug(
+                        `Encrypted event for bus: type=${event.type}`,
+                      );
+                      return bus.publishEvent(correlationId)(encrypted);
+                    });
+              },
+            })),
+
+        createProjectionDecryptor: (role) => (event) =>
+          fieldEncryptor
+            .decryptEvent(event, { role, contexts })
+            .catch(() => fallbackHandler.applyFallbacks(event)),
+
+        wrapStorage: (storageFactory) =>
+          readModelEncryption
+            ? createStorageEncryptor(
+                storageFactory,
+                readModelEncryption,
+                envelope,
+              )
+            : storageFactory,
+
+        createQueryDecryptor: () =>
+          readModelEncryption
+            ? createQueryDecryptorImpl(
+                readModelEncryption,
+                envelope,
+                fallbackValue,
+                contexts,
+              )
+            : null,
+
+        forgetSubject: (subjectId) => {
+          log.info(`Forgetting subject: ${subjectId}`);
+          return cachedKs.deleteKeysForSubject(subjectId);
+        },
+
+        rotateContextKey: (contextName) => {
+          log.info(`Rotating KEK for context: ${contextName}`);
+          return envelope.rotateKEK(contextName);
+        },
+
+        getSchema: () => schema,
+
+        getContexts: () => contexts,
+      };
+    });
+};

package/envelopeEncryption.js

@@ -0,0 +1,35 @@
+import { randomBytes } from 'node:crypto';
+
+export const createEnvelopeManager = (keyStore, contexts) => ({
+  getDEK: (subjectId, contextName, version) =>
+    keyStore.getDEK(subjectId, contextName, version).then((storedDEK) => {
+      if (!storedDEK) {
+        const newDEK = randomBytes(32);
+        return keyStore
+          .wrapDEK(contextName, newDEK)
+          .then((wrappedKey) => ({
+            key: newDEK,
+            version: 1,
+            wrappedKey,
+          }))
+          .then((dekInfo) =>
+            keyStore
+              .storeDEK(subjectId, contextName, dekInfo)
+              .then(() => dekInfo),
+          );
+      }
+      return keyStore
+        .unwrapDEK(contextName, storedDEK.wrappedKey)
+        .then((plainDEK) => ({
+          key: plainDEK,
+          version: storedDEK.version,
+        }));
+    }),
+
+  rotateKEK: (contextName) =>
+    keyStore.rotateKEK
+      ? keyStore.rotateKEK(contextName)
+      : Promise.reject(
+          new Error('KEK rotation not supported by this key store tier'),
+        ),
+});

package/fallback.js

@@ -0,0 +1,23 @@
+import { getNestedValue, setNestedValue } from './pathUtils.js';
+
+export const createFallbackHandler = (
+  schema,
+  defaultFallback = '[deleted]',
+) => ({
+  applyFallbacks: (event) => {
+    const fieldDefs = schema[event.type];
+    if (!fieldDefs) return Promise.resolve(event);
+
+    const result = { ...event, payload: { ...event.payload } };
+
+    for (const [fieldPath, fieldConfig] of Object.entries(fieldDefs)) {
+      const value = getNestedValue(result, fieldPath);
+      if (value && value.__encrypted) {
+        const fallback = fieldConfig.fallback || defaultFallback;
+        setNestedValue(result, fieldPath, fallback);
+      }
+    }
+
+    return Promise.resolve(result);
+  },
+});

package/fieldEncryption.js

@@ -0,0 +1,106 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { getNestedValue, setNestedValue } from './pathUtils.js';
+
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12;
+
+export const encryptValue = (key, plaintext) => {
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  const encrypted = Buffer.concat([
+    cipher.update(String(plaintext), 'utf8'),
+    cipher.final(),
+  ]);
+  const tag = cipher.getAuthTag();
+  return {
+    __encrypted: true,
+    alg: ALGORITHM,
+    iv: iv.toString('base64'),
+    data: encrypted.toString('base64'),
+    tag: tag.toString('base64'),
+  };
+};
+
+export const decryptValue = (key, envelope) => {
+  const decipher = createDecipheriv(
+    envelope.alg || ALGORITHM,
+    key,
+    Buffer.from(envelope.iv, 'base64'),
+  );
+  decipher.setAuthTag(Buffer.from(envelope.tag, 'base64'));
+  return (
+    decipher.update(Buffer.from(envelope.data, 'base64'), null, 'utf8') +
+    decipher.final('utf8')
+  );
+};
+
+export const createFieldEncryptor = (envelope, schema) => ({
+  encryptEvent: (event) => {
+    const fieldDefs = schema[event.type];
+    if (!fieldDefs) return Promise.resolve(event);
+
+    const encrypted = { ...event, payload: { ...event.payload } };
+
+    return Object.entries(fieldDefs).reduce(
+      (promise, [fieldPath, fieldConfig]) =>
+        promise.then((evt) => {
+          const value = getNestedValue(evt, fieldPath);
+          if (value === undefined || value === null) return evt;
+
+          const subjectId = getNestedValue(evt, fieldConfig.subjectField);
+          if (!subjectId) return evt;
+
+          return envelope.getDEK(subjectId, fieldConfig.context).then((dek) => {
+            const encryptedField = {
+              ...encryptValue(dek.key, value),
+              ctx: fieldConfig.context,
+              kid: subjectId,
+              kv: dek.version,
+            };
+            return setNestedValue(evt, fieldPath, encryptedField);
+          });
+        }),
+      Promise.resolve(encrypted),
+    );
+  },
+
+  decryptEvent: (event, accessControl) => {
+    const fieldDefs = schema[event.type];
+    if (!fieldDefs) return Promise.resolve(event);
+
+    const decrypted = { ...event, payload: { ...event.payload } };
+
+    return Object.entries(fieldDefs).reduce(
+      (promise, [fieldPath, fieldConfig]) =>
+        promise.then((evt) => {
+          const value = getNestedValue(evt, fieldPath);
+          if (!value || !value.__encrypted) return evt;
+
+          if (accessControl) {
+            const contextConfig = accessControl.contexts[value.ctx];
+            if (
+              contextConfig &&
+              !contextConfig.roles.includes(accessControl.role)
+            ) {
+              return evt;
+            }
+          }
+
+          return envelope.getDEK(value.kid, value.ctx, value.kv).then((dek) => {
+            const plaintext = decryptValue(dek.key, value);
+            return setNestedValue(evt, fieldPath, plaintext);
+          });
+        }),
+      Promise.resolve(decrypted),
+    );
+  },
+
+  hasEncryptedFields: (event) => {
+    const fieldDefs = schema[event.type];
+    if (!fieldDefs) return false;
+    return Object.keys(fieldDefs).some((fieldPath) => {
+      const value = getNestedValue(event, fieldPath);
+      return value && value.__encrypted;
+    });
+  },
+});