@zintrust/core 0.1.26 → 0.1.28

package/src/security/EncryptedEnvelope.ts

@@ -0,0 +1,373 @@
+/**
+ * EncryptedEnvelope
+ *
+ * Framework-compatible encrypted payload envelope (PHP-style envelope).
+ *
+ * Format: base64(JSON({ iv, value, mac, tag }))
+ * - iv: base64
+ * - value: base64 ciphertext
+ * - mac: hex string (AES-CBC envelopes)
+ * - tag: base64 auth tag (AES-GCM envelopes)
+ */
+
+import { Env } from '@config/env';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHmac,
+  randomBytes,
+  timingSafeEqual,
+} from '@node-singletons/crypto';
+
+export type EncryptedEnvelopeCipher = 'aes-256-cbc' | 'aes-256-gcm';
+export type EncryptedEnvelopeCipherInput = EncryptedEnvelopeCipher | 'AES-256-CBC' | 'AES-256-GCM';
+
+export type EncryptedEnvelopePayload = {
+  iv: string;
+  value: string;
+  mac?: string;
+  tag?: string;
+};
+
+export type EncryptedEnvelopeSerializer<T> = {
+  serialize: (value: T) => string;
+  deserialize: (value: string) => T;
+};
+
+export type EncryptedEnvelopeKeyring = {
+  primaryKey: Uint8Array;
+  previousKeys: Uint8Array[];
+};
+
+export type EncryptedEnvelopeEnv = {
+  APP_KEY?: string;
+  APP_PREVIOUS_KEYS?: string;
+  ENCRYPTION_CIPHER?: string;
+};
+
+const normalizeCipher = (cipher: EncryptedEnvelopeCipherInput): EncryptedEnvelopeCipher => {
+  const normalized = cipher.toLowerCase();
+
+  if (normalized === 'aes-256-cbc') return 'aes-256-cbc';
+  if (normalized === 'aes-256-gcm') return 'aes-256-gcm';
+
+  throw ErrorFactory.createValidationError('Unsupported ENCRYPTION_CIPHER', {
+    cipher,
+    supported: ['aes-256-cbc', 'aes-256-gcm'],
+  });
+};
+
+const normalizeBase64ForCompare = (value: string): string => {
+  const trimmed = value.trim();
+
+  // Remove base64 padding without regex (avoids any regex backtracking concerns).
+  let end = trimmed.length;
+  while (end > 0 && trimmed.codePointAt(end - 1) === 61) {
+    end -= 1;
+  }
+
+  return trimmed.slice(0, end);
+};
+
+const decodeBase64 = (input: string, label: string): Buffer => {
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    throw ErrorFactory.createValidationError(`Invalid base64 for ${label}`);
+  }
+
+  // Note: Buffer.from(..., 'base64') does not reliably throw on invalid input.
+  // Validate by re-encoding and comparing (ignoring padding).
+  const decoded = Buffer.from(trimmed, 'base64');
+  if (decoded.length === 0) {
+    throw ErrorFactory.createValidationError(`Invalid base64 for ${label}`);
+  }
+
+  const roundTrip = decoded.toString('base64');
+  if (normalizeBase64ForCompare(roundTrip) !== normalizeBase64ForCompare(trimmed)) {
+    throw ErrorFactory.createValidationError(`Invalid base64 for ${label}`);
+  }
+
+  return decoded;
+};
+
+const CIPHER_KEY_BYTES: Record<EncryptedEnvelopeCipher, number> = Object.freeze({
+  'aes-256-cbc': 32,
+  'aes-256-gcm': 32,
+});
+
+const expectedKeyBytesForCipher = (cipher: EncryptedEnvelopeCipher): number =>
+  CIPHER_KEY_BYTES[cipher];
+
+const parseKey = (key: string, cipher: EncryptedEnvelopeCipher): Uint8Array => {
+  const trimmed = key.trim();
+  if (trimmed.length === 0) {
+    throw ErrorFactory.createValidationError('Missing APP_KEY');
+  }
+
+  const raw = trimmed.startsWith('base64:') ? trimmed.slice('base64:'.length) : trimmed;
+  const bytes = decodeBase64(raw, 'APP_KEY');
+
+  const expectedBytes = expectedKeyBytesForCipher(cipher);
+  if (bytes.length !== expectedBytes) {
+    throw ErrorFactory.createValidationError('Invalid APP_KEY length for cipher', {
+      cipher,
+      expectedBytes,
+      actualBytes: bytes.length,
+    });
+  }
+
+  return new Uint8Array(bytes);
+};
+
+const parsePreviousKeys = (
+  raw: string | undefined,
+  cipher: EncryptedEnvelopeCipher
+): Uint8Array[] => {
+  const value = (raw ?? '').trim();
+  if (value.length === 0) return [];
+
+  const items: string[] = (() => {
+    if (value.startsWith('[')) {
+      try {
+        const parsed = JSON.parse(value) as unknown;
+        if (!Array.isArray(parsed)) return [];
+        return parsed.filter((v) => typeof v === 'string');
+      } catch {
+        return [];
+      }
+    }
+
+    return value
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+  })();
+
+  return items.map((k) => parseKey(k, cipher));
+};
+
+const parsePayload = (payload: string): EncryptedEnvelopePayload => {
+  const decoded = Buffer.from(payload, 'base64').toString('utf8');
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decoded);
+  } catch {
+    throw ErrorFactory.createValidationError('Invalid encrypted envelope payload (not JSON)');
+  }
+
+  if (typeof parsed !== 'object' || parsed === null) {
+    throw ErrorFactory.createValidationError('Invalid encrypted envelope payload (not an object)');
+  }
+
+  const record = parsed as Record<string, unknown>;
+  const iv = typeof record['iv'] === 'string' ? record['iv'] : '';
+  const value = typeof record['value'] === 'string' ? record['value'] : '';
+  const mac = typeof record['mac'] === 'string' ? record['mac'] : undefined;
+  const tag = typeof record['tag'] === 'string' ? record['tag'] : undefined;
+
+  if (iv.length === 0 || value.length === 0) {
+    throw ErrorFactory.createValidationError(
+      'Invalid encrypted envelope payload (missing iv/value)'
+    );
+  }
+
+  return { iv, value, mac, tag };
+};
+
+const computeMacHex = (key: Uint8Array, ivBase64: string, valueBase64: string): string => {
+  // Envelope MAC: mac = HMAC-SHA256(iv + value, key), where iv/value are base64 strings.
+  return createHmac('sha256', Buffer.from(key))
+    .update(ivBase64 + valueBase64, 'utf8')
+    .digest('hex');
+};
+
+const timingSafeEqualsHex = (a: string, b: string): boolean => {
+  const aBuf = Buffer.from(a, 'utf8');
+  const bBuf = Buffer.from(b, 'utf8');
+  if (aBuf.length !== bBuf.length) return false;
+  return timingSafeEqual(aBuf, bBuf);
+};
+
+const ivLengthFor = (cipher: EncryptedEnvelopeCipher): number => {
+  // OpenSSL defaults for these ciphers.
+  if (cipher === 'aes-256-gcm') return 12;
+  return 16;
+};
+
+const decryptWithKey = (
+  payload: EncryptedEnvelopePayload,
+  cipher: EncryptedEnvelopeCipher,
+  key: Uint8Array
+): string => {
+  const iv = decodeBase64(payload.iv, 'iv');
+  const ciphertext = decodeBase64(payload.value, 'value');
+
+  if (cipher === 'aes-256-cbc') {
+    const expected = payload.mac ?? '';
+    if (expected.length === 0) {
+      throw ErrorFactory.createValidationError('Missing mac for aes-256-cbc envelope');
+    }
+
+    const actual = computeMacHex(key, payload.iv, payload.value);
+    if (!timingSafeEqualsHex(actual, expected)) {
+      throw ErrorFactory.createSecurityError('Invalid MAC');
+    }
+
+    const decipher = createDecipheriv('aes-256-cbc', Buffer.from(key), iv);
+    const plain = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return plain.toString('utf8');
+  }
+
+  const tagB64 = (payload.tag ?? '').trim();
+  if (tagB64.length === 0) {
+    throw ErrorFactory.createValidationError('Missing tag for aes-256-gcm envelope');
+  }
+
+  const tag = decodeBase64(tagB64, 'tag');
+  const decipher = createDecipheriv('aes-256-gcm', Buffer.from(key), iv);
+  decipher.setAuthTag(tag);
+
+  const plain = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  return plain.toString('utf8');
+};
+
+export const EncryptedEnvelope = Object.freeze({
+  normalizeCipher,
+
+  /**
+   * Build a keyring from environment variables.
+   * - Uses APP_KEY
+   * - Supports APP_PREVIOUS_KEYS (comma-separated or JSON array)
+   */
+  keyringFromEnv(
+    env: EncryptedEnvelopeEnv = Env as unknown as EncryptedEnvelopeEnv
+  ): EncryptedEnvelopeKeyring {
+    const cipherRaw = (env.ENCRYPTION_CIPHER ?? '').trim();
+    if (cipherRaw.length === 0) {
+      throw ErrorFactory.createConfigError('ENCRYPTION_CIPHER must be set', {
+        key: 'ENCRYPTION_CIPHER',
+      });
+    }
+
+    const cipher = normalizeCipher(cipherRaw as EncryptedEnvelopeCipherInput);
+    const primaryKey = parseKey(env.APP_KEY ?? '', cipher);
+    const previousKeys = parsePreviousKeys(env.APP_PREVIOUS_KEYS, cipher);
+
+    return { primaryKey, previousKeys };
+  },
+
+  /**
+   * Encrypt a UTF-8 string and return a framework-compatible base64(JSON) envelope.
+   */
+  encryptString(
+    plaintext: string,
+    options: { cipher: EncryptedEnvelopeCipherInput; key: string }
+  ): string {
+    const cipher = normalizeCipher(options.cipher);
+    const key = parseKey(options.key, cipher);
+
+    const iv = randomBytes(ivLengthFor(cipher));
+
+    if (cipher === 'aes-256-cbc') {
+      const c = createCipheriv('aes-256-cbc', Buffer.from(key), iv);
+      const ciphertext = Buffer.concat([c.update(Buffer.from(plaintext, 'utf8')), c.final()]);
+
+      const ivB64 = iv.toString('base64');
+      const valueB64 = ciphertext.toString('base64');
+      const mac = computeMacHex(key, ivB64, valueB64);
+
+      const envelope: EncryptedEnvelopePayload = { iv: ivB64, value: valueB64, mac, tag: '' };
+      return Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64');
+    }
+
+    const c = createCipheriv('aes-256-gcm', Buffer.from(key), iv);
+    const ciphertext = Buffer.concat([c.update(Buffer.from(plaintext, 'utf8')), c.final()]);
+    const tag = c.getAuthTag();
+
+    const envelope: EncryptedEnvelopePayload = {
+      iv: iv.toString('base64'),
+      value: ciphertext.toString('base64'),
+      mac: '',
+      tag: tag.toString('base64'),
+    };
+
+    return Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64');
+  },
+
+  /**
+   * Decrypt a framework-compatible base64(JSON) envelope to a UTF-8 string.
+   * Tries the primary key first, then previous keys.
+   */
+  decryptString(
+    encrypted: string,
+    options: { cipher: EncryptedEnvelopeCipherInput; key: string; previousKeys?: string[] }
+  ): string {
+    const cipher = normalizeCipher(options.cipher);
+    const primaryKey = parseKey(options.key, cipher);
+    const previous = (options.previousKeys ?? []).map((k) => parseKey(k, cipher));
+
+    const payload = parsePayload(encrypted);
+
+    const keys = [primaryKey, ...previous];
+    let lastError: unknown;
+
+    for (const key of keys) {
+      try {
+        return decryptWithKey(payload, cipher, key);
+      } catch (error: unknown) {
+        lastError = error;
+      }
+    }
+
+    throw ErrorFactory.createSecurityError(
+      'Unable to decrypt encrypted envelope with provided keyring',
+      {
+        cause: lastError instanceof Error ? lastError.message : String(lastError),
+      }
+    );
+  },
+
+  /**
+   * Encrypt arbitrary values using a caller-provided serializer.
+   * This supports encrypted payloads for frameworks that store serialized values.
+   */
+  encrypt<T>(
+    value: T,
+    options: {
+      cipher: EncryptedEnvelopeCipherInput;
+      key: string;
+      serializer: EncryptedEnvelopeSerializer<T>;
+    }
+  ): string {
+    const serialized = options.serializer.serialize(value);
+    return EncryptedEnvelope.encryptString(serialized, {
+      cipher: options.cipher,
+      key: options.key,
+    });
+  },
+
+  /**
+   * Decrypt into an arbitrary value using a caller-provided serializer.
+   */
+  decrypt<T>(
+    encrypted: string,
+    options: {
+      cipher: EncryptedEnvelopeCipherInput;
+      key: string;
+      previousKeys?: string[];
+      serializer: EncryptedEnvelopeSerializer<T>;
+    }
+  ): T {
+    const serialized = EncryptedEnvelope.decryptString(encrypted, {
+      cipher: options.cipher,
+      key: options.key,
+      previousKeys: options.previousKeys,
+    });
+
+    return options.serializer.deserialize(serialized);
+  },
+});
+
+export default EncryptedEnvelope;

package/src/security/Encryptor.ts

@@ -0,0 +1,259 @@
+/**
+ * Encryptor
+ * Password hashing with dual support: PBKDF2 (default) and optional bcrypt
+ */
+
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import * as crypto from '@node-singletons/crypto';
+import { promisify } from '@node-singletons/util';
+
+/**
+ * Hash algorithm selector
+ */
+export type HashAlgorithm = 'pbkdf2' | 'bcrypt';
+
+interface BcryptModule {
+  hash: (data: string, saltOrRounds: string | number) => Promise<string>;
+  compare: (data: string, encrypted: string) => Promise<boolean>;
+}
+
+function isBcryptModule(value: unknown): value is BcryptModule {
+  if (typeof value !== 'object' || value === null) return false;
+
+  const record = value as Record<string, unknown>;
+  return typeof record['hash'] === 'function' && typeof record['compare'] === 'function';
+}
+
+let algorithm: HashAlgorithm = 'pbkdf2';
+let bcrypt: BcryptModule | undefined;
+let loadingPromise: Promise<void> | undefined;
+
+async function loadBcrypt(): Promise<void> {
+  try {
+    const imported: unknown = await import('bcrypt');
+    const module = imported as { default?: unknown } & Record<string, unknown>;
+    const candidate: unknown = module.default ?? module;
+
+    if (!isBcryptModule(candidate)) {
+      throw ErrorFactory.createConfigError('Invalid bcrypt module shape');
+    }
+
+    bcrypt = candidate;
+    algorithm = 'bcrypt';
+  } catch (error) {
+    Logger.error('bcrypt not installed, falling back to PBKDF2', error);
+    ErrorFactory.createSecurityError('bcrypt not installed, falling back to PBKDF2', error);
+    // bcrypt not installed, will use PBKDF2
+    algorithm = 'pbkdf2';
+  }
+}
+
+async function ensureLoaded(): Promise<void> {
+  if (bcrypt !== undefined) return;
+  if (loadingPromise !== undefined) return loadingPromise;
+
+  loadingPromise = loadBcrypt();
+  return loadingPromise;
+}
+
+/**
+ * Timing-safe string comparison
+ */
+function timingSafeEquals(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= (a.codePointAt(i) ?? 0) ^ (b.codePointAt(i) ?? 0);
+  }
+
+  return result === 0;
+}
+
+/**
+ * Hash with PBKDF2 (default)
+ */
+async function hashPbkdf2(password: string): Promise<string> {
+  const iterations = 600000; // OWASP recommended for SHA-256
+  const salt = crypto.randomBytes(32).toString('hex');
+  const keyLength = 64;
+  const digest = 'sha256';
+
+  const pbkdf2Fn = (() => {
+    try {
+      const maybe = (crypto as unknown as { pbkdf2?: unknown }).pbkdf2;
+      return typeof maybe === 'function' ? (maybe as (...args: unknown[]) => unknown) : undefined;
+    } catch {
+      return undefined;
+    }
+  })();
+
+  const pbkdf2SyncFn = (() => {
+    try {
+      const maybe = (crypto as unknown as { pbkdf2Sync?: unknown }).pbkdf2Sync;
+      return typeof maybe === 'function' ? (maybe as (...args: unknown[]) => unknown) : undefined;
+    } catch {
+      return undefined;
+    }
+  })();
+
+  let hashHex = '';
+  if (pbkdf2Fn) {
+    const pbkdf2Async = promisify(
+      pbkdf2Fn as (
+        p: string,
+        s: string,
+        i: number,
+        k: number,
+        d: string,
+        callback: (err: Error | null, result: Buffer) => void
+      ) => void
+    );
+    hashHex = (await pbkdf2Async(password, salt, iterations, keyLength, digest)).toString('hex');
+  } else if (pbkdf2SyncFn) {
+    hashHex = (pbkdf2SyncFn(password, salt, iterations, keyLength, digest) as Buffer).toString(
+      'hex'
+    );
+  } else {
+    throw ErrorFactory.createSecurityError('PBKDF2 is not available in this runtime');
+  }
+
+  // Format: algorithm$iterations$salt$hash
+  return `pbkdf2$${iterations}$${salt}$${hashHex}`;
+}
+
+/**
+ * Verify PBKDF2 hash
+ */
+async function verifyPbkdf2(password: string, passwordHash: string): Promise<boolean> {
+  const parts = passwordHash.split('$');
+  const iterationsStr = parts[1];
+  const salt = parts[2];
+  const storedHash = parts[3];
+
+  if (iterationsStr === undefined || salt === undefined || storedHash === undefined) {
+    return false;
+  }
+
+  try {
+    const iterations = Number.parseInt(iterationsStr, 10);
+    const keyLength = 64;
+    const digest = 'sha256';
+
+    const pbkdf2Fn = (() => {
+      try {
+        const maybe = (crypto as unknown as { pbkdf2?: unknown }).pbkdf2;
+        return typeof maybe === 'function' ? (maybe as (...args: unknown[]) => unknown) : undefined;
+      } catch {
+        return undefined;
+      }
+    })();
+
+    const pbkdf2SyncFn = (() => {
+      try {
+        const maybe = (crypto as unknown as { pbkdf2Sync?: unknown }).pbkdf2Sync;
+        return typeof maybe === 'function' ? (maybe as (...args: unknown[]) => unknown) : undefined;
+      } catch {
+        return undefined;
+      }
+    })();
+
+    let computed = '';
+    if (pbkdf2Fn) {
+      const pbkdf2Async = promisify(
+        pbkdf2Fn as (
+          p: string,
+          s: string,
+          i: number,
+          k: number,
+          d: string,
+          callback: (err: Error | null, result: Buffer) => void
+        ) => void
+      );
+      computed = (await pbkdf2Async(password, salt, iterations, keyLength, digest)).toString('hex');
+    } else if (pbkdf2SyncFn) {
+      computed = (pbkdf2SyncFn(password, salt, iterations, keyLength, digest) as Buffer).toString(
+        'hex'
+      );
+    } else {
+      throw ErrorFactory.createSecurityError('PBKDF2 is not available in this runtime');
+    }
+
+    return timingSafeEquals(computed, storedHash);
+  } catch (error) {
+    Logger.error('PBKDF2 verification failed', error);
+    ErrorFactory.createSecurityError('PBKDF2 verification failed', error);
+    return false;
+  }
+}
+
+/**
+ * Hash with bcrypt
+ */
+async function hashBcrypt(bcryptModule: BcryptModule, password: string): Promise<string> {
+  const rounds = 12;
+  return bcryptModule.hash(password, rounds);
+}
+
+/**
+ * Verify bcrypt hash
+ */
+async function verifyBcrypt(
+  bcryptModule: BcryptModule,
+  password: string,
+  passwordHash: string
+): Promise<boolean> {
+  return bcryptModule.compare(password, passwordHash);
+}
+
+export interface IEncryptor {
+  hash(password: string): Promise<string>;
+  verify(password: string, hash: string): Promise<boolean>;
+  getAlgorithm(): HashAlgorithm;
+}
+
+/**
+ * Encryptor handles password hashing and verification
+ * Refactored to Functional Object pattern
+ */
+const hash = async (password: string): Promise<string> => {
+  await ensureLoaded();
+  if (algorithm === 'bcrypt' && bcrypt !== undefined) {
+    return hashBcrypt(bcrypt, password);
+  }
+  return hashPbkdf2(password);
+};
+
+/**
+ * Verify password against hash
+ */
+const verify = async (password: string, passwordHash: string): Promise<boolean> => {
+  await ensureLoaded();
+  // Detect hash format
+  if (passwordHash.startsWith('$2')) {
+    // bcrypt hash format
+    if (bcrypt !== undefined) {
+      return verifyBcrypt(bcrypt, password, passwordHash);
+    }
+    throw ErrorFactory.createConfigError('bcrypt not available to verify hash');
+  }
+
+  // PBKDF2 hash format (algorithm$iterations$salt$hash)
+  return verifyPbkdf2(password, passwordHash);
+};
+
+/**
+ * Get current algorithm
+ */
+const getAlgorithm = (): HashAlgorithm => {
+  return algorithm;
+};
+
+export const Encryptor: IEncryptor = Object.freeze({
+  hash,
+  verify,
+  getAlgorithm,
+});