securenow 7.5.1 → 7.6.0

package/docs/ENVIRONMENT-VARIABLES.md

@@ -1,892 +1,166 @@
-# SecureNow Environment Variables Reference
+# SecureNow Credentials Reference
 
-Complete reference for all environment variables supported by SecureNow.
+SecureNow uses `.securenow/credentials.json` in local development and production. No `.env` file is required.
 
-> **v7+: env vars are all optional.** For local dev, `npx securenow login` writes `.securenow/credentials.json` and the SDK reads it at boot — no env vars needed. Env vars are still supported (and always take precedence) for CI / Docker / production.
-
-> **Resolution order** (first non-empty wins): env var → `./.securenow/credentials.json` → `~/.securenow/credentials.json` → `package.json#name` (label only) → default.
-
----
-
-## Quick Reference Table
-
-| Variable | Type | Default | Description |
-|----------|------|---------|-------------|
-| **SECURENOW_APPID** | Optional | from credentials file | App routing key (UUID). Sent as OTel `service.name`. |
-| **SECURENOW_INSTANCE** | Optional | `https://freetrial.securenow.ai:4318` | OTLP collector base URL |
-| **SECURENOW_API_KEY** | Optional | from credentials file | API key (same UUID as APPID). Enables firewall. |
-| **SECURENOW_LOGGING_ENABLED** | Optional | `1` (on) | Forward `console.*` as OTLP logs. Set to `0` to disable. |
-| **SECURENOW_CAPTURE_BODY** | Optional | `1` (on) | Capture request body. Set to `0` only for a local stream conflict. |
-| **SECURENOW_CAPTURE_MULTIPART** | Optional | `1` (on) | Capture multipart field/file metadata. |
-| **SECURENOW_MAX_BODY_SIZE** | Optional | `10240` | Max body size in bytes |
-| **SECURENOW_SENSITIVE_FIELDS** | Optional | - | Comma-separated extra fields to redact |
-| **SECURENOW_NO_UUID** | Optional | `0` | Disable UUID suffix on `service.instance.id` |
-| **SECURENOW_STRICT** | Optional | `0` | Exit if APPID missing in PM2 cluster mode |
-| **SECURENOW_DISABLE_INSTRUMENTATIONS** | Optional | - | Comma-separated list of OTel instrumentations to disable |
-| **SECURENOW_TEST_SPAN** | Optional | `0` | Emit a single test span on startup (prefer `npx securenow test-span`) |
-| **SECURENOW_HIDE_BANNER** | Optional | `0` | Hide the free-trial banner |
-| **SECURENOW_FIREWALL_ENABLED** | Optional | (dashboard toggle) | Local override only — set to `0` to force-off regardless of dashboard. Primary control is the per-app toggle at `/dashboard/firewall` (≥ 7.3.0). |
-| **SECURENOW_ENABLE_MONGODB_INSTRUMENTATION** | Optional | `0` | Opt in to MongoDB instrumentation (off by default since a cursor bug on mongodb@6.6+; safe since SDK v6.0.2) |
-| **OTEL_SERVICE_NAME** | Optional | - | Alternative to SECURENOW_APPID (label only, no routing) |
-| **OTEL_EXPORTER_OTLP_ENDPOINT** | Optional | - | Alternative to SECURENOW_INSTANCE |
-| **OTEL_EXPORTER_OTLP_HEADERS** | Optional | auto (`x-api-key` injected) | Additional OTLP headers |
-| **OTEL_EXPORTER_OTLP_TRACES_ENDPOINT** | Optional | - | Override traces endpoint |
-| **OTEL_EXPORTER_OTLP_LOGS_ENDPOINT** | Optional | - | Override logs endpoint |
-| **OTEL_LOG_LEVEL** | Optional | `none` | SDK log verbosity (`debug`/`info`/`warn`/`error`) |
-| **NODE_ENV** | Optional | `production` | Environment name |
-| **SECURENOW_API_URL** | Optional | `https://api.securenow.ai` | Dashboard API base URL |
-| **SECURENOW_APP_URL** | Optional | `https://app.securenow.ai` | Dashboard web base URL |
-| **SECURENOW_TOKEN** | Optional | from credentials file | Auth token (overrides credentials file for CI) |
-| **SECURENOW_FIREWALL_ENABLED** | Optional | `1` | Firewall master kill-switch |
-| **SECURENOW_FIREWALL_SYNC_INTERVAL** | Optional | `60` | Blocklist refresh interval (seconds) |
-| **SECURENOW_FIREWALL_FAIL_MODE** | Optional | `open` | Behavior when API unreachable: open/closed |
-| **SECURENOW_FIREWALL_STATUS_CODE** | Optional | `403` | HTTP status for blocked requests |
-| **SECURENOW_FIREWALL_LOG** | Optional | `1` | Log blocked requests |
-| **SECURENOW_FIREWALL_TCP** | Optional | `0` | Enable Layer 2 TCP blocking |
-| **SECURENOW_FIREWALL_IPTABLES** | Optional | `0` | Enable Layer 3 iptables blocking |
-| **SECURENOW_FIREWALL_CLOUD** | Optional | - | Cloud WAF provider (cloudflare/aws/gcp) |
-| **SECURENOW_TRUSTED_PROXIES** | Optional | - | Trusted proxy IPs for X-Forwarded-For |
-
----
-
-## Required Variables
-
-### SECURENOW_APPID
-
-**Description:** Your application identifier. Used as the service name in traces and logs.
-
-**Format:** String (alphanumeric, hyphens, underscores)
-
-**Examples:**
 ```bash
-export SECURENOW_APPID=my-express-app
-export SECURENOW_APPID=api-gateway
-export SECURENOW_APPID=user-service
+npx securenow login
+npx securenow init
 ```
 
-**Notes:**
-- If not set, SecureNow will use a fallback name with UUID
-- In cluster mode with `SECURENOW_STRICT=1`, missing APPID will cause process exit
-- Alternative: Use `OTEL_SERVICE_NAME` (OpenTelemetry standard)
-
-**Behavior:**
-- Without `SECURENOW_NO_UUID=1`: Service name becomes `{APPID}-{UUID}`
-- With `SECURENOW_NO_UUID=1`: Service name is exactly `{APPID}`
+`login` writes the selected app, collector instance, CLI token, and firewall key to `./.securenow/credentials.json`. `init` ensures that file also contains secure defaults and an `_securenow.explanations` block for end users. Keep `.securenow/` in `.gitignore`.
 
----
+## Production Runtime File
 
-### SECURENOW_INSTANCE
+Production should use the same file structure, but without the CLI OAuth fields. From a logged-in project:
 
-**Description:** Base URL of your OTLP collector endpoint.
-
-**Format:** URL (http/https)
-
-**Examples:**
 ```bash
-# Local collector
-export SECURENOW_INSTANCE=http://localhost:4318
-
-# Remote collector
-export SECURENOW_INSTANCE=http://collector.example.com:4318
-
-# HTTPS
-export SECURENOW_INSTANCE=https://collector.example.com:4318
+npx securenow credentials runtime --env production
 ```
 
-**Default:** `https://freetrial.securenow.ai:4318` (if not set)
-
-**Notes:**
-- Used to construct traces and logs endpoints
-- Traces sent to: `{SECURENOW_INSTANCE}/v1/traces`
-- Logs sent to: `{SECURENOW_INSTANCE}/v1/logs`
-- Alternative: Use `OTEL_EXPORTER_OTLP_ENDPOINT`
-
----
+This writes:
 
-## Service Naming
-
-### OTEL_SERVICE_NAME
-
-**Description:** Standard OpenTelemetry variable for service name. Alternative to `SECURENOW_APPID`.
-
-**Format:** String
-
-**Example:**
-```bash
-export OTEL_SERVICE_NAME=my-app
+```text
+.securenow/credentials.production.json
 ```
 
-**Priority:** If both are set, `OTEL_SERVICE_NAME` takes precedence.
+Deploy that JSON as a secret file and mount or copy it to:
 
----
-
-### SECURENOW_NO_UUID
-
-**Description:** Disable automatic UUID suffix on service name.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `0`
-
-**Example:**
-```bash
-export SECURENOW_NO_UUID=1
+```text
+<app-root>/.securenow/credentials.json
 ```
 
-**Use case:**
-- PM2 cluster mode - use same service name for all workers
-- Docker containers with replica sets
-- Kubernetes pods in a deployment
-
-**Behavior:**
-- `0`: Service name = `my-app-a1b2c3d4`
-- `1`: Service name = `my-app`
-
----
-
-### SECURENOW_STRICT
-
-**Description:** Exit process if `SECURENOW_APPID` is not set in cluster mode.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `0`
-
-**Example:**
-```bash
-export SECURENOW_STRICT=1
-```
-
-**Use case:**
-- Production environments where service name must be explicit
-- Prevent "free" or auto-generated service names
-- Ensure proper configuration before starting
-
-**Detection:**
-Cluster mode is detected when any of these exist:
-- `NODE_APP_INSTANCE` (PM2)
-- `pm_id` (PM2)
-
----
-
-## Connection Settings
-
-### OTEL_EXPORTER_OTLP_ENDPOINT
-
-**Description:** Standard OpenTelemetry variable for OTLP endpoint. Alternative to `SECURENOW_INSTANCE`.
-
-**Format:** URL
-
-**Example:**
-```bash
-export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
-```
-
-**Priority:** If both are set, `OTEL_EXPORTER_OTLP_ENDPOINT` takes precedence.
-
----
-
-### OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
-
-**Description:** Override the traces endpoint specifically.
-
-**Format:** Full URL including `/v1/traces`
-
-**Example:**
-```bash
-export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://traces-collector:4318/v1/traces
-```
-
-**Use case:**
-- Separate collectors for traces and logs
-- Different routing for traces
-
----
-
-### OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
-
-**Description:** Override the logs endpoint specifically.
-
-**Format:** Full URL including `/v1/logs`
-
-**Example:**
-```bash
-export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs-collector:4318/v1/logs
-```
-
-**Use case:**
-- Separate collectors for traces and logs
-- Different routing for logs
-
----
-
-### OTEL_EXPORTER_OTLP_HEADERS
-
-**Description:** Headers to include in OTLP export requests.
-
-**Format:** Comma-separated `key=value` pairs
-
-**Examples:**
-```bash
-# Single header
-export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key"
-
-# Multiple headers
-export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=key123,x-tenant-id=tenant456"
-
-# Authentication
-export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer token123"
-```
-
-**Use case:**
-- API authentication
-- Multi-tenancy headers
-- Custom routing headers
-
-**Notes:**
-- Header names are case-insensitive
-- Trailing/leading spaces are trimmed
-
----
-
-## Logging
-
-### SECURENOW_LOGGING_ENABLED
-
-**Description:** Enable or disable automatic logging to OTLP backend.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `1` (enabled by default)
-
-**Examples:**
-```bash
-# Enable logging
-export SECURENOW_LOGGING_ENABLED=1
-
-# Disable logging
-export SECURENOW_LOGGING_ENABLED=0
-```
+The runtime file contains `apiKey`, `app`, `config`, and `_securenow.explanations`; it intentionally omits `token`, `email`, and `expiresAt`.
 
-**When enabled:**
-- Logs are sent to `{SECURENOW_INSTANCE}/v1/logs`
-- Console instrumentation can capture logs
-- Direct logger API is available
+## Resolution Order
 
-**When disabled:**
-- No logs sent to backend
-- `getLogger()` returns `null`
-- Console instrumentation shows warning
+1. Project `./.securenow/credentials.json`
+2. Global `~/.securenow/credentials.json`
+3. `package.json#name` where a human-readable fallback label is useful
+4. Built-in secure default
 
----
+Legacy environment variables are fallback-only for existing deployments. New local, CI, Docker, and production setups should use the credentials file.
 
-## Request Body Capture
+## Credentials File Shape
 
-### SECURENOW_CAPTURE_BODY
-
-**Description:** Enable capture of HTTP request bodies in traces.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `1` (enabled)
-
-**Example:**
-```bash
-# Default is enabled. Use this only to opt out:
-export SECURENOW_CAPTURE_BODY=0
-```
-
-**Supported content types:**
-- `application/json`
-- `application/x-www-form-urlencoded`
-- `application/graphql`
-
-**Not captured:**
-- Bodies larger than `SECURENOW_MAX_BODY_SIZE`
-
-**Security:**
-All captured bodies are automatically scanned for sensitive fields and redacted.
-
----
-
-### SECURENOW_MAX_BODY_SIZE
-
-**Description:** Maximum request body size to capture (in bytes).
-
-**Format:** Number (bytes)
-
-**Default:** `10240` (10 KB)
-
-**Examples:**
-```bash
-# 10 KB (default)
-export SECURENOW_MAX_BODY_SIZE=10240
-
-# 20 KB
-export SECURENOW_MAX_BODY_SIZE=20480
-
-# 5 KB
-export SECURENOW_MAX_BODY_SIZE=5120
-```
-
-**Behavior:**
-- Bodies larger than this are not captured
-- Span attribute shows: `[TOO LARGE: {size} bytes]`
-
----
-
-### SECURENOW_SENSITIVE_FIELDS
-
-**Description:** Additional field names to redact from request bodies (comma-separated).
-
-**Format:** Comma-separated list of field names
-
-**Default:** (see below for auto-redacted fields)
-
-**Examples:**
-```bash
-# Additional custom fields
-export SECURENOW_SENSITIVE_FIELDS="internal_token,session_key"
-
-# Multiple fields
-export SECURENOW_SENSITIVE_FIELDS="custom_secret,private_data,internal_id"
-```
-
-**Auto-redacted fields (built-in):**
-- `password`, `passwd`, `pwd`
-- `secret`, `token`, `api_key`, `apikey`, `access_token`
-- `auth`, `credentials`, `mysql_pwd`
-- `stripeToken`, `card`, `cardnumber`
-- `ccv`, `cvc`, `cvv`
-- `ssn`, `pin`
-
-**Matching:**
-- Case-insensitive
-- Substring match (e.g., `password` matches `user_password`, `PASSWORD`, `passwordField`)
-- Works recursively in nested objects
-
----
-
-### SECURENOW_CAPTURE_MULTIPART
-
-**Description:** Enable capture of `multipart/form-data` request bodies (file upload metadata and text fields). Uses a streaming parser that processes boundary markers on the fly — file binary content is never buffered or stored.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `1` (enabled)
-
-**Example:**
-```bash
-# Default is enabled. Use this only to opt out:
-export SECURENOW_CAPTURE_MULTIPART=0
-```
-
-**What gets captured:**
-- **Text fields** — field name and value (up to 1000 characters), with sensitive fields auto-redacted
-- **File fields** — metadata only: field name, filename, content-type, and size in bytes (no binary content)
-
-**Example span attribute (`http.request.body`):**
 ```json
 {
-  "fields": { "description": "My upload", "token": "[REDACTED]" },
-  "files": [
-    { "field": "avatar", "filename": "photo.jpg", "contentType": "image/jpeg", "size": 524288 },
-    { "field": "document", "filename": "report.pdf", "contentType": "application/pdf", "size": 1048576 }
-  ]
+  "apiKey": "snk_live_...",
+  "app": {
+    "key": "<secure-now-app-uuid>",
+    "name": "my-app",
+    "instance": "https://freetrial.securenow.ai:4318"
+  },
+  "config": {
+    "logging": { "enabled": true },
+    "capture": {
+      "body": true,
+      "multipart": true,
+      "maxBodySize": 10240,
+      "sensitiveFields": []
+    },
+    "otel": {
+      "endpoint": null,
+      "tracesEndpoint": null,
+      "logsEndpoint": null,
+      "headers": {},
+      "logLevel": "none",
+      "disableInstrumentations": []
+    },
+    "runtime": {
+      "deploymentEnvironment": "production",
+      "noUuid": null,
+      "strict": false,
+      "testSpan": false,
+      "hideBanner": false
+    },
+    "firewall": {
+      "enabled": true,
+      "apiUrl": "https://api.securenow.ai",
+      "versionCheckInterval": 10,
+      "syncInterval": 300,
+      "failMode": "open",
+      "statusCode": 403,
+      "log": true,
+      "tcp": false,
+      "iptables": false,
+      "cloud": null,
+      "cloudDryRun": false,
+      "cloudflare": {
+        "apiToken": null,
+        "accountId": null
+      },
+      "aws": {
+        "wafIpSetId": null,
+        "wafIpSetName": "securenow-blocklist",
+        "wafScope": "REGIONAL"
+      },
+      "gcp": {
+        "projectId": null,
+        "securityPolicy": null
+      }
+    },
+    "networking": {
+      "trustedProxies": []
+    }
+  }
 }
 ```
 
-**Additional span attributes set:**
-- `http.request.body.type` = `"multipart"`
-- `http.request.body.size` — total raw request body size in bytes
-- `http.request.body.fields_count` — number of text fields
-- `http.request.body.files_count` — number of file fields
-
-**Memory:** Bounded at ~few KB regardless of upload size (streaming parser discards file content as it passes through).
-
-**Parts limit:** 100 parts maximum per request (safety guard).
-
-**Relationship to body capture:** multipart metadata capture has its own opt-out flag. Leave `SECURENOW_CAPTURE_MULTIPART` unset, `1`, or `true` to keep it enabled.
-
-**Since:** v5.8.0
-
----
-
-## Instrumentation Control
-
-### SECURENOW_DISABLE_INSTRUMENTATIONS
-
-**Description:** Disable specific OpenTelemetry instrumentations.
-
-**Format:** Comma-separated list of package names
-
-**Example:**
-```bash
-# Disable file system and DNS instrumentations
-export SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns
-
-# Disable multiple
-export SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns,net,http2
-```
-
-**Common packages you might disable:**
-- `fs` - File system operations
-- `dns` - DNS lookups
-- `net` - Network operations
-- `http2` - HTTP/2 client/server
-- `grpc` - gRPC client/server
-
-**Use case:**
-- Reduce overhead by disabling unused instrumentations
-- Avoid noisy traces from certain operations
-- Debug issues with specific instrumentations
-
----
-
-## Debugging
-
-### OTEL_LOG_LEVEL
-
-**Description:** OpenTelemetry SDK internal log level.
-
-**Format:** `none`, `error`, `warn`, `info`, `debug`
-
-**Default:** `none`
-
-**Examples:**
-```bash
-# See all debug information
-export OTEL_LOG_LEVEL=debug
-
-# Only errors
-export OTEL_LOG_LEVEL=error
-
-# No SDK logs
-export OTEL_LOG_LEVEL=none
-```
-
-**Use case:**
-- Troubleshooting setup issues
-- Understanding trace/log export behavior
-- Debugging connection problems
-
-**Output:**
-- Goes to console (stderr)
-- Prefixed with `[securenow]`
-
----
-
-### SECURENOW_TEST_SPAN
-
-**Description:** Emit a test span on startup to verify tracing is working.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `0`
-
-**Example:**
-```bash
-export SECURENOW_TEST_SPAN=1
-```
-
-**Behavior:**
-- Creates a span named `securenow.startup.smoke`
-- Span is immediately ended
-- Useful for testing collector connectivity
-
----
-
-## Environment
-
-### NODE_ENV
-
-**Description:** Standard Node.js environment variable. Sent as `deployment.environment` attribute.
-
-**Format:** String (typically: `development`, `production`, `test`, `staging`)
-
-**Default:** `production`
+## Credentials Keys
+
+| Credentials path | Default | Notes |
+|---|---|---|
+| `app.key` | package name fallback | SecureNow app routing UUID / OTel service name. |
+| `app.name` | package name fallback | Human-readable app name. |
+| `app.instance` | `https://freetrial.securenow.ai:4318` | OTLP base endpoint. |
+| `apiKey` | `null` | `snk_live_...` firewall sync key. |
+| `config.otel.endpoint` | app instance | Optional OTLP base endpoint override. |
+| `config.otel.tracesEndpoint` | `{instance}/v1/traces` | Full traces endpoint. |
+| `config.otel.logsEndpoint` | `{instance}/v1/logs` | Full logs endpoint. |
+| `config.otel.headers` | auto `x-api-key=<app.key>` | Extra OTLP headers as an object. |
+| `config.otel.logLevel` | `none` | `none`, `error`, `warn`, `info`, or `debug`. |
+| `config.otel.disableInstrumentations` | `[]` | OTel instrumentation package names to skip. |
+| `config.logging.enabled` | `true` | Console log forwarding. |
+| `config.capture.body` | `true` | JSON, GraphQL, and form body capture. |
+| `config.capture.multipart` | `true` | Multipart text fields and file metadata; never file content. |
+| `config.capture.maxBodySize` | `10240` | Bytes captured per request body. |
+| `config.capture.sensitiveFields` | `[]` | Extra redaction field fragments. |
+| `config.runtime.deploymentEnvironment` | `production` | Sent as `deployment.environment`. |
+| `config.runtime.noUuid` | auto | Auto is true when an app key is present. |
+| `config.runtime.strict` | `false` | Exit clustered workers when no app identity resolves. |
+| `config.runtime.testSpan` | `false` | Prefer `npx securenow test-span` for manual checks. |
+| `config.runtime.hideBanner` | `false` | Hide free-trial response banner. |
+| `config.firewall.enabled` | `true` | Local kill-switch; dashboard app toggle also applies. |
+| `config.firewall.apiUrl` | `https://api.securenow.ai` | SecureNow API base URL. |
+| `config.firewall.versionCheckInterval` | `10` | Seconds between lightweight version checks. |
+| `config.firewall.syncInterval` | `300` | Seconds between full blocklist syncs. |
+| `config.firewall.failMode` | `open` | `open` or `closed`. |
+| `config.firewall.statusCode` | `403` | HTTP status for blocked requests. |
+| `config.firewall.log` | `true` | Log firewall decisions locally. |
+| `config.firewall.tcp` | `false` | Opt-in Layer 2 TCP drop. |
+| `config.firewall.iptables` | `false` | Opt-in Linux iptables/nftables drop. |
+| `config.firewall.cloud` | `null` | `cloudflare`, `aws`, or `gcp`. |
+| `config.firewall.cloudDryRun` | `false` | Preview cloud WAF pushes. |
+| `config.firewall.cloudflare.apiToken` | `null` | Cloudflare Layer 4 WAF credential. |
+| `config.firewall.cloudflare.accountId` | `null` | Cloudflare account id. |
+| `config.firewall.aws.wafIpSetId` | `null` | AWS WAF IP set id. |
+| `config.firewall.aws.wafIpSetName` | `securenow-blocklist` | AWS WAF IP set name. |
+| `config.firewall.aws.wafScope` | `REGIONAL` | AWS WAF scope. |
+| `config.firewall.gcp.projectId` | `null` | GCP project id. |
+| `config.firewall.gcp.securityPolicy` | `null` | GCP Cloud Armor policy. |
+| `config.networking.trustedProxies` | `[]` | Additional proxy IPs trusted for `X-Forwarded-For`. |
+
+## Common Edits
 
-**Examples:**
-```bash
-export NODE_ENV=development
-export NODE_ENV=production
-export NODE_ENV=staging
-export NODE_ENV=test
-```
-
-**Use case:**
-- Filter traces/logs by environment
-- Different configurations per environment
-- Standard Node.js convention
-
----
-
-## Firewall (IP Blocking)
-
-### SECURENOW_API_KEY
-
-**Description:** API key for the SecureNow firewall. When set, the firewall auto-activates and syncs your blocklist. Must have the `firewall:read` scope.
-
-**Format:** String (`snk_live_` prefix + 64 hex characters)
-
-**Example:**
-```bash
-export SECURENOW_API_KEY=snk_live_a1b2c3d4e5f6...
-```
-
-**v7.4.0+:** the firewall also reads this key from `.securenow/credentials.json` (written by `securenow login`, which enables the selected app firewall by default, or by `securenow api-key set`). The env var only wins if it starts with `snk_live_` — otherwise the credentials file is used, so you can rely on the file for local dev without unsetting any stray env var. Setting an app UUID here (the old pre-7.1 habit) is ignored for firewall auth and would produce silent 401s; always use a `snk_live_...` key.
-
----
-
-### SECURENOW_API_URL
-
-**Description:** Base URL for the SecureNow API.
-
-**Format:** URL
-
-**Default:** `https://api.securenow.ai`
-
-**Example:**
-```bash
-export SECURENOW_API_URL=https://api.securenow.ai
-```
-
----
-
-### SECURENOW_FIREWALL_ENABLED
-
-**Description:** Master kill-switch for the firewall. Set to `0` to disable even when `SECURENOW_API_KEY` is set.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `1`
-
----
-
-### SECURENOW_FIREWALL_SYNC_INTERVAL
-
-**Description:** How often (in seconds) to refresh the blocklist from the API.
-
-**Format:** Number (seconds)
-
-**Default:** `60`
-
-**Example:**
-```bash
-export SECURENOW_FIREWALL_SYNC_INTERVAL=30
-```
-
----
-
-### SECURENOW_FIREWALL_FAIL_MODE
-
-**Description:** Behavior when the blocklist cannot be fetched from the API.
-
-**Format:** `open` or `closed`
-
-**Default:** `open`
-
-- `open` — Allow all traffic when list is unavailable (recommended for most apps)
-- `closed` — Block all traffic when list is unavailable (high-security environments)
-
----
-
-### SECURENOW_FIREWALL_STATUS_CODE
-
-**Description:** HTTP status code returned to blocked requests (Layer 1 only).
-
-**Format:** Number
-
-**Default:** `403`
-
-**Example:**
-```bash
-export SECURENOW_FIREWALL_STATUS_CODE=429
-```
-
----
-
-### SECURENOW_FIREWALL_LOG
-
-**Description:** Log blocked requests to the console.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `1`
-
----
-
-### SECURENOW_FIREWALL_TCP
-
-**Description:** Enable Layer 2 TCP-level blocking. Destroys sockets from blocked IPs before HTTP parsing starts.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `0`
-
-**Notes:**
-- Only sees direct connection IP (no proxy headers)
-- Connections from trusted proxies are passed to Layer 1
-- Most effective for direct-to-server deployments
-
----
-
-### SECURENOW_FIREWALL_IPTABLES
-
-**Description:** Enable Layer 3 OS firewall blocking via iptables/nftables. Kernel-level DROP — packets never reach Node.js.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `0`
-
-**Notes:**
-- Linux only (skips gracefully on macOS/Windows)
-- Requires root or CAP_NET_ADMIN
-- Auto-detects nftables vs iptables
-- Dedicated chain: `SECURENOW_BLOCK`
-
----
-
-### SECURENOW_FIREWALL_CLOUD
-
-**Description:** Enable Layer 4 cloud/edge WAF blocking. Pushes the blocklist to your cloud provider's WAF.
-
-**Format:** `cloudflare`, `aws`, or `gcp`
-
-**Default:** *(none — disabled)*
-
-**Provider-specific variables:**
-
-| Provider | Required Variables |
-|----------|-------------------|
-| `cloudflare` | `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` |
-| `aws` | `AWS_WAF_IP_SET_ID`, standard AWS credentials |
-| `gcp` | `GCP_PROJECT_ID`, `GCP_SECURITY_POLICY` |
-
----
-
-### SECURENOW_FIREWALL_CLOUD_DRY_RUN
-
-**Description:** Log cloud WAF pushes without actually applying them. Useful for testing.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `0`
-
----
-
-### SECURENOW_TRUSTED_PROXIES
-
-**Description:** Comma-separated list of additional trusted proxy IPs. The firewall only reads `X-Forwarded-For` from trusted proxies. Private/loopback IPs are always trusted.
-
-**Format:** Comma-separated IPs
-
-**Example:**
-```bash
-export SECURENOW_TRUSTED_PROXIES=34.120.0.1,34.120.0.2
-```
-
----
-
-## Configuration Examples
-
-### Development Environment
-
-```bash
-# .env.development
-SECURENOW_APPID=my-app-dev
-SECURENOW_INSTANCE=http://localhost:4318
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_CAPTURE_BODY=1
-SECURENOW_MAX_BODY_SIZE=20480
-OTEL_LOG_LEVEL=debug
-SECURENOW_TEST_SPAN=1
-NODE_ENV=development
-```
-
-### Production Environment
-
-```bash
-# .env.production
-SECURENOW_APPID=my-app-prod
-SECURENOW_INSTANCE=https://collector.prod.example.com:4318
-OTEL_EXPORTER_OTLP_HEADERS=x-api-key=prod-key-12345
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_CAPTURE_BODY=0
-SECURENOW_NO_UUID=1
-SECURENOW_STRICT=1
-SECURENOW_SENSITIVE_FIELDS=internal_id,session_token
-OTEL_LOG_LEVEL=error
-NODE_ENV=production
-
-# Firewall (optional — auto-activates when API key is set)
-SECURENOW_API_KEY=snk_live_abc123...
-SECURENOW_FIREWALL_TCP=1
-SECURENOW_FIREWALL_SYNC_INTERVAL=30
-```
-
-### PM2 Cluster
-
-```bash
-# ecosystem.config.js environment
-SECURENOW_APPID=my-app
-SECURENOW_INSTANCE=http://localhost:4318
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_NO_UUID=1
-SECURENOW_STRICT=1
-SECURENOW_CAPTURE_BODY=1
-NODE_ENV=production
-```
-
-### Docker / Kubernetes
-
-```bash
-# Docker environment or K8s ConfigMap
-SECURENOW_APPID=my-service
-SECURENOW_INSTANCE=http://otel-collector:4318
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_NO_UUID=1
-SECURENOW_CAPTURE_BODY=0
-NODE_ENV=production
-```
-
-### Separate Collectors for Traces and Logs
-
-```bash
-# Different backends for traces and logs
-SECURENOW_APPID=my-app
-OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://traces-collector:4318/v1/traces
-OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs-collector:4318/v1/logs
-SECURENOW_LOGGING_ENABLED=1
-```
-
----
-
-## Priority and Overrides
-
-When multiple variables are set, this is the priority order:
-
-### Service Name
-
-1. `OTEL_SERVICE_NAME` (highest priority)
-2. `SECURENOW_APPID`
-3. Auto-generated fallback (lowest priority)
-
-### OTLP Endpoint
-
-1. `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (for traces)
-2. `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` (for logs)
-3. `OTEL_EXPORTER_OTLP_ENDPOINT`
-4. `SECURENOW_INSTANCE`
-5. Default: `https://freetrial.securenow.ai:4318` (lowest priority)
-
----
-
-## Validation
-
-SecureNow validates environment variables on startup. Check console output:
-
-```bash
-[securenow] pid=12345 SECURENOW_APPID="my-app" OTEL_SERVICE_NAME=null → service.name=my-app-uuid123
-[securenow] OTel SDK started → http://localhost:4318/v1/traces
-[securenow] 📋 Logging: ENABLED → http://localhost:4318/v1/logs
-[securenow] 📝 Request body capture: ENABLED (max: 10240 bytes)
-```
-
----
-
-## Best Practices
-
-### 1. Use .env Files
-
-Don't hardcode in your application:
-
-```bash
-# .env
-SECURENOW_APPID=my-app
-SECURENOW_INSTANCE=http://localhost:4318
-```
-
-### 2. Different Configs per Environment
-
-```bash
-# .env.development
-SECURENOW_CAPTURE_BODY=1
-OTEL_LOG_LEVEL=debug
-
-# .env.production
-SECURENOW_CAPTURE_BODY=0
-OTEL_LOG_LEVEL=error
-```
-
-### 3. Use SECURENOW_NO_UUID in Clusters
-
-```bash
-# PM2 cluster with 4 workers
-SECURENOW_NO_UUID=1
-```
-
-### 4. Enable SECURENOW_STRICT in Production
-
-```bash
-# Fail fast if misconfigured
-SECURENOW_STRICT=1
-```
-
-### 5. Disable Body Capture in Production
-
-```bash
-# Development
-SECURENOW_CAPTURE_BODY=1
-
-# Production
-SECURENOW_CAPTURE_BODY=0
-```
-
----
-
-## Troubleshooting
-
-### Check Current Values
-
-```bash
-# Print all SECURENOW variables
-env | grep SECURENOW
-
-# Print all OTEL variables
-env | grep OTEL
-
-# Check specific variable
-echo $SECURENOW_APPID
-```
-
-### Verify in Application
-
-SecureNow logs current configuration on startup. Look for lines like:
-
-```
-[securenow] pid=12345 SECURENOW_APPID="my-app" → service.name=my-app
-[securenow] OTel SDK started → http://localhost:4318/v1/traces
-```
-
-### Enable Debug Mode
-
-```bash
-export OTEL_LOG_LEVEL=debug
-node app.js
+```json
+{
+  "config": {
+    "capture": {
+      "maxBodySize": 20480,
+      "sensitiveFields": ["session_id", "internal_token"]
+    },
+    "logging": { "enabled": false },
+    "firewall": { "failMode": "closed" }
+  }
+}
 ```
-
----
-
-## Related Documentation
-
-- [Firewall Guide](./FIREWALL-GUIDE.md)
-- [API Keys Guide](./API-KEYS-GUIDE.md)
-- [Express Setup Guide](./EXPRESS-SETUP-GUIDE.md)
-- [Next.js Setup Guide](./NEXTJS-SETUP-COMPLETE.md)
-- [Logging Guide](./LOGGING-GUIDE.md)
-- [NPM README](../NPM_README.md)
-
----
-
-**Complete reference for all SecureNow environment variables.** 🎯