tina4-nodejs 3.13.141 → 3.13.143

package/packages/core/src/session.ts

@@ -37,7 +37,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, readdir
 import { join } from "node:path";
 import { Log } from "./logger.js";
 import { isTruthy } from "./dotenv.js";
-import { respCommandSync } from "./sessionHandlers/respClient.js";
+import { RespSessionHandler } from "./sessionHandlers/respSessionHandler.js";
 import { ValkeySessionHandler } from "./sessionHandlers/valkeyHandler.js";
 import { MemcachedSessionHandler } from "./sessionHandlers/memcachedHandler.js";
 import { MongoSessionHandler } from "./sessionHandlers/mongoHandler.js";
@@ -304,81 +304,59 @@ export class FileSessionHandler implements SessionHandler {
  *
  * Or pass via SessionConfig.
  */
-export class RedisSessionHandler implements SessionHandler {
-  private host: string;
-  private port: number;
-  private password: string;
-  private prefix: string;
-  private db: number;
-
+export class RedisSessionHandler extends RespSessionHandler {
   constructor(config?: SessionConfig) {
-    this.host = config?.redisHost
-      ?? process.env.TINA4_SESSION_REDIS_HOST
-      ?? "127.0.0.1";
-    this.port = config?.redisPort
-      ?? (process.env.TINA4_SESSION_REDIS_PORT
-        ? parseInt(process.env.TINA4_SESSION_REDIS_PORT, 10)
-        : 6379);
-    this.password = config?.redisPassword
-      ?? process.env.TINA4_SESSION_REDIS_PASSWORD
-      ?? "";
-    this.prefix = config?.redisPrefix
-      ?? process.env.TINA4_SESSION_REDIS_PREFIX
-      ?? "tina4:session:";
-    this.db = config?.redisDb
-      ?? (process.env.TINA4_SESSION_REDIS_DB
-        ? parseInt(process.env.TINA4_SESSION_REDIS_DB, 10)
-        : 0);
-  }
-
-  /**
-   * Execute a Redis command synchronously against the live server.
-   *
-   * Delegates to the shared {@link respCommandSync} transport: a genuine key miss
-   * yields `""`, and a transport/connection FAILURE (server unreachable, rejected
-   * AUTH, timeout) THROWS so the Session boundary can distinguish "not found"
-   * (silent) from "backend failed" (log-loud + degrade). Backend-failure parity.
-   */
-  private execSync(args: string[]): string {
-    return respCommandSync(
-      { host: this.host, port: this.port, password: this.password, db: this.db },
-      args,
+    super(
+      {
+        host: config?.redisHost
+          ?? process.env.TINA4_SESSION_REDIS_HOST
+          ?? "127.0.0.1",
+        port: config?.redisPort
+          ?? (process.env.TINA4_SESSION_REDIS_PORT
+            ? parseInt(process.env.TINA4_SESSION_REDIS_PORT, 10)
+            : 6379),
+        password: config?.redisPassword
+          ?? process.env.TINA4_SESSION_REDIS_PASSWORD
+          ?? "",
+        prefix: config?.redisPrefix
+          ?? process.env.TINA4_SESSION_REDIS_PREFIX
+          ?? "tina4:session:",
+        db: config?.redisDb
+          ?? (process.env.TINA4_SESSION_REDIS_DB
+            ? parseInt(process.env.TINA4_SESSION_REDIS_DB, 10)
+            : 0),
+      },
       "Redis",
     );
   }
+}
 
-  private key(sessionId: string): string {
-    return `${this.prefix}${sessionId}`;
-  }
+// ── Flash data prefix ─────────────────────────────────────────────
 
-  read(sessionId: string): SessionData | null {
-    const raw = this.execSync(["GET", this.key(sessionId)]);
-    if (!raw) return null;     // key miss — normal "no session yet", NOT an error
-    try {
-      return JSON.parse(raw) as SessionData;
-    } catch {
-      return null;
-    }
-  }
+const FLASH_PREFIX = "_flash_";
 
-  write(sessionId: string, data: SessionData, ttl: number = 0): void {
-    const json = JSON.stringify(data);
-    if (ttl > 0) {
-      this.execSync(["SETEX", this.key(sessionId), String(ttl), json]);
-    } else {
-      this.execSync(["SET", this.key(sessionId), json]);
-    }
+/**
+ * The stored form of a value, for telling whether a request changed it.
+ * undefined when it cannot be serialised (a BigInt, a cycle): that always
+ * counts as changed, because writing a value again is harmless and missing a
+ * change is not.
+ */
+function fingerprint(value: unknown): string | undefined {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return undefined;
   }
+}
 
-  destroy(sessionId: string): void {
-    this.execSync(["DEL", this.key(sessionId)]);
+function fingerprints(data: SessionData): Map<string, string | undefined> {
+  const prints = new Map<string, string | undefined>();
+  for (const [key, value] of Object.entries(data)) {
+    prints.set(key, fingerprint(value));
   }
+  return prints;
 }
 
-// ── Flash data prefix ─────────────────────────────────────────────
-
-const FLASH_PREFIX = "_flash_";
-
 // ── Session Class ─────────────────────────────────────────────────
 
 export class Session {
@@ -405,6 +383,29 @@ export class Session {
    * Lets `start()` tell "no such session" from "the store is unreachable".
    */
   private lastReadFailed = false;
+  /**
+   * What this request last saw of the stored record, one fingerprint per key:
+   * taken by start() and again by every save. save() compares the live data
+   * against it to find the keys THIS request changed.
+   */
+  private loaded = new Map<string, string | undefined>();
+  /**
+   * True when this request is working on a record the store holds: start()
+   * adopted one, or a save has written one since. A save never re-creates such
+   * a record once another request has removed it.
+   */
+  private stored = false;
+  /**
+   * True when clear() ran since the last save: the save then replaces the
+   * stored record instead of merging into it.
+   */
+  private cleared = false;
+  /**
+   * True once this request found its session ended by another request (the
+   * record it loaded is gone). It stays ended for the rest of the request:
+   * regenerate() mints nothing either.
+   */
+  private ended = false;
 
   constructor(backend?: string, config?: SessionConfig) {
     const backendType = resolveBackend(
@@ -573,6 +574,11 @@ export class Session {
         const now = Math.floor(Date.now() / 1000);
         this.data = { _created: now, _accessed: now };
         this.dirty = false;
+        // Not a record this request has seen, so its first save writes whole.
+        this.stored = false;
+        this.loaded = new Map();
+        this.cleared = false;
+        this.ended = false;
         return sessionId;
       }
       if (loaded) {
@@ -596,6 +602,10 @@ export class Session {
         // 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);
+        this.stored = true;
+        this.loaded = fingerprints(this.data);
+        this.cleared = false;
+        this.ended = false;
         return sessionId;
       }
     }
@@ -606,6 +616,10 @@ export class Session {
     this.data = { _created: now, _accessed: now };
     this.dirty = false;
     this.safeWrite(this.sessionId, this.data, this.ttl);
+    this.stored = false;
+    this.loaded = new Map();
+    this.cleared = false;
+    this.ended = false;
     return this.sessionId;
   }
 
@@ -650,9 +664,7 @@ export class Session {
     if (this.sessionId) {
       this.safeDestroy(this.sessionId);
     }
-    this.sessionId = null;
-    this.data = null;
-    this.dirty = false;
+    this.forget();
   }
 
   /**
@@ -677,6 +689,7 @@ export class Session {
     const now = Math.floor(Date.now() / 1000);
     this.data = { _created: this.data._created, _accessed: now };
     this.dirty = true;
+    this.cleared = true;
     this.save();
   }
 
@@ -695,8 +708,27 @@ export class Session {
    * 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.
+   *
+   * What is carried is the session as it is stored now with this request's
+   * own changes applied, the same merge save() does. If another request ended
+   * the session after this one loaded it (a logout, or a regenerate of its
+   * own), it stays ended: nothing is carried, no id is minted and null is
+   * returned, so no cookie goes out to replace the one that request sent.
    */
-  regenerate(): string {
+  regenerate(): string | null {
+    if (this.ended) return null;
+    if (this.sessionId && this.stored && this.data) {
+      const current = this.safeRead(this.sessionId);
+      if (!this.lastReadFailed) {
+        if (!current) {
+          this.forget();
+          this.ended = true;
+          return null;
+        }
+        if (!this.cleared) this.data = this.merged(current);
+      }
+    }
+
     const oldId = this.sessionId;
     const oldData = this.data;
 
@@ -710,6 +742,8 @@ export class Session {
     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;
+    // The new id has no record yet: write everything to it.
+    this.stored = false;
     this.save();
     return this.sessionId;
   }
@@ -793,17 +827,86 @@ export class Session {
    *
    * 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.
+   * retries once the backend recovers. A call with no session returns true.
+   *
+   * Other requests on the same session run while this one does, so the save
+   * writes only THIS request's changes, onto the record as it is stored now.
+   * Writing back the whole snapshot start() loaded undid whatever another
+   * request did in between: a logout (destroy, clear, regenerate) or a
+   * privilege change made with set(). A record removed since this request
+   * loaded it is never re-created: the session has ended, for this request
+   * too. A request that has not loaded a stored record (a new session, the new
+   * id regenerate() mints) writes its data whole, as before.
+   *
+   * A session the store already holds is re-written even when this request
+   * changed nothing: that write re-stamps the backend deadline to
+   * now + TINA4_SESSION_TTL, so a session expires after that span of INACTIVITY
+   * rather than that long after its last CHANGE (ADR-0087 — a session's expiry
+   * slides on activity). The re-write is the re-read, merged record, so sliding
+   * the deadline is concurrent-safe: it never clobbers another request's change,
+   * never re-creates an ended record, and TINA4_SESSION_TTL=0 still re-stamps a
+   * never-expires deadline (ADR-0027). A request with no stored session and no
+   * change writes nothing — there is no deadline to move.
    */
   save(): boolean {
     if (!this.sessionId || !this.data) return true;
-    if (!this.dirty) return true;
-    if (this.safeWrite(this.sessionId, this.data, this.ttl)) {
+    if (!this.dirty && !this.stored) return true;
+    let record: SessionData = this.data;
+    if (this.stored) {
+      const current = this.safeRead(this.sessionId);
+      if (this.lastReadFailed) return false;  // nothing written; dirty RETAINED for retry
+      if (!current) {
+        this.forget();
+        this.ended = true;
+        return true;
+      }
+      if (!this.cleared) record = this.merged(current);
+    }
+    if (this.safeWrite(this.sessionId, record, this.ttl)) {
       this.dirty = false;
+      this.stored = true;
+      this.cleared = false;
+      this.loaded = fingerprints(this.data);
       return true;
     }
     return false;  // write failed (logged); dirty RETAINED for retry
   }
+
+  /**
+   * The stored record with this request's changes applied: every key whose
+   * value differs from what this request loaded or last saved, and the
+   * removal of every key it deleted. Keys it did not touch keep whatever is
+   * stored now.
+   */
+  private merged(current: SessionData): SessionData {
+    const data = this.data as SessionData;
+    const record: SessionData = { ...current };
+    for (const [key, value] of Object.entries(data)) {
+      const print = fingerprint(value);
+      if (print === undefined || !this.loaded.has(key) || this.loaded.get(key) !== print) {
+        record[key] = value;
+      }
+    }
+    for (const key of this.loaded.keys()) {
+      if (!Object.prototype.hasOwnProperty.call(data, key)) {
+        delete record[key];
+      }
+    }
+    return record;
+  }
+
+  /**
+   * End the session for this request without touching the store: no id and
+   * no data, so nothing more is written and no cookie goes out for it.
+   */
+  private forget(): void {
+    this.sessionId = null;
+    this.data = null;
+    this.dirty = false;
+    this.stored = false;
+    this.cleared = false;
+    this.loaded = new Map();
+  }
 }
 
 /**

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

@@ -0,0 +1,94 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
+/**
+ * Tina4 RESP Session Handler base — the shared store logic behind Redis and
+ * Valkey, zero dependencies.
+ *
+ * Redis and Valkey speak the same RESP protocol, so the read/write/destroy
+ * transport is byte-for-byte identical between them — only the configuration
+ * variable names and the log label differ. That difference lives entirely in
+ * each subclass constructor; everything the session store actually DOES lives
+ * here, once. A subclass resolves its own host/port/password/prefix/db from
+ * config or environment, then hands a {@link RespConnection} plus a label to
+ * `super()`.
+ */
+import type { SessionHandler } from "../session.js";
+import { respCommandSync } from "./respClient.js";
+
+interface SessionData {
+  _created: number;
+  _accessed: number;
+  [key: string]: unknown;
+}
+
+/** Resolved connection details a RESP session handler needs. */
+export interface RespConnection {
+  host: string;
+  port: number;
+  password: string;
+  prefix: string;
+  db: number;
+}
+
+/**
+ * RESP (Redis/Valkey) session handler using raw TCP — no external client.
+ *
+ * Stores session data as JSON strings with a server-side TTL for automatic
+ * expiry. A genuine key miss yields `null`; a transport/connection FAILURE
+ * (server unreachable, rejected AUTH, timeout) THROWS so the Session boundary
+ * can tell "not found" (silent) from "backend failed" (log-loud + degrade).
+ */
+export abstract class RespSessionHandler implements SessionHandler {
+  protected constructor(
+    private readonly conn: RespConnection,
+    private readonly label: string,
+  ) {}
+
+  /**
+   * Execute a RESP command synchronously against the live server.
+   *
+   * Delegates to the shared {@link respCommandSync} transport: a genuine key
+   * miss yields `""`, and a transport/connection FAILURE THROWS so the caller
+   * can distinguish "not found" from "backend failed". Backend-failure parity.
+   */
+  private execSync(args: string[]): string {
+    return respCommandSync(
+      { host: this.conn.host, port: this.conn.port, password: this.conn.password, db: this.conn.db },
+      args,
+      this.label,
+    );
+  }
+
+  private key(sessionId: string): string {
+    return `${this.conn.prefix}${sessionId}`;
+  }
+
+  read(sessionId: string): SessionData | null {
+    const raw = this.execSync(["GET", this.key(sessionId)]);
+    if (!raw) return null;     // key miss — normal "no session yet", NOT an error
+    try {
+      return JSON.parse(raw) as SessionData;
+    } catch {
+      return null;
+    }
+  }
+
+  write(sessionId: string, data: SessionData, ttl: number = 0): void {
+    const json = JSON.stringify(data);
+    if (ttl > 0) {
+      this.execSync(["SETEX", this.key(sessionId), String(ttl), json]);
+    } else {
+      this.execSync(["SET", this.key(sessionId), json]);
+    }
+  }
+
+  destroy(sessionId: string): void {
+    this.execSync(["DEL", this.key(sessionId)]);
+  }
+}

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

@@ -19,14 +19,7 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/.
  *   TINA4_SESSION_VALKEY_PREFIX   (default: "tina4:session:")
  *   TINA4_SESSION_VALKEY_DB       (default: 0)
  */
-import type { SessionHandler } from "../session.js";
-import { respCommandSync } from "./respClient.js";
-
-interface SessionData {
-  _created: number;
-  _accessed: number;
-  [key: string]: unknown;
-}
+import { RespSessionHandler } from "./respSessionHandler.js";
 
 export interface ValkeySessionConfig {
   host?: string;
@@ -55,73 +48,29 @@ export interface ValkeySessionConfig {
  * Valkey uses the same RESP protocol as Redis, so this handler is functionally
  * identical to RedisSessionHandler but with VALKEY config variable names.
  */
-export class ValkeySessionHandler implements SessionHandler {
-  private host: string;
-  private port: number;
-  private password: string;
-  private prefix: string;
-  private db: number;
-
+export class ValkeySessionHandler extends RespSessionHandler {
   constructor(config?: ValkeySessionConfig) {
-    this.host = config?.host
-      ?? process.env.TINA4_SESSION_VALKEY_HOST
-      ?? "127.0.0.1";
-    this.port = config?.port
-      ?? (process.env.TINA4_SESSION_VALKEY_PORT
-        ? parseInt(process.env.TINA4_SESSION_VALKEY_PORT, 10)
-        : 6379);
-    this.password = config?.password
-      ?? process.env.TINA4_SESSION_VALKEY_PASSWORD
-      ?? "";
-    this.prefix = config?.prefix
-      ?? process.env.TINA4_SESSION_VALKEY_PREFIX
-      ?? "tina4:session:";
-    this.db = config?.db
-      ?? (process.env.TINA4_SESSION_VALKEY_DB
-        ? parseInt(process.env.TINA4_SESSION_VALKEY_DB, 10)
-        : 0);
-  }
-
-  /**
-   * Execute a RESP command synchronously against the live Valkey server.
-   *
-   * Delegates to the shared {@link respCommandSync} transport: a genuine key miss
-   * yields `""`, and a transport/connection FAILURE (server unreachable, rejected
-   * AUTH, timeout) THROWS so the Session boundary can distinguish "not found"
-   * (silent) from "backend failed" (log-loud + degrade). Backend-failure parity.
-   */
-  private execSync(args: string[]): string {
-    return respCommandSync(
-      { host: this.host, port: this.port, password: this.password, db: this.db },
-      args,
+    super(
+      {
+        host: config?.host
+          ?? process.env.TINA4_SESSION_VALKEY_HOST
+          ?? "127.0.0.1",
+        port: config?.port
+          ?? (process.env.TINA4_SESSION_VALKEY_PORT
+            ? parseInt(process.env.TINA4_SESSION_VALKEY_PORT, 10)
+            : 6379),
+        password: config?.password
+          ?? process.env.TINA4_SESSION_VALKEY_PASSWORD
+          ?? "",
+        prefix: config?.prefix
+          ?? process.env.TINA4_SESSION_VALKEY_PREFIX
+          ?? "tina4:session:",
+        db: config?.db
+          ?? (process.env.TINA4_SESSION_VALKEY_DB
+            ? parseInt(process.env.TINA4_SESSION_VALKEY_DB, 10)
+            : 0),
+      },
       "Valkey",
     );
   }
-
-  private key(sessionId: string): string {
-    return `${this.prefix}${sessionId}`;
-  }
-
-  read(sessionId: string): SessionData | null {
-    const raw = this.execSync(["GET", this.key(sessionId)]);
-    if (!raw) return null;     // key miss — normal "no session yet", NOT an error
-    try {
-      return JSON.parse(raw) as SessionData;
-    } catch {
-      return null;
-    }
-  }
-
-  write(sessionId: string, data: SessionData, ttl: number): void {
-    const json = JSON.stringify(data);
-    if (ttl > 0) {
-      this.execSync(["SETEX", this.key(sessionId), String(ttl), json]);
-    } else {
-      this.execSync(["SET", this.key(sessionId), json]);
-    }
-  }
-
-  destroy(sessionId: string): void {
-    this.execSync(["DEL", this.key(sessionId)]);
-  }
 }

package/packages/core/src/sso.ts

@@ -26,7 +26,7 @@ type SessionLike = {
   get(key: string): unknown;
   set(key: string, value: unknown): void;
   delete(key: string): void;
-  regenerate(): string;
+  regenerate(): string | null;
   destroy(): void;
 };
 

package/packages/core/src/static.ts

@@ -10,6 +10,7 @@ import { readFileSync, realpathSync, statSync, type Stats } from "node:fs";
 import { join, extname, sep } from "node:path";
 import { gzipSync } from "node:zlib";
 import type { Tina4Request, Tina4Response } from "./types.js";
+import { etagMatches } from "./etag.js";
 
 /** Content-type prefixes that benefit from gzip. Mirrors the Python master's `_is_compressible`. */
 const COMPRESSIBLE_PREFIXES = [
@@ -200,16 +201,3 @@ function isNotModified(req: Tina4Request, etag: string, stat: Stats): boolean {
   return false;
 }
 
-/**
- * Weak comparison of an `If-None-Match` value against our ETag. The header may
- * be `*`, a single tag, or a comma-separated list; the `W/` weak prefix is
- * stripped on both sides before comparing (RFC 7232 §2.3.2 weak comparison).
- */
-function etagMatches(ifNoneMatch: string, etag: string): boolean {
-  const strip = (tag: string) => tag.trim().replace(/^W\//, "");
-  const target = strip(etag);
-  return ifNoneMatch.split(",").some((candidate) => {
-    const trimmed = candidate.trim();
-    return trimmed === "*" || strip(trimmed) === target;
-  });
-}

package/packages/core/src/types.ts

@@ -126,6 +126,14 @@ export interface Tina4ResponseMethods {
   stream(source: AsyncIterable<string | Buffer>, contentType?: string): Promise<Tina4Response>;
   /** The underlying ServerResponse for advanced use */
   raw: ServerResponse;
+  /**
+   * This response's Content-Security-Policy nonce (ADR-0088). `runDispatch()`
+   * mints one per request and publishes it on the async-context (csp.ts) so the
+   * framework's inline `<style>`/`<script>`, the Frond `csp_nonce()` global, and
+   * the value the security middleware names in the header all agree. Stamp it on
+   * any inline block a route emits: `<script nonce="${res.cspNonce}">`.
+   */
+  cspNonce: string;
 }
 
 /**

package/packages/core/src/upstreamResponse.ts

@@ -0,0 +1,31 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
+import type { Tina4Response } from "./types.js";
+
+/**
+ * Relay a drained upstream (proxied) response to the client.
+ *
+ * The body is read to a string once, then returned as JSON when it parses and
+ * as raw text with the upstream Content-Type otherwise, keeping the upstream
+ * status either way. Shared by the dev-admin supervisor proxy and the feedback
+ * agent proxy so both pass a backend response through identically.
+ */
+export async function relayUpstreamResponse(res: Tina4Response, upstream: Response): Promise<void> {
+  const raw = await upstream.text();
+  const status = upstream.status || 200;
+  try {
+    res.json(JSON.parse(raw), status);
+  } catch {
+    // Non-JSON upstream — pass through as text with the same status.
+    res.raw.writeHead(status, {
+      "Content-Type": upstream.headers.get("content-type") ?? "text/plain; charset=utf-8",
+    });
+    res.raw.end(raw);
+  }
+}