@k2b/cloud 0.29.0 → 0.30.0

package/src/contracts/registry.ts

@@ -88,6 +88,7 @@ export type AppRegistryEntry = {
   adminNav?: AppAdminNavigationGroup[];
   capabilities?: AppRegistryCapabilitySummary;
   help?: AppRegistryHelpSummary;
+  skills?: { manifestHash: string };
   legalLinks?: AppRegistryLegalLink[];
   searchLinks?: readonly AppSearchLink[];
   /** The app's part of the mobile app (preview); `href` is `/pwa/<id>`. Older readers ignore it. */

package/src/contracts/shared.ts

@@ -329,6 +329,11 @@ export const AccessEntrySchema = z.object({
   avatarHash: z.string().nullable().optional(),
   /** Kind of a `service_account` principal; presentation only, never authorization. */
   serviceAccountKind: ServiceAccountKindSchema.optional(),
+  /**
+   * A narrower part of the resource the grant covers, defined by the application, such as Mail's
+   * `assigned` conversations. Absent for a grant on the whole resource.
+   */
+  scope: z.string().min(1).max(64).optional(),
 });
 export type AccessEntry = z.infer<typeof AccessEntrySchema>;
 

package/src/contracts/widgets.ts

@@ -181,3 +181,23 @@ export const WidgetResponseSchema = z
   })
   .strip();
 export type WidgetResponse = z.infer<typeof WidgetResponseSchema>;
+
+/** A widget's stable key on the dashboard and in the widget stream: `<appId>/<widgetId>`. */
+export const widgetKey = (appId: string, widgetId: string): string => `${appId}/${widgetId}`;
+
+/**
+ * How one widget answered in the widget stream: `ok` carries its response, `empty` is a `204`, `forbidden` a `403`,
+ * `timeout` means it did not answer within its own budget, and `error` covers every other failure.
+ */
+export type WidgetStreamStatus = "ok" | "empty" | "forbidden" | "timeout" | "error";
+
+/**
+ * One line of `GET /api/widgets/v1` (`application/x-ndjson`): `start` names the widgets Core asks, in registry
+ * order; one `widget` line follows per widget in the order they finish; `done` closes the stream. Every widget named
+ * in `start` gets exactly one line.
+ */
+export type WidgetStreamLine =
+  | { type: "start"; widgets: string[] }
+  | { type: "widget"; key: string; status: "ok"; widget: WidgetResponse; ms: number }
+  | { type: "widget"; key: string; status: Exclude<WidgetStreamStatus, "ok">; ms: number }
+  | { type: "done"; status: "complete" | "partial" };

package/src/index.ts

@@ -35,6 +35,7 @@ export {
 export type { RuntimeCompatibilityIssue } from "./_internal/runtime-compatibility";
 export { assessRuntimeCompatibility } from "./_internal/runtime-compatibility";
 export { buildRuntimeFromRegistry } from "./_internal/runtime-context";
+export { type AppSkillDefinition, skill } from "./ai/app-skills";
 export { defineCapabilities } from "./contracts/capabilities";
 export type {
   AnyBoundNotificationDefinition,

package/src/server/help.ts

@@ -3,6 +3,7 @@ import { parse as parseYaml } from "yaml";
 import { z } from "zod";
 import { type HelpDocumentManifest, type HelpDocumentPayload, type HelpSearchPayload, helpLocaleChain } from "../shared/help";
 import { markdownToPlainText, renderHelpMarkdown } from "../shared/markdown";
+import { auth } from "./middleware/auth";
 
 const metadataSchema = z.object({
   id: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
@@ -133,6 +134,9 @@ export const defineHelp = (
  * Define one app-owned help corpus. The explicit source list is deliberate:
  * IDs, ordering and ownership stay visible in code; no filesystem scanning or
  * build-time convention is required.
+ *
+ * @deprecated Declare Help with `defineHelp()` and pass it to `app.start({ help })`. This router only
+ * requires sign-in; it does not apply the app's Help visibility, so the mounting app's routes must guard it.
  */
 export const defineHelpCollection = (options: { basePath: string; sources: readonly string[] }): HelpCollection => {
   const basePath = options.basePath.replace(/\/$/, "");
@@ -151,7 +155,10 @@ export const defineHelpCollection = (options: { basePath: string; sources: reado
     url: `${basePath}/${encodeURIComponent(id)}`,
   }));
 
-  const router = new Hono()
+  // Help is for signed-in people wherever an app mounts this router; its own route policy may narrow it further.
+  const router = new Hono();
+  router.use(auth.requireRole("authenticated"), auth.requireUser());
+  router
     .get("/search", (context) => {
       const query = context.req.query("q")?.trim().toLocaleLowerCase().slice(0, 200) ?? "";
       const payload: HelpSearchPayload = {

package/src/services/accounts/users.ts

@@ -223,6 +223,21 @@ export const getMinimal = async (params: { id: string } | { uid: string }): Prom
   return buildUserMutationTarget(rows[0]!);
 };
 
+/** Audience roles for a resolved access subject, including delegated users and group managers. */
+export const getRoles = async (userId: string): Promise<Role[]> => {
+  const { groupsAdmin } = await getFreeIpaConfig();
+  const [row] = await sql<DbRow[]>`SELECT u.provider, u.profile,
+    CASE WHEN u.provider='local' THEN u.admin ELSE EXISTS (
+      SELECT 1 FROM auth.ipa_user_effective_groups eg WHERE eg.user_id=u.id
+        AND eg.group_name=ANY(${toPgTextArray(groupsAdmin)}::text[])
+    ) END AS effective_admin,
+    ARRAY(${managedGroupsNamesSubquery(sql`u.id`)}) AS manages
+    FROM auth.users u WHERE u.id=${userId}::uuid`;
+  if (!row) return [];
+  const { provider, profile } = resolveProviderProfile(row);
+  return buildRoles({ provider, profile, memberofGroup: [], manages: stringArray(row.manages), admin: Boolean(row.effective_admin) });
+};
+
 export const getByUid = async (params: { uid: string }): Promise<{ id: string; roles: Role[] } | null> => {
   const { groupsAdmin } = await getFreeIpaConfig();
   const rows = await sql<DbRow[]>`

package/src/services/help/index.ts

@@ -1,6 +1,8 @@
 import { type SQL, sql } from "bun";
+import { appAudienceRoles, hasAnyAppRole } from "../../_internal/app-roles";
 import { getApp, listApps } from "../../_internal/registry";
 import type { AppRegistryEntry } from "../../contracts/registry";
+import type { RequestActor } from "../../contracts/shared";
 import { resolveAppPresentations } from "../../shared/app-presentation";
 import { helpLocaleChain } from "../../shared/help";
 import { logger } from "../logging";
@@ -12,8 +14,20 @@ export type { HelpArticle, HelpMatch, HelpMetadata, HelpReader, HelpReaderFactor
 
 const log = logger("help");
 
+/**
+ * Help follows the app's declared visibility: it needs a user (the person, or the user an API credential acts
+ * for), the app's navigation roles limit it, and an app reached only through the admin area is for admins.
+ * The app's routes still authorize the app itself.
+ */
+export const canReadAppHelp = (app: Pick<AppRegistryEntry, "nav">, viewer: RequestActor | undefined): boolean => {
+  const user = viewer?.kind === "user" ? viewer.user : (viewer?.delegatedUser ?? undefined);
+  return !!user && hasAnyAppRole(user, appAudienceRoles(app.nav));
+};
+
+/** Reads Help in one language for one viewer; apps the viewer may not see do not exist for this reader. */
 export const createHelpReader = (
   locale: string,
+  viewer: RequestActor | undefined,
   dependencies: {
     db?: SQL;
     listApps?: () => Promise<AppRegistryEntry[]>;
@@ -21,11 +35,10 @@ export const createHelpReader = (
   } = {},
 ): HelpReader => {
   const db = dependencies.db ?? sql;
+  const visible = (app: AppRegistryEntry | null): app is AppRegistryEntry => app !== null && canReadAppHelp(app, viewer);
   const select = async (appId?: string): Promise<HelpSelection[]> => {
-    const apps = appId
-      ? [await (dependencies.getApp ?? getApp)(appId)].filter((app): app is AppRegistryEntry => app !== null)
-      : await (dependencies.listApps ?? listApps)();
-    return resolveAppPresentations(apps, locale).flatMap((app) =>
+    const apps = appId ? [await (dependencies.getApp ?? getApp)(appId)] : await (dependencies.listApps ?? listApps)();
+    return resolveAppPresentations(apps.filter(visible), locale).flatMap((app) =>
       app.help
         ? [
             {
@@ -41,7 +54,7 @@ export const createHelpReader = (
   return {
     async manifest(appId) {
       const app = await (dependencies.getApp ?? getApp)(appId);
-      if (!app?.help) return null;
+      if (!visible(app) || !app.help) return null;
       const [corpus] = await db`SELECT 1 FROM help.corpora WHERE app_id=${app.id} AND manifest_hash=${app.help.manifestHash}`;
       if (!corpus) return null;
       const rows = await queryHelp(

package/src/services/help/types.ts

@@ -1,4 +1,5 @@
 import type { AppRegistryHelpSummary } from "../../contracts/registry";
+import type { RequestActor } from "../../contracts/shared";
 import type { HelpDocumentManifest } from "../../shared/help";
 
 export type HelpDocument = {
@@ -36,11 +37,11 @@ export type HelpSearchInput = { query: string; appId?: string; limit?: number };
 export type HelpReadInput = { appId: string; documentId: string };
 export type HelpManifestResult = AppRegistryHelpSummary & { locale: string; documents: readonly HelpDocumentManifest[] };
 
-/** One request's language; operations resolve the current published app versions. */
+/** One request's language and viewer; operations resolve the current published versions of the apps the viewer may see. */
 export type HelpReader = {
   manifest(appId: string): Promise<HelpManifestResult | null>;
   list(cursor?: string): Promise<HelpMetadata[]>;
   search(input: HelpSearchInput): Promise<HelpMatch[]>;
   read(input: HelpReadInput): Promise<HelpArticle | null>;
 };
-export type HelpReaderFactory = (locale: string) => HelpReader;
+export type HelpReaderFactory = (locale: string, viewer: RequestActor | undefined) => HelpReader;

package/src/services/identity/constants.ts

@@ -13,6 +13,8 @@ export const INVOCATION_CLOCK_TOLERANCE_SECONDS = 2;
 export const IDENTITY_JWKS_MAX_AGE_SECONDS = 5 * 60;
 export const IDENTITY_ACTIVATION_LEAD_MS = 10 * 60_000;
 export const IDENTITY_SIGNING_CACHE_MS = 60_000;
+/** Bounds a shared signer refresh or identity settings load; matches the default issuance deadline. */
+export const IDENTITY_REFRESH_TIMEOUT_MS = 30_000;
 export const IDENTITY_ROTATION_AGE_MS = 30 * 24 * 60 * 60_000;
 export const IDENTITY_ROLLOUT_MARGIN_MS = 10 * 60_000;
 export const IDENTITY_MAX_COMPACT_TOKEN_BYTES = 4 * 1024;

package/src/services/identity/key-ring.ts

@@ -6,6 +6,7 @@ import {
   CLOUD_IDENTITY_ALGORITHM,
   IDENTITY_ACTIVATION_LEAD_MS,
   IDENTITY_CLOCK_TOLERANCE_SECONDS,
+  IDENTITY_REFRESH_TIMEOUT_MS,
   IDENTITY_ROLLOUT_MARGIN_MS,
   IDENTITY_ROTATION_AGE_MS,
   IDENTITY_SIGNING_CACHE_MS,
@@ -76,6 +77,38 @@ const date = (value: Date | string): Date => (value instanceof Date ? value : ne
 const publicJwk = (value: JWK | string): JWK => (typeof value === "string" ? (JSON.parse(value) as JWK) : value);
 const serializedSize = (value: unknown): number => encoder.encode(JSON.stringify(value)).byteLength;
 
+const formatDuration = (ms: number): string => (ms % 1_000 === 0 ? `${ms / 1_000} s` : `${ms} ms`);
+
+/**
+ * Stops waiting for `work` once `signal` aborts. The work itself keeps running
+ * (a pooled query or a shared refresh cannot be cancelled from here), but the
+ * caller is released at its deadline instead of whenever the stall ends.
+ */
+const untilAborted = <V>(work: Promise<V>, signal: AbortSignal): Promise<V> => {
+  if (signal.aborted) {
+    work.catch(() => undefined);
+    return Promise.reject(signal.reason);
+  }
+  return new Promise<V>((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    work.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+  });
+};
+
+const timeoutSignal = (ms: number, reason: () => DOMException): { signal: AbortSignal; clear: () => void } => {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(reason()), ms);
+  return { signal: controller.signal, clear: () => clearTimeout(timer) };
+};
+
+/**
+ * A JS deadline alone cannot cancel a blocked PostgreSQL query. Bound each
+ * statement (including lock waits) on this connection, transaction-local.
+ */
+const boundStatements = (db: typeof sql, deadline: number) =>
+  db`SELECT set_config('statement_timeout', ${`${Math.max(1, Math.floor(deadline - Date.now()))}ms`}, true)`;
+
 const assertRsaJwk = (value: JWK, privateRequired: boolean): void => {
   if (value.kty !== "RSA" || typeof value.n !== "string" || typeof value.e !== "string") {
     throw new Error("Cloud identity key is not an RSA JWK");
@@ -156,8 +189,8 @@ const importRow = async (row: SigningKeyRow, keys: IdentityKeyEncryptionConfig):
   return { kid: row.kid, key, signUntil: date(row.sign_until) };
 };
 
-const selectRows = async (purpose: SigningKeyPurpose): Promise<SigningKeyRow[]> =>
-  sql<SigningKeyRow[]>`
+const selectRows = async (db: typeof sql, purpose: SigningKeyPurpose): Promise<SigningKeyRow[]> =>
+  db<SigningKeyRow[]>`
     SELECT id, purpose, state, kid, alg, public_jwk, encrypted_private_jwk, encryption_key_id,
       created_at, activate_at, activated_at, sign_until, retired_at, verify_until, revoked_at
     FROM auth.signing_keys
@@ -188,9 +221,16 @@ const insertKey = async (
   `;
 };
 
-const maintainPurpose = async (purpose: SigningKeyPurpose): Promise<SigningKeyRow> => {
+/**
+ * Every statement ends by `deadline`, so a refresh that its callers already
+ * gave up on does not keep holding a pooled connection.
+ */
+const maintainPurpose = async (purpose: SigningKeyPurpose, deadline: number): Promise<SigningKeyRow> => {
   const keys = await readIdentityKeyEncryptionConfig();
-  const before = await selectRows(purpose);
+  const before = await sql.begin(async (tx) => {
+    await boundStatements(tx, deadline);
+    return selectRows(tx, purpose);
+  });
   const beforeActive = before.find((row) => row.state === "active");
   const beforePending = before.find((row) => row.state === "pending");
   const nowMs = Date.now();
@@ -205,6 +245,8 @@ const maintainPurpose = async (purpose: SigningKeyPurpose): Promise<SigningKeyRo
       ? await generateEncryptedKey(keys)
       : null;
   const active = await sql.begin(async (tx) => {
+    // Another replica's stuck rotation must not hold this refresh forever.
+    await boundStatements(tx, deadline);
     await tx`SELECT pg_advisory_xact_lock(hashtextextended(${`cloud:identity-keyring:${purpose}`}, 0))`;
     const rows = await tx<SigningKeyRow[]>`
       SELECT id, purpose, state, kid, alg, public_jwk, encrypted_private_jwk, encryption_key_id,
@@ -289,10 +331,24 @@ export const prepareIdentitySigner = async (purpose: SigningKeyPurpose): Promise
   return signerRefreshes.run(
     purpose,
     async () => {
+      // Every caller joins this refresh. Bound it, so one hung connection
+      // cannot hold back every later issuance until TCP gives up.
+      const deadline = Date.now() + IDENTITY_REFRESH_TIMEOUT_MS;
+      const bound = timeoutSignal(
+        IDENTITY_REFRESH_TIMEOUT_MS,
+        () =>
+          new DOMException(
+            `Cloud identity signer refresh did not finish within ${formatDuration(IDENTITY_REFRESH_TIMEOUT_MS)}`,
+            "TimeoutError",
+          ),
+      );
       try {
-        const keys = await readIdentityKeyEncryptionConfig();
-        const row = await maintainPurpose(purpose);
-        const signer = await importRow(row, keys);
+        const refresh = async () => {
+          const keys = await readIdentityKeyEncryptionConfig();
+          const row = await maintainPurpose(purpose, deadline);
+          return importRow(row, keys);
+        };
+        const signer = await untilAborted(refresh(), bound.signal);
         if (signer.signUntil.getTime() <= now) throw new Error(`Active ${purpose} signing key is past sign_until`);
         return signer;
       } catch (error) {
@@ -300,6 +356,8 @@ export const prepareIdentitySigner = async (purpose: SigningKeyPurpose): Promise
         log.error("Cloud identity signer refresh failed", { purpose, error: error instanceof Error ? error.message : String(error) });
         if (cached && cached.signer.signUntil.getTime() > now) return cached.signer;
         throw error;
+      } finally {
+        bound.clear();
       }
     },
     (signer) => {
@@ -313,6 +371,10 @@ export const prepareIdentitySigner = async (purpose: SigningKeyPurpose): Promise
  * The shared row lock makes emergency revocation wait for already-started
  * issuance and prevents replicas from releasing a new result under that key
  * after the revocation commits.
+ *
+ * `timeoutMs` bounds the whole call: signer refresh, identity settings, the
+ * wait for a connection and the key check. The caller is released at the
+ * deadline with a `TimeoutError` that names the step that stalled.
  */
 export const withActiveIdentitySigner = async <T>(
   purpose: SigningKeyPurpose,
@@ -322,42 +384,61 @@ export const withActiveIdentitySigner = async <T>(
   const timeoutMs = options.timeoutMs ?? 30_000;
   if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error("Identity issuance timeout must be positive");
   const deadline = Date.now() + timeoutMs;
-  const checkDeadline = () => {
-    options.signal?.throwIfAborted();
-    if (Date.now() >= deadline) throw new DOMException("Identity issuance deadline exceeded", "TimeoutError");
+  let step = "signer refresh";
+  const expired = () => new DOMException(`Identity service did not respond within ${formatDuration(timeoutMs)} (${step})`, "TimeoutError");
+  const bound = timeoutSignal(timeoutMs, expired);
+  const signal = options.signal ? AbortSignal.any([options.signal, bound.signal]) : bound.signal;
+  // The timer releases a waiting caller. The clock also catches a timer that a
+  // busy event loop delivers late, and a statement Postgres cancels first.
+  const check = () => {
+    signal.throwIfAborted();
+    if (Date.now() >= deadline) throw expired();
   };
-  // Preparation can refresh/rotate keys using the pool. Never do it while
-  // holding a caller's transaction: every issuance needs just one connection.
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    checkDeadline();
-    const signer = await prepareIdentitySigner(purpose);
-    const { issuer } = await getIdentityRuntimeConfig();
-    checkDeadline();
-    const run = async (db: typeof sql): Promise<{ active: false } | { active: true; result: T }> => {
-      checkDeadline();
-      // A JS deadline alone cannot cancel a blocked PostgreSQL query. Bound
-      // each statement (including lock waits) on this connection, transaction-local.
-      await db`SELECT set_config('statement_timeout', ${`${Math.max(1, Math.floor(deadline - Date.now()))}ms`}, true)`;
-      const [active] = await db<Array<{ kid: string }>>`
-        SELECT kid
-        FROM auth.signing_keys
-        WHERE kid = ${signer.kid}
-          AND purpose = ${purpose}
-          AND state = 'active'
-          AND sign_until > now()
-        FOR SHARE
-      `;
-      checkDeadline();
-      if (!active) return { active: false };
-      const result = await callback({ ...signer, issuer }, db);
-      return { active: true, result };
-    };
-    const checked = await (options.pool ?? sql).begin(run);
-    checkDeadline();
-    if (checked.active) return checked.result;
-    invalidateIdentitySignerCache(purpose, signer.kid);
+  const wait = <V>(name: string, work: () => Promise<V>): Promise<V> => {
+    check();
+    step = name;
+    return untilAborted(work(), signal);
+  };
+  try {
+    // Preparation can refresh/rotate keys using the pool. Never do it while
+    // holding a caller's transaction: every issuance needs just one connection.
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      const signer = await wait("signer refresh", () => prepareIdentitySigner(purpose));
+      const { issuer } = await wait("identity settings", getIdentityRuntimeConfig);
+      const run = async (db: typeof sql): Promise<{ active: false } | { active: true; result: T }> => {
+        // A caller released at its deadline must not sign once a connection frees up.
+        check();
+        step = "signing key check";
+        await boundStatements(db, deadline);
+        const [active] = await db<Array<{ kid: string }>>`
+          SELECT kid
+          FROM auth.signing_keys
+          WHERE kid = ${signer.kid}
+            AND purpose = ${purpose}
+            AND state = 'active'
+            AND sign_until > now()
+          FOR SHARE
+        `;
+        check();
+        if (!active) return { active: false };
+        step = "signing";
+        const result = await callback({ ...signer, issuer }, db);
+        // Roll back what the callback wrote instead of committing a result the caller never gets.
+        check();
+        return { active: true, result };
+      };
+      const checked = await wait("database connection", () => (options.pool ?? sql).begin(run));
+      check();
+      if (checked.active) return checked.result;
+      invalidateIdentitySignerCache(purpose, signer.kid);
+    }
+    throw new Error(`No active ${purpose} identity signer is available`);
+  } catch (error) {
+    check();
+    throw error;
+  } finally {
+    bound.clear();
   }
-  throw new Error(`No active ${purpose} identity signer is available`);
 };
 
 export const initializeIdentityAuthority = async (): Promise<void> => {
@@ -474,7 +555,7 @@ const maintainVerificationWindows = async (): Promise<void> => {
 };
 
 export const runIdentityKeyMaintenance = async (): Promise<void> => {
-  for (const purpose of SIGNING_KEY_PURPOSES) await maintainPurpose(purpose);
+  for (const purpose of SIGNING_KEY_PURPOSES) await maintainPurpose(purpose, Date.now() + IDENTITY_REFRESH_TIMEOUT_MS);
   await maintainVerificationWindows();
   await sql`
     DELETE FROM auth.session_families

package/src/services/identity/runtime-config.ts

@@ -1,7 +1,7 @@
 import { env } from "../../config/env";
 import { publicCloudOrigin } from "../../shared/app-url";
 import { get as getSetting } from "../settings";
-import { CLOUD_INVOCATION_JWKS_PATH, CLOUD_OAUTH_JWKS_PATH, CLOUD_SESSION_JWKS_PATH } from "./constants";
+import { CLOUD_INVOCATION_JWKS_PATH, CLOUD_OAUTH_JWKS_PATH, CLOUD_SESSION_JWKS_PATH, IDENTITY_REFRESH_TIMEOUT_MS } from "./constants";
 
 const RUNTIME_CONFIG_TTL_MS = 60_000;
 
@@ -73,7 +73,18 @@ export const getIdentityRuntimeConfig = async (): Promise<IdentityRuntimeConfig>
   const now = Date.now();
   if (cached && cached.expiresAt > now) return cached.value;
   if (loading) return loading;
-  loading = load()
+  // Every caller joins this load. Bound it like the signer refresh, so one hung
+  // settings read cannot hold back every later caller; the next one starts over.
+  loading = new Promise<IdentityRuntimeConfig>((resolve, reject) => {
+    const timer = setTimeout(
+      () =>
+        reject(new DOMException(`Cloud identity settings did not load within ${IDENTITY_REFRESH_TIMEOUT_MS / 1_000} s`, "TimeoutError")),
+      IDENTITY_REFRESH_TIMEOUT_MS,
+    );
+    load()
+      .then(resolve, reject)
+      .finally(() => clearTimeout(timer));
+  })
     .then((value) => {
       cached = { value, expiresAt: Date.now() + RUNTIME_CONFIG_TTL_MS };
       return value;

package/src/services/outbox.ts

@@ -12,10 +12,11 @@ import { logger } from "./logging";
  * 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`.
+ * then completes the batch in one statement. A batch starts no publish after
+ * its claim has ended, because the next claim takes its rows. 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`, `last_error text`, and the `orderBy` and
@@ -52,7 +53,9 @@ export type PgOutboxConfig<Row extends OutboxRow> = {
 };
 
 export type PgOutbox<Row extends OutboxRow> = {
+  /** @internal Test seam; applications use `reconcile`, `notify`, `start`, and `stop`. */
   claim(limit?: number): Promise<Row[]>;
+  /** @internal Test seam; it publishes one row outside the order of its key. */
   dispatch(row: Row, publish?: (row: Row) => Promise<unknown>): Promise<void>;
   /** Drain every claimable row; concurrent calls join the active pass. */
   reconcile(): Promise<number>;
@@ -78,7 +81,10 @@ export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row
   const filters = Object.entries(config.where ?? {}).map(([column, value]) => ({ column: identifier(column, "filter column"), value }));
   const matches = (alias: "current" | "busy") =>
     filters.reduce((fragment, { column, value }) => sql`${fragment} AND ${sql.unsafe(alias)}.${column} = ${value}`, sql``);
-  const claimLock = `${config.table}:${JSON.stringify(config.where ?? {})}`;
+  // Sorted, so the order of the `where` entries cannot give one outbox two locks. Descending keeps the
+  // lock that live outboxes (`kind`, `app_id`) always took, so replicas of two releases share it.
+  const where = Object.entries(config.where ?? {}).sort(([left], [right]) => (left < right ? 1 : -1));
+  const claimLock = `${config.table}:${JSON.stringify(Object.fromEntries(where))}`;
 
   /**
    * Claims rows in sequence order, several per key, and never a row of a key
@@ -151,19 +157,26 @@ export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row
     }
   };
 
-  /** 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[]) => {
+  /**
+   * Publishes a claimed batch: keys concurrently, the rows of one key in order. A failed row releases the rest of its key.
+   * A run starts no publish once the claim has ended (`claimEnds`, monotonic): another replica may own the rest by then.
+   */
+  const dispatchBatch = async (rows: Row[], claimEnds: number) => {
     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()) {
+          if (performance.now() >= claimEnds) return;
           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")})`;
+            // Past the claim, the rest is free already, and releasing it could end another replica's claim.
+            if (rest.length > 0 && performance.now() < claimEnds) {
+              await sql`UPDATE ${table} SET claimed_until = NULL WHERE id = ANY(${sql.array(rest, "uuid")})`;
+            }
             return;
           }
           delivered.push(row.id);
@@ -185,8 +198,10 @@ export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row
       let rows: Row[];
       do {
         reconcileRequested = false;
+        // Taken before the claim, so it ends no later than the `claimed_until` the claim sets.
+        const claimEnds = performance.now() + claimMs;
         rows = await claim();
-        await dispatchBatch(rows);
+        await dispatchBatch(rows, claimEnds);
         processed += rows.length;
       } while (reconcileRequested || rows.length > 0);
       return processed;

package/src/services/outgoing-mail/index.ts

@@ -19,11 +19,15 @@ import { outgoingMailMessages, recordMailBatch, recordMailSend } from "./message
 import { sendMail } from "./send";
 import { OutgoingMailError, outgoingMailStore } from "./store";
 
-const identity = (): Result<string, MailServiceError> => {
+const identity = (read = false): Result<string, MailServiceError> => {
   const appId = getProcessApplicationId();
   if (!appId) return fail({ code: "mail_unavailable", message: "Start the application before using outgoing mail.", status: 500 });
-  if (!getProcessPlatformPermissions().includes("mail:send"))
-    return fail({ code: "mail_not_declared", message: 'Declare platformPermissions: ["mail:send"].', status: 403 });
+  if (!getProcessPlatformPermissions().includes("mail:send") && !(read && getProcessPlatformPermissions().includes("mail:read")))
+    return fail({
+      code: "mail_not_declared",
+      message: read ? 'Declare "mail:send" or "mail:read" in platformPermissions.' : 'Declare platformPermissions: ["mail:send"].',
+      status: 403,
+    });
   return ok(appId);
 };
 const failure = (error: unknown): MailServiceError => {
@@ -39,6 +43,16 @@ const failure = (error: unknown): MailServiceError => {
   };
 };
 export const mail = {
+  async readableApps(): Promise<Result<string[], MailServiceError>> {
+    const caller = identity(true);
+    if (!caller.ok) return caller;
+    try {
+      const granted = getProcessPlatformPermissions().includes("mail:read") ? await outgoingMailStore.logAppsFor(caller.data) : [];
+      return ok([caller.data, ...granted.filter((appId) => appId !== caller.data && appId !== "core").sort()]);
+    } catch (error) {
+      return fail(failure(error));
+    }
+  },
   async enqueue(messages: MailMessage[]): Promise<Result<{ batchId: string; ids: string[] }, MailServiceError>> {
     const caller = identity();
     const parsed = caller.ok ? MailBatchSchema.safeParse(messages) : undefined;
@@ -97,14 +111,28 @@ export const mail = {
     }
   },
   async list(filter: MailFilter = {}, page: MailPageParams = {}): Promise<Result<MailPage, MailServiceError>> {
-    const caller = identity();
+    const caller = identity(true);
     if (!caller.ok) return caller;
     const parsedFilter = MailFilterSchema.safeParse(filter);
     const parsedPage = MailPageParamsSchema.safeParse(page);
     if (!parsedFilter.success || !parsedPage.success)
       return fail({ code: "bad_input", message: "Invalid outgoing mail filter or page.", status: 400 });
     try {
-      return ok(await outgoingMailMessages.list({ ...parsedFilter.data, app: caller.data }, parsedPage.data));
+      const { apps = [caller.data], recipient, ...filter } = parsedFilter.data;
+      const otherApps = apps.filter((appId) => appId !== caller.data);
+      if (otherApps.length) {
+        if (!getProcessPlatformPermissions().includes("mail:read"))
+          return fail({
+            code: "mail_not_declared",
+            message: 'Declare "mail:read" in platformPermissions to read other apps’ mail logs.',
+            status: 403,
+          });
+        const granted = await outgoingMailStore.logAppsFor(caller.data);
+        const denied = otherApps.find((appId) => !granted.includes(appId));
+        if (denied)
+          return fail({ code: "app_not_allowed", message: `This application may not read the mail log of "${denied}".`, status: 403 });
+      }
+      return ok(await outgoingMailMessages.list({ ...filter, apps, recipientExact: recipient }, parsedPage.data, false, caller.data));
     } catch (error) {
       return fail(failure(error));
     }