@k2b/cloud 0.22.0 → 0.24.0

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

@@ -8,7 +8,7 @@ import { helpApiMessages } from "./help-messages";
 export type HelpRouteDependencies = {
   help?: HelpReaderFactory;
   authenticate?: MiddlewareHandler<AuthContext>;
-  renderMarkdown?: (markdown: string) => string;
+  renderMarkdown?: (markdown: string, locale: string) => string;
 };
 
 export const createHelpRoutes = (dependencies: HelpRouteDependencies = {}) => {
@@ -34,7 +34,7 @@ export const createHelpRoutes = (dependencies: HelpRouteDependencies = {}) => {
         id: document.documentId,
         title: document.title,
         markdown: document.markdown,
-        html: (dependencies.renderMarkdown ?? renderHelpMarkdown)(document.markdown),
+        html: (dependencies.renderMarkdown ?? renderHelpMarkdown)(document.markdown, document.locale),
       };
       return c.json(payload);
     });

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,168 @@
+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, getLocale, rateLimit, v } from "../server";
+import { type PwaCredentials, type PwaDeviceNotifier, 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}`;
+
+export type PwaPhoneRouteOptions = PwaRouteOptions & {
+  /** Sends the "new phone paired" notice; completion awaits it before the phone gets its credentials. */
+  notify: PwaDeviceNotifier;
+};
+
+/**
+ * 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: PwaPhoneRouteOptions) => {
+  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,
+          locale: getLocale(c),
+          notify: options.notify,
+        });
+        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);
+    });
+};