securenow 8.24.0 → 8.25.1

package/register.d.ts

@@ -1,61 +1,54 @@
 /**
  * SecureNow Register Module TypeScript Declarations
- * 
- * Main entry point for Node.js/Express/Fastify/NestJS applications.
- * This module is automatically loaded when using NODE_OPTIONS="-r securenow/register"
+ *
+ * Preload for Node.js servers (Express, Fastify, NestJS, Koa, Hapi, Hono, Polka, Feathers, h3,
+ * raw node:http): `node -r securenow/register <entry>`. It starts tracing, logs, body capture,
+ * the firewall and (when configured) session revocation before the app loads.
  */
 
 /**
- * Configuration:
- *
- * Local development reads .securenow/credentials.json. Run
- * `npx securenow login` to choose/create an app, then `npx securenow init`
- * to ensure secure defaults and explanations are present.
- *
- * Production uses the same file shape. Run
- * `npx securenow credentials runtime --env production`, then mount/copy the
- * generated JSON to .securenow/credentials.json in the running app.
+ * Configuration: .securenow/runtime.json, written by `npx securenow login`; `npx securenow init`
+ * adds the secure defaults with explanations.
  *
- * Legacy env vars are fallback-only for existing installs.
+ * Production: `npx securenow credentials runtime --env production`, then mount/copy the file to
+ * .securenow/credentials.json in the running app, or store the `--format env` output
+ * (SECURENOW_CREDENTIALS) as a secret environment variable on hosts without file mounts.
+ * SECURENOW_DISABLED=1 turns the SDK off (tests).
  */
 
 // This module has side effects (initializes OpenTelemetry)
-// It's typically used via NODE_OPTIONS, not imported directly
+// It's typically preloaded with -r, not imported
 export {};
 
 /**
  * @example
  * ```bash
- * # Using with Node.js preload
- * NODE_OPTIONS="-r securenow/register" node app.js
+ * # Preload (CommonJS, ESM and TypeScript alike)
+ * node -r securenow/register app.js
+ * node -r securenow/register --import tsx src/index.ts
+ * NODE_OPTIONS="-r securenow/register" npm start
  * ```
- * 
- * @example
- * ```bash
- * # Using with PM2
- * pm2 start app.js --node-args="-r securenow/register"
- * ```
- * 
+ *
  * @example
  * ```javascript
- * // ecosystem.config.js
+ * // ecosystem.config.cjs (PM2, fork or cluster mode)
  * module.exports = {
  *   apps: [{
  *     name: 'my-app',
  *     script: './app.js',
- *     node_args: '-r securenow/register',
- *     // Local and production use .securenow/credentials.json.
+ *     // An absolute path: a bare '-r securenow/register' is resolved from the PM2 daemon's
+ *     // folder in cluster mode, and the workers crash-loop with "Cannot find module".
+ *     node_args: ['-r', require.resolve('securenow/register')],
+ *     instances: 'max',
+ *     exec_mode: 'cluster',
  *   }]
  * };
  * ```
- * 
+ *
  * @example
- * ```typescript
- * // Explicit import (optional, mainly for side effects)
- * import 'securenow/register';
- * 
- * import express from 'express';
- * const app = express();
- * // Your app code...
+ * ```javascript
+ * // First line of a CommonJS entry (alternative to -r)
+ * require('securenow/register');
+ * const express = require('express');
  * ```
  */

package/request-capture.js

@@ -44,18 +44,21 @@ const DEFAULT_SENSITIVE_FIELDS = [
 // and they only ever transform captured telemetry strings (read-only) — never
 // the actual request/response stream. Compiled once at module load.
 const VALUE_REDACTORS = [
+  // The JWT and email patterns only start where a run of their characters starts (the
+  // lookbehind), so a long run that holds no match is scanned once, not once per position:
+  // a crafted 10KB value costs microseconds, not 50ms+ of event loop.
   // JWT: three base64url segments. Anchored to the eyJ header so it won't
   // match arbitrary dotted tokens.
-  { name: 'jwt', re: /eyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}/g },
+  { name: 'jwt', hint: 'eyJ', re: /(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}/g },
   // Bearer/Basic auth header value embedded in a body string.
   { name: 'bearer', re: /\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi },
   // Stripe-style / SecureNow live+test API keys.
   { name: 'apikey', re: /\b(?:sk|pk|rk|snk)_(?:live|test)_[A-Za-z0-9]{8,}/g },
-  // Email addresses (bounded local/domain parts).
-  { name: 'email', re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,24}\b/g },
+  // Email addresses (bounded local/domain parts: 64 and 253 characters at most).
+  { name: 'email', hint: '@', re: /(?<![\w.%+-])[\w.%+-]{1,64}@[A-Za-z0-9.-]{1,253}\.[A-Za-z]{2,24}\b/g },
   // Credit-card-like: 13–19 digit runs that pass a Luhn check, allowing
   // space/dash grouping. Luhn-gated to avoid clobbering ordinary long numbers.
-  { name: 'card', re: /\b(?:\d[ -]?){13,19}\b/g, luhn: true },
+  { name: 'card', re: /\b(?:\d[ -]?){12,18}\d\b/g, luhn: true },
 ];
 
 // Skip the value-shape scan on very large strings to bound per-body cost.
@@ -77,15 +80,17 @@ function luhnValid(digits) {
 /**
  * Redact obvious secret/PII shapes inside a captured string VALUE.
  * Returns the input unchanged when nothing matches (cheap common case).
+ * maxScanLength: longer values skip the shape scan (log lines pass a larger bound).
  */
-function redactSensitiveValue(value) {
+function redactSensitiveValue(value, maxScanLength = MAX_VALUE_SCAN_LENGTH) {
   if (typeof value !== 'string' || value.length === 0) return value;
   // Credential assignments in GraphQL/query strings need field-aware
   // redaction even though a short numeric OTP has no unique value shape.
   value = redactOtpQuery(redactOtpGraphQL(value));
-  if (value.length > MAX_VALUE_SCAN_LENGTH) return value; // bound shape scans
+  if (value.length > maxScanLength) return value; // bound shape scans
   let out = value;
   for (const r of VALUE_REDACTORS) {
+    if (r.hint && !out.includes(r.hint)) continue;
     r.re.lastIndex = 0;
     if (r.luhn) {
       out = out.replace(r.re, (m) => {

package/resolve-ip.js

@@ -7,17 +7,19 @@ const { createMatcher } = require('./cidr');
 const LOOPBACK_RE = /^(127\.|::1$|::ffff:127\.)/;
 const PRIVATE_IP_RE = /^(127\.|::1$|10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.|169\.254\.|100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.|f[cd][0-9a-f]{2}:)/i;
 
-// Named proxy presets for config.networking.trustedProxies. Cloudflare's published IPv4 edge ranges
-// (https://www.cloudflare.com/ips-v4): an app behind Cloudflare trusts them with "cloudflare".
+// Named proxy presets for config.networking.trustedProxies. Cloudflare's published edge ranges
+// (https://www.cloudflare.com/ips-v4 and /ips-v6): an app behind Cloudflare trusts them with "cloudflare".
 const PROXY_PRESETS = {
   cloudflare: [
     '173.245.48.0/20', '103.21.244.0/22', '103.22.200.0/22', '103.31.4.0/22', '141.101.64.0/18',
     '108.162.192.0/18', '190.93.240.0/20', '188.114.96.0/20', '197.234.240.0/22', '198.41.128.0/17',
     '162.158.0.0/15', '104.16.0.0/13', '104.24.0.0/14', '172.64.0.0/13', '131.0.72.0/22',
+    '2400:cb00::/32', '2606:4700::/32', '2803:f800::/32', '2405:b500::/32', '2405:8100::/32',
+    '2a06:98c0::/29', '2c0f:f248::/32',
   ],
 };
 
-// Exact addresses (IPv4 or IPv6), IPv4 CIDR ranges and presets.
+// Exact addresses and CIDR ranges (IPv4 or IPv6), and presets.
 function trustedProxyMatcher(entries) {
   const expanded = [];
   for (const entry of entries) {
@@ -93,14 +95,30 @@ function getHeader(headers, name) {
   return firstHeaderValue(headers[name] || headers[name.toLowerCase()] || headers[name.toUpperCase()]);
 }
 
+// A request that came over a Unix domain socket or a Windows named pipe has no remote address, and only a
+// process on this machine can connect to one: nginx `proxy_pass http://unix:/run/app.sock`, Nuxt's dev
+// proxy, a local sidecar. Such a connection is a trusted local proxy, so its forwarding headers count
+// (before this, requests over a socket had no client IP at all and IP blocking never applied to them).
+function arrivedOverLocalSocket(request) {
+  const socket = request && request.socket;
+  if (!socket || socket.remoteAddress) return false;
+  try {
+    const server = socket.server || socket._server;
+    return !!server && typeof server.address === 'function' && typeof server.address() === 'string';
+  } catch (_) {
+    return false;
+  }
+}
+
 function resolveClientIpWithDetails(request) {
   const socketIp = normalizeIp(request.socket?.remoteAddress || '');
   const headers = request.headers || {};
-  const trustedProxy = isFromTrustedProxy(socketIp);
+  const viaLocalSocket = !socketIp && arrivedOverLocalSocket(request);
+  const trustedProxy = viaLocalSocket || isFromTrustedProxy(socketIp);
 
   const details = {
     ip: socketIp,
-    source: socketIp ? 'socket' : 'unknown',
+    source: socketIp ? 'socket' : (viaLocalSocket ? 'unix-socket' : 'unknown'),
     socketIp,
     trustedProxy,
     forwardedFor: String(getHeader(headers, 'x-forwarded-for') || ''),

package/sessions.d.ts

@@ -30,6 +30,33 @@ export function guard(options?: GuardOptions): (req: any, res: any, next: any) =
 /** Express-style middleware that ONLY emits session.seen (detection feed, no enforcement). */
 export function capture(options?: GuardOptions): (req: any, res: any, next: any) => void;
 
+export interface CheckOptions {
+  /** Extract the session id. Defaults to the hashed Bearer token or session cookie. */
+  getSessionId?: (req: any) => string | null | undefined;
+  /** Extract the user id. Defaults to the JWT `sub` claim. */
+  getUserId?: (req: any) => string | null | undefined;
+  /** Client IP for session.seen when `req` has no socket (a Web Request). */
+  ip?: string;
+  /** Emit session.seen for detection (default true). */
+  capture?: boolean;
+}
+
+/**
+ * For code that cannot use guard() (Fastify hooks, Koa/Hono middleware, Next.js route handlers, h3):
+ * is this request's session or user revoked? `req` is a Node request or a Web `Request`. Fail-open. (8.25.0+)
+ */
+export function check(req: IncomingMessage | Request | { headers: any }, options?: CheckOptions): {
+  revoked: boolean;
+  sessionId: string | null;
+  userId: string | null;
+};
+
+/**
+ * Zero-code guard/capture for every framework, installed by the SDK from config.sessions.guard /
+ * config.sessions.capture in .securenow/runtime.json. Returns true when it installed the hook. (8.25.0+)
+ */
+export function installHttpGuard(options?: { guard?: boolean; capture?: boolean }): boolean;
+
 /** Resolve the client IP from a request (X-Forwarded-For / CF / socket). */
 export function resolveClientIp(req: any): string | null;
 

package/sessions.js

@@ -4,9 +4,10 @@
 // half of account-takeover response).
 //
 //   const securenow = require('securenow/sessions');
-//   app.use(securenow.guard());           // auto-detects NextAuth/connect.sid/JWT sessions
-//   // ...or check manually in your auth middleware:
-//   if (securenow.isRevoked({ sessionId, userId })) return res.status(401)...
+//   app.use(securenow.guard());           // Express-style; auto-detects NextAuth/connect.sid/JWT sessions
+//   // ...any other framework (Fastify, Koa, Hono, Next.js route handlers, h3):
+//   if (securenow.check(req).revoked) return /* a 401 */;
+//   // ...or no code at all: "sessions": { "guard": true, "capture": true } in .securenow/runtime.json
 //
 // The SDK pulls active revocations from SecureNow (outbound, ETag-cached) and
 // checks each request locally — no inbound webhook, works behind NAT, portable
@@ -150,6 +151,21 @@ const SESSION_COOKIES = [
   'sid',
 ];
 
+// Session cookies: config.sessions.cookieNames first (the app's own), then the defaults.
+function sessionCookieNames() {
+  let extra = [];
+  try { extra = appConfig.listConfig('sessions.cookieNames'); } catch {}
+  return extra.length ? [...extra, ...SESSION_COOKIES] : SESSION_COOKIES;
+}
+
+// A header from a Node request (plain object) or a Web Request (Headers).
+function headerOf(req, name) {
+  const headers = req && req.headers;
+  if (!headers) return '';
+  if (typeof headers.get === 'function') return headers.get(name) || '';
+  return headers[name] || '';
+}
+
 function parseCookies(header) {
   const out = {};
   if (!header) return out;
@@ -165,8 +181,7 @@ function parseCookies(header) {
 function defaultExtract(req) {
   let sessionId = null;
   let userId = null;
-  const headers = req.headers || {};
-  const auth = headers.authorization || headers.Authorization;
+  const auth = headerOf(req, 'authorization') || headerOf(req, 'Authorization');
   if (auth && /^Bearer\s+/i.test(auth)) {
     const token = auth.replace(/^Bearer\s+/i, '').trim();
     if (token) {
@@ -178,9 +193,10 @@ function defaultExtract(req) {
       } catch {}
     }
   }
-  if (!sessionId && headers.cookie) {
-    const cookies = parseCookies(headers.cookie);
-    for (const name of SESSION_COOKIES) {
+  const cookieHeader = headerOf(req, 'cookie');
+  if (!sessionId && cookieHeader) {
+    const cookies = parseCookies(cookieHeader);
+    for (const name of sessionCookieNames()) {
       if (cookies[name]) {
         sessionId = sha256(cookies[name]);
         break;
@@ -255,7 +271,7 @@ function capture(options = {}) {
 
 function defaultOnRevoked(req, res) {
   try {
-    const clears = SESSION_COOKIES.map((n) => `${n}=; Path=/; Max-Age=0; HttpOnly`);
+    const clears = sessionCookieNames().map((n) => `${n}=; Path=/; Max-Age=0; HttpOnly`);
     if (typeof res.setHeader === 'function') res.setHeader('Set-Cookie', clears);
   } catch {}
   if (typeof res.status === 'function' && typeof res.json === 'function') {
@@ -298,4 +314,49 @@ function guard(options = {}) {
   };
 }
 
-module.exports = { start, syncOnce, isRevoked, guard, capture, resolveClientIp, sha256 };
+/**
+ * For code that cannot use guard() (Fastify hooks, Koa or Hono middleware, Next.js route handlers, h3):
+ * is this request's session or user revoked? `req` is a Node request or a Web Request. Feeds
+ * session-theft detection (session.seen) unless options.capture is false. Fail-open.
+ *
+ * @param {object} req
+ * @param {{ getSessionId?: (req)=>string, getUserId?: (req)=>string, ip?: string, capture?: boolean }} [options]
+ * @returns {{ revoked: boolean, sessionId: string|null, userId: string|null }}
+ */
+function check(req, options = {}) {
+  try {
+    if (require('./sdk-disabled').sdkDisabled('sessions check')) return { revoked: false, sessionId: null, userId: null };
+    start(options);
+    const { sessionId, userId } = extractIdentity(req, options.getSessionId, options.getUserId);
+    if (options.capture !== false) emitSessionSeen(sessionId, userId, options.ip || resolveClientIp(req));
+    return { revoked: isRevoked({ sessionId, userId }), sessionId: sessionId || null, userId: userId || null };
+  } catch {
+    return { revoked: false, sessionId: null, userId: null };
+  }
+}
+
+// Zero code, every framework (config.sessions.guard / config.sessions.capture): the firewall's
+// request hook runs this on each incoming request before the app sees it. guard answers a revoked
+// session or user with a 401 and clears the session cookies; capture feeds session-theft detection.
+let _httpGuardInstalled = false;
+function installHttpGuard(options = {}) {
+  const enforce = !!options.guard;
+  const capture = !!options.capture;
+  if ((!enforce && !capture) || _httpGuardInstalled) return false;
+  if (require('./sdk-disabled').sdkDisabled('sessions')) return false;
+  _httpGuardInstalled = true;
+  start(options);
+  require('./firewall').addRequestHook(function securenowSessionHook(req, res) {
+    const { sessionId, userId } = defaultExtract(req);
+    if (!sessionId && !userId) return false;
+    if (capture) emitSessionSeen(sessionId, userId, resolveClientIp(req));
+    if (enforce && isRevoked({ sessionId, userId })) {
+      defaultOnRevoked(req, res);
+      return true;
+    }
+    return false;
+  });
+  return true;
+}
+
+module.exports = { start, syncOnce, isRevoked, guard, capture, check, installHttpGuard, resolveClientIp, sha256 };

package/tracing.d.ts

@@ -1,74 +1,10 @@
 /**
  * SecureNow Tracing Module TypeScript Declarations
- * 
- * Core tracing functionality for Node.js applications.
- * This is typically loaded via register.js, not imported directly.
- */
-
-/**
- * Default sensitive fields that are automatically redacted from request bodies
- */
-export const DEFAULT_SENSITIVE_FIELDS: readonly string[];
-
-/**
- * Redact sensitive fields from an object (recursively)
- * 
- * @param obj - Object to redact (can be nested)
- * @param sensitiveFields - Array of field names to redact (case-insensitive substring match)
- * @returns Redacted copy of the object
- * 
- * @example
- * ```typescript
- * import { redactSensitiveData } from 'securenow/tracing';
- * 
- * const data = {
- *   email: 'user@example.com',
- *   password: 'secret123',
- *   nested: {
- *     api_key: 'sk_live_abc123'
- *   }
- * };
- * 
- * const redacted = redactSensitiveData(data);
- * // Result: {
- * //   email: 'user@example.com',
- * //   password: '[REDACTED]',
- * //   nested: { api_key: '[REDACTED]' }
- * // }
- * ```
- */
-export function redactSensitiveData<T = any>(
-  obj: T,
-  sensitiveFields?: string[]
-): T;
-
-/**
- * Redact sensitive data from GraphQL query strings
- * 
- * @param query - GraphQL query string
- * @param sensitiveFields - Array of field names to redact
- * @returns Redacted query string
- * 
- * @example
- * ```typescript
- * import { redactGraphQLQuery } from 'securenow/tracing';
- * 
- * const query = `
- *   mutation {
- *     login(email: "user@example.com", password: "secret123") {
- *       token
- *     }
- *   }
- * `;
- * 
- * const redacted = redactGraphQLQuery(query);
- * // Result: mutation { login(email: "user@example.com", password: "[REDACTED]") { token } }
- * ```
+ *
+ * Core tracing for Node.js applications. It starts when loaded, usually through
+ * `node -r securenow/register`; import it directly only for the logger API below.
+ * Redaction helpers live in `securenow/nextjs-middleware` and the `securenow redact` CLI.
  */
-export function redactGraphQLQuery(
-  query: string,
-  sensitiveFields?: string[]
-): string;
 
 /**
  * OpenTelemetry Logger interface
@@ -86,19 +22,20 @@ export interface LogRecord {
    * 5 = DEBUG, 9 = INFO, 13 = WARN, 17 = ERROR
    */
   severityNumber: number;
-  
+
   /**
    * Human-readable severity text
    */
   severityText: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | string;
-  
+
   /**
-   * Log message body
+   * Log message body. Secret shapes (JWTs, Bearer credentials, API keys, card numbers, emails,
+   * OTP assignments) are redacted before export unless config.logging.redact is false.
    */
   body: string;
-  
+
   /**
-   * Structured attributes for filtering/searching
+   * Structured attributes for filtering/searching (exported as set)
    */
   attributes?: Record<string, any>;
 }
@@ -112,75 +49,57 @@ export interface LoggerProvider {
 }
 
 /**
- * Get a logger instance for sending structured logs to any OTLP-compatible backend
- * 
- * @param name - Logger name (e.g., 'my-service', 'auth-module')
+ * Get a logger that sends structured logs to SecureNow, correlated with the active trace.
+ *
+ * @param name - Logger name (e.g., 'my-service', 'auth-module'); defaults to 'default'
  * @param version - Logger version (optional, defaults to '1.0.0')
- * @returns Logger instance or null if logging is not enabled
- * 
+ * @returns Logger instance, or null when logging is off (config.logging.enabled=false) or the SDK
+ * did not start (SECURENOW_DISABLED=1)
+ *
  * @example
  * ```typescript
  * import { getLogger } from 'securenow/tracing';
- * 
+ *
  * const logger = getLogger('my-service', '1.0.0');
- * 
- * if (logger) {
- *   logger.emit({
- *     severityNumber: 9,
- *     severityText: 'INFO',
- *     body: 'User logged in',
- *     attributes: {
- *       userId: 123,
- *       username: 'john',
- *     },
- *   });
- * }
+ *
+ * logger?.emit({
+ *   severityNumber: 9,
+ *   severityText: 'INFO',
+ *   body: 'User logged in',
+ *   attributes: { userId: 123 },
+ * });
  * ```
  */
 export function getLogger(name?: string, version?: string): Logger | null;
 
 /**
- * Check if logging is enabled
- * 
- * @returns true when logging resolves enabled from .securenow/credentials.json defaults
- * 
- * @example
- * ```typescript
- * import { isLoggingEnabled } from 'securenow/tracing';
- * 
- * if (isLoggingEnabled()) {
- *   console.log('Logging is enabled');
- * }
- * ```
+ * Whether logs are exported (config.logging.enabled, default true; false when the SDK did not start).
  */
 export function isLoggingEnabled(): boolean;
 
 /**
- * The OpenTelemetry LoggerProvider instance (if logging is enabled)
- * Use getLogger() instead of accessing this directly
+ * The OpenTelemetry LoggerProvider instance (null when logging is off).
+ * Use getLogger() instead of accessing this directly.
  */
 export const loggerProvider: LoggerProvider | null;
 
 /**
- * Configuration:
- *
- * Local development reads .securenow/credentials.json first. Run
- * `npx securenow login` to write app identity/runtime API key and
- * `npx securenow init` to ensure secure defaults and explanations.
+ * Configuration: .securenow/runtime.json, written by `npx securenow login`; `npx securenow init`
+ * adds the secure defaults with explanations.
  *
- * Production uses the same file shape. Run
- * `npx securenow credentials runtime --env production`, then mount/copy the
- * generated JSON to .securenow/credentials.json in the running app.
+ * Production: `npx securenow credentials runtime --env production`, then mount/copy the file to
+ * .securenow/credentials.json in the running app. Hosts without file mounts store
+ * `npx securenow credentials runtime --env production --format env` (SECURENOW_CREDENTIALS) as a
+ * secret environment variable. No other SECURENOW_* variable is read; SECURENOW_DISABLED=1
+ * turns the SDK off (tests).
  *
  * Main config fields:
- * - app.key / app.name
- * - config.otel.endpoint only for advanced/self-hosted collector overrides
- * - apiKey
+ * - app.key / app.name, apiKey (runtime API key)
  * - config.runtime.deploymentEnvironment
- * - config.logging.enabled
+ * - config.logging.enabled / redact
  * - config.capture.body / multipart / maxBodySize / sensitiveFields
- * - config.otel.endpoint / tracesEndpoint / logsEndpoint / headers
- * - config.firewall.enabled and layer/provider options
- *
- * Legacy env vars are fallback-only for existing installs.
+ * - config.otel.endpoint / tracesEndpoint / logsEndpoint / headers (self-hosted collectors only)
+ * - config.networking.trustedProxies
+ * - config.firewall.* (failMode, statusCode, tcp, iptables, cloud, rateLimitStore, ...)
+ * - config.sessions.guard / capture / cookieNames
  */

package/tracing.js

@@ -1,9 +1,12 @@
 'use strict';
 
+// When the SDK does not start, the module still exports its API: getLogger() returns null, as it
+// does with logging disabled, so app code that calls it keeps working under SECURENOW_DISABLED=1.
+const NOT_STARTED = { loggerProvider: null, getLogger: () => null, isLoggingEnabled: () => false };
 // Do nothing inside Node's internal ESM-hooks thread (see internal-thread.js).
-if (require('./internal-thread').inInternalThread()) return;
+if (require('./internal-thread').inInternalThread()) { module.exports = NOT_STARTED; return; }
 // SECURENOW_DISABLED=1 turns the SDK off for this process (test runs).
-if (require('./sdk-disabled').sdkDisabled('tracing')) return;
+if (require('./sdk-disabled').sdkDisabled('tracing')) { module.exports = NOT_STARTED; return; }
 
 /**
  * Preload with: node --require securenow/register app.js
@@ -127,7 +130,7 @@ console.log('[securenow] pid=%d appId=%s instance=%s apiKey=%s credentials=%s
   process.pid,
   JSON.stringify(baseName),
   JSON.stringify(endpointBase),
-  resolvedApp.appKey ? 'set' : 'none',
+  appConfig.resolveApiKey() ? 'set' : 'missing',
   appConfig.describeCredentialsSource(),
   serviceName,
   serviceInstanceId
@@ -239,7 +242,8 @@ if (loggingEnabled) {
   const batchLogProcessor = new BatchLogRecordProcessor({ exporter: logExporter });
   loggerProvider = new LoggerProvider({
     resource: sharedResource,
-    processors: [batchLogProcessor],
+    // Secret shapes in log lines are redacted before export (log-redaction.js).
+    processors: require('./log-redaction').logProcessors(appConfig, batchLogProcessor),
   });
 
   // Auto-patch console.* so every log/warn/error becomes an OTel log record
@@ -348,6 +352,8 @@ const sdk = new NodeSDK({
   instrumentations: [
     httpInstrumentation,
     ...(disabledMap['@opentelemetry/instrumentation-mongodb'] ? [] : [new MongoDBInstrumentation()]),
+    // http.route for Hono, h3, Feathers and Polka (no instrumentation in the OpenTelemetry bundle).
+    ...(disabledMap['securenow-framework-routes'] ? [] : [new (require('./framework-routes').SecureNowRouteInstrumentation)()]),
     ...getNodeAutoInstrumentations({
       ...frameworkInstrumentationConfig,
       ...disabledMap,
@@ -404,6 +410,8 @@ const sdk = new NodeSDK({
         aws: firewallOptions.aws,
         gcp: firewallOptions.gcp,
       });
+      // Zero-code session revocation / session-theft capture (config.sessions.guard / .capture).
+      require('./sessions').installHttpGuard(appConfig.resolveSessionsOptions());
     }
   } catch (e) {
     console.error('[securenow] OTel start failed:', e && e.stack || e);