securenow 7.0.0-anas.2 → 7.0.0-anas.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/CONSUMING-APPS-GUIDE.md +17 -11
  2. package/README.md +204 -282
  3. package/SKILL-CLI.md +8 -4
  4. package/cli/apps.js +8 -19
  5. package/docs/ALL-FRAMEWORKS-QUICKSTART.md +8 -0
  6. package/docs/ENVIRONMENT-VARIABLES.md +24 -15
  7. package/docs/LOGGING-QUICKSTART.md +25 -38
  8. package/docs/NEXTJS-QUICKSTART.md +46 -36
  9. package/docs/NUXT-GUIDE.md +17 -13
  10. package/examples/nextjs-env-example.txt +32 -34
  11. package/package.json +1 -1
  12. package/postinstall.js +3 -11
package/CONSUMING-APPS-GUIDE.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  This guide is for developers who want to add the `securenow` package to their applications to enable logging to SecureNow or any OTLP-compatible backend.
4
4
 
5
- **Since v5.6.0:** When `SECURENOW_LOGGING_ENABLED=1`, `console.log`, `console.warn`, `console.error`, `console.info`, and `console.debug` are **automatically** forwarded as OTLP log records after you load `securenow/register`. A separate `require('securenow/console-instrumentation')` is no longer required (the module remains for backward compatibility).
5
+ **Since v7.0.0:** Logging, body capture, and multipart capture are **on by default**. Credentials come from `.securenow/credentials.json` written by `npx securenow login` — no env vars required for local dev. Set `SECURENOW_LOGGING_ENABLED=0` to disable logging if you don't want it.
6
6
 
7
7
  ---
8
8
 
@@ -10,30 +10,36 @@ This guide is for developers who want to add the `securenow` package to their ap
10
10
 
11
11
  ```bash
12
12
  npm install securenow
13
+ npx securenow login # pick/create your app in the browser
13
14
  ```
14
15
 
16
+ That's it for local dev. The `login` step writes `.securenow/credentials.json` (gitignored automatically) and the SDK reads it at boot.
17
+
18
+ For CI / Docker / production where you can't run the browser flow, set env vars — see "Step 1 (alternative)" below.
19
+
15
20
  ---
16
21
 
17
22
  ## Setup Steps
18
23
 
19
- ### Step 1: Configure Environment Variables
24
+ ### Step 1 (alternative) — Environment variables for CI / Docker / prod
20
25
 
21
- Add these to your `.env` file or export them:
26
+ If `npx securenow login` isn't an option on the target machine, set:
22
27
 
23
28
  ```bash
24
- # Required: Enable logging
25
- SECURENOW_LOGGING_ENABLED=1
29
+ # App routing key (UUID) — from `npx securenow apps`
30
+ SECURENOW_APPID=your-app-key-uuid
26
31
 
27
- # Required: Your app name
28
- SECURENOW_APPID=my-app-name
32
+ # OTLP collector (defaults to https://freetrial.securenow.ai:4318)
33
+ SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
29
34
 
30
- # Required: Your OTLP endpoint
31
- SECURENOW_INSTANCE=http://your-otlp-collector:4318
32
-
33
- # For managed OTLP / authentication (optional):
35
+ # Optional — defaults are already on:
36
+ # SECURENOW_LOGGING_ENABLED=0 # to disable console-log forwarding
37
+ # SECURENOW_CAPTURE_BODY=0 # to disable body capture (required for Fastify/Hapi/Hono)
34
38
  # OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-key"
35
39
  ```
36
40
 
41
+ Env vars always take precedence over the credentials file.
42
+
37
43
  ---
38
44
 
39
45
  ### Step 2: Choose Your Integration Method
package/README.md CHANGED
@@ -1,28 +1,25 @@
1
1
  # SecureNow
2
2
 
3
- OpenTelemetry instrumentation for Node.js, Next.js, and Nuxt applications - send **traces and logs** to any OTLP-compatible backend (including SecureNow).
3
+ Zero-config OpenTelemetry for Node.js, Next.js, and Nuxt — traces, logs, body capture, and IP firewall in one install. **No env vars. No copy-pasting keys.**
4
4
 
5
5
  **Official npm package:** [securenow](http://securenow.ai/)
6
6
 
7
7
  ---
8
8
 
9
- ## 🚀 Quick Start
10
-
11
- ### For Any Node.js App (Express, Fastify, NestJS, Koa, Hapi, etc.)
9
+ ## 🚀 30-second setup
12
10
 
13
11
  ```bash
14
12
  # 1. Install
15
13
  npm install securenow
16
14
 
17
- # 2. Set env vars
18
- export SECURENOW_APPID=my-app
19
- export SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
15
+ # 2. Pick (or create) your app in the browser — writes .securenow/ locally
16
+ npx securenow login
20
17
 
21
- # 3. Add -r securenow/register to your start command
22
- node -r securenow/register src/app.js
18
+ # 3. Start your app — one flag is all it takes
19
+ node -r securenow/register src/index.js
23
20
  ```
24
21
 
25
- That's it. One `-r` flag is all you need — ESM and CJS apps are handled automatically (Node >=20.6 auto-registers the ESM loader hook).
22
+ That's it. No `.env` edits, no API keys to paste, no peer-dep warnings. Your traces arrive in the app you picked during login.
26
23
 
27
24
  > **package.json** example:
28
25
  > ```json
@@ -32,26 +29,51 @@ That's it. One `-r` flag is all you need — ESM and CJS apps are handled automa
32
29
  > }
33
30
  > ```
34
31
 
35
- You can also use `NODE_OPTIONS` so your existing scripts stay unchanged:
36
- ```bash
37
- NODE_OPTIONS="-r securenow/register" npm start
32
+ ---
33
+
34
+ ## How it works
35
+
36
+ `npx securenow login` opens a browser, lets you pick (or create) an application, and writes a **project-local** credentials file to `.securenow/credentials.json`:
37
+
38
+ ```json
39
+ {
40
+ "token": "...",
41
+ "email": "you@example.com",
42
+ "app": {
43
+ "key": "<uuid>",
44
+ "name": "my-backend",
45
+ "instance": "https://freetrial.securenow.ai:4318"
46
+ }
47
+ }
38
48
  ```
39
49
 
40
- See the [All Frameworks Quick Start](./docs/ALL-FRAMEWORKS-QUICKSTART.md) for tested setup guides.
50
+ The SDK reads this file at boot and sends traces/logs directly to the right app bucket. The file is auto-added to `.gitignore` so it never lands in git.
41
51
 
42
52
  ---
43
53
 
44
- ### For Next.js Applications
54
+ ## Framework integration
55
+
56
+ ### Node.js / Express / Fastify / NestJS / Koa / Hapi
57
+
58
+ Just add `-r securenow/register` to your start command. No code changes. Every route, DB call, and `console.log` is captured automatically.
45
59
 
46
60
  ```bash
47
- # 1. Install
48
- npm install securenow
61
+ node -r securenow/register src/app.js
62
+ ```
63
+
64
+ Or with `NODE_OPTIONS` if you can't change the script:
65
+
66
+ ```bash
67
+ NODE_OPTIONS="-r securenow/register" npm start
68
+ ```
69
+
70
+ ### Next.js
49
71
 
50
- # 2. Auto-scaffold instrumentation files
51
- npx securenow init --key snk_live_abc123...
72
+ ```bash
73
+ npx securenow init
52
74
  ```
53
75
 
54
- This creates `instrumentation.ts` and tells you to wrap your `next.config.js`:
76
+ Creates `instrumentation.ts` and shows you how to wrap `next.config.js`:
55
77
 
56
78
  ```javascript
57
79
  // next.config.js
@@ -62,382 +84,282 @@ module.exports = withSecureNow({
62
84
  });
63
85
  ```
64
86
 
65
- `withSecureNow()` auto-detects Next.js 14 vs 15 and sets the correct externalization config. No manual `serverExternalPackages` list needed.
66
-
67
- Configure `.env.local`:
68
-
69
- ```bash
70
- SECURENOW_APPID=my-nextjs-app
71
- SECURENOW_INSTANCE=http://your-otlp-collector:4318
72
- SECURENOW_API_KEY=snk_live_abc123...
73
- ```
74
-
75
- **Done!** See [Next.js Complete Guide](./docs/NEXTJS-GUIDE.md) for details.
76
-
77
- ---
87
+ `withSecureNow()` auto-detects Next.js 14 vs 15 vs 16. See [Next.js Complete Guide](./docs/NEXTJS-GUIDE.md).
78
88
 
79
- ### For Nuxt 3 Applications
80
-
81
- ```bash
82
- # 1. Install
83
- npm install securenow
84
- ```
85
-
86
- Add the module to your `nuxt.config.ts`:
89
+ ### Nuxt 3
87
90
 
88
91
  ```ts
92
+ // nuxt.config.ts
89
93
  export default defineNuxtConfig({
90
94
  modules: ['securenow/nuxt'],
91
95
  });
92
96
  ```
93
97
 
94
- Set environment variables in `.env`:
95
-
96
- ```bash
97
- SECURENOW_APPID=my-nuxt-app
98
- SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
99
- ```
100
-
101
- **Done!** All server-side requests are now traced automatically. The firewall also activates automatically when `SECURENOW_API_KEY` is set. See the [Nuxt 3 Complete Guide](./docs/NUXT-GUIDE.md) for details.
98
+ See [Nuxt 3 Guide](./docs/NUXT-GUIDE.md).
102
99
 
103
100
  ---
104
101
 
105
- ### CLI -- Manage Everything from the Terminal
106
-
107
- ```bash
108
- # Set up your project (auto-detects framework, creates instrumentation files)
109
- npx securenow init --key snk_live_abc123...
110
-
111
- # Authenticate
112
- npx securenow login
113
-
114
- # Create an app and get the key
115
- npx securenow apps create my-app
116
-
117
- # Set it as default so you don't need --app every time
118
- npx securenow config set defaultApp <key>
102
+ ## What's captured automatically
119
103
 
120
- # View traces, logs
121
- npx securenow traces
122
- npx securenow logs
104
+ - ✅ HTTP spans (Express, Fastify, NestJS, Koa, Hapi, Next.js, Nuxt, raw `http`)
105
+ - ✅ Database spans (Postgres, MySQL, MongoDB, Redis)
106
+ - ✅ `console.log/info/warn/error/debug` forwarded as OTLP logs with trace correlation
107
+ - ✅ Request body capture (JSON, GraphQL, form-encoded) with auto-redaction of `password`, `token`, `api_key`, `authorization`, `cookie`, etc.
108
+ - ✅ Multipart upload metadata (field names, file names, sizes, content-types — never file content)
109
+ - ✅ Firewall (500k+ known-bad IPs, refreshed hourly) — activates as soon as you've logged in
123
110
 
124
- # IP intelligence, forensic queries, blocklist
125
- npx securenow ip 1.2.3.4
126
- npx securenow forensics "show top attacking IPs in the last hour"
127
- npx securenow blocklist add 1.2.3.4 --reason "scanner"
128
-
129
- # Firewall — automatic IP blocking
130
- npx securenow firewall status
131
- npx securenow firewall test-ip 1.2.3.4
132
-
133
- # False-positive triage from the terminal (full parity with the dashboard)
134
- npx securenow fp ai-fill --description "Stripe webhook POST to /api/stripe/webhook"
135
- npx securenow fp mark <notification-id> <ip> --reason "Known partner IP"
136
-
137
- # Telemetry from scripts/CI — no SDK boot required
138
- npx securenow log send "Deploy succeeded" --level info --attrs version=1.2.3
139
- npx securenow test-span # verify collector connectivity
140
-
141
- # Diagnostics & utilities
142
- npx securenow doctor # probe OTLP + API endpoints
143
- npx securenow env # show resolved config
144
- npx securenow redact '{"user":"a","password":"s"}' # preview redaction
145
- npx securenow cidr match 10.0.0.5 10.0.0.0/8 # exit 0 = hit, 2 = miss
146
-
147
- # Full dashboard overview
148
- npx securenow status
149
- ```
150
-
151
- Run `npx securenow help` for all commands. See the [CLI Reference](#cli-reference) below.
152
-
153
- > **Full CLI/SDK parity (v6.1.0+).** Every SDK export has a CLI counterpart: `redactSensitiveData` → `securenow redact`, `createMatcher` → `securenow cidr match`, `getLogger().emit()` → `securenow log send`, `SECURENOW_TEST_SPAN` → `securenow test-span`, `node -r securenow/firewall-only` → `securenow run --firewall-only`.
111
+ All of these are **on by default**. Each can be disabled individually with an env var if needed (e.g. `SECURENOW_CAPTURE_BODY=0`).
154
112
 
155
113
  ---
156
114
 
157
- ---
115
+ ## Overriding via environment variables (CI, Docker, prod)
158
116
 
159
- ## 📦 Installation
117
+ `.securenow/credentials.json` is the zero-config path for local dev. For CI, containers, or prod servers where you can't run `npx securenow login`, set env vars — they always take precedence:
160
118
 
161
119
  ```bash
162
- npm install securenow
163
- # or
164
- yarn add securenow
165
- # or
166
- pnpm add securenow
120
+ SECURENOW_APPID=<app-key-uuid> # routing key (from dashboard or `npx securenow apps`)
121
+ SECURENOW_INSTANCE=https://your-collector # defaults to freetrial
122
+ SECURENOW_API_KEY=<same uuid> # enables the firewall
167
123
  ```
168
124
 
169
- ---
125
+ Resolution order (first non-empty wins):
126
+
127
+ 1. Environment variable
128
+ 2. Project-local `.securenow/credentials.json`
129
+ 3. Global `~/.securenow/credentials.json`
130
+ 4. `package.json#name` (label only — won't route telemetry)
170
131
 
171
- ## ⚙️ Configuration
132
+ ---
172
133
 
173
- ### Environment Variables
134
+ ## CLI
174
135
 
175
136
  ```bash
176
- # Required: Your application identifier
177
- SECURENOW_APPID=my-app-name
137
+ # Setup
138
+ npx securenow login # browser auth + app picker (saves to ./.securenow/)
139
+ npx securenow login --global # save to ~/.securenow/ instead
140
+ npx securenow login --token <TOKEN> # headless (CI)
141
+ npx securenow init # scaffold Next.js instrumentation files
142
+
143
+ # Apps
144
+ npx securenow apps # list all apps
145
+ npx securenow apps create my-app # create and get the key
146
+ npx securenow apps default <key> # change which app this project uses
147
+
148
+ # Observability
149
+ npx securenow traces # list recent traces
150
+ npx securenow logs # tail logs
151
+ npx securenow status # dashboard summary
152
+ npx securenow doctor # diagnose config + connectivity
153
+
154
+ # Security
155
+ npx securenow firewall status
156
+ npx securenow blocklist add 1.2.3.4 --reason "scanner"
157
+ npx securenow fp ai-fill --description "Stripe webhook POST /api/stripe/webhook"
178
158
 
179
- # Optional: Your OTLP collector endpoint
180
- # Default: https://freetrial.securenow.ai:4318
181
- SECURENOW_INSTANCE=http://your-otlp-collector:4318
159
+ # Telemetry from shell (no SDK boot)
160
+ npx securenow log send "Deploy succeeded" --level info
161
+ npx securenow test-span # verify collector connectivity
162
+ ```
182
163
 
183
- # Optional: Enable Logging
184
- SECURENOW_LOGGING_ENABLED=1 # Enable automatic log collection
164
+ Full reference: run `npx securenow help` or see [CLI Reference](#cli-reference) below.
185
165
 
186
- # Optional: Additional configuration
187
- SECURENOW_NO_UUID=1 # Don't append UUID to service name
188
- OTEL_LOG_LEVEL=info # debug|info|warn|error
189
- SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns # Disable specific instrumentations
190
- OTEL_EXPORTER_OTLP_HEADERS="x-api-key=..." # Authentication headers
166
+ ---
191
167
 
192
- # Optional: Request body capture (for debugging)
193
- SECURENOW_CAPTURE_BODY=1 # Capture request bodies in traces
194
- SECURENOW_MAX_BODY_SIZE=10240 # Max body size in bytes
195
- SECURENOW_SENSITIVE_FIELDS="field1,field2" # Additional fields to redact
168
+ ## Environment variables (optional)
196
169
 
197
- # Optional: Multipart body capture (file upload metadata)
198
- SECURENOW_CAPTURE_MULTIPART=1 # Capture multipart field names, values & file metadata
199
- ```
170
+ Only set these if you want to override the zero-config defaults.
200
171
 
201
- ### Legacy Environment Variables (still supported)
172
+ | Variable | Default | Purpose |
173
+ |---|---|---|
174
+ | `SECURENOW_APPID` | from credentials file | App routing key (UUID) — sent as OTel `service.name` |
175
+ | `SECURENOW_INSTANCE` | `https://freetrial.securenow.ai:4318` | OTLP collector endpoint |
176
+ | `SECURENOW_API_KEY` | from credentials file | Enables firewall + collector routing |
177
+ | `SECURENOW_LOGGING_ENABLED` | `1` (on) | Forward `console.*` as OTLP logs. Set to `0` to disable. |
178
+ | `SECURENOW_CAPTURE_BODY` | `1` (on) | Capture JSON / form request bodies. Set to `0` for Fastify/Hapi/Hono. |
179
+ | `SECURENOW_CAPTURE_MULTIPART` | `1` (on) | Capture multipart metadata (not content). |
180
+ | `SECURENOW_MAX_BODY_SIZE` | `10240` | Max bytes captured per body. |
181
+ | `SECURENOW_SENSITIVE_FIELDS` | `password,token,authorization,...` | Extra fields to redact (comma-separated). |
182
+ | `SECURENOW_DISABLE_INSTRUMENTATIONS` | — | Comma-separated OTel instrumentations to disable. |
183
+ | `SECURENOW_NO_UUID` | `0` | Don't append a UUID to `service.instance.id`. |
184
+ | `SECURENOW_STRICT` | `0` | Exit with code 1 if `SECURENOW_APPID` is missing in a PM2 cluster. |
185
+ | `OTEL_EXPORTER_OTLP_HEADERS` | — | Raw OTLP headers (e.g. `x-api-key=...`). |
186
+ | `OTEL_LOG_LEVEL` | — | `debug`/`info`/`warn`/`error`. |
202
187
 
203
- ```bash
204
- export securenow=<API-KEY>
205
- export securenow_instance='http://<dedicated_instance>:4318'
206
- ```
188
+ Full list: [docs/ENVIRONMENT-VARIABLES.md](./docs/ENVIRONMENT-VARIABLES.md).
207
189
 
208
190
  ---
209
191
 
210
- ## 🎯 Supported Frameworks & Libraries
192
+ ## Supported frameworks
211
193
 
212
- SecureNow automatically instruments:
213
-
214
- ### Web Frameworks
215
- - ✅ Next.js (App Router & Pages Router)
216
- - ✅ Nuxt 3 (Nitro server)
217
- - ✅ Express.js
218
- - ✅ Fastify
219
- - ✅ NestJS
220
- - ✅ Koa
221
- - ✅ Hapi
194
+ ### Web
195
+ Next.js (App & Pages Router) · Nuxt 3 · Express · Fastify · NestJS · Koa · Hapi
222
196
 
223
197
  ### Databases
224
- - ✅ PostgreSQL
225
- - ✅ MySQL / MySQL2
226
- - ✅ MongoDB
227
- - ✅ Redis
228
-
229
- ### Logging
230
- - ✅ Automatic console logging (console.log, info, warn, error)
231
- - ✅ Structured logging with OpenTelemetry
232
- - ✅ Automatic trace-log correlation
233
- - ✅ Works with all frameworks
198
+ PostgreSQL · MySQL / MySQL2 · MongoDB · Redis
234
199
 
235
200
  ### Other
236
- - ✅ HTTP/HTTPS requests
237
- - ✅ GraphQL
238
- - ✅ gRPC
239
- - ✅ And many more via OpenTelemetry auto-instrumentation
201
+ HTTP/HTTPS · GraphQL · gRPC · and many more via [@opentelemetry/auto-instrumentations-node](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node).
202
+
203
+ > MongoDB instrumentation is opt-in (`SECURENOW_ENABLE_MONGODB_INSTRUMENTATION=1`) because older versions corrupted cursors on `mongodb@6.6+`. Safe again since SDK v6.0.2.
240
204
 
241
205
  ---
242
206
 
243
- ## 📚 Documentation
207
+ ## Documentation
244
208
 
245
209
  ### Quick Starts
246
- - **[Next.js Quick Start](./docs/NEXTJS-QUICKSTART.md)** - Get started in 30 seconds
247
- - **[Nuxt 3 Guide](./docs/NUXT-GUIDE.md)** - One-line Nuxt module setup
248
- - **[Logging Quick Start](./docs/LOGGING-QUICKSTART.md)** - Add logging in 2 minutes
210
+ - [Next.js Quick Start](./docs/NEXTJS-QUICKSTART.md)
211
+ - [Nuxt 3 Guide](./docs/NUXT-GUIDE.md)
212
+ - [All Frameworks](./docs/ALL-FRAMEWORKS-QUICKSTART.md)
213
+ - [Logging Quick Start](./docs/LOGGING-QUICKSTART.md)
249
214
 
250
215
  ### Complete Guides
251
- - **[Firewall Guide](./docs/FIREWALL-GUIDE.md)** - Automatic multi-layer IP blocking
252
- - **[API Keys Guide](./docs/API-KEYS-GUIDE.md)** - API key management and scopes
253
- - **[Next.js Complete Guide](./docs/NEXTJS-GUIDE.md)** - Full Next.js integration guide
254
- - **[Nuxt 3 Complete Guide](./docs/NUXT-GUIDE.md)** - Full Nuxt 3 integration guide
255
- - **[Logging Complete Guide](./docs/LOGGING-GUIDE.md)** - Full logging setup for all frameworks
256
- - **[📚 Complete Documentation](./docs/INDEX.md)** - All guides and references
216
+ - [Firewall](./docs/FIREWALL-GUIDE.md)
217
+ - [API Keys](./docs/API-KEYS-GUIDE.md)
218
+ - [Next.js Complete](./docs/NEXTJS-GUIDE.md)
219
+ - [Nuxt 3 Complete](./docs/NUXT-GUIDE.md)
220
+ - [Logging Complete](./docs/LOGGING-GUIDE.md)
221
+ - [📚 All Docs](./docs/INDEX.md)
257
222
 
258
223
  ### Examples
259
- - **[Code Examples](./examples/)** - Ready-to-use examples for different setups
224
+ - [Code Examples](./examples/)
260
225
 
261
226
  ---
262
227
 
263
228
  ## CLI Reference
264
229
 
265
- After installing the package, the `securenow` CLI is available via `npx securenow` or globally after `npm install -g securenow`.
230
+ After install, the `securenow` CLI is available via `npx securenow` or globally with `npm install -g securenow`.
266
231
 
267
232
  ### Run (convenience wrapper)
268
233
 
269
234
  | Command | Description |
270
- |---------|-------------|
271
- | `securenow run <script>` | Run a Node.js app with `-r securenow/register` injected |
235
+ |---|---|
236
+ | `securenow run <script>` | Run a Node app with `-r securenow/register` injected |
272
237
  | `securenow run --watch <script>` | Same, with Node.js watch mode |
273
-
274
- Most users won't need this — just add `-r securenow/register` to your existing start script.
238
+ | `securenow run --firewall-only <script>` | Preload the firewall only, skip OTel |
275
239
 
276
240
  ### Authentication
277
241
 
278
242
  | Command | Description |
279
- |---------|-------------|
280
- | `securenow login` | Log in via browser (opens OAuth flow) |
281
- | `securenow login --token <TOKEN>` | Log in with a token (for CI/headless) |
282
- | `securenow login --local` | Log in and save credentials to the current project only |
283
- | `securenow logout` | Clear stored credentials |
284
- | `securenow logout --local` | Clear project-local credentials only |
285
- | `securenow whoami` | Show current session info (including auth source) |
243
+ |---|---|
244
+ | `securenow login` | Browser auth + pick app (writes ./.securenow/ by default) |
245
+ | `securenow login --global` | Save to ~/.securenow/ instead |
246
+ | `securenow login --token <TOKEN>` | Headless (CI/servers) |
247
+ | `securenow logout` | Clear project-local credentials |
248
+ | `securenow logout --global` | Clear ~/.securenow/ instead |
249
+ | `securenow whoami` | Show current session (email, app, expiry) |
286
250
 
287
251
  ### Applications
288
252
 
289
253
  | Command | Description |
290
- |---------|-------------|
291
- | `securenow apps` | List all applications |
292
- | `securenow apps create <name>` | Create app and get the app key |
293
- | `securenow apps info <id>` | Show application details |
294
- | `securenow apps delete <id>` | Delete an application |
295
- | `securenow apps default <key>` | Set default app for all commands |
254
+ |---|---|
255
+ | `securenow apps` | List all apps for your account |
256
+ | `securenow apps create <name>` | Create an app |
257
+ | `securenow apps info <id>` | Show app details |
258
+ | `securenow apps delete <id>` | Delete an app |
259
+ | `securenow apps default <key>` | Switch which app this project uses (updates `.securenow/`) |
296
260
 
297
261
  ### Observability
298
262
 
299
263
  | Command | Description |
300
- |---------|-------------|
301
- | `securenow traces --app <key>` | List recent traces |
302
- | `securenow traces show <traceId>` | Show trace spans |
303
- | `securenow traces analyze <traceId>` | AI security analysis of a trace |
304
- | `securenow logs --app <key>` | View logs (with `--minutes`, `--level`) |
305
- | `securenow logs trace <traceId>` | View logs for a specific trace |
306
- | `securenow analytics` | Response code analytics overview |
307
- | `securenow status` | Full dashboard summary |
264
+ |---|---|
265
+ | `securenow traces` | Recent traces |
266
+ | `securenow traces show <traceId>` | Trace spans |
267
+ | `securenow traces analyze <traceId>` | AI security analysis |
268
+ | `securenow logs` | View logs (`--minutes`, `--level`) |
269
+ | `securenow logs trace <traceId>` | Logs for a trace |
270
+ | `securenow analytics` | Response code analytics |
271
+ | `securenow status` | Dashboard summary |
308
272
 
309
273
  ### Detect & Respond
310
274
 
311
275
  | Command | Description |
312
- |---------|-------------|
276
+ |---|---|
313
277
  | `securenow notifications` | List notifications |
314
- | `securenow notifications unread` | Show unread count |
315
- | `securenow notifications read <id>` | Mark notification as read |
316
- | `securenow notifications read-all` | Mark all as read |
317
- | `securenow alerts rules` | List alert rules (status, applications, schedule) |
318
- | `securenow alerts rules show <id>` | Show one rule (includes all-apps vs explicit apps) |
319
- | `securenow alerts rules update <id> --applications-all` | Set rule to all current & future apps |
320
- | `securenow alerts rules update <id> --apps k1,k2` | Scope rule to specific app keys |
321
- | `securenow alerts channels` | List alert channels |
322
- | `securenow alerts history` | View alert history |
278
+ | `securenow notifications unread` | Unread count |
279
+ | `securenow alerts rules` | List alert rules |
280
+ | `securenow alerts history` | Alert history |
323
281
 
324
282
  ### Investigate
325
283
 
326
284
  | Command | Description |
327
- |---------|-------------|
328
- | `securenow ip <address>` | IP intelligence lookup (geo, abuse score, verdict) |
329
- | `securenow ip traces <address>` | Show traces originating from an IP |
330
- | `securenow forensics "<query>"` | Natural language forensic query (NL to SQL) |
331
- | `securenow forensics library` | View saved query library |
332
- | `securenow api-map` | View discovered API endpoints |
333
- | `securenow api-map stats` | API map statistics |
285
+ |---|---|
286
+ | `securenow ip <address>` | IP intel (geo, abuse, verdict) |
287
+ | `securenow ip traces <address>` | Traces from an IP |
288
+ | `securenow forensics "<query>"` | Natural language forensic query |
289
+ | `securenow api-map` | Discovered API endpoints |
334
290
 
335
291
  ### Firewall
336
292
 
337
293
  | Command | Description |
338
- |---------|-------------|
339
- | `securenow firewall status` | Show firewall status, active layers, and API key info |
340
- | `securenow firewall test-ip <ip>` | Check if an IP would be blocked by the current blocklist |
341
- | `securenow run --firewall-only <script>` | Run a Node.js app with the firewall preloaded but **no** OTel tracing overhead |
294
+ |---|---|
295
+ | `securenow firewall status` | Firewall layers + key info |
296
+ | `securenow firewall test-ip <ip>` | Would this IP be blocked? |
342
297
 
343
298
  ### Remediation
344
299
 
345
300
  | Command | Description |
346
- |---------|-------------|
301
+ |---|---|
347
302
  | `securenow blocklist` | List blocked IPs |
348
- | `securenow blocklist add <ip>` | Block an IP (`--reason <reason>`) |
349
- | `securenow blocklist remove <id>` | Remove from blocklist |
350
- | `securenow blocklist stats` | Blocklist statistics |
351
- | `securenow allowlist` | List allowed IPs (restrict-mode) |
352
- | `securenow allowlist add <ip>` | Allow an IP (`--label`, `--reason`) |
353
- | `securenow allowlist remove <id>` | Remove from allowlist |
354
- | `securenow trusted` | List trusted IPs |
355
- | `securenow trusted add <ip>` | Add trusted IP (`--label <label>`) |
356
- | `securenow trusted remove <id>` | Remove trusted IP |
357
-
358
- ### False-Positive Management
303
+ | `securenow blocklist add <ip> [--reason ...]` | Block an IP |
304
+ | `securenow allowlist add <ip>` | Allow an IP (restrict-mode) |
305
+ | `securenow trusted add <ip>` | Mark an IP as trusted |
359
306
 
360
- Full false-positive triage without leaving the terminal — mirrors the web dashboard one-for-one.
307
+ ### False positives
361
308
 
362
309
  | Command | Description |
363
- |---------|-------------|
364
- | `securenow fp` / `securenow fp list` | List all exclusion rules |
365
- | `securenow fp show <id>` | Show rule details (conditions, scope, match mode) |
366
- | `securenow fp create --conditions '[...]'` | Create a raw exclusion rule |
367
- | `securenow fp create --path /api/events --method POST --path-safe standard --ua-safe standard --reason "..."` | Create with safe-value presets |
368
- | `securenow fp edit <id> [--active true\|false] [--conditions '[...]']` | Edit an existing rule |
369
- | `securenow fp delete <id> [--yes]` | Delete a rule |
370
- | `securenow fp test-body '<json>' --conditions '[...]'` | Test conditions against a request body |
371
- | `securenow fp dry-run --conditions '[...]'` | Dry-run against the last 3 days of live traces |
372
- | `securenow fp ai-fill --description "Stripe webhook POST to /api/stripe/webhook"` | AI-generate exclusion conditions |
373
- | `securenow fp mark <notification-id> <ip>` | Mark an IP as false positive on a specific notification |
374
-
375
- ### Telemetry
376
-
377
- Emit OTLP logs and spans from the shell — for cron jobs, CI pipelines, and scripts. No SDK boot required.
310
+ |---|---|
311
+ | `securenow fp` | List exclusion rules |
312
+ | `securenow fp ai-fill --description "..."` | AI-generate exclusion conditions |
313
+ | `securenow fp mark <notif-id> <ip>` | Mark an alert as a false positive |
314
+ | `securenow fp dry-run --conditions '[...]'` | Test against last 3 days of traces |
378
315
 
379
- | Command | Description |
380
- |---------|-------------|
381
- | `securenow log send "<message>" [--level info\|warn\|error] [--attrs k=v,k=v]` | Send a single log record via OTLP/HTTP |
382
- | `securenow test-span [<name>]` | Emit a test span to verify collector connectivity |
383
-
384
- ### Utilities
385
-
386
- SDK helpers surfaced as CLI commands — debug redaction, test CIDR matching, inspect config without writing Node.
316
+ ### Telemetry from the shell
387
317
 
388
318
  | Command | Description |
389
- |---------|-------------|
390
- | `securenow redact '<json>' [--fields f1,f2]` | Redact sensitive fields (also accepts `@file.json`) |
391
- | `securenow cidr match <ip> <cidr1,cidr2>` | Check if an IP matches a CIDR list (exit `0` hit / `2` miss) |
392
- | `securenow cidr parse <cidr>` | Parse a CIDR — print network, broadcast, mask, size |
393
- | `securenow env [--json]` | Show resolved config (service name, endpoints, env vars) |
394
- | `securenow doctor [--json]` | End-to-end diagnostic: probe OTLP + API, check config |
319
+ |---|---|
320
+ | `securenow log send "<msg>" [--level info\|warn\|error]` | Emit a log record via OTLP |
321
+ | `securenow test-span` | Send a test span |
395
322
 
396
- ### Settings
323
+ ### Diagnostics & utilities
397
324
 
398
325
  | Command | Description |
399
- |---------|-------------|
400
- | `securenow instances` | List ClickHouse instances |
401
- | `securenow instances test <id>` | Test instance connection |
402
- | `securenow config get` | Show all config values |
403
- | `securenow config set <key> <value>` | Set a config value |
404
- | `securenow config path` | Show config file locations |
405
- | `securenow init [--key <KEY>]` | Auto-scaffold instrumentation for your framework |
406
- | `securenow version` | Show CLI version |
407
-
408
- ### Global Flags
326
+ |---|---|
327
+ | `securenow doctor` | Probe OTLP + API, check config |
328
+ | `securenow env` | Show resolved config |
329
+ | `securenow redact '<json>'` | Preview redaction |
330
+ | `securenow cidr match <ip> <cidr>` | Test CIDR match (exit 0/2) |
409
331
 
410
- | Flag | Description |
411
- |------|-------------|
412
- | `--json` | Output as JSON (works on every command) |
413
- | `--help` | Show help for any command |
414
- | `--app <key>` | Specify app key (or set default with `config set defaultApp`) |
415
- | `--local` | Save/clear credentials per-project (login/logout only) |
332
+ ### Global flags
416
333
 
417
- ### Configuration
334
+ | Flag | Effect |
335
+ |---|---|
336
+ | `--json` | Machine-readable output |
337
+ | `--help` | Help for any command |
338
+ | `--app <key>` | Override which app |
339
+ | `--global` | Global credentials scope (login/logout) |
418
340
 
419
- Credentials and settings are stored in `~/.securenow/` (global) or `.securenow/` (per-project):
341
+ ### Where things live
420
342
 
421
343
  | File | Purpose |
422
- |------|---------|
344
+ |---|---|
345
+ | `./.securenow/credentials.json` | Project-local token + app (default) |
346
+ | `~/.securenow/credentials.json` | Global (with `login --global`) |
423
347
  | `~/.securenow/config.json` | API URL, default app, preferences |
424
- | `~/.securenow/credentials.json` | Auth token — global (restricted permissions) |
425
- | `.securenow/credentials.json` | Auth token — project-local (use `login --local`) |
426
348
 
427
- **Credential resolution order:** `SECURENOW_TOKEN` env var → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`.
349
+ Resolution order: `SECURENOW_TOKEN` env → project `.securenow/` → global `~/.securenow/`.
428
350
 
429
- Override the API URL with `securenow config set apiUrl <url>` or the `SECURENOW_API_URL` environment variable.
351
+ Override the API with `securenow config set apiUrl <url>` or `SECURENOW_API_URL`.
430
352
 
431
353
  ---
432
354
 
433
355
  ## Support
434
356
 
435
357
  - **Website:** [securenow.ai](http://securenow.ai/)
436
- - **Issues:** Report bugs and request features
437
- - **Documentation:** Full documentation and guides
358
+ - **Docs:** see `docs/` folder
359
+ - **Issues:** report bugs and requests on GitHub
438
360
 
439
361
  ---
440
362
 
441
363
  ## License
442
364
 
443
- ISC
365
+ ISC
package/SKILL-CLI.md CHANGED
@@ -18,13 +18,17 @@ npx securenow <command>
18
18
  ### Authenticate
19
19
 
20
20
  ```bash
21
- securenow login # opens browser OAuth; stores JWT in ~/.securenow/credentials.json
21
+ securenow login # opens browser OAuth + app picker; writes ./.securenow/credentials.json (project-local by default)
22
+ securenow login --global # save to ~/.securenow/ instead (shared across projects)
22
23
  securenow login --token <JWT> # headless / CI login (get token from dashboard Settings)
23
- securenow login --local # save credentials to this project only (.securenow/)
24
- securenow whoami # verify session (shows auth source)
24
+ securenow whoami # verify session (shows email, app, auth source)
25
25
  ```
26
26
 
27
- **Per-project credentials:** Use `--local` to keep separate logins in different project directories on the same machine. Credentials resolve in order: `SECURENOW_TOKEN` env var → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`.
27
+ **Zero-config flow (v7+):** the browser step lets the user pick (or create) an app. The CLI stores the app's **key (UUID)**, **name**, and **instance URL** in `.securenow/credentials.json`. The SDK reads this file at boot and sends traces/logs to the right app bucket — **no env vars required for local dev**.
28
+
29
+ Credentials resolve in order: `SECURENOW_TOKEN` env var → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`.
30
+
31
+ For CI / Docker / production, set env vars directly (always win over the file): `SECURENOW_APPID=<uuid>`, `SECURENOW_INSTANCE=<url>`, `SECURENOW_API_KEY=<uuid>`.
28
32
 
29
33
  ### Integrate With Your App
30
34
 
package/cli/apps.js CHANGED
@@ -64,17 +64,10 @@ async function list(args, flags) {
64
64
  ui.table(['Name', 'Key', 'Instance', 'Created'], rows);
65
65
  console.log('');
66
66
 
67
- if (apps.length > 0) {
68
- console.log(` ${ui.c.bold('Add to your .env:')}`);
69
- const first = apps.find(a => a.key === defaultApp) || apps[0];
70
- const firstInst = first.instanceId ? instMap[first.instanceId] : null;
71
- console.log(` SECURENOW_APPID=${first.key}`);
72
- console.log(` SECURENOW_INSTANCE=${instanceUrl(firstInst)}`);
73
- console.log('');
74
- }
75
-
76
67
  if (!defaultApp && apps.length > 0) {
77
- ui.info(`Tip: Set a default app with ${ui.c.bold('securenow config set defaultApp <key>')}`);
68
+ console.log(` ${ui.c.bold('Use one of these apps in the current project:')}`);
69
+ console.log(` ${ui.c.bold('securenow apps default <key>')}`);
70
+ console.log(` ${ui.c.dim('(or run `securenow login` to pick interactively)')}`);
78
71
  console.log('');
79
72
  }
80
73
  } catch (err) {
@@ -133,12 +126,9 @@ async function create(args, flags) {
133
126
  ]);
134
127
 
135
128
  console.log('');
136
- console.log(` ${ui.c.bold('Add to your .env.local:')}`);
137
- console.log('');
138
- console.log(` SECURENOW_APPID=${app.key}`);
139
- console.log(` SECURENOW_INSTANCE=${envUrl}`);
140
- console.log('');
141
- ui.info(`Set as default: ${ui.c.bold(`securenow config set defaultApp ${app.key}`)}`);
129
+ console.log(` ${ui.c.bold('Use this app in the current project:')}`);
130
+ console.log(` ${ui.c.bold(`securenow apps default ${app.key}`)}`);
131
+ console.log(` ${ui.c.dim('(writes .securenow/credentials.json — no env var needed)')}`);
142
132
  console.log('');
143
133
 
144
134
  if (flags.json) {
@@ -251,9 +241,8 @@ async function info(args, flags) {
251
241
  ]);
252
242
 
253
243
  console.log('');
254
- console.log(` ${ui.c.bold('Environment variables:')}`);
255
- console.log(` SECURENOW_APPID=${app.key}`);
256
- console.log(` SECURENOW_INSTANCE=${envUrl}`);
244
+ console.log(` ${ui.c.bold('Use in current project:')} ${ui.c.bold(`securenow apps default ${app.key}`)}`);
245
+ console.log(` ${ui.c.bold('Or override via env:')} ${ui.c.dim(`SECURENOW_APPID=${app.key} SECURENOW_INSTANCE=${envUrl}`)}`);
257
246
  console.log('');
258
247
  } catch (err) {
259
248
  s.fail('Failed to fetch application');
package/docs/ALL-FRAMEWORKS-QUICKSTART.md CHANGED
@@ -2,6 +2,14 @@
2
2
 
3
3
  Protect any Node.js app in minutes. This guide covers **installation, CLI commands, the forensics chat, and IP blocking** for all 11 supported frameworks.
4
4
 
5
+ > **v7+ — zero-config shortcut.** For local dev, the short version is:
6
+ > ```bash
7
+ > npm install securenow
8
+ > npx securenow login # pick/create app in the browser
9
+ > node -r securenow/register app.js
10
+ > ```
11
+ > No `.env` setup. Credentials live in `.securenow/credentials.json` (gitignored automatically). Skip "Step 2 — Set Environment Variables" below unless you're configuring CI / Docker / prod.
12
+
5
13
  ---
6
14
 
7
15
  ## Table of Contents
package/docs/ENVIRONMENT-VARIABLES.md CHANGED
@@ -2,32 +2,41 @@
2
2
 
3
3
  Complete reference for all environment variables supported by SecureNow.
4
4
 
5
+ > **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.
6
+
7
+ > **Resolution order** (first non-empty wins): env var → `./.securenow/credentials.json` → `~/.securenow/credentials.json` → `package.json#name` (label only) → default.
8
+
5
9
  ---
6
10
 
7
11
  ## Quick Reference Table
8
12
 
9
13
  | Variable | Type | Default | Description |
10
14
  |----------|------|---------|-------------|
11
- | **SECURENOW_APPID** | Required | - | Application identifier / service name |
12
- | **SECURENOW_INSTANCE** | Required | `https://freetrial.securenow.ai:4318` | OTLP collector base URL |
13
- | **SECURENOW_LOGGING_ENABLED** | Optional | `1` | Enable/disable logging |
14
- | **SECURENOW_NO_UUID** | Optional | `0` | Disable UUID suffix on service name |
15
- | **SECURENOW_STRICT** | Optional | `0` | Exit if APPID missing in cluster mode |
16
- | **SECURENOW_CAPTURE_BODY** | Optional | `0` | Enable request body capture |
15
+ | **SECURENOW_APPID** | Optional | from credentials file | App routing key (UUID). Sent as OTel `service.name`. |
16
+ | **SECURENOW_INSTANCE** | Optional | `https://freetrial.securenow.ai:4318` | OTLP collector base URL |
17
+ | **SECURENOW_API_KEY** | Optional | from credentials file | API key (same UUID as APPID). Enables firewall. |
18
+ | **SECURENOW_LOGGING_ENABLED** | Optional | `1` (on) | Forward `console.*` as OTLP logs. Set to `0` to disable. |
19
+ | **SECURENOW_CAPTURE_BODY** | Optional | `1` (on) | Capture request body. Set to `0` for Fastify/Hapi/Hono. |
20
+ | **SECURENOW_CAPTURE_MULTIPART** | Optional | `1` (on) | Capture multipart field/file metadata. |
17
21
  | **SECURENOW_MAX_BODY_SIZE** | Optional | `10240` | Max body size in bytes |
18
- | **SECURENOW_SENSITIVE_FIELDS** | Optional | - | Comma-separated list of fields to redact |
19
- | **SECURENOW_CAPTURE_MULTIPART** | Optional | `0` | Enable multipart/form-data streaming capture |
20
- | **SECURENOW_DISABLE_INSTRUMENTATIONS** | Optional | - | Comma-separated list of packages to disable |
21
- | **SECURENOW_TEST_SPAN** | Optional | `0` | Emit test span on startup |
22
- | **OTEL_SERVICE_NAME** | Optional | - | Alternative to SECURENOW_APPID |
22
+ | **SECURENOW_SENSITIVE_FIELDS** | Optional | - | Comma-separated extra fields to redact |
23
+ | **SECURENOW_NO_UUID** | Optional | `0` | Disable UUID suffix on `service.instance.id` |
24
+ | **SECURENOW_STRICT** | Optional | `0` | Exit if APPID missing in PM2 cluster mode |
25
+ | **SECURENOW_DISABLE_INSTRUMENTATIONS** | Optional | - | Comma-separated list of OTel instrumentations to disable |
26
+ | **SECURENOW_TEST_SPAN** | Optional | `0` | Emit a single test span on startup (prefer `npx securenow test-span`) |
27
+ | **SECURENOW_HIDE_BANNER** | Optional | `0` | Hide the free-trial banner |
28
+ | **SECURENOW_FIREWALL_ENABLED** | Optional | `1` (on when API key is set) | Firewall master switch |
29
+ | **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) |
30
+ | **OTEL_SERVICE_NAME** | Optional | - | Alternative to SECURENOW_APPID (label only, no routing) |
23
31
  | **OTEL_EXPORTER_OTLP_ENDPOINT** | Optional | - | Alternative to SECURENOW_INSTANCE |
24
- | **OTEL_EXPORTER_OTLP_HEADERS** | Optional | - | Headers for OTLP requests |
32
+ | **OTEL_EXPORTER_OTLP_HEADERS** | Optional | auto (`x-api-key` injected) | Additional OTLP headers |
25
33
  | **OTEL_EXPORTER_OTLP_TRACES_ENDPOINT** | Optional | - | Override traces endpoint |
26
34
  | **OTEL_EXPORTER_OTLP_LOGS_ENDPOINT** | Optional | - | Override logs endpoint |
27
- | **OTEL_LOG_LEVEL** | Optional | `none` | SDK log level |
35
+ | **OTEL_LOG_LEVEL** | Optional | `none` | SDK log verbosity (`debug`/`info`/`warn`/`error`) |
28
36
  | **NODE_ENV** | Optional | `production` | Environment name |
29
- | **SECURENOW_API_KEY** | Optional | - | API key for firewall (auto-activates when set) |
30
- | **SECURENOW_API_URL** | Optional | `https://api.securenow.ai` | API base URL |
37
+ | **SECURENOW_API_URL** | Optional | `https://api.securenow.ai` | Dashboard API base URL |
38
+ | **SECURENOW_APP_URL** | Optional | `https://app.securenow.ai` | Dashboard web base URL |
39
+ | **SECURENOW_TOKEN** | Optional | from credentials file | Auth token (overrides credentials file for CI) |
31
40
  | **SECURENOW_FIREWALL_ENABLED** | Optional | `1` | Firewall master kill-switch |
32
41
  | **SECURENOW_FIREWALL_SYNC_INTERVAL** | Optional | `60` | Blocklist refresh interval (seconds) |
33
42
  | **SECURENOW_FIREWALL_FAIL_MODE** | Optional | `open` | Behavior when API unreachable: open/closed |
package/docs/LOGGING-QUICKSTART.md CHANGED
@@ -1,36 +1,23 @@
1
- # SecureNow Logging - Quick Start
1
+ # SecureNow Logging — Quick Start
2
2
 
3
- Get logging set up in your Node.js app in under 2 minutes!
3
+ Get logging sent to your SecureNow dashboard in under 2 minutes.
4
4
 
5
- **Since v5.6.0:** When `SECURENOW_LOGGING_ENABLED=1` is set, all `console.log` / `warn` / `error` / `info` / `debug` calls are automatically forwarded as OTLP log records. You only need `require('securenow/register')`—a separate `console-instrumentation` preload is no longer required.
5
+ **Since v7.0.0:** Logging is **on by default**. `console.log` / `warn` / `error` / `info` / `debug` calls are automatically forwarded as OTLP log records. Disable with `SECURENOW_LOGGING_ENABLED=0` if you don't want it.
6
6
 
7
7
  ---
8
8
 
9
- ## 1. Install
9
+ ## 1. Install + login
10
10
 
11
11
  ```bash
12
12
  npm install securenow
13
+ npx securenow login # pick/create your app in the browser
13
14
  ```
14
15
 
15
- ---
16
-
17
- ## 2. Configure Environment
18
-
19
- Create `.env` file or export variables:
20
-
21
- ```bash
22
- SECURENOW_LOGGING_ENABLED=1
23
- SECURENOW_APPID=my-app
24
- SECURENOW_INSTANCE=http://your-otlp-backend:4318
25
-
26
- # For SecureNow / hosted OTLP (example):
27
- # SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
28
- # OTEL_EXPORTER_OTLP_HEADERS="x-api-key=<your-key>"
29
- ```
16
+ `login` writes `.securenow/credentials.json` locally. No `.env` setup required.
30
17
 
31
18
  ---
32
19
 
33
- ## 3. Add to Your App
20
+ ## 2. Add to Your App
34
21
 
35
22
  **Option A: Automatic Console Logging (Easiest)**
36
23
 
@@ -53,7 +40,7 @@ NODE_OPTIONS="-r securenow/register" node app.js
53
40
 
54
41
  ---
55
42
 
56
- ## 4. Run Your App
43
+ ## 3. Run Your App
57
44
 
58
45
  ```bash
59
46
  node app.js
@@ -70,12 +57,18 @@ You should see:
70
57
 
71
58
  ---
72
59
 
73
- ## 5. View Logs in SecureNow
60
+ ## 4. View Logs in SecureNow
74
61
 
75
62
  1. Open your SecureNow dashboard
76
63
  2. Go to **Logs** section
77
- 3. Filter by `service.name = my-app`
78
- 4. See all your logs with automatic trace correlation!
64
+ 3. Your logs appear under the app you picked during `securenow login`
65
+ 4. All logs come with automatic trace correlation
66
+
67
+ Or from the CLI:
68
+
69
+ ```bash
70
+ npx securenow logs --minutes 5
71
+ ```
79
72
 
80
73
  ---
81
74
 
@@ -102,20 +95,13 @@ app.listen(3000);
102
95
 
103
96
  ```typescript
104
97
  // instrumentation.ts (in project root)
105
- export async function register() {
106
- if (process.env.NEXT_RUNTIME === 'nodejs') {
107
- process.env.SECURENOW_LOGGING_ENABLED = '1';
108
- await import('securenow/register');
109
- }
98
+ import { registerSecureNow } from 'securenow/nextjs';
99
+ export function register() {
100
+ registerSecureNow();
110
101
  }
111
102
  ```
112
103
 
113
- ```bash
114
- # .env.local
115
- SECURENOW_LOGGING_ENABLED=1
116
- SECURENOW_APPID=my-nextjs-app
117
- SECURENOW_INSTANCE=http://localhost:4318
118
- ```
104
+ No `.env.local` needed — credentials come from `.securenow/credentials.json` after `npx securenow login`.
119
105
 
120
106
  ### Fastify
121
107
 
@@ -157,9 +143,10 @@ bootstrap();
157
143
 
158
144
  **Logs not appearing?**
159
145
 
160
- 1. Check `SECURENOW_LOGGING_ENABLED=1` is set
161
- 2. Verify your OTLP / SecureNow endpoint is correct
162
- 3. Enable debug: `OTEL_LOG_LEVEL=debug`
146
+ 1. Check `.securenow/credentials.json` exists (run `npx securenow whoami`).
147
+ 2. Confirm `SECURENOW_LOGGING_ENABLED` is not set to `0`.
148
+ 3. Run `npx securenow doctor` — it probes the full pipeline and reports the failure mode.
149
+ 4. Enable verbose output: `OTEL_LOG_LEVEL=debug`.
163
150
 
164
151
  **Console logs not forwarding?**
165
152
 
package/docs/NEXTJS-QUICKSTART.md CHANGED
@@ -1,67 +1,77 @@
1
- # Next.js + SecureNow Quick Start
1
+ # Next.js + SecureNow — 30 seconds
2
2
 
3
- ## Installation (30 seconds)
3
+ ## The whole setup
4
4
 
5
5
  ```bash
6
+ # 1. Install
6
7
  npm install securenow
7
- ```
8
-
9
- **🎉 The installer will automatically offer to create the instrumentation file!**
10
8
 
11
- Just answer "Y" when prompted, and it's done!
12
-
13
- ---
9
+ # 2. Pick (or create) your app in the browser — writes .securenow/ locally
10
+ npx securenow login
14
11
 
15
- ## Alternative: Manual Setup
12
+ # 3. Scaffold instrumentation.ts and wrap next.config.js
13
+ npx securenow init
16
14
 
17
- If you skipped auto-setup or want to do it manually:
15
+ # 4. Run
16
+ npm run dev
17
+ ```
18
18
 
19
- ### Option 1: Use CLI (Recommended)
19
+ No `.env.local` edits. No API key copy-paste. The app you picked in step 2 is where your traces land.
20
20
 
21
- ```bash
22
- npx securenow init
23
- ```
21
+ ---
24
22
 
25
- ### Option 2: Create File Manually
23
+ ## What `npx securenow init` generates
26
24
 
27
- Create `instrumentation.ts` at project root:
25
+ **`instrumentation.ts`** (or `.js`, auto-detected):
28
26
 
29
27
  ```typescript
30
28
  import { registerSecureNow } from 'securenow/nextjs';
31
- export function register() { registerSecureNow(); }
32
- ```
33
-
34
- ### 2. Create `.env.local`:
35
-
36
- ```bash
37
- SECURENOW_APPID=my-nextjs-app
38
- SECURENOW_INSTANCE=http://your-securenow:4318
29
+ export function register() {
30
+ registerSecureNow();
31
+ }
39
32
  ```
40
33
 
41
- ### 3. (Next.js 14 only) Update `next.config.js`:
34
+ It also tells you to wrap `next.config.js`:
42
35
 
43
36
  ```javascript
44
- module.exports = {
45
- experimental: { instrumentationHook: true }
46
- }
37
+ const { withSecureNow } = require('securenow/nextjs-webpack-config');
38
+
39
+ module.exports = withSecureNow({
40
+ // your existing config
41
+ });
47
42
  ```
48
43
 
49
- ## Run
44
+ `withSecureNow()` auto-detects Next.js 14 vs 15 vs 16 and sets the right externalization config.
50
45
 
51
- ```bash
52
- npm run dev
53
- ```
46
+ ---
54
47
 
55
48
  ## Verify
56
49
 
57
- Look for:
50
+ Start your app. In the console you should see:
51
+
58
52
  ```
59
- [securenow] ✅ OpenTelemetry started for Next.js
53
+ [securenow] Next.js integration loading (pid=…)
54
+ [securenow] ✅ OpenTelemetry started for Next.js → https://freetrial.securenow.ai:4318/v1/traces
60
55
  ```
61
56
 
62
- Open SecureNow → check for traces from `my-nextjs-app`
57
+ Then:
58
+
59
+ ```bash
60
+ npx securenow test-span # emit a test span
61
+ npx securenow traces # see it appear
62
+ ```
63
+
64
+ If `traces` shows your span under the app name you picked, you're done.
63
65
 
64
66
  ---
65
67
 
66
- **That's it!** See [NEXTJS-GUIDE.md](./NEXTJS-GUIDE.md) for advanced configuration.
68
+ ## Overriding for CI / Docker / Vercel
69
+
70
+ `.securenow/credentials.json` is for local dev. For anywhere you can't run `npx securenow login`, set env vars — they always win:
71
+
72
+ ```bash
73
+ SECURENOW_APPID=<app-key-uuid> # from: npx securenow apps
74
+ SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
75
+ ```
67
76
 
77
+ See [NEXTJS-GUIDE.md](./NEXTJS-GUIDE.md) for Vercel, standalone builds, and edge runtime details.
package/docs/NUXT-GUIDE.md CHANGED
@@ -2,12 +2,15 @@
2
2
 
3
3
  ## Quick Start (1 minute)
4
4
 
5
- ### 1. Install
5
+ ### 1. Install + login
6
6
 
7
7
  ```bash
8
8
  npm install securenow
9
+ npx securenow login # pick/create your app in the browser
9
10
  ```
10
11
 
12
+ `login` writes `.securenow/credentials.json` locally. No `.env` needed for local dev.
13
+
11
14
  ### 2. Add the module to `nuxt.config.ts`
12
15
 
13
16
  ```ts
@@ -16,16 +19,7 @@ export default defineNuxtConfig({
16
19
  });
17
20
  ```
18
21
 
19
- ### 3. Set environment variables
20
-
21
- Create a `.env` file in your project root:
22
-
23
- ```env
24
- SECURENOW_APPID=my-nuxt-app
25
- SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
26
- ```
27
-
28
- ### 4. Start your app
22
+ ### 3. Start your app
29
23
 
30
24
  ```bash
31
25
  nuxt dev
@@ -36,10 +30,20 @@ You should see in the console:
36
30
  ```
37
31
  [securenow] Nuxt module loaded — server plugin registered
38
32
  [securenow] 🚀 Nuxt OTel SDK started → https://freetrial.securenow.ai:4318/v1/traces
39
- [securenow] service.name=my-nuxt-app instance.id=my-nuxt-app-...
40
33
  ```
41
34
 
42
- That's it — all server-side requests are now traced.
35
+ That's it — all server-side requests are now traced, logs forwarded, and bodies captured. The app you picked during `login` is where they land.
36
+
37
+ ### 4. (Optional) Override for CI / Docker / prod
38
+
39
+ `.securenow/credentials.json` is for local dev. For environments where you can't run `npx securenow login`, set env vars:
40
+
41
+ ```env
42
+ SECURENOW_APPID=<app-key-uuid>
43
+ SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
44
+ ```
45
+
46
+ Env vars always take precedence.
43
47
 
44
48
  ---
45
49
 
package/examples/nextjs-env-example.txt CHANGED
@@ -1,34 +1,32 @@
1
- # SecureNow Configuration for Next.js
2
- # Place these in your .env.local file
3
-
4
- # Required: Your application identifier
5
- SECURENOW_APPID=my-nextjs-app
6
-
7
- # Optional: Your OTLP collector endpoint (SecureNow or any OTLP-compatible backend)
8
- # Default: https://freetrial.securenow.ai:4318
9
- SECURENOW_INSTANCE=http://your-otlp-collector:4318
10
-
11
- # Optional: API Key or authentication headers
12
- OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key-here"
13
-
14
- # Optional: Don't append UUID to service name (useful for dev)
15
- # SECURENOW_NO_UUID=1
16
-
17
- # Optional: Log level
18
- # OTEL_LOG_LEVEL=info
19
-
20
- # Optional: Disable specific instrumentations (comma-separated)
21
- # SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns
22
-
23
- # Optional: Create a test span on startup
24
- # SECURENOW_TEST_SPAN=1
25
-
26
- # Next.js will automatically use NODE_ENV
27
- # NODE_ENV=production
28
-
29
-
30
-
31
-
32
-
33
-
34
-
1
+ # SecureNow Configuration for Next.js
2
+ #
3
+ # ============================================================
4
+ # For local dev you do NOT need this file.
5
+ # Instead run:
6
+ # npx securenow login
7
+ # That writes .securenow/credentials.json and the SDK reads it.
8
+ # ============================================================
9
+ #
10
+ # This template is for CI / Docker / Vercel — places where you
11
+ # can't run the interactive login. Env vars always take
12
+ # precedence over .securenow/credentials.json.
13
+
14
+ # App routing key (UUID). From: npx securenow apps
15
+ SECURENOW_APPID=your-app-key-uuid
16
+
17
+ # OTLP collector endpoint. Default is the Free Trial.
18
+ SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
19
+
20
+ # Optional — defaults are already sensible. Flip to 0 to disable.
21
+ # SECURENOW_LOGGING_ENABLED=0 # forward console.* as OTLP logs
22
+ # SECURENOW_CAPTURE_BODY=0 # capture POST/PUT/PATCH JSON + form bodies
23
+ # SECURENOW_CAPTURE_MULTIPART=0 # capture multipart field / file metadata
24
+ # SECURENOW_MAX_BODY_SIZE=10240 # bytes (default 10KB)
25
+
26
+ # Optional — OTel tuning
27
+ # OTEL_LOG_LEVEL=info
28
+ # SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns
29
+ # SECURENOW_NO_UUID=1 # use bare APPID as service.name (no UUID suffix)
30
+
31
+ # Authentication (auto-set when SECURENOW_APPID is present)
32
+ # OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key-here"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "securenow",
3
- "version": "7.0.0-anas.2",
3
+ "version": "7.0.0-anas.3",
4
4
  "description": "OpenTelemetry instrumentation for Node.js, Next.js, and Nuxt - Send traces and logs to any OTLP-compatible backend",
5
5
  "type": "commonjs",
6
6
  "main": "register.js",
package/postinstall.js CHANGED
@@ -289,19 +289,11 @@ async function setup() {
289
289
  }
290
290
  }
291
291
 
292
- // Create .env.local if it doesn't exist
293
- const envPath = path.join(process.cwd(), '.env.local');
294
- if (!fs.existsSync(envPath)) {
295
- createEnvTemplate(envPath);
296
- console.log('✅ Created .env.local template');
297
- }
298
-
299
292
  console.log('\n┌─────────────────────────────────────────────────┐');
300
293
  console.log('│ 🚀 Next Steps: │');
301
294
  console.log('│ │');
302
- console.log('│ 1. Edit .env.local and set: │');
303
- console.log('│ SECURENOW_APPID=your-app-name │');
304
- console.log('│ SECURENOW_INSTANCE=http://your-otlp-backend:4318 │');
295
+ console.log('│ 1. Pick your app in the browser: │');
296
+ console.log('│ npx securenow login │');
305
297
  console.log('│ │');
306
298
  console.log('│ 2. Run your app: npm run dev │');
307
299
  console.log('│ │');
@@ -312,7 +304,7 @@ async function setup() {
312
304
  }
313
305
  console.log('│ 📚 Full guide: npm docs securenow │');
314
306
  console.log('└─────────────────────────────────────────────────┘\n');
315
-
307
+
316
308
  rl.close();
317
309
  });
318
310