tina4-nodejs 3.13.138 → 3.13.140

package/packages/orm/src/adapters/sqlCrud.ts

@@ -0,0 +1,178 @@
+/*
+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/.
+*/
+
+/**
+ * One CRUD write composer for every SQL engine, instead of one per adapter.
+ *
+ * `sqlDialect.ts` already collapsed the SQL *fragment* builders (columns, the
+ * SET list, the WHERE list). What it did NOT collapse was the METHOD BODIES:
+ * every SQL adapter's `insert`/`update`/`delete` re-implemented the SAME
+ * envelope around those fragments — the string-filter branch vs the hash-filter
+ * branch, the `[...Object.values(data), ...(params ?? [])]` value assembly, the
+ * batch fan-out — differing only in the two things a `Dialect` already captures
+ * (identifier quoting, parameter marker) plus three per-engine knobs:
+ *
+ *   INSERT SUFFIX     "" | " RETURNING *" | "; SELECT SCOPE_IDENTITY() AS id"
+ *   MARKER START      1 (PostgreSQL $N) | 0 (MSSQL @pN) | ignored (`?` engines)
+ *   FRAGMENT REWRITE  a raw "id = ?" WHERE string: identity on a `?` engine,
+ *                     convertPlaceholders/bindable on a positional one
+ *
+ * This is the Node port of the Python master's `SqlCrudMixin`
+ * (tina4_python/database/adapter.py): build the SQL and the ordered parameter
+ * list engine-neutrally from a dialect + those knobs, and hand the pair back to
+ * the adapter to EXECUTE.
+ *
+ * Like `sqlDialect.ts`, these functions build STRINGS and parameter arrays and
+ * NOTHING else. Execution and result extraction stay in the adapters on purpose:
+ * `this.db.prepare().run()` vs `await this.client!.query()` vs tedious vs a
+ * Firebird transaction handle, and RETURNING / SCOPE_IDENTITY() / lastId /
+ * affectedRows normalisation, are genuinely per-driver — folding them in here
+ * would trade a real duplication for a fake abstraction.
+ *
+ * MongoDB has no entry: it does not build SQL at all.
+ */
+
+import { type Dialect, buildInsert, buildSetClause, buildWhereClause } from "./sqlDialect.js";
+
+/** A composed statement: the SQL text and its ordered parameter list. */
+export interface CrudSql {
+  sql: string;
+  values: unknown[];
+}
+
+/**
+ * A composed batch INSERT: one SQL statement plus one parameter row per input
+ * record, ready for the adapter's own `executeMany`.
+ */
+export interface CrudBatchSql {
+  sql: string;
+  paramsList: unknown[][];
+}
+
+/** The only per-engine differences in a composed write's SQL + parameter list. */
+export interface WriteOptions {
+  /**
+   * 1-based position of the FIRST parameter marker. PostgreSQL numbers `$N`
+   * from 1; MSSQL names `@pN` from 0 and BINDS by that name, so the start must
+   * match its binding loop. Engines whose marker is `?` ignore it. Default 1.
+   */
+  startAt?: number;
+  /**
+   * Rewrite a raw string WHERE fragment's `?` markers for this engine, given the
+   * 1-based position of the fragment's first marker. `?` engines leave it
+   * untouched (the default); a positional engine passes its `convertPlaceholders`
+   * / `bindable`. Only ever applied to the developer-supplied string filter,
+   * never to the framework-built hash WHERE.
+   */
+  convertFragment?: (fragment: string, startAt: number) => string;
+}
+
+const identityFragment = (fragment: string): string => fragment;
+
+/**
+ * A single-row INSERT: `INSERT INTO t (a, b) VALUES (?, ?)<suffix>` and the row's
+ * values in column order. `suffix` carries the genuinely engine-specific tail
+ * (PostgreSQL's ` RETURNING *`, MSSQL's SCOPE_IDENTITY() probe).
+ */
+export function buildInsertRow(
+  dialect: Dialect,
+  table: string,
+  data: Record<string, unknown>,
+  suffix = "",
+  options: WriteOptions = {},
+): CrudSql {
+  const keys = Object.keys(data);
+  const sql = buildInsert(dialect, table, keys, suffix, options.startAt ?? 1);
+  return { sql, values: Object.values(data) };
+}
+
+/**
+ * A batch INSERT from a list of rows — one parameterised statement the adapter
+ * runs once per row via its own `executeMany`. Returns `null` for an empty list
+ * (the adapters treat that as a no-op affecting zero rows). The keys come from
+ * the first row, exactly as every adapter already assumed.
+ */
+export function buildInsertRows(
+  dialect: Dialect,
+  table: string,
+  rows: Record<string, unknown>[],
+): CrudBatchSql | null {
+  if (rows.length === 0) return null;
+  const keys = Object.keys(rows[0]);
+  const sql = buildInsert(dialect, table, keys);
+  const paramsList = rows.map((row) => keys.map((k) => row[k]));
+  return { sql, paramsList };
+}
+
+/**
+ * An UPDATE from a data object and either a hash filter (`{id: 5}` →
+ * `WHERE "id" = ?`) or a raw string filter (`"id = ?"` + `params`). The SET
+ * values always lead the parameter list; the WHERE values follow.
+ */
+export function buildUpdate(
+  dialect: Dialect,
+  table: string,
+  data: Record<string, unknown>,
+  filter: Record<string, unknown> | string,
+  params?: unknown[],
+  options: WriteOptions = {},
+): CrudSql {
+  const startAt = options.startAt ?? 1;
+  const convertFragment = options.convertFragment ?? identityFragment;
+  const dataKeys = Object.keys(data);
+  const setClauses = buildSetClause(dialect, dataKeys, startAt);
+  const whereStart = startAt + dataKeys.length;
+
+  if (typeof filter === "string") {
+    const where = filter ? ` WHERE ${convertFragment(filter, whereStart)}` : "";
+    return {
+      sql: `UPDATE ${dialect.quote(table)} SET ${setClauses}${where}`,
+      values: [...Object.values(data), ...(params ?? [])],
+    };
+  }
+
+  const whereClauses = buildWhereClause(dialect, Object.keys(filter), whereStart);
+  return {
+    sql: `UPDATE ${dialect.quote(table)} SET ${setClauses} WHERE ${whereClauses}`,
+    values: [...Object.values(data), ...Object.values(filter)],
+  };
+}
+
+/**
+ * A DELETE from either a hash filter (`{id: 5}` → `WHERE "id" = ?`) or a raw
+ * string filter (`"age < ?"` + `params`). An empty string filter deletes the
+ * whole table (the explicit `truncate()` spelling routes through here).
+ *
+ * The array-of-dicts filter form is NOT handled here: only SQLite and ODBC
+ * accept it, and both loop it into per-row `delete` calls that land back in one
+ * of the two branches above — that fan-out stays in those two adapters.
+ */
+export function buildDelete(
+  dialect: Dialect,
+  table: string,
+  filter: Record<string, unknown> | string,
+  params?: unknown[],
+  options: WriteOptions = {},
+): CrudSql {
+  const startAt = options.startAt ?? 1;
+  const convertFragment = options.convertFragment ?? identityFragment;
+
+  if (typeof filter === "string") {
+    const where = filter ? ` WHERE ${convertFragment(filter, startAt)}` : "";
+    return {
+      sql: `DELETE FROM ${dialect.quote(table)}${where}`,
+      values: params ?? [],
+    };
+  }
+
+  const whereClauses = buildWhereClause(dialect, Object.keys(filter), startAt);
+  return {
+    sql: `DELETE FROM ${dialect.quote(table)} WHERE ${whereClauses}`,
+    values: Object.values(filter),
+  };
+}

package/packages/orm/src/adapters/sqlite.ts

@@ -7,9 +7,10 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */
 
 import { DatabaseSync } from "node:sqlite";
-import { ANSI_DIALECT, buildInsert, buildSetClause, buildWhereClause } from "./sqlDialect.js";
+import { ANSI_DIALECT } from "./sqlDialect.js";
+import { buildDelete, buildInsertRow, buildInsertRows, buildUpdate } from "./sqlCrud.js";
 import { mkdirSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
 import { SQLTranslator } from "../sqlTranslator.js";
 
@@ -76,31 +77,45 @@ function sqliteVersionAtLeast(major: number, minor: number, patch: number): bool
  *
  * Matches the tina4-python + tina4-php convention:
  *   ":memory:"         → passthrough
- *   "data/app.db"      → {cwd}/data/app.db  (auto-mkdir under cwd)
+ *   "data/app.db"      → {cwd}/data/app.db  (parent auto-created, mode 0775)
  *   "/abs/app.db"      → /abs/app.db        (NO auto-mkdir; user's responsibility)
- *   "C:/Users/app.db"  → C:/Users/app.db    (NO auto-mkdir)
+ *   "C:/Users/app.db"  → C:/Users/app.db    (recognised as absolute on EVERY OS)
+ *   "../../etc/foo.db" → REFUSED loudly (its parent escapes cwd)
  *
- * Never mkdir a directory that isn't a descendant of cwd — that was the
- * root cause of the `EROFS: read-only file system, mkdir '/data'` crash
- * reported on macOS.
+ * The canonical contract is ADR-0086. Two things this pins that node:path alone
+ * gets wrong: a drive-letter path is absolute on POSIX too (isAbsolute does not
+ * recognise it, so it would be re-rooted under cwd), and a relative path whose
+ * parent escapes cwd must be REFUSED — never the silent mkdir outside the
+ * project that was the root cause of the `EROFS: mkdir '/data'` crash.
  */
-function resolveSqlitePath(dbPath: string): string {
+export function resolveSqlitePath(dbPath: string): string {
   if (dbPath === ":memory:") return dbPath;
 
-  let path = dbPath;
-  if (!isAbsolute(path)) {
-    path = join(process.cwd(), path);
-    // Auto-mkdir is safe here — we know the parent is under cwd
-    mkdirSync(dirname(path), { recursive: true });
-  } else {
-    // Absolute path. Only auto-mkdir if it's a descendant of cwd.
-    const cwd = resolve(process.cwd());
-    const abs = resolve(path);
-    if (abs.startsWith(cwd + "/") || abs === cwd) {
-      mkdirSync(dirname(abs), { recursive: true });
-    }
-    // Otherwise, trust the user — don't touch the filesystem.
+  // A Windows drive-letter path (C:/... or C:\...) is absolute on EVERY OS.
+  // node:path.isAbsolute does NOT recognise it on POSIX (it would re-root the
+  // path under cwd), so recognise it explicitly for parity (ADR-0086).
+  const isWindowsAbs = /^[A-Za-z]:[\\/]/.test(dbPath);
+  if (isAbsolute(dbPath) || isWindowsAbs) {
+    // Absolute — trust the user; never auto-mkdir (parity with the other three).
+    return dbPath;
   }
+
+  // Relative — resolve under cwd; create the parent (mode 0775) ONLY when it
+  // stays inside cwd. A relative path whose parent escapes the project is
+  // REFUSED loudly — never a silent mkdir outside the project.
+  const cwd = resolve(process.cwd());
+  const path = join(cwd, dbPath);
+  const parent = dirname(path);
+  const absParent = resolve(parent);
+  if (absParent !== cwd && !absParent.startsWith(cwd + sep)) {
+    throw new Error(
+      `SQLite path "${dbPath}" resolves outside the project directory: ` +
+        `"${absParent}" is not within "${cwd}". Tina4 refuses to create ` +
+        `directories outside the project (ADR-0086). Use an absolute path for a ` +
+        `database that lives outside the project.`,
+    );
+  }
+  mkdirSync(parent, { recursive: true, mode: 0o775 });
   return path;
 }
 
@@ -264,17 +279,13 @@ export class SQLiteAdapter implements DatabaseAdapter {
 
   insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult {
     if (Array.isArray(data)) {
-      if (data.length === 0) return { success: true, affectedRows: 0 };
-      const keys = Object.keys(data[0]);
-      const sql = buildInsert(ANSI_DIALECT, table, keys);
-      const paramsList = data.map((row) => keys.map((k) => row[k]));
-      const result = this.executeMany(sql, paramsList);
+      const batch = buildInsertRows(ANSI_DIALECT, table, data);
+      if (!batch) return { success: true, affectedRows: 0 };
+      const result = this.executeMany(batch.sql, batch.paramsList);
       return { success: true, affectedRows: result.affectedRows, lastId: result.lastId };
     }
 
-    const keys = Object.keys(data);
-    const sql = buildInsert(ANSI_DIALECT, table, keys);
-    const values = Object.values(data);
+    const { sql, values } = buildInsertRow(ANSI_DIALECT, table, data);
 
     try {
       const result = this.db.prepare(sql).run(...toSqlParams(values));
@@ -286,30 +297,11 @@ export class SQLiteAdapter implements DatabaseAdapter {
   }
 
   update(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): DatabaseResult {
-    const setClauses = buildSetClause(ANSI_DIALECT, Object.keys(data));
-
-    // A raw WHERE fragment + params is half the write_path contract's filter
-    // form ("a string filter with params works the same as a hash filter").
-    // Without this branch Object.keys("id = ?") yields the STRING INDICES
-    // ["0","1",...], producing `WHERE "0" = ? AND "1" = ?` and SQLite reports
-    // `no such column: "0"`. delete() below already carried this branch and
-    // update() did not — the same gap 3.13.94 closed in the postgres/mysql/
-    // mssql/firebird adapters, still open here on the DEFAULT engine.
-    if (typeof filter === "string") {
-      const where = filter ? ` WHERE ${filter}` : "";
-      const sql = `UPDATE ${ANSI_DIALECT.quote(table)} SET ${setClauses}${where}`;
-      const values = [...Object.values(data), ...(params ?? [])];
-      try {
-        const result = this.db.prepare(sql).run(...toSqlParams(values));
-        return { success: true, affectedRows: Number(result.changes) };
-      } catch (e) {
-        return { success: false, affectedRows: 0, error: (e as Error).message };
-      }
-    }
-
-    const whereClauses = buildWhereClause(ANSI_DIALECT, Object.keys(filter));
-    const sql = `UPDATE ${ANSI_DIALECT.quote(table)} SET ${setClauses} WHERE ${whereClauses}`;
-    const values = [...Object.values(data), ...Object.values(filter)];
+    // The string-filter vs hash-filter branch and the value assembly live in the
+    // shared composer (sqlCrud.ts); SQLite supplies only its driver execution.
+    // A raw WHERE fragment carries `?` markers, which SQLite uses natively, so no
+    // fragment rewrite is needed.
+    const { sql, values } = buildUpdate(ANSI_DIALECT, table, data, filter, params);
 
     try {
       const result = this.db.prepare(sql).run(...toSqlParams(values));
@@ -329,19 +321,7 @@ export class SQLiteAdapter implements DatabaseAdapter {
       return { success: true, affectedRows: totalAffected };
     }
 
-    if (typeof filter === "string") {
-      const sql = filter ? `DELETE FROM "${table}" WHERE ${filter}` : `DELETE FROM "${table}"`;
-      try {
-        const result = this.db.prepare(sql).run(...toSqlParams(params ?? []));
-        return { success: true, affectedRows: Number(result.changes) };
-      } catch (e) {
-        return { success: false, affectedRows: 0, error: (e as Error).message };
-      }
-    }
-
-    const whereClauses = buildWhereClause(ANSI_DIALECT, Object.keys(filter));
-    const sql = `DELETE FROM ${ANSI_DIALECT.quote(table)} WHERE ${whereClauses}`;
-    const values = Object.values(filter);
+    const { sql, values } = buildDelete(ANSI_DIALECT, table, filter, params);
 
     try {
       const result = this.db.prepare(sql).run(...toSqlParams(values));

package/packages/orm/src/index.ts

@@ -93,7 +93,7 @@ export type {
 } from "./docstore.js";
 
 // Database adapters
-export { SQLiteAdapter } from "./adapters/sqlite.js";
+export { SQLiteAdapter, resolveSqlitePath } from "./adapters/sqlite.js";
 export { PostgresAdapter } from "./adapters/postgres.js";
 export type { PostgresConfig } from "./adapters/postgres.js";
 export { MysqlAdapter } from "./adapters/mysql.js";

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

@@ -121,6 +121,11 @@ export interface ApiOptions {
      * persisted; scoped to this instance.
      */
     cookies?: boolean;
+    /**
+     * SSRF guard (ADR-0084): an explicit allow-list of hosts / host:port / CIDRs
+     * that bypass the private-address refusal even with the opt-out off.
+     */
+    allowHosts?: string[];
 }
 /**
  * Split an async byte iterable into UTF-8 lines. Handles LF and CRLF; a
@@ -155,6 +160,7 @@ export declare class Api {
     private transportFn?;
     private cookiesEnabled;
     private cookies;
+    private allowHosts;
     /**
      * Construct an Api client.
      *

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

@@ -1,4 +1,34 @@
 import type { Middleware } from "./types.js";
+/**
+ * Token purposes that are never an identity (ADR-0079 s1). Frond's formToken()
+ * signs a JWT with the same TINA4_SECRET as an auth token, marked
+ * `type: "form"`. A form token proves where a write came from, never who the
+ * caller is, so every identity gate refuses these purposes. validToken itself
+ * stays purpose-neutral: the CSRF middleware needs it for form tokens.
+ */
+export declare const NON_IDENTITY_TOKEN_TYPES: readonly string[];
+/**
+ * Minimum HMAC key length in bytes (ADR-0079 s2): the HS256 output size, RFC
+ * 7518 s3.2. A blank key is the shortest case - anyone can reproduce it.
+ */
+export declare const MIN_SECRET_BYTES = 32;
+/**
+ * True when a VERIFIED payload may stand for a caller's identity. A payload
+ * whose `type` is a reserved non-identity purpose (a Frond form token) is
+ * refused; application payloads are otherwise untouched.
+ */
+export declare function isIdentityPayload(payload: Record<string, unknown> | null | undefined): payload is Record<string, unknown>;
+/** The actionable error for a weak HMAC key, or null when the key is usable. */
+export declare function insecureSecretMessage(secret: string | undefined | null): string | null;
+/**
+ * Refuse to boot with a secret that makes tokens forgeable (ADR-0079 s2).
+ * Outside dev a blank TINA4_SECRET is refused; in any mode a set-but-short one
+ * is refused. Dev with a blank secret has already had one minted into
+ * .env.local by ensureDevSecret(). RS256 keys are PEMs and are not measured.
+ *
+ * @throws Error with the actionable message naming TINA4_SECRET.
+ */
+export declare function requireBootSecret(): void;
 /**
  * Ensure a usable TINA4_SECRET exists. Run ONCE at server boot, after env load
  * and before auth is used. Mirrors Python's `ensure_dev_secret()`.

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

@@ -38,6 +38,16 @@ export declare function graphqlAutoSchemaEnabled(): boolean;
  * set `<= 0` to disable the guard. A non-numeric value falls back to 50.
  */
 export declare function graphqlMaxDepth(): number;
+/**
+ * F2: maximum number of expanded selection nodes a single query may request.
+ * The depth guard bounds NESTING but not WIDTH: a fragment that spreads another
+ * fragment many times (a "fragment bomb") stays shallow while expanding to
+ * millions of fields, and a query with thousands of aliases of one field is not
+ * deep at all. This budget bounds the expanded selection tree (fragments
+ * expanded, aliases counted) so both are rejected before any resolver runs.
+ * `TINA4_GRAPHQL_MAX_NODES` overrides the default (1000); `<= 0` disables it.
+ */
+export declare function graphqlMaxNodes(): number;
 export declare class GraphQL {
     private types;
     private queries;
@@ -53,6 +63,12 @@ export declare class GraphQL {
      * spread / inline fragment, so circular fragments are caught too.
      */
     maxDepth: number;
+    /**
+     * Maximum expanded selection nodes per query (from `TINA4_GRAPHQL_MAX_NODES`,
+     * default 1000; `<= 0` disables). Bounds query WIDTH — fragment bombs and
+     * alias explosions — which the depth guard does not. See {@link graphqlMaxNodes}.
+     */
+    maxNodes: number;
     /**
      * Decorator-style resolver registration.
      *
@@ -124,6 +140,15 @@ export declare class GraphQL {
      * instead of recursing until the interpreter stack overflows. Top-level
      * starts at depth 1; `maxDepth <= 0` disables the guard.
      */
+    /**
+     * Count the expanded selection nodes, throwing {@link ComplexityError} past
+     * `maxNodes` (F2). Fragment spreads are expanded (so a fragment bomb is
+     * counted, not the small unexpanded document) and every field — including
+     * each alias — counts once. The count is capped by `maxNodes` and the walk by
+     * `maxDepth`, so a circular fragment trips the budget instead of looping and
+     * the check itself can never cost more than the budget.
+     */
+    private assertComplexity;
     private resolveSelectionsInto;
     /**
      * Generate SDL schema string.

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

@@ -40,6 +40,7 @@ export type { ServiceOptions, ServiceContext, ServiceHandler, ServiceInfo } from
 export { responseCache, clearCache, cacheStats, cacheGet, cacheSet, cacheDelete, cacheClear, cacheBackendStats, sweep, createBackend, _resetBackend } from "./cache.js";
 export type { ResponseCacheConfig, CacheBackend } from "./cache.js";
 export { Api, ApiStreamError, parseLineStream, parseSseStream } from "./api.js";
+export { guardUrl, isBlockedAddress, allowPrivateRequests, SsrfError, ALLOW_PRIVATE_ENV } from "./ssrf.js";
 export type { ApiResult, ApiOptions, ApiTransport, DownloadResult, UploadOptions, StreamOptions, SseEvent } from "./api.js";
 export { Context, defaultContext, existingContext, fts5Supported, _sharedContexts } from "./context/index.js";
 export type { SearchHit } from "./context/index.js";

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

@@ -31,6 +31,7 @@ export interface JobLifecycle {
 export type QueueJob = JobData & JobLifecycle;
 export interface JobQueueBridge {
     _failJob(topic: string, job: QueueJob, reason: string, maxRetries: number): void;
+    _rejectJob(topic: string, job: QueueJob, reason: string, maxRetries: number): void;
     _retryJob(topic: string, job: QueueJob, delaySeconds?: number): void;
     _completeJob(topic: string, job: QueueJob): void;
     getMaxRetries(): number;

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

@@ -11,6 +11,11 @@ export interface PushOptions {
     privateKey?: string;
     ttl?: number;
     urgency?: "very-low" | "low" | "normal" | "high";
+    /**
+     * SSRF guard (ADR-0084): an explicit allow-list of hosts / host:port / CIDRs
+     * that bypass the private-endpoint refusal even with the opt-out off.
+     */
+    allowHosts?: string[];
 }
 export interface PushResult {
     ok: boolean;

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

@@ -59,7 +59,7 @@ export interface ConsumeOptions {
 export interface QueueBackendInterface {
     push(queue: string, payload: unknown, delay?: number, priority?: number): string;
     pop(queue: string): QueueJob | null;
-    size(queue: string): number;
+    size(queue: string, status?: string): number;
     clear(queue: string): void;
     /**
      * Release whatever connection the backend holds, and be safe to call twice.
@@ -74,6 +74,7 @@ export interface QueueBackendInterface {
     close(): void;
     complete?(queue: string, id: string): void;
     fail?(queue: string, id: string, error: string, maxRetries: number, retryBackoff: number): void;
+    reject?(queue: string, id: string, reason: string, maxRetries: number): void;
     /**
      * Explicit manual re-queue: returns true if the id was found and revived,
      * false otherwise (parity with Python's backend.retry_job()). A backend may
@@ -289,6 +290,11 @@ export declare class Queue {
      * after retryBackoff seconds) or dead-letter (attempts >= maxRetries).
      */
     _failJob(queue: string, job: QueueJob, error: string, maxRetries: number): void;
+    /**
+     * Dead-letter a job immediately — no retry (ADR-0023 reject()). Distinct from
+     * _failJob, which retries until maxRetries is spent.
+     */
+    _rejectJob(queue: string, job: QueueJob, reason: string, maxRetries: number): void;
     /**
      * Re-queue a job back to the main queue directory with incremented attempts.
      */

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

@@ -130,5 +130,14 @@ export declare class LiteBackend {
      * dead-letter file -- two spellings of the same intent that previously
      * diverged.
      */
+    /**
+     * Reject a job permanently — dead-letter it NOW, no retry (ADR-0023).
+     *
+     * Unlike failJob(), which requeues until maxRetries is spent, rejectJob()
+     * moves a known-poison job straight to the dead-letter store. attempts is
+     * floored at maxRetries so deadLetters() (attempts >= maxRetries) returns it
+     * and size("dead") agrees.
+     */
+    rejectJob(queue: string, job: QueueJob, reason: string, maxRetries: number): void;
     retryJob(queue: string, job: QueueJob, delaySeconds?: number): void;
 }

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

@@ -76,7 +76,14 @@ export declare class MongoBackend implements QueueBackend {
     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;
+    size(queue: string, status?: string): number;
+    /**
+     * Dead-letter a job immediately — no retry (ADR-0023 reject()). Distinct from
+     * fail(): fail() requeues until maxRetries is spent. attempts is floored at
+     * maxRetries so deadLetters()/size("dead") (which filter/scope to the
+     * dead-letter store) see it.
+     */
+    reject(queue: string, id: string, reason: string, maxRetries: number): void;
     clear(queue: string): void;
     /**
      * Acknowledge a completed job — drop its reservation so the reclaim never

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

@@ -86,9 +86,33 @@ export declare class DatabaseSessionHandler implements SessionHandler {
     /** Run a statement that returns nothing. */
     private exec;
     /**
-     * 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;
+    /**
+     * 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;
     read(sessionId: string): SessionData | null;
     write(sessionId: string, data: SessionData, ttl: number): void;
     destroy(sessionId: string): void;

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

@@ -2,6 +2,7 @@ import type { Router } from "./router.js";
 export declare class SsoError extends Error {
 }
 type Json = Record<string, any>;
+export { liveSessionIdentity } from "./ssoIdentity.js";
 export interface SsoOptions {
     issuer?: string;
     clientId?: string;

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

@@ -0,0 +1,10 @@
+/**
+ * The stored SSO identity, only while it is live (ADR-0079 s5). `stored` is the
+ * reserved _tina4_sso session value. The identity needs an issuer and a
+ * subject, and a numeric expires_at that is 0 (the provider gave no lifetime)
+ * or still in the future.
+ *
+ * Its own dependency-free module, so the auth gate can use it without
+ * importing the OIDC client (and everything the client imports).
+ */
+export declare function liveSessionIdentity(stored: unknown): Record<string, any> | null;

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

@@ -0,0 +1,19 @@
+export declare const ALLOW_PRIVATE_ENV = "TINA4_ALLOW_PRIVATE_REQUESTS";
+/** Raised when the SSRF guard refuses an outbound request. */
+export declare class SsrfError extends Error {
+    constructor(message: string);
+}
+/** True when TINA4_ALLOW_PRIVATE_REQUESTS opts out of the guard. */
+export declare function allowPrivateRequests(): boolean;
+/**
+ * Classify one IP string: true = private/internal, refuse it. An IPv4-mapped
+ * IPv6 address is classified by its embedded IPv4. An unparseable value is
+ * treated as blocked - the guard refuses what it cannot classify.
+ */
+export declare function isBlockedAddress(ip: string): boolean;
+/**
+ * Refuse `url` when it targets a private/internal address. Throws SsrfError for a
+ * non-http(s) scheme, an unresolvable host, or any resolved address in the
+ * blocked space. `allowHosts` is a list of hosts / host:port / CIDRs to permit.
+ */
+export declare function guardUrl(url: string, allowHosts?: string[]): Promise<void>;