securenow 6.0.2 → 6.1.0

package/NPM_README.md

@@ -0,0 +1,2029 @@
+# 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.
+
+**Full CLI/SDK parity (v6.1.0+):** every SDK export has a matching CLI command. `redactSensitiveData` → `securenow redact`, `createMatcher` → `securenow cidr match`, `getLogger().emit()` → `securenow log send`, `SECURENOW_TEST_SPAN` → `securenow test-span`, `node -r securenow/firewall-only` → `securenow run --firewall-only`. False-positive triage (`fp create`, `fp ai-fill`, `fp mark`) works from the terminal without the web dashboard.
+
+### 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>
+```
+
+### 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>
+```
+
+### False-Positive Management
+
+Full FP triage from the terminal — no dashboard required.
+
+```bash
+# Browse & inspect rules
+npx securenow fp
+npx securenow fp show <rule-id>
+
+# Create a rule from AI-drafted conditions
+npx securenow fp ai-fill --description "Stripe webhook POST to /api/stripe/webhook"
+npx securenow fp create --conditions '<ai-output>' --rule-scope any_rule --reason "Stripe webhook"
+
+# Create with safe-value presets (shorthand)
+npx securenow fp create \
+  --path /api/events --method POST \
+  --path-safe standard --ua-safe standard --headers-safe standard \
+  --query-keys page,limit --reason "Event webhook"
+
+# Test & dry-run before committing
+npx securenow fp test-body '{"user":"admin"}' --conditions '[...]'
+npx securenow fp dry-run --conditions '[...]'    # last 3 days of live traces
+
+# Mark a notification's IP as FP in one shot
+npx securenow fp mark <notification-id> <ip> --rule-scope this_rule --reason "Known partner IP"
+
+# Edit / delete
+npx securenow fp edit <id> --active false
+npx securenow fp delete <id> --yes
+```
+
+### Telemetry -- Emit Logs and Spans From the Shell
+
+Mirrors the SDK's `getLogger()` and tracing APIs. Useful for cron jobs, shell scripts, and CI pipelines that need to push events into SecureNow **without booting the full OTel SDK**.
+
+```bash
+# Send a structured log record to your OTLP collector
+npx securenow log send "Deployment completed" --level info --attrs version=1.2.3,service=api
+npx securenow log send "Backup failed" --level error --attrs host=db-01
+
+# Emit a test span to verify the collector accepts OTLP traffic
+npx securenow test-span
+npx securenow test-span "ci.smoke-test"          # custom span name
+```
+
+Both commands use the resolved `SECURENOW_INSTANCE` / `OTEL_EXPORTER_OTLP_*` endpoints and honor `OTEL_EXPORTER_OTLP_HEADERS` for API-key auth. Non-zero exit on HTTP errors so CI/cron can detect failures.
+
+### Utilities -- Redaction, CIDR, Diagnostics
+
+SDK helpers surfaced as CLI commands so agents (and humans) can validate behavior without writing Node.
+
+```bash
+# Redact sensitive fields (password, token, card, ssn, etc.)
+npx securenow redact '{"user":"alice","password":"s3cret","card":"4242"}'
+npx securenow redact @request.json --fields internal_id,sessionHash
+
+# CIDR — match an IP against a list, or parse a range
+npx securenow cidr match 10.0.0.5 10.0.0.0/8,192.168.1.0/24  # exit 0 = hit, 2 = miss
+npx securenow cidr parse 10.0.0.0/24                         # network, broadcast, mask, size
+
+# Show resolved config (service name, endpoints, env vars, firewall layers)
+npx securenow env                 # human-readable
+npx securenow env --json          # pipe to jq
+
+# End-to-end diagnostic: probe OTLP + API endpoints
+npx securenow doctor              # exits 0 if healthy, 1 otherwise
+npx securenow doctor --json
+```
+
+### 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 logs --json
+
+# Or use login with explicit token
+npx securenow login --token $SECURENOW_TOKEN
+
+# Use --json for machine-readable output
+npx securenow logs --json --level error | jq '.logs'
+```
+
+### 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** | `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 |
+| | `run --firewall-only <script>` | Preload firewall without OTel tracing overhead |
+| **Remediate** | `blocklist` | Blocked IPs |
+| | `blocklist add <ip>` | Block IP |
+| | `blocklist remove <id>` | Unblock IP |
+| | `blocklist stats` | Block stats |
+| | `allowlist` | Allowed IPs (restrict-mode) |
+| | `allowlist add <ip>` | Allow IP (`--label`, `--reason`) |
+| | `allowlist remove <id>` | Remove from allowlist |
+| | `trusted` | Trusted IPs |
+| | `trusted add <ip>` | Add trusted IP |
+| | `trusted remove <id>` | Remove trusted |
+| **False Positives** | `fp` / `fp list` | List exclusion rules |
+| | `fp show <id>` | Rule detail |
+| | `fp create --conditions '[...]'` | Create raw exclusion rule |
+| | `fp create --path /api/events --method POST --path-safe standard` | Safe-value preset helper |
+| | `fp edit <id>` | Edit rule (`--active`, `--conditions`) |
+| | `fp delete <id>` | Delete rule |
+| | `fp test-body '<json>' --conditions '[...]'` | Test conditions against a payload |
+| | `fp dry-run --conditions '[...]'` | Dry-run against last 3 days of traces |
+| | `fp ai-fill --description "..."` | AI-generate exclusion conditions |
+| | `fp mark <notification-id> <ip>` | Mark an IP as FP on a notification |
+| **Telemetry** | `log send "<msg>" --level info --attrs k=v` | Emit an OTLP log record |
+| | `test-span [<name>]` | Emit a test span to the collector |
+| **Utilities** | `redact '<json>' [--fields f1,f2]` | Redact sensitive fields (accepts `@file.json`) |
+| | `cidr match <ip> <cidrs>` | IP vs. CIDR list (exit 0 hit / 2 miss) |
+| | `cidr parse <cidr>` | Parse CIDR (network, broadcast, mask, size) |
+| | `env [--json]` | Show resolved config (service name, endpoints, env vars) |
+| | `doctor [--json]` | Probe OTLP + API endpoints, check config |
+| **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
+# Manual preload flag
+node -r securenow/firewall-only app.js
+
+# Or via the CLI (v6.1.0+) — same effect, clearer intent
+securenow run --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**