securenow 5.14.0 → 5.15.0

package/NPM_README.md

@@ -3,15 +3,18 @@
 OpenTelemetry instrumentation library for Node.js, Next.js, and Nuxt applications. Send distributed traces and logs to any OTLP-compatible observability backend.
 
 **Features:**
-- 🚀 Zero-config automatic instrumentation
-- 📊 Distributed tracing for all popular frameworks
-- 📋 Automatic logging with console instrumentation
-- 🔐 Built-in sensitive data redaction
-- 🎯 Request body capture for debugging
-- 🛡️ Multi-layer firewall — auto-blocks IPs from your SecureNow blocklist
-- 🔧 Fully configurable via environment variables
-- 🖥️ Single `-r securenow/register` flag — works for both CJS and ESM apps
-- 🟢 Native Nuxt 3 module (`securenow/nuxt`)
+- Zero-config automatic instrumentation
+- Distributed tracing for all popular frameworks
+- Automatic logging with console instrumentation
+- Built-in sensitive data redaction
+- Request body capture for debugging
+- Multi-layer firewall -- auto-blocks IPs from your SecureNow blocklist
+- `withSecureNow()` config wrapper for Next.js -- eliminates manual `serverExternalPackages`
+- `securenow init` CLI scaffolds instrumentation files for any framework
+- `securenow/firewall-only` entry point for firewall without tracing overhead
+- Fully configurable via environment variables
+- Single `-r securenow/register` flag -- works for both CJS and ESM apps
+- Native Nuxt 3 module (`securenow/nuxt`)
 
 ---
 
@@ -19,7 +22,7 @@ OpenTelemetry instrumentation library for Node.js, Next.js, and Nuxt application
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [CLI — Command Line Interface](#cli--command-line-interface)
+- [CLI -- Command Line Interface](#cli--command-line-interface)
 - [Framework-Specific Setup](#framework-specific-setup)
   - [Express.js](#expressjs)
   - [Next.js](#nextjs)
@@ -28,7 +31,7 @@ OpenTelemetry instrumentation library for Node.js, Next.js, and Nuxt application
   - [NestJS](#nestjs)
   - [Koa](#koa)
   - [Hapi](#hapi)
-- [Firewall — Automatic IP Blocking](#firewall--automatic-ip-blocking)
+- [Firewall -- Automatic IP Blocking](#firewall--automatic-ip-blocking)
 - [Environment Variables Reference](#environment-variables-reference)
 - [Logging Setup](#logging-setup)
 - [Request Body Capture](#request-body-capture)
@@ -54,7 +57,23 @@ yarn add securenow
 
 ## Quick Start
 
-### 1. Set Environment Variables
+### 1. Automatic Setup (Recommended)
+
+Run the init command after installing:
+
+```bash
+npx securenow init --key snk_live_abc123...
+```
+
+This detects your framework and:
+- **Next.js**: Creates `instrumentation.ts`, suggests `withSecureNow()` for `next.config.js`
+- **Nuxt 3**: Suggests adding `securenow/nuxt` to modules
+- **Express / Node.js**: Shows how to add `-r securenow/register` to your start script
+- **All**: Writes `SECURENOW_API_KEY` to `.env.local` when `--key` is provided
+
+### 2. Manual Setup
+
+#### Set Environment Variables
 
 ```bash
 # Required: Your application identifier
@@ -65,11 +84,14 @@ export SECURENOW_INSTANCE=http://your-otlp-collector:4318
 
 # Optional: Enable logging
 export SECURENOW_LOGGING_ENABLED=1
+
+# Optional: Enable the firewall (set your API key)
+export SECURENOW_API_KEY=snk_live_abc123...
 ```
 
-### 2. Run Your Application
+#### Run Your Application
 
-Add `-r securenow/register` to your start command — that's the only change:
+Add `-r securenow/register` to your start command -- that's the only change:
 
 ```bash
 node -r securenow/register app.js
@@ -106,15 +128,16 @@ const app = express();
 You'll see confirmation in the console:
 
 ```
-[securenow] OTel SDK started → http://your-otlp-collector:4318/v1/traces
-[securenow] 📝 Request body capture: ENABLED
+[securenow] OTel SDK started -> http://your-otlp-collector:4318/v1/traces
+[securenow] Firewall: ENABLED
+[securenow] Firewall: synced 142 blocked IPs (138 exact + 4 CIDR ranges)
 ```
 
 ---
 
-## CLI — Command Line Interface
+## CLI -- Command Line Interface
 
-The `securenow` CLI gives you full access to the SecureNow platform from the terminal — no browser required for day-to-day workflows. Zero additional dependencies.
+The `securenow` CLI gives you full access to the SecureNow platform from the terminal -- no browser required for day-to-day workflows. Zero additional dependencies.
 
 ### Getting Started
 
@@ -129,6 +152,18 @@ npx securenow login --token <YOUR_JWT>
 npx securenow whoami
 ```
 
+### Project Setup
+
+```bash
+# Auto-detect framework and scaffold instrumentation files
+npx securenow init
+
+# Pass your API key to auto-write it to .env.local
+npx securenow init --key snk_live_abc123...
+```
+
+For Next.js projects, `init` creates `instrumentation.ts` (or `.js` if no TypeScript) and tells you how to update `next.config.js` with `withSecureNow()`. For Nuxt, it suggests adding `securenow/nuxt` to your modules. For Express/Node, it shows the `-r securenow/register` flag.
+
 ### Managing Applications
 
 ```bash
@@ -213,7 +248,7 @@ npx securenow alerts history --limit 20
 ### IP Intelligence & Blocklist
 
 ```bash
-# Look up any IP — geo, abuse score, verdict, risk factors
+# Look up any IP -- geo, abuse score, verdict, risk factors
 npx securenow ip 203.0.113.42
 
 # Show traces from a specific IP
@@ -233,7 +268,7 @@ npx securenow trusted remove <id>
 
 ### Forensic Queries
 
-Ask questions in plain English — the AI translates them to SQL and runs them against your data.
+Ask questions in plain English -- the AI translates them to SQL and runs them against your data.
 
 ```bash
 # Run a forensic query
@@ -296,14 +331,6 @@ Config files are stored in `~/.securenow/`:
 | `config.json` | API URL, default app, output format |
 | `credentials.json` | Auth token (file permissions: 0600) |
 
-### Initialize Instrumentation
-
-```bash
-# Interactive setup — creates instrumentation files for Next.js
-npx securenow init
-npx securenow init --ts --src --force
-```
-
 ### Global Flags
 
 Every command supports these flags:
@@ -344,6 +371,7 @@ fi
 
 | Category | Command | Description |
 |----------|---------|-------------|
+| **Setup** | `init` | Auto-scaffold instrumentation for your framework |
 | **Auth** | `login` | Authenticate via browser or `--token` |
 | | `logout` | Clear credentials |
 | | `whoami` | Show session info |
@@ -389,7 +417,6 @@ fi
 | | `config get` | Show config |
 | | `config set <k> <v>` | Set config value |
 | | `config path` | Config file paths |
-| | `init` | Setup instrumentation |
 | | `version` | Show version |
 
 ---
@@ -439,6 +466,7 @@ module.exports = {
     env: {
       SECURENOW_APPID: 'your-app-key',
       SECURENOW_INSTANCE: 'https://freetrial.securenow.ai:4318',
+      SECURENOW_API_KEY: 'snk_live_abc123...',
       SECURENOW_LOGGING_ENABLED: '1',
       SECURENOW_NO_UUID: '1',
       SECURENOW_CAPTURE_BODY: '1',
@@ -447,6 +475,8 @@ module.exports = {
 };
 ```
 
+> **Important:** Always use `node_args: '-r securenow/register'` in PM2 configs. Without it, PM2 restarts won't load the SDK, and the firewall won't activate.
+
 ---
 
 ### Fastify
@@ -476,7 +506,7 @@ fastify.listen({ port: 3000 }, (err) => {
 });
 ```
 
-> **Important:** Set `SECURENOW_CAPTURE_BODY=0` with Fastify — the body capture hook conflicts with Fastify's internal stream handling.
+> **Important:** Set `SECURENOW_CAPTURE_BODY=0` with Fastify -- the body capture hook conflicts with Fastify's internal stream handling.
 
 ---
 
@@ -519,7 +549,7 @@ app.listen(3000, () => console.log('Koa running on port 3000'));
 npm install securenow @nestjs/core @nestjs/common reflect-metadata ts-node typescript
 ```
 
-NestJS uses TypeScript — securenow is loaded via `-r` flags instead of in-code `require()`:
+NestJS uses TypeScript -- securenow is loaded via `-r` flags instead of in-code `require()`:
 
 ```typescript
 // app.ts
@@ -599,7 +629,7 @@ const init = async () => {
 init().catch((err) => { console.error(err); process.exit(1); });
 ```
 
-> **Important:** Set `SECURENOW_CAPTURE_BODY=0` with Hapi — the body capture hook consumes the request stream before Hapi's payload parser.
+> **Important:** Set `SECURENOW_CAPTURE_BODY=0` with Hapi -- the body capture hook consumes the request stream before Hapi's payload parser.
 
 ---
 
@@ -642,7 +672,7 @@ http.createServer(toNodeListener(app)).listen(3000, () => {
 npm install securenow polka
 ```
 
-Polka is minimalist — no built-in body parser:
+Polka is minimalist -- no built-in body parser:
 
 ```javascript
 // app.js
@@ -719,7 +749,7 @@ http.createServer(handler).listen(3000, () => console.log('HTTP running on port
 npm install securenow hono @hono/node-server
 ```
 
-Hono uses ESM — preload via `-r` flag (the ESM hook is auto-registered on Node >=20.6):
+Hono uses ESM -- preload via `-r` flag (the ESM hook is auto-registered on Node >=20.6):
 
 ```javascript
 // app.mjs
@@ -753,7 +783,7 @@ node -r securenow/register app.mjs
 npm install securenow @feathersjs/feathers @feathersjs/express @feathersjs/errors
 ```
 
-Feathers uses Express transport — same setup as Express:
+Feathers uses Express transport -- same setup as Express:
 
 ```javascript
 // app.js
@@ -788,27 +818,101 @@ app.listen(3000, () => console.log('Feathers running on port 3000'));
 
 ### Next.js
 
-See [Next.js Complete Guide →](./docs/NEXTJS-SETUP-COMPLETE.md)
+See [Next.js Complete Guide](./docs/NEXTJS-SETUP-COMPLETE.md) for the full reference.
+
+#### Option A: `withSecureNow()` wrapper (v5.13.0+ -- Recommended)
+
+One wrapper handles everything: `serverExternalPackages` (Next 15) or `experimental.serverComponentsExternalPackages` (Next 14), `instrumentationHook`, and webpack warning suppression.
+
+**1. Update `next.config.js`:**
+
+```javascript
+const { withSecureNow } = require('securenow/nextjs-webpack-config');
+
+module.exports = withSecureNow({
+  // your existing config -- reactStrictMode, images, rewrites, etc.
+});
+```
 
-Create `instrumentation.ts` in your project root:
+**2. Create `instrumentation.ts` (or `.js`):**
 
 ```typescript
 export async function register() {
   if (process.env.NEXT_RUNTIME === 'nodejs') {
-    await import('securenow/register');
+    const { registerSecureNow } = require('securenow/nextjs');
+    registerSecureNow();
   }
 }
 ```
 
-`.env.local`:
+Or run `npx securenow init` to auto-generate this file.
+
+**3. Set environment variables in `.env.local`:**
 
 ```env
 SECURENOW_APPID=my-nextjs-app
 SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+SECURENOW_API_KEY=snk_live_abc123...
 SECURENOW_LOGGING_ENABLED=1
 SECURENOW_NO_UUID=1
 ```
 
+That's it. `withSecureNow()` auto-detects your Next.js version and configures:
+- **Next.js 15+**: Sets `serverExternalPackages` with all 13 required OTel packages
+- **Next.js 14**: Sets `experimental.serverComponentsExternalPackages` and `experimental.instrumentationHook: true`
+- **Both**: Suppresses webpack warnings from OpenTelemetry instrumentation packages
+
+#### Option B: Manual configuration
+
+If you prefer not to use the wrapper, manually add the packages:
+
+```javascript
+// next.config.js (Next.js 15+)
+module.exports = {
+  serverExternalPackages: [
+    'securenow',
+    '@opentelemetry/sdk-node',
+    '@opentelemetry/auto-instrumentations-node',
+    '@opentelemetry/instrumentation-http',
+    '@opentelemetry/exporter-trace-otlp-http',
+    '@opentelemetry/exporter-logs-otlp-http',
+    '@opentelemetry/sdk-logs',
+    '@opentelemetry/instrumentation',
+    '@opentelemetry/resources',
+    '@opentelemetry/semantic-conventions',
+    '@opentelemetry/api',
+    '@opentelemetry/api-logs',
+    '@vercel/otel',
+  ],
+};
+```
+
+```javascript
+// next.config.js (Next.js 14)
+module.exports = {
+  experimental: {
+    instrumentationHook: true,
+    serverComponentsExternalPackages: [
+      'securenow',
+      '@opentelemetry/sdk-node',
+      '@opentelemetry/auto-instrumentations-node',
+      '@opentelemetry/instrumentation-http',
+      '@opentelemetry/exporter-trace-otlp-http',
+      '@opentelemetry/exporter-logs-otlp-http',
+      '@opentelemetry/sdk-logs',
+      '@opentelemetry/instrumentation',
+      '@opentelemetry/resources',
+      '@opentelemetry/semantic-conventions',
+      '@opentelemetry/api',
+      '@opentelemetry/api-logs',
+      '@vercel/otel',
+    ],
+  },
+};
+```
+
+**Why is this needed?** Next.js bundles server code with webpack, which breaks OpenTelemetry's dynamic `require()` calls and monkey-patching. Externalizing these packages keeps them as normal Node.js `require()` calls at runtime. The `withSecureNow()` wrapper handles this automatically.
+
 ---
 
 ### Nuxt 3
@@ -830,9 +934,10 @@ export default defineNuxtConfig({
 ```env
 SECURENOW_APPID=my-nuxt-app
 SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+SECURENOW_API_KEY=snk_live_abc123...
 ```
 
-That's it — the Nuxt module handles OTel SDK initialization, Nitro externalization, and request tracing automatically. Optional config:
+That's it -- the Nuxt module handles OTel SDK initialization, Nitro externalization, firewall activation, and request tracing automatically. Optional config:
 
 ```typescript
 export default defineNuxtConfig({
@@ -845,30 +950,32 @@ export default defineNuxtConfig({
 });
 ```
 
+The Nuxt server plugin (v5.13.0+) initializes the firewall independently from OpenTelemetry, so IP blocking works even if tracing encounters an error.
+
 ---
 
 ### Compatibility Matrix
 
-| Framework | Traces | Logs | Body Capture | Notes |
-|-----------|--------|------|--------------|-------|
-| Express | Yes | Yes | Yes | Fully compatible |
-| Fastify | Yes | Yes | **No** | `SECURENOW_CAPTURE_BODY=0` required |
-| Koa | Yes | Yes | Yes | Needs `koa-bodyparser` |
-| NestJS | Yes | Yes | Yes | Use `-r ts-node/register` |
-| Hapi | Yes | Yes | **No** | `SECURENOW_CAPTURE_BODY=0` required |
-| h3 | Yes | Yes | Yes | Uses `toNodeListener()` |
-| Polka | Yes | Yes | Yes | Needs manual body parser |
-| Micro/HTTP | Yes | Yes | Yes | Full control |
-| Hono | Yes | Yes | **No** | `SECURENOW_CAPTURE_BODY=0`; ESM `-r` flag |
-| Feathers | Yes | Yes | Yes | Uses Express transport |
-| Next.js | Yes | Yes | Yes | Use `instrumentation.ts` |
-| Nuxt 3 | Yes | Yes | Yes | Use `securenow/nuxt` module |
+| Framework | Traces | Logs | Body Capture | Firewall | Notes |
+|-----------|--------|------|--------------|----------|-------|
+| Express | Yes | Yes | Yes | Yes | Fully compatible |
+| Fastify | Yes | Yes | **No** | Yes | `SECURENOW_CAPTURE_BODY=0` required |
+| Koa | Yes | Yes | Yes | Yes | Needs `koa-bodyparser` |
+| NestJS | Yes | Yes | Yes | Yes | Use `-r ts-node/register` |
+| Hapi | Yes | Yes | **No** | Yes | `SECURENOW_CAPTURE_BODY=0` required |
+| h3 | Yes | Yes | Yes | Yes | Uses `toNodeListener()` |
+| Polka | Yes | Yes | Yes | Yes | Needs manual body parser |
+| Micro/HTTP | Yes | Yes | Yes | Yes | Full control |
+| Hono | Yes | Yes | **No** | Yes | `SECURENOW_CAPTURE_BODY=0`; ESM `-r` flag |
+| Feathers | Yes | Yes | Yes | Yes | Uses Express transport |
+| Next.js | Yes | Yes | Yes | Yes | Use `instrumentation.ts` + `withSecureNow()` |
+| Nuxt 3 | Yes | Yes | Yes | Yes | Use `securenow/nuxt` module |
 
 ---
 
-## Firewall — Automatic IP Blocking
+## Firewall -- Automatic IP Blocking
 
-SecureNow can automatically block IPs from your blocklist at the application layer. No code changes — just set an API key and the firewall activates.
+SecureNow can automatically block IPs from your blocklist at the application layer. No code changes -- just set an API key and the firewall activates.
 
 ### Enable the Firewall
 
@@ -885,17 +992,70 @@ That's it. On startup, you'll see:
 [securenow] Firewall: synced 142 blocked IPs (138 exact + 4 CIDR ranges)
 ```
 
+### How It Works
+
+The firewall uses a version-based sync protocol for efficiency:
+
+1. **Version check** every 10 seconds (lightweight HEAD-like request with ETag)
+2. **Full blocklist sync** only when the version changes (or every 5 minutes as a safety net)
+3. **In-memory matching** with a pre-compiled set (exact IPs) and sorted CIDR list for sub-millisecond lookups
+4. **Exponential backoff** with jitter when the API is temporarily unreachable
+5. **Allowlist support** -- trusted IPs are never blocked, even if they appear on the blocklist
+6. **Localhost fallback** -- when the configured API URL is unreachable (ECONNREFUSED), the SDK automatically tries `http://localhost:4000` for co-located deployments
+
+After you block an IP in the dashboard or CLI, it typically takes 10-15 seconds to propagate to all running instances.
+
+### Firewall-Only Mode (No Tracing)
+
+If you only need IP blocking without OpenTelemetry tracing overhead, use the standalone entry point:
+
+```bash
+node -r securenow/firewall-only app.js
+```
+
+Or in `package.json`:
+
+```json
+"scripts": {
+  "start": "node -r securenow/firewall-only app.js"
+}
+```
+
+This is useful when:
+- You only need IP blocking, not observability
+- You want to minimize startup time and memory footprint
+- You're adding the firewall to a project that uses a different tracing solution
+- For Next.js, this avoids the need for `serverExternalPackages` entirely
+
+Environment variables for firewall-only mode:
+
+```bash
+SECURENOW_API_KEY=snk_live_abc123...       # Required
+SECURENOW_API_URL=https://api.securenow.ai # Optional (auto-detected)
+SECURENOW_FIREWALL_ENABLED=1               # Default: 1
+SECURENOW_FIREWALL_TCP=1                   # Optional: Layer 2
+SECURENOW_FIREWALL_IPTABLES=1              # Optional: Layer 3
+SECURENOW_FIREWALL_CLOUD=cloudflare        # Optional: Layer 4
+```
+
 ### Blocking Layers
 
-The firewall supports four layers — Layer 1 is always on, the rest are opt-in:
+The firewall supports four layers -- Layer 1 is always on, the rest are opt-in:
 
 | Layer | Env Var | Description |
 |-------|---------|-------------|
-| **Layer 1: HTTP** | *(always on)* | Returns 403 Forbidden. Works with proxy headers. |
-| **Layer 2: TCP** | `SECURENOW_FIREWALL_TCP=1` | `socket.destroy()` — zero bytes sent back |
+| **Layer 1: HTTP** | *(always on)* | Returns 403 Forbidden with a security alert page. Works with proxy headers. |
+| **Layer 2: TCP** | `SECURENOW_FIREWALL_TCP=1` | `socket.destroy()` -- zero bytes sent back |
 | **Layer 3: iptables** | `SECURENOW_FIREWALL_IPTABLES=1` | Kernel-level DROP (Linux, requires root) |
 | **Layer 4: Cloud WAF** | `SECURENOW_FIREWALL_CLOUD=cloudflare` | Pushes to Cloudflare, AWS WAF, or GCP Cloud Armor |
 
+### Blocked Page
+
+When an IP is blocked at Layer 1, the user sees a full-page security alert with:
+- Their detected IP address
+- A warning that malicious activity was detected
+- Contact information (`contact@securenow.ai`) for false positives
+
 ### Get an API Key
 
 ```bash
@@ -967,13 +1127,17 @@ See the [Firewall Guide](./docs/FIREWALL-GUIDE.md) for the full reference.
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `SECURENOW_API_KEY` | API key with `firewall:read` scope. Enables the firewall when set. | - |
-| `SECURENOW_API_URL` | SecureNow API base URL. | `https://api.securenow.ai` |
+| `SECURENOW_API_URL` | SecureNow API base URL. Auto-detected for co-located deployments (falls back to `http://localhost:4000` on ECONNREFUSED). | `https://api.securenow.ai` |
 | `SECURENOW_FIREWALL_ENABLED` | Master kill-switch. Set to `0` to disable. | `1` |
-| `SECURENOW_FIREWALL_SYNC_INTERVAL` | Blocklist refresh interval in seconds. | `60` |
+| `SECURENOW_FIREWALL_VERSION_INTERVAL` | Seconds between version checks (lightweight ETag-based). | `10` |
+| `SECURENOW_FIREWALL_SYNC_INTERVAL` | Full blocklist refresh interval in seconds (safety net). | `300` |
 | `SECURENOW_FIREWALL_FAIL_MODE` | `open` (allow when unavailable) or `closed` (block all). | `open` |
+| `SECURENOW_FIREWALL_STATUS_CODE` | HTTP status code for blocked requests. | `403` |
+| `SECURENOW_FIREWALL_LOG` | Log blocked requests and sync events to console. Set to `0` to silence. | `1` |
 | `SECURENOW_FIREWALL_TCP` | Enable Layer 2 TCP blocking. | `0` |
 | `SECURENOW_FIREWALL_IPTABLES` | Enable Layer 3 iptables blocking. | `0` |
 | `SECURENOW_FIREWALL_CLOUD` | Cloud WAF provider: `cloudflare`, `aws`, or `gcp`. | - |
+| `SECURENOW_FIREWALL_CLOUD_DRY_RUN` | Log cloud pushes without applying changes. | `0` |
 | `SECURENOW_TRUSTED_PROXIES` | Comma-separated trusted proxy IPs. | - |
 
 See [Firewall Guide](./docs/FIREWALL-GUIDE.md) for complete details on all layers.
@@ -993,6 +1157,22 @@ See [Firewall Guide](./docs/FIREWALL-GUIDE.md) for complete details on all layer
 
 ---
 
+## Entry Points Reference
+
+SecureNow provides multiple entry points depending on your needs:
+
+| Entry Point | Usage | Includes Tracing | Includes Firewall | Notes |
+|-------------|-------|-------------------|-------------------|-------|
+| `securenow/register` | `node -r securenow/register app.js` | Yes | Yes | Default -- full tracing + firewall |
+| `securenow/firewall-only` | `node -r securenow/firewall-only app.js` | No | Yes | Firewall only, no OTel overhead |
+| `securenow/nextjs` | `require('securenow/nextjs').registerSecureNow()` | Yes | Yes | Next.js instrumentation hook |
+| `securenow/nuxt` | `modules: ['securenow/nuxt']` | Yes | Yes | Nuxt 3 module |
+| `securenow/nextjs-webpack-config` | `withSecureNow(config)` | - | - | Next.js config wrapper |
+| `securenow/firewall` | `require('securenow/firewall').init({...})` | No | Yes | Programmatic firewall API |
+| `securenow/tracing` | `require('securenow/tracing')` | Yes | No | Programmatic tracing API |
+
+---
+
 ## Logging Setup
 
 ### Automatic Console Logging
@@ -1012,11 +1192,11 @@ console.debug('Debug info');
 ```
 
 **Severity mapping:**
-- `console.log()` → INFO
-- `console.info()` → INFO
-- `console.warn()` → WARN
-- `console.error()` → ERROR
-- `console.debug()` → DEBUG
+- `console.log()` -> INFO
+- `console.info()` -> INFO
+- `console.warn()` -> WARN
+- `console.error()` -> ERROR
+- `console.debug()` -> DEBUG
 
 **Environment variable:**
 ```bash
@@ -1086,11 +1266,11 @@ export SECURENOW_MAX_BODY_SIZE=10240  # 10KB (optional)
 
 ### Multipart Body Capture (v5.8.0+)
 
-Enable with `SECURENOW_CAPTURE_MULTIPART=1` to capture multipart/form-data requests. Uses a streaming parser that never buffers file content — memory stays at ~few KB regardless of upload size.
+Enable with `SECURENOW_CAPTURE_MULTIPART=1` to capture multipart/form-data requests. Uses a streaming parser that never buffers file content -- memory stays at ~few KB regardless of upload size.
 
 **What gets captured:**
-- **Text fields** — field name and value (up to 1000 chars), with sensitive fields auto-redacted
-- **File fields** — metadata only: field name, filename, content-type, and size in bytes
+- **Text fields** -- field name and value (up to 1000 chars), with sensitive fields auto-redacted
+- **File fields** -- metadata only: field name, filename, content-type, and size in bytes
 
 **Example trace attribute:**
 ```json
@@ -1159,6 +1339,12 @@ export SECURENOW_CAPTURE_BODY=1
 export SECURENOW_MAX_BODY_SIZE=20480
 export SECURENOW_SENSITIVE_FIELDS="internal_id,session_key"
 
+# Firewall
+export SECURENOW_API_KEY=snk_live_abc123...
+export SECURENOW_FIREWALL_TCP=1
+export SECURENOW_FIREWALL_VERSION_INTERVAL=10
+export SECURENOW_FIREWALL_SYNC_INTERVAL=300
+
 # Environment
 export NODE_ENV=production
 
@@ -1261,13 +1447,21 @@ const enabled: boolean = isLoggingEnabled();
 // instrumentation.ts
 export async function register() {
   if (process.env.NEXT_RUNTIME === 'nodejs') {
-    process.env.SECURENOW_LOGGING_ENABLED = '1';
-    
-    await import('securenow/register');
+    const { registerSecureNow } = require('securenow/nextjs');
+    registerSecureNow();
   }
 }
 ```
 
+```javascript
+// next.config.js
+const { withSecureNow } = require('securenow/nextjs-webpack-config');
+
+module.exports = withSecureNow({
+  reactStrictMode: true,
+});
+```
+
 ### NestJS with TypeScript
 
 Use `-r securenow/register -r ts-node/register` flags instead of in-code require:
@@ -1316,7 +1510,7 @@ node app.js
 
 Look for lines like:
 ```
-[securenow] OTel SDK started → http://localhost:4318/v1/traces
+[securenow] OTel SDK started -> http://localhost:4318/v1/traces
 ```
 
 **Check 4: Verify initialization order**
@@ -1324,15 +1518,52 @@ Look for lines like:
 SecureNow must be required BEFORE any other modules:
 
 ```javascript
-// ✅ Correct
+// Correct
 require('securenow/register');
 const express = require('express');
 
-// ❌ Wrong - too late!
+// Wrong -- too late!
 const express = require('express');
 require('securenow/register');
 ```
 
+### Firewall Not Blocking IPs
+
+**Check 1: Is `SECURENOW_API_KEY` set?**
+
+```bash
+echo $SECURENOW_API_KEY
+```
+
+**Check 2: Is the IP in the blocklist?**
+
+```bash
+npx securenow blocklist
+npx securenow firewall test-ip 1.2.3.4
+```
+
+**Check 3: Check startup logs for sync status**
+
+You should see:
+```
+[securenow] Firewall: ENABLED
+[securenow] Firewall: synced 142 blocked IPs
+```
+
+If you see `initial sync failed`, check the API URL and key.
+
+**Check 4: Wait for propagation**
+
+After blocking an IP, it takes 10-15 seconds to propagate (one version-check interval).
+
+**Check 5: Are you behind a proxy?**
+
+Set `SECURENOW_TRUSTED_PROXIES` to your proxy's IP so the firewall sees the real client IP.
+
+**Check 6: Using PM2?**
+
+Make sure `node_args: '-r securenow/register'` is in your `ecosystem.config.cjs`. Without it, PM2 restarts skip the SDK entirely.
+
 ### Logs Not Appearing
 
 **Check 1: Is logging enabled?**
@@ -1352,7 +1583,7 @@ require('securenow/register');
 
 You should see:
 ```
-[securenow] 📋 Logging: ENABLED → http://localhost:4318/v1/logs
+[securenow] Logging: ENABLED -> http://localhost:4318/v1/logs
 ```
 
 **Check 4: Verify OTLP logs endpoint**
@@ -1407,22 +1638,24 @@ export SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns,net
 
 ### Next.js Instrumentation Not Working
 
-**Check 1: Verify instrumentation file location**
+**Check 1: Using `withSecureNow()`?**
+
+```javascript
+const { withSecureNow } = require('securenow/nextjs-webpack-config');
+module.exports = withSecureNow({ /* your config */ });
+```
+
+This auto-handles `serverExternalPackages` / `experimental.serverComponentsExternalPackages` and `instrumentationHook` based on your Next.js version.
+
+**Check 2: Verify instrumentation file location**
 
 `instrumentation.ts` or `instrumentation.js` must be in the project root (same level as `app/` or `pages/`).
 
-**Check 2: Enable instrumentation hook**
+**Check 3: Check for OTel MODULE_NOT_FOUND errors**
 
-```javascript
-// next.config.js
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-};
-```
+If you see `MODULE_NOT_FOUND` for `@opentelemetry/*` packages, your `next.config.js` is missing the externalization. Use `withSecureNow()` to fix this automatically.
 
-**Check 3: Restart dev server**
+**Check 4: Restart dev server**
 
 ```bash
 # Kill the server and restart
@@ -1441,12 +1674,12 @@ export SECURENOW_NO_UUID=1
 
 This uses the same service name for all workers.
 
-**Problem: Workers not instrumented**
+**Problem: Workers not instrumented / firewall not active**
 
 **Solution: Use node_args in PM2 config**
 
 ```javascript
-// ecosystem.config.js
+// ecosystem.config.cjs
 module.exports = {
   apps: [{
     name: 'my-app',
@@ -1456,11 +1689,14 @@ module.exports = {
     env: {
       SECURENOW_APPID: 'my-app',
       SECURENOW_INSTANCE: 'http://localhost:4318',
+      SECURENOW_API_KEY: 'snk_live_abc123...',
     }
   }]
 };
 ```
 
+Without `node_args`, PM2 starts your script directly without the securenow preload, so neither tracing nor the firewall will be active.
+
 ---
 
 ## Best Practices
@@ -1470,10 +1706,10 @@ module.exports = {
 Don't hardcode configuration. Use environment variables:
 
 ```javascript
-// ❌ Bad
+// Bad
 process.env.SECURENOW_APPID = 'hardcoded-value';
 
-// ✅ Good - use .env file or export
+// Good -- use .env file or export
 // .env
 SECURENOW_APPID=my-app
 SECURENOW_INSTANCE=http://localhost:4318
@@ -1484,10 +1720,10 @@ SECURENOW_INSTANCE=http://localhost:4318
 Pass objects to console methods for better filtering:
 
 ```javascript
-// ❌ Less useful
+// Less useful
 console.log('User 123 logged in');
 
-// ✅ Better - structured attributes
+// Better -- structured attributes
 console.log('User logged in', {
   userId: 123,
   email: 'user@example.com',
@@ -1517,13 +1753,13 @@ console.debug('Cache hit', { key: 'user:123' });
 Even though SecureNow automatically redacts common sensitive fields, avoid logging:
 
 ```javascript
-// ❌ Bad
+// Bad
 console.log('Login attempt', {
   email: 'user@example.com',
   password: 'secret123', // Will be redacted, but don't log it!
 });
 
-// ✅ Good
+// Good
 console.log('Login attempt', {
   email: 'user@example.com',
   timestamp: Date.now(),
@@ -1594,31 +1830,35 @@ No code changes needed!
 ## Architecture
 
 ```
-┌─────────────────────────────────┐
-│   Your Application              │
-│   (Express/Next.js/etc)         │
-└───────────────┬─────────────────┘
-                │
-                ▼
-┌─────────────────────────────────┐
-│   SecureNow Library             │
-│   - Auto-instrumentation        │
-│   - Console wrapper (optional)  │
-│   - Body capture (optional)     │
-└───────────────┬─────────────────┘
-                │
-                ▼
-┌─────────────────────────────────┐
-│   OpenTelemetry SDK             │
-│   - Trace/Log processors        │
-│   - OTLP exporters              │
-└───────────────┬─────────────────┘
-                │
-                ▼
-┌─────────────────────────────────┐
-│   OTLP Collector/Backend        │
-│   (Your observability platform) │
-└─────────────────────────────────┘
+                    Your Application
+                    (Express/Next.js/etc)
+                           |
+                           v
+              +---------------------------+
+              |     SecureNow Library      |
+              |  +---------------------+  |
+              |  |    Firewall Layer    |  |  <-- Blocks IPs before they reach your app
+              |  +---------------------+  |
+              |  | Auto-instrumentation |  |
+              |  | Console wrapper      |  |
+              |  | Body capture         |  |
+              |  +---------------------+  |
+              +---------------------------+
+                           |
+                 +---------+---------+
+                 |                   |
+                 v                   v
+          +-----------+      +-----------+
+          | OTel SDK  |      | SecureNow |
+          | OTLP      |      | API       |
+          | Exporters |      | (blocklist|
+          +-----------+      |  sync)    |
+                 |           +-----------+
+                 v
+          +-----------+
+          | Your OTLP |
+          | Backend   |
+          +-----------+
 ```
 
 ---
@@ -1629,6 +1869,8 @@ No code changes needed!
 - **Batch export:** Traces and logs are batched before sending
 - **Async processing:** No blocking of application threads
 - **Configurable:** Disable instrumentations you don't need
+- **Firewall:** Sub-millisecond IP lookups using pre-compiled hash sets and sorted CIDR lists
+- **Smart sync:** Version-based polling with ETag/304 eliminates unnecessary data transfer
 
 ---
 
@@ -1636,10 +1878,12 @@ No code changes needed!
 
 - **Automatic redaction** of sensitive fields (passwords, tokens, keys)
 - **Configurable** sensitive field patterns
-- **No data stored** locally - everything sent to your OTLP backend
-- **Multi-layer firewall** — blocks IPs at HTTP, TCP, OS, and cloud-edge levels
+- **No data stored** locally -- everything sent to your OTLP backend
+- **Multi-layer firewall** -- blocks IPs at HTTP, TCP, OS, and cloud-edge levels
 - **API keys** with granular scopes, IP allowlisting, and SHA-256 hashing
-- **Open source** - audit the code yourself
+- **Allowlist support** -- trusted IPs are never blocked
+- **Fail-open by default** -- network issues never accidentally block legitimate traffic
+- **Open source** -- audit the code yourself
 
 ---
 
@@ -1677,4 +1921,4 @@ Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for gu
 
 ---
 
-**Made with ❤️ for the Node.js community**
+**Made with care for the Node.js community**