tina4-nodejs 3.13.37 → 3.13.39

package/packages/core/src/server.ts

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { execFileSync, exec } from "node:child_process";
 import cluster from "node:cluster";
 import os from "node:os";
+import type { Socket } from "node:net";
 import type { Tina4Config, Tina4Request, Tina4Response } from "./types.js";
 import { Router, defaultRouter, runRouteMiddlewares } from "./router.js";
 import { validToken, getPayload, refreshToken } from "./auth.js";
@@ -19,7 +20,7 @@ import { createHealthRoutes } from "./health.js";
 import { rateLimiter } from "./rateLimiter.js";
 import { Log } from "./logger.js";
 import { DevAdmin, RequestInspector, WsTracker } from "./devAdmin.js";
-import { devReloadWs } from "./websocket.js";
+import { devReloadWs, serveWebSocketRoute, wsRouteManager } from "./websocket.js";
 import { feedbackEnabled, injectFeedbackWidget } from "./feedback.js";
 import { I18n } from "./i18n.js";
 import { stopAllBackgroundTasks } from "./background.js";
@@ -33,6 +34,72 @@ const BUILTIN_ERROR_TEMPLATES_DIR = resolve(__dirname, "..", "templates");
 /** Built-in public directory for framework-bundled static assets. */
 const BUILTIN_PUBLIC_DIR = resolve(__dirname, "..", "public");
 
+/**
+ * Apply pending DB migrations on startup — NON-BREAKING.
+ *
+ * When a `migrations/` folder exists (with at least one `.sql` file, excluding
+ * `.down.sql`) and `TINA4_AUTO_MIGRATE` is not disabled (default "true";
+ * false/0/no/off disable), pending migrations are applied during boot so the
+ * schema is current with no manual `tina4 migrate` step. A failure here is
+ * logged LOUD via `Log.error` and the service STILL starts — a bad migration
+ * must never take the backend down. (The explicit `tina4 migrate` CLI stays
+ * fail-fast so CI still gets a non-zero exit. Only this startup hook swallows.)
+ *
+ * Disable with `TINA4_AUTO_MIGRATE=false` — e.g. multi-instance production that
+ * migrates as a separate deploy step (concurrent first-apply can race).
+ *
+ * @param migrationDir - migrations directory (default "migrations", relative to base)
+ * @param base - project root used to resolve the migrations directory
+ */
+export async function autoMigrateOnStartup(
+  migrationDir = "migrations",
+  base = process.cwd(),
+): Promise<void> {
+  const dir = resolve(base, migrationDir);
+
+  // Gate 1: a migrations/ folder with at least one .sql (non-down) file.
+  if (!existsSync(dir)) return;
+  let hasSql = false;
+  try {
+    hasSql = readdirSync(dir).some((f) => f.endsWith(".sql") && !f.endsWith(".down.sql"));
+  } catch {
+    return; // unreadable dir → nothing to do (silent)
+  }
+  if (!hasSql) return;
+
+  // Gate 2: TINA4_AUTO_MIGRATE not falsy (default "true").
+  const flag = process.env.TINA4_AUTO_MIGRATE;
+  if (flag != null && !isTruthy(flag)) {
+    Log.debug("TINA4_AUTO_MIGRATE is off — skipping startup migrations");
+    return;
+  }
+
+  // Gate 3: a DB adapter must be resolvable. (initDatabase() has already run by
+  // the time this is called from startServer.)
+  let orm: typeof import("../../orm/src/index.js");
+  try {
+    orm = await import("../../orm/src/index.js");
+    orm.getAdapter(); // throws if no adapter configured
+  } catch (err) {
+    Log.debug(`Startup migrations skipped (no database configured): ${err instanceof Error ? err.message : String(err)}`);
+    return;
+  }
+
+  // Run the EXISTING migrate runner inside try/catch — NEVER re-raise out of
+  // the startup hook (non-breaking).
+  try {
+    const result = await orm.migrate(undefined, { migrationsDir: dir });
+    if (result.applied.length > 0) {
+      Log.info(`Applied ${result.applied.length} pending migration(s) on startup`);
+    }
+  } catch (err) {
+    Log.error(
+      `Startup auto-migration failed: ${err instanceof Error ? err.message : String(err)} — ` +
+      "the service is starting anyway. Run `tina4 migrate` to retry.",
+    );
+  }
+}
+
 /** Read version from root package.json so the banner always matches the published version. */
 function readPackageVersion(): string {
   try {
@@ -675,9 +742,23 @@ export async function startServer(config?: Tina4Config): Promise<{
   router: Router;
   port: number;
 }> {
-  // Load .env early so TINA4_DEBUG is available for cluster decision
+  // Load env early so TINA4_DEBUG is available for the cluster decision.
+  // Precedence MUST be: real environment (set before boot) > .env.local > .env.
+  // loadEnv(override=false) is first-wins (only sets a key not already present),
+  // so load .env.local BEFORE .env — both with override=false. A real env var
+  // set before boot is already present and wins over both; .env.local fills
+  // local-only keys; .env fills whatever neither set. Loading .env.local with
+  // override=true would let a stray gitignored .env.local clobber an explicitly
+  // set real env var (e.g. a production TINA4_SECRET) — never do that.
+  loadEnv(".env.local");
   loadEnv();
 
+  // Auto-generate a per-machine dev secret to a gitignored .env.local when one
+  // is missing (dev only, never CI/prod). Must run after env load and before
+  // any auth use. Local import avoids a load-time cycle through auth.
+  const { ensureDevSecret } = await import("./auth.js");
+  ensureDevSecret();
+
   // Refuse to boot with pre-3.12 un-prefixed env vars set.
   _checkLegacyEnvVars();
 
@@ -869,6 +950,12 @@ ${reset}
     } catch (err) {
       console.warn(`\n  ORM not available (install @tina4/orm to enable):`, err);
     }
+
+    // Auto-run pending migrations on startup — AFTER initDatabase()/model sync,
+    // BEFORE the server listens. Non-breaking: a failure is logged and boot
+    // continues (the helper never throws). Gated on a migrations/ dir + the
+    // TINA4_AUTO_MIGRATE flag (default on) + a resolvable DB adapter.
+    await autoMigrateOnStartup("migrations", base);
   }
 
   // Initialize Swagger — gated on TINA4_SWAGGER_ENABLED (default: enabled
@@ -972,8 +1059,8 @@ ${reset}
           rawRes.setHeader("Content-Length", String(accumulated));
         }
         const realCb = typeof chunk === "function" ? chunk : cb;
-        return origEnd(undefined, undefined, realCb);
         void origWrite; // referenced to keep tsc happy
+        return typeof realCb === "function" ? origEnd(realCb) : origEnd();
       }) as typeof rawRes.end;
     }
 
@@ -1151,7 +1238,14 @@ ${reset}
         ];
         if (globalMiddleware.length > 0) {
           const [, , proceed] = await MiddlewareRunner.runBefore(globalMiddleware, req, res);
-          if (!proceed || res.raw.writableEnded) return;
+          if (!proceed || res.raw.writableEnded) {
+            // AFTER-ON-4xx RULE (M2): after_* ALWAYS run even when a before_*
+            // short-circuited (4xx / clean 500 / response ended), so they can
+            // still add headers / logging. Run them, then stop the handler.
+            await MiddlewareRunner.runAfter(globalMiddleware, req, res);
+            if (!res.raw.writableEnded) res.raw.end();
+            return;
+          }
         }
 
         // Run per-route middlewares if any
@@ -1393,31 +1487,52 @@ ${reset}
   // posts /__dev/api/reload to the MAIN port. Matches Python (master).
   const server = createServer(dispatch);
 
-  // WebSocket-primary DevReload: accept and hold /__dev_reload upgrades on the
-  // MAIN port (debug only) so POST /__dev/api/reload can push an instant reload.
-  // Mirrors Python's _register_dev_reload_ws + _ws_manager.broadcast(path=…).
-  // Without this the handshake 404s and the whole stack silently falls back to
-  // polling. Track connections in WsTracker so they appear in the dev-admin list.
+  // WebSocket upgrade handling on the MAIN port. Two responsibilities:
+  //
+  //  1. WebSocket-primary DevReload (debug only): accept and hold /__dev_reload
+  //     upgrades so POST /__dev/api/reload can push an instant reload. Mirrors
+  //     Python's _register_dev_reload_ws + _ws_manager.broadcast(path=…).
+  //
+  //  2. USER WS ROUTES (always): a route registered via Router.websocket() /
+  //     WebSocketServer.route() is dispatched to a live open/message/close
+  //     lifecycle on the real connection — parity with Python/PHP/Ruby. Per-route
+  //     auth is enforced here on the upgrade (serveWebSocketRoute): a @secured /
+  //     .secure() route rejects a missing/invalid JWT before accepting; public
+  //     routes pass. Previously the integrated server only handled /__dev_reload,
+  //     so user WS routes never reached a live connection.
+  //
+  // Tracking goes through WsTracker so connections show in the dev-admin list.
   if (isDevMode()) {
     devReloadWs.setTracker(
       (remoteAddress, p) => WsTracker.add(remoteAddress, p),
       (id) => { WsTracker.remove(id); },
     );
-    server.on("upgrade", (req: IncomingMessage, socket, head) => {
-      const upPath = (req.url ?? "/").split("?")[0];
-      if (upPath === "/__dev_reload") {
-        devReloadWs.handleUpgrade(req, socket, head);
-        return;
-      }
-      // Not a dev-reload upgrade — refuse cleanly rather than leaving it hanging.
-      try {
-        socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
-        socket.destroy();
-      } catch {
-        /* socket already gone */
-      }
-    });
+    wsRouteManager.setTracker(
+      (remoteAddress, p) => WsTracker.add(remoteAddress, p),
+      (id) => { WsTracker.remove(id); },
+    );
   }
+  server.on("upgrade", (req: IncomingMessage, socket: Socket, head: Buffer) => {
+    const upPath = (req.url ?? "/").split("?")[0];
+    // Dev-reload channel (debug only).
+    if (isDevMode() && upPath === "/__dev_reload") {
+      devReloadWs.handleUpgrade(req, socket, head);
+      return;
+    }
+    // User-registered WS route — enforces per-route auth, then drives the
+    // open/message/close lifecycle on this connection. Returns false only when
+    // no WS route matches this path.
+    if (serveWebSocketRoute(req, socket, head)) {
+      return;
+    }
+    // No dev-reload and no matching user route — refuse cleanly.
+    try {
+      socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+      socket.destroy();
+    } catch {
+      /* socket already gone */
+    }
+  });
 
   return new Promise((resolvePromise) => {
     server.listen(port, host, () => {

package/packages/core/src/session.ts

@@ -28,6 +28,8 @@ import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
+import { Log } from "./logger.js";
+import { isTruthy } from "./dotenv.js";
 import { RedisNpmSessionHandler } from "./sessionHandlers/redisHandler.js";
 import { ValkeySessionHandler } from "./sessionHandlers/valkeyHandler.js";
 import { MongoSessionHandler } from "./sessionHandlers/mongoHandler.js";
@@ -196,7 +198,10 @@ export class RedisSessionHandler implements SessionHandler {
   /**
    * Execute a Redis command synchronously via a short-lived TCP connection.
    *
-   * Returns the raw RESP response string.
+   * Returns the command result string. A genuine key miss yields `""`. A
+   * transport/connection FAILURE (server unreachable, AUTH error, timeout)
+   * THROWS so the Session boundary can distinguish "not found" (silent) from
+   * "backend failed" (log-loud + degrade). Backend-failure policy parity.
    */
   private execSync(args: string[]): string {
     const script = `
@@ -270,18 +275,24 @@ export class RedisSessionHandler implements SessionHandler {
       setTimeout(() => { sock.destroy(); process.exit(1); }, 3000);
     `;
 
+    let result: string;
     try {
-      const result = execFileSync(process.execPath, ["-e", script], {
+      result = execFileSync(process.execPath, ["-e", script], {
         encoding: "utf-8",
         timeout: 5000,
         stdio: ["pipe", "pipe", "pipe"],
       });
-      if (result === "__NULL__") return "";
-      if (result.startsWith("__ERR__")) return "";
-      return result;
-    } catch {
-      return "";
+    } catch (err) {
+      // Non-zero exit = the child hit a socket error / AUTH failure / timeout.
+      // That is a transport FAILURE, not a key miss — surface it so the
+      // Session boundary logs + degrades (or re-throws under strict mode).
+      throw new Error(`Redis command failed: ${(err as Error).message}`);
+    }
+    if (result === "__NULL__") return "";        // genuine key miss
+    if (result.startsWith("__ERR__")) {
+      throw new Error(`Redis error: ${result.slice("__ERR__".length)}`);
     }
+    return result;
   }
 
   private key(sessionId: string): string {
@@ -290,7 +301,7 @@ export class RedisSessionHandler implements SessionHandler {
 
   read(sessionId: string): SessionData | null {
     const raw = this.execSync(["GET", this.key(sessionId)]);
-    if (!raw) return null;
+    if (!raw) return null;     // key miss — normal "no session yet", NOT an error
     try {
       return JSON.parse(raw) as SessionData;
     } catch {
@@ -323,6 +334,20 @@ export class Session {
   private ttl: number;
   private sessionId: string | null = null;
   private data: SessionData | null = null;
+  /**
+   * Dirty flag — set when data changes, cleared only on a successful write.
+   * Retained on a failed write so a later save() retries once the backend
+   * recovers (mirrors the Python `_dirty` semantics).
+   */
+  private dirty = false;
+  /**
+   * Backend-failure policy: log-loud + degrade (default), or re-raise when
+   * TINA4_SESSION_STRICT is truthy. A read failure logs + yields an empty
+   * session, a write failure logs + returns false (best-effort, dirty
+   * retained), destroy/gc failures log + swallow. Parity across all four
+   * frameworks. Strict mode is the escape hatch (same as events/seeding).
+   */
+  private strict: boolean;
 
   constructor(backend?: string, config?: SessionConfig) {
     const backendType = backend
@@ -333,6 +358,8 @@ export class Session {
     this.ttl = config?.ttl
       ?? (process.env.TINA4_SESSION_TTL ? parseInt(process.env.TINA4_SESSION_TTL, 10) : 3600);
 
+    this.strict = isTruthy(process.env.TINA4_SESSION_STRICT);
+
     // Select handler based on backend type
     switch (backendType) {
       case "redis":
@@ -370,6 +397,57 @@ export class Session {
     this.handler = handler;
   }
 
+  // ── Backend-failure policy: log-loud + degrade ─────────────────────
+  //
+  // The handlers themselves stay honest — they raise when the backend
+  // (Redis/Valkey/Mongo/DB) is unreachable, and return null/empty WITHOUT
+  // raising for a genuine "no session yet" miss. The Session layer is the
+  // single place that decides the resilience policy so every backend behaves
+  // the same: a transient outage logs + degrades rather than 500-ing every
+  // request (cascade outage) or vanishing silently (data loss). A genuinely
+  // empty result is NOT an error and never reaches these logs.
+
+  private logBackendError(op: string, err: unknown): void {
+    const handlerName = (this.handler as object)?.constructor?.name ?? "SessionHandler";
+    const message = err instanceof Error ? err.message : String(err);
+    Log.error(`Session backend ${op} failed (${handlerName}): ${message}`);
+  }
+
+  /** Read through the backend; on FAILURE log + degrade to empty (or re-throw under strict). */
+  private safeRead(sessionId: string): SessionData | null {
+    try {
+      return this.handler.read(sessionId);
+    } catch (err) {
+      this.logBackendError("read", err);
+      if (this.strict) throw err;
+      return null;
+    }
+  }
+
+  /** Write through the backend; on FAILURE log + return false (or re-throw under strict). */
+  private safeWrite(sessionId: string, data: SessionData, ttl: number): boolean {
+    try {
+      this.handler.write(sessionId, data, ttl);
+      return true;
+    } catch (err) {
+      this.logBackendError("write", err);
+      if (this.strict) throw err;
+      return false;
+    }
+  }
+
+  /** Destroy through the backend; on FAILURE log + swallow (or re-throw under strict). */
+  private safeDestroy(sessionId: string): boolean {
+    try {
+      this.handler.destroy(sessionId);
+      return true;
+    } catch (err) {
+      this.logBackendError("destroy", err);
+      if (this.strict) throw err;
+      return false;
+    }
+  }
+
   /**
    * Start or resume a session.
    * @param sessionId - Existing session ID to resume (optional)
@@ -377,17 +455,20 @@ export class Session {
    */
   start(sessionId?: string): string {
     if (sessionId) {
-      const loaded = this.handler.read(sessionId);
+      const loaded = this.safeRead(sessionId);
       if (loaded) {
         // Check TTL for file backend (Redis handles TTL natively)
         const now = Math.floor(Date.now() / 1000);
         if (loaded._accessed && (now - loaded._accessed) > this.ttl) {
-          this.handler.destroy(sessionId);
+          this.safeDestroy(sessionId);
         } else {
           this.sessionId = sessionId;
           this.data = loaded;
           this.data._accessed = now;
-          this.handler.write(this.sessionId, this.data, this.ttl);
+          this.dirty = false;
+          // Refresh the accessed timestamp; a write failure here is logged but
+          // must not abort the resume — the request still serves.
+          this.safeWrite(this.sessionId, this.data, this.ttl);
           return sessionId;
         }
       }
@@ -397,7 +478,8 @@ export class Session {
     this.sessionId = randomBytes(16).toString("hex");
     const now = Math.floor(Date.now() / 1000);
     this.data = { _created: now, _accessed: now };
-    this.handler.write(this.sessionId, this.data, this.ttl);
+    this.dirty = false;
+    this.safeWrite(this.sessionId, this.data, this.ttl);
     return this.sessionId;
   }
 
@@ -418,6 +500,7 @@ export class Session {
   set(key: string, value: unknown): void {
     if (!this.data) return;
     this.data[key] = value;
+    this.dirty = true;
     this.save();
   }
 
@@ -427,18 +510,23 @@ export class Session {
   delete(key: string): void {
     if (!this.data) return;
     delete this.data[key];
+    this.dirty = true;
     this.save();
   }
 
   /**
    * Destroy the entire session.
+   *
+   * A backend failure is logged (never silent) but does not throw under the
+   * default policy — local state is cleared regardless so the request proceeds.
    */
   destroy(): void {
     if (this.sessionId) {
-      this.handler.destroy(this.sessionId);
+      this.safeDestroy(this.sessionId);
     }
     this.sessionId = null;
     this.data = null;
+    this.dirty = false;
   }
 
   /**
@@ -462,6 +550,7 @@ export class Session {
     if (!this.data) return;
     const now = Math.floor(Date.now() / 1000);
     this.data = { _created: this.data._created, _accessed: now };
+    this.dirty = true;
     this.save();
   }
 
@@ -475,6 +564,11 @@ export class Session {
 
   /**
    * Regenerate the session ID (keeps data, new ID).
+   *
+   * Call this right after a successful login or any privilege change to defeat
+   * session fixation — the pre-auth ID is destroyed and the data is carried
+   * onto a fresh, unguessable ID. A backend destroy/write failure is logged
+   * (never silent) but does not throw under the default policy.
    */
   regenerate(): string {
     const oldId = this.sessionId;
@@ -482,13 +576,14 @@ export class Session {
 
     // Remove old session
     if (oldId) {
-      this.handler.destroy(oldId);
+      this.safeDestroy(oldId);
     }
 
     // New ID, keep data
     this.sessionId = randomBytes(16).toString("hex");
     this.data = oldData ?? { _created: Math.floor(Date.now() / 1000), _accessed: Math.floor(Date.now() / 1000) };
     this.data._accessed = Math.floor(Date.now() / 1000);
+    this.dirty = true;
     this.save();
     return this.sessionId;
   }
@@ -510,6 +605,7 @@ export class Session {
     if (!this.data || !(flashKey in this.data)) return undefined;
     const stored = this.data[flashKey];
     delete this.data[flashKey];
+    this.dirty = true;
     this.save();
     return stored;
   }
@@ -545,19 +641,35 @@ export class Session {
   /**
    * Run garbage collection on the session backend.
    * Removes expired file/database sessions. Redis/Valkey/Mongo handle TTL natively.
+   *
+   * A backend failure is logged (never silent) but does not throw under the
+   * default policy (re-raises under TINA4_SESSION_STRICT=true).
    */
   gc(): void {
-    if (this.handler.gc) {
+    if (!this.handler.gc) return;
+    try {
       this.handler.gc(this.ttl);
+    } catch (err) {
+      this.logBackendError("gc", err);
+      if (this.strict) throw err;
     }
   }
 
   /**
    * Persist session data to the backend.
+   *
+   * Returns true on a successful persist, false if the backend was unreachable
+   * (logged). The dirty flag is cleared only on success so a later save()
+   * retries once the backend recovers. A nothing-to-persist call returns true.
    */
-  save(): void {
-    if (!this.sessionId || !this.data) return;
-    this.handler.write(this.sessionId, this.data, this.ttl);
+  save(): boolean {
+    if (!this.sessionId || !this.data) return true;
+    if (!this.dirty) return true;
+    if (this.safeWrite(this.sessionId, this.data, this.ttl)) {
+      this.dirty = false;
+      return true;
+    }
+    return false;  // write failed (logged); dirty RETAINED for retry
   }
 }
 

package/packages/core/src/sessionHandlers/databaseHandler.ts

@@ -22,6 +22,16 @@ interface SessionData {
 export interface DatabaseSessionConfig {
   /** SQLite database file path (default: extracted from TINA4_DATABASE_URL or "data/tina4_sessions.db") */
   dbPath?: string;
+  // Unified SessionConfig fields are tolerated (and ignored) so the central
+  // Session can forward its config object without a structural mismatch.
+  backend?: string;
+  path?: string;
+  ttl?: number;
+  redisHost?: string;
+  redisPort?: number;
+  redisPassword?: string;
+  redisPrefix?: string;
+  redisDb?: number;
 }
 
 /**

package/packages/core/src/sessionHandlers/mongoHandler.ts

@@ -30,6 +30,16 @@ export interface MongoSessionConfig {
   password?: string;
   database?: string;
   collection?: string;
+  // Unified SessionConfig fields are tolerated (and ignored) so the central
+  // Session can forward its config object without a structural mismatch.
+  backend?: string;
+  path?: string;
+  ttl?: number;
+  redisHost?: string;
+  redisPort?: number;
+  redisPassword?: string;
+  redisPrefix?: string;
+  redisDb?: number;
 }
 
 /**
@@ -79,6 +89,11 @@ export class MongoSessionHandler implements SessionHandler {
    * Uses the MongoDB wire protocol (OP_MSG) to communicate with the server.
    * For simplicity, we use the `runCommand` approach with JSON serialization
    * of BSON documents using a minimal BSON encoder.
+   *
+   * Returns the command response string (or `__EMPTY__` for an absent doc).
+   * A transport/connection FAILURE (server unreachable, socket error, timeout)
+   * THROWS so the Session boundary can distinguish "not found" (silent) from
+   * "backend failed" (log-loud + degrade). Backend-failure policy parity.
    */
   private execSync(command: string, args: string): string {
     const script = `
@@ -226,14 +241,16 @@ export class MongoSessionHandler implements SessionHandler {
     `;
 
     try {
-      const result = execFileSync(process.execPath, ["-e", script], {
+      return execFileSync(process.execPath, ["-e", script], {
         encoding: "utf-8",
         timeout: 8000,
         stdio: ["pipe", "pipe", "pipe"],
       });
-      return result;
-    } catch {
-      return "";
+    } catch (err) {
+      // Non-zero exit = the child hit a socket error / timeout. That is a
+      // transport FAILURE, not an absent document — surface it so the Session
+      // boundary logs + degrades (or re-throws under strict mode).
+      throw new Error(`MongoDB command failed: ${(err as Error).message}`);
     }
   }
 

package/packages/core/src/sessionHandlers/redisHandler.ts

@@ -32,6 +32,16 @@ export interface RedisNpmSessionConfig {
   password?: string;
   prefix?: string;
   db?: number;
+  // Unified SessionConfig fields are tolerated (and ignored) so the central
+  // Session can forward its config object without a structural mismatch.
+  backend?: string;
+  path?: string;
+  ttl?: number;
+  redisHost?: string;
+  redisPort?: number;
+  redisPassword?: string;
+  redisPrefix?: string;
+  redisDb?: number;
 }
 
 /**
@@ -78,6 +88,11 @@ export class RedisNpmSessionHandler implements SessionHandler {
    *
    * Attempts to use the `redis` npm package first. If unavailable, falls
    * back to raw TCP (RESP protocol) — same as valkeyHandler.ts.
+   *
+   * Returns the command result string. A genuine key miss yields `""`. A
+   * transport/connection FAILURE (server unreachable, AUTH error, timeout)
+   * THROWS so the Session boundary can distinguish "not found" (silent) from
+   * "backend failed" (log-loud + degrade). Backend-failure policy parity.
    */
   private execSync(args: string[]): string {
     const script = `
@@ -187,18 +202,24 @@ export class RedisNpmSessionHandler implements SessionHandler {
       }
     `;
 
+    let result: string;
     try {
-      const result = execFileSync(process.execPath, ["-e", script], {
+      result = execFileSync(process.execPath, ["-e", script], {
         encoding: "utf-8",
         timeout: 5000,
         stdio: ["pipe", "pipe", "pipe"],
       });
-      if (result === "__NULL__") return "";
-      if (result.startsWith("__ERR__")) return "";
-      return result;
-    } catch {
-      return "";
+    } catch (err) {
+      // Non-zero exit = the child hit a socket error / AUTH failure / timeout.
+      // That is a transport FAILURE, not a key miss — surface it so the
+      // Session boundary logs + degrades (or re-throws under strict mode).
+      throw new Error(`Redis command failed: ${(err as Error).message}`);
+    }
+    if (result === "__NULL__") return "";        // genuine key miss
+    if (result.startsWith("__ERR__")) {
+      throw new Error(`Redis error: ${result.slice("__ERR__".length)}`);
     }
+    return result;
   }
 
   private key(sessionId: string): string {
@@ -207,7 +228,7 @@ export class RedisNpmSessionHandler implements SessionHandler {
 
   read(sessionId: string): SessionData | null {
     const raw = this.execSync(["GET", this.key(sessionId)]);
-    if (!raw) return null;
+    if (!raw) return null;     // key miss — normal "no session yet", NOT an error
     try {
       return JSON.parse(raw) as SessionData;
     } catch {