securenow 5.16.2 → 5.17.0

package/SKILL-API.md

@@ -460,6 +460,7 @@ Add custom fields via `SECURENOW_SENSITIVE_FIELDS=field1,field2`.
 | `SECURENOW_API_KEY` | API key (`snk_live_...`); activates firewall when set | — |
 | `SECURENOW_API_URL` | SecureNow API base URL | `https://api.securenow.ai` |
 | `SECURENOW_FIREWALL_ENABLED` | Master kill-switch (`0` to disable) | `1` |
+| `SECURENOW_FIREWALL_VERSION_INTERVAL` | Seconds between lightweight version checks | `10` |
 | `SECURENOW_FIREWALL_SYNC_INTERVAL` | Full blocklist refresh interval in seconds | `300` |
 | `SECURENOW_FIREWALL_FAIL_MODE` | `open` (allow all when unavailable) or `closed` | `open` |
 | `SECURENOW_FIREWALL_STATUS_CODE` | HTTP status for blocked requests | `403` |
@@ -470,6 +471,8 @@ Add custom fields via `SECURENOW_SENSITIVE_FIELDS=field1,field2`.
 | `SECURENOW_FIREWALL_CLOUD_DRY_RUN` | `1` to log cloud pushes without applying | `0` |
 | `SECURENOW_TRUSTED_PROXIES` | Comma-separated trusted proxy IPs | — |
 
+**Resilience:** The firewall SDK includes a circuit breaker (opens after 5 consecutive errors, 2-min cooldown), in-flight request guards (prevents overlapping requests), 429 Retry-After support, and exponential backoff on both version checks and initial sync retries.
+
 ### Cloud WAF Provider Variables
 
 | Provider | Variables |

package/SKILL-CLI.md

@@ -336,7 +336,7 @@ securenow instances test <id>                # test connection
 
 ```bash
 securenow notifications list --limit 5 --json
-securenow issues show <issue-id> --json
+# IMPORTANT: parse the ipInvestigations array for each notification — see statuses below
 securenow ip <attacker-ip> --json
 securenow ip traces <attacker-ip> --json
 securenow traces show <trace-id> --json
@@ -345,6 +345,19 @@ securenow traces analyze <trace-id> --json
 securenow blocklist add <attacker-ip> --reason "Automated: SQL injection from issue #<id>"
 ```
 
+#### Notification IP Investigation Statuses
+
+Each notification contains an `ipInvestigations` array. **Every IP has its own `status` field** that you MUST check before taking action or raising flags. Do not rely only on top-level notification fields — always cross-reference each IP's individual investigation status.
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| `open` | Still needs review — no determination yet | Investigate: run `securenow ip <ip>`, check traces, decide to block or dismiss |
+| `false_positive` | Trusted/dismissed by exclusion rule, verified bot, or trusted IP list | **Skip** — greyed out in UI, no action needed |
+| `blocked` | Already on the user's blocklist | **Skip** — already handled |
+| `clean` | Pipeline analyzed and cleared as benign | **Skip** — verified safe |
+
+**Critical workflow rule:** When investigating notifications, iterate `ipInvestigations[]` and **only flag or act on IPs with `status: "open"`**. IPs marked `false_positive`, `blocked`, or `clean` have already been triaged — do not re-flag them.
+
 ### Triage and Suppress a False Positive
 
 ```bash

package/cli/auth.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const http = require('http');
+const crypto = require('crypto');
 const { execFileSync } = require('child_process');
 const config = require('./config');
 const { api, CLIError } = require('./client');
@@ -39,16 +40,18 @@ function decodeJwtPayload(token) {
 
 async function loginWithBrowser() {
   const appUrl = config.getAppUrl();
+  const nonce = crypto.randomBytes(24).toString('base64url');
 
   return new Promise((resolve, reject) => {
     let pendingToken = null;
 
     const server = http.createServer((req, res) => {
-      const url = new URL(req.url, `http://localhost`);
+      const url = new URL(req.url, `http://127.0.0.1`);
 
       if (url.pathname === '/callback') {
         const token = url.searchParams.get('token');
         const error = url.searchParams.get('error');
+        const returnedState = url.searchParams.get('state');
 
         res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
 
@@ -59,13 +62,20 @@ async function loginWithBrowser() {
           return;
         }
 
+        if (returnedState !== nonce) {
+          res.end('<html><body style="font-family:system-ui;text-align:center;padding:60px"><h2>Security Error</h2><p>State mismatch — this request may not have originated from your CLI. Please try again.</p></body></html>');
+          server.close();
+          reject(new CLIError('State mismatch on callback — possible CSRF. Please retry `securenow login`.'));
+          return;
+        }
+
         if (token) {
           pendingToken = token;
           const payload = decodeJwtPayload(token);
           const email = payload?.email || 'unknown account';
           const safeEmail = email.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
           const port = server.address().port;
-          const switchUrl = `${appUrl}/cli/auth?callback=http://localhost:${port}/callback&force_login=1`;
+          const switchUrl = `${appUrl}/cli/auth?callback=http://127.0.0.1:${port}/callback&state=${encodeURIComponent(nonce)}&force_login=1`;
 
           res.end([
             '<!DOCTYPE html><html><head><meta charset="utf-8"><title>SecureNow CLI Login</title></head>',
@@ -91,7 +101,7 @@ async function loginWithBrowser() {
             '<script>',
             'document.getElementById("confirm-btn").addEventListener("click", function(){',
             '  this.disabled=true;this.textContent="Connecting\u2026";this.style.background="#86efac";this.style.cursor="default";',
-            `  fetch("/confirm").then(function(){`,
+            `  fetch("/confirm?nonce=${encodeURIComponent(nonce)}").then(function(){`,
             '    document.getElementById("confirm-btn").style.display="none";',
             '    document.getElementById("done-msg").style.display="block";',
             '  });',
@@ -109,6 +119,11 @@ async function loginWithBrowser() {
       }
 
       if (url.pathname === '/confirm' && pendingToken) {
+        if (url.searchParams.get('nonce') !== nonce) {
+          res.writeHead(403, { 'Content-Type': 'application/json' });
+          res.end('{"error":"invalid nonce"}');
+          return;
+        }
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end('{"ok":true}');
         const token = pendingToken;
@@ -124,7 +139,7 @@ async function loginWithBrowser() {
 
     server.listen(0, '127.0.0.1', () => {
       const port = server.address().port;
-      const authUrl = `${appUrl}/cli/auth?callback=http://localhost:${port}/callback`;
+      const authUrl = `${appUrl}/cli/auth?callback=http://127.0.0.1:${port}/callback&state=${encodeURIComponent(nonce)}`;
 
       console.log('');
       ui.info('Opening browser for authentication...');

package/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 'use strict';
 
 const ui = require('./cli/ui');

package/docs/FIREWALL-GUIDE.md

@@ -345,6 +345,21 @@ The firewall uses the same trusted-proxy-aware IP resolution as SecureNow tracin
 - Store it in environment variables or `.env` — never commit it to source control
 - The key is hashed (SHA-256) on the server — SecureNow never stores the plaintext
 
+### Sync Architecture
+
+The SDK uses a unified sync endpoint (`/firewall/sync`) that combines version checking and data fetching into a single request:
+
+1. **One request per poll** — The SDK sends its current blocklist and allowlist versions. The API responds with version info and only includes full IP lists for lists that have changed.
+2. **HTTP Keep-Alive** — TCP connections are reused across polls. TLS handshake happens once; subsequent requests reuse the socket (~5-10ms vs ~100-200ms per request).
+3. **Automatic fallback** — If the unified endpoint is not available (older API), the SDK falls back to legacy separate endpoints.
+
+### Circuit Breaker & Back-Pressure
+
+- **Circuit breaker** — After 5 consecutive errors, the SDK pauses all polling for 2 minutes. After cooldown, a single probe is sent. If it succeeds, normal polling resumes.
+- **In-flight guard** — Only one poll can be in-flight at a time. If the API is slow, the next scheduled poll is skipped.
+- **429 Retry-After** — When the API returns HTTP 429, all polling pauses for the `Retry-After` duration.
+- **Exponential backoff** — Poll interval doubles on each consecutive error (10s → 20s → 40s → 80s, capped at 120s).
+
 ### Cleanup on Shutdown
 
 All layers clean up on process exit (SIGINT/SIGTERM):

package/firewall.js

@@ -8,7 +8,7 @@ const { resolveClientIp } = require('./resolve-ip');
 let _options = null;
 let _matcher = null;
 let _syncTimer = null;
-let _versionTimer = null;
+let _pollTimer = null;
 let _lastModified = null;
 let _lastVersion = null;
 let _lastSyncEtag = null;
@@ -25,85 +25,89 @@ let _allowlistRawIps = [];
 let _lastAllowlistModified = null;
 let _lastAllowlistVersion = null;
 let _lastAllowlistSyncEtag = null;
-let _allowlistVersionTimer = null;
 
-// ────── Blocklist Sync ──────
+// Circuit breaker
+const CIRCUIT_OPEN_THRESHOLD = 5;
+const CIRCUIT_OPEN_COOLDOWN_MS = 120_000;
+let _circuitState = 'closed';
+let _circuitOpenedAt = 0;
 
-function buildUrl(apiUrl, path) {
-  return apiUrl.replace(/\/+$/, '') + '/api/v1' + path;
-}
+// In-flight guard and 429 back-off
+let _pollInflight = false;
+let _retryAfterUntil = 0;
 
-function syncBlocklist(callback) {
-  const url = buildUrl(_options.apiUrl, '/firewall/blocklist');
-  const mod = url.startsWith('https') ? https : http;
-  const parsed = new URL(url);
+// Keep-alive agents — reuse TCP connections across polls (TLS handshake once)
+const _httpAgent = new http.Agent({ keepAlive: true, maxSockets: 2, keepAliveMsecs: 30_000 });
+const _httpsAgent = new https.Agent({ keepAlive: true, maxSockets: 2, keepAliveMsecs: 30_000 });
 
-  const reqOptions = {
-    hostname: parsed.hostname,
-    port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
-    path: parsed.pathname + parsed.search,
-    method: 'GET',
-    headers: {
-      'Authorization': `Bearer ${_options.apiKey}`,
-      'User-Agent': 'securenow-firewall-sdk',
-    },
-    timeout: 10000,
-  };
+// Unified sync uses /firewall/sync (v2). Falls back to legacy on 404.
+let _useUnifiedSync = true;
 
-  if (_lastSyncEtag) {
-    reqOptions.headers['If-None-Match'] = _lastSyncEtag;
-  } else if (_lastModified) {
-    reqOptions.headers['If-Modified-Since'] = _lastModified;
-  }
+// ────── Circuit Breaker ──────
 
-  const req = mod.request(reqOptions, (res) => {
-    if (res.statusCode === 304) {
-      callback(null, false);
-      return;
+function maybeOpenCircuit() {
+  if (_circuitState === 'open') return;
+  if (_consecutiveErrors >= CIRCUIT_OPEN_THRESHOLD) {
+    _circuitState = 'open';
+    _circuitOpenedAt = Date.now();
+    if (_options && _options.log) {
+      console.warn('[securenow] Firewall: circuit breaker OPEN — pausing polling for %ds', CIRCUIT_OPEN_COOLDOWN_MS / 1000);
     }
+  }
+}
 
-    let data = '';
-    res.on('data', (chunk) => { data += chunk; });
-    res.on('end', () => {
-      if (res.statusCode !== 200) {
-        callback(new Error(`API returned ${res.statusCode}: ${data.slice(0, 200)}`));
-        return;
-      }
-      try {
-        const body = JSON.parse(data);
-        const ips = body.ips || [];
-        _rawIps = ips;
-        _matcher = createMatcher(ips);
-        _lastModified = res.headers['last-modified'] || null;
-        if (res.headers['etag']) _lastSyncEtag = res.headers['etag'];
-        _stats.syncs++;
-        notifyLayers(ips);
-        callback(null, true, _matcher.stats());
-      } catch (e) {
-        callback(new Error(`Failed to parse blocklist response: ${e.message}`));
-      }
-    });
-  });
+function resetCircuit() {
+  if (_circuitState !== 'closed') {
+    _circuitState = 'closed';
+    if (_options && _options.log) console.log('[securenow] Firewall: circuit breaker CLOSED — API healthy');
+  }
+  _consecutiveErrors = 0;
+}
 
-  req.on('error', (err) => callback(err));
-  req.on('timeout', () => { req.destroy(); callback(new Error('Sync request timed out')); });
-  req.end();
+function shouldSkipRequest() {
+  if (Date.now() < _retryAfterUntil) return true;
+  if (_circuitState === 'closed') return false;
+  if (_circuitState === 'open') {
+    if (Date.now() - _circuitOpenedAt >= CIRCUIT_OPEN_COOLDOWN_MS) {
+      _circuitState = 'half-open';
+      return false;
+    }
+    return true;
+  }
+  return false; // half-open: allow one probe
 }
 
-function notifyLayers(ips) {
-  for (const layer of _layers) {
-    try { if (typeof layer.sync === 'function') layer.sync(ips); } catch (_) {}
+function handleRetryAfter(res) {
+  const ra = res.headers['retry-after'];
+  if (!ra) return;
+  const secs = parseInt(ra, 10);
+  if (secs > 0 && secs <= 300) {
+    _retryAfterUntil = Date.now() + secs * 1000;
+    if (_options && _options.log) {
+      console.warn('[securenow] Firewall: API returned 429, backing off for %ds', secs);
+    }
   }
 }
 
-// ────── Allowlist Sync ──────
+// ────── HTTP helpers ──────
 
-function syncAllowlist(callback) {
-  const url = buildUrl(_options.apiUrl, '/firewall/allowlist');
+function buildUrl(apiUrl, path) {
+  return apiUrl.replace(/\/+$/, '') + '/api/v1' + path;
+}
+
+function jitter(baseMs) {
+  return baseMs * (0.8 + Math.random() * 0.4);
+}
+
+function agentFor(url) {
+  return url.startsWith('https') ? _httpsAgent : _httpAgent;
+}
+
+function httpGet(url, extraHeaders, timeout, callback) {
   const mod = url.startsWith('https') ? https : http;
   const parsed = new URL(url);
 
-  const reqOptions = {
+  const req = mod.request({
     hostname: parsed.hostname,
     port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
     path: parsed.pathname + parsed.search,
@@ -111,211 +115,315 @@ function syncAllowlist(callback) {
     headers: {
       'Authorization': `Bearer ${_options.apiKey}`,
       'User-Agent': 'securenow-firewall-sdk',
+      ...extraHeaders,
     },
-    timeout: 10000,
-  };
-
-  if (_lastAllowlistSyncEtag) {
-    reqOptions.headers['If-None-Match'] = _lastAllowlistSyncEtag;
-  } else if (_lastAllowlistModified) {
-    reqOptions.headers['If-Modified-Since'] = _lastAllowlistModified;
-  }
-
-  const req = mod.request(reqOptions, (res) => {
-    if (res.statusCode === 304) {
-      callback(null, false);
-      return;
-    }
-
+    timeout,
+    agent: agentFor(url),
+  }, (res) => {
     let data = '';
     res.on('data', (chunk) => { data += chunk; });
-    res.on('end', () => {
-      if (res.statusCode !== 200) {
-        callback(new Error(`API returned ${res.statusCode}: ${data.slice(0, 200)}`));
-        return;
-      }
-      try {
-        const body = JSON.parse(data);
-        const ips = body.ips || [];
-        _allowlistRawIps = ips;
-        _allowlistMatcher = createMatcher(ips);
-        _lastAllowlistModified = res.headers['last-modified'] || null;
-        if (res.headers['etag']) _lastAllowlistSyncEtag = res.headers['etag'];
-        callback(null, true, _allowlistMatcher.stats());
-      } catch (e) {
-        callback(new Error(`Failed to parse allowlist response: ${e.message}`));
-      }
-    });
+    res.on('end', () => { callback(null, res, data); });
   });
 
   req.on('error', (err) => callback(err));
-  req.on('timeout', () => { req.destroy(); callback(new Error('Allowlist sync request timed out')); });
+  req.on('timeout', () => { req.destroy(); callback(new Error('Request timed out')); });
   req.end();
 }
 
-function checkAllowlistVersion(callback) {
-  const url = buildUrl(_options.apiUrl, '/firewall/allowlist/version');
-  const mod = url.startsWith('https') ? https : http;
-  const parsed = new URL(url);
+// ────── Unified Sync (v2 — single request for everything) ──────
 
-  const headers = {
-    'Authorization': `Bearer ${_options.apiKey}`,
-    'User-Agent': 'securenow-firewall-sdk',
-  };
-  if (_lastAllowlistVersion) headers['If-None-Match'] = _lastAllowlistVersion;
+function doUnifiedSync(callback) {
+  const url = buildUrl(_options.apiUrl, '/firewall/sync');
+  const headers = {};
+  if (_lastVersion) headers['X-Blocklist-Version'] = _lastVersion;
+  if (_lastAllowlistVersion) headers['X-Allowlist-Version'] = _lastAllowlistVersion;
+
+  httpGet(url, headers, 8000, (err, res, data) => {
+    if (err) return callback(err);
+
+    _stats.versionChecks++;
 
-  const req = mod.request({
-    hostname: parsed.hostname,
-    port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
-    path: parsed.pathname + parsed.search,
-    method: 'GET',
-    headers,
-    timeout: 5000,
-  }, (res) => {
     if (res.statusCode === 304) {
-      res.resume();
-      callback(null, false);
-      return;
+      return callback(null, { blChanged: false, alChanged: false });
     }
 
-    let data = '';
-    res.on('data', (chunk) => { data += chunk; });
-    res.on('end', () => {
-      if (res.statusCode !== 200) {
-        callback(null, false);
-        return;
+    if (res.statusCode === 404) {
+      _useUnifiedSync = false;
+      if (_options.log) console.log('[securenow] Firewall: /sync not available, using legacy endpoints');
+      return callback(null, { blChanged: false, alChanged: false, useLegacy: true });
+    }
+
+    if (res.statusCode === 429) { handleRetryAfter(res); }
+
+    if (res.statusCode !== 200) {
+      return callback(new Error(`API returned ${res.statusCode}: ${data.slice(0, 200)}`));
+    }
+
+    try {
+      const body = JSON.parse(data);
+
+      let blChanged = false;
+      let alChanged = false;
+
+      // Update blocklist version + data
+      if (body.blocklist) {
+        const newVer = body.blocklist.version;
+        if (newVer !== _lastVersion) {
+          _lastVersion = newVer;
+          blChanged = true;
+        }
       }
-      try {
-        const body = JSON.parse(data);
-        const version = body.version || null;
-        const changed = version !== _lastAllowlistVersion;
-        if (changed) _lastAllowlistVersion = version;
-        callback(null, changed);
-      } catch (_e) { callback(null, false); }
-    });
-  });
 
-  req.on('error', () => { callback(null, false); });
-  req.on('timeout', () => { req.destroy(); callback(null, false); });
-  req.end();
+      if (body.blocklistIps) {
+        _rawIps = body.blocklistIps;
+        _matcher = createMatcher(body.blocklistIps);
+        _stats.syncs++;
+        notifyLayers(body.blocklistIps);
+        blChanged = true;
+      }
+
+      // Update allowlist version + data
+      if (body.allowlist) {
+        const newVer = body.allowlist.version;
+        if (newVer !== _lastAllowlistVersion) {
+          _lastAllowlistVersion = newVer;
+          alChanged = true;
+        }
+      }
+
+      if (body.allowlistIps) {
+        _allowlistRawIps = body.allowlistIps;
+        _allowlistMatcher = createMatcher(body.allowlistIps);
+        alChanged = true;
+      }
+
+      callback(null, { blChanged, alChanged });
+    } catch (e) {
+      callback(new Error(`Failed to parse sync response: ${e.message}`));
+    }
+  });
 }
 
-function doFullAllowlistSync() {
-  syncAllowlist((err, changed, stats) => {
-    if (err) {
-      if (_options.log) console.warn('[securenow] Firewall: allowlist sync failed:', err.message);
-    } else if (changed && stats && _options.log) {
-      console.log('[securenow] Firewall: re-synced %d allowed IPs', stats.total);
+// ────── Legacy Sync (v1 — separate endpoints, kept for backward compat) ──────
+
+function legacyBlocklistSync(callback) {
+  const url = buildUrl(_options.apiUrl, '/firewall/blocklist');
+  const headers = {};
+  if (_lastSyncEtag) headers['If-None-Match'] = _lastSyncEtag;
+  else if (_lastModified) headers['If-Modified-Since'] = _lastModified;
+
+  httpGet(url, headers, 10000, (err, res, data) => {
+    if (err) return callback(err);
+    if (res.statusCode === 304) return callback(null, false);
+    if (res.statusCode === 429) { handleRetryAfter(res); }
+    if (res.statusCode !== 200) return callback(new Error(`API returned ${res.statusCode}: ${data.slice(0, 200)}`));
+
+    try {
+      const body = JSON.parse(data);
+      const ips = body.ips || [];
+      _rawIps = ips;
+      _matcher = createMatcher(ips);
+      _lastModified = res.headers['last-modified'] || null;
+      if (res.headers['etag']) _lastSyncEtag = res.headers['etag'];
+      _stats.syncs++;
+      notifyLayers(ips);
+      callback(null, true, _matcher.stats());
+    } catch (e) {
+      callback(new Error(`Failed to parse blocklist: ${e.message}`));
     }
   });
 }
 
-function scheduleNextAllowlistVersionCheck() {
-  const baseMs = (_options.versionCheckInterval || 10) * 1000;
-  const delayMs = jitter(baseMs);
+function legacyAllowlistSync(callback) {
+  const url = buildUrl(_options.apiUrl, '/firewall/allowlist');
+  const headers = {};
+  if (_lastAllowlistSyncEtag) headers['If-None-Match'] = _lastAllowlistSyncEtag;
+  else if (_lastAllowlistModified) headers['If-Modified-Since'] = _lastAllowlistModified;
 
-  _allowlistVersionTimer = setTimeout(() => {
-    checkAllowlistVersion((_err, changed) => {
-      if (changed) {
-        if (_options.log) console.log('[securenow] Firewall: allowlist version changed, syncing…');
-        doFullAllowlistSync();
-      }
-      scheduleNextAllowlistVersionCheck();
-    });
-  }, delayMs);
-  if (_allowlistVersionTimer.unref) _allowlistVersionTimer.unref();
+  httpGet(url, headers, 10000, (err, res, data) => {
+    if (err) return callback(err);
+    if (res.statusCode === 304) return callback(null, false);
+    if (res.statusCode === 429) { handleRetryAfter(res); }
+    if (res.statusCode !== 200) return callback(new Error(`API returned ${res.statusCode}: ${data.slice(0, 200)}`));
+
+    try {
+      const body = JSON.parse(data);
+      const ips = body.ips || [];
+      _allowlistRawIps = ips;
+      _allowlistMatcher = createMatcher(ips);
+      _lastAllowlistModified = res.headers['last-modified'] || null;
+      if (res.headers['etag']) _lastAllowlistSyncEtag = res.headers['etag'];
+      callback(null, true, _allowlistMatcher.stats());
+    } catch (e) {
+      callback(new Error(`Failed to parse allowlist: ${e.message}`));
+    }
+  });
 }
 
-function checkVersion(callback) {
+function legacyVersionCheck(callback) {
   const url = buildUrl(_options.apiUrl, '/firewall/blocklist/version');
-  const mod = url.startsWith('https') ? https : http;
-  const parsed = new URL(url);
-
-  const headers = {
-    'Authorization': `Bearer ${_options.apiKey}`,
-    'User-Agent': 'securenow-firewall-sdk',
-  };
+  const headers = {};
   if (_lastVersion) headers['If-None-Match'] = _lastVersion;
 
-  const req = mod.request({
-    hostname: parsed.hostname,
-    port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
-    path: parsed.pathname + parsed.search,
-    method: 'GET',
-    headers,
-    timeout: 5000,
-  }, (res) => {
+  httpGet(url, headers, 5000, (err, res, data) => {
+    if (err) return callback(err);
     _stats.versionChecks++;
+    if (res.statusCode === 304) return callback(null, false, false);
+    if (res.statusCode === 429) { handleRetryAfter(res); }
+    if (res.statusCode !== 200) return callback(new Error(`API ${res.statusCode}`));
 
-    if (res.statusCode === 304) {
-      _consecutiveErrors = 0;
-      res.resume();
-      callback(null, false);
-      return;
+    try {
+      const body = JSON.parse(data);
+      const version = body.version || null;
+      const changed = version !== _lastVersion;
+      if (changed) _lastVersion = version;
+      callback(null, changed, false);
+    } catch (_e) { callback(null, false, false); }
+  });
+}
+
+function legacyAllowlistVersionCheck(callback) {
+  const url = buildUrl(_options.apiUrl, '/firewall/allowlist/version');
+  const headers = {};
+  if (_lastAllowlistVersion) headers['If-None-Match'] = _lastAllowlistVersion;
+
+  httpGet(url, headers, 5000, (err, res, data) => {
+    if (err) return callback(err);
+    if (res.statusCode === 304) return callback(null, false);
+    if (res.statusCode === 429) { handleRetryAfter(res); }
+    if (res.statusCode !== 200) return callback(new Error(`API ${res.statusCode}`));
+
+    try {
+      const body = JSON.parse(data);
+      const version = body.version || null;
+      const changed = version !== _lastAllowlistVersion;
+      if (changed) _lastAllowlistVersion = version;
+      callback(null, changed);
+    } catch (_e) { callback(null, false); }
+  });
+}
+
+function doLegacyPoll(callback) {
+  let pending = 2;
+  let blChanged = false;
+  let alChanged = false;
+  let firstError = null;
+
+  function checkDone() {
+    if (--pending > 0) return;
+    if (firstError) return callback(firstError);
+
+    let syncsPending = 0;
+    if (blChanged) syncsPending++;
+    if (alChanged) syncsPending++;
+    if (syncsPending === 0) return callback(null, { blChanged: false, alChanged: false });
+
+    function syncDone() {
+      if (--syncsPending > 0) return;
+      callback(null, { blChanged, alChanged });
     }
 
-    let data = '';
-    res.on('data', (chunk) => { data += chunk; });
-    res.on('end', () => {
-      if (res.statusCode !== 200) {
-        _consecutiveErrors++;
-        _stats.errors++;
-        callback(null, false);
-        return;
-      }
-      _consecutiveErrors = 0;
-      try {
-        const body = JSON.parse(data);
-        const version = body.version || null;
-        const changed = version !== _lastVersion;
-        if (changed) _lastVersion = version;
-        callback(null, changed);
-      } catch (_e) { callback(null, false); }
-    });
+    if (blChanged) {
+      legacyBlocklistSync((err, changed, stats) => {
+        if (err && _options.log) console.warn('[securenow] Firewall: sync failed (using stale list):', err.message);
+        else if (changed && stats && _options.log) console.log('[securenow] Firewall: re-synced %d blocked IPs', stats.total);
+        syncDone();
+      });
+    }
+    if (alChanged) {
+      legacyAllowlistSync((err, changed, stats) => {
+        if (err && _options.log) console.warn('[securenow] Firewall: allowlist sync failed:', err.message);
+        else if (changed && stats && _options.log) console.log('[securenow] Firewall: re-synced %d allowed IPs', stats.total);
+        syncDone();
+      });
+    }
+  }
+
+  legacyVersionCheck((err, changed) => {
+    if (err) firstError = firstError || err;
+    blChanged = changed;
+    checkDone();
   });
 
-  req.on('error', () => { _consecutiveErrors++; _stats.errors++; callback(null, false); });
-  req.on('timeout', () => { req.destroy(); _consecutiveErrors++; _stats.errors++; callback(null, false); });
-  req.end();
+  legacyAllowlistVersionCheck((err, changed) => {
+    if (err) firstError = firstError || err;
+    alChanged = changed;
+    checkDone();
+  });
 }
 
-function doFullSync() {
-  syncBlocklist((err, changed, stats) => {
+// ────── Unified poll loop ──────
+
+function notifyLayers(ips) {
+  for (const layer of _layers) {
+    try { if (typeof layer.sync === 'function') layer.sync(ips); } catch (_) {}
+  }
+}
+
+function pollOnce(callback) {
+  if (_pollInflight || shouldSkipRequest()) return callback(null);
+  _pollInflight = true;
+
+  const done = (err, result) => {
+    _pollInflight = false;
     if (err) {
-      if (_options.log) console.warn('[securenow] Firewall: sync failed (using stale list):', err.message);
-    } else if (changed && stats && _options.log) {
-      console.log('[securenow] Firewall: re-synced %d blocked IPs', stats.total);
+      _consecutiveErrors++;
+      _stats.errors++;
+      maybeOpenCircuit();
+      if (_options.log) console.warn('[securenow] Firewall: poll failed:', err.message);
+      return callback(err);
     }
-  });
-}
+    _consecutiveErrors = 0;
+    resetCircuit();
+    if (result) {
+      if (result.blChanged && _options.log && _matcher) {
+        const s = _matcher.stats();
+        console.log('[securenow] Firewall: re-synced %d blocked IPs (%d exact + %d CIDR ranges)', s.total, s.exact, s.cidr);
+      }
+      if (result.alChanged && _options.log && _allowlistMatcher) {
+        const s = _allowlistMatcher.stats();
+        console.log('[securenow] Firewall: re-synced %d allowed IPs (%d exact + %d CIDR ranges)', s.total, s.exact, s.cidr);
+      }
+    }
+    callback(null);
+  };
 
-function jitter(baseMs) {
-  return baseMs * (0.8 + Math.random() * 0.4);
+  if (_useUnifiedSync) {
+    doUnifiedSync((err, result) => {
+      if (err) return done(err);
+      if (result && result.useLegacy) {
+        doLegacyPoll(done);
+      } else {
+        done(null, result);
+      }
+    });
+  } else {
+    doLegacyPoll(done);
+  }
 }
 
-function scheduleNextVersionCheck() {
+function scheduleNextPoll() {
   const baseMs = (_options.versionCheckInterval || 10) * 1000;
   const backoffMs = Math.min(baseMs * Math.pow(2, _consecutiveErrors), 120_000);
   const delayMs = jitter(backoffMs);
 
-  _versionTimer = setTimeout(() => {
-    checkVersion((_err, changed) => {
-      if (changed) {
-        if (_options.log) console.log('[securenow] Firewall: blocklist version changed, syncing…');
-        doFullSync();
-      }
-      scheduleNextVersionCheck();
-    });
+  _pollTimer = setTimeout(() => {
+    pollOnce(() => { scheduleNextPoll(); });
   }, delayMs);
-  if (_versionTimer.unref) _versionTimer.unref();
+  if (_pollTimer.unref) _pollTimer.unref();
 }
 
 function startSyncLoop() {
   const fullSyncIntervalMs = (_options.syncInterval || 300) * 1000;
-  const RETRY_DELAY = 5000;
+  const BASE_RETRY = 5000;
+  const MAX_RETRY = 120_000;
+  let _initAttempt = 0;
 
   function initialSync() {
-    syncBlocklist((err, changed, stats) => {
+    // Use unified endpoint for initial sync too
+    const syncFn = _useUnifiedSync ? doUnifiedSync : (cb) => doLegacyPoll(cb);
+
+    syncFn((err, result) => {
       if (err) {
         const isConnErr = /ECONNREFUSED|ENOTFOUND|timed out/i.test(err.message);
         if (isConnErr && !_localhostFallbackTried && _options.apiUrl !== 'http://localhost:4000') {
@@ -327,42 +435,58 @@ function startSyncLoop() {
           if (retryTimer.unref) retryTimer.unref();
           return;
         }
+        if (result && result.useLegacy) {
+          const retryTimer = setTimeout(initialSync, 1000);
+          if (retryTimer.unref) retryTimer.unref();
+          return;
+        }
         if (_options.log) console.warn('[securenow] Firewall: initial sync failed:', err.message);
         if (_options.failMode === 'closed') {
           _matcher = { isBlocked: () => true, stats: () => ({ exact: 0, cidr: 0, total: 0 }) };
         }
-        const retryTimer = setTimeout(initialSync, RETRY_DELAY);
+        _initAttempt++;
+        const delay = Math.min(BASE_RETRY * Math.pow(2, _initAttempt), MAX_RETRY);
+        const retryTimer = setTimeout(initialSync, jitter(delay));
         if (retryTimer.unref) retryTimer.unref();
         return;
       }
-      if (changed && stats) {
-        if (_options.log) console.log('[securenow] Firewall: synced %d blocked IPs (%d exact + %d CIDR ranges)', stats.total, stats.exact, stats.cidr);
-      }
-      _initialized = true;
-    });
-  }
 
-  function initialAllowlistSync() {
-    syncAllowlist((err, changed, stats) => {
-      if (err) {
-        if (_options.log) console.warn('[securenow] Firewall: initial allowlist sync failed:', err.message);
-        const retryTimer = setTimeout(initialAllowlistSync, RETRY_DELAY);
+      if (result && result.useLegacy) {
+        const retryTimer = setTimeout(initialSync, 1000);
         if (retryTimer.unref) retryTimer.unref();
         return;
       }
-      if (changed && stats && stats.total > 0) {
-        if (_options.log) console.log('[securenow] Firewall: synced %d allowed IPs (%d exact + %d CIDR ranges)', stats.total, stats.exact, stats.cidr);
+
+      _initialized = true;
+      if (_options.log && _matcher) {
+        const s = _matcher.stats();
+        console.log('[securenow] Firewall: synced %d blocked IPs (%d exact + %d CIDR ranges)', s.total, s.exact, s.cidr);
+      }
+      if (_options.log && _allowlistMatcher) {
+        const s = _allowlistMatcher.stats();
+        if (s.total > 0) console.log('[securenow] Firewall: synced %d allowed IPs (%d exact + %d CIDR ranges)', s.total, s.exact, s.cidr);
       }
     });
   }
 
   initialSync();
-  initialAllowlistSync();
-
-  scheduleNextVersionCheck();
-  scheduleNextAllowlistVersionCheck();
-
-  _syncTimer = setInterval(() => { doFullSync(); doFullAllowlistSync(); }, fullSyncIntervalMs);
+  scheduleNextPoll();
+
+  // Safety-net full sync timer (less frequent, uses same path)
+  _syncTimer = setInterval(() => {
+    if (shouldSkipRequest()) return;
+    // Force a full re-fetch by clearing versions so unified endpoint returns full data
+    const savedBlVer = _lastVersion;
+    const savedAlVer = _lastAllowlistVersion;
+    _lastVersion = null;
+    _lastAllowlistVersion = null;
+    pollOnce((err) => {
+      if (err) {
+        _lastVersion = savedBlVer;
+        _lastAllowlistVersion = savedAlVer;
+      }
+    });
+  }, fullSyncIntervalMs);
   if (_syncTimer.unref) _syncTimer.unref();
 }
 
@@ -445,7 +569,6 @@ function firewallRequestHandler(req, res) {
       sendBlockResponse(req, res, ip);
       return true;
     }
-    // IP is on the allowlist — skip blocklist check, allow through
     return false;
   }
 
@@ -479,7 +602,6 @@ function patchHttpLayer() {
   if (_httpPatched) return;
   _httpPatched = true;
 
-  // Patch Server.prototype.emit to intercept requests on already-created servers
   patchEmitLayer();
 
   http.createServer = function(...args) {
@@ -506,11 +628,9 @@ function init(options) {
 
   if (_options.log) console.log('[securenow] Firewall: ENABLED');
 
-  // Layer 1: HTTP (always on)
   patchHttpLayer();
   if (_options.log) console.log('[securenow] Firewall: Layer 1 (HTTP 403)      active');
 
-  // Layer 2: TCP
   if (_options.tcp) {
     try {
       const tcpLayer = require('./firewall-tcp');
@@ -524,7 +644,6 @@ function init(options) {
     if (_options.log) console.log('[securenow] Firewall: Layer 2 (TCP drop)       disabled (set SECURENOW_FIREWALL_TCP=1)');
   }
 
-  // Layer 3: iptables
   if (_options.iptables) {
     try {
       const iptablesLayer = require('./firewall-iptables');
@@ -538,7 +657,6 @@ function init(options) {
     if (_options.log) console.log('[securenow] Firewall: Layer 3 (iptables)       disabled (set SECURENOW_FIREWALL_IPTABLES=1)');
   }
 
-  // Layer 4: Cloud WAF
   if (_options.cloud) {
     try {
       const cloudLayer = require('./firewall-cloud');
@@ -556,10 +674,18 @@ function init(options) {
 }
 
 function shutdown() {
-  if (_versionTimer) { clearTimeout(_versionTimer); _versionTimer = null; }
-  if (_allowlistVersionTimer) { clearTimeout(_allowlistVersionTimer); _allowlistVersionTimer = null; }
+  if (_pollTimer) { clearTimeout(_pollTimer); _pollTimer = null; }
   if (_syncTimer) { clearInterval(_syncTimer); _syncTimer = null; }
 
+  _circuitState = 'closed';
+  _circuitOpenedAt = 0;
+  _consecutiveErrors = 0;
+  _pollInflight = false;
+  _retryAfterUntil = 0;
+
+  _httpAgent.destroy();
+  _httpsAgent.destroy();
+
   for (const layer of _layers) {
     try { if (typeof layer.shutdown === 'function') layer.shutdown(); } catch (_) {}
   }
@@ -582,6 +708,9 @@ function getStats() {
     matcher: _matcher ? _matcher.stats() : null,
     allowlistMatcher: _allowlistMatcher ? _allowlistMatcher.stats() : null,
     initialized: _initialized,
+    circuitState: _circuitState,
+    consecutiveErrors: _consecutiveErrors,
+    unifiedSync: _useUnifiedSync,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securenow",
-  "version": "5.16.2",
+  "version": "5.17.0",
   "description": "OpenTelemetry instrumentation for Node.js, Next.js, and Nuxt - Send traces and logs to any OTLP-compatible backend",
   "type": "commonjs",
   "main": "register.js",