nexus-fca 3.0.1 → 3.0.2

package/README.md

@@ -147,6 +147,7 @@ const login = require('nexus-fca');
 |----------|----------|
 | Full API Reference | `DOCS.md` |
 | Feature Guides | `docs/*.md` |
+| Configuration Reference | `docs/configuration-reference.md` |
 | Safety Details | `docs/account-safety.md` |
 | Examples | `examples/` |
 

package/docs/README.md

@@ -22,6 +22,9 @@ This folder contains comprehensive documentation for all features of Nexus-FCA,
 ### 🔧 Core API Documentation
 Each `.md` file documents a single core API feature with usage examples, parameters, and safety notes.
 
+Additional references:
+- [Configuration Reference](./configuration-reference.md) — all env vars, programmatic options, and config file keys
+
 ### 🔗 Migration Guides
 - **[Migration-fca-unofficial.md](./Migration-fca-unofficial.md)** - Migrate from fca-unofficial
 - **[Migration-ws3-fca.md](./Migration-ws3-fca.md)** - Migrate from ws3-fca  

package/docs/configuration-reference.md

@@ -0,0 +1,195 @@
+# Configuration Reference (Nexus-FCA 3.0)
+
+This document lists every supported configuration surface across the project: programmatic options, config file keys, and environment variables. Use this as a single source of truth when deploying locally or to PaaS.
+
+---
+## 1) Programmatic options (api.setOptions / login options)
+
+These map to `globalOptions` and are available via `api.setOptions({ ... })` or by passing as the second argument to `login(credentials, options)`.
+
+- Booleans
+  - `online` (default: true) – Advertise chat availability when connected
+  - `selfListen` – Receive your own sent messages
+  - `listenEvents` – Emit non-message events (nicknames, pins, joins, etc.)
+  - `listenTyping` – Emit typing events
+  - `updatePresence` – Enable presence updates processing
+  - `forceLogin` – Force legacy login behavior where applicable
+  - `autoMarkDelivery` – Auto mark delivery for inbound messages
+  - `autoMarkRead` – Auto mark read for inbound messages
+  - `autoReconnect` (default: true) – Reconnect MQTT after disconnect
+  - `emitReady` – Emit a synthetic `ready` event after connect
+
+- Strings
+  - `logLevel`: 'silent' | 'error' | 'warn' | 'info' | 'verbose'
+  - `pageID`: string – Page scope for actions
+  - `userAgent`: string – Overrides UA for outbound requests
+  - `proxy`: string – HTTP(S) proxy URL
+  - `acceptLanguage`: string – Accept-Language header for MQTT/Web requests
+
+- Numbers
+  - `logRecordSize` – npmlog ring buffer size
+
+- Advanced (set via helper methods)
+  - `api.setBackoffOptions({ base, factor, max, jitter })` – Adaptive MQTT reconnect backoff tuning
+  - `api.setEditOptions({ maxPendingEdits, editTTLms, ackTimeoutMs, maxResendAttempts })` – Message edit safety controls
+  - `api.enableLazyPreflight(enable=true)` – When true, preflight is lighter/skipped if recent successful connect
+  - Group queue controls for large group threads:
+    - `api.enableGroupQueue(enable=true)`
+    - `api.setGroupQueueCapacity(n)`
+    - Internals: `groupQueueIdleMs` (default 30m) – idle purge window
+
+Notes:
+- Unknown keys passed to `setOptions` are warned and ignored.
+- `api.listen` is an alias of `api.listenMqtt`.
+
+---
+## 2) Config file: fca-config.json
+
+Auto-created in project root on first run and merged with defaults. Good for project-wide non-secret settings.
+
+Example keys (merge-safe):
+
+```json
+{
+  "autoUpdate": true,
+  "mqtt": { "enabled": true, "reconnectInterval": 3600 },
+  "logLevel": "warn",
+  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
+  "proxy": "http://user:pass@host:port"
+}
+```
+
+For secrets and per-deploy toggles, prefer environment variables.
+
+---
+## 3) Environment variables
+
+Environment variables are the primary way to configure behavior in production. They override defaults and complement programmatic options.
+
+### 3.1 Storage & persistence
+- `NEXUS_DATA_DIR` – Base directory for persistent files (fallback: `RENDER_DATA_DIR` or CWD)
+- `NEXUS_APPSTATE_PATH` – Path to appstate.json
+- `NEXUS_CREDENTIALS_PATH` – Path to credentials.json (integrated login)
+- `NEXUS_BACKUP_PATH` – Directory for appstate backups
+- `NEXUS_DEVICE_FILE` – Path to persistent-device.json
+- `NEXUS_PERSISTENT_DEVICE` = true|false – Keep stable device fingerprint
+
+### 3.2 Networking & headers
+- `NEXUS_PROXY` – HTTP(S) proxy URL (also respects `HTTPS_PROXY` / `HTTP_PROXY`)
+- `NEXUS_ACCEPT_LANGUAGE` – Example: `en-US,en;q=0.9`
+- `NEXUS_UA` – Override User-Agent
+- `NEXUS_REGION` – Force MQTT region (e.g., `HIL`)
+
+### 3.3 Stability & preflight
+- `NEXUS_DISABLE_PREFLIGHT` = true|false – Skip heavy preflight validation
+- `NEXUS_ONLINE` = true|false – Override chat availability flag
+- `NEXUS_VERBOSE_MQTT` = true|false – Extra MQTT diagnostics logging
+
+### 3.4 Single-session guard (prevents concurrent runs)
+- `NEXUS_SESSION_LOCK_PATH` – Path for session lock file (default: `<DATA_DIR>/session.lock`)
+- `NEXUS_SESSION_TTL_MS` – Lock stale timeout (default: 900000 = 15m)
+- `NEXUS_FORCE_LOCK` = true|false – Force takeover if lock present
+
+### 3.5 Safety layer & allow/block lists
+- `NEXUS_FCA_ULTRA_SAFE_MODE` = '1' – Maximum protection presets
+- `NEXUS_FCA_SAFE_MODE` = '1' – Safe mode presets
+- `NEXUS_FCA_ALLOW_LIST` – Comma-separated userIDs allowed
+- `NEXUS_FCA_BLOCK_LIST` – Comma-separated userIDs blocked
+
+### 3.6 Example-only envs (for quick scripts)
+Used in example snippets and README demos; not used by the core library itself:
+- `FB_EMAIL` – Facebook username/email
+- `FB_PASS` / `FB_PASSWORD` – Facebook password
+- `FB_2FA_SECRET` – TOTP secret for 2FA (if used)
+- `EMAIL` / `PASSWORD` – Alternative names used in example scripts
+- `DEBUG` – e.g. `nexus-fca:*` to enable debug output in certain examples
+
+---
+## 4) Integrated Nexus Login System options
+
+Used internally for credential-based login; also exported for direct use via `IntegratedNexusLoginSystem`. Options can be provided in code or via the env overrides above.
+
+- Paths & persistence
+  - `appstatePath` (env: `NEXUS_APPSTATE_PATH`)
+  - `credentialsPath` (env: `NEXUS_CREDENTIALS_PATH`)
+  - `backupPath` (env: `NEXUS_BACKUP_PATH`)
+  - `persistentDevice` (env: `NEXUS_PERSISTENT_DEVICE`)
+  - `persistentDeviceFile` (env: `NEXUS_DEVICE_FILE`)
+
+- Behavior
+  - `autoLogin` (default: true)
+  - `autoSave` (default: true)
+  - `safeMode` (default: true)
+  - `maxRetries` (default: 3)
+  - `retryDelay` (default: 5000 ms)
+
+---
+## 5) MQTT & connection behavior
+
+Controlled via programmatic options and envs:
+
+- `autoReconnect` (default true) – Reconnect on close/error
+- Backoff: `api.setBackoffOptions({ base, factor, max, jitter })`
+- Keepalives & diagnostics: `NEXUS_VERBOSE_MQTT` for extra logs
+- Headers: `acceptLanguage`, `userAgent`, `proxy`
+- Region override: `NEXUS_REGION`
+
+---
+## 6) Delivery & read behavior
+
+- `autoMarkDelivery` – Calls `markAsDelivered` for inbound messages
+- `autoMarkRead` – Optional follow-up read marking
+- Adaptive suppression & retries are built-in; metrics accessible via `api.getHealthMetrics()`
+
+---
+## 7) Health and memory metrics
+
+- `api.getHealthMetrics()` – ACKs, reconnect counts, delivery stats, last connect timestamps, etc.
+- `api.getMemoryMetrics()` – Pending edits, outbound queue depth, group queue prunes, memory guard actions
+
+---
+## 8) Logging
+
+- `logLevel`: 'silent' | 'error' | 'warn' | 'info' | 'verbose'
+- `logRecordSize`: ring buffer size
+- Temporarily increase MQTT verbosity with `NEXUS_VERBOSE_MQTT=true` when debugging
+
+---
+## 9) Quick matrix (where to set)
+
+| Setting                        | setOptions | login options | fca-config.json | ENV |
+|--------------------------------|------------|---------------|-----------------|-----|
+| online                         | ✅         | ✅            |                 | ✅ (`NEXUS_ONLINE`) |
+| selfListen / listenEvents      | ✅         | ✅            |                 |     |
+| updatePresence                 | ✅         | ✅            |                 |     |
+| autoMarkDelivery / autoMarkRead| ✅         | ✅            |                 |     |
+| autoReconnect                  | ✅         | ✅            |                 |     |
+| userAgent                      | ✅         | ✅            | ✅               | ✅ (`NEXUS_UA`) |
+| proxy                          | ✅         | ✅            | ✅               | ✅ (`NEXUS_PROXY`/`HTTPS_PROXY`/`HTTP_PROXY`) |
+| acceptLanguage                 | ✅         | ✅            |                 | ✅ (`NEXUS_ACCEPT_LANGUAGE`) |
+| disablePreflight               | via `enableLazyPreflight(false)` | ✅ |       | ✅ (`NEXUS_DISABLE_PREFLIGHT`) |
+| pageID                         | ✅         | ✅            |                 |     |
+| backoff/edit settings          | helper fns |               |                 |     |
+| data/appstate/backup/device    |            | via Integrated Login |         | ✅ (`NEXUS_*` paths) |
+| session guard (lock/ttl/force) |            |               |                 | ✅ |
+| safety modes / lists           |            |               |                 | ✅ |
+
+---
+## 10) Recommended PaaS baseline
+
+Set at minimum:
+
+```
+NEXUS_DATA_DIR=/var/data/nexus-fca
+NEXUS_APPSTATE_PATH=/var/data/nexus-fca/appstate.json
+NEXUS_DEVICE_FILE=/var/data/nexus-fca/persistent-device.json
+NEXUS_PERSISTENT_DEVICE=true
+NEXUS_ACCEPT_LANGUAGE=en-US,en;q=0.9
+# Optional hardening
+NEXUS_DISABLE_PREFLIGHT=true
+# Optional proxy/region
+# NEXUS_PROXY=http://user:pass@host:port
+# NEXUS_REGION=HIL
+```
+
+See also: `docs/deployment-config.md` for end-to-end deployment steps.

package/docs/deployment-config.md

@@ -0,0 +1,178 @@
+# Deployment & Configuration Guide (Nexus-FCA 3.0)
+
+This guide shows how to use Nexus-FCA as an npm package, configure it via file and environment variables, deploy safely on platforms like Render, and avoid the “you couldn't create multiple sessions” warning.
+
+---
+## 1) Using as an npm package
+
+Install:
+
+```bash
+npm install nexus-fca
+```
+
+Basic appstate usage:
+
+```js
+const login = require('nexus-fca');
+
+(async () => {
+  const api = await login({ appState: require('./appstate.json') });
+  api.listen((err, evt) => {
+    if (err) return console.error(err);
+    if (evt.body) api.sendMessage('Echo: ' + evt.body, evt.threadID);
+  });
+})();
+```
+
+---
+## 2) Configuration options
+
+You can control behavior via:
+- Programmatic options: `api.setOptions({ ... })`
+- Config file: `fca-config.json` (auto-created on first run)
+- Environment variables (recommended for hosting)
+
+### 2.1 Programmatic options (common)
+```js
+api.setOptions({
+  autoReconnect: true,
+  updatePresence: false,
+  selfListen: false,
+  logLevel: 'warn',           // npmlog level: silly|verbose|info|warn|error
+  userAgent: '...Chrome/...',
+  proxy: 'http://user:pass@host:port',
+});
+```
+
+### 2.2 Config file: `fca-config.json`
+A default file is stored at project root and merged with internal defaults. You can keep project-wide settings here:
+
+```json
+{
+  "autoUpdate": true,
+  "mqtt": { "enabled": true, "reconnectInterval": 3600 },
+  "logLevel": "warn",
+  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
+  "proxy": "http://user:pass@host:port"
+}
+```
+
+Note: For secrets and deployment toggles, prefer environment variables below.
+
+### 2.3 Environment variables (hosting-friendly)
+These are read at runtime and override defaults:
+
+- Storage & persistence
+  - `NEXUS_DATA_DIR` → base directory for persistent files
+  - `NEXUS_APPSTATE_PATH` → path to `appstate.json`
+  - `NEXUS_DEVICE_FILE` → path to `persistent-device.json`
+  - `NEXUS_BACKUP_PATH` → directory for appstate backups
+  - `NEXUS_PERSISTENT_DEVICE` → `true|false` (keep same device fingerprint)
+
+- Networking & headers
+  - `NEXUS_PROXY` (or `HTTPS_PROXY` / `HTTP_PROXY`) → Proxy URL
+  - `NEXUS_ACCEPT_LANGUAGE` → e.g. `en-US,en;q=0.9`
+  - `NEXUS_UA` → override User-Agent
+  - `NEXUS_REGION` → force MQTT region (e.g., `HIL`)
+
+- Stability & preflight
+  - `NEXUS_DISABLE_PREFLIGHT` → `true|false` (skip heavy session preflight)
+  - `NEXUS_ONLINE` → `true|false`
+  - `NEXUS_VERBOSE_MQTT` → `true|false` (extra MQTT logs only when needed)
+
+Example (Render):
+```
+NEXUS_DATA_DIR=/var/data/nexus-fca
+NEXUS_APPSTATE_PATH=/var/data/nexus-fca/appstate.json
+NEXUS_DEVICE_FILE=/var/data/nexus-fca/persistent-device.json
+NEXUS_BACKUP_PATH=/var/data/nexus-fca/backups
+NEXUS_PERSISTENT_DEVICE=true
+
+NEXUS_ACCEPT_LANGUAGE=en-US,en;q=0.9
+NEXUS_UA=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36
+NEXUS_DISABLE_PREFLIGHT=true
+NEXUS_ONLINE=false
+# Optional region & proxy
+# NEXUS_REGION=HIL
+# NEXUS_PROXY=http://user:pass@host:port
+```
+
+---
+## 3) Deploying on Render (or other PaaS)
+
+1) Persistent disk
+- Mount a disk and point `NEXUS_DATA_DIR` to it.
+- Ensure `appstate.json` and `persistent-device.json` live on this disk.
+
+2) Single instance per account
+- Run only one service instance for a given account.
+- Disable autoscaling/replicas for this worker.
+
+3) Environment hardening
+- Set `NEXUS_PERSISTENT_DEVICE=true` to anchor device fingerprint.
+- Set `NEXUS_DISABLE_PREFLIGHT=true` to reduce heavy checks.
+- Optionally use a reputable residential/mobile proxy via `NEXUS_PROXY`.
+
+4) Keep your appstate fresh
+- Generate appstate locally on a trusted network, then deploy it.
+- Avoid frequent credential logins from the server itself.
+
+---
+## 4) "You couldn't create multiple sessions" – what it means and fixes
+
+This warning typically appears when Facebook detects concurrent or rapidly rotating logins for the same account, often from:
+- Multiple bots/instances using the same account at the same time
+- Different IPs or device fingerprints in quick succession
+- Frequent logouts/re-logins (or unstable appstate)
+
+How to avoid:
+- Run exactly one bot instance per account.
+- Reuse the same `appstate.json` and `persistent-device.json` (set `NEXUS_PERSISTENT_DEVICE=true`).
+- Avoid logging in with username/password from multiple places—generate appstate once and reuse it.
+- Use a stable IP. If your PaaS IPs rotate or look like a datacenter bot, use a reputable residential/mobile proxy.
+- Keep preflight light on PaaS (`NEXUS_DISABLE_PREFLIGHT=true`).
+
+Recovery steps when you see the warning:
+- Stop all other running instances for the same account.
+- Log in manually in a browser, pass any checkpoint, verify recent logins.
+- Regenerate a fresh appstate (locally), deploy, and keep it persistent.
+
+---
+## 5) Minimal config-first example
+
+`fca-config.json` (project root):
+```json
+{
+  "logLevel": "warn",
+  "mqtt": { "enabled": true, "reconnectInterval": 3600 },
+  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/121.0.0.0 Safari/537.36"
+}
+```
+
+Bot code:
+```js
+const login = require('nexus-fca');
+(async () => {
+  const api = await login({ appState: require(process.env.NEXUS_APPSTATE_PATH || './appstate.json') });
+  // Optional fine-tuning
+  api.setOptions({
+    autoReconnect: true,
+    updatePresence: false,
+    proxy: process.env.NEXUS_PROXY,
+  });
+  api.listen((err, evt) => {
+    if (err) return console.error(err);
+    if (evt.body) api.sendMessage('Echo: ' + evt.body, evt.threadID);
+  });
+})();
+```
+
+---
+## 6) Troubleshooting quick tips
+- Rapid cookie expiry: ensure persistence paths are on mounted disk; set `NEXUS_PERSISTENT_DEVICE=true`.
+- Frequent reconnect warnings: let adaptive backoff work; keep `autoReconnect=true`.
+- No replies sent: check proxy/network egress; use delivery metrics via `api.getHealthMetrics()`.
+- Noisy logs: avoid `NEXUS_VERBOSE_MQTT` unless debugging; prefer `logLevel=warn`.
+
+For full API details, see `DOCS.md` and other files in `docs/`.

package/index.js

@@ -51,6 +51,7 @@ 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');
 
 // Core compatibility imports
 const MqttManager = require('./lib/mqtt/MqttManager');
@@ -195,6 +196,10 @@ function buildAPI(globalOptions, html, jar) {
   } catch (e) {
     log.warning("login", "Not MQTT endpoint");
   }
+  // Allow environment override for region (useful on PaaS where HTML may omit region or mismatch)
+  if (process.env.NEXUS_REGION) {
+    try { region = process.env.NEXUS_REGION.toUpperCase(); } catch(_) {}
+  }
   const tokenMatch = html.match(/DTSGInitialData.*?token":"(.*?)"/);
   if (tokenMatch) {
     fb_dtsg = tokenMatch[1];
@@ -557,20 +562,24 @@ const crypto = require('crypto');
 
 class IntegratedNexusLoginSystem {
     constructor(options = {}) {
-        this.options = {
-            appstatePath: options.appstatePath || path.join(process.cwd(), 'appstate.json'),
-            credentialsPath: options.credentialsPath || path.join(process.cwd(), 'credentials.json'),
-            backupPath: options.backupPath || path.join(process.cwd(), 'backups'),
-            autoLogin: options.autoLogin !== false,
-            autoSave: options.autoSave !== false,
-            safeMode: options.safeMode !== false,
-            maxRetries: options.maxRetries || 3,
-            retryDelay: options.retryDelay || 5000,
-            // New: persistentDevice disables random device rotation
-            persistentDevice: options.persistentDevice !== false,
-            persistentDeviceFile: options.persistentDeviceFile || path.join(process.cwd(), 'persistent-device.json'),
-            ...options
-        };
+    const dataDir = process.env.NEXUS_DATA_DIR || process.env.RENDER_DATA_DIR || process.cwd();
+    const envPersistent = (v) => (v === '0' || v === 'false') ? false : (v === '1' || v === 'true') ? true : undefined;
+    const envPD = envPersistent(process.env.NEXUS_PERSISTENT_DEVICE);
+
+    this.options = {
+      appstatePath: options.appstatePath || process.env.NEXUS_APPSTATE_PATH || path.join(dataDir, 'appstate.json'),
+      credentialsPath: options.credentialsPath || process.env.NEXUS_CREDENTIALS_PATH || path.join(dataDir, 'credentials.json'),
+      backupPath: options.backupPath || process.env.NEXUS_BACKUP_PATH || path.join(dataDir, 'backups'),
+      autoLogin: options.autoLogin !== false,
+      autoSave: options.autoSave !== false,
+      safeMode: options.safeMode !== false,
+      maxRetries: options.maxRetries || 3,
+      retryDelay: options.retryDelay || 5000,
+      // New: persistentDevice disables random device rotation
+      persistentDevice: typeof envPD === 'boolean' ? envPD : (options.persistentDevice !== false),
+      persistentDeviceFile: options.persistentDeviceFile || process.env.NEXUS_DEVICE_FILE || path.join(dataDir, 'persistent-device.json'),
+      ...options
+    };
 
         this.deviceCache = new Map();
         this.loginAttempts = 0;
@@ -578,10 +587,30 @@ class IntegratedNexusLoginSystem {
         // New: load previously persisted device if any
         this.fixedDeviceProfile = this.loadPersistentDevice();
         
-        this.ensureDirectories();
+    this.ensureDirectories();
         this.logger('Login system ready', '🚀');
     }
 
+  ensureDirectories() {
+    try {
+      // backups dir
+      if (this.options.backupPath && !fs.existsSync(this.options.backupPath)) {
+        fs.mkdirSync(this.options.backupPath, { recursive: true });
+      }
+      // parent dir for appstate
+      const appstateDir = path.dirname(this.options.appstatePath);
+      if (!fs.existsSync(appstateDir)) fs.mkdirSync(appstateDir, { recursive: true });
+      // parent dir for credentials
+      const credDir = path.dirname(this.options.credentialsPath);
+      if (!fs.existsSync(credDir)) fs.mkdirSync(credDir, { recursive: true });
+      // parent dir for persistent device
+      const pdDir = path.dirname(this.options.persistentDeviceFile);
+      if (!fs.existsSync(pdDir)) fs.mkdirSync(pdDir, { recursive: true });
+    } catch (e) {
+      this.logger('Failed to ensure directories: ' + e.message, '⚠️');
+    }
+  }
+
     loadPersistentDevice() {
         try {
             if (!this.options.persistentDevice) return null;
@@ -1102,7 +1131,7 @@ async function integratedNexusLogin(credentials = null, options = {}) {
         
         try {
             // Prepare global options for bot system
-            const globalOptions = {
+      const globalOptions = {
                 selfListen: false,
                 selfListenEvent: false,
                 listenEvents: false,
@@ -1113,9 +1142,12 @@ async function integratedNexusLogin(credentials = null, options = {}) {
                 autoMarkRead: false,
                 autoReconnect: true,
                 logRecordSize: defaultLogRecordSize,
-                online: true,
+        online: (process.env.NEXUS_ONLINE ? (process.env.NEXUS_ONLINE === '1' || process.env.NEXUS_ONLINE === 'true') : true),
                 emitReady: false,
-                userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
+        userAgent: process.env.NEXUS_UA || "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
+        proxy: process.env.NEXUS_PROXY || process.env.HTTPS_PROXY || process.env.HTTP_PROXY,
+        acceptLanguage: process.env.NEXUS_ACCEPT_LANGUAGE || 'en-US,en;q=0.9',
+        disablePreflight: process.env.NEXUS_DISABLE_PREFLIGHT === '1' || process.env.NEXUS_DISABLE_PREFLIGHT === 'true',
                 ...options
             };
 
@@ -1229,7 +1261,18 @@ async function login(loginData, options = {}, callback) {
       mainLogger.info('✅ Session generated successfully');
       mainLogger.info('🔄 Starting bot with generated session (old system)');
       
-      // STEP 2: ALWAYS use OLD system for actual login/session/bot
+      // STEP 2: Single session guard before starting bot
+      try {
+        const ssg = new SingleSessionGuard({ dataDir: process.env.NEXUS_DATA_DIR });
+        ssg.acquire();
+        // keep guard reference to release on exit
+        global.__NEXUS_SSG__ = ssg;
+      } catch (e) {
+        mainLogger.error('⚠️ Single session guard blocked start', e.message);
+        if (callback) callback(e);
+        return usePromise ? promise : undefined;
+      }
+      // STEP 3: ALWAYS use OLD system for actual login/session/bot
       const globalOptions = {
         selfListen: false,
         selfListenEvent: false,
@@ -1271,7 +1314,16 @@ async function login(loginData, options = {}, callback) {
       return usePromise ? promise : undefined;
     }
     
-    // Direct session authentication using appstate
+    // Direct session authentication using appstate (with single session guard)
+    try {
+      const ssg = new SingleSessionGuard({ dataDir: process.env.NEXUS_DATA_DIR });
+      ssg.acquire();
+      global.__NEXUS_SSG__ = ssg;
+    } catch (e) {
+      mainLogger.error('⚠️ Single session guard blocked start', e.message);
+      if (callback) callback(e);
+      return usePromise ? promise : undefined;
+    }
     mainLogger.info('🔄 Starting session authentication');
     
     const globalOptions = {
@@ -1285,9 +1337,12 @@ async function login(loginData, options = {}, callback) {
       autoMarkRead: false,
       autoReconnect: true,
       logRecordSize: defaultLogRecordSize,
-      online: true,
+      online: (process.env.NEXUS_ONLINE ? (process.env.NEXUS_ONLINE === '1' || process.env.NEXUS_ONLINE === 'true') : true),
       emitReady: false,
-      userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
+      userAgent: process.env.NEXUS_UA || "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
+      proxy: process.env.NEXUS_PROXY || process.env.HTTPS_PROXY || process.env.HTTP_PROXY,
+      acceptLanguage: process.env.NEXUS_ACCEPT_LANGUAGE || 'en-US,en;q=0.9',
+      disablePreflight: process.env.NEXUS_DISABLE_PREFLIGHT === '1' || process.env.NEXUS_DISABLE_PREFLIGHT === 'true',
       ...options
     };
     

package/lib/logger.js

@@ -1,7 +1,6 @@
 const chalk = require('chalk');
 const gradient = require('gradient-string');
 
-// Use a professional gradient for info logs
 const infoGradient = gradient(['#00c6ff', '#0072ff']); // blue-cyan gradient
 const warnColor = chalk.yellow.bold;
 const errorColor = chalk.red.bold;

package/lib/safety/SingleSessionGuard.js

@@ -0,0 +1,99 @@
+"use strict";
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+function nowIso(){ return new Date().toISOString(); }
+
+function readJsonSafe(file){
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch(_) { return null; }
+}
+
+function writeJsonSafe(file, obj){
+  try { fs.writeFileSync(file, JSON.stringify(obj, null, 2)); } catch(_) {}
+}
+
+class SingleSessionGuard {
+  constructor(options={}){
+    const baseDir = options.dataDir || process.env.NEXUS_DATA_DIR || process.env.RENDER_DATA_DIR || process.cwd();
+    this.lockPath = options.lockPath || process.env.NEXUS_SESSION_LOCK_PATH || path.join(baseDir, 'session.lock');
+    this.ttlMs = options.ttlMs || parseInt(process.env.NEXUS_SESSION_TTL_MS || '900000', 10); // default 15m
+    this.force = options.force || (process.env.NEXUS_FORCE_LOCK === '1' || process.env.NEXUS_FORCE_LOCK === 'true');
+    this.heartbeatMs = options.heartbeatMs || 60000; // 1m
+    this.sessionId = (options.sessionId) || `${process.pid}-${Math.random().toString(36).slice(2,10)}`;
+    this._hbTimer = null;
+    this._acquired = false;
+  }
+
+  isStale(lock){
+    if(!lock || !lock.updatedAt) return true;
+    const age = Date.now() - new Date(lock.updatedAt).getTime();
+    return age > this.ttlMs;
+  }
+
+  acquire(){
+    // Ensure parent dir exists
+    try { fs.mkdirSync(path.dirname(this.lockPath), { recursive: true }); } catch(_) {}
+    if (fs.existsSync(this.lockPath)){
+      const existing = readJsonSafe(this.lockPath);
+      if (this.isStale(existing) || this.force){
+        // Take over
+        try { fs.unlinkSync(this.lockPath); } catch(_) {}
+      } else {
+        const msg = `Another Nexus-FCA session appears active (lock: ${this.lockPath}). Set NEXUS_FORCE_LOCK=true to override or wait until stale.`;
+        const error = new Error(msg);
+        error.code = 'NEXUS_MULTIPLE_SESSIONS';
+        throw error;
+      }
+    }
+    const payload = {
+      pid: process.pid,
+      host: os.hostname(),
+      sessionId: this.sessionId,
+      startedAt: nowIso(),
+      updatedAt: nowIso()
+    };
+    writeJsonSafe(this.lockPath, payload);
+    this._acquired = true;
+    this._startHeartbeat();
+    this._installExitHooks();
+    return true;
+  }
+
+  _startHeartbeat(){
+    this._clearHeartbeat();
+    this._hbTimer = setInterval(()=>{
+      try {
+        if(!this._acquired) return;
+        const cur = readJsonSafe(this.lockPath) || {};
+        cur.updatedAt = nowIso();
+        cur.pid = process.pid;
+        cur.sessionId = this.sessionId;
+        cur.host = cur.host || os.hostname();
+        writeJsonSafe(this.lockPath, cur);
+      } catch(_){}
+    }, this.heartbeatMs).unref();
+  }
+
+  _clearHeartbeat(){
+    if(this._hbTimer){ try { clearInterval(this._hbTimer); } catch(_){} this._hbTimer = null; }
+  }
+
+  _installExitHooks(){
+    if (this._exitHooksInstalled) return;
+    this._exitHooksInstalled = true;
+    const release = () => { try { this.release(); } catch(_){} };
+    process.on('SIGINT', release);
+    process.on('SIGTERM', release);
+    process.on('exit', release);
+  }
+
+  release(){
+    this._clearHeartbeat();
+    if(!this._acquired) return;
+    this._acquired = false;
+    try { if(fs.existsSync(this.lockPath)) fs.unlinkSync(this.lockPath); } catch(_){}
+  }
+}
+
+module.exports = { SingleSessionGuard };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexus-fca",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "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": {

package/src/listenMqtt.js

@@ -68,6 +68,7 @@ function resetBackoff(state){
 // Build lazy preflight gating
 function shouldRunPreflight(ctx){
   if(ctx.globalOptions.disablePreflight) return false;
+  if(process.env.NEXUS_DISABLE_PREFLIGHT === '1' || process.env.NEXUS_DISABLE_PREFLIGHT === 'true') return false;
   // If we connected successfully within last 10 minutes, skip heavy preflight to reduce surface.
   const now = Date.now();
   const metrics = ctx.health;
@@ -174,8 +175,9 @@ function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
   const backoff = getBackoffState(ctx);
   if(!ctx._mqttDiag) ctx._mqttDiag = { attempts:0, events:[] }; 
   ctx._mqttDiag.attempts++;
-  // Suppress previously noisy test info log (kept only if verbose flag enabled)
-  if (ctx.globalOptions && ctx.globalOptions.verboseMqtt) {
+  // Suppress previously noisy test info log (visible only if verbose flag enabled or env toggled)
+  const verboseMqtt = (ctx.globalOptions && ctx.globalOptions.verboseMqtt) || process.env.NEXUS_VERBOSE_MQTT === '1' || process.env.NEXUS_VERBOSE_MQTT === 'true';
+  if (verboseMqtt) {
     log.info('listenMqtt', `Starting Nexus MQTT bridge (attempt=${ctx._mqttDiag.attempts}, backoff=${backoff.current||0}ms)`);
   }
   const runPreflight = shouldRunPreflight(ctx);
@@ -251,7 +253,7 @@ function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
         Upgrade: "websocket",
         "Sec-WebSocket-Version": "13",
         "Accept-Encoding": "gzip, deflate, br",
-        "Accept-Language": "vi,en;q=0.9",
+  "Accept-Language": (ctx.globalOptions && ctx.globalOptions.acceptLanguage) || process.env.NEXUS_ACCEPT_LANGUAGE || "en-US,en;q=0.9",
         "Sec-WebSocket-Extensions":
           "permessage-deflate; client_max_window_bits",
       },
@@ -264,6 +266,11 @@ function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
     reconnectPeriod: 1000,
     connectTimeout: 5000,
   };
+  // Proxy support via option or environment
+  if (ctx.globalOptions.proxy === undefined) {
+    const envProxy = process.env.NEXUS_PROXY || process.env.HTTPS_PROXY || process.env.HTTP_PROXY;
+    if (envProxy) ctx.globalOptions.proxy = envProxy;
+  }
   if (ctx.globalOptions.proxy !== undefined) {
     try {
       const agent = new HttpsProxyAgent(ctx.globalOptions.proxy);
@@ -279,7 +286,7 @@ function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
     () => buildStream(options, rawWs, buildProxy()),
     options
   );
-  if (ctx.globalOptions && ctx.globalOptions.verboseMqtt) {
+  if (verboseMqtt) {
     log.info('listenMqtt', `MQTT bridge dialing ${host}`);
   }
   const mqttClient = ctx.mqttClient;
@@ -331,7 +338,7 @@ function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
   mqttClient.on("connect", function () {
     resetBackoff(backoff);
     ctx.health.onConnect();
-  if (ctx.globalOptions && ctx.globalOptions.verboseMqtt) {
+  if (verboseMqtt) {
     log.info('listenMqtt', `Nexus MQTT bridge established in ${(Date.now()-attemptStartTs)}ms (attempt=${ctx._mqttDiag.attempts}).`);
   }
     if (ctx.globalSafety) { try { ctx.globalSafety.recordEvent(); } catch(_) {} }