aiox-core 5.0.0 → 5.0.2

package/pro/license/license-crypto.js

@@ -0,0 +1,303 @@
+/**
+ * License Crypto Module
+ *
+ * Provides cryptographic utilities for license cache encryption:
+ * - Machine ID generation (deterministic fingerprint)
+ * - PBKDF2 key derivation
+ * - AES-256-GCM encryption/decryption
+ * - HMAC-SHA256 integrity verification
+ *
+ * @module pro/license/license-crypto
+ * @see ADR-PRO-003 - Feature Gating & Licensing
+ * @see Story PRO-6 - License Key & Feature Gating System
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const os = require('os');
+
+/**
+ * Configuration constants for cryptographic operations.
+ * These values follow security best practices per ADR-PRO-003.
+ */
+const CONFIG = {
+  // PBKDF2 settings
+  PBKDF2_ITERATIONS: 100000, // Minimum per ADR-PRO-003
+  PBKDF2_KEY_LENGTH: 32, // 256 bits for AES-256
+  PBKDF2_DIGEST: 'sha256',
+
+  // AES-256-GCM settings
+  AES_ALGORITHM: 'aes-256-gcm',
+  AES_IV_LENGTH: 12, // 96 bits recommended for GCM
+  AES_TAG_LENGTH: 16, // 128 bits auth tag
+
+  // HMAC settings
+  HMAC_ALGORITHM: 'sha256',
+
+  // Salt settings
+  SALT_LENGTH: 16, // 128 bits
+};
+
+/**
+ * Generate a deterministic machine identifier.
+ *
+ * Combines hostname + CPU model + first MAC address to create
+ * a unique but reproducible identifier for this machine.
+ *
+ * @returns {string} SHA-256 hash of machine fingerprint components
+ */
+function generateMachineId() {
+  const components = [];
+
+  // Hostname
+  const hostname = os.hostname();
+  components.push(hostname);
+
+  // CPU model (first CPU)
+  const cpus = os.cpus();
+  if (cpus.length > 0) {
+    components.push(cpus[0].model);
+  }
+
+  // First non-internal MAC address
+  const networkInterfaces = os.networkInterfaces();
+  for (const [, interfaces] of Object.entries(networkInterfaces)) {
+    for (const iface of interfaces) {
+      if (!iface.internal && iface.mac && iface.mac !== '00:00:00:00:00:00') {
+        components.push(iface.mac);
+        break;
+      }
+    }
+    // Only use first valid MAC
+    if (components.length > 2) {
+      break;
+    }
+  }
+
+  // Create deterministic hash
+  const fingerprint = components.join('|');
+  return crypto.createHash('sha256').update(fingerprint).digest('hex');
+}
+
+/**
+ * Generate a cryptographically secure random salt.
+ *
+ * @param {number} [length=16] - Salt length in bytes
+ * @returns {Buffer} Random salt buffer
+ */
+function generateSalt(length = CONFIG.SALT_LENGTH) {
+  return crypto.randomBytes(length);
+}
+
+/**
+ * Derive an encryption key from machine ID using PBKDF2.
+ *
+ * Uses 100,000 iterations minimum per ADR-PRO-003 security requirements.
+ *
+ * @param {string} machineId - Machine identifier from generateMachineId()
+ * @param {Buffer|string} salt - Random salt (Buffer or hex string)
+ * @returns {Buffer} 256-bit derived key
+ */
+function deriveCacheKey(machineId, salt) {
+  const saltBuffer = Buffer.isBuffer(salt) ? salt : Buffer.from(salt, 'hex');
+
+  return crypto.pbkdf2Sync(
+    machineId,
+    saltBuffer,
+    CONFIG.PBKDF2_ITERATIONS,
+    CONFIG.PBKDF2_KEY_LENGTH,
+    CONFIG.PBKDF2_DIGEST,
+  );
+}
+
+/**
+ * Encrypt data using AES-256-GCM.
+ *
+ * Returns an object containing the encrypted ciphertext, initialization vector,
+ * and authentication tag for integrity verification.
+ *
+ * @param {string|object} data - Data to encrypt (objects are JSON stringified)
+ * @param {Buffer|string} key - 256-bit encryption key (Buffer or hex string)
+ * @returns {{ ciphertext: string, iv: string, tag: string }} Encrypted data components (hex encoded)
+ * @throws {Error} If encryption fails
+ */
+function encrypt(data, key) {
+  const keyBuffer = Buffer.isBuffer(key) ? key : Buffer.from(key, 'hex');
+
+  if (keyBuffer.length !== 32) {
+    throw new Error('Encryption key must be 256 bits (32 bytes)');
+  }
+
+  // Generate random IV
+  const iv = crypto.randomBytes(CONFIG.AES_IV_LENGTH);
+
+  // Stringify objects
+  const plaintext = typeof data === 'object' ? JSON.stringify(data) : String(data);
+
+  // Create cipher and encrypt
+  const cipher = crypto.createCipheriv(CONFIG.AES_ALGORITHM, keyBuffer, iv, {
+    authTagLength: CONFIG.AES_TAG_LENGTH,
+  });
+
+  let ciphertext = cipher.update(plaintext, 'utf8', 'hex');
+  ciphertext += cipher.final('hex');
+
+  // Get auth tag
+  const tag = cipher.getAuthTag();
+
+  return {
+    ciphertext,
+    iv: iv.toString('hex'),
+    tag: tag.toString('hex'),
+  };
+}
+
+/**
+ * Decrypt data using AES-256-GCM.
+ *
+ * Verifies the authentication tag to ensure data integrity.
+ *
+ * @param {{ ciphertext: string, iv: string, tag: string }} encryptedData - Encrypted data object
+ * @param {Buffer|string} key - 256-bit encryption key (Buffer or hex string)
+ * @param {boolean} [parseJson=true] - Whether to parse result as JSON
+ * @returns {string|object} Decrypted data
+ * @throws {Error} If decryption fails or authentication fails
+ */
+function decrypt(encryptedData, key, parseJson = true) {
+  const { ciphertext, iv, tag } = encryptedData;
+
+  const keyBuffer = Buffer.isBuffer(key) ? key : Buffer.from(key, 'hex');
+
+  if (keyBuffer.length !== 32) {
+    throw new Error('Decryption key must be 256 bits (32 bytes)');
+  }
+
+  const ivBuffer = Buffer.from(iv, 'hex');
+  const tagBuffer = Buffer.from(tag, 'hex');
+
+  // Create decipher
+  const decipher = crypto.createDecipheriv(CONFIG.AES_ALGORITHM, keyBuffer, ivBuffer, {
+    authTagLength: CONFIG.AES_TAG_LENGTH,
+  });
+
+  decipher.setAuthTag(tagBuffer);
+
+  let plaintext = decipher.update(ciphertext, 'hex', 'utf8');
+  plaintext += decipher.final('utf8');
+
+  // Optionally parse as JSON
+  if (parseJson) {
+    try {
+      return JSON.parse(plaintext);
+    } catch {
+      // Return as string if not valid JSON
+      return plaintext;
+    }
+  }
+
+  return plaintext;
+}
+
+/**
+ * Compute HMAC-SHA256 for data integrity verification.
+ *
+ * @param {string|Buffer} data - Data to compute HMAC for
+ * @param {Buffer|string} key - HMAC key (Buffer or hex string)
+ * @returns {string} HMAC as hex string
+ */
+function computeHMAC(data, key) {
+  const keyBuffer = Buffer.isBuffer(key) ? key : Buffer.from(key, 'hex');
+  const dataString = Buffer.isBuffer(data) ? data.toString('utf8') : String(data);
+
+  return crypto.createHmac(CONFIG.HMAC_ALGORITHM, keyBuffer).update(dataString).digest('hex');
+}
+
+/**
+ * Verify HMAC matches expected value.
+ *
+ * Uses timing-safe comparison to prevent timing attacks.
+ *
+ * @param {string|Buffer} data - Data to verify
+ * @param {Buffer|string} key - HMAC key
+ * @param {string} expectedHmac - Expected HMAC value (hex string)
+ * @returns {boolean} true if HMAC matches
+ */
+function verifyHMAC(data, key, expectedHmac) {
+  const computedHmac = computeHMAC(data, key);
+
+  // Use timing-safe comparison
+  const computedBuffer = Buffer.from(computedHmac, 'hex');
+  const expectedBuffer = Buffer.from(expectedHmac, 'hex');
+
+  if (computedBuffer.length !== expectedBuffer.length) {
+    return false;
+  }
+
+  return crypto.timingSafeEqual(computedBuffer, expectedBuffer);
+}
+
+/**
+ * Mask a license key for display.
+ *
+ * Shows only first and last 4 characters: PRO-XXXX-****-****-XXXX
+ * CRITICAL: Always use this function when logging or displaying keys.
+ *
+ * @param {string} key - Full license key
+ * @returns {string} Masked key for display
+ */
+function maskKey(key) {
+  if (!key || typeof key !== 'string') {
+    return '****-****-****-****';
+  }
+
+  // Handle PRO-XXXX-XXXX-XXXX-XXXX format
+  const parts = key.split('-');
+  if (parts.length !== 5 || parts[0] !== 'PRO') {
+    // Non-standard format, mask all but first/last 4
+    if (key.length <= 8) {
+      return '****';
+    }
+    return `${key.slice(0, 4)}-****-****-${key.slice(-4)}`;
+  }
+
+  // Standard format: PRO-XXXX-XXXX-XXXX-XXXX
+  return `${parts[0]}-${parts[1]}-****-****-${parts[4]}`;
+}
+
+/**
+ * Validate license key format.
+ *
+ * Expected format: PRO-XXXX-XXXX-XXXX-XXXX
+ * Where X is alphanumeric (A-Z0-9)
+ *
+ * @param {string} key - License key to validate
+ * @returns {boolean} true if format is valid
+ */
+function validateKeyFormat(key) {
+  if (!key || typeof key !== 'string') {
+    return false;
+  }
+
+  // Format: PRO-XXXX-XXXX-XXXX-XXXX (uppercase alphanumeric)
+  const pattern = /^PRO-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$/;
+  return pattern.test(key);
+}
+
+module.exports = {
+  // Core functions per ADR-PRO-003
+  generateMachineId,
+  deriveCacheKey,
+  encrypt,
+  decrypt,
+  computeHMAC,
+
+  // Additional utilities
+  generateSalt,
+  verifyHMAC,
+  maskKey,
+  validateKeyFormat,
+
+  // Exported for testing
+  _CONFIG: CONFIG,
+};