securenow 7.7.14 → 7.7.16

package/SKILL-CLI.md

@@ -35,13 +35,13 @@ securenow login --token <JWT>   # headless / CI login (get token from dashboard
 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 or production**.
+**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**.
 
 **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).
 
-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. Legacy env vars are fallback-only for existing deployments and do not choose the credentials filename.
+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.
 
-The **firewall API key** should live in the same credentials file as `apiKey`. Legacy `SECURENOW_API_KEY` overrides are honored only when they start with `snk_live_`.
+The **firewall API key** should live in the same credentials file 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.
 
@@ -83,7 +83,7 @@ Config lives in `~/.securenow/` (global) and optionally `.securenow/` (per-proje
 | `.securenow/credentials.json` | `token`, `email`, `expiresAt`, `apiKey`, `app`, `config`, `_securenow.explanations` (project-local default) |
 | `.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 vars are fallback-only for existing deployments.
+**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.
 
 **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.
 
@@ -95,7 +95,7 @@ securenow config get defaultApp          # show one
 securenow config path                    # print file paths + active auth source
 ```
 
-Legacy CLI overrides still exist for existing automation (`SECURENOW_TOKEN`, `SECURENOW_API_URL`, `SECURENOW_APP_URL`, `SECURENOW_APP`), but file credentials are the default path.
+Legacy CLI overrides still exist for operator automation, but runtime SDK config should stay in the credentials file.
 
 ## Global Flags
 
@@ -172,7 +172,7 @@ 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 `.securenow/` is gitignored
+- **Credentials**: ensures `.securenow/credentials.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
@@ -473,7 +473,7 @@ securenow test-span
 securenow test-span "ci.smoke-test"          # custom span name
 ```
 
-Both commands use the resolved collector settings from `.securenow/credentials.json` (`app.instance`, `config.otel.*`) 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/credentials.json`, and return non-zero on HTTP errors so CI/cron can detect failures.
 
 ### Utilities — Redaction, CIDR, Diagnostics
 
@@ -497,7 +497,7 @@ securenow doctor                             # exits 0 if healthy, 1 otherwise
 securenow doctor --json
 ```
 
-The `redact` command accepts a JSON string or `@path/to/file.json`, layers your `--fields` flag on top of `DEFAULT_SENSITIVE_FIELDS`, and also honors `SECURENOW_SENSITIVE_FIELDS` from the env. Exit code from `cidr match` is `0` if the IP matches the list, `2` otherwise — scriptable.
+The `redact` command accepts a JSON string or `@path/to/file.json` and layers your `--fields` flag on top of `DEFAULT_SENSITIVE_FIELDS`. Exit code from `cidr match` is `0` if the IP matches the list, `2` otherwise — scriptable.
 
 ---
 

package/app-config.js

@@ -8,17 +8,19 @@
  * ./.securenow/credentials.production.json are also accepted when the
  * canonical file is not present. Filename selection is deterministic and does
  * not read environment variables.
- * Legacy environment variables are only fallback inputs for existing installs;
- * every SDK setting has a file-backed equivalent so customers do not need .env
- * files.
+ * Legacy environment fallbacks are disabled by default; every SDK setting has
+ * a file-backed equivalent so customers do not need .env files.
  */
 
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const FREE_TRIAL_INSTANCE = 'https://freetrial.securenow.ai:4318';
+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;
 const CREDENTIAL_FILE_ENVIRONMENTS = Object.freeze([
   'staging',
@@ -92,13 +94,13 @@ const CONFIG_EXPLANATIONS = Object.freeze({
   'apiKey': 'Scoped firewall API key (`snk_live_...`) minted by login 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.instance': 'OTLP collector base URL for this app. Production should provide this same credentials file at .securenow/credentials.json.',
+  'app.routing': 'Telemetry uses the default SecureNow ingestion gateway and routes by app.key; runtime credentials do not expose per-instance collector URLs.',
   'config.logging.enabled': 'Secure default: console log forwarding is on. Set false to disable OTLP logs.',
   'config.capture.body': 'Secure default: JSON, GraphQL, and form request bodies are captured with redaction.',
   'config.capture.multipart': 'Secure default: multipart text fields and file metadata are captured. File content is never buffered.',
   'config.capture.maxBodySize': 'Maximum body bytes captured per request. Default 10KB limits memory and sensitive data exposure.',
   'config.capture.sensitiveFields': 'Extra field-name fragments to redact in addition to SecureNow built-ins.',
-  'config.otel.endpoint': 'Optional OTLP base endpoint override. Usually app.instance is enough.',
+  'config.otel.endpoint': 'Optional OTLP base endpoint override for advanced/self-hosted collectors. Leave null for the SecureNow ingestion gateway.',
   'config.otel.tracesEndpoint': 'Optional full traces endpoint override, for split collectors.',
   'config.otel.logsEndpoint': 'Optional full logs endpoint override, for split collectors.',
   'config.otel.headers': 'Optional OTLP headers. The SDK auto-adds x-api-key from app.key when missing.',
@@ -110,7 +112,7 @@ const CONFIG_EXPLANATIONS = Object.freeze({
   '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.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.',
@@ -392,11 +394,14 @@ function mergeCredentials(globalCredentials, localCredentials) {
 function withCredentialDefaults(credentials) {
   if (!credentials || typeof credentials !== 'object') return null;
   const out = clone(credentials);
+  if (out.app && typeof out.app === 'object' && !Array.isArray(out.app)) {
+    delete out.app.instance;
+  }
   out.config = mergeMissing(out.config, DEFAULT_CONFIG);
   out._securenow = mergeMissing(out._securenow, {
     schemaVersion: CONFIG_SCHEMA_VERSION,
     note: 'Local SecureNow credentials and secure SDK defaults. This file may contain secrets; keep .securenow/ in .gitignore.',
-    precedence: 'The same credentials file works in local development and production. Legacy environment variables are only fallback inputs when this file does not define a value.',
+    precedence: `The same credentials file works in local development and production. SDK runtime config is read from credentials JSON. Legacy environment fallbacks are disabled unless ${LEGACY_ENV_FALLBACK_FLAG}=1 is set.`,
     explanations: CONFIG_EXPLANATIONS,
   });
   return out;
@@ -412,10 +417,82 @@ function getPath(obj, dotted) {
   return cur;
 }
 
+function legacyEnvFallbackEnabled() {
+  const raw =
+    process.env[LEGACY_ENV_FALLBACK_FLAG] ??
+    process.env.SECURENOW_ALLOW_ENV_CONFIG ??
+    process.env.SECURENOW_LEGACY_ENV;
+  return /^(1|true|yes)$/i.test(String(raw || '').trim());
+}
+
 function rawEnv(key) {
+  if (!legacyEnvFallbackEnabled()) return undefined;
   return process.env[key] ?? process.env[key.toUpperCase()] ?? process.env[key.toLowerCase()];
 }
 
+function normalizeInstanceEndpoint(value) {
+  if (value === undefined || value === null || value === '') return value;
+  const endpoint = String(value).trim().replace(/\/$/, '');
+  if (!endpoint) return endpoint;
+  if (endpoint === LEGACY_SECURENOW_GATEWAY) return FREE_TRIAL_INSTANCE;
+
+  try {
+    const parseable = /^[a-z][a-z0-9+.-]*:\/\//i.test(endpoint) ? endpoint : `https://${endpoint}`;
+    const url = new URL(parseable);
+    if (url.port === '4318' && url.hostname.toLowerCase().endsWith('.securenow.ai')) {
+      return FREE_TRIAL_INSTANCE;
+    }
+  } catch {}
+
+  return endpoint;
+}
+
+function normalizeSignalEndpoint(value, signalType) {
+  if (value === undefined || value === null || value === '') return value;
+  const endpoint = String(value).trim().replace(/\/$/, '');
+  const signalPath = `/v1/${signalType}`;
+  if (endpoint.endsWith(signalPath)) {
+    const base = normalizeInstanceEndpoint(endpoint.slice(0, -signalPath.length));
+    return `${base}${signalPath}`;
+  }
+  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') {
@@ -514,6 +591,22 @@ function resolveConfigPath(configPath, envKeys = [], fallback) {
   return fallback;
 }
 
+function configValue(configPath, fallback) {
+  return resolveConfigPath(configPath, [], fallback);
+}
+
+function boolConfig(configPath, fallback = false) {
+  return parseBool(configValue(configPath), fallback);
+}
+
+function numberConfig(configPath, fallback, min) {
+  return parseNumber(configValue(configPath), fallback, min);
+}
+
+function listConfig(configPath) {
+  return parseList(configValue(configPath));
+}
+
 function resolveAppKey() {
   const creds = loadCredentials();
   if (creds && creds.app && pick(creds.app.key)) return String(pick(creds.app.key));
@@ -559,18 +652,13 @@ function resolveApiKey() {
 
 function resolveInstance() {
   const fromConfig = pick(resolveConfigPath('otel.endpoint'));
-  if (fromConfig) return String(fromConfig).replace(/\/$/, '');
-
-  const creds = loadCredentials();
-  if (creds && creds.app && pick(creds.app.instance)) {
-    return String(pick(creds.app.instance)).replace(/\/$/, '');
-  }
+  if (fromConfig) return normalizeInstanceEndpoint(fromConfig);
 
   const fromEnv =
     pick(rawEnv('SECURENOW_INSTANCE')) ||
     pick(rawEnv('securenow_instance')) ||
     pick(rawEnv('OTEL_EXPORTER_OTLP_ENDPOINT'));
-  if (fromEnv) return String(fromEnv).replace(/\/$/, '');
+  if (fromEnv) return normalizeInstanceEndpoint(fromEnv);
 
   return FREE_TRIAL_INSTANCE;
 }
@@ -587,13 +675,7 @@ function resolveAll() {
 }
 
 function resolveDeploymentEnvironment() {
-  return normalizeDeploymentEnvironment(
-    resolveConfigPath('runtime.deploymentEnvironment', [
-      'SECURENOW_ENVIRONMENT',
-      'SECURENOW_DEPLOYMENT_ENVIRONMENT',
-      'NODE_ENV',
-    ])
-  );
+  return normalizeDeploymentEnvironment(resolveConfigPath('runtime.deploymentEnvironment'));
 }
 
 function resolveNoUuid(opts = {}) {
@@ -643,11 +725,15 @@ function listEnv(key) {
 }
 
 function resolveOtlpHeaders() {
-  const headers = parseHeaders(resolveConfigPath('otel.headers', ['OTEL_EXPORTER_OTLP_HEADERS'], {}));
+  const headers = parseHeaders(configValue('otel.headers', {}));
   const appKey = resolveAppKey();
   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;
 }
 
@@ -656,11 +742,13 @@ function resolveOtlpHeaderString() {
 }
 
 function resolveEndpoints(options = {}) {
-  const endpointBase = String(options.endpoint || resolveInstance()).replace(/\/$/, '');
+  const endpointBase = String(normalizeInstanceEndpoint(options.endpoint || resolveInstance())).replace(/\/$/, '');
+  const tracesOverride = configValue('otel.tracesEndpoint');
+  const logsOverride = configValue('otel.logsEndpoint');
   return {
     endpointBase,
-    tracesUrl: env('OTEL_EXPORTER_OTLP_TRACES_ENDPOINT') || `${endpointBase}/v1/traces`,
-    logsUrl: env('OTEL_EXPORTER_OTLP_LOGS_ENDPOINT') || `${endpointBase}/v1/logs`,
+    tracesUrl: normalizeSignalEndpoint(tracesOverride, 'traces') || `${endpointBase}/v1/traces`,
+    logsUrl: normalizeSignalEndpoint(logsOverride, 'logs') || `${endpointBase}/v1/logs`,
     headers: resolveOtlpHeaders(),
   };
 }
@@ -673,33 +761,35 @@ function resolveFirewallEnabled() {
 }
 
 function resolveFirewallOptions() {
+  const apiUrl = resolveFirewallApiUrl();
   return {
     apiKey: resolveApiKey(),
     appKey: resolveAppKey() || null,
     environment: resolveDeploymentEnvironment(),
     enabled: resolveFirewallEnabled(),
-    apiUrl: env('SECURENOW_API_URL') || DEFAULT_API_URL,
-    versionCheckInterval: numberEnv('SECURENOW_FIREWALL_VERSION_INTERVAL', 10, 1),
-    syncInterval: numberEnv('SECURENOW_FIREWALL_SYNC_INTERVAL', 3600, 1),
-    failMode: env('SECURENOW_FIREWALL_FAIL_MODE') || 'open',
-    statusCode: numberEnv('SECURENOW_FIREWALL_STATUS_CODE', 403, 100),
-    log: boolEnv('SECURENOW_FIREWALL_LOG', true),
-    tcp: boolEnv('SECURENOW_FIREWALL_TCP', false),
-    iptables: boolEnv('SECURENOW_FIREWALL_IPTABLES', false),
-    cloud: env('SECURENOW_FIREWALL_CLOUD') || null,
-    cloudDryRun: boolEnv('SECURENOW_FIREWALL_CLOUD_DRY_RUN', false),
+    apiUrl,
+    apiUrlFallbacks: resolveFirewallApiFallbacks(apiUrl),
+    versionCheckInterval: numberConfig('firewall.versionCheckInterval', 10, 1),
+    syncInterval: numberConfig('firewall.syncInterval', 3600, 1),
+    failMode: configValue('firewall.failMode', 'open') || 'open',
+    statusCode: numberConfig('firewall.statusCode', 403, 100),
+    log: boolConfig('firewall.log', true),
+    tcp: boolConfig('firewall.tcp', false),
+    iptables: boolConfig('firewall.iptables', false),
+    cloud: configValue('firewall.cloud', null) || null,
+    cloudDryRun: boolConfig('firewall.cloudDryRun', false),
     cloudflare: {
-      apiToken: env('CLOUDFLARE_API_TOKEN') || null,
-      accountId: env('CLOUDFLARE_ACCOUNT_ID') || null,
+      apiToken: resolveConfigPath('firewall.cloudflare.apiToken', [], null) || null,
+      accountId: resolveConfigPath('firewall.cloudflare.accountId', [], null) || null,
     },
     aws: {
-      wafIpSetId: env('AWS_WAF_IP_SET_ID') || null,
-      wafIpSetName: env('AWS_WAF_IP_SET_NAME') || 'securenow-blocklist',
-      wafScope: env('AWS_WAF_SCOPE') || 'REGIONAL',
+      wafIpSetId: resolveConfigPath('firewall.aws.wafIpSetId', [], null) || null,
+      wafIpSetName: resolveConfigPath('firewall.aws.wafIpSetName', [], 'securenow-blocklist') || 'securenow-blocklist',
+      wafScope: resolveConfigPath('firewall.aws.wafScope', [], 'REGIONAL') || 'REGIONAL',
     },
     gcp: {
-      projectId: env('GCP_PROJECT_ID') || null,
-      securityPolicy: env('GCP_SECURITY_POLICY') || null,
+      projectId: resolveConfigPath('firewall.gcp.projectId', [], null) || null,
+      securityPolicy: resolveConfigPath('firewall.gcp.securityPolicy', [], null) || null,
     },
   };
 }
@@ -707,6 +797,9 @@ 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,
   DEFAULT_CONFIG,
@@ -715,12 +808,17 @@ module.exports = {
   withCredentialDefaults,
   mergeCredentials,
   resolveConfigPath,
+  configValue,
+  boolConfig,
+  numberConfig,
+  listConfig,
   resolveAppKey,
   resolveAppName,
   resolveAppId,
   resolveApiKey,
   resolveInstance,
   normalizeDeploymentEnvironment,
+  legacyEnvFallbackEnabled,
   resolveDeploymentEnvironment,
   resolveAll,
   resolveNoUuid,
@@ -728,12 +826,17 @@ module.exports = {
   resolveOtlpHeaderString,
   resolveEndpoints,
   resolveFirewallEnabled,
+  normalizeFirewallApiUrl,
+  resolveFirewallApiUrl,
+  resolveFirewallApiFallbacks,
   resolveFirewallOptions,
   env,
   boolEnv,
   numberEnv,
   listEnv,
   parseHeaders,
+  normalizeInstanceEndpoint,
+  normalizeSignalEndpoint,
   headersToString,
   credentialRelativePaths,
   resolveLocalCredentialsFile,