feat(secure): level envelope encryption with key rotation (#546)

Author: l1ttps

core-api/example.env

@@ -13,6 +13,9 @@ REDIS_URL=redis://:password@localhost:6379/0
 
 GEO_IP_URL=localhost:4360
 
+# Envelope encryption: comma-separated KEKs. Last key = active (encrypt + decrypt), older = decrypt-only
+ENCRYPTION_KEYS=your-encryption-key-change-in-production
+
 # RustFS Configuration
 RUSTFS_ENDPOINT=http://localhost:9000
 RUSTFS_ACCESS_KEY=rustfsadmin

core-api/src/common/utils/encryption.util.ts

@@ -9,32 +9,97 @@ import { DEFAULT_ENCRYPTION_KEY } from '../constants/app.constants';
 const ALGORITHM = 'aes-256-cbc';
 const IV_LENGTH = 16;
 
-function getEncryptionKey(): Buffer {
-  let key = process.env.ENCRYPTION_KEY;
-  if (!key) {
-    key = DEFAULT_ENCRYPTION_KEY;
-  }
-  return createHash('sha256').update(key).digest();
+/**
+ * Parse ENCRYPTION_KEYS env var into SHA-256 hashed key buffers.
+ * Format: "key-v1,key-v2,key-v3" — comma-separated.
+ * Falls back to DEFAULT_ENCRYPTION_KEY if env var is not set.
+ *
+ * Last key = active (used for encrypt).
+ * All keys = valid for decrypt.
+ *
+ * Key rotation: append a new key → new data encrypted with new key,
+ * old data still decryptable via index prefix lookup.
+ */
+export function parseEncryptionKeys(): Buffer[] {
+  const raw = process.env.ENCRYPTION_KEYS;
+  const keys = raw
+    ? raw.split(',').map((k) => k.trim()).filter(Boolean)
+    : [DEFAULT_ENCRYPTION_KEY];
+  return keys.map((k) => createHash('sha256').update(k).digest());
+}
+
+/**
+ * Returns the active (latest) encryption key for encrypting new data.
+ * Always the last key in ENCRYPTION_KEYS list.
+ */
+export function getActiveEncryptionKey(): Buffer {
+  const keys = parseEncryptionKeys();
+  return keys[keys.length - 1];
 }
 
+/**
+ * Encrypt plaintext with the active KEK.
+ * Output format: "{activeIndex}:ivHex:encryptedHex"
+ * Index is the position in ENCRYPTION_KEYS (0-based), enabling O(1) decrypt.
+ *
+ * @deprecated For workspace-scoped encryption, use encryptWithDEK instead.
+ */
 export function encrypt(text: string): string {
+  const keys = parseEncryptionKeys();
+  const activeIndex = keys.length - 1;
+  const key = keys[activeIndex];
   const iv = randomBytes(IV_LENGTH);
-  const cipher = createCipheriv(ALGORITHM, getEncryptionKey(), iv);
-  const encrypted = Buffer.concat([
-    cipher.update(text, 'utf8'),
-    cipher.final(),
-  ]);
-  return iv.toString('hex') + ':' + encrypted.toString('hex');
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  const encrypted = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]);
+  return `${activeIndex}:${iv.toString('hex')}:${encrypted.toString('hex')}`;
 }
 
+/**
+ * Decrypt ciphertext. Supports both new and old formats:
+ * - New: "{index}:ivHex:encryptedHex" → O(1) key lookup by index
+ * - Old: "ivHex:encryptedHex" (no prefix) → tries all keys (O(n), backward compat)
+ *
+ * @deprecated For workspace-scoped decryption, use decryptWithDEK instead.
+ */
 export function decrypt(encryptedText: string): string {
-  const [ivHex, encryptedHex] = encryptedText.split(':');
+  const parts = encryptedText.split(':');
+
+  // Detect format: if first part is numeric and has 3+ segments, it's the key index
+  const firstPartIsIndex = parts.length >= 3 && /^\d+$/.test(parts[0]);
+
+  let ivHex: string, encryptedHex: string;
+  let keys: Buffer[];
+
+  if (firstPartIsIndex) {
+    const keyIndex = parseInt(parts[0], 10);
+    ivHex = parts[1];
+    encryptedHex = parts.slice(2).join(':');
+    const allKeys = parseEncryptionKeys();
+    if (keyIndex < 0 || keyIndex >= allKeys.length) {
+      throw new Error(`Invalid key index: ${keyIndex}`);
+    }
+    keys = allKeys; // O(1) on match, O(n) fallback — try all keys for backward compat
+  } else {
+    // Old format: no prefix, try all keys
+    ivHex = parts[0];
+    encryptedHex = parts.slice(1).join(':');
+    keys = parseEncryptionKeys(); // all keys
+  }
+
   const iv = Buffer.from(ivHex, 'hex');
   const encrypted = Buffer.from(encryptedHex, 'hex');
-  const decipher = createDecipheriv(ALGORITHM, getEncryptionKey(), iv);
-  const decrypted = Buffer.concat([
-    decipher.update(encrypted),
-    decipher.final(),
-  ]);
-  return decrypted.toString('utf8');
+
+  const errors: Error[] = [];
+  for (const key of keys) {
+    try {
+      const decipher = createDecipheriv(ALGORITHM, key, iv);
+      return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString('utf8');
+    } catch (e) {
+      errors.push(e as Error);
+    }
+  }
+
+  throw new Error(
+    `Decryption failed with ${keys.length} key(s): ${errors.map((e) => e.message).join('; ')}`,
+  );
 }

core-api/src/common/utils/workspace-encryption.util.spec.ts

@@ -0,0 +1,137 @@
+import { createHash, randomBytes, createCipheriv } from 'crypto';
+import {
+  generateDEK,
+  wrapDEK,
+  unwrapDEK,
+  encryptWithDEK,
+  decryptWithDEK,
+} from './workspace-encryption.util';
+
+// Helper: manually encrypt with DEFAULT key in OLD format (no prefix)
+function encryptLegacy(text: string): string {
+  const key = createHash('sha256')
+    .update('OASM_DEFAULT_ENCRYPTION_KEY')
+    .digest();
+  const iv = randomBytes(16);
+  const cipher = createCipheriv('aes-256-cbc', key, iv);
+  const encrypted = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]);
+  return iv.toString('hex') + ':' + encrypted.toString('hex');
+}
+
+describe('generateDEK', () => {
+  it('should generate a 32-byte buffer', () => {
+    const dek = generateDEK();
+    expect(Buffer.isBuffer(dek)).toBe(true);
+    expect(dek.length).toBe(32);
+  });
+
+  it('should generate unique keys each call', () => {
+    const dek1 = generateDEK();
+    const dek2 = generateDEK();
+    expect(dek1.equals(dek2)).toBe(false);
+  });
+});
+
+describe('wrapDEK / unwrapDEK', () => {
+  it('should roundtrip: wrap then unwrap produces original DEK', () => {
+    const dek = generateDEK();
+    const wrapped = wrapDEK(dek);
+    expect(typeof wrapped).toBe('string');
+    expect(wrapped).toContain(':');
+
+    // Should have numeric index prefix
+    const firstColon = wrapped.indexOf(':');
+    const indexStr = wrapped.substring(0, firstColon);
+    expect(/^\d+$/.test(indexStr)).toBe(true);
+
+    const unwrapped = unwrapDEK(wrapped);
+    expect(Buffer.isBuffer(unwrapped)).toBe(true);
+    expect(dek.equals(unwrapped)).toBe(true);
+  });
+
+  it('should fail unwrap on corrupted data', () => {
+    expect(() => unwrapDEK('0:bad:data')).toThrow();
+  });
+
+  it('should fail unwrap on invalid key index', () => {
+    expect(() => unwrapDEK('99:abc:def')).toThrow(/key index/);
+  });
+});
+
+describe('encryptWithDEK / decryptWithDEK', () => {
+  const sampleText = 'Hello, World! Đây là dữ liệu cần mã hóa.';
+
+  it('should roundtrip with valid DEK', () => {
+    const dek = generateDEK();
+    const encrypted = encryptWithDEK(sampleText, dek);
+    expect(encrypted).not.toBe(sampleText);
+    expect(encrypted).toContain(':');
+
+    const decrypted = decryptWithDEK(encrypted, dek);
+    expect(decrypted).toBe(sampleText);
+  });
+
+  it('should handle empty string', () => {
+    const dek = generateDEK();
+    const encrypted = encryptWithDEK('', dek);
+    expect(decryptWithDEK(encrypted, dek)).toBe('');
+  });
+
+  it('should handle UTF-8 characters', () => {
+    const dek = generateDEK();
+    const text = 'こんにちは世界 🌍';
+    const encrypted = encryptWithDEK(text, dek);
+    expect(decryptWithDEK(encrypted, dek)).toBe(text);
+  });
+
+  it('should fail decrypt with wrong DEK', () => {
+    const dek1 = generateDEK();
+    const dek2 = generateDEK();
+    const encrypted = encryptWithDEK(sampleText, dek1);
+    expect(() => decryptWithDEK(encrypted, dek2)).toThrow();
+  });
+});
+
+describe('backward compatibility — decryptWithDEK with legacy KEK data', () => {
+  const sampleText = 'Hello, World! Đây là dữ liệu cần mã hóa.';
+
+  it('should decrypt legacy KEK data (no prefix) when DEK is null', () => {
+    const legacyEncrypted = encryptLegacy(sampleText);
+    // Legacy format: no numeric prefix
+    expect(legacyEncrypted.split(':')[0]).not.toMatch(/^\d+$/);
+
+    const result = decryptWithDEK(legacyEncrypted, null);
+    expect(result).toBe(sampleText);
+  });
+
+  it('should fall back to KEK when DEK decryption fails', () => {
+    const legacyEncrypted = encryptLegacy(sampleText);
+    const dek = generateDEK();
+    const result = decryptWithDEK(legacyEncrypted, dek);
+    expect(result).toBe(sampleText);
+  });
+});
+
+describe('end-to-end envelope encryption flow', () => {
+  const sampleText = 'Full lifecycle test.';
+
+  it('should simulate the full workspace encryption lifecycle', () => {
+    // 1. Generate DEK
+    const dek = generateDEK();
+    // 2. Wrap DEK with KEK (what gets stored in workspace.dek)
+    const wrappedDEK = wrapDEK(dek);
+    // 3. Store wrappedDEK in DB (simulated)
+    const storedWrappedDEK = wrappedDEK;
+    // 4. Later: unwrap DEK from stored value
+    const unwrappedDEK = unwrapDEK(storedWrappedDEK);
+    expect(dek.equals(unwrappedDEK)).toBe(true);
+    // 5. Encrypt data with DEK (no prefix — DEK is the key)
+    const encrypted = encryptWithDEK(sampleText, unwrappedDEK);
+    // 6. Decrypt data with DEK
+    const decrypted = decryptWithDEK(encrypted, unwrappedDEK);
+    expect(decrypted).toBe(sampleText);
+    // 7. Different workspace DEK cannot decrypt
+    const otherDEK = generateDEK();
+    expect(() => decryptWithDEK(encrypted, otherDEK)).toThrow();
+  });
+});

core-api/src/common/utils/workspace-encryption.util.ts

@@ -0,0 +1,127 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  randomBytes,
+} from 'crypto';
+import {
+  decrypt,
+  getActiveEncryptionKey,
+  parseEncryptionKeys,
+} from './encryption.util';
+
+const ALGORITHM = 'aes-256-cbc';
+const IV_LENGTH = 16;
+const DEK_LENGTH = 32; // 256 bits for AES-256
+
+/**
+ * Generate a random 32-byte Data Encryption Key (DEK).
+ * Each workspace gets its own DEK.
+ */
+export function generateDEK(): Buffer {
+  return randomBytes(DEK_LENGTH);
+}
+
+/**
+ * Wrap (encrypt) a DEK with the system KEK.
+ * Uses the active key (last in ENCRYPTION_KEYS).
+ * Returns "{activeIndex}:ivHex:encryptedHex" for storage in workspaces.dek.
+ *
+ * The index prefix enables O(1) key lookup during unwrap — critical for
+ * key rotation: DEK wrapped with key-0 remains decryptable after adding key-1.
+ */
+export function wrapDEK(dek: Buffer): string {
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, getActiveEncryptionKey(), iv);
+  const encrypted = Buffer.concat([cipher.update(dek), cipher.final()]);
+  const allKeys = parseEncryptionKeys();
+  const activeIndex = allKeys.length - 1;
+  return `${activeIndex}:${iv.toString('hex')}:${encrypted.toString('hex')}`;
+}
+
+/**
+ * Unwrap (decrypt) a wrapped DEK using the system KEK.
+ * Uses key index prefix for O(1) lookup.
+ * Falls back to trial decryption for legacy format (no prefix).
+ */
+export function unwrapDEK(wrappedDEK: string): Buffer {
+  const parts = wrappedDEK.split(':');
+  const firstPartIsIndex = parts.length >= 3 && /^\d+$/.test(parts[0]);
+
+  let ivHex: string, encryptedHex: string, keys: Buffer[];
+
+  if (firstPartIsIndex) {
+    const keyIndex = parseInt(parts[0], 10);
+    const allKeys = parseEncryptionKeys();
+    if (keyIndex < 0 || keyIndex >= allKeys.length) {
+      throw new Error(
+        `Invalid key index in wrapped DEK: ${keyIndex} (have ${allKeys.length} keys)`,
+      );
+    }
+    keys = allKeys; // try all keys for backward compat
+    ivHex = parts[1];
+    encryptedHex = parts.slice(2).join(':');
+  } else {
+    // Legacy format — no prefix, try all keys
+    keys = parseEncryptionKeys();
+    ivHex = parts[0];
+    encryptedHex = parts.slice(1).join(':');
+  }
+
+  const iv = Buffer.from(ivHex, 'hex');
+  const encrypted = Buffer.from(encryptedHex, 'hex');
+
+  for (const key of keys) {
+    try {
+      const decipher = createDecipheriv(ALGORITHM, key, iv);
+      return Buffer.concat([decipher.update(encrypted), decipher.final()]);
+    } catch {
+      // Try next key
+    }
+  }
+  throw new Error('Failed to unwrap DEK — no valid KEK found');
+}
+
+/**
+ * Encrypt data using a workspace-specific DEK.
+ * Format: "ivHex:encryptedHex" (no key index — DEK is the key itself).
+ */
+export function encryptWithDEK(text: string, dek: Buffer): string {
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, dek, iv);
+  const encrypted = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]);
+  return iv.toString('hex') + ':' + encrypted.toString('hex');
+}
+
+/**
+ * Decrypt data. Fallback chain: DEK → KEK (index prefix) → KEK trial.
+ *
+ * @param encryptedText - "ivHex:encryptedHex" (DEK) or "{index}:ivHex:encryptedHex" (KEK)
+ * @param dek - Cleartext DEK, or null for pre-envelope-encryption workspaces
+ */
+export function decryptWithDEK(encryptedText: string, dek: Buffer | null): string {
+  const parts = encryptedText.split(':');
+  const firstPartIsIndex = parts.length >= 3 && /^\d+$/.test(parts[0]);
+  const ivHex = firstPartIsIndex ? parts[1] : parts[0];
+  const encryptedHex = firstPartIsIndex
+    ? parts.slice(2).join(':')
+    : parts.slice(1).join(':');
+
+  if (!ivHex || !encryptedHex) {
+    throw new Error('Invalid encrypted data format');
+  }
+  const iv = Buffer.from(ivHex, 'hex');
+  const encrypted = Buffer.from(encryptedHex, 'hex');
+
+  // Layer 1: DEK (only for non-prefixed data — DEK-encrypted data has no prefix)
+  if (dek !== null && !firstPartIsIndex) {
+    try {
+      const decipher = createDecipheriv(ALGORITHM, dek, iv);
+      return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString('utf8');
+    } catch {
+      // DEK failed, fall through to KEK
+    }
+  }
+
+  // Layer 2: KEK — leverage shared decrypt() which handles both formats
+  return decrypt(encryptedText);
+}