tina4-nodejs 3.13.94 → 3.13.96

package/packages/core/src/session.ts

@@ -24,21 +24,21 @@
  *   session.get("user");  // { name: "Alice" }
  *   session.destroy();
  */
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { Log } from "./logger.js";
 import { isTruthy } from "./dotenv.js";
 import { respCommandSync } from "./sessionHandlers/respClient.js";
-import { RedisNpmSessionHandler } from "./sessionHandlers/redisHandler.js";
 import { ValkeySessionHandler } from "./sessionHandlers/valkeyHandler.js";
+import { MemcachedSessionHandler } from "./sessionHandlers/memcachedHandler.js";
 import { MongoSessionHandler } from "./sessionHandlers/mongoHandler.js";
 import { DatabaseSessionHandler } from "./sessionHandlers/databaseHandler.js";
 
 // ── Types ─────────────────────────────────────────────────────────
 
 export interface SessionConfig {
-  /** Session backend type: "file", "redis", "valkey", "mongo", "database" (or "db") */
+  /** Session backend type: "file", "redis", "valkey", "mongo", "memcached", "database" (or "db") */
   backend?: string;
   /** File storage path (default: "data/sessions") */
   path?: string;
@@ -62,6 +62,104 @@ interface SessionData {
   [key: string]: unknown;
 }
 
+// ── Session id validation ─────────────────────────────────────────
+
+/**
+ * A session id is OPAQUE — an unguessable lookup token and nothing else. It is
+ * never a filename, a path, a SQL fragment or a Redis key fragment, so the only
+ * characters it may contain are the ones every backend treats as inert.
+ *
+ * The alphabet is the RFC 4648 base64url set, which is exactly what all four
+ * frameworks already mint: Python `secrets.token_urlsafe(32)`, Ruby
+ * `SecureRandom.hex(32)`, PHP/Node `hex(16)`. Validation is therefore
+ * non-breaking for every id the family has ever issued, while rejecting the
+ * `.` and `/` that turn a cookie into a path traversal.
+ *
+ * The rule is the ALPHABET, not the length. The vulnerability was `.` and `/`
+ * turning a cookie into a path; entropy is not something this check can supply,
+ * because unguessability comes from the framework's own minting and an app that
+ * calls `start("my-session-id")` is a trusted caller managing its own id, not an
+ * attacker. So the floor is 1, and only the 128-character ceiling remains — it
+ * bounds what an attacker can push through a backend key.
+ */
+const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+
+/**
+ * Is `sessionId` a well-formed opaque session identifier?
+ *
+ * Callers pass UNTRUSTED input here (the session cookie is attacker-chosen), so
+ * anything that is not a string of the opaque alphabet is rejected.
+ */
+export function isValidSessionId(sessionId: unknown): boolean {
+  return typeof sessionId === "string" && SESSION_ID_PATTERN.test(sessionId);
+}
+
+// ── Backend name resolution ───────────────────────────────────────
+
+/**
+ * Every accepted backend name, aliases included. Byte-identical membership in
+ * all four frameworks. Written once here so the switch below and the error
+ * message cannot disagree.
+ */
+export const VALID_SESSION_BACKENDS = [
+  "file", "filesystem",
+  "redis",
+  "valkey",
+  "mongodb", "mongo",
+  "memcached", "memcache",
+  "database", "db",
+] as const;
+
+/** Canonical name of each backend, for the error message (aliases omitted). */
+export const CANONICAL_SESSION_BACKENDS = [
+  "file", "redis", "valkey", "mongodb", "memcached", "database",
+] as const;
+
+/**
+ * Names that USED to work, mapped to the message a caller needs to migrate.
+ *
+ * A retired name must not fall into the generic "unknown backend" message: the
+ * operator had a working config, and telling them what replaced it is the whole
+ * point. Checked before the membership test so the specific message wins.
+ */
+const RETIRED_SESSION_BACKENDS: Record<string, string> = {
+  "redis-npm":
+    'TINA4_SESSION_BACKEND="redis-npm" was removed on 2026-07-31. Use "redis": '
+    + "it is the same Redis backend and reads the same TINA4_SESSION_REDIS_* "
+    + "settings, over a faster persistent connection.",
+};
+
+/**
+ * Normalise a backend name and reject anything unrecognised.
+ *
+ * An UNKNOWN name used to fall through to `default:` in the switch below, which
+ * is the file handler. A typo in TINA4_SESSION_BACKEND ("redsi") - or, before
+ * this normalisation existed, merely a capital ("Redis") - produced a running
+ * app writing sessions to local disk while the operator believed they were in
+ * Redis. Nothing logged, nothing failed, and the symptom surfaced much later as
+ * users being logged out whenever a request landed on another instance.
+ *
+ * A BLANK name still means file. An env var set to "" is a SET variable, so it
+ * never reaches the `??` default; rejecting blank would break every deployment
+ * that clears the var to take the default.
+ */
+function resolveBackend(name: string): string {
+  const normalised = String(name).trim().toLowerCase();
+  if (normalised === "") return "file";
+
+  const retired = RETIRED_SESSION_BACKENDS[normalised];
+  if (retired) throw new Error(retired);
+
+  if (!(VALID_SESSION_BACKENDS as readonly string[]).includes(normalised)) {
+    throw new Error(
+      `Unknown session backend "${normalised}". `
+      + `Valid backends: ${CANONICAL_SESSION_BACKENDS.join(", ")}. `
+      + "Leave TINA4_SESSION_BACKEND unset for the file default.",
+    );
+  }
+  return normalised;
+}
+
 // ── Session Handler Interface ─────────────────────────────────────
 
 /**
@@ -93,8 +191,38 @@ export class FileSessionHandler implements SessionHandler {
     }
   }
 
+  /**
+   * Derive the file backing a session id. TWO independent guards, both required.
+   *
+   * This is the one place a session id becomes a filesystem path, and it used to
+   * interpolate the id RAW: `join(storagePath, "../../OUTSIDE/appconfig.json")`
+   * left the session directory entirely, so a cookie could read an existing
+   * .json from anywhere on disk into `session.all()` and then OVERWRITE it on
+   * save. Reproduced on Node 24.9.0 / macOS.
+   *
+   *  1. VALIDATE — a malformed id is refused outright. It throws rather than
+   *     returning null so a hostile id can never be mistaken for an ordinary
+   *     cache miss (the Session layer catches it, logs it, and degrades).
+   *  2. HASH — the filename is a SHA-256 of the id, matching the Python master
+   *     (`hashlib.sha256(session_id.encode()).hexdigest()`). A hex digest cannot
+   *     contain a separator or a dot, so even an id that somehow passed the
+   *     validator can only ever name a file inside `storagePath`.
+   *
+   * DEPLOY NOTE: hashing CHANGES the filename for every id, so existing on-disk
+   * sessions are orphaned and every logged-in user is logged out ONCE on the
+   * deploy that ships this. That is accepted: under strict session mode an old
+   * cookie is discarded on a read miss anyway, so the sessions were going to be
+   * dropped regardless.
+   */
   private filePath(id: string): string {
-    return join(this.storagePath, `${id}.json`);
+    if (!isValidSessionId(id)) {
+      throw new Error(
+        `Invalid session id ${JSON.stringify(id)} — a session id is opaque and must match `
+        + `${SESSION_ID_PATTERN.source}. It is never a path, so it is refused rather than `
+        + "resolved to a file.",
+      );
+    }
+    return join(this.storagePath, `${createHash("sha256").update(id).digest("hex")}.json`);
   }
 
   read(sessionId: string): SessionData | null {
@@ -264,12 +392,19 @@ export class Session {
    * frameworks. Strict mode is the escape hatch (same as events/seeding).
    */
   private strict: boolean;
+  /**
+   * True when the LAST backend read RAISED rather than returning a miss.
+   * Lets `start()` tell "no such session" from "the store is unreachable".
+   */
+  private lastReadFailed = false;
 
   constructor(backend?: string, config?: SessionConfig) {
-    const backendType = backend
-      ?? config?.backend
-      ?? process.env.TINA4_SESSION_BACKEND
-      ?? "file";
+    const backendType = resolveBackend(
+      backend
+        ?? config?.backend
+        ?? process.env.TINA4_SESSION_BACKEND
+        ?? "file",
+    );
 
     this.ttl = config?.ttl
       ?? (process.env.TINA4_SESSION_TTL ? parseInt(process.env.TINA4_SESSION_TTL, 10) : 3600);
@@ -281,10 +416,11 @@ export class Session {
       case "redis":
         this.handler = new RedisSessionHandler(config);
         break;
-      case "redis-npm": {
-        this.handler = new RedisNpmSessionHandler(config);
-        break;
-      }
+      // `redis-npm` was RETIRED here on 2026-07-31 (a Node-only backend NAME for
+      // the optional `redis` npm driver, still running execFileSync per command).
+      // Its rejection now lives in RETIRED_SESSION_BACKENDS above, so the helpful
+      // migration message survives the generic unknown-name check rather than
+      // being swallowed by it.
       case "valkey": {
         this.handler = new ValkeySessionHandler(config);
         break;
@@ -294,15 +430,30 @@ export class Session {
         this.handler = new MongoSessionHandler(config);
         break;
       }
+      case "memcached":
+      case "memcache": {
+        this.handler = new MemcachedSessionHandler(config);
+        break;
+      }
       case "database":
       case "db": {
         this.handler = new DatabaseSessionHandler(config);
         break;
       }
       case "file":
-      default:
+      case "filesystem":
         this.handler = new FileSessionHandler(config?.path);
         break;
+      default:
+        // Unreachable for a user's typo - resolveBackend already rejected it.
+        // Only a name that IS in VALID_SESSION_BACKENDS but has no case above can
+        // land here, which is a bug in this switch rather than a configuration
+        // error, so it must not be swallowed into a file handler either.
+        throw new Error(
+          `Session backend "${backendType}" is listed in VALID_SESSION_BACKENDS `
+          + "but has no handler case. This is a framework bug, not a "
+          + "configuration error.",
+        );
     }
   }
 
@@ -329,11 +480,23 @@ export class Session {
     Log.error(`Session backend ${op} failed (${handlerName}): ${message}`);
   }
 
-  /** Read through the backend; on FAILURE log + degrade to empty (or re-throw under strict). */
+  /**
+   * Read through the backend; on FAILURE log + degrade to empty (or re-throw
+   * under strict).
+   *
+   * Sets {@link lastReadFailed} so `start()` can tell "the store answered, and
+   * has no such session" from "the store did not answer at all". Strict mode
+   * must discard an id only on the first: treating an outage as an unknown id
+   * rotates the session id on EVERY request for the whole outage, logging the
+   * entire userbase out over one Redis blip and orphaning their stored
+   * sessions. The policy is log-loud + degrade, never rotate.
+   */
   private safeRead(sessionId: string): SessionData | null {
+    this.lastReadFailed = false;
     try {
       return this.handler.read(sessionId);
     } catch (err) {
+      this.lastReadFailed = true;
       this.logBackendError("read", err);
       if (this.strict) throw err;
       return null;
@@ -366,27 +529,66 @@ export class Session {
 
   /**
    * Start or resume a session.
+   *
+   * `sessionId` is UNTRUSTED — it arrives from the session cookie, which the
+   * client fully controls. An id that is not a well-formed opaque identifier is
+   * DISCARDED and a fresh one minted, never adopted: adopting it let a cookie
+   * steer a filesystem path (a `tina4_session=../../OUTSIDE/appconfig` cookie
+   * read an existing .json from outside the session directory into
+   * `session.all()`, then OVERWROTE it on save) and let an attacker pre-plant a
+   * session id that survived the victim's login (session fixation).
+   *
+   * The check runs BEFORE the read, so a hostile id never reaches a handler at
+   * all. A legitimate id from any of the four frameworks passes unchanged.
+   *
+   * STRICT SESSION MODE (deliberate, and Node is the family reference for it):
+   * an id that is WELL-FORMED but UNKNOWN to the backend is also discarded and
+   * a fresh one minted — the `if (loaded)` below only adopts an id the store
+   * actually knows. That is OWASP's strict mode and PHP's own
+   * `session.use_strict_mode=1` default, and it is what stops an attacker
+   * planting a session id that survives the victim's login. The validation
+   * above sits IN FRONT of it; neither replaces the other.
+   *
    * @param sessionId - Existing session ID to resume (optional)
    * @returns The session ID
    */
   start(sessionId?: string): string {
+    if (sessionId !== undefined && !isValidSessionId(sessionId)) {
+      sessionId = undefined;
+    }
     if (sessionId) {
       const loaded = this.safeRead(sessionId);
+      if (!loaded && this.lastReadFailed) {
+        // The store did not ANSWER. That is not evidence the id is unknown, so
+        // keep it and degrade to an empty session rather than rotating.
+        this.sessionId = sessionId;
+        const now = Math.floor(Date.now() / 1000);
+        this.data = { _created: now, _accessed: now };
+        this.dirty = false;
+        return sessionId;
+      }
       if (loaded) {
-        // Check TTL for file backend (Redis handles TTL natively)
+        // Expiry is the HANDLER's job, and it is decided from the record's own
+        // absolute deadline. There used to be a SECOND, relative check here —
+        // `loaded._accessed && (now - loaded._accessed) > this.ttl` followed by
+        // safeDestroy() — running in series with the handler's absolute one.
+        //
+        // That is the exact shape that made tina4-php's file backend destroy
+        // records on read (a missing stamp fed into a subtraction, failure branch
+        // deletes). It was defused here only by the leading `loaded._accessed &&`
+        // short-circuit, and it was a landmine: two expiry mechanisms on the same
+        // data, one of them the broken shape, and this one judged a stored record
+        // against whatever ttl the READER happened to carry rather than the
+        // deadline the record was written with.
         const now = Math.floor(Date.now() / 1000);
-        if (loaded._accessed && (now - loaded._accessed) > this.ttl) {
-          this.safeDestroy(sessionId);
-        } else {
-          this.sessionId = sessionId;
-          this.data = loaded;
-          this.data._accessed = now;
-          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;
-        }
+        this.sessionId = sessionId;
+        this.data = loaded;
+        this.data._accessed = now;
+        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;
       }
     }
 
@@ -634,6 +836,21 @@ export function sessionCookieName(): string {
   return process.env.TINA4_SESSION_NAME ?? "tina4_session";
 }
 
+/**
+ * Is TINA4_SESSION_STRICT on? The single source of truth for the flag.
+ *
+ * Module level, not a Session field, because the REQUEST PATH has to be able to
+ * consult it when a Session could not be constructed at all - a handler whose
+ * constructor raises, or a refused TINA4_SESSION_BACKEND, both fail BEFORE
+ * there is an object to ask. That gap is why strict mode used to be inert on
+ * the request path. Parity with Python `session.session_strict_mode()`.
+ *
+ *   TINA4_SESSION_STRICT   re-throw instead of degrading (default: false)
+ */
+export function sessionStrictMode(): boolean {
+  return isTruthy(process.env.TINA4_SESSION_STRICT);
+}
+
 /**
  * Build the `Set-Cookie` header value for a Tina4 session. Centralised so
  * the auto-cookie path in server.ts and `Session.cookieHeader()` agree on