tina4-nodejs 3.13.137 → 3.13.139

package/packages/core/src/response.ts

@@ -1,3 +1,11 @@
+/*
+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 { ServerResponse } from "node:http";
 import fs from "node:fs";
 import nodePath from "node:path";
@@ -24,6 +32,39 @@ async function closeSource(source: AsyncIterable<unknown>): Promise<void> {
   }
 }
 
+/** RFC 9110 `token`: one or more `tchar`. */
+const HEADER_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+/**
+ * The caller's name as a JSON string literal with non-ASCII escaped, byte-
+ * identical to Python's json.dumps (ADR-0068), so a name that is itself broken
+ * cannot break the error message or the log line carrying it.
+ */
+export function quoteHeaderName(name: string): string {
+  return JSON.stringify(name).replace(/[\u007f-\uffff]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+}
+
+/** A TypeError carrying node:http's own error code, as setHeader() throws natively. */
+function headerRefusal(message: string, code: string): TypeError {
+  return Object.assign(new TypeError(message), { code });
+}
+
+/**
+ * Refuse a response header whose name is not an HTTP token or whose value
+ * carries CR, LF or NUL, with the exact ADR-0068 wording. node:http refuses
+ * these too, but names a broken header raw (a CR/LF in the name reaches the
+ * log line) - this is the ADR's form, checked first.
+ */
+export function assertSafeHeader(name: string, value: unknown): void {
+  if (!HEADER_TOKEN.test(name)) {
+    throw headerRefusal(`Header name must be a valid HTTP token [${quoteHeaderName(name)}]`, "ERR_INVALID_HTTP_TOKEN");
+  }
+  const values = Array.isArray(value) ? value : [value];
+  if (values.some((item) => /[\r\n\0]/.test(String(item)))) {
+    throw headerRefusal(`Invalid character in header content [${quoteHeaderName(name)}]`, "ERR_INVALID_CHAR");
+  }
+}
+
 /** Cache Frond instances by template directory to avoid repeated instantiation. */
 const _frondCache = new Map<string, InstanceType<any>>();
 
@@ -147,10 +188,24 @@ export function createResponse(res: ServerResponse): Tina4Response {
       res.end(chunk, encoding);
     }
   };
+  // Every header this Response sets goes through here, so every one is
+  // checked (ADR-0068) - even after the headers are sent, since an unsafe
+  // value is a bug in the code that built it either way.
   const safeSetHeader = (name: string, value: string | number | readonly string[]) => {
+    assertSafeHeader(name, value);
     if (!res.headersSent) res.setHeader(name, value);
   };
 
+  // True once the route set Content-Type with header(); response(data) then
+  // keeps it instead of detecting one (ADR-0072, #144).
+  let contentTypeFromHeader = false;
+  const setDetectedContentType = (contentType: string) => {
+    if (!contentTypeFromHeader) safeSetHeader("Content-Type", contentType);
+  };
+  const noteContentTypeHeader = (name: string) => {
+    if (name.toLowerCase() === "content-type") contentTypeFromHeader = true;
+  };
+
   // ── The callable: response(data, status, contentType) ──
   const response = function (data?: unknown, statusCode?: number, contentType?: string): Tina4Response {
     if (res.headersSent) return response;
@@ -158,6 +213,10 @@ export function createResponse(res: ServerResponse): Tina4Response {
     // Normalise ORM models / collections / query results so handlers can
     // `return response(model)` without serialising by hand.
     data = toJsonable(data);
+    // Any byte array is a binary body: view it as a Buffer (no copy) so every branch below writes it as bytes.
+    if (data instanceof Uint8Array && !Buffer.isBuffer(data)) {
+      data = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    }
 
     if (statusCode !== undefined) {
       res.statusCode = statusCode;
@@ -166,21 +225,23 @@ export function createResponse(res: ServerResponse): Tina4Response {
     if (contentType) {
       // Explicit content type
       safeSetHeader("Content-Type", contentType);
-      if (typeof data === "object" && data !== null && !Buffer.isBuffer(data)) {
+      if (Buffer.isBuffer(data)) {
+        safeEnd(data);
+      } else if (typeof data === "object" && data !== null) {
         safeEnd(JSON.stringify(data));
       } else {
         safeEnd(data == null ? "" : String(data));
       }
     } else if (typeof data === "object" && data !== null && !Buffer.isBuffer(data)) {
       // dict/array → auto JSON
-      safeSetHeader("Content-Type", "application/json");
+      setDetectedContentType("application/json");
       safeEnd(JSON.stringify(data));
     } else if (typeof data === "string") {
       const trimmed = data.trim();
       if (trimmed.startsWith("<") && trimmed.endsWith(">")) {
-        safeSetHeader("Content-Type", "text/html; charset=utf-8");
+        setDetectedContentType("text/html; charset=utf-8");
       } else {
-        safeSetHeader("Content-Type", "text/plain; charset=utf-8");
+        setDetectedContentType("text/plain; charset=utf-8");
       }
       safeEnd(data);
     } else if (Buffer.isBuffer(data)) {
@@ -191,7 +252,7 @@ export function createResponse(res: ServerResponse): Tina4Response {
     } else if (data == null) {
       safeEnd("");
     } else {
-      safeSetHeader("Content-Type", "text/plain; charset=utf-8");
+      setDetectedContentType("text/plain; charset=utf-8");
       safeEnd(String(data));
     }
 
@@ -246,6 +307,7 @@ export function createResponse(res: ServerResponse): Tina4Response {
 
   response.header = function (name: string, value: string | number | readonly string[]): Tina4Response {
     safeSetHeader(name, value);
+    noteContentTypeHeader(name);
     return response;
   };
 
@@ -254,9 +316,11 @@ export function createResponse(res: ServerResponse): Tina4Response {
    */
   response.addHeader = function (name: string, value: string): void {
     safeSetHeader(name, value);
+    noteContentTypeHeader(name);
   };
 
   response.redirect = function (url: string, code?: number): Tina4Response {
+    assertSafeHeader("Location", url); // before the status changes
     if (res.headersSent) return response;
     res.statusCode = code ?? 302;
     safeSetHeader("Location", url);
@@ -265,6 +329,15 @@ export function createResponse(res: ServerResponse): Tina4Response {
   };
 
   response.cookie = function (name: string, value: string, options?: CookieOptions): Tina4Response {
+    // The name and value are percent-encoded below, so they cannot carry CR,
+    // LF, NUL or ';' to the wire and keep being encoded (ADR-0068). Attribute
+    // values are written as given, so one carrying those is refused: a ';'
+    // would add an attribute (say Domain=) the application never set.
+    for (const attribute of [options?.path, options?.domain, options?.sameSite, options?.maxAge]) {
+      if (attribute !== undefined && /[\r\n\0;]/.test(String(attribute))) {
+        throw headerRefusal(`Invalid character in cookie content [${quoteHeaderName(name)}]`, "ERR_INVALID_CHAR");
+      }
+    }
     const parts = [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`];
     if (options?.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`);
     if (options?.expires) parts.push(`Expires=${options.expires.toUTCString()}`);
@@ -419,6 +492,7 @@ export function createResponse(res: ServerResponse): Tina4Response {
     source: AsyncIterable<string | Buffer>,
     contentType: string = "text/event-stream",
   ): Promise<Tina4Response> {
+    assertSafeHeader("Content-Type", contentType);
     if (res.headersSent) return response;
     res.writeHead(200, {
       "Content-Type": contentType,

package/packages/core/src/routeDiscovery.ts

@@ -1,3 +1,11 @@
+/*
+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 { readdirSync, statSync, mkdirSync, writeFileSync, existsSync } from "node:fs";
 import { join, relative, basename, extname } from "node:path";
 import type { RouteDefinition, RouteHandler, RouteMeta } from "./types.js";

package/packages/core/src/router.ts

@@ -1,3 +1,11 @@
+/*
+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 { RouteHandler, RouteDefinition, RouteMeta, Middleware, MiddlewareSpec, Tina4Request, Tina4Response, WebSocketRouteHandler, WebSocketRouteDefinition } from "./types.js";
 import { isTruthy } from "./dotenv.js";
 import { MiddlewareRunner, isMiddlewareClass } from "./middleware.js";

package/packages/core/src/server.ts

@@ -1,4 +1,13 @@
+/*
+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 { createServer, IncomingMessage, ServerResponse } from "node:http";
+import { createTina4HttpServer, guardUnsafeHeaders, sendTransportRejection } from "./transport.js";
 import { randomBytes } from "node:crypto";
 import { resolve, dirname, join, relative } from "node:path";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
@@ -21,7 +30,7 @@ import {
   TAKEOVER_KILLED,
   TAKEOVER_REFUSALS,
 } from "./portTakeover.js";
-import { createRequest } from "./request.js";
+import { createRequest, PayloadTooLargeError } from "./request.js";
 import {
   resetRequestCaches,
   headStripIntercept,
@@ -36,7 +45,7 @@ import { isDebugMode } from "./errorOverlay.js";
 import { createHealthRoutes } from "./health.js";
 import { rateLimiter } from "./rateLimiter.js";
 import { Log } from "./logger.js";
-import { DevAdmin, RequestInspector, WsTracker, devMutationDenial, DEV_SAFE_METHODS } from "./devAdmin.js";
+import { DevAdmin, RequestInspector, WsTracker, devRequestDenial, devHostAllowed } from "./devAdmin.js";
 import { CLOSE_GOING_AWAY, devReloadWs, serveWebSocketRoute, wsRouteManager } from "./websocket.js";
 import { feedbackEnabled, injectFeedbackWidget } from "./feedback.js";
 import { I18n } from "./i18n.js";
@@ -355,6 +364,35 @@ function findAvailablePort(start: number): number {
   }
 }
 
+/**
+ * Variables that mark a CI run, in ADR-0070's order (ci_env_vars). A run is CI
+ * when any of them holds a value that, trimmed and lower-cased, is non-empty
+ * and not in CI_NOT_SET_VALUES.
+ */
+export const CI_ENVIRONMENT_VARIABLES = ["CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "GITLAB_CI", "BUILDKITE", "JENKINS_URL", "TF_BUILD", "TEAMCITY_VERSION"];
+
+/** Values that say "not under CI" (ADR-0070 ci_not_set_values), compared trimmed and lower-cased. */
+export const CI_NOT_SET_VALUES = ["false", "0", "no", "off"];
+
+/**
+ * Whether the server may open a browser (ADR-0070): only for a developer at a
+ * desk. Every rule is a veto; nothing forces a browser open past one.
+ *
+ *   1. development only - the caller's resolved debug mode, and never with
+ *      TINA4_PRODUCTION truthy or in a cluster worker (the primary decides);
+ *   2. never when TINA4_NO_BROWSER is truthy (true/1/yes/on);
+ *   3. never with --no-browser / a programmatic noBrowser (it can only veto);
+ *   4. never under CI.
+ */
+export function shouldOpenBrowser(isDevelopment: boolean, noBrowser = false): boolean {
+  if (!isDevelopment || isTruthy(process.env.TINA4_PRODUCTION) || cluster.isWorker) return false;
+  if (noBrowser || isTruthy(process.env.TINA4_NO_BROWSER)) return false;
+  return !CI_ENVIRONMENT_VARIABLES.some((name) => {
+    const value = (process.env[name] ?? "").trim().toLowerCase();
+    return value !== "" && !CI_NOT_SET_VALUES.includes(value);
+  });
+}
+
 /**
  * Open the user's default browser after a short delay so the server is ready.
  */
@@ -578,9 +616,9 @@ const HTTP_REASON_PHRASES: Record<number, string> = {
   304: "Not Modified", 307: "Temporary Redirect", 308: "Permanent Redirect",
   400: "Bad Request", 401: "Unauthorized", 403: "Forbidden",
   404: "Not Found", 405: "Method Not Allowed", 406: "Not Acceptable",
-  409: "Conflict", 410: "Gone", 413: "Content Too Large",
+  408: "Request Timeout", 409: "Conflict", 410: "Gone", 413: "Content Too Large",
   415: "Unsupported Media Type", 422: "Unprocessable Content",
-  429: "Too Many Requests",
+  429: "Too Many Requests", 431: "Request Header Fields Too Large",
   500: "Internal Server Error", 501: "Not Implemented",
   502: "Bad Gateway", 503: "Service Unavailable", 504: "Gateway Timeout",
 };
@@ -628,6 +666,9 @@ export function resolveTemplate(pathname: string, templatesDir: string): string
     // Skip underscore-prefixed files even within pages/ — they're private
     // by Hugo/Jekyll convention (helpers, fragments) and shouldn't auto-serve.
     if (cleanPath.split("/").some((seg) => seg.startsWith("_"))) return null;
+    // ADR-0082: a "." / ".." segment (or a backslash) could walk out of pages/
+    // - the only directory that auto-routes. Refuse it outright.
+    if (cleanPath.includes("\\") || cleanPath.split("/").some((seg) => seg === "" || seg === "." || seg === "..")) return null;
     const pagesDir = resolve(templatesDir, TEMPLATE_PAGES_DIR);
     for (const ext of [".twig", ".html"]) {
       if (existsSync(resolve(pagesDir, cleanPath + ext))) {
@@ -1101,21 +1142,6 @@ async function runMatchedRoute(ctx: MatchedRouteContext): Promise<void> {
   const { req, res, match, postMatchMiddleware } = ctx;
   req.params = match.params as never;
 
-  // DEVADMIN-DEC-01/02: fail-closed same-origin + loopback gate on every /__dev
-  // write (POST/PUT/PATCH/DELETE), BEFORE the handler runs. Closes drive-by CSRF
-  // (a cross-origin page POSTing to /file/save then /reload) and a network-exposed
-  // debug box. Scoped to /__dev so /__feedback + /ai are unaffected; GET/HEAD/
-  // OPTIONS are safe and skip the gate. The MCP endpoints keep their own 404 gate
-  // (devMutationDenial skips the mcp prefixes for the loopback part).
-  const devMethod = (req.method ?? "GET").toUpperCase();
-  if (ctx.pathname.startsWith("/__dev") && !DEV_SAFE_METHODS.has(devMethod)) {
-    const denial = devMutationDenial(req);
-    if (denial) {
-      res.json({ ok: false, error: denial.error }, denial.status);
-      return;
-    }
-  }
-
   if (await runGlobalMiddlewarePass(postMatchMiddleware, req, res)) return;
 
   // Auth enforcement lives in enforceRouteAuth (authGate.ts) so the in-process
@@ -1707,6 +1733,10 @@ async function dispatchInner(
   // These four close over nothing but the raw req/res (never ctx), which is
   // why they take no context object at all.
   await resetRequestCaches();
+  // Installed FIRST so it is the innermost wrapper of end()/write(): whatever
+  // the later interceptors do, a response carrying a header node:http refused
+  // leaves as the ADR-0068 500 {"error":"Invalid response header"}.
+  guardUnsafeHeaders(rawRes);
   headStripIntercept(rawReq, rawRes);
   // Feature 40 (CE-DEC-01/02): gzip + ETag + conditional-GET for every
   // dynamic response. Installed right after headStripIntercept so it runs
@@ -1718,6 +1748,11 @@ async function dispatchInner(
   // res.render() is handled natively by response.ts via Frond
 
   try {
+    // Gate before middleware, matching and automatic OPTIONS handling (ADR-0082).
+    if (req.path.replace(/\/+/g, "/").startsWith("/__dev")) {
+      const denial = devRequestDenial(req);
+      if (denial) { res.json({ ok: false, error: denial.error }, denial.status); return; }
+    }
     // sessionAutoStart is the one prologue stage INSIDE the try. It degrades
     // on its own (ADR-0021), so the only thing that escapes it is a
     // TINA4_SESSION_STRICT refusal - and that must become a 500 through the
@@ -1740,6 +1775,16 @@ async function dispatchInner(
     try {
       await req.parseBody();
     } catch (err) {
+      // The transport already answered (a 408 for a stalled body) and the
+      // connection is going away: nothing left to say.
+      if (rawRes.writableEnded) return;
+      // A body over TINA4_MAX_UPLOAD_SIZE is a transport rejection (ADR-0068
+      // section 4): exact body, security headers, and Connection: close, so
+      // node:http does not go on reading the rest of the upload.
+      if (err instanceof PayloadTooLargeError) {
+        sendTransportRejection(rawRes, 413, err.message);
+        return;
+      }
       const status = (err as { statusCode?: number })?.statusCode;
       if (typeof status === "number" && status >= 400 && status < 500) {
         if (!rawRes.writableEnded) {
@@ -1910,7 +1955,7 @@ function startLoopbackSiblings(
     siblingHosts.map(
       (siblingHost) =>
         new Promise<ReturnType<typeof createServer> | null>((resolveSibling) => {
-          const sibling = createServer(dispatch);
+          const sibling = createTina4HttpServer(dispatch);
           let settled = false;
           sibling.on("error", (err: NodeJS.ErrnoException) => {
             const expected =
@@ -2011,9 +2056,14 @@ export async function startServer(config?: Tina4Config): Promise<{
   // 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");
+  const { ensureDevSecret, requireBootSecret } = await import("./auth.js");
   ensureDevSecret();
 
+  // Refuse to serve with a secret anyone can reproduce: blank outside dev, or
+  // set but shorter than 32 bytes in any mode (ADR-0079 s2). Throws the
+  // actionable message naming TINA4_SECRET.
+  requireBootSecret();
+
   // Refuse to boot with pre-3.12 un-prefixed env vars set.
   _checkLegacyEnvVars();
 
@@ -2186,7 +2236,7 @@ export async function startServer(config?: Tina4Config): Promise<{
   // dev; the stable AI port (port+1000, created below) suppresses reload/toolbar so an
   // AI tool can drive it without its own edits triggering refreshes. The tina4 client
   // posts /__dev/api/reload to the MAIN port. Matches Python (master).
-  const server = createServer(dispatch);
+  const server = createTina4HttpServer(dispatch);
 
   // WebSocket upgrade handling on the MAIN port. Two responsibilities:
   //
@@ -2217,6 +2267,11 @@ export async function startServer(config?: Tina4Config): Promise<{
     const upPath = (req.url ?? "/").split("?")[0];
     // Dev-reload channel (debug only).
     if (isDevMode() && upPath === "/__dev_reload") {
+      // ADR-0082: the reload socket answers only a loopback / TINA4_HOST Host.
+      if (!devHostAllowed(req.headers.host)) {
+        try { socket.write("HTTP/1.1 403 Forbidden\r\n\r\n"); socket.destroy(); } catch { /* gone */ }
+        return;
+      }
       devReloadWs.handleUpgrade(req, socket, head);
       return;
     }
@@ -2295,7 +2350,7 @@ export async function startServer(config?: Tina4Config): Promise<{
 
       if (isDebug && !noAiPort && aiPortInRange) {
         // Stable AI port (port+1000): tag requests so /__dev_reload + toolbar are suppressed.
-        aiServer = createServer(async (req, res) => {
+        aiServer = createTina4HttpServer(async (req, res) => {
           (req as any)._tina4AiPort = true;
           await dispatch(req, res);
         });
@@ -2352,8 +2407,7 @@ ${reset}
   Debug:     ${isDebug ? "ON" : "OFF"} (Log level: ${logLevel})${dualPortLines}
 `);
       }
-      const noBrowser = isTruthy(process.env.TINA4_NO_BROWSER);
-      if (!noBrowser) {
+      if (shouldOpenBrowser(isDebug, config?.noBrowser === true)) {
         // Open the browser on the MAIN port — that's the hot-reload port.
         openBrowser(`http://${displayHost}:${port}`);
       }

package/packages/core/src/service.ts

@@ -1,3 +1,11 @@
+/*
+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/.
+*/
+
 /**
  * Service Runner — in-process background services using Node.js timers.
  * Zero dependencies. Supports cron timing, simple intervals, and daemon mode.

package/packages/core/src/session.ts

@@ -1,3 +1,11 @@
+/*
+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 Session — Pluggable session backends, zero core dependencies.
  *

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

@@ -1,3 +1,11 @@
+/*
+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 session handlers — turn a failed `execFileSync` child into a readable cause.
  *

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

@@ -1,3 +1,11 @@
+/*
+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 Database Session Handler — sessions in a `tina4_session` table on ANY
  * engine the ORM Database layer supports: sqlite, postgres, mysql, mssql,
@@ -152,6 +160,16 @@ const CREATE_TABLE: Record<string, string> = {
     `,
 };
 
+/** How many times ensureTable() tries the CREATE before a failure is real. */
+const CREATE_ATTEMPTS = 5;
+/** Base pause between tries; it grows linearly (50, 100, 150, 200 ms). */
+const CREATE_RETRY_DELAY_MS = 50;
+
+/** Block this thread for `ms` - the SessionHandler interface is synchronous. */
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
 /**
  * Read a column out of a result row, case-insensitively.
  *
@@ -215,6 +233,12 @@ export class DatabaseSessionHandler implements SessionHandler {
   private get sqlite(): any {
     if (this.sqliteHandle === null) {
       this.sqliteHandle = new DatabaseSync(this.dbPath as string);
+      // Wait up to 5 s for another process's write lock instead of failing at
+      // once with "database is locked" - node:sqlite's default is NO wait, so
+      // racing processes collided on the first overlap (five of six died,
+      // measured). 5000 ms matches PHP's busyTimeout(5000) and Python's sqlite3
+      // default. Set BEFORE the WAL pragma so that write waits too.
+      this.sqliteHandle.exec("PRAGMA busy_timeout = 5000");
       this.sqliteHandle.exec("PRAGMA journal_mode = WAL");
     }
     return this.sqliteHandle;
@@ -334,16 +358,57 @@ export class DatabaseSessionHandler implements SessionHandler {
   }
 
   /**
-   * Ensure the session table exists (called once on first use).
+   * Ensure the session table exists (called once on first use) - safely when
+   * several processes race to create it.
+   *
+   * Every per-engine statement above is check-then-act, so two processes can
+   * both find the table absent and both CREATE; the loser errors, and every
+   * engine spells that differently (a pg_type unique violation on PostgreSQL,
+   * Msg 2714 on SQL Server, an RDB$RELATIONS unique violation on Firebird). So
+   * a failure is judged by RE-CHECKING whether the table now exists, never by
+   * parsing the message - the rescue the Firebird note above has always
+   * assumed, and which was not here. MEASURED on the lab before it: six real
+   * processes racing lost one to five of them on PostgreSQL, SQLite and
+   * Firebird.
+   *
+   * The re-check is RETRIED because the loser can fail BEFORE the winner has
+   * committed. On MySQL, CREATE TABLE IF NOT EXISTS takes a shared metadata
+   * lock, checks, then upgrades it to exclusive; two upgrades deadlock, and when
+   * MySQL cannot back the victim off silently it answers 1213 "Deadlock found"
+   * while the winner's table is still invisible (tina4-php CI run 35972320442).
+   * Bounded, so a genuine failure (no CREATE grant) still throws. Same attempts
+   * and delays in all four frameworks.
    */
   private ensureTable(): void {
     if (this.initialized) return;
     const ddl = CREATE_TABLE[this.engine];
-    if (this.target === null) this.sqlite.exec(ddl);
-    else sqlCommandSync(this.target, ddl, []);
+    for (let attempt = 1; ; attempt++) {
+      try {
+        if (this.target === null) this.sqlite.exec(ddl);
+        else sqlCommandSync(this.target, ddl, []);
+        break;
+      } catch (error) {
+        if (this.tableExists()) break;
+        if (attempt >= CREATE_ATTEMPTS) throw error;
+        sleepSync(CREATE_RETRY_DELAY_MS * attempt);
+      }
+    }
     this.initialized = true;
   }
 
+  /**
+   * Whether tina4_session exists, asked the one way every engine answers alike:
+   * a query against it that returns no rows succeeds only if it is there.
+   */
+  private tableExists(): boolean {
+    try {
+      this.query("SELECT 1 FROM tina4_session WHERE 1 = 0", []);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   read(sessionId: string): SessionData | null {
     this.ensureTable();
 

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

@@ -1,3 +1,11 @@
+/*
+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 Memcached Session Handler — zero-dependency text protocol over TCP.
  *

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

@@ -1,3 +1,11 @@
+/*
+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 synchronous MongoDB transport — ONE persistent client per target.
  *

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

@@ -1,3 +1,11 @@
+/*
+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 MongoDB Session Handler — MongoDB wire protocol via raw TCP, zero dependencies.
  *

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

@@ -1,3 +1,11 @@
+/*
+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 synchronous RESP transport — shared by every Redis/Valkey session handler.
  *

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

@@ -1,3 +1,11 @@
+/*
+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 synchronous SQL transport for the database session backend.
  *

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

@@ -1,3 +1,11 @@
+/*
+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 sync-over-async bridge — call an ASYNC worker from SYNCHRONOUS code.
  *

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

@@ -1,3 +1,11 @@
+/*
+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 synchronous socket transport — ONE persistent connection per target.
  *

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

@@ -1,3 +1,11 @@
+/*
+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 Valkey Session Handler — Valkey (Redis-compatible) via raw TCP, zero dependencies.
  *