@k2b/cloud 0.22.0 → 0.23.0

package/src/events/live-protocol.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+
+/** Messages a live socket accepts: subscriptions only. Writes go over HTTP. */
+export const LiveClientMessageSchema = z.discriminatedUnion("t", [
+  z
+    .object({
+      t: z.literal("sub"),
+      id: z.string().min(1).max(32),
+      channel: z.string().min(1).max(64),
+      scope: z.unknown(),
+      after: z.string().min(1).max(256).optional(),
+    })
+    .strict(),
+  z.object({ t: z.literal("unsub"), id: z.string().min(1).max(32) }).strict(),
+]);
+export type LiveClientMessage = z.infer<typeof LiveClientMessageSchema>;
+
+/**
+ * Messages a live socket sends. Events of one subscription arrive in topic order
+ * and strictly after its `ready` or `resync` cursor; `progress` says every event
+ * up to its cursor was sent to this socket.
+ */
+export const LiveServerMessageSchema = z.discriminatedUnion("t", [
+  z.object({ t: z.literal("ready"), id: z.string(), cursor: z.string() }),
+  z.object({ t: z.literal("event"), id: z.string(), cursor: z.string(), data: z.unknown() }),
+  z.object({ t: z.literal("progress"), cursor: z.string() }),
+  z.object({ t: z.literal("resync"), id: z.string(), cursor: z.string() }),
+  z.object({ t: z.literal("revoked"), id: z.string(), code: z.enum(["not_found", "access_denied"]) }),
+  z.object({ t: z.literal("error"), code: z.string(), message: z.string() }),
+]);
+export type LiveServerMessage = z.infer<typeof LiveServerMessageSchema>;

package/src/events/live.ts

@@ -0,0 +1,298 @@
+import type { Topic, TopicConfig } from "@k2b/sync";
+import { type ServerWebSocket, type SQL, sql } from "bun";
+import { type Context, Hono } from "hono";
+import { upgradeWebSocket } from "hono/bun";
+import type { z } from "zod";
+import { lazySync } from "../_internal/process-sync";
+import { type AuthContext, auth } from "../server/middleware/auth";
+import { rateLimit } from "../server/middleware/rate-limit";
+import { logger } from "../services/logging";
+import { createPgOutbox } from "../services/outbox";
+import * as settings from "../services/settings";
+import { publicCloudOrigin } from "../shared/app-url";
+import {
+  createLiveEngine,
+  type LiveChannel,
+  type LiveConnectionHandle,
+  type LiveEngine,
+  type LiveEnvelope,
+  type LiveViewer,
+} from "./live-engine";
+
+export type { LiveChannel, LiveViewer } from "./live-engine";
+
+const RECONCILE_INTERVAL_MS = 1_000;
+const STALE_CHECK_INTERVAL_MS = 60_000;
+
+/**
+ * The live topic of one application. Frozen: Sync rejects a declaration that
+ * differs from the existing stream, so two releases with different values
+ * would break each other during a rollout. A change ships under a new id.
+ */
+export const liveTopicConfig = (appId: string) =>
+  ({
+    id: `cloud:live:${appId}`,
+    owner: "cloud",
+    retention: { maxAgeMs: 24 * 3_600_000, maxBytes: 64 * 1024 ** 2 },
+    maxPayloadBytes: 40 * 1024,
+    deadLetterRetention: { maxBytes: 1024 ** 2 },
+  }) satisfies TopicConfig;
+
+type LiveOutboxRow = { id: string; attempts: number; ordering_key: string; payload: LiveEnvelope };
+
+const log = logger("events:live");
+
+const liveTopics = lazySync((sync) => {
+  const topics = new Map<string, Topic<LiveEnvelope>>();
+  return (appId: string): Topic<LiveEnvelope> => {
+    const existing = topics.get(appId);
+    if (existing) return existing;
+    const topic = sync.topic<LiveEnvelope>(liveTopicConfig(appId));
+    topics.set(appId, topic);
+    return topic;
+  };
+});
+
+/** Dispatcher of one application's live rows: ordered per key, deleted once published. */
+export const liveOutbox = (appId: string, publish: (row: LiveOutboxRow) => Promise<unknown>) =>
+  createPgOutbox<LiveOutboxRow>({
+    table: "events.outbox",
+    name: `events:live:${appId}`,
+    where: { kind: "live", app_id: appId },
+    orderBy: "ordering_key",
+    sequence: "seq",
+    onDelivered: "delete",
+    reconcileIntervalMs: RECONCILE_INTERVAL_MS,
+    publish,
+  });
+
+/** Applications whose live updates this process defines, with the wake of their running dispatcher. */
+const dispatchers = new Map<string, (() => void) | null>();
+/** Live sockets served by this process; they close when the application stops. */
+const engines = new Set<LiveEngine>();
+/** Set when the application stops delivery: its engines stay stopped until delivery starts again. */
+let stopped = false;
+
+/** Closes every live socket of this process with 1012, so clients reconnect to another replica. */
+export const stopLiveEngines = () => {
+  stopped = true;
+  for (const engine of engines) engine.stop();
+};
+
+const logStaleRows = async (appId: string): Promise<void> => {
+  const [row] = await sql<{ count: number; oldest_seconds: number | null }[]>`
+    SELECT COUNT(*)::int AS count, EXTRACT(EPOCH FROM now() - MIN(created_at))::int AS oldest_seconds
+    FROM events.outbox
+    WHERE kind = 'live' AND app_id = ${appId} AND created_at < now() - interval '60 seconds'
+  `;
+  if (row && row.count > 0) log.warn("Live updates wait to be published", { appId, count: row.count, oldestSeconds: row.oldest_seconds });
+};
+
+/**
+ * Publishes the rows of the live definitions in this process. `app.start()`
+ * calls it with the started application's ID; it does nothing without a
+ * definition, and fails when a definition names another application or Core
+ * has not created the outbox yet.
+ */
+export const startLiveOutbox = async (startedAppId: string): Promise<(() => Promise<void>) | null> => {
+  const appIds = [...dispatchers.keys()];
+  if (appIds.length === 0) return null;
+  const foreign = appIds.filter((appId) => appId !== startedAppId);
+  if (foreign.length > 0) {
+    throw new Error(
+      `defineLive() names "${foreign.join('", "')}", but this process starts "${startedAppId}". Use the ID from the application's declaration.`,
+    );
+  }
+  const [installed] = await sql<{ ready: boolean }[]>`
+    SELECT to_regprocedure('events.enqueue(uuid,text,text,text,jsonb,text)') IS NOT NULL AS ready
+  `;
+  if (!installed?.ready) {
+    throw new Error(
+      `"${appIds.join('", "')}" writes live updates to events.outbox, which does not exist. Update Cloud Core first: its migration creates the outbox.`,
+    );
+  }
+  // Delivery starts again: the engines stopped before give way to new ones.
+  if (stopped) {
+    engines.clear();
+    stopped = false;
+  }
+  const stops = appIds.map((appId) => {
+    const topic = liveTopics()(appId);
+    const outbox = liveOutbox(appId, (row) => topic.publish({ data: row.payload, orderingKey: row.ordering_key, idempotencyKey: row.id }));
+    outbox.start();
+    dispatchers.set(appId, () => void outbox.notify());
+    const staleCheck = setInterval(() => {
+      logStaleRows(appId).catch((error) =>
+        log.warn("Live outbox check failed", { appId, error: error instanceof Error ? error.message : String(error) }),
+      );
+    }, STALE_CHECK_INTERVAL_MS);
+    staleCheck.unref();
+    return async () => {
+      clearInterval(staleCheck);
+      dispatchers.set(appId, null);
+      await outbox.stop();
+    };
+  });
+  return async () => {
+    stopLiveEngines();
+    await Promise.all(stops.map((stop) => stop()));
+  };
+};
+
+/**
+ * The viewer of an authenticated request. Its ID separates every credential of
+ * one principal that can decide differently: an app session holds no `admin`
+ * role, and an API key or OAuth token is limited by its scopes.
+ */
+const viewerOf = <Env extends AuthContext>(c: Context<Env>): LiveViewer => {
+  const accessSubject = c.get("accessSubject");
+  const scopes = c.get("credentialScopes") ?? [];
+  const principal = accessSubject.type === "user" ? `user:${accessSubject.userId}` : `service_account:${accessSubject.serviceAccountId}`;
+  const credential =
+    c.get("credentialKind") === "session"
+      ? c.get("sessionKind") === "app"
+        ? ":app"
+        : ""
+      : `:scopes=${[...new Set(scopes)].sort().join(",")}`;
+  return { id: `${principal}${credential}`, actor: c.get("actor"), accessSubject, scopes };
+};
+
+type ProbeEnv = AuthContext & { Bindings: { found: (viewer: LiveViewer) => void } };
+
+/** The ordinary credential check of every API request, run again for an open socket. */
+const probe = new Hono<ProbeEnv>()
+  .onError((error) => {
+    throw error;
+  })
+  .get("*", auth.requireRole("authenticated"), (c) => {
+    c.env.found(viewerOf(c));
+    return c.body(null, 204);
+  });
+
+/** Checks the socket's credential again: `null` once the session or token is no longer valid. */
+const revalidator = (c: Context<AuthContext>) => {
+  const headers = new Headers();
+  for (const name of ["cookie", "authorization"]) {
+    const value = c.req.header(name);
+    if (value) headers.set(name, value);
+  }
+  const path = c.req.path;
+  return async (): Promise<LiveViewer | null> => {
+    let viewer: LiveViewer | null = null;
+    await probe.request(path, { headers }, { found: (found: LiveViewer) => (viewer = found) });
+    return viewer;
+  };
+};
+
+type Refusal = { code: "login_required" | "forbidden_origin" | "missing_scope"; message: string };
+
+/**
+ * Why the socket may not serve this request. The refusal is sent on an
+ * accepted socket, with close code 1008: the gateway accepts the browser's
+ * socket before it reaches the application and would turn a refused handshake
+ * into a retryable 1012.
+ */
+const refusalOf = async (c: Context<AuthContext>): Promise<Refusal | null> => {
+  if (!c.get("actor")) return { code: "login_required", message: "Sign in again to receive live updates." };
+  // A session cookie travels with every page of the browser, so a browser's socket must come from Cloud's own origin.
+  // Browsers always send Origin on a socket; a client without one is no page that another site could have opened.
+  const origin = c.req.header("Origin");
+  if (
+    c.get("credentialKind") === "session" &&
+    origin !== undefined &&
+    origin !== publicCloudOrigin(await settings.get<string>("app.url"))
+  ) {
+    return { code: "forbidden_origin", message: "Live sockets signed in with a session must come from the Cloud origin." };
+  }
+  const oauthScopes = c.get("oauthScopes");
+  if (oauthScopes && !oauthScopes.includes("read") && !oauthScopes.includes("admin")) {
+    return { code: "missing_scope", message: "Live updates need an OAuth token with the read scope." };
+  }
+  return null;
+};
+
+/**
+ * Live updates of one application: hints, optionally with data, for its own
+ * open tabs. Define them once at module scope; `app.start()` then publishes the
+ * rows that `publish()` writes, and `routes()` serves them to browsers.
+ * `appId` is required and must be the ID that the process starts; it is never
+ * derived from the process.
+ */
+export const defineLive = <const Event extends z.ZodType>(definition: { appId: string; event: Event }) => {
+  const { appId, event } = definition;
+  if (!dispatchers.has(appId)) dispatchers.set(appId, null);
+  return {
+    /**
+     * Writes one update in `tx`, the transaction that makes the change: a
+     * rollback writes nothing, a commit publishes it at least once. Data above
+     * 32 KiB becomes a reload hint for `key`; `data` must not hold anything a
+     * reader of `key` may not see. `access: true` announces that who may read
+     * `key` changed, in a row of its own before the data: every replica checks
+     * its subscribers of `key` again before it delivers the data, and its
+     * collections right after.
+     */
+    publish: async (
+      tx: SQL,
+      input: { key: string; data: z.input<Event>; access?: true } | { key: string; data?: undefined; access: true },
+    ): Promise<void> => {
+      // Store the JSON form of the input, and validate exactly that form here:
+      // the browser parses it, and data that does not survive JSON fails this write.
+      const data: unknown = input.data === undefined ? undefined : JSON.parse(JSON.stringify(input.data));
+      if (data !== undefined) event.parse(data);
+      const enqueue = (envelope: LiveEnvelope) =>
+        tx`SELECT events.enqueue(${crypto.randomUUID()}::uuid, ${appId}, 'live', ${input.key}, ${JSON.stringify(envelope)}::text::jsonb)`;
+      // The access change is a row of its own, so data too large for the outbox cannot drop it.
+      if (input.access) await enqueue({ v: 1, k: input.key, a: true });
+      if (data !== undefined) await enqueue({ v: 1, k: input.key, d: data });
+    },
+    /** Publishes committed updates now instead of within the next second. Call it after the commit. */
+    wake: (): void => dispatchers.get(appId)?.(),
+    /** The topic head. Read it before loading the snapshot it belongs to. */
+    cursor: (): Promise<string> => liveTopics()(appId).head(),
+    /**
+     * The live socket with these channels. Mount it once, at `/api/<app>/live`.
+     * It authenticates like any API request; a session needs the Cloud origin
+     * and an OAuth token the `read` scope. A refused socket receives `error`
+     * and closes with 1008. Channels are passed here, not to
+     * `defineLive()`, because they check access with the domain services that
+     * themselves publish updates.
+     */
+    routes: <const Scopes extends Record<string, z.ZodType>>(channels: { [Name in keyof Scopes]: LiveChannel<Scopes[Name]> }) => {
+      let engine: LiveEngine | null = null;
+      const serve = (): LiveEngine => {
+        if (engine && engines.has(engine)) return engine;
+        engine = createLiveEngine({ appId, topic: () => liveTopics()(appId), channels });
+        engines.add(engine);
+        // A socket that opens while the application stops closes with 1012 and starts nothing.
+        if (stopped) engine.stop();
+        return engine;
+      };
+      return new Hono<AuthContext>().get(
+        "/",
+        rateLimit({ limitPerSecond: 5 }),
+        auth.requireRole("*"),
+        upgradeWebSocket(async (c) => {
+          const refusal = await refusalOf(c);
+          if (refusal) {
+            return {
+              onOpen: (_event, ws) => {
+                ws.send(JSON.stringify({ t: "error", ...refusal }));
+                ws.close(1008, refusal.code);
+              },
+            };
+          }
+          const viewer = viewerOf(c);
+          const revalidate = revalidator(c);
+          let connection: LiveConnectionHandle | null = null;
+          return {
+            onOpen: (_event, ws) => {
+              connection = serve().open(ws.raw as ServerWebSocket<unknown>, viewer, revalidate);
+            },
+            onMessage: (message) => connection?.message(message.data),
+            onClose: () => connection?.closed(),
+          };
+        }),
+      );
+    },
+  };
+};

package/src/server/actor.ts

@@ -24,6 +24,13 @@ export const userFromActor = (actor: RequestActor | undefined): ActingUser | nul
   return actor.kind === "user" ? actor.user : actor.delegatedUser;
 };
 
+/**
+ * True when the actor works through the mobile app's session (directly, through an invocation or
+ * in an Assistant turn started there). Such an actor must not create authority that outlives the
+ * phone: sign-in methods, API keys or background mandates.
+ */
+export const isAppSessionActor = (actor: RequestActor | undefined): boolean => actor?.kind === "user" && actor.sessionKind === "app";
+
 /** Same, read off the request context. */
 export const getUserBackedActor = <T extends AuthContext>(c: Context<T>): ActingUser | null =>
   userFromActor(c.get("actor") as RequestActor | undefined);

package/src/server/api-client.ts

@@ -1,5 +1,6 @@
 import type { Hono } from "hono";
 import { hc } from "hono/client";
+import { insideMobileApp, renewAppSession } from "../browser/app-session";
 
 export type CreateApiClientConfig = {
   baseUrl?: string;
@@ -10,9 +11,29 @@ export type CreateApiClientConfig = {
 // ==========================
 
 /**
- * Creates a typed Hono API client.
+ * A request from a page of the mobile app that answers `401` met an ended app session. The client renews it and sends
+ * the request once more, so the action is not lost. A `401` means the server applied nothing: the auth middleware
+ * answers it before any handler runs, and a route that answers `401` itself must do so before it changes anything.
  */
-export const createApiClient = <TApi extends Hono<any, any, any>>(config: CreateApiClientConfig = {}) => hc<TApi>(config.baseUrl ?? "/api");
+const fetchInMobileApp = async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]): Promise<Response> => {
+  const response = await fetch(input, init);
+  if (response.status !== 401 || init?.body instanceof ReadableStream) return response;
+  // Also after a renewal that found the session current: another renewal on this page may have replaced the session
+  // after this request left with the old one.
+  if (!(await renewAppSession()).ok) return response;
+  return fetch(input, init);
+};
+
+// On the web, the client hands back fetch's own promise, so its answers arrive exactly as without the app session.
+const fetchWithAppSession = (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]): Promise<Response> =>
+  insideMobileApp() ? fetchInMobileApp(input, init) : fetch(input, init);
+
+/**
+ * Creates a typed Hono API client. On a page of the mobile app, it renews an expired app session and repeats the
+ * request once.
+ */
+export const createApiClient = <TApi extends Hono<any, any, any>>(config: CreateApiClientConfig = {}) =>
+  hc<TApi>(config.baseUrl ?? "/api", { fetch: fetchWithAppSession });
 
 /**
  * Untyped fallback API client for core-only browser code.

package/src/server/index.ts

@@ -1,4 +1,5 @@
-export { expectUserBackedActor, getUserBackedActor, userFromActor } from "./actor";
+export { buildMetadata } from "../_internal/build-metadata";
+export { expectUserBackedActor, getUserBackedActor, isAppSessionActor, userFromActor } from "./actor";
 export type { ApiErrorBody, ApiErrorResponse, ApiErrorStatus } from "./api";
 export { api, respond, respondMessage } from "./api";
 export type { CreateApiClientConfig } from "./api-client";
@@ -74,6 +75,7 @@ export {
   getEffectiveGroupIds,
   getEffectiveGroups,
   getEffectivePermission,
+  getEffectivePermissions,
   hasPermission,
   images,
   isServiceError,

package/src/server/middleware/auth.ts

@@ -7,8 +7,9 @@ import { isReservedWorkloadApiCredential } from "../../services/identity/workloa
 import { oauthTokens } from "../../services/oauth-tokens";
 import { serviceAccountCredentials } from "../../services/service-account-credentials";
 import type { ServiceAccount } from "../../services/service-accounts";
-import { session } from "../../services/session";
+import { type AuthenticatedSession, isAppPagePath, type SessionKind, session } from "../../services/session";
 import { createLoginRedirectUrl } from "../../shared/redirect";
+import { isAppSessionActor } from "../actor";
 import type { AccessSubject } from "../services/access";
 
 // ==========================
@@ -31,6 +32,12 @@ export type UserRequestActor = {
   kind: "user";
   user: User;
   delegation?: InvocationProvenance;
+  /**
+   * `"app"` when the person acts through the mobile app's session: directly, through an
+   * invocation, or in an Assistant turn started there. Such an actor never carries the
+   * `admin` role and must not create authority that outlives the phone.
+   */
+  sessionKind?: "app";
 };
 
 export type ServiceAccountRequestActor =
@@ -73,6 +80,8 @@ export type AuthContext = {
     sessionToken?: string;
     /** Credential class resolved once for downstream delegation. */
     credentialKind?: RequestCredentialKind;
+    /** With `credentialKind: "session"`: `"app"` for a paired phone in the mobile app, otherwise `"web"`. */
+    sessionKind?: SessionKind;
     /** Constraints carried by OAuth/API credentials; absent sessions are unrestricted by transport scope. */
     credentialScopes?: string[];
     /** OAuth scopes for bearer-token requests. Absent for sessions and API credentials. */
@@ -123,20 +132,28 @@ const loadAuthenticatedActorUncached = async (
   c: Context<AuthContext>,
   options: Pick<RoleOptions, "oauthAudience"> = {},
 ): Promise<AuthenticatedActorResult> => {
-  const token = session.getToken(c);
-  const authenticatedSession = token ? await session.authenticateRequest(c, token) : null;
-  const user = authenticatedSession?.user ?? null;
+  let token = session.getToken(c);
+  let authenticatedSession: AuthenticatedSession | null = token ? await session.authenticateRequest(c, token) : null;
+  const fallback = authenticatedSession ? null : session.appSessionFallback(c, token);
+  if (fallback) {
+    token = fallback;
+    authenticatedSession = await session.authenticateRequest(c, fallback);
+  }
+  // Below /pwa/ only an app session counts: no web session, bearer or API key reaches app pages.
+  if (isAppPagePath(c.req.path) && authenticatedSession?.data.kind !== "app") return { token: null, user: null, actor: null };
 
-  if (user && token) {
-    c.set("actor", { kind: "user", user });
+  if (authenticatedSession && token) {
+    const { user } = authenticatedSession;
+    const actor: UserRequestActor = { kind: "user", user, ...(authenticatedSession.data.kind === "app" ? { sessionKind: "app" } : {}) };
+    c.set("actor", actor);
     c.set("accessSubject", { type: "user", userId: user.id });
     c.set("user", user);
     c.set("sessionToken", token);
     c.set("credentialKind", "session");
+    c.set("sessionKind", authenticatedSession.data.kind);
+    return { token, user, actor };
   }
 
-  if (user) return { token, user, actor: { kind: "user", user } };
-
   const bearer = session.getBearerToken(c);
   if (bearer && serviceAccountCredentials.isApiToken(bearer)) {
     const authResult = await serviceAccountCredentials.authenticateApiToken(bearer);
@@ -224,6 +241,44 @@ const loadAuthenticatedActor = (
   return pending;
 };
 
+/**
+ * Re-checks the credential that admitted this request, past the per-request
+ * cache, for a response that outlives its request such as a stream. True while
+ * that credential still authenticates the same actor; pass the same
+ * `oauthAudience` the route admitted with. Invocation credentials are bound to
+ * one call and always fail.
+ */
+export const isRequestCredentialCurrent = async (
+  c: Context<AuthContext>,
+  options: Pick<RoleOptions, "oauthAudience"> = {},
+): Promise<boolean> => {
+  const actor = c.get("actor");
+  if (!actor) return false;
+  const credentialKind = c.get("credentialKind");
+  if (credentialKind === "session") {
+    const token = c.get("sessionToken");
+    if (!token || actor.kind !== "user") return false;
+    return (await session.authenticateUserId(token)) === actor.user.id;
+  }
+
+  const bearer = session.getBearerToken(c);
+  if (!bearer) return false;
+  if (credentialKind === "api_key") {
+    if (actor.kind !== "service_account") return false;
+    const current = await serviceAccountCredentials.authenticateApiToken(bearer);
+    if (current?.delegatedUser && isAccountExpired(current.delegatedUser.accountExpires)) return false;
+    return current?.credential.id === actor.credentialId;
+  }
+  if (credentialKind === "oauth") {
+    const expectedAudience = typeof options.oauthAudience === "function" ? await options.oauthAudience() : options.oauthAudience;
+    const current = await oauthTokens.verifyAccessToken(bearer, expectedAudience);
+    if (!current) return false;
+    if (current.kind === "user") return actor.kind === "user" && current.user.id === actor.user.id;
+    return actor.kind === "service_account" && current.serviceAccount.id === actor.serviceAccount.id;
+  }
+  return false;
+};
+
 /**
  * Universal auth middleware. Handles authentication AND authorization.
  *
@@ -342,6 +397,21 @@ const getAuthority = (c: Context<AuthContext>): RequestAuthority => {
   };
 };
 
+/**
+ * True when the request acts through the mobile app's session, directly or through an
+ * invocation made for one. Such requests cannot create authority that outlives the phone.
+ */
+const isAppSession = (c: Context<AuthContext>): boolean => isAppSessionActor(c.get("actor"));
+
+/** The standard answer for actions the mobile app may not take. */
+export const APP_SESSION_FORBIDDEN = { code: "FORBIDDEN", message: "Use Cloud on the web for this." } as const;
+
+/**
+ * Rejects the mobile app's session with `403` {@link APP_SESSION_FORBIDDEN}. Use it on every route
+ * that creates authority outliving the phone: sign-in methods, API keys, background mandates.
+ */
+const rejectAppSession = createMiddleware<AuthContext>(async (c, next) => (isAppSession(c) ? c.json(APP_SESSION_FORBIDDEN, 403) : next()));
+
 /** Preset: Redirect to a fixed URL on rejection */
 const redirect = (url: string): RoleOptions => ({
   onReject: () => url,
@@ -379,6 +449,8 @@ export const auth = {
   session,
   requireRole,
   requireUser,
+  isAppSession,
+  rejectAppSession,
   requireOAuthScope,
   getAuthority,
   requireAccount,

package/src/server/middleware/openapi.ts

@@ -69,7 +69,8 @@ export const openApiMeta: Partial<GenerateSpecOptions> = {
           type: "apiKey",
           in: "cookie",
           name: "session_token",
-          description: "Session cookie (automatically set after login)",
+          description:
+            "Session cookie (automatically set after login). Requests from the mobile app carry the `pwa_session` cookie instead; it is accepted the same way, except where an endpoint needs the web.",
         },
         bearerAuth: {
           type: "http",

package/src/server/services/access.ts

@@ -394,6 +394,55 @@ export const getEffectivePermission = async (params: {
   return rows[0]?.permission ?? "none";
 };
 
+/** A Postgres UUID[] literal that keeps `null` entries in place. */
+const uuidArrayWithNulls = (values: readonly (string | null)[]): string => `{${values.map((value) => value ?? "NULL").join(",")}}`;
+
+/**
+ * The effective permission of many subjects on one resource, with one query.
+ * Each result is what `getEffectivePermission()` returns for the subject at the
+ * same position: the same direct, nested-group, authenticated, and public rules.
+ * Use it where one decision is needed for many readers, such as a live
+ * channel's `authorize`.
+ */
+export const getEffectivePermissions = async (params: {
+  accessIds: string[];
+  subjects: readonly AccessSubject[];
+}): Promise<PermissionLevel[]> => {
+  const { accessIds, subjects } = params;
+  if (subjects.length === 0) return [];
+  if (accessIds.length === 0) return subjects.map(() => "none");
+  const userIds = subjects.map((subject) => (subject.type === "user" ? subject.userId : null));
+  const serviceAccountIds = subjects.map((subject) => (subject.type === "service_account" ? subject.serviceAccountId : null));
+  // The tiers of buildAccessPrincipalTierConditions, evaluated per row of `s`; every subject here is authenticated.
+  const rows = await sql<{ position: number; permission: PermissionLevel | null }[]>`
+    SELECT s.position::int AS position, (
+      SELECT a.permission
+      FROM auth.access a
+      WHERE a.id = ANY(${toPgUuidArray(accessIds)}::uuid[])
+        AND (
+          a.service_account_id = s.service_account_id
+          OR a.user_id = s.user_id
+          OR (s.user_id IS NOT NULL AND a.group_id IN (${recursiveGroupIdsSubquery(sql`s.user_id`)}))
+          OR a.authenticated_only = true
+          OR (a.user_id IS NULL AND a.group_id IS NULL AND a.service_account_id IS NULL AND a.authenticated_only = false)
+        )
+      ORDER BY
+        CASE a.permission
+          WHEN 'admin' THEN 4
+          WHEN 'write' THEN 3
+          WHEN 'read' THEN 2
+          WHEN 'none' THEN 1
+        END DESC
+      LIMIT 1
+    ) AS permission
+    FROM unnest(${uuidArrayWithNulls(userIds)}::uuid[], ${uuidArrayWithNulls(serviceAccountIds)}::uuid[])
+      WITH ORDINALITY AS s(user_id, service_account_id, position)
+  `;
+  const permissions = subjects.map((): PermissionLevel => "none");
+  for (const row of rows) permissions[row.position - 1] = row.permission ?? "none";
+  return permissions;
+};
+
 /**
  * Lists concrete users reachable from auth.access entries.
  *

package/src/server/services/index.ts

@@ -23,6 +23,7 @@ export {
   getEffectiveGroupIds,
   getEffectiveGroups,
   getEffectivePermission,
+  getEffectivePermissions,
   hasPermission,
   listUsersWithAccess,
   PERMISSION_LEVELS,