securenow 7.6.7 → 7.6.8

package/docs/API-KEYS-GUIDE.md

@@ -1,278 +0,0 @@
-# SecureNow API Keys
-
-API keys provide programmatic access to the SecureNow platform. They support granular feature-level permissions, application scoping, IP allowlisting, and secure one-time-copy generation.
-
----
-
-## Creating an API Key
-
-### From the Dashboard
-
-1. Go to **Settings → API Keys**
-2. Click **Create API Key**
-3. Enter a name (e.g., "Production Firewall", "CI/CD Pipeline")
-4. Select the scopes (permissions) you need
-5. Optionally restrict to specific applications and IP addresses
-6. Click **Create**
-7. **Copy the key immediately** — it will only be shown once
-
-### From the CLI
-
-```bash
-npx securenow login
-npx securenow firewall status
-```
-
-The `securenow init` and `securenow login` commands can automatically provision a firewall API key for you.
-
----
-
-## Key Format
-
-All API keys use the format:
-
-```
-snk_live_<64 hex characters>
-```
-
-Example: `snk_live_a1b2c3d4e5f6...`
-
-The `snk_live_` prefix makes it easy to identify SecureNow keys in your codebase and credential scanners.
-
----
-
-## Storing the API Key
-
-Since v7.1.0, the firewall reads its API key from `.securenow/credentials.json` as well as `SECURENOW_API_KEY`. You don't need to manage env vars for local dev.
-
-**Resolution order (firewall):**
-
-1. `SECURENOW_API_KEY` env var — **only if it starts with `snk_live_`** (non-matching values are ignored so the file can still win)
-2. Project `./.securenow/credentials.json`
-3. Global `~/.securenow/credentials.json`
-
-### Writing the key to the credentials file
-
-```bash
-# Interactive onboarding - picks/creates an app, enables that app's firewall,
-# and mints a key scoped firewall:read + blocklist:read + allowlist:read
-# (the "firewall" preset, used by default for CLI firewall onboarding)
-# and writes it to ./.securenow/credentials.json automatically.
-npx securenow login
-
-# Already have a key? Write it directly:
-npx securenow api-key set snk_live_abc123...
-
-# Save to ~/.securenow/ instead of the project
-npx securenow api-key set snk_live_abc123... --global
-
-# Inspect (masked) and see which file it came from
-npx securenow api-key show
-
-# Remove just the API key (leaves session/app in place)
-npx securenow api-key clear
-npx securenow api-key clear --global
-```
-
-The key must start with `snk_live_` — `api-key set` rejects anything else.
-
----
-
-## Scopes (Permissions)
-
-Each API key has a set of scopes that control what it can access. Scopes follow the `resource:action` pattern.
-
-| Scope | Description |
-|-------|-------------|
-| `firewall:read` | Read the blocklist (used by the firewall SDK) |
-| `blocklist:read` | List and check blocked IPs |
-| `blocklist:write` | Add and remove blocked IPs |
-| `applications:read` | List and view applications |
-| `applications:write` | Create and delete applications |
-| `traces:read` | Query traces |
-| `logs:read` | Query logs |
-| `issues:read` | List and view security issues |
-| `issues:write` | Resolve and manage issues |
-| `alerts:read` | View alert rules, channels, and history |
-| `alerts:write` | Create and manage alert rules |
-| `analytics:read` | View analytics data |
-| `forensics:read` | Run forensic queries |
-| `ip:read` | IP intelligence lookups |
-| `trusted:read` | List trusted IPs |
-| `trusted:write` | Manage trusted IPs |
-| `notifications:read` | List notifications |
-| `notifications:write` | Mark notifications as read |
-| `api-map:read` | View API map |
-| `instances:read` | List instances |
-| `false-positives:read` | List false positive rules |
-| `false-positives:write` | Create and manage false positive rules |
-
-### Principle of Least Privilege
-
-Only grant the scopes your use case requires:
-
-- **Firewall SDK:** `firewall:read`
-- **CI/CD monitoring:** `issues:read`, `traces:read`
-- **Automated remediation:** `blocklist:read`, `blocklist:write`
-- **Dashboard integration:** all `*:read` scopes
-
----
-
-## Application Scoping
-
-Restrict an API key to specific applications. When set, the key can only access data for those applications.
-
-Leave empty to allow access to all applications on your account.
-
-**Alert rules:** Keys that are scoped to specific applications **cannot** create or update alert rules with **`applicationsAll: true`** (“all applications”). Use explicit app keys on each rule instead. Unscoped keys may use all-apps mode.
-
----
-
-## IP Allowlisting
-
-Restrict an API key to specific client IPs or CIDR ranges. When set, requests from other IPs are rejected with 403.
-
-```
-34.56.78.90
-10.0.0.0/24
-```
-
-Leave empty to allow from any IP.
-
----
-
-## Using API Keys
-
-### In HTTP Requests
-
-Pass the API key in the `Authorization` header:
-
-```bash
-curl -s https://api.securenow.ai/api/v1/blocklist \
-  -H "Authorization: Bearer snk_live_abc123..."
-```
-
-### In the Firewall SDK
-
-Easiest path (v7.1+) — let the CLI write the key to the credentials file for you:
-
-```bash
-npx securenow login                       # firewall onboarding in the browser
-# or, if you already have a key:
-npx securenow api-key set snk_live_abc...
-```
-
-Or set the env var the old way:
-
-```bash
-SECURENOW_API_KEY=snk_live_abc123...
-```
-
-The firewall SDK reads the credentials file on startup if the env var is unset (or isn't a `snk_live_` key). Env vars still take precedence when present and well-formed — useful in CI / Docker / prod.
-
-### In CI/CD
-
-```yaml
-# GitHub Actions example — SDK firewall key
-env:
-  SECURENOW_API_KEY: ${{ secrets.SECURENOW_API_KEY }}
-
-steps:
-  - run: |
-      ISSUES=$(curl -s https://api.securenow.ai/api/v1/issues \
-        -H "Authorization: Bearer $SECURENOW_API_KEY")
-      echo "$ISSUES" | jq '.issues | length'
-```
-
-### CLI Authentication in CI/CD
-
-For CLI commands in CI, use the `SECURENOW_TOKEN` env var to skip file-based login:
-
-```yaml
-# GitHub Actions example — CLI auth via env var
-env:
-  SECURENOW_TOKEN: ${{ secrets.SECURENOW_CLI_TOKEN }}
-
-steps:
-  - run: npx securenow issues --json --status open
-  - run: npx securenow forensics "critical attacks in last 24h" --json
-```
-
-The `SECURENOW_TOKEN` env var takes priority over any stored credentials.
-
----
-
-## Key Management
-
-### Viewing Keys
-
-```bash
-# From the CLI
-npx securenow api-keys list
-```
-
-Or go to **Settings → API Keys** in the dashboard. You'll see the key name, last 4 characters, status, scopes, and last used timestamp.
-
-### Revoking a Key
-
-```bash
-npx securenow api-keys revoke <key-id>
-```
-
-Or click **Revoke** in the dashboard. Revoked keys immediately stop working. This cannot be undone.
-
-### Regenerating a Key
-
-Regeneration creates a new key with the same name, scopes, and settings. The old key is automatically revoked.
-
----
-
-## Rate Limits
-
-API keys are subject to rate limiting:
-
-| Endpoint | Limit |
-|----------|-------|
-| General API (`/api/*`) | 600 requests/minute |
-| Firewall sync (`/api/firewall/*`) | 120 requests/minute |
-
-Rate limit headers are included in every response:
-
-```
-X-RateLimit-Limit: 600
-X-RateLimit-Remaining: 597
-X-RateLimit-Reset: 1712534400
-```
-
----
-
-## Security Best Practices
-
-1. **Never commit API keys to source control.** Use `.env` files or secret managers.
-2. **Use the minimum scopes required.** A firewall key only needs `firewall:read`.
-3. **Restrict by IP when possible.** Server keys should be locked to your server IPs.
-4. **Rotate keys periodically.** Use the regenerate feature to rotate without downtime.
-5. **Monitor usage.** Check the "last used" timestamp and known IPs in the dashboard.
-6. **Revoke unused keys.** Delete keys that are no longer in use.
-
----
-
-## API Versioning
-
-All API endpoints are available at both `/api/` and `/api/v1/`. We recommend using the versioned path for stability:
-
-```bash
-# Recommended
-https://api.securenow.ai/api/v1/blocklist
-
-# Also works (unversioned)
-https://api.securenow.ai/api/blocklist
-```
-
----
-
-## Related Documentation
-
-- [Firewall Guide](./FIREWALL-GUIDE.md) — Automatic IP blocking setup
-- [Environment Variables Reference](./ENVIRONMENT-VARIABLES.md) — All configuration options
-- [All Frameworks Quick Start](./ALL-FRAMEWORKS-QUICKSTART.md) — Framework setup guides

package/docs/ARCHITECTURE.md

@@ -1,408 +0,0 @@
-# SecureNow Architecture
-
-## Overview
-
-SecureNow provides seamless OpenTelemetry instrumentation for Node.js and Next.js applications with minimal configuration.
-
----
-
-## Component Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     SecureNow Package                       │
-├─────────────────────────────────────────────────────────────┤
-│                                                               │
-│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐       │
-│  │ register.js │  │  tracing.js  │  │  nextjs.js   │       │
-│  │ (Node.js    │  │  (Manual     │  │  (Next.js    │       │
-│  │  Preload)   │  │   Setup)     │  │  Integration)│       │
-│  └─────────────┘  └──────────────┘  └──────────────┘       │
-│         │                 │                  │               │
-│         └─────────────────┴──────────────────┘               │
-│                           │                                   │
-│                           ▼                                   │
-│         ┌──────────────────────────────────┐                 │
-│         │  OpenTelemetry Node SDK          │                 │
-│         │  + Auto-Instrumentations         │                 │
-│         └──────────────────────────────────┘                 │
-│                           │                                   │
-└───────────────────────────┼───────────────────────────────────┘
-                            │
-                            ▼
-         ┌──────────────────────────────────┐
-         │   OTLP/HTTP Trace Exporter       │
-         └──────────────────────────────────┘
-                            │
-                            ▼
-         ┌──────────────────────────────────┐
-         │   SecureNow / OpenTelemetry      │
-         │   Collector                      │
-         └──────────────────────────────────┘
-```
-
----
-
-## Entry Points
-
-### 1. `register.js` - Node.js Preload (General Apps)
-
-**Use Case:** Express, Fastify, NestJS, any Node.js app
-
-**Usage:**
-```bash
-NODE_OPTIONS="-r securenow/register" node app.js
-```
-
-**How it works:**
-- Loads before your application code
-- Imports `tracing.js` to initialize OpenTelemetry
-- Works with any Node.js framework
-
----
-
-### 2. `nextjs.js` - Next.js Integration
-
-**Use Case:** Next.js applications (App Router & Pages Router)
-
-**Usage:**
-```typescript
-// instrumentation.ts
-import { registerSecureNow } from 'securenow/nextjs';
-export function register() { registerSecureNow(); }
-```
-
-**How it works:**
-- Exports `registerSecureNow()` function
-- Called by Next.js instrumentation hook
-- Initializes OpenTelemetry SDK for Node.js runtime only
-- Skips Edge runtime (not yet supported)
-
-**Special features:**
-- Detects Next.js environment variables (`VERCEL_ENV`, `VERCEL_REGION`)
-- Uses `service.instance.id` for multi-worker deployments
-- Disables noisy instrumentations (like `fs`) by default
-
----
-
-### 3. `tracing.js` - Core Instrumentation
-
-**Use Case:** Manual setup, or imported by other entry points
-
-**Usage:**
-```javascript
-require('securenow/tracing');
-```
-
-**How it works:**
-- Core OpenTelemetry setup
-- Configures OTLP exporter
-- Initializes `getNodeAutoInstrumentations()`
-- Handles graceful shutdown
-
----
-
-## Configuration Flow
-
-```
-Environment Variables
-         │
-         ├─► SECURENOW_APPID / OTEL_SERVICE_NAME
-         │       └─► service.name
-         │
-         ├─► SECURENOW_INSTANCE / OTEL_EXPORTER_OTLP_ENDPOINT
-         │       └─► Traces endpoint URL
-         │
-         ├─► OTEL_EXPORTER_OTLP_HEADERS
-         │       └─► Authentication headers
-         │
-         ├─► SECURENOW_NO_UUID
-         │       └─► Disable UUID suffix
-         │
-         └─► SECURENOW_DISABLE_INSTRUMENTATIONS
-                 └─► Disable specific instrumentations
-```
-
----
-
-## Auto-Instrumentation
-
-SecureNow uses `@opentelemetry/auto-instrumentations-node` which includes:
-
-### Web Frameworks
-- `@opentelemetry/instrumentation-express`
-- `@opentelemetry/instrumentation-fastify`
-- `@opentelemetry/instrumentation-nestjs-core`
-- `@opentelemetry/instrumentation-koa`
-- `@opentelemetry/instrumentation-hapi`
-
-### Databases
-- `@opentelemetry/instrumentation-pg` (PostgreSQL)
-- `@opentelemetry/instrumentation-mysql`
-- `@opentelemetry/instrumentation-mysql2`
-- `@opentelemetry/instrumentation-mongodb`
-- `@opentelemetry/instrumentation-redis`
-
-### HTTP & Network
-- `@opentelemetry/instrumentation-http`
-- `@opentelemetry/instrumentation-https`
-- `@opentelemetry/instrumentation-fetch`
-- `@opentelemetry/instrumentation-grpc`
-- `@opentelemetry/instrumentation-graphql`
-
-### Other
-- `@opentelemetry/instrumentation-dns`
-- `@opentelemetry/instrumentation-net`
-- `@opentelemetry/instrumentation-fs`
-- And many more...
-
----
-
-## Data Flow
-
-```
-Your Application
-      │
-      ├─► HTTP Request
-      ├─► Database Query
-      ├─► External API Call
-      └─► Custom Operations
-            │
-            ▼
-   ┌─────────────────┐
-   │  Auto           │
-   │  Instrumentations│
-   └─────────────────┘
-            │
-            ▼
-   ┌─────────────────┐
-   │  OpenTelemetry  │
-   │  SDK            │
-   │  - Create Spans │
-   │  - Add Attributes│
-   │  - Sampling     │
-   └─────────────────┘
-            │
-            ▼
-   ┌─────────────────┐
-   │  Batch Span     │
-   │  Processor      │
-   └─────────────────┘
-            │
-            ▼
-   ┌─────────────────┐
-   │  OTLP Trace     │
-   │  Exporter       │
-   │  (HTTP)         │
-   └─────────────────┘
-            │
-            ▼
-   ┌─────────────────┐
-   │  SecureNow /    │
-   │  OTLP Collector │
-   └─────────────────┘
-```
-
----
-
-## Resource Attributes
-
-Every span includes these resource attributes:
-
-```javascript
-{
-  "service.name": "my-app-uuid",           // From SECURENOW_APPID
-  "service.instance.id": "my-app-uuid",    // Unique per worker
-  "deployment.environment": "production",   // From NODE_ENV
-  "service.version": "1.0.0",              // From package.json
-  
-  // Next.js specific
-  "next.runtime": "nodejs",                // Next.js runtime type
-  "vercel.region": "iad1"                  // Vercel deployment region
-}
-```
-
----
-
-## Span Lifecycle
-
-```
-1. Request arrives
-         │
-         ▼
-2. Auto-instrumentation creates root span
-         │
-         ▼
-3. Application code executes
-   - Child spans created automatically
-   - Database queries → spans
-   - HTTP calls → spans
-   - Framework operations → spans
-         │
-         ▼
-4. Request completes
-         │
-         ▼
-5. Spans end and are batched
-         │
-         ▼
-6. Batch sent to collector via HTTP
-         │
-         ▼
-7. Visible in SecureNow UI
-```
-
----
-
-## Shutdown Process
-
-```
-Signal (SIGTERM/SIGINT)
-         │
-         ▼
-Shutdown handler triggered
-         │
-         ├─► Flush pending spans
-         │
-         ├─► Close exporter
-         │
-         └─► Exit process
-```
-
----
-
-## Next.js Specific Behavior
-
-### Instrumentation Hook Flow
-
-```
-1. Next.js starts
-         │
-         ▼
-2. Reads instrumentation.ts/js
-         │
-         ▼
-3. Calls register() function
-         │
-         ▼
-4. registerSecureNow() initializes
-   - Checks runtime (skip if Edge)
-   - Configures SDK
-   - Starts instrumentation
-         │
-         ▼
-5. Application code runs with tracing
-```
-
-### Runtime Detection
-
-```javascript
-if (process.env.NEXT_RUNTIME === 'edge') {
-  // Skip Edge runtime (not supported)
-  return;
-}
-
-// Continue with Node.js runtime
-```
-
----
-
-## Performance Considerations
-
-### Sampling
-- Default: All spans sampled (100%)
-- Configurable via OpenTelemetry SDK
-
-### Batching
-- Spans batched before export
-- Reduces network calls
-- Configurable batch size
-
-### Overhead
-- Typical overhead: 1-5% CPU
-- Memory: ~10-50MB depending on traffic
-- Negligible latency impact
-
----
-
-## Security
-
-### API Key Handling
-```bash
-# Passed via headers
-OTEL_EXPORTER_OTLP_HEADERS="x-api-key=secret"
-
-# Never logged or exposed
-# Sent directly to collector
-```
-
-### Network
-- OTLP/HTTP uses standard HTTP(S)
-- Supports TLS encryption
-- Authentication via headers
-
----
-
-## Troubleshooting
-
-### Debug Mode
-
-Enable verbose logging:
-```bash
-OTEL_LOG_LEVEL=debug
-```
-
-Output includes:
-- SDK initialization
-- Span creation
-- Export attempts
-- Errors
-
-### Test Span
-
-Create a test span on startup:
-```bash
-SECURENOW_TEST_SPAN=1
-```
-
-Verifies:
-- SDK is initialized
-- Tracer is working
-- Configuration is correct
-
----
-
-## Comparison Matrix
-
-| Feature | register.js | nextjs.js | tracing.js |
-|---------|-------------|-----------|------------|
-| Node.js Apps | ✅ | ❌ | ✅ |
-| Next.js | ❌ | ✅ | ❌ |
-| Auto-preload | ✅ | ❌ | ❌ |
-| Manual import | ❌ | ✅ | ✅ |
-| Edge Runtime | ❌ | ⚠️ (skipped) | ❌ |
-| PM2/Cluster | ✅ | ✅ | ✅ |
-
----
-
-## Future Enhancements
-
-- [ ] Edge Runtime support
-- [ ] Browser instrumentation integration
-- [ ] Metrics support (in addition to traces)
-- [ ] Logs correlation
-- [ ] Custom span decorators
-- [ ] Configuration presets (development, production)
-
----
-
-**For more details, see:**
-- [NEXTJS-GUIDE.md](./NEXTJS-GUIDE.md) - Complete Next.js guide
-- [README.md](./README.md) - General documentation
-
-
-
-
-
-
-