@lazyapps/encryption 0.0.0-init.0

package/forgetSubjectEndpoints.js

@@ -0,0 +1,90 @@
+import { getLogger } from '@lazyapps/logger';
+
+export const createForgetSubjectEndpoints = (encryption) => (context, app) => {
+  const log = getLogger('Encryption/Endpoints', 'INIT');
+
+  app.post('/api/forget-subject', (req, res) => {
+    const reqTimestamp = Date.now();
+    const correlationId = req.body.correlationId;
+    const reqLog = getLogger('Encryption/ForgetSubject', correlationId);
+
+    const subjectId = req.body.subjectId;
+    if (!subjectId) {
+      res.status(400).json({ error: 'Missing subjectId' });
+      return;
+    }
+
+    const aggregate = context.aggregates && context.aggregates.subjectLifecycle;
+    if (!aggregate) {
+      reqLog.error('subjectLifecycle aggregate not registered');
+      res.status(500).json({ error: 'subjectLifecycle aggregate not found' });
+      return;
+    }
+
+    const commandHandler =
+      aggregate.commands && aggregate.commands.FORGET_SUBJECT;
+    if (!commandHandler) {
+      reqLog.error('FORGET_SUBJECT command not found on subjectLifecycle');
+      res.status(500).json({ error: 'FORGET_SUBJECT command not found' });
+      return;
+    }
+
+    const payload = {
+      subjectId,
+      subjectType: req.body.subjectType || 'unknown',
+      reason: req.body.reason || 'Right to be forgotten',
+      requestedBy:
+        req.body.requestedBy || (req.auth && req.auth.sub) || 'system',
+    };
+
+    context
+      .handleCommand(
+        context.aggregateStore,
+        context.eventStore,
+        context.eventBus,
+        'FORGET_SUBJECT',
+        'subjectLifecycle',
+        subjectId,
+        payload,
+        commandHandler,
+        req.auth,
+        reqTimestamp,
+        correlationId,
+      )
+      .then(() => {
+        res.json({ status: 'forgotten', subjectId });
+      })
+      .catch((err) => {
+        if (err.name === 'ValidationError') {
+          reqLog.error(`Validation error: ${err.message}`);
+          res.status(400).json({ error: err.message });
+        } else {
+          reqLog.error(`Error forgetting subject ${subjectId}: ${err}`);
+          res.status(500).json({ error: err.message });
+        }
+      });
+  });
+
+  app.post('/api/admin/rotate-context-key', (req, res) => {
+    const correlationId = req.body.correlationId;
+    const reqLog = getLogger('Encryption/RotateKey', correlationId);
+
+    const contextName = req.body.contextName;
+    if (!contextName) {
+      res.status(400).json({ error: 'Missing contextName' });
+      return;
+    }
+
+    encryption
+      .then((enc) => enc.rotateContextKey(contextName))
+      .then(() => {
+        res.json({ status: 'rotated', context: contextName });
+      })
+      .catch((err) => {
+        reqLog.error(`Error rotating key for context ${contextName}: ${err}`);
+        res.status(500).json({ error: err.message });
+      });
+  });
+
+  log.info('Forget-subject and rotate-context-key endpoints installed');
+};

package/index.js

@@ -0,0 +1,8 @@
+export { createEncryption } from './encryption.js';
+export { defineEncryptionSchema } from './schema.js';
+export { inMemoryKeyStore } from './keystores/inmemory.js';
+export { mongoKeyStore } from './keystores/mongo.js';
+export { vaultKeyStore, appRole } from './keystores/vault.js';
+export { subjectLifecycleAggregate } from './subjectLifecycle.js';
+export { createForgetSubjectEndpoints } from './forgetSubjectEndpoints.js';
+export { getNestedValue, setNestedValue } from './pathUtils.js';

package/keyCache.js

@@ -0,0 +1,52 @@
+export const createKeyCache = (
+  keyStore,
+  { maxSize = 10000, ttlMs = 300000 },
+) => {
+  const cache = new Map();
+
+  const evictExpired = () => {
+    const now = Date.now();
+    for (const [key, entry] of cache) {
+      if (entry.expiresAt < now) cache.delete(key);
+    }
+  };
+
+  const evictLRU = () => {
+    if (cache.size <= maxSize) return;
+    const firstKey = cache.keys().next().value;
+    cache.delete(firstKey);
+  };
+
+  return {
+    ...keyStore,
+
+    getDEK: (subjectId, contextName, version) => {
+      const cacheKey = `${subjectId}:${contextName}:${version || 'latest'}`;
+      const cached = cache.get(cacheKey);
+      if (cached && cached.expiresAt > Date.now()) {
+        cache.delete(cacheKey);
+        cache.set(cacheKey, cached);
+        return Promise.resolve(cached.value);
+      }
+
+      return keyStore.getDEK(subjectId, contextName, version).then((dek) => {
+        if (dek) {
+          evictExpired();
+          cache.set(cacheKey, {
+            value: dek,
+            expiresAt: Date.now() + ttlMs,
+          });
+          evictLRU();
+        }
+        return dek;
+      });
+    },
+
+    deleteKeysForSubject: (subjectId) => {
+      for (const key of cache.keys()) {
+        if (key.startsWith(`${subjectId}:`)) cache.delete(key);
+      }
+      return keyStore.deleteKeysForSubject(subjectId);
+    },
+  };
+};

package/keystores/inmemory.js

@@ -0,0 +1,93 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12;
+
+export const inMemoryKeyStore = (initialKEKs = {}) => ({
+  initialize: () => {
+    const keks = new Map(
+      Object.entries(initialKEKs).map(([k, v]) => [
+        k,
+        Buffer.isBuffer(v) ? v : Buffer.from(v, 'base64'),
+      ]),
+    );
+    const deks = new Map();
+
+    const wrapLocal = (kek, plainDEK) => {
+      const iv = randomBytes(IV_LENGTH);
+      const cipher = createCipheriv(ALGORITHM, kek, iv);
+      const encrypted = Buffer.concat([
+        cipher.update(plainDEK),
+        cipher.final(),
+      ]);
+      const tag = cipher.getAuthTag();
+      return {
+        iv: iv.toString('base64'),
+        data: encrypted.toString('base64'),
+        tag: tag.toString('base64'),
+      };
+    };
+
+    const unwrapLocal = (kek, wrapped) => {
+      const decipher = createDecipheriv(
+        ALGORITHM,
+        kek,
+        Buffer.from(wrapped.iv, 'base64'),
+      );
+      decipher.setAuthTag(Buffer.from(wrapped.tag, 'base64'));
+      return Buffer.concat([
+        decipher.update(Buffer.from(wrapped.data, 'base64')),
+        decipher.final(),
+      ]);
+    };
+
+    return Promise.resolve({
+      wrapDEK: (contextName, plainDEK) =>
+        keks.has(contextName)
+          ? Promise.resolve(wrapLocal(keks.get(contextName), plainDEK))
+          : Promise.reject(
+              Object.assign(new Error(`KEK not found: ${contextName}`), {
+                code: 'KEK_NOT_FOUND',
+              }),
+            ),
+
+      unwrapDEK: (contextName, wrappedDEK) =>
+        keks.has(contextName)
+          ? Promise.resolve(unwrapLocal(keks.get(contextName), wrappedDEK))
+          : Promise.reject(
+              Object.assign(new Error(`KEK not found: ${contextName}`), {
+                code: 'KEK_NOT_FOUND',
+              }),
+            ),
+
+      getDEK: (subjectId, contextName) => {
+        const key = `${subjectId}:${contextName}`;
+        return Promise.resolve(deks.get(key) || null);
+      },
+
+      storeDEK: (subjectId, contextName, dekInfo) => {
+        deks.set(`${subjectId}:${contextName}`, {
+          wrappedKey: dekInfo.wrappedKey,
+          version: dekInfo.version,
+        });
+        return Promise.resolve();
+      },
+
+      getAllDEKsForContext: (contextName) =>
+        Promise.resolve(
+          Array.from(deks.entries())
+            .filter(([k]) => k.endsWith(`:${contextName}`))
+            .map(([k, v]) => ({ subjectId: k.split(':')[0], ...v })),
+        ),
+
+      deleteKeysForSubject: (subjectId) => {
+        for (const key of deks.keys()) {
+          if (key.startsWith(`${subjectId}:`)) deks.delete(key);
+        }
+        return Promise.resolve();
+      },
+
+      close: () => Promise.resolve(),
+    });
+  },
+});

package/keystores/mongo.js

@@ -0,0 +1,125 @@
+import { MongoClient } from 'mongodb';
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHmac,
+  randomBytes,
+} from 'node:crypto';
+import { getLogger } from '@lazyapps/logger';
+
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12;
+
+const deriveKEK = (rootSecret, contextName) => {
+  const hmac = createHmac('sha256', rootSecret);
+  hmac.update(contextName);
+  return hmac.digest();
+};
+
+const wrapLocal = (kek, plainDEK) => {
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, kek, iv);
+  const encrypted = Buffer.concat([cipher.update(plainDEK), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return {
+    iv: iv.toString('base64'),
+    data: encrypted.toString('base64'),
+    tag: tag.toString('base64'),
+  };
+};
+
+const unwrapLocal = (kek, wrapped) => {
+  const decipher = createDecipheriv(
+    ALGORITHM,
+    kek,
+    Buffer.from(wrapped.iv, 'base64'),
+  );
+  decipher.setAuthTag(Buffer.from(wrapped.tag, 'base64'));
+  return Buffer.concat([
+    decipher.update(Buffer.from(wrapped.data, 'base64')),
+    decipher.final(),
+  ]);
+};
+
+export const mongoKeyStore = ({
+  url,
+  rootSecret,
+  database = 'encryption-keys',
+  dekCollection = 'deks',
+}) => ({
+  initialize: () => {
+    const log = getLogger('Encryption/KS', 'INIT');
+    const secret = Buffer.isBuffer(rootSecret)
+      ? rootSecret
+      : Buffer.from(rootSecret, 'base64');
+
+    return MongoClient.connect(url).then((client) => {
+      const db = client.db(database);
+      log.info(`Key store connected to ${database}`);
+      return {
+        wrapDEK: (contextName, plainDEK) =>
+          Promise.resolve(wrapLocal(deriveKEK(secret, contextName), plainDEK)),
+
+        unwrapDEK: (contextName, wrappedDEK) =>
+          Promise.resolve(
+            unwrapLocal(deriveKEK(secret, contextName), wrappedDEK),
+          ),
+
+        getDEK: (subjectId, contextName, version) => {
+          const filter = { subjectId, context: contextName };
+          if (version) filter.version = version;
+          return db
+            .collection(dekCollection)
+            .findOne(filter, { sort: { version: -1 } })
+            .then((doc) =>
+              doc
+                ? {
+                    wrappedKey: { iv: doc.iv, data: doc.data, tag: doc.tag },
+                    version: doc.version,
+                  }
+                : null,
+            );
+        },
+
+        storeDEK: (subjectId, contextName, dekInfo) =>
+          db.collection(dekCollection).insertOne({
+            subjectId,
+            context: contextName,
+            version: dekInfo.version,
+            iv: dekInfo.wrappedKey.iv,
+            data: dekInfo.wrappedKey.data,
+            tag: dekInfo.wrappedKey.tag,
+            createdAt: Date.now(),
+          }),
+
+        getAllDEKsForContext: (contextName) =>
+          db
+            .collection(dekCollection)
+            .find({ context: contextName })
+            .toArray()
+            .then((docs) =>
+              docs.map((d) => ({
+                subjectId: d.subjectId,
+                wrappedKey: { iv: d.iv, data: d.data, tag: d.tag },
+                version: d.version,
+              })),
+            ),
+
+        deleteKeysForSubject: (subjectId) => {
+          const ksLog = getLogger('Encryption/KS', 'ADMIN');
+          ksLog.info(`Deleting all keys for subject: ${subjectId}`);
+          return db
+            .collection(dekCollection)
+            .deleteMany({ subjectId })
+            .then((result) => {
+              ksLog.info(
+                `Deleted ${result.deletedCount} keys for ${subjectId}`,
+              );
+            });
+        },
+
+        close: () => client.close(),
+      };
+    });
+  },
+});

package/keystores/vault.js

@@ -0,0 +1,144 @@
+import { getLogger } from '@lazyapps/logger';
+
+const vaultRequest = (vaultUrl, token) => (method, path, body) =>
+  fetch(`${vaultUrl}/v1/${path}`, {
+    method,
+    headers: {
+      'X-Vault-Token': token,
+      'Content-Type': 'application/json',
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  }).then((res) =>
+    res.ok
+      ? res.json()
+      : res.json().then((err) => {
+          const error = new Error(
+            `Vault ${method} ${path}: ${err.errors?.[0] || res.statusText}`,
+          );
+          error.status = res.status;
+          throw error;
+        }),
+  );
+
+const authenticateAppRole = (vaultUrl, roleId, secretId) =>
+  fetch(`${vaultUrl}/v1/auth/approle/login`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ role_id: roleId, secret_id: secretId }),
+  })
+    .then((res) => res.json())
+    .then((data) => data.auth.client_token);
+
+const initDekInMemory = () => {
+  const deks = new Map();
+  return Promise.resolve({
+    getDEK: (subjectId, contextName) => {
+      const key = `${subjectId}:${contextName}`;
+      return Promise.resolve(deks.get(key) || null);
+    },
+    storeDEK: (subjectId, contextName, dekInfo) => {
+      deks.set(`${subjectId}:${contextName}`, {
+        wrappedKey: dekInfo.wrappedKey,
+        version: dekInfo.version,
+      });
+      return Promise.resolve();
+    },
+    getAllDEKsForContext: (contextName) =>
+      Promise.resolve(
+        Array.from(deks.entries())
+          .filter(([k]) => k.endsWith(`:${contextName}`))
+          .map(([k, v]) => ({ subjectId: k.split(':')[0], ...v })),
+      ),
+    deleteKeysForSubject: (subjectId) => {
+      for (const key of deks.keys()) {
+        if (key.startsWith(`${subjectId}:`)) deks.delete(key);
+      }
+      return Promise.resolve();
+    },
+    close: () => Promise.resolve(),
+  });
+};
+
+const initDekMongo = ({ url, database, collection }) =>
+  import('mongodb').then(({ MongoClient }) =>
+    MongoClient.connect(url).then((client) => {
+      const db = client.db(database);
+      const coll = db.collection(collection);
+      return {
+        getDEK: (subjectId, contextName) =>
+          coll
+            .findOne(
+              { subjectId, context: contextName },
+              { sort: { version: -1 } },
+            )
+            .then((doc) =>
+              doc ? { wrappedKey: doc.wrappedKey, version: doc.version } : null,
+            ),
+        storeDEK: (subjectId, contextName, dekInfo) =>
+          coll.insertOne({
+            subjectId,
+            context: contextName,
+            wrappedKey: dekInfo.wrappedKey,
+            version: dekInfo.version,
+            createdAt: Date.now(),
+          }),
+        getAllDEKsForContext: (contextName) =>
+          coll
+            .find({ context: contextName })
+            .toArray()
+            .then((docs) =>
+              docs.map((d) => ({
+                subjectId: d.subjectId,
+                wrappedKey: d.wrappedKey,
+                version: d.version,
+              })),
+            ),
+        deleteKeysForSubject: (subjectId) =>
+          coll.deleteMany({ subjectId }).then(() => {}),
+        close: () => client.close(),
+      };
+    }),
+  );
+
+export const appRole = ({ roleId, secretId }) => ({ roleId, secretId });
+
+export const vaultKeyStore = ({ vaultUrl, token, authMethod, dekBackend }) => ({
+  initialize: () => {
+    const log = getLogger('Encryption/Vault', 'INIT');
+
+    const getToken = token
+      ? Promise.resolve(token)
+      : authenticateAppRole(vaultUrl, authMethod.roleId, authMethod.secretId);
+
+    return getToken.then((vaultToken) => {
+      const request = vaultRequest(vaultUrl, vaultToken);
+      log.info(`Vault key store connected to ${vaultUrl}`);
+
+      const dekStore = dekBackend
+        ? initDekMongo(dekBackend)
+        : initDekInMemory();
+
+      return dekStore.then((deks) => ({
+        wrapDEK: (contextName, plainDEK) =>
+          request('POST', `transit/encrypt/${contextName}`, {
+            plaintext: plainDEK.toString('base64'),
+          }).then((res) => res.data.ciphertext),
+
+        unwrapDEK: (contextName, wrappedDEK) =>
+          request('POST', `transit/decrypt/${contextName}`, {
+            ciphertext: wrappedDEK,
+          }).then((res) => Buffer.from(res.data.plaintext, 'base64')),
+
+        getDEK: deks.getDEK,
+        storeDEK: deks.storeDEK,
+        getAllDEKsForContext: deks.getAllDEKsForContext,
+        deleteKeysForSubject: deks.deleteKeysForSubject,
+
+        rotateKEK: (contextName) =>
+          request('POST', `transit/keys/${contextName}/rotate`),
+
+        close: deks.close || (() => Promise.resolve()),
+      }));
+    });
+  },
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@lazyapps/encryption",
+  "version": "0.0.0-init.0",
+  "description": "Field-level PII encryption with crypto-shredding for LazyApps event-sourcing",
+  "main": "index.js",
+  "files": [
+    "*.js",
+    "keystores/"
+  ],
+  "scripts": {
+    "test": "vitest"
+  },
+  "keywords": [
+    "event-sourcing",
+    "cqrs",
+    "lazyapps",
+    "encryption",
+    "pii",
+    "crypto-shredding",
+    "gdpr"
+  ],
+  "author": "Oliver Sturm",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oliversturm/lazyapps-libs.git",
+    "directory": "packages/encryption"
+  },
+  "bugs": {
+    "url": "https://github.com/oliversturm/lazyapps-libs/issues"
+  },
+  "homepage": "https://github.com/oliversturm/lazyapps-libs/tree/main/packages/encryption#readme",
+  "engines": {
+    "node": ">=18.20.3 || >=20.18.0"
+  },
+  "dependencies": {
+    "@lazyapps/logger": "workspace:^"
+  },
+  "peerDependencies": {
+    "mongodb": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mongodb": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "eslint": "^8.46.0",
+    "vitest": "^4.0.18"
+  },
+  "type": "module"
+}

package/pathUtils.js

@@ -0,0 +1,13 @@
+export const getNestedValue = (obj, path) =>
+  path.split('.').reduce((current, key) => current && current[key], obj);
+
+export const setNestedValue = (obj, path, value) => {
+  const keys = path.split('.');
+  const last = keys.pop();
+  const target = keys.reduce((current, key) => {
+    if (!current[key]) current[key] = {};
+    return current[key];
+  }, obj);
+  target[last] = value;
+  return obj;
+};

package/queryDecryptor.js

@@ -0,0 +1,55 @@
+import { decryptValue } from './fieldEncryption.js';
+import { getLogger } from '@lazyapps/logger';
+
+export const createQueryDecryptor = (
+  readModelEncryption,
+  envelope,
+  fallbackValue,
+  contexts,
+) => {
+  const log = getLogger('Encryption/Query', 'INIT');
+
+  log.info('Query decryptor initialized');
+
+  return {
+    decrypt: (doc, { roles, identity, subjectField }) => {
+      if (!doc) return Promise.resolve(doc);
+
+      const isSelf =
+        identity && doc[subjectField] && identity === doc[subjectField];
+      const effectiveRoles = isSelf ? [...roles, 'self'] : [...roles];
+
+      const encryptedFields = Object.entries(doc).filter(
+        ([, value]) => value && value.__encrypted,
+      );
+
+      if (encryptedFields.length === 0) return Promise.resolve(doc);
+
+      return encryptedFields.reduce(
+        (promise, [fieldName, fieldValue]) =>
+          promise.then((d) => {
+            const contextConfig = contexts[fieldValue.ctx];
+            const isAuthorized =
+              contextConfig &&
+              contextConfig.roles.some((r) => effectiveRoles.includes(r));
+
+            if (!isAuthorized) {
+              return { ...d, [fieldName]: '[restricted]' };
+            }
+
+            return envelope
+              .getDEK(fieldValue.kid, fieldValue.ctx, fieldValue.kv)
+              .then((dek) => ({
+                ...d,
+                [fieldName]: decryptValue(dek.key, fieldValue),
+              }))
+              .catch(() => ({
+                ...d,
+                [fieldName]: fallbackValue,
+              }));
+          }),
+        Promise.resolve({ ...doc }),
+      );
+    },
+  };
+};

package/schema.js

@@ -0,0 +1,26 @@
+import { getLogger } from '@lazyapps/logger';
+
+export const defineEncryptionSchema = (schemaDef) => {
+  const log = getLogger('Encryption/Schema', 'INIT');
+
+  for (const [eventType, fields] of Object.entries(schemaDef)) {
+    for (const [fieldPath, config] of Object.entries(fields)) {
+      if (!config.context) {
+        throw new Error(
+          `Encryption schema: field ${fieldPath} in ${eventType} missing 'context'`,
+        );
+      }
+      if (!config.subjectField) {
+        throw new Error(
+          `Encryption schema: field ${fieldPath} in ${eventType} missing 'subjectField'`,
+        );
+      }
+    }
+  }
+
+  log.debug(
+    `Encryption schema defined for ${Object.keys(schemaDef).length} event types`,
+  );
+
+  return schemaDef;
+};