securenow 7.0.0-anas.3 → 7.2.0

package/NPM_README.md

@@ -59,17 +59,25 @@ yarn add securenow
 
 ### 1. Automatic Setup (Recommended)
 
-Run the init command after installing:
+Run login — it's a browser flow that picks an app and, since v7.1.0, also offers one-click firewall onboarding:
 
 ```bash
-npx securenow init --key snk_live_abc123...
+npx securenow login
+```
+
+During the browser step you can choose **Enable the Firewall?** — if you accept, the dashboard mints an API key (scoped `firewall:read + blocklist:read + allowlist:read`) and the CLI writes it into `.securenow/credentials.json`. No env vars, no copy-pasting keys.
+
+For framework scaffolding (Next.js `instrumentation.ts`, etc.) use:
+
+```bash
+npx securenow init --key snk_live_abc123...   # --key is optional now that login handles it
 ```
 
 This detects your framework and:
 - **Next.js**: Creates `instrumentation.ts`, suggests `withSecureNow()` for `next.config.js`
 - **Nuxt 3**: Suggests adding `securenow/nuxt` to modules
 - **Express / Node.js**: Shows how to add `-r securenow/register` to your start script
-- **All**: Writes `SECURENOW_API_KEY` to `.env.local` when `--key` is provided
+- **All**: Writes `SECURENOW_API_KEY` to `.env.local` when `--key` is provided (not needed if `login` already wrote it to `.securenow/credentials.json`)
 
 ### 2. Manual Setup
 
@@ -144,7 +152,10 @@ The `securenow` CLI gives you full access to the SecureNow platform from the ter
 ### Getting Started
 
 ```bash
-# Log in (opens browser for OAuth)
+# Log in (opens browser for OAuth + app picker)
+# Since v7.1.0 the browser flow also offers one-click firewall onboarding —
+# accept "Enable the Firewall?" to have the CLI mint and store the API key
+# in .securenow/credentials.json automatically (no env var needed).
 npx securenow login
 
 # Or use a token for CI/headless environments
@@ -155,6 +166,11 @@ npx securenow login --local
 
 # Check who you're logged in as (shows auth source)
 npx securenow whoami
+
+# Already have a firewall key? Store it without re-running login:
+npx securenow api-key set snk_live_abc123...   # --global for ~/.securenow/
+npx securenow api-key show                     # masked key + source
+npx securenow api-key clear                    # remove just the key
 ```
 
 ### Project Setup
@@ -461,6 +477,9 @@ npx securenow logs --json --level error | jq '.logs'
 | | `apps info <id>` | Application details |
 | | `apps delete <id>` | Delete application |
 | | `apps default <key>` | Set default app |
+| **API Key** | `api-key set <snk_live_...> [--global]` | Save firewall key to `.securenow/credentials.json` |
+| | `api-key show` | Show masked key + source |
+| | `api-key clear [--global]` | Remove stored key (leaves session/app) |
 | **Observe** | `traces` | List traces |
 | | `traces show <id>` | Trace details |
 | | `traces analyze <id>` | AI trace analysis |
@@ -1076,16 +1095,28 @@ The Nuxt server plugin (v5.13.0+) initializes the firewall independently from Op
 
 ## Firewall -- Automatic IP Blocking
 
-SecureNow can automatically block IPs from your blocklist at the application layer. No code changes -- just set an API key and the firewall activates.
+SecureNow can automatically block IPs from your blocklist at the application layer. No code changes -- just provide an API key (via `securenow login`, the `api-key` CLI, or env var) and the firewall activates.
 
 ### Enable the Firewall
 
+Pick whichever fits your environment:
+
 ```bash
-# Add to your .env
+# (a) Zero-config (v7.1+): login + opt in to the firewall in the browser.
+# Key is minted and written to .securenow/credentials.json automatically.
+npx securenow login
+
+# (b) Already have a key? Write it to the creds file directly:
+npx securenow api-key set snk_live_abc123...
+
+# (c) Old-school env var (still works; preferred for CI/Docker/prod):
+# .env
 SECURENOW_API_KEY=snk_live_abc123...
 ```
 
-That's it. On startup, you'll see:
+The SDK resolves the firewall key in this order: `SECURENOW_API_KEY` env var (only if it starts with `snk_live_`) → project `./.securenow/credentials.json` → global `~/.securenow/credentials.json`.
+
+On startup, you'll see:
 
 ```
 [securenow] Firewall: ENABLED
@@ -1231,7 +1262,7 @@ See the [Firewall Guide](./docs/FIREWALL-GUIDE.md) for the full reference.
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `SECURENOW_API_KEY` | API key with `firewall:read` scope. Enables the firewall when set. | - |
+| `SECURENOW_API_KEY` | API key with `firewall:read` scope. Enables the firewall when set. Since v7.1.0 the firewall also reads this from `.securenow/credentials.json` (written by `securenow login` or `securenow api-key set`); env var only wins if it starts with `snk_live_`. | from creds file |
 | `SECURENOW_API_URL` | SecureNow API base URL. Auto-detected for co-located deployments (falls back to `http://localhost:4000` on ECONNREFUSED). | `https://api.securenow.ai` |
 | `SECURENOW_FIREWALL_ENABLED` | Master kill-switch. Set to `0` to disable. | `1` |
 | `SECURENOW_FIREWALL_VERSION_INTERVAL` | Seconds between version checks (lightweight ETag-based). | `10` |

package/README.md

@@ -12,7 +12,9 @@ Zero-config OpenTelemetry for Node.js, Next.js, and Nuxt — traces, logs, body
 # 1. Install
 npm install securenow
 
-# 2. Pick (or create) your app in the browser — writes .securenow/ locally
+# 2. Pick (or create) your app in the browser — writes .securenow/ locally.
+#    Since v7.1.0, the browser step also offers one-click firewall onboarding:
+#    say yes and the CLI stores a scoped API key in the same file — no env vars.
 npx securenow login
 
 # 3. Start your app — one flag is all it takes
@@ -135,10 +137,11 @@ Resolution order (first non-empty wins):
 
 ```bash
 # Setup
-npx securenow login                 # browser auth + app picker (saves to ./.securenow/)
+npx securenow login                 # browser auth + app picker + firewall onboarding (saves to ./.securenow/)
 npx securenow login --global        # save to ~/.securenow/ instead
 npx securenow login --token <TOKEN> # headless (CI)
 npx securenow init                  # scaffold Next.js instrumentation files
+npx securenow api-key set snk_live_... # store firewall key in .securenow/credentials.json
 
 # Apps
 npx securenow apps                  # list all apps
@@ -241,12 +244,15 @@ After install, the `securenow` CLI is available via `npx securenow` or globally
 
 | Command | Description |
 |---|---|
-| `securenow login` | Browser auth + pick app (writes ./.securenow/ by default) |
+| `securenow login` | Browser auth + pick app + optional firewall key onboarding (writes ./.securenow/ by default) |
 | `securenow login --global` | Save to ~/.securenow/ instead |
 | `securenow login --token <TOKEN>` | Headless (CI/servers) |
 | `securenow logout` | Clear project-local credentials |
 | `securenow logout --global` | Clear ~/.securenow/ instead |
 | `securenow whoami` | Show current session (email, app, expiry) |
+| `securenow api-key set <snk_live_...>` | Store firewall key in `.securenow/credentials.json` (`--global` for `~/.securenow/`) |
+| `securenow api-key show` | Print masked key + source file |
+| `securenow api-key clear` | Remove stored key (`--global` for `~/.securenow/`) |
 
 ### Applications
 

package/SKILL-API.md

@@ -48,12 +48,16 @@ That's it. Traces and logs flow to your OTLP collector. No code changes for Expr
 
 ### 3. Enable the Firewall (Optional)
 
-Add one more env var to auto-activate IP blocking:
+Since v7.1.0 the firewall key lives in your credentials file — no env var required:
 
 ```bash
-SECURENOW_API_KEY=snk_live_abc123...
+npx securenow login              # pick app + click "Enable firewall" in browser
+# or, if you already have one:
+npx securenow api-key set snk_live_abc123...
 ```
 
+Both paths write the key to `.securenow/credentials.json` (auto-gitignored) and the firewall activates on next start. Setting `SECURENOW_API_KEY=snk_live_...` in the environment still works and takes precedence.
+
 The firewall syncs your blocklist and enforces it on every request — zero code changes.
 
 ---
@@ -259,7 +263,7 @@ Instruments document load, fetch, XMLHttpRequest, and user interactions with bro
 
 ## Firewall — Multi-Layer IP Blocking
 
-The firewall auto-activates when `SECURENOW_API_KEY` is set. It syncs your blocklist from the SecureNow API and enforces it across up to four layers:
+The firewall auto-activates once an API key is resolvable. Since **v7.1.0** the key is read from `.securenow/credentials.json` (written by `npx securenow login` or `securenow api-key set`), so the `SECURENOW_API_KEY` env var is optional. Resolution order: env (must start with `snk_live_`) → project `./.securenow/credentials.json` → global `~/.securenow/credentials.json`.
 
 ```
 Layer 4: Cloud/Edge WAF    →  blocked at CDN (Cloudflare, AWS WAF, GCP Cloud Armor)
@@ -271,11 +275,16 @@ Layer 1: HTTP Handler      →  403 JSON response (always active)
 ### Activate
 
 ```bash
-# .env
-SECURENOW_API_KEY=snk_live_abc123...     # auto-activates Layer 1
+# Zero-config (recommended) — writes the key to .securenow/credentials.json
+npx securenow login              # pick app + click "Enable firewall"
+# or, if you already have a key:
+npx securenow api-key set snk_live_abc123...
+
+# Optional .env overrides for the stronger layers
 SECURENOW_FIREWALL_TCP=1                  # opt-in Layer 2
 SECURENOW_FIREWALL_IPTABLES=1             # opt-in Layer 3 (Linux, needs root)
 SECURENOW_FIREWALL_CLOUD=cloudflare       # opt-in Layer 4
+# SECURENOW_API_KEY=snk_live_...          # still honored; only wins if it starts with snk_live_
 ```
 
 ### Firewall-Only Mode (No Tracing Overhead)
@@ -483,7 +492,7 @@ securenow redact @request.json --fields internal_id,sessionHash
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `SECURENOW_API_KEY` | API key (`snk_live_...`); activates firewall when set | — |
+| `SECURENOW_API_KEY` | API key (`snk_live_...`); activates firewall when set. Since v7.1.0, this is also read from `.securenow/credentials.json` — env var only wins when it starts with `snk_live_`. | — |
 | `SECURENOW_API_URL` | SecureNow API base URL | `https://api.securenow.ai` |
 | `SECURENOW_FIREWALL_ENABLED` | Master kill-switch (`0` to disable) | `1` |
 | `SECURENOW_FIREWALL_VERSION_INTERVAL` | Seconds between lightweight version checks | `10` |
@@ -542,16 +551,16 @@ No code changes to the application needed.
 
 ```bash
 npm install securenow
-npx securenow init --key snk_live_abc123...
+npx securenow login              # pick app + "Enable firewall" in browser
 ```
 
-The `init` command creates `instrumentation.ts` and suggests `next.config` changes. Then set env vars in `.env.local`:
+`securenow login` writes session, app, and firewall key to `.securenow/credentials.json` (auto-gitignored). The `init` command still works for manual setup — it creates `instrumentation.ts` and suggests `next.config` changes. Most users only need this `.env.local`:
 
 ```
 SECURENOW_APPID=my-nextjs-app
 SECURENOW_INSTANCE=https://your-collector:4318
-SECURENOW_API_KEY=snk_live_abc123...
 SECURENOW_CAPTURE_BODY=1
+# SECURENOW_API_KEY=snk_live_...   (otherwise lives in .securenow/credentials.json)
 ```
 
 ### Enable Firewall With Zero Tracing Overhead
@@ -562,7 +571,7 @@ For apps that only need IP blocking:
 node -r securenow/firewall-only app.js
 ```
 
-Set `SECURENOW_API_KEY` in the environment. No other configuration needed.
+Make sure an API key is resolvable — either run `npx securenow login` / `securenow api-key set snk_live_...` (writes the creds file), or set `SECURENOW_API_KEY` in the environment. No other configuration needed.
 
 ### Production Hardened Configuration
 

package/SKILL-CLI.md

@@ -26,9 +26,13 @@ securenow whoami            # verify session (shows email, app, auth source)
 
 **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**.
 
+**Firewall onboarding (v7.1+):** after picking the app, `securenow login` asks "Enable the Firewall?" in the browser. If you accept, the dashboard mints an API key with `firewall:read + blocklist:read + allowlist:read` scopes and the CLI writes it into `.securenow/credentials.json` automatically — no `SECURENOW_API_KEY` env var needed. To add or rotate a key later without re-running login, use `securenow api-key set snk_live_...` (see [API Key Management](#api-key-management) below).
+
 Credentials resolve in order: `SECURENOW_TOKEN` env var → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`.
 
-For CI / Docker / production, set env vars directly (always win over the file): `SECURENOW_APPID=<uuid>`, `SECURENOW_INSTANCE=<url>`, `SECURENOW_API_KEY=<uuid>`.
+The **firewall API key** resolves in a slightly different order: `SECURENOW_API_KEY` env var (only if it starts with `snk_live_`) → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`. An env var that isn't the `snk_live_` format is ignored, so the file can still win.
+
+For CI / Docker / production, set env vars directly (always win over the file): `SECURENOW_APPID=<uuid>`, `SECURENOW_INSTANCE=<url>`, `SECURENOW_API_KEY=snk_live_<...>`.
 
 ### Integrate With Your App
 
@@ -66,6 +70,8 @@ Config lives in `~/.securenow/` (global) and optionally `.securenow/` (per-proje
 
 **Credential resolution order:** `SECURENOW_TOKEN` env var → `.securenow/credentials.json` (project) → `~/.securenow/credentials.json` (global).
 
+**Firewall API key resolution (v7.1+):** `SECURENOW_API_KEY` env var (only honored if it starts with `snk_live_`) → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`. Use `securenow api-key set` to write the key to the credentials file without touching env vars.
+
 ```bash
 securenow config set apiUrl https://api.securenow.ai
 securenow config set defaultApp my-app-key
@@ -128,6 +134,20 @@ securenow apps discover [appId] [--domain example.com]  # discover subdomains, a
 securenow apps scan [--yes]                  # scan all app domains for new subdomains
 ```
 
+### API Key Management
+
+Manage the firewall API key stored in the credentials file. Since v7.1.0 the firewall reads `snk_live_...` keys from `.securenow/credentials.json` so no env var is required.
+
+```bash
+securenow api-key set snk_live_xxxxxxxxxx    # save to project ./.securenow/ (default)
+securenow api-key set snk_live_xxx --global  # save to ~/.securenow/ instead
+securenow api-key show                       # print the masked current key + its source
+securenow api-key clear                      # remove just the API key (keeps session/app)
+securenow api-key clear --global             # same, but from the global file
+```
+
+The key must start with `snk_live_`. `securenow login` with firewall enabled writes the key automatically; use `api-key set` when you already have a key from the dashboard, or to rotate it later.
+
 ### Init — Project Setup
 
 ```bash
@@ -225,6 +245,8 @@ securenow firewall status                    # layers, sync time, blocked count,
 securenow firewall test-ip <ip>              # check if IP would be blocked
 ```
 
+**Zero-config setup (v7.1+):** running `securenow login` and opting into "Enable the Firewall?" in the browser auto-mints an API key (scoped `firewall:read + blocklist:read + allowlist:read`) and writes it to the credentials file. No `SECURENOW_API_KEY` env var needed. If the user already has a key, `securenow api-key set snk_live_...` achieves the same thing. See [the landing firewall page](https://securenow.ai/firewall) for an overview.
+
 ### Blocklist — Block Malicious IPs
 
 ```bash

package/app-config.js

@@ -14,6 +14,10 @@
  *   - What human label to show?     (resolveAppName) — display only, never
  *                                     sent to the collector.
  *   - Which OTLP collector to hit?  (resolveInstance)
+ *   - Which firewall API key?       (resolveApiKey) — the snk_live_... key the
+ *                                     firewall sends as Bearer to /api/firewall
+ *                                     for blocklist sync. Separate from the
+ *                                     app routing key: this one is user-scoped.
  *
  * Resolution order (first non-empty wins):
  *
@@ -25,7 +29,7 @@
  *   5. Hard default / null
  *
  * Credentials file schema:
- *   { token, email, expiresAt, app: { key: <uuid>, name: <display>, instance } }
+ *   { token, email, expiresAt, apiKey: <snk_live_...>, app: { key, name, instance } }
  */
 
 const fs = require('fs');
@@ -112,6 +116,21 @@ function resolveAppId() {
   return resolveAppKey() || resolveAppName();
 }
 
+// Firewall / user-scoped API key (snk_live_...).
+// Distinct from resolveAppKey: that one is the application UUID for OTel
+// routing. This one authenticates the firewall blocklist sync to /api/firewall,
+// so it must look like a real `snk_live_` key — the app UUID won't pass auth.
+function resolveApiKey() {
+  const fromEnv = pick(process.env.SECURENOW_API_KEY);
+  if (fromEnv && fromEnv.startsWith('snk_live_')) return fromEnv;
+
+  const creds = loadCredentials();
+  const fromCreds = creds && pick(creds.apiKey);
+  if (fromCreds && fromCreds.startsWith('snk_live_')) return fromCreds;
+
+  return null;
+}
+
 function resolveInstance() {
   const fromEnv =
     pick(process.env.SECURENOW_INSTANCE) ||
@@ -143,6 +162,7 @@ module.exports = {
   resolveAppKey,
   resolveAppName,
   resolveAppId,
+  resolveApiKey,
   resolveInstance,
   resolveAll,
   loadCredentials,

package/cli/apiKey.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const config = require('./config');
+const ui = require('./ui');
+
+function maskKey(key) {
+  if (!key || key.length < 16) return key || '';
+  return `${key.slice(0, 12)}••••••${key.slice(-4)}`;
+}
+
+async function set(args, flags) {
+  const key = args[0];
+  if (!key) {
+    ui.error('API key is required. Usage: securenow api-key set <snk_live_...>');
+    process.exit(1);
+  }
+  if (!key.startsWith('snk_live_')) {
+    ui.error('API key must start with "snk_live_"');
+    ui.info('Create one in the dashboard: Settings → API Keys');
+    process.exit(1);
+  }
+
+  const local = flags.global ? false : true;
+  config.setApiKey(key, { local });
+  if (local) config.ensureLocalGitignore();
+
+  ui.success(`API key saved (${maskKey(key)})`);
+  ui.info(local
+    ? 'Stored in project .securenow/credentials.json (local)'
+    : 'Stored in ~/.securenow/credentials.json (global)');
+  ui.info('The firewall will now pick it up automatically — no SECURENOW_API_KEY env var needed.');
+}
+
+async function clear(args, flags) {
+  const local = flags.global ? false : true;
+  const existing = config.getApiKey();
+  config.clearApiKey({ local });
+  if (existing) {
+    ui.success(`Cleared API key (${maskKey(existing)})`);
+  } else {
+    ui.info('No API key was stored');
+  }
+}
+
+async function show() {
+  const key = config.getApiKey();
+  if (!key) {
+    ui.info('No API key stored in credentials. Falling back to SECURENOW_API_KEY env var.');
+    return;
+  }
+  console.log(maskKey(key));
+  ui.info(`Source: ${config.getAuthSource()}`);
+}
+
+module.exports = { set, clear, show };

package/cli/auth.js

@@ -45,6 +45,14 @@ async function loginWithBrowser() {
   return new Promise((resolve, reject) => {
     let pendingToken = null;
     let pendingApp = null;
+    let pendingApiKey = null;
+    const sockets = new Set();
+
+    const closeServer = () => {
+      try { server.close(); } catch {}
+      for (const s of sockets) { try { s.destroy(); } catch {} }
+      sockets.clear();
+    };
 
     const server = http.createServer((req, res) => {
       const url = new URL(req.url, `http://127.0.0.1`);
@@ -56,19 +64,20 @@ async function loginWithBrowser() {
         const appKey = url.searchParams.get('app_key');
         const appName = url.searchParams.get('app_name');
         const appInstance = url.searchParams.get('app_instance');
+        const apiKey = url.searchParams.get('api_key');
 
         res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
 
         if (error) {
           res.end('<html><body style="font-family:system-ui;text-align:center;padding:60px"><h2>Authentication Failed</h2><p>You can close this window.</p></body></html>');
-          server.close();
+          closeServer();
           reject(new CLIError(`Authentication failed: ${error}`));
           return;
         }
 
         if (returnedState !== nonce) {
           res.end('<html><body style="font-family:system-ui;text-align:center;padding:60px"><h2>Security Error</h2><p>State mismatch — this request may not have originated from your CLI. Please try again.</p></body></html>');
-          server.close();
+          closeServer();
           reject(new CLIError('State mismatch on callback — possible CSRF. Please retry `securenow login`.'));
           return;
         }
@@ -82,6 +91,9 @@ async function loginWithBrowser() {
               instance: appInstance || null,
             };
           }
+          if (apiKey && apiKey.startsWith('snk_live_')) {
+            pendingApiKey = apiKey;
+          }
           const payload = decodeJwtPayload(token);
           const email = payload?.email || 'unknown account';
           const safeEmail = email.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
@@ -124,7 +136,7 @@ async function loginWithBrowser() {
         }
 
         res.end('<html><body style="font-family:system-ui;text-align:center;padding:60px"><h2>Something went wrong</h2><p>No token received. Please try again.</p></body></html>');
-        server.close();
+        closeServer();
         reject(new CLIError('No token received in callback'));
         return;
       }
@@ -139,10 +151,12 @@ async function loginWithBrowser() {
         res.end('{"ok":true}');
         const token = pendingToken;
         const app = pendingApp;
+        const apiKeyFromLogin = pendingApiKey;
         pendingToken = null;
         pendingApp = null;
-        server.close();
-        resolve({ token, app });
+        pendingApiKey = null;
+        closeServer();
+        resolve({ token, app, apiKey: apiKeyFromLogin });
         return;
       }
 
@@ -150,6 +164,11 @@ async function loginWithBrowser() {
       res.end();
     });
 
+    server.on('connection', (socket) => {
+      sockets.add(socket);
+      socket.once('close', () => sockets.delete(socket));
+    });
+
     server.listen(0, '127.0.0.1', () => {
       const port = server.address().port;
       const authUrl = `${appUrl}/cli/auth?callback=http://127.0.0.1:${port}/callback&state=${encodeURIComponent(nonce)}`;
@@ -170,7 +189,7 @@ async function loginWithBrowser() {
       console.log(ui.c.dim('  Waiting for authentication...'));
 
       const timeout = setTimeout(() => {
-        server.close();
+        closeServer();
         reject(new CLIError('Login timed out after 5 minutes. Try `securenow login --token <TOKEN>` instead.'));
       }, 5 * 60 * 1000);
 
@@ -219,12 +238,13 @@ async function login(args, flags) {
   }
 
   try {
-    const { token, app } = await loginWithBrowser();
+    const { token, app, apiKey } = await loginWithBrowser();
     const payload = decodeJwtPayload(token);
     const email = payload?.email || 'unknown';
     const exp = payload?.exp ? payload.exp * 1000 : null;
 
     config.setAuth(token, email, exp, { local, app });
+    if (apiKey) config.setApiKey(apiKey, { local });
     if (local) config.ensureLocalGitignore();
     console.log('');
     ui.success(`Logged in as ${ui.c.bold(email)}`);
@@ -232,6 +252,9 @@ async function login(args, flags) {
     if (app && (app.name || app.key)) {
       ui.info(`Linked to app ${ui.c.bold(app.name || app.key)}${app.key ? ` (${ui.c.dim(app.key)})` : ''}`);
     }
+    if (apiKey) {
+      ui.info(`Firewall API key saved — the firewall will activate automatically on next start`);
+    }
     if (exp) {
       const days = Math.ceil((exp - Date.now()) / (1000 * 60 * 60 * 24));
       ui.info(`Session expires in ${days} days`);

package/cli/config.js

@@ -135,6 +135,27 @@ function getApp() {
   return creds && creds.app ? creds.app : null;
 }
 
+function setApiKey(apiKey, { local } = {}) {
+  const useLocal = local === true || (local == null && hasLocalCredentials());
+  const targetFile = useLocal ? LOCAL_CREDENTIALS_FILE : CREDENTIALS_FILE;
+  const existing = loadJSON(targetFile);
+  saveJSON(targetFile, { ...existing, apiKey });
+}
+
+function clearApiKey({ local } = {}) {
+  const useLocal = local === true || (local == null && hasLocalCredentials());
+  const targetFile = useLocal ? LOCAL_CREDENTIALS_FILE : CREDENTIALS_FILE;
+  const existing = loadJSON(targetFile);
+  if (!existing || !existing.apiKey) return;
+  delete existing.apiKey;
+  saveJSON(targetFile, existing);
+}
+
+function getApiKey() {
+  const creds = loadCredentials();
+  return creds && creds.apiKey ? creds.apiKey : null;
+}
+
 function setApp(app, { local } = {}) {
   const useLocal = local === true || (local == null && hasLocalCredentials());
   const targetFile = useLocal ? LOCAL_CREDENTIALS_FILE : CREDENTIALS_FILE;
@@ -193,6 +214,9 @@ module.exports = {
   setAuth,
   getApp,
   setApp,
+  setApiKey,
+  clearApiKey,
+  getApiKey,
   getAuthSource,
   hasLocalCredentials,
   ensureLocalGitignore,

package/cli/diagnostics.js

@@ -25,7 +25,9 @@ function resolvedConfig() {
       ? `${process.env.OTEL_EXPORTER_OTLP_ENDPOINT.replace(/\/$/, '')}/v1/logs`
       : `${instance.replace(/\/$/, '')}/v1/logs`);
   const headers = process.env.OTEL_EXPORTER_OTLP_HEADERS || '';
-  const apiKey = process.env.SECURENOW_API_KEY || '';
+  // Resolve firewall API key the same way the SDK does: env, then
+  // .securenow/credentials.json (project-local, then global).
+  const apiKey = require('../app-config').resolveApiKey() || '';
   const apiUrl = config.getApiUrl();
   const loggingEnabled = !/^(0|false)$/i.test(String(process.env.SECURENOW_LOGGING_ENABLED ?? ''));
   const captureBody = !/^(0|false)$/i.test(String(process.env.SECURENOW_CAPTURE_BODY ?? ''));

package/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 'use strict';
 
 const ui = require('./cli/ui');
@@ -73,6 +73,30 @@ const COMMANDS = {
     usage: 'securenow whoami',
     run: () => require('./cli/auth').whoami(),
   },
+  'api-key': {
+    desc: 'Manage the firewall API key stored in .securenow/credentials.json',
+    usage: 'securenow api-key <subcommand> [options]',
+    sub: {
+      set: {
+        desc: 'Save an API key (snk_live_...) to the credentials file',
+        usage: 'securenow api-key set <snk_live_...> [--global]',
+        flags: { global: 'Save to ~/.securenow/ instead of project-local' },
+        run: (a, f) => require('./cli/apiKey').set(a, f),
+      },
+      clear: {
+        desc: 'Remove the stored API key',
+        usage: 'securenow api-key clear [--global]',
+        flags: { global: 'Clear from ~/.securenow/ instead of project-local' },
+        run: (a, f) => require('./cli/apiKey').clear(a, f),
+      },
+      show: {
+        desc: 'Print the masked API key currently in use',
+        usage: 'securenow api-key show',
+        run: () => require('./cli/apiKey').show(),
+      },
+    },
+    defaultSub: 'show',
+  },
   apps: {
     desc: 'Manage applications',
     usage: 'securenow apps <subcommand> [options]',

package/docs/API-KEYS-GUIDE.md

@@ -41,6 +41,43 @@ The `snk_live_` prefix makes it easy to identify SecureNow keys in your codebase
 
 ---
 
+## 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 and, if you opt in,
+# 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.
@@ -117,13 +154,21 @@ curl -s https://api.securenow.ai/api/v1/blocklist \
 
 ### In the Firewall SDK
 
-Set the `SECURENOW_API_KEY` environment variable:
+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 this automatically on startup.
+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
 

package/docs/ENVIRONMENT-VARIABLES.md

@@ -533,6 +533,8 @@ export NODE_ENV=test
 export SECURENOW_API_KEY=snk_live_a1b2c3d4e5f6...
 ```
 
+**v7.1.0+:** the firewall also reads this key from `.securenow/credentials.json` (written by `securenow login` with firewall enabled, or by `securenow api-key set`). The env var only wins if it starts with `snk_live_` — otherwise the credentials file is used, so you can rely on the file for local dev without unsetting any stray env var. Setting an app UUID here (the old pre-7.1 habit) is ignored for firewall auth and would produce silent 401s; always use a `snk_live_...` key.
+
 ---
 
 ### SECURENOW_API_URL

package/docs/FIREWALL-GUIDE.md

@@ -44,17 +44,26 @@ All layers share the same in-memory blocklist, synced from the SecureNow API usi
 
 ### 1. Get an API Key
 
+Two ways to get the firewall wired up — pick whichever fits:
+
 ```bash
-# Log in to SecureNow
+# (a) Zero-config (v7.1+): run login and choose "Enable firewall" in the browser.
+# The dashboard mints a key scoped firewall:read + blocklist:read + allowlist:read
+# and the CLI writes it to .securenow/credentials.json. No further config needed.
 npx securenow login
 
-# View your firewall status and API key
+# (b) Already have a key? Drop it into the credentials file directly:
+npx securenow api-key set snk_live_abc123...
+
+# View your firewall status and API key source
 npx securenow firewall status
 ```
 
 Or create an API key from the dashboard: **Settings → API Keys → Create Key** with the `firewall:read` scope.
 
-### 2. Add the Key to Your Environment
+### 2. Add the Key to Your Environment (optional)
+
+If you used `securenow login` or `securenow api-key set` above, you can **skip this step** — the SDK reads the key from `.securenow/credentials.json` at boot. Env vars are still supported for CI / Docker / prod:
 
 ```bash
 # .env
@@ -67,7 +76,7 @@ SECURENOW_API_KEY=snk_live_abc123...
 node -r securenow/register app.js
 ```
 
-That's it. The firewall auto-activates when `SECURENOW_API_KEY` is present. You'll see:
+That's it. The firewall auto-activates as soon as a valid `snk_live_...` key is available (env var or credentials file). You'll see:
 
 ```
 [securenow] Firewall: ENABLED
@@ -191,7 +200,7 @@ SECURENOW_FIREWALL_CLOUD_DRY_RUN=1
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `SECURENOW_API_KEY` | *(required)* | API key with `firewall:read` scope |
+| `SECURENOW_API_KEY` | *(from creds file)* | API key with `firewall:read` scope. Since v7.1.0 the firewall also reads this from `.securenow/credentials.json` (written by `securenow login` or `securenow api-key set`), so this env var is optional. The env var only wins if it starts with `snk_live_`; otherwise the credentials file is used. |
 | `SECURENOW_API_URL` | `https://api.securenow.ai` | API base URL. Auto-fallback to `http://localhost:4000` on ECONNREFUSED. |
 | `SECURENOW_FIREWALL_ENABLED` | `1` | Master kill-switch (`0` to disable) |
 | `SECURENOW_FIREWALL_VERSION_INTERVAL` | `10` | Seconds between version checks (lightweight ETag-based) |

package/docs/INDEX.md

@@ -80,8 +80,8 @@ Complete documentation for SecureNow - OpenTelemetry instrumentation for Node.js
 
 ### 🛡️ Security & Protection
 
-- **[Firewall Guide](FIREWALL-GUIDE.md)** - Automatic IP blocking (multi-layer: HTTP, TCP, iptables, Cloud WAF)
-- **[API Keys Guide](API-KEYS-GUIDE.md)** - Creating, managing, and securing API keys
+- **[Firewall Guide](FIREWALL-GUIDE.md)** - Automatic IP blocking (multi-layer: HTTP, TCP, iptables, Cloud WAF). v7.1+: `securenow login` now offers one-click firewall onboarding that writes the key to `.securenow/credentials.json`.
+- **[API Keys Guide](API-KEYS-GUIDE.md)** - Creating, managing, and securing API keys. Includes the `securenow api-key set|show|clear` command family (v7.1+).
 - **[Redaction Examples](REDACTION-EXAMPLES.md)** - How sensitive data is redacted
 - **[Automatic IP Capture](AUTOMATIC-IP-CAPTURE.md)** - IP address and metadata collection
 

package/firewall-only.js

@@ -8,7 +8,7 @@
  *   NODE_OPTIONS='-r securenow/firewall-only' next start
  *
  * Reads .env via dotenv (if installed), then initialises the HTTP-level
- * firewall when SECURENOW_API_KEY is present.
+ * firewall when an API key is resolvable (env var or .securenow/credentials.json).
  */
 
 try { require('dotenv').config(); } catch (_) {}
@@ -16,7 +16,8 @@ try { require('dotenv').config(); } catch (_) {}
 const env = (k) =>
   process.env[k] ?? process.env[k.toUpperCase()] ?? process.env[k.toLowerCase()];
 
-const firewallApiKey = env('SECURENOW_API_KEY');
+const { resolveApiKey } = require('./app-config');
+const firewallApiKey = resolveApiKey();
 
 if (firewallApiKey && env('SECURENOW_FIREWALL_ENABLED') !== '0') {
   require('./firewall').init({

package/nextjs.js

@@ -610,8 +610,10 @@ function registerSecureNow(options = {}) {
     }
   }
 
-  // Firewall — runs independently from OTel so it works even if tracing fails
-  const firewallApiKey = env('SECURENOW_API_KEY');
+  // Firewall — runs independently from OTel so it works even if tracing fails.
+  // Key comes from env OR .securenow/credentials.json (set via
+  // `npx securenow api-key set snk_live_...`), so you don't need a .env entry.
+  const firewallApiKey = require('./app-config').resolveApiKey();
   if (firewallApiKey && env('SECURENOW_FIREWALL_ENABLED') !== '0') {
     try {
       require('./firewall').init({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securenow",
-  "version": "7.0.0-anas.3",
+  "version": "7.2.0",
   "description": "OpenTelemetry instrumentation for Node.js, Next.js, and Nuxt - Send traces and logs to any OTLP-compatible backend",
   "type": "commonjs",
   "main": "register.js",
@@ -165,7 +165,8 @@
   },
   "overrides": {
     "@opentelemetry/api": "1.7.0",
-    "@opentelemetry/api-logs": "0.47.0"
+    "@opentelemetry/api-logs": "0.47.0",
+    "protobufjs": "^7.5.5"
   },
   "sideEffects": true,
   "license": "ISC"