tina4-nodejs 3.13.91 → 3.13.94

package/packages/core/src/auth.ts

@@ -127,6 +127,72 @@ export function ensureDevSecret(cwd?: string): string | null {
   return newSecret;
 }
 
+// ── JWT algorithms ────────────────────────────────────────────────
+//
+// Mirrors the Python master (tina4_python/auth/__init__.py) — the digest is
+// LOOKED UP from the configured algorithm rather than hardcoded, so the "alg"
+// advertised in the header is always the one that actually produced the
+// signature (python#105). TINA4_JWT_ALGORITHM is read for real, and an
+// algorithm we cannot sign fails loudly instead of silently downgrading to
+// HS256 (python#106).
+
+/** HMAC algorithms → their node:crypto digest name. All in node:crypto — zero dependencies. */
+const HMAC_DIGESTS = new Map<string, string>([
+  ["HS256", "sha256"],
+  ["HS384", "sha384"],
+  ["HS512", "sha512"],
+]);
+
+/**
+ * RSA algorithms → their node:crypto sign/verify algorithm name.
+ *
+ * Node ships `node:crypto`, so RS256 is legitimately available here at zero
+ * dependency cost. Python and Ruby cannot do RS256 without a third-party
+ * package, so RS256 is a documented PHP/Node-only EXTRA, not a parity
+ * requirement — the HMAC family is the cross-framework contract.
+ */
+const RSA_SIGN_ALGORITHMS = new Map<string, string>([["RS256", "RSA-SHA256"]]);
+
+/** Every algorithm Tina4 for Node can sign and verify, in the order we advertise them. */
+const SUPPORTED_ALGORITHMS: readonly string[] = [
+  ...HMAC_DIGESTS.keys(),
+  ...RSA_SIGN_ALGORITHMS.keys(),
+];
+
+/**
+ * Seconds of clock skew tolerated on the "nbf" (not-before) claim.
+ *
+ * Without this, a token minted on one host and validated on another a second
+ * behind is rejected for no real reason; RFC 7519 explicitly allows "a small
+ * leeway". Same value as the Python master's `_JWT_LEEWAY_SECONDS`.
+ */
+export const JWT_LEEWAY_SECONDS = 60;
+
+/** The loud, actionable failure for an algorithm we cannot sign — names the supported set. */
+function unsupportedAlgorithmError(algorithm: string): Error {
+  return new Error(
+    `Unsupported JWT algorithm "${algorithm}". Tina4 signs with ` +
+      `${SUPPORTED_ALGORITHMS.join(", ")} (HMAC via node:crypto; RS256 needs a PEM key pair). ` +
+      `Set TINA4_JWT_ALGORITHM to one of those.`,
+  );
+}
+
+/**
+ * Pick the JWT algorithm: explicit argument, else TINA4_JWT_ALGORITHM, else HS256.
+ *
+ * Throws (naming the supported set and the env var) when asked for an algorithm
+ * we cannot sign — a silent downgrade to HS256 is the whole bug in python#106.
+ *
+ * @param algorithm - Explicit algorithm; wins over the environment when given.
+ */
+export function resolveAlgorithm(algorithm?: string): string {
+  const chosen = (algorithm || process.env.TINA4_JWT_ALGORITHM || "HS256").trim();
+  if (!HMAC_DIGESTS.has(chosen) && !RSA_SIGN_ALGORITHMS.has(chosen)) {
+    throw unsupportedAlgorithmError(chosen);
+  }
+  return chosen;
+}
+
 // ── Base64url helpers (RFC 7515) ──────────────────────────────────
 
 function base64urlEncode(data: Buffer): string {
@@ -146,12 +212,20 @@ function base64urlDecode(str: string): Buffer {
  * Create a signed JWT token.
  *
  * Secret is always read from `process.env.TINA4_SECRET`.
- * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256").
+ * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256");
+ * HS256 / HS384 / HS512 / RS256 are supported and anything else throws.
+ *
+ * The header's `alg` is always the algorithm that actually signed the token.
+ *
+ * No `nbf` (not-before) claim is stamped — parity with Python and PHP. Pass your
+ * own `nbf` in the payload to post-date a token; `validToken` enforces it.
  *
  * @param payload          - Claims to encode (e.g. `{ userId: 1, role: "admin" }`)
  * @param secretOrExpiresIn - Signing secret string, OR expiresIn number in MINUTES (back-compat with old 2-arg form)
  * @param expiresIn         - Lifetime in MINUTES (default 60). `0` ⇒ no `exp` claim (non-expiring). Only used when secret is a string.
+ * @param algorithm         - Overrides TINA4_JWT_ALGORITHM for this call.
  * @returns Signed JWT string: header.payload.signature
+ * @throws When the resolved algorithm is not one Tina4 can sign.
  */
 export function getToken(
   payload: Record<string, unknown>,
@@ -173,7 +247,8 @@ export function getToken(
   if (!resolvedSecret) {
     _warnBlankSecret();
   }
-  const resolvedAlgorithm = algorithm ?? process.env.TINA4_JWT_ALGORITHM ?? "HS256";
+  // Throws on an algorithm we cannot sign — never silently downgrades to HS256.
+  const resolvedAlgorithm = resolveAlgorithm(algorithm);
 
   const header = { alg: resolvedAlgorithm, typ: "JWT" };
   const now = Math.floor(Date.now() / 1000);
@@ -204,30 +279,62 @@ export function getToken(
  *
  * Secret is read from `process.env.TINA4_SECRET` when not passed explicitly.
  * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256").
+ *
+ * Checks, in order: the header's `alg` must BE the expected algorithm (blocks alg
+ * substitution, including `alg: "none"`, before any signature work), then the
+ * signature, then `exp`, then `nbf` (with `JWT_LEEWAY_SECONDS` of clock skew).
  */
 export function validToken(token: string, secret?: string, algorithm?: string): Record<string, unknown> | null {
   const resolvedSecret = secret ?? process.env.TINA4_SECRET ?? "";
   if (!resolvedSecret) {
     _warnBlankSecret();
   }
-  const resolvedAlgorithm = algorithm ?? process.env.TINA4_JWT_ALGORITHM ?? "HS256";
+  // Resolved OUTSIDE the try so a bad TINA4_JWT_ALGORITHM throws rather than
+  // being swallowed into a null. A misconfigured algorithm is a deployment
+  // error, not a bad token: swallowing it turns one actionable message into a
+  // silent 401 on every request, which is far harder to diagnose. It also could
+  // not hide the fault anyway - getToken() already throws on the same value, so
+  // a typo surfaces at login regardless; swallowing here only made the two paths
+  // disagree. Python (master, raises in the constructor) and PHP both throw.
+  const resolvedAlgorithm = resolveAlgorithm(algorithm);
+
   try {
     const parts = token.split(".");
     if (parts.length !== 3) return null;
 
     const [h, p, sig] = parts;
-    const signingInput = `${h}.${p}`;
 
+    // Pin the algorithm to OUR configured one instead of trusting the token's
+    // header. A token asking to be verified as anything else — "none", a weaker
+    // HMAC, or an RSA alg when we sign HMAC — is rejected BEFORE any signature
+    // work, which is what blocks alg substitution. Matches the Python master.
+    const header = JSON.parse(base64urlDecode(h).toString()) as Record<string, unknown>;
+    if (header.alg !== resolvedAlgorithm) return null;
+
+    const signingInput = `${h}.${p}`;
     if (!verifySignature(signingInput, sig, resolvedSecret, resolvedAlgorithm)) {
       return null;
     }
 
     const payload = JSON.parse(base64urlDecode(p).toString()) as Record<string, unknown>;
 
-    if (typeof payload.exp === "number" && Date.now() / 1000 > payload.exp) {
+    const now = Date.now() / 1000;
+    if (typeof payload.exp === "number" && now > payload.exp) {
       return null;
     }
 
+    // "nbf" (not-before): a post-dated token is not valid YET. Was honoured only
+    // by Ruby, so Python/PHP/Node accepted tokens their issuer had explicitly
+    // marked as not-yet-usable (nodejs#39 / python#107). A token with no nbf is
+    // unaffected — that is what keeps this non-breaking. A PRESENT but
+    // non-numeric nbf is rejected (Python raises a TypeError there and returns
+    // None; a malformed not-before must never read as "no constraint").
+    if (Object.hasOwn(payload, "nbf")) {
+      const notBefore = payload.nbf;
+      if (typeof notBefore !== "number" || !Number.isFinite(notBefore)) return null;
+      if (now + JWT_LEEWAY_SECONDS < notBefore) return null;
+    }
+
     return payload;
   } catch {
     return null;
@@ -250,21 +357,23 @@ export function getPayload(token: string): Record<string, unknown> | null {
 // ── Signing helpers ───────────────────────────────────────────────
 
 function sign(input: string, secret: string, algorithm: string): string {
-  if (algorithm === "HS256") {
-    const sig = createHmac("sha256", secret).update(input).digest();
-    return base64urlEncode(sig);
+  // The digest comes from the configured algorithm, so the "alg" we advertise in
+  // the header is the one that actually produced this signature.
+  const digest = HMAC_DIGESTS.get(algorithm);
+  if (digest) {
+    return base64urlEncode(createHmac(digest, secret).update(input).digest());
   }
-  if (algorithm === "RS256") {
-    const signer = createSign("RSA-SHA256");
+  const rsaAlgorithm = RSA_SIGN_ALGORITHMS.get(algorithm);
+  if (rsaAlgorithm) {
+    const signer = createSign(rsaAlgorithm);
     signer.update(input);
-    const sig = signer.sign(secret);
-    return base64urlEncode(sig);
+    return base64urlEncode(signer.sign(secret));
   }
-  throw new Error(`Unsupported algorithm: ${algorithm}`);
+  throw unsupportedAlgorithmError(algorithm);
 }
 
 function verifySignature(input: string, sig: string, secret: string, algorithm: string): boolean {
-  if (algorithm === "HS256") {
+  if (HMAC_DIGESTS.has(algorithm)) {
     const expected = sign(input, secret, algorithm);
     // Constant-time comparison
     const a = Buffer.from(sig);
@@ -272,12 +381,13 @@ function verifySignature(input: string, sig: string, secret: string, algorithm:
     if (a.length !== b.length) return false;
     return timingSafeEqual(a, b);
   }
-  if (algorithm === "RS256") {
-    const verifier = createVerify("RSA-SHA256");
+  const rsaAlgorithm = RSA_SIGN_ALGORITHMS.get(algorithm);
+  if (rsaAlgorithm) {
+    const verifier = createVerify(rsaAlgorithm);
     verifier.update(input);
     return verifier.verify(secret, base64urlDecode(sig));
   }
-  throw new Error(`Unsupported algorithm: ${algorithm}`);
+  throw unsupportedAlgorithmError(algorithm);
 }
 
 // ── Password Hashing (PBKDF2) ────────────────────────────────────
@@ -334,8 +444,14 @@ export function checkPassword(password: string, hash: string): boolean {
  * Auth middleware that extracts and verifies a Bearer JWT from the
  * Authorization header. On success, attaches the decoded payload to
  * `(request as any).auth`. On failure, sends a 401 JSON response.
+ *
+ * @param secret    - Signing secret / PEM public key (default: TINA4_SECRET env var).
+ * @param algorithm - JWT algorithm. Omit it to honour TINA4_JWT_ALGORITHM (then
+ *   HS256). It used to default to the literal "HS256", which SHADOWED the env
+ *   var: an app on TINA4_JWT_ALGORITHM=HS512 minted HS512 tokens and this
+ *   middleware verified them as HS256, rejecting every valid token.
  */
-export function authMiddleware(secret?: string, algorithm: string = "HS256"): Middleware {
+export function authMiddleware(secret?: string, algorithm?: string): Middleware {
   return (req: Tina4Request, res: Tina4Response, next: () => void): void => {
     const authHeader = req.headers.authorization ?? "";
 
@@ -394,7 +510,7 @@ export function refreshToken(
 export function authenticateRequest(
   headers: Record<string, string | string[] | undefined>,
   secret?: string,
-  algorithm: string = "HS256",
+  algorithm?: string,
 ): Record<string, unknown> | null {
   const authHeader =
     (headers.authorization ?? headers.Authorization ?? "") as string;
@@ -403,8 +519,12 @@ export function authenticateRequest(
 
   const token = authHeader.slice(7);
 
-  // Try JWT first (secret/algorithm params kept for backward compat but validToken reads from env)
-  if (validToken(token)) return getPayload(token);
+  // Both overrides are FORWARDED. They used to be accepted and dropped - the
+  // body called bare validToken(token), so a caller passing secret= or
+  // 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);
 
   // Fallback: treat Bearer value as API key
   if (validateApiKey(token)) {

package/packages/core/src/devMailbox.ts

@@ -15,8 +15,6 @@ import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 
 import type { SendResult, EmailMessage } from "./messenger.js";
-import { Messenger } from "./messenger.js";
-import { isTruthy } from "./dotenv.js";
 
 // ── DevMailbox ───────────────────────────────────────────────
 
@@ -38,20 +36,35 @@ export class DevMailbox {
 
   /**
    * Capture an email to the dev mailbox instead of sending it.
+   *
+   * The parameter order MATCHES Messenger.send() on purpose. It did not before:
+   * send()'s 5th positional was `text` and capture()'s was `cc`, so the same call
+   * meant different things depending on which door it came through -- that mismatch
+   * IS nodejs#42.
+   *
+   * BREAKING: `text` is now the 5th positional. A caller passing cc positionally
+   * must move it. Aligning the two signatures is the fix; leaving them apart would
+   * preserve the bug.
    */
   capture(
     to: string | string[],
     subject: string,
     body: string,
     html: boolean = false,
-    cc: string[] = [],
-    bcc: string[] = [],
+    text?: string,
+    cc: string | string[] = [],
+    bcc: string | string[] = [],
     replyTo?: string,
     attachments: string[] = [],
     from?: string,
   ): SendResult {
     const id = randomUUID();
     const toList = Array.isArray(to) ? to : [to];
+    // Normalised HERE, at the boundary, so a message is well formed however it
+    // arrived. A dev mailbox that stores a malformed message and reports success
+    // defeats its own purpose -- it exists to show you what you WOULD have sent.
+    const ccList = Array.isArray(cc) ? cc : (cc ? [cc] : []);
+    const bccList = Array.isArray(bcc) ? bcc : (bcc ? [bcc] : []);
     const now = new Date().toISOString();
 
     const message: EmailMessage = {
@@ -59,11 +72,12 @@ export class DevMailbox {
       type: "outbox",
       from: from ?? process.env.TINA4_MAIL_FROM ?? "dev@localhost",
       to: toList,
-      cc,
-      bcc,
+      cc: ccList,
+      bcc: bccList,
       reply_to: replyTo,
       subject,
       body,
+      text,
       html,
       attachments,
       date: now,
@@ -280,41 +294,3 @@ export class DevMailbox {
 }
 
 // ── Factory ──────────────────────────────────────────────────
-
-/**
- * Create a Messenger or DevMailbox based on the environment.
- *
- * Returns DevMailbox when:
- *   - TINA4_DEBUG is "true", OR
- *   - No TINA4_MAIL_HOST is configured
- *
- * Returns a real Messenger otherwise (SMTP configured + not debug mode).
- *
- * This follows the factory pattern from PHP's MessengerFactory.
- */
-export function createMessenger(): Messenger | DevMailbox {
-  const debug = process.env.TINA4_DEBUG;
-  const smtpHost = process.env.TINA4_MAIL_HOST;
-
-  // Production = NOT debug mode AND NODE_ENV is "production".
-  // Derived here (was previously referenced undefined → ReferenceError).
-  const isProd = !isTruthy(debug) && process.env.NODE_ENV === "production";
-
-  // Force dev mode when TINA4_DEBUG is truthy
-  if (isTruthy(debug)) {
-    return new DevMailbox();
-  }
-
-  // No SMTP configured — must use dev mailbox
-  if (!smtpHost) {
-    return new DevMailbox();
-  }
-
-  // Non-production environment — use dev mailbox
-  if (!isProd) {
-    return new DevMailbox();
-  }
-
-  // Production with SMTP configured — use real Messenger
-  return new Messenger();
-}

package/packages/core/src/index.ts

@@ -94,9 +94,9 @@ export {
   handleFeedbackWidgetJs,
   registerFeedbackRoutes,
 } from "./feedback.js";
-export { Messenger, MessengerConnectionError } from "./messenger.js";
+export { Messenger, MessengerConnectionError, createMessenger } from "./messenger.js";
 export type { SendResult, EmailMessage } from "./messenger.js";
-export { DevMailbox, createMessenger } from "./devMailbox.js";
+export { DevMailbox } from "./devMailbox.js";
 export { WSDLService, WSDLOperation } from "./wsdl.js";
 export type { WSDLOperationMeta } from "./wsdl.js";
 export { HtmlElement, htmlElement, addHtmlHelpers, Raw, SafeString } from "./htmlElement.js";

package/packages/core/src/messenger.ts

@@ -29,6 +29,7 @@ import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { randomUUID } from "node:crypto";
 import { isTruthy } from "./dotenv.js";
+import { DevMailbox } from "./devMailbox.js";
 import { Log } from "./logger.js";
 
 /**
@@ -77,6 +78,10 @@ export interface EmailMessage {
   reply_to?: string;
   subject: string;
   body: string;
+  /** Plain-text alternative. Carried on the dev path too, so the captured message
+   *  is the message: a mailbox that shows you something other than what you wrote
+   *  is worse than no mailbox. */
+  text?: string;
   html: boolean;
   attachments: string[];
   date: string;
@@ -328,6 +333,10 @@ export class Messenger {
   private fromName: string;
   private encryption: string;
   private useTls: boolean;
+  /** Whether an SMTP host was actually configured (see the constructor). */
+  private smtpConfigured: boolean = false;
+  /** The local mailbox, present only when this messenger captures. */
+  public devMailbox: DevMailbox | null = null;
   private imapHost: string;
   private imapPort: number;
   private imapUser: string;
@@ -337,6 +346,11 @@ export class Messenger {
   constructor(options?: MessengerOptions) {
     // Priority: constructor > TINA4_MAIL_* > sensible default.
     // Legacy SMTP_*/IMAP_* env vars were removed in v3.12 — boot guard rejects them.
+    // Whether a host was actually CONFIGURED, which is not the same as this.host
+    // being set: it falls back to "localhost", so it is never empty and cannot
+    // answer "can this messenger send?". The capture gate needs that answer, so
+    // record it here while the real inputs are still in scope.
+    this.smtpConfigured = Boolean(options?.host ?? process.env.TINA4_MAIL_HOST);
     this.host = options?.host
       ?? process.env.TINA4_MAIL_HOST
       ?? "localhost";
@@ -399,6 +413,31 @@ export class Messenger {
   /**
    * Send an email via SMTP.
    */
+  /**
+   * Should send() capture locally instead of talking to SMTP?
+   *
+   * Availability decides, not verbosity. With no SMTP host configured sending is
+   * impossible, so simulate it into a folder rather than failing -- that is what
+   * makes a laptop with no mail server usable. TINA4_MAIL_CAPTURE forces capture
+   * even when a host IS configured.
+   *
+   * TINA4_DEBUG deliberately does NOT gate this, and neither does NODE_ENV. Debug
+   * must still be able to send, and the old `NODE_ENV !== "production"` clause
+   * silently swallowed every staging email.
+   */
+  private shouldCapture(): boolean {
+    if (isTruthy(process.env.TINA4_MAIL_CAPTURE)) return true;
+    return !this.smtpConfigured;
+  }
+
+  /** The local mailbox, created on first capture and reused after. */
+  private getDevMailbox(): DevMailbox {
+    if (this.devMailbox === null) {
+      this.devMailbox = new DevMailbox();
+    }
+    return this.devMailbox;
+  }
+
   async send(
     to: string | string[],
     subject: string,
@@ -416,6 +455,17 @@ export class Messenger {
     const ccList = Array.isArray(options.cc) ? options.cc : (options.cc ? [options.cc] : []);
     const bccList = Array.isArray(options.bcc) ? options.bcc : (options.bcc ? [options.bcc] : []);
     const allRecipients = [...toList, ...ccList, ...bccList];
+
+    // Dev capture is a BRANCH here, not a different object returned by the factory.
+    // createMessenger() used to hand back a DevMailbox, which has capture() and no
+    // send(), so the documented call threw TypeError (nodejs#41).
+    if (this.shouldCapture()) {
+      return this.getDevMailbox().capture(
+        to, subject, body, html, text, ccList, bccList, replyTo,
+        attachments, this.fromAddress || undefined,
+      );
+    }
+
     const messageId = `${randomUUID()}@${this.host}`;
 
     if (allRecipients.length === 0) {
@@ -1069,3 +1119,25 @@ function parseFullMessage(uid: string, response: string): ImapFullMessage {
     headers,
   };
 }
+
+/**
+ * Create a Messenger configured for the current environment.
+ *
+ * Returns ONE concrete type, always. It used to return `Messenger | DevMailbox`,
+ * and those two shared NO sending method -- DevMailbox has capture(), Messenger has
+ * send() -- so the documented call threw TypeError whenever the dev branch was
+ * taken. That is nodejs#41. Capture is now a branch inside Messenger.send(), so the
+ * object you get back has one send() with one signature either way.
+ *
+ * The gate is availability, not verbosity:
+ *   - no TINA4_MAIL_HOST -> capture (sending is impossible, so simulate it)
+ *   - TINA4_MAIL_CAPTURE truthy -> capture even with SMTP configured
+ *   - otherwise -> send, EVEN WITH TINA4_DEBUG ON
+ *
+ * TINA4_DEBUG no longer forces capture: debug must still be able to send real mail.
+ * The `NODE_ENV !== "production"` clause is also gone -- it captured even with SMTP
+ * configured and debug off, which silently ate every staging email.
+ */
+export function createMessenger(): Messenger {
+  return new Messenger();
+}

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

@@ -497,12 +497,15 @@ export class KafkaBackend implements QueueBackend {
             if (errCode === 0) {
               finish("__PUBLISHED__", 0);
             } else {
+              // Report the CODE, not just "it failed" — the caller decides
+              // whether it is retriable (3/5, the async topic-creation race)
+              // or fatal (e.g. 29 TOPIC_AUTHORIZATION_FAILED).
               process.stderr.write("Produce error code " + errCode);
-              finish("__ERROR__" + errCode, 0);
+              finish("__PRODUCEERROR__" + errCode, 0);
             }
           } catch (e) {
             process.stderr.write("produce parse: " + e.message);
-            finish("__ERROR__", 0);
+            finish("__PARSEERROR__produce: " + e.message, 0);
           }
           return;
         } else if (operation === "get") {
@@ -516,6 +519,7 @@ export class KafkaBackend implements QueueBackend {
             pos += 4;                                   // throttleTimeMs (v1+)
             const topicCount = buffer.readInt32BE(pos); pos += 4;
             let out = "__EMPTY__";
+            let fatalCode = 0;
             for (let t = 0; t < topicCount; t++) {
               const tl = buffer.readInt16BE(pos); pos += 2 + tl;
               const pc = buffer.readInt32BE(pos); pos += 4;
@@ -527,6 +531,14 @@ export class KafkaBackend implements QueueBackend {
                 const abortedCount = buffer.readInt32BE(pos); pos += 4;
                 if (abortedCount > 0) pos += abortedCount * 16; // (-1 => none, skip)
                 const recSetSize = buffer.readInt32BE(pos); pos += 4;
+                // 3 = UNKNOWN_TOPIC_OR_PARTITION, 5 = LEADER_NOT_AVAILABLE:
+                // "nothing to read here yet", which a consumer that starts
+                // before its producer hits on every cold start. Any OTHER code
+                // (29 TOPIC_AUTHORIZATION_FAILED, 13 STALE_CONTROLLER_EPOCH, …)
+                // is a real failure and must NOT be reported as an empty queue.
+                if (errCode !== 0 && errCode !== 3 && errCode !== 5) {
+                  fatalCode = errCode;
+                }
                 if (errCode === 0 && recSetSize > 0) {
                   const val = firstRecordValue(buffer, pos, pos + recSetSize);
                   if (val !== null) out = val;
@@ -534,21 +546,33 @@ export class KafkaBackend implements QueueBackend {
                 pos += recSetSize > 0 ? recSetSize : 0;
               }
             }
+            if (fatalCode !== 0) {
+              process.stderr.write("Fetch error code " + fatalCode);
+              finish("__FETCHERROR__" + fatalCode, 0);
+              return;
+            }
             finish(out, 0);
           } catch (e) {
+            // A parse failure is NOT an empty queue either — say so.
             process.stderr.write("fetch parse: " + e.message);
-            finish("__EMPTY__", 0);
+            finish("__PARSEERROR__fetch: " + e.message, 0);
           }
           return;
         }
       });
 
+      // Report the reason on STDOUT and exit 0. Writing it to stderr and
+      // exiting non-zero LOST it: stderr to a pipe is an async write and
+      // process.exit() truncates it, so the parent saw an empty stderr and fell
+      // back to execFileSync's message -- which embeds this entire script.
+      // stdout is flushed by finish()'s write callback, so it survives.
       sock.on("error", (err) => {
-        process.stderr.write(err.message);
-        finish("", 1);
+        finish("__TRANSPORTERROR__" + err.message, 0);
       });
 
-      var timer = setTimeout(() => { finish("", 1); }, 10000);
+      var timer = setTimeout(() => {
+        finish("__TRANSPORTERROR__timed out after 10s talking to " + host + ":" + port, 0);
+      }, 10000);
     `;
 
     try {
@@ -558,8 +582,59 @@ export class KafkaBackend implements QueueBackend {
         stdio: ["pipe", "pipe", "pipe"],
       });
       return result;
-    } catch {
-      return "";
+    } catch (err) {
+      // Reached only when the child itself could not run (spawn failure, killed,
+      // the outer 15s timeout). The socket-level reasons come back through
+      // stdout as __TRANSPORTERROR__ instead. Swallowing this to "" made every
+      // failure indistinguishable from an empty queue.
+      //
+      // execFileSync's own message embeds the ENTIRE generated script, so it is
+      // truncated here -- a 20KB error that buries the cause is barely better
+      // than no error at all.
+      const e = err as { stderr?: Buffer | string; message?: string };
+      const reason = String(e.stderr ?? "").trim() || e.message || "unknown error";
+      const firstLine = reason.split("\n", 1)[0]!.slice(0, 200);
+      return "__TRANSPORTERROR__" + firstLine;
+    }
+  }
+
+  /**
+   * Sleep synchronously between produce retries.
+   *
+   * `push()` is synchronous (the whole backend drives its socket through a child
+   * process), so there is no event loop to await on. `Atomics.wait` on a
+   * SharedArrayBuffer is the stdlib way to block a thread for a fixed time --
+   * no dependency, no busy-wait burning CPU.
+   */
+  private static sleepSync(ms: number): void {
+    const shared = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(shared, 0, 0, ms);
+  }
+
+  /**
+   * Turn a sentinel from the protocol child into a thrown error, or return.
+   *
+   * The wording matches the Python and PHP backends exactly -- the parity rule
+   * covers user-visible error messages, not just behaviour.
+   */
+  private static assertNoError(result: string, operation: string, topic: string): void {
+    const fatal = /^__(PRODUCEERROR|FETCHERROR)__(\d+)/.exec(result);
+    if (fatal) {
+      throw new Error(
+        `Kafka rejected the ${operation} for topic ${topic}: error code ${fatal[2]}`,
+      );
+    }
+    if (result.startsWith("__TRANSPORTERROR__")) {
+      throw new Error(
+        `Kafka ${operation} for topic ${topic} failed: ` +
+          result.slice("__TRANSPORTERROR__".length),
+      );
+    }
+    if (result.startsWith("__PARSEERROR__")) {
+      throw new Error(
+        `Kafka ${operation} for topic ${topic} returned an unreadable response: ` +
+          result.slice("__PARSEERROR__".length),
+      );
     }
   }
 
@@ -576,15 +651,36 @@ export class KafkaBackend implements QueueBackend {
       delayUntil: null,
     };
 
-    const result = this.execSync("publish", queue, JSON.stringify(job));
-    if (!result.includes("__PUBLISHED__")) {
-      throw new Error("Kafka publish failed");
+    // Topic auto-creation is ASYNCHRONOUS, so a brand-new topic answers
+    // UNKNOWN_TOPIC_OR_PARTITION (3) or LEADER_NOT_AVAILABLE (5) on the first
+    // attempt while the controller is still electing a leader. Retry those
+    // (same 10 attempts / 200ms as the Python and PHP backends) instead of
+    // failing a cold-start push; every other code throws immediately.
+    const body = JSON.stringify(job);
+    let result = "";
+    for (let attempt = 1; attempt <= 10; attempt++) {
+      result = this.execSync("publish", queue, body);
+      if (result.includes("__PUBLISHED__")) {
+        return id;
+      }
+      const retriable = /^__PRODUCEERROR__(3|5)\b/.test(result);
+      if (!retriable || attempt === 10) {
+        break;
+      }
+      KafkaBackend.sleepSync(200);
     }
-    return id;
+
+    KafkaBackend.assertNoError(result, "produce", queue);
+    throw new Error(`Kafka publish failed for topic ${queue}: ${result || "no response"}`);
   }
 
   pop(queue: string): QueueJob | null {
     const result = this.execSync("get", queue);
+
+    // A real failure must NOT read as an empty queue: a mis-permissioned
+    // consumer would otherwise poll an "idle" topic forever.
+    KafkaBackend.assertNoError(result, "fetch", queue);
+
     if (!result || result === "__EMPTY__" || result === "__UNSUPPORTED__") return null;
 
     try {