tina4-nodejs 3.13.94 → 3.13.96

package/types/core/src/middleware.d.ts

@@ -18,6 +18,18 @@ export declare class MiddlewareChain {
      */
     run(req: Tina4Request, res: Tina4Response): Promise<boolean>;
 }
+/**
+ * True when a middleware spec is a CLASS (the beforeX/afterX convention)
+ * rather than a plain `(req, res, next)` middleware function.
+ *
+ * A class's `prototype` property is non-writable by the language spec
+ * (ClassDefinitionEvaluation); an ordinary function's is writable, and an
+ * arrow function, async function or bound function has no `prototype` at all.
+ * That is a language-level distinction rather than a name or source-string
+ * sniff, so a class named `cors` and a function named `Cors` both classify
+ * correctly.
+ */
+export declare function isMiddlewareClass(spec: unknown): boolean;
 export declare class MiddlewareRunner {
     /** Globally registered middleware classes (parity with PHP/Ruby/Python orchestrators). */
     private static globalMiddleware;
@@ -28,18 +40,58 @@ export declare class MiddlewareRunner {
      */
     static use(cls: any): void;
     /** Return the list of globally registered middleware classes. */
+    /**
+     * Global middleware that runs BEFORE route matching.
+     *
+     * A middleware opts in with `static preMatch = true`. Everything else stays
+     * where it has always run - after matching - so this is additive and no
+     * existing middleware changes behaviour.
+     *
+     * The two groups need opposite things. CORS must run before matching so its
+     * headers survive a short-circuited 401/403; a browser shown a 401 without
+     * them reports a CORS error and the real status never reaches the developer.
+     * CSRF must run AFTER, because it reads the matched route's metadata to
+     * honour a route marked noAuth - PHP shipped exactly that bypass as dead
+     * code once, because the metadata was not assigned yet.
+     *
+     * NOT named `beforeMatch` - hook discovery treats every `before*` static as
+     * a middleware hook and would call the flag itself with (req, res).
+     */
+    static partitionByMatchPhase(all: any[]): {
+        pre: any[];
+        post: any[];
+    };
     static getGlobal(): any[];
     /** Clear all globally registered middleware (primarily for tests). */
     static reset(): void;
     /**
-     * Discover the before-prefixed / after-prefixed method names on a
-     * middleware class in DEFINITION order (M1).
-     * `Object.getOwnPropertyNames` returns a class's own
-     * static method names in source-declaration order — we deliberately do NOT
-     * sort() them, so within a class the hooks run in the order they were
-     * written (parity with Python walking __dict__, PHP get_class_methods, Ruby
+     * Discover the before-prefixed / after-prefixed hook names on a middleware
+     * class, INHERITED HOOKS INCLUDED, base class first (M1).
+     *
+     * `Object.getOwnPropertyNames` returns a class's OWN statics only, in
+     * source-declaration order. On its own that silently DROPPED every hook a
+     * subclass inherited: for `class Sub extends Base` with `static beforeBase`
+     * on the base, discovery returned only ["beforeSub"] even though
+     * `Sub.beforeBase` is a live function — so a shared base middleware simply
+     * never ran, with no error. Python returns ['before_base','before_sub'] and
+     * Ruby [:before_base,:before_sub]; Node was the only one of the four that
+     * lost hooks.
+     *
+     * So walk the prototype chain (the STATIC side: Sub -> Base -> ...) and emit
+     * base-class hooks BEFORE the subclass's own, de-duping an override to its
+     * first (base) position. That is exactly Python's `_discover_methods`
+     * walking `reversed(__mro__)` over each `__dict__`, and Ruby's
+     * `discover_methods` walking `ancestors.reverse_each`.
+     *
+     * Within one class the order is still source-declaration order — we
+     * deliberately do NOT sort(), so hooks run in the order they were written
+     * (parity with Python walking __dict__, PHP get_class_methods, Ruby
      * instance_methods(false)). Cross-class order is the natural iteration of
      * the registered classes = REGISTRATION order.
+     *
+     * The chain walk stops at Function.prototype / Object.prototype, so the
+     * built-in members are never scanned. A plain object registered as
+     * middleware still works: its own keys are level 0.
      */
     private static methodNames;
     /**
@@ -63,6 +115,10 @@ export declare class MiddlewareRunner {
      * a synchronous hook that returns an array is harmless (the array resolves
      * immediately), so existing sync hooks keep working unchanged.
      *
+     * RETURN VALUE — see `interpretHookResult` for the one table every hook at
+     * every scope obeys. A returned Response object is the PRIMARY
+     * short-circuit; `false` is a deny.
+     *
      * Returns [req, res, shouldContinue].
      */
     static runBefore(classes: any[], req: Tina4Request, res: Tina4Response): Promise<[Tina4Request, Tina4Response, boolean]>;
@@ -84,12 +140,18 @@ export declare class MiddlewareRunner {
      * ASYNC — each hook is awaited (e.g. the responseCache after-hook awaiting
      * `backend.set`). Awaiting a synchronous hook is harmless, so existing sync
      * after-hooks keep working unchanged.
+     *
+     * RETURN VALUE — the SAME table as runBefore (`interpretHookResult`): the
+     * contract is one table for every hook at every scope. There is nothing left
+     * to skip after the handler, so a short-circuit here ends the after chain.
+     * A THROW is different and unchanged: it is logged, becomes a clean 500, and
+     * the remaining after hooks still run.
      */
     static runAfter(classes: any[], req: Tina4Request, res: Tina4Response): Promise<[Tina4Request, Tina4Response]>;
 }
 /** Configuration for the CORS middleware */
 export interface CorsConfig {
-    /** Allowed origins. Default: "*" (or TINA4_CORS_ORIGINS env, comma-separated) */
+    /** Allowed origins. Default: NONE (deny) — or TINA4_CORS_ORIGINS env, comma-separated. "*" allows any. */
     origins?: string | string[];
     /** Allowed methods. Default: standard REST methods (or TINA4_CORS_METHODS env) */
     methods?: string | string[];
@@ -97,22 +159,79 @@ export interface CorsConfig {
     headers?: string | string[];
     /** Access-Control-Max-Age in seconds. Default: 86400 (or TINA4_CORS_MAX_AGE env) */
     maxAge?: number;
+    /** Send Access-Control-Allow-Credentials. Default: false (or TINA4_CORS_CREDENTIALS env). Never sent with a wildcard origin. */
+    credentials?: boolean;
+}
+/** Reset the CORS warn-once ledger. Test seam. */
+export declare function resetCorsWarnings(): void;
+/**
+ * The resolved CORS policy — ONE implementation of the rules.
+ *
+ * Both the function middleware `cors()` and the class middleware
+ * `CorsMiddleware` build one of these and apply what it returns. They used to
+ * be two independent implementations that had already drifted: `cors()` never
+ * read TINA4_CORS_CREDENTIALS at all, so the DEFAULT always-on pipeline
+ * silently ignored a documented env var (measured 2026-07-31). One feature,
+ * one code path.
+ *
+ * DENY BY DEFAULT (ADR-0018). With no origins configured, NO
+ * Access-Control-Allow-Origin is emitted and the browser's own CORS check
+ * blocks the cross-origin request. "*" still works, it just has to be asked for.
+ *
+ * CREDENTIALS AND THE WILDCARD ARE MUTUALLY EXCLUSIVE. The Fetch Standard's
+ * CORS check treats "*" as a literal (not a wildcard) once the request's
+ * credentials mode is "include", so ACAO: * with
+ * Access-Control-Allow-Credentials: true is rejected by every browser.
+ *
+ * VARY: ORIGIN whenever the ACAO value is COMPUTED from the request's Origin,
+ * i.e. whenever an allow-list is configured — on a MISS as well as a match.
+ * RFC 9110 s12.5.5: a Vary field name list tells cache recipients they "MUST
+ * NOT use this response to satisfy a later request unless the later request
+ * has the same values for the listed header fields as the original request".
+ * The miss case matters most: without it a shared cache can store the no-ACAO
+ * response for origin B and serve it to origin A. A constant "*" genuinely
+ * does not vary and gets no Vary, which would only fragment a CDN's cache.
+ *
+ * Access-Control-Allow-Methods / -Allow-Headers are static configured lists
+ * here, never derived from the request's Access-Control-Request-* headers, so
+ * those field names do NOT belong in Vary.
+ */
+export declare class CorsPolicy {
+    readonly allowedOrigins: string[];
+    readonly allowedMethods: string;
+    readonly allowedHeaders: string;
+    readonly maxAge: number;
+    readonly credentials: boolean;
+    constructor(config?: CorsConfig);
+    /** Whether an operator has actually declared a CORS policy. */
+    isConfigured(): boolean;
+    /** The origin to send in Access-Control-Allow-Origin, or undefined for none. */
+    resolveOrigin(requestOrigin: string): string | undefined;
+    /**
+     * The CORS headers for a request origin. `isPreflight` adds Max-Age, which
+     * the Fetch Standard only defines for a preflight response.
+     */
+    headersFor(requestOrigin: string, isPreflight: boolean): Record<string, string>;
 }
 /**
  * Built-in CORS middleware (function form).
- * Reads configuration from env vars if not provided:
+ *
+ * A thin adapter over CorsPolicy — see that class for the rules and the
+ * standards behind them. Reads configuration from env vars when not provided:
  *   TINA4_CORS_ORIGINS — comma-separated list of allowed origins, or "*"
  *   TINA4_CORS_METHODS — comma-separated list of allowed methods
  *   TINA4_CORS_HEADERS — comma-separated list of allowed headers
  *   TINA4_CORS_MAX_AGE — preflight cache duration in seconds
+ *   TINA4_CORS_CREDENTIALS — send Access-Control-Allow-Credentials
  *
- * Preflight (OPTIONS) returns 204 with appropriate headers.
- * Supports wildcard ("*") and specific origin matching.
+ * A real preflight is answered 204. The status is the same whether the origin
+ * was allowed or denied — the browser does the blocking.
  */
 export declare function cors(config?: CorsConfig): Middleware;
 /**
  * Class-based CORS middleware using the before/after convention.
- * Wraps the same CORS logic as the `cors()` function middleware.
+ *
+ * The same CorsPolicy as `cors()` — one implementation, one set of semantics.
  *
  * Usage:
  *   Router.use(CorsMiddleware);
@@ -121,6 +240,10 @@ export declare class CorsMiddleware {
     static beforeCors(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
     /**
      * Check if a request is an OPTIONS preflight.
+     *
+     * NOTE: returns true for ANY OPTIONS, with no Origin check, so the name
+     * overstates what it tests. The real short-circuit uses isCorsPreflight().
+     * Kept because existing tests pin this meaning.
      */
     static isPreflight(method: string): boolean;
 }

package/types/core/src/queue.d.ts

@@ -19,12 +19,23 @@ export interface QueueConfig {
      * re-enqueuing, or dead-lettering past maxRetries (at-least-once delivery).
      * Falls back to TINA4_QUEUE_VISIBILITY_TIMEOUT, else 300 (5 min). <= 0
      * disables the reclaim (a reservation then lasts until the consumer acks —
-     * the old at-most-once behaviour). File + MongoDB backends only;
-     * RabbitMQ/Kafka delegate visibility to the broker. Parity with Python's
+     * the old at-most-once behaviour). File + MongoDB backends, which are the
+     * only backends Node offers (ADR-0022). Parity with Python's
      * visibility_timeout.
      */
     visibilityTimeout?: number;
 }
+/**
+ * Where the file-backed queue stores its jobs — `TINA4_QUEUE_PATH`, else
+ * `data/queue` (relative to the working directory).
+ *
+ * Exported because it is the ONE answer to "where do the queue files live",
+ * and anything that reads the store directly (the dev-admin queue panel) must
+ * ask here rather than re-deriving it. The dev admin hardcoded
+ * `cwd/data/queue/<topic>` and so listed a DIFFERENT directory from the one
+ * `Queue.size()` counted the moment `TINA4_QUEUE_PATH` was set.
+ */
+export declare function queueBasePath(): string;
 export interface ProcessOptions {
     pollInterval?: number;
     maxJobs?: number;
@@ -46,10 +57,21 @@ export interface ConsumeOptions {
     id?: string;
 }
 export interface QueueBackendInterface {
-    push(queue: string, payload: unknown, delay?: number): string;
+    push(queue: string, payload: unknown, delay?: number, priority?: number): string;
     pop(queue: string): QueueJob | null;
     size(queue: string): number;
     clear(queue: string): void;
+    /**
+     * Release whatever connection the backend holds, and be safe to call twice.
+     *
+     * REQUIRED, not optional, and deliberately so: it mirrors PHP's
+     * Tina4\Queue\QueueBackend, where close() has always been part of the
+     * interface. Optional would reintroduce exactly the bug this closes — a
+     * caller feature-detecting `backend.close?.()` silently skips the backend
+     * that forgot to implement it, which is how tina4-ruby's lite backend went
+     * un-closed by every `respond_to?(:close)` guard in its tree.
+     */
+    close(): void;
     complete?(queue: string, id: string): void;
     fail?(queue: string, id: string, error: string, maxRetries: number, retryBackoff: number): void;
     retry?(queue: string, id: string, delaySeconds?: number): void;
@@ -71,9 +93,11 @@ export declare class Queue {
      * Unified Queue constructor.
      *
      * Accepts either:
-     *   - new Queue({ topic: "tasks", backend: "rabbitmq" })
-     *   - new Queue("rabbitmq", { path: "data/queue" })  // legacy
+     *   - new Queue({ topic: "tasks", backend: "mongodb" })
+     *   - new Queue("mongodb", { path: "data/queue" })  // legacy
      *   - new Queue()  // file backend, default topic
+     *
+     * Throws on backend "rabbitmq" or "kafka" (ADR-0022).
      */
     constructor(backendOrConfig?: string | QueueConfig, config?: QueueConfig);
     /**
@@ -120,6 +144,31 @@ export declare class Queue {
      * Remove all jobs from this queue's topic. Returns the number cleared.
      */
     clear(): number;
+    /**
+     * Release the backend's connection and free its resources.
+     *
+     * MEASURED 2026-08-04: close() was absent on the top-level Queue in ALL FOUR
+     * frameworks, and in Node it was absent on every backend class too — so an
+     * application had no way at all to hand a queue's client back. Same class of
+     * leak as ADR-0025 corollary 4 (client-lifecycle-is-bounded).
+     *
+     * Safe on EVERY backend: the file backend holds no connection and closes as a
+     * documented no-op, so a TINA4_QUEUE_BACKEND change never turns a working
+     * shutdown path into an error. Idempotent — each backend drops its handles on
+     * the first call, so a second call finds nothing to close and returns.
+     *
+     * HONEST CAVEAT specific to Node: neither backend it can reach holds a
+     * connection between calls today. The Mongo backend runs each operation in
+     * its own child process (ADR-0022), which closes its own client before it
+     * exits, and rabbitmq/kafka are refused outright at construction. So this
+     * releases nothing YET — it is here for the contract, and because the day the
+     * persistent-connection rewrite lands the client is released here with no
+     * change at any call site. Python, PHP and Ruby release a REAL client through
+     * the identically-named method.
+     *
+     * Treat the queue as spent afterwards and build a new one to keep working.
+     */
+    close(): void;
     /**
      * Get jobs that failed at least once but are still being retried
      * (0 < attempts < maxRetries). These live in the pending queue under the

package/types/core/src/queueBackends/kafkaBackend.d.ts

@@ -44,7 +44,7 @@ export interface KafkaClientConfig extends KafkaSecurityConfig {
  */
 export declare function kafkaSecurityConfig(env?: NodeJS.ProcessEnv): KafkaSecurityConfig;
 export interface QueueBackend {
-    push(queue: string, payload: unknown, delay?: number): string;
+    push(queue: string, payload: unknown, delay?: number, priority?: number): string;
     pop(queue: string): QueueJob | null;
     size(queue: string): number;
     clear(queue: string): void;

package/types/core/src/queueBackends/liteBackend.d.ts

@@ -20,6 +20,15 @@ export declare class LiteBackend {
     private nowIso;
     private futureIso;
     private nextPrefix;
+    /**
+     * No-op: the file backend holds no connection to release.
+     *
+     * It exists so `Queue.close()` can call ONE method on every backend instead
+     * of testing for it, and so switching TINA4_QUEUE_BACKEND to "file" never
+     * turns a working close() into "backend.close is not a function". Idempotent
+     * by construction — there is nothing to drop.
+     */
+    close(): void;
     push(queue: string, payload: unknown, delay?: number, priority?: number): string;
     /**
      * Return [filename, jobData] for every pending, non-delayed job, ordered by

package/types/core/src/queueBackends/mongoBackend.d.ts

@@ -18,10 +18,12 @@ export interface MongoConfig {
     maxRetries?: number;
 }
 export interface QueueBackend {
-    push(queue: string, payload: unknown, delay?: number): string;
+    push(queue: string, payload: unknown, delay?: number, priority?: number): string;
     pop(queue: string): QueueJob | null;
     size(queue: string): number;
     clear(queue: string): void;
+    /** Release whatever connection the backend holds. Must be idempotent. */
+    close(): void;
 }
 /**
  * MongoDB queue backend using the `mongodb` npm package.
@@ -69,7 +71,8 @@ export declare class MongoBackend implements QueueBackend {
      * Execute a MongoDB operation synchronously via a child process.
      */
     private execSync;
-    push(queue: string, payload: unknown, delay?: number): string;
+    popById(queue: string, id: string): QueueJob | null;
+    push(queue: string, payload: unknown, delay?: number, priority?: number): string;
     pop(queue: string): QueueJob | null;
     size(queue: string): number;
     clear(queue: string): void;
@@ -94,4 +97,23 @@ export declare class MongoBackend implements QueueBackend {
     retryFailed(queue: string, maxRetries?: number): number;
     /** Remove jobs by status (default: every doc for the topic). Returns count removed. */
     purge(queue: string, status?: string): number;
+    /**
+     * Release the MongoDB connection. Idempotent — a second call is a no-op.
+     *
+     * HONEST CAVEAT, and it is the whole reason ADR-0022 exists: THIS backend
+     * holds no connection between calls to release. Every operation runs in its
+     * own child process (see execSync/buildScript), and that child's `finally`
+     * already does `await client.close()` before it exits — so the pool it opened
+     * is gone by the time the method returns. Unlike tina4-python, tina4-php and
+     * tina4-ruby, whose Mongo/broker backends hold a long-lived client that this
+     * method genuinely hands back, Node has nothing to give back.
+     *
+     * It is implemented anyway, and required by the QueueBackend interface,
+     * because the CONTRACT is what matters: `Queue.close()` must be callable on
+     * every backend in every framework, and the day the persistent-connection
+     * rewrite lands (ADR-0022's tracked fix) the client goes here with no change
+     * at any call site. A method that is a no-op today and correct forever beats
+     * a missing method the caller has to feature-detect.
+     */
+    close(): void;
 }

package/types/core/src/queueBackends/rabbitmqBackend.d.ts

@@ -16,12 +16,12 @@ export interface RabbitMQConfig {
  * Parse an AMQP URL (amqp://[user:pass@]host[:port][/vhost]) into a partial
  * RabbitMQConfig. Mirrors the Python/PHP/Ruby `parse_amqp_url` semantics:
  * strips a leading amqp:// or amqps:// scheme, splits optional credentials,
- * and prepends a leading "/" to the vhost when missing. Only fields present
- * in the URL are populated.
+ * and reads the path segment as the URL-decoded vhost name. Only fields
+ * present in the URL are populated.
  */
 export declare function parseAmqpUrl(url: string): RabbitMQConfig;
 export interface QueueBackend {
-    push(queue: string, payload: unknown, delay?: number): string;
+    push(queue: string, payload: unknown, delay?: number, priority?: number): string;
     pop(queue: string): QueueJob | null;
     size(queue: string): number;
     clear(queue: string): void;

package/types/core/src/router.d.ts

@@ -317,10 +317,21 @@ export declare class RouteGroup {
  */
 export declare function resolveStringMiddleware(spec: string): Promise<Middleware>;
 /**
- * Run per-route middleware chain, then call the handler.
+ * Run the per-route middleware chain. Returns false when it short-circuited
+ * and the handler must be skipped.
  *
- * Accepts middleware functions and/or string specs (e.g. "ResponseCache:300").
- * Each spec is resolved to a middleware function just before it runs.
+ * Accepts middleware functions, middleware CLASSES, and string specs
+ * (e.g. "ResponseCache:300"). A function or string spec is resolved and
+ * invoked as `mw(req, res, next)` exactly as before.
+ *
+ * A CLASS runs its beforeX hooks through the SAME `MiddlewareRunner.runBefore`
+ * and the SAME return-value table as global middleware — no parallel runner.
+ * Its afterX hooks run with the global after pass once the handler is done
+ * (server.ts / testClient.ts append the route's classes to that list), because
+ * "after" means after the handler, not after this function. Every spec used to
+ * be invoked as `mw(req, res, next)`, which for a class throws "Class
+ * constructor cannot be invoked without 'new'", so a class attached per-route
+ * was inert. Python and PHP both ran per-route class hooks already.
  */
 export declare function runRouteMiddlewares(middlewares: MiddlewareSpec[], req: Tina4Request, res: Tina4Response): Promise<boolean>;
 /**

package/types/core/src/server.d.ts

@@ -1,6 +1,21 @@
 import { IncomingMessage, ServerResponse } from "node:http";
 import type { Tina4Config } from "./types.js";
 import { Router } from "./router.js";
+/** How long a graceful shutdown waits for in-flight requests, in seconds. */
+export declare const DEFAULT_SHUTDOWN_TIMEOUT_SECONDS = 30;
+/**
+ * Resolve the shutdown budget from `TINA4_SHUTDOWN_TIMEOUT` (seconds).
+ *
+ * 30s matches Kubernetes' default `terminationGracePeriodSeconds` and
+ * Gunicorn's `graceful_timeout`, so the drain finishes just BEFORE the
+ * orchestrator's SIGKILL rather than being truncated by it. Same env var and
+ * same default as tina4-ruby's `Tina4::Shutdown`.
+ *
+ * A non-numeric or negative value falls back to the default rather than
+ * silently disabling the drain - a typo must not turn shutdown into a
+ * zero-second force-kill.
+ */
+export declare function shutdownTimeoutSeconds(): number;
 /**
  * Build the startup banner's optional surface lines (issue #99).
  *
@@ -105,10 +120,6 @@ export declare function resetTemplateCache(): void;
  * The whole feature can be turned off with `TINA4_TEMPLATE_ROUTING=off`.
  */
 export declare function resolveTemplate(pathname: string, templatesDir: string): string | null;
-/**
- * Start the Tina4 HTTP server.
- * Thin wrapper around startServer() for cross-framework parity with PHP and Ruby.
- */
 export declare function start(config?: Tina4Config): Promise<{
     close: () => void;
     router: Router;

package/types/core/src/session.d.ts

@@ -1,5 +1,5 @@
 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;
@@ -21,6 +21,21 @@ interface SessionData {
     _accessed: number;
     [key: string]: unknown;
 }
+/**
+ * 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 declare function isValidSessionId(sessionId: unknown): boolean;
+/**
+ * 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 declare const VALID_SESSION_BACKENDS: readonly ["file", "filesystem", "redis", "valkey", "mongodb", "mongo", "memcached", "memcache", "database", "db"];
+/** Canonical name of each backend, for the error message (aliases omitted). */
+export declare const CANONICAL_SESSION_BACKENDS: readonly ["file", "redis", "valkey", "mongodb", "memcached", "database"];
 /**
  * Base interface for session storage backends.
  * Implementations must provide read, write, and destroy.
@@ -36,6 +51,29 @@ export declare class FileSessionHandler implements SessionHandler {
     private storagePath;
     constructor(storagePath?: string);
     private ensureDir;
+    /**
+     * 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;
     read(sessionId: string): SessionData | null;
     write(sessionId: string, data: SessionData, ttl?: number): void;
@@ -97,13 +135,28 @@ export declare class Session {
      * frameworks. Strict mode is the escape hatch (same as events/seeding).
      */
     private strict;
+    /**
+     * 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;
     constructor(backend?: string, config?: SessionConfig);
     /**
      * Use a custom session handler (for advanced use cases).
      */
     setHandler(handler: SessionHandler): void;
     private logBackendError;
-    /** 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;
     /** Write through the backend; on FAILURE log + return false (or re-throw under strict). */
     private safeWrite;
@@ -111,6 +164,26 @@ export declare class Session {
     private safeDestroy;
     /**
      * 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
      */
@@ -232,6 +305,18 @@ export declare function isSecureScheme(forwardedProto?: string, socketEncrypted?
  * `session.session_cookie_name()`.
  */
 export declare function sessionCookieName(): string;
+/**
+ * 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 declare function sessionStrictMode(): boolean;
 /**
  * Build the `Set-Cookie` header value for a Tina4 session. Centralised so
  * the auto-cookie path in server.ts and `Session.cookieHeader()` agree on