tina4-nodejs 3.13.138 → 3.13.140

package/packages/core/src/api.ts

@@ -29,6 +29,7 @@ import { promises as fsp, createWriteStream } from "node:fs";
 import { basename } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { TINA4_VERSION } from "./version.js";
+import { guardUrl } from "./ssrf.js";
 
 export interface ApiResult {
     http_code: number | null;
@@ -229,6 +230,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[];
 }
 
 /** True when two URLs share scheme + host + (effective) port. */
@@ -430,6 +436,7 @@ export class Api {
     private transportFn?: ApiTransport;
     private cookiesEnabled: boolean;
     private cookies: Record<string, string>;
+    private allowHosts: string[];
 
     /**
      * Construct an Api client.
@@ -476,6 +483,7 @@ export class Api {
         this.transportFn = undefined;
         this.cookiesEnabled = false;
         this.cookies = {};
+        this.allowHosts = [];
 
         // Options-bag form — second arg is an object literal
         if (typeof authHeaderOrOptions === "object" && authHeaderOrOptions !== null) {
@@ -487,6 +495,7 @@ export class Api {
             this.retryBackoff = opts.retryBackoff ?? 0.5;
             this.transportFn = opts.transport;
             this.cookiesEnabled = opts.cookies ?? false;
+            this.allowHosts = opts.allowHosts ?? [];
 
             // Bearer wins over basic-auth when both are passed
             if (opts.bearerToken != null) {
@@ -842,13 +851,19 @@ export class Api {
      * body-phase timeout is applied by the caller (streamBytes) via
      * `res.destroy()`.
      */
-    private openStreamRequest(
+    private async openStreamRequest(
         method: string,
         url: string,
         headers: Record<string, string>,
         data: Buffer | undefined,
         connectSec: number,
     ): Promise<{ res: http.IncomingMessage }> {
+        // SSRF guard (ADR-0084): refuse a private/internal target before connect.
+        try {
+            await guardUrl(url, this.allowHosts);
+        } catch (err) {
+            throw new ApiStreamError(err instanceof Error ? err.message : String(err), null);
+        }
         return new Promise((resolve, reject) => {
             let parsed: URL;
             try {
@@ -915,12 +930,18 @@ export class Api {
         targetUrl?: string,
     ): { headers: Record<string, string>; data: Buffer | undefined } {
         const headers: Record<string, string> = { "User-Agent": `Tina4/${TINA4_VERSION}`, ...this.headers };
-        if (this.authHeader) {
+        // Attach the configured Authorization / Cookie ONLY when the request
+        // target is same-origin as the configured base. A path that is itself
+        // an absolute off-origin URL (e.g. get("http://evil/x")) otherwise
+        // leaks the bearer token / session cookie to an attacker-chosen host —
+        // the same cross-origin strip already applied to followed redirects.
+        const sameOriginAsBase = targetUrl === undefined || sameOrigin(targetUrl, this.baseUrl);
+        if (this.authHeader && sameOriginAsBase) {
             headers["Authorization"] = this.authHeader;
         }
 
         // Cookie jar: attach the accumulated Cookie header when enabled.
-        if (this.cookiesEnabled) {
+        if (this.cookiesEnabled && sameOriginAsBase) {
             const cookieHeader = this.cookieHeader();
             if (cookieHeader) {
                 headers["Cookie"] = cookieHeader;
@@ -1049,13 +1070,21 @@ export class Api {
      * bearer token / session cookie never leaks to a host you didn't
      * authenticate to.
      */
-    private performRequest(
+    private async performRequest(
         method: string,
         url: string,
         headers: Record<string, string>,
         data: Buffer | undefined,
         redirectsLeft: number,
     ): Promise<NetworkResult> {
+        // SSRF guard (ADR-0084): re-validated per hop (this method recurses on a
+        // redirect), so a hop to a private/internal address is refused even when
+        // the initial URL was public.
+        try {
+            await guardUrl(url, this.allowHosts);
+        } catch (err) {
+            return { kind: "error", error: err instanceof Error ? err.message : String(err) };
+        }
         return new Promise<NetworkResult>((resolve) => {
             let parsed: URL;
             try {

package/packages/core/src/auth.ts

@@ -82,6 +82,58 @@ function _warnBlankSecret(): void {
   void _logWarning(BLANK_SECRET_WARNING);
 }
 
+// ── Auth-token rules (ADR-0079) ────────────────────────────────────
+
+/**
+ * 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 const NON_IDENTITY_TOKEN_TYPES: readonly string[] = ["form"];
+
+/**
+ * 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 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 function isIdentityPayload(payload: Record<string, unknown> | null | undefined): payload is Record<string, unknown> {
+  return payload != null && !NON_IDENTITY_TOKEN_TYPES.includes(payload.type as string);
+}
+
+/** The actionable error for a weak HMAC key, or null when the key is usable. */
+export function insecureSecretMessage(secret: string | undefined | null): string | null {
+  const length = Buffer.byteLength(secret ?? "", "utf8");
+  if (length >= MIN_SECRET_BYTES) return null;
+  const what = length === 0 ? "is not set" : `is ${length} bytes`;
+  return `Auth: TINA4_SECRET ${what}; an HMAC JWT secret must be at least ${MIN_SECRET_BYTES} bytes. ` +
+    "Generate one with `openssl rand -hex 32` and set TINA4_SECRET in your environment or .env.";
+}
+
+/**
+ * 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 function requireBootSecret(): void {
+  const algorithm = (process.env.TINA4_JWT_ALGORITHM ?? "").trim() || "HS256";
+  if (RSA_SIGN_ALGORITHMS.has(algorithm)) return;
+  const secret = process.env.TINA4_SECRET ?? "";
+  if (secret === "" && _isDev()) return;
+  const message = insecureSecretMessage(secret);
+  if (message) throw new Error(message);
+}
+
 /**
  * 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()`.
@@ -460,6 +512,14 @@ export function validToken(token: string, secret?: string, algorithm?: string):
     const header = JSON.parse(base64urlDecode(h).toString()) as Record<string, unknown>;
     if (header.alg !== resolvedAlgorithm) return null;
 
+    // A blank or short HMAC key verifies tokens anyone can mint, so the token is
+    // REJECTED (fail closed with a 401, never a 500) and the operator is told
+    // why. ADR-0079 s2.
+    if (HMAC_DIGESTS.has(resolvedAlgorithm)) {
+      const weak = insecureSecretMessage(resolvedSecret);
+      if (weak) { void _logWarning(weak); return null; }
+    }
+
     const signingInput = `${h}.${p}`;
     if (!verifySignature(signingInput, sig, resolvedSecret, resolvedAlgorithm)) {
       return null;
@@ -522,6 +582,8 @@ function sign(input: string, secret: string, algorithm: string): string {
   // the header is the one that actually produced this signature.
   const digest = HMAC_DIGESTS.get(algorithm);
   if (digest) {
+    const weak = insecureSecretMessage(secret);
+    if (weak) throw new Error(weak);
     return base64urlEncode(createHmac(digest, secret).update(input).digest());
   }
   const rsaAlgorithm = RSA_SIGN_ALGORITHMS.get(algorithm);
@@ -622,12 +684,14 @@ export function authMiddleware(secret?: string, algorithm?: string): Middleware
     }
 
     const token = authHeader.slice(7);
-    if (!validToken(token, secret, algorithm)) {
+    const payload = validToken(token, secret, algorithm);
+    // Invalid, expired, or a form token (not an identity, ADR-0079 s1).
+    if (!isIdentityPayload(payload)) {
       res({ error: "Unauthorized" }, 401);
       return;
     }
 
-    (req as any).auth = getPayload(token);
+    (req as any).auth = payload;
     next();
   };
 }
@@ -648,11 +712,12 @@ export function refreshToken(
   token: string,
   expiresIn: number = 60,
 ): string | null {
-  if (!validToken(token)) return null;
-
-  const payload = getPayload(token);
+  const payload = validToken(token);
   if (!payload) return null;
 
+  // Refresh preserves PURPOSE: a form token comes back as a form token (CSRF
+  // rotation) and so can still never pass an identity gate. The route gate
+  // issues a FreshToken only for an identity token. ADR-0079 s1.
   // Strip standard timing claims so getToken sets fresh ones
   const { iat: _iat, exp: _exp, ...claims } = payload;
   return getToken(claims, expiresIn);
@@ -686,7 +751,9 @@ export function authenticateRequest(
   // algorithm= silently got the env values instead, and `algorithm` defaulted to
   // the literal "HS256" which additionally shadowed TINA4_JWT_ALGORITHM. Python,
   // PHP and Ruby all honour these; Node was the last one that did not.
-  if (validToken(token, secret, algorithm)) return getPayload(token);
+  const payload = validToken(token, secret, algorithm);
+  // A form token is not an identity (ADR-0079 s1).
+  if (payload) return isIdentityPayload(payload) ? payload : null;
 
   // Fallback: treat Bearer value as API key
   if (validateApiKey(token)) {

package/packages/core/src/authGate.ts

@@ -17,7 +17,8 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/.
  * verification layer lied. This is the same defect fixed in tina4-python under
  * #PY2; extracting the gate here lets both callers share one implementation.
  */
-import { validToken, getPayload, refreshToken } from "./auth.js";
+import { validToken, refreshToken, isIdentityPayload } from "./auth.js";
+import { liveSessionIdentity } from "./ssoIdentity.js";
 import type { Tina4Request, Tina4Response } from "./types.js";
 
 /** Just the auth-relevant fields of a matched route. */
@@ -52,52 +53,58 @@ export function enforceRouteAuth(
     return false;
   }
 
+  // Token slots in priority order: Bearer header, body formToken (frond.js
+  // puts the auth token it received as a FreshToken there), session token.
+  // Each slot is accepted only when it carries an IDENTITY token: a Frond
+  // form token (`type: "form"`) proves where a write came from, not who sent
+  // it, so it is skipped and the search moves on (ADR-0079 s1).
   const authHeader = req.headers.authorization ?? "";
   const headerToken = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
 
-  let resolvedToken = "";
+  let payload: Record<string, unknown> | null = null;
   let tokenSource: "header" | "body" | "session" | "" = "";
+  let resolvedToken = "";
 
   // Priority 1: Authorization Bearer header
-  if (headerToken && validToken(headerToken)) {
-    resolvedToken = headerToken;
-    tokenSource = "header";
+  if (headerToken) {
+    const candidate = validToken(headerToken);
+    if (isIdentityPayload(candidate)) { payload = candidate; tokenSource = "header"; resolvedToken = headerToken; }
   }
 
   // Priority 2: formToken from request body
-  if (!resolvedToken) {
+  if (!payload) {
     const bodyToken = (req.body as Record<string, unknown>)?.formToken as string | undefined;
-    if (bodyToken && validToken(bodyToken)) {
-      resolvedToken = bodyToken;
-      tokenSource = "body";
+    if (bodyToken) {
+      const candidate = validToken(bodyToken);
+      if (isIdentityPayload(candidate)) { payload = candidate; tokenSource = "body"; resolvedToken = bodyToken; }
     }
   }
 
-  // Priority 3: Session token
-  if (!resolvedToken) {
-    const sso = (req as any).session?.get?.("_tina4_sso") as Record<string, any> | undefined;
-    const identity = sso?.identity;
-    if (identity?.issuer && identity?.subject) {
+  // Priority 3: Session — a provider-verified SSO identity while it is live
+  // (ADR-0079 s5), then the session token.
+  if (!payload) {
+    const identity = liveSessionIdentity((req as any).session?.get?.("_tina4_sso"));
+    if (identity) {
       req.user = identity;
       // RBAC guards apply to the SSO identity too (Feature 138).
       return rbacForbidden(match, identity, res);
     }
     const sessionToken = (req as any).session?.get?.("token") as string | undefined;
-    if (sessionToken && validToken(sessionToken)) {
-      resolvedToken = sessionToken;
-      tokenSource = "session";
+    if (sessionToken) {
+      const candidate = validToken(sessionToken);
+      if (isIdentityPayload(candidate)) { payload = candidate; tokenSource = "session"; resolvedToken = sessionToken; }
     }
   }
 
-  if (!resolvedToken) {
+  if (!payload) {
     res.raw.writeHead(401, { "Content-Type": "application/json" });
     res.raw.end(JSON.stringify({ error: "Unauthorized" }));
     return true;
   }
 
-  req.user = getPayload(resolvedToken) ?? {};
+  req.user = payload;
 
-  // When a body formToken validates, return a FreshToken header with a refreshed JWT
+  // When a body token authenticates, return a FreshToken header with a refreshed JWT
   if (tokenSource === "body") {
     const fresh = refreshToken(resolvedToken);
     if (fresh) {

package/packages/core/src/graphql.ts

@@ -175,10 +175,17 @@ type ParsedDefinition = ParsedOperation | ParsedFragment;
 class Parser {
   private tokens: Token[];
   private pos: number;
+  // F2: bound the parser's own recursion. A deeply nested query
+  // ("{a{a{a...}}}") otherwise recurses in parseSelectionSet until the call
+  // stack overflows — BEFORE the execution-time depth guard can run. Reusing
+  // TINA4_GRAPHQL_MAX_DEPTH keeps parse and execution on one bound.
+  private depth = 0;
+  private readonly maxDepth: number;
 
   constructor(tokens: Token[]) {
     this.tokens = tokens;
     this.pos = 0;
+    this.maxDepth = graphqlMaxDepth();
   }
 
   peek(): Token | null {
@@ -272,6 +279,18 @@ class Parser {
   }
 
   private parseSelectionSet(): ParsedSelection[] {
+    this.depth++;
+    if (this.maxDepth > 0 && this.depth > this.maxDepth) {
+      throw new Error(`Query exceeds maximum depth of ${this.maxDepth}`);
+    }
+    try {
+      return this.parseSelectionSetInner();
+    } finally {
+      this.depth--;
+    }
+  }
+
+  private parseSelectionSetInner(): ParsedSelection[] {
     this.expect("LBRACE");
     const selections: ParsedSelection[] = [];
     while (!this.match("RBRACE")) {
@@ -488,6 +507,24 @@ export function graphqlMaxDepth(): number {
   return Number.isNaN(n) ? 50 : n;
 }
 
+/**
+ * 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 function graphqlMaxNodes(): number {
+  const raw = (process.env.TINA4_GRAPHQL_MAX_NODES ?? "1000").trim();
+  const n = parseInt(raw, 10);
+  return Number.isNaN(n) ? 1000 : n;
+}
+
+/** Thrown when a query's expanded selection count exceeds the node budget (F2). */
+class ComplexityError extends Error {}
+
 // ── GraphQL Engine ───────────────────────────────────────────
 
 export class GraphQL {
@@ -515,6 +552,13 @@ export class GraphQL {
    */
   public maxDepth: number = graphqlMaxDepth();
 
+  /**
+   * 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}.
+   */
+  public maxNodes: number = graphqlMaxNodes();
+
   /**
    * Decorator-style resolver registration.
    *
@@ -692,6 +736,20 @@ export class GraphQL {
     }
 
     const op = operations[0];
+
+    // F2: reject an over-complex query (fragment bomb / alias explosion) before
+    // any resolver runs.
+    if (this.maxNodes > 0) {
+      try {
+        this.assertComplexity(op.selections, fragments);
+      } catch (e: unknown) {
+        if (e instanceof ComplexityError) {
+          return { data: null, errors: [{ message: e.message }] };
+        }
+        throw e;
+      }
+    }
+
     const resolvers = op.operation === "query" ? this.queries : this.mutations;
 
     // Apply variable defaults
@@ -723,6 +781,40 @@ export 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(
+    selections: ParsedSelection[],
+    fragments: Map<string, ParsedFragment>,
+  ): void {
+    const depthCap = this.maxDepth > 0 ? this.maxDepth : 1000;
+    let count = 0;
+    const walk = (sels: ParsedSelection[], depth: number): void => {
+      if (depth > depthCap) return;
+      for (const sel of sels) {
+        count++;
+        if (count > this.maxNodes) {
+          throw new ComplexityError(`Query exceeds maximum complexity of ${this.maxNodes} nodes`);
+        }
+        if (sel.kind === "fragment_spread") {
+          const frag = fragments.get(sel.name);
+          if (frag) walk(frag.selections, depth + 1);
+        } else if (sel.kind === "inline_fragment") {
+          walk(sel.selections, depth + 1);
+        } else if (sel.kind === "field" && sel.selections) {
+          walk(sel.selections, depth + 1);
+        }
+      }
+    };
+    walk(selections, 1);
+  }
+
   private async resolveSelectionsInto(
     selections: ParsedSelection[],
     resolvers: Map<string, QueryConfig>,

package/packages/core/src/index.ts

@@ -90,6 +90,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/packages/core/src/job.ts

@@ -47,6 +47,7 @@ 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;
@@ -74,7 +75,13 @@ export function createJob(data: JobData, queue: JobQueueBridge): QueueJob {
       queue._failJob(job.topic, job, reason, queue.getMaxRetries());
     },
     reject(reason = "") {
-      job.fail(reason);
+      // Reject permanently — dead-letter NOW, no retry (ADR-0023). Distinct
+      // from fail(): fail() retries until maxRetries is spent; reject() is for
+      // a message the consumer KNOWS is poison and sends it straight to the
+      // dead-letter store. Was a literal alias for fail() before 3.13.139.
+      job.status = "dead";
+      job.error = reason;
+      queue._rejectJob(job.topic, job, reason, queue.getMaxRetries());
     },
     retry(delaySeconds?: number) {
       queue._retryJob(job.topic, job, delaySeconds);

package/packages/core/src/mcp.ts

@@ -238,7 +238,9 @@ function envTruthy(val: string | undefined): boolean {
  * Python master parity: tina4_python.mcp.is_loopback.
  */
 export function isLoopback(ip: string | undefined | null): boolean {
-  if (ip == null || ip === "") return true;
+  // An empty or missing peer is UNKNOWN and is not loopback: a runtime path
+  // that lost its socket address must fail closed (ADR-0079 s4).
+  if (ip == null || ip === "") return false;
   let addr = ip.trim().toLowerCase();
   if (addr.startsWith("::ffff:")) addr = addr.slice(7);
   return addr === "::1" || addr === "localhost" || addr.startsWith("127.");

package/packages/core/src/middleware.ts

@@ -8,7 +8,7 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 import type { Tina4Request, Tina4Response, Middleware } from "./types.js";
 import { HTTP_OK, HTTP_FORBIDDEN } from "./constants.js";
-import { validToken, getPayload } from "./auth.js";
+import { validToken, getPayload, isIdentityPayload } from "./auth.js";
 import { Log } from "./logger.js";
 import { isTruthy } from "./dotenv.js";
 import { defaultRouter, type Router } from "./router.js";
@@ -1060,7 +1060,9 @@ function csrfBearerIsValid(req: Tina4Request, secret: string): boolean {
   const authHeader = req.headers.authorization ?? "";
   if (!authHeader.startsWith("Bearer ")) return false;
   const bearerToken = authHeader.slice(7).trim();
-  return Boolean(bearerToken && validToken(bearerToken, secret));
+  // Only an IDENTITY token marks an API client; a form token in the Bearer
+  // slot is not one and does not skip the check (ADR-0079 s1).
+  return Boolean(bearerToken && isIdentityPayload(validToken(bearerToken, secret)));
 }
 
 function csrfRequestToken(req: Tina4Request): { token: string; fromQuery: boolean } {

package/packages/core/src/push.ts

@@ -21,6 +21,7 @@ import {
   createSign,
   randomBytes,
 } from "node:crypto";
+import { guardUrl, SsrfError } from "./ssrf.js";
 
 const CURVE = "prime256v1";
 const RECORD_SIZE = 4096;
@@ -40,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 {
@@ -267,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

@@ -127,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.
@@ -152,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
@@ -432,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);
   }
@@ -758,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/liteBackend.ts

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