aiox-core 5.0.0 → 5.0.2

package/pro/license/feature-gate.js

@@ -0,0 +1,354 @@
+/**
+ * Feature Gate Module
+ *
+ * Singleton class that validates feature availability based on license cache.
+ * Supports exact feature ID matching and wildcard patterns.
+ *
+ * Usage:
+ *   const { featureGate } = require('./feature-gate');
+ *
+ *   // Check availability
+ *   if (featureGate.isAvailable('pro.squads.premium')) {
+ *     // Feature is licensed
+ *   }
+ *
+ *   // Require feature (throws if not available)
+ *   featureGate.require('pro.squads.premium', 'Premium Squads');
+ *
+ * @module pro/license/feature-gate
+ * @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 yaml = require('yaml');
+const { readLicenseCache, isExpired, isInGracePeriod, getLicenseState } = require('./license-cache');
+const { ProFeatureError } = require('./errors');
+
+/**
+ * Path to the feature registry YAML file.
+ */
+const REGISTRY_PATH = path.join(__dirname, '..', 'feature-registry.yaml');
+
+/**
+ * FeatureGate class - validates feature availability.
+ *
+ * Singleton pattern ensures consistent state across the application.
+ */
+class FeatureGate {
+  constructor() {
+    this._cache = null;
+    this._licensedFeatures = new Set();
+    this._registeredFeatures = new Map();
+    this._lastLoadTime = null;
+    this._cacheLoaded = false;
+    this._registryLoaded = false;
+  }
+
+  /**
+   * Load the feature registry from YAML.
+   *
+   * @private
+   */
+  _loadRegistry() {
+    if (this._registryLoaded) {
+      return;
+    }
+
+    try {
+      if (fs.existsSync(REGISTRY_PATH)) {
+        const content = fs.readFileSync(REGISTRY_PATH, 'utf8');
+        const registry = yaml.parse(content);
+
+        // Extract all features from modules
+        const modules = ['squads', 'memory', 'metrics', 'integrations', 'agents', 'cli', 'config'];
+
+        for (const module of modules) {
+          if (registry[module] && Array.isArray(registry[module])) {
+            for (const feature of registry[module]) {
+              this._registeredFeatures.set(feature.id, {
+                id: feature.id,
+                name: feature.name,
+                description: feature.description,
+                module: feature.module,
+              });
+            }
+          }
+        }
+
+        this._registryLoaded = true;
+      }
+    } catch {
+      // Registry load failed, features will still work via license patterns
+      this._registryLoaded = true;
+    }
+  }
+
+  /**
+   * Load the license cache and populate licensed features.
+   *
+   * @private
+   * @param {boolean} [force=false] - Force reload even if already loaded
+   */
+  _loadCache(force = false) {
+    if (this._cacheLoaded && !force) {
+      return;
+    }
+
+    // Load registry if not loaded
+    this._loadRegistry();
+
+    // Read license cache
+    this._cache = readLicenseCache();
+    this._licensedFeatures.clear();
+    this._lastLoadTime = Date.now();
+
+    if (!this._cache) {
+      this._cacheLoaded = true;
+      return;
+    }
+
+    // Check if cache is valid (not expired, or in grace period)
+    const state = getLicenseState(this._cache);
+
+    if (state === 'Expired') {
+      // Expired and past grace period - no features available
+      // Keep cache reference so getLicenseState can report 'Expired'
+      this._cacheLoaded = true;
+      return;
+    }
+
+    // Populate licensed features from cache
+    if (this._cache.features && Array.isArray(this._cache.features)) {
+      for (const featurePattern of this._cache.features) {
+        this._licensedFeatures.add(featurePattern);
+      }
+    }
+
+    this._cacheLoaded = true;
+  }
+
+  /**
+   * Check if a feature pattern matches a feature ID using wildcard matching.
+   *
+   * Supports:
+   * - Exact match: "pro.squads.premium" matches "pro.squads.premium"
+   * - Wildcard: "pro.squads.*" matches "pro.squads.premium", "pro.squads.custom"
+   * - Module wildcard: "pro.*" matches any pro feature
+   *
+   * @private
+   * @param {string} featureId - Feature ID to check
+   * @param {string} pattern - Pattern from license
+   * @returns {boolean} true if pattern matches feature ID
+   */
+  _matchWildcard(featureId, pattern) {
+    // Exact match
+    if (pattern === featureId) {
+      return true;
+    }
+
+    // Wildcard match: "pro.*" matches "pro.squads.premium"
+    if (pattern.endsWith('.*')) {
+      const prefix = pattern.slice(0, -1); // Remove trailing * → "pro."
+      return featureId.startsWith(prefix);
+    }
+
+    // BUG-7 fix (INS-1): Bare module pattern without dots (e.g., "pro")
+    // should match all features under that module (equivalent to "pro.*")
+    if (!pattern.includes('.') && featureId.startsWith(pattern + '.')) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if a feature is available (licensed).
+   *
+   * Performance: < 5ms (cache read only, per AC-13)
+   *
+   * @param {string} featureId - Feature ID to check (e.g., "pro.squads.premium")
+   * @returns {boolean} true if feature is licensed and available
+   */
+  isAvailable(featureId) {
+    this._loadCache();
+
+    if (this._licensedFeatures.size === 0) {
+      return false;
+    }
+
+    // Check direct match first (O(1))
+    if (this._licensedFeatures.has(featureId)) {
+      return true;
+    }
+
+    // Check wildcard patterns
+    for (const pattern of this._licensedFeatures) {
+      if (this._matchWildcard(featureId, pattern)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Require a feature to be available, throw if not.
+   *
+   * Use this to gate premium functionality:
+   *
+   *   featureGate.require('pro.squads.premium', 'Premium Squads');
+   *
+   * @param {string} featureId - Feature ID to require
+   * @param {string} [friendlyName] - Human-friendly feature name for error message
+   * @throws {ProFeatureError} If feature is not licensed
+   */
+  require(featureId, friendlyName) {
+    if (!this.isAvailable(featureId)) {
+      const name = friendlyName || this._getFeatureName(featureId) || featureId;
+      throw new ProFeatureError(featureId, name);
+    }
+  }
+
+  /**
+   * Get the friendly name of a feature from registry.
+   *
+   * @private
+   * @param {string} featureId - Feature ID
+   * @returns {string|null} Feature name or null
+   */
+  _getFeatureName(featureId) {
+    this._loadRegistry();
+    const feature = this._registeredFeatures.get(featureId);
+    return feature ? feature.name : null;
+  }
+
+  /**
+   * List all available (licensed) feature IDs.
+   *
+   * Returns the resolved list of feature IDs, expanding wildcards
+   * against the registry.
+   *
+   * @returns {string[]} Array of available feature IDs
+   */
+  listAvailable() {
+    this._loadCache();
+    this._loadRegistry();
+
+    const available = new Set();
+
+    // Check each registered feature against licensed patterns
+    for (const [featureId] of this._registeredFeatures) {
+      if (this.isAvailable(featureId)) {
+        available.add(featureId);
+      }
+    }
+
+    return Array.from(available).sort();
+  }
+
+  /**
+   * List all registered features with their availability status.
+   *
+   * @returns {Array<{ id: string, name: string, description: string, module: string, available: boolean }>}
+   */
+  listAll() {
+    this._loadCache();
+    this._loadRegistry();
+
+    const features = [];
+
+    for (const [featureId, feature] of this._registeredFeatures) {
+      features.push({
+        ...feature,
+        available: this.isAvailable(featureId),
+      });
+    }
+
+    return features.sort((a, b) => a.id.localeCompare(b.id));
+  }
+
+  /**
+   * List features grouped by module.
+   *
+   * @returns {Object<string, Array<{ id: string, name: string, available: boolean }>>}
+   */
+  listByModule() {
+    const all = this.listAll();
+    const grouped = {};
+
+    for (const feature of all) {
+      if (!grouped[feature.module]) {
+        grouped[feature.module] = [];
+      }
+      grouped[feature.module].push(feature);
+    }
+
+    return grouped;
+  }
+
+  /**
+   * Force reload of the license cache.
+   *
+   * Call this after activation to pick up new features.
+   */
+  reload() {
+    this._cacheLoaded = false;
+    this._loadCache(true);
+  }
+
+  /**
+   * Get the current license state.
+   *
+   * @returns {'Active'|'Expired'|'Grace'|'Not Activated'} License state
+   */
+  getLicenseState() {
+    this._loadCache();
+    return getLicenseState(this._cache);
+  }
+
+  /**
+   * Get license information for display.
+   *
+   * @returns {{ state: string, features: string[], inGrace: boolean } | null}
+   */
+  getLicenseInfo() {
+    this._loadCache();
+
+    if (!this._cache) {
+      return null;
+    }
+
+    return {
+      state: getLicenseState(this._cache),
+      features: Array.from(this._licensedFeatures),
+      inGrace: isInGracePeriod(this._cache),
+      isExpired: isExpired(this._cache),
+    };
+  }
+
+  /**
+   * Clear internal state (for testing).
+   *
+   * @private
+   */
+  _reset() {
+    this._cache = null;
+    this._licensedFeatures.clear();
+    this._registeredFeatures.clear();
+    this._lastLoadTime = null;
+    this._cacheLoaded = false;
+    this._registryLoaded = false;
+  }
+}
+
+// Singleton instance
+const featureGate = new FeatureGate();
+
+module.exports = {
+  FeatureGate,
+  featureGate,
+};

package/pro/license/index.js

@@ -0,0 +1,181 @@
+/**
+ * License Module - Public API
+ *
+ * This module provides the public interface for license management
+ * and feature gating in AIOS Pro.
+ *
+ * Usage:
+ *   const { featureGate, licenseApi } = require('@aios-fullstack/pro/license');
+ *
+ *   // Check feature availability
+ *   if (featureGate.isAvailable('pro.squads.premium')) {
+ *     // Feature is licensed
+ *   }
+ *
+ *   // Require feature (throws if not available)
+ *   featureGate.require('pro.squads.premium', 'Premium Squads');
+ *
+ *   // Activate license
+ *   await licenseApi.activate(key, machineId, version);
+ *
+ * @module pro/license
+ * @see ADR-PRO-003 - Feature Gating & Licensing
+ * @see Story PRO-6 - License Key & Feature Gating System
+ */
+
+'use strict';
+
+// Feature gating
+const { FeatureGate, featureGate } = require('./feature-gate');
+
+// License cache operations
+const {
+  writeLicenseCache,
+  readLicenseCache,
+  deleteLicenseCache,
+  isExpired,
+  isInGracePeriod,
+  getDaysRemaining,
+  getExpiryDate,
+  getLicenseState,
+  setPendingDeactivation,
+  hasPendingDeactivation,
+  markPendingDeactivationSynced,
+  clearPendingDeactivation,
+} = require('./license-cache');
+
+// License API client
+const { LicenseApiClient, licenseApi } = require('./license-api');
+
+// Crypto utilities
+const {
+  generateMachineId,
+  maskKey,
+  validateKeyFormat,
+} = require('./license-crypto');
+
+// Error classes
+const {
+  ProFeatureError,
+  LicenseActivationError,
+  LicenseValidationError,
+} = require('./errors');
+
+// Graceful degradation utilities
+const {
+  withGracefulDegradation,
+  ifProAvailable,
+  getFeatureFriendlyName,
+  logDegradationMessage,
+  createDegradationWrapper,
+  isInDegradedMode,
+  getDegradationStatus,
+} = require('./degradation');
+
+/**
+ * Convenience function to check if a feature is available.
+ *
+ * @param {string} featureId - Feature ID to check
+ * @returns {boolean} true if feature is licensed
+ */
+function isFeatureAvailable(featureId) {
+  return featureGate.isAvailable(featureId);
+}
+
+/**
+ * Convenience function to require a feature.
+ *
+ * @param {string} featureId - Feature ID to require
+ * @param {string} [friendlyName] - Human-friendly name for error message
+ * @throws {ProFeatureError} If feature is not licensed
+ */
+function requireFeature(featureId, friendlyName) {
+  featureGate.require(featureId, friendlyName);
+}
+
+/**
+ * Convenience function to get the current license state.
+ *
+ * @returns {'Active'|'Expired'|'Grace'|'Not Activated'} License state
+ */
+function getCurrentLicenseState() {
+  return featureGate.getLicenseState();
+}
+
+/**
+ * Convenience function to get license info.
+ *
+ * @returns {{ state: string, features: string[], inGrace: boolean } | null}
+ */
+function getLicenseInfo() {
+  return featureGate.getLicenseInfo();
+}
+
+/**
+ * Convenience function to list available features.
+ *
+ * @returns {string[]} Array of available feature IDs
+ */
+function listAvailableFeatures() {
+  return featureGate.listAvailable();
+}
+
+/**
+ * Reload license cache (after activation/deactivation).
+ */
+function reloadLicense() {
+  featureGate.reload();
+}
+
+module.exports = {
+  // Primary exports - Feature Gate
+  FeatureGate,
+  featureGate,
+
+  // Primary exports - API Client
+  LicenseApiClient,
+  licenseApi,
+
+  // Error classes
+  ProFeatureError,
+  LicenseActivationError,
+  LicenseValidationError,
+
+  // Cache operations
+  writeLicenseCache,
+  readLicenseCache,
+  deleteLicenseCache,
+  isExpired,
+  isInGracePeriod,
+  getDaysRemaining,
+  getExpiryDate,
+  getLicenseState,
+
+  // Pending deactivation
+  setPendingDeactivation,
+  hasPendingDeactivation,
+  markPendingDeactivationSynced,
+  clearPendingDeactivation,
+
+  // Crypto utilities
+  generateMachineId,
+  maskKey,
+  validateKeyFormat,
+
+  // Convenience functions
+  isFeatureAvailable,
+  requireFeature,
+  getCurrentLicenseState,
+  getLicenseInfo,
+  listAvailableFeatures,
+  reloadLicense,
+
+  // Graceful degradation (AC-8)
+  withGracefulDegradation,
+  ifProAvailable,
+  getFeatureFriendlyName,
+  logDegradationMessage,
+  createDegradationWrapper,
+  isInDegradedMode,
+  getDegradationStatus,
+};