@k2b/cloud 0.23.0 → 0.25.0

package/src/server/services/access.ts

@@ -1,5 +1,7 @@
 import { err, fail, ok, type Result } from "@k2b/stdlib";
 import { type SQLQuery, sql } from "bun";
+import { type ManagerCandidate, removesLastManager } from "../../access/managers";
+import { accessMessages } from "../../access/messages";
 import { recursiveGroupIdsSubquery } from "../../services/accounts/group-sql";
 import { toPgUuidArray } from "../../services/postgres";
 import type { ServiceAccountKind } from "../../services/service-accounts";
@@ -238,6 +240,31 @@ export const updateAccess = async (params: { id: string; permission: PermissionL
   return ok();
 };
 
+/**
+ * Refuse a grant change that would leave a resource without a manager.
+ *
+ * Pass the resource's entries before and after the change, read in the
+ * transaction that writes it after locking the resource, so concurrent changes
+ * see each other. A manager is an `admin` entry for a user, a group, all
+ * signed-in users, or a standalone or agent service account; service-account
+ * entries need their `serviceAccountKind`. Only a change from at least one
+ * manager to none fails, with status 409 and code `LAST_MANAGER`. An app whose
+ * own precedence lets another entry shadow `admin` drops the shadowed entries
+ * from both lists first. An app whose permission editor names `admin`
+ * differently passes that localized name as `level`, so the message uses the
+ * word the person sees; it defaults to the editor's “Manage”.
+ */
+export const ensureManagerRemains = (params: {
+  before: readonly ManagerCandidate[];
+  after: readonly ManagerCandidate[];
+  locale?: string | null;
+  level?: string;
+}): Result<void> => {
+  if (!removesLastManager(params.before, params.after)) return ok();
+  const { t } = accessMessages.resolve(params.locale ? [params.locale] : []);
+  return fail({ code: "LAST_MANAGER", message: t.lastManager({ level: params.level ?? t.manage }), status: 409 });
+};
+
 /** Resolve direct and nested group memberships from the authoritative database mirror. */
 export const getEffectiveGroups = async (params: { userId: string | null }, db: AccessDb = sql): Promise<EffectiveGroup[]> => {
   if (!params.userId) return [];
@@ -337,17 +364,23 @@ export const buildAccessPrincipalCondition = (params: { subject: AccessSubject |
  * - Direct and nested user group memberships resolved from the database
  * - Authenticated access for every authenticated subject
  * - Public access for every subject, including anonymous callers
+ *
+ * Pass the transaction that locked the resource as `db` to authorize a change
+ * against the grants it writes.
  */
-export const getEffectivePermission = async (params: {
-  accessIds: string[];
-  subject?: AccessSubject | null;
-  /** @deprecated Pass subject instead. */
-  userId?: string | null;
-  /** @deprecated Membership is resolved from userId and this value is intentionally ignored. */
-  userGroups?: string[];
-  /** @deprecated Pass subject instead. */
-  serviceAccountId?: string | null;
-}): Promise<PermissionLevel> => {
+export const getEffectivePermission = async (
+  params: {
+    accessIds: string[];
+    subject?: AccessSubject | null;
+    /** @deprecated Pass subject instead. */
+    userId?: string | null;
+    /** @deprecated Membership is resolved from userId and this value is intentionally ignored. */
+    userGroups?: string[];
+    /** @deprecated Pass subject instead. */
+    serviceAccountId?: string | null;
+  },
+  db: AccessDb = sql,
+): Promise<PermissionLevel> => {
   const accessIds = params.accessIds ?? [];
   const subject =
     "subject" in params
@@ -376,7 +409,7 @@ export const getEffectivePermission = async (params: {
         },
       });
 
-  const rows = await sql<{ permission: PermissionLevel }[]>`
+  const rows = await db<{ permission: PermissionLevel }[]>`
     SELECT a.permission
     FROM auth.access a
     WHERE a.id = ANY(${toPgUuidArray(accessIds)}::uuid[])

package/src/server/services/index.ts

@@ -19,6 +19,7 @@ export {
   buildAccessPrincipalTierConditions,
   createAccess,
   deleteAccess,
+  ensureManagerRemains,
   getAccess,
   getEffectiveGroupIds,
   getEffectiveGroups,

package/src/services/index.ts

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

package/src/services/outbox.ts

@@ -5,29 +5,25 @@ import { logger } from "./logging";
  * PostgreSQL transactional-outbox dispatcher.
  *
  * Domain writers insert a row in their own transaction; this dispatcher claims
- * pending rows (`FOR UPDATE SKIP LOCKED`), publishes them, and records
- * delivery or an exponential-backoff retry. Rows stay durable until they are
- * delivered (or dead after `maxAttempts`, when the table has a `dead_at`
- * column), and delivered rows are pruned after a retention period.
+ * pending rows (`FOR UPDATE SKIP LOCKED`), publishes them, and deletes a
+ * published row or schedules an exponential-backoff retry. Every row in the
+ * table is pending: rows stay until they are published.
  *
- * With `sequence`, it works in batches: claims of one outbox (table and
- * `where`) take turns, a claim takes rows in sequence order with several rows
- * per ordering key, and the dispatcher publishes keys concurrently and the
- * rows of one key in order, then completes the batch in one statement. A row
- * that never failed is due at once. Claims stay proportional to the batch
- * with an index on the `where` columns and `sequence`, and one on the `where`
- * columns and `orderBy` limited to `claimed_until IS NOT NULL OR attempts > 0`.
+ * It works in batches: claims of one outbox (table and `where`) take turns, a
+ * claim takes rows in `sequence` order with several rows per ordering key, and
+ * the dispatcher publishes keys concurrently and the rows of one key in order,
+ * then completes the batch in one statement. A row that never failed is due at
+ * once. Claims stay proportional to the batch with an index on the `where`
+ * columns and `sequence`, and one on the `where` columns and `orderBy` limited
+ * to `claimed_until IS NOT NULL OR attempts > 0`.
  *
  * Required columns: `id uuid`, `attempts int`, `next_attempt_at timestamptz`,
- * `claimed_until timestamptz`, `delivered_at timestamptz`, `last_error text`,
- * `created_at timestamptz`. `maxAttempts` additionally needs `dead_at`;
- * `onDelivered: "delete"` needs no `delivered_at`.
+ * `claimed_until timestamptz`, `last_error text`, and the `orderBy` and
+ * `sequence` columns.
  */
 
 const DEFAULT_CLAIM_MS = 30_000;
 const DEFAULT_BATCH_SIZE = 100;
-const DELIVERED_RETENTION = "7 days";
-const DEAD_RETENTION = "30 days";
 const IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
 
 export type OutboxRow = {
@@ -43,20 +39,14 @@ export type PgOutboxConfig<Row extends OutboxRow> = {
   publish: (row: Row) => Promise<unknown>;
   reconcileIntervalMs: number;
   /**
-   * Column whose rows must be delivered in insertion order. A pending earlier
-   * row with the same value blocks later ones until it is delivered or dead.
-   * With `sequence`, a value waits while any of its rows is claimed or waits
-   * for a retry.
+   * Column whose rows are published in `sequence` order. A value waits while
+   * any of its rows is claimed or waits for a retry.
    */
-  orderBy?: Extract<keyof Row, string>;
+  orderBy: Extract<keyof Row, string>;
+  /** Insertion-order column that orders claims. */
+  sequence: string;
   /** Fixed column values every claimed row matches, e.g. `{ kind: "live", app_id: "contacts" }`. */
   where?: Readonly<Record<string, string>>;
-  /** Insertion-order column that orders claims instead of `(created_at, id)`, and enables batches (see above). */
-  sequence?: string;
-  /** Delete a published row instead of setting `delivered_at`; every row in the table is then pending. */
-  onDelivered?: "delete";
-  /** Mark rows dead after this many failed attempts (requires `dead_at`). */
-  maxAttempts?: number;
   claimMs?: number;
   batchSize?: number;
 };
@@ -79,23 +69,15 @@ const identifier = (name: string, label: string): ReturnType<typeof sql.unsafe>
 
 export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row>): PgOutbox<Row> => {
   const table = identifier(config.table, "table");
-  const orderBy = config.orderBy ? identifier(config.orderBy, "ordering column") : null;
-  const maxAttempts = config.maxAttempts ?? null;
+  const runKey = config.orderBy;
+  const runColumn = identifier(runKey, "ordering column");
+  const sequence = identifier(config.sequence, "sequence column");
   const claimMs = config.claimMs ?? DEFAULT_CLAIM_MS;
   const batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE;
   const log = logger(config.name);
-  const sequence = config.sequence ? identifier(config.sequence, "sequence column") : null;
-  const deleteDelivered = config.onDelivered === "delete";
-  const notDead = maxAttempts === null ? sql`` : sql`AND dead_at IS NULL`;
-  const earlierNotDead = maxAttempts === null ? sql`` : sql`AND earlier.dead_at IS NULL`;
-  const pending = deleteDelivered ? sql`` : sql`AND delivered_at IS NULL`;
-  const earlierPending = deleteDelivered ? sql`` : sql`AND earlier.delivered_at IS NULL`;
   const filters = Object.entries(config.where ?? {}).map(([column, value]) => ({ column: identifier(column, "filter column"), value }));
-  const matches = (alias: "current" | "earlier" | "busy") =>
+  const matches = (alias: "current" | "busy") =>
     filters.reduce((fragment, { column, value }) => sql`${fragment} AND ${sql.unsafe(alias)}.${column} = ${value}`, sql``);
-  // Rows without an ordering column are independent: each is a key of its own.
-  const runKey = config.orderBy ?? "id";
-  const runColumn = identifier(runKey, "ordering column");
   const claimLock = `${config.table}:${JSON.stringify(config.where ?? {})}`;
 
   /**
@@ -104,8 +86,9 @@ export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row
    * delays retries: it is the writer's transaction start, so a fresh row that
    * committed later can carry an earlier one, or one after this claim began.
    */
-  const claimBatch = (cap: number, order: ReturnType<typeof sql.unsafe>) =>
+  const claim: PgOutbox<Row>["claim"] = (limit = batchSize) =>
     sql.begin(async (tx) => {
+      const cap = Math.min(Math.max(limit, 1), batchSize);
       // Claims take turns: a concurrent claim would skip this one's locked rows and take later rows of the same keys.
       // A claim that outlives its claim period is worthless, so neither a slow statement nor a vanished client holds the turn longer.
       await tx`
@@ -121,20 +104,16 @@ export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row
           FROM ${table} current
           WHERE (current.attempts = 0 OR current.next_attempt_at <= now())
             AND (current.claimed_until IS NULL OR current.claimed_until <= now())
-            ${pending}
-            ${notDead}
             ${matches("current")}
             AND NOT EXISTS (
               SELECT
               FROM ${table} busy
               WHERE busy.${runColumn} = current.${runColumn}
                 AND (busy.claimed_until > now() OR (busy.attempts > 0 AND busy.next_attempt_at > now()))
-                ${pending}
-                ${notDead}
                 ${matches("busy")}
               OFFSET 0
             )
-          ORDER BY current.${order}
+          ORDER BY current.${sequence}
           LIMIT ${cap}
           FOR UPDATE SKIP LOCKED
         ), claimed AS (
@@ -144,63 +123,21 @@ export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row
           WHERE outbox.id = candidates.id
           RETURNING outbox.*
         )
-        SELECT * FROM claimed ORDER BY ${order}
+        SELECT * FROM claimed ORDER BY ${sequence}
       `;
     });
 
-  const claim: PgOutbox<Row>["claim"] = async (limit = batchSize) => {
-    const cap = Math.min(Math.max(limit, 1), batchSize);
-    if (sequence !== null) return claimBatch(cap, sequence);
-    const ordered =
-      orderBy === null
-        ? sql``
-        : sql`
-          AND NOT EXISTS (
-            SELECT 1
-            FROM ${table} earlier
-            WHERE earlier.${orderBy} = current.${orderBy}
-              ${earlierPending}
-              ${earlierNotDead}
-              ${matches("earlier")}
-              AND (earlier.created_at, earlier.id) < (current.created_at, current.id)
-          )
-        `;
-    // One statement: the CTE claim and the update commit atomically.
-    return sql<Row[]>`
-      WITH candidates AS MATERIALIZED (
-        SELECT current.id
-        FROM ${table} current
-        WHERE current.next_attempt_at <= now()
-          AND (current.claimed_until IS NULL OR current.claimed_until <= now())
-          ${pending}
-          ${notDead}
-          ${matches("current")}
-          ${ordered}
-        ORDER BY current.next_attempt_at, current.created_at, current.id
-        LIMIT ${cap}
-        FOR UPDATE SKIP LOCKED
-      )
-      UPDATE ${table} outbox
-      SET claimed_until = now() + (${claimMs} * interval '1 millisecond')
-      FROM candidates
-      WHERE outbox.id = candidates.id
-      RETURNING outbox.*
-    `;
-  };
-
   const retryLater = async (row: Row, error: unknown) => {
     const attempts = row.attempts + 1;
     const message = error instanceof Error ? error.message : String(error);
     const delaySeconds = Math.min(300, 2 ** Math.min(attempts, 8));
-    const dead = maxAttempts === null ? sql`` : sql`dead_at = CASE WHEN ${attempts} >= ${maxAttempts} THEN now() ELSE dead_at END,`;
     await sql`
       UPDATE ${table}
       SET attempts = ${attempts},
           next_attempt_at = now() + (${delaySeconds} * interval '1 second'),
           claimed_until = NULL,
-          ${dead}
           last_error = ${message.slice(0, 1_000)}
-      WHERE id = ${row.id}::uuid ${pending} ${notDead} AND attempts = ${row.attempts}
+      WHERE id = ${row.id}::uuid AND attempts = ${row.attempts}
     `;
     log.warn("Outbox delivery failed", { outboxId: row.id, attempts, error: message });
   };
@@ -208,15 +145,7 @@ export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row
   const dispatch: PgOutbox<Row>["dispatch"] = async (row, publish = config.publish) => {
     try {
       await publish(row);
-      if (deleteDelivered) {
-        await sql`DELETE FROM ${table} WHERE id = ${row.id}::uuid AND attempts = ${row.attempts}`;
-        return;
-      }
-      await sql`
-        UPDATE ${table}
-        SET delivered_at = now(), claimed_until = NULL, last_error = NULL
-        WHERE id = ${row.id}::uuid ${pending} ${notDead} AND attempts = ${row.attempts}
-      `;
+      await sql`DELETE FROM ${table} WHERE id = ${row.id}::uuid AND attempts = ${row.attempts}`;
     } catch (error) {
       await retryLater(row, error);
     }
@@ -241,12 +170,7 @@ export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row
         }
       }),
     );
-    if (delivered.length > 0) {
-      const ids = sql.array(delivered, "uuid");
-      await (deleteDelivered
-        ? sql`DELETE FROM ${table} WHERE id = ANY(${ids})`
-        : sql`UPDATE ${table} SET delivered_at = now(), claimed_until = NULL, last_error = NULL WHERE id = ANY(${ids})`);
-    }
+    if (delivered.length > 0) await sql`DELETE FROM ${table} WHERE id = ANY(${sql.array(delivered, "uuid")})`;
     for (const result of results) if (result.status === "rejected") throw result.reason;
   };
 
@@ -257,22 +181,12 @@ export const createPgOutbox = <Row extends OutboxRow>(config: PgOutboxConfig<Row
     reconcileRequested = true;
     if (activeReconcile) return activeReconcile;
     activeReconcile = (async () => {
-      if (!deleteDelivered) {
-        const deadExpired = maxAttempts === null ? sql`` : sql`OR dead_at < now() - ${DEAD_RETENTION}::interval`;
-        await sql`
-          DELETE FROM ${table}
-          WHERE delivered_at < now() - ${DELIVERED_RETENTION}::interval
-             ${deadExpired}
-        `;
-      }
       let processed = 0;
       let rows: Row[];
       do {
         reconcileRequested = false;
         rows = await claim();
-        if (sequence !== null) await dispatchBatch(rows);
-        // Sequential: across keys, the claim order is the publish order.
-        else for (const row of rows) await dispatch(row);
+        await dispatchBatch(rows);
         processed += rows.length;
       } while (reconcileRequested || rows.length > 0);
       return processed;

package/src/services/pdf/markdown.ts

@@ -1,3 +1,4 @@
+import { markdownInfoBlocks } from "@k2b/ui";
 import { Marked, Renderer, type Tokens } from "marked";
 import postcss from "postcss";
 import {
@@ -122,6 +123,25 @@ hr { border: 0; border-top: 1px solid #d1d5db; margin: .9em 0; }
 `,
 };
 
+/**
+ * Markdown info blocks print as the calm NoticeCard: a light tint per tone, no
+ * border, and the preset's own text colour, so they stay readable on paper.
+ * The tints are a step stronger than on screen because paper and printers wash
+ * them out. Every preset and application document shares them.
+ */
+const INFO_BLOCK_PRINT_CSS = `
+.k2b-sr-only { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+.k2b-notice-card { margin: 0 0 1em; padding: .85em 1.05em; border-radius: .8em; background: var(--notice-tint); break-inside: avoid; print-color-adjust: exact; -webkit-print-color-adjust: exact; }
+.k2b-notice-card[data-tone="neutral"] { --notice-tint: #f1f2f4; }
+.k2b-notice-card[data-tone="info"] { --notice-tint: #e9f1fe; }
+.k2b-notice-card[data-tone="success"] { --notice-tint: #e6f6ee; }
+.k2b-notice-card[data-tone="warning"] { --notice-tint: #fcf2da; }
+.k2b-notice-card[data-tone="danger"] { --notice-tint: #fcebeb; }
+.k2b-notice-card__title { margin: 0 0 .25em; font-weight: 600; }
+.k2b-notice-card__body > :first-child { margin-top: 0; }
+.k2b-notice-card__body > :last-child { margin-bottom: 0; }
+`;
+
 const byteLength = (value: string): number => new TextEncoder().encode(value).byteLength;
 
 const escapeHtml = (value: string): string =>
@@ -156,7 +176,7 @@ const renderMarkdown = (source: string): string => {
     return `<a href="${escapeHtml(safeHref)}"${titleAttribute}>${body}</a>`;
   };
 
-  const parser = new Marked({ breaks: true, gfm: true, renderer });
+  const parser = new Marked({ breaks: true, gfm: true, renderer }, markdownInfoBlocks());
   try {
     return parser.parse(source, { async: false }) as string;
   } catch (cause) {
@@ -216,7 +236,7 @@ export const buildPresetPdfHtml = (input: BuildPresetPdfHtmlInput): string => {
   const suppliedCustomCss = input.customCss?.trim() ?? "";
   const customCss = suppliedCustomCss ? validateCustomCss(input.customCss ?? "") : "";
   const presetCss = templateId ? TEMPLATE_CSS[templateId] : customCss ? "" : TEMPLATE_CSS.document;
-  const baseCss = [presetCss, input.css ? styleText(input.css) : ""].filter(Boolean).join("\n");
+  const baseCss = [presetCss, INFO_BLOCK_PRINT_CSS, input.css ? styleText(input.css) : ""].filter(Boolean).join("\n");
   const stylesheet = `${baseCss}${baseCss && customCss ? `\n/* Custom CSS overrides */\n` : ""}${customCss}`;
   return `<!doctype html>
 <html lang="en">

package/src/services/pwa-devices.ts

@@ -4,6 +4,7 @@ import type { Context } from "hono";
 import { PWA_LIMITS as limits, type PwaDeviceView, type PwaErrorCode, type PwaPairingState, type PwaPlatform } from "../contracts/pwa";
 import { isAccountCategoryAllowed } from "./account-category-policy";
 import { audit } from "./audit";
+import { logger } from "./logging";
 import { pairingSecret } from "./pairing-secret";
 import { type AuthenticatedSession, session } from "./session";
 import { requireRecentWebSession } from "./session/recent";
@@ -32,6 +33,19 @@ export type PwaWebActor = { userId: string; sid: string };
 /** Administration of another account's phones needs current admin authority. */
 export type PwaDeviceAdministrator = { userId: string; admin: boolean };
 export type PwaRevocationReason = "user" | "unpaired" | "admin" | "replaced" | "account_expired";
+/**
+ * The "new phone paired" notice, sent once per device after its pairing committed. It carries no
+ * pairing code, secret or key. `locale` is the completing request's locale, if one was stored.
+ */
+export type PwaDevicePairedNotice = {
+  deviceId: string;
+  userId: string;
+  name: string;
+  platform: PwaPlatform;
+  pairedAt: string;
+  locale: string | null;
+};
+export type PwaDeviceNotifier = (notice: PwaDevicePairedNotice) => Promise<unknown>;
 
 type PairingRow = {
   id: string;
@@ -59,6 +73,8 @@ type DeviceRow = {
   created_at: Date;
   last_used_at: Date;
   revoked_at: Date | null;
+  locale: string | null;
+  notified_at: Date | null;
 };
 type UserRow = {
   id: string;
@@ -70,6 +86,7 @@ type UserRow = {
   account_expires: Date | null;
 };
 
+const log = logger("pwa-devices");
 const iso = (value: Date | string) => new Date(value).toISOString();
 const passed = (value: Date | string) => new Date(value).getTime() <= Date.now();
 const DEVICE_KEY = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.([A-Za-z0-9_-]{43})$/;
@@ -123,6 +140,30 @@ const initiatorValid = async (tx: SQL, pairing: PairingRow): Promise<boolean> =>
 };
 
 const accountExpired = (user: UserRow) => Boolean(user.account_expires && passed(user.account_expires));
+
+/** `name` is the one the owner confirmed; the phone can rename itself once it is paired. */
+const pairedNotice = (device: DeviceRow, name: string): PwaDevicePairedNotice => ({
+  deviceId: device.id,
+  userId: device.user_id,
+  name,
+  platform: device.platform,
+  pairedAt: iso(device.created_at),
+  locale: device.locale,
+});
+
+/**
+ * Sends the "new phone paired" notice and marks it sent. The notification owner deduplicates by
+ * device id, so a crash between the two sends nothing twice. A failure leaves it to maintenance.
+ */
+const announce = async (notify: PwaDeviceNotifier, notice: PwaDevicePairedNotice) => {
+  try {
+    await notify(notice);
+    await sql`UPDATE auth.pwa_devices SET notified_at = now() WHERE id = ${notice.deviceId}::uuid AND notified_at IS NULL`;
+  } catch (error) {
+    log.warn("App device notice failed", { error: error instanceof Error ? error.name : "UnknownError" });
+  }
+};
+
 const legalAccepted = async (tx: SQL, userId: string) =>
   (await tx`SELECT 1 FROM auth.legal_acceptances WHERE user_id = ${userId}::uuid`).length > 0;
 
@@ -402,7 +443,9 @@ export const createPwaDeviceService = () => {
 
     /**
      * Finishes a confirmed pairing in the app. `webUserId` is the owner of a valid web session in
-     * the same cookie jar; `appSession` is a valid app session presented with the request.
+     * the same cookie jar; `appSession` is a valid app session presented with the request. The
+     * "new phone paired" notice goes out before the phone receives its credentials, so the phone
+     * can neither turn it off, rename itself in it, nor sign out before it is sent.
      */
     completePairing: async (
       c: Context,
@@ -411,6 +454,9 @@ export const createPwaDeviceService = () => {
         deviceKey: string | null | undefined;
         appSession: AuthenticatedSession | null;
         webUserId: string | null;
+        /** The request locale, kept for the "new phone paired" notice. */
+        locale?: string;
+        notify: PwaDeviceNotifier;
       },
     ): Promise<PwaCompletion> => {
       if (!input.completionSecret) return fail("EXPIRED", 410);
@@ -428,7 +474,7 @@ export const createPwaDeviceService = () => {
       if (snapshot.state !== "confirmed" && snapshot.state !== "completed") return fail("EXPIRED", 410);
       // The device key of this app, read before the locks; it is rechecked under them.
       const presented = await presentedDevice(input.deviceKey);
-      type Step = { kind: "already" } | { kind: "issued"; deviceKey: string };
+      type Step = { kind: "already" } | { kind: "issued"; deviceKey: string; notice: PwaDevicePairedNotice | null };
       const { value, token } = await session.issueInTransaction<Step>(c, async (tx, issue) => {
         const user = await lockUser(tx, snapshot.user_id);
         const [p] = await tx<PairingRow[]>`SELECT * FROM auth.pwa_pairings WHERE id = ${snapshot.id}::uuid FOR UPDATE`;
@@ -447,7 +493,9 @@ export const createPwaDeviceService = () => {
           const deviceKey = await newKey(tx, device.id, "rotate");
           await issue(user.id, appSession(device.id));
           await record(tx, "device.recover", { type: "pwa_device", id: device.id }, user.id);
-          return { kind: "issued", deviceKey };
+          // The first answer may have been lost before its notice went out.
+          const notice = device.notified_at ? null : pairedNotice(device, p.device_name ?? device.name);
+          return { kind: "issued", deviceKey, notice };
         }
         if (p.state !== "confirmed" || !p.platform || !p.device_name) return fail("EXPIRED", 410);
         if (!(await initiatorValid(tx, p))) return fail("EXPIRED", 410);
@@ -466,16 +514,21 @@ export const createPwaDeviceService = () => {
         if ((active?.count ?? 0) >= limits.devicesPerAccount) return fail("LIMIT_REACHED", 429);
         const deviceId = crypto.randomUUID();
         const secret = pairingSecret.create();
-        await tx`INSERT INTO auth.pwa_devices (id, user_id, name, platform, auth_epoch, secret_hash, rotated_at)
-          VALUES (${deviceId}::uuid, ${user.id}::uuid, ${p.device_name}, ${p.platform}, ${user.auth_epoch}, ${pairingSecret.hash(secret)}, now())`;
+        // An unusually long locale tag is dropped; the notice then uses the operator's locale.
+        const locale = input.locale && input.locale.length <= 35 ? input.locale : null;
+        const [device] = await tx<DeviceRow[]>`
+          INSERT INTO auth.pwa_devices (id, user_id, name, platform, auth_epoch, secret_hash, rotated_at, locale)
+          VALUES (${deviceId}::uuid, ${user.id}::uuid, ${p.device_name}, ${p.platform}, ${user.auth_epoch}, ${pairingSecret.hash(secret)}, now(), ${locale})
+          RETURNING *`;
         await issue(user.id, appSession(deviceId));
         await tx`UPDATE auth.pwa_pairings SET state = 'completed', device_id = ${deviceId}::uuid WHERE id = ${p.id}::uuid`;
         await record(tx, "device.enroll", { type: "pwa_device", id: deviceId }, user.id, { platform: p.platform, pairingId: p.id });
-        return { kind: "issued", deviceKey: `${deviceId}.${secret}` };
+        return { kind: "issued", deviceKey: `${deviceId}.${secret}`, notice: pairedNotice(device!, p.device_name) };
       });
       const platform = snapshot.platform ?? "other";
       if (value.kind === "already") return { state: "paired", credentials: null, platform };
       if (!token) throw new Error("App session was not issued");
+      if (value.notice) await announce(input.notify, value.notice);
       return { state: "paired", credentials: { deviceKey: value.deviceKey, sessionToken: token }, platform };
     },
 
@@ -543,8 +596,11 @@ export const createPwaDeviceService = () => {
 
     // ---------- Maintenance ----------
 
-    /** Bounded to 100 rows per step; runs every minute from Core's scheduler. */
-    maintain: async (signal?: AbortSignal) => {
+    /**
+     * Bounded to 100 rows per step; runs every minute from Core's scheduler. `notify` retries the
+     * "new phone paired" notices that completion could not send.
+     */
+    maintain: async (notify: PwaDeviceNotifier, signal?: AbortSignal) => {
       await sql`DELETE FROM auth.pwa_pairings WHERE id IN (
         SELECT id FROM auth.pwa_pairings WHERE expires_at < now() ORDER BY expires_at LIMIT 100 FOR UPDATE SKIP LOCKED)`;
       signal?.throwIfAborted();
@@ -567,6 +623,16 @@ export const createPwaDeviceService = () => {
         WHERE (d.revoked_at < now() - interval '30 days' OR d.rotated_at < now() - ${limits.idleDays + 30} * interval '1 day')
           AND NOT EXISTS (SELECT 1 FROM auth.session_families f WHERE f.pwa_device_id = d.id)
         ORDER BY d.id LIMIT 100 FOR UPDATE SKIP LOCKED)`;
+      signal?.throwIfAborted();
+      // Every pairing is announced, also of a phone removed since: it had access to the account.
+      const pending = await sql<DeviceRow[]>`
+        SELECT * FROM auth.pwa_devices WHERE notified_at IS NULL ORDER BY created_at, id LIMIT 100
+      `;
+      for (const row of pending) {
+        signal?.throwIfAborted();
+        // A failing notice stays pending for the next run and does not hold back the others.
+        await announce(notify, pairedNotice(row, row.name));
+      }
     },
   };
 };