@k2b/cloud 0.21.1 → 0.23.0

package/src/ai/client/transport.ts

@@ -13,6 +13,38 @@ export type AiConversationStreamTransport = {
   }) => AiStreamHandle;
 };
 
+/**
+ * Why a conversation stream ended for good. The codes match the live
+ * WebSocket's turn errors and revocations.
+ */
+export type AiStreamErrorCode = "login_required" | "access_denied" | "not_found";
+
+/** A stream that will not recover by reconnecting; `message` comes from the server when it sent one. */
+export class AiStreamError extends Error {
+  readonly code: AiStreamErrorCode;
+
+  constructor(code: AiStreamErrorCode, message: string) {
+    super(message);
+    this.name = "AiStreamError";
+    this.code = code;
+  }
+}
+
+const TERMINAL_STATUS_CODES: Readonly<Record<number, AiStreamErrorCode>> = {
+  401: "login_required",
+  403: "access_denied",
+  404: "not_found",
+};
+
+const terminalStreamError = async (response: Response, code: AiStreamErrorCode): Promise<AiStreamError> => {
+  const body: unknown = await response.json().catch(() => null);
+  const message =
+    body && typeof body === "object" && "message" in body && typeof body.message === "string" && body.message
+      ? body.message
+      : `AI stream failed: ${response.status}`;
+  return new AiStreamError(code, message);
+};
+
 const RECONNECT_BASE_MS = 500;
 const RECONNECT_MAX_MS = 5_000;
 const CONNECT_TIMEOUT_MS = 10_000;
@@ -53,12 +85,15 @@ export async function* parseAiSse(response: Response, signal: AbortSignal): Asyn
 /**
  * Subscribe to a conversation's SSE stream with automatic reconnect. Each
  * (re)connect starts with a fresh `state` event, so the projection self-heals on
- * every reconnect without cursor bookkeeping.
+ * every reconnect without cursor bookkeeping. A 401, 403, or 404 cannot heal
+ * that way: the subscription stops and reports an `AiStreamError` once through
+ * `onError`, its only signal that the stream ended. Status stays where it was.
  */
 export const subscribeAiStream = (input: {
   url: string;
   onEvent: (event: AiStreamEvent) => void;
   onStatus?: (status: AiStreamConnectionStatus) => void;
+  onError?: (error: AiStreamError) => void;
   fetch?: AiStreamFetch;
 }): AiStreamHandle => {
   const fetchStream: AiStreamFetch = input.fetch ?? fetch;
@@ -80,8 +115,17 @@ export const subscribeAiStream = (input: {
       try {
         input.onStatus?.(reconnectDelay === RECONNECT_BASE_MS ? "connecting" : "reconnecting");
         const response = await fetchStream(input.url, { signal: attempt.signal, headers: { Accept: "text/event-stream" } });
-        clearConnectTimer();
         if (stopped) return;
+        const terminalCode = TERMINAL_STATUS_CODES[response.status];
+        if (terminalCode) {
+          // The connect timeout still bounds reading the error body.
+          const error = await terminalStreamError(response, terminalCode);
+          if (stopped) return;
+          stopped = true;
+          input.onError?.(error);
+          return;
+        }
+        clearConnectTimer();
         if (!response.ok || !response.body) throw new Error(`AI stream failed: ${response.status}`);
         input.onStatus?.("open");
         reconnectDelay = RECONNECT_BASE_MS;
@@ -113,5 +157,5 @@ export const subscribeAiStream = (input: {
 };
 
 export const aiSseConversationStreamTransport: AiConversationStreamTransport = {
-  subscribe: ({ url, onEvent, onStatus }) => subscribeAiStream({ url, onEvent, onStatus }),
+  subscribe: ({ url, onEvent, onStatus, onError }) => subscribeAiStream({ url, onEvent, onStatus, onError }),
 };

package/src/ai/live-routes.ts

@@ -353,8 +353,8 @@ const buildAiLiveRoutes = (config: AiLiveRoutesConfig = {}) => {
 
   return new Hono<AuthContext>().get(
     "/",
-    upgradeWebSocket((c) => {
-      const sessionToken = auth.session.getToken(c);
+    upgradeWebSocket(async (c) => {
+      const sessionToken = await auth.session.resolveToken(c);
       const messages = aiLiveMessages(getLocale(c));
       let ctx: WsContext | null = null;
       let processing: Promise<void> = Promise.resolve();

package/src/ai/pdf-render.ts

@@ -1,5 +1,5 @@
-import { fileURLToPath } from "node:url";
 import { z } from "zod";
+import { spawnCanvasWorker } from "../_internal/canvas-worker";
 
 declare const __CLOUD_PDF_RENDER_WORKER__: string | undefined;
 let activeRenders = 0;
@@ -31,27 +31,7 @@ export async function renderPdfPages(bytes: Uint8Array, pages: number[] = [1], s
       typeof __CLOUD_PDF_RENDER_WORKER__ === "string"
         ? new URL(__CLOUD_PDF_RENDER_WORKER__, import.meta.url)
         : new URL("./pdf-render-worker.ts", import.meta.url);
-    // RLIMIT_DATA bounds the decoder heap/native writable mappings on Linux.
-    // Positional arguments keep paths out of shell code. No elevated privileges.
-    const child = Bun.spawn(
-      ["/bin/sh", "-c", 'ulimit -d 524288 || exit 70; exec "$@"', "pdf-decoder", process.execPath, "--no-env-file", fileURLToPath(worker)],
-      {
-        stdin: new Blob([JSON.stringify({ pdf: Buffer.from(bytes).toString("base64"), pages })]),
-        stdout: "pipe",
-        stderr: "ignore",
-        // No application credentials or configuration reach the decoder, only fixed
-        // thread pool sizes: the Bun work pool, canvas tokio runtime, and JSC GC
-        // markers otherwise grow with the host's cores, and RLIMIT_DATA also counts
-        // each thread's stack and allocator memory.
-        env: {
-          PATH: process.env.PATH,
-          LANG: "C.UTF-8",
-          UV_THREADPOOL_SIZE: "2",
-          TOKIO_WORKER_THREADS: "2",
-          BUN_JSC_numberOfGCMarkers: "2",
-        },
-      },
-    );
+    const child = spawnCanvasWorker(worker, "pdf-decoder", JSON.stringify({ pdf: Buffer.from(bytes).toString("base64"), pages }));
     const stop = () => child.kill("SIGKILL");
     boundedSignal.addEventListener("abort", stop, { once: true });
     if (boundedSignal.aborted) stop();

package/src/ai/routes.ts

@@ -16,6 +16,7 @@ import {
   respond,
   v,
 } from "../server";
+import { isRequestCredentialCurrent } from "../server/middleware/auth";
 import { logger } from "../services/logging";
 import { coreSettings } from "../services/settings/api";
 import type { AiToolApprovalContext } from "./approvals";
@@ -1108,11 +1109,11 @@ export const aiRoutes = (() => {
         return createAiConversationStreamResponse({
           conversation,
           signal: c.req.raw.signal,
-          // Both calls hit the database: resolveContext re-runs the app's own
-          // access check, loadConversation re-checks ownership and resource
-          // scope. The actor itself is a request-time snapshot, so this catches
-          // a withdrawn grant but not a revoked credential — see r9358ceb.
+          // The actor is a request-time snapshot: re-authenticate its
+          // credential first, so a revoked session or API key ends the stream,
+          // then re-check ownership and resource scope of the conversation.
           revalidate: async () => {
+            if (!(await isRequestCredentialCurrent(c))) return false;
             const current = await resolveContext(c);
             if (current instanceof Response) return false;
             return Boolean(await loadConversation(c, current));

package/src/ai/stream.ts

@@ -16,6 +16,16 @@ import type { AiConversation } from "./types";
 
 const log = logger("ai:stream");
 
+/**
+ * Bytes an SSE reader may leave unread before its stream ends, the live
+ * socket's send-buffer limit. The check runs before each event, so the queue
+ * can exceed it by the event that crosses it, and a state snapshot or a
+ * finished turn with its messages can be larger than one live event. The
+ * reconnect starts from a fresh state snapshot, so ending the stream loses
+ * nothing durable.
+ */
+const AI_STREAM_MAX_BUFFERED_BYTES = 4 * 1024 * 1024;
+
 /**
  * Live fanout for wire events. Events carry their full payload so the SSE hot
  * path never touches Postgres; durable state lives in ai.messages plus the
@@ -224,11 +234,11 @@ export const createAiConversationStreamResponse = (input: {
   signal?: AbortSignal;
   heartbeatMs?: number;
   /**
-   * Re-checked on every heartbeat. A stream can outlive the grant that opened
-   * it by hours, and authorizing once at connect time means a withdrawn grant
-   * keeps delivering model output until the client happens to disconnect.
-   * Returning false closes the stream; the client's reconnect then meets the
-   * ordinary 403.
+   * Re-checked on every heartbeat. A stream can outlive the credential and the
+   * grant that opened it by hours, and authorizing once at connect time means
+   * a revoked session or withdrawn grant keeps delivering model output until
+   * the client happens to disconnect. Returning false closes the stream; the
+   * client's reconnect then meets the ordinary 401, 403, or 404.
    */
   revalidate?: () => Promise<boolean>;
 }): Response => {
@@ -241,73 +251,87 @@ export const createAiConversationStreamResponse = (input: {
   if (input.signal?.aborted) abortLive();
   else input.signal?.addEventListener("abort", abortLive, { once: true });
 
-  const stream = new ReadableStream<Uint8Array>({
-    async start(controller) {
-      const enqueue = (chunk: Uint8Array): boolean => {
-        if (closed) return false;
+  const stream = new ReadableStream<Uint8Array>(
+    {
+      async start(controller) {
+        const enqueue = (chunk: Uint8Array): boolean => {
+          if (closed) return false;
+          // desiredSize is the budget left after what the reader has not taken
+          // yet. A reader that falls this far behind gets a fresh snapshot on
+          // reconnect instead of an ever-growing queue on the server.
+          if ((controller.desiredSize ?? 0) <= 0) {
+            log.warn("AI conversation stream closed: the reader fell behind", {
+              conversationId: input.conversation.id,
+              maxBufferedBytes: AI_STREAM_MAX_BUFFERED_BYTES,
+            });
+            close();
+            return false;
+          }
+          try {
+            controller.enqueue(chunk);
+            return true;
+          } catch {
+            close();
+            return false;
+          }
+        };
+        const close = () => {
+          if (closed) return;
+          closed = true;
+          if (heartbeat) clearInterval(heartbeat);
+          heartbeat = undefined;
+          input.signal?.removeEventListener("abort", abortLive);
+          abortLive();
+          try {
+            controller.close();
+          } catch {
+            // The client may already have cancelled the stream.
+          }
+        };
+
+        if (heartbeatMs > 0) {
+          heartbeat = setInterval(() => {
+            if (!enqueue(encodeSseHeartbeat())) return;
+            if (!input.revalidate) return;
+            // Fail closed: a revalidation that throws is not a pass.
+            void input
+              .revalidate()
+              .catch((error) => {
+                log.warn("AI conversation stream revalidation failed", {
+                  conversationId: input.conversation.id,
+                  error: error instanceof Error ? error.message : "revalidation failed",
+                });
+                return false;
+              })
+              .then((allowed) => {
+                if (!allowed) close();
+              });
+          }, heartbeatMs);
+        }
+
         try {
-          controller.enqueue(chunk);
-          return true;
-        } catch {
+          for await (const event of streamAiConversationEvents({ conversation: input.conversation, signal: liveAbort.signal })) {
+            if (!enqueue(encodeSseEvent(event))) return;
+          }
+        } catch (error) {
+          if (!liveAbort.signal.aborted) {
+            log.warn("AI conversation stream failed", {
+              conversationId: input.conversation.id,
+              error: error instanceof Error ? error.message : "AI conversation stream failed",
+            });
+          }
+        } finally {
           close();
-          return false;
         }
-      };
-      const close = () => {
-        if (closed) return;
+      },
+      cancel() {
         closed = true;
         if (heartbeat) clearInterval(heartbeat);
-        heartbeat = undefined;
-        input.signal?.removeEventListener("abort", abortLive);
         abortLive();
-        try {
-          controller.close();
-        } catch {
-          // The client may already have cancelled the stream.
-        }
-      };
-
-      if (heartbeatMs > 0) {
-        heartbeat = setInterval(() => {
-          if (!enqueue(encodeSseHeartbeat())) return;
-          if (!input.revalidate) return;
-          // Fail closed: a revalidation that throws is not a pass.
-          void input
-            .revalidate()
-            .catch((error) => {
-              log.warn("AI conversation stream revalidation failed", {
-                conversationId: input.conversation.id,
-                error: error instanceof Error ? error.message : "revalidation failed",
-              });
-              return false;
-            })
-            .then((allowed) => {
-              if (!allowed) close();
-            });
-        }, heartbeatMs);
-      }
-
-      try {
-        for await (const event of streamAiConversationEvents({ conversation: input.conversation, signal: liveAbort.signal })) {
-          if (!enqueue(encodeSseEvent(event))) return;
-        }
-      } catch (error) {
-        if (!liveAbort.signal.aborted) {
-          log.warn("AI conversation stream failed", {
-            conversationId: input.conversation.id,
-            error: error instanceof Error ? error.message : "AI conversation stream failed",
-          });
-        }
-      } finally {
-        close();
-      }
-    },
-    cancel() {
-      closed = true;
-      if (heartbeat) clearInterval(heartbeat);
-      abortLive();
+      },
     },
-  });
+    new ByteLengthQueuingStrategy({ highWaterMark: AI_STREAM_MAX_BUFFERED_BYTES }),
+  );
 
   return new Response(stream, { headers: sseHeaders });
 };

package/src/api/app-approval.ts

@@ -24,9 +24,13 @@ type Service = ReturnType<typeof createAppApprovalService>;
 /** This is a separate credential surface, never a user API-key or OAuth scope. */
 export const createAppApprovalRoutes = (service: Service = appApproval) => {
   const actor = async (c: Parameters<typeof auth.session.getToken>[0]): Promise<AppApprovalActor> => {
-    const token = auth.session.getToken(c);
+    // The web session (or an explicit bearer session), never the mobile app's session: a phone
+    // that pairs sign-in devices would hand out authority that outlives its removal.
+    const token = auth.session.getBearerToken(c) ?? auth.session.getWebToken(c);
+    if (!token && auth.session.getAppToken(c)) throw new AppApprovalError("FORBIDDEN", 403);
     const session = token ? await auth.session.authenticateRequest(c, token) : null;
     if (!session) throw new AppApprovalError("REAUTHENTICATE", 403);
+    if (session.data.kind === "app") throw new AppApprovalError("FORBIDDEN", 403);
     return { userId: session.user.id, sid: session.data.sid, admin: session.user.roles.includes("admin") };
   };
   return new Hono<AuthContext>()

package/src/api/index.ts

@@ -38,12 +38,14 @@ import { createCapabilityRoutes } from "./capabilities";
 import { createHelpRoutes } from "./help";
 import { createMcpRoutes } from "./mcp";
 import meRoutes from "./me";
+import { createPwaRoutes } from "./pwa";
 import { createSearchRoutes } from "./search";
 import { createSyncOpsProxyRoutes } from "./sync-ops";
 import { createWidgetRoutes } from "./widgets";
 
 export { type CapabilityDispatchDependencies, dispatchCapability } from "./capabilities";
 export { cliPluginListRoutes } from "./cli-plugins";
+export { createPwaPhoneRoutes } from "./pwa-phone";
 
 /**
  * Single-expression chain so `typeof buildCoreApi()` captures every route's
@@ -64,6 +66,7 @@ const buildCoreApi = (options: CoreApiOptions) => {
   return new Hono()
     .use(prettyJSON())
     .route("/auth/app-approval/v1", createAppApprovalRoutes())
+    .route("/auth/pwa/v1", createPwaRoutes())
     .route("/auth", createAuthRoutes(options.notifications))
     .route("/me", meRoutes)
     .route("/accounts", accountsEntitiesRoutes)

package/src/api/me.ts

@@ -5,7 +5,7 @@
  */
 
 import { ok } from "@k2b/stdlib";
-import { Hono, type MiddlewareHandler } from "hono";
+import { type Context, Hono, type MiddlewareHandler } from "hono";
 import { createMiddleware } from "hono/factory";
 import { describeRoute } from "hono-openapi";
 import { z } from "zod";
@@ -37,6 +37,7 @@ import {
 } from "../contracts";
 import { CapabilityAppIdSchema } from "../contracts/capabilities";
 import { type AuthContext, auth, getLocale, jsonResponse, rateLimit, requiresAuth, respond, v } from "../server";
+import { APP_SESSION_FORBIDDEN } from "../server/middleware/auth";
 import {
   accountLifecycle,
   accountsAppService as accountsService,
@@ -59,6 +60,9 @@ const toAccountsActor = (user: AuthContext["Variables"]["user"]) => ({
   provider: user.provider,
 });
 
+/** The answer for actions the mobile app's session may not take. */
+const webOnly = (c: Context) => c.json(APP_SESSION_FORBIDDEN, 403);
+
 /**
  * Guards the endpoints that manage how the account is authenticated: passkeys,
  * API keys, the password, and account deletion.
@@ -71,7 +75,8 @@ const toAccountsActor = (user: AuthContext["Variables"]["user"]) => ({
  *
  * A credential may still *read* its account's passkeys and keys; only the
  * mutations are gated. Browser sessions and user-issued OAuth access tokens
- * both resolve to a `user` actor and are unaffected.
+ * both resolve to a `user` actor and are unaffected. The mobile app's session
+ * is rejected too: whatever it created would outlive removing the phone.
  */
 const requireDirectUserActor = createMiddleware<AuthContext>(async (c, next) => {
   if (c.get("actor")?.kind !== "user") {
@@ -83,6 +88,7 @@ const requireDirectUserActor = createMiddleware<AuthContext>(async (c, next) =>
       403,
     );
   }
+  if (auth.isAppSession(c)) return webOnly(c);
   return next();
 });
 
@@ -134,6 +140,8 @@ const requireSessionMandateCreation = createMiddleware<AuthContext>(async (c, ne
   if (c.get("credentialKind") !== "session" || c.get("actor")?.kind !== "user") {
     return c.json({ code: "FORBIDDEN", message: "Sign in with a browser session to create background authority" }, 403);
   }
+  // A mandate would keep acting after the phone is removed.
+  if (auth.isAppSession(c)) return webOnly(c);
   return next();
 });
 
@@ -231,6 +239,7 @@ const app = new Hono<AuthContext>()
 
   .post(
     "/notifications/browser/endpoints",
+    auth.rejectAppSession,
     describeRoute({
       tags: ["Me"],
       summary: "Register browser notification endpoint",
@@ -240,6 +249,7 @@ const app = new Hono<AuthContext>()
         200: jsonResponse(BrowserNotificationEndpointSchema, "Registered browser notification endpoint"),
         400: jsonResponse(ErrorResponseSchema, "Invalid browser subscription"),
         401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "Not available in the mobile app"),
       },
     }),
     v("json", RegisterBrowserNotificationEndpointSchema),
@@ -400,17 +410,21 @@ const app = new Hono<AuthContext>()
         200: jsonResponse(MessageResponseSchema, "Profile updated"),
         400: jsonResponse(ErrorResponseSchema, "Failed to update profile"),
         401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "SSH keys cannot be changed in the mobile app"),
       },
     }),
     v("json", UpdateProfileSchema),
-    async (c) =>
-      respond(c, async () => {
+    async (c) => {
+      // SSH keys sign in to the directory's hosts and would outlive removing the phone.
+      if (c.req.valid("json").ipa?.sshPublicKeys !== undefined && auth.isAppSession(c)) return webOnly(c);
+      return respond(c, async () => {
         const user = c.get("user");
         const data = c.req.valid("json");
         const result = await accountsService.user.update({ actor: toAccountsActor(user), id: user.id, data });
         if (!result.ok) return result;
         return ok({ message: "Profile updated." });
-      }),
+      });
+    },
   )
 
   .put(

package/src/api/pwa-phone.ts

@@ -0,0 +1,161 @@
+import { type Context, Hono } from "hono";
+import { deleteCookie, getCookie, setCookie } from "hono/cookie";
+import { env } from "../config/env";
+import { PWA_AUTH_PATH, PWA_COOKIES, PWA_LIMITS, PWA_SCOPE, PwaClaimSchema, type PwaLaunchState, PwaRenameSchema } from "../contracts/pwa";
+import { type AuthContext, auth, rateLimit, v } from "../server";
+import { type PwaCredentials, PwaError, pwaDevices } from "../services/pwa-devices";
+import { defaultShellAvailable, handlePwaError, type PwaRouteOptions, pwaErrorResponse, pwaInvalidRequest, pwaTransport } from "./pwa";
+
+const PAIRING_COOKIE_PATH = `${PWA_AUTH_PATH}/pairings`;
+const cookie = { httpOnly: true, secure: !env.IS_DEVELOPMENT } as const;
+
+const setAppCredentials = (c: Context, credentials: PwaCredentials) => {
+  setCookie(c, PWA_COOKIES.session, credentials.sessionToken, { ...cookie, sameSite: "Lax", path: "/", maxAge: PWA_LIMITS.sessionSeconds });
+  // Only Core's /pwa/_auth endpoints ever receive the device key.
+  setCookie(c, PWA_COOKIES.device, credentials.deviceKey, {
+    ...cookie,
+    sameSite: "Lax",
+    path: PWA_AUTH_PATH,
+    maxAge: PWA_LIMITS.idleDays * 86_400,
+  });
+};
+const clearAppCredentials = (c: Context) => {
+  deleteCookie(c, PWA_COOKIES.session, { ...cookie, path: "/" });
+  deleteCookie(c, PWA_COOKIES.device, { ...cookie, path: PWA_AUTH_PATH });
+};
+const clearPairing = (c: Context) => deleteCookie(c, PWA_COOKIES.pairing, { ...cookie, path: PAIRING_COOKIE_PATH });
+
+const authenticated = async (c: Context, token: string | null) => (token ? auth.session.authenticateRequest(c, token) : null);
+const appSession = async (c: Context) => {
+  const session = await authenticated(c, auth.session.getAppToken(c));
+  return session?.data.kind === "app" ? session : null;
+};
+const webSession = async (c: Context) => {
+  const session = await authenticated(c, auth.session.getWebToken(c));
+  return session?.data.kind === "web" ? session : null;
+};
+
+/**
+ * A path inside the app to return to after the launch bounce; anything else becomes `/pwa/`.
+ * The `pwa_launch` marker lets the page stop instead of bouncing again.
+ */
+export const launchTarget = (to: string | undefined): string => {
+  const fallback = `${PWA_SCOPE}?pwa_launch=1`;
+  if (!to || to.length > 2048 || !to.startsWith(PWA_SCOPE) || to.includes("//") || to.includes("\\")) return fallback;
+  const url = new URL(to, "http://launch.invalid");
+  // Judge the path the browser will request: dot segments and escapes are resolved by then.
+  let path: string;
+  try {
+    path = decodeURIComponent(url.pathname);
+  } catch {
+    return fallback;
+  }
+  const inside = (value: string) => value.startsWith(PWA_SCOPE) && value !== PWA_AUTH_PATH && !value.startsWith(`${PWA_AUTH_PATH}/`);
+  if (url.origin !== "http://launch.invalid" || !inside(url.pathname) || !inside(path) || path.includes("//")) return fallback;
+  url.searchParams.set("pwa_launch", "1");
+  return url.pathname + url.search;
+};
+
+const stateUrl = (state: PwaLaunchState) => `${PWA_SCOPE}?pwa=${state}`;
+
+/**
+ * Phone side of the mobile app (preview), mounted by Core at `/pwa/_auth` before its page
+ * catch-all. The device key and the completion secret use cookie paths below `/pwa/_auth`,
+ * which only Core serves; other applications see only the 24-hour app session.
+ */
+export const createPwaPhoneRoutes = (options: PwaRouteOptions = {}) => {
+  const service = options.service ?? pwaDevices;
+  const shellAvailable = options.shellAvailable ?? defaultShellAvailable;
+  const limit = rateLimit({ keyBy: "ip" });
+  const requireShell = (c: Context) => {
+    if (!shellAvailable(c)) throw new PwaError("UNAVAILABLE", 503);
+  };
+  return new Hono<AuthContext>()
+    .onError(handlePwaError)
+    .use("*", ...pwaTransport())
+    .use("*", async (c, next) => {
+      const limited = await limit(c, next);
+      // A navigation always gets a page, never JSON: a limited launch shows the unavailable state, which retries.
+      if (limited instanceof Response && c.req.method === "GET" && c.req.path.endsWith("/session/launch")) {
+        return c.redirect(stateUrl("unavailable"), 302);
+      }
+      return limited;
+    })
+    .post("/pairings/claim", v("json", PwaClaimSchema, pwaInvalidRequest), async (c) => {
+      requireShell(c);
+      const input = c.req.valid("json");
+      const claimed = await service.claimPairing({ ...input, userAgent: c.req.header("User-Agent") });
+      setCookie(c, PWA_COOKIES.pairing, claimed.completionSecret, {
+        ...cookie,
+        sameSite: "Strict",
+        path: PAIRING_COOKIE_PATH,
+        maxAge: Math.max(1, Math.ceil((Date.parse(claimed.expiresAt) - Date.now()) / 1000)),
+      });
+      return c.json({ code: claimed.code, account: claimed.account, expiresAt: claimed.expiresAt });
+    })
+    .post("/pairings/complete", async (c) => {
+      requireShell(c);
+      const web = await webSession(c);
+      try {
+        const result = await service.completePairing(c, {
+          completionSecret: getCookie(c, PWA_COOKIES.pairing),
+          deviceKey: getCookie(c, PWA_COOKIES.device),
+          appSession: await appSession(c),
+          webUserId: web?.user.id ?? null,
+        });
+        if (result.state === "waiting") return c.json(result, 202);
+        if (result.credentials) setAppCredentials(c, result.credentials);
+        clearPairing(c);
+        // A Home Screen app on iOS has its own cookie jar; a web session there is only a copy from Safari.
+        if (result.platform === "ios" && auth.session.getWebToken(c)) deleteCookie(c, "session_token", { path: "/" });
+        return c.json({ state: "paired" as const });
+      } catch (error) {
+        if (error instanceof PwaError && error.code === "EXPIRED") clearPairing(c);
+        throw error;
+      }
+    })
+    .get("/session/launch", async (c) => {
+      const to = launchTarget(c.req.query("to"));
+      if (!shellAvailable(c)) return c.redirect(stateUrl("unavailable"), 302);
+      try {
+        const result = await service.renew(c, { deviceKey: getCookie(c, PWA_COOKIES.device), appSession: await appSession(c) });
+        if (result.outcome === "renewed") setAppCredentials(c, result.credentials);
+        if (result.outcome === "renewed" || result.outcome === "current") return c.redirect(to, 302);
+        if (result.outcome === "blocked") return c.redirect(stateUrl("blocked"), 302);
+        if (result.outcome === "ended") clearAppCredentials(c);
+        return c.redirect(stateUrl(result.outcome === "missing" ? "new" : "ended"), 302);
+      } catch (error) {
+        // Logs an unexpected failure by name only; a navigation always gets a page, never JSON.
+        handlePwaError(error instanceof Error ? error : new Error("UnknownError"), c);
+        return c.redirect(stateUrl("unavailable"), 302);
+      }
+    })
+    .post("/session/renew", async (c) => {
+      // Without the app, no phone may renew; 503 never signs a phone out.
+      requireShell(c);
+      const [result, web] = await Promise.all([
+        service.renew(c, { deviceKey: getCookie(c, PWA_COOKIES.device), appSession: await appSession(c) }),
+        webSession(c),
+      ]);
+      if (result.outcome === "missing" || result.outcome === "ended") {
+        clearAppCredentials(c);
+        return pwaErrorResponse(c, new PwaError("UNPAIRED", 401));
+      }
+      if (result.outcome === "blocked") return pwaErrorResponse(c, new PwaError("ACCOUNT_BLOCKED", 403));
+      if (result.outcome === "renewed") setAppCredentials(c, result.credentials);
+      // Android shares Chrome's cookies with the app: fetches may run as that other web account.
+      const otherAccount = web && web.user.id !== result.userId ? { name: web.user.displayName || web.user.uid } : undefined;
+      return c.json({ renewed: result.outcome === "renewed", ...(otherAccount ? { otherAccount } : {}) });
+    })
+    .patch("/session", v("json", PwaRenameSchema, pwaInvalidRequest), async (c) => {
+      await service.rename(getCookie(c, PWA_COOKIES.device), c.req.valid("json").name);
+      return c.body(null, 204);
+    })
+    .delete("/session", async (c) => {
+      await service.unpair(getCookie(c, PWA_COOKIES.device));
+      clearAppCredentials(c);
+      // A pairing confirmed before the sign-out must not finish on its own later.
+      clearPairing(c);
+      return c.body(null, 204);
+    });
+};