securenow 7.5.1 → 7.6.0

package/app-config.js

@@ -1,35 +1,12 @@
 'use strict';
 
 /**
- * Shared app-configuration resolver.
+ * Shared SecureNow configuration resolver.
  *
- * Used by both the SDK (tracing.js, nextjs.js, nuxt-server-plugin.mjs) and
- * the CLI to answer three questions with a single source of truth:
- *
- *   - What is the app routing key?  (resolveAppKey) — used as OTel service.name
- *                                     AND as x-api-key header. The collector
- *                                     filters ClickHouse queries by
- *                                     `resource_string_service$$name IN (...)`
- *                                     so service.name MUST be the app.key UUID.
- *   - 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):
- *
- *   1. Explicit environment variable
- *      (SECURENOW_APPID / SECURENOW_API_KEY / SECURENOW_INSTANCE)
- *   2. Project-local credentials  (./.securenow/credentials.json)
- *   3. Global credentials         (~/.securenow/credentials.json)
- *   4. package.json#name (for the human label only — can't route on this)
- *   5. Hard default / null
- *
- * Credentials file schema:
- *   { token, email, expiresAt, apiKey: <snk_live_...>, app: { key, name, instance } }
+ * Local development and production are driven by ./.securenow/credentials.json.
+ * 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.
  */
 
 const fs = require('fs');
@@ -37,6 +14,147 @@ const path = require('path');
 const os = require('os');
 
 const FREE_TRIAL_INSTANCE = 'https://freetrial.securenow.ai:4318';
+const DEFAULT_API_URL = 'https://api.securenow.ai';
+const CONFIG_SCHEMA_VERSION = 2;
+
+const DEFAULT_CONFIG = Object.freeze({
+  logging: {
+    enabled: true,
+  },
+  capture: {
+    body: true,
+    multipart: true,
+    maxBodySize: 10240,
+    sensitiveFields: [],
+  },
+  otel: {
+    endpoint: null,
+    tracesEndpoint: null,
+    logsEndpoint: null,
+    headers: {},
+    logLevel: 'none',
+    disableInstrumentations: [],
+  },
+  runtime: {
+    deploymentEnvironment: 'production',
+    noUuid: null,
+    strict: false,
+    testSpan: false,
+    hideBanner: false,
+  },
+  firewall: {
+    enabled: true,
+    apiUrl: DEFAULT_API_URL,
+    versionCheckInterval: 10,
+    syncInterval: 300,
+    failMode: 'open',
+    statusCode: 403,
+    log: true,
+    tcp: false,
+    iptables: false,
+    cloud: null,
+    cloudDryRun: false,
+    cloudflare: {
+      apiToken: null,
+      accountId: null,
+    },
+    aws: {
+      wafIpSetId: null,
+      wafIpSetName: 'securenow-blocklist',
+      wafScope: 'REGIONAL',
+    },
+    gcp: {
+      projectId: null,
+      securityPolicy: null,
+    },
+  },
+  networking: {
+    trustedProxies: [],
+  },
+});
+
+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.',
+  '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.',
+  '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.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.',
+  'config.otel.logLevel': 'OpenTelemetry diagnostic log level: none, error, warn, info, or debug.',
+  'config.otel.disableInstrumentations': 'Optional OTel instrumentation package names to disable.',
+  'config.runtime.deploymentEnvironment': 'deployment.environment resource attribute. Set this in the credentials file for production.',
+  'config.runtime.noUuid': 'null means auto: true when app.key is present. Set true/false only for advanced routing needs.',
+  '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.versionCheckInterval': 'Seconds between lightweight firewall version checks.',
+  'config.firewall.syncInterval': 'Seconds between full firewall blocklist syncs.',
+  'config.firewall.failMode': 'open allows traffic if SecureNow is temporarily unreachable; closed blocks all on sync failure.',
+  'config.firewall.statusCode': 'HTTP status returned by application-layer firewall blocks.',
+  'config.firewall.log': 'Log firewall decisions locally.',
+  'config.firewall.tcp': 'Layer 2 TCP drop. Default false because it patches sockets.',
+  'config.firewall.iptables': 'Layer 3 OS firewall. Default false because it requires Linux root/CAP_NET_ADMIN.',
+  'config.firewall.cloud': 'Layer 4 WAF provider: cloudflare, aws, gcp, or null.',
+  'config.firewall.cloudDryRun': 'Log intended cloud WAF pushes without applying them.',
+  'config.firewall.cloudflare': 'Cloudflare API token/account id for Layer 4 WAF. Secrets: do not commit.',
+  'config.firewall.aws': 'AWS WAF IP set configuration for Layer 4 WAF.',
+  'config.firewall.gcp': 'GCP Cloud Armor policy configuration for Layer 4 WAF.',
+  'config.networking.trustedProxies': 'Additional proxy IPs whose X-Forwarded-For headers should be trusted.',
+});
+
+const ENV_TO_CONFIG_PATH = Object.freeze({
+  SECURENOW_LOGGING_ENABLED: 'logging.enabled',
+  SECURENOW_CAPTURE_BODY: 'capture.body',
+  SECURENOW_CAPTURE_MULTIPART: 'capture.multipart',
+  SECURENOW_MAX_BODY_SIZE: 'capture.maxBodySize',
+  SECURENOW_SENSITIVE_FIELDS: 'capture.sensitiveFields',
+  SECURENOW_DISABLE_INSTRUMENTATIONS: 'otel.disableInstrumentations',
+  OTEL_EXPORTER_OTLP_ENDPOINT: 'otel.endpoint',
+  OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: 'otel.tracesEndpoint',
+  OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: 'otel.logsEndpoint',
+  OTEL_EXPORTER_OTLP_HEADERS: 'otel.headers',
+  OTEL_LOG_LEVEL: 'otel.logLevel',
+  SECURENOW_ENVIRONMENT: 'runtime.deploymentEnvironment',
+  SECURENOW_DEPLOYMENT_ENVIRONMENT: 'runtime.deploymentEnvironment',
+  NODE_ENV: 'runtime.deploymentEnvironment',
+  SECURENOW_NO_UUID: 'runtime.noUuid',
+  SECURENOW_STRICT: 'runtime.strict',
+  SECURENOW_TEST_SPAN: 'runtime.testSpan',
+  SECURENOW_HIDE_BANNER: 'runtime.hideBanner',
+  SECURENOW_FIREWALL_ENABLED: 'firewall.enabled',
+  SECURENOW_API_URL: 'firewall.apiUrl',
+  SECURENOW_FIREWALL_VERSION_INTERVAL: 'firewall.versionCheckInterval',
+  SECURENOW_FIREWALL_SYNC_INTERVAL: 'firewall.syncInterval',
+  SECURENOW_FIREWALL_FAIL_MODE: 'firewall.failMode',
+  SECURENOW_FIREWALL_STATUS_CODE: 'firewall.statusCode',
+  SECURENOW_FIREWALL_LOG: 'firewall.log',
+  SECURENOW_FIREWALL_TCP: 'firewall.tcp',
+  SECURENOW_FIREWALL_IPTABLES: 'firewall.iptables',
+  SECURENOW_FIREWALL_CLOUD: 'firewall.cloud',
+  SECURENOW_FIREWALL_CLOUD_DRY_RUN: 'firewall.cloudDryRun',
+  CLOUDFLARE_API_TOKEN: 'firewall.cloudflare.apiToken',
+  CLOUDFLARE_ACCOUNT_ID: 'firewall.cloudflare.accountId',
+  AWS_WAF_IP_SET_ID: 'firewall.aws.wafIpSetId',
+  AWS_WAF_IP_SET_NAME: 'firewall.aws.wafIpSetName',
+  AWS_WAF_SCOPE: 'firewall.aws.wafScope',
+  GCP_PROJECT_ID: 'firewall.gcp.projectId',
+  GCP_SECURITY_POLICY: 'firewall.gcp.securityPolicy',
+  SECURENOW_TRUSTED_PROXIES: 'networking.trustedProxies',
+});
+
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
 
 function readJsonSafe(filepath) {
   try {
@@ -49,7 +167,7 @@ function readJsonSafe(filepath) {
 function loadLocalCredentials() {
   try {
     const cwd = typeof process !== 'undefined' && process.cwd ? process.cwd() : '.';
-    return readJsonSafe(path.join(cwd, '.securenow', 'credentials.json'));
+    return withCredentialDefaults(readJsonSafe(path.join(cwd, '.securenow', 'credentials.json')));
   } catch {
     return null;
   }
@@ -57,14 +175,21 @@ function loadLocalCredentials() {
 
 function loadGlobalCredentials() {
   try {
-    return readJsonSafe(path.join(os.homedir(), '.securenow', 'credentials.json'));
+    return withCredentialDefaults(readJsonSafe(path.join(os.homedir(), '.securenow', 'credentials.json')));
   } catch {
     return null;
   }
 }
 
 function loadCredentials() {
-  return loadLocalCredentials() || loadGlobalCredentials() || null;
+  try {
+    const cwd = typeof process !== 'undefined' && process.cwd ? process.cwd() : '.';
+    const local = readJsonSafe(path.join(cwd, '.securenow', 'credentials.json'));
+    const global = readJsonSafe(path.join(os.homedir(), '.securenow', 'credentials.json'));
+    return withCredentialDefaults(mergeCredentials(global, local));
+  } catch {
+    return loadLocalCredentials() || loadGlobalCredentials() || null;
+  }
 }
 
 function loadPackageJsonName() {
@@ -78,70 +203,236 @@ function loadPackageJsonName() {
   return null;
 }
 
+function mergeMissing(target, defaults) {
+  const out = target && typeof target === 'object' && !Array.isArray(target) ? clone(target) : {};
+  for (const [key, value] of Object.entries(defaults || {})) {
+    if (out[key] === undefined) {
+      out[key] = clone(value);
+    } else if (
+      value &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      out[key] &&
+      typeof out[key] === 'object' &&
+      !Array.isArray(out[key])
+    ) {
+      out[key] = mergeMissing(out[key], value);
+    }
+  }
+  return out;
+}
+
+function deepOverlay(base, overlay) {
+  if (!base || typeof base !== 'object' || Array.isArray(base)) base = {};
+  if (!overlay || typeof overlay !== 'object' || Array.isArray(overlay)) return clone(base);
+
+  const out = clone(base);
+  for (const [key, value] of Object.entries(overlay)) {
+    if (value === undefined) continue;
+    if (
+      value &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      out[key] &&
+      typeof out[key] === 'object' &&
+      !Array.isArray(out[key])
+    ) {
+      out[key] = deepOverlay(out[key], value);
+    } else {
+      out[key] = clone(value);
+    }
+  }
+  return out;
+}
+
+function mergeCredentials(globalCredentials, localCredentials) {
+  if (!globalCredentials && !localCredentials) return null;
+  return deepOverlay(globalCredentials || {}, localCredentials || {});
+}
+
+function withCredentialDefaults(credentials) {
+  if (!credentials || typeof credentials !== 'object') return null;
+  const out = clone(credentials);
+  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.',
+    explanations: CONFIG_EXPLANATIONS,
+  });
+  return out;
+}
+
+function getPath(obj, dotted) {
+  if (!obj || !dotted) return undefined;
+  let cur = obj;
+  for (const part of dotted.split('.')) {
+    if (!cur || typeof cur !== 'object' || !(part in cur)) return undefined;
+    cur = cur[part];
+  }
+  return cur;
+}
+
+function rawEnv(key) {
+  return process.env[key] ?? process.env[key.toUpperCase()] ?? process.env[key.toLowerCase()];
+}
+
 function pick(value) {
   if (value === undefined || value === null) return null;
-  const str = String(value).trim();
-  return str.length > 0 ? str : null;
+  if (typeof value === 'string') {
+    const str = value.trim();
+    return str.length > 0 ? str : null;
+  }
+  return value;
 }
 
-// Routing key = app.key UUID. This is what the collector filters on.
-// Also used as x-api-key header once the collector supports it.
-function resolveAppKey() {
-  const fromEnv =
-    pick(process.env.SECURENOW_APPID) ||
-    pick(process.env.SECURENOW_API_KEY) ||
-    pick(process.env.securenow);
-  if (fromEnv) return fromEnv;
+function parseBool(value, fallback = false) {
+  if (value === undefined || value === null || value === '') return fallback;
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') return value !== 0;
+  const text = String(value).trim().toLowerCase();
+  if (['0', 'false', 'no', 'off', 'disabled'].includes(text)) return false;
+  if (['1', 'true', 'yes', 'on', 'enabled'].includes(text)) return true;
+  return fallback;
+}
+
+function parseNumber(value, fallback, min) {
+  const n = Number.parseInt(value, 10);
+  const resolved = Number.isFinite(n) ? n : fallback;
+  return typeof min === 'number' ? Math.max(min, resolved) : resolved;
+}
+
+function parseList(value) {
+  if (Array.isArray(value)) return value.map(String).map((s) => s.trim()).filter(Boolean);
+  if (value == null || value === '') return [];
+  return String(value).split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+function normalizeDeploymentEnvironment(value) {
+  const raw = pick(value);
+  if (raw == null) return 'production';
+  const text = String(raw).trim().toLowerCase();
+  if (text === 'dev' || text === 'development') return 'local';
+  if (text === 'prod') return 'production';
+  if (!/^[a-z0-9_.-]{1,64}$/.test(text)) return 'production';
+  return text;
+}
+
+function parseHeaders(value) {
+  const out = {};
+  if (!value) return out;
+
+  if (typeof value === 'object' && !Array.isArray(value)) {
+    for (const [key, rawValue] of Object.entries(value)) {
+      const k = String(key).trim().toLowerCase();
+      const v = pick(rawValue);
+      if (k && v != null) out[k] = String(v);
+    }
+    return out;
+  }
+
+  for (const raw of String(value).split(',')) {
+    const s = raw.trim();
+    if (!s) continue;
+    const i = s.indexOf('=');
+    if (i === -1) continue;
+    const key = s.slice(0, i).trim().toLowerCase();
+    const val = s.slice(i + 1).trim();
+    if (key && val) out[key] = val;
+  }
+  return out;
+}
+
+function headersToString(headers) {
+  if (!headers || typeof headers !== 'object') return '';
+  return Object.entries(headers)
+    .filter(([, value]) => pick(value) != null)
+    .map(([key, value]) => `${key}=${value}`)
+    .join(',');
+}
+
+function toEnvString(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (typeof value === 'boolean') return value ? '1' : '0';
+  if (Array.isArray(value)) return value.join(',');
+  if (typeof value === 'object') return headersToString(value);
+  return String(value);
+}
 
+function resolveConfigPath(configPath, envKeys = [], fallback) {
   const creds = loadCredentials();
-  if (creds && creds.app && pick(creds.app.key)) return pick(creds.app.key);
+  const fromCreds = pick(getPath(creds && creds.config, configPath));
+  if (fromCreds != null) return fromCreds;
+
+  for (const key of envKeys) {
+    const fromEnv = pick(rawEnv(key));
+    if (fromEnv != null) return fromEnv;
+  }
+
+  const fromDefault = pick(getPath(DEFAULT_CONFIG, configPath));
+  if (fromDefault != null) return fromDefault;
+
+  return fallback;
+}
+
+function resolveAppKey() {
+  const creds = loadCredentials();
+  if (creds && creds.app && pick(creds.app.key)) return String(pick(creds.app.key));
+
+  const fromEnv = pick(rawEnv('SECURENOW_APPID')) || pick(rawEnv('securenow'));
+  if (fromEnv) return String(fromEnv);
+
+  // Legacy compatibility: older docs sometimes used SECURENOW_API_KEY as the
+  // app routing UUID. Real firewall keys start with snk_live_ and are handled
+  // by resolveApiKey(), not as service.name.
+  const legacyApiKey = pick(rawEnv('SECURENOW_API_KEY'));
+  if (legacyApiKey && !String(legacyApiKey).startsWith('snk_live_')) {
+    return String(legacyApiKey);
+  }
+
   return null;
 }
 
-// Human label for observability tools — never touches collector routing.
-// Falls back to package.json#name so pre-login users still see something readable.
 function resolveAppName() {
-  const fromEnv = pick(process.env.OTEL_SERVICE_NAME);
-  if (fromEnv) return fromEnv;
-
   const creds = loadCredentials();
-  if (creds && creds.app && pick(creds.app.name)) return pick(creds.app.name);
+  if (creds && creds.app && pick(creds.app.name)) return String(pick(creds.app.name));
+
+  const fromEnv = pick(rawEnv('OTEL_SERVICE_NAME'));
+  if (fromEnv) return String(fromEnv);
 
   return loadPackageJsonName();
 }
 
-// Legacy alias — callers that want "whatever identifies this process to OTel"
-// get the routing key if logged in, otherwise the human label fallback.
 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;
+  if (fromCreds && String(fromCreds).startsWith('snk_live_')) return String(fromCreds);
+
+  const fromEnv = pick(rawEnv('SECURENOW_API_KEY'));
+  if (fromEnv && String(fromEnv).startsWith('snk_live_')) return String(fromEnv);
 
   return null;
 }
 
 function resolveInstance() {
-  const fromEnv =
-    pick(process.env.SECURENOW_INSTANCE) ||
-    pick(process.env.securenow_instance) ||
-    pick(process.env.OTEL_EXPORTER_OTLP_ENDPOINT);
-  if (fromEnv) return fromEnv.replace(/\/$/, '');
+  const fromConfig = pick(resolveConfigPath('otel.endpoint'));
+  if (fromConfig) return String(fromConfig).replace(/\/$/, '');
 
   const creds = loadCredentials();
   if (creds && creds.app && pick(creds.app.instance)) {
-    return pick(creds.app.instance).replace(/\/$/, '');
+    return String(pick(creds.app.instance)).replace(/\/$/, '');
   }
+
+  const fromEnv =
+    pick(rawEnv('SECURENOW_INSTANCE')) ||
+    pick(rawEnv('securenow_instance')) ||
+    pick(rawEnv('OTEL_EXPORTER_OTLP_ENDPOINT'));
+  if (fromEnv) return String(fromEnv).replace(/\/$/, '');
+
   return FREE_TRIAL_INSTANCE;
 }
 
@@ -150,46 +441,151 @@ function resolveAll() {
   return {
     appKey,
     appName: resolveAppName(),
-    // service.name must be the routing UUID when available — that's what the
-    // collector filters on. Fall back to the human label pre-login.
     appId: appKey || resolveAppName(),
     instance: resolveInstance(),
+    deploymentEnvironment: resolveDeploymentEnvironment(),
   };
 }
 
-// Decide whether to append a per-worker UUID suffix to service.name.
-//
-// The dashboard filters traces with an exact match on service.name
-// (`resource_string_service$$name IN (...)`), so when appId IS the routing
-// UUID (customer is logged in → credentials file provides app.key), the
-// suffix guarantees a miss. Per-worker disambiguation still happens via
-// service.instance.id, which is never used for filtering.
-//
-// Precedence:
-//   1. Explicit opts.noUuid (caller passed it)                  — wins
-//   2. Explicit SECURENOW_NO_UUID env var (0/1/true/false)      — wins
-//   3. appKey resolved (logged-in, appId is routing UUID)       → true
-//   4. Otherwise (pre-login, appId = package.json#name)         → false
+function resolveDeploymentEnvironment() {
+  return normalizeDeploymentEnvironment(
+    resolveConfigPath('runtime.deploymentEnvironment', [
+      'SECURENOW_ENVIRONMENT',
+      'SECURENOW_DEPLOYMENT_ENVIRONMENT',
+      'NODE_ENV',
+    ])
+  );
+}
+
 function resolveNoUuid(opts = {}) {
   if (opts.noUuid !== undefined && opts.noUuid !== null) return !!opts.noUuid;
 
-  const raw = process.env.SECURENOW_NO_UUID;
-  if (raw !== undefined && raw !== '') {
-    return /^(1|true)$/i.test(String(raw).trim());
-  }
+  const fromConfig = pick(getPath(loadCredentials()?.config, 'runtime.noUuid'));
+  if (fromConfig !== null) return parseBool(fromConfig, false);
+
+  const raw = pick(rawEnv('SECURENOW_NO_UUID'));
+  if (raw !== null) return parseBool(raw, false);
 
   return !!resolveAppKey();
 }
 
+function resolveEnvKey(key) {
+  const upper = String(key).toUpperCase();
+
+  if (upper === 'SECURENOW_APPID') return resolveAppKey();
+  if (upper === 'OTEL_SERVICE_NAME') return resolveAppName();
+  if (upper === 'SECURENOW_API_KEY') return resolveApiKey();
+  if (upper === 'SECURENOW_INSTANCE' || upper === 'OTEL_EXPORTER_OTLP_ENDPOINT') return resolveInstance();
+
+  const configPath = ENV_TO_CONFIG_PATH[upper];
+  if (configPath) return resolveConfigPath(configPath);
+
+  const fromEnv = pick(rawEnv(upper));
+  if (fromEnv != null) return fromEnv;
+
+  return undefined;
+}
+
+function env(key) {
+  return toEnvString(resolveEnvKey(key));
+}
+
+function boolEnv(key, fallback = false) {
+  return parseBool(resolveEnvKey(key), fallback);
+}
+
+function numberEnv(key, fallback, min) {
+  return parseNumber(resolveEnvKey(key), fallback, min);
+}
+
+function listEnv(key) {
+  return parseList(resolveEnvKey(key));
+}
+
+function resolveOtlpHeaders() {
+  const headers = parseHeaders(resolveConfigPath('otel.headers', ['OTEL_EXPORTER_OTLP_HEADERS'], {}));
+  const appKey = resolveAppKey();
+  if (appKey && !headers['x-api-key']) {
+    headers['x-api-key'] = appKey;
+  }
+  return headers;
+}
+
+function resolveOtlpHeaderString() {
+  return headersToString(resolveOtlpHeaders());
+}
+
+function resolveEndpoints(options = {}) {
+  const endpointBase = String(options.endpoint || resolveInstance()).replace(/\/$/, '');
+  return {
+    endpointBase,
+    tracesUrl: env('OTEL_EXPORTER_OTLP_TRACES_ENDPOINT') || `${endpointBase}/v1/traces`,
+    logsUrl: env('OTEL_EXPORTER_OTLP_LOGS_ENDPOINT') || `${endpointBase}/v1/logs`,
+    headers: resolveOtlpHeaders(),
+  };
+}
+
+function resolveFirewallOptions() {
+  return {
+    apiKey: resolveApiKey(),
+    appKey: resolveAppKey() || null,
+    environment: resolveDeploymentEnvironment(),
+    enabled: boolEnv('SECURENOW_FIREWALL_ENABLED', true),
+    apiUrl: env('SECURENOW_API_URL') || DEFAULT_API_URL,
+    versionCheckInterval: numberEnv('SECURENOW_FIREWALL_VERSION_INTERVAL', 10, 1),
+    syncInterval: numberEnv('SECURENOW_FIREWALL_SYNC_INTERVAL', 300, 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),
+    cloudflare: {
+      apiToken: env('CLOUDFLARE_API_TOKEN') || null,
+      accountId: env('CLOUDFLARE_ACCOUNT_ID') || 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',
+    },
+    gcp: {
+      projectId: env('GCP_PROJECT_ID') || null,
+      securityPolicy: env('GCP_SECURITY_POLICY') || null,
+    },
+  };
+}
+
 module.exports = {
   FREE_TRIAL_INSTANCE,
+  DEFAULT_API_URL,
+  CONFIG_SCHEMA_VERSION,
+  DEFAULT_CONFIG,
+  CONFIG_EXPLANATIONS,
+  ENV_TO_CONFIG_PATH,
+  withCredentialDefaults,
+  mergeCredentials,
+  resolveConfigPath,
   resolveAppKey,
   resolveAppName,
   resolveAppId,
   resolveApiKey,
   resolveInstance,
+  normalizeDeploymentEnvironment,
+  resolveDeploymentEnvironment,
   resolveAll,
   resolveNoUuid,
+  resolveOtlpHeaders,
+  resolveOtlpHeaderString,
+  resolveEndpoints,
+  resolveFirewallOptions,
+  env,
+  boolEnv,
+  numberEnv,
+  listEnv,
+  parseHeaders,
+  headersToString,
   loadCredentials,
   loadLocalCredentials,
   loadGlobalCredentials,

package/cli/apiKey.js

@@ -45,7 +45,7 @@ async function clear(args, flags) {
 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.');
+    ui.info('No API key stored in credentials. Run `npx securenow login` or `npx securenow api-key set snk_live_...`.');
     return;
   }
   console.log(maskKey(key));

package/cli/apps.js

@@ -242,7 +242,7 @@ async function info(args, flags) {
 
     console.log('');
     console.log(`  ${ui.c.bold('Use in current project:')}   ${ui.c.bold(`securenow apps default ${app.key}`)}`);
-    console.log(`  ${ui.c.bold('Or override via env:')}       ${ui.c.dim(`SECURENOW_APPID=${app.key} SECURENOW_INSTANCE=${envUrl}`)}`);
+    console.log(`  ${ui.c.bold('Or for CI/prod env:')}       ${ui.c.dim(`SECURENOW_APPID=${app.key} SECURENOW_INSTANCE=${envUrl}`)}`);
     console.log('');
   } catch (err) {
     s.fail('Failed to fetch application');