tina4-nodejs 3.13.92 → 3.13.95

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

@@ -0,0 +1,146 @@
+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).
+ *
+ * Only advertise a surface that is actually REACHABLE. In production, or with
+ * TINA4_DEBUG off, /swagger and /__dev return 404 -- printing them anyway both
+ * misleads an operator into believing a dev surface is exposed and sends a
+ * developer to a dead link.
+ *
+ * Kept as a pure function of (port, two booleans) so the contract is unit
+ * testable without booting a server and grepping stdout. Parity: Python
+ * banner_surface_lines, PHP App::bannerSurfaceLines, Ruby
+ * Tina4.banner_surface_lines.
+ *
+ * @returns [swaggerLine, dashboardLine] -- each empty, or a newline plus the
+ *          banner row, ready to interpolate.
+ */
+export declare function bannerSurfaceLines(port: number, opts: {
+    swaggerEnabled: boolean;
+    devAdminEnabled: boolean;
+}): [string, string];
+/**
+ * Apply pending DB migrations on startup — NON-BREAKING.
+ *
+ * When a `migrations/` folder exists (with at least one `.sql` file, excluding
+ * `.down.sql`) and `TINA4_AUTO_MIGRATE` is not disabled (default "true";
+ * false/0/no/off disable), pending migrations are applied during boot so the
+ * schema is current with no manual `tina4 migrate` step. A failure here is
+ * logged LOUD via `Log.error` and the service STILL starts — a bad migration
+ * must never take the backend down. (The explicit `tina4 migrate` CLI stays
+ * fail-fast so CI still gets a non-zero exit. Only this startup hook swallows.)
+ *
+ * Disable with `TINA4_AUTO_MIGRATE=false` — e.g. multi-instance production that
+ * migrates as a separate deploy step (concurrent first-apply can race).
+ *
+ * @param migrationDir - migrations directory (default "migrations", relative to base)
+ * @param base - project root used to resolve the migrations directory
+ */
+export declare function autoMigrateOnStartup(migrationDir?: string, base?: string): Promise<void>;
+/**
+ * Refuse to boot if pre-3.12 un-prefixed env vars are still set.
+ *
+ * Tina4 v3.12 hard-renamed every framework-specific env var to use the
+ * `TINA4_` prefix. Booting silently with a legacy `DATABASE_URL` or
+ * `SECRET` would let auth, DB, or mail fall back to insecure defaults
+ * while the user thought their config was being read. Better to die
+ * loudly with a list of names to fix.
+ *
+ * Bypass with `TINA4_ALLOW_LEGACY_ENV=true` in CI / migration scripts
+ * that genuinely need both names set during a transition window.
+ */
+export declare function _checkLegacyEnvVars(): void;
+/**
+ * Resolve port and host with priority: explicit config > ENV var > default.
+ * Exported for testability.
+ *
+ * Host resolution prefers `TINA4_HOST` (the framework-prefixed name —
+ * matches Python parity) and falls back to the unprefixed `HOST` env var
+ * for backwards compatibility.
+ */
+export declare function resolvePortAndHost(config?: {
+    port?: number;
+    host?: string;
+}): {
+    port: number;
+    host: string;
+};
+/**
+ * Whether the boot banner should be suppressed. Set TINA4_SUPPRESS=true to
+ * silence the ASCII-art banner and route table on startup — useful in CI,
+ * test runners, and embedded contexts where stdout is consumed by another
+ * process.
+ */
+export declare function isBannerSuppressed(): boolean;
+/**
+ * Honour TINA4_TEMPLATE_ROUTING=off|false|0|no|disabled as an explicit kill
+ * switch. Default: enabled. Drop a file in src/templates/pages/ and it serves
+ * at the matching URL — the zero-config Tina4 convention. Operators who want
+ * explicit-only routing can set TINA4_TEMPLATE_ROUTING=off and every URL
+ * must be registered via get() / post() (or be a static file).
+ */
+export declare function templateAutoRoutingEnabled(): boolean;
+/**
+ * Return the canonical HTTP reason phrase for `status`. Falls back to a
+ * sensible label when an exotic status is used. Never returns an empty string.
+ */
+export declare function httpReason(status: number): string;
+/**
+ * Reset the production template cache. Tests use this between scenarios so
+ * a fresh scan picks up fixture files in a tmp project.
+ */
+export declare function resetTemplateCache(): void;
+/**
+ * Resolve a URL path to a template file in src/templates/pages/.
+ *
+ * Only files inside `src/templates/pages/` auto-route from a URL. Anything
+ * in `src/templates/` outside `pages/` (partials, layouts, base.twig,
+ * errors, components) is never served standalone.
+ *
+ * Dev mode: checks filesystem every time for live changes.
+ * Production: uses a cached lookup built once at startup.
+ *
+ * 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;
+    port: number;
+}>;
+/**
+ * Stop the running Tina4 server gracefully.
+ */
+export declare function stop(): void;
+/**
+ * Dispatch a raw Node.js request through the Tina4 router and write the response.
+ * Requires startServer() to have been called first.
+ * Useful for testing and embedding.
+ */
+export declare function handle(rawReq: IncomingMessage, rawRes: ServerResponse): Promise<void>;
+export declare function startServer(config?: Tina4Config): Promise<{
+    close: () => void;
+    router: Router;
+    port: number;
+}>;

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

@@ -0,0 +1,115 @@
+export interface ServiceOptions {
+    timing?: string;
+    daemon?: boolean;
+    interval?: number;
+    maxRetries?: number;
+}
+export interface ServiceContext {
+    running: boolean;
+    lastRun: Date | null;
+    name: string;
+}
+export type ServiceHandler = (context: ServiceContext) => Promise<void> | void;
+export interface ServiceInfo {
+    name: string;
+    options: ServiceOptions;
+    running: boolean;
+    lastRun: Date | null;
+    retries: number;
+}
+/**
+ * Parse a single cron field and check if the given value matches.
+ * Supports: * (every), N/n (step), N,N,N (list), N-N (range), plain number.
+ */
+export declare function matchCronField(field: string, value: number): boolean;
+/**
+ * Check whether a Date matches a 5-field cron expression.
+ * Fields: minute hour dayOfMonth month dayOfWeek
+ */
+export declare function matchesCron(expression: string, date: Date): boolean;
+export declare abstract class Tina4Service {
+    private _running;
+    /** Main work loop — subclasses MUST override. */
+    abstract run(): Promise<void> | void;
+    /**
+     * Signal this service to stop. The next `shouldStop()` check returns true.
+     * Override for custom shutdown behaviour but always call `super.stop()`.
+     */
+    stop(): void;
+    /**
+     * Returns true once `stop()` has been called. Use inside `run()` loops
+     * as the exit condition:
+     *
+     *     async run() {
+     *       while (!this.shouldStop()) { ... }
+     *     }
+     */
+    shouldStop(): boolean;
+    /**
+     * Return a callable that ServiceRunner can register. Used by
+     * ServiceRunner.registerService under the hood.
+     */
+    asHandler(): ServiceHandler;
+}
+export declare class ServiceRunner {
+    /**
+     * Register a service with a handler and options.
+     */
+    static register(name: string, handler: ServiceHandler, options?: ServiceOptions): void;
+    /**
+     * Register a class-based service (subclass of {@link Tina4Service}) by name.
+     *
+     * Wraps the service's `run()` method as the runner's handler. Defaults
+     * to `daemon: true` because Tina4Service subclasses manage their own
+     * loop inside `run()`. Override via `options`.
+     *
+     *     class EmailWorker extends Tina4Service { async run() { ... } }
+     *     ServiceRunner.registerService("emails", new EmailWorker());
+     *     await ServiceRunner.start();
+     *
+     * Cross-framework parity with PHP `ServiceRunner::registerService` and
+     * Ruby `Tina4::ServiceRunner.register_service`.
+     */
+    static registerService(name: string, service: Tina4Service, options?: ServiceOptions): void;
+    /**
+     * Discover services from a directory. Each file should export
+     * { name, handler, timing?, interval?, daemon?, maxRetries? }.
+     */
+    static discover(serviceDir?: string): Promise<ServiceInfo[]>;
+    /**
+     * Start all registered services, or a specific one by name.
+     */
+    static start(name?: string): void;
+    /**
+     * Stop all running services, or a specific one by name.
+     */
+    static stop(name?: string): void;
+    /**
+     * List all registered services with their current state.
+     */
+    static list(): ServiceInfo[];
+    /**
+     * Check if a specific service is running.
+     */
+    static isRunning(name: string): boolean;
+    /**
+     * Remove a service from the registry (stops it first if running).
+     */
+    static remove(name: string): boolean;
+    /**
+     * Clear all registered services (stops them all first).
+     */
+    static clear(): void;
+    /**
+     * Check if a 5-field cron pattern matches the given (or current) date/time.
+     */
+    static matchCron(pattern: string, now?: Date): boolean;
+    /**
+     * Watch service files for changes and hot-reload in dev mode.
+     */
+    static watch(serviceDir?: string): void;
+    /**
+     * Stop watching service files.
+     */
+    static unwatch(): void;
+}

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

@@ -0,0 +1,341 @@
+export interface SessionConfig {
+    /** Session backend type: "file", "redis", "valkey", "mongo", "memcached", "database" (or "db") */
+    backend?: string;
+    /** File storage path (default: "data/sessions") */
+    path?: string;
+    /** Time-to-live in seconds (default: 3600) */
+    ttl?: number;
+    /** Redis host (default: "127.0.0.1") */
+    redisHost?: string;
+    /** Redis port (default: 6379) */
+    redisPort?: number;
+    /** Redis password (optional) */
+    redisPassword?: string;
+    /** Redis key prefix (default: "tina4:session:") */
+    redisPrefix?: string;
+    /** Redis database index (default: 0) */
+    redisDb?: number;
+}
+interface SessionData {
+    _created: number;
+    _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.
+ */
+export interface SessionHandler {
+    read(sessionId: string): SessionData | null;
+    write(sessionId: string, data: SessionData, ttl?: number): void;
+    destroy(sessionId: string): void;
+    /** Garbage-collect expired sessions. Optional — Redis/Valkey/Mongo handle TTL natively. */
+    gc?(maxLifetime: number): void;
+}
+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;
+    destroy(sessionId: string): void;
+    gc(maxLifetime?: number): void;
+}
+/**
+ * Redis session handler using raw TCP (RESP protocol).
+ *
+ * Uses synchronous socket communication — no external Redis client required.
+ * Stores session data as JSON strings with Redis TTL for automatic expiry.
+ *
+ * Configure via environment variables:
+ *   TINA4_SESSION_REDIS_HOST    (default: "127.0.0.1")
+ *   TINA4_SESSION_REDIS_PORT    (default: 6379)
+ *   TINA4_SESSION_REDIS_PASSWORD (optional)
+ *   TINA4_SESSION_REDIS_PREFIX  (default: "tina4:session:")
+ *   TINA4_SESSION_REDIS_DB      (default: 0)
+ *
+ * Or pass via SessionConfig.
+ */
+export declare class RedisSessionHandler implements SessionHandler {
+    private host;
+    private port;
+    private password;
+    private prefix;
+    private db;
+    constructor(config?: SessionConfig);
+    /**
+     * 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;
+    private key;
+    read(sessionId: string): SessionData | null;
+    write(sessionId: string, data: SessionData, ttl?: number): void;
+    destroy(sessionId: string): void;
+}
+export declare class Session {
+    private handler;
+    private ttl;
+    private sessionId;
+    private data;
+    /**
+     * Dirty flag — set when data changes, cleared only on a successful write.
+     * Retained on a failed write so a later save() retries once the backend
+     * recovers (mirrors the Python `_dirty` semantics).
+     */
+    private dirty;
+    /**
+     * Backend-failure policy: log-loud + degrade (default), or re-raise when
+     * TINA4_SESSION_STRICT is truthy. A read failure logs + yields an empty
+     * session, a write failure logs + returns false (best-effort, dirty
+     * retained), destroy/gc failures log + swallow. Parity across all four
+     * frameworks. Strict mode is the escape hatch (same as events/seeding).
+     */
+    private strict;
+    /**
+     * 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).
+     *
+     * 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;
+    /** Destroy through the backend; on FAILURE log + swallow (or re-throw under strict). */
+    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
+     */
+    start(sessionId?: string): string;
+    /**
+     * Get a value from the session.
+     */
+    get(key: string, defaultValue?: unknown): unknown;
+    /**
+     * Set a value in the session.
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Delete a key from the session.
+     */
+    delete(key: string): void;
+    /**
+     * Destroy the entire session.
+     *
+     * A backend failure is logged (never silent) but does not throw under the
+     * default policy — local state is cleared regardless so the request proceeds.
+     */
+    destroy(): void;
+    /**
+     * Get all session data (excluding internal keys).
+     */
+    all(): Record<string, unknown>;
+    /**
+     * Clear all session data (but keep the session alive).
+     */
+    clear(): void;
+    /**
+     * Check if a key exists in the session.
+     */
+    has(key: string): boolean;
+    /**
+     * Regenerate the session ID (keeps data, new ID).
+     *
+     * Call this right after a successful login or any privilege change to defeat
+     * session fixation — the pre-auth ID is destroyed and the data is carried
+     * onto a fresh, unguessable ID. A backend destroy/write failure is logged
+     * (never silent) but does not throw under the default policy.
+     */
+    regenerate(): string;
+    /**
+     * Dual-mode flash: set with value, get+remove without.
+     *
+     *   session.flash("message", "Saved!")  // set
+     *   session.flash("message")            // get + auto-remove → "Saved!"
+     */
+    flash(key: string, value?: unknown): unknown;
+    /**
+     * Get flash data by key (alias for flash(key) without value).
+     */
+    getFlash(key: string, defaultValue?: unknown): unknown;
+    /**
+     * Get the current session ID.
+     */
+    getSessionId(): string | null;
+    /**
+     * Return a Set-Cookie header value for this session.
+     *
+     * Honours these env vars (cross-framework parity):
+     *   TINA4_SESSION_NAME      — cookie name (default: "tina4_session")
+     *   TINA4_SESSION_SAMESITE  — SameSite attribute (default: "Lax")
+     *   TINA4_SESSION_HTTPONLY  — emit HttpOnly (default: true)
+     *   TINA4_SESSION_SECURE    — emit Secure (default: false)
+     */
+    cookieHeader(cookieName?: string): string;
+    /**
+     * Run garbage collection on the session backend.
+     * Removes expired file/database sessions. Redis/Valkey/Mongo handle TTL natively.
+     *
+     * A backend failure is logged (never silent) but does not throw under the
+     * default policy (re-raises under TINA4_SESSION_STRICT=true).
+     */
+    gc(): void;
+    /**
+     * Persist session data to the backend.
+     *
+     * Returns true on a successful persist, false if the backend was unreachable
+     * (logged). The dirty flag is cleared only on success so a later save()
+     * retries once the backend recovers. A nothing-to-persist call returns true.
+     */
+    save(): boolean;
+}
+/**
+ * Is the client's scheme HTTPS? Proxy-aware.
+ *
+ * TLS is normally terminated at a proxy (nginx, HAProxy, ALB, Cloudflare, most
+ * container deploys) which then forwards plain HTTP to Node — so the native
+ * socket is NOT encrypted on exactly the deployments that ARE https, and it
+ * cannot be the only signal. `x-forwarded-proto` carries the scheme the client
+ * actually used; a chain of proxies appends each hop ("https, http") and the
+ * FIRST is the client-facing one, which is the scheme the browser used.
+ *
+ * Parity with PHP `Request::isSecureScheme` (tina4-php#175). Spoofable when the
+ * app is directly reachable, but the failure mode is self-limiting: a spoofed
+ * `https` only makes the cookie MORE restrictive, and `request.ts` already
+ * trusts the same header for URL construction — honouring it here is consistent.
+ *
+ * @param forwardedProto Raw `x-forwarded-proto` value (or a resolved scheme like
+ *                       "https"/"http"); "" / undefined means "absent".
+ * @param socketEncrypted True when Node terminated TLS itself (direct https, no
+ *                        proxy) — the native fallback when no forwarded header.
+ */
+export declare function isSecureScheme(forwardedProto?: string, socketEncrypted?: boolean): boolean;
+/**
+ * Resolve the session cookie name — the single source of truth shared by the
+ * WRITE side (`buildSessionCookie` / `Session.cookieHeader`) and the READ side
+ * (the auto-session cookie parse in `server.ts`), so a cookie written under a
+ * renamed name is read back on the next request.
+ *
+ *   TINA4_SESSION_NAME   Cookie name (default: "tina4_session")
+ *
+ * Keeping this in one place means the default can never drift between the two
+ * sides: an operator who sets `TINA4_SESSION_NAME` renames the cookie on both
+ * the emit and the parse paths at once. Parity with Python
+ * `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
+ * which env vars are honoured and what the defaults are.
+ *
+ * Env vars (Python parity):
+ *   TINA4_SESSION_NAME      — cookie name (default: "tina4_session")
+ *   TINA4_SESSION_SAMESITE  — SameSite attribute (default: "Lax")
+ *   TINA4_SESSION_HTTPONLY  — emit HttpOnly (default: true)
+ *   TINA4_SESSION_SECURE    — emit Secure (default: false; SameSite=None forces it on)
+ *
+ * `Secure` is emitted when ANY of: TINA4_SESSION_SECURE is truthy; SameSite is
+ * `None` (browsers reject a None cookie without Secure); OR the request scheme
+ * is https, detected proxy-aware from `forwardedProto` / `socketEncrypted`. The
+ * auto-cookie path in server.ts threads the request's scheme in so an HTTPS
+ * deploy behind a TLS-terminating proxy ships Secure without the operator
+ * having to know about TINA4_SESSION_SECURE (nodejs#34). Plain HTTP with no
+ * proxy header and no native TLS stays NOT Secure — an eager Secure would make
+ * http://localhost dev cookies undeliverable.
+ */
+export declare function buildSessionCookie(sessionId: string | null, ttl: number, cookieName?: string, forwardedProto?: string, socketEncrypted?: boolean): string;
+export {};

package/types/core/src/sessionHandlers/childError.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Tina4 session handlers — turn a failed `execFileSync` child into a readable cause.
+ *
+ * The session-handler interface is synchronous but every backend client is async,
+ * so each command runs in a short-lived `node -e` child. When that child fails,
+ * `execFileSync` throws an error whose `.message` begins "Command failed:" and
+ * then embeds THE ENTIRE GENERATED SCRIPT — kilobytes of source with the real
+ * reason nowhere in it. Every handler used to throw exactly that, so an
+ * operator debugging a Redis outage got a wall of JavaScript instead of
+ * "connect ECONNREFUSED 127.0.0.1:6379".
+ *
+ * The children already write the real reason to stderr; `execFileSync` captures
+ * it on `err.stderr`. This module is the ONE place that prefers it, so the three
+ * call sites (respClient, mongoClient, redisHandler's npm path) cannot drift.
+ */
+/**
+ * Extract the most useful one-line cause from a thrown `execFileSync` error.
+ *
+ * Order of preference:
+ *  1. the child's own stderr — what it actually reported;
+ *  2. a timeout, named as such (a SIGTERM kill leaves stderr empty, so without
+ *     this the caller would see the useless generic message);
+ *  3. a non-zero exit code with no output at all;
+ *  4. the error's own message, first line only and length-capped, so the
+ *     generated script can never be dumped into a log.
+ */
+export declare function childFailureReason(err: unknown): string;
+/**
+ * Build the Error a session handler throws when its child command failed.
+ *
+ * `label` names the backend ("Redis", "Valkey", "MongoDB") so the message says
+ * which one broke; the wording is shared so all three read alike.
+ */
+export declare function childFailureError(label: string, err: unknown): Error;