@k2b/cloud 0.29.0 → 0.29.1

package/src/contracts/outgoing-mail.ts

@@ -2,7 +2,7 @@ import type { PageParams, Paginated, ServiceError } from "@k2b/stdlib";
 import { z } from "zod";
 import { type RequestActor, ServiceAccountSchema, UserSchema } from "./shared";
 
-export const PlatformPermissionSchema = z.enum(["mail:send"]);
+export const PlatformPermissionSchema = z.enum(["mail:send", "mail:read"]);
 export type PlatformPermission = z.infer<typeof PlatformPermissionSchema>;
 export const MailRetentionSchema = z.object({ contentDays: z.int().min(1).max(36500), recordDays: z.int().min(1).max(36500) }).strict();
 export type MailRetention = z.infer<typeof MailRetentionSchema>;
@@ -74,6 +74,7 @@ export type MailProfile = z.infer<typeof MailProfileSchema>;
 export const MailErrorCodeSchema = z.enum([
   "bad_input",
   "profile_not_allowed",
+  "app_not_allowed",
   "profile_required",
   "quota_exceeded",
   "backlog_full",
@@ -110,14 +111,31 @@ export const AdminMailProfileSchema = MailProfileInputSchema.omit({ smtpPassword
   appCount: z.int(),
 });
 export type AdminMailProfile = z.infer<typeof AdminMailProfileSchema>;
-export type AdminMailApp = {
-  appId: string;
-  name: string;
-  registered: boolean;
-  declared: boolean;
-  mode: "default" | "selected";
-  profiles: string[];
-};
+export const AdminMailAppSchema = z.object({
+  appId: z.string(),
+  name: z.string(),
+  registered: z.boolean(),
+  declared: z.boolean(),
+  mode: z.enum(["default", "selected"]),
+  profiles: z.array(z.string()),
+  /** Whether the registered app declares `mail:read`; grants in `logApps` only apply with it. */
+  readDeclared: z.boolean(),
+  /** Other apps whose send log this app may read, besides its own. */
+  logApps: z.array(z.string()),
+});
+export type AdminMailApp = z.infer<typeof AdminMailAppSchema>;
+/** Application IDs as registered, like sender access; Core's own mail is never readable by apps. */
+export const MailLogAppIdSchema = z.string().min(1);
+/** How many other apps' send logs an administrator can let one app read. */
+const MAIL_LOG_GRANT_LIMIT = 100;
+export const MailLogAccessSchema = z
+  .object({ apps: z.array(MailLogAppIdSchema).max(MAIL_LOG_GRANT_LIMIT) })
+  .strict()
+  .refine(
+    (value) => new Set(value.apps).size === value.apps.length && !value.apps.includes("core"),
+    "Choose distinct apps other than core",
+  );
+export type MailLogAccess = z.infer<typeof MailLogAccessSchema>;
 
 export const MailStatusSchema = z.enum(["queued", "sending", "sent", "failed", "bounced", "cancelled"]);
 export type MailStatus = z.infer<typeof MailStatusSchema>;
@@ -218,11 +236,38 @@ export const MailFilterSchema = z
     batchId: z.uuid().optional(),
     status: z.array(MailStatusSchema).max(6).optional(),
     since: z.iso.datetime({ offset: true }).optional(),
+    /** Exclusive upper bound on `createdAt`. */
+    until: z.iso.datetime({ offset: true }).optional(),
+    /**
+     * Apps whose records to read; omitted means only the calling app. Others need `mail:read` and an
+     * administrator grant. Holds everything `mail.readableApps()` returns: the caller and every grant.
+     */
+    apps: z
+      .array(MailLogAppIdSchema)
+      .min(1)
+      .max(MAIL_LOG_GRANT_LIMIT + 1)
+      .refine((apps) => new Set(apps).size === apps.length, "Choose distinct apps")
+      .optional(),
+    /**
+     * Case-insensitive substring of a recipient address or the subject. Three letters or digits in a row
+     * give the trigram index something to look up; without them every record would be a candidate.
+     */
+    q: z
+      .string()
+      .refine((value) => !/[\x00-\x1f\x7f]/.test(value), "Search must not contain control characters")
+      .trim()
+      .max(200)
+      .regex(/[\p{L}\p{N}]{3}/u, "Search needs three letters or digits in a row")
+      .optional(),
+    /** One recipient address, matched exactly but case-insensitively. */
+    recipient: z.string().trim().pipe(mailAddress).optional(),
   })
   .strict();
 export type MailFilter = z.infer<typeof MailFilterSchema>;
 export const MailRecordSchema = z.object({
   id: z.uuid(),
+  /** The app that sent the record. */
+  appId: z.string(),
   batchId: z.uuid().optional(),
   profile: z.string(),
   ref: ref.optional(),
@@ -241,7 +286,6 @@ export const MailRecordSchema = z.object({
 });
 export type MailRecord = z.infer<typeof MailRecordSchema>;
 export const AdminMailRecordSchema = MailRecordSchema.omit({ text: true }).extend({
-  appId: z.string(),
   errorCode: z.string().optional(),
   response: z.string().optional(),
 });
@@ -252,9 +296,10 @@ export type MailPage<T = MailRecord> = Paginated<T> & { nextCursor?: string };
 export const MailPageParamsSchema = z
   .object({ page: z.int().min(1).optional(), perPage: z.int().min(1).max(100).optional(), cursor: z.string().max(1024).optional() })
   .strict();
-export const AdminMailFilterSchema = MailFilterSchema.extend({
+export const AdminMailFilterSchema = MailFilterSchema.omit({ apps: true }).extend({
   app: z.string().min(1).optional(),
   profile: MailProfileKeySchema.optional(),
+  /** Administrators search a recipient substring. */
   recipient: z.string().max(320).optional(),
 });
 export type AdminMailFilter = z.infer<typeof AdminMailFilterSchema>;

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
       ? {

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

@@ -8,6 +8,9 @@ import {
   MailAppAccessSchema,
   type MailBounceErrorCode,
   type MailErrorCode,
+  type MailLogAccess,
+  MailLogAccessSchema,
+  MailLogAppIdSchema,
   type MailProfile,
   type MailProfileInput,
   MailProfileInputSchema,
@@ -22,7 +25,7 @@ export class OutgoingMailError extends Error {
   constructor(
     public readonly code: MailErrorCode,
     message: string,
-    public readonly status: 400 | 404 | 409 | 502 = 400,
+    public readonly status: 400 | 403 | 404 | 409 | 502 = 400,
   ) {
     super(message);
   }
@@ -75,11 +78,12 @@ const locked = async <T>(run: (tx: SQL) => Promise<T>): Promise<T> =>
     await tx`SELECT pg_advisory_xact_lock(hashtextextended('outgoing_mail.policy', 0))`;
     return run(tx);
   });
-const record = (db: SQL, context: MailAuditContext, action: string, target: string) =>
+const record = (db: SQL, context: MailAuditContext, action: string, target: string, metadata?: Record<string, unknown>) =>
   audit.record(
     {
       ...context,
       action: `outgoing_mail.${action}`,
+      ...(metadata ? { metadata } : {}),
       outcome: "allowed",
       target: { type: action.startsWith("profile.") ? "outgoing_mail_profile" : "outgoing_mail_app", id: target },
     },
@@ -241,7 +245,9 @@ const appsState = async (
   const registered = registeredApps ?? (await listApps());
   const { access, grants } = await accessRows(db);
   const [profile] = await db<{ key: string }[]>`SELECT key FROM outgoing_mail.profiles WHERE is_default`;
-  const ids = new Set([...registered.map((app) => app.id), ...access.map((a) => a.app_id)]);
+  const logGrants = await db<{ app_id: string; source_app_id: string }[]>`
+    SELECT app_id, source_app_id FROM outgoing_mail.app_log_access ORDER BY source_app_id`;
+  const ids = new Set([...registered.map((app) => app.id), ...access.map((a) => a.app_id), ...logGrants.map((g) => g.app_id)]);
   const items = [...ids]
     .map((appId): AdminMailApp => {
       const app = registered.find((a) => a.id === appId);
@@ -251,6 +257,13 @@ const appsState = async (
         name: app?.name ?? appId,
         registered: !!app,
         declared: !!app?.platformPermissions?.includes("mail:send"),
+        readDeclared: appId !== "core" && !!app?.platformPermissions?.includes("mail:read"),
+        logApps:
+          appId === "core"
+            ? []
+            : logGrants
+                .filter((g) => g.app_id === appId && g.source_app_id !== "core" && g.source_app_id !== appId)
+                .map((g) => g.source_app_id),
         mode,
         profiles: mode === "selected" ? grants.filter((g) => g.app_id === appId).map((g) => g.key) : [],
       };
@@ -285,6 +298,41 @@ const setAppAccess = async (appId: string, value: MailAppAccess, context: MailAu
         name: appId,
         registered: false,
         declared: false,
+        readDeclared: false,
+        logApps: [],
+        mode: "default",
+        profiles: [],
+      }
+    );
+  });
+};
+const logAppsFor = async (appId: string): Promise<string[]> => {
+  if (appId === "core") return [];
+  const rows = await sql<{ source_app_id: string }[]>`SELECT source_app_id FROM outgoing_mail.app_log_access
+    WHERE app_id = ${appId} AND source_app_id <> 'core' AND source_app_id <> app_id ORDER BY source_app_id`;
+  return rows.map((row) => row.source_app_id);
+};
+const setAppLogAccess = async (appId: string, value: MailLogAccess, context: MailAuditContext): Promise<AdminMailApp> => {
+  const reader = MailLogAppIdSchema.safeParse(appId);
+  const parsed = MailLogAccessSchema.safeParse(value);
+  if (!reader.success || appId === "core" || !parsed.success || parsed.data.apps.includes(appId))
+    throw new OutgoingMailError("bad_input", "Choose a valid reader and distinct source apps other than Core or the reader itself.");
+  const apps = [...parsed.data.apps].sort();
+  const registered = await listApps();
+  return locked(async (tx) => {
+    await tx`DELETE FROM outgoing_mail.app_log_access WHERE app_id = ${appId}`;
+    await tx`INSERT INTO outgoing_mail.app_log_access(app_id, source_app_id, created_by)
+      SELECT ${appId}, source_app_id, ${context.actor.userId ?? null}
+      FROM unnest(${toPgTextArray(apps)}::text[]) AS source_app_id`;
+    await record(tx, context, "app_log_access.update", appId, { apps });
+    return (
+      (await appsState(tx, registered)).items.find((app) => app.appId === appId) ?? {
+        appId,
+        name: appId,
+        registered: false,
+        declared: false,
+        readDeclared: false,
+        logApps: [],
         mode: "default",
         profiles: [],
       }
@@ -319,7 +367,18 @@ const profilesForApp = async (appId: string): Promise<MailProfile[]> => {
     quota: { dailyRecipients: row.daily_recipient_limit, usedLast24h: row.used },
   }));
 };
-export const outgoingMailStore = { list, get, put, setDefault, delete: remove, apps: appsState, setAppAccess, profilesForApp };
+export const outgoingMailStore = {
+  list,
+  get,
+  put,
+  setDefault,
+  delete: remove,
+  apps: appsState,
+  setAppAccess,
+  setAppLogAccess,
+  logAppsFor,
+  profilesForApp,
+};
 
 /** Platform email send path only. Never use this helper to shape API or CLI responses. */
 export const resolveMailCredentials = async (key?: string | { id: string }) => {

package/src/shared/network-address.ts

@@ -65,6 +65,7 @@ const UNSAFE_IPV6_RANGES: ReadonlyArray<readonly [bigint, number]> = [
   [ipv6ToBigInt("2001:2::")!, 48],
   [ipv6ToBigInt("2001:db8::")!, 32],
   [ipv6ToBigInt("2002::")!, 16],
+  [ipv6ToBigInt("3fff::")!, 20],
   [ipv6ToBigInt("fc00::")!, 7],
   [ipv6ToBigInt("fe80::")!, 10],
   [ipv6ToBigInt("fec0::")!, 10],

package/src/styles/effects.css

@@ -96,6 +96,148 @@
   outline-offset: var(--k2b-focus-offset);
 }
 
+/* A pending approval: a calm tinted card in place 4 that says what will happen. Fields stack on phones and the
+   decision buttons share the width there. */
+.k2b-ui .ai-approval {
+  display: grid;
+  min-width: 0;
+  gap: 0.75rem;
+  padding: 1rem 1.125rem;
+  /* Transparent, so forced colours still draw an outline where the tint disappears. */
+  border: 1px solid transparent;
+  border-radius: calc(var(--k2b-radius-surface) + 0.25rem);
+  color: var(--k2b-text-secondary);
+  background: color-mix(in srgb, var(--k2b-warning-surface) 70%, var(--k2b-surface-canvas));
+  font-size: 0.8125rem;
+  line-height: 1.5;
+}
+
+.k2b-ui.k2b-dark .ai-approval,
+.dark .k2b-ui .ai-approval {
+  background: color-mix(in srgb, var(--k2b-warning-surface) 55%, var(--k2b-surface-canvas));
+}
+
+.k2b-ui .ai-approval__head {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.k2b-ui .ai-approval__icon {
+  flex: none;
+  color: var(--k2b-warning-text);
+  font-size: 1.125rem;
+}
+
+/* The title wraps, so it reads in full where the decision button has to shorten it. */
+.k2b-ui .ai-approval__title {
+  margin: 0;
+  color: var(--k2b-text);
+  font-size: 0.875rem;
+  font-weight: 600;
+  overflow-wrap: anywhere;
+}
+
+.k2b-ui .ai-approval__sub,
+.k2b-ui .ai-approval__state {
+  margin: 0;
+  color: var(--k2b-text-muted);
+  font-size: 0.75rem;
+}
+
+.k2b-ui .ai-approval__state {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  font-weight: 500;
+}
+
+.k2b-ui .ai-approval__text {
+  min-width: 0;
+  color: var(--k2b-text-secondary);
+  font-size: 0.75rem;
+}
+
+.k2b-ui .ai-approval__label,
+.k2b-ui .ai-approval__fields dt {
+  color: var(--k2b-text);
+  font-size: 0.75rem;
+  font-weight: 600;
+}
+
+.k2b-ui .ai-approval__fields {
+  display: grid;
+  margin: 0;
+  gap: 0.3rem 1rem;
+  grid-template-columns: max-content minmax(0, 1fr);
+  font-size: 0.75rem;
+}
+
+.k2b-ui .ai-approval__fields dd {
+  min-width: 0;
+  margin: 0;
+  color: var(--k2b-text-secondary);
+  overflow-wrap: anywhere;
+}
+
+.k2b-ui .ai-approval__preview {
+  max-height: 12rem;
+  margin: 0;
+  overflow: auto;
+  color: var(--k2b-text-secondary);
+  font-size: 0.75rem;
+  line-height: 1.55;
+}
+
+.k2b-ui .ai-approval__foot {
+  display: flex;
+  min-width: 0;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.k2b-ui .ai-approval__actions {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  gap: 0.375rem;
+  margin-left: auto;
+}
+
+@media (max-width: 40rem) {
+  .k2b-ui .ai-approval__fields {
+    grid-template-columns: minmax(0, 1fr);
+    gap: 0;
+  }
+
+  .k2b-ui .ai-approval__fields dd {
+    margin-bottom: 0.35rem;
+  }
+
+  .k2b-ui .ai-approval__actions {
+    width: 100%;
+    margin-left: 0;
+  }
+
+  /* The buttons share the width and may shrink below their labels: a long action title ends in an ellipsis instead
+     of pushing the menu out of the card. The title above shows it in full. */
+  .k2b-ui .ai-approval__actions > *,
+  .k2b-ui .ai-approval__actions .k2b-split-button__primary {
+    min-width: 0;
+    flex: 1;
+    justify-content: center;
+  }
+
+  .k2b-ui .ai-approval__actions .k2b-split-button__primary > .k2b-button__label {
+    display: block;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+}
+
 /* Result links sit inside an already padded activity row. Keep them inline so
    they do not make linked capability results taller than neighboring rows. */
 .k2b-ui .k2b-button.ai-chat-result-link[data-size="xs"] {