nexus-fca 3.0.2 → 3.0.3

package/docs/advanced-configuration.md

@@ -0,0 +1,101 @@
+# Advanced Configuration Options for Nexus-FCA
+
+This document outlines additional configuration options available to optimize your Nexus-FCA experience.
+
+## Environment Variables
+
+Nexus-FCA supports various environment variables to fine-tune its behavior:
+
+### Session Management
+
+```
+# Device persistence
+NEXUS_PERSISTENT_DEVICE=true    # Enable consistent device fingerprinting (default)
+NEXUS_DEVICE_FILE=./device.json # Custom path to device profile file
+
+# Single-session guard (built-in)
+# Uses SingleSessionGuard with NEXUS_SESSION_LOCK_PATH and NEXUS_FORCE_LOCK
+NEXUS_SESSION_LOCK_PATH=./lock  # Path to session lock file used by SingleSessionGuard
+NEXUS_FORCE_LOCK=false          # Force acquire lock even if lock exists
+
+# Region control
+NEXUS_REGION=NA                 # Set fixed region (NA, EU, AS)
+```
+
+### Cookie Management
+
+```
+# Cookie refresher settings
+NEXUS_COOKIE_REFRESH_INTERVAL=1800000  # Refresh interval in ms (default: 30 minutes)
+NEXUS_COOKIE_EXPIRY_DAYS=90           # Days to extend cookie expiry
+NEXUS_COOKIE_BACKUP_PATH=./backups    # Path to store cookie backups
+NEXUS_COOKIE_MAX_BACKUPS=5            # Maximum number of cookie backups to keep
+```
+
+### Connection Settings
+
+```
+# Connection resilience
+NEXUS_MAX_RETRIES=5              # Maximum connection retry attempts
+NEXUS_RETRY_DELAY=5000           # Base delay between retries (ms)
+NEXUS_KEEPALIVE_INTERVAL=300000  # Keepalive interval (ms)
+```
+
+### Safety Features
+
+```
+# Safety controls
+NEXUS_FCA_SAFE_MODE=1            # Enable basic safety measures
+NEXUS_FCA_ULTRA_SAFE_MODE=1      # Enable maximum safety for stability
+NEXUS_DELIVERY_TIMEOUT=60000     # Message delivery timeout (ms)
+NEXUS_AUTO_MARK_READ=false       # Automatically mark messages as read
+```
+
+## API Configuration Options
+
+When initializing the API, you can pass additional options:
+
+```javascript
+const api = await login({
+  appState: require('./appstate.json'),
+  
+  // Session stability options
+  persistentDevice: true,           // Use consistent device fingerprinting
+  deviceFilePath: './device.json',  // Custom device profile path
+  // Single-session guard is enabled by default internally
+  // Configure via env: NEXUS_SESSION_LOCK_PATH, NEXUS_FORCE_LOCK
+  
+  // Connection options
+  region: 'NA',                     // Set fixed region
+  userAgent: 'custom-user-agent',   // Override user agent
+  
+  // Cookie management
+  cookieRefreshInterval: 1800000,   // Cookie refresh interval (ms)
+  cookieExpiryDays: 90,             // Days to extend cookie expiry
+  cookieBackupEnabled: true,        // Enable cookie backups
+  cookieMaxBackups: 5,              // Maximum cookie backups
+  
+  // Safety options
+  forceLogout: true,                // Force logout any other sessions
+  safetyLevel: 2                    // Safety level (0-2)
+});
+```
+
+## Best Practices
+
+For the most stable experience:
+
+1. **Always enable persistent device**: Use the same device fingerprint across restarts
+2. **Enable session locking**: Prevent multiple instances from using the same account
+3. **Set a fixed region**: Use the `NEXUS_REGION` environment variable
+4. **Use a modern user agent**: Let the system select an appropriate one
+5. **Keep cookie refreshing enabled**: Maintains fresh cookies
+6. **Back up working appstate files**: Keep copies of working sessions
+
+## Security Considerations
+
+- Store sensitive information like appstate files securely
+- Use environment variables for credentials instead of hardcoding
+- Use `.env` files in development (gitignored)
+- Consider using a dedicated account for automation
+- Respect Facebook's terms of service and rate limits

package/docs/cookie-management.md

@@ -0,0 +1,87 @@
+# Cookie Expiry and Session Management Guide
+
+This document explains how Nexus-FCA handles cookie management to prevent rapid session expiry and improve overall stability.
+
+## Understanding the Issue
+
+Facebook cookies may expire rapidly (within hours) due to several reasons:
+
+1. **Missing Expiry Dates**: Some cookies don't have proper expiry timestamps
+2. **Short-lived Sessions**: Facebook may issue cookies with short expiry times
+3. **Device Inconsistency**: Using different device profiles between sessions
+4. **Multiple Sessions**: Running multiple bots with the same account
+5. **Security Triggers**: Suspicious activities triggering Facebook safety mechanisms
+
+## Nexus-FCA Solution
+
+Nexus-FCA implements a robust multi-layered approach to maintain session stability:
+
+### 1. Cookie Expiry Extension
+
+The system automatically extends cookie expiry dates:
+
+- Critical cookies (`c_user`, `xs`, `fr`, `datr`, `sb`) are extended to 90 days
+- All cookies are validated at startup and fixed if needed
+- Proper expiry format is enforced using the standard RFC format
+
+### 2. Persistent Device Profile
+
+To maintain consistency across restarts:
+
+- Device fingerprints (device ID, user agent, family device ID) are preserved
+- The same device profile is used for all requests
+- Configuration option: `persistentDevice: true` (enabled by default)
+
+### 3. Cookie Refresher
+
+An active background service keeps your session fresh:
+
+- Periodically refreshes cookies (every 30 minutes)
+- Makes lightweight requests to maintain session activity
+- Extends cookie expiry dates automatically
+- Creates backups of working sessions
+
+### 4. Single Session Guard
+
+Prevents multiple instances from using the same account:
+
+- File-based locking mechanism prevents duplicate sessions
+- Ensures Facebook sees consistent device information
+- Configuration via `NEXUS_SESSION_LOCK_PATH` and `NEXUS_FORCE_LOCK`
+
+## Best Practices
+
+For maximum session stability:
+
+1. **Use Persistent Device**: Always enable persistentDevice (default)
+2. **Keep Proxy Consistent**: Use the same proxy for extended periods
+3. **Set Region**: Use `NEXUS_REGION` to maintain a consistent region
+4. **Avoid Multiple Instances**: Never run multiple bots with the same account
+5. **Regular Backups**: Keep backups of working appstate files
+
+## Configuration
+
+Key environment variables for session stability:
+
+```
+# Session stability
+NEXUS_PERSISTENT_DEVICE=true    # Keep device fingerprint consistent (default)
+NEXUS_DEVICE_FILE=./device.json # Custom device profile path
+NEXUS_SESSION_LOCK_PATH=./lock  # Single session lock file location
+NEXUS_REGION=NA                 # Fixed region (NA, EU, AS, etc.)
+
+# Safety settings
+NEXUS_FCA_ULTRA_SAFE_MODE=1     # Maximum safety for stability
+```
+
+## Troubleshooting
+
+If you still experience session expiry:
+
+1. **Check Logs**: Look for warnings about cookie expiry or checkpoint
+2. **Monitor Activity**: High message volume can trigger Facebook limits
+3. **Fresh Login**: Generate a completely new appstate if needed
+4. **API Limits**: Respect Facebook rate limits with delay between actions
+5. **Secure Network**: Use residential IPs rather than datacenter IPs
+
+The new cookie management system should significantly improve stability and prevent the rapid expiry issues previously encountered.

package/index.js

@@ -7,6 +7,8 @@ const { promises: fsPromises, readFileSync } = require('fs');
 const fs = require('fs');
 const axios = require('axios');
 const path = require('path');
+const crypto = require("crypto");
+const { v4: uuidv4 } = require("uuid");
 const models = require("./lib/database/models");
 const logger = require("./lib/logger");
 const { safeMode, ultraSafeMode, smartSafetyLimiter, isUserAllowed } = require('./utils'); // Enhanced safety system
@@ -52,6 +54,8 @@ const { User } = require('./lib/message/User');
 // Advanced Safety Module - Minimizes ban/lock/checkpoint rates
 const FacebookSafety = require('./lib/safety/FacebookSafety');
 const { SingleSessionGuard } = require('./lib/safety/SingleSessionGuard');
+const { CookieRefresher } = require('./lib/safety/CookieRefresher');
+const { CookieManager } = require('./lib/safety/CookieManager');
 
 // Core compatibility imports
 const MqttManager = require('./lib/mqtt/MqttManager');
@@ -459,7 +463,14 @@ function loginHelper(appState, email, password, globalOptions, callback, prCallb
     }
 
     try {
-      appState.forEach(c => {
+      // Fix any cookie expiry issues before setting
+      const fixedAppState = CookieManager.fixCookieExpiry(appState, {
+        defaultExpiryDays: 90,
+        criticalExpiryDays: 90,
+        refreshExisting: true
+      });
+      
+      fixedAppState.forEach(c => {
         const str = `${c.key}=${c.value}; expires=${c.expires}; domain=${c.domain}; path=${c.path};`;
         jar.setCookie(str, "http://" + c.domain);
       });
@@ -520,7 +531,48 @@ function loginHelper(appState, email, password, globalOptions, callback, prCallb
       logger('✅ Session authenticated successfully', 'info');
       // Initialize safety monitoring
       globalSafety.startMonitoring(ctx, api);
-  try { globalSafety.startDynamicSystems(); } catch(_) {}
+      try { globalSafety.startDynamicSystems(); } catch(_) {}
+      
+      // Initialize Cookie Refresher to prevent cookie expiry (env-configurable)
+      try {
+        const envBool = (v) => (v === '1' || (v && v.toLowerCase && v.toLowerCase() === 'true'));
+        const toInt = (v, def) => {
+          const n = parseInt(v, 10);
+          return Number.isFinite(n) && n > 0 ? n : def;
+        };
+
+        const refreshEnabled = process.env.NEXUS_COOKIE_REFRESH_ENABLED ? envBool(process.env.NEXUS_COOKIE_REFRESH_ENABLED) : true;
+        const refreshInterval = toInt(process.env.NEXUS_COOKIE_REFRESH_INTERVAL, 30 * 60 * 1000);
+        const expiryDays = toInt(process.env.NEXUS_COOKIE_EXPIRY_DAYS, 90);
+        const maxBackups = toInt(process.env.NEXUS_COOKIE_MAX_BACKUPS, 5);
+        const backupsEnabled = process.env.NEXUS_COOKIE_BACKUP_ENABLED ? envBool(process.env.NEXUS_COOKIE_BACKUP_ENABLED) : true;
+
+        const cookieRefresher = new CookieRefresher({
+          enabled: refreshEnabled,
+          cookieRefreshIntervalMs: refreshInterval,
+          forceExpiryExtension: true,
+          expiryDays: expiryDays,
+          backupEnabled: backupsEnabled,
+          maxBackups: maxBackups
+        });
+        
+        // Get appstate path from options or ctx
+  const appstatePath = globalOptions.appstatePath || process.env.NEXUS_APPSTATE_PATH || (ctx.dataDir ? path.join(ctx.dataDir, 'appstate.json') : null);
+  const backupPath = process.env.NEXUS_COOKIE_BACKUP_PATH || globalOptions.backupPath || (ctx.dataDir ? path.join(ctx.dataDir, 'backups') : null);
+        
+        if (appstatePath) {
+          ctx.cookieRefresher = cookieRefresher.initialize(ctx, utils, defaultFuncs, appstatePath, backupPath);
+          logger('✅ Cookie Refresher initialized - cookies will be kept fresh', 'info');
+          
+          // Immediate first refresh to ensure long expiry
+          cookieRefresher.refreshNow().catch(err => {
+            logger(`❌ Initial cookie refresh failed: ${err.message}`, 'warn');
+          });
+        }
+      } catch (err) {
+        logger(`❌ Cookie Refresher initialization failed: ${err.message}`, 'error');
+      }
+      
       // Consolidated: delegate light poke to unified safety module (prevents duplicate refresh scheduling)
       if (globalSafety && typeof globalSafety.scheduleLightPoke === 'function') {
         globalSafety.scheduleLightPoke();
@@ -556,9 +608,7 @@ function loginHelper(appState, email, password, globalOptions, callback, prCallb
 
 // --- INTEGRATED NEXUS LOGIN SYSTEM ---
 // Full Nexus Login System integrated for npm package compatibility
-const { v4: uuidv4 } = require('uuid');
 const { TOTP } = require("totp-generator");
-const crypto = require('crypto');
 
 class IntegratedNexusLoginSystem {
     constructor(options = {}) {
@@ -723,7 +773,56 @@ class IntegratedNexusLoginSystem {
         try {
             const appstate = JSON.parse(fs.readFileSync(this.options.appstatePath, 'utf8'));
             this.logger(`Loaded appstate with ${appstate.length} cookies`, '✅');
-            return appstate;
+            
+            // Enhanced: Check and fix cookie expiry
+            const fixedAppstate = CookieManager.fixCookieExpiry(appstate, {
+                defaultExpiryDays: 90,
+                criticalExpiryDays: 90,
+                refreshExisting: true
+            });
+            
+            // Save the fixed appstate back to file
+            if (fixedAppstate !== appstate) {
+                fs.writeFileSync(this.options.appstatePath, JSON.stringify(fixedAppstate, null, 2));
+                this.logger('Fixed cookie expiry dates and saved appstate', '🔧');
+            }
+            
+            // Validate critical cookies
+            const validation = CookieManager.validateCriticalCookies(fixedAppstate);
+            if (!validation.valid) {
+                this.logger(`Warning: Missing critical cookies: ${validation.missing.join(', ')}`, '⚠️');
+            }
+
+      // Warn if any critical cookies are expiring soon (< 7 days)
+      try {
+        const critical = new Set(['c_user', 'xs', 'fr', 'datr', 'sb', 'spin']);
+        let hasExpiringSoon = false;
+        for (const cookie of fixedAppstate) {
+          if (!cookie || !cookie.key || !critical.has(cookie.key)) continue;
+          if (!cookie.expires) continue;
+          try {
+            const expiry = new Date(cookie.expires);
+            if (isNaN(expiry.getTime())) {
+              this.logger(`Warning: ${cookie.key} cookie has invalid expiry format: ${cookie.expires}`, '⚠️');
+              hasExpiringSoon = true;
+              continue;
+            }
+            const daysRemaining = Math.floor((expiry - new Date()) / (1000 * 60 * 60 * 24));
+            if (daysRemaining < 7) {
+              this.logger(`Warning: ${cookie.key} cookie expires in ${daysRemaining} days`, '⚠️');
+              hasExpiringSoon = true;
+            }
+          } catch (_) {
+            this.logger(`Warning: ${cookie.key} cookie has invalid expiry format: ${cookie.expires}`, '⚠️');
+            hasExpiringSoon = true;
+          }
+        }
+        if (hasExpiringSoon) {
+          this.logger(`Some critical cookies expire soon - Cookie Refresher will extend them`, 'ℹ️');
+        }
+      } catch (_) {}
+            
+      return fixedAppstate;
         } catch (error) {
             this.logger(`Failed to load appstate: ${error.message}`, '❌');
             return null;
@@ -732,14 +831,21 @@ class IntegratedNexusLoginSystem {
 
     saveAppstate(appstate, metadata = {}) {
         try {
-            fs.writeFileSync(this.options.appstatePath, JSON.stringify(appstate, null, 2));
+            // First fix any cookie expiry issues
+            const fixedAppstate = CookieManager.fixCookieExpiry(appstate, {
+                defaultExpiryDays: 90,
+                criticalExpiryDays: 90,
+                refreshExisting: false
+            });
+            
+            fs.writeFileSync(this.options.appstatePath, JSON.stringify(fixedAppstate, null, 2));
             
             // Create backup
             const backupName = `appstate_${new Date().toISOString().replace(/[:.]/g, '-')}.json`;
             const backupPath = path.join(this.options.backupPath, backupName);
             
             const backupData = {
-                appstate,
+                appstate: fixedAppstate,
                 metadata: {
                     ...metadata,
                     created: new Date().toISOString(),
@@ -851,7 +957,7 @@ class IntegratedNexusLoginSystem {
                                 value: cookie.value,
                                 domain: cookie.domain,
                                 path: cookie.path,
-                                expires: cookie.expires,
+                                expires: cookie.expires ? new Date(cookie.expires * 1000).toUTCString() : CookieManager.getDefaultExpiry(cookie.name),
                                 httpOnly: cookie.httpOnly,
                                 secure: cookie.secure
                             }));
@@ -861,7 +967,9 @@ class IntegratedNexusLoginSystem {
                                     key: 'i_user',
                                     value: credentials.i_user,
                                     domain: '.facebook.com',
-                                    path: '/'
+                                    path: '/',
+                                    expires: CookieManager.getDefaultExpiry('i_user'),
+                                    secure: true
                                 });
                             }
 
@@ -951,7 +1059,7 @@ class IntegratedNexusLoginSystem {
                                 value: cookie.value,
                                 domain: cookie.domain,
                                 path: cookie.path,
-                                expires: cookie.expires,
+                                expires: cookie.expires ? new Date(cookie.expires * 1000).toUTCString() : CookieManager.getDefaultExpiry(cookie.name),
                                 httpOnly: cookie.httpOnly,
                                 secure: cookie.secure
                             }));
@@ -961,7 +1069,9 @@ class IntegratedNexusLoginSystem {
                                     key: 'i_user',
                                     value: credentials.i_user,
                                     domain: '.facebook.com',
-                                    path: '/'
+                                    path: '/',
+                                    expires: CookieManager.getDefaultExpiry('i_user'),
+                                    secure: true
                                 });
                             }
 

package/lib/safety/CookieManager.js

@@ -0,0 +1,168 @@
+"use strict";
+
+/**
+ * Nexus Cookie Manager
+ * Ensures Facebook session cookies stay valid and fixes expiry issues
+ */
+
+const fs = require('fs');
+const path = require('path');
+const logger = require('../logger');
+
+class CookieManager {
+  /**
+   * Fix expiry dates on Facebook cookies to prevent rapid expiration
+   * @param {Array} cookies - Array of Facebook cookies from appstate
+   * @param {Object} options - Options for fixing cookies
+   * @returns {Array} - Fixed cookies with proper expiry dates
+   */
+  static fixCookieExpiry(cookies, options = {}) {
+    if (!Array.isArray(cookies) || cookies.length === 0) {
+      return cookies;
+    }
+    
+    const {
+      defaultExpiryDays = 90,
+      criticalExpiryDays = 90,
+      refreshExisting = true
+    } = options;
+    
+    const now = new Date();
+    const criticalCookies = ['c_user', 'xs', 'fr', 'datr', 'sb', 'spin'];
+    let fixedCount = 0;
+    
+    for (const cookie of cookies) {
+      // Skip cookies with no key
+      if (!cookie.key) continue;
+      
+      const isCritical = criticalCookies.includes(cookie.key);
+      const days = isCritical ? criticalExpiryDays : defaultExpiryDays;
+      
+      // Check if cookie needs expiry fix
+      const needsFix = !cookie.expires || 
+                      refreshExisting || 
+                      !this._isValidDate(cookie.expires) ||
+                      this._getRemainingDays(cookie.expires) < 7;
+      
+      if (needsFix) {
+        // Set expiry to future date
+        const futureDate = new Date(now.getTime() + (days * 24 * 60 * 60 * 1000));
+        cookie.expires = futureDate.toUTCString();
+        fixedCount++;
+      }
+    }
+    
+    if (fixedCount > 0) {
+      logger(`Fixed expiry dates for ${fixedCount} cookies`, 'info');
+    }
+    
+    return cookies;
+  }
+  
+  /**
+   * Check if cookie expiry is a valid date
+   * @param {string} dateStr - Date string to check
+   * @returns {boolean} - True if valid date
+   */
+  static _isValidDate(dateStr) {
+    if (!dateStr) return false;
+    const date = new Date(dateStr);
+    return !isNaN(date.getTime());
+  }
+  
+  /**
+   * Get days remaining until expiry
+   * @param {string} dateStr - Date string to check
+   * @returns {number} - Days remaining
+   */
+  static _getRemainingDays(dateStr) {
+    if (!dateStr) return 0;
+    try {
+      const expiryDate = new Date(dateStr);
+      const now = new Date();
+      return Math.floor((expiryDate - now) / (1000 * 60 * 60 * 24));
+    } catch (e) {
+      return 0;
+    }
+  }
+  
+  /**
+   * Check if appstate has critical cookies
+   * @param {Array} cookies - Cookies to check
+   * @returns {Object} - Result with status and missing cookies
+   */
+  static validateCriticalCookies(cookies) {
+    if (!Array.isArray(cookies) || cookies.length === 0) {
+      return { valid: false, missing: ['all'] };
+    }
+    
+    const criticalCookies = ['c_user', 'xs', 'datr', 'sb'];
+    const missing = [];
+    
+    for (const critical of criticalCookies) {
+      if (!cookies.some(c => c.key === critical)) {
+        missing.push(critical);
+      }
+    }
+    
+    return {
+      valid: missing.length === 0,
+      missing
+    };
+  }
+  
+  /**
+   * Generate default cookie expiry date
+   * @param {string} cookieName - Name of cookie
+   * @returns {string} - Expiry date string
+   */
+  static getDefaultExpiry(cookieName) {
+    const now = new Date();
+    const criticalCookies = ['c_user', 'xs', 'fr', 'datr', 'sb'];
+    
+    // Critical cookies get 90 days, others get 30 days
+    const days = criticalCookies.includes(cookieName) ? 90 : 30;
+    const future = new Date(now.getTime() + (days * 24 * 60 * 60 * 1000));
+    return future.toUTCString();
+  }
+  
+  /**
+   * Load and fix appstate file
+   * @param {string} appstatePath - Path to appstate.json
+   * @returns {Array|null} - Fixed cookies or null if failed
+   */
+  static loadAndFixAppstate(appstatePath) {
+    try {
+      if (!fs.existsSync(appstatePath)) {
+        logger(`Appstate file not found: ${appstatePath}`, 'error');
+        return null;
+      }
+      
+      const cookies = JSON.parse(fs.readFileSync(appstatePath, 'utf8'));
+      if (!Array.isArray(cookies)) {
+        logger('Invalid appstate format: not an array', 'error');
+        return null;
+      }
+      
+      // Fix expiry dates
+      const fixed = this.fixCookieExpiry(cookies);
+      
+      // Validate critical cookies
+      const validation = this.validateCriticalCookies(fixed);
+      if (!validation.valid) {
+        logger(`Missing critical cookies: ${validation.missing.join(', ')}`, 'warn');
+      }
+      
+      // Save back fixed cookies
+      fs.writeFileSync(appstatePath, JSON.stringify(fixed, null, 2));
+      logger(`Fixed and saved appstate with ${fixed.length} cookies`, 'info');
+      
+      return fixed;
+    } catch (err) {
+      logger(`Failed to load and fix appstate: ${err.message}`, 'error');
+      return null;
+    }
+  }
+}
+
+module.exports = { CookieManager };

package/lib/safety/CookieRefresher.js

@@ -0,0 +1,277 @@
+"use strict";
+
+/**
+ * Nexus Cookie Refresher
+ * Maintains cookie freshness and prevents expiry by strategically refreshing sessions
+ */
+
+const fs = require('fs');
+const path = require('path');
+const logger = require('../logger');
+
+class CookieRefresher {
+  constructor(options = {}) {
+    this.options = {
+      enabled: options.enabled !== false,
+      cookieRefreshIntervalMs: options.cookieRefreshIntervalMs || 60 * 60 * 1000, // 1 hour default
+      forceExpiryExtension: options.forceExpiryExtension !== false, 
+      expiryDays: options.expiryDays || 60, // 60 days default expiry extension
+      backupEnabled: options.backupEnabled !== false,
+      maxBackups: options.maxBackups || 5,
+      ...options
+    };
+    
+    this.refreshTimer = null;
+    this.ctx = null;
+    this.jar = null;
+    this.utils = null;
+    this.defaultFuncs = null;
+    this.appstatePath = null;
+    this.backupPath = null;
+    this.sessionStartTime = Date.now();
+    this.lastRefreshTime = null;
+    this.refreshCount = 0;
+  }
+  
+  /**
+   * Initialize the refresher with API context
+   */
+  initialize(ctx, utils, defaultFuncs, appstatePath, backupPath) {
+    this.ctx = ctx;
+    this.jar = ctx.jar;
+    this.utils = utils;
+    this.defaultFuncs = defaultFuncs;
+    this.appstatePath = appstatePath;
+    this.backupPath = backupPath || path.dirname(appstatePath);
+    
+    // Add timestamps to context for monitoring
+    ctx._cookieRefresher = {
+      sessionStartTime: this.sessionStartTime,
+      lastRefreshTime: null,
+      refreshCount: 0,
+      nextScheduledRefresh: null
+    };
+    
+    if (this.options.enabled) {
+      this.start();
+    }
+    
+    return this;
+  }
+  
+  /**
+   * Start the cookie refresh cycle
+   */
+  start() {
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+    }
+    
+    // Schedule next refresh
+    const nextRefresh = this.options.cookieRefreshIntervalMs;
+    logger('CookieRefresher', `Scheduling next cookie refresh in ${Math.floor(nextRefresh/60000)} minutes`, 'debug');
+    
+    this.refreshTimer = setTimeout(() => {
+      this.performRefresh()
+        .then(() => this.start()) // Schedule next refresh after success
+        .catch(err => {
+          logger('CookieRefresher', `Refresh failed: ${err.message}. Retrying in 15 minutes...`, 'warn');
+          // If refresh fails, try again sooner
+          setTimeout(() => this.start(), 15 * 60 * 1000); 
+        });
+    }, nextRefresh);
+    
+    // Don't prevent Node from exiting
+    this.refreshTimer.unref();
+    
+    // Update next scheduled time
+    if (this.ctx && this.ctx._cookieRefresher) {
+      this.ctx._cookieRefresher.nextScheduledRefresh = Date.now() + nextRefresh;
+    }
+  }
+  
+  /**
+   * Perform the actual cookie refresh operation
+   */
+  async performRefresh() {
+    if (!this.ctx || !this.jar || !this.utils || !this.defaultFuncs) {
+      throw new Error('CookieRefresher not properly initialized');
+    }
+    
+    try {
+      // 1. First do a simple fetch to keep session alive
+      logger('CookieRefresher', 'Refreshing cookies to extend session...', 'info');
+      const urls = [
+        'https://www.facebook.com/me',
+        'https://www.facebook.com/ajax/haste-response/?__a=1',
+        'https://www.facebook.com/ajax/bootloader-endpoint/?__a=1'
+      ];
+      
+      let success = false;
+      for (const url of urls) {
+        try {
+          // Try multiple URLs in case some are blocked
+          const res = await this.defaultFuncs.get(url, this.jar, {});
+          
+          // Save any cookies that were set
+          if (res && res.headers && res.headers["set-cookie"]) {
+            this.utils.saveCookies(this.jar)(res);
+            success = true;
+            break;
+          }
+        } catch (err) {
+          logger('CookieRefresher', `Failed to refresh with ${url}: ${err.message}`, 'debug');
+          // Continue to next URL
+        }
+      }
+      
+      if (!success) {
+        throw new Error('All refresh URLs failed');
+      }
+      
+      // 2. Get current cookies
+      const appstate = this.utils.getAppState(this.jar);
+      
+      // 3. Force extend cookie expiry dates if enabled
+      if (this.options.forceExpiryExtension) {
+        this._extendCookieExpiry(appstate);
+      }
+      
+      // 4. Save refreshed cookies
+      if (this.appstatePath) {
+        this._saveAppstate(appstate);
+      }
+      
+      // 5. Update counters
+      this.lastRefreshTime = Date.now();
+      this.refreshCount++;
+      if (this.ctx && this.ctx._cookieRefresher) {
+        this.ctx._cookieRefresher.lastRefreshTime = this.lastRefreshTime;
+        this.ctx._cookieRefresher.refreshCount = this.refreshCount;
+      }
+      
+      logger('CookieRefresher', `Successfully refreshed cookies (refresh #${this.refreshCount})`, 'info');
+      return true;
+    } catch (err) {
+      logger('CookieRefresher', `Cookie refresh failed: ${err.message}`, 'error');
+      throw err;
+    }
+  }
+  
+  /**
+   * Force extend cookie expiry dates
+   */
+  _extendCookieExpiry(appstate) {
+    if (!Array.isArray(appstate)) return;
+    
+    const now = new Date();
+    const expiryDate = new Date(now.getTime() + this.options.expiryDays * 24 * 60 * 60 * 1000);
+    const expiryStr = expiryDate.toUTCString();
+    
+    // Important cookies that should never expire
+    const criticalCookies = ['c_user', 'xs', 'fr', 'datr', 'sb', 'spin'];
+    
+    let extended = 0;
+    for (const cookie of appstate) {
+      // Skip cookies that shouldn't have their expiry extended
+      if (cookie.key && cookie.key.startsWith('_')) continue;
+      
+      // Set cookie expiry to far future, prioritize critical cookies
+      if (criticalCookies.includes(cookie.key) || !cookie.expires || new Date(cookie.expires) < expiryDate) {
+        cookie.expires = expiryStr;
+        extended++;
+      }
+    }
+    
+    logger('CookieRefresher', `Extended expiration for ${extended} cookies to ${expiryStr}`, 'debug');
+  }
+  
+  /**
+   * Save appstate with backup
+   */
+  _saveAppstate(appstate) {
+    try {
+      // 1. Save main appstate file
+      fs.writeFileSync(this.appstatePath, JSON.stringify(appstate, null, 2));
+      
+      // 2. Create backup if enabled
+      if (this.options.backupEnabled) {
+        const backupName = `appstate_refreshed_${new Date().toISOString().replace(/[:.]/g, '-')}.json`;
+        const backupPath = path.join(this.backupPath, backupName);
+        
+        const backupData = {
+          appstate,
+          metadata: {
+            refreshed: new Date().toISOString(),
+            refreshCount: this.refreshCount,
+            sessionStartTime: new Date(this.sessionStartTime).toISOString(),
+            source: 'NexusCookieRefresher'
+          }
+        };
+        
+        fs.writeFileSync(backupPath, JSON.stringify(backupData, null, 2));
+        
+        // 3. Cleanup old backups if needed
+        this._cleanupOldBackups();
+      }
+      
+      return true;
+    } catch (err) {
+      logger('CookieRefresher', `Failed to save refreshed appstate: ${err.message}`, 'error');
+      return false;
+    }
+  }
+  
+  /**
+   * Clean up old backup files
+   */
+  _cleanupOldBackups() {
+    try {
+      const maxBackups = this.options.maxBackups;
+      const backupDir = this.backupPath;
+      
+      // Find all appstate backup files
+      const files = fs.readdirSync(backupDir)
+        .filter(file => file.startsWith('appstate_refreshed_') && file.endsWith('.json'))
+        .map(file => path.join(backupDir, file));
+      
+      // Sort by modified time (newest first)
+      files.sort((a, b) => {
+        return fs.statSync(b).mtime.getTime() - fs.statSync(a).mtime.getTime();
+      });
+      
+      // Delete old backups beyond the limit
+      if (files.length > maxBackups) {
+        const toDelete = files.slice(maxBackups);
+        for (const file of toDelete) {
+          fs.unlinkSync(file);
+        }
+        logger('CookieRefresher', `Cleaned up ${toDelete.length} old cookie backup files`, 'debug');
+      }
+    } catch (err) {
+      logger('CookieRefresher', `Backup cleanup error: ${err.message}`, 'debug');
+    }
+  }
+  
+  /**
+   * Stop the refresher
+   */
+  stop() {
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
+  
+  /**
+   * Perform an immediate refresh
+   */
+  async refreshNow() {
+    this.stop();
+    await this.performRefresh();
+    this.start();
+    return true;
+  }
+}
+
+module.exports = { CookieRefresher };

package/lib/safety/DeviceManager.js

@@ -0,0 +1,161 @@
+"use strict";
+
+/**
+ * Nexus Device Manager
+ * Ensures consistent device fingerprinting to prevent Facebook security triggers
+ */
+
+const fs = require('fs');
+const path = require('path');
+const logger = require('../logger');
+const { v4: uuidv4 } = require('uuid');
+
+class DeviceManager {
+  constructor(options = {}) {
+    this.options = {
+      enabled: options.enabled !== false,
+      deviceFilePath: options.deviceFilePath || './device.json',
+      ...options
+    };
+    
+    this.deviceInfo = null;
+    this.initialized = false;
+  }
+  
+  /**
+   * Initialize device manager and load/create device profile
+   */
+  initialize() {
+    if (this.initialized) return this;
+    
+    try {
+      // Check if environment variable overrides path
+      const envPath = process.env.NEXUS_DEVICE_FILE;
+      if (envPath) {
+        this.options.deviceFilePath = envPath;
+      }
+      
+      // Ensure directory exists
+      const dirPath = path.dirname(this.options.deviceFilePath);
+      if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+      }
+      
+      // Try to load existing device info
+      if (fs.existsSync(this.options.deviceFilePath)) {
+        this.deviceInfo = JSON.parse(fs.readFileSync(this.options.deviceFilePath, 'utf8'));
+        logger(`Loaded existing device profile: ${this.deviceInfo.deviceId}`, 'info');
+      } else {
+        // Create new device info
+        this.deviceInfo = this._generateDeviceInfo();
+        this._saveDeviceInfo();
+        logger(`Created new device profile: ${this.deviceInfo.deviceId}`, 'info');
+      }
+      
+      this.initialized = true;
+      return this;
+    } catch (err) {
+      logger(`Failed to initialize DeviceManager: ${err.message}`, 'error');
+      // Fallback to default device info
+      this.deviceInfo = this._generateDeviceInfo();
+      return this;
+    }
+  }
+  
+  /**
+   * Generate new device information
+   */
+  _generateDeviceInfo() {
+    const deviceId = `device_${uuidv4().replace(/-/g, '')}`;
+    const familyDeviceId = `family_device_${uuidv4().replace(/-/g, '')}`;
+    
+    // Modern Facebook user agent strings
+    const userAgents = [
+      'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.99 Safari/537.36',
+      'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36',
+      'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.99 Safari/537.36',
+      'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36'
+    ];
+    
+    return {
+      deviceId,
+      familyDeviceId,
+      userAgent: userAgents[Math.floor(Math.random() * userAgents.length)],
+      created: new Date().toISOString(),
+      lastUsed: new Date().toISOString()
+    };
+  }
+  
+  /**
+   * Save device information to file
+   */
+  _saveDeviceInfo() {
+    if (!this.options.enabled || !this.deviceInfo) return false;
+    
+    try {
+      // Update last used timestamp
+      this.deviceInfo.lastUsed = new Date().toISOString();
+      
+      // Save to file
+      fs.writeFileSync(this.options.deviceFilePath, JSON.stringify(this.deviceInfo, null, 2));
+      return true;
+    } catch (err) {
+      logger(`Failed to save device info: ${err.message}`, 'error');
+      return false;
+    }
+  }
+  
+  /**
+   * Get device ID for consistent identification
+   */
+  getDeviceId() {
+    if (!this.initialized) this.initialize();
+    return this.deviceInfo?.deviceId || `device_${uuidv4().replace(/-/g, '')}`;
+  }
+  
+  /**
+   * Get family device ID for consistent identification
+   */
+  getFamilyDeviceId() {
+    if (!this.initialized) this.initialize();
+    return this.deviceInfo?.familyDeviceId || `family_device_${uuidv4().replace(/-/g, '')}`;
+  }
+  
+  /**
+   * Get user agent for consistent browser fingerprint
+   */
+  getUserAgent() {
+    if (!this.initialized) this.initialize();
+    return this.deviceInfo?.userAgent || 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.99 Safari/537.36';
+  }
+  
+  /**
+   * Apply device information to request options
+   */
+  applyToRequestOptions(options = {}) {
+    if (!this.initialized) this.initialize();
+    
+    return {
+      ...options,
+      headers: {
+        ...options.headers,
+        'User-Agent': this.getUserAgent(),
+        'X-FB-Device-Id': this.getDeviceId(),
+        'X-FB-Family-Device-ID': this.getFamilyDeviceId()
+      }
+    };
+  }
+  
+  /**
+   * Update last used timestamp
+   */
+  updateUsage() {
+    if (!this.initialized) this.initialize();
+    if (this.deviceInfo) {
+      this.deviceInfo.lastUsed = new Date().toISOString();
+      this._saveDeviceInfo();
+    }
+  }
+}
+
+module.exports = { DeviceManager };

package/lib/safety/SessionLock.js

@@ -0,0 +1,3 @@
+"use strict";
+// Deprecated optional lock. Use built-in SingleSessionGuard instead.
+module.exports = { };

package/lib/safety/sessionStability.js

@@ -0,0 +1,3 @@
+"use strict";
+// Deprecated helper. Stability is handled in core + SingleSessionGuard.
+module.exports = {}; 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexus-fca",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "Nexus-FCA 3.0 – stable, low-risk Facebook Messenger automation API with integrated secure login (ID / Password / 2FA), adaptive MQTT core, safety orchestration, metrics, and TypeScript support.",
   "main": "index.js",
   "repository": {