aiox-core 5.0.3 → 5.0.4

package/pro/license/license-api.js

@@ -1,679 +1,701 @@
-/**
- * License API Client
- *
- * HTTP client for communicating with the license validation server.
- * Supports activation, validation, deactivation, and offline sync.
- *
- * @module pro/license/license-api
- * @see ADR-PRO-003 - Feature Gating & Licensing
- * @see Story PRO-6 - License Key & Feature Gating System
- */
-
-'use strict';
-
-const https = require('https');
-const http = require('http');
-const { URL } = require('url');
-const { LicenseActivationError, AuthError, BuyerValidationError } = require('./errors');
-const { hasPendingDeactivation, clearPendingDeactivation } = require('./license-cache');
-
-/**
- * Default configuration.
- */
-const CONFIG = {
-  BASE_URL: process.env.AIOX_LICENSE_API_URL || 'https://aios-license-server.vercel.app',
-  TIMEOUT_MS: 10000,
-  MAX_RETRIES: 3,
-  RETRY_DELAY_MS: 1000,
-  USER_AGENT: 'AIOX-Pro-License-Client/1.0',
-};
-
-/**
- * LicenseApiClient - HTTP client for license operations.
- */
-class LicenseApiClient {
-  /**
-   * Create a LicenseApiClient.
-   *
-   * @param {object} [options] - Client options
-   * @param {string} [options.baseUrl] - Base URL for API (default: api.synkra.ai)
-   * @param {number} [options.timeoutMs] - Request timeout in ms (default: 10000)
-   */
-  constructor(options = {}) {
-    this.baseUrl = options.baseUrl || CONFIG.BASE_URL;
-    this.timeoutMs = options.timeoutMs || CONFIG.TIMEOUT_MS;
-  }
-
-  /**
-   * Make an HTTP request with timeout and abort support.
-   *
-   * @private
-   * @param {string} method - HTTP method
-   * @param {string} path - API path
-   * @param {object} body - Request body
-   * @returns {Promise<object>} Response data
-   * @throws {LicenseActivationError} On network or server errors
-   */
-  async _request(method, path, body) {
-    const url = new URL(path, this.baseUrl);
-    const isHttps = url.protocol === 'https:';
-    const client = isHttps ? https : http;
-
-    const requestData = JSON.stringify(body);
-
-    const options = {
-      method,
-      hostname: url.hostname,
-      port: url.port || (isHttps ? 443 : 80),
-      path: url.pathname + url.search,
-      headers: {
-        'Content-Type': 'application/json',
-        'Content-Length': Buffer.byteLength(requestData),
-        'User-Agent': CONFIG.USER_AGENT,
-        Accept: 'application/json',
-      },
-      timeout: this.timeoutMs,
-    };
-
-    return new Promise((resolve, reject) => {
-      const req = client.request(options, (res) => {
-        let data = '';
-
-        res.on('data', (chunk) => {
-          data += chunk;
-        });
-
-        res.on('end', () => {
-          try {
-            const response = data ? JSON.parse(data) : {};
-            this._handleResponse(res.statusCode, response, resolve, reject);
-          } catch {
-            reject(
-              new LicenseActivationError(
-                'Invalid response from license server',
-                'INVALID_RESPONSE',
-                { rawData: data.substring(0, 200) },
-              ),
-            );
-          }
-        });
-      });
-
-      // Handle request timeout
-      req.on('timeout', () => {
-        req.destroy();
-        reject(LicenseActivationError.networkError(new Error('Request timeout')));
-      });
-
-      // Handle request error
-      req.on('error', (error) => {
-        reject(LicenseActivationError.networkError(error));
-      });
-
-      // Send request body
-      req.write(requestData);
-      req.end();
-    });
-  }
-
-  /**
-   * Handle HTTP response based on status code.
-   *
-   * @private
-   * @param {number} statusCode - HTTP status code
-   * @param {object} response - Parsed response body
-   * @param {Function} resolve - Promise resolve
-   * @param {Function} reject - Promise reject
-   */
-  _handleResponse(statusCode, response, resolve, reject) {
-    // Success
-    if (statusCode >= 200 && statusCode < 300) {
-      resolve(response);
-      return;
-    }
-
-    // Normalize server error envelope: { error: { code, message, details } } → flat
-    const err = response.error || response;
-    const code = err.code;
-    const message = err.message;
-    const details = err.details;
-
-    // Client errors
-    switch (statusCode) {
-      case 400:
-        reject(
-          new LicenseActivationError(
-            message || 'Invalid request',
-            code || 'BAD_REQUEST',
-            details,
-          ),
-        );
-        break;
-
-      case 401:
-        // Preserve server error code (e.g., INVALID_CREDENTIALS, EMAIL_NOT_VERIFIED)
-        reject(
-          new LicenseActivationError(
-            message || 'Unauthorized',
-            code || 'INVALID_KEY',
-            details,
-          ),
-        );
-        break;
-
-      case 409:
-        reject(
-          new LicenseActivationError(
-            message || 'Conflict',
-            code || 'CONFLICT',
-            details,
-          ),
-        );
-        break;
-
-      case 403:
-        if (code === 'EXPIRED_KEY') {
-          reject(LicenseActivationError.expiredKey());
-        } else if (code === 'SEAT_LIMIT_EXCEEDED') {
-          reject(
-            LicenseActivationError.seatLimitExceeded(
-              details?.used || 0,
-              details?.max || 0,
-            ),
-          );
-        } else {
-          reject(
-            new LicenseActivationError(
-              message || 'Access forbidden',
-              code || 'FORBIDDEN',
-              details,
-            ),
-          );
-        }
-        break;
-
-      case 429:
-        reject(LicenseActivationError.rateLimited(err.retryAfter || response.retryAfter));
-        break;
-
-      case 500:
-      case 502:
-      case 503:
-      case 504:
-        // Preserve server error code if provided (e.g., BUYER_SERVICE_UNAVAILABLE)
-        if (code) {
-          reject(
-            new LicenseActivationError(
-              message || 'Server error',
-              code,
-              details,
-            ),
-          );
-        } else {
-          reject(LicenseActivationError.serverError());
-        }
-        break;
-
-      default:
-        // Preserve server error code/message when available
-        reject(
-          new LicenseActivationError(
-            message || `Unexpected response: ${statusCode}`,
-            code || 'UNEXPECTED_STATUS',
-            details || { statusCode, response },
-          ),
-        );
-    }
-  }
-
-  /**
-   * Activate a license key.
-   *
-   * @param {string} key - License key (PRO-XXXX-XXXX-XXXX-XXXX)
-   * @param {string} machineId - Machine fingerprint
-   * @param {string} aiosCoreVersion - AIOX Core version
-   * @returns {Promise<object>} Activation result with features, seats, cache info
-   * @throws {LicenseActivationError} On activation failure
-   */
-  async activate(key, machineId, aiosCoreVersion) {
-    // First, sync any pending deactivations
-    await this.syncPendingDeactivation(machineId);
-
-    const response = await this._request('POST', '/v1/license/activate', {
-      key,
-      machineId,
-      aiosCoreVersion,
-    });
-
-    // Validate response structure
-    if (!response.features || !Array.isArray(response.features)) {
-      throw new LicenseActivationError(
-        'Invalid activation response: missing features',
-        'INVALID_RESPONSE',
-      );
-    }
-
-    return {
-      key: response.key || key,
-      features: response.features,
-      seats: response.seats || { used: 1, max: 1 },
-      expiresAt: response.expiresAt,
-      cacheValidDays: response.cacheValidDays || 30,
-      gracePeriodDays: response.gracePeriodDays || 7,
-      activatedAt: new Date().toISOString(),
-    };
-  }
-
-  /**
-   * Validate an existing license.
-   *
-   * @param {string} key - License key
-   * @param {string} machineId - Machine fingerprint
-   * @returns {Promise<object>} Validation result
-   * @throws {LicenseActivationError} On validation failure
-   */
-  async validate(key, machineId) {
-    // First, sync any pending deactivations
-    await this.syncPendingDeactivation(machineId);
-
-    const response = await this._request('POST', '/v1/license/validate', {
-      key,
-      machineId,
-    });
-
-    return {
-      valid: response.valid !== false,
-      features: response.features || [],
-      seats: response.seats || { used: 1, max: 1 },
-      expiresAt: response.expiresAt,
-      cacheValidDays: response.cacheValidDays || 30,
-      gracePeriodDays: response.gracePeriodDays || 7,
-    };
-  }
-
-  /**
-   * Deactivate a license from this machine.
-   *
-   * @param {string} key - License key
-   * @param {string} machineId - Machine fingerprint
-   * @returns {Promise<object>} Deactivation result
-   * @throws {LicenseActivationError} On deactivation failure
-   */
-  async deactivate(key, machineId) {
-    const response = await this._request('POST', '/v1/license/deactivate', {
-      key,
-      machineId,
-    });
-
-    return {
-      success: response.success !== false,
-      seatFreed: response.seatFreed !== false,
-      message: response.message || 'License deactivated successfully',
-    };
-  }
-
-  /**
-   * Sync any pending offline deactivations with the server.
-   *
-   * This is called automatically before activate/validate operations.
-   *
-   * @param {string} machineId - Current machine ID for verification
-   * @param {string} [baseDir] - Base directory for cache (optional)
-   * @returns {Promise<boolean>} true if sync was performed
-   */
-  async syncPendingDeactivation(machineId, baseDir) {
-    try {
-      const pendingResult = hasPendingDeactivation(baseDir);
-
-      if (!pendingResult.pending) {
-        return false;
-      }
-
-      const pending = pendingResult.data;
-
-      if (!pending || !pending.licenseKey) {
-        // Invalid pending data, clear it
-        clearPendingDeactivation(baseDir);
-        return false;
-      }
-
-      // Attempt to deactivate on server
-      try {
-        await this._request('POST', '/v1/license/deactivate', {
-          key: pending.licenseKey,
-          machineId: pending.machineId || machineId,
-          offlineDeactivation: true,
-          offlineTimestamp: pending.deactivatedAt,
-        });
-
-        // Success - clear the pending flag
-        clearPendingDeactivation(baseDir);
-        return true;
-      } catch (error) {
-        // If the key is already deactivated or invalid, clear pending
-        if (error.code === 'INVALID_KEY' || error.code === 'NOT_ACTIVATED') {
-          clearPendingDeactivation(baseDir);
-          return true;
-        }
-
-        // For other errors (network, server), keep pending for next sync
-        // Don't throw - allow the main operation to continue
-        return false;
-      }
-    } catch {
-      // If we can't read pending state, continue anyway
-      return false;
-    }
-  }
-
-  // ────────────────────────────────────────────────────────────────
-  // Auth methods (Story PRO-11 - Email Authentication)
-  // ────────────────────────────────────────────────────────────────
-
-  /**
-   * Pre-flight check: verify buyer status and account existence for an email.
-   *
-   * @param {string} email - User email
-   * @returns {Promise<object>} Result with { isBuyer, hasAccount, email }
-   * @throws {AuthError} On check failure
-   */
-  async checkEmail(email) {
-    try {
-      const response = await this._request('POST', '/api/v1/auth/check-email', {
-        email,
-      });
-
-      return {
-        isBuyer: response.isBuyer === true,
-        hasAccount: response.hasAccount === true,
-        email: response.email || email,
-      };
-    } catch (error) {
-      if (error.code === 'RATE_LIMITED') {
-        throw AuthError.rateLimited(error.details?.retryAfter);
-      }
-      throw new AuthError(
-        error.message || 'Failed to check email',
-        error.code || 'CHECK_EMAIL_FAILED',
-        error.details,
-      );
-    }
-  }
-
-  /**
-   * Register a new user with email and password.
-   *
-   * @param {string} email - User email
-   * @param {string} password - User password (min 8 characters)
-   * @returns {Promise<object>} Signup result with { userId, message }
-   * @throws {AuthError} On signup failure
-   */
-  async signup(email, password) {
-    try {
-      const response = await this._request('POST', '/api/v1/auth/signup', {
-        email,
-        password,
-      });
-
-      return {
-        userId: response.userId,
-        message: response.message || 'Verification email sent. Please check your inbox.',
-      };
-    } catch (error) {
-      if (
-        error.code === 'EMAIL_ALREADY_REGISTERED' ||
-        (error.code === 'BAD_REQUEST' && error.message.includes('already'))
-      ) {
-        throw AuthError.emailAlreadyRegistered();
-      }
-      if (error.code === 'RATE_LIMITED') {
-        throw AuthError.rateLimited(error.details?.retryAfter);
-      }
-      throw new AuthError(
-        error.message || 'Signup failed',
-        error.code || 'SIGNUP_FAILED',
-        error.details,
-      );
-    }
-  }
-
-  /**
-   * Login with email and password.
-   *
-   * @param {string} email - User email
-   * @param {string} password - User password
-   * @returns {Promise<object>} Login result with { sessionToken, userId, emailVerified }
-   * @throws {AuthError} On login failure
-   */
-  async login(email, password) {
-    try {
-      const response = await this._request('POST', '/api/v1/auth/login', {
-        email,
-        password,
-      });
-
-      return {
-        sessionToken: response.accessToken,
-        userId: response.userId,
-        emailVerified: response.emailVerified !== false,
-      };
-    } catch (error) {
-      if (error.code === 'EMAIL_NOT_VERIFIED') {
-        throw AuthError.emailNotVerified();
-      }
-      if (
-        error.code === 'INVALID_KEY' ||
-        error.code === 'INVALID_CREDENTIALS' ||
-        error.code === 'BAD_REQUEST'
-      ) {
-        throw AuthError.invalidCredentials();
-      }
-      if (error.code === 'RATE_LIMITED') {
-        throw AuthError.rateLimited(error.details?.retryAfter);
-      }
-      throw new AuthError(
-        error.message || 'Login failed',
-        error.code || 'LOGIN_FAILED',
-        error.details,
-      );
-    }
-  }
-
-  /**
-   * Check if user's email has been verified.
-   *
-   * @param {string} sessionToken - Session token from login/signup
-   * @returns {Promise<object>} Status with { verified, email }
-   * @throws {AuthError} On verification check failure
-   */
-  async checkEmailVerified(sessionToken) {
-    try {
-      const response = await this._request('POST', '/api/v1/auth/verify-status', {
-        accessToken: sessionToken,
-      });
-
-      return {
-        verified: response.emailVerified === true,
-        email: response.email,
-      };
-    } catch (error) {
-      throw new AuthError(
-        error.message || 'Failed to check email verification status',
-        error.code || 'VERIFY_CHECK_FAILED',
-        error.details,
-      );
-    }
-  }
-
-  /**
-   * Activate Pro via authenticated session.
-   *
-   * Server-side flow: verify session → check email verified → validate buyer → generate/recover key → activate.
-   *
-   * @param {string} sessionToken - Session token from login
-   * @param {string} machineId - Machine fingerprint
-   * @param {string} aiosCoreVersion - AIOX Core version
-   * @returns {Promise<object>} Activation result (same shape as activate())
-   * @throws {AuthError} On auth failure
-   * @throws {BuyerValidationError} If user is not a buyer
-   * @throws {LicenseActivationError} On activation failure
-   */
-  async activateByAuth(sessionToken, machineId, aiosCoreVersion) {
-    try {
-      const response = await this._request('POST', '/api/v1/auth/activate-pro', {
-        accessToken: sessionToken,
-        machineId,
-        aiosCoreVersion,
-      });
-
-      if (!response.features || !Array.isArray(response.features)) {
-        throw new LicenseActivationError(
-          'Invalid activation response: missing features',
-          'INVALID_RESPONSE',
-        );
-      }
-
-      return {
-        key: response.licenseKey || response.key,
-        features: response.features,
-        seats: response.seats || { used: 1, max: 3 },
-        expiresAt: response.expiresAt,
-        cacheValidDays: response.cacheValidDays || 30,
-        gracePeriodDays: response.gracePeriodDays || 7,
-        activatedAt: new Date().toISOString(),
-      };
-    } catch (error) {
-      // Re-throw typed errors
-      if (error instanceof AuthError || error instanceof BuyerValidationError) {
-        throw error;
-      }
-
-      if (error.code === 'EMAIL_NOT_VERIFIED') {
-        throw AuthError.emailNotVerified();
-      }
-      if (error.code === 'NOT_A_BUYER') {
-        throw BuyerValidationError.notABuyer();
-      }
-      if (error.code === 'BUYER_SERVICE_UNAVAILABLE') {
-        throw BuyerValidationError.serviceUnavailable();
-      }
-      if (error.code === 'SEAT_LIMIT_EXCEEDED') {
-        throw LicenseActivationError.seatLimitExceeded(
-          error.details?.used || 0,
-          error.details?.max || 0,
-        );
-      }
-
-      throw new AuthError(
-        error.message || 'Pro activation failed',
-        error.code || 'ACTIVATE_PRO_FAILED',
-        error.details,
-      );
-    }
-  }
-
-  /**
-   * Request a password reset email via Supabase.
-   *
-   * @param {string} email - User email address
-   * @returns {Promise<object>} Result with { message }
-   * @throws {AuthError} On failure
-   */
-  async requestPasswordReset(email) {
-    try {
-      const response = await this._request('POST', '/api/v1/auth/request-reset', {
-        email,
-      });
-
-      return {
-        message: response.message || 'If this email is associated with an account, you will receive reset instructions.',
-      };
-    } catch (error) {
-      if (error.code === 'RATE_LIMITED') {
-        throw AuthError.rateLimited(error.details?.retryAfter);
-      }
-      throw new AuthError(
-        error.message || 'Failed to request password reset',
-        error.code || 'REQUEST_RESET_FAILED',
-        error.details,
-      );
-    }
-  }
-
-  /**
-   * Resend email verification.
-   *
-   * @param {string} email - User email address
-   * @returns {Promise<object>} Result with { message }
-   * @throws {AuthError} On failure
-   */
-  async resendVerification(email) {
-    try {
-      const response = await this._request('POST', '/api/v1/auth/resend-verification', {
-        email,
-      });
-
-      return {
-        message: response.message || 'Verification email resent.',
-      };
-    } catch (error) {
-      if (error.code === 'RATE_LIMITED') {
-        throw AuthError.rateLimited(error.details?.retryAfter);
-      }
-      throw new AuthError(
-        error.message || 'Failed to resend verification email',
-        error.code || 'RESEND_FAILED',
-        error.details,
-      );
-    }
-  }
-
-  /**
-   * Check if the API server is reachable.
-   *
-   * @returns {Promise<boolean>} true if server is reachable
-   */
-  async isOnline() {
-    try {
-      const url = new URL('/health', this.baseUrl);
-      const isHttps = url.protocol === 'https:';
-      const client = isHttps ? https : http;
-
-      return new Promise((resolve) => {
-        const req = client.request(
-          {
-            method: 'HEAD',
-            hostname: url.hostname,
-            port: url.port || (isHttps ? 443 : 80),
-            path: url.pathname,
-            timeout: 3000, // Quick check
-          },
-          (res) => {
-            resolve(res.statusCode < 500);
-          },
-        );
-
-        req.on('timeout', () => {
-          req.destroy();
-          resolve(false);
-        });
-
-        req.on('error', () => {
-          resolve(false);
-        });
-
-        req.end();
-      });
-    } catch {
-      return false;
-    }
-  }
-}
-
-// Singleton instance
-const licenseApi = new LicenseApiClient();
-
-module.exports = {
-  LicenseApiClient,
-  licenseApi,
-};
+/**
+ * License API Client
+ *
+ * HTTP client for communicating with the license validation server.
+ * Supports activation, validation, deactivation, and offline sync.
+ *
+ * @module pro/license/license-api
+ * @see ADR-PRO-003 - Feature Gating & Licensing
+ * @see Story PRO-6 - License Key & Feature Gating System
+ */
+
+'use strict';
+
+const https = require('https');
+const http = require('http');
+const { URL } = require('url');
+const { LicenseActivationError, AuthError, BuyerValidationError } = require('./errors');
+const { hasPendingDeactivation, clearPendingDeactivation } = require('./license-cache');
+
+/**
+ * Default configuration.
+ */
+const CONFIG = {
+  BASE_URL: process.env.AIOX_LICENSE_API_URL || 'https://aiox-license-server.vercel.app',
+  TIMEOUT_MS: 10000,
+  MAX_RETRIES: 3,
+  RETRY_DELAY_MS: 1000,
+  USER_AGENT: 'AIOX-Pro-License-Client/1.0',
+};
+
+/**
+ * LicenseApiClient - HTTP client for license operations.
+ */
+class LicenseApiClient {
+  /**
+   * Create a LicenseApiClient.
+   *
+   * @param {object} [options] - Client options
+   * @param {string} [options.baseUrl] - Base URL for API (default: api.synkra.ai)
+   * @param {number} [options.timeoutMs] - Request timeout in ms (default: 10000)
+   */
+  constructor(options = {}) {
+    this.baseUrl = options.baseUrl || CONFIG.BASE_URL;
+    this.timeoutMs = options.timeoutMs || CONFIG.TIMEOUT_MS;
+  }
+
+  /**
+   * Make an HTTP request with timeout and abort support.
+   *
+   * @private
+   * @param {string} method - HTTP method
+   * @param {string} path - API path
+   * @param {object} body - Request body
+   * @returns {Promise<object>} Response data
+   * @throws {LicenseActivationError} On network or server errors
+   */
+  async _request(method, path, body) {
+    const url = new URL(path, this.baseUrl);
+    const isHttps = url.protocol === 'https:';
+    const client = isHttps ? https : http;
+
+    const requestData = JSON.stringify(body);
+
+    const options = {
+      method,
+      hostname: url.hostname,
+      port: url.port || (isHttps ? 443 : 80),
+      path: url.pathname + url.search,
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(requestData),
+        'User-Agent': CONFIG.USER_AGENT,
+        Accept: 'application/json',
+      },
+      timeout: this.timeoutMs,
+    };
+
+    return new Promise((resolve, reject) => {
+      const req = client.request(options, (res) => {
+        // Follow 301/302/307/308 redirects (safety net for domain migrations)
+        if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location) {
+          const redirectUrl = new (require('url').URL)(res.headers.location);
+          const redirectOpts = { ...options, hostname: redirectUrl.hostname, path: redirectUrl.pathname + redirectUrl.search };
+          const rReq = client.request(redirectOpts, (rRes) => {
+            let rData = '';
+            rRes.on('data', (chunk) => { rData += chunk; });
+            rRes.on('end', () => {
+              try {
+                const response = rData ? JSON.parse(rData) : {};
+                this._handleResponse(rRes.statusCode, response, resolve, reject);
+              } catch {
+                reject(new LicenseActivationError('Invalid response from license server', 'INVALID_RESPONSE', { rawData: rData.substring(0, 200) }));
+              }
+            });
+          });
+          rReq.on('error', (error) => reject(LicenseActivationError.networkError(error)));
+          rReq.write(requestData);
+          rReq.end();
+          return;
+        }
+
+        let data = '';
+
+        res.on('data', (chunk) => {
+          data += chunk;
+        });
+
+        res.on('end', () => {
+          try {
+            const response = data ? JSON.parse(data) : {};
+            this._handleResponse(res.statusCode, response, resolve, reject);
+          } catch {
+            reject(
+              new LicenseActivationError(
+                'Invalid response from license server',
+                'INVALID_RESPONSE',
+                { rawData: data.substring(0, 200) },
+              ),
+            );
+          }
+        });
+      });
+
+      // Handle request timeout
+      req.on('timeout', () => {
+        req.destroy();
+        reject(LicenseActivationError.networkError(new Error('Request timeout')));
+      });
+
+      // Handle request error
+      req.on('error', (error) => {
+        reject(LicenseActivationError.networkError(error));
+      });
+
+      // Send request body
+      req.write(requestData);
+      req.end();
+    });
+  }
+
+  /**
+   * Handle HTTP response based on status code.
+   *
+   * @private
+   * @param {number} statusCode - HTTP status code
+   * @param {object} response - Parsed response body
+   * @param {Function} resolve - Promise resolve
+   * @param {Function} reject - Promise reject
+   */
+  _handleResponse(statusCode, response, resolve, reject) {
+    // Success
+    if (statusCode >= 200 && statusCode < 300) {
+      resolve(response);
+      return;
+    }
+
+    // Normalize server error envelope: { error: { code, message, details } } → flat
+    const err = response.error || response;
+    const code = err.code;
+    const message = err.message;
+    const details = err.details;
+
+    // Client errors
+    switch (statusCode) {
+      case 400:
+        reject(
+          new LicenseActivationError(
+            message || 'Invalid request',
+            code || 'BAD_REQUEST',
+            details,
+          ),
+        );
+        break;
+
+      case 401:
+        // Preserve server error code (e.g., INVALID_CREDENTIALS, EMAIL_NOT_VERIFIED)
+        reject(
+          new LicenseActivationError(
+            message || 'Unauthorized',
+            code || 'INVALID_KEY',
+            details,
+          ),
+        );
+        break;
+
+      case 409:
+        reject(
+          new LicenseActivationError(
+            message || 'Conflict',
+            code || 'CONFLICT',
+            details,
+          ),
+        );
+        break;
+
+      case 403:
+        if (code === 'EXPIRED_KEY') {
+          reject(LicenseActivationError.expiredKey());
+        } else if (code === 'SEAT_LIMIT_EXCEEDED') {
+          reject(
+            LicenseActivationError.seatLimitExceeded(
+              details?.used || 0,
+              details?.max || 0,
+            ),
+          );
+        } else {
+          reject(
+            new LicenseActivationError(
+              message || 'Access forbidden',
+              code || 'FORBIDDEN',
+              details,
+            ),
+          );
+        }
+        break;
+
+      case 429:
+        reject(LicenseActivationError.rateLimited(err.retryAfter || response.retryAfter));
+        break;
+
+      case 500:
+      case 502:
+      case 503:
+      case 504:
+        // Preserve server error code if provided (e.g., BUYER_SERVICE_UNAVAILABLE)
+        if (code) {
+          reject(
+            new LicenseActivationError(
+              message || 'Server error',
+              code,
+              details,
+            ),
+          );
+        } else {
+          reject(LicenseActivationError.serverError());
+        }
+        break;
+
+      default:
+        // Preserve server error code/message when available
+        reject(
+          new LicenseActivationError(
+            message || `Unexpected response: ${statusCode}`,
+            code || 'UNEXPECTED_STATUS',
+            details || { statusCode, response },
+          ),
+        );
+    }
+  }
+
+  /**
+   * Activate a license key.
+   *
+   * @param {string} key - License key (PRO-XXXX-XXXX-XXXX-XXXX)
+   * @param {string} machineId - Machine fingerprint
+   * @param {string} aiosCoreVersion - AIOX Core version
+   * @returns {Promise<object>} Activation result with features, seats, cache info
+   * @throws {LicenseActivationError} On activation failure
+   */
+  async activate(key, machineId, aiosCoreVersion) {
+    // First, sync any pending deactivations
+    await this.syncPendingDeactivation(machineId);
+
+    const response = await this._request('POST', '/v1/license/activate', {
+      key,
+      machineId,
+      aiosCoreVersion,
+    });
+
+    // Validate response structure
+    if (!response.features || !Array.isArray(response.features)) {
+      throw new LicenseActivationError(
+        'Invalid activation response: missing features',
+        'INVALID_RESPONSE',
+      );
+    }
+
+    return {
+      key: response.key || key,
+      features: response.features,
+      seats: response.seats || { used: 1, max: 1 },
+      expiresAt: response.expiresAt,
+      cacheValidDays: response.cacheValidDays || 30,
+      gracePeriodDays: response.gracePeriodDays || 7,
+      activatedAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Validate an existing license.
+   *
+   * @param {string} key - License key
+   * @param {string} machineId - Machine fingerprint
+   * @returns {Promise<object>} Validation result
+   * @throws {LicenseActivationError} On validation failure
+   */
+  async validate(key, machineId) {
+    // First, sync any pending deactivations
+    await this.syncPendingDeactivation(machineId);
+
+    const response = await this._request('POST', '/v1/license/validate', {
+      key,
+      machineId,
+    });
+
+    return {
+      valid: response.valid !== false,
+      features: response.features || [],
+      seats: response.seats || { used: 1, max: 1 },
+      expiresAt: response.expiresAt,
+      cacheValidDays: response.cacheValidDays || 30,
+      gracePeriodDays: response.gracePeriodDays || 7,
+    };
+  }
+
+  /**
+   * Deactivate a license from this machine.
+   *
+   * @param {string} key - License key
+   * @param {string} machineId - Machine fingerprint
+   * @returns {Promise<object>} Deactivation result
+   * @throws {LicenseActivationError} On deactivation failure
+   */
+  async deactivate(key, machineId) {
+    const response = await this._request('POST', '/v1/license/deactivate', {
+      key,
+      machineId,
+    });
+
+    return {
+      success: response.success !== false,
+      seatFreed: response.seatFreed !== false,
+      message: response.message || 'License deactivated successfully',
+    };
+  }
+
+  /**
+   * Sync any pending offline deactivations with the server.
+   *
+   * This is called automatically before activate/validate operations.
+   *
+   * @param {string} machineId - Current machine ID for verification
+   * @param {string} [baseDir] - Base directory for cache (optional)
+   * @returns {Promise<boolean>} true if sync was performed
+   */
+  async syncPendingDeactivation(machineId, baseDir) {
+    try {
+      const pendingResult = hasPendingDeactivation(baseDir);
+
+      if (!pendingResult.pending) {
+        return false;
+      }
+
+      const pending = pendingResult.data;
+
+      if (!pending || !pending.licenseKey) {
+        // Invalid pending data, clear it
+        clearPendingDeactivation(baseDir);
+        return false;
+      }
+
+      // Attempt to deactivate on server
+      try {
+        await this._request('POST', '/v1/license/deactivate', {
+          key: pending.licenseKey,
+          machineId: pending.machineId || machineId,
+          offlineDeactivation: true,
+          offlineTimestamp: pending.deactivatedAt,
+        });
+
+        // Success - clear the pending flag
+        clearPendingDeactivation(baseDir);
+        return true;
+      } catch (error) {
+        // If the key is already deactivated or invalid, clear pending
+        if (error.code === 'INVALID_KEY' || error.code === 'NOT_ACTIVATED') {
+          clearPendingDeactivation(baseDir);
+          return true;
+        }
+
+        // For other errors (network, server), keep pending for next sync
+        // Don't throw - allow the main operation to continue
+        return false;
+      }
+    } catch {
+      // If we can't read pending state, continue anyway
+      return false;
+    }
+  }
+
+  // ────────────────────────────────────────────────────────────────
+  // Auth methods (Story PRO-11 - Email Authentication)
+  // ────────────────────────────────────────────────────────────────
+
+  /**
+   * Pre-flight check: verify buyer status and account existence for an email.
+   *
+   * @param {string} email - User email
+   * @returns {Promise<object>} Result with { isBuyer, hasAccount, email }
+   * @throws {AuthError} On check failure
+   */
+  async checkEmail(email) {
+    try {
+      const response = await this._request('POST', '/api/v1/auth/check-email', {
+        email,
+      });
+
+      return {
+        isBuyer: response.isBuyer === true,
+        hasAccount: response.hasAccount === true,
+        email: response.email || email,
+      };
+    } catch (error) {
+      if (error.code === 'RATE_LIMITED') {
+        throw AuthError.rateLimited(error.details?.retryAfter);
+      }
+      throw new AuthError(
+        error.message || 'Failed to check email',
+        error.code || 'CHECK_EMAIL_FAILED',
+        error.details,
+      );
+    }
+  }
+
+  /**
+   * Register a new user with email and password.
+   *
+   * @param {string} email - User email
+   * @param {string} password - User password (min 8 characters)
+   * @returns {Promise<object>} Signup result with { userId, message }
+   * @throws {AuthError} On signup failure
+   */
+  async signup(email, password) {
+    try {
+      const response = await this._request('POST', '/api/v1/auth/signup', {
+        email,
+        password,
+      });
+
+      return {
+        userId: response.userId,
+        message: response.message || 'Verification email sent. Please check your inbox.',
+      };
+    } catch (error) {
+      if (
+        error.code === 'EMAIL_ALREADY_REGISTERED' ||
+        (error.code === 'BAD_REQUEST' && error.message.includes('already'))
+      ) {
+        throw AuthError.emailAlreadyRegistered();
+      }
+      if (error.code === 'RATE_LIMITED') {
+        throw AuthError.rateLimited(error.details?.retryAfter);
+      }
+      throw new AuthError(
+        error.message || 'Signup failed',
+        error.code || 'SIGNUP_FAILED',
+        error.details,
+      );
+    }
+  }
+
+  /**
+   * Login with email and password.
+   *
+   * @param {string} email - User email
+   * @param {string} password - User password
+   * @returns {Promise<object>} Login result with { sessionToken, userId, emailVerified }
+   * @throws {AuthError} On login failure
+   */
+  async login(email, password) {
+    try {
+      const response = await this._request('POST', '/api/v1/auth/login', {
+        email,
+        password,
+      });
+
+      return {
+        sessionToken: response.accessToken,
+        userId: response.userId,
+        emailVerified: response.emailVerified !== false,
+      };
+    } catch (error) {
+      if (error.code === 'EMAIL_NOT_VERIFIED') {
+        throw AuthError.emailNotVerified();
+      }
+      if (
+        error.code === 'INVALID_KEY' ||
+        error.code === 'INVALID_CREDENTIALS' ||
+        error.code === 'BAD_REQUEST'
+      ) {
+        throw AuthError.invalidCredentials();
+      }
+      if (error.code === 'RATE_LIMITED') {
+        throw AuthError.rateLimited(error.details?.retryAfter);
+      }
+      throw new AuthError(
+        error.message || 'Login failed',
+        error.code || 'LOGIN_FAILED',
+        error.details,
+      );
+    }
+  }
+
+  /**
+   * Check if user's email has been verified.
+   *
+   * @param {string} sessionToken - Session token from login/signup
+   * @returns {Promise<object>} Status with { verified, email }
+   * @throws {AuthError} On verification check failure
+   */
+  async checkEmailVerified(sessionToken) {
+    try {
+      const response = await this._request('POST', '/api/v1/auth/verify-status', {
+        accessToken: sessionToken,
+      });
+
+      return {
+        verified: response.emailVerified === true,
+        email: response.email,
+      };
+    } catch (error) {
+      throw new AuthError(
+        error.message || 'Failed to check email verification status',
+        error.code || 'VERIFY_CHECK_FAILED',
+        error.details,
+      );
+    }
+  }
+
+  /**
+   * Activate Pro via authenticated session.
+   *
+   * Server-side flow: verify session → check email verified → validate buyer → generate/recover key → activate.
+   *
+   * @param {string} sessionToken - Session token from login
+   * @param {string} machineId - Machine fingerprint
+   * @param {string} aiosCoreVersion - AIOX Core version
+   * @returns {Promise<object>} Activation result (same shape as activate())
+   * @throws {AuthError} On auth failure
+   * @throws {BuyerValidationError} If user is not a buyer
+   * @throws {LicenseActivationError} On activation failure
+   */
+  async activateByAuth(sessionToken, machineId, aiosCoreVersion) {
+    try {
+      const response = await this._request('POST', '/api/v1/auth/activate-pro', {
+        accessToken: sessionToken,
+        machineId,
+        aiosCoreVersion,
+      });
+
+      if (!response.features || !Array.isArray(response.features)) {
+        throw new LicenseActivationError(
+          'Invalid activation response: missing features',
+          'INVALID_RESPONSE',
+        );
+      }
+
+      return {
+        key: response.licenseKey || response.key,
+        features: response.features,
+        seats: response.seats || { used: 1, max: 3 },
+        expiresAt: response.expiresAt,
+        cacheValidDays: response.cacheValidDays || 30,
+        gracePeriodDays: response.gracePeriodDays || 7,
+        activatedAt: new Date().toISOString(),
+      };
+    } catch (error) {
+      // Re-throw typed errors
+      if (error instanceof AuthError || error instanceof BuyerValidationError) {
+        throw error;
+      }
+
+      if (error.code === 'EMAIL_NOT_VERIFIED') {
+        throw AuthError.emailNotVerified();
+      }
+      if (error.code === 'NOT_A_BUYER') {
+        throw BuyerValidationError.notABuyer();
+      }
+      if (error.code === 'BUYER_SERVICE_UNAVAILABLE') {
+        throw BuyerValidationError.serviceUnavailable();
+      }
+      if (error.code === 'SEAT_LIMIT_EXCEEDED') {
+        throw LicenseActivationError.seatLimitExceeded(
+          error.details?.used || 0,
+          error.details?.max || 0,
+        );
+      }
+
+      throw new AuthError(
+        error.message || 'Pro activation failed',
+        error.code || 'ACTIVATE_PRO_FAILED',
+        error.details,
+      );
+    }
+  }
+
+  /**
+   * Request a password reset email via Supabase.
+   *
+   * @param {string} email - User email address
+   * @returns {Promise<object>} Result with { message }
+   * @throws {AuthError} On failure
+   */
+  async requestPasswordReset(email) {
+    try {
+      const response = await this._request('POST', '/api/v1/auth/request-reset', {
+        email,
+      });
+
+      return {
+        message: response.message || 'If this email is associated with an account, you will receive reset instructions.',
+      };
+    } catch (error) {
+      if (error.code === 'RATE_LIMITED') {
+        throw AuthError.rateLimited(error.details?.retryAfter);
+      }
+      throw new AuthError(
+        error.message || 'Failed to request password reset',
+        error.code || 'REQUEST_RESET_FAILED',
+        error.details,
+      );
+    }
+  }
+
+  /**
+   * Resend email verification.
+   *
+   * @param {string} email - User email address
+   * @returns {Promise<object>} Result with { message }
+   * @throws {AuthError} On failure
+   */
+  async resendVerification(email) {
+    try {
+      const response = await this._request('POST', '/api/v1/auth/resend-verification', {
+        email,
+      });
+
+      return {
+        message: response.message || 'Verification email resent.',
+      };
+    } catch (error) {
+      if (error.code === 'RATE_LIMITED') {
+        throw AuthError.rateLimited(error.details?.retryAfter);
+      }
+      throw new AuthError(
+        error.message || 'Failed to resend verification email',
+        error.code || 'RESEND_FAILED',
+        error.details,
+      );
+    }
+  }
+
+  /**
+   * Check if the API server is reachable.
+   *
+   * @returns {Promise<boolean>} true if server is reachable
+   */
+  async isOnline() {
+    try {
+      const url = new URL('/health', this.baseUrl);
+      const isHttps = url.protocol === 'https:';
+      const client = isHttps ? https : http;
+
+      return new Promise((resolve) => {
+        const req = client.request(
+          {
+            method: 'HEAD',
+            hostname: url.hostname,
+            port: url.port || (isHttps ? 443 : 80),
+            path: url.pathname,
+            timeout: 3000, // Quick check
+          },
+          (res) => {
+            resolve(res.statusCode < 500);
+          },
+        );
+
+        req.on('timeout', () => {
+          req.destroy();
+          resolve(false);
+        });
+
+        req.on('error', () => {
+          resolve(false);
+        });
+
+        req.end();
+      });
+    } catch {
+      return false;
+    }
+  }
+}
+
+// Singleton instance
+const licenseApi = new LicenseApiClient();
+
+module.exports = {
+  LicenseApiClient,
+  licenseApi,
+};