@k2b/cloud 0.38.0 → 0.39.0

package/src/contracts/app-approval.ts

@@ -30,7 +30,10 @@ export const APP_ACTION_LIMITS = {
   valueChars: 300,
 } as const;
 /** Commands a Cloud serves beyond the first version, announced in `/info` as `features`. */
-export const APP_APPROVAL_FEATURES = ["actions"] as const;
+export const APP_APPROVAL_FEATURES = ["actions", "terminal-logins"] as const;
+
+export const APP_APPROVAL_ACCEPT = ["terminal-logins"] as const;
+export type AppApprovalAccept = (typeof APP_APPROVAL_ACCEPT)[number];
 
 const Id = z.string().uuid();
 const Secret = z.string().regex(/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/);
@@ -77,7 +80,17 @@ export const AppDeviceCommandSchema = z.discriminatedUnion("operation", [
   /** Stores the authenticator's opaque push token for sign-in wake-ups on this device. */
   z.object({ operation: z.literal("push"), token: z.string().regex(/^[A-Za-z0-9_-]{43}$/) }).strict(),
   /** Pending sign-ins and the newest open Action approvals of the signing device's account in one call. */
-  z.object({ operation: z.literal("inbox") }).strict(),
+  z
+    .object({
+      operation: z.literal("inbox"),
+      accept: z
+        .array(z.enum(APP_APPROVAL_ACCEPT))
+        .min(1)
+        .max(8)
+        .refine((values) => new Set(values).size === values.length)
+        .optional(),
+    })
+    .strict(),
   /** One open Action approval as the device shows it, with the digest the device recomputes before it decides. */
   z.object({ operation: z.literal("action"), actionId: Id }).strict(),
   /** Decides an Action approval. `digest` binds the decision to exactly the view the person saw. */
@@ -121,6 +134,7 @@ export const appDeviceProofMessage = (proof: AppDeviceProof): string => {
     c.operation,
     ...(c.operation === "decide" ? [c.requestId, c.challenge, c.comparison, c.decision] : []),
     ...(c.operation === "push" ? [c.token] : []),
+    ...(c.operation === "inbox" && c.accept !== undefined ? [c.accept] : []),
     ...(c.operation === "action" ? [c.actionId] : []),
     ...(c.operation === "act" ? [c.actionId, c.digest, c.decision] : []),
   ]);
@@ -151,8 +165,40 @@ export const AppDeviceViewSchema = z
     assisted: z.boolean(),
   })
   .strict();
+/** Plain text on one line: no control, format or bidirectional characters, so an app cannot fake Cloud's own frame. */
+const PlainText = (max: number) =>
+  z
+    .string()
+    .refine((value) => Array.from(value).length <= max, `Must contain at most ${max} code points`)
+    .regex(/^[^\p{Cc}\p{Cf}\p{Zl}\p{Zp}]*$/u);
+export const AppTerminalLoginSchema = z
+  .object({
+    client: z
+      .object({
+        // Bound encoded bytes including escapes, so five complete consent rows fit the response budget.
+        id: PlainText(256)
+          .min(1)
+          .refine((value) => new TextEncoder().encode(JSON.stringify(value)).length <= 258),
+        name: PlainText(APP_ACTION_LIMITS.nameChars).min(1),
+      })
+      .strict(),
+    scopes: z
+      .array(z.string().regex(/^[a-z][a-z0-9_:.-]{0,39}$/))
+      .min(1)
+      .max(16),
+    lifetimeSeconds: z.number().int().positive(),
+  })
+  .strict();
+export type AppTerminalLogin = z.infer<typeof AppTerminalLoginSchema>;
 export const AppPendingLoginSchema = z
-  .object({ requestId: Id, challenge: Secret, comparison: Comparison, createdAt: DateTime, expiresAt: DateTime })
+  .object({
+    requestId: Id,
+    challenge: Secret,
+    comparison: Comparison,
+    createdAt: DateTime,
+    expiresAt: DateTime,
+    terminal: AppTerminalLoginSchema.optional(),
+  })
   .strict();
 export const AppPairingPayloadSchema = z
   .object({ protocol: z.literal(APP_APPROVAL_PROTOCOL), issuer: z.string().url(), pairingId: Id, secret: Secret, expiresAt: DateTime })
@@ -215,12 +261,6 @@ export const AppDeviceAccountSchema = z
   })
   .strict();
 export type AppDeviceAccount = z.infer<typeof AppDeviceAccountSchema>;
-/** Plain text on one line: no control, format or bidirectional characters, so an app cannot fake Cloud's own frame. */
-const PlainText = (max: number) =>
-  z
-    .string()
-    .refine((value) => Array.from(value).length <= max, `Must contain at most ${max} code points`)
-    .regex(/^[^\p{Cc}\p{Cf}\p{Zl}\p{Zp}]*$/u);
 const ActionApp = z
   .object({ id: PlainText(APP_ACTION_LIMITS.nameChars).min(1), name: PlainText(APP_ACTION_LIMITS.nameChars).min(1) })
   .strict();

package/src/contracts/app.ts

@@ -58,6 +58,7 @@ export type AppAdminNavigationGroup = {
 
 export type AppPresentationTranslation = {
   name?: string;
+  panelLabel?: string;
   description?: string;
   /** Group labels keyed by `adminNav[].id`. */
   adminGroups?: Readonly<Record<string, string>>;
@@ -107,6 +108,18 @@ export type AppPwaPart = {
   requiresRoles?: Role[];
 };
 
+/** One same-origin panel page contributed by an application. Routes and services still authorize. */
+export type AppPanel = {
+  /** GET page below the app's routes, rendered with PanelLayout. */
+  href: string;
+  /** Panel name in the app's base locale; translated with presentation.translations[locale].panelLabel. */
+  label: string;
+  /** Icon class, for example "ti ti-sparkles". */
+  icon: string;
+  /** Coarse visibility like nav.requiresRoles; the slot grants no access. */
+  requiresRoles?: Role[];
+};
+
 export type AppMeta = {
   platformPermissions?: readonly PlatformPermission[];
   id: string;
@@ -142,6 +155,7 @@ export type AppMeta = {
   searchLinks?: readonly AppSearchLink[];
   /** The app's pages in the installable mobile app (preview), at `href` = `/pwa/<id>`. */
   pwa?: AppPwaPart;
+  panel?: AppPanel;
   /**
    * Dashboard widget endpoints this app exposes. Each entry references an
    * HTTP endpoint that returns a `WidgetResponse` (see `contracts/widgets.ts`).

package/src/contracts/registry.ts

@@ -1,4 +1,4 @@
-import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPresentationCatalog, AppSearchLink } from "./app";
+import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPanel, AppPresentationCatalog, AppSearchLink } from "./app";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "./capabilities";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { Role } from "./shared";
@@ -103,6 +103,8 @@ export type AppRegistryEntry = {
   searchLinks?: readonly AppSearchLink[];
   /** The app's part of the mobile app (preview); `href` is `/pwa/<id>`. Older readers ignore it. */
   pwa?: AppRegistryPwaPart;
+  /** Optional panel declaration; older readers ignore it. */
+  panel?: AppPanel;
   widgets?: AppRegistryWidget[];
   /** Setting keys declared by this app. Used by admin tooling to avoid treating live app-owned settings as legacy. */
   settingKeys?: readonly string[];

package/src/contracts/shared.ts

@@ -401,6 +401,8 @@ export type SettingEntry = {
   valueSource: SettingValueSource;
   resetValueSource: Exclude<SettingValueSource, "custom">;
   isCustom: boolean;
+  /** A stored row exists but this application cannot decrypt or validate it; `value` is the fallback in use. */
+  unreadable: boolean;
   templateVars?: string[];
   options?: SettingOption[];
   min?: number;

package/src/server/services/access.ts

@@ -629,7 +629,11 @@ export const listUsersWithAccess = async (params: {
         OR LOWER(uid) LIKE ${pattern} ESCAPE '\\'
         OR LOWER(group_names) LIKE ${pattern} ESCAPE '\\'
       )
-    ORDER BY LOWER(display_name), id
+    -- A limit must never hide an exact login-name match.
+    ORDER BY
+      CASE WHEN LOWER(uid) = ${query || null}::text THEN 0 ELSE 1 END,
+      CASE WHEN LOWER(display_name) = ${query || null}::text THEN 0 ELSE 1 END,
+      LOWER(display_name), id
     LIMIT ${limit}
   `;
 

package/src/services/accounts/posix.ts

@@ -329,7 +329,8 @@ export const createPosixRuntime = (db: typeof sql = sql, readRanges = readIpaIdR
         // Same order as provisioning; settings write upgrades this lock in the same transaction.
         await lock(tx);
         if (parsed.data.enabled) await checkRange(tx, parsed.data, ranges);
-        await settings.set(CONFIG_KEY, JSON.stringify(parsed.data), tx);
+        // complete value from explicit admin input; nothing is merged over a read (#1303)
+        await settings.set(CONFIG_KEY, JSON.stringify(parsed.data), tx, { replaceUnreadable: true });
         await audit.record(
           {
             action: "accounts.linux.configure",

package/src/services/app-approval.ts

@@ -3,6 +3,7 @@ import { lazySync } from "../_internal/process-sync";
 import { env } from "../config/env";
 import { type AccountCategory, accountCategory } from "../contracts/account-categories";
 import {
+  APP_ACTION_LIMITS,
   APP_APPROVAL_FEATURES,
   APP_APPROVAL_PATH,
   APP_APPROVAL_PROTOCOL,
@@ -19,9 +20,11 @@ import {
 } from "../contracts/app-approval";
 import { publicCloudOrigin } from "../shared/app-url";
 import { isAccountCategoryAllowed } from "./account-category-policy";
+import { appApprovalText } from "./approvals/device";
 import { audit } from "./audit";
 import { logger } from "./logging";
 import { pairingSecret } from "./pairing-secret";
+import { toPgTextArray } from "./postgres";
 import { requireEligibleAccount, requireRecentWebSession } from "./session/recent";
 import { CORE_SETTINGS } from "./settings/core-settings";
 import { decryptValue } from "./settings/crypto";
@@ -109,6 +112,7 @@ type DeviceRow = {
   created_at: Date;
   last_used_at: Date | null;
   assisted: boolean;
+  accepts: string[] | null;
 };
 type PairingRow = {
   id: string;
@@ -127,6 +131,11 @@ type PairingRow = {
   comparison: string | null;
 };
 type LoginRow = {
+  kind: "browser" | "terminal";
+  device_authorization_id: string | null;
+  client_id: string | null;
+  scopes: string[] | null;
+  lifetime_seconds: number | null;
   id: string;
   user_id: string | null;
   auth_epoch: string | null;
@@ -164,9 +173,30 @@ export type AppDeviceActions = {
     approved: boolean;
   }): Promise<boolean>;
 };
-// Bundle Action wake-ups for 30 seconds while the previously woken request is still open.
+export type AppTerminalLoginInput = {
+  deviceAuthorizationId: string;
+  identifier: string;
+  clientId: string;
+  scopes: string[];
+  lifetimeSeconds: number;
+};
+export type AppTerminalLogins = {
+  /** Live pending authorizations whose registry client still allows the device grant. */
+  describe(tx: SQL, ids: string[]): Promise<Map<string, { id: string; name: string }>>;
+  /** In the sign-in decision transaction; false aborts both decisions and their audits. */
+  decide(
+    tx: SQL,
+    input: {
+      deviceAuthorizationId: string;
+      clientId: string;
+      user: Pick<AccountRow, "id" | "uid" | "provider" | "profile">;
+      decision: "approve" | "deny";
+    },
+  ): Promise<boolean>;
+};
+// Bundle sign-in and Action wake-ups for 30 seconds while the previously woken request is still open.
 // Cloud Login gives Actions a separate 30-per-token budget in five minutes, preserving the full sign-in budget.
-const ACTION_WAKE_SECONDS = 30;
+const WAKE_SECONDS = 30;
 /** Best-effort sign-in wake-ups through the trusted authenticator; returns the HTTP status. */
 export type AppLoginPushSender = (
   appOrigin: string,
@@ -247,7 +277,7 @@ export const createAppApprovalService = (
     // Bounded opportunistic maintenance: each accepted write retires up to 100
     // expired rows per table, so bursts cannot trigger an unbounded sweep.
     await db`DELETE FROM auth.app_pairings WHERE id IN (SELECT id FROM auth.app_pairings WHERE expires_at < now() ORDER BY expires_at LIMIT 100 FOR UPDATE SKIP LOCKED)`;
-    await db`DELETE FROM auth.app_logins WHERE id IN (SELECT id FROM auth.app_logins WHERE expires_at < now() ORDER BY expires_at LIMIT 100 FOR UPDATE SKIP LOCKED)`;
+    await db`DELETE FROM auth.app_logins WHERE id IN (SELECT id FROM auth.app_logins WHERE expires_at < now() AND NOT (kind='terminal' AND state='approved') ORDER BY expires_at LIMIT 100 FOR UPDATE SKIP LOCKED)`;
     await db`DELETE FROM auth.app_device_proofs WHERE (device_id,jti) IN (SELECT device_id,jti FROM auth.app_device_proofs WHERE expires_at < now() ORDER BY expires_at LIMIT 100 FOR UPDATE SKIP LOCKED)`;
   };
   const authorizePairing = async (tx: SQL, actor: AppApprovalActor, pairing: PairingRow, cfg: AppApprovalConfig) => {
@@ -269,12 +299,18 @@ export const createAppApprovalService = (
 
   /** Runs after the login commit and never delays or fails it. The body names only
    * this Cloud and the request id; a 410 means the phone's subscription is gone. */
-  const wake = async (cfg: AppApprovalConfig, userId: string, requestId: string) => {
+  const wake = async (cfg: AppApprovalConfig, userId: string, requestId: string, options?: { terminal: boolean }) => {
     try {
-      const rows = await db<{ push_token: string }[]>`SELECT DISTINCT push_token FROM auth.app_devices
-        WHERE issuer=${cfg.issuer} AND user_id=${userId}::uuid AND revoked_at IS NULL AND push_token IS NOT NULL LIMIT ${limits.devicesPerAccount}`;
+      const rows = await db<{ push_token: string }[]>`
+        UPDATE auth.app_devices d SET login_wake_at=now(), login_wake_ref=${requestId}::uuid
+        WHERE issuer=${cfg.issuer} AND user_id=${userId}::uuid AND revoked_at IS NULL AND push_token IS NOT NULL
+          AND (${options?.terminal ?? false}=false OR 'terminal-logins'=ANY(d.accepts))
+          AND (d.login_wake_at IS NULL OR d.login_wake_at <= now() - ${WAKE_SECONDS} * interval '1 second'
+            OR NOT EXISTS (SELECT 1 FROM auth.app_logins w
+              WHERE w.id=d.login_wake_ref AND w.state='pending' AND w.expires_at > now()))
+        RETURNING push_token`;
       await Promise.all(
-        rows.map(async ({ push_token: token }) => {
+        Array.from(new Set(rows.map((row) => row.push_token)), async (token) => {
           const status = await push(cfg.appOrigin, { token, cloudOrigin: cfg.issuer, requestRef: requestId });
           if (status === 410)
             await db`UPDATE auth.app_devices SET push_token=NULL WHERE issuer=${cfg.issuer} AND user_id=${userId}::uuid AND push_token=${token}`;
@@ -285,6 +321,31 @@ export const createAppApprovalService = (
     }
   };
 
+  const loginCandidate = async (tx: SQL, identifier: string, category?: AccountCategory) => {
+    const candidates = await tx<AccountRow[]>`
+      SELECT id,uid,provider,profile,auth_epoch,account_expires FROM auth.users
+      WHERE lower(uid)=lower(${identifier}) OR lower(btrim(mail))=lower(${identifier}) LIMIT 2`;
+    const candidate = candidates.length === 1 ? candidates[0] : undefined;
+    if (
+      candidate &&
+      ((category !== undefined && accountCategory(candidate) !== category) ||
+        (candidate.account_expires && new Date(candidate.account_expires).getTime() <= Date.now()) ||
+        !(await isAccountCategoryAllowed(candidate, tx)))
+    )
+      return undefined;
+    if (!candidate) return undefined;
+    // Re-read under the account lock: starts share one budget, and epoch changes cannot race the snapshot.
+    const [locked] = await tx<AccountRow[]>`SELECT id,uid,provider,profile,auth_epoch,account_expires
+      FROM auth.users WHERE id=${candidate.id}::uuid FOR UPDATE`;
+    if (locked?.account_expires && new Date(locked.account_expires).getTime() <= Date.now()) return undefined;
+    return locked;
+  };
+  const loginBudget = async (tx: SQL, issuer: string, userId: string) => {
+    const [count] = await tx<{ count: number }[]>`SELECT count(*)::int AS count FROM auth.app_logins
+      WHERE issuer=${issuer} AND user_id=${userId}::uuid AND expires_at > now() AND state IN ('pending','approved')`;
+    return (count?.count ?? 0) < limits.pendingPerAccount;
+  };
+
   return {
     config,
     cleanup,
@@ -303,7 +364,7 @@ export const createAppApprovalService = (
               AND device.issuer=${cfg.issuer} AND device.revoked_at IS NULL AND device.push_token IS NOT NULL
               AND device.actions_at IS NOT NULL
             LIMIT ${limits.devicesPerAccount}
-          ) AND (d.action_wake_at IS NULL OR d.action_wake_at <= now() - ${ACTION_WAKE_SECONDS} * interval '1 second'
+          ) AND (d.action_wake_at IS NULL OR d.action_wake_at <= now() - ${WAKE_SECONDS} * interval '1 second'
             OR NOT EXISTS (SELECT 1 FROM approvals.requests w
               WHERE w.id=d.action_wake_ref AND w.status='pending' AND w.expires_at > now()))
           RETURNING d.push_token,d.user_id`;
@@ -505,24 +566,8 @@ export const createAppApprovalService = (
         expiresAt = future(limits.loginSeconds);
       let owner: string | undefined;
       await db.begin(async (tx) => {
-        const candidates = await tx<
-          AccountRow[]
-        >`SELECT id,uid,provider,profile,auth_epoch,account_expires FROM auth.users WHERE lower(uid)=lower(${identifier}) OR lower(btrim(mail))=lower(${identifier}) LIMIT 2`;
-        let candidate = candidates.length === 1 ? candidates[0] : undefined;
-        if (
-          candidate &&
-          (accountCategory(candidate) !== category ||
-            (candidate.account_expires && new Date(candidate.account_expires).getTime() <= Date.now()) ||
-            !(await isAccountCategoryAllowed(candidate, tx)))
-        )
-          candidate = undefined;
-        if (candidate) {
-          await tx`SELECT id FROM auth.users WHERE id=${candidate.id}::uuid FOR UPDATE`;
-          const [count] = await tx<
-            { count: number }[]
-          >`SELECT count(*)::int AS count FROM auth.app_logins WHERE issuer=${cfg.issuer} AND user_id=${candidate.id}::uuid AND expires_at > now() AND state IN ('pending','approved')`;
-          if ((count?.count ?? 0) >= limits.pendingPerAccount) candidate = undefined;
-        }
+        let candidate = await loginCandidate(tx, identifier, category);
+        if (candidate && !(await loginBudget(tx, cfg.issuer, candidate.id))) candidate = undefined;
         // Unknown, ambiguous, disabled and throttled accounts have the identical
         // public shape and a decoy pending transaction; no account enumeration.
         await tx`INSERT INTO auth.app_logins(id,issuer,user_id,auth_epoch,category,browser_hash,challenge,comparison,expires_at)
@@ -533,7 +578,38 @@ export const createAppApprovalService = (
       if (owner) void wake(cfg, owner, id);
       return { requestId: id, browserSecret, comparison: code, expiresAt: iso(expiresAt), pollAfterSeconds: limits.pollSeconds };
     },
-    deviceCommand: async (request: AppDeviceRequest, actions: AppDeviceActions) => {
+    startTerminalLogin: async (
+      input: AppTerminalLoginInput,
+      access: (tx: SQL, account: Pick<AccountRow, "id" | "profile">) => Promise<boolean>,
+    ) => {
+      const cfg = await config();
+      await cleanup();
+      const id = crypto.randomUUID(),
+        code = comparison(),
+        expiresAt = future(limits.loginSeconds);
+      let owner: string | undefined;
+      await db.begin(async (tx) => {
+        let candidate = await loginCandidate(tx, input.identifier);
+        const subject = candidate ?? { id: crypto.randomUUID(), profile: "user" as const };
+        // Even a decoy performs the client-access, device and shared-budget queries.
+        const allowed = await access(tx, subject);
+        const devices = await tx`SELECT id FROM auth.app_devices WHERE issuer=${cfg.issuer}
+          AND user_id=${subject.id}::uuid AND revoked_at IS NULL LIMIT 1`;
+        const budget = await loginBudget(tx, cfg.issuer, subject.id);
+        if (!allowed || !devices.length || !budget) candidate = undefined;
+        const inserted = await tx`INSERT INTO auth.app_logins
+          (id,issuer,user_id,auth_epoch,category,browser_hash,challenge,comparison,expires_at,kind,device_authorization_id,client_id,scopes,lifetime_seconds)
+          VALUES (${id}::uuid,${cfg.issuer},${candidate?.id ?? null}::uuid,${candidate?.auth_epoch ?? null},
+            ${candidate ? accountCategory(candidate) : "login"},${hash(secret())},${secret()},${code},${expiresAt},'terminal',
+            ${input.deviceAuthorizationId}::uuid,${input.clientId},${toPgTextArray(input.scopes)}::text[],${input.lifetimeSeconds})
+          ON CONFLICT (device_authorization_id) WHERE device_authorization_id IS NOT NULL DO NOTHING RETURNING id`;
+        if (!inserted.length) return reject("CONFLICT", 409);
+        owner = candidate?.id;
+      });
+      if (owner) void wake(cfg, owner, id, { terminal: true });
+      return { comparison: code, expiresAt: iso(expiresAt) };
+    },
+    deviceCommand: async (request: AppDeviceRequest, actions: AppDeviceActions, terminal?: AppTerminalLogins) => {
       const cfg = await config();
       const { proof, signature } = request;
       const now = Math.floor(Date.now() / 1000);
@@ -580,20 +656,40 @@ export const createAppApprovalService = (
           return { operation: command.operation, userId: device.user_id, deviceId: device.id };
         if (command.operation === "pending" || command.operation === "inbox") {
           const user = await eligible(tx, device.user_id);
+          const acceptsTerminal =
+            command.operation === "inbox" && command.accept?.includes("terminal-logins") === true && terminal !== undefined;
           const rows = await tx<
             LoginRow[]
-          >`SELECT * FROM auth.app_logins WHERE issuer=${cfg.issuer} AND user_id=${device.user_id}::uuid AND state='pending' AND expires_at>now() AND auth_epoch=${user.auth_epoch} AND category=${accountCategory(user)} ORDER BY created_at LIMIT ${limits.pendingPerAccount}`;
-          const requests = rows.map(
-            (row): AppPendingLogin => ({
+          >`SELECT * FROM auth.app_logins WHERE (kind='browser' OR ${acceptsTerminal}) AND issuer=${cfg.issuer} AND user_id=${device.user_id}::uuid AND state='pending' AND expires_at>now() AND auth_epoch=${user.auth_epoch} AND category=${accountCategory(user)} ORDER BY created_at LIMIT ${limits.pendingPerAccount}`;
+          const clients =
+            acceptsTerminal && terminal
+              ? await terminal.describe(
+                  tx,
+                  rows.flatMap((row) => (row.device_authorization_id ? [row.device_authorization_id] : [])),
+                )
+              : new Map<string, { id: string; name: string }>();
+          const requests: AppPendingLogin[] = [];
+          for (const row of rows) {
+            const login: AppPendingLogin = {
               requestId: row.id,
               challenge: row.challenge,
               comparison: row.comparison,
               createdAt: iso(row.created_at),
               expiresAt: iso(row.expires_at),
-            }),
-          );
+            };
+            if (row.kind === "terminal") {
+              const client = row.device_authorization_id ? clients.get(row.device_authorization_id) : undefined;
+              if (!client || client.id !== row.client_id || !row.scopes || !row.lifetime_seconds) continue;
+              login.terminal = {
+                client: { id: client.id, name: appApprovalText(client.name || client.id, APP_ACTION_LIMITS.nameChars) || "OAuth" },
+                scopes: row.scopes,
+                lifetimeSeconds: row.lifetime_seconds,
+              };
+            }
+            requests.push(login);
+          }
           if (command.operation === "inbox") {
-            await tx`UPDATE auth.app_devices SET actions_at=now() WHERE id=${device.id}::uuid`;
+            await tx`UPDATE auth.app_devices SET actions_at=now(), accepts=${toPgTextArray(command.accept ?? [])}::text[] WHERE id=${device.id}::uuid`;
             return { operation: "inbox" as const, userId: device.user_id, logins: requests };
           }
           return { requests, pollAfterSeconds: limits.pollSeconds };
@@ -612,9 +708,29 @@ export const createAppApprovalService = (
           row.category !== accountCategory(user)
         )
           return reject("CONFLICT", 409);
+        if (
+          row.kind === "terminal" &&
+          (!device.accepts?.includes("terminal-logins") ||
+            !terminal ||
+            !row.device_authorization_id ||
+            !row.client_id ||
+            !(await terminal.decide(tx, {
+              deviceAuthorizationId: row.device_authorization_id,
+              clientId: row.client_id,
+              user,
+              decision: command.decision,
+            })))
+        )
+          return reject("CONFLICT", 409);
         const state = command.decision === "approve" ? "approved" : "denied";
-        await tx`UPDATE auth.app_logins SET state=${state},approved_by=${device.id}::uuid WHERE id=${row.id}::uuid`;
-        await record(tx, `login.${command.decision}`, device.user_id, device.id, { requestId: row.id });
+        // A hook may wait on another transaction. Expiry still wins before either decision commits.
+        const decided = await tx`UPDATE auth.app_logins SET state=${state},approved_by=${device.id}::uuid
+          WHERE id=${row.id}::uuid AND expires_at > clock_timestamp() RETURNING id`;
+        if (!decided.length) return reject("CONFLICT", 409);
+        await record(tx, `login.${command.decision}`, device.user_id, device.id, {
+          requestId: row.id,
+          ...(row.kind === "terminal" ? { kind: "terminal", clientId: row.client_id, deviceGrantId: row.device_authorization_id } : {}),
+        });
         return { state };
       });
       if (outcome.operation !== undefined) {
@@ -655,7 +771,7 @@ export const createAppApprovalService = (
     browserStatus: async (id: string, token: string, hold?: { ms: number; signal?: AbortSignal }) => {
       const cfg = await config();
       const read = async () => {
-        const [row] = await db<LoginRow[]>`SELECT * FROM auth.app_logins WHERE id=${id}::uuid AND issuer=${cfg.issuer}`;
+        const [row] = await db<LoginRow[]>`SELECT * FROM auth.app_logins WHERE kind='browser' AND id=${id}::uuid AND issuer=${cfg.issuer}`;
         if (!row || !matches(token, row.browser_hash)) return reject("UNAVAILABLE", 404);
         const expiresIn = new Date(row.expires_at).getTime() - Date.now();
         return { state: expiresIn <= 0 ? "expired" : row.state, expiresIn };
@@ -686,10 +802,14 @@ export const createAppApprovalService = (
       const cfg = await config();
       return db.begin(async (tx) => {
         // Lock order is device -> request for both approval and completion.
-        const [snapshot] = await tx<LoginRow[]>`SELECT * FROM auth.app_logins WHERE id=${id}::uuid AND issuer=${cfg.issuer}`;
+        const [snapshot] = await tx<
+          LoginRow[]
+        >`SELECT * FROM auth.app_logins WHERE kind='browser' AND id=${id}::uuid AND issuer=${cfg.issuer}`;
         if (!snapshot || !snapshot.approved_by || !matches(token, snapshot.browser_hash)) return reject("CONFLICT", 409);
         const device = await activeDevice(tx, snapshot.approved_by, cfg.issuer);
-        const [row] = await tx<LoginRow[]>`SELECT * FROM auth.app_logins WHERE id=${id}::uuid AND issuer=${cfg.issuer} FOR UPDATE`;
+        const [row] = await tx<
+          LoginRow[]
+        >`SELECT * FROM auth.app_logins WHERE kind='browser' AND id=${id}::uuid AND issuer=${cfg.issuer} FOR UPDATE`;
         const user = await eligible(tx, device.user_id);
         if (
           !row ||

package/src/services/approvals/device.ts

@@ -21,6 +21,8 @@ const cut = (value: string, limit: number): string => {
   return points.length > limit ? `${points.slice(0, limit - 1).join("")}…` : value;
 };
 
+export const appApprovalText = (value: string, limit: number): string => cut(plain(value), limit);
+
 /** A deterministic, plain-text snapshot; the digest binds the device's choice to everything it shows. */
 export const appActionView = async (
   row: PendingApprovalRow,

package/src/services/index.ts

@@ -114,8 +114,8 @@ export type { AccountLifecycleNotificationSender } from "./account-lifecycle/not
 export { lifecycleJobs } from "./account-lifecycle/scheduler";
 
 export { settings } from "./settings/namespace";
-export { loadCache, get, set, remove, getAll } from "./settings";
-export type { SettingEntry } from "./settings";
+export { loadCache, get, read, readStates, set, remove, getAll, SettingUnreadableError } from "./settings";
+export type { SettingEntry, SettingRead, StoredSettingState } from "./settings";
 export { SETTINGS, SETTINGS_MAP, registerSettings } from "./settings/defaults";
 export { validateSettingValue, normalizeSettingValue, getSettingLabel } from "./settings/defaults";
 export type { SettingDef, SettingKind, SettingOption } from "./settings/defaults";
@@ -164,6 +164,9 @@ export {
   renderHtmlToPdfWithConfig,
   renderTemplatePdfPreview,
   testGotenberg,
+  preparePdfImage,
+  PDF_IMAGE_MAX_INPUT_BYTES,
+  PDF_IMAGE_MAX_BOXES,
 } from "./pdf";
 export type {
   BuildPresetPdfHtmlInput,
@@ -184,6 +187,12 @@ export type {
   TemplatePdfPreviewError,
   TemplatePdfPreviewPhase,
   TemplatePdfPreviewResult,
+  PdfImageBox,
+  PdfImageVariant,
+  PdfImageErrorCode,
+  PreparePdfImageInput,
+  PreparePdfImageOptions,
+  PreparePdfImageResult,
 } from "./pdf";
 
 export { createSyncOpsRoutes, SYNC_OPS_DEAD_LETTER_LIMIT } from "./sync-ops";
@@ -198,7 +207,16 @@ 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 {
+  AppApprovalError,
+  appApproval,
+  type AppDeviceAdministrator,
+  type AppDeviceEnrollmentNotice,
+  type AppApprovalConfig,
+  type AppTerminalLogins,
+  type AppTerminalLoginInput,
+  readAppApprovalConfig,
+} from "./app-approval";
 export { PwaError, pwaDevices, type PwaDeviceAdministrator, type PwaDevicePairedNotice } from "./pwa-devices";
 export { legalConsent } from "./legal-consent";
 

package/src/services/notifications/browser.ts

@@ -7,6 +7,7 @@ import { isSafeNotificationTargetHref } from "../../contracts/notification-types
 import { type BrowserPushSubscription, BrowserPushSubscriptionSchema } from "../../contracts/user-notifications";
 import { decryptSecret, encryptSecret } from "../secrets";
 import { coreSettings } from "../settings/api";
+import { SettingUnreadableError } from "../settings/store";
 import { type NotificationDestination, registerNotificationChannel } from "./channels";
 import { NOTIFICATION_PREVIEW_LIMIT } from "./preview";
 import { sendPinnedWebPush } from "./web-push-transport";
@@ -76,10 +77,16 @@ const ensureVapidConfig = (): Promise<{ publicKey: string; privateKey: string }>
   vapidConfigPromise = sql
     .begin(async (tx) => {
       await tx`SELECT pg_advisory_xact_lock(hashtextextended('notifications:web-push-vapid', 0))`;
-      let [publicKey, privateKey] = await Promise.all([
-        coreSettings.get<string>("notifications.web_push_public_key"),
-        coreSettings.get<string>("notifications.web_push_private_key"),
-      ]);
+      const keys = ["notifications.web_push_public_key", "notifications.web_push_private_key"] as const;
+      const states = await Promise.all(keys.map((key) => coreSettings.read<string>(key)));
+      for (const [index, state] of states.entries()) {
+        if (state.stored === "unreadable") {
+          const key = keys[index]!;
+          console.warn(`[notifications] cannot read setting "${key}"; keeping stored VAPID keys unchanged`);
+          throw new SettingUnreadableError(key);
+        }
+      }
+      let [publicKey, privateKey] = states.map((state) => state.value);
       if (!publicKey || !privateKey) {
         const generated = webpush.generateVAPIDKeys();
         publicKey = generated.publicKey;
@@ -240,7 +247,11 @@ unregisterDriver = registerNotificationChannel(browserDriver);
 export const browserNotifications = {
   start: async (): Promise<void> => {
     unregisterDriver ??= registerNotificationChannel(browserDriver);
-    await ensureWebPushConfigured();
+    try {
+      await ensureWebPushConfigured();
+    } catch (error) {
+      if (!(error instanceof SettingUnreadableError)) throw error;
+    }
   },
   stop: (): void => {
     unregisterDriver?.();