securenow 8.11.2 → 8.11.3

package/firewall.js

@@ -1,1470 +1,1470 @@
-'use strict';
-
-const http = require('http');
-const https = require('https');
-const { createMatcher } = require('./cidr');
-const { resolveClientIp } = require('./resolve-ip');
-const challenge = require('./challenge');
-
-let _options = null;
-let _matcher = null;
-let _syncTimer = null;
-let _pollTimer = null;
-let _lastModified = null;
-let _lastVersion = null;
-let _lastSyncEtag = null;
-let _lastUnifiedEtag = null;
-let _initialized = false;
-let _consecutiveErrors = 0;
-let _layers = [];
-let _rawIps = [];
-let _blocklistRules = [];
-let _stats = { syncs: 0, blocked: 0, rateLimited: 0, challenged: 0, allowed: 0, versionChecks: 0, errors: 0, suppressedDisabled: 0 };
-let _localhostFallbackTried = false;
-let _eventQueue = [];
-let _eventTimer = null;
-let _remainingApiUrlFallbacks = [];
-
-// Remote toggle - set by /firewall/sync when an appKey is in scope. Default
-// true so a missing/unreachable backend fails open (matches pre-7.3 behavior).
-// When the dashboard / CLI flips this off, the next poll suppresses
-// enforcement without restarting the host process.
-let _remoteEnabled = true;
-let _lastRemoteEnabled = null;
-
-// Allowlist state
-let _allowlistMatcher = null;
-let _allowlistRawIps = [];
-let _lastAllowlistModified = null;
-let _lastAllowlistVersion = null;
-let _lastAllowlistSyncEtag = null;
-
-// Route/method-scoped policy state. Global IP/CIDR blocks stay in _matcher so
-// TCP, OS firewall, and Cloud WAF layers never over-enforce an HTTP-only rule.
-let _rateLimitRules = [];
-let _lastRateLimitVersion = null;
-let _rateLimitBuckets = new Map();
-
-// CAPTCHA / proof-of-work challenge state. _challengeConfig.secret signs the
-// challenge tokens + clearance cookies (delivered per-app over sync). When a
-// matched request carries no valid clearance the SDK serves an interstitial
-// instead of passing it through.
-let _challengeRules = [];
-let _lastChallengeVersion = null;
-let _challengeConfig = null;
-// Per-IP count of failed/abandoned challenges, for escalation reporting.
-let _challengeFails = new Map();
-
-// Circuit breaker
-const CIRCUIT_OPEN_THRESHOLD = 5;
-const CIRCUIT_OPEN_COOLDOWN_MS = 120_000;
-let _circuitState = 'closed';
-let _circuitOpenedAt = 0;
-
-// In-flight guard and 429 back-off
-let _pollInflight = false;
-let _retryAfterUntil = 0;
-
-// Firewall control-plane traffic is low-frequency and correctness-critical.
-// Use non-keep-alive agents so clustered apps do not reuse sockets that an
-// upstream load balancer has silently closed between sync cycles.
-const _httpAgent = new http.Agent({ keepAlive: false });
-const _httpsAgent = new https.Agent({ keepAlive: false });
-const EVENT_FLUSH_INTERVAL_MS = 2_000;
-const EVENT_BATCH_SIZE = 25;
-const EVENT_QUEUE_MAX = 1_000;
-const TRANSIENT_NETWORK_CODES = new Set(['ECONNRESET', 'ECONNREFUSED', 'EPIPE', 'ETIMEDOUT', 'EAI_AGAIN', 'ENOTFOUND']);
-
-// Unified sync uses /firewall/sync (v2). Falls back to legacy on 404.
-let _useUnifiedSync = true;
-
-function originalConsoleMethod(method) {
-  const originals = console.__securenow_original || console.__securenowOriginalConsole;
-  return (originals && originals[method]) || console[method] || console.log;
-}
-
-function firewallConsole(method, ...args) {
-  if (!_options || !_options.log) return;
-  try {
-    originalConsoleMethod(method).apply(console, args);
-  } catch (_) {}
-}
-
-function fwLog(...args) {
-  firewallConsole('log', ...args);
-}
-
-function fwWarn(...args) {
-  firewallConsole('warn', ...args);
-}
-
-// Circuit Breaker
-
-function maybeOpenCircuit() {
-  if (_circuitState === 'open') return;
-  if (_consecutiveErrors >= CIRCUIT_OPEN_THRESHOLD) {
-    _circuitState = 'open';
-    _circuitOpenedAt = Date.now();
-    if (_options && _options.log) {
-      fwWarn('[securenow] Firewall: circuit breaker OPEN - pausing polling for %ds', CIRCUIT_OPEN_COOLDOWN_MS / 1000);
-    }
-  }
-}
-
-function resetCircuit() {
-  if (_circuitState !== 'closed') {
-    _circuitState = 'closed';
-    if (_options && _options.log) fwLog('[securenow] Firewall: circuit breaker CLOSED - API healthy');
-  }
-  _consecutiveErrors = 0;
-}
-
-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 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) {
-      fwWarn('[securenow] Firewall: API returned 429, backing off for %ds', secs);
-    }
-  }
-}
-
-// HTTP helpers
-
-function buildUrl(apiUrl, path) {
-  return apiUrl.replace(/\/+$/, '') + '/api/v1' + path;
-}
-
-function buildFirewallUrl(path) {
-  const query = new URLSearchParams();
-  if (_options && _options.appKey) query.set('app', _options.appKey);
-  if (_options && _options.environment) query.set('env', _options.environment);
-  const suffix = query.toString() ? `?${query.toString()}` : '';
-  return buildUrl(_options.apiUrl, path) + suffix;
-}
-
-function jitter(baseMs) {
-  return baseMs * (0.8 + Math.random() * 0.4);
-}
-
-function agentFor(url) {
-  return url.startsWith('https') ? _httpsAgent : _httpAgent;
-}
-
-function isTransientNetworkError(err) {
-  if (!err) return false;
-  if (err.code && TRANSIENT_NETWORK_CODES.has(err.code)) return true;
-  return /socket hang up|connection reset|ECONNRESET|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|timed out/i.test(String(err.message || ''));
-}
-
-function isApiReachabilityError(err) {
-  if (isTransientNetworkError(err)) return true;
-  const text = `${err && err.code || ''} ${err && err.message || ''}`;
-  return /TLS|SSL|certificate|CERT_|UNABLE_TO_VERIFY|self signed/i.test(text);
-}
-
-function formatRequestError(err) {
-  if (!err) return 'unknown error';
-  const parts = [err.message || String(err)];
-  if (err.code && !parts[0].includes(err.code)) parts.push(`code=${err.code}`);
-  if (err.syscall) parts.push(`syscall=${err.syscall}`);
-  return parts.join(' ');
-}
-
-function resetApiUrlFallbacks() {
-  const seen = new Set([_options && _options.apiUrl].filter(Boolean));
-  _remainingApiUrlFallbacks = [];
-  for (const candidate of Array.isArray(_options && _options.apiUrlFallbacks) ? _options.apiUrlFallbacks : []) {
-    const url = String(candidate || '').trim().replace(/\/$/, '');
-    if (!url || seen.has(url)) continue;
-    seen.add(url);
-    _remainingApiUrlFallbacks.push(url);
-  }
-}
-
-function switchToNextApiUrl(reason) {
-  if (!_options || _remainingApiUrlFallbacks.length === 0) return false;
-  const previous = _options.apiUrl;
-  _options.apiUrl = _remainingApiUrlFallbacks.shift();
-  _lastUnifiedEtag = null;
-  _lastSyncEtag = null;
-  _lastAllowlistSyncEtag = null;
-  if (_options.log) {
-    fwWarn('[securenow] Firewall: %s unreachable (%s), retrying sync via %s',
-      previous,
-      reason || 'network error',
-      _options.apiUrl);
-  }
-  return true;
-}
-
-function requestOnce(method, url, body, extraHeaders, timeout, callback) {
-  const mod = url.startsWith('https') ? https : http;
-  const parsed = new URL(url);
-  const payload = body == null ? null : JSON.stringify(body || {});
-
-  const req = mod.request({
-    hostname: parsed.hostname,
-    port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
-    path: parsed.pathname + parsed.search,
-    method,
-    headers: {
-      'Authorization': `Bearer ${_options.apiKey}`,
-      'User-Agent': 'securenow-firewall-sdk',
-      'Connection': 'close',
-      ...(payload
-        ? {
-            'Content-Type': 'application/json',
-            'Content-Length': Buffer.byteLength(payload),
-          }
-        : {}),
-      ...extraHeaders,
-    },
-    timeout,
-    agent: agentFor(url),
-  }, (res) => {
-    let data = '';
-    res.on('data', (chunk) => { data += chunk; });
-    res.on('end', () => { done(null, res, data); });
-  });
-
-  let finished = false;
-  function done(...args) {
-    if (finished) return;
-    finished = true;
-    callback(...args);
-  }
-
-  req.on('error', (err) => done(err));
-  req.on('timeout', () => {
-    const err = new Error('Request timed out');
-    err.code = 'ETIMEDOUT';
-    done(err);
-    req.destroy(err);
-  });
-  if (payload) req.write(payload);
-  req.end();
-}
-
-function requestWithRetry(method, url, body, extraHeaders, timeout, callback) {
-  requestOnce(method, url, body, extraHeaders, timeout, (err, res, data) => {
-    if (!err || !isTransientNetworkError(err)) return callback(err, res, data);
-
-    if (_options && _options.log) {
-      fwWarn('[securenow] Firewall: transient API socket error, retrying once:', formatRequestError(err));
-    }
-
-    const retryTimer = setTimeout(() => {
-      requestOnce(method, url, body, extraHeaders, timeout, callback);
-    }, 100);
-    if (retryTimer.unref) retryTimer.unref();
-  });
-}
-
-function httpGet(url, extraHeaders, timeout, callback) {
-  requestWithRetry('GET', url, null, extraHeaders, timeout, callback);
-}
-
-function httpPostJson(url, body, timeout, callback) {
-  requestWithRetry('POST', url, body, {}, timeout, callback);
-}
-
-function scheduleEventFlush() {
-  if (_eventTimer || _eventQueue.length === 0) return;
-  _eventTimer = setTimeout(() => {
-    _eventTimer = null;
-    flushFirewallEvents();
-  }, EVENT_FLUSH_INTERVAL_MS);
-  if (_eventTimer.unref) _eventTimer.unref();
-}
-
-function flushFirewallEvents() {
-  if (!_options || !_options.apiKey || !_options.apiUrl || _eventQueue.length === 0) return;
-  if (shouldSkipRequest()) {
-    _eventQueue = [];
-    return;
-  }
-
-  const batch = _eventQueue.splice(0, EVENT_BATCH_SIZE);
-  const url = buildFirewallUrl('/firewall/events');
-
-  httpPostJson(url, { events: batch }, 5000, (err, res) => {
-    if (err || !res || res.statusCode >= 400) {
-      if (_options.log) {
-        const msg = err ? formatRequestError(err) : `API returned ${res.statusCode}`;
-        fwWarn('[securenow] Firewall: failed to report blocked-request ledger:', msg);
-      }
-    }
-    if (_eventQueue.length) scheduleEventFlush();
-  });
-}
-
-function reportFirewallEvent(event) {
-  if (!_options || !_options.apiKey || !_options.apiUrl) return;
-
-  const item = {
-    applicationKey: _options.appKey || null,
-    environment: _options.environment || 'production',
-    action: 'blocked',
-    statusCode: (_options && _options.statusCode) || 403,
-    occurredAt: new Date().toISOString(),
-    ...event,
-  };
-
-  _eventQueue.push(item);
-  if (_eventQueue.length > EVENT_QUEUE_MAX) {
-    _eventQueue.splice(0, _eventQueue.length - EVENT_QUEUE_MAX);
-  }
-
-  if (_eventQueue.length >= EVENT_BATCH_SIZE) flushFirewallEvents();
-  else scheduleEventFlush();
-}
-
-function normalizePrefixPattern(pattern) {
-  const value = String(pattern || '');
-  return value.endsWith('*') ? value.slice(0, -1) : value;
-}
-
-function normalizeBlocklistRules(rules) {
-  if (!Array.isArray(rules)) return [];
-  return rules
-    .map((rule) => {
-      if (!rule || !rule.ip) return null;
-      const pathMatchMode = ['exact', 'prefix', 'regex'].includes(String(rule.pathMatchMode || '').toLowerCase())
-        ? String(rule.pathMatchMode).toLowerCase()
-        : 'prefix';
-      return {
-        ...rule,
-        ip: String(rule.ip || '').trim(),
-        method: String(rule.method || 'ALL').toUpperCase(),
-        pathPattern: pathMatchMode === 'prefix'
-          ? normalizePrefixPattern(rule.pathPattern)
-          : String(rule.pathPattern || '').trim(),
-        pathMatchMode,
-      };
-    })
-    .filter(Boolean);
-}
-
-function setBlocklistData(ips, rules) {
-  const normalizedIps = Array.isArray(ips) ? ips : [];
-  _rawIps = normalizedIps;
-  _blocklistRules = normalizeBlocklistRules(rules);
-  _matcher = createMatcher(normalizedIps);
-  _stats.syncs++;
-  notifyLayers(normalizedIps);
-}
-
-// Unified Sync (v2 - single request for everything)
-
-function doUnifiedSync(callback) {
-  const query = new URLSearchParams();
-  if (_options.appKey) query.set('app', _options.appKey);
-  if (_options.environment) query.set('env', _options.environment);
-  const suffix = query.toString() ? `?${query.toString()}` : '';
-  const url = buildUrl(_options.apiUrl, '/firewall/sync') + suffix;
-  const headers = {};
-  if (_options.environment) headers['X-SecureNow-Environment'] = _options.environment;
-  if (_lastVersion) headers['X-Blocklist-Version'] = _lastVersion;
-  if (_lastAllowlistVersion) headers['X-Allowlist-Version'] = _lastAllowlistVersion;
-  if (_lastRateLimitVersion) headers['X-Rate-Limit-Version'] = _lastRateLimitVersion;
-  if (_lastChallengeVersion) headers['X-Challenge-Version'] = _lastChallengeVersion;
-  if (_lastUnifiedEtag) headers['If-None-Match'] = _lastUnifiedEtag;
-
-  httpGet(url, headers, 8000, (err, res, data) => {
-    if (err) return callback(err);
-
-    _stats.versionChecks++;
-    if (res.headers && res.headers.etag) _lastUnifiedEtag = res.headers.etag;
-
-    if (res.statusCode === 304) {
-      return callback(null, { blChanged: false, alChanged: false });
-    }
-
-    if (res.statusCode === 404) {
-      _useUnifiedSync = false;
-      if (_options.log) fwLog('[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;
-
-      // Apply remote per-app toggle. Absent body.app means the backend either
-      // doesn't know about appKey-scoped sync (older API) or no appKey was
-      // sent - leave the previous value untouched (default true on first run).
-      if (body.app && typeof body.app.firewallEnabled === 'boolean') {
-        const next = body.app.firewallEnabled;
-        if (next !== _lastRemoteEnabled) {
-          _remoteEnabled = next;
-          if (_options.log) {
-            fwLog('[securenow] Firewall: remote toggle -> %s (app=%s)',
-              next ? 'ENABLED' : 'DISABLED', body.app.key || _options.appKey);
-          }
-          _lastRemoteEnabled = next;
-        }
-      }
-
-      // Update blocklist version + data
-      if (body.blocklist) {
-        const newVer = body.blocklist.version;
-        if (newVer !== _lastVersion) {
-          _lastVersion = newVer;
-        }
-      }
-
-      if (body.blocklistIps || body.blocklistRules) {
-        setBlocklistData(body.blocklistIps || [], body.blocklistRules || []);
-        blChanged = true;
-      }
-
-      // Update allowlist version + data
-      if (body.allowlist) {
-        const newVer = body.allowlist.version;
-        if (newVer !== _lastAllowlistVersion) {
-          _lastAllowlistVersion = newVer;
-        }
-      }
-
-      if (body.allowlistIps) {
-        _allowlistRawIps = body.allowlistIps;
-        _allowlistMatcher = createMatcher(body.allowlistIps);
-        alChanged = true;
-      }
-
-      if (body.rateLimits) {
-        const newVer = body.rateLimits.version;
-        if (newVer !== _lastRateLimitVersion) {
-          _lastRateLimitVersion = newVer;
-        }
-      }
-
-      if (Array.isArray(body.rateLimitRules)) {
-        _rateLimitRules = body.rateLimitRules;
-        pruneRateLimitBuckets(_rateLimitRules);
-      }
-
-      // Per-app challenge config (secret + defaults) rides on the app block.
-      if (body.app && body.app.challenge && typeof body.app.challenge === 'object') {
-        _challengeConfig = body.app.challenge;
-      }
-
-      if (body.challenges) {
-        const newVer = body.challenges.version;
-        if (newVer !== _lastChallengeVersion) {
-          _lastChallengeVersion = newVer;
-        }
-      }
-
-      if (Array.isArray(body.challengeRules)) {
-        _challengeRules = body.challengeRules;
-      }
-
-      callback(null, { blChanged, alChanged, rlChanged: Array.isArray(body.rateLimitRules) });
-    } catch (e) {
-      callback(new Error(`Failed to parse sync response: ${e.message}`));
-    }
-  });
-}
-
-// Legacy Sync (v1 - separate endpoints, kept for backward compat)
-
-function legacyBlocklistSync(callback) {
-  const url = buildFirewallUrl('/firewall/blocklist');
-  const headers = {};
-  if (_options.environment) headers['X-SecureNow-Environment'] = _options.environment;
-  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 || [];
-      setBlocklistData(ips, body.rules || body.blocklistRules || []);
-      _lastModified = res.headers['last-modified'] || null;
-      if (res.headers['etag']) _lastSyncEtag = res.headers['etag'];
-      callback(null, true, _matcher.stats());
-    } catch (e) {
-      callback(new Error(`Failed to parse blocklist: ${e.message}`));
-    }
-  });
-}
-
-function legacyAllowlistSync(callback) {
-  const url = buildFirewallUrl('/firewall/allowlist');
-  const headers = {};
-  if (_options.environment) headers['X-SecureNow-Environment'] = _options.environment;
-  if (_lastAllowlistSyncEtag) headers['If-None-Match'] = _lastAllowlistSyncEtag;
-  else if (_lastAllowlistModified) headers['If-Modified-Since'] = _lastAllowlistModified;
-
-  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 legacyVersionCheck(callback) {
-  const url = buildFirewallUrl('/firewall/blocklist/version');
-  const headers = {};
-  if (_options.environment) headers['X-SecureNow-Environment'] = _options.environment;
-  if (_lastVersion) headers['If-None-Match'] = _lastVersion;
-
-  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}`));
-
-    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 = buildFirewallUrl('/firewall/allowlist/version');
-  const headers = {};
-  if (_options.environment) headers['X-SecureNow-Environment'] = _options.environment;
-  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 });
-    }
-
-    if (blChanged) {
-      legacyBlocklistSync((err, changed, stats) => {
-        if (err && _options.log) fwWarn('[securenow] Firewall: sync failed (using stale list):', formatRequestError(err));
-        else if (changed && stats && _options.log) fwLog('[securenow] Firewall: re-synced %d blocked IPs', stats.total);
-        syncDone();
-      });
-    }
-    if (alChanged) {
-      legacyAllowlistSync((err, changed, stats) => {
-        if (err && _options.log) fwWarn('[securenow] Firewall: allowlist sync failed:', formatRequestError(err));
-        else if (changed && stats && _options.log) fwLog('[securenow] Firewall: re-synced %d allowed IPs', stats.total);
-        syncDone();
-      });
-    }
-  }
-
-  legacyVersionCheck((err, changed) => {
-    if (err) firstError = firstError || err;
-    blChanged = changed;
-    checkDone();
-  });
-
-  legacyAllowlistVersionCheck((err, changed) => {
-    if (err) firstError = firstError || err;
-    alChanged = changed;
-    checkDone();
-  });
-}
-
-// 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 (isApiReachabilityError(err) && switchToNextApiUrl(formatRequestError(err))) {
-        _pollInflight = false;
-        const retryTimer = setTimeout(() => pollOnce(callback), 1000);
-        if (retryTimer.unref) retryTimer.unref();
-        return;
-      }
-      _consecutiveErrors++;
-      _stats.errors++;
-      maybeOpenCircuit();
-      if (_options.log) fwWarn('[securenow] Firewall: poll failed:', formatRequestError(err));
-      return callback(err);
-    }
-    _consecutiveErrors = 0;
-    resetCircuit();
-    if (result) {
-      if (result.blChanged && _options.log && _matcher) {
-        const s = _matcher.stats();
-        fwLog('[securenow] Firewall: re-synced %d global blocked IPs (%d exact + %d CIDR ranges) and %d scoped block rules',
-          s.total, s.exact, s.cidr, _blocklistRules.length);
-      }
-      if (result.alChanged && _options.log && _allowlistMatcher) {
-        const s = _allowlistMatcher.stats();
-        fwLog('[securenow] Firewall: re-synced %d allowed IPs (%d exact + %d CIDR ranges)', s.total, s.exact, s.cidr);
-      }
-      if (result.rlChanged && _options.log) {
-        fwLog('[securenow] Firewall: re-synced %d rate-limit rules', _rateLimitRules.length);
-      }
-    }
-    callback(null);
-  };
-
-  if (_useUnifiedSync) {
-    doUnifiedSync((err, result) => {
-      if (err) return done(err);
-      if (result && result.useLegacy) {
-        doLegacyPoll(done);
-      } else {
-        done(null, result);
-      }
-    });
-  } else {
-    doLegacyPoll(done);
-  }
-}
-
-function scheduleNextPoll() {
-  const baseMs = (_options.versionCheckInterval || 10) * 1000;
-  const backoffMs = Math.min(baseMs * Math.pow(2, _consecutiveErrors), 120_000);
-  const delayMs = jitter(backoffMs);
-
-  _pollTimer = setTimeout(() => {
-    pollOnce(() => { scheduleNextPoll(); });
-  }, delayMs);
-  if (_pollTimer.unref) _pollTimer.unref();
-}
-
-function startSyncLoop() {
-  const fullSyncIntervalMs = (_options.syncInterval || 300) * 1000;
-  const BASE_RETRY = 5000;
-  const MAX_RETRY = 120_000;
-  let _initAttempt = 0;
-
-  function initialSync() {
-    // 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 (isApiReachabilityError(err) && switchToNextApiUrl(formatRequestError(err))) {
-          const retryTimer = setTimeout(initialSync, 1000);
-          if (retryTimer.unref) retryTimer.unref();
-          return;
-        }
-        if (isConnErr && !_localhostFallbackTried && _options.apiUrl !== 'http://localhost:4000') {
-          _localhostFallbackTried = true;
-          const origUrl = _options.apiUrl;
-          _options.apiUrl = 'http://localhost:4000';
-          if (_options.log) fwLog('[securenow] Firewall: %s unreachable, trying http://localhost:4000', origUrl);
-          const retryTimer = setTimeout(initialSync, 1000);
-          if (retryTimer.unref) retryTimer.unref();
-          return;
-        }
-        if (result && result.useLegacy) {
-          const retryTimer = setTimeout(initialSync, 1000);
-          if (retryTimer.unref) retryTimer.unref();
-          return;
-        }
-        if (_options.log) fwWarn('[securenow] Firewall: initial sync failed:', formatRequestError(err));
-        if (_options.failMode === 'closed') {
-          _matcher = { isBlocked: () => true, stats: () => ({ exact: 0, cidr: 0, total: 0 }) };
-        }
-        _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 (result && result.useLegacy) {
-        const retryTimer = setTimeout(initialSync, 1000);
-        if (retryTimer.unref) retryTimer.unref();
-        return;
-      }
-
-      _initialized = true;
-      if (_options.log && _matcher) {
-        const s = _matcher.stats();
-        fwLog('[securenow] Firewall: synced %d global blocked IPs (%d exact + %d CIDR ranges) and %d scoped block rules',
-          s.total, s.exact, s.cidr, _blocklistRules.length);
-      }
-      if (_options.log && _allowlistMatcher) {
-        const s = _allowlistMatcher.stats();
-        if (s.total > 0) fwLog('[securenow] Firewall: synced %d allowed IPs (%d exact + %d CIDR ranges)', s.total, s.exact, s.cidr);
-      }
-      if (_options.log && _rateLimitRules.length > 0) {
-        fwLog('[securenow] Firewall: synced %d rate-limit rules', _rateLimitRules.length);
-      }
-    });
-  }
-
-  initialSync();
-  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;
-    const savedRlVer = _lastRateLimitVersion;
-    const savedUnifiedEtag = _lastUnifiedEtag;
-    _lastVersion = null;
-    _lastAllowlistVersion = null;
-    _lastRateLimitVersion = null;
-    _lastUnifiedEtag = null;
-    pollOnce((err) => {
-      if (err) {
-        _lastVersion = savedBlVer;
-        _lastAllowlistVersion = savedAlVer;
-        _lastRateLimitVersion = savedRlVer;
-        _lastUnifiedEtag = savedUnifiedEtag;
-      }
-    });
-  }, fullSyncIntervalMs);
-  if (_syncTimer.unref) _syncTimer.unref();
-}
-
-// Layer 1: HTTP Handler
-
-const _origHttpCreate = http.createServer;
-const _origHttpsCreate = https.createServer;
-let _httpPatched = false;
-
-function blockedHtml(ip) {
-  const maskedIp = ip || 'unknown';
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
-<title>Access Blocked - Security Alert</title>
-<style>
-*{margin:0;padding:0;box-sizing:border-box}
-body{min-height:100vh;display:flex;align-items:center;justify-content:center;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;background:#0a0a0a;color:#e5e5e5}
-.wrap{text-align:center;max-width:540px;padding:2.5rem 2rem}
-.icon{width:64px;height:64px;margin:0 auto 1.5rem;border-radius:50%;background:rgba(220,38,38,.12);display:flex;align-items:center;justify-content:center}
-.icon svg{width:32px;height:32px;fill:none;stroke:#dc2626;stroke-width:2;stroke-linecap:round;stroke-linejoin:round}
-.badge{display:inline-block;padding:.25rem .75rem;border-radius:999px;background:rgba(220,38,38,.15);color:#f87171;font-size:.7rem;font-weight:700;letter-spacing:.08em;text-transform:uppercase;margin-bottom:1.25rem}
-h1{font-size:1.6rem;font-weight:700;margin-bottom:.6rem;color:#fff}
-.sub{font-size:1rem;color:#f87171;font-weight:600;margin-bottom:1.25rem}
-p{font-size:.9rem;line-height:1.7;color:#a1a1aa;margin-bottom:.5rem}
-.ip-box{display:inline-block;margin:1rem 0;padding:.6rem 1.5rem;border-radius:8px;background:rgba(255,255,255,.04);border:1px solid rgba(220,38,38,.25);font-family:"SF Mono",SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:.95rem;color:#fca5a5;letter-spacing:.03em}
-.divider{width:48px;height:2px;background:rgba(220,38,38,.3);margin:1.5rem auto}
-.contact{font-size:.85rem;color:#71717a;line-height:1.7}
-.contact a{color:#f87171;text-decoration:none;font-weight:500}
-.contact a:hover{text-decoration:underline}
-.footer{margin-top:2rem;font-size:.7rem;color:#3f3f46}
-.powered{margin-top:1.5rem;font-size:.75rem;color:#52525b}.powered a{color:#a1a1aa;text-decoration:none;font-weight:600;transition:color .2s}.powered a:hover{color:#f87171;text-decoration:underline}
-</style>
-</head>
-<body>
-<div class="wrap">
-<div class="icon"><svg viewBox="0 0 24 24"><path d="M12 9v4m0 4h.01M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z"/></svg></div>
-<span class="badge">Security Alert</span>
-<h1>Access Blocked</h1>
-<p class="sub">Malicious activity detected from your IP address</p>
-<p>Your IP has been flagged and blocked due to suspicious or malicious behavior originating from your network. Our security team has been notified and is actively investigating.</p>
-<div class="ip-box">${maskedIp}</div>
-<div class="divider"></div>
-<p class="contact">If you believe this is a mistake, please contact us at<br><a href="mailto:contact@securenow.ai?subject=Blocked%20IP%20Appeal%20-%20${encodeURIComponent(maskedIp)}&body=IP:%20${encodeURIComponent(maskedIp)}%0ATimestamp:%20${encodeURIComponent(new Date().toISOString())}%0A%0APlease%20describe%20why%20you%20believe%20this%20block%20is%20incorrect:">contact@securenow.ai</a><br>Include your IP address and the time of this incident.</p>
-<p class="footer">Ref: ${maskedIp} &mdash; ${new Date().toISOString()} &mdash; HTTP 403</p>
-<p class="powered">Protected by <a href="https://securenow.ai" rel="dofollow" target="_blank">SecureNow</a></p>
-</div>
-</body>
-</html>`;
-}
-
-function wrapListener(originalListener) {
-  return function firewallGuard(req, res) {
-    _stats.allowed++;
-    return originalListener.call(this, req, res);
-  };
-}
-
-function sendBlockResponse(req, res, ip) {
-  const code = (_options && _options.statusCode) || 403;
-  const accept = req.headers['accept'] || '';
-  if (accept.includes('text/html')) {
-    res.writeHead(code, { 'Content-Type': 'text/html; charset=utf-8' });
-    res.end(blockedHtml(ip));
-  } else {
-    res.writeHead(code, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ error: 'Forbidden', ip }));
-  }
-}
-
-function sendRateLimitResponse(req, res, ip, decision) {
-  const retryAfter = Math.max(1, decision.retryAfter || 1);
-  const headers = {
-    'Retry-After': String(retryAfter),
-    'X-RateLimit-Limit': String(decision.limit || ''),
-    'X-RateLimit-Window': String(decision.windowSeconds || ''),
-    'X-SecureNow-Rate-Limit-Rule': decision.ruleId || '',
-  };
-  const accept = req.headers['accept'] || '';
-  if (accept.includes('text/html')) {
-    res.writeHead(429, { ...headers, 'Content-Type': 'text/html; charset=utf-8' });
-    res.end('<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>Too Many Requests</title></head><body><h1>Too Many Requests</h1><p>Please retry later.</p></body></html>');
-  } else {
-    res.writeHead(429, { ...headers, 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({
-      error: 'Too Many Requests',
-      ip,
-      retryAfter,
-    }));
-  }
-}
-
-function requestPath(req) {
-  try {
-    return new URL(req.url || '/', 'http://localhost').pathname || '/';
-  } catch (_) {
-    return req.url || '/';
-  }
-}
-
-function ruleIpMatches(rule, ip) {
-  const target = String(rule.ip || '').trim();
-  if (!target) return true;
-  try {
-    return createMatcher([target]).isBlocked(ip);
-  } catch (_) {
-    return false;
-  }
-}
-
-function rulePathMatches(rule, path) {
-  const pattern = String(rule.pathPattern || '').trim();
-  if (!pattern) return true;
-  const mode = rule.pathMatchMode || 'prefix';
-  if (mode === 'exact') return path === pattern;
-  if (mode === 'regex') {
-    try { return new RegExp(pattern).test(path); } catch (_) { return false; }
-  }
-  return path.startsWith(normalizePrefixPattern(pattern));
-}
-
-function rateLimitKey(rule, ip) {
-  const id = rule.id || rule._id || `${rule.ip || '*'}:${rule.method || 'ALL'}:${rule.pathPattern || '*'}`;
-  const subject = rule.keyBy === 'global' ? 'global' : ip;
-  return `${id}|${subject}`;
-}
-
-function checkBlocklistRules(req, ip) {
-  if (!_blocklistRules || _blocklistRules.length === 0) return null;
-  const method = String(req.method || 'GET').toUpperCase();
-  const path = requestPath(req);
-
-  for (const rule of _blocklistRules) {
-    if (!rule) continue;
-    const ruleMethod = String(rule.method || 'ALL').toUpperCase();
-    if (ruleMethod !== 'ALL' && ruleMethod !== method) continue;
-    if (!ruleIpMatches(rule, ip)) continue;
-    if (!rulePathMatches(rule, path)) continue;
-    return {
-      rule,
-      ruleId: rule.id || rule._id || '',
-      matchedEntry: rule.ip || ip,
-      path,
-    };
-  }
-
-  return null;
-}
-
-function checkRateLimitRules(req, ip) {
-  if (!_rateLimitRules || _rateLimitRules.length === 0) return null;
-  const method = String(req.method || 'GET').toUpperCase();
-  const path = requestPath(req);
-  const now = Date.now();
-
-  for (const rule of _rateLimitRules) {
-    if (!rule) continue;
-    const ruleMethod = String(rule.method || 'ALL').toUpperCase();
-    if (ruleMethod !== 'ALL' && ruleMethod !== method) continue;
-    if (!ruleIpMatches(rule, ip)) continue;
-    if (!rulePathMatches(rule, path)) continue;
-
-    const limit = Math.max(1, Number(rule.limit || 1) || 1);
-    const windowSeconds = Math.max(1, Number(rule.windowSeconds || 60) || 60);
-    const windowMs = windowSeconds * 1000;
-    const key = rateLimitKey(rule, ip);
-    let bucket = _rateLimitBuckets.get(key);
-    if (!bucket || now - bucket.windowStart >= windowMs) {
-      bucket = { windowStart: now, count: 0 };
-      _rateLimitBuckets.set(key, bucket);
-    }
-
-    if (bucket.count >= limit) {
-      const retryAfter = Math.ceil((bucket.windowStart + windowMs - now) / 1000);
-      return {
-        rule,
-        ruleId: rule.id || rule._id || '',
-        limit,
-        windowSeconds,
-        retryAfter,
-        path,
-      };
-    }
-    bucket.count++;
-  }
-
-  return null;
-}
-
-function pruneRateLimitBuckets(rules) {
-  const ids = new Set((rules || []).map((rule) => String(rule.id || rule._id || `${rule.ip || '*'}:${rule.method || 'ALL'}:${rule.pathPattern || '*'}`)));
-  for (const key of _rateLimitBuckets.keys()) {
-    const idx = key.indexOf('|');
-    const ruleKey = idx === -1 ? key : key.slice(0, idx);
-    if (!ids.has(ruleKey)) _rateLimitBuckets.delete(key);
-  }
-}
-
-// ── Challenge (CAPTCHA / proof-of-work) enforcement ──
-
-const CHALLENGE_INTERNAL_PATH = '/__securenow/challenge';
-
-function isSecureRequest(req) {
-  if (req.socket && req.socket.encrypted) return true;
-  const xfp = String(req.headers['x-forwarded-proto'] || '').split(',')[0].trim().toLowerCase();
-  return xfp === 'https';
-}
-
-function challengeDifficulty(rule) {
-  const d = Number(rule && rule.difficulty);
-  if (Number.isFinite(d) && d >= 4 && d <= 28) return d;
-  const cfg = Number(_challengeConfig && _challengeConfig.difficulty);
-  if (Number.isFinite(cfg) && cfg >= 4) return cfg;
-  return challenge.DEFAULTS.difficulty;
-}
-
-function findChallengeRuleById(rid) {
-  if (!rid || rid === '*') return null;
-  for (const rule of _challengeRules) {
-    if (String(rule.id || rule._id || '') === String(rid)) return rule;
-  }
-  return null;
-}
-
-function challengeClearanceTtl(rule) {
-  const t = Number(rule && rule.clearanceTtlSeconds);
-  if (Number.isFinite(t) && t >= 30) return t;
-  const cfg = Number(_challengeConfig && _challengeConfig.clearanceTtl);
-  if (Number.isFinite(cfg) && cfg >= 30) return cfg;
-  return challenge.DEFAULTS.clearanceTtl;
-}
-
-function checkChallengeRules(req, ip) {
-  if (!_challengeRules || _challengeRules.length === 0) return null;
-  if (!_challengeConfig || !_challengeConfig.secret) return null;
-  const method = String(req.method || 'GET').toUpperCase();
-  const path = requestPath(req);
-  for (const rule of _challengeRules) {
-    if (!rule) continue;
-    const ruleMethod = String(rule.method || 'ALL').toUpperCase();
-    if (ruleMethod !== 'ALL' && ruleMethod !== method) continue;
-    if (!ruleIpMatches(rule, ip)) continue;
-    if (!rulePathMatches(rule, path)) continue;
-    return { rule, ruleId: rule.id || rule._id || '', path };
-  }
-  return null;
-}
-
-function hasValidClearance(req, ip) {
-  const secret = _challengeConfig && _challengeConfig.secret;
-  if (!secret) return false;
-  const cookie = challenge.readClearanceCookie(req);
-  if (!cookie) return false;
-  const ua = req.headers['user-agent'] || '';
-  return challenge.verifyClearance(secret, { cookie, ip, ua }).ok;
-}
-
-function buildClearanceCookie(value, maxAge, secure) {
-  let cookie = `${challenge.CLEARANCE_COOKIE}=${value}; Max-Age=${maxAge}; Path=/; HttpOnly; SameSite=Lax`;
-  if (secure) cookie += '; Secure';
-  return cookie;
-}
-
-function readJsonBody(req, maxBytes, cb) {
-  let size = 0;
-  const chunks = [];
-  let done = false;
-  const finish = (err, val) => { if (done) return; done = true; cb(err, val); };
-  req.on('data', (chunk) => {
-    size += chunk.length;
-    if (size > maxBytes) {
-      finish(new Error('too_large'));
-      try { req.destroy(); } catch (_) {}
-      return;
-    }
-    chunks.push(chunk);
-  });
-  req.on('end', () => {
-    if (done) return;
-    try { finish(null, JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}')); }
-    catch (e) { finish(e); }
-  });
-  req.on('error', (e) => finish(e));
-}
-
-function noteChallengeFail(ip) {
-  if (_challengeFails.size > 50_000) _challengeFails.clear();
-  const n = (_challengeFails.get(ip) || 0) + 1;
-  _challengeFails.set(ip, n);
-  return n;
-}
-
-// Serve the proof-of-work interstitial (or a JSON challenge for API clients).
-function sendChallengeResponse(req, res, ip, decision) {
-  const secret = _challengeConfig.secret;
-  const rule = decision.rule || {};
-  const difficulty = challengeDifficulty(rule);
-  const rid = decision.ruleId || '*';
-  const challengeTtl = Number(_challengeConfig.challengeTtl) || challenge.DEFAULTS.challengeTtl;
-  const token = challenge.signChallenge(secret, { ip, difficulty, rid, challengeTtl });
-  const baseHeaders = { 'X-SecureNow-Challenge': 'required', 'Cache-Control': 'no-store' };
-
-  reportFirewallEvent({
-    action: 'captcha_challenged',
-    source: 'challenge',
-    statusCode: 403,
-    ip,
-    matchedEntry: rid,
-    method: req.method || '',
-    path: decision.path || req.url || '',
-    userAgent: req.headers['user-agent'] || '',
-  });
-
-  const accept = req.headers['accept'] || '';
-  if (accept.includes('text/html')) {
-    res.writeHead(403, { ...baseHeaders, 'Content-Type': 'text/html; charset=utf-8' });
-    res.end(challenge.challengeHtml({
-      token,
-      difficulty,
-      submitPath: CHALLENGE_INTERNAL_PATH,
-      returnPath: req.url || '/',
-      ip,
-    }));
-  } else {
-    res.writeHead(403, { ...baseHeaders, 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({
-      error: 'challenge_required',
-      challenge: { token, alg: challenge.ALG_POW, difficulty, submit: CHALLENGE_INTERNAL_PATH },
-    }));
-  }
-}
-
-// Handle the internal solve endpoint (POST /__securenow/challenge). Verifies
-// the proof-of-work — locally with the per-app secret, or by proxying to the
-// API — then issues a clearance cookie on success.
-function handleChallengeInternal(req, res, ip) {
-  if (String(req.method || '').toUpperCase() !== 'POST') {
-    res.writeHead(405, { 'Content-Type': 'application/json', Allow: 'POST' });
-    res.end(JSON.stringify({ ok: false, reason: 'method_not_allowed' }));
-    return true;
-  }
-
-  const secret = _challengeConfig && _challengeConfig.secret;
-  const verifyMode = (_challengeConfig && _challengeConfig.verify) || 'auto';
-
-  readJsonBody(req, 8192, (err, body) => {
-    if (err || !body || !body.token) {
-      res.writeHead(400, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ ok: false, reason: 'bad_request' }));
-      return;
-    }
-    const ua = req.headers['user-agent'] || '';
-    const rid = body.rid || '*';
-    const clearanceTtl = challengeClearanceTtl(findChallengeRuleById(rid));
-    const useProxy = verifyMode === 'proxy' || !secret;
-
-    const onPass = (value, maxAge) => {
-      _challengeFails.delete(ip);
-      res.setHeader('Set-Cookie', buildClearanceCookie(value, maxAge || clearanceTtl, isSecureRequest(req)));
-      res.writeHead(204);
-      res.end();
-      reportFirewallEvent({
-        action: 'captcha_passed', source: 'challenge', statusCode: 204,
-        ip, matchedEntry: rid, method: 'POST', path: CHALLENGE_INTERNAL_PATH, userAgent: ua,
-      });
-    };
-    const onFail = (reason) => {
-      const n = noteChallengeFail(ip);
-      res.writeHead(400, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ ok: false, reason: reason || 'verification_failed' }));
-      reportFirewallEvent({
-        action: 'captcha_failed', source: 'challenge', statusCode: 400,
-        ip, matchedEntry: String(n), method: 'POST', path: CHALLENGE_INTERNAL_PATH, userAgent: ua,
-      });
-    };
-
-    if (useProxy) {
-      const url = buildFirewallUrl('/firewall/verify-challenge');
-      httpPostJson(url, { token: body.token, nonce: body.nonce, ip, ua, rid, clearanceTtl }, 8000, (e, r, data) => {
-        if (e || !r || r.statusCode !== 200) return onFail('proxy_unreachable');
-        let parsed;
-        try { parsed = JSON.parse(data); } catch (_) { return onFail('proxy_bad_response'); }
-        if (!parsed || !parsed.ok || !parsed.clearance) return onFail(parsed && parsed.reason);
-        onPass(parsed.clearance.value, parsed.clearance.maxAge);
-      });
-    } else {
-      const result = challenge.verifyChallengeSolution(secret, { token: body.token, nonce: body.nonce, ip });
-      if (!result.ok) return onFail(result.reason);
-      const cl = challenge.issueClearance(secret, { ip, ua, rid, clearanceTtl });
-      onPass(cl.value, cl.maxAge);
-    }
-  });
-  return true;
-}
-
-function firewallRequestHandler(req, res) {
-  // Remote disable wins over everything: when the dashboard / CLI flips the
-  // toggle off, requests pass through the SDK as if the firewall weren't
-  // installed. The poll loop keeps running so we re-enable within seconds.
-  if (_remoteEnabled === false) {
-    _stats.suppressedDisabled++;
-    return false;
-  }
-
-  const ip = resolveClientIp(req);
-
-  // SecureNow-internal challenge solve endpoint. Handled before any IP rule
-  // check so a challenged visitor can always submit their proof-of-work.
-  if (requestPath(req) === CHALLENGE_INTERNAL_PATH) {
-    return handleChallengeInternal(req, res, ip);
-  }
-
-  // Allowlist check: if active, only listed IPs are allowed through
-  if (_allowlistMatcher && _allowlistMatcher.stats().total > 0) {
-    if (!_allowlistMatcher.isBlocked(ip)) {
-      _stats.blocked++;
-      if (_options && _options.log) fwLog('[securenow] Firewall: blocked %s via HTTP (not in allowlist)', ip);
-      reportFirewallEvent({
-        source: 'allowlist',
-        ip,
-        matchedEntry: '',
-        method: req.method || '',
-        path: req.url || '',
-        userAgent: req.headers['user-agent'] || '',
-      });
-      sendBlockResponse(req, res, ip);
-      return true;
-    }
-    return false;
-  }
-
-  // Blocklist check
-  if (_matcher && _matcher.isBlocked(ip)) {
-    _stats.blocked++;
-    if (_options && _options.log) fwLog('[securenow] Firewall: blocked %s via HTTP', ip);
-    reportFirewallEvent({
-      source: 'blocklist',
-      ip,
-      matchedEntry: ip,
-      method: req.method || '',
-      path: req.url || '',
-      userAgent: req.headers['user-agent'] || '',
-    });
-    sendBlockResponse(req, res, ip);
-    return true;
-  }
-
-  const blockRuleDecision = checkBlocklistRules(req, ip);
-  if (blockRuleDecision) {
-    _stats.blocked++;
-    if (_options && _options.log) {
-      fwLog('[securenow] Firewall: blocked %s via HTTP (rule=%s)', ip, blockRuleDecision.ruleId || 'scoped');
-    }
-    reportFirewallEvent({
-      source: 'blocklist',
-      ip,
-      matchedEntry: blockRuleDecision.matchedEntry || ip,
-      method: req.method || '',
-      path: blockRuleDecision.path || req.url || '',
-      userAgent: req.headers['user-agent'] || '',
-    });
-    sendBlockResponse(req, res, ip);
-    return true;
-  }
-
-  // Challenge check sits between hard-block and rate-limit: a matched-but-
-  // uncleared visitor gets the interstitial (and does not consume a rate-limit
-  // bucket); once they hold a valid clearance they fall through to rate-limit.
-  const challengeDecision = checkChallengeRules(req, ip);
-  if (challengeDecision && !hasValidClearance(req, ip)) {
-    _stats.challenged = (_stats.challenged || 0) + 1;
-    if (_options && _options.log) {
-      fwLog('[securenow] Firewall: challenged %s via HTTP (rule=%s)', ip, challengeDecision.ruleId || 'scoped');
-    }
-    sendChallengeResponse(req, res, ip, challengeDecision);
-    return true;
-  }
-
-  const rateLimitDecision = checkRateLimitRules(req, ip);
-  if (rateLimitDecision) {
-    _stats.rateLimited++;
-    if (_options && _options.log) {
-      fwLog('[securenow] Firewall: rate-limited %s via HTTP (rule=%s)', ip, rateLimitDecision.ruleId || 'unknown');
-    }
-    reportFirewallEvent({
-      action: 'rate_limited',
-      source: 'rate_limit',
-      statusCode: 429,
-      ip,
-      matchedEntry: rateLimitDecision.ruleId || '',
-      method: req.method || '',
-      path: rateLimitDecision.path || req.url || '',
-      userAgent: req.headers['user-agent'] || '',
-    });
-    sendRateLimitResponse(req, res, ip, rateLimitDecision);
-    return true;
-  }
-
-  return false;
-}
-
-const _origEmit = http.Server.prototype.emit;
-let _emitPatched = false;
-
-function patchEmitLayer() {
-  if (_emitPatched) return;
-  _emitPatched = true;
-
-  http.Server.prototype.emit = function(event, req, res, ...rest) {
-    if (event === 'request' && req && res && !res.headersSent) {
-      if (firewallRequestHandler(req, res)) return true;
-    }
-    return _origEmit.call(this, event, req, res, ...rest);
-  };
-}
-
-function patchHttpLayer() {
-  if (_httpPatched) return;
-  _httpPatched = true;
-
-  patchEmitLayer();
-
-  http.createServer = function(...args) {
-    if (typeof args[args.length - 1] === 'function') {
-      args[args.length - 1] = wrapListener(args[args.length - 1]);
-    }
-    return _origHttpCreate.apply(this, args);
-  };
-  Object.assign(http.createServer, _origHttpCreate);
-
-  https.createServer = function(...args) {
-    if (typeof args[args.length - 1] === 'function') {
-      args[args.length - 1] = wrapListener(args[args.length - 1]);
-    }
-    return _origHttpsCreate.apply(this, args);
-  };
-  Object.assign(https.createServer, _origHttpsCreate);
-}
-
-// Init
-
-function init(options) {
-  _options = options || {};
-  _options.apiUrl = String(_options.apiUrl || '').trim().replace(/\/$/, '');
-  _localhostFallbackTried = false;
-  _useUnifiedSync = true;
-  resetApiUrlFallbacks();
-
-  if (_options.log) fwLog('[securenow] Firewall: ENABLED');
-  if (_options.log && _options.apiUrl) fwLog('[securenow] Firewall: sync endpoint=%s/api/v1/firewall/sync', _options.apiUrl);
-  if (_options.log && _options.environment) fwLog('[securenow] Firewall: environment=%s', _options.environment);
-
-  patchHttpLayer();
-  if (_options.log) fwLog('[securenow] Firewall: Layer 1 (HTTP 403)      active');
-
-  if (_options.tcp) {
-    try {
-      const tcpLayer = require('./firewall-tcp');
-      tcpLayer.init(() => _matcher, _options, () => _allowlistMatcher);
-      _layers.push(tcpLayer);
-      if (_options.log) fwLog('[securenow] Firewall: Layer 2 (TCP drop)       active');
-    } catch (e) {
-      if (_options.log) fwWarn('[securenow] Firewall: Layer 2 (TCP drop)       failed:', e.message);
-    }
-  } else {
-    if (_options.log) fwLog('[securenow] Firewall: Layer 2 (TCP drop)       disabled (set config.firewall.tcp=true)');
-  }
-
-  if (_options.iptables) {
-    try {
-      const iptablesLayer = require('./firewall-iptables');
-      iptablesLayer.init(_options);
-      _layers.push(iptablesLayer);
-      if (_options.log) fwLog('[securenow] Firewall: Layer 3 (iptables)       active');
-    } catch (e) {
-      if (_options.log) fwWarn('[securenow] Firewall: Layer 3 (iptables)       failed:', e.message);
-    }
-  } else {
-    if (_options.log) fwLog('[securenow] Firewall: Layer 3 (iptables)       disabled (set config.firewall.iptables=true)');
-  }
-
-  if (_options.cloud) {
-    try {
-      const cloudLayer = require('./firewall-cloud');
-      cloudLayer.init(_options);
-      _layers.push(cloudLayer);
-      if (_options.log) fwLog('[securenow] Firewall: Layer 4 (Cloud WAF)      active (%s)', _options.cloud);
-    } catch (e) {
-      if (_options.log) fwWarn('[securenow] Firewall: Layer 4 (Cloud WAF)      failed:', e.message);
-    }
-  } else {
-    if (_options.log) fwLog('[securenow] Firewall: Layer 4 (Cloud WAF)      disabled (set config.firewall.cloud=cloudflare|aws|gcp)');
-  }
-
-  startSyncLoop();
-}
-
-function shutdown() {
-  if (_pollTimer) { clearTimeout(_pollTimer); _pollTimer = null; }
-  if (_syncTimer) { clearInterval(_syncTimer); _syncTimer = null; }
-  if (_eventTimer) { clearTimeout(_eventTimer); _eventTimer = null; }
-  flushFirewallEvents();
-
-  _circuitState = 'closed';
-  _circuitOpenedAt = 0;
-  _consecutiveErrors = 0;
-  _pollInflight = false;
-  _retryAfterUntil = 0;
-  _localhostFallbackTried = false;
-  _blocklistRules = [];
-  _rateLimitRules = [];
-  _rateLimitBuckets = new Map();
-  _challengeRules = [];
-  _challengeConfig = null;
-  _lastChallengeVersion = null;
-  _challengeFails = new Map();
-  _remainingApiUrlFallbacks = [];
-
-  _httpAgent.destroy();
-  _httpsAgent.destroy();
-
-  for (const layer of _layers) {
-    try { if (typeof layer.shutdown === 'function') layer.shutdown(); } catch (_) {}
-  }
-  _layers = [];
-
-  if (_emitPatched) {
-    http.Server.prototype.emit = _origEmit;
-    _emitPatched = false;
-  }
-  if (_httpPatched) {
-    http.createServer = _origHttpCreate;
-    https.createServer = _origHttpsCreate;
-    _httpPatched = false;
-  }
-}
-
-function getStats() {
-  return {
-    ..._stats,
-    matcher: _matcher ? _matcher.stats() : null,
-    blocklistRules: _blocklistRules.length,
-    allowlistMatcher: _allowlistMatcher ? _allowlistMatcher.stats() : null,
-    rateLimitRules: _rateLimitRules.length,
-    rateLimitBuckets: _rateLimitBuckets.size,
-    initialized: _initialized,
-    circuitState: _circuitState,
-    consecutiveErrors: _consecutiveErrors,
-    unifiedSync: _useUnifiedSync,
-    remoteEnabled: _remoteEnabled,
-    appKey: _options ? _options.appKey || null : null,
-    environment: _options ? _options.environment || null : null,
-  };
-}
-
-// Layers (TCP / iptables / cloud) read the matcher to populate kernel-level
-// rules. When the remote toggle is off, return null so they treat the policy
-// as "no IPs to block" without us mutating the cached matcher.
-function getMatcher() { return _remoteEnabled === false ? null : _matcher; }
-function getAllowlistMatcher() { return _remoteEnabled === false ? null : _allowlistMatcher; }
-function getBlocklistRules() { return _remoteEnabled === false ? [] : _blocklistRules.slice(); }
-function getRateLimitRules() { return _remoteEnabled === false ? [] : _rateLimitRules.slice(); }
-function isRemoteEnabled() { return _remoteEnabled !== false; }
-
-function getChallengeRules() { return _challengeRules; }
-
-module.exports = { init, shutdown, getStats, getMatcher, getAllowlistMatcher, getBlocklistRules, getRateLimitRules, getChallengeRules, isRemoteEnabled };
+'use strict';
+
+const http = require('http');
+const https = require('https');
+const { createMatcher } = require('./cidr');
+const { resolveClientIp } = require('./resolve-ip');
+const challenge = require('./challenge');
+
+let _options = null;
+let _matcher = null;
+let _syncTimer = null;
+let _pollTimer = null;
+let _lastModified = null;
+let _lastVersion = null;
+let _lastSyncEtag = null;
+let _lastUnifiedEtag = null;
+let _initialized = false;
+let _consecutiveErrors = 0;
+let _layers = [];
+let _rawIps = [];
+let _blocklistRules = [];
+let _stats = { syncs: 0, blocked: 0, rateLimited: 0, challenged: 0, allowed: 0, versionChecks: 0, errors: 0, suppressedDisabled: 0 };
+let _localhostFallbackTried = false;
+let _eventQueue = [];
+let _eventTimer = null;
+let _remainingApiUrlFallbacks = [];
+
+// Remote toggle - set by /firewall/sync when an appKey is in scope. Default
+// true so a missing/unreachable backend fails open (matches pre-7.3 behavior).
+// When the dashboard / CLI flips this off, the next poll suppresses
+// enforcement without restarting the host process.
+let _remoteEnabled = true;
+let _lastRemoteEnabled = null;
+
+// Allowlist state
+let _allowlistMatcher = null;
+let _allowlistRawIps = [];
+let _lastAllowlistModified = null;
+let _lastAllowlistVersion = null;
+let _lastAllowlistSyncEtag = null;
+
+// Route/method-scoped policy state. Global IP/CIDR blocks stay in _matcher so
+// TCP, OS firewall, and Cloud WAF layers never over-enforce an HTTP-only rule.
+let _rateLimitRules = [];
+let _lastRateLimitVersion = null;
+let _rateLimitBuckets = new Map();
+
+// CAPTCHA / proof-of-work challenge state. _challengeConfig.secret signs the
+// challenge tokens + clearance cookies (delivered per-app over sync). When a
+// matched request carries no valid clearance the SDK serves an interstitial
+// instead of passing it through.
+let _challengeRules = [];
+let _lastChallengeVersion = null;
+let _challengeConfig = null;
+// Per-IP count of failed/abandoned challenges, for escalation reporting.
+let _challengeFails = new Map();
+
+// Circuit breaker
+const CIRCUIT_OPEN_THRESHOLD = 5;
+const CIRCUIT_OPEN_COOLDOWN_MS = 120_000;
+let _circuitState = 'closed';
+let _circuitOpenedAt = 0;
+
+// In-flight guard and 429 back-off
+let _pollInflight = false;
+let _retryAfterUntil = 0;
+
+// Firewall control-plane traffic is low-frequency and correctness-critical.
+// Use non-keep-alive agents so clustered apps do not reuse sockets that an
+// upstream load balancer has silently closed between sync cycles.
+const _httpAgent = new http.Agent({ keepAlive: false });
+const _httpsAgent = new https.Agent({ keepAlive: false });
+const EVENT_FLUSH_INTERVAL_MS = 2_000;
+const EVENT_BATCH_SIZE = 25;
+const EVENT_QUEUE_MAX = 1_000;
+const TRANSIENT_NETWORK_CODES = new Set(['ECONNRESET', 'ECONNREFUSED', 'EPIPE', 'ETIMEDOUT', 'EAI_AGAIN', 'ENOTFOUND']);
+
+// Unified sync uses /firewall/sync (v2). Falls back to legacy on 404.
+let _useUnifiedSync = true;
+
+function originalConsoleMethod(method) {
+  const originals = console.__securenow_original || console.__securenowOriginalConsole;
+  return (originals && originals[method]) || console[method] || console.log;
+}
+
+function firewallConsole(method, ...args) {
+  if (!_options || !_options.log) return;
+  try {
+    originalConsoleMethod(method).apply(console, args);
+  } catch (_) {}
+}
+
+function fwLog(...args) {
+  firewallConsole('log', ...args);
+}
+
+function fwWarn(...args) {
+  firewallConsole('warn', ...args);
+}
+
+// Circuit Breaker
+
+function maybeOpenCircuit() {
+  if (_circuitState === 'open') return;
+  if (_consecutiveErrors >= CIRCUIT_OPEN_THRESHOLD) {
+    _circuitState = 'open';
+    _circuitOpenedAt = Date.now();
+    if (_options && _options.log) {
+      fwWarn('[securenow] Firewall: circuit breaker OPEN - pausing polling for %ds', CIRCUIT_OPEN_COOLDOWN_MS / 1000);
+    }
+  }
+}
+
+function resetCircuit() {
+  if (_circuitState !== 'closed') {
+    _circuitState = 'closed';
+    if (_options && _options.log) fwLog('[securenow] Firewall: circuit breaker CLOSED - API healthy');
+  }
+  _consecutiveErrors = 0;
+}
+
+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 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) {
+      fwWarn('[securenow] Firewall: API returned 429, backing off for %ds', secs);
+    }
+  }
+}
+
+// HTTP helpers
+
+function buildUrl(apiUrl, path) {
+  return apiUrl.replace(/\/+$/, '') + '/api/v1' + path;
+}
+
+function buildFirewallUrl(path) {
+  const query = new URLSearchParams();
+  if (_options && _options.appKey) query.set('app', _options.appKey);
+  if (_options && _options.environment) query.set('env', _options.environment);
+  const suffix = query.toString() ? `?${query.toString()}` : '';
+  return buildUrl(_options.apiUrl, path) + suffix;
+}
+
+function jitter(baseMs) {
+  return baseMs * (0.8 + Math.random() * 0.4);
+}
+
+function agentFor(url) {
+  return url.startsWith('https') ? _httpsAgent : _httpAgent;
+}
+
+function isTransientNetworkError(err) {
+  if (!err) return false;
+  if (err.code && TRANSIENT_NETWORK_CODES.has(err.code)) return true;
+  return /socket hang up|connection reset|ECONNRESET|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|timed out/i.test(String(err.message || ''));
+}
+
+function isApiReachabilityError(err) {
+  if (isTransientNetworkError(err)) return true;
+  const text = `${err && err.code || ''} ${err && err.message || ''}`;
+  return /TLS|SSL|certificate|CERT_|UNABLE_TO_VERIFY|self signed/i.test(text);
+}
+
+function formatRequestError(err) {
+  if (!err) return 'unknown error';
+  const parts = [err.message || String(err)];
+  if (err.code && !parts[0].includes(err.code)) parts.push(`code=${err.code}`);
+  if (err.syscall) parts.push(`syscall=${err.syscall}`);
+  return parts.join(' ');
+}
+
+function resetApiUrlFallbacks() {
+  const seen = new Set([_options && _options.apiUrl].filter(Boolean));
+  _remainingApiUrlFallbacks = [];
+  for (const candidate of Array.isArray(_options && _options.apiUrlFallbacks) ? _options.apiUrlFallbacks : []) {
+    const url = String(candidate || '').trim().replace(/\/$/, '');
+    if (!url || seen.has(url)) continue;
+    seen.add(url);
+    _remainingApiUrlFallbacks.push(url);
+  }
+}
+
+function switchToNextApiUrl(reason) {
+  if (!_options || _remainingApiUrlFallbacks.length === 0) return false;
+  const previous = _options.apiUrl;
+  _options.apiUrl = _remainingApiUrlFallbacks.shift();
+  _lastUnifiedEtag = null;
+  _lastSyncEtag = null;
+  _lastAllowlistSyncEtag = null;
+  if (_options.log) {
+    fwWarn('[securenow] Firewall: %s unreachable (%s), retrying sync via %s',
+      previous,
+      reason || 'network error',
+      _options.apiUrl);
+  }
+  return true;
+}
+
+function requestOnce(method, url, body, extraHeaders, timeout, callback) {
+  const mod = url.startsWith('https') ? https : http;
+  const parsed = new URL(url);
+  const payload = body == null ? null : JSON.stringify(body || {});
+
+  const req = mod.request({
+    hostname: parsed.hostname,
+    port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+    path: parsed.pathname + parsed.search,
+    method,
+    headers: {
+      'Authorization': `Bearer ${_options.apiKey}`,
+      'User-Agent': 'securenow-firewall-sdk',
+      'Connection': 'close',
+      ...(payload
+        ? {
+            'Content-Type': 'application/json',
+            'Content-Length': Buffer.byteLength(payload),
+          }
+        : {}),
+      ...extraHeaders,
+    },
+    timeout,
+    agent: agentFor(url),
+  }, (res) => {
+    let data = '';
+    res.on('data', (chunk) => { data += chunk; });
+    res.on('end', () => { done(null, res, data); });
+  });
+
+  let finished = false;
+  function done(...args) {
+    if (finished) return;
+    finished = true;
+    callback(...args);
+  }
+
+  req.on('error', (err) => done(err));
+  req.on('timeout', () => {
+    const err = new Error('Request timed out');
+    err.code = 'ETIMEDOUT';
+    done(err);
+    req.destroy(err);
+  });
+  if (payload) req.write(payload);
+  req.end();
+}
+
+function requestWithRetry(method, url, body, extraHeaders, timeout, callback) {
+  requestOnce(method, url, body, extraHeaders, timeout, (err, res, data) => {
+    if (!err || !isTransientNetworkError(err)) return callback(err, res, data);
+
+    if (_options && _options.log) {
+      fwWarn('[securenow] Firewall: transient API socket error, retrying once:', formatRequestError(err));
+    }
+
+    const retryTimer = setTimeout(() => {
+      requestOnce(method, url, body, extraHeaders, timeout, callback);
+    }, 100);
+    if (retryTimer.unref) retryTimer.unref();
+  });
+}
+
+function httpGet(url, extraHeaders, timeout, callback) {
+  requestWithRetry('GET', url, null, extraHeaders, timeout, callback);
+}
+
+function httpPostJson(url, body, timeout, callback) {
+  requestWithRetry('POST', url, body, {}, timeout, callback);
+}
+
+function scheduleEventFlush() {
+  if (_eventTimer || _eventQueue.length === 0) return;
+  _eventTimer = setTimeout(() => {
+    _eventTimer = null;
+    flushFirewallEvents();
+  }, EVENT_FLUSH_INTERVAL_MS);
+  if (_eventTimer.unref) _eventTimer.unref();
+}
+
+function flushFirewallEvents() {
+  if (!_options || !_options.apiKey || !_options.apiUrl || _eventQueue.length === 0) return;
+  if (shouldSkipRequest()) {
+    _eventQueue = [];
+    return;
+  }
+
+  const batch = _eventQueue.splice(0, EVENT_BATCH_SIZE);
+  const url = buildFirewallUrl('/firewall/events');
+
+  httpPostJson(url, { events: batch }, 5000, (err, res) => {
+    if (err || !res || res.statusCode >= 400) {
+      if (_options.log) {
+        const msg = err ? formatRequestError(err) : `API returned ${res.statusCode}`;
+        fwWarn('[securenow] Firewall: failed to report blocked-request ledger:', msg);
+      }
+    }
+    if (_eventQueue.length) scheduleEventFlush();
+  });
+}
+
+function reportFirewallEvent(event) {
+  if (!_options || !_options.apiKey || !_options.apiUrl) return;
+
+  const item = {
+    applicationKey: _options.appKey || null,
+    environment: _options.environment || 'production',
+    action: 'blocked',
+    statusCode: (_options && _options.statusCode) || 403,
+    occurredAt: new Date().toISOString(),
+    ...event,
+  };
+
+  _eventQueue.push(item);
+  if (_eventQueue.length > EVENT_QUEUE_MAX) {
+    _eventQueue.splice(0, _eventQueue.length - EVENT_QUEUE_MAX);
+  }
+
+  if (_eventQueue.length >= EVENT_BATCH_SIZE) flushFirewallEvents();
+  else scheduleEventFlush();
+}
+
+function normalizePrefixPattern(pattern) {
+  const value = String(pattern || '');
+  return value.endsWith('*') ? value.slice(0, -1) : value;
+}
+
+function normalizeBlocklistRules(rules) {
+  if (!Array.isArray(rules)) return [];
+  return rules
+    .map((rule) => {
+      if (!rule || !rule.ip) return null;
+      const pathMatchMode = ['exact', 'prefix', 'regex'].includes(String(rule.pathMatchMode || '').toLowerCase())
+        ? String(rule.pathMatchMode).toLowerCase()
+        : 'prefix';
+      return {
+        ...rule,
+        ip: String(rule.ip || '').trim(),
+        method: String(rule.method || 'ALL').toUpperCase(),
+        pathPattern: pathMatchMode === 'prefix'
+          ? normalizePrefixPattern(rule.pathPattern)
+          : String(rule.pathPattern || '').trim(),
+        pathMatchMode,
+      };
+    })
+    .filter(Boolean);
+}
+
+function setBlocklistData(ips, rules) {
+  const normalizedIps = Array.isArray(ips) ? ips : [];
+  _rawIps = normalizedIps;
+  _blocklistRules = normalizeBlocklistRules(rules);
+  _matcher = createMatcher(normalizedIps);
+  _stats.syncs++;
+  notifyLayers(normalizedIps);
+}
+
+// Unified Sync (v2 - single request for everything)
+
+function doUnifiedSync(callback) {
+  const query = new URLSearchParams();
+  if (_options.appKey) query.set('app', _options.appKey);
+  if (_options.environment) query.set('env', _options.environment);
+  const suffix = query.toString() ? `?${query.toString()}` : '';
+  const url = buildUrl(_options.apiUrl, '/firewall/sync') + suffix;
+  const headers = {};
+  if (_options.environment) headers['X-SecureNow-Environment'] = _options.environment;
+  if (_lastVersion) headers['X-Blocklist-Version'] = _lastVersion;
+  if (_lastAllowlistVersion) headers['X-Allowlist-Version'] = _lastAllowlistVersion;
+  if (_lastRateLimitVersion) headers['X-Rate-Limit-Version'] = _lastRateLimitVersion;
+  if (_lastChallengeVersion) headers['X-Challenge-Version'] = _lastChallengeVersion;
+  if (_lastUnifiedEtag) headers['If-None-Match'] = _lastUnifiedEtag;
+
+  httpGet(url, headers, 8000, (err, res, data) => {
+    if (err) return callback(err);
+
+    _stats.versionChecks++;
+    if (res.headers && res.headers.etag) _lastUnifiedEtag = res.headers.etag;
+
+    if (res.statusCode === 304) {
+      return callback(null, { blChanged: false, alChanged: false });
+    }
+
+    if (res.statusCode === 404) {
+      _useUnifiedSync = false;
+      if (_options.log) fwLog('[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;
+
+      // Apply remote per-app toggle. Absent body.app means the backend either
+      // doesn't know about appKey-scoped sync (older API) or no appKey was
+      // sent - leave the previous value untouched (default true on first run).
+      if (body.app && typeof body.app.firewallEnabled === 'boolean') {
+        const next = body.app.firewallEnabled;
+        if (next !== _lastRemoteEnabled) {
+          _remoteEnabled = next;
+          if (_options.log) {
+            fwLog('[securenow] Firewall: remote toggle -> %s (app=%s)',
+              next ? 'ENABLED' : 'DISABLED', body.app.key || _options.appKey);
+          }
+          _lastRemoteEnabled = next;
+        }
+      }
+
+      // Update blocklist version + data
+      if (body.blocklist) {
+        const newVer = body.blocklist.version;
+        if (newVer !== _lastVersion) {
+          _lastVersion = newVer;
+        }
+      }
+
+      if (body.blocklistIps || body.blocklistRules) {
+        setBlocklistData(body.blocklistIps || [], body.blocklistRules || []);
+        blChanged = true;
+      }
+
+      // Update allowlist version + data
+      if (body.allowlist) {
+        const newVer = body.allowlist.version;
+        if (newVer !== _lastAllowlistVersion) {
+          _lastAllowlistVersion = newVer;
+        }
+      }
+
+      if (body.allowlistIps) {
+        _allowlistRawIps = body.allowlistIps;
+        _allowlistMatcher = createMatcher(body.allowlistIps);
+        alChanged = true;
+      }
+
+      if (body.rateLimits) {
+        const newVer = body.rateLimits.version;
+        if (newVer !== _lastRateLimitVersion) {
+          _lastRateLimitVersion = newVer;
+        }
+      }
+
+      if (Array.isArray(body.rateLimitRules)) {
+        _rateLimitRules = body.rateLimitRules;
+        pruneRateLimitBuckets(_rateLimitRules);
+      }
+
+      // Per-app challenge config (secret + defaults) rides on the app block.
+      if (body.app && body.app.challenge && typeof body.app.challenge === 'object') {
+        _challengeConfig = body.app.challenge;
+      }
+
+      if (body.challenges) {
+        const newVer = body.challenges.version;
+        if (newVer !== _lastChallengeVersion) {
+          _lastChallengeVersion = newVer;
+        }
+      }
+
+      if (Array.isArray(body.challengeRules)) {
+        _challengeRules = body.challengeRules;
+      }
+
+      callback(null, { blChanged, alChanged, rlChanged: Array.isArray(body.rateLimitRules) });
+    } catch (e) {
+      callback(new Error(`Failed to parse sync response: ${e.message}`));
+    }
+  });
+}
+
+// Legacy Sync (v1 - separate endpoints, kept for backward compat)
+
+function legacyBlocklistSync(callback) {
+  const url = buildFirewallUrl('/firewall/blocklist');
+  const headers = {};
+  if (_options.environment) headers['X-SecureNow-Environment'] = _options.environment;
+  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 || [];
+      setBlocklistData(ips, body.rules || body.blocklistRules || []);
+      _lastModified = res.headers['last-modified'] || null;
+      if (res.headers['etag']) _lastSyncEtag = res.headers['etag'];
+      callback(null, true, _matcher.stats());
+    } catch (e) {
+      callback(new Error(`Failed to parse blocklist: ${e.message}`));
+    }
+  });
+}
+
+function legacyAllowlistSync(callback) {
+  const url = buildFirewallUrl('/firewall/allowlist');
+  const headers = {};
+  if (_options.environment) headers['X-SecureNow-Environment'] = _options.environment;
+  if (_lastAllowlistSyncEtag) headers['If-None-Match'] = _lastAllowlistSyncEtag;
+  else if (_lastAllowlistModified) headers['If-Modified-Since'] = _lastAllowlistModified;
+
+  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 legacyVersionCheck(callback) {
+  const url = buildFirewallUrl('/firewall/blocklist/version');
+  const headers = {};
+  if (_options.environment) headers['X-SecureNow-Environment'] = _options.environment;
+  if (_lastVersion) headers['If-None-Match'] = _lastVersion;
+
+  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}`));
+
+    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 = buildFirewallUrl('/firewall/allowlist/version');
+  const headers = {};
+  if (_options.environment) headers['X-SecureNow-Environment'] = _options.environment;
+  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 });
+    }
+
+    if (blChanged) {
+      legacyBlocklistSync((err, changed, stats) => {
+        if (err && _options.log) fwWarn('[securenow] Firewall: sync failed (using stale list):', formatRequestError(err));
+        else if (changed && stats && _options.log) fwLog('[securenow] Firewall: re-synced %d blocked IPs', stats.total);
+        syncDone();
+      });
+    }
+    if (alChanged) {
+      legacyAllowlistSync((err, changed, stats) => {
+        if (err && _options.log) fwWarn('[securenow] Firewall: allowlist sync failed:', formatRequestError(err));
+        else if (changed && stats && _options.log) fwLog('[securenow] Firewall: re-synced %d allowed IPs', stats.total);
+        syncDone();
+      });
+    }
+  }
+
+  legacyVersionCheck((err, changed) => {
+    if (err) firstError = firstError || err;
+    blChanged = changed;
+    checkDone();
+  });
+
+  legacyAllowlistVersionCheck((err, changed) => {
+    if (err) firstError = firstError || err;
+    alChanged = changed;
+    checkDone();
+  });
+}
+
+// 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 (isApiReachabilityError(err) && switchToNextApiUrl(formatRequestError(err))) {
+        _pollInflight = false;
+        const retryTimer = setTimeout(() => pollOnce(callback), 1000);
+        if (retryTimer.unref) retryTimer.unref();
+        return;
+      }
+      _consecutiveErrors++;
+      _stats.errors++;
+      maybeOpenCircuit();
+      if (_options.log) fwWarn('[securenow] Firewall: poll failed:', formatRequestError(err));
+      return callback(err);
+    }
+    _consecutiveErrors = 0;
+    resetCircuit();
+    if (result) {
+      if (result.blChanged && _options.log && _matcher) {
+        const s = _matcher.stats();
+        fwLog('[securenow] Firewall: re-synced %d global blocked IPs (%d exact + %d CIDR ranges) and %d scoped block rules',
+          s.total, s.exact, s.cidr, _blocklistRules.length);
+      }
+      if (result.alChanged && _options.log && _allowlistMatcher) {
+        const s = _allowlistMatcher.stats();
+        fwLog('[securenow] Firewall: re-synced %d allowed IPs (%d exact + %d CIDR ranges)', s.total, s.exact, s.cidr);
+      }
+      if (result.rlChanged && _options.log) {
+        fwLog('[securenow] Firewall: re-synced %d rate-limit rules', _rateLimitRules.length);
+      }
+    }
+    callback(null);
+  };
+
+  if (_useUnifiedSync) {
+    doUnifiedSync((err, result) => {
+      if (err) return done(err);
+      if (result && result.useLegacy) {
+        doLegacyPoll(done);
+      } else {
+        done(null, result);
+      }
+    });
+  } else {
+    doLegacyPoll(done);
+  }
+}
+
+function scheduleNextPoll() {
+  const baseMs = (_options.versionCheckInterval || 10) * 1000;
+  const backoffMs = Math.min(baseMs * Math.pow(2, _consecutiveErrors), 120_000);
+  const delayMs = jitter(backoffMs);
+
+  _pollTimer = setTimeout(() => {
+    pollOnce(() => { scheduleNextPoll(); });
+  }, delayMs);
+  if (_pollTimer.unref) _pollTimer.unref();
+}
+
+function startSyncLoop() {
+  const fullSyncIntervalMs = (_options.syncInterval || 300) * 1000;
+  const BASE_RETRY = 5000;
+  const MAX_RETRY = 120_000;
+  let _initAttempt = 0;
+
+  function initialSync() {
+    // 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 (isApiReachabilityError(err) && switchToNextApiUrl(formatRequestError(err))) {
+          const retryTimer = setTimeout(initialSync, 1000);
+          if (retryTimer.unref) retryTimer.unref();
+          return;
+        }
+        if (isConnErr && !_localhostFallbackTried && _options.apiUrl !== 'http://localhost:4000') {
+          _localhostFallbackTried = true;
+          const origUrl = _options.apiUrl;
+          _options.apiUrl = 'http://localhost:4000';
+          if (_options.log) fwLog('[securenow] Firewall: %s unreachable, trying http://localhost:4000', origUrl);
+          const retryTimer = setTimeout(initialSync, 1000);
+          if (retryTimer.unref) retryTimer.unref();
+          return;
+        }
+        if (result && result.useLegacy) {
+          const retryTimer = setTimeout(initialSync, 1000);
+          if (retryTimer.unref) retryTimer.unref();
+          return;
+        }
+        if (_options.log) fwWarn('[securenow] Firewall: initial sync failed:', formatRequestError(err));
+        if (_options.failMode === 'closed') {
+          _matcher = { isBlocked: () => true, stats: () => ({ exact: 0, cidr: 0, total: 0 }) };
+        }
+        _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 (result && result.useLegacy) {
+        const retryTimer = setTimeout(initialSync, 1000);
+        if (retryTimer.unref) retryTimer.unref();
+        return;
+      }
+
+      _initialized = true;
+      if (_options.log && _matcher) {
+        const s = _matcher.stats();
+        fwLog('[securenow] Firewall: synced %d global blocked IPs (%d exact + %d CIDR ranges) and %d scoped block rules',
+          s.total, s.exact, s.cidr, _blocklistRules.length);
+      }
+      if (_options.log && _allowlistMatcher) {
+        const s = _allowlistMatcher.stats();
+        if (s.total > 0) fwLog('[securenow] Firewall: synced %d allowed IPs (%d exact + %d CIDR ranges)', s.total, s.exact, s.cidr);
+      }
+      if (_options.log && _rateLimitRules.length > 0) {
+        fwLog('[securenow] Firewall: synced %d rate-limit rules', _rateLimitRules.length);
+      }
+    });
+  }
+
+  initialSync();
+  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;
+    const savedRlVer = _lastRateLimitVersion;
+    const savedUnifiedEtag = _lastUnifiedEtag;
+    _lastVersion = null;
+    _lastAllowlistVersion = null;
+    _lastRateLimitVersion = null;
+    _lastUnifiedEtag = null;
+    pollOnce((err) => {
+      if (err) {
+        _lastVersion = savedBlVer;
+        _lastAllowlistVersion = savedAlVer;
+        _lastRateLimitVersion = savedRlVer;
+        _lastUnifiedEtag = savedUnifiedEtag;
+      }
+    });
+  }, fullSyncIntervalMs);
+  if (_syncTimer.unref) _syncTimer.unref();
+}
+
+// Layer 1: HTTP Handler
+
+const _origHttpCreate = http.createServer;
+const _origHttpsCreate = https.createServer;
+let _httpPatched = false;
+
+function blockedHtml(ip) {
+  const maskedIp = ip || 'unknown';
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Access Blocked - Security Alert</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+body{min-height:100vh;display:flex;align-items:center;justify-content:center;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;background:#0a0a0a;color:#e5e5e5}
+.wrap{text-align:center;max-width:540px;padding:2.5rem 2rem}
+.icon{width:64px;height:64px;margin:0 auto 1.5rem;border-radius:50%;background:rgba(220,38,38,.12);display:flex;align-items:center;justify-content:center}
+.icon svg{width:32px;height:32px;fill:none;stroke:#dc2626;stroke-width:2;stroke-linecap:round;stroke-linejoin:round}
+.badge{display:inline-block;padding:.25rem .75rem;border-radius:999px;background:rgba(220,38,38,.15);color:#f87171;font-size:.7rem;font-weight:700;letter-spacing:.08em;text-transform:uppercase;margin-bottom:1.25rem}
+h1{font-size:1.6rem;font-weight:700;margin-bottom:.6rem;color:#fff}
+.sub{font-size:1rem;color:#f87171;font-weight:600;margin-bottom:1.25rem}
+p{font-size:.9rem;line-height:1.7;color:#a1a1aa;margin-bottom:.5rem}
+.ip-box{display:inline-block;margin:1rem 0;padding:.6rem 1.5rem;border-radius:8px;background:rgba(255,255,255,.04);border:1px solid rgba(220,38,38,.25);font-family:"SF Mono",SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:.95rem;color:#fca5a5;letter-spacing:.03em}
+.divider{width:48px;height:2px;background:rgba(220,38,38,.3);margin:1.5rem auto}
+.contact{font-size:.85rem;color:#71717a;line-height:1.7}
+.contact a{color:#f87171;text-decoration:none;font-weight:500}
+.contact a:hover{text-decoration:underline}
+.footer{margin-top:2rem;font-size:.7rem;color:#3f3f46}
+.powered{margin-top:1.5rem;font-size:.75rem;color:#52525b}.powered a{color:#a1a1aa;text-decoration:none;font-weight:600;transition:color .2s}.powered a:hover{color:#f87171;text-decoration:underline}
+</style>
+</head>
+<body>
+<div class="wrap">
+<div class="icon"><svg viewBox="0 0 24 24"><path d="M12 9v4m0 4h.01M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z"/></svg></div>
+<span class="badge">Security Alert</span>
+<h1>Access Blocked</h1>
+<p class="sub">Malicious activity detected from your IP address</p>
+<p>Your IP has been flagged and blocked due to suspicious or malicious behavior originating from your network. Our security team has been notified and is actively investigating.</p>
+<div class="ip-box">${maskedIp}</div>
+<div class="divider"></div>
+<p class="contact">If you believe this is a mistake, please contact us at<br><a href="mailto:contact@securenow.ai?subject=Blocked%20IP%20Appeal%20-%20${encodeURIComponent(maskedIp)}&body=IP:%20${encodeURIComponent(maskedIp)}%0ATimestamp:%20${encodeURIComponent(new Date().toISOString())}%0A%0APlease%20describe%20why%20you%20believe%20this%20block%20is%20incorrect:">contact@securenow.ai</a><br>Include your IP address and the time of this incident.</p>
+<p class="footer">Ref: ${maskedIp} &mdash; ${new Date().toISOString()} &mdash; HTTP 403</p>
+<p class="powered">Protected by <a href="https://securenow.ai" rel="dofollow" target="_blank">SecureNow</a></p>
+</div>
+</body>
+</html>`;
+}
+
+function wrapListener(originalListener) {
+  return function firewallGuard(req, res) {
+    _stats.allowed++;
+    return originalListener.call(this, req, res);
+  };
+}
+
+function sendBlockResponse(req, res, ip) {
+  const code = (_options && _options.statusCode) || 403;
+  const accept = req.headers['accept'] || '';
+  if (accept.includes('text/html')) {
+    res.writeHead(code, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(blockedHtml(ip));
+  } else {
+    res.writeHead(code, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Forbidden', ip }));
+  }
+}
+
+function sendRateLimitResponse(req, res, ip, decision) {
+  const retryAfter = Math.max(1, decision.retryAfter || 1);
+  const headers = {
+    'Retry-After': String(retryAfter),
+    'X-RateLimit-Limit': String(decision.limit || ''),
+    'X-RateLimit-Window': String(decision.windowSeconds || ''),
+    'X-SecureNow-Rate-Limit-Rule': decision.ruleId || '',
+  };
+  const accept = req.headers['accept'] || '';
+  if (accept.includes('text/html')) {
+    res.writeHead(429, { ...headers, 'Content-Type': 'text/html; charset=utf-8' });
+    res.end('<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>Too Many Requests</title></head><body><h1>Too Many Requests</h1><p>Please retry later.</p></body></html>');
+  } else {
+    res.writeHead(429, { ...headers, 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      error: 'Too Many Requests',
+      ip,
+      retryAfter,
+    }));
+  }
+}
+
+function requestPath(req) {
+  try {
+    return new URL(req.url || '/', 'http://localhost').pathname || '/';
+  } catch (_) {
+    return req.url || '/';
+  }
+}
+
+function ruleIpMatches(rule, ip) {
+  const target = String(rule.ip || '').trim();
+  if (!target) return true;
+  try {
+    return createMatcher([target]).isBlocked(ip);
+  } catch (_) {
+    return false;
+  }
+}
+
+function rulePathMatches(rule, path) {
+  const pattern = String(rule.pathPattern || '').trim();
+  if (!pattern) return true;
+  const mode = rule.pathMatchMode || 'prefix';
+  if (mode === 'exact') return path === pattern;
+  if (mode === 'regex') {
+    try { return new RegExp(pattern).test(path); } catch (_) { return false; }
+  }
+  return path.startsWith(normalizePrefixPattern(pattern));
+}
+
+function rateLimitKey(rule, ip) {
+  const id = rule.id || rule._id || `${rule.ip || '*'}:${rule.method || 'ALL'}:${rule.pathPattern || '*'}`;
+  const subject = rule.keyBy === 'global' ? 'global' : ip;
+  return `${id}|${subject}`;
+}
+
+function checkBlocklistRules(req, ip) {
+  if (!_blocklistRules || _blocklistRules.length === 0) return null;
+  const method = String(req.method || 'GET').toUpperCase();
+  const path = requestPath(req);
+
+  for (const rule of _blocklistRules) {
+    if (!rule) continue;
+    const ruleMethod = String(rule.method || 'ALL').toUpperCase();
+    if (ruleMethod !== 'ALL' && ruleMethod !== method) continue;
+    if (!ruleIpMatches(rule, ip)) continue;
+    if (!rulePathMatches(rule, path)) continue;
+    return {
+      rule,
+      ruleId: rule.id || rule._id || '',
+      matchedEntry: rule.ip || ip,
+      path,
+    };
+  }
+
+  return null;
+}
+
+function checkRateLimitRules(req, ip) {
+  if (!_rateLimitRules || _rateLimitRules.length === 0) return null;
+  const method = String(req.method || 'GET').toUpperCase();
+  const path = requestPath(req);
+  const now = Date.now();
+
+  for (const rule of _rateLimitRules) {
+    if (!rule) continue;
+    const ruleMethod = String(rule.method || 'ALL').toUpperCase();
+    if (ruleMethod !== 'ALL' && ruleMethod !== method) continue;
+    if (!ruleIpMatches(rule, ip)) continue;
+    if (!rulePathMatches(rule, path)) continue;
+
+    const limit = Math.max(1, Number(rule.limit || 1) || 1);
+    const windowSeconds = Math.max(1, Number(rule.windowSeconds || 60) || 60);
+    const windowMs = windowSeconds * 1000;
+    const key = rateLimitKey(rule, ip);
+    let bucket = _rateLimitBuckets.get(key);
+    if (!bucket || now - bucket.windowStart >= windowMs) {
+      bucket = { windowStart: now, count: 0 };
+      _rateLimitBuckets.set(key, bucket);
+    }
+
+    if (bucket.count >= limit) {
+      const retryAfter = Math.ceil((bucket.windowStart + windowMs - now) / 1000);
+      return {
+        rule,
+        ruleId: rule.id || rule._id || '',
+        limit,
+        windowSeconds,
+        retryAfter,
+        path,
+      };
+    }
+    bucket.count++;
+  }
+
+  return null;
+}
+
+function pruneRateLimitBuckets(rules) {
+  const ids = new Set((rules || []).map((rule) => String(rule.id || rule._id || `${rule.ip || '*'}:${rule.method || 'ALL'}:${rule.pathPattern || '*'}`)));
+  for (const key of _rateLimitBuckets.keys()) {
+    const idx = key.indexOf('|');
+    const ruleKey = idx === -1 ? key : key.slice(0, idx);
+    if (!ids.has(ruleKey)) _rateLimitBuckets.delete(key);
+  }
+}
+
+// ── Challenge (CAPTCHA / proof-of-work) enforcement ──
+
+const CHALLENGE_INTERNAL_PATH = '/__securenow/challenge';
+
+function isSecureRequest(req) {
+  if (req.socket && req.socket.encrypted) return true;
+  const xfp = String(req.headers['x-forwarded-proto'] || '').split(',')[0].trim().toLowerCase();
+  return xfp === 'https';
+}
+
+function challengeDifficulty(rule) {
+  const d = Number(rule && rule.difficulty);
+  if (Number.isFinite(d) && d >= 4 && d <= 28) return d;
+  const cfg = Number(_challengeConfig && _challengeConfig.difficulty);
+  if (Number.isFinite(cfg) && cfg >= 4) return cfg;
+  return challenge.DEFAULTS.difficulty;
+}
+
+function findChallengeRuleById(rid) {
+  if (!rid || rid === '*') return null;
+  for (const rule of _challengeRules) {
+    if (String(rule.id || rule._id || '') === String(rid)) return rule;
+  }
+  return null;
+}
+
+function challengeClearanceTtl(rule) {
+  const t = Number(rule && rule.clearanceTtlSeconds);
+  if (Number.isFinite(t) && t >= 30) return t;
+  const cfg = Number(_challengeConfig && _challengeConfig.clearanceTtl);
+  if (Number.isFinite(cfg) && cfg >= 30) return cfg;
+  return challenge.DEFAULTS.clearanceTtl;
+}
+
+function checkChallengeRules(req, ip) {
+  if (!_challengeRules || _challengeRules.length === 0) return null;
+  if (!_challengeConfig || !_challengeConfig.secret) return null;
+  const method = String(req.method || 'GET').toUpperCase();
+  const path = requestPath(req);
+  for (const rule of _challengeRules) {
+    if (!rule) continue;
+    const ruleMethod = String(rule.method || 'ALL').toUpperCase();
+    if (ruleMethod !== 'ALL' && ruleMethod !== method) continue;
+    if (!ruleIpMatches(rule, ip)) continue;
+    if (!rulePathMatches(rule, path)) continue;
+    return { rule, ruleId: rule.id || rule._id || '', path };
+  }
+  return null;
+}
+
+function hasValidClearance(req, ip) {
+  const secret = _challengeConfig && _challengeConfig.secret;
+  if (!secret) return false;
+  const cookie = challenge.readClearanceCookie(req);
+  if (!cookie) return false;
+  const ua = req.headers['user-agent'] || '';
+  return challenge.verifyClearance(secret, { cookie, ip, ua }).ok;
+}
+
+function buildClearanceCookie(value, maxAge, secure) {
+  let cookie = `${challenge.CLEARANCE_COOKIE}=${value}; Max-Age=${maxAge}; Path=/; HttpOnly; SameSite=Lax`;
+  if (secure) cookie += '; Secure';
+  return cookie;
+}
+
+function readJsonBody(req, maxBytes, cb) {
+  let size = 0;
+  const chunks = [];
+  let done = false;
+  const finish = (err, val) => { if (done) return; done = true; cb(err, val); };
+  req.on('data', (chunk) => {
+    size += chunk.length;
+    if (size > maxBytes) {
+      finish(new Error('too_large'));
+      try { req.destroy(); } catch (_) {}
+      return;
+    }
+    chunks.push(chunk);
+  });
+  req.on('end', () => {
+    if (done) return;
+    try { finish(null, JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}')); }
+    catch (e) { finish(e); }
+  });
+  req.on('error', (e) => finish(e));
+}
+
+function noteChallengeFail(ip) {
+  if (_challengeFails.size > 50_000) _challengeFails.clear();
+  const n = (_challengeFails.get(ip) || 0) + 1;
+  _challengeFails.set(ip, n);
+  return n;
+}
+
+// Serve the proof-of-work interstitial (or a JSON challenge for API clients).
+function sendChallengeResponse(req, res, ip, decision) {
+  const secret = _challengeConfig.secret;
+  const rule = decision.rule || {};
+  const difficulty = challengeDifficulty(rule);
+  const rid = decision.ruleId || '*';
+  const challengeTtl = Number(_challengeConfig.challengeTtl) || challenge.DEFAULTS.challengeTtl;
+  const token = challenge.signChallenge(secret, { ip, difficulty, rid, challengeTtl });
+  const baseHeaders = { 'X-SecureNow-Challenge': 'required', 'Cache-Control': 'no-store' };
+
+  reportFirewallEvent({
+    action: 'captcha_challenged',
+    source: 'challenge',
+    statusCode: 403,
+    ip,
+    matchedEntry: rid,
+    method: req.method || '',
+    path: decision.path || req.url || '',
+    userAgent: req.headers['user-agent'] || '',
+  });
+
+  const accept = req.headers['accept'] || '';
+  if (accept.includes('text/html')) {
+    res.writeHead(403, { ...baseHeaders, 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(challenge.challengeHtml({
+      token,
+      difficulty,
+      submitPath: CHALLENGE_INTERNAL_PATH,
+      returnPath: req.url || '/',
+      ip,
+    }));
+  } else {
+    res.writeHead(403, { ...baseHeaders, 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      error: 'challenge_required',
+      challenge: { token, alg: challenge.ALG_POW, difficulty, submit: CHALLENGE_INTERNAL_PATH },
+    }));
+  }
+}
+
+// Handle the internal solve endpoint (POST /__securenow/challenge). Verifies
+// the proof-of-work — locally with the per-app secret, or by proxying to the
+// API — then issues a clearance cookie on success.
+function handleChallengeInternal(req, res, ip) {
+  if (String(req.method || '').toUpperCase() !== 'POST') {
+    res.writeHead(405, { 'Content-Type': 'application/json', Allow: 'POST' });
+    res.end(JSON.stringify({ ok: false, reason: 'method_not_allowed' }));
+    return true;
+  }
+
+  const secret = _challengeConfig && _challengeConfig.secret;
+  const verifyMode = (_challengeConfig && _challengeConfig.verify) || 'auto';
+
+  readJsonBody(req, 8192, (err, body) => {
+    if (err || !body || !body.token) {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, reason: 'bad_request' }));
+      return;
+    }
+    const ua = req.headers['user-agent'] || '';
+    const rid = body.rid || '*';
+    const clearanceTtl = challengeClearanceTtl(findChallengeRuleById(rid));
+    const useProxy = verifyMode === 'proxy' || !secret;
+
+    const onPass = (value, maxAge) => {
+      _challengeFails.delete(ip);
+      res.setHeader('Set-Cookie', buildClearanceCookie(value, maxAge || clearanceTtl, isSecureRequest(req)));
+      res.writeHead(204);
+      res.end();
+      reportFirewallEvent({
+        action: 'captcha_passed', source: 'challenge', statusCode: 204,
+        ip, matchedEntry: rid, method: 'POST', path: CHALLENGE_INTERNAL_PATH, userAgent: ua,
+      });
+    };
+    const onFail = (reason) => {
+      const n = noteChallengeFail(ip);
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, reason: reason || 'verification_failed' }));
+      reportFirewallEvent({
+        action: 'captcha_failed', source: 'challenge', statusCode: 400,
+        ip, matchedEntry: String(n), method: 'POST', path: CHALLENGE_INTERNAL_PATH, userAgent: ua,
+      });
+    };
+
+    if (useProxy) {
+      const url = buildFirewallUrl('/firewall/verify-challenge');
+      httpPostJson(url, { token: body.token, nonce: body.nonce, ip, ua, rid, clearanceTtl }, 8000, (e, r, data) => {
+        if (e || !r || r.statusCode !== 200) return onFail('proxy_unreachable');
+        let parsed;
+        try { parsed = JSON.parse(data); } catch (_) { return onFail('proxy_bad_response'); }
+        if (!parsed || !parsed.ok || !parsed.clearance) return onFail(parsed && parsed.reason);
+        onPass(parsed.clearance.value, parsed.clearance.maxAge);
+      });
+    } else {
+      const result = challenge.verifyChallengeSolution(secret, { token: body.token, nonce: body.nonce, ip });
+      if (!result.ok) return onFail(result.reason);
+      const cl = challenge.issueClearance(secret, { ip, ua, rid, clearanceTtl });
+      onPass(cl.value, cl.maxAge);
+    }
+  });
+  return true;
+}
+
+function firewallRequestHandler(req, res) {
+  // Remote disable wins over everything: when the dashboard / CLI flips the
+  // toggle off, requests pass through the SDK as if the firewall weren't
+  // installed. The poll loop keeps running so we re-enable within seconds.
+  if (_remoteEnabled === false) {
+    _stats.suppressedDisabled++;
+    return false;
+  }
+
+  const ip = resolveClientIp(req);
+
+  // SecureNow-internal challenge solve endpoint. Handled before any IP rule
+  // check so a challenged visitor can always submit their proof-of-work.
+  if (requestPath(req) === CHALLENGE_INTERNAL_PATH) {
+    return handleChallengeInternal(req, res, ip);
+  }
+
+  // Allowlist check: if active, only listed IPs are allowed through
+  if (_allowlistMatcher && _allowlistMatcher.stats().total > 0) {
+    if (!_allowlistMatcher.isBlocked(ip)) {
+      _stats.blocked++;
+      if (_options && _options.log) fwLog('[securenow] Firewall: blocked %s via HTTP (not in allowlist)', ip);
+      reportFirewallEvent({
+        source: 'allowlist',
+        ip,
+        matchedEntry: '',
+        method: req.method || '',
+        path: req.url || '',
+        userAgent: req.headers['user-agent'] || '',
+      });
+      sendBlockResponse(req, res, ip);
+      return true;
+    }
+    return false;
+  }
+
+  // Blocklist check
+  if (_matcher && _matcher.isBlocked(ip)) {
+    _stats.blocked++;
+    if (_options && _options.log) fwLog('[securenow] Firewall: blocked %s via HTTP', ip);
+    reportFirewallEvent({
+      source: 'blocklist',
+      ip,
+      matchedEntry: ip,
+      method: req.method || '',
+      path: req.url || '',
+      userAgent: req.headers['user-agent'] || '',
+    });
+    sendBlockResponse(req, res, ip);
+    return true;
+  }
+
+  const blockRuleDecision = checkBlocklistRules(req, ip);
+  if (blockRuleDecision) {
+    _stats.blocked++;
+    if (_options && _options.log) {
+      fwLog('[securenow] Firewall: blocked %s via HTTP (rule=%s)', ip, blockRuleDecision.ruleId || 'scoped');
+    }
+    reportFirewallEvent({
+      source: 'blocklist',
+      ip,
+      matchedEntry: blockRuleDecision.matchedEntry || ip,
+      method: req.method || '',
+      path: blockRuleDecision.path || req.url || '',
+      userAgent: req.headers['user-agent'] || '',
+    });
+    sendBlockResponse(req, res, ip);
+    return true;
+  }
+
+  // Challenge check sits between hard-block and rate-limit: a matched-but-
+  // uncleared visitor gets the interstitial (and does not consume a rate-limit
+  // bucket); once they hold a valid clearance they fall through to rate-limit.
+  const challengeDecision = checkChallengeRules(req, ip);
+  if (challengeDecision && !hasValidClearance(req, ip)) {
+    _stats.challenged = (_stats.challenged || 0) + 1;
+    if (_options && _options.log) {
+      fwLog('[securenow] Firewall: challenged %s via HTTP (rule=%s)', ip, challengeDecision.ruleId || 'scoped');
+    }
+    sendChallengeResponse(req, res, ip, challengeDecision);
+    return true;
+  }
+
+  const rateLimitDecision = checkRateLimitRules(req, ip);
+  if (rateLimitDecision) {
+    _stats.rateLimited++;
+    if (_options && _options.log) {
+      fwLog('[securenow] Firewall: rate-limited %s via HTTP (rule=%s)', ip, rateLimitDecision.ruleId || 'unknown');
+    }
+    reportFirewallEvent({
+      action: 'rate_limited',
+      source: 'rate_limit',
+      statusCode: 429,
+      ip,
+      matchedEntry: rateLimitDecision.ruleId || '',
+      method: req.method || '',
+      path: rateLimitDecision.path || req.url || '',
+      userAgent: req.headers['user-agent'] || '',
+    });
+    sendRateLimitResponse(req, res, ip, rateLimitDecision);
+    return true;
+  }
+
+  return false;
+}
+
+const _origEmit = http.Server.prototype.emit;
+let _emitPatched = false;
+
+function patchEmitLayer() {
+  if (_emitPatched) return;
+  _emitPatched = true;
+
+  http.Server.prototype.emit = function(event, req, res, ...rest) {
+    if (event === 'request' && req && res && !res.headersSent) {
+      if (firewallRequestHandler(req, res)) return true;
+    }
+    return _origEmit.call(this, event, req, res, ...rest);
+  };
+}
+
+function patchHttpLayer() {
+  if (_httpPatched) return;
+  _httpPatched = true;
+
+  patchEmitLayer();
+
+  http.createServer = function(...args) {
+    if (typeof args[args.length - 1] === 'function') {
+      args[args.length - 1] = wrapListener(args[args.length - 1]);
+    }
+    return _origHttpCreate.apply(this, args);
+  };
+  Object.assign(http.createServer, _origHttpCreate);
+
+  https.createServer = function(...args) {
+    if (typeof args[args.length - 1] === 'function') {
+      args[args.length - 1] = wrapListener(args[args.length - 1]);
+    }
+    return _origHttpsCreate.apply(this, args);
+  };
+  Object.assign(https.createServer, _origHttpsCreate);
+}
+
+// Init
+
+function init(options) {
+  _options = options || {};
+  _options.apiUrl = String(_options.apiUrl || '').trim().replace(/\/$/, '');
+  _localhostFallbackTried = false;
+  _useUnifiedSync = true;
+  resetApiUrlFallbacks();
+
+  if (_options.log) fwLog('[securenow] Firewall: ENABLED');
+  if (_options.log && _options.apiUrl) fwLog('[securenow] Firewall: sync endpoint=%s/api/v1/firewall/sync', _options.apiUrl);
+  if (_options.log && _options.environment) fwLog('[securenow] Firewall: environment=%s', _options.environment);
+
+  patchHttpLayer();
+  if (_options.log) fwLog('[securenow] Firewall: Layer 1 (HTTP 403)      active');
+
+  if (_options.tcp) {
+    try {
+      const tcpLayer = require('./firewall-tcp');
+      tcpLayer.init(() => _matcher, _options, () => _allowlistMatcher);
+      _layers.push(tcpLayer);
+      if (_options.log) fwLog('[securenow] Firewall: Layer 2 (TCP drop)       active');
+    } catch (e) {
+      if (_options.log) fwWarn('[securenow] Firewall: Layer 2 (TCP drop)       failed:', e.message);
+    }
+  } else {
+    if (_options.log) fwLog('[securenow] Firewall: Layer 2 (TCP drop)       disabled (set config.firewall.tcp=true)');
+  }
+
+  if (_options.iptables) {
+    try {
+      const iptablesLayer = require('./firewall-iptables');
+      iptablesLayer.init(_options);
+      _layers.push(iptablesLayer);
+      if (_options.log) fwLog('[securenow] Firewall: Layer 3 (iptables)       active');
+    } catch (e) {
+      if (_options.log) fwWarn('[securenow] Firewall: Layer 3 (iptables)       failed:', e.message);
+    }
+  } else {
+    if (_options.log) fwLog('[securenow] Firewall: Layer 3 (iptables)       disabled (set config.firewall.iptables=true)');
+  }
+
+  if (_options.cloud) {
+    try {
+      const cloudLayer = require('./firewall-cloud');
+      cloudLayer.init(_options);
+      _layers.push(cloudLayer);
+      if (_options.log) fwLog('[securenow] Firewall: Layer 4 (Cloud WAF)      active (%s)', _options.cloud);
+    } catch (e) {
+      if (_options.log) fwWarn('[securenow] Firewall: Layer 4 (Cloud WAF)      failed:', e.message);
+    }
+  } else {
+    if (_options.log) fwLog('[securenow] Firewall: Layer 4 (Cloud WAF)      disabled (set config.firewall.cloud=cloudflare|aws|gcp)');
+  }
+
+  startSyncLoop();
+}
+
+function shutdown() {
+  if (_pollTimer) { clearTimeout(_pollTimer); _pollTimer = null; }
+  if (_syncTimer) { clearInterval(_syncTimer); _syncTimer = null; }
+  if (_eventTimer) { clearTimeout(_eventTimer); _eventTimer = null; }
+  flushFirewallEvents();
+
+  _circuitState = 'closed';
+  _circuitOpenedAt = 0;
+  _consecutiveErrors = 0;
+  _pollInflight = false;
+  _retryAfterUntil = 0;
+  _localhostFallbackTried = false;
+  _blocklistRules = [];
+  _rateLimitRules = [];
+  _rateLimitBuckets = new Map();
+  _challengeRules = [];
+  _challengeConfig = null;
+  _lastChallengeVersion = null;
+  _challengeFails = new Map();
+  _remainingApiUrlFallbacks = [];
+
+  _httpAgent.destroy();
+  _httpsAgent.destroy();
+
+  for (const layer of _layers) {
+    try { if (typeof layer.shutdown === 'function') layer.shutdown(); } catch (_) {}
+  }
+  _layers = [];
+
+  if (_emitPatched) {
+    http.Server.prototype.emit = _origEmit;
+    _emitPatched = false;
+  }
+  if (_httpPatched) {
+    http.createServer = _origHttpCreate;
+    https.createServer = _origHttpsCreate;
+    _httpPatched = false;
+  }
+}
+
+function getStats() {
+  return {
+    ..._stats,
+    matcher: _matcher ? _matcher.stats() : null,
+    blocklistRules: _blocklistRules.length,
+    allowlistMatcher: _allowlistMatcher ? _allowlistMatcher.stats() : null,
+    rateLimitRules: _rateLimitRules.length,
+    rateLimitBuckets: _rateLimitBuckets.size,
+    initialized: _initialized,
+    circuitState: _circuitState,
+    consecutiveErrors: _consecutiveErrors,
+    unifiedSync: _useUnifiedSync,
+    remoteEnabled: _remoteEnabled,
+    appKey: _options ? _options.appKey || null : null,
+    environment: _options ? _options.environment || null : null,
+  };
+}
+
+// Layers (TCP / iptables / cloud) read the matcher to populate kernel-level
+// rules. When the remote toggle is off, return null so they treat the policy
+// as "no IPs to block" without us mutating the cached matcher.
+function getMatcher() { return _remoteEnabled === false ? null : _matcher; }
+function getAllowlistMatcher() { return _remoteEnabled === false ? null : _allowlistMatcher; }
+function getBlocklistRules() { return _remoteEnabled === false ? [] : _blocklistRules.slice(); }
+function getRateLimitRules() { return _remoteEnabled === false ? [] : _rateLimitRules.slice(); }
+function isRemoteEnabled() { return _remoteEnabled !== false; }
+
+function getChallengeRules() { return _challengeRules; }
+
+module.exports = { init, shutdown, getStats, getMatcher, getAllowlistMatcher, getBlocklistRules, getRateLimitRules, getChallengeRules, isRemoteEnabled };