securenow 8.23.0 → 8.25.0

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
  */