tina4-nodejs 3.13.137 → 3.13.139

package/packages/core/src/mqtt.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Zero-dependency MQTT 3.1.1 client — the protocol every broker and every IoT
  * device already speaks.

package/packages/core/src/mqttMessage.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * One MQTT 3.1.1 application message as delivered by the broker.
  *

package/packages/core/src/optionalPackage.ts

@@ -0,0 +1,48 @@
+/*
+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/.
+*/
+
+/**
+ * Optional peer packages: the database drivers and service clients an
+ * APPLICATION installs, never the framework (ADR-0067).
+ *
+ * tina4-nodejs installs as exactly one package. `pg`, `mongodb`, `redis` and
+ * the `@aws-sdk` S3 client are optional peerDependencies, which npm does not
+ * install, so for most apps "missing" is the normal state. Every feature that
+ * reaches for one must therefore fail at the point of use with the exact
+ * command that fixes it - never a bare MODULE_NOT_FOUND, never a silent no-op.
+ */
+
+/** The actionable "install it" error, one wording for every optional peer. */
+export function optionalPackageMissing(feature: string, packageNames: string[]): Error {
+  const quoted = packageNames.map((name) => `'${name}'`).join(" and ");
+  const [noun, pronoun] = packageNames.length === 1 ? ["package is", "it"] : ["packages are", "them"];
+  return new Error(
+    `The ${quoted} ${noun} required for ${feature}. ` +
+      `Install ${pronoun} with: npm install ${packageNames.join(" ")}`,
+  );
+}
+
+/**
+ * Resolve an optional peer from the FRAMEWORK's location and return its module
+ * URL, or throw the actionable error. Synchronous, so a constructor can refuse
+ * immediately (parity with the Python master, which raises ImportError in the
+ * constructor) instead of leaving a rejected promise for later.
+ *
+ * Resolving from here rather than from process.cwd() is what finds the peer an
+ * app installed, wherever the server was started from.
+ *
+ * @param installTogether packages the feature needs as a set (S3 needs the
+ *   client AND the presigner), all named in the one install command.
+ */
+export function resolveOptionalPackage(packageName: string, feature: string, installTogether: string[] = [packageName]): string {
+  try {
+    return import.meta.resolve(packageName);
+  } catch {
+    throw optionalPackageMissing(feature, installTogether);
+  }
+}

package/packages/core/src/plan.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Project plan management — persistent, human-readable task state.
  *

package/packages/core/src/portTakeover.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Identity-checked port takeover, shared by the CLI and the runtime paths.
  *

package/packages/core/src/projectIndex.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Project index — lightweight, persistent "where is what" map.
  *

package/packages/core/src/projectIndexExtractors.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import * as path from "node:path";
 import type { FileEntry, FileRoute } from "./projectIndex.js";
 

package/packages/core/src/projectIndexStorage.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as crypto from "node:crypto";

package/packages/core/src/push.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Provider-neutral Web Push delivery using Node's built-in crypto and fetch.
  *
@@ -13,6 +21,7 @@ import {
   createSign,
   randomBytes,
 } from "node:crypto";
+import { guardUrl, SsrfError } from "./ssrf.js";
 
 const CURVE = "prime256v1";
 const RECORD_SIZE = 4096;
@@ -32,6 +41,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 {
@@ -259,10 +273,20 @@ export class Push {
   }
 
   private async deliver(endpoint: URL, config: { subject: string; publicKey: string; privateKey: string }, keys: { rawPublic: Buffer; rawPrivate: Buffer }, body: Buffer): Promise<PushResult> {
+    // SSRF guard (ADR-0084): refuse a private/internal push endpoint.
+    try {
+      await guardUrl(endpoint.toString(), this.options.allowHosts);
+    } catch (error) {
+      if (error instanceof SsrfError) throw new PushError(error.message);
+      throw error;
+    }
     let response: Response;
     try {
       response = await fetch(endpoint, {
         method: "POST",
+        // A real push service answers the POST directly; a redirect from a push
+        // endpoint is not followed to a private address (ADR-0084).
+        redirect: "manual",
         headers: {
           Authorization: `vapid t=${vapidToken(endpoint.toString(), config.subject, keys.rawPrivate, keys.rawPublic)}, k=${config.publicKey}`,
           "Content-Encoding": "aes128gcm",

package/packages/core/src/queue.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 Queue — Unified job queue with pluggable backends, zero dependencies.
  *
@@ -119,7 +127,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.
@@ -144,6 +152,7 @@ export interface QueueBackendInterface {
   // persistent-connection rewrite lands.
   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
@@ -424,7 +433,7 @@ export class Queue {
     const q = this.topic;
 
     if (this.externalBackend) {
-      return this.externalBackend.size(q);
+      return this.externalBackend.size(q, status);
     }
     return this.liteBackend.size(q, status);
   }
@@ -750,6 +759,18 @@ export class Queue {
     this.liteBackend.failJob(queue, job, error, maxRetries, this._retryBackoff);
   }
 
+  /**
+   * 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 {
+    if (this.externalBackend?.reject) {
+      this.externalBackend.reject(queue, job.id, reason, maxRetries);
+      return;
+    }
+    this.liteBackend.rejectJob(queue, job, reason, maxRetries);
+  }
+
   /**
    * Re-queue a job back to the main queue directory with incremented attempts.
    */

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

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 Kafka Queue Backend — Kafka protocol via raw TCP, zero dependencies.
  *

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

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * LiteBackend — file-based queue backend for Tina4 Queue.
  * Stores jobs as JSON files on disk. Zero dependencies.
@@ -685,6 +693,21 @@ export 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 {
+    this.clearReservation(queue, job.id);
+    job.attempts = Math.max((job.attempts || 0) + 1, maxRetries);
+    job.error = reason;
+    this.deadLetter(queue, job, reason);
+  }
+
   retryJob(queue: string, job: QueueJob, delaySeconds?: number): void {
     // Clear the reservation — the consumer acknowledged (with an explicit retry).
     this.clearReservation(queue, job.id);

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

@@ -1,5 +1,14 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
- * Tina4 MongoDB Queue Backend — uses `mongodb` npm package via dynamic import.
+ * Tina4 MongoDB Queue Backend — uses the `mongodb` npm package, which the app
+ * installs (`npm install mongodb`; an optional peer, ADR-0067).
  *
  * Implements the same interface as the file-based queue but uses MongoDB
  * for message storage and delivery. Atomic pop via findOneAndUpdate.
@@ -21,6 +30,7 @@
 import { randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import type { QueueJob } from "../queue.js";
+import { resolveOptionalPackage } from "../optionalPackage.js";
 
 // ── Types ────────────────────────────────────────────────────
 
@@ -71,8 +81,17 @@ export class MongoBackend implements QueueBackend {
   private collection: string;
   private visibilityTimeout: number;
   private maxRetries: number;
+  /** Module URL of the app-installed `mongodb` driver, resolved once. */
+  private driverUrl: string;
 
   constructor(config?: MongoConfig) {
+    // Optional peer (ADR-0067), resolved HERE, on the main thread. Every
+    // operation runs in a child process that swallows its own failures, so a
+    // driver missing there used to surface as "MongoDB push failed" and a pop
+    // that silently returned nothing. The Python master raises in its
+    // constructor; so does this. Resolving from the framework's location also
+    // means the child finds the driver whatever directory the server runs in.
+    this.driverUrl = resolveOptionalPackage("mongodb", "the MongoDB queue backend");
     this.host = config?.host ?? process.env.TINA4_MONGO_HOST ?? "localhost";
     this.port = config?.port
       ?? (process.env.TINA4_MONGO_PORT ? parseInt(process.env.TINA4_MONGO_PORT, 10) : 27017);
@@ -136,13 +155,7 @@ export class MongoBackend implements QueueBackend {
   buildScript(operation: string, queue: string, data?: string): string {
     return `
       async function main() {
-        let mongodb;
-        try {
-          mongodb = await import("mongodb");
-        } catch {
-          process.stderr.write("mongodb package not installed — run: npm install mongodb");
-          process.exit(1);
-        }
+        const mongodb = await import(${JSON.stringify(this.driverUrl)});
 
         const { MongoClient } = mongodb;
         const uri = ${JSON.stringify(this.uri)};
@@ -294,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__");
@@ -546,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/queueBackends/rabbitmqBackend.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 RabbitMQ Queue Backend — AMQP 0-9-1 via raw TCP, zero dependencies.
  *

package/packages/core/src/rateLimiter.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import type { Middleware, Tina4Request, Tina4Response } from "./types.js";
 import { resolveClientIp } from "./trustedProxy.js";
 

package/packages/core/src/request.ts

@@ -1,8 +1,17 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import type { IncomingMessage, IncomingHttpHeaders } from "node:http";
 import { mkdirSync, realpathSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import type { Tina4Request, UploadedFile } from "./types.js";
-import { resolveClientIp } from "./trustedProxy.js";
+import { resolveClientIp, isTrustedProxy } from "./trustedProxy.js";
+import { Log } from "./logger.js";
 
 /**
  * Wrap Node's `IncomingHttpHeaders` in a Proxy so mixed-case lookups
@@ -53,10 +62,11 @@ export function createRequest(req: IncomingMessage): Tina4Request {
     makeCaseInsensitiveHeaders(req.headers);
 
   // Resolve scheme + host honouring proxy headers — parity with PHP/Python/Ruby.
-  const xfProto = req.headers["x-forwarded-proto"];
+  const trustedPeer = isTrustedProxy(req.socket?.remoteAddress ?? "");
+  const xfProto = trustedPeer ? req.headers["x-forwarded-proto"] : undefined;
   const proto = (Array.isArray(xfProto) ? xfProto[0] : xfProto)
     ?? ((req.socket as { encrypted?: boolean })?.encrypted ? "https" : "http");
-  const xfHost = req.headers["x-forwarded-host"];
+  const xfHost = trustedPeer ? req.headers["x-forwarded-host"] : undefined;
   const host = (Array.isArray(xfHost) ? xfHost[0] : xfHost)
     ?? (req.headers.host ?? "localhost");
 
@@ -148,13 +158,50 @@ export function createRequest(req: IncomingMessage): Tina4Request {
   return tReq;
 }
 
-/** Maximum upload size in bytes (default 10 MB). Override via TINA4_MAX_UPLOAD_SIZE env var. */
-const TINA4_MAX_UPLOAD_SIZE = parseInt(process.env.TINA4_MAX_UPLOAD_SIZE ?? "10485760", 10);
+
+// ── Request limits (ADR-0068) ────────────────────────────────────────────────
+// Here rather than in a module of their own: request.ts sits below the server
+// and transport.ts, so both can read them without an import cycle, and the
+// core barrel's eager module graph stays one module smaller.
+
+export const DEFAULT_MAX_UPLOAD_SIZE = 10_485_760;
+
+const warnedLimits = new Set<string>();
+
+/**
+ * Read a numeric limit from the environment. A value that is not a usable
+ * number falls back to the default with a warning naming the variable (the
+ * same rule as PHP's Server::resolveLimit) - a typo must never be what
+ * disables a DoS guard.
+ */
+export function resolveLimit(name: string, fallback: number, zeroAllowed = false): number {
+  const raw = (process.env[name] ?? "").trim();
+  if (raw === "") return fallback;
+  const value = /^[0-9]+$/.test(raw) ? Number(raw) : NaN;
+  if (Number.isSafeInteger(value) && (value > 0 || (value === 0 && zeroAllowed))) return value;
+  if (!warnedLimits.has(`${name}=${raw}`)) {
+    warnedLimits.add(`${name}=${raw}`);
+    Log.warning(`${name}=${raw} is not a usable limit - using ${fallback}`);
+  }
+  return fallback;
+}
+
+/** TINA4_MAX_UPLOAD_SIZE, read when it is needed so a value from .env counts. */
+export function maxUploadSize(): number {
+  return resolveLimit("TINA4_MAX_UPLOAD_SIZE", DEFAULT_MAX_UPLOAD_SIZE);
+}
+
+/** The one 413 wording (ADR-0068 section 4). */
+export function bodyTooLargeMessage(bytes: number | bigint | string, limit: number): string {
+  return `Request body (${bytes} bytes) exceeds TINA4_MAX_UPLOAD_SIZE (${limit} bytes)`;
+}
+
+
 
 export class PayloadTooLargeError extends Error {
   public statusCode = 413;
   constructor(actual: number, limit: number) {
-    super(`Request body (${actual} bytes) exceeds TINA4_MAX_UPLOAD_SIZE (${limit} bytes)`);
+    super(bodyTooLargeMessage(actual, limit));
     this.name = "PayloadTooLargeError";
   }
 }
@@ -164,9 +211,11 @@ async function parseBody(req: Tina4Request): Promise<void> {
   if (method === "GET" || method === "HEAD" || method === "OPTIONS") return;
 
   // Check content-length header against upload size limit before reading body
+  const uploadLimit = maxUploadSize();
+
   const declaredLength = parseInt(req.headers["content-length"] ?? "0", 10);
-  if (declaredLength > TINA4_MAX_UPLOAD_SIZE) {
-    throw new PayloadTooLargeError(declaredLength, TINA4_MAX_UPLOAD_SIZE);
+  if (declaredLength > uploadLimit) {
+    throw new PayloadTooLargeError(declaredLength, uploadLimit);
   }
 
   const contentType = req.headers["content-type"] ?? "";
@@ -190,10 +239,10 @@ async function parseBody(req: Tina4Request): Promise<void> {
     req.on("data", (chunk: Buffer) => {
       if (refused) return;
       received += chunk.length;
-      if (received > TINA4_MAX_UPLOAD_SIZE) {
+      if (received > uploadLimit) {
         refused = true;
         chunks.length = 0; // drop what we have; the request is dead
-        reject(new PayloadTooLargeError(received, TINA4_MAX_UPLOAD_SIZE));
+        reject(new PayloadTooLargeError(received, uploadLimit));
         return;
       }
       chunks.push(chunk);