@k2b/cloud 0.22.0 → 0.24.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/api/search/schemas.ts

@@ -85,6 +85,40 @@ export const SearchResponseSchema = z.object({
   failedApps: z.array(z.string()).optional(),
 });
 
+/** Media type a client sends in `Accept` to receive one NDJSON line per app as soon as it finishes. */
+export const SEARCH_STREAM_CONTENT_TYPE = "application/x-ndjson";
+
+export const SearchProviderStatusSchema = z.enum(["ok", "empty", "timeout", "error"]);
+
+/**
+ * One line of a streamed search: `start` names the apps that search, one `provider` line follows per app in the
+ * order the apps finish, and `done` closes the search. Apps without a line before `done` do not exist: every app
+ * named in `start` gets exactly one line.
+ */
+export const SearchStreamLineSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("start"),
+    query: z.string(),
+    apps: z.array(SearchAppSchema),
+    providers: z.array(z.string()),
+    unsupportedTags: z.array(z.string()).optional(),
+  }),
+  z.object({
+    type: z.literal("provider"),
+    provider: z.string(),
+    status: SearchProviderStatusSchema,
+    results: z.array(SearchItemSchema),
+    ms: z.number().int().nonnegative(),
+  }),
+  z.object({
+    type: z.literal("done"),
+    status: z.enum(["complete", "partial"]),
+    count: z.number().int().nonnegative(),
+  }),
+]);
+
 export type SearchApp = z.infer<typeof SearchAppSchema>;
 export type SearchItem = z.infer<typeof SearchItemSchema>;
 export type SearchResponse = z.infer<typeof SearchResponseSchema>;
+export type SearchProviderStatus = z.infer<typeof SearchProviderStatusSchema>;
+export type SearchStreamLine = z.infer<typeof SearchStreamLineSchema>;

package/src/api/search.ts

@@ -1,5 +1,5 @@
 import { Hono, type MiddlewareHandler } from "hono";
-import { describeRoute } from "hono-openapi";
+import { describeRoute, resolver } from "hono-openapi";
 import { readBoundedJson } from "../_internal/bounded-json";
 import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
 import { listCapabilities } from "../_internal/registry";
@@ -18,14 +18,24 @@ import { searchInvocationOperation } from "../services/identity/invocation-opera
 import { normalizeInvocationRequestId, signInvocationToken } from "../services/identity/invocation-token";
 import { withActiveIdentitySigner } from "../services/identity/key-ring";
 import { LOCALE_HEADER } from "../shared/locale";
-import { type SearchItem, SearchItemSchema, SearchQuerySchema, SearchResponseSchema } from "./search/schemas";
+import {
+  SEARCH_STREAM_CONTENT_TYPE,
+  type SearchItem,
+  SearchItemSchema,
+  type SearchProviderStatus,
+  SearchQuerySchema,
+  type SearchResponse,
+  SearchResponseSchema,
+  type SearchStreamLine,
+  SearchStreamLineSchema,
+} from "./search/schemas";
 
 const log = logger("search");
 const SearchProviderResultSchema = capabilityResultSchema(UniversalSearchDataSchema);
 
 /**
- * Maximum items returned to the client after merging across providers.
- * The frontend has no further limit — this caps the rendered list.
+ * Maximum items of the merged JSON response. A streamed search has no merged
+ * list: each app's line carries at most that app's provider limit.
  */
 const GLOBAL_RESULT_LIMIT = 30;
 const PROVIDER_CONCURRENCY = 8;
@@ -122,8 +132,25 @@ const startBounded = <T, R>(
   return deferred.map((entry) => entry.promise);
 };
 
-const settleBounded = async <T, R>(items: readonly T[], concurrency: number, run: (item: T, index: number) => Promise<R>) =>
-  Promise.all(startBounded(items, concurrency, run));
+/** Highest app-provided priority first, then by title. */
+const rankItems = (items: SearchItem[]) => items.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0) || a.title.localeCompare(b.title));
+
+/** The browser asks for a stream explicitly; every other client keeps the merged JSON response. */
+const acceptsStream = (accept: string | undefined) =>
+  accept?.split(",").some((type) => type.split(";")[0]?.trim().toLowerCase() === SEARCH_STREAM_CONTENT_TYPE) ?? false;
+
+const streamHeaders = {
+  "content-type": `${SEARCH_STREAM_CONTENT_TYPE}; charset=utf-8`,
+  // Each line must reach the browser when it is written: no cache, no transformation, no proxy buffering.
+  "cache-control": "no-store, no-transform",
+  "x-accel-buffering": "no",
+} as const;
+
+const encoder = new TextEncoder();
+const lineText = (line: SearchStreamLine) => `${JSON.stringify(line)}\n`;
+const encodeLine = (line: SearchStreamLine) => encoder.encode(lineText(line));
+
+type AppOutcome = { appId: string; status: SearchProviderStatus; items: SearchItem[]; ms: number };
 
 const waitWithin = <T>(value: Promise<T>, signal: AbortSignal): Promise<T> =>
   new Promise<T>((resolve, reject) => {
@@ -160,7 +187,14 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
       description: "Searches across app providers discovered via the service registry with optional tag filters.",
       ...requiresAuth,
       responses: {
-        200: jsonResponse(SearchResponseSchema, "Merged search results"),
+        200: {
+          description:
+            "Merged search results. With `Accept: application/x-ndjson`, one JSON line per app in the order the apps finish instead.",
+          content: {
+            "application/json": { schema: resolver(SearchResponseSchema) },
+            [SEARCH_STREAM_CONTENT_TYPE]: { schema: resolver(SearchStreamLineSchema) },
+          },
+        },
         400: jsonResponse(ErrorResponseSchema, "Invalid query"),
         401: jsonResponse(ErrorResponseSchema, "Authentication required"),
         403: jsonResponse(ErrorResponseSchema, "User-backed actor required"),
@@ -172,6 +206,7 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
       expectUserBackedActor(c);
 
       const query = c.req.valid("query");
+      const stream = acceptsStream(c.req.header("accept"));
       const requestId = normalizeInvocationRequestId(c.req.header("x-request-id"));
       const invocationAuthority = invocationAuthorityFromRequest(auth.getAuthority(c));
       let entries: CapabilityRegistryEntry[];
@@ -231,18 +266,24 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
       const active =
         query.tag.length === 0 ? appProviders : appProviders.filter((provider) => provider.tags.some((tag) => query.tag.includes(tag)));
 
+      // Answers without a provider call: the catalog alone, or only unsupported tags.
+      const answerWithoutProviders = (body: SearchResponse) =>
+        stream
+          ? new Response(
+              [
+                lineText({ type: "start", query: body.query, apps, providers: [], ...(body.unsupportedTags ? { unsupportedTags } : {}) }),
+                lineText({ type: "done", status: "complete", count: 0 }),
+              ].join(""),
+              { headers: streamHeaders },
+            )
+          : c.json(body);
+
       if (query.q.length === 0 && query.tag.length === 0 && !query.app && !scope) {
-        return c.json({ query: "", count: 0, items: [], apps });
+        return answerWithoutProviders({ query: "", count: 0, items: [], apps });
       }
 
       if (query.tag.length > 0 && active.length === 0) {
-        return c.json({
-          query: query.q,
-          count: 0,
-          items: [],
-          apps,
-          unsupportedTags,
-        });
+        return answerWithoutProviders({ query: query.q, count: 0, items: [], apps, unsupportedTags });
       }
 
       // Single-provider queries get a larger sample for better local
@@ -252,7 +293,9 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
       const effectiveProviderLimit = active.length === 1 ? Math.min(GLOBAL_RESULT_LIMIT, query.provider_limit * 3) : query.provider_limit;
       // The same request-wide budget covers signing and provider I/O.
       const providerDeadline = AbortSignal.timeout(PROVIDER_TIMEOUT_MS);
-      const fanoutSignal = AbortSignal.any([c.req.raw.signal, providerDeadline]);
+      // A client that stops reading a stream, such as the browser on the next keystroke, ends the search too.
+      const streamCancelled = new AbortController();
+      const fanoutSignal = AbortSignal.any([c.req.raw.signal, providerDeadline, streamCancelled.signal]);
       // Guard the whole issuance batch once, then reuse the prepared signer for
       // every target. This is one Postgres check per outer search request, not
       // one check per provider.
@@ -298,7 +341,8 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
       // One request-wide budget keeps latency flat as the number of apps grows.
       // Workers that have not started when the deadline expires fail fast on
       // the already-aborted signal instead of opening a fresh timeout window.
-      const settled = await settleBounded(active, PROVIDER_CONCURRENCY, async (provider, index) => {
+      const fanoutStarted = performance.now();
+      const settled = startBounded(active, PROVIDER_CONCURRENCY, async (provider, index) => {
         // Scope tags to those this provider declared. Apps no longer need
         // their own gate — the framework guarantees they only see tags
         // they understand.
@@ -395,47 +439,71 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
         return validItems;
       });
 
-      const items = settled.flatMap((result, index) => {
-        if (result.status === "fulfilled") return result.value;
-
-        log.warn("Search provider failed", {
-          appId: active[index]?.appId ?? "unknown",
-          tags: query.tag,
-          error: result.reason instanceof Error ? result.reason.message : String(result.reason),
-        });
-        return [];
+      // One outcome per app, when all of its Queries have finished. Multiple
+      // focused Queries from one app must not buy that app a larger share.
+      const appIds = [...new Set(active.map((provider) => provider.appId))];
+      const outcomes = appIds.map(async (appId): Promise<AppOutcome> => {
+        const results = await Promise.all(active.flatMap((provider, index) => (provider.appId === appId ? [settled[index]!] : [])));
+        const failed = results.filter((result) => result.status === "rejected");
+        for (const result of failed) {
+          log.warn("Search provider failed", {
+            appId,
+            tags: query.tag,
+            error: result.reason instanceof Error ? result.reason.message : String(result.reason),
+          });
+        }
+        const items = rankItems(results.flatMap((result) => (result.status === "fulfilled" ? result.value : []))).slice(
+          0,
+          effectiveProviderLimit,
+        );
+        const status = failed.length ? (providerDeadline.aborted ? "timeout" : "error") : items.length ? "ok" : "empty";
+        return { appId, status, items, ms: Math.round(performance.now() - fanoutStarted) };
       });
+      const failure = (outcome: AppOutcome) => outcome.status === "timeout" || outcome.status === "error";
 
-      items.sort((a, b) => {
-        const priorityDiff = (b.priority ?? 0) - (a.priority ?? 0);
-        if (priorityDiff !== 0) return priorityDiff;
-        return a.title.localeCompare(b.title);
-      });
+      if (stream) {
+        let cancelled = false;
+        const body = new ReadableStream<Uint8Array>({
+          start(controller) {
+            const write = (line: SearchStreamLine) => {
+              if (!cancelled) controller.enqueue(encodeLine(line));
+            };
+            write({ type: "start", query: query.q, apps, providers: appIds, ...(unsupportedTags.length > 0 ? { unsupportedTags } : {}) });
+            let count = 0;
+            let partial = false;
+            // A slow app never holds back the others: each line is written when its app finishes.
+            void Promise.all(
+              outcomes.map((pending) =>
+                pending.then((outcome) => {
+                  count += outcome.items.length;
+                  partial ||= failure(outcome);
+                  write({ type: "provider", provider: outcome.appId, status: outcome.status, results: outcome.items, ms: outcome.ms });
+                }),
+              ),
+            ).then(() => {
+              write({ type: "done", status: partial ? "partial" : "complete", count });
+              if (!cancelled) controller.close();
+            });
+          },
+          cancel() {
+            cancelled = true;
+            streamCancelled.abort();
+          },
+        });
+        return new Response(body, { headers: streamHeaders });
+      }
 
-      // Multiple focused Queries from one app must not buy that app a larger
-      // share of the merged result set.
-      const appCounts = new Map<string, number>();
-      const appBounded = items.filter((item) => {
-        const count = appCounts.get(item.appId) ?? 0;
-        if (count >= effectiveProviderLimit) return false;
-        appCounts.set(item.appId, count + 1);
-        return true;
-      });
-      const sliced = appBounded.slice(0, GLOBAL_RESULT_LIMIT);
+      const finished = await Promise.all(outcomes);
+      const items = rankItems(finished.flatMap((outcome) => outcome.items)).slice(0, GLOBAL_RESULT_LIMIT);
+      const failedApps = finished.filter(failure).map((outcome) => outcome.appId);
 
       return c.json({
         query: query.q,
-        count: sliced.length,
-        items: sliced,
+        count: items.length,
+        items,
         apps,
         ...(unsupportedTags.length > 0 ? { unsupportedTags } : {}),
-        ...(settled.some((result) => result.status === "rejected")
-          ? {
-              failedApps: [
-                ...new Set(active.filter((_, index) => settled[index]?.status === "rejected").map((provider) => provider.appId)),
-              ],
-            }
-          : {}),
+        ...(failedApps.length > 0 ? { failedApps } : {}),
       });
     },
   );

package/src/browser/CloudResourceSearch.browser-harness.tsx

@@ -0,0 +1,11 @@
+import { createGlobalSearchHost } from "../ssr/GlobalSearchDialog";
+import { openCloudResourcePicker } from "./resource-picker";
+
+/**
+ * Opens the real global search, or with `?picker` the resource picker, for a browser test that answers
+ * `/api/search` with invented, line-by-line results. `?app=<id>` narrows either one to one app.
+ */
+const params = new URLSearchParams(location.search);
+const app = params.get("app") ?? undefined;
+if (params.has("picker")) void openCloudResourcePicker({ initialAppId: app });
+else createGlobalSearchHost(() => []).open(app ? { scope: { appId: app, label: params.get("label") ?? app } } : {});