securenow 5.18.0 → 6.0.1

package/SKILL-API.md

@@ -1,600 +0,0 @@
-# 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.
-
-## Installation
-
-```bash
-npm install securenow
-```
-
-### 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. Set Environment Variables
-
-```bash
-# .env or .env.local
-SECURENOW_APPID=my-app
-SECURENOW_INSTANCE=https://your-collector:4318
-```
-
-### 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 --key snk_live_...
-```
-
-That's it. Traces and logs flow to your OTLP collector. No code changes for Express, Fastify, NestJS, Koa, Hapi, and raw Node.
-
-### 3. Enable the Firewall (Optional)
-
-Add one more env var to auto-activate IP blocking:
-
-```bash
-SECURENOW_API_KEY=snk_live_abc123...
-```
-
-The firewall syncs your blocklist and enforces it on every request — zero code changes.
-
----
-
-## 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/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: [{
-    name: 'my-app',
-    script: './app.js',
-    instances: 4,
-    node_args: '-r securenow/register',
-    env: {
-      SECURENOW_APPID: 'my-app',
-      SECURENOW_INSTANCE: 'https://your-collector:4318',
-      SECURENOW_NO_UUID: '1',
-    },
-  }],
-};
-```
-
-**Docker:**
-
-```dockerfile
-ENV SECURENOW_APPID=my-app
-ENV SECURENOW_INSTANCE=https://your-collector:4318
-CMD ["node", "-r", "securenow/register", "app.js"]
-```
-
----
-
-### Next.js
-
-Three files to touch:
-
-**1. `next.config.js`** (or `.mjs` / `.ts`):
-
-```javascript
-const { withSecureNow } = require('securenow/nextjs-webpack-config');
-
-module.exports = withSecureNow({
-  // your existing config
-});
-```
-
-`withSecureNow()` auto-detects Next.js version:
-- **>=15**: sets `serverExternalPackages`
-- **<15**: sets `experimental.serverComponentsExternalPackages` + `experimental.instrumentationHook` + webpack ignore rules
-
-**2. `instrumentation.ts`** (or `.js`, can be in `src/`):
-
-```typescript
-export async function register() {
-  if (process.env.NEXT_RUNTIME === 'nodejs') {
-    const { registerSecureNow } = require('securenow/nextjs');
-    registerSecureNow();
-  }
-}
-```
-
-`registerSecureNow(options?)` accepts:
-
-```typescript
-interface RegisterOptions {
-  serviceName?: string;   // override SECURENOW_APPID
-  endpoint?: string;      // override SECURENOW_INSTANCE
-  noUuid?: boolean;       // override SECURENOW_NO_UUID
-  captureBody?: boolean;  // override SECURENOW_CAPTURE_BODY
-}
-```
-
-On Vercel it uses `@vercel/otel`; self-hosted uses vanilla `@opentelemetry/sdk-node`.
-
-**3. `.env.local`:**
-
-```bash
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=https://your-collector:4318
-```
-
-#### 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') {
-    const { registerSecureNow } = require('securenow/nextjs');
-    registerSecureNow({ captureBody: true });
-    require('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 init --key snk_live_abc123...
-```
-
-Auto-detects Next.js, creates `instrumentation.ts`, suggests `next.config` changes, writes API key to `.env.local`.
-
----
-
-### Nuxt 3
-
-**`nuxt.config.ts`:**
-
-```typescript
-export default defineNuxtConfig({
-  modules: ['securenow/nuxt'],
-  securenow: {
-    // optional overrides (defaults come from env vars)
-  },
-});
-```
-
-**`.env`:**
-
-```bash
-SECURENOW_APPID=my-nuxt-app
-SECURENOW_INSTANCE=https://your-collector:4318
-```
-
-The Nuxt module auto-configures Nitro externals, runtime config, and a server plugin that sets up OTel tracing + logging + firewall.
-
----
-
-### 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 when `SECURENOW_API_KEY` is set. It syncs your blocklist from the SecureNow API and enforces it across up to four layers:
-
-```
-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
-# .env
-SECURENOW_API_KEY=snk_live_abc123...     # auto-activates Layer 1
-SECURENOW_FIREWALL_TCP=1                  # opt-in Layer 2
-SECURENOW_FIREWALL_IPTABLES=1             # opt-in Layer 3 (Linux, needs root)
-SECURENOW_FIREWALL_CLOUD=cloudflare       # opt-in Layer 4
-```
-
-### Firewall-Only Mode (No Tracing Overhead)
-
-```bash
-node -r securenow/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');
-
-await firewall.init({
-  apiKey: process.env.SECURENOW_API_KEY,
-  apiUrl: 'https://api.securenow.ai',
-  syncInterval: 300,        // full sync every 5 min
-  versionCheckInterval: 10, // lightweight version 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' } });
-}
-```
-
-### 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
-```
-
----
-
-## 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 `SECURENOW_SENSITIVE_FIELDS=field1,field2`.
-
----
-
-## Environment Variables — Complete Reference
-
-### Required
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `SECURENOW_APPID` | Service name / app identifier | *(auto-generated with UUID)* |
-| `SECURENOW_INSTANCE` | OTLP collector base URL | `https://freetrial.securenow.ai:4318` |
-
-### Service Naming
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `OTEL_SERVICE_NAME` | OpenTelemetry standard; overrides `SECURENOW_APPID` | — |
-| `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` | Standard OTel endpoint; overrides `SECURENOW_INSTANCE` | — |
-| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Override traces endpoint specifically | `{instance}/v1/traces` |
-| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Override logs endpoint specifically | `{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 | `0` |
-| `SECURENOW_MAX_BODY_SIZE` | Max body size in bytes | `10240` |
-| `SECURENOW_CAPTURE_MULTIPART` | Capture multipart/form-data (streaming, metadata only) | `0` |
-| `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 log level: `none`, `error`, `warn`, `info`, `debug` | `none` |
-| `NODE_ENV` | Sent as `deployment.environment` attribute | `production` |
-
-### Firewall
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `SECURENOW_API_KEY` | API key (`snk_live_...`); activates firewall when set | — |
-| `SECURENOW_API_URL` | SecureNow API base URL | `https://api.securenow.ai` |
-| `SECURENOW_FIREWALL_ENABLED` | Master kill-switch (`0` to disable) | `1` |
-| `SECURENOW_FIREWALL_VERSION_INTERVAL` | Seconds between lightweight version checks | `10` |
-| `SECURENOW_FIREWALL_SYNC_INTERVAL` | Full blocklist refresh interval in seconds | `300` |
-| `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 | — |
-
-**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 version 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:** `OTEL_SERVICE_NAME` > `SECURENOW_APPID` > auto-generated
-
-**Endpoint:** `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` > `OTEL_EXPORTER_OTLP_ENDPOINT` > `SECURENOW_INSTANCE` > `https://freetrial.securenow.ai:4318`
-
----
-
-## Recipes for Agentic AI
-
-### Add Observability to an Existing Express App
-
-```bash
-npm install securenow
-```
-
-Create `.env`:
-```
-SECURENOW_APPID=my-express-api
-SECURENOW_INSTANCE=https://your-collector:4318
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_CAPTURE_BODY=1
-```
-
-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
-npx securenow init --key snk_live_abc123...
-```
-
-The `init` command creates `instrumentation.ts` and suggests `next.config` changes. Then set env vars in `.env.local`:
-
-```
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=https://your-collector:4318
-SECURENOW_API_KEY=snk_live_abc123...
-SECURENOW_CAPTURE_BODY=1
-```
-
-### Enable Firewall With Zero Tracing Overhead
-
-For apps that only need IP blocking:
-
-```bash
-node -r securenow/firewall-only app.js
-```
-
-Set `SECURENOW_API_KEY` in the environment. No other configuration needed.
-
-### Production Hardened Configuration
-
-```bash
-SECURENOW_APPID=prod-api
-SECURENOW_INSTANCE=https://collector.prod.internal:4318
-SECURENOW_NO_UUID=1
-SECURENOW_STRICT=1
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_CAPTURE_BODY=0
-SECURENOW_API_KEY=snk_live_abc123...
-SECURENOW_FIREWALL_TCP=1
-SECURENOW_FIREWALL_SYNC_INTERVAL=30
-SECURENOW_FIREWALL_FAIL_MODE=open
-OTEL_LOG_LEVEL=error
-NODE_ENV=production
-```
-
-### Instrument a Docker Container
-
-```dockerfile
-FROM node:20-slim
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --omit=dev
-COPY . .
-
-ENV SECURENOW_APPID=my-service
-ENV SECURENOW_INSTANCE=http://otel-collector:4318
-ENV SECURENOW_NO_UUID=1
-ENV SECURENOW_API_KEY=snk_live_abc123...
-
-CMD ["node", "-r", "securenow/register", "src/index.js"]
-```
-
-### Kubernetes with Separate Trace/Log Collectors
-
-```bash
-SECURENOW_APPID=k8s-service
-OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://tempo:4318/v1/traces
-OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://loki:4318/v1/logs
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_NO_UUID=1
-```
-
----
-
-## Verification
-
-On startup, securenow logs its configuration:
-
-```
-[securenow] pid=12345 SECURENOW_APPID="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
-```
-
-Use `OTEL_LOG_LEVEL=debug` and `SECURENOW_TEST_SPAN=1` to troubleshoot connectivity issues.