securenow 7.7.14 → 7.7.15

package/SKILL-API.md

@@ -1,74 +1,74 @@
-# SecureNow SDK — Agent Skill
-
-Instrument any Node.js application with OpenTelemetry tracing, structured logging, request body capture, and a multi-layer IP firewall. Supports Express, Fastify, NestJS, Koa, Hapi, Next.js, Nuxt 3, Vite (browser), and raw `http.createServer` — with zero code changes for most setups.
-
-**CLI parity:** every capability exposed below (redaction, CIDR matching, log/span emission, firewall preload, config inspection) has an equivalent `securenow` CLI command. See [SKILL-CLI.md](./SKILL-CLI.md) for the terminal surface.
-
+# SecureNow SDK — Agent Skill
+
+Instrument any Node.js application with OpenTelemetry tracing, structured logging, request body capture, and a multi-layer IP firewall. Supports Express, Fastify, NestJS, Koa, Hapi, Next.js, Nuxt 3, Vite (browser), and raw `http.createServer` — with zero code changes for most setups.
+
+**CLI parity:** every capability exposed below (redaction, CIDR matching, log/span emission, firewall preload, config inspection) has an equivalent `securenow` CLI command. See [SKILL-CLI.md](./SKILL-CLI.md) for the terminal surface.
+
 **MCP parity (v7.5+):** `npx securenow mcp` starts a local stdio MCP server for Codex, Claude, and other MCP clients. It reuses the same `.securenow/credentials.json` file as the CLI/SDK and exposes SecureNow tools, bundled docs resources, and setup prompts to agents. Alert-rule operators can inspect notifications, read exact `metadata.matchedSubdetectors`, dry-run candidate SQL with `securenow_alert_rule_candidate_test`, and apply global system-rule query fixes with `securenow_alert_rule_query_update` when evidence is clear.
 
 **Noisy alert-rule reviews:** prefer fixing a generic system-rule detector over creating customer-specific false positives. Dry-run candidate SQL first, preserve tenant scoping with `__USER_APP_KEYS__`, keep exploit-specific indicators, then save the shared query mapping only with an audit reason and explicit confirmation.
-
-## Installation
-
-```bash
-npm install securenow@latest
-```
-
-### Install This Skill in Cursor
-
-Save this file as `.cursor/skills/securenow-api/SKILL.md` in your project. Your AI agent will auto-discover it whenever you ask about integrating securenow, configuring tracing, setting up the firewall, or instrumenting any framework.
-
-## Quick Start — Any Node.js Framework
-
-### 1. Install, Login, And Init
-
-```bash
-npm install securenow@latest
-node -p "require('./node_modules/securenow/package.json').version"
-npx securenow version
-npx securenow login
-npx securenow init
-```
-
-Use `securenow@7.5.1` or newer. Start authentication with `npx securenow login`; do not manually open auth URLs, because the CLI generates the callback/state values. The login flow lets the user pick or create an app, enables the app firewall by default, writes `.securenow/credentials.json`, and `init` scaffolds the framework integration.
-
-### 2. Run With Instrumentation
-
-**Option A — CLI (recommended):**
-
-```bash
-npx securenow run src/index.js
-```
-
-**Option B — Node preload flag:**
-
-```bash
-node -r securenow/register src/index.js
-```
-
-**Option C — Auto-setup for Next.js:**
-
-```bash
-npx securenow init
-```
-
-That's it. Traces, logs, request body capture, multipart metadata capture, and firewall enforcement are on by default. No code changes for Express, Fastify, NestJS, Koa, Hapi, and raw Node.
-
-### 3. Firewall Is Enabled by Default
-
-Since v7.5.1, the browser login flow connects the firewall automatically after
-the user picks or creates an app. The firewall key lives in your credentials
-file — no env var required:
-
-```bash
-npx securenow login              # pick/create app; firewall key is minted automatically
-# or, if you already have one:
-npx securenow api-key set snk_live_abc123...
-```
-
-Both paths write the key to `.securenow/credentials.json` (auto-gitignored) and the firewall activates on next start. For production, run `npx securenow credentials runtime --env production` and mount/copy the tokenless file as `.securenow/credentials.json`.
-
-The firewall syncs your blocklist and enforces it on every request — zero code changes.
+
+## Installation
+
+```bash
+npm install securenow@latest
+```
+
+### Install This Skill in Cursor
+
+Save this file as `.cursor/skills/securenow-api/SKILL.md` in your project. Your AI agent will auto-discover it whenever you ask about integrating securenow, configuring tracing, setting up the firewall, or instrumenting any framework.
+
+## Quick Start — Any Node.js Framework
+
+### 1. Install, Login, And Init
+
+```bash
+npm install securenow@latest
+node -p "require('./node_modules/securenow/package.json').version"
+npx securenow version
+npx securenow login
+npx securenow init
+```
+
+Use `securenow@7.5.1` or newer. Start authentication with `npx securenow login`; do not manually open auth URLs, because the CLI generates the callback/state values. The login flow lets the user pick or create an app, enables the app firewall by default, writes `.securenow/credentials.json`, and `init` scaffolds the framework integration.
+
+### 2. Run With Instrumentation
+
+**Option A — CLI (recommended):**
+
+```bash
+npx securenow run src/index.js
+```
+
+**Option B — Node preload flag:**
+
+```bash
+node -r securenow/register src/index.js
+```
+
+**Option C — Auto-setup for Next.js:**
+
+```bash
+npx securenow init
+```
+
+That's it. Traces, logs, request body capture, multipart metadata capture, and firewall enforcement are on by default. No code changes for Express, Fastify, NestJS, Koa, Hapi, and raw Node.
+
+### 3. Firewall Is Enabled by Default
+
+Since v7.5.1, the browser login flow connects the firewall automatically after
+the user picks or creates an app. The firewall key lives in your credentials
+file — no env var required:
+
+```bash
+npx securenow login              # pick/create app; firewall key is minted automatically
+# or, if you already have one:
+npx securenow api-key set snk_live_abc123...
+```
+
+Both paths write the key to `.securenow/credentials.json` (gitignored via credential-file patterns, not a whole-directory `.securenow/` ignore) and the firewall activates on next start. For production, run `npx securenow credentials runtime --env production` and mount/copy the tokenless file as `.securenow/credentials.json`.
+
+The firewall syncs your blocklist and enforces it on every request — zero code changes.
 
 Blocklist unblocks are audit-preserving: dashboard/API/CLI/MCP unblock actions
 mark the active block as `removed`, invalidate firewall sync, clear expiry to
@@ -76,9 +76,10 @@ avoid TTL deletion, and retain block reports/history for future review or
 reblock context.
 
 For near-realtime propagation after a block/unblock, set
-`SECURENOW_FIREWALL_VERSION_INTERVAL=1` or `2` in the protected app. The SDK
-polls `/firewall/sync` with ETag/304, so unchanged checks are lightweight; keep
-`SECURENOW_FIREWALL_SYNC_INTERVAL` high as a safety-net full refresh.
+`config.firewall.versionCheckInterval` to `1` or `2` in the protected app's
+`.securenow/credentials.json`. The SDK polls `/firewall/sync` with ETag/304, so
+unchanged checks are lightweight; keep `config.firewall.syncInterval` high as a
+safety-net full refresh.
 
 Default automation is active for new and existing customers. The API
 idempotently provisions risk-score rules for all apps/environments:
@@ -87,52 +88,52 @@ Run `securenow automation defaults --yes` or the API backfill script when an
 operator needs to ensure those defaults immediately.
 
 ---
-
-## Import Map
-
-| Import | Purpose | Type |
-|--------|---------|------|
-| `securenow` / `securenow/register` | Auto-register tracing + firewall (side-effect) | Preload (`-r`) |
-| `securenow/tracing` | Core OTel SDK; exports `getLogger()`, `isLoggingEnabled()` | CJS |
-| `securenow/nextjs` | Next.js instrumentation; exports `registerSecureNow(options?)` | CJS |
-| `securenow/nextjs-webpack-config` | Next.js config wrapper; exports `withSecureNow()`, `getSecureNowWebpackConfig()`, `EXTERNAL_PACKAGES` | CJS |
-| `securenow/nextjs-middleware` | Edge middleware body capture; exports `middleware()`, `redactSensitiveData()`, `DEFAULT_SENSITIVE_FIELDS` | CJS |
-| `securenow/nextjs-wrapper` | Route handler wrappers; exports `withSecureNow()`, `withSecureNowAsync()`, `captureRequestBody()`, `redactSensitiveData()` | CJS |
-| `securenow/nextjs-auto-capture` | Auto-patch Next request for body capture; exports `patchNextRequest()`, `safeBodyCapture()`, `redactSensitiveData()`, `isBodyCaptureEnabled()` | CJS |
+
+## Import Map
+
+| Import | Purpose | Type |
+|--------|---------|------|
+| `securenow` / `securenow/register` | Auto-register tracing + firewall (side-effect) | Preload (`-r`) |
+| `securenow/tracing` | Core OTel SDK; exports `getLogger()`, `isLoggingEnabled()` | CJS |
+| `securenow/nextjs` | Next.js instrumentation; exports `registerSecureNow(options?)` | CJS |
+| `securenow/nextjs-webpack-config` | Next.js config wrapper; exports `withSecureNow()`, `getSecureNowWebpackConfig()`, `EXTERNAL_PACKAGES` | CJS |
+| `securenow/nextjs-middleware` | Edge middleware body capture; exports `middleware()`, `redactSensitiveData()`, `DEFAULT_SENSITIVE_FIELDS` | CJS |
+| `securenow/nextjs-wrapper` | Route handler wrappers; exports `withSecureNow()`, `withSecureNowAsync()`, `captureRequestBody()`, `redactSensitiveData()` | CJS |
+| `securenow/nextjs-auto-capture` | Auto-patch Next request for body capture; exports `patchNextRequest()`, `safeBodyCapture()`, `redactSensitiveData()`, `isBodyCaptureEnabled()` | CJS |
 | `securenow/nuxt` | Nuxt 3 module (add to `modules` array) | ESM |
 | `securenow/firewall` | Standalone firewall; exports `init()`, `shutdown()`, `getStats()`, `getMatcher()`, `getAllowlistMatcher()` | CJS |
 | `securenow/rate-limits` | Rate-limit remediation API helper; exports `parseRateLimitText()`, `createRateLimitFromText()`, `createRateLimit()`, `listRateLimits()` | CJS |
 | `securenow/firewall-only` | Preload: dotenv + firewall only, no tracing | Preload (`-r`) |
-| `securenow/cidr` | CIDR utilities; exports `createMatcher()`, `ipToInt()`, `parseCidr()`, `matchesCidr()` | CJS |
-| `securenow/resolve-ip` | IP resolution; exports `resolveClientIp()`, `resolveSocketIp()`, `isFromTrustedProxy()` | CJS |
-| `securenow/console-instrumentation` | Console→OTLP bridge; exports `originalConsole`, `restoreConsole()` | CJS |
-| `securenow/web-vite` | Browser OTel (document load, fetch, XHR, user interaction); default export `startSecurenowWeb()` | ESM |
-| `securenow/register-vite` | CJS bridge for Vite preload | CJS |
-
----
-
-## Framework Integration Guides
-
-### Express / Fastify / NestJS / Koa / Hapi / Raw Node
-
-No code changes. Use the preload:
-
-```bash
-node -r securenow/register app.js
-```
-
-Or with the CLI:
-
-```bash
-npx securenow run app.js
-```
-
-**PM2:**
-
-```javascript
-// ecosystem.config.cjs
-module.exports = {
-  apps: [{
+| `securenow/cidr` | CIDR utilities; exports `createMatcher()`, `ipToInt()`, `parseCidr()`, `matchesCidr()` | CJS |
+| `securenow/resolve-ip` | IP resolution; exports `resolveClientIp()`, `resolveSocketIp()`, `isFromTrustedProxy()` | CJS |
+| `securenow/console-instrumentation` | Console→OTLP bridge; exports `originalConsole`, `restoreConsole()` | CJS |
+| `securenow/web-vite` | Browser OTel (document load, fetch, XHR, user interaction); default export `startSecurenowWeb()` | ESM |
+| `securenow/register-vite` | CJS bridge for Vite preload | CJS |
+
+---
+
+## Framework Integration Guides
+
+### Express / Fastify / NestJS / Koa / Hapi / Raw Node
+
+No code changes. Use the preload:
+
+```bash
+node -r securenow/register app.js
+```
+
+Or with the CLI:
+
+```bash
+npx securenow run app.js
+```
+
+**PM2:**
+
+```javascript
+// ecosystem.config.cjs
+module.exports = {
+  apps: [{
     name: 'my-app',
     script: './app.js',
     instances: 4,
@@ -141,16 +142,16 @@ module.exports = {
   }],
 };
 ```
-
-**Docker:**
-
+
+**Docker:**
+
 ```dockerfile
 COPY .securenow/credentials.json ./.securenow/credentials.json
 CMD ["node", "-r", "securenow/register", "app.js"]
 ```
-
----
-
+
+---
+
 ### Next.js
 
 Run `npx securenow init` first. It creates the straightforward integration below when files are missing, and prints a Codex/Claude-ready merge prompt when existing files need careful edits.
@@ -182,13 +183,13 @@ export async function register() {
   await import(/* webpackIgnore: true */ 'securenow/nextjs-auto-capture');
 }
 ```
-
-`registerSecureNow(options?)` accepts:
-
+
+`registerSecureNow(options?)` accepts:
+
 ```typescript
 interface RegisterOptions {
   serviceName?: string;   // override credentials app key/name
-  endpoint?: string;      // override credentials app instance
+  endpoint?: string;      // advanced OTLP endpoint override
   noUuid?: boolean;       // override credentials config.runtime.noUuid
   captureBody?: boolean;  // override credentials config.capture.body
 }
@@ -203,7 +204,7 @@ On Vercel it uses `@vercel/otel`; self-hosted uses vanilla `@opentelemetry/sdk-n
   "app": {
     "key": "<uuid>",
     "name": "my-nextjs-app",
-    "instance": "https://freetrial.securenow.ai:4318"
+    "instance": "https://ingest.securenow.ai"
   },
   "config": {
     "logging": { "enabled": true },
@@ -214,13 +215,13 @@ On Vercel it uses `@vercel/otel`; self-hosted uses vanilla `@opentelemetry/sdk-n
 ```
 
 Local development and production do not need `.env.local`; `npx securenow login` and `npx securenow init` keep `.securenow/credentials.json` filled and gitignored. For production, run `npx securenow credentials runtime --env production` and mount/copy the generated JSON as `.securenow/credentials.json`.
-
-#### Next.js Body Capture
-
-**Option A — Auto-capture (recommended):**
-
-Add to your `instrumentation.ts`:
-
+
+#### Next.js Body Capture
+
+**Option A — Auto-capture (recommended):**
+
+Add to your `instrumentation.ts`:
+
 ```typescript
 export async function register() {
   if (process.env.NEXT_RUNTIME !== 'nodejs') return;
@@ -231,42 +232,42 @@ export async function register() {
   await import(/* webpackIgnore: true */ 'securenow/nextjs-auto-capture');
 }
 ```
-
-**Option B — Middleware:**
-
-```typescript
-// middleware.ts
-export { middleware } from 'securenow/nextjs-middleware';
-export const config = { matcher: ['/api/:path*'] };
-```
-
-**Option C — Per-route wrapper:**
-
-```typescript
-import { withSecureNow } from 'securenow/nextjs-wrapper';
-
-export const POST = withSecureNow(async (req) => {
-  // handler
-});
-```
-
-#### Next.js with `securenow init`
-
-```bash
-npx securenow login
-npx securenow init
-```
-
+
+**Option B — Middleware:**
+
+```typescript
+// middleware.ts
+export { middleware } from 'securenow/nextjs-middleware';
+export const config = { matcher: ['/api/:path*'] };
+```
+
+**Option C — Per-route wrapper:**
+
+```typescript
+import { withSecureNow } from 'securenow/nextjs-wrapper';
+
+export const POST = withSecureNow(async (req) => {
+  // handler
+});
+```
+
+#### Next.js with `securenow init`
+
+```bash
+npx securenow login
+npx securenow init
+```
+
 Auto-detects Next.js, creates `instrumentation.ts`, adds `serverExternalPackages: ['securenow']` plus `outputFileTracingIncludes` when safe, and reuses the app, instance, firewall key, and secure defaults in `.securenow/credentials.json`. If files already exist, it prints an agent-ready prompt with the exact edits to propose.
-
----
-
-### Nuxt 3
-
-**`nuxt.config.ts`:**
-
-```typescript
-export default defineNuxtConfig({
+
+---
+
+### Nuxt 3
+
+**`nuxt.config.ts`:**
+
+```typescript
+export default defineNuxtConfig({
   modules: ['securenow/nuxt'],
   securenow: {
     // optional overrides (defaults come from .securenow/credentials.json)
@@ -275,60 +276,60 @@ export default defineNuxtConfig({
 ```
 
 The Nuxt module auto-configures Nitro externals, runtime config, and a server plugin that sets up OTel tracing + logging + firewall. Local and production app identity, firewall key, and secure defaults come from `.securenow/credentials.json`.
-
----
-
-### Vite / Browser
-
-```javascript
-import startSecurenowWeb from 'securenow/web-vite';
-
-startSecurenowWeb({
-  serviceName: 'my-frontend',
-  endpoint: 'https://your-collector:4318',
-});
-```
-
-Instruments document load, fetch, XMLHttpRequest, and user interactions with browser-side OpenTelemetry.
-
----
-
-## Firewall — Multi-Layer IP Blocking
-
-The firewall auto-activates once an API key is resolvable and the app firewall toggle is on. Since **v7.5.1**, `npx securenow login` enables the selected app firewall by default and writes the scoped key to `.securenow/credentials.json`; `securenow api-key set` can still write/rotate the key later. Production should use the tokenless file generated by `securenow credentials runtime --env production`. Resolution order: project `./.securenow/credentials.json` -> project named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order -> global `~/.securenow/credentials.json` -> global named runtime credentials in the same fixed order; legacy env vars are fallback-only for existing deployments and do not choose the credentials filename.
-
-```
-Layer 4: Cloud/Edge WAF    →  blocked at CDN (Cloudflare, AWS WAF, GCP Cloud Armor)
-Layer 3: OS Firewall       →  kernel-level DROP (iptables/nftables)
-Layer 2: TCP Socket        →  socket.destroy() before HTTP parsing
-Layer 1: HTTP Handler      →  403 JSON response (always active)
-```
-
-### Activate
-
-```bash
-# Zero-config (recommended) — writes the key to .securenow/credentials.json
-npx securenow login              # pick/create app; firewall connects automatically
-# or, if you already have a key:
-npx securenow api-key set snk_live_abc123...
-
+
+---
+
+### Vite / Browser
+
+```javascript
+import startSecurenowWeb from 'securenow/web-vite';
+
+startSecurenowWeb({
+  serviceName: 'my-frontend',
+  endpoint: 'https://ingest.securenow.ai',
+});
+```
+
+Instruments document load, fetch, XMLHttpRequest, and user interactions with browser-side OpenTelemetry.
+
+---
+
+## Firewall — Multi-Layer IP Blocking
+
+The firewall auto-activates once an API key is resolvable and the app firewall toggle is on. Since **v7.5.1**, `npx securenow login` enables the selected app firewall by default and writes the scoped key to `.securenow/credentials.json`; `securenow api-key set` can still write/rotate the key later. Production should use the tokenless file generated by `securenow credentials runtime --env production`. Resolution order: project `./.securenow/credentials.json` -> project named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order -> global `~/.securenow/credentials.json` -> global named runtime credentials in the same fixed order. Runtime config is credentials-json based; legacy env fallback is disabled unless `SECURENOW_ENABLE_LEGACY_ENV=1` is explicitly set for an old deployment.
+
+```
+Layer 4: Cloud/Edge WAF    →  blocked at CDN (Cloudflare, AWS WAF, GCP Cloud Armor)
+Layer 3: OS Firewall       →  kernel-level DROP (iptables/nftables)
+Layer 2: TCP Socket        →  socket.destroy() before HTTP parsing
+Layer 1: HTTP Handler      →  403 JSON response (always active)
+```
+
+### Activate
+
+```bash
+# Zero-config (recommended) — writes the key to .securenow/credentials.json
+npx securenow login              # pick/create app; firewall connects automatically
+# or, if you already have a key:
+npx securenow api-key set snk_live_abc123...
+
 # Production runtime file:
 npx securenow credentials runtime --env production
-```
-
-### Firewall-Only Mode (No Tracing Overhead)
-
-```bash
-node -r securenow/firewall-only app.js
-
-# Or via the CLI (same effect)
-securenow run --firewall-only app.js
-```
-
-Loads only dotenv + firewall. No OpenTelemetry, no tracing, no external packages needed.
-
-### Programmatic Firewall API
-
+```
+
+### Firewall-Only Mode (No Tracing Overhead)
+
+```bash
+node -r securenow/firewall-only app.js
+
+# Or via the CLI (same effect)
+securenow run --firewall-only app.js
+```
+
+Loads only dotenv + firewall. No OpenTelemetry, no tracing, no external packages needed.
+
+### Programmatic Firewall API
+
 ```javascript
 const firewall = require('securenow/firewall');
 const appConfig = require('securenow/app-config');
@@ -338,260 +339,260 @@ await firewall.init({
   apiUrl: 'https://api.securenow.ai',
   syncInterval: 3600,       // safety-net full sync every hour
   versionCheckInterval: 10, // lightweight ETag check every 10s
-  failMode: 'open',         // 'open' or 'closed'
-  statusCode: 403,
-  log: true,
-  tcp: false,
-  iptables: false,
-  cloud: null,              // 'cloudflare' | 'aws' | 'gcp'
-});
-
-const stats = firewall.getStats();
-const matcher = firewall.getMatcher();       // (ip) => boolean
-const allowMatcher = firewall.getAllowlistMatcher();
-
-await firewall.shutdown();
-```
-
-### Cloud WAF Providers
-
-**Cloudflare:**
-```bash
-SECURENOW_FIREWALL_CLOUD=cloudflare
-CLOUDFLARE_API_TOKEN=your-token
-CLOUDFLARE_ACCOUNT_ID=your-account-id
-```
-
-**AWS WAF:**
-```bash
-SECURENOW_FIREWALL_CLOUD=aws
-AWS_WAF_IP_SET_ID=your-ip-set-id
-# + standard AWS credentials (env, profile, or IAM role)
-```
-Requires peer dep: `npm install @aws-sdk/client-wafv2`
-
-**GCP Cloud Armor:**
-```bash
-SECURENOW_FIREWALL_CLOUD=gcp
-GCP_PROJECT_ID=your-project
-GCP_SECURITY_POLICY=your-policy-name
-```
-Requires peer dep: `npm install @google-cloud/compute`
-
-**Dry-run (log only, no actual WAF changes):**
-```bash
-SECURENOW_FIREWALL_CLOUD_DRY_RUN=1
-```
-
----
-
-## Logging
-
-Logging is enabled by default (`SECURENOW_LOGGING_ENABLED=1`). Logs are exported to your OTLP collector alongside traces.
-
-### Get a Logger
-
-```javascript
-const { getLogger } = require('securenow/tracing');
-
-const logger = getLogger('my-module', '1.0.0');
-if (logger) {
-  logger.emit({ body: 'User login succeeded', severityText: 'INFO', attributes: { userId: '123' } });
-}
-```
-
-**CLI equivalent** (for shell scripts, cron, CI):
-
-```bash
-securenow log send "User login succeeded" --level info --attrs userId=123
-securenow test-span "ci.smoke-test"          # emit a span without booting the SDK
-```
-
-### Console Instrumentation
-
-When tracing is active, `console.log/warn/error` are automatically patched to emit OTLP log records correlated with the active trace span. To access the original console:
-
-```javascript
-const { originalConsole, restoreConsole } = require('securenow/console-instrumentation');
-originalConsole.log('This bypasses OTLP');
-restoreConsole(); // undo the patch
-```
-
----
-
-## IP Resolution Utilities
-
-```javascript
-const { resolveClientIp, resolveSocketIp, isFromTrustedProxy } = require('securenow/resolve-ip');
-
-// From an HTTP request (respects X-Forwarded-For from trusted proxies)
-const clientIp = resolveClientIp(req);
-
-// Direct socket IP
-const socketIp = resolveSocketIp(req);
-
-// Check if request comes from a trusted proxy
-const trusted = isFromTrustedProxy(req);
-```
-
-### CIDR Matching
-
-```javascript
-const { createMatcher, ipToInt, parseCidr, matchesCidr } = require('securenow/cidr');
-
-const isBlocked = createMatcher(['10.0.0.0/8', '192.168.1.0/24']);
-isBlocked('10.0.0.5');   // true
-isBlocked('8.8.8.8');    // false
-```
-
-**CLI equivalent:**
-
-```bash
-securenow cidr match 10.0.0.5 10.0.0.0/8,192.168.1.0/24    # exit 0 = match, 2 = miss
-securenow cidr parse 10.0.0.0/8                             # network/broadcast/mask/size
-```
-
----
-
-## Sensitive Data Redaction
-
-Available from multiple entry points (`securenow/nextjs-middleware`, `securenow/nextjs-wrapper`, `securenow/nextjs-auto-capture`):
-
-```javascript
-const { redactSensitiveData, DEFAULT_SENSITIVE_FIELDS } = require('securenow/nextjs-middleware');
-
-const safe = redactSensitiveData({ username: 'alice', password: 's3cret', token: 'abc' });
-// { username: 'alice', password: '[REDACTED]', token: '[REDACTED]' }
-```
-
-**Auto-redacted fields:** `password`, `passwd`, `pwd`, `secret`, `token`, `api_key`, `apikey`, `access_token`, `auth`, `credentials`, `mysql_pwd`, `stripeToken`, `card`, `cardnumber`, `ccv`, `cvc`, `cvv`, `ssn`, `pin`.
-
-Add custom fields via `config.capture.sensitiveFields` in `.securenow/credentials.json`; `SECURENOW_SENSITIVE_FIELDS=field1,field2` is a legacy fallback for existing installs.
-
-**CLI equivalent** (for piping, scripts, debugging what a payload looks like post-redaction):
-
-```bash
-securenow redact '{"user":"alice","password":"s3cret"}'
-securenow redact @request.json --fields internal_id,sessionHash
-```
-
----
-
+  failMode: 'open',         // 'open' or 'closed'
+  statusCode: 403,
+  log: true,
+  tcp: false,
+  iptables: false,
+  cloud: null,              // 'cloudflare' | 'aws' | 'gcp'
+});
+
+const stats = firewall.getStats();
+const matcher = firewall.getMatcher();       // (ip) => boolean
+const allowMatcher = firewall.getAllowlistMatcher();
+
+await firewall.shutdown();
+```
+
+### Cloud WAF Providers
+
+**Cloudflare:**
+```json
+{
+  "config": {
+    "firewall": {
+      "cloud": "cloudflare",
+      "cloudflare": {
+        "apiToken": "your-token",
+        "accountId": "your-account-id"
+      }
+    }
+  }
+}
+```
+
+**AWS WAF:**
+```json
+{
+  "config": {
+    "firewall": {
+      "cloud": "aws",
+      "aws": {
+        "wafIpSetId": "your-ip-set-id",
+        "wafIpSetName": "your-ip-set-name",
+        "wafScope": "REGIONAL"
+      }
+    }
+  }
+}
+```
+AWS authentication should use the standard AWS credential chain outside the
+SecureNow SDK config.
+Requires peer dep: `npm install @aws-sdk/client-wafv2`
+
+**GCP Cloud Armor:**
+```json
+{
+  "config": {
+    "firewall": {
+      "cloud": "gcp",
+      "gcp": {
+        "projectId": "your-project",
+        "securityPolicy": "your-policy-name"
+      }
+    }
+  }
+}
+```
+Requires peer dep: `npm install @google-cloud/compute`
+
+**Dry-run (log only, no actual WAF changes):**
+```json
+{
+  "config": {
+    "firewall": {
+      "cloudDryRun": true
+    }
+  }
+}
+```
+
+---
+
+## Logging
+
+Logging is enabled by default (`config.logging.enabled: true`). Logs are exported to your OTLP collector alongside traces.
+
+### Get a Logger
+
+```javascript
+const { getLogger } = require('securenow/tracing');
+
+const logger = getLogger('my-module', '1.0.0');
+if (logger) {
+  logger.emit({ body: 'User login succeeded', severityText: 'INFO', attributes: { userId: '123' } });
+}
+```
+
+**CLI equivalent** (for shell scripts, cron, CI):
+
+```bash
+securenow log send "User login succeeded" --level info --attrs userId=123
+securenow test-span "ci.smoke-test"          # emit a span without booting the SDK
+```
+
+### Console Instrumentation
+
+When tracing is active, `console.log/warn/error` are automatically patched to emit OTLP log records correlated with the active trace span. To access the original console:
+
+```javascript
+const { originalConsole, restoreConsole } = require('securenow/console-instrumentation');
+originalConsole.log('This bypasses OTLP');
+restoreConsole(); // undo the patch
+```
+
+---
+
+## IP Resolution Utilities
+
+```javascript
+const { resolveClientIp, resolveSocketIp, isFromTrustedProxy } = require('securenow/resolve-ip');
+
+// From an HTTP request (respects X-Forwarded-For from trusted proxies)
+const clientIp = resolveClientIp(req);
+
+// Direct socket IP
+const socketIp = resolveSocketIp(req);
+
+// Check if request comes from a trusted proxy
+const trusted = isFromTrustedProxy(req);
+```
+
+### CIDR Matching
+
+```javascript
+const { createMatcher, ipToInt, parseCidr, matchesCidr } = require('securenow/cidr');
+
+const isBlocked = createMatcher(['10.0.0.0/8', '192.168.1.0/24']);
+isBlocked('10.0.0.5');   // true
+isBlocked('8.8.8.8');    // false
+```
+
+**CLI equivalent:**
+
+```bash
+securenow cidr match 10.0.0.5 10.0.0.0/8,192.168.1.0/24    # exit 0 = match, 2 = miss
+securenow cidr parse 10.0.0.0/8                             # network/broadcast/mask/size
+```
+
+---
+
+## Sensitive Data Redaction
+
+Available from multiple entry points (`securenow/nextjs-middleware`, `securenow/nextjs-wrapper`, `securenow/nextjs-auto-capture`):
+
+```javascript
+const { redactSensitiveData, DEFAULT_SENSITIVE_FIELDS } = require('securenow/nextjs-middleware');
+
+const safe = redactSensitiveData({ username: 'alice', password: 's3cret', token: 'abc' });
+// { username: 'alice', password: '[REDACTED]', token: '[REDACTED]' }
+```
+
+**Auto-redacted fields:** `password`, `passwd`, `pwd`, `secret`, `token`, `api_key`, `apikey`, `access_token`, `auth`, `credentials`, `mysql_pwd`, `stripeToken`, `card`, `cardnumber`, `ccv`, `cvc`, `cvv`, `ssn`, `pin`.
+
+Add custom fields via `config.capture.sensitiveFields` in `.securenow/credentials.json`.
+
+**CLI equivalent** (for piping, scripts, debugging what a payload looks like post-redaction):
+
+```bash
+securenow redact '{"user":"alice","password":"s3cret"}'
+securenow redact @request.json --fields internal_id,sessionHash
+```
+
+---
+
 ## Credentials Configuration
 
-Local development and production use `.securenow/credentials.json`. Every setting below lives under `app` or `config`; `npx securenow credentials runtime --env production` creates a tokenless production file with the same structure. Since v7.7.2, the SDK also accepts named runtime files such as `.securenow/credentials.production.json` when the canonical `credentials.json` file is absent. Filename lookup is deterministic and does not read environment variables. Environment variables are legacy fallbacks only.
-
-### App Identity
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `SECURENOW_APPID` | Legacy fallback for `app.key` / service name | from credentials file, then package name |
-| `SECURENOW_INSTANCE` | Legacy fallback for `app.instance` / OTLP collector base URL | from credentials file, then `https://freetrial.securenow.ai:4318` |
-
-### Service Naming
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `OTEL_SERVICE_NAME` | Legacy fallback for `app.name` | — |
-| `SECURENOW_NO_UUID` | `1` to use exact app ID without UUID suffix | `0` |
-| `SECURENOW_STRICT` | `1` to exit if APPID missing in PM2 cluster | `0` |
-
-### OTLP Connection
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | Legacy fallback for `config.otel.endpoint` | — |
-| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Legacy fallback for `config.otel.tracesEndpoint` | `{instance}/v1/traces` |
-| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Legacy fallback for `config.otel.logsEndpoint` | `{instance}/v1/logs` |
-| `OTEL_EXPORTER_OTLP_HEADERS` | Comma-separated `key=value` headers for OTLP requests | — |
-
-### Behavior
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `SECURENOW_LOGGING_ENABLED` | Enable OTLP log export | `1` |
-| `SECURENOW_CAPTURE_BODY` | Capture HTTP request bodies | `1` |
-| `SECURENOW_MAX_BODY_SIZE` | Max body size in bytes | `10240` |
-| `SECURENOW_CAPTURE_MULTIPART` | Capture multipart/form-data (streaming, metadata only) | `1` |
-| `SECURENOW_SENSITIVE_FIELDS` | Comma-separated extra fields to redact | — |
-| `SECURENOW_DISABLE_INSTRUMENTATIONS` | Comma-separated packages to skip (e.g. `fs,dns`) | — |
-| `SECURENOW_TEST_SPAN` | `1` to emit a test span on startup | `0` |
-| `SECURENOW_HIDE_BANNER` | `1` to suppress free-trial upgrade banner | `0` |
-| `OTEL_LOG_LEVEL` | SDK diagnostic override: `error`, `warn`, `info`, `debug`, or `none` | `error` |
-| `SECURENOW_ENVIRONMENT` / `SECURENOW_DEPLOYMENT_ENVIRONMENT` / `NODE_ENV` | Legacy fallback for `config.runtime.deploymentEnvironment` | `production` |
-
-### Firewall
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `SECURENOW_API_KEY` | Legacy env override for the `apiKey` field (`snk_live_...`). Since v7.5.1, login writes the scoped firewall key to `.securenow/credentials.json`. | - |
-| `SECURENOW_API_URL` | SecureNow API base URL | `https://api.securenow.ai` |
-| `SECURENOW_FIREWALL_VERSION_INTERVAL` | Seconds between lightweight ETag checks | `10` |
-| `SECURENOW_FIREWALL_SYNC_INTERVAL` | Safety-net full blocklist refresh interval in seconds | `3600` |
-| `SECURENOW_FIREWALL_FAIL_MODE` | `open` (allow all when unavailable) or `closed` | `open` |
-| `SECURENOW_FIREWALL_STATUS_CODE` | HTTP status for blocked requests | `403` |
-| `SECURENOW_FIREWALL_LOG` | Log blocked requests | `1` |
-| `SECURENOW_FIREWALL_TCP` | Enable Layer 2 TCP blocking | `0` |
-| `SECURENOW_FIREWALL_IPTABLES` | Enable Layer 3 iptables/nftables | `0` |
-| `SECURENOW_FIREWALL_CLOUD` | Cloud WAF: `cloudflare`, `aws`, or `gcp` | — |
-| `SECURENOW_FIREWALL_CLOUD_DRY_RUN` | `1` to log cloud pushes without applying | `0` |
-| `SECURENOW_TRUSTED_PROXIES` | Comma-separated trusted proxy IPs | — |
-
+Local development and production use `.securenow/credentials.json`. Every setting below lives under `app` or `config`; `npx securenow credentials runtime --env production` creates a tokenless production file with the same structure. Since v7.7.2, the SDK also accepts named runtime files such as `.securenow/credentials.production.json` when the canonical `credentials.json` file is absent. Filename lookup is deterministic and does not read environment variables. Legacy env fallback is disabled unless `SECURENOW_ENABLE_LEGACY_ENV=1` is explicitly set.
+
+| Credentials path | Purpose |
+|---|---|
+| `app.key` | App routing UUID. The SecureNow ingestion gateway routes telemetry by this key |
+| `app.name` | Human-readable app label |
+| `apiKey` | Scoped firewall key (`snk_live_...`) |
+| `config.otel.endpoint` | Optional OTLP base endpoint override |
+| `config.otel.tracesEndpoint` | Optional full traces endpoint |
+| `config.otel.logsEndpoint` | Optional full logs endpoint |
+| `config.otel.headers` | Extra OTLP headers as JSON object |
+| `config.otel.logLevel` | SDK diagnostics: `error`, `warn`, `info`, `debug`, or `none` |
+| `config.otel.disableInstrumentations` | OTel instrumentation package names to skip |
+| `config.logging.enabled` | Enable/disable OTLP log export |
+| `config.capture.body` | Capture HTTP request bodies |
+| `config.capture.maxBodySize` | Max body size in bytes |
+| `config.capture.multipart` | Capture multipart metadata, never file content |
+| `config.capture.sensitiveFields` | Extra redaction field fragments |
+| `config.runtime.deploymentEnvironment` | Sent as `deployment.environment` |
+| `config.runtime.noUuid` | Use exact app key as service name without UUID suffix |
+| `config.runtime.strict` | Exit clustered workers when no app identity resolves |
+| `config.runtime.testSpan` | Emit a startup test span |
+| `config.runtime.hideBanner` | Suppress the free-trial upgrade banner |
+| `config.firewall.*` | Local firewall behavior, API URL, intervals, cloud WAF, and trusted proxy settings |
+
 **Resilience:** The firewall SDK includes a circuit breaker (opens after 5 consecutive errors, 2-min cooldown), in-flight request guards (prevents overlapping requests), 429 Retry-After support, and exponential backoff on both lightweight ETag checks and initial sync retries.
-
-### Cloud WAF Provider Variables
-
-| Provider | Variables |
-|----------|-----------|
-| Cloudflare | `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` |
-| AWS WAF | `AWS_WAF_IP_SET_ID`, `AWS_WAF_IP_SET_NAME`, `AWS_WAF_SCOPE` |
-| GCP | `GCP_PROJECT_ID`, `GCP_SECURITY_POLICY` |
-
-### Priority Order
-
-**Service name:** credentials `app.key` > credentials `app.name` > legacy env fallback > package name
-
-**Endpoint:** credentials `config.otel.tracesEndpoint` / `config.otel.endpoint` / `app.instance` > legacy env fallback > `https://freetrial.securenow.ai:4318`
-
----
-
-## Recipes for Agentic AI
-
-### Add Observability to an Existing Express App
-
-```bash
+
+### Cloud WAF Provider Variables
+
+| Provider | Variables |
+|----------|-----------|
+| Cloudflare | `config.firewall.cloudflare.apiToken`, `config.firewall.cloudflare.accountId` |
+| AWS WAF | `config.firewall.aws.wafIpSetId`, `config.firewall.aws.wafIpSetName`, `config.firewall.aws.wafScope` |
+| GCP | `config.firewall.gcp.projectId`, `config.firewall.gcp.securityPolicy` |
+
+### Priority Order
+
+**Service name:** credentials `app.key` > credentials `app.name` > package name
+
+**Endpoint:** credentials `config.otel.tracesEndpoint` / `config.otel.endpoint` > default SecureNow ingestion gateway `https://ingest.securenow.ai`
+
+---
+
+## Recipes for Agentic AI
+
+### Add Observability to an Existing Express App
+
+```bash
 npm install securenow@latest
 npx securenow login
-```
-
-No `.env` is needed. `npx securenow login` writes app identity, collector URL, firewall key, and secure defaults to `.securenow/credentials.json`; `npx securenow init` makes sure the file has explanations and is gitignored.
-
-Update `package.json`:
-```json
-{ "scripts": { "start": "node -r securenow/register src/index.js" } }
-```
-
-No code changes to the application needed.
-
-### Add Observability + Firewall to a Next.js App
-
-```bash
+```
+
+No `.env` is needed. `npx securenow login` writes app identity, firewall key, and secure defaults to `.securenow/credentials.json`; the SDK uses the default SecureNow ingestion gateway and the gateway routes by `app.key`. `npx securenow init` makes sure the file has explanations and is gitignored without ignoring the whole `.securenow/` directory.
+
+Update `package.json`:
+```json
+{ "scripts": { "start": "node -r securenow/register src/index.js" } }
+```
+
+No code changes to the application needed.
+
+### Add Observability + Firewall to a Next.js App
+
+```bash
 npm install securenow@latest
 npx securenow login              # pick/create app; firewall key is minted automatically
-```
-
-`securenow login` enables the selected app's firewall toggle and writes session, app, and firewall key to `.securenow/credentials.json` (auto-gitignored). Traces, logs, request body capture, multipart metadata capture, and firewall enforcement are enabled by default. Then run `npx securenow init`; it creates `instrumentation.ts`, patches `next.config.*` when safe, or prints exact Codex/Claude merge instructions for existing files.
-
-### Enable Firewall With Zero Tracing Overhead
-
-For apps that only need IP blocking:
-
-```bash
-node -r securenow/firewall-only app.js
-```
-
+```
+
+`securenow login` enables the selected app's firewall toggle and writes session, app, and firewall key to `.securenow/credentials.json` (gitignored via credential-file patterns, not a whole-directory `.securenow/` ignore). Traces, logs, request body capture, multipart metadata capture, and firewall enforcement are enabled by default. Then run `npx securenow init`; it creates `instrumentation.ts`, patches `next.config.*` when safe, or prints exact Codex/Claude merge instructions for existing files.
+
+### Enable Firewall With Zero Tracing Overhead
+
+For apps that only need IP blocking:
+
+```bash
+node -r securenow/firewall-only app.js
+```
+
 Make sure an API key is resolvable by running `npx securenow login` first. If you already have a key, `securenow api-key set snk_live_...` writes the creds file. For production, run `npx securenow credentials runtime --env production` and mount/copy it as `.securenow/credentials.json`.
-
+
 ### Production Hardened Configuration
 
 ```json
@@ -611,22 +612,22 @@ Make sure an API key is resolvable by running `npx securenow login` first. If yo
   }
 }
 ```
-
-### Instrument a Docker Container
-
-```dockerfile
-FROM node:20-slim
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --omit=dev
+
+### Instrument a Docker Container
+
+```dockerfile
+FROM node:20-slim
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
 COPY . .
 # Mount/copy secret file at runtime as /app/.securenow/credentials.json.
 
 CMD ["node", "-r", "securenow/register", "src/index.js"]
 ```
-
-### Kubernetes with Separate Trace/Log Collectors
-
+
+### Kubernetes with Separate Trace/Log Collectors
+
 ```json
 {
   "app": { "key": "k8s-service", "name": "k8s-service" },
@@ -640,26 +641,26 @@ CMD ["node", "-r", "securenow/register", "src/index.js"]
   }
 }
 ```
-
----
-
-## Verification
-
-On startup, securenow logs its configuration:
-
-```
-[securenow] app.key="my-app" → service.name=my-app
-[securenow] OTel SDK started → https://collector:4318/v1/traces
-[securenow] Logging: ENABLED → https://collector:4318/v1/logs
+
+---
+
+## Verification
+
+On startup, securenow logs its configuration:
+
+```
+[securenow] app.key="my-app" → service.name=my-app
+[securenow] OTel SDK started → https://collector:4318/v1/traces
+[securenow] Logging: ENABLED → https://collector:4318/v1/logs
 [securenow] Request body capture: ENABLED (max: 10240 bytes)
 [securenow] Firewall: ENABLED
 [securenow] Firewall: synced 142 blocked IPs
 ```
 
 Set `config.otel.logLevel` to `debug`, or temporarily run with `OTEL_LOG_LEVEL=debug`, and run `securenow doctor --json` to troubleshoot connectivity, duplicate OpenTelemetry API packages, and provider registration issues.
-
-**CLI equivalent** (works without booting the SDK — useful when the app won't start):
-
+
+**CLI equivalent** (works without booting the SDK — useful when the app won't start):
+
 ```bash
 securenow env                     # show resolved app key, endpoints, and credentials fields
 securenow doctor                  # probe OTLP + API endpoints, exits 1 on failure