aiox-core 5.0.0 → 5.0.2

package/pro/license/license-cache.js

@@ -0,0 +1,523 @@
+/**
+ * License Cache Module
+ *
+ * Manages encrypted license cache file operations:
+ * - Write encrypted cache with HMAC integrity
+ * - Read and verify cache with tamper detection
+ * - Expiry and grace period calculations
+ * - Atomic file operations for data safety
+ * - Pending deactivation tracking for offline scenarios
+ *
+ * Cache file: .aiox/license.cache (encrypted, gitignored)
+ *
+ * @module pro/license/license-cache
+ * @see ADR-PRO-003 - Feature Gating & Licensing
+ * @see Story PRO-6 - License Key & Feature Gating System
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  generateMachineId,
+  generateSalt,
+  deriveCacheKey,
+  encrypt,
+  decrypt,
+  computeHMAC,
+  verifyHMAC,
+} = require('./license-crypto');
+
+/**
+ * Configuration constants for cache operations.
+ */
+const CONFIG = {
+  // Default expiry settings (per ADR-PRO-003)
+  DEFAULT_CACHE_VALID_DAYS: 30,
+  DEFAULT_GRACE_PERIOD_DAYS: 7,
+
+  // File paths
+  AIOX_DIR: '.aiox',
+  CACHE_FILENAME: 'license.cache',
+  PENDING_DEACTIVATION_FILENAME: 'pending-deactivation.json',
+
+  // Cache version for migration support
+  CACHE_VERSION: 1,
+};
+
+/**
+ * Get the directory path for AIOX cache files.
+ *
+ * Uses project root (cwd) by default, falls back to home directory.
+ *
+ * @param {string} [baseDir] - Optional base directory override
+ * @returns {string} Full path to .aiox directory
+ */
+function getAioxDir(baseDir = process.cwd()) {
+  return path.join(baseDir, CONFIG.AIOX_DIR);
+}
+
+/**
+ * Get the full path to the license cache file.
+ *
+ * @param {string} [baseDir] - Optional base directory override
+ * @returns {string} Full path to license.cache
+ */
+function getCachePath(baseDir) {
+  return path.join(getAioxDir(baseDir), CONFIG.CACHE_FILENAME);
+}
+
+/**
+ * Get the full path to the pending deactivation file.
+ *
+ * @param {string} [baseDir] - Optional base directory override
+ * @returns {string} Full path to pending-deactivation.json
+ */
+function getPendingDeactivationPath(baseDir) {
+  return path.join(getAioxDir(baseDir), CONFIG.PENDING_DEACTIVATION_FILENAME);
+}
+
+/**
+ * Ensure the .aiox directory exists.
+ *
+ * @param {string} [baseDir] - Optional base directory override
+ */
+function ensureAioxDir(baseDir) {
+  const aioxDir = getAioxDir(baseDir);
+  if (!fs.existsSync(aioxDir)) {
+    fs.mkdirSync(aioxDir, { recursive: true });
+  }
+}
+
+/**
+ * Write license cache to disk with encryption and integrity protection.
+ *
+ * Uses atomic write (temp file → rename) for crash safety.
+ *
+ * Cache format on disk:
+ * {
+ *   "encrypted": "<AES-256-GCM ciphertext>",
+ *   "iv": "<initialization vector>",
+ *   "tag": "<auth tag>",
+ *   "hmac": "<HMAC-SHA256 of encrypted content>",
+ *   "salt": "<PBKDF2 salt>",
+ *   "version": 1
+ * }
+ *
+ * @param {object} data - License data to cache
+ * @param {string} data.key - License key (PRO-XXXX-XXXX-XXXX-XXXX)
+ * @param {string} data.activatedAt - ISO timestamp of activation
+ * @param {string} data.expiresAt - ISO timestamp of expiry
+ * @param {string[]} data.features - Array of enabled feature IDs
+ * @param {object} data.seats - Seat usage info { used, max }
+ * @param {number} [data.cacheValidDays=30] - Days until cache expires
+ * @param {number} [data.gracePeriodDays=7] - Grace period after expiry
+ * @param {string} [baseDir] - Optional base directory override
+ * @returns {{ success: boolean, error?: string }} Write result
+ */
+function writeLicenseCache(data, baseDir) {
+  try {
+    ensureAioxDir(baseDir);
+
+    // Generate machine-specific encryption key
+    const machineId = generateMachineId();
+    const salt = generateSalt();
+    const key = deriveCacheKey(machineId, salt);
+
+    // Add metadata to cache data
+    const cacheData = {
+      ...data,
+      machineId, // Store for verification (hashed, not sensitive)
+      cacheValidDays: data.cacheValidDays || CONFIG.DEFAULT_CACHE_VALID_DAYS,
+      gracePeriodDays: data.gracePeriodDays || CONFIG.DEFAULT_GRACE_PERIOD_DAYS,
+      version: CONFIG.CACHE_VERSION,
+    };
+
+    // Encrypt the data
+    const encrypted = encrypt(cacheData, key);
+
+    // Compute HMAC over encrypted content for integrity
+    const hmacData = JSON.stringify({
+      ciphertext: encrypted.ciphertext,
+      iv: encrypted.iv,
+      tag: encrypted.tag,
+    });
+    const hmac = computeHMAC(hmacData, key);
+
+    // Build cache file structure
+    const cacheFile = {
+      encrypted: encrypted.ciphertext,
+      iv: encrypted.iv,
+      tag: encrypted.tag,
+      hmac,
+      salt: salt.toString('hex'),
+      version: CONFIG.CACHE_VERSION,
+    };
+
+    // Atomic write: temp file → rename
+    const cachePath = getCachePath(baseDir);
+    const tempPath = `${cachePath}.tmp.${process.pid}`;
+
+    fs.writeFileSync(tempPath, JSON.stringify(cacheFile, null, 2), 'utf8');
+    fs.renameSync(tempPath, cachePath);
+
+    return { success: true };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Read and verify license cache from disk.
+ *
+ * Performs:
+ * 1. File existence check
+ * 2. JSON parsing
+ * 3. HMAC integrity verification
+ * 4. AES-256-GCM decryption with auth tag verification
+ * 5. Machine ID verification (cache non-portable)
+ *
+ * @param {string} [baseDir] - Optional base directory override
+ * @returns {object|null} Decrypted cache data or null if invalid/missing
+ */
+function readLicenseCache(baseDir) {
+  try {
+    const cachePath = getCachePath(baseDir);
+
+    // Check file exists
+    if (!fs.existsSync(cachePath)) {
+      return null;
+    }
+
+    // Read and parse
+    const fileContent = fs.readFileSync(cachePath, 'utf8');
+    const cacheFile = JSON.parse(fileContent);
+
+    // Validate structure
+    if (!cacheFile.encrypted || !cacheFile.iv || !cacheFile.tag || !cacheFile.hmac || !cacheFile.salt) {
+      return null;
+    }
+
+    // Derive key from current machine
+    const machineId = generateMachineId();
+    const salt = Buffer.from(cacheFile.salt, 'hex');
+    const key = deriveCacheKey(machineId, salt);
+
+    // Verify HMAC integrity
+    const hmacData = JSON.stringify({
+      ciphertext: cacheFile.encrypted,
+      iv: cacheFile.iv,
+      tag: cacheFile.tag,
+    });
+
+    if (!verifyHMAC(hmacData, key, cacheFile.hmac)) {
+      // HMAC mismatch: cache is tampered or from different machine
+      return null;
+    }
+
+    // Decrypt
+    const encryptedData = {
+      ciphertext: cacheFile.encrypted,
+      iv: cacheFile.iv,
+      tag: cacheFile.tag,
+    };
+
+    const decrypted = decrypt(encryptedData, key);
+
+    // Verify machine ID matches (defense in depth)
+    if (decrypted.machineId !== machineId) {
+      return null;
+    }
+
+    return decrypted;
+  } catch {
+    // Any error (parse, decrypt, etc.) means cache is invalid
+    return null;
+  }
+}
+
+/**
+ * Delete the license cache file.
+ *
+ * @param {string} [baseDir] - Optional base directory override
+ * @returns {{ success: boolean, error?: string }} Delete result
+ */
+function deleteLicenseCache(baseDir) {
+  try {
+    const cachePath = getCachePath(baseDir);
+
+    if (fs.existsSync(cachePath)) {
+      fs.unlinkSync(cachePath);
+    }
+
+    return { success: true };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Check if the license cache is expired.
+ *
+ * Expired means: current date > activatedAt + cacheValidDays
+ *
+ * @param {object} cache - Decrypted cache data
+ * @returns {boolean} true if cache is expired
+ */
+function isExpired(cache) {
+  if (!cache || !cache.activatedAt) {
+    return true;
+  }
+
+  const activatedAt = new Date(cache.activatedAt);
+  const cacheValidDays = cache.cacheValidDays || CONFIG.DEFAULT_CACHE_VALID_DAYS;
+
+  const expiryDate = new Date(activatedAt);
+  expiryDate.setDate(expiryDate.getDate() + cacheValidDays);
+
+  return new Date() > expiryDate;
+}
+
+/**
+ * Check if the license is in grace period.
+ *
+ * Grace period: cache is expired but within gracePeriodDays after expiry.
+ *
+ * @param {object} cache - Decrypted cache data
+ * @returns {boolean} true if in grace period
+ */
+function isInGracePeriod(cache) {
+  if (!cache || !cache.activatedAt) {
+    return false;
+  }
+
+  // Must be expired first
+  if (!isExpired(cache)) {
+    return false;
+  }
+
+  const activatedAt = new Date(cache.activatedAt);
+  const cacheValidDays = cache.cacheValidDays || CONFIG.DEFAULT_CACHE_VALID_DAYS;
+  const gracePeriodDays = cache.gracePeriodDays || CONFIG.DEFAULT_GRACE_PERIOD_DAYS;
+
+  // Calculate grace period end
+  const expiryDate = new Date(activatedAt);
+  expiryDate.setDate(expiryDate.getDate() + cacheValidDays);
+
+  const graceEndDate = new Date(expiryDate);
+  graceEndDate.setDate(graceEndDate.getDate() + gracePeriodDays);
+
+  return new Date() <= graceEndDate;
+}
+
+/**
+ * Get the number of days remaining until cache expires.
+ *
+ * @param {object} cache - Decrypted cache data
+ * @returns {number} Days remaining (negative if expired)
+ */
+function getDaysRemaining(cache) {
+  if (!cache || !cache.activatedAt) {
+    return -1;
+  }
+
+  const activatedAt = new Date(cache.activatedAt);
+  const cacheValidDays = cache.cacheValidDays || CONFIG.DEFAULT_CACHE_VALID_DAYS;
+
+  const expiryDate = new Date(activatedAt);
+  expiryDate.setDate(expiryDate.getDate() + cacheValidDays);
+
+  const now = new Date();
+  const diffMs = expiryDate - now;
+  const diffDays = Math.ceil(diffMs / (1000 * 60 * 60 * 24));
+
+  return diffDays;
+}
+
+/**
+ * Get the expiry date of the cache.
+ *
+ * @param {object} cache - Decrypted cache data
+ * @returns {Date|null} Expiry date or null
+ */
+function getExpiryDate(cache) {
+  if (!cache || !cache.activatedAt) {
+    return null;
+  }
+
+  const activatedAt = new Date(cache.activatedAt);
+  const cacheValidDays = cache.cacheValidDays || CONFIG.DEFAULT_CACHE_VALID_DAYS;
+
+  const expiryDate = new Date(activatedAt);
+  expiryDate.setDate(expiryDate.getDate() + cacheValidDays);
+
+  return expiryDate;
+}
+
+/**
+ * Get the license state based on cache.
+ *
+ * @param {object|null} cache - Decrypted cache data
+ * @returns {'Active'|'Expired'|'Grace'|'Not Activated'} License state
+ */
+function getLicenseState(cache) {
+  if (!cache) {
+    return 'Not Activated';
+  }
+
+  if (!isExpired(cache)) {
+    return 'Active';
+  }
+
+  if (isInGracePeriod(cache)) {
+    return 'Grace';
+  }
+
+  return 'Expired';
+}
+
+/**
+ * Store a pending deactivation flag.
+ *
+ * Used when user deactivates offline - the deactivation will
+ * be synced to the server on next online connection.
+ *
+ * @param {string} licenseKey - The license key being deactivated
+ * @param {string} [baseDir] - Optional base directory override
+ * @returns {{ success: boolean, error?: string }} Result
+ */
+function setPendingDeactivation(licenseKey, baseDir) {
+  try {
+    ensureAioxDir(baseDir);
+
+    const pendingPath = getPendingDeactivationPath(baseDir);
+    const machineId = generateMachineId();
+
+    const pendingData = {
+      licenseKey,
+      machineId,
+      deactivatedAt: new Date().toISOString(),
+      synced: false,
+    };
+
+    fs.writeFileSync(pendingPath, JSON.stringify(pendingData, null, 2), 'utf8');
+
+    return { success: true };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Check if there's a pending deactivation to sync.
+ *
+ * @param {string} [baseDir] - Optional base directory override
+ * @returns {{ pending: boolean, data?: object }} Pending status and data
+ */
+function hasPendingDeactivation(baseDir) {
+  try {
+    const pendingPath = getPendingDeactivationPath(baseDir);
+
+    if (!fs.existsSync(pendingPath)) {
+      return { pending: false };
+    }
+
+    const content = fs.readFileSync(pendingPath, 'utf8');
+    const data = JSON.parse(content);
+
+    if (data.synced) {
+      return { pending: false };
+    }
+
+    return { pending: true, data };
+  } catch {
+    return { pending: false };
+  }
+}
+
+/**
+ * Mark pending deactivation as synced.
+ *
+ * @param {string} [baseDir] - Optional base directory override
+ * @returns {{ success: boolean, error?: string }} Result
+ */
+function markPendingDeactivationSynced(baseDir) {
+  try {
+    const pendingPath = getPendingDeactivationPath(baseDir);
+
+    if (!fs.existsSync(pendingPath)) {
+      return { success: true };
+    }
+
+    const content = fs.readFileSync(pendingPath, 'utf8');
+    const data = JSON.parse(content);
+
+    data.synced = true;
+    data.syncedAt = new Date().toISOString();
+
+    fs.writeFileSync(pendingPath, JSON.stringify(data, null, 2), 'utf8');
+
+    return { success: true };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Clear the pending deactivation file.
+ *
+ * @param {string} [baseDir] - Optional base directory override
+ * @returns {{ success: boolean, error?: string }} Result
+ */
+function clearPendingDeactivation(baseDir) {
+  try {
+    const pendingPath = getPendingDeactivationPath(baseDir);
+
+    if (fs.existsSync(pendingPath)) {
+      fs.unlinkSync(pendingPath);
+    }
+
+    return { success: true };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Check if the cache file exists.
+ *
+ * @param {string} [baseDir] - Optional base directory override
+ * @returns {boolean} true if cache file exists
+ */
+function cacheExists(baseDir) {
+  return fs.existsSync(getCachePath(baseDir));
+}
+
+module.exports = {
+  // Core cache operations
+  writeLicenseCache,
+  readLicenseCache,
+  deleteLicenseCache,
+
+  // Expiry checks
+  isExpired,
+  isInGracePeriod,
+  getDaysRemaining,
+  getExpiryDate,
+  getLicenseState,
+
+  // Pending deactivation (offline scenario)
+  setPendingDeactivation,
+  hasPendingDeactivation,
+  markPendingDeactivationSynced,
+  clearPendingDeactivation,
+
+  // Utilities
+  cacheExists,
+  getCachePath,
+  getAioxDir,
+
+  // Exported for testing
+  _CONFIG: CONFIG,
+};