securenow 5.17.1 → 6.0.0

package/NPM_README.md

@@ -1,1958 +0,0 @@
-# SecureNow - Complete OpenTelemetry Observability for Node.js
-
-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
-- `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`)
-
----
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [CLI -- Command Line Interface](#cli--command-line-interface)
-- [Framework-Specific Setup](#framework-specific-setup)
-  - [Express.js](#expressjs)
-  - [Next.js](#nextjs)
-  - [Nuxt 3](#nuxt-3)
-  - [Fastify](#fastify)
-  - [NestJS](#nestjs)
-  - [Koa](#koa)
-  - [Hapi](#hapi)
-- [Firewall -- Automatic IP Blocking](#firewall--automatic-ip-blocking)
-- [Environment Variables Reference](#environment-variables-reference)
-- [Logging Setup](#logging-setup)
-- [Request Body Capture](#request-body-capture)
-- [Advanced Configuration](#advanced-configuration)
-- [TypeScript Support](#typescript-support)
-- [Troubleshooting](#troubleshooting)
-
----
-
-## Installation
-
-```bash
-npm install securenow
-```
-
-Or with yarn:
-
-```bash
-yarn add securenow
-```
-
----
-
-## Quick Start
-
-### 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
-export SECURENOW_APPID=my-app
-
-# Required: Your OTLP collector endpoint
-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...
-```
-
-#### Run Your Application
-
-Add `-r securenow/register` to your start command -- that's the only change:
-
-```bash
-node -r securenow/register app.js
-```
-
-ESM and CJS apps are both handled automatically (Node >=20.6 auto-registers the ESM loader hook via `module.register()`).
-
-**package.json** example:
-
-```json
-"scripts": {
-  "start": "node -r securenow/register app.js",
-  "dev": "node -r securenow/register --watch app.js"
-}
-```
-
-**Alternative: Use NODE_OPTIONS** so your existing scripts stay unchanged:
-
-```bash
-NODE_OPTIONS="-r securenow/register" npm start
-```
-
-**CJS only: Code-based initialization**
-
-```javascript
-// At the very top of your main file, before any other require
-require('securenow/register');
-
-const express = require('express');
-const app = express();
-// ...
-```
-
-You'll see confirmation in the console:
-
-```
-[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
-
-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
-
-```bash
-# Log in (opens browser for OAuth)
-npx securenow login
-
-# Or use a token for CI/headless environments
-npx securenow login --token <YOUR_JWT>
-
-# Log in for this project only (per-project credentials)
-npx securenow login --local
-
-# Check who you're logged in as (shows auth source)
-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
-# List all applications
-npx securenow apps
-
-# Create a new application
-npx securenow apps create my-production-app --hosts api.example.com,app.example.com
-
-# Get application details (including the app key)
-npx securenow apps info <app-id>
-
-# Set a default app so you don't need --app on every command
-npx securenow apps default <app-key>
-
-# Delete an application
-npx securenow apps delete <app-id> --force
-```
-
-### Viewing Traces
-
-```bash
-# List recent traces (uses default app, or specify --app)
-npx securenow traces
-npx securenow traces --app <key> --limit 50
-
-# Show detailed spans for a trace
-npx securenow traces show <traceId>
-
-# AI-powered security analysis of a trace
-npx securenow traces analyze <traceId>
-```
-
-### Viewing Logs
-
-```bash
-# List recent logs
-npx securenow logs
-npx securenow logs --app <key> --minutes 30 --level error
-
-# Show logs for a specific trace
-npx securenow logs trace <traceId>
-```
-
-### Security Issues
-
-```bash
-# List all issues
-npx securenow issues
-npx securenow issues --status open
-
-# Show issue details with AI analysis
-npx securenow issues show <issue-id>
-
-# Resolve an issue
-npx securenow issues resolve <issue-id>
-```
-
-### Notifications
-
-```bash
-# List notifications
-npx securenow notifications
-
-# Check unread count
-npx securenow notifications unread
-
-# Mark as read
-npx securenow notifications read <id>
-npx securenow notifications read-all
-```
-
-### Alerting
-
-```bash
-# View alert rules, channels, and history
-npx securenow alerts rules
-npx securenow alerts rules show <rule-id>
-npx securenow alerts rules update <rule-id> --applications-all
-npx securenow alerts rules update <rule-id> --apps key1,key2
-npx securenow alerts channels
-npx securenow alerts history --limit 20
-```
-
-### IP Intelligence & Blocklist
-
-```bash
-# Look up any IP -- geo, abuse score, verdict, risk factors
-npx securenow ip 203.0.113.42
-
-# Show traces from a specific IP
-npx securenow ip traces 203.0.113.42
-
-# Manage the blocklist
-npx securenow blocklist
-npx securenow blocklist add 203.0.113.42 --reason "Brute force scanner"
-npx securenow blocklist remove <id>
-npx securenow blocklist stats
-
-# Manage trusted IPs
-npx securenow trusted
-npx securenow trusted add 10.0.0.1 --label "Office VPN"
-npx securenow trusted remove <id>
-```
-
-### Forensic Queries
-
-Ask questions in plain English -- the AI translates them to SQL and runs them against your data.
-
-```bash
-# Run a forensic query
-npx securenow forensics "show top 10 attacking IPs in the last hour"
-npx securenow forensics "which endpoints had 5xx errors today"
-
-# Browse the saved query library
-npx securenow forensics library
-```
-
-### API Map
-
-```bash
-# View all discovered API endpoints
-npx securenow api-map
-
-# API map statistics
-npx securenow api-map stats
-```
-
-### Analytics & Dashboard
-
-```bash
-# Response code analytics
-npx securenow analytics --app <key>
-
-# Full dashboard overview (apps, protection status, unread alerts)
-npx securenow status
-```
-
-### Instances
-
-```bash
-# List ClickHouse instances
-npx securenow instances
-
-# Test an instance connection
-npx securenow instances test <id>
-```
-
-### Configuration
-
-```bash
-# View all config
-npx securenow config get
-
-# Set values
-npx securenow config set apiUrl https://custom-api.example.com
-npx securenow config set defaultApp <app-key>
-npx securenow config set format json
-
-# Show config file paths
-npx securenow config path
-```
-
-Config files are stored in `~/.securenow/` (global) or `.securenow/` in the project root (per-project):
-
-| File | Description |
-|------|-------------|
-| `~/.securenow/config.json` | API URL, default app, output format |
-| `~/.securenow/credentials.json` | Auth token — global (file permissions: 0600) |
-| `.securenow/credentials.json` | Auth token — project-local (use `login --local`) |
-
-**Resolution order:** `SECURENOW_TOKEN` env var → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`.
-
-### Global Flags
-
-Every command supports these flags:
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--json` | `-j` | Output as JSON for scripting and CI/CD |
-| `--help` | | Show help for the command |
-| `--app <key>` | | Override the default application key |
-
-### Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `SECURENOW_TOKEN` | JWT token — overrides all file-based credentials |
-| `SECURENOW_API_URL` | Override the API base URL |
-| `SECURENOW_DEBUG` | Show stack traces on errors |
-| `NO_COLOR` | Disable colored output |
-
-### Multi-Project Sessions
-
-Use `--local` to maintain separate logins per project on the same machine:
-
-```bash
-# In project A — log in as user-a@company.com
-cd ~/projects/project-a
-npx securenow login --local
-
-# In project B — log in as user-b@company.com
-cd ~/projects/project-b
-npx securenow login --local
-
-# Each project uses its own credentials independently
-npx securenow whoami   # Shows auth source: project (.securenow/)
-```
-
-You can also use the `SECURENOW_TOKEN` env var for per-terminal sessions without touching any files.
-
-### CI/CD Integration
-
-```bash
-# Authenticate with a token in CI (env var — no file needed)
-SECURENOW_TOKEN=$MY_SECRET npx securenow issues --json
-
-# Or use login with explicit token
-npx securenow login --token $SECURENOW_TOKEN
-
-# Use --json for machine-readable output
-npx securenow issues --json | jq '.[] | select(.severity == "critical")'
-
-# Check for critical issues in a pipeline
-ISSUES=$(npx securenow issues --json --status open)
-CRITICAL=$(echo "$ISSUES" | jq '[.[] | select(.severity == "critical")] | length')
-if [ "$CRITICAL" -gt "0" ]; then
-  echo "Found $CRITICAL critical issues!"
-  exit 1
-fi
-```
-
-### Complete Command Reference
-
-| Category | Command | Description |
-|----------|---------|-------------|
-| **Setup** | `init` | Auto-scaffold instrumentation for your framework |
-| **Auth** | `login` | Authenticate via browser, `--token`, or `--local` |
-| | `logout` | Clear credentials (`--local` for project only) |
-| | `whoami` | Show session info and auth source |
-| **Apps** | `apps` | List applications |
-| | `apps create <name>` | Create application |
-| | `apps info <id>` | Application details |
-| | `apps delete <id>` | Delete application |
-| | `apps default <key>` | Set default app |
-| **Observe** | `traces` | List traces |
-| | `traces show <id>` | Trace details |
-| | `traces analyze <id>` | AI trace analysis |
-| | `logs` | List logs |
-| | `logs trace <id>` | Logs for a trace |
-| | `analytics` | Response analytics |
-| | `status` | Dashboard overview |
-| **Detect** | `issues` | List issues |
-| | `issues show <id>` | Issue details |
-| | `issues resolve <id>` | Resolve issue |
-| | `notifications` | List notifications |
-| | `notifications unread` | Unread count |
-| | `notifications read <id>` | Mark read |
-| | `notifications read-all` | Mark all read |
-| | `alerts rules` | List rules (status, apps, schedule) |
-| | `alerts rules show <id>` | Rule detail |
-| | `alerts rules update <id> --applications-all` / `--apps k1,k2` | Application scope |
-| | `alerts channels` | Alert channels |
-| | `alerts history` | Alert history |
-| **Investigate** | `ip <addr>` | IP intelligence |
-| | `ip traces <addr>` | Traces from IP |
-| | `forensics "<query>"` | NL forensic query |
-| | `forensics library` | Saved queries |
-| | `api-map` | API endpoints |
-| | `api-map stats` | API stats |
-| **Firewall** | `firewall status` | Firewall status and API key info |
-| | `firewall test-ip <ip>` | Check if an IP would be blocked |
-| **Remediate** | `blocklist` | Blocked IPs |
-| | `blocklist add <ip>` | Block IP |
-| | `blocklist remove <id>` | Unblock IP |
-| | `blocklist stats` | Block stats |
-| | `trusted` | Trusted IPs |
-| | `trusted add <ip>` | Add trusted IP |
-| | `trusted remove <id>` | Remove trusted |
-| **Settings** | `instances` | List instances |
-| | `instances test <id>` | Test connection |
-| | `config get` | Show config |
-| | `config set <k> <v>` | Set config value |
-| | `config path` | Config file paths |
-| | `version` | Show version |
-
----
-
-## Framework-Specific Setup
-
-> **v5.6.0+:** When `SECURENOW_LOGGING_ENABLED=1`, all `console.log`/`warn`/`error`/`info`/`debug` calls
-> are **automatically** forwarded as OTLP log records. The separate `require('securenow/console-instrumentation')` is no longer needed (but still available for backward compat).
-
-### Express.js
-
-```bash
-npm install securenow express
-```
-
-```javascript
-// app.js
-require('securenow/register');
-const express = require('express');
-
-const app = express();
-app.use(express.json());
-
-app.get('/health', (req, res) => res.json({ status: 'ok' }));
-
-app.post('/tasks', (req, res) => {
-  console.log('Created task:', req.body.title);
-  res.status(201).json({ id: '1', title: req.body.title });
-});
-
-app.listen(3000, () => console.log('Express running on port 3000'));
-```
-
-```bash
-node app.js
-```
-
-#### With PM2
-
-```javascript
-// ecosystem.config.cjs
-module.exports = {
-  apps: [{
-    name: 'my-app',
-    script: './app.js',
-    node_args: '-r securenow/register',
-    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',
-    }
-  }]
-};
-```
-
-> **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
-
-```bash
-npm install securenow fastify
-```
-
-```javascript
-// app.js
-require('securenow/register');
-const Fastify = require('fastify');
-const fastify = Fastify({ logger: true });
-
-fastify.get('/health', async () => ({ status: 'ok' }));
-
-fastify.post('/tasks', {
-  schema: { body: { type: 'object', required: ['title'], properties: { title: { type: 'string' } } } }
-}, async (request) => {
-  console.log('Created task:', request.body.title);
-  return { id: '1', title: request.body.title };
-});
-
-fastify.listen({ port: 3000 }, (err) => {
-  if (err) { fastify.log.error(err); process.exit(1); }
-  console.log('Fastify running on port 3000');
-});
-```
-
-> **Important:** Set `SECURENOW_CAPTURE_BODY=0` with Fastify -- the body capture hook conflicts with Fastify's internal stream handling.
-
----
-
-### Koa
-
-```bash
-npm install securenow koa @koa/router koa-bodyparser
-```
-
-```javascript
-// app.js
-require('securenow/register');
-const Koa = require('koa');
-const Router = require('@koa/router');
-const bodyParser = require('koa-bodyparser');
-
-const app = new Koa();
-const router = new Router();
-
-router.get('/health', (ctx) => { ctx.body = { status: 'ok' }; });
-
-router.post('/tasks', (ctx) => {
-  console.log('Created task:', ctx.request.body.title);
-  ctx.status = 201;
-  ctx.body = { id: '1', title: ctx.request.body.title };
-});
-
-app.use(bodyParser());
-app.use(router.routes());
-app.use(router.allowedMethods());
-
-app.listen(3000, () => console.log('Koa running on port 3000'));
-```
-
----
-
-### NestJS
-
-```bash
-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()`:
-
-```typescript
-// app.ts
-import 'reflect-metadata';
-import { NestFactory } from '@nestjs/core';
-import { Module, Controller, Get, Post, Body } from '@nestjs/common';
-
-@Controller()
-class AppController {
-  @Get('health')
-  health() { return { status: 'ok' }; }
-
-  @Post('tasks')
-  create(@Body() body: { title: string }) {
-    console.log('Created task:', body.title);
-    return { id: '1', title: body.title };
-  }
-}
-
-@Module({ controllers: [AppController] })
-class AppModule {}
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  await app.listen(3000);
-  console.log('NestJS running on port 3000');
-}
-bootstrap();
-```
-
-```bash
-node -r securenow/register -r ts-node/register app.ts
-```
-
-PM2 config:
-
-```javascript
-{
-  name: 'my-nestjs-app',
-  script: 'app.ts',
-  interpreter: 'node',
-  node_args: '-r securenow/register -r ts-node/register',
-}
-```
-
----
-
-### Hapi
-
-```bash
-npm install securenow @hapi/hapi
-```
-
-```javascript
-// app.js
-require('securenow/register');
-const Hapi = require('@hapi/hapi');
-
-const init = async () => {
-  const server = Hapi.server({ port: 3000, host: '0.0.0.0' });
-
-  server.route({ method: 'GET', path: '/health', handler: () => ({ status: 'ok' }) });
-
-  server.route({
-    method: 'POST', path: '/tasks',
-    options: { payload: { parse: true, allow: 'application/json' } },
-    handler: (request, h) => {
-      console.log('Created task:', request.payload.title);
-      return h.response({ id: '1', title: request.payload.title }).code(201);
-    }
-  });
-
-  await server.start();
-  console.log('Hapi running on port 3000');
-};
-
-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.
-
----
-
-### h3 (UnJS / Nitro)
-
-```bash
-npm install securenow h3
-```
-
-```javascript
-// app.js
-require('securenow/register');
-const { createApp, createRouter, defineEventHandler, readBody, setResponseStatus, toNodeListener } = require('h3');
-const http = require('http');
-
-const app = createApp();
-const router = createRouter();
-
-router.get('/health', defineEventHandler(() => ({ status: 'ok' })));
-
-router.post('/tasks', defineEventHandler(async (event) => {
-  const body = await readBody(event);
-  console.log('Created task:', body.title);
-  setResponseStatus(event, 201);
-  return { id: '1', title: body.title };
-}));
-
-app.use(router);
-
-http.createServer(toNodeListener(app)).listen(3000, () => {
-  console.log('h3 running on port 3000');
-});
-```
-
----
-
-### Polka
-
-```bash
-npm install securenow polka
-```
-
-Polka is minimalist -- no built-in body parser:
-
-```javascript
-// app.js
-require('securenow/register');
-const polka = require('polka');
-
-function jsonBody(req, res, next) {
-  if (req.method === 'GET' || req.method === 'DELETE') return next();
-  let data = '';
-  req.on('data', chunk => { data += chunk; });
-  req.on('end', () => { try { req.body = JSON.parse(data); } catch { req.body = {}; } next(); });
-}
-
-function sendJson(res, status, body) {
-  res.writeHead(status, { 'Content-Type': 'application/json' });
-  res.end(JSON.stringify(body));
-}
-
-polka()
-  .use(jsonBody)
-  .get('/health', (req, res) => sendJson(res, 200, { status: 'ok' }))
-  .post('/tasks', (req, res) => {
-    console.log('Created task:', req.body.title);
-    sendJson(res, 201, { id: '1', title: req.body.title });
-  })
-  .listen(3000, () => console.log('Polka running on port 3000'));
-```
-
----
-
-### Micro / Raw HTTP
-
-For apps using Node's bare `http` module:
-
-```bash
-npm install securenow
-```
-
-```javascript
-// app.js
-require('securenow/register');
-const http = require('http');
-
-function sendJson(res, status, body) {
-  res.writeHead(status, { 'Content-Type': 'application/json' });
-  res.end(JSON.stringify(body));
-}
-
-function readBody(req) {
-  return new Promise((resolve) => {
-    let d = ''; req.on('data', c => { d += c; }); req.on('end', () => { try { resolve(JSON.parse(d)); } catch { resolve({}); } });
-  });
-}
-
-async function handler(req, res) {
-  const url = new URL(req.url, `http://${req.headers.host}`);
-  if (url.pathname === '/health') return sendJson(res, 200, { status: 'ok' });
-  if (url.pathname === '/tasks' && req.method === 'POST') {
-    const body = await readBody(req);
-    console.log('Created task:', body.title);
-    return sendJson(res, 201, { id: '1', title: body.title });
-  }
-  sendJson(res, 404, { error: 'Not found' });
-}
-
-http.createServer(handler).listen(3000, () => console.log('HTTP running on port 3000'));
-```
-
----
-
-### Hono (ESM)
-
-```bash
-npm install securenow hono @hono/node-server
-```
-
-Hono uses ESM -- preload via `-r` flag (the ESM hook is auto-registered on Node >=20.6):
-
-```javascript
-// app.mjs
-import { serve } from '@hono/node-server';
-import { Hono } from 'hono';
-
-const app = new Hono();
-
-app.get('/health', (c) => c.json({ status: 'ok' }));
-
-app.post('/tasks', async (c) => {
-  const body = await c.req.json();
-  console.log('Created task:', body.title);
-  return c.json({ id: '1', title: body.title }, 201);
-});
-
-serve({ fetch: app.fetch, port: 3000 }, () => console.log('Hono running on port 3000'));
-```
-
-```bash
-node -r securenow/register app.mjs
-```
-
-> **Important:** Set `SECURENOW_CAPTURE_BODY=0` with Hono. Do **not** add `require('securenow/register')` inside `.mjs` files.
-
----
-
-### Feathers
-
-```bash
-npm install securenow @feathersjs/feathers @feathersjs/express @feathersjs/errors
-```
-
-Feathers uses Express transport -- same setup as Express:
-
-```javascript
-// app.js
-require('securenow/register');
-const feathers = require('@feathersjs/feathers');
-const express = require('@feathersjs/express');
-const errors = require('@feathersjs/errors');
-
-class TaskService {
-  constructor() { this.tasks = []; this.nextId = 1; }
-  async find() { return this.tasks; }
-  async create(data) {
-    if (!data.title) throw new errors.BadRequest('title is required');
-    const task = { id: String(this.nextId++), title: data.title };
-    this.tasks.push(task);
-    console.log('Created task:', task.id);
-    return task;
-  }
-}
-
-const app = express(feathers());
-app.use(express.json());
-app.configure(express.rest());
-app.get('/health', (req, res) => res.json({ status: 'ok' }));
-app.use('/tasks', new TaskService());
-app.use(express.errorHandler());
-
-app.listen(3000, () => console.log('Feathers running on port 3000'));
-```
-
----
-
-### Next.js
-
-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.
-});
-```
-
-**2. Create `instrumentation.ts` (or `.js`):**
-
-```typescript
-export async function register() {
-  if (process.env.NEXT_RUNTIME === 'nodejs') {
-    const { registerSecureNow } = require('securenow/nextjs');
-    registerSecureNow();
-  }
-}
-```
-
-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
-
-```bash
-npm install securenow
-```
-
-Add the module to `nuxt.config.ts`:
-
-```typescript
-export default defineNuxtConfig({
-  modules: ['securenow/nuxt'],
-});
-```
-
-`.env`:
-
-```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, firewall activation, and request tracing automatically. Optional config:
-
-```typescript
-export default defineNuxtConfig({
-  modules: ['securenow/nuxt'],
-  securenow: {
-    captureBody: true,
-    logging: true,
-    noUuid: true,
-  },
-});
-```
-
-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 | 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
-
-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
-
-```bash
-# Add to your .env
-SECURENOW_API_KEY=snk_live_abc123...
-```
-
-That's it. On startup, you'll see:
-
-```
-[securenow] Firewall: ENABLED
-[securenow] Firewall: Layer 1 (HTTP 403)      active
-[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:
-
-| Layer | Env Var | Description |
-|-------|---------|-------------|
-| **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
-npx securenow login
-npx securenow firewall status
-```
-
-Or create one from the dashboard with the `firewall:read` scope.
-
-See the [Firewall Guide](./docs/FIREWALL-GUIDE.md) for the full reference.
-
----
-
-## Environment Variables Reference
-
-### Required Variables
-
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `SECURENOW_APPID` | Your application identifier. Used as the service name in traces. | `my-app` |
-| `SECURENOW_INSTANCE` | Base URL of your OTLP collector endpoint. | `http://localhost:4318` |
-
-### Optional Configuration
-
-#### Service Naming
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `OTEL_SERVICE_NAME` | Alternative to SECURENOW_APPID. Standard OpenTelemetry variable. | - |
-| `SECURENOW_NO_UUID` | Set to `1` to disable UUID suffix on service name. Useful for clustered apps. | `0` |
-| `SECURENOW_STRICT` | Set to `1` to exit process if SECURENOW_APPID is not set in cluster mode. | `0` |
-
-#### Connection Settings
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | Alternative to SECURENOW_INSTANCE. Standard OpenTelemetry variable. | - |
-| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Override traces endpoint specifically. | `{SECURENOW_INSTANCE}/v1/traces` |
-| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Override logs endpoint specifically. | `{SECURENOW_INSTANCE}/v1/logs` |
-| `OTEL_EXPORTER_OTLP_HEADERS` | Headers to send with OTLP exports. Format: `key1=value1,key2=value2` | - |
-
-#### Logging
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `SECURENOW_LOGGING_ENABLED` | Enable automatic logging to OTLP backend. Set to `1` to enable, `0` to disable. | `1` |
-
-#### Request Body Capture
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `SECURENOW_CAPTURE_BODY` | Enable request body capture in traces. Set to `1` to enable. | `0` |
-| `SECURENOW_MAX_BODY_SIZE` | Maximum body size to capture in bytes. Bodies larger than this are truncated. | `10240` (10KB) |
-| `SECURENOW_SENSITIVE_FIELDS` | Comma-separated list of additional field names to redact. | - |
-| `SECURENOW_CAPTURE_MULTIPART` | Enable multipart/form-data capture. Streams through the request to extract text field values and file metadata (name, filename, content-type, size) without buffering file content. Set to `1` to enable. | `0` |
-
-**Default sensitive fields (auto-redacted):** `password`, `passwd`, `pwd`, `secret`, `token`, `api_key`, `apikey`, `access_token`, `auth`, `credentials`, `mysql_pwd`, `stripeToken`, `card`, `cardnumber`, `ccv`, `cvc`, `cvv`, `ssn`, `pin`
-
-#### Instrumentation Control
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `SECURENOW_DISABLE_INSTRUMENTATIONS` | Comma-separated list of instrumentation packages to disable. | - |
-
-**Example:** `SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns` disables filesystem and DNS instrumentations.
-
-#### Firewall
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `SECURENOW_API_KEY` | API key with `firewall:read` scope. Enables the firewall when set. | - |
-| `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_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.
-
-#### Debugging
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `OTEL_LOG_LEVEL` | OpenTelemetry SDK log level. Options: `debug`, `info`, `warn`, `error` | `none` |
-| `SECURENOW_TEST_SPAN` | Set to `1` to emit a test span on startup. | `0` |
-
-#### Environment
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `NODE_ENV` | Deployment environment name. Sent as `deployment.environment` attribute. | `production` |
-
----
-
-## 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
-
-Since **v5.6.0**, when `SECURENOW_LOGGING_ENABLED=1`, all console calls are automatically forwarded as OTLP log records:
-
-```javascript
-// At the top of your main file
-require('securenow/register');
-
-// With SECURENOW_LOGGING_ENABLED=1, all console logs are automatically sent
-console.log('Application started');
-console.info('User action', { userId: 123, action: 'login' });
-console.warn('Deprecation warning');
-console.error('Error occurred', { error: 'Something failed' });
-console.debug('Debug info');
-```
-
-**Severity mapping:**
-- `console.log()` -> INFO
-- `console.info()` -> INFO
-- `console.warn()` -> WARN
-- `console.error()` -> ERROR
-- `console.debug()` -> DEBUG
-
-**Environment variable:**
-```bash
-SECURENOW_LOGGING_ENABLED=1
-```
-
-### Direct Logger API
-
-For more control, use the OpenTelemetry logger API:
-
-```javascript
-require('securenow/register');
-const { getLogger } = require('securenow/tracing');
-
-// Get a logger instance
-const logger = getLogger('my-module', '1.0.0');
-
-// Emit structured logs
-logger.emit({
-  severityNumber: 9,      // INFO
-  severityText: 'INFO',
-  body: 'User logged in',
-  attributes: {
-    userId: 123,
-    username: 'john',
-    sessionId: 'abc123',
-  },
-});
-```
-
-**Severity numbers:**
-- `5` - DEBUG
-- `9` - INFO
-- `13` - WARN
-- `17` - ERROR
-
-### Using with NODE_OPTIONS
-
-```bash
-# Enable tracing + logging (console auto-forwarding is built-in since v5.6.0)
-NODE_OPTIONS="-r securenow/register" \
-SECURENOW_APPID=my-app \
-SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318 \
-SECURENOW_LOGGING_ENABLED=1 \
-node app.js
-```
-
----
-
-## Request Body Capture
-
-SecureNow can capture HTTP request bodies in traces for debugging purposes. This is disabled by default.
-
-### Enable Body Capture
-
-```bash
-export SECURENOW_CAPTURE_BODY=1
-export SECURENOW_MAX_BODY_SIZE=10240  # 10KB (optional)
-```
-
-### Supported Content Types
-
-- `application/json`
-- `application/x-www-form-urlencoded`
-- `application/graphql`
-- `multipart/form-data` (requires `SECURENOW_CAPTURE_MULTIPART=1`)
-
-### 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.
-
-**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
-
-**Example trace attribute:**
-```json
-{
-  "fields": { "description": "My upload", "token": "[REDACTED]" },
-  "files": [
-    { "field": "avatar", "filename": "photo.jpg", "contentType": "image/jpeg", "size": 524288 },
-    { "field": "resume", "filename": "cv.pdf", "contentType": "application/pdf", "size": 1048576 }
-  ]
-}
-```
-
-File binary content is never stored in traces.
-
-### Sensitive Data Redaction
-
-All request bodies are automatically scanned and sensitive fields are redacted:
-
-**Automatically redacted fields:** `password`, `secret`, `token`, `api_key`, `card`, `cvv`, `ssn`, and more.
-
-**Add custom fields to redact:**
-
-```bash
-export SECURENOW_SENSITIVE_FIELDS="custom_secret,internal_token"
-```
-
-### Example
-
-```javascript
-// POST /api/users with body:
-{
-  "email": "user@example.com",
-  "password": "secret123",
-  "name": "John Doe"
-}
-
-// Captured in trace as:
-{
-  "email": "user@example.com",
-  "password": "[REDACTED]",
-  "name": "John Doe"
-}
-```
-
----
-
-## Advanced Configuration
-
-### Complete Example with All Options
-
-```bash
-# Service identification
-export SECURENOW_APPID=my-production-app
-export SECURENOW_NO_UUID=1
-export SECURENOW_STRICT=1
-
-# OTLP backend
-export SECURENOW_INSTANCE=http://collector.example.com:4318
-export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key"
-
-# Logging
-export SECURENOW_LOGGING_ENABLED=1
-
-# Request body capture
-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
-
-# Debugging
-export OTEL_LOG_LEVEL=info
-
-# Disable specific instrumentations
-export SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns
-
-# Run application
-NODE_OPTIONS="-r securenow/register" node app.js
-```
-
-### Using Multiple Logger Instances
-
-```javascript
-const { getLogger } = require('securenow/tracing');
-
-const authLogger = getLogger('auth-service', '1.0.0');
-const dbLogger = getLogger('database', '1.0.0');
-const apiLogger = getLogger('api-handler', '1.0.0');
-
-authLogger.emit({
-  severityNumber: 9,
-  severityText: 'INFO',
-  body: 'User authenticated',
-  attributes: { userId: 123 },
-});
-
-dbLogger.emit({
-  severityNumber: 13,
-  severityText: 'WARN',
-  body: 'Slow query detected',
-  attributes: { queryTime: 5000 },
-});
-```
-
-### Check if Logging is Enabled
-
-```javascript
-const { isLoggingEnabled } = require('securenow/tracing');
-
-if (isLoggingEnabled()) {
-  console.log('Logging is enabled');
-} else {
-  console.log('Logging is disabled');
-}
-```
-
-### Programmatic Configuration
-
-While environment variables are recommended, you can also configure programmatically:
-
-```javascript
-// Set environment variables before requiring securenow
-process.env.SECURENOW_APPID = 'my-app';
-process.env.SECURENOW_INSTANCE = 'http://localhost:4318';
-process.env.SECURENOW_LOGGING_ENABLED = '1';
-
-// Then initialize (console log forwarding is automatic since v5.6.0)
-require('securenow/register');
-```
-
----
-
-## TypeScript Support
-
-SecureNow includes full TypeScript definitions.
-
-### Type Definitions
-
-```typescript
-import { getLogger, isLoggingEnabled, Logger, LogRecord } from 'securenow/tracing';
-
-// Get a typed logger
-const logger: Logger | null = getLogger('my-service', '1.0.0');
-
-// Emit a log with type checking
-if (logger) {
-  const logRecord: LogRecord = {
-    severityNumber: 9,
-    severityText: 'INFO',
-    body: 'User action',
-    attributes: {
-      userId: 123,
-      action: 'login',
-    },
-  };
-  
-  logger.emit(logRecord);
-}
-
-// Check if enabled
-const enabled: boolean = isLoggingEnabled();
-```
-
-### Next.js with TypeScript
-
-```typescript
-// instrumentation.ts
-export async function register() {
-  if (process.env.NEXT_RUNTIME === 'nodejs') {
-    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:
-
-```typescript
-// main.ts (run with: node -r securenow/register -r ts-node/register main.ts)
-import { NestFactory } from '@nestjs/core';
-import { AppModule } from './app.module';
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  await app.listen(3000);
-}
-
-bootstrap();
-```
-
----
-
-## Troubleshooting
-
-### Traces Not Appearing
-
-**Check 1: Verify environment variables**
-
-```bash
-echo $SECURENOW_APPID
-echo $SECURENOW_INSTANCE
-```
-
-Both should output values.
-
-**Check 2: Verify OTLP collector is running**
-
-```bash
-curl http://localhost:4318/v1/traces
-# Should return 200 or 405 (method not allowed)
-```
-
-**Check 3: Enable debug logging**
-
-```bash
-export OTEL_LOG_LEVEL=debug
-node app.js
-```
-
-Look for lines like:
-```
-[securenow] OTel SDK started -> http://localhost:4318/v1/traces
-```
-
-**Check 4: Verify initialization order**
-
-SecureNow must be required BEFORE any other modules:
-
-```javascript
-// Correct
-require('securenow/register');
-const express = require('express');
-
-// 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?**
-
-```bash
-echo $SECURENOW_LOGGING_ENABLED
-# Should output: 1
-```
-
-**Check 2: Verify console instrumentation is loaded**
-
-```javascript
-require('securenow/register');
-```
-
-**Check 3: Check console output**
-
-You should see:
-```
-[securenow] Logging: ENABLED -> http://localhost:4318/v1/logs
-```
-
-**Check 4: Verify OTLP logs endpoint**
-
-```bash
-curl http://localhost:4318/v1/logs
-# Should return 200 or 405
-```
-
-### Request Body Not Captured
-
-**Check 1: Is body capture enabled?**
-
-```bash
-export SECURENOW_CAPTURE_BODY=1
-```
-
-**Check 2: Verify content type**
-
-Body capture only works for:
-- `application/json`
-- `application/x-www-form-urlencoded`
-- `application/graphql`
-
-**Check 3: Check body size**
-
-Bodies larger than `SECURENOW_MAX_BODY_SIZE` are truncated:
-
-```bash
-export SECURENOW_MAX_BODY_SIZE=20480  # Increase to 20KB
-```
-
-### High Memory Usage
-
-**Option 1: Disable body capture**
-
-```bash
-export SECURENOW_CAPTURE_BODY=0
-```
-
-**Option 2: Reduce body size limit**
-
-```bash
-export SECURENOW_MAX_BODY_SIZE=5120  # 5KB
-```
-
-**Option 3: Disable specific instrumentations**
-
-```bash
-export SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns,net
-```
-
-### Next.js Instrumentation Not Working
-
-**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 3: Check for OTel MODULE_NOT_FOUND errors**
-
-If you see `MODULE_NOT_FOUND` for `@opentelemetry/*` packages, your `next.config.js` is missing the externalization. Use `withSecureNow()` to fix this automatically.
-
-**Check 4: Restart dev server**
-
-```bash
-# Kill the server and restart
-npm run dev
-```
-
-### PM2 Cluster Issues
-
-**Problem: Different service names for each worker**
-
-**Solution: Use SECURENOW_NO_UUID**
-
-```bash
-export SECURENOW_NO_UUID=1
-```
-
-This uses the same service name for all workers.
-
-**Problem: Workers not instrumented / firewall not active**
-
-**Solution: Use node_args in PM2 config**
-
-```javascript
-// ecosystem.config.cjs
-module.exports = {
-  apps: [{
-    name: 'my-app',
-    script: './app.js',
-    instances: 4,
-    node_args: '-r securenow/register',
-    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
-
-### 1. Use Environment Variables
-
-Don't hardcode configuration. Use environment variables:
-
-```javascript
-// Bad
-process.env.SECURENOW_APPID = 'hardcoded-value';
-
-// Good -- use .env file or export
-// .env
-SECURENOW_APPID=my-app
-SECURENOW_INSTANCE=http://localhost:4318
-```
-
-### 2. Use Structured Logging
-
-Pass objects to console methods for better filtering:
-
-```javascript
-// Less useful
-console.log('User 123 logged in');
-
-// Better -- structured attributes
-console.log('User logged in', {
-  userId: 123,
-  email: 'user@example.com',
-  timestamp: new Date().toISOString(),
-});
-```
-
-### 3. Choose Appropriate Severity Levels
-
-```javascript
-// Normal operations
-console.log('Request processed');
-console.info('User created', { userId: 123 });
-
-// Warnings
-console.warn('API rate limit approaching', { remaining: 10 });
-
-// Errors
-console.error('Database connection failed', { error: err.message });
-
-// Debug (only in development)
-console.debug('Cache hit', { key: 'user:123' });
-```
-
-### 4. Don't Log Sensitive Data
-
-Even though SecureNow automatically redacts common sensitive fields, avoid logging:
-
-```javascript
-// Bad
-console.log('Login attempt', {
-  email: 'user@example.com',
-  password: 'secret123', // Will be redacted, but don't log it!
-});
-
-// Good
-console.log('Login attempt', {
-  email: 'user@example.com',
-  timestamp: Date.now(),
-});
-```
-
-### 5. Use Different Logger Instances for Different Modules
-
-```javascript
-// auth-service.js
-const authLogger = getLogger('auth-service', '1.0.0');
-
-// database.js
-const dbLogger = getLogger('database', '1.0.0');
-
-// api.js
-const apiLogger = getLogger('api', '1.0.0');
-```
-
-### 6. Enable Body Capture Only in Development
-
-```bash
-# .env.development
-SECURENOW_CAPTURE_BODY=1
-
-# .env.production
-SECURENOW_CAPTURE_BODY=0
-```
-
----
-
-## Supported Runtimes
-
-- **Node.js:** 18+
-- **Frameworks:** Express, Next.js, Nuxt 3, Fastify, NestJS, Koa, Hapi, and more
-- **Databases:** PostgreSQL, MySQL, MongoDB, Redis
-- **HTTP Clients:** axios, fetch, node-fetch, got, request
-- **GraphQL:** Apollo Server, GraphQL.js
-- **Message Queues:** Redis, BullMQ
-- **And many more via OpenTelemetry auto-instrumentation**
-
----
-
-## Automatic Instrumentations
-
-SecureNow automatically instruments:
-
-- HTTP/HTTPS (incoming and outgoing)
-- Express.js
-- Fastify
-- Koa
-- Hapi
-- Next.js
-- PostgreSQL
-- MySQL/MySQL2
-- MongoDB
-- Redis
-- GraphQL
-- gRPC
-- DNS
-- File System
-- And 50+ more libraries
-
-No code changes needed!
-
----
-
-## Architecture
-
-```
-                    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   |
-          +-----------+
-```
-
----
-
-## Performance
-
-- **Minimal overhead:** < 1% CPU and memory impact
-- **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
-
----
-
-## Security
-
-- **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
-- **API keys** with granular scopes, IP allowlisting, and SHA-256 hashing
-- **Allowlist support** -- trusted IPs are never blocked
-- **Fail-open by default** -- network issues never accidentally block legitimate traffic
-- **Open source** -- audit the code yourself
-
----
-
-## License
-
-ISC
-
----
-
-## Support
-
-- **Documentation:** [GitHub Docs](https://github.com/your-repo/securenow-npm/tree/main/docs)
-- **Issues:** [GitHub Issues](https://github.com/your-repo/securenow-npm/issues)
-- **Examples:** [GitHub Examples](https://github.com/your-repo/securenow-npm/tree/main/examples)
-
----
-
-## Changelog
-
-See [CHANGELOG.md](CHANGELOG.md) for version history.
-
----
-
-## Contributing
-
-Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
----
-
-## Related Packages
-
-- [@opentelemetry/sdk-node](https://www.npmjs.com/package/@opentelemetry/sdk-node) - Core OpenTelemetry SDK
-- [@opentelemetry/auto-instrumentations-node](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node) - Auto-instrumentation
-- [@opentelemetry/exporter-trace-otlp-http](https://www.npmjs.com/package/@opentelemetry/exporter-trace-otlp-http) - OTLP exporter
-
----
-
-**Made with care for the Node.js community**