@k2b/cloud 0.37.0 → 0.39.0

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/help/index.ts

@@ -4,7 +4,8 @@ import { getApp, listApps } from "../../_internal/registry";
 import type { AppRegistryEntry } from "../../contracts/registry";
 import type { RequestActor } from "../../contracts/shared";
 import { resolveAppPresentations } from "../../shared/app-presentation";
-import { helpLocaleChain } from "../../shared/help";
+import { type HelpArticleLink, helpLocaleChain, parseHelpReference } from "../../shared/help";
+import { lexHelpMarkdown, walkHelpTokens } from "../../shared/markdown";
 import { logger } from "../logging";
 import { HELP_RESOURCE_PAGE_SIZE, type HelpSelection, hasHelpBm25, metadata, queryHelp } from "./store";
 import type { HelpReader } from "./types";
@@ -36,9 +37,8 @@ export const createHelpReader = (
 ): HelpReader => {
   const db = dependencies.db ?? sql;
   const visible = (app: AppRegistryEntry | null): app is AppRegistryEntry => app !== null && canReadAppHelp(app, viewer);
-  const select = async (appId?: string): Promise<HelpSelection[]> => {
-    const apps = appId ? [await (dependencies.getApp ?? getApp)(appId)] : await (dependencies.listApps ?? listApps)();
-    return resolveAppPresentations(apps.filter(visible), locale).flatMap((app) =>
+  const selectionFor = (apps: AppRegistryEntry[]): HelpSelection[] =>
+    apps.flatMap((app) =>
       app.help
         ? [
             {
@@ -50,6 +50,9 @@ export const createHelpReader = (
           ]
         : [],
     );
+  const select = async (appId?: string): Promise<HelpSelection[]> => {
+    const apps = appId ? [await (dependencies.getApp ?? getApp)(appId)] : await (dependencies.listApps ?? listApps)();
+    return selectionFor(resolveAppPresentations(apps.filter(visible), locale));
   };
   return {
     async manifest(appId) {
@@ -80,6 +83,7 @@ export const createHelpReader = (
             icon: row.icon ?? undefined,
             description: row.description ?? undefined,
             order: row.sort_order,
+            kind: row.kind,
             locale: row.locale,
             searchUrl: `/api/help/v1/${encodeURIComponent(appId)}/search`,
             url: `/api/help/v1/${encodeURIComponent(appId)}/documents/${encodeURIComponent(row.document_id)}`,
@@ -91,7 +95,44 @@ export const createHelpReader = (
     },
     async read(input) {
       const [row] = await queryHelp(await select(input.appId), { documentId: input.documentId, body: true, limit: 1 }, db);
-      return row?.markdown === undefined ? null : { ...metadata(row), markdown: row.markdown };
+      if (row?.markdown === undefined) return null;
+      const references = new Set<string>();
+      const add = (reference: string) => {
+        const ref = parseHelpReference(reference);
+        if (ref) references.add(`${ref.appId ?? input.appId}/${ref.documentId}`);
+      };
+      if (row.next_id) add(row.next_id);
+      for (const reference of row.related) add(reference);
+      walkHelpTokens(lexHelpMarkdown(row.markdown, row.locale), (token) => {
+        if (token.type === "link" && token.href.startsWith("help:")) add(token.href.slice(5));
+      });
+      // Only targets in the current Help of apps this viewer may see become links; the rest stay text.
+      const referencedApps = new Set([...references].map((reference) => reference.split("/")[0]));
+      const apps = references.size
+        ? resolveAppPresentations(
+            (referencedApps.size === 1 && referencedApps.has(input.appId)
+              ? [await (dependencies.getApp ?? getApp)(input.appId)]
+              : await (dependencies.listApps ?? listApps)()
+            ).filter((app): app is AppRegistryEntry => visible(app) && referencedApps.has(app.id)),
+            locale,
+          )
+        : [];
+      const targets = apps.length ? await queryHelp(selectionFor(apps), { references: [...references] }, db) : [];
+      const accents = new Map(apps.map((app) => [app.id, app.appearance?.accent]));
+      const links: Record<string, HelpArticleLink> = {};
+      for (const target of targets) {
+        links[`${target.app_id}/${target.document_id}`] = {
+          appId: target.app_id,
+          appName: target.app_name,
+          accent: accents.get(target.app_id),
+          documentId: target.document_id,
+          title: target.title,
+          description: target.description ?? undefined,
+          icon: target.icon ?? undefined,
+          url: `/help/apps/${encodeURIComponent(target.app_id)}/${encodeURIComponent(target.document_id)}`,
+        };
+      }
+      return { ...metadata(row), markdown: row.markdown, links };
     },
     async search(input) {
       const query = input.query.trim().slice(0, 200);

package/src/services/help/store.ts

@@ -1,6 +1,7 @@
 import { type SQL, sql } from "bun";
 import { APP_REGISTRY_TTL_MS } from "../../_internal/registry";
-import { ensureSchema } from "../postgres";
+import type { HelpAccessLevel, HelpKind } from "../../shared/help";
+import { ensureSchema, toPgTextArray } from "../postgres";
 import type { HelpCorpus, HelpMetadata } from "./types";
 
 // One expired app lease of grace after an app can no longer be discovered.
@@ -26,6 +27,15 @@ export const migrateHelp = async (db: SQL = sql): Promise<void> => {
     PRIMARY KEY (app_id, manifest_hash, locale, document_id),
     FOREIGN KEY (app_id, manifest_hash) REFERENCES help.corpora ON DELETE CASCADE
   )`.simple();
+    const columns = await tx`SELECT column_name FROM information_schema.columns
+      WHERE table_schema = 'help' AND table_name = 'documents'
+        AND column_name IN ('kind', 'needs', 'next_id', 'related')`;
+    if (columns.length < 4)
+      await tx`ALTER TABLE help.documents
+      ADD COLUMN IF NOT EXISTS kind text NOT NULL DEFAULT 'task',
+      ADD COLUMN IF NOT EXISTS needs text,
+      ADD COLUMN IF NOT EXISTS next_id text,
+      ADD COLUMN IF NOT EXISTS related text[] NOT NULL DEFAULT '{}'`.simple();
     await tx`CREATE INDEX IF NOT EXISTS help_search_idx ON help.documents USING gin(search_document)`.simple();
   });
   // The operator enables the extension; Help never installs server extensions.
@@ -63,9 +73,9 @@ export const registerHelp = async (corpus: HelpCorpus, db: SQL = sql): Promise<v
       for (const document of documents) {
         const text = `${document.title}\n${document.description ?? ""}\n${document.searchText}`;
         await tx`INSERT INTO help.documents(app_id, manifest_hash, locale, document_id, title, description, icon,
-          sort_order, markdown, search_text, search_config, search_document)
+          sort_order, kind, needs, next_id, related, markdown, search_text, search_config, search_document)
           VALUES (${corpus.appId}, ${corpus.manifestHash}, ${locale}, ${document.id}, ${document.title},
-            ${document.description ?? null}, ${document.icon ?? null}, ${document.order}, ${document.markdown}, ${text}, ${config},
+            ${document.description ?? null}, ${document.icon ?? null}, ${document.order}, ${document.kind}, ${document.needs ?? null}, ${document.next ?? null}, ${toPgTextArray([...document.related])}::text[], ${document.markdown}, ${text}, ${config},
             setweight(to_tsvector(${config}::regconfig, ${document.id + " " + document.title}), 'A') ||
             setweight(to_tsvector(${config}::regconfig, ${document.description ?? ""}), 'B') ||
             setweight(to_tsvector(${config}::regconfig, ${document.searchText}), 'D'))`;
@@ -97,6 +107,10 @@ type Row = {
   description: string | null;
   icon: string | null;
   sort_order: number;
+  kind: HelpKind;
+  needs: HelpAccessLevel | null;
+  next_id: string | null;
+  related: string[];
   markdown?: string;
 };
 export const metadata = (row: Row): HelpMetadata => ({
@@ -109,6 +123,10 @@ export const metadata = (row: Row): HelpMetadata => ({
   description: row.description ?? undefined,
   icon: row.icon ?? undefined,
   order: row.sort_order,
+  kind: row.kind,
+  needs: row.needs ?? undefined,
+  next: row.next_id ?? undefined,
+  related: row.related,
 });
 
 export const hasHelpBm25 = async (db: SQL = sql): Promise<boolean> => {
@@ -130,6 +148,7 @@ export const queryHelp = async (
     limit?: number;
     cursor?: string;
     bm25?: boolean;
+    references?: readonly string[];
   },
   db: SQL = sql,
 ): Promise<Row[]> => {
@@ -145,10 +164,11 @@ export const queryHelp = async (
   const pending = db.unsafe<Row[]>(
     `WITH active AS (
     SELECT * FROM jsonb_to_recordset(($1::text)::jsonb) AS a(app_id text, app_name text, manifest_hash text, locales text[])
-  ) SELECT d.app_id, a.app_name, d.manifest_hash, d.locale, d.document_id, d.title, d.description, d.icon, d.sort_order
+  ) SELECT d.app_id, a.app_name, d.manifest_hash, d.locale, d.document_id, d.title, d.description, d.icon, d.sort_order, d.kind, d.needs, d.next_id, d.related
     ${input.body ? ", d.markdown" : ""}
     FROM help.documents d JOIN active a ON a.app_id=d.app_id AND a.manifest_hash=d.manifest_hash
     WHERE length($2::text) >= 0 AND d.locale=ANY(a.locales)
+      AND ($5::text[] IS NULL OR (d.app_id || '/' || d.document_id)=ANY($5::text[]))
       AND NOT EXISTS (SELECT 1 FROM help.documents preferred
         WHERE preferred.app_id=d.app_id AND preferred.manifest_hash=d.manifest_hash AND preferred.document_id=d.document_id
           AND preferred.locale=ANY(a.locales) AND array_position(a.locales, preferred.locale)<array_position(a.locales, d.locale))
@@ -162,12 +182,13 @@ export const queryHelp = async (
         : ""
     }
       d.app_id COLLATE "C", ${input.cursor !== undefined ? "" : "d.sort_order,"} d.document_id COLLATE "C"
-    ${input.limit !== undefined ? "LIMIT $5" : ""}`,
+    ${input.limit !== undefined ? "LIMIT $6" : ""}`,
     [
       JSON.stringify(selection),
       input.query ?? "",
       input.documentId ?? null,
       input.cursor ?? null,
+      input.references ? toPgTextArray([...input.references]) : null,
       ...(input.limit !== undefined ? [input.limit] : []),
     ],
   );

package/src/services/help/types.ts

@@ -1,6 +1,6 @@
 import type { AppRegistryHelpSummary } from "../../contracts/registry";
 import type { RequestActor } from "../../contracts/shared";
-import type { HelpDocumentManifest } from "../../shared/help";
+import type { HelpAccessLevel, HelpArticleLink, HelpDocumentManifest, HelpKind } from "../../shared/help";
 
 export type HelpDocument = {
   id: string;
@@ -8,6 +8,10 @@ export type HelpDocument = {
   icon?: string;
   description?: string;
   order: number;
+  kind: HelpKind;
+  needs?: HelpAccessLevel;
+  next?: string;
+  related: readonly string[];
   markdown: string;
   searchText: string;
 };
@@ -30,8 +34,12 @@ export type HelpMetadata = {
   description?: string;
   icon?: string;
   order: number;
+  kind: HelpKind;
+  needs?: HelpAccessLevel;
+  next?: string;
+  related: readonly string[];
 };
-export type HelpArticle = HelpMetadata & { markdown: string };
+export type HelpArticle = HelpMetadata & { markdown: string; links: Readonly<Record<string, HelpArticleLink>> };
 export type HelpMatch = Pick<HelpMetadata, "appId" | "appName" | "locale" | "documentId" | "title" | "description"> & { kind: "help" };
 export type HelpSearchInput = { query: string; appId?: string; limit?: number };
 export type HelpReadInput = { appId: string; documentId: string };

package/src/services/index.ts

@@ -8,6 +8,7 @@ export { accountIdentities, AccountIdentityError } from "./accounts/identities";
 export type { AccountIdentityUser, AccountIdentityGroup, AccountIdentityPage, AccountIdentityAvailability } from "./accounts/identities";
 export type { AccountIdentityReconciliation } from "./accounts/identity-reconciliation";
 export { providers } from "./providers";
+export { createAllowedNetworkFetch } from "./allowed-network-fetch";
 export { requestPublicHttps, type PublicHttpInput } from "./public-http";
 export { authFlows } from "./auth-flows";
 export { toPgIntArray, toPgTextArray, toPgUuidArray, escapeLikePattern, isUniqueViolation } from "./postgres";
@@ -113,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";
@@ -163,6 +164,9 @@ export {
   renderHtmlToPdfWithConfig,
   renderTemplatePdfPreview,
   testGotenberg,
+  preparePdfImage,
+  PDF_IMAGE_MAX_INPUT_BYTES,
+  PDF_IMAGE_MAX_BOXES,
 } from "./pdf";
 export type {
   BuildPresetPdfHtmlInput,
@@ -183,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";
@@ -197,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?.();