securenow 7.7.15 → 7.8.1

package/firewall.js

@@ -17,10 +17,12 @@ let _initialized = false;
 let _consecutiveErrors = 0;
 let _layers = [];
 let _rawIps = [];
+let _blocklistRules = [];
 let _stats = { syncs: 0, blocked: 0, rateLimited: 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).
@@ -36,8 +38,8 @@ let _lastAllowlistModified = null;
 let _lastAllowlistVersion = null;
 let _lastAllowlistSyncEtag = null;
 
-// Rate-limit policy state is synced in Phase 1 for forward compatibility.
-// Enforcement is intentionally added in the next SDK phase.
+// 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();
@@ -60,7 +62,7 @@ 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', 'EPIPE', 'ETIMEDOUT', 'EAI_AGAIN']);
+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;
@@ -156,7 +158,13 @@ function agentFor(url) {
 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/i.test(String(err.message || ''));
+  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) {
@@ -167,6 +175,33 @@ function formatRequestError(err) {
   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);
@@ -288,9 +323,44 @@ function reportFirewallEvent(event) {
   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);
@@ -355,13 +425,10 @@ function doUnifiedSync(callback) {
         }
       }
 
-      if (body.blocklistIps) {
-        _rawIps = body.blocklistIps;
-        _matcher = createMatcher(body.blocklistIps);
-        _stats.syncs++;
-        notifyLayers(body.blocklistIps);
-        blChanged = true;
-      }
+      if (body.blocklistIps || body.blocklistRules) {
+        setBlocklistData(body.blocklistIps || [], body.blocklistRules || []);
+        blChanged = true;
+      }
 
       // Update allowlist version + data
       if (body.allowlist) {
@@ -411,16 +478,13 @@ function legacyBlocklistSync(callback) {
     if (res.statusCode === 429) { handleRetryAfter(res); }
     if (res.statusCode !== 200) return callback(new Error(`API returned ${res.statusCode}: ${data.slice(0, 200)}`));
 
-    try {
-      const body = JSON.parse(data);
-      const ips = body.ips || [];
-      _rawIps = ips;
-      _matcher = createMatcher(ips);
-      _lastModified = res.headers['last-modified'] || null;
-      if (res.headers['etag']) _lastSyncEtag = res.headers['etag'];
-      _stats.syncs++;
-      notifyLayers(ips);
-      callback(null, true, _matcher.stats());
+    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}`));
     }
@@ -562,9 +626,15 @@ function pollOnce(callback) {
 
   const done = (err, result) => {
     _pollInflight = false;
-    if (err) {
-      _consecutiveErrors++;
-      _stats.errors++;
+    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);
@@ -572,16 +642,17 @@ function pollOnce(callback) {
     _consecutiveErrors = 0;
     resetCircuit();
     if (result) {
-      if (result.blChanged && _options.log && _matcher) {
-        const s = _matcher.stats();
-        fwLog('[securenow] Firewall: re-synced %d blocked IPs (%d exact + %d CIDR ranges)', s.total, s.exact, s.cidr);
-      }
+      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 (enforcement pending SDK phase 2)', _rateLimitRules.length);
+        fwLog('[securenow] Firewall: re-synced %d rate-limit rules', _rateLimitRules.length);
       }
     }
     callback(null);
@@ -623,9 +694,14 @@ function startSyncLoop() {
     const syncFn = _useUnifiedSync ? doUnifiedSync : (cb) => doLegacyPoll(cb);
 
     syncFn((err, result) => {
-      if (err) {
-        const isConnErr = /ECONNREFUSED|ENOTFOUND|timed out/i.test(err.message);
-        if (isConnErr && !_localhostFallbackTried && _options.apiUrl !== 'http://localhost:4000') {
+      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';
@@ -656,17 +732,18 @@ function startSyncLoop() {
         return;
       }
 
-      _initialized = true;
-      if (_options.log && _matcher) {
-        const s = _matcher.stats();
-        fwLog('[securenow] Firewall: synced %d blocked IPs (%d exact + %d CIDR ranges)', s.total, s.exact, s.cidr);
-      }
+      _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 (enforcement pending SDK phase 2)', _rateLimitRules.length);
+        fwLog('[securenow] Firewall: synced %d rate-limit rules', _rateLimitRules.length);
       }
     });
   }
@@ -814,7 +891,7 @@ function rulePathMatches(rule, path) {
   if (mode === 'regex') {
     try { return new RegExp(pattern).test(path); } catch (_) { return false; }
   }
-  return path.startsWith(pattern);
+  return path.startsWith(normalizePrefixPattern(pattern));
 }
 
 function rateLimitKey(rule, ip) {
@@ -823,6 +900,28 @@ function rateLimitKey(rule, 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();
@@ -918,6 +1017,24 @@ function firewallRequestHandler(req, res) {
     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;
+  }
+
   const rateLimitDecision = checkRateLimitRules(req, ip);
   if (rateLimitDecision) {
     _stats.rateLimited++;
@@ -981,10 +1098,15 @@ function patchHttpLayer() {
 
 // Init
 
-function init(options) {
-  _options = options;
+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();
@@ -1043,8 +1165,11 @@ function shutdown() {
   _consecutiveErrors = 0;
   _pollInflight = false;
   _retryAfterUntil = 0;
+  _localhostFallbackTried = false;
+  _blocklistRules = [];
   _rateLimitRules = [];
   _rateLimitBuckets = new Map();
+  _remainingApiUrlFallbacks = [];
 
   _httpAgent.destroy();
   _httpsAgent.destroy();
@@ -1067,8 +1192,9 @@ function shutdown() {
 
 function getStats() {
   return {
-    ..._stats,
+    ..._stats,
     matcher: _matcher ? _matcher.stats() : null,
+    blocklistRules: _blocklistRules.length,
     allowlistMatcher: _allowlistMatcher ? _allowlistMatcher.stats() : null,
     rateLimitRules: _rateLimitRules.length,
     rateLimitBuckets: _rateLimitBuckets.size,
@@ -1087,7 +1213,8 @@ function getStats() {
 // 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; }
 
-module.exports = { init, shutdown, getStats, getMatcher, getAllowlistMatcher, getRateLimitRules, isRemoteEnabled };
+module.exports = { init, shutdown, getStats, getMatcher, getAllowlistMatcher, getBlocklistRules, getRateLimitRules, isRemoteEnabled };

package/mcp/catalog.js

@@ -10,14 +10,15 @@ const MARKDOWN = 'text/markdown';
 const UNIVERSAL_SECURENOW_SETUP_PROMPT = `You are working in an existing JavaScript or TypeScript app. Set up SecureNow end-to-end for the framework/runtime already used by this repo. Treat this as a real onboarding, not just a package install.
 
 Primary goals:
-- Use the latest published SecureNow npm package. Require securenow@7.5.1 or newer.
+- Use the latest published SecureNow npm package. Require securenow@7.8.0 or newer for split admin/runtime credentials.
 - By default, enable tracing, logs, POST request body capture, multipart metadata capture, and the SecureNow firewall.
 - If I explicitly ask for firewall-only mode, keep the same install/login/verification gates, but use firewall-only preload and do not add tracing, logging, or OTel instrumentation.
-- The firewall must protect the selected SecureNow app, use SecureNow's own blocklist/allowlist/IPDB data, and respect that app's SecureNow IPDB confidence threshold. Do not add custom IP reputation providers or custom auto-blocking.
+- The firewall must protect the selected SecureNow app, use SecureNow's own blocklist/allowlist/IPDB data, and respect that app's SecureNow IPDB confidence threshold. Do not add custom IP reputation providers or custom auto-blocking.
+- Do not confuse IP Allowlist with Trusted IPs. IP Allowlist is restrictive deny-by-default: when any allowlist entry exists for an app/environment, only listed IPs can reach it and all other IPs are blocked. Use Trusted IPs for known-safe monitors, office/VPN traffic, or false-positive suppression. Only use allowlist after explicit human approval to lock the app/environment to known IPs.
 
 Safety rules:
-- Do not print full API keys, JWTs, tokens, or .securenow/credentials.json. Mask secrets.
-- Do not commit secrets. Ignore only local SecureNow credential files (.securenow/credentials.json and .securenow/credentials.*.json); keep the .securenow/ directory itself trackable for repo-owned docs/templates.
+- Do not print full API keys, JWTs, tokens, or local SecureNow credential files (.securenow/admin.json, .securenow/runtime.json, legacy .securenow/credentials.json, or .securenow/credentials.*.json). Mask secrets.
+- Do not commit secrets. Ignore only local SecureNow credential files (.securenow/admin.json, .securenow/runtime.json, .securenow/credentials.json, and .securenow/credentials.*.json); keep the .securenow/ directory itself trackable for repo-owned docs/templates.
 - Do not manually browse to a SecureNow auth URL. Always start auth with npx securenow login so the CLI generates the required callback and state.
 - If the browser says "Missing callback parameter", you opened the wrong URL: rerun npx securenow login from the project root.
 - Do not skip login, app selection, firewall connection, or verification unless I explicitly say to.
@@ -31,33 +32,35 @@ Runbook:
 2. Install or upgrade SecureNow with the detected package manager, using securenow@latest. Verify the actual installed version with:
    node -p "require('./node_modules/securenow/package.json').version"
    npx securenow version
-   Stop and fix the install if either is below 7.5.1 or npx still resolves an older local package.
+   Stop and fix the install if either is below 7.8.0 or npx still resolves an older local package.
 3. Read the installed package surface before editing files: node_modules/securenow/package.json, README/NPM_README, SKILL-API, SKILL-CLI, npx securenow help, and relevant subcommand help for login/init/firewall/doctor/env/test-span/log/mcp.
-4. Mandatory auth gate:
-   - Run npx securenow whoami from the project root.
-   - If not logged in, run npx securenow login from the project root and wait for the browser flow.
-   - After the CLI exits, rerun npx securenow whoami.
-   - Do not proceed to app edits or verification until whoami succeeds.
+4. Mandatory auth/runtime gate:
+   - Run npx securenow whoami from the project root.
+   - If admin auth is missing, run npx securenow admin login from the project root and wait for the browser flow.
+   - If runtime app config is missing, run npx securenow app connect from the project root and wait for the browser flow.
+   - After the CLI exits, rerun npx securenow whoami.
+   - Do not proceed to app edits or verification until whoami shows the required lane(s). SDK setup needs runtime app config; admin/global MCP operations need admin auth.
 5. Validate project-local credentials without exposing secrets:
-   - Confirm .securenow/credentials.json exists.
-   - Confirm it has SecureNow's default config/explanations block.
-   - Confirm it has an app key/name/instance and a firewall API key after login/app selection.
-   - Confirm .securenow/credentials.json and any .securenow/credentials.*.json runtime files are ignored by git, without ignoring the entire .securenow/ directory.
-6. Run npx securenow init. If it fails with ui.header is not a function or another CLI bug, upgrade to securenow@latest, verify >=7.5.1, and retry. Do not silently ignore init failures.
+   - Confirm .securenow/runtime.json exists for SDK runtime setup, or legacy .securenow/credentials.json exists for old installs.
+   - Confirm the runtime file has SecureNow's default config/explanations block.
+   - Confirm the runtime file has an app key/name/instance and a firewall API key after app selection.
+   - Confirm .securenow/admin.json exists only when admin CLI/MCP auth is needed.
+   - Confirm .securenow/admin.json, .securenow/runtime.json, legacy .securenow/credentials.json, and any .securenow/credentials.*.json runtime files are ignored by git, without ignoring the entire .securenow/ directory.
+6. Run npx securenow init. If it fails with ui.header is not a function or another CLI bug, upgrade to securenow@latest, verify >=7.8.0, and retry. Do not silently ignore init failures.
 7. Configure the least invasive framework-specific integration:
    - Next.js: preserve instrumentation.js/ts. Register securenow/nextjs only when NEXT_RUNTIME is nodejs. In ESM files, use createRequire before require("securenow/nextjs"). Include require("securenow/nextjs-auto-capture") for body capture. For Next 15+, add securenow to serverExternalPackages. For older Next.js, use experimental.serverComponentsExternalPackages. Preserve proxy.js/middleware.js.
    - Nuxt/Nitro: use the documented securenow/nuxt module or Nitro server plugin.
    - Express/Fastify/NestJS/Koa/Hapi/Hono/raw Node: preload securenow/register through existing scripts, NODE_OPTIONS, PM2 node_args, Docker CMD, or the process manager already used.
    - Firewall-only: preload securenow/firewall-only or use the documented securenow run --firewall-only command. Do not add OTel/tracing/logging in this mode.
    - Vite/browser-only: use only documented browser integration and state that server firewall protection requires a server runtime.
-8. Do not create or require a .env file for local development or production. The SDK reads defaults from .securenow/credentials.json:
+8. Do not create or require a .env file for local development or production. The SDK reads defaults from .securenow/runtime.json, with legacy .securenow/credentials.json and generated runtime credential files still supported:
    - config.logging.enabled: true
    - config.capture.body: true
    - config.capture.multipart: true
    - config.firewall.enabled: true
    - config.firewall.failMode: "open"
    - config.capture.maxBodySize: 10240
-   For production, run npx securenow credentials runtime --env production, store the resulting JSON as a deployment secret file, and mount/copy it to <app-root>/.securenow/credentials.json. Do not recommend env vars unless the user explicitly asks for legacy fallbacks.
+   For production, run npx securenow credentials runtime --env production, store the resulting JSON as a deployment secret file, and mount/copy it to <app-root>/.securenow/credentials.json or <app-root>/.securenow/credentials.production.json. Do not recommend env vars unless the user explicitly asks for legacy fallbacks.
    Local credentials should use config.runtime.deploymentEnvironment="local". Production runtime credentials should use "production". The app key stays the same; traces, logs, firewall status, forensics, and CLI/MCP queries are scoped by environment.
 9. Verify firewall and threshold:
    - Run npx securenow firewall apps and npx securenow firewall status.
@@ -1108,19 +1111,22 @@ const TOOLS = [
   {
     name: 'securenow_blocklist_add',
     title: 'Add Blocked IP',
-    description: 'Add an IP/CIDR to the blocklist. Write action; requires confirmation.',
+    description: 'Add an IP/CIDR to the blocklist, optionally scoped to a route/method. Write action; requires confirmation.',
     scope: 'blocklist:write',
     readOnly: false,
     confirm: true,
     method: 'POST',
     endpoint: '/blocklist',
-    bodyFields: ['ip', 'reason', 'expiresAt', 'metadata', 'appKey', 'environment'],
+    bodyFields: ['ip', 'reason', 'expiresAt', 'metadata', 'appKey', 'environment', 'pathPattern', 'pathMatchMode', 'method'],
     inputSchema: objectSchema({
       ip: string('IPv4 address or CIDR.'),
       reason: string('Reason for blocking.'),
       expiresAt: string('Optional expiry time as ISO 8601.'),
       metadata: { type: 'object', additionalProperties: true, description: 'Optional metadata.' },
       appKey: string('Optional application key to scope this block. Omit for all apps.'),
+      pathPattern: string('Optional route/path pattern, for example /admin*. Omit to block all routes.'),
+      pathMatchMode: { type: 'string', enum: ['exact', 'prefix', 'regex'], description: 'Path matching mode. Defaults to prefix.' },
+      method: { type: 'string', enum: ['ALL', 'GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'], description: 'HTTP method scope. Defaults to ALL.' },
       ...environmentInput,
       ...confirmSchema,
     }, ['ip', 'confirm', 'reason']),
@@ -1169,8 +1175,8 @@ const TOOLS = [
   },
   {
     name: 'securenow_allowlist_list',
-    title: 'List Allowlist',
-    description: 'List allowed IPs.',
+    title: 'List Restrictive Allowlist',
+    description: 'List restrictive allowlist entries. If any active entry exists for an app/environment, only listed IPs can reach it and all other IPs are blocked. This is not the Trusted IP list.',
     scope: 'allowlist:read',
     readOnly: true,
     method: 'GET',
@@ -1184,24 +1190,26 @@ const TOOLS = [
   },
   {
     name: 'securenow_allowlist_add',
-    title: 'Add Allowed IP',
-    description: 'Add an IP/CIDR to the allowlist. Write action; requires confirmation.',
+    title: 'Add Restrictive Allowlist IP',
+    description: 'Dangerous production action: add an IP/CIDR to the restrictive allowlist. Once active, allowlist mode blocks every IP except listed entries. Do not use this to mark an IP trusted or suppress false positives; use securenow_trusted_add instead. Requires explicit human approval confirming deny-all behavior.',
     scope: 'allowlist:write',
     readOnly: false,
     confirm: true,
     method: 'POST',
     endpoint: '/allowlist',
-    bodyFields: ['ip', 'label', 'reason', 'expiresAt', 'applicationsAll', 'applicationKeys', 'environment'],
+    fixedBody: { initiatedBy: 'mcp' },
+    bodyFields: ['ip', 'label', 'reason', 'expiresAt', 'applicationsAll', 'applicationKeys', 'environment', 'allowlistDenyAllApproved'],
     inputSchema: objectSchema({
       ip: string('IPv4 address or CIDR.'),
       label: string('Human-readable label.'),
-      reason: string('Reason for allowing.'),
+      reason: string('Required human-approved reason. Must acknowledge that allowlist blocks all non-listed IPs and why Trusted IPs is not the correct action.'),
       expiresAt: string('Optional expiry time as ISO 8601.'),
       applicationsAll: boolean('Apply to all applications.'),
       applicationKeys: arrayOfStrings('Application keys to scope this allowlist entry to.'),
+      allowlistDenyAllApproved: boolean('Must be true only after the user explicitly approves deny-by-default allowlist behavior. Do not set this for trusted IPs, monitors, false positives, or investigation cleanup.'),
       ...environmentInput,
       ...confirmSchema,
-    }, ['ip', 'confirm', 'reason']),
+    }, ['ip', 'confirm', 'reason', 'allowlistDenyAllApproved']),
   },
   {
     name: 'securenow_allowlist_remove',
@@ -1221,7 +1229,7 @@ const TOOLS = [
   {
     name: 'securenow_trusted_list',
     title: 'List Trusted IPs',
-    description: 'List trusted IPs.',
+    description: 'List trusted IPs. Trusted IPs are for known-safe traffic and do not turn on deny-by-default allowlist mode.',
     scope: 'trusted_ips:read',
     readOnly: true,
     method: 'GET',
@@ -1235,7 +1243,7 @@ const TOOLS = [
   {
     name: 'securenow_trusted_add',
     title: 'Add Trusted IP',
-    description: 'Add a trusted IP/CIDR. Write action; requires confirmation.',
+    description: 'Add a trusted IP/CIDR for known-safe infrastructure, monitors, office/VPN traffic, or scoped false-positive suppression. This does not enable deny-by-default allowlist mode and is the correct tool when an IP should be trusted without blocking other visitors. Write action; requires confirmation.',
     scope: 'trusted_ips:write',
     readOnly: false,
     confirm: true,
@@ -1417,7 +1425,7 @@ function promptMessages(name, args = {}) {
             'Verify SecureNow default-on protection for this project.',
             args.appKey ? `App key: ${args.appKey}` : null,
             'Check npx securenow whoami, npx securenow api-key show, npx securenow firewall apps, and npx securenow firewall status.',
-            'Confirm traces, logs, capture.body, capture.multipart, and firewall.enabled are enabled by .securenow/credentials.json defaults unless explicitly set false.',
+            'Confirm traces, logs, capture.body, capture.multipart, and firewall.enabled are enabled by .securenow/runtime.json defaults unless explicitly set false. Legacy .securenow/credentials.json is still accepted.',
             'Do not print full tokens or API keys.',
           ].filter(Boolean).join('\n'),
         },
@@ -1436,7 +1444,7 @@ function promptMessages(name, args = {}) {
             args.appKeys ? `Scope to app keys: ${args.appKeys}` : null,
             `Environment scope: ${args.environment || 'production'}.`,
             'Use IP intelligence first, then related traces/logs, then recommend remediation.',
-            'Only block, allow, or trust the IP after explicit user confirmation.',
+            'Only block or trust the IP after explicit user confirmation. Never use IP Allowlist for false positives or trusted traffic; allowlist is deny-by-default and blocks all non-listed IPs.',
           ].filter(Boolean).join('\n'),
         },
       },
@@ -1461,6 +1469,7 @@ function promptMessages(name, args = {}) {
             'Return one clear outcome: Block IP, Rate Limit, False Positive, Rule Tuning Needed, or Ambiguous. If evidence is ambiguous, stop and explain what is missing.',
             'Use rate limiting only as temporary soft remediation for repeated route-specific abuse such as login brute force, credential stuffing, scraping/API bursts, enumeration, recon/probing, or repeated noisy payloads where risk/impact evidence is below the block threshold.',
             'Do not rate-limit instead of blocking when there is confirmed exploit success, token/data exposure, SSRF reachability, file read, RCE, persistence, malware/C2, or riskScore >= 85 with high-confidence malicious evidence. Do not rate-limit benign false positives, trusted monitors, app-server/proxy attribution problems, isolated one-off requests, or broad noisy rules that need alert tuning.',
+            'Do not create or recommend IP Allowlist entries during investigations unless the user explicitly asks to lock the app/environment to a known set of IPs. For safe monitors, offices, VPNs, or false positives, use Trusted IPs or scoped false-positive exclusions instead.',
             confirmWrites
               ? 'The user requested execution. If evidence supports the decision, call securenow_human_action_block, securenow_rate_limit_create_from_text plus securenow_human_action_decision_report_add(outcome=rate_limited), or securenow_human_action_false_positive with confirm:true, a precise reason, and a decisionReport containing summary, evidence, reviewedHistory, traceIds, and missingProof when relevant. If you skip/mark ambiguous but still need to record the audit trail, call securenow_human_action_decision_report_add.'
               : 'Do not execute write tools yet. Prepare the recommended decision and exact tool call the user can approve.',
@@ -1487,6 +1496,7 @@ function promptMessages(name, args = {}) {
             'For each row choose exactly one outcome: Block IP, Rate Limit, False Positive, Rule Tuning Needed, or Skip because evidence is insufficient. Explain skipped rows.',
             'Use Rate Limit only for repeated route-specific abuse where temporary friction is safer than blocking: login brute force/credential stuffing, password reset/account enumeration, scraping/API bursts, path or ID enumeration, recon/probing, or repeated noisy payloads without confirmed exploit success.',
             'Do not rate-limit confirmed high-risk attacks that should be blocked, benign traffic that should be false-positive scoped, broad noisy rules that need tuning, app-server/proxy attribution problems, or isolated one-off requests.',
+            'Do not create or recommend IP Allowlist entries while working this queue unless the user explicitly approves deny-by-default allowlist mode for the whole app/environment. Use Trusted IPs for trusted/bypass cases.',
             confirmWrites
               ? 'The user requested execution. For supported decisions, call the correct write tool with confirm:true, a precise reason, and a decisionReport containing summary, evidence, reviewedHistory, traceIds, and missingProof when relevant, then continue. For skipped/ambiguous/rule-tuning-needed rows that should be auditable without changing IP status, use securenow_human_action_decision_report_add.'
               : 'Do not execute write tools yet. Produce a row-by-row action plan and exact MCP write calls for user approval.',
@@ -1595,6 +1605,9 @@ function assertConfirmed(tool, args = {}) {
   if (!args.reason || !String(args.reason).trim()) {
     throw new Error(`${tool.name} requires a non-empty reason.`);
   }
+  if (tool.name === 'securenow_allowlist_add' && args.allowlistDenyAllApproved !== true) {
+    throw new Error('securenow_allowlist_add is deny-by-default: it blocks every non-listed IP for the scoped app/environment. Pass allowlistDenyAllApproved:true only after explicit human approval. Use securenow_trusted_add for trusted IPs or false positives.');
+  }
 }
 
 function buildApiRequest(tool, rawArgs = {}) {