securenow 5.5.0 → 5.6.1

package/docs/ALL-FRAMEWORKS-QUICKSTART.md

@@ -1,455 +1,1282 @@
-# Quick Start Guide - All Frameworks
-
-Fast setup guide for SecureNow with any Node.js framework in under 5 minutes.
-
----
-
-## Universal Setup (Works with Any Framework)
-
-### Step 1: Install
-
-```bash
-npm install securenow
-```
-
-### Step 2: Set Environment Variables
-
-```bash
-export SECURENOW_APPID=my-app
-export SECURENOW_INSTANCE=http://localhost:4318
-export SECURENOW_LOGGING_ENABLED=1
-```
-
-### Step 3: Initialize
-
-**Option A: Using NODE_OPTIONS (No code changes)**
-
-```bash
-NODE_OPTIONS="-r securenow/register -r securenow/console-instrumentation" node app.js
-```
-
-**Option B: Add to your code**
-
-```javascript
-// At the very top of your main file
-require('securenow/register');
-require('securenow/console-instrumentation');
-
-// Rest of your application
-```
-
-**Done!** Your app is now sending traces and logs.
-
----
-
-## Framework-Specific Quick Starts
-
-### Express.js
-
-```javascript
-// app.js
-require('securenow/register');
-require('securenow/console-instrumentation');
-
-const express = require('express');
-const app = express();
-
-app.get('/', (req, res) => {
-  console.log('Request received');
-  res.send('Hello World');
-});
-
-app.listen(3000);
-```
-
-**Run:**
-```bash
-SECURENOW_APPID=express-app \
-SECURENOW_INSTANCE=http://localhost:4318 \
-node app.js
-```
-
-[Full Express Guide →](./EXPRESS-SETUP-GUIDE.md)
-
----
-
-### Next.js (App Router)
-
-**1. Create `instrumentation.ts` in project root:**
-
-```typescript
-export async function register() {
-  if (process.env.NEXT_RUNTIME === 'nodejs') {
-    process.env.SECURENOW_LOGGING_ENABLED = '1';
-    await import('securenow/register');
-    await import('securenow/console-instrumentation');
-  }
-}
-```
-
-**2. Enable in `next.config.js`:**
-
-```javascript
-module.exports = {
-  experimental: {
-    instrumentationHook: true,
-  },
-};
-```
-
-**3. Create `.env.local`:**
-
-```env
-SECURENOW_APPID=nextjs-app
-SECURENOW_INSTANCE=http://localhost:4318
-```
-
-**4. Run:**
-
-```bash
-npm run dev
-```
-
-[Full Next.js Guide →](./NEXTJS-SETUP-COMPLETE.md)
-
----
-
-### Fastify
-
-```javascript
-// server.js
-require('securenow/register');
-require('securenow/console-instrumentation');
-
-const fastify = require('fastify')();
-
-fastify.get('/', async () => {
-  console.log('Route called');
-  return { hello: 'world' };
-});
-
-fastify.listen({ port: 3000 });
-```
-
-**Run:**
-```bash
-SECURENOW_APPID=fastify-app node server.js
-```
-
----
-
-### NestJS
-
-```typescript
-// src/main.ts
-require('securenow/register');
-require('securenow/console-instrumentation');
-
-import { NestFactory } from '@nestjs/core';
-import { AppModule } from './app.module';
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  await app.listen(3000);
-}
-
-bootstrap();
-```
-
-**Run:**
-```bash
-npm run start
-```
-
----
-
-### Koa
-
-```javascript
-// app.js
-require('securenow/register');
-require('securenow/console-instrumentation');
-
-const Koa = require('koa');
-const app = new Koa();
-
-app.use(async ctx => {
-  console.log('Request received');
-  ctx.body = 'Hello World';
-});
-
-app.listen(3000);
-```
-
----
-
-### Hapi
-
-```javascript
-// server.js
-require('securenow/register');
-require('securenow/console-instrumentation');
-
-const Hapi = require('@hapi/hapi');
-
-const init = async () => {
-  const server = Hapi.server({ port: 3000 });
-  
-  server.route({
-    method: 'GET',
-    path: '/',
-    handler: () => {
-      console.log('Route called');
-      return 'Hello World';
-    }
-  });
-  
-  await server.start();
-};
-
-init();
-```
-
----
-
-## Environment Variables
-
-### Minimal Setup
-
-```bash
-SECURENOW_APPID=my-app
-SECURENOW_INSTANCE=http://localhost:4318
-```
-
-### Recommended Setup
-
-```bash
-SECURENOW_APPID=my-app
-SECURENOW_INSTANCE=http://localhost:4318
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_CAPTURE_BODY=1
-NODE_ENV=development
-```
-
-### Production Setup
-
-```bash
-SECURENOW_APPID=my-app-prod
-SECURENOW_INSTANCE=http://collector.prod:4318
-OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-key
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_NO_UUID=1
-SECURENOW_CAPTURE_BODY=0
-NODE_ENV=production
-```
-
-[Complete Environment Variables Reference →](./ENVIRONMENT-VARIABLES.md)
-
----
-
-## Logging Examples
-
-### Automatic Console Logging
-
-```javascript
-// All console methods are automatically captured
-console.log('Application started');
-console.info('User action', { userId: 123 });
-console.warn('Warning message');
-console.error('Error occurred', { error: 'details' });
-```
-
-### Direct Logger API
-
-```javascript
-const { getLogger } = require('securenow/tracing');
-const logger = getLogger('my-module', '1.0.0');
-
-logger.emit({
-  severityNumber: 9,
-  severityText: 'INFO',
-  body: 'Custom log message',
-  attributes: {
-    userId: 123,
-    action: 'login',
-  },
-});
-```
-
-[Complete Logging Guide →](./LOGGING-GUIDE.md)
-
----
-
-## Request Body Capture
-
-Enable request body capture for debugging:
-
-```bash
-export SECURENOW_CAPTURE_BODY=1
-export SECURENOW_MAX_BODY_SIZE=10240  # 10KB
-```
-
-**Automatically redacted:** passwords, tokens, API keys, card numbers, etc.
-
----
-
-## PM2 Setup
-
-```javascript
-// ecosystem.config.js
-module.exports = {
-  apps: [{
-    name: 'my-app',
-    script: './app.js',
-    instances: 4,
-    exec_mode: 'cluster',
-    node_args: '-r securenow/register -r securenow/console-instrumentation',
-    env: {
-      SECURENOW_APPID: 'my-app',
-      SECURENOW_INSTANCE: 'http://localhost:4318',
-      SECURENOW_LOGGING_ENABLED: '1',
-      SECURENOW_NO_UUID: '1',
-    }
-  }]
-};
-```
-
-```bash
-pm2 start ecosystem.config.js
-```
-
----
-
-## Docker Setup
-
-```dockerfile
-FROM node:20-alpine
-
-WORKDIR /app
-
-COPY package*.json ./
-RUN npm install
-
-COPY . .
-
-ENV SECURENOW_APPID=my-app
-ENV SECURENOW_INSTANCE=http://collector:4318
-ENV SECURENOW_LOGGING_ENABLED=1
-
-EXPOSE 3000
-CMD ["node", "app.js"]
-```
-
----
-
-## Verification
-
-After starting your app, you should see:
-
-```
-[securenow] OTel SDK started → http://localhost:4318/v1/traces
-[securenow] 📋 Logging: ENABLED → http://localhost:4318/v1/logs
-[securenow] Console instrumentation installed
-```
-
-Check your observability backend - traces and logs should appear within seconds.
-
----
-
-## Troubleshooting
-
-### Traces Not Appearing
-
-1. Check environment variables:
-   ```bash
-   echo $SECURENOW_APPID
-   echo $SECURENOW_INSTANCE
-   ```
-
-2. Enable debug logging:
-   ```bash
-   export OTEL_LOG_LEVEL=debug
-   node app.js
-   ```
-
-3. Verify collector is running:
-   ```bash
-   curl http://localhost:4318/v1/traces
-   ```
-
-### Logs Not Appearing
-
-1. Check logging is enabled:
-   ```bash
-   echo $SECURENOW_LOGGING_ENABLED  # Should be: 1
-   ```
-
-2. Verify console instrumentation loaded:
-   ```
-   [securenow] Console instrumentation installed
-   ```
-
-3. Check initialization order:
-   ```javascript
-   // ✅ Correct
-   require('securenow/register');
-   require('securenow/console-instrumentation');
-   const express = require('express');
-   
-   // ❌ Wrong
-   const express = require('express');
-   require('securenow/register');
-   ```
-
----
-
-## Complete Documentation
-
-- **[NPM README](../NPM_README.md)** - Full npm package documentation
-- **[Express Guide](./EXPRESS-SETUP-GUIDE.md)** - Complete Express.js setup
-- **[Next.js Guide](./NEXTJS-SETUP-COMPLETE.md)** - Complete Next.js setup
-- **[Logging Guide](./LOGGING-GUIDE.md)** - Complete logging reference
-- **[Environment Variables](./ENVIRONMENT-VARIABLES.md)** - All variables explained
-
----
-
-## What Gets Instrumented Automatically
-
-- HTTP/HTTPS (incoming and outgoing)
-- Express.js, Fastify, Koa, Hapi, Next.js
-- PostgreSQL, MySQL, MongoDB, Redis
-- GraphQL, gRPC
-- axios, fetch, node-fetch, got
-- And 50+ more libraries
-
-**No code changes needed!**
-
----
-
-## Performance
-
-- **< 1% overhead:** Minimal CPU and memory impact
-- **Async processing:** No blocking of requests
-- **Batch export:** Efficient data transmission
-- **Production-ready:** Battle-tested in high-traffic applications
-
----
-
-## Security
-
-- **Automatic redaction** of sensitive fields
-- **Configurable** field patterns
-- **No local storage** - data goes directly to your backend
-- **Open source** - audit the code yourself
-
----
-
-## 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)
-
----
-
-**Get your app observable in under 5 minutes!** 🚀
+# SecureNow — Complete Guide for Every Node.js Framework
+
+Protect any Node.js app in minutes. This guide covers **installation, CLI commands, the forensics chat, and IP blocking** for all 11 supported frameworks.
+
+---
+
+## Table of Contents
+
+1. [Prerequisites](#prerequisites)
+2. [Install & Create Your App](#step-1--install--create-your-app)
+3. [Set Environment Variables](#step-2--set-environment-variables)
+4. [Plug SecureNow into Your Framework](#step-3--plug-securenow-into-your-framework)
+   - [Express.js](#expressjs)
+   - [Fastify](#fastify)
+   - [Koa](#koa)
+   - [NestJS](#nestjs)
+   - [Hapi](#hapi)
+   - [h3 (UnJS / Nitro)](#h3-unjs--nitro)
+   - [Polka](#polka)
+   - [Micro / Raw HTTP](#micro--raw-http)
+   - [Hono](#hono)
+   - [Feathers](#feathers)
+   - [Next.js](#nextjs)
+5. [Verify It Works](#step-4--verify-it-works)
+6. [CLI Command Reference](#step-5--cli-command-reference)
+7. [Forensics Chat — Ask Questions in Plain English](#step-6--forensics-chat--ask-questions-in-plain-english)
+8. [Block & Manage IPs](#step-7--block--manage-ips)
+9. [Monitor, Detect & Respond](#step-8--monitor-detect--respond)
+10. [PM2 / Docker Deployment](#deployment)
+11. [Compatibility Matrix](#compatibility-matrix)
+12. [Troubleshooting](#troubleshooting)
+
+---
+
+## Prerequisites
+
+| Requirement | Details |
+|-------------|---------|
+| **Node.js** | v16 or later |
+| **npm** | v7 or later |
+| **Account** | Free trial at [app.securenow.ai](https://app.securenow.ai) (no credit card) |
+
+---
+
+## Step 1 — Install & Create Your App
+
+### 1a. Install the package
+
+```bash
+npm install securenow
+```
+
+### 1b. Authenticate the CLI
+
+```bash
+npx securenow login
+```
+
+This opens your browser. Log in with your SecureNow account and the CLI receives a session token automatically.
+
+**Alternative — token-based login (CI / headless servers):**
+
+```bash
+npx securenow login --token <YOUR_TOKEN>
+```
+
+Get your CLI token from [app.securenow.ai/dashboard/settings](https://app.securenow.ai/dashboard/settings).
+
+### 1c. Create an application
+
+```bash
+npx securenow apps create my-app
+```
+
+The CLI returns your **app key** and **instance URL**. Copy them — you need both in the next step.
+
+```
+  Name       my-app
+  Key        my-app
+  Instance   Free Trial (https://freetrial.securenow.ai:4318)
+
+  Add to your .env.local:
+    SECURENOW_APPID=my-app
+    SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+```
+
+### 1d. Set it as the default app (optional)
+
+```bash
+npx securenow config set defaultApp my-app
+```
+
+This lets you run CLI commands like `securenow traces` without passing `--app` every time.
+
+---
+
+## Step 2 — Set Environment Variables
+
+Create a `.env` file in your project root:
+
+```env
+SECURENOW_APPID=my-app
+SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_NO_UUID=1
+```
+
+### All Environment Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `SECURENOW_APPID` | Your app key (from `securenow apps create`) | **Required** |
+| `SECURENOW_INSTANCE` | OTLP collector endpoint | `https://freetrial.securenow.ai:4318` |
+| `SECURENOW_LOGGING_ENABLED` | Auto-forward all `console.*` calls as OTLP logs | `0` |
+| `SECURENOW_NO_UUID` | Keep `service.name` equal to your app key (no UUID suffix) | `0` |
+| `SECURENOW_CAPTURE_BODY` | Capture request/response bodies in traces | `0` |
+| `SECURENOW_MAX_BODY_SIZE` | Max captured body size in bytes | `10240` |
+| `SECURENOW_SENSITIVE_FIELDS` | Extra field names to auto-redact (comma-separated) | — |
+| `SECURENOW_TRUSTED_PROXIES` | Comma-separated proxy IPs for X-Forwarded-For | — |
+| `SECURENOW_DISABLE_INSTRUMENTATIONS` | OTel instrumentation packages to skip (comma-separated) | — |
+| `SECURENOW_HIDE_BANNER` | Hide the free-trial testing banner | `0` |
+| `SECURENOW_STRICT` | Exit if `APPID` is missing in PM2 cluster mode | `0` |
+| `OTEL_LOG_LEVEL` | OTel diagnostic level (`debug`, `info`, `warn`, `error`, `none`) | `none` |
+
+### Production Example
+
+```env
+SECURENOW_APPID=my-app-prod
+SECURENOW_INSTANCE=https://collector.yourcompany.com:4318
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_NO_UUID=1
+SECURENOW_CAPTURE_BODY=0
+SECURENOW_TRUSTED_PROXIES=10.0.0.1,10.0.0.2
+NODE_ENV=production
+```
+
+---
+
+## Step 3 — Plug SecureNow into Your Framework
+
+There are two ways to initialize SecureNow. Both work with every framework.
+
+**Option A — Zero code changes (recommended)**
+
+```bash
+node -r securenow/register app.js
+```
+
+**Option B — Add one line to your entry file**
+
+```javascript
+require('securenow/register'); // Must be the very first line
+```
+
+Pick **one** method. Both do the same thing. Below are complete, copy-paste examples for each framework.
+
+---
+
+### Express.js
+
+```bash
+npm install securenow express
+```
+
+```javascript
+// app.js
+'use strict';
+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) => {
+  const { title } = req.body;
+  if (!title) return res.status(400).json({ error: 'title is required' });
+  console.log('Created task:', title);
+  res.status(201).json({ id: '1', title });
+});
+
+app.listen(3000, () => {
+  console.log('Express app running on port 3000');
+});
+```
+
+```bash
+node app.js
+```
+
+| Feature | Supported |
+|---------|-----------|
+| Traces | Yes |
+| Logs | Yes |
+| Body Capture | Yes — set `SECURENOW_CAPTURE_BODY=1` |
+
+---
+
+### Fastify
+
+```bash
+npm install securenow fastify
+```
+
+```javascript
+// app.js
+'use strict';
+require('securenow/register');
+const Fastify = require('fastify');
+
+const fastify = Fastify({ logger: true });
+
+fastify.get('/health', async () => {
+  return { status: 'ok' };
+});
+
+fastify.post('/tasks', {
+  schema: {
+    body: { type: 'object', required: ['title'], properties: { title: { type: 'string' } } }
+  }
+}, async (request) => {
+  const { title } = request.body;
+  console.log('Created task:', title);
+  return { id: '1', title };
+});
+
+fastify.listen({ port: 3000 }, (err) => {
+  if (err) { fastify.log.error(err); process.exit(1); }
+  console.log('Fastify app running on port 3000');
+});
+```
+
+```bash
+node app.js
+```
+
+| Feature | Supported |
+|---------|-----------|
+| Traces | Yes |
+| Logs | Yes |
+| Body Capture | **No** — set `SECURENOW_CAPTURE_BODY=0` (stream conflict) |
+
+---
+
+### Koa
+
+```bash
+npm install securenow koa @koa/router koa-bodyparser
+```
+
+```javascript
+// app.js
+'use strict';
+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) => {
+  const { title } = ctx.request.body;
+  if (!title) { ctx.status = 400; ctx.body = { error: 'title is required' }; return; }
+  console.log('Created task:', title);
+  ctx.status = 201;
+  ctx.body = { id: '1', title };
+});
+
+app.use(bodyParser());
+app.use(router.routes());
+app.use(router.allowedMethods());
+
+app.listen(3000, () => {
+  console.log('Koa app running on port 3000');
+});
+```
+
+```bash
+node app.js
+```
+
+| Feature | Supported |
+|---------|-----------|
+| Traces | Yes |
+| Logs | Yes |
+| Body Capture | Yes — set `SECURENOW_CAPTURE_BODY=1` |
+
+---
+
+### NestJS
+
+```bash
+npm install securenow
+```
+
+NestJS uses TypeScript. Create an `instrument.js` file in your project root to load SecureNow before anything else:
+
+```javascript
+// instrument.js
+require('securenow/register');
+```
+
+Your NestJS entry file stays unchanged:
+
+```typescript
+// src/main.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 app running on port 3000');
+}
+bootstrap();
+```
+
+**Development (ts-node):**
+
+```bash
+node -r ./instrument.js -r ts-node/register src/main.ts
+```
+
+**Production (compiled):**
+
+```bash
+node -r ./instrument.js dist/main.js
+```
+
+Add both to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "start:dev": "node -r ./instrument.js -r ts-node/register src/main.ts",
+    "start": "node -r ./instrument.js dist/main.js"
+  }
+}
+```
+
+| Feature | Supported |
+|---------|-----------|
+| Traces | Yes |
+| Logs | Yes |
+| Body Capture | Yes — set `SECURENOW_CAPTURE_BODY=1` |
+
+---
+
+### Hapi
+
+```bash
+npm install securenow @hapi/hapi
+```
+
+```javascript
+// app.js
+'use strict';
+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) => {
+      const { title } = request.payload || {};
+      if (!title) return h.response({ error: 'title is required' }).code(400);
+      console.log('Created task:', title);
+      return h.response({ id: '1', title }).code(201);
+    }
+  });
+
+  await server.start();
+  console.log('Hapi app running on port 3000');
+};
+
+init().catch((err) => { console.error(err); process.exit(1); });
+```
+
+```bash
+node app.js
+```
+
+| Feature | Supported |
+|---------|-----------|
+| Traces | Yes |
+| Logs | Yes |
+| Body Capture | **No** — set `SECURENOW_CAPTURE_BODY=0` (payload stream conflict) |
+
+---
+
+### h3 (UnJS / Nitro)
+
+```bash
+npm install securenow h3
+```
+
+```javascript
+// app.js
+'use strict';
+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(() => {
+  return { status: 'ok' };
+}));
+
+router.post('/tasks', defineEventHandler(async (event) => {
+  const body = await readBody(event);
+  if (!body?.title) { setResponseStatus(event, 400); return { error: 'title is required' }; }
+  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 app running on port 3000');
+});
+```
+
+```bash
+node app.js
+```
+
+| Feature | Supported |
+|---------|-----------|
+| Traces | Yes |
+| Logs | Yes |
+| Body Capture | Yes — set `SECURENOW_CAPTURE_BODY=1` |
+
+---
+
+### Polka
+
+```bash
+npm install securenow polka
+```
+
+Polka has no built-in body parser, so add a simple middleware:
+
+```javascript
+// app.js
+'use strict';
+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) => {
+    const { title } = req.body;
+    if (!title) return sendJson(res, 400, { error: 'title is required' });
+    console.log('Created task:', title);
+    sendJson(res, 201, { id: '1', title });
+  })
+  .listen(3000, () => {
+    console.log('Polka app running on port 3000');
+  });
+```
+
+```bash
+node app.js
+```
+
+| Feature | Supported |
+|---------|-----------|
+| Traces | Yes |
+| Logs | Yes |
+| Body Capture | Yes — set `SECURENOW_CAPTURE_BODY=1` |
+
+---
+
+### Micro / Raw HTTP
+
+For apps using the bare `http` module:
+
+```bash
+npm install securenow
+```
+
+```javascript
+// app.js
+'use strict';
+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 data = '';
+    req.on('data', chunk => { data += chunk; });
+    req.on('end', () => {
+      try { resolve(JSON.parse(data)); } catch { resolve({}); }
+    });
+  });
+}
+
+async function handler(req, res) {
+  const url = new URL(req.url, `http://${req.headers.host}`);
+
+  if (url.pathname === '/health' && req.method === 'GET') {
+    return sendJson(res, 200, { status: 'ok' });
+  }
+
+  if (url.pathname === '/tasks' && req.method === 'POST') {
+    const body = await readBody(req);
+    if (!body.title) return sendJson(res, 400, { error: 'title is required' });
+    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 app running on port 3000');
+});
+```
+
+```bash
+node app.js
+```
+
+| Feature | Supported |
+|---------|-----------|
+| Traces | Yes |
+| Logs | Yes |
+| Body Capture | Yes — set `SECURENOW_CAPTURE_BODY=1` |
+
+---
+
+### Hono
+
+```bash
+npm install securenow hono @hono/node-server
+```
+
+Hono uses ESM, so load SecureNow via the `-r` flag (do **not** use `require()` in `.mjs` files):
+
+```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();
+  if (!body.title) return c.json({ error: 'title is required' }, 400);
+  console.log('Created task:', body.title);
+  return c.json({ id: '1', title: body.title }, 201);
+});
+
+serve({ fetch: app.fetch, port: 3000 }, () => {
+  console.log('Hono app running on port 3000');
+});
+```
+
+```bash
+node -r securenow/register app.mjs
+```
+
+| Feature | Supported |
+|---------|-----------|
+| Traces | Yes |
+| Logs | Yes |
+| Body Capture | **No** — set `SECURENOW_CAPTURE_BODY=0` (stream conflict) |
+
+---
+
+### Feathers
+
+```bash
+npm install securenow @feathersjs/feathers @feathersjs/express @feathersjs/errors
+```
+
+Feathers uses Express as its transport, so the setup is identical:
+
+```javascript
+// app.js
+'use strict';
+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 app running on port 3000');
+});
+```
+
+```bash
+node app.js
+```
+
+| Feature | Supported |
+|---------|-----------|
+| Traces | Yes |
+| Logs | Yes |
+| Body Capture | Yes — set `SECURENOW_CAPTURE_BODY=1` |
+
+---
+
+### Next.js
+
+```bash
+npm install securenow
+```
+
+Create `instrumentation.ts` (or `.js`) in your project root (or `src/` if you use that layout):
+
+```typescript
+// instrumentation.ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    await import('securenow/register');
+  }
+}
+```
+
+Add to `.env.local`:
+
+```env
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_NO_UUID=1
+```
+
+**Or scaffold it automatically:**
+
+```bash
+npx securenow init
+```
+
+This creates both `instrumentation.ts` and `.env.local` for you.
+
+```bash
+npm run dev
+```
+
+| Feature | Supported |
+|---------|-----------|
+| Traces | Yes |
+| Logs | Yes |
+| Body Capture | Yes |
+
+See the [full Next.js guide](./NEXTJS-SETUP-COMPLETE.md) for App Router, middleware, and server actions.
+
+---
+
+## Step 4 — Verify It Works
+
+After starting your app, you should see this in the console:
+
+```
+[securenow] OTel SDK started → https://freetrial.securenow.ai:4318/v1/traces
+[securenow] 📋 Logging: ENABLED → https://freetrial.securenow.ai:4318/v1/logs
+```
+
+Send a test request:
+
+```bash
+curl http://localhost:3000/health
+```
+
+Then check traces from the CLI:
+
+```bash
+npx securenow traces --app my-app
+```
+
+Traces and logs should appear within seconds.
+
+---
+
+## Step 5 — CLI Command Reference
+
+The SecureNow CLI is your terminal command center. Below is every command organized by workflow.
+
+### Authentication
+
+| Command | What It Does |
+|---------|-------------|
+| `securenow login` | Opens browser to authenticate |
+| `securenow login --token <T>` | Authenticate with a token (for CI/CD or headless servers) |
+| `securenow logout` | Clear stored credentials |
+| `securenow whoami` | Show current session (email, API URL, expiry, default app) |
+
+### App Management
+
+| Command | What It Does |
+|---------|-------------|
+| `securenow apps list` | List all your applications |
+| `securenow apps create <name>` | Create a new app (interactive instance picker) |
+| `securenow apps create <name> --hosts api.example.com` | Create with host binding |
+| `securenow apps info <id>` | Show app details + env variables |
+| `securenow apps delete <id>` | Delete an app |
+| `securenow apps default <key>` | Set default app for CLI commands |
+| `securenow apps discover --domain example.com` | Discover subdomains and add as apps |
+| `securenow apps scan --yes` | Scan all app domains for new subdomains |
+
+### Observe — Traces & Logs
+
+| Command | What It Does |
+|---------|-------------|
+| `securenow traces` | List recent traces |
+| `securenow traces --app my-app --limit 50` | Filtered trace list |
+| `securenow traces show <traceId>` | Show all spans in a trace |
+| `securenow traces analyze <traceId>` | AI-powered security analysis of a trace |
+| `securenow logs` | List recent logs |
+| `securenow logs --app my-app --minutes 30 --level ERROR` | Filtered logs |
+| `securenow logs trace <traceId>` | Show all logs for a specific trace |
+| `securenow analytics --app my-app` | Response code breakdown (2xx/3xx/4xx/5xx) |
+| `securenow status` | Dashboard overview (apps, alerts, protection status) |
+
+### Detect & Respond — Issues, Alerts, Notifications
+
+| Command | What It Does |
+|---------|-------------|
+| `securenow issues` | List security issues |
+| `securenow issues --status open` | Filter by status |
+| `securenow issues show <id>` | Full issue detail + AI analysis |
+| `securenow issues resolve <id>` | Mark issue as resolved |
+| `securenow alerts rules` | List alert rules |
+| `securenow alerts channels` | List alert channels (email, webhook, Slack) |
+| `securenow alerts history --limit 50` | View past triggered alerts |
+| `securenow notifications` | List notifications |
+| `securenow notifications unread` | Show unread count |
+| `securenow notifications read <id>` | Mark one as read |
+| `securenow notifications read-all` | Mark all as read |
+
+### Investigate — IP Intelligence & Forensics
+
+| Command | What It Does |
+|---------|-------------|
+| `securenow ip <ip-address>` | Full IP intelligence report (country, ISP, abuse score, risk factors) |
+| `securenow ip traces <ip-address>` | Show all traces from a specific IP |
+| `securenow forensics "<query>"` | **Chat with your data** — natural language to SQL (see below) |
+| `securenow forensics library` | View saved forensic queries |
+| `securenow api-map` | List all discovered API endpoints |
+| `securenow api-map stats` | API map statistics |
+
+### Remediation — Blocklist & Trusted IPs
+
+| Command | What It Does |
+|---------|-------------|
+| `securenow blocklist` | List all blocked IPs |
+| `securenow blocklist add <ip>` | Block an IP address |
+| `securenow blocklist add <cidr> --reason "brute force"` | Block a CIDR range with reason |
+| `securenow blocklist remove <id>` | Unblock an IP |
+| `securenow blocklist stats` | Blocklist statistics |
+| `securenow trusted` | List trusted IPs |
+| `securenow trusted add <ip> --label "office"` | Add a trusted IP |
+| `securenow trusted remove <id>` | Remove a trusted IP |
+
+### Settings & Config
+
+| Command | What It Does |
+|---------|-------------|
+| `securenow config set <key> <value>` | Set a config value |
+| `securenow config get [key]` | Get a config value (or show all) |
+| `securenow config path` | Show config + credentials file paths |
+| `securenow instances` | List ClickHouse instances |
+| `securenow instances test <id>` | Test an instance connection |
+| `securenow version` | Show CLI version |
+
+### Global Flags
+
+Every command supports:
+
+| Flag | Effect |
+|------|--------|
+| `--json` | Output raw JSON (pipe to `jq`, scripts, etc.) |
+| `--help` | Show help for any command |
+| `--app <key>` | Override the default app for this command |
+
+---
+
+## Step 6 — Forensics Chat — Ask Questions in Plain English
+
+The `securenow forensics` command lets you **ask security questions in plain English**. SecureNow translates your question to SQL, runs it against your ClickHouse traces database, and returns the results.
+
+### How to Use
+
+```bash
+npx securenow forensics "your question here"
+```
+
+### Example Queries
+
+**Find suspicious activity:**
+
+```bash
+npx securenow forensics "show me all 401 responses in the last hour"
+```
+
+**Hunt for attackers:**
+
+```bash
+npx securenow forensics "which IPs sent the most requests in the last 24 hours"
+```
+
+**Find slow endpoints:**
+
+```bash
+npx securenow forensics "show the slowest API endpoints this week"
+```
+
+**Investigate a specific IP:**
+
+```bash
+npx securenow forensics "show all requests from 185.220.101.1 in the last 7 days"
+```
+
+**Error analysis:**
+
+```bash
+npx securenow forensics "count 500 errors per endpoint in the last 24 hours"
+```
+
+**Brute force detection:**
+
+```bash
+npx securenow forensics "find IPs that sent more than 100 POST requests to /login today"
+```
+
+**Data exfiltration patterns:**
+
+```bash
+npx securenow forensics "show requests with response bodies larger than 1MB"
+```
+
+### How It Works
+
+1. You type a question in English
+2. SecureNow's AI converts it to a SQL query
+3. The query runs against your ClickHouse traces database
+4. Results are displayed as a table in your terminal
+
+The CLI shows you both the generated SQL and the results:
+
+```
+  Generated SQL
+
+    SELECT ClientIP, count() as cnt FROM traces
+    WHERE Timestamp > now() - INTERVAL 1 HOUR AND ResponseStatusCode = 401
+    GROUP BY ClientIP ORDER BY cnt DESC LIMIT 20
+
+  Results (5 rows)
+
+    ClientIP          cnt
+    185.220.101.1     342
+    45.134.26.8       128
+    ...
+```
+
+### Save & Reuse Queries
+
+View your saved query library:
+
+```bash
+npx securenow forensics library
+```
+
+### Output as JSON
+
+Pipe forensic results to scripts or other tools:
+
+```bash
+npx securenow forensics "top 10 IPs by request count today" --json | jq '.result'
+```
+
+---
+
+## Step 7 — Block & Manage IPs
+
+SecureNow gives you full IP lifecycle management — investigate, block, trust, and audit.
+
+### Investigate an IP
+
+Before blocking, look up the IP's intelligence:
+
+```bash
+npx securenow ip 185.220.101.1
+```
+
+Output:
+
+```
+  IP Intelligence: 185.220.101.1
+
+    Country       Germany (DE)
+    ISP           Tor Exit Node
+    Usage Type    Hosting
+    Abuse Score   100/100
+    Malicious     Yes
+    Bot           Yes
+    Total Reports 4,521
+
+  Risk Factors
+    • Known Tor exit node
+    • High abuse confidence score
+    • Associated with brute force attacks
+
+  Attack Types
+    • SSH Brute Force
+    • Web Application Attack
+    • Port Scanning
+```
+
+### See What That IP Did
+
+```bash
+npx securenow ip traces 185.220.101.1
+```
+
+Shows all traced requests from that IP — method, status code, URL, duration, and time.
+
+### Block an IP
+
+```bash
+npx securenow blocklist add 185.220.101.1 --reason "tor exit node, brute force"
+```
+
+Block a CIDR range:
+
+```bash
+npx securenow blocklist add 185.220.101.0/24 --reason "malicious subnet"
+```
+
+Block with an expiration:
+
+```bash
+npx securenow blocklist add 45.134.26.8 --reason "rate limiting" --duration 24h
+```
+
+### View All Blocked IPs
+
+```bash
+npx securenow blocklist
+```
+
+Output:
+
+```
+  ID           IP/CIDR            Reason                    Source     Added        Expires
+  abc123...    185.220.101.1      tor exit node             manual     2 hours ago  permanent
+  def456...    185.220.101.0/24   malicious subnet          manual     1 hour ago   permanent
+  ghi789...    45.134.26.8        rate limiting             manual     30 min ago   2024-01-16
+```
+
+### Unblock an IP
+
+```bash
+npx securenow blocklist remove abc123
+```
+
+### Blocklist Statistics
+
+```bash
+npx securenow blocklist stats
+```
+
+Shows total active blocks, removed blocks, manual vs automated counts, and active automation rules.
+
+### Trust an IP (Whitelist)
+
+Trusted IPs bypass security detections:
+
+```bash
+npx securenow trusted add 203.0.113.50 --label "office VPN"
+```
+
+List trusted IPs:
+
+```bash
+npx securenow trusted
+```
+
+Remove a trusted IP:
+
+```bash
+npx securenow trusted remove <id>
+```
+
+### Full Investigation → Block Workflow
+
+Here is the typical workflow for handling a suspicious IP:
+
+```bash
+# 1. Check forensics for anomalies
+npx securenow forensics "IPs with more than 50 failed login attempts today"
+
+# 2. Pick a suspicious IP and investigate
+npx securenow ip 185.220.101.1
+
+# 3. See exactly what it did
+npx securenow ip traces 185.220.101.1
+
+# 4. Block it
+npx securenow blocklist add 185.220.101.1 --reason "brute force login attempts"
+
+# 5. Verify it's blocked
+npx securenow blocklist
+```
+
+---
+
+## Step 8 — Monitor, Detect & Respond
+
+### Daily Monitoring
+
+```bash
+# Quick overview of all your apps
+npx securenow status
+
+# Check for unread alerts
+npx securenow notifications unread
+
+# List open security issues
+npx securenow issues --status open
+```
+
+### Respond to an Issue
+
+```bash
+# Read the full issue detail (includes AI analysis)
+npx securenow issues show <id>
+
+# If it's resolved, mark it
+npx securenow issues resolve <id>
+```
+
+### AI Trace Analysis
+
+Let SecureNow's AI analyze a suspicious trace for security issues:
+
+```bash
+npx securenow traces analyze <traceId>
+```
+
+Returns a summary, risk level, specific security issues found, and recommended actions.
+
+### Set Up Alerts
+
+Configure alert rules and channels from the [dashboard](https://app.securenow.ai/dashboard), then monitor from the CLI:
+
+```bash
+# List your alert rules
+npx securenow alerts rules
+
+# List alert channels (email, Slack, webhook)
+npx securenow alerts channels
+
+# View alert history
+npx securenow alerts history --limit 20
+```
+
+---
+
+## Deployment
+
+### PM2 Setup (All Frameworks)
+
+```javascript
+// ecosystem.config.cjs
+module.exports = {
+  apps: [{
+    name: 'my-app',
+    script: './app.js',
+    node_args: '-r securenow/register',
+    env: {
+      SECURENOW_APPID: 'my-app',
+      SECURENOW_INSTANCE: 'https://freetrial.securenow.ai:4318',
+      SECURENOW_LOGGING_ENABLED: '1',
+      SECURENOW_NO_UUID: '1',
+      SECURENOW_CAPTURE_BODY: '1',
+      PORT: 3000,
+    }
+  }]
+};
+```
+
+```bash
+pm2 start ecosystem.config.cjs
+```
+
+**NestJS (TypeScript):**
+
+```javascript
+{
+  name: 'my-nestjs-app',
+  script: 'dist/main.js',
+  node_args: '-r ./instrument.js',
+  env: { /* same as above */ }
+}
+```
+
+**Hono (ESM `.mjs`):**
+
+```javascript
+{
+  name: 'my-hono-app',
+  script: 'app.mjs',
+  node_args: '-r securenow/register',
+  env: {
+    SECURENOW_CAPTURE_BODY: '0',  // Required for Hono
+    /* ... other vars ... */
+  }
+}
+```
+
+### Docker
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+COPY . .
+
+ENV SECURENOW_APPID=my-app
+ENV SECURENOW_INSTANCE=https://collector:4318
+ENV SECURENOW_LOGGING_ENABLED=1
+ENV SECURENOW_NO_UUID=1
+
+EXPOSE 3000
+CMD ["node", "-r", "securenow/register", "app.js"]
+```
+
+---
+
+## Compatibility Matrix
+
+| Framework | Traces | Logs | Body Capture | Init Method | Notes |
+|-----------|--------|------|--------------|-------------|-------|
+| Express | Yes | Yes | Yes | `require()` or `-r` | Fully compatible |
+| Fastify | Yes | Yes | **No** | `require()` or `-r` | Set `SECURENOW_CAPTURE_BODY=0` |
+| Koa | Yes | Yes | Yes | `require()` or `-r` | Needs `koa-bodyparser` |
+| NestJS | Yes | Yes | Yes | `instrument.js` + `-r ./instrument.js` | Create `instrument.js` with `require('securenow/register')` |
+| Hapi | Yes | Yes | **No** | `require()` or `-r` | Set `SECURENOW_CAPTURE_BODY=0` |
+| h3 | Yes | Yes | Yes | `require()` or `-r` | Uses `toNodeListener()` |
+| Polka | Yes | Yes | Yes | `require()` or `-r` | Needs manual body parser |
+| Micro/HTTP | Yes | Yes | Yes | `require()` or `-r` | Raw `http.createServer` |
+| Hono | Yes | Yes | **No** | `-r` flag only (ESM) | Set `SECURENOW_CAPTURE_BODY=0` |
+| Feathers | Yes | Yes | Yes | `require()` or `-r` | Express transport |
+| Next.js | Yes | Yes | Yes | `instrumentation.ts` | Use `securenow init` |
+
+---
+
+## Troubleshooting
+
+### Traces not appearing
+
+1. Verify `SECURENOW_APPID` and `SECURENOW_INSTANCE` are set
+2. Set `SECURENOW_NO_UUID=1` so the dashboard matches your app key exactly
+3. Enable debug logging: `OTEL_LOG_LEVEL=debug node -r securenow/register app.js`
+
+### Logs not appearing
+
+1. Confirm `SECURENOW_LOGGING_ENABLED=1` is set
+2. Check that startup output shows `📋 Logging: ENABLED`
+3. Any `console.log` / `console.error` in your app automatically becomes an OTLP log record
+
+### ESM apps (.mjs / "type": "module")
+
+Use `NODE_OPTIONS="-r securenow/register"` or `node -r securenow/register app.mjs`.
+Do **not** add `require('securenow/register')` inside `.mjs` files.
+
+### Body capture crashes / empty payloads
+
+Set `SECURENOW_CAPTURE_BODY=0` for Fastify, Hapi, and Hono. These frameworks use custom stream handling that conflicts with the body capture hook.
+
+### CLI says "Not logged in"
+
+```bash
+npx securenow login
+```
+
+Or re-authenticate with a token:
+
+```bash
+npx securenow login --token <YOUR_TOKEN>
+```
+
+### CLI says "Session expired"
+
+Tokens expire after a set period. Re-run `securenow login` to get a fresh session.
+
+---
+
+## Complete Documentation
+
+- [Express Guide](./EXPRESS-SETUP-GUIDE.md)
+- [Next.js Guide](./NEXTJS-SETUP-COMPLETE.md)
+- [Logging Guide](./LOGGING-GUIDE.md)
+- [Environment Variables](./ENVIRONMENT-VARIABLES.md)
+- [Body Capture](./REQUEST-BODY-CAPTURE.md)
+- [NPM README](../NPM_README.md)