securenow 8.23.0 → 8.25.0

package/README.md

@@ -10,6 +10,8 @@ Your agent already sees the repository, the dependencies, the auth implementatio
 
 **Find it in code. Watch it in production.**
 
+The full guides ship in this package: [`SKILL-API.md`](./SKILL-API.md) (wiring every framework, every setting and feature, deployment, verification, troubleshooting) and [`SKILL-CLI.md`](./SKILL-CLI.md) (every CLI command, by task).
+
 ---
 
 ## What it looks like
@@ -45,16 +47,21 @@ Paste this into Claude Code, Codex, or Cursor:
 Set up SecureNow (npm package "securenow") in this project:
 
 1. Install it: npm install securenow@latest
-2. Run npx securenow login from the project root and wait while I complete
+2. Read node_modules/securenow/SKILL-API.md and follow it for this
+   project's framework and deployment.
+3. Run npx securenow login from the project root and wait while I complete
    the browser flow. It writes .securenow/runtime.json (SDK runtime config +
    runtime API key) and .securenow/admin.json (CLI/MCP auth).
-3. Wire the runtime: run npx securenow init for Next.js or Nuxt; for plain
-   Node servers (Express, Fastify, NestJS, Koa, Hapi) add
-   -r securenow/register to the start script instead.
-4. Make sure the .securenow/*.json credential files are gitignored without
+4. Run npx securenow init, then wire the runtime as SKILL-API.md says:
+   Next.js and Nuxt through init and the module; plain Node servers
+   (Express, Fastify, NestJS, Koa, Hapi, Hono, Polka, Feathers, h3) with
+   -r securenow/register on the command that starts the server, including
+   Docker CMD, PM2 node_args or systemd ExecStart.
+5. Make sure the .securenow/*.json credential files are gitignored without
    ignoring the whole .securenow/ directory. Never print their contents.
-5. Verify: npx securenow whoami, npx securenow doctor,
-   npx securenow test-span, then npx securenow status.
+6. Verify: npx securenow whoami, npx securenow doctor,
+   npx securenow test-span, start the app and check its [securenow] lines,
+   then npx securenow status.
 
 Do not block traffic or modify security policy without asking me first.
 ```
@@ -65,17 +72,20 @@ Do not block traffic or modify security policy without asking me first.
 
 ```bash
 # 1. Install
-npm install securenow
+npm install securenow@latest
 
 # 2. Pick (or create) your app in the browser — writes .securenow/runtime.json
 #    and refreshes CLI/MCP auth in .securenow/admin.json
 npx securenow login
 
-# 3. Start your app — one flag is all it takes
+# 3. Fill the runtime config and detect the framework
+npx securenow init
+
+# 4. Start your app — one flag is all it takes
 node -r securenow/register src/index.js
 ```
 
-No `.env` edits, no API keys to paste. Runtime config lives in `.securenow/runtime.json`; it is never read from environment variables.
+No `.env` edits, no API keys to paste. Runtime config lives in `.securenow/runtime.json`. The only environment variables the SDK reads are `SECURENOW_CREDENTIALS`, for hosts that cannot mount a file (see Production), and the `SECURENOW_DISABLED` test switch; any other `SECURENOW_*` variable is ignored.
 
 ```json
 "scripts": {
@@ -84,11 +94,15 @@ No `.env` edits, no API keys to paste. Runtime config lives in `.securenow/runti
 }
 ```
 
-Can't change the script? Use `NODE_OPTIONS="-r securenow/register" npm start`, or the wrapper: `npx securenow run src/index.js`.
+The same flag works for CommonJS, ESM (`"type": "module"`, `.mjs`) and TypeScript (`node -r securenow/register --import tsx src/index.ts`). Can't change the script? Use `NODE_OPTIONS="-r securenow/register" npm start`, or the wrapper: `npx securenow run src/index.js`.
+
+**Express, Fastify, NestJS, Koa, Hapi, Hono (`@hono/node-server`), Polka, Feathers, h3, raw `http`/`https`** — the preload above, no code changes.
+
+**Next.js 15 and 16** — `npx securenow init` creates `instrumentation.ts` and patches `next.config.*` when it can do so safely (`serverExternalPackages: ['securenow']` plus `outputFileTracingIncludes` for standalone output). If your config needs human judgment, `init` prints an agent-ready prompt with the exact edits to merge. `next start` and `output: 'standalone'` (Docker) both work. If `init` wrote your instrumentation file before 8.24.0, run it again: it replaces that file, whose `webpackIgnore` imports left SecureNow's dependencies out of standalone builds. With a `src/` layout `init` writes `src/instrumentation.ts` (8.25.0+), where Next.js loads it. The Edge runtime is not instrumented.
 
-**Next.js** — `npx securenow init` creates `instrumentation.ts` and patches `next.config.*` when it can do so safely (adds `securenow` to `serverExternalPackages` on Next.js 15+). If your config needs human judgment, `init` prints an agent-ready prompt with the exact edits to merge.
+**Next.js 14 (8.25.0+)** — `init` writes the `experimental` version of the config (`instrumentationHook`, `serverComponentsExternalPackages`, `outputFileTracingIncludes`), or prints the exact edits for an existing config. Tested on 14.2 (`next start` and standalone).
 
-**Nuxt 3** — add the module, then run `npx securenow init`:
+**Nuxt 3 and 4** — add the module, then run `npx securenow init`. The `nuxt build` output is fully covered (tested on Nuxt 3.21 and 4.6, with `.output` running on its own like a Docker image), and `nuxt dev` is traced too. In `nuxt dev` the client IP is known from 8.25.0; before, it was unknown behind Nuxt's dev proxy, so IP blocking only applied to the built server.
 
 ```ts
 export default defineNuxtConfig({
@@ -96,24 +110,65 @@ export default defineNuxtConfig({
 });
 ```
 
-**What's captured automatically:** HTTP spans (Express, Fastify, NestJS, Koa, Hapi, Next.js, Nuxt, raw `http`), database spans (Postgres, MySQL, MongoDB, Redis), `console.*` as logs with trace correlation, crashes (uncaught exceptions and unhandled rejections) as `FATAL` logs with their stack, request bodies with auto-redaction, multipart metadata (never file content), plus the firewall. Tune everything in `.securenow/runtime.json` under `config`.
+Settings come from `.securenow/runtime.json` like every other integration; `securenow: { ... }` options in `nuxt.config` are ignored.
+
+**PM2** — in `ecosystem.config.cjs`, pass the preload as an absolute path: `node_args: ['-r', require.resolve('securenow/register')]`. That works in fork and cluster mode (`instances: 'max'`) wherever the PM2 daemon was started. (In cluster mode Node resolves a bare `-r securenow/register` from the daemon's folder, so after `pm2 resurrect` at boot the workers crash-loop with `Cannot find module 'securenow/register'`.) Each process reads the `.securenow/` folder of the app PM2 started.
+
+**Vite** — browser telemetry is not sent to SecureNow. Instrument the Node process that serves the app: `node -r securenow/register-vite node_modules/vite/bin/vite.js preview`, or `-r securenow/register` for a Vite SSR server.
+
+**Bun** — `bun --preload securenow/register app.js` works for apps served through `node:http` (tested with Express 5 on Bun 1.3). `Bun.serve` is not traced or protected. Deno and edge runtimes (Cloudflare Workers, Vercel Edge) are not supported: SecureNow runs inside a Node.js process.
 
-**Production** — same file structure, no env vars. Generate a tokenless runtime credentials file and mount it as a deployment secret:
+**What's captured automatically:** HTTP spans with the client IP, database spans (Postgres, MySQL, MongoDB, Redis), outgoing HTTP, `console.*` as logs with trace correlation, crashes (uncaught exceptions and unhandled rejections) as `FATAL` logs with their stack, plus the spans that ended just before the crash, request headers and bodies with auto-redaction, multipart metadata (never file content), plus the firewall. `http.route` is recorded for Express, Fastify, NestJS, Koa with `@koa/router`, Hapi and Nuxt; from 8.25.0 also for Hono, h3, Feathers and Polka, and for Next.js 15 and 16 on the HTTP span (before 8.25.0 those four showed the raw path, Next.js 16 put the route on Next.js's own span and Next.js 15 recorded `next.route`). Tune everything in `.securenow/runtime.json` under `config`.
+
+**Behind a proxy** — forwarding headers (`X-Forwarded-For`, `CF-Connecting-IP`...) count only when the connection comes from a trusted proxy: private and loopback addresses, the host itself, and from 8.25.0 Unix-socket and named-pipe connections (nginx `proxy_pass http://unix:...`). Add public load balancers or CDNs to `config.networking.trustedProxies` (IPv4/IPv6 addresses or ranges, or `"cloudflare"`).
+
+**Production** — same file structure. Generate a tokenless runtime credentials file and mount it as a deployment secret (Docker, Kubernetes, VMs):
 
 ```bash
 npx securenow credentials runtime --env production
 # store the output, mount it at <app-root>/.securenow/credentials.json
 ```
 
+**Hosts without file mounts** (Vercel, Railway, Render, Heroku, Fly) — print the same credentials as one environment variable and store it as a secret there:
+
+```bash
+npx securenow credentials runtime --env production --format env
+# SECURENOW_CREDENTIALS=eyJ... -> add as a secret environment variable
+```
+
+`SECURENOW_CREDENTIALS` (raw JSON or base64) takes precedence over credential files. The startup line says where credentials came from (`credentials=env:SECURENOW_CREDENTIALS` or the file path). Next.js on Vercel goes through `@vercel/otel` and is not tested end to end; the firewall is not verified on Vercel serverless functions. Docker, Kubernetes, PM2 and systemd recipes: SKILL-API.md, section 6.
+
 **Verify** any environment with:
 
 ```bash
-npx securenow test-span      # send a test span
-npx securenow doctor         # diagnose config + connectivity
+npx securenow doctor         # diagnose config + connectivity ("All checks passed.")
+npx securenow test-span      # send a test span ("Span accepted (HTTP 200)")
 npx securenow status         # dashboard summary
+npx securenow today          # what happened, what SecureNow did, what needs you
+```
+
+**Tests** — test runs otherwise report to your real app with the project's `.securenow` credentials. `SECURENOW_DISABLED=1 npm test` turns the SDK off for that process: no traces, logs, events, firewall or session sync, and `guard()` just calls `next()`. Apart from `SECURENOW_CREDENTIALS`, this is the only setting read from the environment.
+
+---
+
+## Custom events and session revocation
+
+Report what only your app knows, so SecureNow can catch brute force, credential stuffing and account takeover:
+
+```js
+const { track } = require('securenow/events');
+track('auth.login.failure', { userId, ip, userAgent, severity: 'warn', attributes: { reason: 'bad_password' } });
 ```
 
-**Tests** — test runs otherwise report to your real app with the project's `.securenow` credentials. `SECURENOW_DISABLED=1 npm test` turns the SDK off for that process: no traces, logs, events, firewall or session sync, and `guard()` just calls `next()`. This is the only setting read from the environment.
+Fire-and-forget, batched, never throws. Recommended events: `auth.login.failure`, `auth.login.success`, `auth.otp.send.requested`, `auth.otp.send.result`, `auth.otp.verify.failure`, `auth.otp.verify.success`, `auth.password_reset.requested`, `auth.password_reset.completed`, `auth.mfa.challenge.failure`, `auth.mfa.challenge.success`, `auth.session.revoked`. From scripts or non-JS services: `npx securenow event send <type> --user <id> --ip <ip>`.
+
+Kill a stolen session with `npx securenow revoke session <id>` (or `revoke user <id>`); the SDK enforces it within 30 seconds:
+
+- **Zero code, any framework (8.25.0+):** `"sessions": { "guard": true, "capture": true }` under `config` in `.securenow/runtime.json`. Revoked sessions get 401 and their cookies cleared; `capture` sends `session.seen` for session-theft detection.
+- **Express-style middleware:** `app.use(require('securenow/sessions').guard())` (Express, Connect, Polka, NestJS with Express, Feathers-Express).
+- **Anything else (8.25.0+):** `const { revoked } = require('securenow/sessions').check(req)` in a Fastify hook, Koa or Hono middleware, a Next.js route handler or an h3 handler; `req` can be a Node request or a Web `Request`, and you return the 401.
+
+Examples for each framework: SKILL-API.md, sections 5.9 and 5.10.
 
 ---
 
@@ -146,20 +201,24 @@ codex mcp add securenow -- npx securenow mcp
 }
 ```
 
-The server resolves credentials by operation type: admin/control-plane tools use `.securenow/admin.json`, app-scoped runtime reads can use `.securenow/runtime.json` or an explicit app key. Refresh one lane with `npx securenow admin login` or `npx securenow app connect`.
+**Hosted** — `https://api.securenow.ai/mcp`, with OAuth sign-in (no install), for Claude Code (`claude mcp add --transport http securenow https://api.securenow.ai/mcp`), claude.ai, Claude Desktop, ChatGPT or any MCP client.
+
+The local server resolves credentials by operation type: admin/control-plane tools use `.securenow/admin.json`, app-scoped runtime reads can use `.securenow/runtime.json` or an explicit app key. Refresh one lane with `npx securenow admin login` or `npx securenow app connect`.
 
-It exposes tools for apps, traces, logs, firewall, IP intelligence, forensics, blocklist/allowlist/trusted IPs, session revocation, rate limits, and the human approval queue — plus bundled docs as MCP resources and ready-made prompts (`investigate_ip`, `work_human_actions`, `work_alert_review`, `soc_patrol`, `secure_project_setup`). Read tools are annotated read-only; every write tool refuses to run without `confirm: true` and a non-empty `reason`.
+It exposes tools for apps, traces, logs, the firewall, IP intelligence, forensics, blocklist/allowlist/trusted IPs, rate limits, challenges, alert rules, starter protection, and both review queues — plus bundled docs as MCP resources and ready-made prompts (`investigate_ip`, `work_human_actions`, `work_alert_review`, `soc_patrol`, `secure_project_setup`). `npx securenow mcp --profile investigator|detection|responder` serves a smaller set. Read tools are annotated read-only; every write tool refuses to run without `confirm: true` and a non-empty `reason`. Session revocation is a CLI command (`securenow revoke`).
 
 ---
 
 ## CLI
 
-Everything the MCP server can do is also a command. Run `npx securenow help` for the full reference; most read commands take `--json` for machine-readable output and `--app <key>` to target another app.
+Everything the MCP server can do is also a command. Run `npx securenow help` for the list and `npx securenow help <command>` for flags; most read commands take `--json` for machine-readable output and `--app <key>` to target another app. SKILL-CLI.md organizes them by task.
 
 ### Investigate
 
 | Command | Description |
 |---|---|
+| `securenow today` | The Overview: what happened, what SecureNow did, what needs you |
+| `securenow attacker <address>` | Why an address was flagged: verdict, signals, traffic, detections, timeline |
 | `securenow ip <address>` | IP intelligence (geo, abuse, verdict) |
 | `securenow ip traces <address>` | Traces from an IP |
 | `securenow forensics "<query>"` | Natural-language forensic query |
@@ -168,6 +227,7 @@ Everything the MCP server can do is also a command. Run `npx securenow help` for
 | `securenow traces` / `traces show <traceId>` | Recent traces / trace spans |
 | `securenow traces analyze <traceId>` | AI security analysis of a trace |
 | `securenow logs [--since 6h] [--level error]` | View logs |
+| `securenow logs errors [--since 1h]` | Failures grouped by message |
 | `securenow analytics` | Response-code analytics |
 
 ### Respond
@@ -185,8 +245,9 @@ Everything the MCP server can do is also a command. Run `npx securenow help` for
 | `securenow ratelimit add --route /api/ --limit 100 --window 1m --header x-api-key` | Per-API-key (or `--cookie session` per-session) limit |
 | `securenow firewall hits --since 1h` | Who your blocks, rate limits and challenges actually stopped |
 | `securenow challenge add <ip> --route /login` | Proof-of-work challenge instead of a hard block |
-| `securenow revoke session <id>` / `revoke user <id>` | Kill stolen sessions (enforced via `securenow/sessions`) |
+| `securenow revoke session <id>` / `revoke user <id>` | Kill stolen sessions (the SDK's session guard enforces it) |
 | `securenow trusted add <ip>` | Mark an IP as trusted |
+| `securenow agent` / `agent mode <action> <mode>` | The autonomous agent that works both queues: status, what it may do |
 
 ### Rate limits, outside your code
 
@@ -198,13 +259,15 @@ Counters live in each process by default. To share one counter across workers an
 { "config": { "firewall": { "rateLimitStore": "redis://your-redis:6379" } } }
 ```
 
-The firewall never waits on Redis: it decides from what it already knows and reports each hit in the background (at most about one extra request per process can get through while a reply is in flight). If Redis is unreachable, counting falls back to in-process.
+The firewall never waits on Redis: it decides from what it already knows and reports each hit in the background (at most a request or two per process can get through while a reply is in flight). If Redis is unreachable, counting falls back to in-process.
 
 ### Rules & detections
 
 | Command | Description |
 |---|---|
-| `securenow alerts rules` | List alert rules (`create`, `update`, `test`, `delete`, ...) |
+| `securenow protect` | Starter protection (about 20 rules every app gets, monitor or block mode) |
+| `securenow alerts rules from-text "<what to catch>" --app <key>` | Describe a detection in English; checked draft, created in test mode |
+| `securenow alerts rules` | List alert rules (`create`, `update`, `test`, `runs`, `why`, `promote`, `delete`, ...) |
 | `securenow alerts rules validate --sql @rule.sql --app <key>` | Compile and dry-run candidate detection SQL |
 | `securenow alerts history` | Alert history |
 | `securenow fp` / `fp ai-fill --description "..."` | False-positive exclusions, AI-drafted |
@@ -243,18 +306,18 @@ npx securenow run --firewall-only src/index.js
 node -r securenow/firewall-only src/index.js
 ```
 
-It syncs your app's blocklist plus SecureNow's known-bad IP feed, refreshed hourly, and blocks in-process with HTTP 403. No proxies, no DNS changes, no network configuration — and it fails open.
+It syncs your app's blocklist plus SecureNow's known-bad IP feed, refreshed hourly, and blocks in-process with HTTP 403. No proxies, no DNS changes, no network configuration — and it fails open. Rate limits (429) and proof-of-work challenges run in the same place.
 
 ---
 
 ## Security & trust
 
 - **SecureNow never needs your source code.** It sees runtime telemetry — requests, spans, logs — not your repository.
-- **Redacted at capture.** `password`, `token`, `api_key`, `authorization`, `cookie`, and friends are auto-redacted before leaving your process; multipart file content is never captured. Preview with `securenow redact '<json>'`.
+- **Redacted at capture.** `password`, `token`, `api_key`, `authorization`, `cookie`, emails, card numbers and friends are auto-redacted before leaving your process; multipart file content is never captured. Preview with `securenow redact '<json>'`. Log lines are redacted too (8.25.0+, `config.logging.redact`): credential fields and secret shapes become `[REDACTED]`, but a secret in free text still goes out, so don't log secrets.
 
   SecureNow 8.11.2 redacts sign-in credentials named `code`, `otpCode`, `oneTimeCode`, `verificationCode`, and `passcode` by default, including case and separator variants. JSON, form, GraphQL, and multipart text capture use the same rule; URL query parameters and captured headers are also protected. Credential names match exactly after normalization, so `status_code` and `error_code` remain available for investigation. Redaction changes exported telemetry only.
 - **Fails open.** If SecureNow is unreachable, your app serves traffic normally (`config.firewall.failMode: "open"` is the default).
-- **Read/write split.** MCP read tools are read-only; write tools require explicit `confirm: true` plus a reason, so your agent asks you before it blocks, rate-limits or revokes anything; every write is recorded and reversible.
+- **Read/write split.** MCP read tools are read-only; write tools require explicit `confirm: true` plus a reason, so your agent asks you before it blocks, rate-limits or changes a rule; every write is recorded and reversible.
 
 More at [securenow.ai/security](https://securenow.ai/security).
 
@@ -268,7 +331,7 @@ One plan: **$99 per app per month**, every feature included — detection, MCP,
 - **14-day free trial** for the whole account, every feature, no credit card.
 - **No free tier.** After the trial, everything pauses until you subscribe, including the firewall (the known-bad IP feed and blocklist sync stop being served).
 
-Details at [securenow.ai](https://securenow.ai/). Full CLI/SDK reference: `npx securenow help` plus the `SKILL-CLI.md` and `SKILL-API.md` files shipped in this package.
+Details at [securenow.ai](https://securenow.ai/). Full CLI/SDK reference: `npx securenow help` plus the [`SKILL-CLI.md`](./SKILL-CLI.md) and [`SKILL-API.md`](./SKILL-API.md) files shipped in this package.
 
 ## License