@coffeerunhobby/mcp-ha-connect 1.2.0 → 1.3.0

package/src/server/http.ts

@@ -11,9 +11,11 @@ import type { LocalAIClient } from '../localAI/index.js';
 import type { OmadaClient } from '../omadaClient/index.js';
 import { logger } from '../utils/logger.js';
 import { handleStreamRequest, type StreamTransportState, type StreamTransportOptions } from './stream.js';
-import { handleEventSubscription, getClientCount } from './eventSubscription.js';
+import { handleEventSubscription } from './eventSubscription.js';
 import { RateLimiter } from './rateLimiter.js';
-import { createAuthMiddleware } from './auth.js';
+import { createAuthMiddleware, type AuthenticatedRequest } from './auth.js';
+import { Permission, hasPermission, getPermissionNames } from '../permissions/index.js';
+import { sanitizeError } from '../utils/sanitizeError.js';
 import { VERSION } from '../version.js';
 
 // Session storage for stateful mode
@@ -53,27 +55,83 @@ function wrapResponseWithTiming(res: ServerResponse): { res: ServerResponse; sta
 }
 
 /**
- * Parse JSON body from request
+ * Maximum accepted request body size, in bytes (M5 / OWASP API4:2023).
+ * 1 MB is comfortably above any legitimate MCP/JSON-RPC or REST payload.
  */
-function parseBody(req: IncomingMessage): Promise<unknown> {
+export const MAX_BODY_BYTES = 1024 * 1024;
+
+/** Error carrying an HTTP status for the request handler to surface. */
+interface HttpError extends Error {
+  statusCode?: number;
+}
+
+/**
+ * Parse a JSON request body, enforcing a hard size cap (M5).
+ *
+ * If the streamed body exceeds `maxBytes` the promise rejects with a 413-tagged
+ * error and the socket is destroyed, so an attacker cannot exhaust memory by
+ * streaming an unbounded payload. Buffering stops the moment the cap is crossed.
+ */
+export function parseBody(req: IncomingMessage, maxBytes: number = MAX_BODY_BYTES): Promise<unknown> {
   return new Promise((resolve, reject) => {
-    let body = '';
-    req.on('data', (chunk) => (body += chunk.toString()));
+    const chunks: Buffer[] = [];
+    let size = 0;
+    let aborted = false;
+
+    req.on('data', (chunk: Buffer | string) => {
+      if (aborted) {
+        return;
+      }
+      const buf = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+      size += buf.length;
+      if (size > maxBytes) {
+        aborted = true;
+        const err: HttpError = new Error('Request body too large');
+        err.statusCode = 413;
+        reject(err);
+        req.destroy();
+        return;
+      }
+      chunks.push(buf);
+    });
+
     req.on('end', () => {
-      if (!body) {
+      if (aborted) {
+        return;
+      }
+      if (chunks.length === 0) {
         resolve(undefined);
         return;
       }
       try {
-        resolve(JSON.parse(body));
+        resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
       } catch (error) {
         reject(new Error(`Invalid JSON: ${(error as Error).message}`));
       }
     });
+
     req.on('error', reject);
   });
 }
 
+/** Extract a numeric HTTP status from a thrown value, if present. */
+function errorStatusCode(error: unknown): number | undefined {
+  const code = (error as HttpError | undefined)?.statusCode;
+  return typeof code === 'number' ? code : undefined;
+}
+
+/**
+ * Apply baseline security response headers (L4 / OWASP A05:2021).
+ *
+ * Cheap, static defenses applied to every response: block MIME sniffing,
+ * forbid framing (clickjacking), and avoid leaking full URLs in the Referer.
+ */
+export function applySecurityHeaders(res: ServerResponse): void {
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+  res.setHeader('X-Frame-Options', 'DENY');
+  res.setHeader('Referrer-Policy', 'no-referrer');
+}
+
 /**
  * Send JSON response with proper Content-Length header
  */
@@ -86,24 +144,16 @@ function sendJson(res: ServerResponse, statusCode: number, data: unknown): void
 }
 
 /**
- * Handle health check endpoint
+ * Handle health check endpoint (M7 / OWASP A09:2021).
+ *
+ * `/health` is unauthenticated (it is on the auth skip-list so container/orchestrator
+ * probes can reach it). It therefore returns liveness ONLY — never version, auth
+ * method, AI provider URLs, client counts, or any other internal configuration that
+ * would aid an unauthenticated attacker fingerprinting the deployment. Operators who
+ * need that detail can query the authenticated MCP tools (e.g. `getVersion`).
  */
-function handleHealthCheck(res: ServerResponse, config: EnvironmentConfig, aiEnabled: boolean, eventsEnabled: boolean): void {
-  sendJson(res, 200, {
-    status: 'healthy',
-    version: VERSION,
-    transport: 'stream',
-    stateful: config.stateful,
-    authMethod: config.authMethod,
-    aiEnabled,
-    aiProvider: aiEnabled ? config.aiProvider : undefined,
-    aiUrl: aiEnabled ? config.aiUrl : undefined,
-    aiModel: aiEnabled ? config.aiModel : undefined,
-    eventsEnabled,
-    eventsPath: eventsEnabled ? config.sseEventsPath : undefined,
-    eventsConnectedClients: eventsEnabled ? getClientCount() : undefined,
-    rateLimitEnabled: config.rateLimitEnabled,
-  });
+export function handleHealthCheck(res: ServerResponse): void {
+  sendJson(res, 200, { status: 'healthy' });
 }
 
 /**
@@ -117,11 +167,44 @@ function addRestApiCors(req: IncomingMessage, res: ServerResponse): void {
   res.setHeader('Access-Control-Max-Age', '86400');
 }
 
+/**
+ * Resolve the permission a REST `/api/*` route requires.
+ *
+ * Each route mirrors the `Permission.*` bit of its MCP-tool twin so the REST
+ * bridge cannot be used to bypass RBAC (finding H1 / OWASP A01:2021, BFLA).
+ * Read routes require QUERY; the service-call route requires CONTROL (matching
+ * the `callService` tool). Unknown routes return `null` — the handler falls
+ * through to a 404, which needs no permission.
+ */
+export function requiredRestPermission(method: string, pathname: string): number | null {
+  const m = method.toUpperCase();
+
+  if (m === 'GET') {
+    if (
+      pathname === '/api/states' ||
+      pathname === '/api/sensors' ||
+      pathname === '/api/search' ||
+      pathname === '/api/version' ||
+      /^\/api\/states\/[^/]+$/.test(pathname) ||
+      /^\/api\/entities\/[^/]+$/.test(pathname) ||
+      /^\/api\/history\/[^/]+$/.test(pathname)
+    ) {
+      return Permission.QUERY;
+    }
+  }
+
+  if (m === 'POST' && /^\/api\/services\/[^/]+\/[^/]+$/.test(pathname)) {
+    return Permission.CONTROL;
+  }
+
+  return null;
+}
+
 /**
  * Handle REST API requests for Open WebUI compatibility
  * These endpoints translate REST calls to Home Assistant API calls
  */
-async function handleRestApi(
+export async function handleRestApi(
   req: IncomingMessage,
   res: ServerResponse,
   url: string,
@@ -133,6 +216,26 @@ async function handleRestApi(
   const parsedUrl = new URL(url, `http://${req.headers.host}`);
   const pathname = parsedUrl.pathname;
 
+  // H1: enforce RBAC on REST routes before touching Home Assistant.
+  const required = requiredRestPermission(req.method ?? 'GET', pathname);
+  if (required !== null) {
+    // Fail closed: a missing mask grants nothing.
+    const userPermissions = ((req as AuthenticatedRequest).auth?.extra?.permissions as number | undefined) ?? 0;
+    if (!hasPermission(userPermissions, required)) {
+      logger.warn('REST API permission denied', {
+        method: req.method,
+        path: pathname,
+        required: getPermissionNames(required),
+        has: getPermissionNames(userPermissions),
+      });
+      sendJson(res, 403, {
+        error: 'Forbidden',
+        message: `This endpoint requires permission: ${getPermissionNames(required).join(', ')}`,
+      });
+      return;
+    }
+  }
+
   try {
     // GET /api/states - Get all entity states
     if (req.method === 'GET' && pathname === '/api/states') {
@@ -229,10 +332,18 @@ async function handleRestApi(
     // Not found
     sendJson(res, 404, { error: 'API endpoint not found' });
   } catch (error) {
+    // M5: a body that exceeded the size cap surfaces as 413, not a generic 500.
+    if (errorStatusCode(error) === 413) {
+      if (!res.headersSent) {
+        sendJson(res, 413, { error: 'Payload Too Large', message: 'Request body exceeds the size limit' });
+      }
+      return;
+    }
     logger.error('REST API error', { error, url });
+    // M6: log the detail above; never echo raw error text to the client.
     sendJson(res, 500, {
       error: 'Internal server error',
-      message: error instanceof Error ? error.message : String(error),
+      message: sanitizeError(error),
     });
   }
 }
@@ -437,6 +548,8 @@ export async function startHttpServer(options: HttpServerOptions): Promise<void>
         windowMs: config.rateLimitWindowMs,
         maxRequests: config.rateLimitMaxRequests,
         skipPaths: [healthPath, '/openapi.json'],
+        // M4: only trust forwarding headers from configured proxies.
+        trustedProxies: config.rateLimitTrustedProxies,
       })
     : null;
 
@@ -446,6 +559,9 @@ export async function startHttpServer(options: HttpServerOptions): Promise<void>
     secret: config.authSecret,
     permissions: config.permissions,
     skipPaths: [healthPath, '/openapi.json'],
+    requireExp: config.authRequireExp,
+    issuer: config.authIssuer,
+    audience: config.authAudience,
   });
 
   // Initialize event subscriber if SSE events are enabled and HA is configured
@@ -485,6 +601,9 @@ export async function startHttpServer(options: HttpServerOptions): Promise<void>
     // Wrap response to add Server-Timing header
     const { res } = wrapResponseWithTiming(originalRes);
 
+    // L4: baseline security headers on every response.
+    applySecurityHeaders(res);
+
     const url = req.url ?? '/';
     const urlPath = url.split('?')[0];
 
@@ -519,7 +638,7 @@ export async function startHttpServer(options: HttpServerOptions): Promise<void>
     try {
       // Health check endpoint
       if (config.httpEnableHealthcheck && url === healthPath) {
-        handleHealthCheck(res, config, !!aiClient, !!eventSubscriber);
+        handleHealthCheck(res);
         return;
       }
 
@@ -570,6 +689,14 @@ export async function startHttpServer(options: HttpServerOptions): Promise<void>
       // Not found
       sendJson(res, 404, { error: 'Not found' });
     } catch (error) {
+      // M5: oversize body → 413 rather than a generic 500.
+      if (errorStatusCode(error) === 413) {
+        if (!res.headersSent) {
+          sendJson(res, 413, { error: 'Payload Too Large', message: 'Request body exceeds the size limit' });
+        }
+        return;
+      }
+
       logger.error('HTTP request error', {
         error,
         method: req.method,
@@ -577,14 +704,23 @@ export async function startHttpServer(options: HttpServerOptions): Promise<void>
       });
 
       if (!res.headersSent) {
+        // M6: detail is logged above; the client gets only a generic message.
         sendJson(res, 500, {
           error: 'Internal server error',
-          message: error instanceof Error ? error.message : String(error),
+          message: sanitizeError(error),
         });
       }
     }
   });
 
+  // M5: bound how long a client may take to deliver headers/body so a slow-loris
+  // connection cannot tie up a socket indefinitely. These cap request *intake*
+  // time, not response duration, so long-lived SSE streams are unaffected.
+  server.headersTimeout = 30_000;   // 30s to send all request headers
+  server.requestTimeout = 60_000;   // 60s to deliver the complete request
+  server.keepAliveTimeout = 5_000;  // 5s idle on a keep-alive connection
+  server.maxRequestsPerSocket = 0;  // unlimited (default); explicit for clarity
+
   // Graceful shutdown handler
   let isShuttingDown = false;
 

package/src/server/rateLimiter.ts

@@ -11,6 +11,13 @@ export interface RateLimitConfig {
   maxRequests?: number;   // Maximum requests per window (default: 100)
   skipPaths?: string[];   // Paths to skip rate limiting (e.g., health checks)
   keyGenerator?: (req: IncomingMessage) => string;  // Custom key generator
+  /**
+   * Immediate-peer IPs whose forwarding headers (CF-Connecting-IP / X-Forwarded-For /
+   * X-Real-IP) may be trusted to identify the real client (M4). Empty by default —
+   * with no trusted proxy, client-supplied headers are IGNORED and the socket
+   * address is used, so a forged header cannot evade limits or grow the bucket map.
+   */
+  trustedProxies?: string[];
 }
 
 interface RateLimitEntry {
@@ -26,6 +33,7 @@ export class RateLimiter {
   private readonly maxRequests: number;
   private readonly skipPaths: Set<string>;
   private readonly keyGenerator: (req: IncomingMessage) => string;
+  private readonly trustedProxies: Set<string>;
   private readonly entries = new Map<string, RateLimitEntry>();
   private cleanupInterval: ReturnType<typeof setInterval> | null = null;
 
@@ -33,30 +41,54 @@ export class RateLimiter {
     this.windowMs = config.windowMs ?? 60000; // 1 minute default
     this.maxRequests = config.maxRequests ?? 100; // 100 requests per minute
     this.skipPaths = new Set(config.skipPaths ?? ['/health', '/healthcheck']);
-    this.keyGenerator = config.keyGenerator ?? this.defaultKeyGenerator;
+    this.trustedProxies = new Set(config.trustedProxies ?? []);
+    // Bind so a custom generator OR the default both see `this`.
+    this.keyGenerator = config.keyGenerator ?? ((req) => this.defaultKeyGenerator(req));
 
     // Start cleanup interval to prevent memory leaks
     this.startCleanup();
   }
 
+  /** First value of a possibly-array header, trimmed; undefined if absent/empty. */
+  private firstHeader(value: string | string[] | undefined): string | undefined {
+    const v = Array.isArray(value) ? value[0] : value;
+    const trimmed = v?.trim();
+    return trimmed ? trimmed : undefined;
+  }
+
   /**
-   * Default key generator - uses IP address
+   * Default key generator (M4 / OWASP API4:2023).
+   *
+   * Client-supplied forwarding headers are honored ONLY when the immediate peer
+   * (`socket.remoteAddress`) is a configured trusted proxy. Otherwise we key on the
+   * socket address — an attacker cannot forge that, so they can neither evade the
+   * limit by rotating X-Forwarded-For nor exhaust memory with unbounded forged keys.
    */
   private defaultKeyGenerator(req: IncomingMessage): string {
-    // Try to get real IP from common proxy headers
-    const forwardedFor = req.headers['x-forwarded-for'];
-    if (forwardedFor) {
-      const ips = Array.isArray(forwardedFor) ? forwardedFor[0] : forwardedFor;
-      return ips.split(',')[0].trim();
+    const socketAddr = req.socket?.remoteAddress ?? 'unknown';
+
+    if (!this.trustedProxies.has(socketAddr)) {
+      return socketAddr;
+    }
+
+    // Behind a trusted proxy: prefer Cloudflare's single-client CF-Connecting-IP,
+    // then the left-most X-Forwarded-For hop, then X-Real-IP.
+    const cf = this.firstHeader(req.headers['cf-connecting-ip']);
+    if (cf) {
+      return cf;
+    }
+
+    const xff = this.firstHeader(req.headers['x-forwarded-for']);
+    if (xff) {
+      return xff.split(',')[0].trim();
     }
 
-    const realIp = req.headers['x-real-ip'];
+    const realIp = this.firstHeader(req.headers['x-real-ip']);
     if (realIp) {
-      return Array.isArray(realIp) ? realIp[0] : realIp;
+      return realIp;
     }
 
-    // Fall back to socket remote address
-    return req.socket.remoteAddress ?? 'unknown';
+    return socketAddr;
   }
 
   /**

package/src/server/stdio.ts

@@ -8,6 +8,7 @@ import type { HaClient } from '../haClient/index.js';
 import type { LocalAIClient } from '../localAI/index.js';
 import type { OmadaClient } from '../omadaClient/index.js';
 import { logger } from '../utils/logger.js';
+import { setLocalFullTrust } from '../tools/common.js';
 import { createServer } from './common.js';
 
 export interface StdioServerOptions {
@@ -19,6 +20,11 @@ export interface StdioServerOptions {
 export async function startStdioServer(options: StdioServerOptions): Promise<void> {
   logger.info('Starting stdio server');
 
+  // L3: stdio has no per-request auth; the local process owner is trusted. Grant
+  // full permissions to tool calls that arrive without an explicit mask. HTTP
+  // transports never enable this — they fail closed on a missing mask.
+  setLocalFullTrust(true);
+
   const server = createServer(options);
   const transport = new StdioServerTransport();
 

package/src/server/stream.ts

@@ -28,6 +28,66 @@ export interface StreamTransportOptions {
   config: EnvironmentConfig;
 }
 
+export interface TransportSecurityOptions {
+  allowedOrigins: string[];
+  allowedHosts: string[];
+  enableDnsRebindingProtection: boolean;
+}
+
+/**
+ * Build the DNS-rebinding protection options for the Streamable HTTP transport
+ * (M3 / OWASP A05:2021).
+ *
+ * Host-header validation is **opt-in**. The SDK only validates the `Host` header
+ * when `allowedHosts` is non-empty (EXACT string match), and only validates
+ * `Origin` when `allowedOrigins` is non-empty. CORS/Origin enforcement already
+ * lives in the HTTP layer, so this helper governs ONLY the Host check and leaves
+ * `allowedOrigins` empty to avoid double-enforcing origins at the transport.
+ *
+ * - `MCP_HTTP_ALLOWED_HOSTS` UNSET → Host validation OFF (protection disabled).
+ *   This preserves pre-1.3.0 behavior: an upgrade never silently 403s clients
+ *   that reach the server by a host not listed in the (CORS) origins. The
+ *   server's own reachable host and its allowed CORS origins are frequently
+ *   different addresses, so deriving hosts from origins would break real setups.
+ * - `MCP_HTTP_ALLOWED_HOSTS` SET → enforce exactly those host[:port] values, plus
+ *   loopback/bind-address conveniences so on-box health checks and local tools
+ *   keep working. Any other `Host` header is rejected with a 403.
+ */
+export function buildTransportSecurityOptions(config: EnvironmentConfig): TransportSecurityOptions {
+  const explicitHosts = config.httpAllowedHosts ?? [];
+
+  // Opt-out by default: no explicit hosts ⇒ no Host-header validation.
+  if (explicitHosts.length === 0) {
+    return { allowedOrigins: [], allowedHosts: [], enableDnsRebindingProtection: false };
+  }
+
+  const port = config.httpPort ?? 3000;
+  const bindAddr = config.httpBindAddr ?? '127.0.0.1';
+  const hosts = new Set<string>();
+
+  for (const entry of explicitHosts) {
+    try {
+      // Accept a full URL form (e.g. https://example.com) → host header form.
+      hosts.add(new URL(entry).host);
+    } catch {
+      // Bare hostname / IP[:port] already in host-header form.
+      hosts.add(entry);
+    }
+  }
+
+  // Always permit direct loopback / bind-address access on the listen port.
+  for (const host of [bindAddr, 'localhost', '127.0.0.1']) {
+    hosts.add(host);
+    hosts.add(`${host}:${port}`);
+  }
+
+  return {
+    allowedOrigins: [],
+    allowedHosts: [...hosts],
+    enableDnsRebindingProtection: true,
+  };
+}
+
 /**
  * Creates a Streamable HTTP transport
  * This implements the MCP protocol version 2025-03-26
@@ -43,10 +103,13 @@ export function createStreamTransport(options: StreamTransportOptions): StreamTr
     logger.info('Starting Streamable HTTP transport in stateless mode; Mcp-Session-Id headers are optional');
   }
 
+  const security = buildTransportSecurityOptions(config);
+
   const transport = new StreamableHTTPServerTransport({
     sessionIdGenerator,
-    allowedOrigins: config.httpAllowedOrigins,
-    enableDnsRebindingProtection: true,
+    allowedOrigins: security.allowedOrigins,
+    allowedHosts: security.allowedHosts,
+    enableDnsRebindingProtection: security.enableDnsRebindingProtection,
     onsessioninitialized: (sessionId: string) => {
       logger.info('Session initialized', { sessionId });
     },

package/src/tools/common.ts

@@ -12,6 +12,24 @@ import { Permission, hasPermission, getPermissionNames } from '../permissions/in
 // Re-export Permission for tool files
 export { Permission };
 
+/**
+ * Local-trust flag for the stdio transport (L3 / OWASP A04:2021).
+ *
+ * Tool calls normally carry a permission mask in `authInfo.extra.permissions`,
+ * populated by the HTTP auth middleware (bearer mask, or 0xFF for the loopback
+ * `none` mode). When that mask is ABSENT we fail closed — deny — instead of the
+ * old default-allow `?? 0xFF`.
+ *
+ * The one legitimate no-auth path is stdio (Claude Desktop): there is no per-request
+ * auth and the process owner is the trusted local user. `startStdioServer` opts into
+ * full trust by calling `setLocalFullTrust(true)`. HTTP never enables it.
+ */
+let localFullTrust = false;
+
+export function setLocalFullTrust(enabled: boolean): void {
+  localFullTrust = enabled;
+}
+
 /**
  * Extra context passed to tool handlers
  * Permissions are extracted from authInfo.extra.permissions (MCP SDK standard)
@@ -55,8 +73,11 @@ export function wrapToolHandler<T>(
 ): (args: T, extra: ToolExtra) => Promise<CallToolResult> {
   return async (args: T, extra: ToolExtra): Promise<CallToolResult> => {
     const sessionId = extra.sessionId ?? 'unknown-session';
-    // Extract permissions from MCP SDK authInfo.extra.permissions
-    const userPermissions = (extra.authInfo?.extra?.permissions as number | undefined) ?? 0xFF;
+    // Extract permissions from MCP SDK authInfo.extra.permissions.
+    // L3: fail closed when the mask is absent — only the trusted-local stdio path
+    // (setLocalFullTrust) grants full permissions without an explicit mask.
+    const userPermissions =
+      (extra.authInfo?.extra?.permissions as number | undefined) ?? (localFullTrust ? 0xFF : 0);
 
     // Check permissions if required
     if (requiredPermission !== undefined && !hasPermission(userPermissions, requiredPermission)) {

package/src/utils/config-validations.ts

@@ -12,6 +12,21 @@ export function isValidBindAddress(addr: string): boolean {
   return isIPv4(addr) || isIPv6(addr);
 }
 
+/**
+ * Returns true if the address is a loopback address (localhost-only).
+ *
+ * Used to enforce that an unauthenticated server (MCP_AUTH_METHOD=none) may only
+ * be bound to a loopback interface — never to `0.0.0.0`/`::` or a LAN address.
+ */
+export function isLoopbackAddress(addr: string): boolean {
+  if (!addr) return false;
+  const a = addr.toLowerCase();
+  if (a === 'localhost' || a === '::1') return true;
+  // IPv4 loopback is the whole 127.0.0.0/8 block.
+  if (isIPv4(a) && a.startsWith('127.')) return true;
+  return false;
+}
+
 /**
  * Validates if a string is a valid hostname
  * Allows alphanumeric characters, hyphens, and dots

package/src/utils/jwt.ts

@@ -9,6 +9,9 @@ export interface JwtPayload {
   sub?: string;
   exp?: number;
   iat?: number;
+  nbf?: number;
+  iss?: string;
+  aud?: string | string[];
   [key: string]: unknown;
 }
 
@@ -18,6 +21,18 @@ export interface JwtResult {
   error?: string;
 }
 
+/** Optional claim-validation policy for verifyJwt. */
+export interface JwtVerifyOptions {
+  /** Reject tokens that have no `exp` claim (H3). Default: false (backward-compatible). */
+  requireExp?: boolean;
+  /** Require `iss` to equal this value when set (L6). */
+  issuer?: string;
+  /** Require `aud` to include this value when set (L6). */
+  audience?: string;
+  /** Allowable clock skew in seconds for exp/nbf comparisons (L6). Default: 0. */
+  clockSkewSec?: number;
+}
+
 function b64decode(str: string): string {
   const pad = str + '='.repeat((4 - (str.length % 4)) % 4);
   return Buffer.from(pad.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString();
@@ -27,7 +42,7 @@ function b64encode(data: Buffer): string {
   return data.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
 }
 
-export function verifyJwt(token: string, secret: string): JwtResult {
+export function verifyJwt(token: string, secret: string, options: JwtVerifyOptions = {}): JwtResult {
   const parts = token.split('.');
   if (parts.length !== 3) {
     return { valid: false, error: 'bad format' };
@@ -52,9 +67,37 @@ export function verifyJwt(token: string, secret: string): JwtResult {
     return { valid: false, error: 'bad payload' };
   }
 
-  // Check expiration
-  if (payload.exp && payload.exp < Date.now() / 1000) {
-    return { valid: false, error: 'expired' };
+  const now = Date.now() / 1000;
+  const skew = options.clockSkewSec ?? 0;
+
+  // Expiration (H3): enforce when present; optionally require it.
+  if (payload.exp !== undefined) {
+    if (typeof payload.exp !== 'number' || payload.exp < now - skew) {
+      return { valid: false, error: 'expired' };
+    }
+  } else if (options.requireExp) {
+    return { valid: false, error: 'missing exp' };
+  }
+
+  // Not-before (L6)
+  if (payload.nbf !== undefined) {
+    if (typeof payload.nbf !== 'number' || payload.nbf > now + skew) {
+      return { valid: false, error: 'not yet valid' };
+    }
+  }
+
+  // Issuer (L6): only checked when an expected issuer is configured.
+  if (options.issuer !== undefined && payload.iss !== options.issuer) {
+    return { valid: false, error: 'bad issuer' };
+  }
+
+  // Audience (L6): only checked when an expected audience is configured.
+  if (options.audience !== undefined) {
+    const aud = payload.aud;
+    const ok = Array.isArray(aud) ? aud.includes(options.audience) : aud === options.audience;
+    if (!ok) {
+      return { valid: false, error: 'bad audience' };
+    }
   }
 
   return { valid: true, payload };

package/src/utils/sanitizeError.ts

@@ -0,0 +1,18 @@
+/**
+ * Error sanitization for client-facing responses (M6 / OWASP A09:2021).
+ *
+ * Raw `error.message` values routinely embed infrastructure detail — internal
+ * hostnames, ports, filesystem paths, upstream stack fragments, occasionally
+ * tokens. None of that belongs in an HTTP response body. Callers should log the
+ * full error server-side (via `logger.error`) and send the return of this helper
+ * to the client instead.
+ *
+ * The function intentionally ignores the error's own text: returning a constant
+ * generic string is the whole point — there is no "safe subset" of an arbitrary
+ * upstream message we can trust to forward.
+ */
+const GENERIC_MESSAGE = 'Internal server error';
+
+export function sanitizeError(_error: unknown, fallback: string = GENERIC_MESSAGE): string {
+  return fallback;
+}