securenow 7.7.15 → 7.8.1

package/SKILL-CLI.md

@@ -24,24 +24,27 @@ codex mcp add securenow -- npx securenow mcp
 npx -p securenow securenow-mcp
 ```
 
-The MCP server reuses `.securenow/credentials.json` and exposes apps, traces, logs, firewall, IP intelligence, forensics, notifications, remediation tools, alert-rule review/tuning tools, bundled docs resources, and setup prompts. Write tools require `confirm:true` plus a reason.
+The MCP server reads admin/control-plane auth from `.securenow/admin.json` and SDK runtime app credentials from `.securenow/runtime.json`, with legacy `.securenow/credentials.json` still supported. Admin/global tools use admin auth; runtime-scoped read tools can use the runtime firewall key where its scopes allow it. Write tools require `confirm:true` plus a reason.
 
 ### Authenticate
 
 ```bash
-securenow login             # opens browser OAuth + app picker; writes ./.securenow/credentials.json (project-local by default)
-securenow login --global    # save to ~/.securenow/ instead (shared across projects)
-securenow login --token <JWT>   # headless / CI login (get token from dashboard Settings)
-securenow whoami            # verify session (shows email, app, auth source)
-```
+securenow login             # friendly flow: admin auth + app runtime connection
+securenow admin login       # admin/control-plane CLI and MCP auth only
+securenow app connect       # app/runtime SDK connection only
+securenow admin login --token <JWT>   # headless / CI admin auth
+securenow whoami            # verify both admin auth and runtime app status
+```
+
+**Two-lane credentials (v7.8+):** admin/control-plane auth lives in `.securenow/admin.json`; SDK runtime app config and the firewall API key live in `.securenow/runtime.json`. `securenow login` can run both lanes for onboarding, but `securenow admin login` never replaces runtime app config and `securenow app connect` never replaces admin auth. Legacy combined `.securenow/credentials.json` files are still read.
 
-**Zero-config flow (v7+):** the browser step lets the user pick (or create) an app. The CLI stores the app's **key (UUID)** and **name** in `.securenow/credentials.json`. The SDK sends traces/logs to the default SecureNow ingestion gateway, which routes by app key — **no env vars or per-instance collector URLs required for local dev or production**.
+**Zero-config runtime flow:** the browser step lets the user pick (or create) an app. The CLI stores the app's **key (UUID)** and **name** in `.securenow/runtime.json`. The SDK sends traces/logs to the default SecureNow ingestion gateway, which routes by app key, so no env vars or per-instance collector URLs are required for local dev or production.
 
-**Default-on security (v7.5.1+):** after picking or creating the app, `securenow login` turns on that app's firewall toggle, mints an API key with `firewall:read + blocklist:read + allowlist:read` scopes, and writes it into `.securenow/credentials.json`. Traces, logs, POST body capture, multipart metadata capture, and the firewall are enabled by default. No `SECURENOW_API_KEY` env var is 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).
+**Default-on security (v7.5.1+):** after picking or creating the app, `securenow app connect` turns on that app's firewall toggle, mints an API key with `firewall:read + blocklist:read + allowlist:read` scopes, and writes it into `.securenow/runtime.json`. Traces, logs, POST body capture, multipart metadata capture, and the firewall are enabled by default. No `SECURENOW_API_KEY` env var is needed. To add or rotate a key later without re-running app connect, use `securenow api-key set snk_live_...` (see [API Key Management](#api-key-management) below).
 
-Credentials resolve in order: project `.securenow/credentials.json` -> project named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order -> global `~/.securenow/credentials.json` -> global named runtime credentials in the same fixed order. Runtime config is credentials-json based; legacy env fallbacks are disabled unless `SECURENOW_ENABLE_LEGACY_ENV=1` is set and never choose the credentials filename.
+Runtime credentials resolve in order: project `.securenow/runtime.json` -> legacy project `.securenow/credentials.json` -> project named runtime credentials -> global `.securenow/runtime.json` -> legacy global credentials -> global named runtime credentials. Admin auth resolves from `admin.json` first, then legacy `credentials.json`. Runtime config is credentials-json based; legacy env fallbacks are disabled unless `SECURENOW_ENABLE_LEGACY_ENV=1` is set and never choose the credentials filename.
 
-The **firewall API key** should live in the same credentials file as `apiKey`.
+The **firewall API key** should live in runtime credentials as `apiKey`.
 
 For CI / Docker / production, use `securenow credentials runtime --env production` to generate a tokenless runtime file, then mount/copy it as `.securenow/credentials.json`. Since v7.7.2, mounting the generated `.securenow/credentials.production.json` filename directly also works when `credentials.json` is absent.
 
@@ -62,11 +65,11 @@ node -r securenow/register src/index.js
 For Next.js, run the interactive scaffolding:
 
 ```bash
-securenow login
-securenow init
-```
-
-This auto-detects your framework, creates the necessary `instrumentation.ts` and `next.config.js` changes, and reuses the app, instance, and firewall key written by login to `.securenow/credentials.json`.
+securenow login
+securenow init
+```
+
+This auto-detects your framework, creates the necessary `instrumentation.ts` and `next.config.js` changes, and reuses the app, instance, and firewall key written by login or `app connect` to `.securenow/runtime.json`.
 
 ### Install This Skill in Cursor
 
@@ -76,16 +79,19 @@ Save this file as `.cursor/skills/securenow-cli/SKILL.md` in your project. Your
 
 Config lives in `~/.securenow/` (global) and optionally `.securenow/` (per-project):
 
-| File | Content |
-|------|---------|
-| `~/.securenow/config.json` | `apiUrl`, `appUrl`, `defaultApp`, `output` |
-| `~/.securenow/credentials.json` | `token`, `email`, `expiresAt`, `apiKey`, `app`, `config` (global, use `login --global`) |
-| `.securenow/credentials.json` | `token`, `email`, `expiresAt`, `apiKey`, `app`, `config`, `_securenow.explanations` (project-local default) |
+| File | Content |
+|------|---------|
+| `~/.securenow/config.json` | `apiUrl`, `appUrl`, `defaultApp`, `output` |
+| `~/.securenow/admin.json` | `token`, `email`, `expiresAt` for global admin/control-plane CLI and MCP auth |
+| `~/.securenow/runtime.json` | `apiKey`, `app`, `config` for global SDK runtime |
+| `.securenow/admin.json` | `token`, `email`, `expiresAt` for project-local admin/control-plane CLI and MCP auth |
+| `.securenow/runtime.json` | `apiKey`, `app`, `config`, `_securenow.explanations` for project-local SDK runtime |
+| `.securenow/credentials.json` | Legacy combined credentials; still read for backward compatibility |
 | `.securenow/credentials.<environment>.json` | Tokenless runtime credentials generated by `securenow credentials runtime --env <environment>`; read in a fixed order, not selected from env vars |
 
-**Credential resolution order:** `.securenow/credentials.json` (project) -> project named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order -> `~/.securenow/credentials.json` (global) -> global named runtime credentials in the same fixed order. Legacy env fallbacks are disabled unless `SECURENOW_ENABLE_LEGACY_ENV=1` is set.
+**Credential resolution order:** runtime config resolves from project `.securenow/runtime.json` -> legacy project `.securenow/credentials.json` -> project named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order -> global `.securenow/runtime.json` -> legacy global credentials -> global named runtime credentials. Admin auth resolves from `admin.json` first, then legacy `credentials.json`. Legacy env fallbacks are disabled unless `SECURENOW_ENABLE_LEGACY_ENV=1` is set.
 
-**Firewall API key resolution (v7.5.1+):** project `.securenow/credentials.json` -> project named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order -> global `~/.securenow/credentials.json` -> global named runtime credentials in the same fixed order. Use `securenow login` for default setup or `securenow api-key set` to rotate a key without touching env vars.
+**Firewall API key resolution (v7.8+):** project `.securenow/runtime.json` -> legacy project credentials -> project named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order -> global runtime credentials -> legacy global credentials -> global named runtime credentials. Use `securenow app connect` for runtime setup or `securenow api-key set` to rotate a key without touching admin auth or env vars.
 
 ```bash
 securenow config set apiUrl https://api.securenow.ai
@@ -128,12 +134,13 @@ Spawns `node --require securenow/register [--import otel/hook.mjs] <script>`. ES
 ### Authentication
 
 ```bash
-securenow login                   # browser-based OAuth (stores in project ./.securenow/)
-securenow login --token <JWT>     # headless / CI login
-securenow login --global          # save credentials to ~/.securenow/ instead
-securenow logout                  # clear active credentials (local if present, else global)
-securenow logout --global         # clear global credentials only
-securenow whoami                  # show email, user ID, API URL, auth source, expiry, default app
+securenow login                   # friendly flow: admin auth + app runtime connection
+securenow admin login             # admin/control-plane CLI and MCP auth only
+securenow admin login --token <JWT> # headless / CI admin auth
+securenow app connect             # app/runtime SDK connection only
+securenow logout                  # clear admin auth; runtime app config remains
+securenow logout --global         # clear global admin auth only
+securenow whoami                  # show admin auth and runtime app status separately
 ```
 
 ### Applications
@@ -151,7 +158,7 @@ securenow apps scan [--yes]                  # scan all app domains for new subd
 
 ### API Key Management
 
-Manage the firewall API key stored in the credentials file. Since v7.5.1 the login flow writes `snk_live_...` keys to `.securenow/credentials.json` by default, so no env var is required for local dev.
+Manage the firewall API key stored in runtime credentials. Since v7.8 the app runtime flow writes `snk_live_...` keys to `.securenow/runtime.json` by default, so no env var is required for local dev.
 
 ```bash
 securenow api-key create --name "CLI firewall" # mint + save a firewall key with your logged-in session
@@ -163,7 +170,7 @@ securenow api-key clear --global             # same, but from the global file
 securenow credentials runtime --env production # write .securenow/credentials.production.json for production secret-file deploys
 ```
 
-The key must start with `snk_live_`. `securenow login` with firewall enabled writes the key automatically; use `api-key create` when you have an account session but no runtime key yet, or `api-key set` when you already have a key from the dashboard.
+The key must start with `snk_live_`. `securenow app connect` writes the key automatically; use `api-key create` when you have admin auth but no runtime key yet, or `api-key set` when you already have a key from the dashboard.
 
 ### Init — Project Setup
 
@@ -172,12 +179,12 @@ securenow init [--env local] [--key <API_KEY>]
 ```
 
 Auto-detects framework (Next.js, Nuxt, Express, Fastify, Koa, Hapi, Node) from `package.json`. Then:
-- **Credentials**: ensures `.securenow/credentials.json` exists, has secure defaults/explanations, and local credential JSON files are gitignored without ignoring the whole `.securenow/` directory
+- **Credentials**: ensures `.securenow/runtime.json` exists, has secure defaults/explanations, and local credential JSON files are gitignored without ignoring the whole `.securenow/` directory
 - **Next.js**: creates `instrumentation.ts/js` with `securenow/nextjs` + `securenow/nextjs-auto-capture`, and adds `serverExternalPackages: ['securenow']` plus `outputFileTracingIncludes` when the config can be patched safely
 - **Existing Next.js files**: prints a Codex/Claude-ready merge prompt when instrumentation or config already exists or is too custom to safely patch
 - **Nuxt**: tells you to add `securenow/nuxt` to modules
 - **Node/Express/etc.**: suggests adding `-r securenow/register` to start script
-- Reuses `.securenow/credentials.json` written by login; production should mount/copy the tokenless runtime file generated by `securenow credentials runtime --env production`
+- Reuses `.securenow/runtime.json` written by login/app connect; production should mount/copy the tokenless runtime file generated by `securenow credentials runtime --env production`
 
 ### Dashboard & Status
 
@@ -305,7 +312,7 @@ securenow firewall status --app <key> --env production   # app/env toggle, sync
 securenow firewall test-ip <ip> --app <key> --env local  # check if IP would be blocked
 ```
 
-**Zero-config setup (v7.5.1+):** running `securenow login` enables the selected app's firewall toggle, auto-mints an API key (scoped `firewall:read + blocklist:read + allowlist:read`), and writes it to the credentials file after the app is selected. 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.
+**Zero-config setup:** running `securenow app connect` enables the selected app's firewall toggle, auto-mints an API key (scoped `firewall:read + blocklist:read + allowlist:read`), and writes it to `.securenow/runtime.json` after the app is selected. 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
 
@@ -313,12 +320,17 @@ securenow firewall test-ip <ip> --app <key> --env local  # check if IP would be
 securenow blocklist                          # list blocked IPs
 securenow blocklist list
 securenow blocklist add <ip> --app <key> --env production --reason "Brute force"
+securenow blocklist add <ip> --route /admin* --mode prefix --method ALL --reason "Admin probing"
 securenow blocklist unblock <id> --reason "False alarm after review"
 securenow blocklist remove <id>              # compatibility alias for unblock
 securenow blocklist list --status removed    # audit retained unblocks
 securenow blocklist stats                    # block counts, top reasons
 ```
 
+Scoped blocks use the same model as rate limits: `--route`/`--path`/`--pattern`
+sets `pathPattern`, `--mode`/`--path-mode` chooses `prefix`, `exact`, or
+`regex`, and `--method` limits enforcement to one HTTP method or `ALL`.
+
 Unblock stops firewall enforcement but preserves the block report, history, and
 unblock audit fields. Reblocking the same IP later creates a fresh active block
 without erasing the previous investigation trail.
@@ -368,7 +380,13 @@ supporting evidence, not the primary automation score.
 
 ### Allowlist — Restrict to Known IPs
 
-```bash
+Dangerous production mode: IP Allowlist is deny-by-default. Once any active
+allowlist entry exists for an app/environment, only listed IPs can reach it and
+all other IPs are blocked. Do not use allowlist to mark an IP trusted, suppress
+false positives, or clean up investigations. Use `securenow trusted add` for
+known-safe monitors, office/VPN traffic, or trusted bypass cases.
+
+```bash
 securenow allowlist                          # list allowed IPs
 securenow allowlist list
 securenow allowlist add <ip> --app <key> --env local --label "Office" --reason "Corporate VPN"
@@ -376,10 +394,13 @@ securenow allowlist remove <id>
 securenow allowlist stats
 ```
 
-### Trusted Proxies
+### Trusted IPs
 
-```bash
-securenow trusted                            # list trusted IPs
+Trusted IPs are the safe bypass/suppression mechanism for known infrastructure
+and do not enable deny-by-default allowlist mode.
+
+```bash
+securenow trusted                            # list trusted IPs
 securenow trusted list
 securenow trusted add <ip> [--label "CloudFlare edge"]
 securenow trusted remove <id>
@@ -473,7 +494,7 @@ securenow test-span
 securenow test-span "ci.smoke-test"          # custom span name
 ```
 
-Both commands use the default SecureNow ingestion gateway plus optional advanced `config.otel.*` overrides from `.securenow/credentials.json`, and return non-zero on HTTP errors so CI/cron can detect failures.
+Both commands use the default SecureNow ingestion gateway plus optional advanced `config.otel.*` overrides from `.securenow/runtime.json` or legacy runtime credentials, and return non-zero on HTTP errors so CI/cron can detect failures.
 
 ### Utilities — Redaction, CIDR, Diagnostics
 
@@ -581,8 +602,8 @@ All commands support `--json` for structured output. When piping to other tools
 
 | Exit code / Error | Meaning | Recovery |
 |------------------|---------|----------|
-| `Session expired` | JWT expired | `securenow login` (or `login --global` for shared credentials) |
-| `Not logged in` | No token found | `securenow login` or mount/copy the right `.securenow/credentials.json` |
+| `Session expired` | Admin JWT expired | `securenow admin login` (or `admin login --global` for shared admin auth) |
+| `Not logged in` | No admin token found | `securenow admin login`; runtime `.securenow/runtime.json` is unrelated |
 | `Access denied (403)` | Insufficient plan or permissions | Upgrade plan or check user role |
 | `Cannot connect` | API unreachable | Check `securenow config get apiUrl` or network |
 | `Unknown command` | Typo or unrecognized command | `securenow help` |

package/app-config.js

@@ -3,7 +3,8 @@
 /**
  * Shared SecureNow configuration resolver.
  *
- * Local development and production are driven by ./.securenow/credentials.json.
+ * Local development is driven by ./.securenow/runtime.json.
+ * Legacy combined ./.securenow/credentials.json files remain readable.
  * Named runtime files such as ./.securenow/credentials.staging.json and
  * ./.securenow/credentials.production.json are also accepted when the
  * canonical file is not present. Filename selection is deterministic and does
@@ -18,6 +19,7 @@ const os = require('os');
 
 const FREE_TRIAL_INSTANCE = 'https://ingest.securenow.ai';
 const DEFAULT_API_URL = 'https://api.securenow.ai';
+const DEFAULT_FIREWALL_API_URL = FREE_TRIAL_INSTANCE;
 const LEGACY_SECURENOW_GATEWAY = 'https://api.securenow.ai/api/otlp';
 const LEGACY_ENV_FALLBACK_FLAG = 'SECURENOW_ENABLE_LEGACY_ENV';
 const CONFIG_SCHEMA_VERSION = 2;
@@ -31,6 +33,8 @@ const CREDENTIAL_FILE_ENVIRONMENTS = Object.freeze([
   'dev',
   'prod',
 ]);
+const RUNTIME_CREDENTIALS_FILENAME = 'runtime.json';
+const ADMIN_CREDENTIALS_FILENAME = 'admin.json';
 
 const DEFAULT_CONFIG = Object.freeze({
   logging: {
@@ -89,8 +93,8 @@ const DEFAULT_CONFIG = Object.freeze({
 });
 
 const CONFIG_EXPLANATIONS = Object.freeze({
-  'token': 'CLI session token written by `npx securenow login`. Secret: do not commit.',
-  'apiKey': 'Scoped firewall API key (`snk_live_...`) minted by login or `securenow api-key set`. Secret: do not commit.',
+  'token': 'Legacy CLI session token. New admin/control-plane auth is written to admin.json. Secret: do not commit.',
+  'apiKey': 'Scoped firewall API key (`snk_live_...`) minted by `securenow app connect` or `securenow api-key set`. Secret: do not commit.',
   'app.key': 'SecureNow application routing UUID. The SDK uses this as OTel service.name so dashboard queries match exactly.',
   'app.name': 'Human-readable app label shown in CLI output.',
   'app.routing': 'Telemetry uses the default SecureNow ingestion gateway and routes by app.key; runtime credentials do not expose per-instance collector URLs.',
@@ -110,8 +114,8 @@ const CONFIG_EXPLANATIONS = Object.freeze({
   'config.runtime.strict': 'If true, PM2/cluster workers exit when no app identity is resolvable.',
   'config.runtime.testSpan': 'If true, emit a startup smoke span. Prefer `npx securenow test-span` for manual checks.',
   'config.runtime.hideBanner': 'Hide the free-trial response banner when using the managed free-trial collector.',
-  'config.firewall.enabled': 'Secure default: app firewall enforcement starts when apiKey is present and the dashboard toggle is on.',
-  'config.firewall.apiUrl': 'SecureNow API base URL for firewall sync.',
+  'config.firewall.enabled': 'Deprecated local hint. Runtime firewall enforcement is controlled by the SecureNow dashboard/API app environment toggle; the SDK starts sync whenever apiKey is present.',
+  'config.firewall.apiUrl': 'Optional SecureNow firewall control-plane base URL. Leave unset/default so hosted SDKs sync through the SecureNow ingest gateway.',
   'config.firewall.versionCheckInterval': 'Seconds between lightweight firewall version/ETag checks.',
   'config.firewall.syncInterval': 'Seconds between safety-net full firewall blocklist syncs.',
   'config.firewall.failMode': 'open allows traffic if SecureNow is temporarily unreachable; closed blocks all on sync failure.',
@@ -243,7 +247,7 @@ function uniq(values) {
   return out;
 }
 
-function credentialRelativePaths() {
+function legacyCredentialRelativePaths() {
   return uniq([
     path.join('.securenow', 'credentials.json'),
     ...CREDENTIAL_FILE_ENVIRONMENTS.map((envName) =>
@@ -252,7 +256,25 @@ function credentialRelativePaths() {
   ]);
 }
 
-function resolveLocalCredentialsFile() {
+function runtimeCredentialRelativePaths() {
+  return uniq([
+    path.join('.securenow', RUNTIME_CREDENTIALS_FILENAME),
+    ...legacyCredentialRelativePaths(),
+  ]);
+}
+
+function adminCredentialRelativePaths() {
+  return uniq([
+    path.join('.securenow', ADMIN_CREDENTIALS_FILENAME),
+    ...legacyCredentialRelativePaths(),
+  ]);
+}
+
+function credentialRelativePaths() {
+  return runtimeCredentialRelativePaths();
+}
+
+function resolveLocalFileFromRelativePaths(relativePaths) {
   const starts = [];
   try {
     if (typeof process !== 'undefined' && process.cwd) starts.push(process.cwd());
@@ -262,7 +284,7 @@ function resolveLocalCredentialsFile() {
   if (process.argv && process.argv[1]) starts.push(path.dirname(process.argv[1]));
   if (require.main && require.main.filename) starts.push(path.dirname(require.main.filename));
 
-  const candidates = credentialRelativePaths();
+  const candidates = relativePaths;
   for (const start of uniq(starts)) {
     const found = findUpFirstFile(start, candidates);
     if (found) return found;
@@ -271,7 +293,15 @@ function resolveLocalCredentialsFile() {
   return null;
 }
 
-function resolveGlobalCredentialsFile() {
+function resolveLocalCredentialsFile() {
+  return resolveLocalFileFromRelativePaths(runtimeCredentialRelativePaths());
+}
+
+function resolveLocalAdminCredentialsFile() {
+  return resolveLocalFileFromRelativePaths(adminCredentialRelativePaths());
+}
+
+function resolveGlobalFileFromRelativePaths(relativePaths) {
   let home;
   try {
     home = os.homedir();
@@ -279,7 +309,7 @@ function resolveGlobalCredentialsFile() {
     return null;
   }
 
-  for (const relativePath of credentialRelativePaths()) {
+  for (const relativePath of relativePaths) {
     const found = fileIfReadable(path.join(home, relativePath));
     if (found) return found;
   }
@@ -287,6 +317,36 @@ function resolveGlobalCredentialsFile() {
   return null;
 }
 
+function resolveGlobalCredentialsFile() {
+  return resolveGlobalFileFromRelativePaths(runtimeCredentialRelativePaths());
+}
+
+function resolveGlobalAdminCredentialsFile() {
+  return resolveGlobalFileFromRelativePaths(adminCredentialRelativePaths());
+}
+
+function runtimeCredentialsFromDocument(credentials) {
+  if (!credentials || typeof credentials !== 'object' || Array.isArray(credentials)) return null;
+  if (!credentials.runtime || typeof credentials.runtime !== 'object' || Array.isArray(credentials.runtime)) {
+    return credentials;
+  }
+
+  const runtime = clone(credentials.runtime);
+  if (runtime.environment) {
+    runtime.config = runtime.config || {};
+    runtime.config.runtime = runtime.config.runtime || {};
+    runtime.config.runtime.deploymentEnvironment = runtime.environment;
+    delete runtime.environment;
+  }
+  if (runtime.instanceUrl) {
+    runtime.config = runtime.config || {};
+    runtime.config.otel = runtime.config.otel || {};
+    if (!runtime.config.otel.endpoint) runtime.config.otel.endpoint = runtime.instanceUrl;
+    delete runtime.instanceUrl;
+  }
+  return runtime;
+}
+
 function resolvePackageJsonFile() {
   const starts = [];
   try {
@@ -307,7 +367,7 @@ function resolvePackageJsonFile() {
 
 function loadLocalCredentials() {
   try {
-    return withCredentialDefaults(readJsonSafe(resolveLocalCredentialsFile()));
+    return withCredentialDefaults(runtimeCredentialsFromDocument(readJsonSafe(resolveLocalCredentialsFile())));
   } catch {
     return null;
   }
@@ -315,7 +375,7 @@ function loadLocalCredentials() {
 
 function loadGlobalCredentials() {
   try {
-    return withCredentialDefaults(readJsonSafe(resolveGlobalCredentialsFile()));
+    return withCredentialDefaults(runtimeCredentialsFromDocument(readJsonSafe(resolveGlobalCredentialsFile())));
   } catch {
     return null;
   }
@@ -325,7 +385,7 @@ function loadCredentials() {
   try {
     const localFile = resolveLocalCredentialsFile();
     if (localFile) {
-      return withCredentialDefaults(readJsonSafe(localFile));
+      return withCredentialDefaults(runtimeCredentialsFromDocument(readJsonSafe(localFile)));
     }
     return loadGlobalCredentials();
   } catch {
@@ -457,6 +517,41 @@ function normalizeSignalEndpoint(value, signalType) {
   return endpoint;
 }
 
+function normalizeFirewallApiUrl(value) {
+  const raw = pick(value);
+  if (raw == null) return DEFAULT_FIREWALL_API_URL;
+  const endpoint = normalizeInstanceEndpoint(raw);
+  if (!endpoint) return DEFAULT_FIREWALL_API_URL;
+  const trimmed = String(endpoint).trim().replace(/\/$/, '').replace(/\/api(?:\/v1)?$/i, '');
+
+  // api.securenow.ai was the historical SDK default. Hosted runtime sync now
+  // shares the ingest gateway so telemetry and firewall state fail or recover
+  // together, and so customer apps need only one public SecureNow egress host.
+  if (trimmed === DEFAULT_API_URL || trimmed === LEGACY_SECURENOW_GATEWAY) {
+    return DEFAULT_FIREWALL_API_URL;
+  }
+  if (trimmed === DEFAULT_FIREWALL_API_URL) return DEFAULT_FIREWALL_API_URL;
+
+  return trimmed;
+}
+
+function resolveFirewallApiUrl() {
+  return normalizeFirewallApiUrl(configValue('firewall.apiUrl', DEFAULT_API_URL));
+}
+
+function resolveFirewallApiFallbacks(primary = resolveFirewallApiUrl()) {
+  const normalizedPrimary = normalizeFirewallApiUrl(primary);
+  const fallbacks = [];
+
+  if (normalizedPrimary === DEFAULT_FIREWALL_API_URL) {
+    fallbacks.push(DEFAULT_API_URL);
+  } else if (normalizedPrimary === DEFAULT_API_URL) {
+    fallbacks.push(DEFAULT_FIREWALL_API_URL);
+  }
+
+  return uniq(fallbacks.filter((url) => url && url !== normalizedPrimary));
+}
+
 function pick(value) {
   if (value === undefined || value === null) return null;
   if (typeof value === 'string') {
@@ -694,6 +789,10 @@ function resolveOtlpHeaders() {
   if (appKey && !headers['x-api-key']) {
     headers['x-api-key'] = appKey;
   }
+  const deploymentEnvironment = resolveDeploymentEnvironment();
+  if (deploymentEnvironment && !headers['x-securenow-environment']) {
+    headers['x-securenow-environment'] = deploymentEnvironment;
+  }
   return headers;
 }
 
@@ -714,19 +813,18 @@ function resolveEndpoints(options = {}) {
 }
 
 function resolveFirewallEnabled() {
-  const fromConfig = pick(getPath(loadCredentials()?.config, 'firewall.enabled'));
-  if (fromConfig != null) return parseBool(fromConfig, true);
-
-  return parseBool(getPath(DEFAULT_CONFIG, 'firewall.enabled'), true);
+  return true;
 }
 
 function resolveFirewallOptions() {
+  const apiUrl = resolveFirewallApiUrl();
   return {
     apiKey: resolveApiKey(),
     appKey: resolveAppKey() || null,
     environment: resolveDeploymentEnvironment(),
     enabled: resolveFirewallEnabled(),
-    apiUrl: configValue('firewall.apiUrl', DEFAULT_API_URL) || DEFAULT_API_URL,
+    apiUrl,
+    apiUrlFallbacks: resolveFirewallApiFallbacks(apiUrl),
     versionCheckInterval: numberConfig('firewall.versionCheckInterval', 10, 1),
     syncInterval: numberConfig('firewall.syncInterval', 3600, 1),
     failMode: configValue('firewall.failMode', 'open') || 'open',
@@ -755,10 +853,13 @@ function resolveFirewallOptions() {
 module.exports = {
   FREE_TRIAL_INSTANCE,
   DEFAULT_API_URL,
+  DEFAULT_FIREWALL_API_URL,
   LEGACY_SECURENOW_GATEWAY,
   LEGACY_ENV_FALLBACK_FLAG,
   CONFIG_SCHEMA_VERSION,
   CREDENTIAL_FILE_ENVIRONMENTS,
+  RUNTIME_CREDENTIALS_FILENAME,
+  ADMIN_CREDENTIALS_FILENAME,
   DEFAULT_CONFIG,
   CONFIG_EXPLANATIONS,
   ENV_TO_CONFIG_PATH,
@@ -783,6 +884,9 @@ module.exports = {
   resolveOtlpHeaderString,
   resolveEndpoints,
   resolveFirewallEnabled,
+  normalizeFirewallApiUrl,
+  resolveFirewallApiUrl,
+  resolveFirewallApiFallbacks,
   resolveFirewallOptions,
   env,
   boolEnv,
@@ -792,9 +896,14 @@ module.exports = {
   normalizeInstanceEndpoint,
   normalizeSignalEndpoint,
   headersToString,
+  legacyCredentialRelativePaths,
+  runtimeCredentialRelativePaths,
+  adminCredentialRelativePaths,
   credentialRelativePaths,
   resolveLocalCredentialsFile,
   resolveGlobalCredentialsFile,
+  resolveLocalAdminCredentialsFile,
+  resolveGlobalAdminCredentialsFile,
   loadCredentials,
   loadLocalCredentials,
   loadGlobalCredentials,

package/cli/apiKey.js

@@ -34,15 +34,15 @@ async function create(args, flags) {
         name: result.apiKey?.name || name,
         preset,
         key: maskKey(key),
-        savedTo: local ? 'project .securenow/credentials.json' : '~/.securenow/credentials.json',
+        savedTo: local ? 'project .securenow/runtime.json' : '~/.securenow/runtime.json',
       });
       return;
     }
 
     ui.success(`API key saved (${maskKey(key)})`);
     ui.info(local
-      ? 'Stored in project .securenow/credentials.json (local)'
-      : 'Stored in ~/.securenow/credentials.json (global)');
+      ? 'Stored in project .securenow/runtime.json (local)'
+      : 'Stored in ~/.securenow/runtime.json (global)');
     ui.info('The plaintext key is not printed. The SDK will read it from the credentials file.');
   } catch (err) {
     s.fail('Failed to create API key');
@@ -68,8 +68,8 @@ async function set(args, flags) {
 
   ui.success(`API key saved (${maskKey(key)})`);
   ui.info(local
-    ? 'Stored in project .securenow/credentials.json (local)'
-    : 'Stored in ~/.securenow/credentials.json (global)');
+    ? 'Stored in project .securenow/runtime.json (local)'
+    : 'Stored in ~/.securenow/runtime.json (global)');
   ui.info('The firewall will now pick it up automatically — no SECURENOW_API_KEY env var needed.');
 }
 
@@ -87,11 +87,11 @@ async function clear(args, flags) {
 async function show() {
   const key = config.getApiKey();
   if (!key) {
-    ui.info('Runtime firewall enforcement key is missing. Run `npx securenow login` or `npx securenow api-key set snk_live_...` to refresh .securenow/credentials.json.');
+    ui.info('Runtime firewall enforcement key is missing. Run `npx securenow app connect` or `npx securenow api-key set snk_live_...` to refresh .securenow/runtime.json.');
     return;
   }
   console.log(maskKey(key));
-  ui.info(`Source: ${config.getAuthSource()}`);
+  ui.info(`Source: ${config.getRuntimeSource()}`);
 }
 
 module.exports = { create, set, clear, show };

package/cli/apps.js

@@ -66,7 +66,7 @@ async function list(args, flags) {
     if (!defaultApp && apps.length > 0) {
       console.log(`  ${ui.c.bold('Use one of these apps in the current project:')}`);
       console.log(`    ${ui.c.bold('securenow apps default <key>')}`);
-      console.log(`  ${ui.c.dim('(or run `securenow login` to pick interactively)')}`);
+      console.log(`  ${ui.c.dim('(or run `securenow app connect` to pick interactively)')}`);
       console.log('');
     }
   } catch (err) {
@@ -127,7 +127,7 @@ async function create(args, flags) {
     console.log('');
     console.log(`  ${ui.c.bold('Use this app in the current project:')}`);
     console.log(`    ${ui.c.bold(`securenow apps default ${app.key}`)}`);
-    console.log(`  ${ui.c.dim('(writes .securenow/credentials.json — no env var needed)')}`);
+    console.log(`  ${ui.c.dim('(writes .securenow/runtime.json - no env var needed)')}`);
     console.log('');
 
     if (flags.json) {
@@ -285,7 +285,7 @@ async function setDefault(args) {
   }
   config.setConfigValue('defaultApp', key);
 
-  // Mirror into credentials.json so the SDK picks this app up with zero env vars.
+  // Mirror into runtime credentials so the SDK picks this app up with zero env vars.
   try {
     requireAuth();
     const appData = await api.get(`/applications/${key}`);