tina4-nodejs 3.13.104 → 3.13.108

package/packages/core/src/authGate.ts

@@ -16,6 +16,9 @@ import type { Tina4Request, Tina4Response } from "./types.js";
 export interface AuthGateRoute {
   secure?: boolean;
   noAuth?: boolean;
+  /** RBAC guard groups (Feature 138): OR within a group, AND across groups. */
+  requiredRoles?: string[][];
+  requiredPerms?: string[][];
 }
 
 /**
@@ -68,7 +71,8 @@ export function enforceRouteAuth(
     const identity = sso?.identity;
     if (identity?.issuer && identity?.subject) {
       req.user = identity;
-      return false;
+      // 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)) {
@@ -93,5 +97,61 @@ export function enforceRouteAuth(
     }
   }
 
+  // ── RBAC guards (Feature 138): authorization AFTER authentication ──
+  // Auth has passed (401 ruled out above). If the route carries role/permission
+  // guards, the verified payload must satisfy them, else 403.
+  return rbacForbidden(match, req.user, res);
+}
+
+/** Read a claim as a list of strings; coerce a legacy singular string. */
+function rbacClaimList(subject: Record<string, unknown>, key: string, legacy?: string): string[] {
+  const coerce = (v: unknown): string[] => {
+    if (typeof v === "string") return v === "" ? [] : [v];
+    if (Array.isArray(v)) return v.map((x) => String(x)).filter((x) => x !== "");
+    return [];
+  };
+  let out = coerce(subject[key]);
+  if (out.length === 0 && legacy) out = coerce(subject[legacy]);
+  return out;
+}
+
+/**
+ * True if any GRANTED permission satisfies the concrete REQUIRED one.
+ * `*` grants everything; `posts.*` grants `posts.<...>` on the dot boundary.
+ */
+function rbacPermGranted(granted: string[], required: string): boolean {
+  return granted.some(
+    (g) => g === "*" || g === required || (g.endsWith(".*") && required.startsWith(g.slice(0, -1))),
+  );
+}
+
+/**
+ * Write a 403 and return `true` when a route's RBAC guards are not satisfied by
+ * the verified payload; return `false` (no write) when authorised or unguarded.
+ * AND across guard groups, OR within a group. Feature 138 / ADR-0058.
+ */
+function rbacForbidden(match: AuthGateRoute, payload: unknown, res: Tina4Response): boolean {
+  const requiredRoles = match.requiredRoles ?? [];
+  const requiredPerms = match.requiredPerms ?? [];
+  if (requiredRoles.length === 0 && requiredPerms.length === 0) {
+    return false;
+  }
+  const subject =
+    payload && typeof payload === "object" ? (payload as Record<string, unknown>) : {};
+
+  const roles = rbacClaimList(subject, "roles", "role");
+  for (const group of requiredRoles) {
+    if (!group.some((r) => roles.includes(r))) return writeForbidden(res);
+  }
+  const perms = rbacClaimList(subject, "permissions");
+  for (const group of requiredPerms) {
+    if (!group.some((p) => rbacPermGranted(perms, p))) return writeForbidden(res);
+  }
   return false;
 }
+
+function writeForbidden(res: Tina4Response): boolean {
+  res.raw.writeHead(403, { "Content-Type": "application/json" });
+  res.raw.end(JSON.stringify({ error: "Forbidden" }));
+  return true;
+}

package/packages/core/src/queue.ts

@@ -144,7 +144,13 @@ 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;
-  retry?(queue: string, id: string, delaySeconds?: 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
+   * legacy-return void; callers coerce a void return to true so nothing that
+   * used to be reported as success silently flips to failure.
+   */
+  retry?(queue: string, id: string, delaySeconds?: number): boolean | void;
   deadLetters?(queue: string, maxRetries?: number): QueueJob[];
   failed?(queue: string, maxRetries?: number): QueueJob[];
   retryFailed?(queue: string, maxRetries?: number): number;
@@ -400,7 +406,19 @@ export class Queue {
   }
 
   /**
-   * Count jobs filtered by status. Defaults to "pending".
+   * Count jobs by status. Defaults to "pending".
+   *
+   * ``"pending"`` counts jobs waiting to be popped -- INCLUDES retryable-
+   * but-attempted ones, because they live in the pending queue under the
+   * auto-retry lifecycle (see failed()).
+   * ``"reserved"`` counts jobs a consumer has popped but not yet
+   * completed/failed (in-flight against the visibility timeout).
+   * ``"completed"`` counts jobs the consumer has finished successfully.
+   * ``"failed"``, ``"dead"``, ``"dead_letter"`` are ALIASES that all count
+   * the dead-letter store -- jobs whose attempts >= maxRetries and that
+   * have given up. Use deadLetters() to list them. Retryable-but-attempted
+   * jobs are NOT counted by size("failed"); use failed() to list them or
+   * size("pending") to include them in a total.
    */
   size(status: string = "pending"): number {
     const q = this.topic;
@@ -455,13 +473,21 @@ export class Queue {
   /**
    * Get jobs that failed at least once but are still being retried
    * (0 < attempts < maxRetries). These live in the pending queue under the
-   * auto-retry lifecycle; dead-lettered jobs are returned by deadLetters().
+   * auto-retry lifecycle (fail() re-queues them with an incremented attempts
+   * count and a retryBackoff delay) so pop() picks them up again. They are
+   * NOT counted by size("failed") -- that alias counts the dead-letter store,
+   * matching deadLetters(). To include retryable-failed jobs in a total, use
+   * size("pending"). Terminal failures are returned by deadLetters().
    */
   failed(): QueueJob[] {
-    if (this.externalBackend?.failed) {
-      return this.externalBackend.failed(this.topic, this._maxRetries);
-    }
-    return this.liteBackend.failed(this.topic, this._maxRetries);
+    const raw = this.externalBackend?.failed
+      ? this.externalBackend.failed(this.topic, this._maxRetries)
+      : this.liteBackend.failed(this.topic, this._maxRetries);
+    // Wrap so callers get the full Job lifecycle (parity with deadLetters()
+    // and Python's failed()).
+    return raw.map((data) =>
+      createJob({ ...(data as JobData), topic: (data as JobData).topic ?? this.topic }, this),
+    );
   }
 
   /**
@@ -473,21 +499,31 @@ export class Queue {
    */
   retry(jobId?: string, delaySeconds?: number): boolean {
     if (jobId) {
-      // Retry a specific job by ID
+      // Retry a specific job by ID. Honour whatever the external backend
+      // returns (a boolean) so an unknown id reports false; only coerce a
+      // legacy void return to true to preserve the pre-3.13.105 contract on
+      // a backend that hasn't been updated (LiteBackend already returns bool).
       if (this.externalBackend?.retry) {
-        this.externalBackend.retry(this.topic, jobId, delaySeconds);
-        return true;
+        const result = this.externalBackend.retry(this.topic, jobId, delaySeconds);
+        return result === undefined ? true : Boolean(result);
       }
       return this.liteBackend.retry(this.topic, jobId, delaySeconds);
     }
-    // Retry all dead-letter jobs
+    // Retry ALL dead-letter jobs -- an explicit for...of iterates every
+    // entry rather than a reducer like .some() that would short-circuit on
+    // the first truthy result (PY-12-04 parity: Python's generator-inside-
+    // any() had exactly that bug pre-3.13.105 and left the remaining
+    // dead letters silently in the store).
     const deadJobs = this.deadLetters();
     if (deadJobs.length === 0) return false;
     let retried = false;
     for (const job of deadJobs) {
       if (this.externalBackend?.retry) {
-        this.externalBackend.retry(this.topic, job.id, delaySeconds);
-        retried = true;
+        const result = this.externalBackend.retry(this.topic, job.id, delaySeconds);
+        // A modern backend returns bool; a legacy backend returns void which
+        // we optimistically treat as revived (parity with the pre-3.13.105
+        // pathway that never had a way to know otherwise).
+        if (result === undefined || Boolean(result)) retried = true;
       } else if (this.liteBackend.retry(this.topic, job.id, delaySeconds)) {
         retried = true;
       }
@@ -496,13 +532,34 @@ export class Queue {
   }
 
   /**
-   * Get dead letter jobs — failed jobs that exceeded max retries.
+   * Get jobs that exceeded max_retries -- terminal failures.
+   *
+   * Same set counted by size("failed") / size("dead") / size("dead_letter")
+   * (three aliases for the dead-letter store). To LIST retryable-but-
+   * attempted jobs (attempts > 0 AND attempts < maxRetries) that are still
+   * being auto-retried, use failed() -- those live in the pending queue and
+   * are NOT dead letters.
+   *
+   * Returns Job objects with the failure reason on ``.error`` (not raw dicts)
+   * so callers can iterate uniformly with the rest of the queue API and, in
+   * particular, call ``.retry()`` on each to manually revive it:
+   *
+   *     for (const job of queue.deadLetters()) {
+   *       Log.warn(`revived ${job.id}: ${job.error}`);
+   *       job.retry();
+   *     }
    */
   deadLetters(maxRetries?: number): QueueJob[] {
-    if (this.externalBackend?.deadLetters) {
-      return this.externalBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
-    }
-    return this.liteBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
+    const raw = this.externalBackend?.deadLetters
+      ? this.externalBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries)
+      : this.liteBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
+    // Wrap so ``job.retry()`` / ``job.fail()`` / ``job.complete()`` work
+    // uniformly (parity with pop() and the Python master). Preserves the
+    // job's own topic so the lifecycle methods route back to THIS queue's
+    // backend even on a job that dead-lettered on a different topic.
+    return raw.map((data) =>
+      createJob({ ...(data as JobData), topic: (data as JobData).topic ?? this.topic }, this),
+    );
   }
 
   /**

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

@@ -677,11 +677,27 @@ export class LiteBackend {
    * Explicit re-queue requested by the caller (job.retry()).
    *
    * Always re-enqueues regardless of the retry limit — manual override,
-   * distinct from the automatic failJob() path.
+   * distinct from the automatic failJob() path. Cleans up BOTH the
+   * reservation record AND any dead-letter file for this id, so a caller
+   * that iterates deadLetters() and calls .retry() on each doesn't leave
+   * the failed/ directory carrying duplicates (PY-12-05, 3.13.105).
+   * Aligns with retry(queue, jobId) which had always unlinked the
+   * dead-letter file -- two spellings of the same intent that previously
+   * diverged.
    */
   retryJob(queue: string, job: QueueJob, delaySeconds?: number): void {
     // Clear the reservation — the consumer acknowledged (with an explicit retry).
     this.clearReservation(queue, job.id);
+    // Drop any dead-letter file for this id BEFORE the re-queue -- if this
+    // job came from deadLetters() it lives in failed/ and would otherwise
+    // stay on disk while a fresh pending file appears in the queue dir, so
+    // the next deadLetters() call reports the job again and a consumer
+    // processes it twice.
+    try {
+      unlinkSync(join(this.ensureFailedDir(queue), `${job.id}.queue-data`));
+    } catch {
+      // ENOENT is fine (the job never dead-lettered or was already cleared).
+    }
     job.attempts = (job.attempts || 0) + 1;
     job.error = undefined;
     this.requeue(queue, job, delaySeconds ?? 0, undefined);

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

@@ -343,17 +343,67 @@ export class MongoBackend implements QueueBackend {
             process.stdout.write("__OK__");
           }
           else if (operation === "retry") {
-            // Explicit manual re-queue (always re-enqueues). data = JSON
-            // { id, delaySeconds }.
+            // Explicit manual re-queue. Serves BOTH Queue.retry(id) (revive
+            // a dead-letter job) AND job.retry() (manual re-queue of a live
+            // reserved/pending job) so the Mongo backend matches
+            // LiteBackend's dual behaviour.
+            //
+            // 1) DL revival (Queue.retry(id) after fail exhausted retries).
+            //    Pre-3.13.105 this branch was BROKEN: the search filter was
+            //    { queue: queueName, id, status: "failed" } -- three separate
+            //    reasons it could never match. dead_letter() inserts under
+            //    queueName + ".dead_letter" (not queueName), carries
+            //    status "dead" (not "failed"), and the original under
+            //    queueName was already acked to "completed" by the time the
+            //    DL was written. Now we look up in the DL namespace by id,
+            //    delete the DL doc first (so an interrupted retry never
+            //    leaves both a DL and a fresh pending doc), and upsert the
+            //    original back to pending -- re-hydrating if the original
+            //    was purged (housekeeping) so a retry always works.
+            // 2) Live-doc manual re-queue (job.retry() on a job the caller
+            //    just popped and wants back in pending). The live-doc path
+            //    is preserved from before 3.13.105.
+            //
+            // Returns __OK__ when either path acted; __NOT_FOUND__ when
+            // neither the DL nor the live doc existed, so Queue.retry(id)
+            // can now report the pre-3.13.105 blanket-true as false for
+            // unknown ids. data = JSON { id, delaySeconds }.
             const info = JSON.parse(data);
+            const dlTopic = queueName + ".dead_letter";
+            const now = new Date().toISOString();
             const avail = info.delaySeconds > 0
               ? new Date(Date.now() + info.delaySeconds * 1000).toISOString()
-              : new Date().toISOString();
-            await col.updateOne(
-              { queue: queueName, id: info.id },
-              { $set: { status: "pending", availableAt: avail, reservedAt: null }, $inc: { attempts: 1 } },
-            );
-            process.stdout.write("__OK__");
+              : now;
+            const dlDoc = await col.findOne({ queue: dlTopic, id: info.id });
+            if (dlDoc !== null) {
+              await col.deleteOne({ _id: dlDoc._id });
+              const payload = dlDoc.payload ?? {};
+              const priority = dlDoc.priority ?? 0;
+              await col.updateOne(
+                { queue: queueName, id: info.id },
+                {
+                  $set: {
+                    status: "pending",
+                    availableAt: avail,
+                    reservedAt: null,
+                    error: null,
+                    payload,
+                    priority,
+                    id: info.id,
+                    createdAt: dlDoc.createdAt ?? now,
+                  },
+                  $inc: { attempts: 1 },
+                },
+                { upsert: true },
+              );
+              process.stdout.write("__OK__");
+            } else {
+              const result = await col.updateOne(
+                { queue: queueName, id: info.id },
+                { $set: { status: "pending", availableAt: avail, reservedAt: null }, $inc: { attempts: 1 } },
+              );
+              process.stdout.write(result.matchedCount > 0 ? "__OK__" : "__NOT_FOUND__");
+            }
           }
           else if (operation === "deadLetters") {
             const docs = await col.find({ queue: queueName + ".dead_letter" }).toArray();
@@ -398,10 +448,20 @@ export class MongoBackend implements QueueBackend {
             process.stdout.write(String(revived));
           }
           else if (operation === "purge") {
-            // Delete docs by status (default: all for the topic). data = JSON { status }.
+            // Delete docs by status (default: every doc for the topic).
+            // Pre-3.13.105 this filtered by { queue: queueName, status } for
+            // EVERY status -- correct for pending/reserved/completed, wrong
+            // for the dead-letter states (dead/failed/dead_letter) which
+            // live under queueName + ".dead_letter" and carry status "dead".
+            // A purge("dead") therefore deleted nothing and returned 0.
+            // data = JSON { status }.
             const info = data ? JSON.parse(data) : {};
-            const filter = { queue: queueName };
-            if (info.status) filter.status = info.status;
+            const isDead = info.status && ["dead", "failed", "dead_letter"].includes(info.status);
+            const filter = isDead
+              ? { queue: queueName + ".dead_letter" }
+              : (info.status
+                ? { queue: queueName, status: info.status }
+                : { queue: queueName });
             const res = await col.deleteMany(filter);
             process.stdout.write(String(res.deletedCount || 0));
           }
@@ -513,9 +573,15 @@ export class MongoBackend implements QueueBackend {
     this.execSync("fail", queue, JSON.stringify({ id, error, maxRetries, retryBackoff }));
   }
 
-  /** Explicit manual re-queue (always re-enqueues regardless of the retry limit). */
-  retry(queue: string, id: string, delaySeconds: number = 0): void {
-    this.execSync("retry", queue, JSON.stringify({ id, delaySeconds }));
+  /**
+   * Revive a specific dead-letter job by id. Returns true if the DL was found
+   * and revived, false otherwise (parity with LiteBackend.retry(queue, id)
+   * and Python's mongo_backend.retry_job()). Pre-3.13.105 this returned void
+   * and Queue.retry(id) reported success for every call, even for unknown ids.
+   */
+  retry(queue: string, id: string, delaySeconds: number = 0): boolean {
+    const out = this.execSync("retry", queue, JSON.stringify({ id, delaySeconds }));
+    return out.includes("__OK__");
   }
 
   /** Jobs that exceeded max retries (the `<queue>.dead_letter` collection topic). */

package/packages/core/src/router.ts

@@ -69,6 +69,8 @@ interface MatchResult {
   secure?: boolean;
   cached?: boolean;
   noAuth?: boolean;
+  requiredRoles?: string[][];
+  requiredPerms?: string[][];
 }
 
 interface CompiledRoute {
@@ -86,6 +88,9 @@ interface CompiledRoute {
   cacheStore?: Map<string, { data: unknown; expires: number }>;
   cacheTtl?: number;
   template?: string;
+  /** RBAC guard groups (Feature 138): OR within a group, AND across groups. */
+  requiredRoles?: string[][];
+  requiredPerms?: string[][];
 }
 
 /**
@@ -126,6 +131,33 @@ export class RouteRef {
     return this;
   }
 
+  /**
+   * RBAC: require ONE of the named roles (OR). Reads the verified JWT `roles`
+   * claim. Chain .role()/.can() for AND. Implies auth. Feature 138 / ADR-0058.
+   */
+  role(...names: string[]): this {
+    const clean = names.filter((n) => n !== "");
+    if (clean.length > 0) {
+      (this.route.requiredRoles ??= []).push(clean);
+      this.route.secure = true;
+    }
+    return this;
+  }
+
+  /**
+   * RBAC: require ONE of the named permissions (OR). Reads the verified JWT
+   * `permissions` claim; granted-side wildcards (`posts.*`, `*`) satisfy a
+   * concrete requirement. Chain for AND. Implies auth. Feature 138.
+   */
+  can(...permissions: string[]): this {
+    const clean = permissions.filter((p) => p !== "");
+    if (clean.length > 0) {
+      (this.route.requiredPerms ??= []).push(clean);
+      this.route.secure = true;
+    }
+    return this;
+  }
+
   /** Mark this route's response as cacheable. */
   cache(): this {
     this.route.cached = true;
@@ -220,6 +252,8 @@ export class Router {
       cached: definition.cached,
       noAuth: definition.noAuth,
       template: definition.template,
+      requiredRoles: definition.requiredRoles,
+      requiredPerms: definition.requiredPerms,
     };
     routes.push(compiled);
     return new RouteRef(compiled);
@@ -393,6 +427,8 @@ export class Router {
           secure: route.secure,
           cached: route.cached,
           noAuth: route.noAuth,
+          requiredRoles: route.requiredRoles,
+          requiredPerms: route.requiredPerms,
         };
       }
     }
@@ -417,6 +453,8 @@ export class Router {
           secure: route.secure,
           cached: route.cached,
           noAuth: route.noAuth,
+          requiredRoles: route.requiredRoles,
+          requiredPerms: route.requiredPerms,
         });
       }
     }

package/packages/core/src/server.ts

@@ -1210,6 +1210,30 @@ function asHtmlString(chunk: unknown): string | null {
   return null;
 }
 
+/**
+ * Whether this response's body can still have HTML spliced into it.
+ *
+ * `text/html` is NOT enough on its own. A static-file response (static.ts) gzips
+ * itself and sets Content-Encoding BEFORE it calls `res.raw.end()` - and that
+ * `end()` is the intercepted one below, so the chunk arriving there is
+ * COMPRESSED BYTES, not markup. Reading them back as UTF-8 to inject a toolbar
+ * replaces every byte outside ASCII with U+FFFD, and the browser is handed a
+ * gzip stream whose header is `1f ef bf bd` instead of `1f 8b`. Chrome answers
+ * ERR_CONTENT_DECODING_FAILED and the page does not load at all.
+ *
+ * That is not a corner case: in dev mode it corrupted EVERY static .html file
+ * over the 1024-byte compression threshold, which is most real pages, so
+ * `tina4 serve` served an unloadable page while curl (which asks for no
+ * encoding by default) looked perfectly healthy.
+ *
+ * dispatchPipeline.ts already guards the sibling half of this - it refuses to
+ * gzip a body some earlier stage has already encoded - with the same test. This
+ * is the other half: do not TEXT-EDIT a body some earlier stage has encoded.
+ */
+function isInjectableHtml(res: Tina4Response): boolean {
+  return isHtmlResponse(res) && !res.raw.getHeader("content-encoding");
+}
+
 /**
  * Inject the dev toolbar (dev mode only) and the feedback widget into an HTML body.
  *
@@ -1269,7 +1293,11 @@ function wrapResponseEnd(ctx: ResponseWrapContext): void {
       );
     }
 
-    if (isHtmlResponse(res)) {
+    // An ENCODED body is passed straight through, untouched and with its
+    // Content-Length intact: the length static.ts set describes the compressed
+    // bytes and is correct, and there is nothing here we could inject into
+    // without destroying them. See isInjectableHtml.
+    if (isInjectableHtml(res)) {
       const html = asHtmlString(chunk);
       if (html !== null) chunk = injectIntoHtml(ctx, devToolbar, html);
       // Dropped for ANY html response, not only one carrying a body: that is

package/packages/core/src/types.ts

@@ -161,6 +161,10 @@ export interface RouteDefinition {
   cached?: boolean;
   /** Opt out of secure-by-default auth on write routes */
   noAuth?: boolean;
+  /** RBAC role guard groups (Feature 138): OR within a group, AND across groups */
+  requiredRoles?: string[][];
+  /** RBAC permission guard groups (Feature 138) */
+  requiredPerms?: string[][];
 }
 
 export interface RouteMeta {