@k2b/cloud 0.22.0 → 0.23.0

package/src/api/pwa.ts

@@ -0,0 +1,179 @@
+import { type Context, Hono, type MiddlewareHandler } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { HTTPException } from "hono/http-exception";
+import { describeRoute } from "hono-openapi";
+import { z } from "zod";
+import {
+  isPwaShellAvailable,
+  PWA_LIMITS,
+  PwaDeviceListSchema,
+  PwaPairingConfirmSchema,
+  PwaPairingStartResultSchema,
+  PwaPairingStatusSchema,
+} from "../contracts/pwa";
+import { type AuthContext, auth, jsonResponse, rateLimit, v } from "../server";
+import { logger } from "../services/logging";
+import { PwaError, pwaDevices } from "../services/pwa-devices";
+import * as settings from "../services/settings";
+import { publicCloudOrigin } from "../shared/app-url";
+import { getRuntimeContext } from "../ssr/runtime";
+
+export type PwaRouteOptions = {
+  service?: typeof pwaDevices;
+  /** True while the mobile app (the `pwa` application) is registered. */
+  shellAvailable?: (c: Context) => boolean;
+};
+
+const log = logger("pwa");
+
+const MESSAGES: Record<PwaError["code"], string> = {
+  UNAVAILABLE: "The mobile app is not available right now.",
+  REAUTHENTICATE: "Sign in again to pair a phone.",
+  FORBIDDEN: "Use Cloud on the web for this.",
+  ACCOUNT_BLOCKED: "This account cannot use the mobile app right now.",
+  INVALID_REQUEST: "The request is not valid.",
+  NOT_FOUND: "Not found.",
+  EXPIRED: "This pairing has expired.",
+  ALREADY_USED: "This pairing link was already used.",
+  WRONG_CODE: "The code does not match.",
+  CONFLICT: "The pairing is not at this step.",
+  ALREADY_PAIRED: "This app is paired with another account.",
+  ACCOUNT_MISMATCH: "This browser is signed in to another account.",
+  LIMIT_REACHED: "The limit for this account was reached.",
+  UNPAIRED: "This phone is not paired.",
+};
+
+/** `{ code, message }` with a safe English message; the UI maps codes to its own catalog. */
+export const pwaErrorResponse = (c: Context, error: PwaError) =>
+  c.json(
+    { code: error.code, message: MESSAGES[error.code], ...(error.attemptsLeft !== undefined ? { attemptsLeft: error.attemptsLeft } : {}) },
+    error.status,
+  );
+
+export const pwaInvalidRequest = () => ({ code: "INVALID_REQUEST", message: MESSAGES.INVALID_REQUEST });
+
+/** Never log bodies, cookies, secrets, keys or codes: only the error name. */
+export const handlePwaError = (error: Error, c: Context) => {
+  if (error instanceof PwaError) return pwaErrorResponse(c, error);
+  if (error instanceof HTTPException && error.status < 500) return pwaErrorResponse(c, new PwaError("INVALID_REQUEST", 400));
+  log.error("Mobile app operation failed", { error: error.name || "UnknownError" });
+  return pwaErrorResponse(c, new PwaError("UNAVAILABLE", 503));
+};
+
+/** Reads the live registry that Core's runtime middleware puts on every request. */
+export const defaultShellAvailable = (c: Context): boolean => isPwaShellAvailable(getRuntimeContext(c).apps);
+
+/**
+ * No caching or referrers, JSON bodies within the limit, and an `Origin` equal to the
+ * operator's canonical address on every non-GET request. Forwarded headers are never
+ * trusted: behind the gateway they describe the internal hop.
+ */
+export const pwaTransport = (): MiddlewareHandler[] => [
+  async (c, next) => {
+    c.header("Cache-Control", "no-store");
+    c.header("Referrer-Policy", "no-referrer");
+    c.header("Vary", "Origin");
+    if (c.req.method !== "GET" && c.req.method !== "HEAD") {
+      const origin = c.req.header("Origin");
+      if (!origin || origin !== publicCloudOrigin(await settings.get<string>("app.url"))) {
+        return pwaErrorResponse(c, new PwaError("FORBIDDEN", 403));
+      }
+    }
+    await next();
+  },
+  bodyLimit({ maxSize: PWA_LIMITS.bodyBytes, onError: (c) => pwaErrorResponse(c, new PwaError("INVALID_REQUEST", 400)) }),
+];
+
+const IdParamSchema = z.object({ id: z.string().uuid() });
+
+/** The web session of a person: never the mobile app's session, an API key or an OAuth token. */
+const webActor = async (c: Context) => {
+  if (c.req.header("Authorization")) throw new PwaError("FORBIDDEN", 403);
+  const token = auth.session.getWebToken(c);
+  // Only the mobile app's session: pairing phones needs the web, a new sign-in would not help.
+  if (!token && auth.session.getAppToken(c)) throw new PwaError("FORBIDDEN", 403);
+  const session = token ? await auth.session.authenticateRequest(c, token) : null;
+  if (!session) throw new PwaError("REAUTHENTICATE", 403);
+  if (session.data.kind !== "web") throw new PwaError("FORBIDDEN", 403);
+  return { userId: session.user.id, sid: session.data.sid };
+};
+
+/** The phone this request also comes from (Chrome on a paired Android phone shares the app's cookies). */
+const currentDeviceId = async (c: Context, userId: string): Promise<string | null> => {
+  const token = auth.session.getAppToken(c);
+  const session = token ? await auth.session.authenticateRequest(c, token) : null;
+  return session?.data.kind === "app" && session.user.id === userId ? (session.data.deviceId ?? null) : null;
+};
+
+const tags = ["Mobile app"];
+
+/** Web side of the mobile app (preview), mounted by Core at `/api/auth/pwa/v1`. */
+export const createPwaRoutes = (options: PwaRouteOptions = {}) => {
+  const service = options.service ?? pwaDevices;
+  const shellAvailable = options.shellAvailable ?? defaultShellAvailable;
+  return new Hono<AuthContext>()
+    .onError(handlePwaError)
+    .use("*", ...pwaTransport())
+    .use("*", rateLimit())
+    .post(
+      "/pairings",
+      describeRoute({
+        tags,
+        summary: "Start pairing a phone",
+        description: "Needs a web sign-in from the last ten minutes. The link secret is returned once.",
+        responses: { 201: jsonResponse(PwaPairingStartResultSchema, "Pairing started") },
+      }),
+      async (c) => {
+        const actor = await webActor(c);
+        if (!shellAvailable(c)) throw new PwaError("UNAVAILABLE", 503);
+        return c.json(await service.startPairing(actor), 201);
+      },
+    )
+    .get(
+      "/pairings/:id",
+      describeRoute({
+        tags,
+        summary: "Read a pairing",
+        description: "Only for the web session that started it. Never returns the code.",
+        responses: { 200: jsonResponse(PwaPairingStatusSchema, "Pairing state") },
+      }),
+      v("param", IdParamSchema, pwaInvalidRequest),
+      async (c) => c.json(await service.inspectPairing(await webActor(c), c.req.valid("param").id)),
+    )
+    .post(
+      "/pairings/:id/confirm",
+      describeRoute({ tags, summary: "Confirm a pairing with the code the phone shows", responses: { 204: { description: "Confirmed" } } }),
+      v("param", IdParamSchema, pwaInvalidRequest),
+      v("json", PwaPairingConfirmSchema, pwaInvalidRequest),
+      async (c) => {
+        await service.confirmPairing(await webActor(c), c.req.valid("param").id, c.req.valid("json").code);
+        return c.body(null, 204);
+      },
+    )
+    .post(
+      "/pairings/:id/cancel",
+      describeRoute({ tags, summary: "Cancel a pairing", responses: { 204: { description: "Cancelled" } } }),
+      v("param", IdParamSchema, pwaInvalidRequest),
+      async (c) => {
+        await service.cancelPairing(await webActor(c), c.req.valid("param").id);
+        return c.body(null, 204);
+      },
+    )
+    .get(
+      "/devices",
+      describeRoute({ tags, summary: "List paired phones", responses: { 200: jsonResponse(PwaDeviceListSchema, "Active phones") } }),
+      async (c) => {
+        const actor = await webActor(c);
+        return c.json({ items: await service.list(actor, await currentDeviceId(c, actor.userId)) });
+      },
+    )
+    .delete(
+      "/devices/:id",
+      describeRoute({ tags, summary: "Remove a paired phone", responses: { 204: { description: "Removed; idempotent" } } }),
+      v("param", IdParamSchema, pwaInvalidRequest),
+      async (c) => {
+        await service.revoke(await webActor(c), c.req.valid("param").id);
+        return c.body(null, 204);
+      },
+    );
+};

package/src/browser/app-session.ts

@@ -0,0 +1,69 @@
+import { PWA_AUTH_PATH, PWA_SCOPE } from "../contracts/pwa-paths";
+
+export type AppSessionRenewal = {
+  /** The page has a valid app session now. */
+  ok: boolean;
+  /** Android shares Chrome's cookies with the app, so the web session there may belong to another account. */
+  otherAccount?: { name: string };
+};
+
+/** Whether this document is a page of the mobile app, whose requests carry the app session. */
+export const insideMobileApp = (): boolean =>
+  typeof location !== "undefined" && location.pathname.startsWith(PWA_SCOPE) && !location.pathname.startsWith(`${PWA_AUTH_PATH}/`);
+
+const call = async (): Promise<AppSessionRenewal & { renewed: boolean }> => {
+  let response: Response;
+  try {
+    response = await fetch(`${PWA_AUTH_PATH}/session/renew`, {
+      method: "POST",
+      credentials: "same-origin",
+      headers: { Accept: "application/json" },
+    });
+  } catch {
+    // Offline or unreachable: the next foreground or request tries again.
+    return { ok: false, renewed: false };
+  }
+  if (response.status === 401) {
+    // The phone was removed or its pairing ended. Core has already deleted the device key with this answer, so
+    // a reload could only show the generic pairing view; the pairing view for a signed-out phone says why.
+    location.replace(`${PWA_SCOPE}?pwa=ended`);
+    return { ok: false, renewed: false };
+  }
+  if (response.status === 403) {
+    const body: unknown = await response.json().catch(() => null);
+    if (typeof body === "object" && body !== null && "code" in body && body.code === "ACCOUNT_BLOCKED") {
+      location.replace(`${PWA_SCOPE}?pwa=blocked`);
+    }
+    return { ok: false, renewed: false };
+  }
+  if (!response.ok) return { ok: false, renewed: false };
+  // `PwaRenewResultSchema`, read by hand: the typed client on every page must not load the validators.
+  const body: unknown = await response.json().catch(() => null);
+  if (typeof body !== "object" || body === null || !("renewed" in body) || typeof body.renewed !== "boolean") {
+    return { ok: false, renewed: false };
+  }
+  const other = "otherAccount" in body ? body.otherAccount : undefined;
+  const otherAccount =
+    typeof other === "object" && other !== null && "name" in other && typeof other.name === "string" ? { name: other.name } : undefined;
+  return { ok: true, renewed: body.renewed, otherAccount };
+};
+
+let running: Promise<AppSessionRenewal> | undefined;
+
+/**
+ * Renews the mobile app's session with the phone's device key through Core. One renewal runs at a time in a page,
+ * and every caller shares it. An ended pairing or a blocked account leaves for the app's matching Start view.
+ */
+export const renewAppSession = (): Promise<AppSessionRenewal> => {
+  running ??= (async () => {
+    try {
+      const first = await call();
+      // After a rotation, a second call presents the new key and retires the old one.
+      if (first.renewed) await call();
+      return { ok: first.ok, otherAccount: first.otherAccount };
+    } finally {
+      running = undefined;
+    }
+  })();
+  return running;
+};

package/src/browser/live-connection.ts

@@ -0,0 +1,211 @@
+import { type LiveServerMessage, LiveServerMessageSchema } from "../events/live-protocol";
+import { createLiveWebSocket, type LiveWebSocket } from "./live-websocket";
+
+export type LiveSubscriptionHandlers<T> = {
+  /** The cursor the server-rendered state belongs to; `null` starts at the current position. */
+  cursor: string | null;
+  /** Validates one event's data. A failure reloads the state through `resync`. */
+  parse: (data: unknown) => T;
+  /** Applies events in order. Idempotent: reconnects and retries can repeat an event. */
+  apply: (events: { data: T; cursor: string }[]) => Promise<void>;
+  /** Loads the canonical state again; events after it follow. */
+  resync: () => Promise<void>;
+  /** The subscription ended because its resource is gone or no longer readable. */
+  revoked?: (code: "not_found" | "access_denied") => void;
+  /** Live updates stopped: the session ended, or `apply` or `resync` kept failing. Never called after `close()`. */
+  unavailable: () => void;
+};
+
+export type LiveSubscription = { close: () => void };
+
+export type LiveConnection = {
+  subscribe: <T>(channel: string, scope: unknown, handlers: LiveSubscriptionHandlers<T>) => LiveSubscription;
+};
+
+type Subscriber = {
+  frame: () => unknown;
+  confirmed: boolean;
+  receive: (message: LiveServerMessage) => void;
+  end: () => void;
+};
+
+type Shared = { socket: LiveWebSocket; subscribers: Map<string, Subscriber>; next: number };
+
+const RETRY_DELAYS_MS = [1_000, 3_000, 9_000];
+const MAX_BATCH = 100;
+/** Events that may wait for `apply`; more collapse into one `resync`, which covers them. */
+const MAX_WAITING = 10 * MAX_BATCH;
+
+/** One socket per URL and page, shared by every subscription on it. */
+const shared = new Map<string, Shared>();
+
+const parseMessage = (raw: string): LiveServerMessage | null => {
+  try {
+    const parsed = LiveServerMessageSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+};
+
+const connect = (url: string, activity: "visible" | "always"): Shared => {
+  const subscribers = new Map<string, Subscriber>();
+  const socket = createLiveWebSocket<LiveServerMessage>({
+    url,
+    activity,
+    parse: parseMessage,
+    onOpen: (controls) => {
+      for (const subscriber of subscribers.values()) {
+        subscriber.confirmed = false;
+        controls.send(subscriber.frame());
+      }
+    },
+    onMessage: (message) => {
+      if (message.t === "progress") {
+        for (const subscriber of subscribers.values()) if (subscriber.confirmed) subscriber.receive(message);
+        return;
+      }
+      if (message.t !== "error") subscribers.get(message.id)?.receive(message);
+    },
+    onFatal: () => {
+      if (shared.get(url)?.socket === socket) shared.delete(url);
+      for (const subscriber of [...subscribers.values()]) subscriber.end();
+    },
+  });
+  return { socket, subscribers, next: 0 };
+};
+
+type Work<T> = { kind: "events"; events: { data: T; cursor: string }[] } | { kind: "mark" | "resync"; cursor: string };
+
+/**
+ * Subscribes to channels of an application's live socket (`/api/<app>/live`).
+ * Each subscription applies its events serially and moves its cursor only after
+ * `apply` resolved or at a server mark, so a reconnect resumes exactly there.
+ * Only `resync` reloads state; a returning tab replays what it missed.
+ */
+export const liveConnection = (url: string, options: { activity?: "visible" | "always" } = {}): LiveConnection => ({
+  subscribe: <T>(channel: string, scope: unknown, handlers: LiveSubscriptionHandlers<T>): LiveSubscription => {
+    let connection = shared.get(url);
+    if (!connection) {
+      connection = connect(url, options.activity ?? "visible");
+      shared.set(url, connection);
+    }
+    const { socket, subscribers } = connection;
+    const id = String(++connection.next);
+    let cursor = handlers.cursor;
+    /** The cursor of a `resync` that has not finished: a reconnect resumes after it. */
+    let resyncAt: string | null = null;
+    let ended = false;
+    let running = false;
+    const work: Work<T>[] = [];
+
+    const attempt = async (run: () => Promise<void>): Promise<boolean> => {
+      for (let tries = 0; ; tries++) {
+        try {
+          await run();
+          return true;
+        } catch {
+          const delay = RETRY_DELAYS_MS[tries];
+          if (delay === undefined || ended) return false;
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          if (ended) return false;
+        }
+      }
+    };
+
+    const drain = async () => {
+      if (running) return;
+      running = true;
+      try {
+        while (work.length > 0 && !ended) {
+          const item = work.shift() as Work<T>;
+          if (item.kind === "mark") {
+            cursor = item.cursor;
+            continue;
+          }
+          const applied = item.kind === "events" ? await attempt(() => handlers.apply(item.events)) : await attempt(handlers.resync);
+          if (!applied) {
+            // A closed subscription reports nothing: its owner ended it.
+            if (ended) return;
+            stop();
+            handlers.unavailable();
+            return;
+          }
+          cursor = item.kind === "events" ? (item.events.at(-1)?.cursor ?? cursor) : item.cursor;
+          if (item.kind === "resync" && resyncAt === item.cursor) resyncAt = null;
+        }
+      } finally {
+        running = false;
+      }
+    };
+
+    /** Work queued before a resync is covered by the reloaded state. */
+    const resync = (at: string) => {
+      work.length = 0;
+      work.push({ kind: "resync", cursor: at });
+      resyncAt = at;
+    };
+
+    const waiting = () => work.reduce((count, item) => count + (item.kind === "events" ? item.events.length : 0), 0);
+
+    const subscriber: Subscriber = {
+      frame: () => {
+        const after = resyncAt ?? cursor;
+        return { t: "sub", id, channel, scope, ...(after ? { after } : {}) };
+      },
+      confirmed: false,
+      receive: (message) => {
+        if (ended) return;
+        if (message.t === "revoked") {
+          stop();
+          handlers.revoked?.(message.code);
+          return;
+        }
+        if (message.t === "ready" || message.t === "progress") {
+          subscriber.confirmed = true;
+          work.push({ kind: "mark", cursor: message.cursor });
+        } else if (message.t === "resync") {
+          subscriber.confirmed = true;
+          resync(message.cursor);
+        } else if (message.t === "event") {
+          let data: T;
+          try {
+            data = handlers.parse(message.data);
+          } catch {
+            resync(message.cursor);
+            void drain();
+            return;
+          }
+          const last = work.at(-1);
+          if (waiting() >= MAX_WAITING) resync(message.cursor);
+          else if (last?.kind === "events" && last.events.length < MAX_BATCH) last.events.push({ data, cursor: message.cursor });
+          else work.push({ kind: "events", events: [{ data, cursor: message.cursor }] });
+        }
+        void drain();
+      },
+      end: () => {
+        if (ended) return;
+        stop();
+        handlers.unavailable();
+      },
+    };
+
+    const stop = () => {
+      if (ended) return;
+      ended = true;
+      work.length = 0;
+      if (subscribers.get(id) !== subscriber) return;
+      subscribers.delete(id);
+      socket.send({ t: "unsub", id });
+      if (subscribers.size === 0 && shared.get(url) === connection) {
+        shared.delete(url);
+        socket.dispose();
+      }
+    };
+
+    subscribers.set(id, subscriber);
+    if (subscribers.size === 1) socket.connect();
+    else socket.send(subscriber.frame());
+    return { close: stop };
+  },
+});

package/src/browser/live-websocket.ts

@@ -13,6 +13,13 @@ export type LiveWebSocketClose = {
 
 export type LiveWebSocketControls = {
   markApplied: (cursor: string | null | undefined) => void;
+  /**
+   * The cursor the current connection subscribed from: the last applied cursor
+   * when the socket opened. A server that confirms exactly this cursor resumes
+   * the stream after it, so the page needs no snapshot refresh. Any other
+   * cursor means events between the two were skipped.
+   */
+  subscribedCursor: () => string | null;
   /** Forget an expired cursor before resubscribing from a fresh snapshot. */
   resetCursor: () => void;
   send: (message: unknown) => boolean;
@@ -23,7 +30,8 @@ export type LiveWebSocketOptions<TMessage> = {
   url: string | (() => string);
   initialCursor?: string | null;
   activity?: LiveWebSocketActivity;
-  subscribe: (cursor: string | null) => unknown;
+  /** The subscription sent when a socket opens; omit it when `onOpen` sends the subscriptions. */
+  subscribe?: (cursor: string | null) => unknown;
   parse: (raw: string) => TMessage | null;
   onOpen?: (controls: LiveWebSocketControls) => void;
   onMessage: (message: TMessage, controls: LiveWebSocketControls) => void;
@@ -62,12 +70,13 @@ const DEFAULT_RECONNECT = {
  */
 const CONNECT_TIMEOUT_MS = DEFAULT_RECONNECT.maxDelayMs;
 
-const defaultCloseError = ({ code, reason }: LiveWebSocketClose): LiveWebSocketError | null => {
-  if (code === 1008) return { code: reason || "access_denied", message: "Live access changed or expired." };
-  if (code === 1011) return { code: reason || "internal_error", message: "Live updates failed." };
-  if (code === 1013) return { code: reason || "backpressure", message: "Live updates are overloaded." };
-  return null;
-};
+/**
+ * Only a policy close (`1008`) ends live updates by default. Every other close,
+ * including `1011` (internal error) and `1013` (try again later), reconnects
+ * with backoff; the new subscription checks access again.
+ */
+const defaultCloseError = ({ code, reason }: LiveWebSocketClose): LiveWebSocketError | null =>
+  code === 1008 ? { code: reason || "access_denied", message: "Live access changed or expired." } : null;
 
 const socketUrl = (raw: string): string => {
   const url = new URL(raw, window.location.origin);
@@ -96,6 +105,7 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
   let connectStartedAt = 0;
   let reconnectAttempt = 0;
   let lastAppliedCursor = options.initialCursor ?? null;
+  let subscribedCursor = lastAppliedCursor;
   let started = false;
   let disposed = false;
   let terminated = false;
@@ -165,6 +175,7 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
 
   const controls: LiveWebSocketControls = {
     markApplied,
+    subscribedCursor: () => subscribedCursor,
     resetCursor,
     send,
     terminate: fatal,
@@ -210,6 +221,9 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
     }
     socket = next;
     connectStartedAt = Date.now();
+    // When the server first answered. A server can accept a subscription and fail right after, often with an error
+    // frame, so the backoff starts over only once the connection stayed up for the longest delay after that.
+    let answeredAt: number | null = null;
     connectTimer = setTimeout(() => {
       connectTimer = null;
       if (next.readyState === WebSocket.CONNECTING) abandonAttempt(next);
@@ -219,7 +233,9 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
       if (socket !== next || disposed || terminated) return;
       clearConnectDeadline();
       try {
-        if (!send(options.subscribe(lastAppliedCursor))) throw new Error("Live WebSocket subscription could not be sent");
+        subscribedCursor = lastAppliedCursor;
+        if (options.subscribe && !send(options.subscribe(subscribedCursor)))
+          throw new Error("Live WebSocket subscription could not be sent");
         setStatus("open");
         options.onOpen?.(controls);
       } catch (error) {
@@ -232,8 +248,8 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
       try {
         const message = options.parse(event.data);
         if (message) {
+          answeredAt ??= Date.now();
           options.onMessage(message, controls);
-          reconnectAttempt = 0;
         }
       } catch (error) {
         fatal(
@@ -249,8 +265,12 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
       clearConnectDeadline();
       if (disposed || terminated) return;
       const closeError = classifyClose({ code: event.code, reason: event.reason.trim() });
-      if (closeError) fatal(closeError, { code: event.code, reason: event.reason });
-      else scheduleReconnect();
+      if (closeError) {
+        fatal(closeError, { code: event.code, reason: event.reason });
+        return;
+      }
+      if (answeredAt !== null && Date.now() - answeredAt >= reconnect.maxDelayMs) reconnectAttempt = 0;
+      scheduleReconnect();
     };
 
     next.onerror = () => {

package/src/browser/live.ts

@@ -0,0 +1,2 @@
+export * from "./live-connection";
+export * from "./live-websocket";

package/src/contracts/app.ts

@@ -88,6 +88,14 @@ export type AppCliModule = {
 /** `cld` modules keyed by module name, the command `cld <name>`. */
 export type AppCliModules = Readonly<Record<string, AppCliModule>>;
 
+/** An application's part of the mobile app (preview). */
+export type AppPwaPart = {
+  /** Always `/pwa/<app id>`. */
+  href: string;
+  /** Coarse visibility in the mobile app, like `nav.requiresRoles`. Routes and services still authorize. */
+  requiresRoles?: Role[];
+};
+
 export type AppMeta = {
   id: string;
   name: string;
@@ -118,6 +126,8 @@ export type AppMeta = {
   legalLinks?: LegalLink[];
   /** Static search destinations, visible when the app is in the user's navigation catalog. */
   searchLinks?: readonly AppSearchLink[];
+  /** The app's pages in the installable mobile app (preview), at `href` = `/pwa/<id>`. */
+  pwa?: AppPwaPart;
   /**
    * Dashboard widget endpoints this app exposes. Each entry references an
    * HTTP endpoint that returns a `WidgetResponse` (see `contracts/widgets.ts`).

package/src/contracts/index.ts

@@ -9,6 +9,7 @@ export * from "./contact-directory";
 export * from "./notification-types";
 export * from "./posix";
 export * from "./profile";
+export * from "./pwa";
 // Core app bar administration and shared shortcut values.
 export { RailAccessSchema, type RailAdminEntry, RailAdminInputSchema, RailAdminSchema, type RailAdminState } from "./rail-admin";
 export type { RailShortcut } from "./rail-preferences";

package/src/contracts/pwa-paths.ts

@@ -0,0 +1,6 @@
+/**
+ * Paths of the installable mobile app, without schemas, so browser code that runs on every page can test for an
+ * app page without loading the contract's validators.
+ */
+export const PWA_SCOPE = "/pwa/";
+export const PWA_AUTH_PATH = "/pwa/_auth";