@k2b/cloud 0.22.0 → 0.23.0

package/src/services/app-approval.ts

@@ -1,4 +1,3 @@
-import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto";
 import { type SQL, sql } from "bun";
 import { lazySync } from "../_internal/process-sync";
 import { env } from "../config/env";
@@ -19,6 +18,8 @@ import { publicCloudOrigin } from "../shared/app-url";
 import { isAccountCategoryAllowed } from "./account-category-policy";
 import { audit } from "./audit";
 import { logger } from "./logging";
+import { pairingSecret } from "./pairing-secret";
+import { requireEligibleAccount, requireRecentWebSession } from "./session/recent";
 import { CORE_SETTINGS } from "./settings/core-settings";
 import { decryptValue } from "./settings/crypto";
 
@@ -33,10 +34,7 @@ export class AppApprovalError extends Error {
 const reject = (code: AppApprovalError["code"], status: AppApprovalError["status"]): never => {
   throw new AppApprovalError(code, status);
 };
-const secret = () => randomBytes(32).toString("base64url");
-const hash = (value: string) => createHash("sha256").update(value).digest("hex");
-const matches = (value: string, expected: string) => timingSafeEqual(Buffer.from(hash(value), "hex"), Buffer.from(expected, "hex"));
-const comparison = () => String(randomInt(0, 1_000_000)).padStart(6, "0");
+const { create: secret, hash, matches, code: comparison } = pairingSecret;
 const iso = (value: Date | string) => new Date(value).toISOString();
 const future = (seconds: number) => new Date(Date.now() + seconds * 1000);
 
@@ -217,26 +215,9 @@ export const createAppApprovalService = (
     if (requireEnabled && (!value.enabled || !value.appOrigin)) return reject("UNAVAILABLE", 503);
     return value;
   };
-  const eligible = async (tx: SQL, id: string): Promise<AccountRow> => {
-    const [row] = await tx<
-      AccountRow[]
-    >`SELECT id, uid, provider, profile, auth_epoch, account_expires FROM auth.users WHERE id = ${id}::uuid`;
-    if (
-      !row ||
-      (row.account_expires && new Date(row.account_expires).getTime() <= Date.now()) ||
-      !(await isAccountCategoryAllowed(row, tx))
-    )
-      return reject("FORBIDDEN", 403);
-    return row;
-  };
-  const fresh = async (tx: SQL, actor: AppApprovalActor) => {
-    const [row] = await tx`SELECT sid FROM auth.session_families f JOIN auth.users u ON u.id = f.user_id
-      WHERE f.sid = ${actor.sid}::uuid AND f.user_id = ${actor.userId}::uuid AND f.revoked_at IS NULL
-        AND f.auth_epoch = u.auth_epoch AND f.expires_at > now()
-        AND f.issued_at > now() - ${limits.recentSessionSeconds} * interval '1 second'`;
-    if (!row) return reject("REAUTHENTICATE", 403);
-    await eligible(tx, actor.userId);
-  };
+  const forbidden = (code: "REAUTHENTICATE" | "FORBIDDEN") => reject(code, 403);
+  const eligible = (tx: SQL, id: string): Promise<AccountRow> => requireEligibleAccount(tx, id, forbidden);
+  const fresh = (tx: SQL, actor: AppApprovalActor) => requireRecentWebSession(tx, actor, limits.recentSessionSeconds, forbidden);
   const record = (tx: SQL, action: string, userId: string, id: string, metadata: Record<string, unknown> = {}) =>
     audit.record({ action: `auth.app.${action}`, outcome: "allowed", actor: { userId }, target: { type: "app_device", id }, metadata }, tx);
   const cleanup = async () => {

package/src/services/audit/index.ts

@@ -120,6 +120,8 @@ const SELF_SERVICE_ACTION_LABELS = {
   "webauthn_credential.create": "Passkey added",
   "webauthn_credential.delete": "Passkey removed",
   "webauthn_credential.authenticate": "Passkey used",
+  "auth.pwa.device.enroll": "App paired",
+  "auth.pwa.device.revoke": "App removed",
 } as const satisfies Record<string, string>;
 const SELF_SERVICE_ACTIONS = Object.keys(SELF_SERVICE_ACTION_LABELS);
 

package/src/services/branding/app-icon-source.ts

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+import { CLOUD_LOGO_SVG } from "../../shared/branding";
+import * as settings from "../settings";
+
+/** Bumped when the drawing changes, so installed apps pick up the new icons. */
+const RENDERER_VERSION = "1";
+/** Larger logos fall back to the Cloud logo instead of reaching the decoder. */
+export const APP_ICON_SOURCE_MAX_BYTES = 10 * 1024 * 1024;
+
+export type AppIconSource = { data: Uint8Array; mime: string; version: string };
+
+const DATA_URI = /^data:([^;,]+);base64,(.+)$/;
+
+let latest: { logo: string; source: AppIconSource } | undefined;
+
+const parse = (logo: string): AppIconSource => {
+  const match = DATA_URI.exec(logo);
+  const data = match ? Buffer.from(match[2]!, "base64") : null;
+  const source =
+    match && data && data.byteLength > 0 && data.byteLength <= APP_ICON_SOURCE_MAX_BYTES
+      ? { data: new Uint8Array(data), mime: match[1]!, key: logo }
+      : { data: new TextEncoder().encode(CLOUD_LOGO_SVG), mime: "image/svg+xml", key: CLOUD_LOGO_SVG };
+  const version = createHash("sha256").update(source.key).update(RENDERER_VERSION).digest("hex").slice(0, 12);
+  return { data: source.data, mime: source.mime, version };
+};
+
+/**
+ * The installation logo the app icons are drawn from: `app.logo` when it is a base64 data URI (as uploaded in the
+ * settings), otherwise the Cloud logo. `version` is the first 12 hex characters of a hash over the logo and the
+ * drawing, so it changes exactly when the icons do.
+ */
+export const readAppIconSource = async (): Promise<AppIconSource> => {
+  const logo = (await settings.get<string>("app.logo")) || "";
+  // The manifest, the worker and the icons read it on every request; decode and hash a logo only once.
+  if (latest?.logo !== logo) latest = { logo, source: parse(logo) };
+  return latest.source;
+};
+
+/** The icons' version; the app's manifest carries it, so a new logo reaches installed apps. */
+export const appIconVersion = async (): Promise<string> => (await readAppIconSource()).version;

package/src/services/branding/app-icons.ts

@@ -0,0 +1,112 @@
+import { z } from "zod";
+import { spawnCanvasWorker } from "../../_internal/canvas-worker";
+import { PWA_CANVAS_COLORS } from "../../contracts/pwa";
+import { CLOUD_LOGO_SVG } from "../../shared/branding";
+import { logger } from "../logging";
+import { appIconVersion, readAppIconSource } from "./app-icon-source";
+
+declare const __CLOUD_ICON_RENDER_WORKER__: string | undefined;
+
+/**
+ * The icons of the installable mobile app. `any` icons are transparent; the maskable and the Apple icon are opaque,
+ * because launchers crop maskable icons to their own shape and iOS paints transparency black. The maskable logo stays
+ * inside the safe circle (40 % radius), so its square is at most 56 % of the icon.
+ */
+export const APP_ICON_VARIANTS = {
+  "pwa-icon-192": { size: 192, background: null, box: 0.84 },
+  "pwa-icon-512": { size: 512, background: null, box: 0.84 },
+  "pwa-icon-maskable-512": { size: 512, background: PWA_CANVAS_COLORS.light, box: 0.56 },
+  "apple-touch-icon": { size: 180, background: PWA_CANVAS_COLORS.light, box: 0.7 },
+} as const;
+export type AppIconVariant = keyof typeof APP_ICON_VARIANTS;
+
+const RENDER_TIMEOUT_MS = 10_000;
+/** A failed run is kept this long, so failing requests cannot start a worker each; the icon routes ask to retry after it. */
+export const APP_ICON_RETRY_SECONDS = 60;
+/** Four PNGs of at most 512 px, in base64, plus the JSON envelope. */
+const MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+const RenderResult = z.object({
+  icons: z.record(z.string(), z.string()),
+  fallback: z.boolean(),
+});
+
+const log = logger("branding");
+
+const renderAll = async (source: Awaited<ReturnType<typeof readAppIconSource>>): Promise<Map<AppIconVariant, Uint8Array<ArrayBuffer>>> => {
+  if (process.platform !== "linux") throw new Error("Icon rendering requires the Linux Cloud runtime with memory isolation.");
+  const worker =
+    typeof __CLOUD_ICON_RENDER_WORKER__ === "string"
+      ? new URL(__CLOUD_ICON_RENDER_WORKER__, import.meta.url)
+      : new URL("./icon-render-worker.ts", import.meta.url);
+  const signal = AbortSignal.timeout(RENDER_TIMEOUT_MS);
+  const child = spawnCanvasWorker(
+    worker,
+    "icon-renderer",
+    JSON.stringify({
+      source: Buffer.from(source.data).toString("base64"),
+      mime: source.mime,
+      fallback: CLOUD_LOGO_SVG,
+      variants: Object.entries(APP_ICON_VARIANTS).map(([id, variant]) => ({ id, ...variant })),
+    }),
+  );
+  const stop = () => child.kill("SIGKILL");
+  signal.addEventListener("abort", stop, { once: true });
+  try {
+    let length = 0;
+    const stdout = child.stdout.pipeThrough(
+      new TransformStream<Uint8Array, Uint8Array>({
+        transform(chunk, controller) {
+          length += chunk.byteLength;
+          if (length > MAX_OUTPUT_BYTES) throw new Error("Rendered icons exceed their budget.");
+          controller.enqueue(chunk);
+        },
+      }),
+    );
+    const text = await new Response(stdout).text();
+    signal.throwIfAborted();
+    if ((await child.exited) !== 0 || !text.trim()) throw new Error("Icon rendering failed.");
+    const output = RenderResult.parse(JSON.parse(text));
+    // Never log the logo or its data, only that it could not be used.
+    if (output.fallback) log.warn("The installation logo could not be decoded; the app icons use the Cloud logo");
+    const icons = new Map<AppIconVariant, Uint8Array<ArrayBuffer>>();
+    for (const variant of Object.keys(APP_ICON_VARIANTS) as AppIconVariant[]) {
+      const png = output.icons[variant];
+      if (!png) throw new Error("Icon rendering failed.");
+      icons.set(variant, new Uint8Array(Buffer.from(png, "base64")));
+    }
+    return icons;
+  } finally {
+    signal.removeEventListener("abort", stop);
+    stop();
+    await child.exited;
+  }
+};
+
+/**
+ * Renders the mobile app's icons from the installation logo. One run draws all variants in an isolated process; the
+ * result is kept for the current logo, concurrent requests share one run, a new logo is drawn on its next read, and a
+ * failed run is tried again after `APP_ICON_RETRY_SECONDS`.
+ */
+export const createAppIcons = () => {
+  type Run = { version: string; icons: Promise<Map<AppIconVariant, Uint8Array<ArrayBuffer>>>; failedAt?: number };
+  let current: Run | undefined;
+  return {
+    version: appIconVersion,
+    render: async (variant: AppIconVariant): Promise<{ png: Uint8Array<ArrayBuffer>; etag: string }> => {
+      const source = await readAppIconSource();
+      let entry = current;
+      const retry = entry?.failedAt !== undefined && Date.now() - entry.failedAt >= APP_ICON_RETRY_SECONDS * 1000;
+      if (entry?.version !== source.version || retry) {
+        const created: Run = { version: source.version, icons: renderAll(source) };
+        created.icons.catch(() => {
+          created.failedAt = Date.now();
+        });
+        current = entry = created;
+      }
+      const icons = await entry.icons;
+      return { png: icons.get(variant)!, etag: `"${source.version}"` };
+    },
+  };
+};
+
+export const appIcons = createAppIcons();

package/src/services/branding/icon-render-worker.ts

@@ -0,0 +1,69 @@
+// Standalone subprocess. No server imports or application credentials.
+
+import { createCanvas, type Image, loadImage } from "@napi-rs/canvas";
+import { z } from "zod";
+import { sizedSvg } from "./icon-svg";
+
+const MAX_SOURCE_BYTES = 10 * 1024 * 1024;
+const inputSchema = z.object({
+  source: z.string().max(Math.ceil((MAX_SOURCE_BYTES * 4) / 3)),
+  mime: z.string().max(100),
+  fallback: z.string().max(64 * 1024),
+  variants: z
+    .array(
+      z.object({
+        id: z.string().regex(/^[a-z0-9-]+$/),
+        size: z.number().int().min(16).max(1024),
+        /** Opaque background, or none for a transparent icon. */
+        background: z
+          .string()
+          .regex(/^#[0-9a-f]{6}$/i)
+          .nullable(),
+        /** Side of the centred square the logo fits into, as a fraction of the icon. */
+        box: z.number().gt(0).max(1),
+      }),
+    )
+    .min(1)
+    .max(8),
+});
+
+const decode = async (data: Buffer, mime: string, size: number): Promise<Image> =>
+  loadImage(mime === "image/svg+xml" ? Buffer.from(sizedSvg(data.toString("utf8"), size)) : data);
+
+try {
+  const input = inputSchema.parse(JSON.parse(await Bun.stdin.text()));
+  const source = Buffer.from(input.source, "base64");
+  if (source.byteLength > MAX_SOURCE_BYTES) throw new Error("The logo exceeds the 10 MiB limit.");
+  let fallback = false;
+  const icons: Record<string, string> = {};
+  for (const variant of input.variants) {
+    const box = Math.round(variant.size * variant.box);
+    let image: Image;
+    try {
+      if (fallback) throw new Error("fallback");
+      image = await decode(source, input.mime, box);
+      if (!(image.width > 0 && image.height > 0)) throw new Error("empty");
+    } catch {
+      fallback = true;
+      image = await decode(Buffer.from(input.fallback), "image/svg+xml", box);
+    }
+    const canvas = createCanvas(variant.size, variant.size);
+    const context = canvas.getContext("2d");
+    if (variant.background) {
+      context.fillStyle = variant.background;
+      context.fillRect(0, 0, variant.size, variant.size);
+    }
+    context.imageSmoothingEnabled = true;
+    context.imageSmoothingQuality = "high";
+    // Fit the logo into the centred box and keep its aspect ratio.
+    const scale = Math.min(box / image.width, box / image.height);
+    const width = image.width * scale;
+    const height = image.height * scale;
+    context.drawImage(image, (variant.size - width) / 2, (variant.size - height) / 2, width, height);
+    icons[variant.id] = Buffer.from(canvas.toBuffer("image/png")).toString("base64");
+  }
+  process.stdout.write(JSON.stringify({ icons, fallback }));
+} catch (error) {
+  process.stdout.write(JSON.stringify({ error: error instanceof z.ZodError ? "Invalid icon request." : "Icon rendering failed." }));
+  process.exitCode = 1;
+}

package/src/services/branding/icon-svg.ts

@@ -0,0 +1,22 @@
+/** A root `width` or `height` in plain pixels; percentages and other units do not give the drawing's extent. */
+const pixels = (attributes: string, name: "width" | "height"): number | undefined => {
+  const match = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, "i").exec(attributes);
+  const value = (match?.[1] ?? match?.[2] ?? match?.[3])?.trim();
+  return value && /^\d+(?:\.\d+)?(?:px)?$/i.test(value) ? Number.parseFloat(value) : undefined;
+};
+
+/**
+ * Gives an SVG root the target size, so the vector renders sharp instead of being scaled as a bitmap. Without a
+ * viewBox, a new size would crop instead of scale, so the root gets one from its pixel size; a root with neither
+ * stays as it is.
+ */
+export const sizedSvg = (svg: string, size: number): string =>
+  svg.replace(/<svg\b([^>]*)>/i, (tag, attributes: string) => {
+    const viewBox = /\sviewBox\s*=/i.test(attributes);
+    const width = pixels(attributes, "width");
+    const height = pixels(attributes, "height");
+    if (!viewBox && (width === undefined || height === undefined)) return tag;
+    let rest = attributes.replace(/\s(?:width|height)\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, "");
+    if (!viewBox) rest += ` viewBox="0 0 ${width} ${height}"`;
+    return `<svg${rest} width="${size}" height="${size}">`;
+  });

package/src/services/identity/invocation-actor.ts

@@ -4,7 +4,7 @@ import type { AccessSubject } from "../../server/services/access";
 import { isAccountCategoryAllowed } from "../account-category-policy";
 import { isAccountExpired } from "../account-model";
 import type { ServiceAccount } from "../service-accounts";
-import { buildProjectedUser, loadCurrentUser, userProjectionJoin, userProjectionSql } from "../session/user";
+import { buildProjectedUser, loadCurrentUser, userProjectionJoin, userProjectionSql, withoutAdminRole } from "../session/user";
 import type { CloudInvocationClaims } from "./invocation-token";
 import { getIdentityRuntimeConfig } from "./runtime-config";
 
@@ -66,11 +66,14 @@ export const resolveInvocationAuthority = async (
   const delegation = provenance(claims);
 
   if (claims.principal_type === "user") {
-    const user = await loadCurrentUser({ userId: claims.sub, groupsAdmin }, query);
-    if (!user || isAccountExpired(user.accountExpires)) return null;
-    if (!(await isAccountCategoryAllowed(user, query))) return null;
+    const current = await loadCurrentUser({ userId: claims.sub, groupsAdmin }, query);
+    if (!current || isAccountExpired(current.accountExpires)) return null;
+    if (!(await isAccountCategoryAllowed(current, query))) return null;
+    // The mobile app's session never acts as an installation administrator, also not through another app.
+    const app = claims.session_kind === "app";
+    const user = app ? withoutAdminRole(current) : current;
     return {
-      actor: { kind: "user", user, delegation },
+      actor: { kind: "user", user, delegation, ...(app ? { sessionKind: "app" as const } : {}) },
       accessSubject: { type: "user", userId: user.id },
       credentialKind: "invocation",
       scopes: [...claims.scopes],

package/src/services/identity/invocation-authority.ts

@@ -17,6 +17,7 @@ export const invocationAuthorityFromRequest = (authority: RequestAuthority): Inv
       access_subject_type: "user",
       access_subject_id: authority.actor.user.id,
       credential_kind: authority.credentialKind,
+      ...(authority.credentialKind === "session" && authority.actor.sessionKind === "app" ? { session_kind: "app" as const } : {}),
       scopes: [...new Set(authority.scopes)].sort(),
     };
   }

package/src/services/identity/invocation-token.ts

@@ -56,6 +56,8 @@ const InvocationPayloadSchema = z
     delegated_user_id: z.string().uuid().optional(),
     act: z.object({ sub: z.string().regex(/^app:[a-z][a-z0-9-]{0,79}$/) }).strict(),
     credential_kind: z.enum(["session", "oauth", "api_key", "mandate"]),
+    /** Only for an app session of the mobile app, which never acts as an administrator. */
+    session_kind: z.literal("app").optional(),
     credential_id: BoundedIdentifierSchema.optional(),
     scopes: z
       .array(ScopeSchema)
@@ -97,6 +99,9 @@ const InvocationPayloadSchema = z
     if (claims.credential_kind === "session" && claims.principal_type !== "user") {
       context.addIssue({ code: "custom", message: "A session invocation must use a user principal" });
     }
+    if (claims.session_kind && claims.credential_kind !== "session") {
+      context.addIssue({ code: "custom", message: "Only a session invocation has a session kind" });
+    }
     if (claims.credential_kind === "session" && claims.scopes.length > 0) {
       context.addIssue({ code: "custom", message: "A session invocation cannot carry credential scopes" });
     }
@@ -120,6 +125,7 @@ export type InvocationAuthority = Pick<
   | "access_subject_id"
   | "delegated_user_id"
   | "credential_kind"
+  | "session_kind"
   | "credential_id"
   | "scopes"
   | "mandate_id"

package/src/services/index.ts

@@ -197,6 +197,7 @@ export type {
 export { latestTopicCursor } from "./topic-cursor";
 export { readAccountCategoryPolicy, isAccountCategoryAllowed } from "./account-category-policy";
 export { AppApprovalError, appApproval, type AppDeviceAdministrator, type AppDeviceEnrollmentNotice } from "./app-approval";
+export { PwaError, pwaDevices, type PwaDeviceAdministrator } from "./pwa-devices";
 export { legalConsent } from "./legal-consent";
 
 /** Core-owned app bar administration; service methods enforce administrator access. */

package/src/services/outbox.ts

@@ -10,9 +10,18 @@ import { logger } from "./logging";
  * delivered (or dead after `maxAttempts`, when the table has a `dead_at`
  * column), and delivered rows are pruned after a retention period.
  *
+ * With `sequence`, it works in batches: claims of one outbox (table and
+ * `where`) take turns, a claim takes rows in sequence order with several rows
+ * per ordering key, and the dispatcher publishes keys concurrently and the
+ * rows of one key in order, then completes the batch in one statement. A row
+ * that never failed is due at once. Claims stay proportional to the batch
+ * with an index on the `where` columns and `sequence`, and one on the `where`
+ * columns and `orderBy` limited to `claimed_until IS NOT NULL OR attempts > 0`.
+ *
  * Required columns: `id uuid`, `attempts int`, `next_attempt_at timestamptz`,
  * `claimed_until timestamptz`, `delivered_at timestamptz`, `last_error text`,
- * `created_at timestamptz`. `maxAttempts` additionally needs `dead_at`.
+ * `created_at timestamptz`. `maxAttempts` additionally needs `dead_at`;
+ * `onDelivered: "delete"` needs no `delivered_at`.
  */
 
 const DEFAULT_CLAIM_MS = 30_000;
@@ -27,7 +36,7 @@ export type OutboxRow = {
 };
 
 export type PgOutboxConfig<Row extends OutboxRow> = {
-  /** Schema-qualified table, e.g. `mail.live_invalidation_outbox`. */
+  /** Schema-qualified table, e.g. `events.outbox`. */
   table: string;
   /** Log source. */
   name: string;
@@ -36,8 +45,16 @@ export type PgOutboxConfig<Row extends OutboxRow> = {
   /**
    * Column whose rows must be delivered in insertion order. A pending earlier
    * row with the same value blocks later ones until it is delivered or dead.
+   * With `sequence`, a value waits while any of its rows is claimed or waits
+   * for a retry.
    */
-  orderBy?: string;
+  orderBy?: Extract<keyof Row, string>;
+  /** Fixed column values every claimed row matches, e.g. `{ kind: "live", app_id: "contacts" }`. */
+  where?: Readonly<Record<string, string>>;
+  /** Insertion-order column that orders claims instead of `(created_at, id)`, and enables batches (see above). */
+  sequence?: string;
+  /** Delete a published row instead of setting `delivered_at`; every row in the table is then pending. */
+  onDelivered?: "delete";
   /** Mark rows dead after this many failed attempts (requires `dead_at`). */
   maxAttempts?: number;
   claimMs?: number;
@@ -67,11 +84,73 @@ export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row
   const claimMs = config.claimMs ?? DEFAULT_CLAIM_MS;
   const batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE;
   const log = logger(config.name);
+  const sequence = config.sequence ? identifier(config.sequence, "sequence column") : null;
+  const deleteDelivered = config.onDelivered === "delete";
   const notDead = maxAttempts === null ? sql`` : sql`AND dead_at IS NULL`;
   const earlierNotDead = maxAttempts === null ? sql`` : sql`AND earlier.dead_at IS NULL`;
+  const pending = deleteDelivered ? sql`` : sql`AND delivered_at IS NULL`;
+  const earlierPending = deleteDelivered ? sql`` : sql`AND earlier.delivered_at IS NULL`;
+  const filters = Object.entries(config.where ?? {}).map(([column, value]) => ({ column: identifier(column, "filter column"), value }));
+  const matches = (alias: "current" | "earlier" | "busy") =>
+    filters.reduce((fragment, { column, value }) => sql`${fragment} AND ${sql.unsafe(alias)}.${column} = ${value}`, sql``);
+  // Rows without an ordering column are independent: each is a key of its own.
+  const runKey = config.orderBy ?? "id";
+  const runColumn = identifier(runKey, "ordering column");
+  const claimLock = `${config.table}:${JSON.stringify(config.where ?? {})}`;
+
+  /**
+   * Claims rows in sequence order, several per key, and never a row of a key
+   * that has a claimed row or one waiting for a retry. `next_attempt_at` only
+   * delays retries: it is the writer's transaction start, so a fresh row that
+   * committed later can carry an earlier one, or one after this claim began.
+   */
+  const claimBatch = (cap: number, order: ReturnType<typeof sql.unsafe>) =>
+    sql.begin(async (tx) => {
+      // Claims take turns: a concurrent claim would skip this one's locked rows and take later rows of the same keys.
+      // A claim that outlives its claim period is worthless, so neither a slow statement nor a vanished client holds the turn longer.
+      await tx`
+        SELECT set_config('statement_timeout', ${String(claimMs)}, true),
+               set_config('idle_in_transaction_session_timeout', ${String(claimMs)}, true),
+               pg_advisory_xact_lock(hashtextextended(${claimLock}, 0))
+      `;
+      // The busy probe runs per candidate (OFFSET 0 keeps the planner from turning it into a join, which
+      // stale statistics can make quadratic), against an index of claimed and retried rows per key.
+      return tx<Row[]>`
+        WITH candidates AS MATERIALIZED (
+          SELECT current.id
+          FROM ${table} current
+          WHERE (current.attempts = 0 OR current.next_attempt_at <= now())
+            AND (current.claimed_until IS NULL OR current.claimed_until <= now())
+            ${pending}
+            ${notDead}
+            ${matches("current")}
+            AND NOT EXISTS (
+              SELECT
+              FROM ${table} busy
+              WHERE busy.${runColumn} = current.${runColumn}
+                AND (busy.claimed_until > now() OR (busy.attempts > 0 AND busy.next_attempt_at > now()))
+                ${pending}
+                ${notDead}
+                ${matches("busy")}
+              OFFSET 0
+            )
+          ORDER BY current.${order}
+          LIMIT ${cap}
+          FOR UPDATE SKIP LOCKED
+        ), claimed AS (
+          UPDATE ${table} outbox
+          SET claimed_until = now() + (${claimMs} * interval '1 millisecond')
+          FROM candidates
+          WHERE outbox.id = candidates.id
+          RETURNING outbox.*
+        )
+        SELECT * FROM claimed ORDER BY ${order}
+      `;
+    });
 
   const claim: PgOutbox<Row>["claim"] = async (limit = batchSize) => {
     const cap = Math.min(Math.max(limit, 1), batchSize);
+    if (sequence !== null) return claimBatch(cap, sequence);
     const ordered =
       orderBy === null
         ? sql``
@@ -80,8 +159,9 @@ export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row
             SELECT 1
             FROM ${table} earlier
             WHERE earlier.${orderBy} = current.${orderBy}
-              AND earlier.delivered_at IS NULL
+              ${earlierPending}
               ${earlierNotDead}
+              ${matches("earlier")}
               AND (earlier.created_at, earlier.id) < (current.created_at, current.id)
           )
         `;
@@ -90,10 +170,11 @@ export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row
       WITH candidates AS MATERIALIZED (
         SELECT current.id
         FROM ${table} current
-        WHERE current.delivered_at IS NULL
-          ${notDead}
-          AND current.next_attempt_at <= now()
+        WHERE current.next_attempt_at <= now()
           AND (current.claimed_until IS NULL OR current.claimed_until <= now())
+          ${pending}
+          ${notDead}
+          ${matches("current")}
           ${ordered}
         ORDER BY current.next_attempt_at, current.created_at, current.id
         LIMIT ${cap}
@@ -107,30 +188,66 @@ export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row
     `;
   };
 
+  const retryLater = async (row: Row, error: unknown) => {
+    const attempts = row.attempts + 1;
+    const message = error instanceof Error ? error.message : String(error);
+    const delaySeconds = Math.min(300, 2 ** Math.min(attempts, 8));
+    const dead = maxAttempts === null ? sql`` : sql`dead_at = CASE WHEN ${attempts} >= ${maxAttempts} THEN now() ELSE dead_at END,`;
+    await sql`
+      UPDATE ${table}
+      SET attempts = ${attempts},
+          next_attempt_at = now() + (${delaySeconds} * interval '1 second'),
+          claimed_until = NULL,
+          ${dead}
+          last_error = ${message.slice(0, 1_000)}
+      WHERE id = ${row.id}::uuid ${pending} ${notDead} AND attempts = ${row.attempts}
+    `;
+    log.warn("Outbox delivery failed", { outboxId: row.id, attempts, error: message });
+  };
+
   const dispatch: PgOutbox<Row>["dispatch"] = async (row, publish = config.publish) => {
     try {
       await publish(row);
+      if (deleteDelivered) {
+        await sql`DELETE FROM ${table} WHERE id = ${row.id}::uuid AND attempts = ${row.attempts}`;
+        return;
+      }
       await sql`
         UPDATE ${table}
         SET delivered_at = now(), claimed_until = NULL, last_error = NULL
-        WHERE id = ${row.id}::uuid AND delivered_at IS NULL ${notDead} AND attempts = ${row.attempts}
+        WHERE id = ${row.id}::uuid ${pending} ${notDead} AND attempts = ${row.attempts}
       `;
     } catch (error) {
-      const attempts = row.attempts + 1;
-      const message = error instanceof Error ? error.message : String(error);
-      const delaySeconds = Math.min(300, 2 ** Math.min(attempts, 8));
-      const dead = maxAttempts === null ? sql`` : sql`dead_at = CASE WHEN ${attempts} >= ${maxAttempts} THEN now() ELSE dead_at END,`;
-      await sql`
-        UPDATE ${table}
-        SET attempts = ${attempts},
-            next_attempt_at = now() + (${delaySeconds} * interval '1 second'),
-            claimed_until = NULL,
-            ${dead}
-            last_error = ${message.slice(0, 1_000)}
-        WHERE id = ${row.id}::uuid AND delivered_at IS NULL ${notDead} AND attempts = ${row.attempts}
-      `;
-      log.warn("Outbox delivery failed", { outboxId: row.id, attempts, error: message });
+      await retryLater(row, error);
+    }
+  };
+
+  /** Publishes a claimed batch: keys concurrently, the rows of one key in order. A failed row releases the rest of its key. */
+  const dispatchBatch = async (rows: Row[]) => {
+    const delivered: string[] = [];
+    const runs = Map.groupBy(rows, (row) => row[runKey]);
+    const results = await Promise.allSettled(
+      [...runs.values()].map(async (run) => {
+        for (const [index, row] of run.entries()) {
+          try {
+            await config.publish(row);
+          } catch (error) {
+            await retryLater(row, error);
+            const rest = run.slice(index + 1).map((later) => later.id);
+            if (rest.length > 0) await sql`UPDATE ${table} SET claimed_until = NULL WHERE id = ANY(${sql.array(rest, "uuid")})`;
+            return;
+          }
+          delivered.push(row.id);
+        }
+      }),
+    );
+    if (delivered.length > 0) {
+      const ids = sql.array(delivered, "uuid");
+      await (deleteDelivered
+        ? sql`DELETE FROM ${table} WHERE id = ANY(${ids})`
+        : sql`UPDATE ${table} SET delivered_at = now(), claimed_until = NULL, last_error = NULL WHERE id = ANY(${ids})`);
     }
+    for (const result of results) if (result.status === "rejected") throw result.reason;
   };
 
   let activeReconcile: Promise<number> | null = null;
@@ -140,19 +257,22 @@ export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row
     reconcileRequested = true;
     if (activeReconcile) return activeReconcile;
     activeReconcile = (async () => {
-      const deadExpired = maxAttempts === null ? sql`` : sql`OR dead_at < now() - ${DEAD_RETENTION}::interval`;
-      await sql`
-        DELETE FROM ${table}
-        WHERE delivered_at < now() - ${DELIVERED_RETENTION}::interval
-           ${deadExpired}
-      `;
+      if (!deleteDelivered) {
+        const deadExpired = maxAttempts === null ? sql`` : sql`OR dead_at < now() - ${DEAD_RETENTION}::interval`;
+        await sql`
+          DELETE FROM ${table}
+          WHERE delivered_at < now() - ${DELIVERED_RETENTION}::interval
+             ${deadExpired}
+        `;
+      }
       let processed = 0;
       let rows: Row[];
       do {
         reconcileRequested = false;
         rows = await claim();
-        // Sequential: a claimed batch may contain ordered rows of one key.
-        for (const row of rows) await dispatch(row);
+        if (sequence !== null) await dispatchBatch(rows);
+        // Sequential: across keys, the claim order is the publish order.
+        else for (const row of rows) await dispatch(row);
         processed += rows.length;
       } while (reconcileRequested || rows.length > 0);
       return processed;