tina4-nodejs 3.13.138 → 3.13.140

package/packages/core/src/queueBackends/mongoBackend.ts

@@ -307,12 +307,36 @@ export class MongoBackend implements QueueBackend {
             }
           }
           else if (operation === "size") {
-            const count = await col.countDocuments({
-              queue: queueName,
-              status: "pending",
-            });
+            // ADR-0022 dec 7: size(status) must not answer a different question.
+            // The dead aliases count the .dead_letter store (== deadLetters().length);
+            // reserved/completed count by status; else pending. data = status.
+            const status = data || "pending";
+            let count: number;
+            if (status === "dead" || status === "failed" || status === "dead_letter") {
+              count = await col.countDocuments({ queue: queueName + ".dead_letter" });
+            } else if (status === "reserved" || status === "completed") {
+              count = await col.countDocuments({ queue: queueName, status });
+            } else {
+              count = await col.countDocuments({ queue: queueName, status: "pending" });
+            }
             process.stdout.write(String(count));
           }
+          else if (operation === "reject") {
+            // Dead-letter NOW, no retry (ADR-0023). Floor attempts at maxRetries
+            // so it reads as exhausted (parity with fail()'s dead-letter branch
+            // and size("dead")). data = JSON { id, reason, maxRetries }.
+            const info = JSON.parse(data);
+            const doc = await col.findOne({ queue: queueName, id: info.id });
+            if (doc) {
+              const attempts = Math.max((doc.attempts || 0) + 1, info.maxRetries);
+              await col.insertOne({
+                ...doc, _id: undefined, attempts,
+                status: "dead", queue: queueName + ".dead_letter", error: info.reason,
+              });
+              await col.deleteOne({ _id: doc._id, queue: queueName });
+            }
+            process.stdout.write("__OK__");
+          }
           else if (operation === "clear") {
             await col.deleteMany({ queue: queueName });
             process.stdout.write("__CLEARED__");
@@ -559,12 +583,22 @@ export class MongoBackend implements QueueBackend {
     }
   }
 
-  size(queue: string): number {
-    const result = this.execSync("size", queue);
+  size(queue: string, status: string = "pending"): number {
+    const result = this.execSync("size", queue, status);
     const num = parseInt(result, 10);
     return isNaN(num) ? 0 : num;
   }
 
+  /**
+   * 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 {
+    this.execSync("reject", queue, JSON.stringify({ id, reason, maxRetries }));
+  }
+
   clear(queue: string): void {
     this.execSync("clear", queue);
   }

package/packages/core/src/server.ts

@@ -2056,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();
 

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

@@ -160,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.
  *
@@ -223,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;
@@ -342,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/sso.ts

@@ -13,6 +13,15 @@ import type { Router } from "./router.js";
 export class SsoError extends Error {}
 
 type Json = Record<string, any>;
+
+export { liveSessionIdentity } from "./ssoIdentity.js";
+import { liveSessionIdentity } from "./ssoIdentity.js";
+
+/** When the provider's access token lapses; 0 when it gave no lifetime (never "now"). */
+function expiresAt(tokens: Json): number {
+  const lifetime = Number(tokens.expires_in ?? 0);
+  return lifetime > 0 ? Math.floor(Date.now() / 1000) + lifetime : 0;
+}
 type SessionLike = {
   get(key: string): unknown;
   set(key: string, value: unknown): void;
@@ -225,14 +234,13 @@ export class Sso {
     session!.regenerate();
     session!.set(Sso.SESSION_KEY, {
       version: 1, identity, access_token: tokens.access_token, refresh_token: tokens.refresh_token,
-      id_token: tokens.id_token, expires_at: Math.floor(Date.now() / 1000) + Number(tokens.expires_in ?? 0),
+      id_token: tokens.id_token, expires_at: expiresAt(tokens),
     });
     return { identity, return_to: Sso.safeReturn(pending.return_to) };
   }
 
   identity(requestOrSession: any): Json | null {
-    const stored = this.session(requestOrSession)?.get(Sso.SESSION_KEY) as Json | undefined;
-    const identity = stored?.identity ?? null;
+    const identity = liveSessionIdentity(this.session(requestOrSession)?.get(Sso.SESSION_KEY));
     if (identity && requestOrSession?.session) requestOrSession.user = identity;
     return identity;
   }
@@ -251,7 +259,7 @@ export class Sso {
       const identity = this.normalize(claims);
       session!.set(Sso.SESSION_KEY, { ...stored, identity, access_token: tokens.access_token,
         refresh_token: tokens.refresh_token ?? stored.refresh_token, id_token: tokens.id_token ?? stored.id_token,
-        expires_at: Math.floor(Date.now() / 1000) + Number(tokens.expires_in ?? 0) });
+        expires_at: expiresAt(tokens) });
       return identity;
     } catch (error) { session?.delete(Sso.SESSION_KEY); throw error; }
   }

package/packages/core/src/ssoIdentity.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 function liveSessionIdentity(stored: unknown): Record<string, any> | null {
+  if (!stored || typeof stored !== "object") return null;
+  const identity = (stored as Record<string, any>).identity;
+  if (!identity || typeof identity !== "object" || !identity.issuer || !identity.subject) return null;
+  const expiresAt = (stored as Record<string, any>).expires_at ?? 0;
+  if (typeof expiresAt !== "number") return null;
+  if (expiresAt > 0 && Math.floor(Date.now() / 1000) >= expiresAt) return null;
+  return identity;
+}
+

package/packages/core/src/ssrf.ts

@@ -0,0 +1,221 @@
+/**
+ * Outbound SSRF guard (ADR-0084).
+ *
+ * The Api client and Web Push refuse, by default, to connect to a private or
+ * internal address. Before each connection - the initial URL and every redirect
+ * hop the Api client follows - the host is resolved to its IP address(es) and
+ * the request is refused if any resolved address is loopback, private,
+ * link-local (including the cloud metadata address 169.254.169.254), unspecified
+ * or CGNAT. A non-http(s) scheme is refused.
+ *
+ * Off by default; TINA4_ALLOW_PRIVATE_REQUESTS (truthy) or an explicit allow-list
+ * of hosts / host:port / CIDRs opts out. Zero external dependencies - node:net +
+ * node:dns.
+ */
+import { isIP } from "node:net";
+import { lookup } from "node:dns/promises";
+
+export const ALLOW_PRIVATE_ENV = "TINA4_ALLOW_PRIVATE_REQUESTS";
+
+/** Truthiness identical to ADR-0070's set (trimmed, lower-cased). */
+const TRUTHY: ReadonlySet<string> = new Set(["1", "true", "yes", "on"]);
+
+/** Raised when the SSRF guard refuses an outbound request. */
+export class SsrfError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "SsrfError";
+    }
+}
+
+interface Cidr {
+    net: Uint8Array;
+    bits: number;
+}
+
+/**
+ * The blocked address space, one definition shared with the contract fixture.
+ * 0.0.0.0/8 covers the unspecified address and the "this network" block.
+ */
+const BLOCKED_CIDRS: readonly string[] = [
+    "0.0.0.0/8", "10.0.0.0/8", "127.0.0.0/8", "169.254.0.0/16",
+    "172.16.0.0/12", "192.168.0.0/16", "100.64.0.0/10",
+    "::1/128", "::/128", "fc00::/7", "fe80::/10",
+];
+
+function v4ToBytes(ip: string): Uint8Array | null {
+    const parts = ip.split(".");
+    if (parts.length !== 4) return null;
+    const bytes = new Uint8Array(4);
+    for (let i = 0; i < 4; i++) {
+        const n = Number(parts[i]);
+        if (!Number.isInteger(n) || n < 0 || n > 255 || !/^\d+$/.test(parts[i])) return null;
+        bytes[i] = n;
+    }
+    return bytes;
+}
+
+function v6ToBytes(input: string): Uint8Array | null {
+    let ip = input.split("%")[0];
+    // Embedded IPv4 tail (::ffff:1.2.3.4).
+    const lastColon = ip.lastIndexOf(":");
+    const tail = ip.slice(lastColon + 1);
+    if (tail.includes(".")) {
+        const v4 = v4ToBytes(tail);
+        if (!v4) return null;
+        const hextetA = ((v4[0] << 8) | v4[1]).toString(16);
+        const hextetB = ((v4[2] << 8) | v4[3]).toString(16);
+        ip = ip.slice(0, lastColon + 1) + hextetA + ":" + hextetB;
+    }
+    const halves = ip.split("::");
+    if (halves.length > 2) return null;
+    const head = halves[0] ? halves[0].split(":") : [];
+    const back = halves.length === 2 ? (halves[1] ? halves[1].split(":") : []) : [];
+    let groups: string[];
+    if (halves.length === 1) {
+        if (head.length !== 8) return null;
+        groups = head;
+    } else {
+        const missing = 8 - (head.length + back.length);
+        if (missing < 0) return null;
+        groups = [...head, ...Array(missing).fill("0"), ...back];
+    }
+    if (groups.length !== 8) return null;
+    const bytes = new Uint8Array(16);
+    for (let i = 0; i < 8; i++) {
+        if (!/^[0-9a-fA-F]{1,4}$/.test(groups[i])) return null;
+        const g = parseInt(groups[i], 16);
+        bytes[i * 2] = (g >> 8) & 0xff;
+        bytes[i * 2 + 1] = g & 0xff;
+    }
+    return bytes;
+}
+
+/** Parse an IP string (v4 or v6, IPv4-mapped included) to its packed bytes. */
+function ipToBytes(ip: string): Uint8Array | null {
+    const cleaned = ip.split("%")[0];
+    const family = isIP(cleaned);
+    if (family === 4) return v4ToBytes(cleaned);
+    if (family === 6) {
+        const bytes = v6ToBytes(cleaned);
+        if (!bytes) return null;
+        // Unwrap IPv4-mapped IPv6 (::ffff:a.b.c.d) to its 4-byte IPv4.
+        const isMapped = bytes.subarray(0, 10).every((b) => b === 0)
+            && bytes[10] === 0xff && bytes[11] === 0xff;
+        return isMapped ? bytes.subarray(12) : bytes;
+    }
+    return null;
+}
+
+function parseCidr(cidr: string): Cidr | null {
+    const [netStr, bitsStr] = cidr.split("/");
+    const net = ipToBytes(netStr);
+    if (!net) return null;
+    return { net, bits: Number(bitsStr) };
+}
+
+const BLOCKED: readonly Cidr[] = BLOCKED_CIDRS
+    .map(parseCidr)
+    .filter((c): c is Cidr => c !== null);
+
+function inCidr(packed: Uint8Array, cidr: Cidr): boolean {
+    if (packed.length !== cidr.net.length) return false;
+    const whole = Math.floor(cidr.bits / 8);
+    const remainder = cidr.bits % 8;
+    for (let i = 0; i < whole; i++) {
+        if (packed[i] !== cidr.net[i]) return false;
+    }
+    if (remainder === 0) return true;
+    const mask = (0xff << (8 - remainder)) & 0xff;
+    return (packed[whole] & mask) === (cidr.net[whole] & mask);
+}
+
+/** True when TINA4_ALLOW_PRIVATE_REQUESTS opts out of the guard. */
+export function allowPrivateRequests(): boolean {
+    return TRUTHY.has((process.env[ALLOW_PRIVATE_ENV] ?? "").trim().toLowerCase());
+}
+
+/**
+ * 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 function isBlockedAddress(ip: string): boolean {
+    const packed = ipToBytes(ip);
+    if (!packed) return true;
+    return BLOCKED.some((cidr) => inCidr(packed, cidr));
+}
+
+function matchesAllowList(host: string, port: number, resolved: string[], allowHosts?: string[]): boolean {
+    const hostLower = host.toLowerCase();
+    for (const raw of allowHosts ?? []) {
+        const entry = String(raw).trim().toLowerCase();
+        if (!entry) continue;
+        if (entry === hostLower || entry === `${hostLower}:${port}`) return true;
+        if (entry.includes("/")) {
+            const cidr = parseCidr(entry);
+            if (cidr && resolved.some((ip) => {
+                const packed = ipToBytes(ip);
+                return packed !== null && inCidr(packed, cidr);
+            })) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+function logBlock(host: string, ip: string): void {
+    // Log lazily to avoid a hard dependency cycle with the logger.
+    void import("./logger.js")
+        .then((mod) => mod.Log?.warning?.(`SSRF guard blocked outbound request to ${host} (${ip})`))
+        .catch(() => undefined);
+}
+
+/**
+ * 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 async function guardUrl(url: string, allowHosts?: string[]): Promise<void> {
+    let parsed: URL;
+    try {
+        parsed = new URL(url);
+    } catch {
+        throw new SsrfError(`Blocked request: '${url}' is not a valid URL`);
+    }
+    const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();
+    if (scheme !== "http" && scheme !== "https") {
+        throw new SsrfError(`Blocked request: URL scheme '${scheme || "(none)"}' is not http or https`);
+    }
+    const host = parsed.hostname.replace(/^\[|\]$/g, "");
+    if (!host) {
+        throw new SsrfError("Blocked request: URL has no host");
+    }
+    const port = parsed.port ? Number(parsed.port) : (scheme === "https" ? 443 : 80);
+
+    if (allowPrivateRequests()) return;
+
+    let resolved: string[];
+    try {
+        const results = await lookup(host, { all: true });
+        resolved = results.map((r) => r.address);
+    } catch {
+        throw new SsrfError(`Blocked request to ${host}: cannot resolve host`);
+    }
+    if (resolved.length === 0) {
+        throw new SsrfError(`Blocked request to ${host}: cannot resolve host`);
+    }
+
+    if (matchesAllowList(host, port, resolved, allowHosts)) return;
+
+    for (const ip of resolved) {
+        if (isBlockedAddress(ip)) {
+            logBlock(host, ip);
+            throw new SsrfError(
+                `Blocked request to private/internal address ${ip} (host ${host}): ` +
+                `set ${ALLOW_PRIVATE_ENV}=true to allow, or pass an allow-list.`,
+            );
+        }
+    }
+}

package/packages/core/src/testClient.ts

@@ -207,6 +207,9 @@ export class TestClient {
 
     // Create a mock IncomingMessage
     const socket = new Socket();
+    // The in-process client is a local caller and says so explicitly: an
+    // unknown (empty) peer is not loopback (ADR-0079 s4).
+    Object.defineProperty(socket, "remoteAddress", { value: "127.0.0.1" });
     const rawReq = new IncomingMessage(socket);
     rawReq.method = method.toUpperCase();
     rawReq.url = path;

package/packages/core/src/websocket.ts

@@ -38,7 +38,7 @@ import type { WebSocketConnection } from "./websocketConnection.js";
 import type { WebSocketRouteHandler } from "./types.js";
 import { Router } from "./router.js";
 import { Log } from "./logger.js";
-import { validToken } from "./auth.js";
+import { validToken, isIdentityPayload } from "./auth.js";
 import { WsBackplaneManager, type WsEnvelope } from "./websocketBackplane.js";
 
 // ── Constants ────────────────────────────────────────────────
@@ -211,7 +211,9 @@ export function wsAuthorized(
   const token = wsToken(headers, queryString, subprotocol);
   if (!token) return [null, false];
   const payload = validToken(token);
-  return [payload, payload !== null];
+  // A form token is not an identity (ADR-0079 s1).
+  if (!isIdentityPayload(payload)) return [null, false];
+  return [payload, true];
 }
 
 /**

package/packages/frond/dist/index.js

@@ -1415,6 +1415,12 @@ function _b64url(data) {
 var _formTokenSessionId = "";
 function _buildFormTokenJwt(descriptor = "") {
   const secret = process.env.TINA4_SECRET ?? "";
+  const secretBytes = Buffer.byteLength(secret, "utf8");
+  if (secretBytes < 32) {
+    throw new Error(
+      `Auth: TINA4_SECRET ${secretBytes === 0 ? "is not set" : `is ${secretBytes} bytes`}; an HMAC JWT secret must be at least 32 bytes. Generate one with \`openssl rand -hex 32\` and set TINA4_SECRET in your environment or .env.`
+    );
+  }
   const ttlMinutes = parseInt(process.env.TINA4_TOKEN_LIMIT || "60", 10);
   const header = { alg: "HS256", typ: "JWT" };
   const now = Math.floor(Date.now() / 1e3);

package/packages/frond/src/engine.ts

@@ -1794,6 +1794,15 @@ function _buildFormTokenJwt(descriptor: string = ""): string {
   // AND a ''-forged token was accepted (CSRF-NODE-SECRET-SPLIT, feature 37).
   // The generator and the validator MUST resolve the same secret.
   const secret = process.env.TINA4_SECRET ?? "";
+  // Same rule as core auth (ADR-0079 s2): never sign with a blank or short key,
+  // which would make every form token reproducible by anyone.
+  const secretBytes = Buffer.byteLength(secret, "utf8");
+  if (secretBytes < 32) {
+    throw new Error(
+      `Auth: TINA4_SECRET ${secretBytes === 0 ? "is not set" : `is ${secretBytes} bytes`}; an HMAC JWT secret must be at least 32 bytes. ` +
+      "Generate one with `openssl rand -hex 32` and set TINA4_SECRET in your environment or .env.",
+    );
+  }
   const ttlMinutes = parseInt(process.env.TINA4_TOKEN_LIMIT || "60", 10);
 
   const header = { alg: "HS256", typ: "JWT" };