@k2b/cloud 0.28.0 → 0.29.1

package/src/services/notifications/dispatcher.ts

@@ -2,6 +2,7 @@ import { sql } from "bun";
 import { z } from "zod";
 import { decryptSecret } from "../secrets";
 import { getNotificationChannel } from "./channels";
+import { quietStateForEvent } from "./quiet";
 
 const MAX_DELIVERY_ATTEMPTS = 5;
 const BASE_RETRY_MS = 2_000;
@@ -19,12 +20,40 @@ type DeliveryRow = {
 };
 
 export type DeliveryAttemptResult =
-  | { status: "skipped" | "delivered" | "failed" }
+  | { status: "skipped" | "delivered" | "suppressed" | "failed" }
   | { status: "pending"; retryAfterMs: number }
   | { status: "retry"; retryAfterMs: number; error: string };
 
 const retryDelay = (attempt: number): number => Math.min(BASE_RETRY_MS * 2 ** Math.max(0, attempt - 1), MAX_RETRY_MS);
 
+/**
+ * Do not disturb and quiet hours hold back recommended browser notifications when they would go out. The
+ * notification is dropped, not postponed, so nothing arrives in a burst when the quiet time ends, and it is not
+ * rerouted: the event's waiting fallbacks end with it. Required deliveries are part of a protocol and still go.
+ */
+const holdBackForQuietTime = async (delivery: DeliveryRow): Promise<boolean> => {
+  if (delivery.channel !== "browser" || delivery.required) return false;
+  const quiet = await quietStateForEvent(delivery.event_id);
+  if (!quiet?.active) return false;
+  const code = quiet.reason === "doNotDisturb" ? "do_not_disturb" : "quiet_hours";
+  const message = quiet.reason === "doNotDisturb" ? "Held back by do not disturb." : "Held back during quiet hours.";
+  // One transaction: a crash in between must not leave fallbacks waiting, with their payload, behind a dropped push.
+  await sql.begin(async (tx) => {
+    await tx`
+      UPDATE notifications.deliveries
+      SET status = 'suppressed', attempt_count = attempt_count - 1, next_attempt_at = NULL,
+          error_code = ${code}, error_message = ${message}, payload_encrypted = NULL, updated_at = now()
+      WHERE id = ${delivery.id}::uuid AND status = 'sending'
+    `;
+    await tx`
+      UPDATE notifications.deliveries
+      SET status = 'suppressed', error_code = ${code}, error_message = ${message}, payload_encrypted = NULL, updated_at = now()
+      WHERE event_id = ${delivery.event_id}::uuid AND required = false AND status = 'deferred'
+    `;
+  });
+  return true;
+};
+
 const activateNextFallback = async (eventId: string): Promise<string[]> => {
   const delivered = await sql<{ exists: boolean }[]>`
     SELECT EXISTS (
@@ -85,6 +114,7 @@ export const processNotificationDelivery = async (
   if (!delivery) return { status: "skipped" };
 
   try {
+    if (await holdBackForQuietTime(delivery)) return { status: "suppressed" };
     const driver = getNotificationChannel(delivery.channel);
     if (!driver)
       throw Object.assign(new Error(`Notification channel "${delivery.channel}" is unavailable`), { code: "channel_unavailable" });

package/src/services/notifications/platform.ts

@@ -1,5 +1,6 @@
 import { sql } from "bun";
 import type { output, ZodType } from "zod";
+import { isNotificationGroup, notificationGroupTag } from "../../contracts/notification-group";
 import type {
   BoundNotificationDefinition,
   EmailNotificationPresentation,
@@ -15,6 +16,7 @@ import { encryptSecret } from "../secrets";
 import { ensureNotificationDefinition } from "./catalog";
 import { getNotificationChannel, type NotificationDestination, type ResolvedNotificationRecipient } from "./channels";
 import { processNotificationDelivery } from "./dispatcher";
+import { normalizeNotificationPreview } from "./preview";
 import { enqueueNotificationDeliveries, enqueueNotificationDelivery } from "./runtime";
 
 export type TypedNotificationDeliveryStatus = "deferred" | "pending" | "sending" | "delivered" | "suppressed" | "failed";
@@ -69,14 +71,38 @@ const preparationFailure = (input: { channel: string; required: boolean; routePr
   errorMessage: "Notification delivery could not be prepared.",
 });
 
-const validatePresentation = (presentation: NotificationPresentation): NotificationPresentation => {
+const validatePresentation = (presentation: NotificationPresentation, appId: string): NotificationPresentation => {
   const title = presentation.title.trim();
   const body = presentation.body?.trim();
+  if (presentation.preview !== undefined && typeof presentation.preview !== "string") {
+    throw new Error("Notification preview must be a string");
+  }
+  const preview = presentation.preview === undefined ? undefined : normalizeNotificationPreview(presentation.preview);
   if (!title) throw new Error("Notification title is required");
   if (title.length > 200) throw new Error("Notification title must not exceed 200 characters");
   if (body && body.length > 4_000) throw new Error("Notification body must not exceed 4000 characters");
   const targetHref = presentation.targetHref ? validateNotificationTargetHref(presentation.targetHref) : undefined;
-  return { title, ...(body ? { body } : {}), ...(targetHref ? { targetHref } : {}) };
+  if (presentation.group !== undefined && !isNotificationGroup(presentation.group)) {
+    throw new Error(
+      "Notification group must contain 1 to 128 characters using only letters, digits, dots, underscores, colons, or hyphens",
+    );
+  }
+  if (presentation.group !== undefined && notificationGroupTag(appId, presentation.group) === null) {
+    throw new Error(
+      "Notification group requires an app ID that starts with a lowercase letter and contains only lowercase letters, digits, and hyphens",
+    );
+  }
+  if (presentation.badge !== undefined && (!Number.isSafeInteger(presentation.badge) || presentation.badge < 0)) {
+    throw new Error("Notification badge must be a non-negative safe integer");
+  }
+  return {
+    title,
+    ...(body ? { body } : {}),
+    ...(preview ? { preview } : {}),
+    ...(targetHref ? { targetHref } : {}),
+    ...(presentation.group !== undefined ? { group: presentation.group } : {}),
+    ...(presentation.badge !== undefined ? { badge: presentation.badge } : {}),
+  };
 };
 
 const resolveRecipient = async (
@@ -172,6 +198,8 @@ const prepareChannel = async (input: {
 
   try {
     const emailPresentation = input.channel === "email" ? await input.emailPresentation?.() : undefined;
+    const { preview: _preview, ...otherPresentation } = input.presentation;
+    const presentation = input.channel === "browser" ? input.presentation : otherPresentation;
     return await Promise.all(
       destinations.map(async (destination) => ({
         channel: input.channel,
@@ -179,7 +207,7 @@ const prepareChannel = async (input: {
         destinationKey: destination.key,
         destinationLabel: destination.label,
         payloadEncrypted: await encryptSecret(
-          driver.createPayload({ presentation: input.presentation, email: emailPresentation, destination, event: input.event }),
+          driver.createPayload({ presentation, email: emailPresentation, destination, event: input.event }),
         ),
         required: input.required,
         routePriority: input.routePriority,
@@ -241,7 +269,7 @@ export const sendTypedNotification = async <
 
   const data: output<S> = definition.data.parse(input.data);
   const renderContext = { locale: normalizeLocale(input.locale) };
-  const presentation = validatePresentation(await definition.render(data, renderContext));
+  const presentation = validatePresentation(await definition.render(data, renderContext), definition.appId);
   const resolved = await resolveRecipient(input.recipient);
   const candidateEventId = crypto.randomUUID();
   await ensureNotificationDefinition(definition);

package/src/services/notifications/preview.ts

@@ -0,0 +1,23 @@
+export const NOTIFICATION_PREVIEW_LIMIT = 200;
+const PREVIEW_INPUT_LIMIT = 1_000;
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+export const normalizeNotificationPreview = (value: string): string | undefined => {
+  let prefix = value.slice(0, PREVIEW_INPUT_LIMIT);
+  const clipped = value.length > prefix.length;
+  if (clipped) {
+    // A boundary at or before the bound depends on at most one following code point (two UTF-16 units).
+    const last = segmenter.segment(value.slice(0, PREVIEW_INPUT_LIMIT + 2)).containing(PREVIEW_INPUT_LIMIT - 1);
+    if (last && last.index + last.segment.length > PREVIEW_INPUT_LIMIT) prefix = prefix.slice(0, last.index);
+  }
+  const text = prefix.replace(/[\s\p{Cc}]+/gu, " ").trim();
+  if (!text) return undefined;
+  if (!clipped && text.length <= NOTIFICATION_PREVIEW_LIMIT) return text;
+
+  let end = 0;
+  for (const { segment, index } of segmenter.segment(text)) {
+    if (index + segment.length > NOTIFICATION_PREVIEW_LIMIT - 1) break;
+    end = index + segment.length;
+  }
+  return `${text.slice(0, end).trimEnd()}…`;
+};

package/src/services/notifications/quiet.ts

@@ -0,0 +1,153 @@
+import { dates } from "@k2b/stdlib";
+import { sql } from "bun";
+import type { MutationResult } from "../../contracts/shared";
+import {
+  NOTIFICATION_DO_NOT_DISTURB_MAX_DAYS,
+  type NotificationQuietHours,
+  NotificationQuietHoursSchema,
+  type NotificationQuietSettings,
+  type NotificationQuietState,
+  type UpdateNotificationQuietSettings,
+} from "../../contracts/user-notifications";
+import { normalizeTimeZone } from "../../shared/time";
+
+const DAY_MS = 24 * 60 * 60_000;
+/** How far ahead `until` looks. A schedule that stays quiet for longer has no end worth naming. */
+const LOOKAHEAD_DAYS = 8;
+
+type QuietInput = { doNotDisturbUntil: Date | null; quietHours: NotificationQuietHours };
+type Interval = { start: number; end: number };
+
+const pad2 = (value: number): string => String(value).padStart(2, "0");
+
+/**
+ * The quiet-hours intervals that touch `[from - 1 day, from + days]`, as instants. Each period belongs to the
+ * local day it starts on; wall-clock times are converted per date, so a period keeps its local times across
+ * daylight-saving changes. A time inside a skipped hour moves forward like the clock does. In a repeated hour a
+ * start takes the first occurrence and an end the second, so the period covers every instant the clock shows a
+ * time inside it.
+ */
+const quietHourIntervals = (hours: NotificationQuietHours, from: number, days: number): Interval[] => {
+  if (hours.periods.length === 0) return [];
+  const timeZone = normalizeTimeZone(hours.timeZone);
+  const [localDate = ""] = dates.instantToZonedInput(new Date(from), timeZone).split("T");
+  const [year, month, day] = localDate.split("-").map(Number) as [number, number, number];
+  const instant = (offset: number, time: string, disambiguation: "compatible" | "later"): number => {
+    const date = new Date(Date.UTC(year, month - 1, day + offset));
+    const wallClock = `${date.getUTCFullYear()}-${pad2(date.getUTCMonth() + 1)}-${pad2(date.getUTCDate())}T${time}`;
+    return Date.parse(dates.zonedDateTimeToInstant(wallClock, timeZone, { disambiguation }));
+  };
+  const intervals: Interval[] = [];
+  for (let offset = -1; offset <= days; offset += 1) {
+    const isoWeekday = new Date(Date.UTC(year, month - 1, day + offset)).getUTCDay() || 7;
+    for (const period of hours.periods) {
+      if (!period.days.includes(isoWeekday)) continue;
+      const start = instant(offset, period.start, "compatible");
+      const end = instant(period.end > period.start ? offset : offset + 1, period.end, "later");
+      if (end > start) intervals.push({ start, end });
+    }
+  }
+  return intervals;
+};
+
+/**
+ * Follow quiet hours from `from` across overlapping and adjoining periods. Returns `from` when it is not quiet
+ * and null when the quiet time does not end within the lookahead, for example with every day fully quiet.
+ */
+const quietHoursEnd = (hours: NotificationQuietHours, from: number): number | null => {
+  const intervals = quietHourIntervals(hours, from, LOOKAHEAD_DAYS);
+  const horizon = from + LOOKAHEAD_DAYS * DAY_MS;
+  let until = from;
+  for (;;) {
+    const ends = intervals.filter((interval) => interval.start <= until && until < interval.end).map((interval) => interval.end);
+    if (ends.length === 0) return until;
+    until = Math.max(...ends);
+    if (until > horizon) return null;
+  }
+};
+
+/**
+ * Whether browser notifications are held back at `now`, why, and until when. Do not disturb names the reason
+ * while it lasts; `until` also covers quiet hours that continue when it ends.
+ */
+export const notificationQuietState = (input: QuietInput, now: Date = new Date()): NotificationQuietState => {
+  const at = now.getTime();
+  const iso = (instant: number | null) => (instant === null ? null : new Date(instant).toISOString());
+  const doNotDisturbUntil = input.doNotDisturbUntil?.getTime() ?? null;
+  if (doNotDisturbUntil !== null && doNotDisturbUntil > at) {
+    return { active: true, reason: "doNotDisturb", until: iso(quietHoursEnd(input.quietHours, doNotDisturbUntil)), nextStart: null };
+  }
+  const until = quietHoursEnd(input.quietHours, at);
+  if (until !== at) return { active: true, reason: "quietHours", until: iso(until), nextStart: null };
+  const starts = quietHourIntervals(input.quietHours, at, LOOKAHEAD_DAYS)
+    .map((interval) => interval.start)
+    .filter((start) => start > at && start <= at + LOOKAHEAD_DAYS * DAY_MS);
+  return { active: false, reason: null, until: null, nextStart: iso(starts.length > 0 ? Math.min(...starts) : null) };
+};
+
+type QuietRow = { do_not_disturb_until: Date | null; time_zone: string; periods: unknown };
+
+/** Parse a stored row defensively: a schedule that no longer validates silences nothing. */
+export const quietInputFromRow = (row: QuietRow | undefined, fallbackTimeZone = "UTC"): QuietInput => {
+  const parsed = row ? NotificationQuietHoursSchema.safeParse({ timeZone: row.time_zone, periods: row.periods }) : null;
+  return {
+    doNotDisturbUntil: row?.do_not_disturb_until ?? null,
+    quietHours: parsed?.success ? parsed.data : { timeZone: normalizeTimeZone(row?.time_zone ?? fallbackTimeZone), periods: [] },
+  };
+};
+
+const toSettings = (input: QuietInput, now = new Date()): NotificationQuietSettings => ({
+  doNotDisturbUntil:
+    input.doNotDisturbUntil && input.doNotDisturbUntil.getTime() > now.getTime() ? input.doNotDisturbUntil.toISOString() : null,
+  quietHours: input.quietHours,
+  state: notificationQuietState(input, now),
+});
+
+/** The person's quiet settings and current state. Without saved quiet hours, `fallbackTimeZone` is offered. */
+const getQuietSettings = async (userId: string, fallbackTimeZone = "UTC"): Promise<NotificationQuietSettings> => {
+  const [row] = await sql<QuietRow[]>`
+    SELECT do_not_disturb_until, time_zone, periods FROM notifications.quiet_times WHERE user_id = ${userId}::uuid
+  `;
+  return toSettings(quietInputFromRow(row, fallbackTimeZone));
+};
+
+const updateQuietSettings = async (config: {
+  userId: string;
+  update: UpdateNotificationQuietSettings;
+  fallbackTimeZone?: string;
+}): Promise<MutationResult<NotificationQuietSettings>> => {
+  const { doNotDisturbUntil, quietHours } = config.update;
+  const until = doNotDisturbUntil ? new Date(doNotDisturbUntil) : null;
+  if (until && until.getTime() <= Date.now()) {
+    return { ok: false, error: "Do not disturb must end in the future", status: 400 };
+  }
+  if (until && until.getTime() > Date.now() + NOTIFICATION_DO_NOT_DISTURB_MAX_DAYS * DAY_MS) {
+    return { ok: false, error: "Do not disturb must end within a year", status: 400 };
+  }
+  const timeZone = normalizeTimeZone(quietHours?.timeZone ?? config.fallbackTimeZone);
+  const periods = quietHours ? JSON.stringify(quietHours.periods) : "[]";
+  await sql`
+    INSERT INTO notifications.quiet_times (user_id, do_not_disturb_until, time_zone, periods, updated_at)
+    VALUES (${config.userId}::uuid, ${until}::timestamptz, ${timeZone}, (${periods}::text)::jsonb, now())
+    ON CONFLICT (user_id) DO UPDATE SET
+      do_not_disturb_until = CASE WHEN ${doNotDisturbUntil !== undefined} THEN EXCLUDED.do_not_disturb_until
+        ELSE notifications.quiet_times.do_not_disturb_until END,
+      time_zone = CASE WHEN ${quietHours !== undefined} THEN EXCLUDED.time_zone ELSE notifications.quiet_times.time_zone END,
+      periods = CASE WHEN ${quietHours !== undefined} THEN EXCLUDED.periods ELSE notifications.quiet_times.periods END,
+      updated_at = now()
+  `;
+  return { ok: true, data: await getQuietSettings(config.userId, config.fallbackTimeZone) };
+};
+
+/** The quiet state of an event's recipient, or null when the recipient is not a Cloud user. */
+export const quietStateForEvent = async (eventId: string, now = new Date()): Promise<NotificationQuietState | null> => {
+  const [row] = await sql<QuietRow[]>`
+    SELECT q.do_not_disturb_until, q.time_zone, q.periods
+    FROM notifications.events e
+    JOIN notifications.quiet_times q ON q.user_id = e.recipient_user_id
+    WHERE e.id = ${eventId}::uuid
+  `;
+  return row ? notificationQuietState(quietInputFromRow(row), now) : null;
+};
+
+export const userQuietTimes = { get: getQuietSettings, update: updateQuietSettings } as const;

package/src/services/notifications/user.ts

@@ -14,6 +14,7 @@ import type {
 import { normalizeLocale } from "../../shared/locale";
 import { toPgTextArray } from "../postgres";
 import { listNotificationChannels } from "./channels";
+import { userQuietTimes } from "./quiet";
 
 type PreferenceRow = {
   id: string;
@@ -164,6 +165,10 @@ const publicDeliveryError = (code: string | null, status: NotificationDeliverySt
       return { code, message: "This delivery channel is currently unavailable." };
     case "no_endpoint":
       return { code, message: "No registered destination is available for this channel." };
+    case "do_not_disturb":
+      return { code, message: "Held back because do not disturb was on." };
+    case "quiet_hours":
+      return { code, message: "Held back during your quiet hours." };
     case "fallback_not_needed":
       return { code, message: "Another preferred channel delivered this notification." };
     case "lease_recovered":
@@ -245,4 +250,5 @@ const listHistory = async (config: {
 export const userNotifications = {
   preferences: { list: listPreferences, set: setPreference, reset: resetPreference },
   history: { list: listHistory },
+  quiet: userQuietTimes,
 } as const;

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));
     }

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

@@ -4,6 +4,7 @@ import { z } from "zod";
 import {
   type AdminMailFilter,
   type AdminMailRecord,
+  type MailFilter,
   type MailMessage,
   type MailPage,
   type MailPageParams,
@@ -86,16 +87,17 @@ type LogRow = Pick<
   | "sent_at"
   | "content_purged_at"
 >;
-const logColumns = (db: SQL, includeText: boolean) => db`id, app_id, profile_key, batch_id, ref_scope, ref_id, to_addresses, subject,
-  ${includeText ? db`text_body` : db`NULL::text AS text_body`}, attachments, status, error_code, error_message, smtp_response,
+const logColumns = (db: SQL, ownApp?: string) => db`id, app_id, profile_key, batch_id, ref_scope, ref_id, to_addresses, subject,
+  ${ownApp === undefined ? db`NULL::text AS text_body` : db`CASE WHEN app_id = ${ownApp} THEN text_body END AS text_body`}, attachments, status, error_code, error_message, smtp_response,
   failures, attempt_count, actor_id, actor_name, created_at, created_at::text AS cursor_created_at, sent_at, content_purged_at`;
 const metadata = async (id: string): Promise<AdminMailRecord | undefined> => {
-  const [row] = await sql<LogRow[]>`SELECT ${logColumns(sql, false)} FROM outgoing_mail.messages WHERE id = ${id}::uuid`;
+  const [row] = await sql<LogRow[]>`SELECT ${logColumns(sql)} FROM outgoing_mail.messages WHERE id = ${id}::uuid`;
   return row ? adminMessageRecord(row) : undefined;
 };
 const date = (value: Date | string) => new Date(value).toISOString();
 export const messageRecord = (row: LogRow): MailRecord => ({
   id: row.id,
+  appId: row.app_id,
   profile: row.profile_key,
   to: row.to_addresses,
   subject: row.subject,
@@ -329,28 +331,67 @@ export const decodeMailCursor = (cursor?: string) => {
     throw new OutgoingMailError("bad_input", "Invalid outgoing mail cursor.");
   }
 };
+type LogFilter = AdminMailFilter & Pick<MailFilter, "apps"> & { recipientExact?: string };
+/**
+ * The longest one search of the send log may run, the same budget as a Mail search; its statements share
+ * it. A broad search on a large log, or one that runs before Core has built the search indexes, could
+ * otherwise read every record on every page.
+ */
+const SEARCH_BUDGET_MS = 5_000;
+const searchTooBroad = () =>
+  new OutgoingMailError("bad_input", "This search took too long. Narrow it with a longer term, fewer apps, or a shorter time range.");
+const isStatementTimeout = (error: unknown) => {
+  const candidate = error as { code?: unknown; errno?: unknown } | null;
+  return candidate?.errno === "57014" || candidate?.code === "57014";
+};
+const withinSearchBudget = async <T>(read: (tx: SQL, limit: () => Promise<void>) => Promise<T>): Promise<T> => {
+  const deadline = Date.now() + SEARCH_BUDGET_MS;
+  try {
+    return await sql.begin((tx) =>
+      read(tx, async () => {
+        const remainingMs = Math.floor(deadline - Date.now());
+        if (remainingMs < 1) throw searchTooBroad();
+        await tx`SELECT set_config('statement_timeout', ${`${remainingMs}ms`}, true)`;
+      }),
+    );
+  } catch (error) {
+    throw isStatementTimeout(error) ? searchTooBroad() : error;
+  }
+};
 const list = async (
-  filter: AdminMailFilter,
+  filter: LogFilter,
   page: MailPageParams = {},
   metadata = false,
+  ownApp?: string,
 ): Promise<MailPage<MailRecord | AdminMailRecord>> => {
   const cursor = decodeMailCursor(page.cursor);
   const perPage = page.perPage ?? 50;
   const pageNumber = cursor?.page ?? page.page ?? 1;
-  const where = sql`WHERE TRUE
-    ${filter.app === undefined ? sql`` : sql`AND app_id = ${filter.app}`}
-    ${filter.profile === undefined ? sql`` : sql`AND profile_key = ${filter.profile}`}
-    ${filter.ids === undefined ? sql`` : sql`AND id = ANY(${toPgUuidArray(filter.ids)}::uuid[])`}
-    ${filter.batchId === undefined ? sql`` : sql`AND batch_id = ${filter.batchId}::uuid`}
-    ${filter.status === undefined ? sql`` : sql`AND status = ANY(${toPgTextArray(filter.status)}::text[])`}
-    ${filter.since === undefined ? sql`` : sql`AND created_at >= ${filter.since}::timestamptz`}
-    ${filter.ref === undefined ? sql`` : sql`AND ref_scope = ${filter.ref.scope}`}
-    ${filter.ref?.id === undefined ? sql`` : sql`AND ref_id = ${filter.ref.id}`}
-    ${filter.recipient === undefined ? sql`` : sql`AND EXISTS(SELECT 1 FROM unnest(to_addresses) AS address WHERE address ILIKE ${`%${escapeLikePattern(filter.recipient)}%`})`}`;
-  const [count] = await sql<{ total: number }[]>`SELECT count(*)::int AS total FROM outgoing_mail.messages ${where}`;
-  const rows = await sql<LogRow[]>`SELECT ${logColumns(sql, !metadata)} FROM outgoing_mail.messages ${where}
-    ${cursor ? sql`AND (created_at < ${cursor.createdAt}::timestamptz OR (created_at = ${cursor.createdAt}::timestamptz AND id > ${cursor.id}::uuid))` : sql``}
-    ORDER BY created_at DESC, id LIMIT ${perPage + 1} OFFSET ${cursor ? 0 : (pageNumber - 1) * perPage}`;
+  const where = (db: SQL) => db`WHERE TRUE
+    ${filter.apps === undefined ? db`` : db`AND app_id = ANY(${toPgTextArray(filter.apps)}::text[])`}
+    ${filter.app === undefined ? db`` : db`AND app_id = ${filter.app}`}
+    ${filter.profile === undefined ? db`` : db`AND profile_key = ${filter.profile}`}
+    ${filter.ids === undefined ? db`` : db`AND id = ANY(${toPgUuidArray(filter.ids)}::uuid[])`}
+    ${filter.batchId === undefined ? db`` : db`AND batch_id = ${filter.batchId}::uuid`}
+    ${filter.status === undefined ? db`` : db`AND status = ANY(${toPgTextArray(filter.status)}::text[])`}
+    ${filter.since === undefined ? db`` : db`AND created_at >= ${filter.since}::timestamptz`}
+    ${filter.until === undefined ? db`` : db`AND created_at < ${filter.until}::timestamptz`}
+    ${filter.q === undefined ? db`` : db`AND outgoing_mail.search_text(subject, to_addresses) ILIKE ${`%${escapeLikePattern(filter.q.toLowerCase())}%`}`}
+    ${filter.recipientExact === undefined ? db`` : db`AND outgoing_mail.lower_addresses(to_addresses) @> ARRAY[pg_catalog.lower(${filter.recipientExact})]`}
+    ${filter.ref === undefined ? db`` : db`AND ref_scope = ${filter.ref.scope}`}
+    ${filter.ref?.id === undefined ? db`` : db`AND ref_id = ${filter.ref.id}`}
+    ${filter.recipient === undefined ? db`` : db`AND EXISTS(SELECT 1 FROM unnest(to_addresses) AS address WHERE address ILIKE ${`%${escapeLikePattern(filter.recipient)}%`})`}`;
+  const read = async (db: SQL, limit: () => Promise<void>) => {
+    await limit();
+    const [count] = await db<{ total: number }[]>`SELECT count(*)::int AS total FROM outgoing_mail.messages ${where(db)}`;
+    await limit();
+    const rows = await db<LogRow[]>`SELECT ${logColumns(db, metadata ? undefined : ownApp)} FROM outgoing_mail.messages ${where(db)}
+      ${cursor ? db`AND (created_at < ${cursor.createdAt}::timestamptz OR (created_at = ${cursor.createdAt}::timestamptz AND id > ${cursor.id}::uuid))` : db``}
+      ORDER BY created_at DESC, id LIMIT ${perPage + 1} OFFSET ${cursor ? 0 : (pageNumber - 1) * perPage}`;
+    return { total: count?.total ?? 0, rows };
+  };
+  const { total, rows } =
+    filter.q === undefined && filter.recipientExact === undefined ? await read(sql, async () => {}) : await withinSearchBudget(read);
   const hasNext = rows.length > perPage;
   const items = rows.slice(0, perPage);
   const last = items.at(-1);
@@ -358,7 +399,7 @@ const list = async (
     items: items.map(metadata ? adminMessageRecord : messageRecord),
     page: pageNumber,
     perPage,
-    total: count?.total ?? 0,
+    total,
     hasNext,
     ...(hasNext && last
       ? {