@k2b/cloud 0.42.0 → 0.44.0

package/src/api/mcp.ts

@@ -14,7 +14,9 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { Hono, type MiddlewareHandler } from "hono";
 import { z } from "zod";
+import { type CatalogSubscription, projectAppEventCatalog, readEventCatalogSubscriptions } from "../_internal/app-event-catalog";
 import { readBoundedJson } from "../_internal/bounded-json";
+import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
 import { capabilitySentenceText } from "../_internal/capability-sentences";
 import { withCapabilityRequestTimeout } from "../_internal/capability-timeout";
 import {
@@ -32,8 +34,12 @@ import {
   CAPABILITY_MAX_REQUEST_BYTES,
   CAPABILITY_MAX_RESULT_BYTES,
   CAPABILITY_PROTOCOL_VERSION,
+  CAPABILITY_QUALIFIED_ID_MAX_LENGTH,
   type CapabilityActionManifest,
   CapabilityActionReceiptSchema,
+  CapabilityAppIdSchema,
+  CapabilityEventCatalogEntrySchema,
+  CapabilityQualifiedIdSchema,
   type CapabilityQueryManifest,
   CapabilitySemanticLinkSchema,
   type CloudResourceRef,
@@ -46,6 +52,7 @@ import {
 import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
 import { type AuthContext, auth, type RequestAuthority, rateLimit, rejectReservedWorkloadCredential, resolveLocale } from "../server";
 import { preferredLocale } from "../server/locale";
+import { oauthScopeByOperation } from "../server/middleware/auth";
 import { noTransform } from "../server/middleware/no-transform";
 import { discoverableApps } from "../services/app-discovery";
 import { createHelpReader, type HelpArticle, type HelpMetadata, type HelpReader, type HelpReaderFactory } from "../services/help";
@@ -63,6 +70,27 @@ const IDEMPOTENCY_KEY_FIELD = "idempotencyKey";
 const RESOURCE_READ_TOOL = "cloud__resource__read";
 const HELP_SEARCH_TOOL = "cloud__help__search";
 const HELP_READ_TOOL = "cloud__help__read";
+const EVENT_LIST_TOOL = "cloud__events__list";
+const EVENT_READ_TOOL = "cloud__events__read";
+const eventListArguments = z.strictObject({
+  appId: CapabilityAppIdSchema.optional(),
+  automation: z.boolean().optional(),
+  cursor: z
+    .string()
+    .max(CAPABILITY_QUALIFIED_ID_MAX_LENGTH + 1 + String(Number.MAX_SAFE_INTEGER).length)
+    .regex(/^[a-z][a-z0-9-]*\.[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*@[1-9]\d*$/)
+    .optional(),
+  limit: z.number().int().min(1).max(MCP_TOOL_PAGE_SIZE).default(MCP_TOOL_PAGE_SIZE),
+});
+const eventReadArguments = z.strictObject({ type: CapabilityQualifiedIdSchema, version: z.number().int().positive() });
+const eventSummarySchema = CapabilityEventCatalogEntrySchema.omit({ dataSchema: true, subscribers: true }).extend({
+  appId: CapabilityAppIdSchema,
+});
+const eventDetailSchema = CapabilityEventCatalogEntrySchema.extend({ appId: CapabilityAppIdSchema });
+const eventPageSchema = z.object({
+  events: z.array(eventSummarySchema),
+  nextCursor: z.string().optional(),
+});
 export const CLOUD_MCP_PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource/api/mcp/v1";
 const MCP_TOOL_NAME_MAX_LENGTH = 128;
 const MCP_INSTRUCTIONS =
@@ -72,6 +100,7 @@ const log = logger("mcp");
 type McpRouteDependencies = CapabilityDispatchDependencies & {
   listApps?: () => Promise<AppRegistryEntry[]>;
   help?: HelpReaderFactory;
+  eventSubscriptions?: (type: string, version: number) => Promise<CatalogSubscription[]>;
   getOperatorLocale?: () => Promise<string | undefined>;
   getOperatorTimeZone?: () => Promise<string | undefined>;
   getAppUrl?: () => Promise<string>;
@@ -205,6 +234,38 @@ const platformTools: Tool[] = [
     annotations: { title: "Read Cloud Help", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { "cloud/kind": "help-read" },
   },
+  {
+    name: EVENT_LIST_TOOL,
+    title: "List declared Cloud events",
+    description:
+      "Discover declared event types of apps you may discover. Returns publisher appId, type, version, title, description, subject and place types (place may be null), and automation metadata. Filter by appId or automation; pass nextCursor to continue. This reads declarations only.",
+    inputSchema: cloneObjectSchema(z.toJSONSchema(eventListArguments, { io: "input" })),
+    outputSchema: cloneObjectSchema(z.toJSONSchema(eventPageSchema)),
+    annotations: {
+      title: "List declared Cloud events",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    _meta: { "cloud/kind": "events-list" },
+  },
+  {
+    name: EVENT_READ_TOOL,
+    title: "Read declared Cloud event",
+    description:
+      "Read one exact event type and version returned by cloud__events__list, including its data JSON Schema and discoverable subscribers with persisted subscription states. This reads declarations only; it does not observe events or create subscriptions.",
+    inputSchema: cloneObjectSchema(z.toJSONSchema(eventReadArguments)),
+    outputSchema: cloneObjectSchema(z.toJSONSchema(z.object({ event: eventDetailSchema }))),
+    annotations: {
+      title: "Read declared Cloud event",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    _meta: { "cloud/kind": "events-read" },
+  },
 ];
 
 const projectTool = (
@@ -342,10 +403,12 @@ const parseResponse = async (response: Response): Promise<Record<string, unknown
     : { code: CAPABILITY_FRAMEWORK_ERROR_CODES.invalidAppResponse, message: "Capability returned a non-object result" };
 };
 
-const responseTooLargeToolResult = (): CallToolResult => {
+const responseTooLargeToolResult = (
+  message = "Capability result is too large for an MCP tool response; narrow the query and retry",
+): CallToolResult => {
   const error = {
     code: CAPABILITY_FRAMEWORK_ERROR_CODES.responseTooLarge,
-    message: "Capability result is too large for an MCP tool response; narrow the query and retry",
+    message,
   };
   return { isError: true, structuredContent: error, content: [{ type: "text", text: JSON.stringify(error) }] };
 };
@@ -489,6 +552,97 @@ const callHelpTool = async (name: string, argsValue: unknown, reader: HelpReader
   return null;
 };
 
+const eventCursor = (event: { type: string; version: number }): string => `${event.type}@${event.version}`;
+
+type EventCatalogReader = {
+  registry: () => Promise<AppRegistryEntry[]>;
+  lookup: (appId: string) => Promise<CapabilityRegistryEntry | null>;
+  locale: () => Promise<string>;
+  subscriptions: (type: string, version: number) => Promise<CatalogSubscription[]>;
+};
+
+const listEvents = async (argsValue: unknown, reader: EventCatalogReader): Promise<CallToolResult> => {
+  const parsed = eventListArguments.safeParse(argsValue ?? {});
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ");
+    return validationToolError(`cloud__events__list accepts appId, automation (boolean), cursor and limit (1-100) (${issues})`);
+  }
+  const { appId, automation, cursor, limit } = parsed.data;
+  const cursorAppId = cursor?.split(".")[0];
+  if (appId && cursorAppId && appId !== cursorAppId) {
+    return validationToolError("cloud__events__list cursor must belong to the requested appId");
+  }
+  const summaries = (await reader.registry())
+    .filter((entry) => entry.capabilities?.protocolVersion === CAPABILITY_PROTOCOL_VERSION)
+    .sort((left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+  const locale = await reader.locale();
+  const events: z.infer<typeof eventSummarySchema>[] = [];
+  const encoder = new TextEncoder();
+  const emptyBytes = encoder.encode(JSON.stringify(toolResult({ events: [] }, false))).byteLength;
+  let bytes = emptyBytes;
+  for (const summary of summaries) {
+    if (appId && summary.id !== appId) continue;
+    if (cursorAppId && summary.id < cursorAppId) continue;
+    const app = await reader.lookup(summary.id);
+    if (!app || app.manifest.manifestHash !== summary.capabilities?.manifestHash) continue;
+    const manifest = resolveCapabilityManifestPresentation(app.manifest, app.presentation, locale);
+    const catalog = projectAppEventCatalog(manifest, []).sort((left, right) =>
+      eventCursor(left) < eventCursor(right) ? -1 : eventCursor(left) > eventCursor(right) ? 1 : 0,
+    );
+    for (const entry of catalog) {
+      if (automation !== undefined && entry.automation !== automation) continue;
+      if (cursor && summary.id === cursorAppId && eventCursor(entry) <= cursor) continue;
+      const last = events.at(-1);
+      if (last && events.length === limit) return boundedToolResult({ events, nextCursor: eventCursor(last) }, false);
+      const { dataSchema: _schema, subscribers: _subscribers, ...summaryEntry } = entry;
+      const next = { appId: app.appId, ...summaryEntry };
+      const serialized = JSON.stringify(next);
+      // Count both structuredContent and the JSON-escaped text copy, plus their array separators.
+      const entryBytes = encoder.encode(serialized).byteLength + encoder.encode(JSON.stringify(serialized)).byteLength - 2;
+      const nextBytes = bytes + entryBytes + (events.length ? 2 : 0);
+      const cursorBytes =
+        encoder.encode(JSON.stringify(toolResult({ events: [], nextCursor: eventCursor(next) }, false))).byteLength - emptyBytes;
+      if (nextBytes + cursorBytes > CAPABILITY_MAX_RESULT_BYTES) {
+        return last ? boundedToolResult({ events, nextCursor: eventCursor(last) }, false) : responseTooLargeToolResult();
+      }
+      events.push(next);
+      bytes = nextBytes;
+    }
+  }
+  return boundedToolResult({ events }, false);
+};
+
+const readEvent = async (argsValue: unknown, reader: EventCatalogReader): Promise<CallToolResult> => {
+  const parsed = eventReadArguments.safeParse(argsValue);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ");
+    return validationToolError(`cloud__events__read requires an exact event type and positive integer version (${issues})`);
+  }
+  const { type, version } = parsed.data;
+  const summaries = (await reader.registry()).filter((entry) => entry.capabilities?.protocolVersion === CAPABILITY_PROTOCOL_VERSION);
+  const summary = summaries.find((entry) => entry.id === type.split(".")[0]);
+  if (summary) {
+    const app = await reader.lookup(summary.id);
+    if (app && app.manifest.manifestHash === summary.capabilities?.manifestHash) {
+      const manifest = resolveCapabilityManifestPresentation(app.manifest, app.presentation, await reader.locale());
+      const declaration = manifest.events?.find((event) => `${app.appId}.${event.localId}` === type && event.version === version);
+      if (declaration) {
+        const visibleApps = new Set(summaries.map((entry) => entry.id));
+        const subscribers = (await reader.subscriptions(type, version)).filter((row) => visibleApps.has(row.appId));
+        const [entry] = projectAppEventCatalog({ ...manifest, events: [declaration] }, subscribers);
+        const result = toolResult({ event: { appId: app.appId, ...entry } }, false);
+        return fitsToolResult(result)
+          ? result
+          : responseTooLargeToolResult("Event schema and subscriber list exceed the MCP response size limit");
+      }
+    }
+  }
+  return boundedToolResult(
+    { code: "EVENT_NOT_FOUND", message: "Event type and version are not in the current discoverable catalog" },
+    true,
+  );
+};
+
 const createMcpServer = (
   request: Request,
   dependencies: McpRouteDependencies,
@@ -581,6 +735,26 @@ const createMcpServer = (
   });
 
   server.setRequestHandler(CallToolRequestSchema, async (message) => {
+    if (message.params.name === EVENT_LIST_TOOL || message.params.name === EVENT_READ_TOOL) {
+      if (!hasScope("read")) return boundedToolResult({ code: "FORBIDDEN", message: "OAuth scope read is required" }, true);
+      const reader: EventCatalogReader = {
+        registry,
+        lookup: capabilityLookup,
+        locale: resolveHelpLocale,
+        subscriptions: dependencies.eventSubscriptions ?? readEventCatalogSubscriptions,
+      };
+      try {
+        return message.params.name === EVENT_LIST_TOOL
+          ? await listEvents(message.params.arguments, reader)
+          : await readEvent(message.params.arguments, reader);
+      } catch (error) {
+        log.error("Failed to read MCP event catalog", { error: error instanceof Error ? error.message : String(error) });
+        return boundedToolResult(
+          { code: CAPABILITY_FRAMEWORK_ERROR_CODES.appUnavailable, message: "Event catalog is currently unavailable" },
+          true,
+        );
+      }
+    }
     if (message.params.name === HELP_SEARCH_TOOL || message.params.name === HELP_READ_TOOL) {
       if (!hasScope("read")) {
         return boundedToolResult({ code: "FORBIDDEN", message: "OAuth scope read is required" }, true);
@@ -783,8 +957,8 @@ export const createMcpRoutes = (dependencies: McpRouteDependencies = {}) =>
     .use("/mcp/v1", validateMcpOrigin(dependencies.getAppUrl ?? defaultAppUrl))
     .use("/mcp/v1", dependencies.authenticate ?? mcpAuthentication(dependencies.getAppUrl ?? defaultAppUrl))
     .use("/mcp/v1", rejectReservedWorkloadCredential)
-    .use("/mcp/v1", dependencies.limit ?? rateLimit())
-    .all("/mcp/v1", async (c) =>
+    .use("/mcp/v1", auth.readOnlyMiddleware(dependencies.limit ?? rateLimit()))
+    .post("/mcp/v1", oauthScopeByOperation, async (c) =>
       withCapabilityRequestTimeout(c, "query", async () => {
         if (c.req.method !== "POST") {
           return new Response(null, { status: 405, headers: { Allow: "POST" } });
@@ -825,6 +999,7 @@ export const createMcpRoutes = (dependencies: McpRouteDependencies = {}) =>
           }
         }
       }),
-    );
+    )
+    .all("/mcp/v1", () => new Response(null, { status: 405, headers: { Allow: "POST" } }));
 
 export type McpApiType = ReturnType<typeof createMcpRoutes>;

package/src/api/me.ts

@@ -13,6 +13,7 @@ import { describeRoute } from "hono-openapi";
 import { z } from "zod";
 import {
   AccountActivityListResponseSchema,
+  AvatarStateSchema,
   BrowserNotificationConfigurationSchema,
   BrowserNotificationEndpointSchema,
   BrowserPushSubscriptionSchema,
@@ -27,10 +28,10 @@ import {
   NotificationDeliveryStatusSchema,
   NotificationQuietSettingsSchema,
   RegisterBrowserNotificationEndpointSchema,
+  SaveAvatarResponseSchema,
+  SaveAvatarSchema,
   ServiceAccountCredentialSchema,
   SignOutOthersResponseSchema,
-  UpdateAvatarResponseSchema,
-  UpdateAvatarSchema,
   UpdateNotificationQuietSettingsSchema,
   UpdateProfileSchema,
   UpdateUserNotificationPreferenceSchema,
@@ -323,7 +324,8 @@ const app = new Hono<AuthContext>()
     describeRoute({
       tags: ["Me"],
       summary: "List current user notification preferences",
-      description: "List active user-facing notification kinds, app recommendations, required channels, and explicit preferences.",
+      description:
+        "List active user-facing notification kinds, app recommendations, required and excluded channels, and explicit preferences.",
       ...requiresAuth,
       responses: {
         200: jsonResponse(UserNotificationPreferencesResponseSchema, "Notification preferences"),
@@ -342,11 +344,12 @@ const app = new Hono<AuthContext>()
     describeRoute({
       tags: ["Me"],
       summary: "Set current user notification preference",
-      description: "Replace optional channels for one notification kind. Required channels remain enforced by the definition.",
+      description:
+        "Replace optional channels for one notification kind. Required channels remain enforced; excluded channels are rejected.",
       ...requiresAuth,
       responses: {
         200: jsonResponse(UserNotificationPreferenceSchema, "Updated notification preference"),
-        400: jsonResponse(ErrorResponseSchema, "Invalid or unavailable channel"),
+        400: jsonResponse(ErrorResponseSchema, "Invalid, unavailable, or excluded channel"),
         401: jsonResponse(ErrorResponseSchema, "Authentication required"),
         404: jsonResponse(ErrorResponseSchema, "Notification preference not found"),
       },
@@ -492,32 +495,50 @@ const app = new Hono<AuthContext>()
     },
   )
 
+  .get(
+    "/avatar",
+    describeRoute({
+      tags: ["Me"],
+      summary: "Read current user profile picture",
+      description:
+        "Which picture others see (photo, built avatar, or initials), the stored built avatar, and whether a photo is stored. The image itself is served under the account's avatar URL.",
+      ...requiresAuth,
+      responses: {
+        200: jsonResponse(AvatarStateSchema, "Profile picture"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        404: jsonResponse(ErrorResponseSchema, "User not found"),
+      },
+    }),
+    async (c) =>
+      respond(c, async () => {
+        const state = await accountsService.user.getAvatarState({ id: c.get("user").id });
+        return state ? ok(state) : fail(err.notFound("User"));
+      }),
+  )
+
   .put(
     "/avatar",
     describeRoute({
       tags: ["Me"],
-      summary: "Update current user avatar",
-      description: "Store a small profile picture for the authenticated account. Avatars are visible to user-backed authenticated actors.",
+      summary: "Update current user profile picture",
+      description:
+        "Store and show a photo (`dataUrl`) or a built avatar (`built`), or show a stored picture (`use`: photo, built, or initials). A stored photo stays until it is deleted; only the shown picture is served. Avatars are visible to user-backed authenticated actors.",
       ...requiresAuth,
       responses: {
-        200: jsonResponse(UpdateAvatarResponseSchema, "Avatar updated"),
+        200: jsonResponse(SaveAvatarResponseSchema, "Avatar updated"),
         400: jsonResponse(ErrorResponseSchema, "Failed to update avatar"),
         401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        409: jsonResponse(ErrorResponseSchema, "The picture to show is not stored"),
         422: jsonResponse(ErrorResponseSchema, "Malformed image container or EXIF"),
       },
     }),
-    v("json", UpdateAvatarSchema),
+    v("json", SaveAvatarSchema),
     async (c) =>
       respond(c, async () => {
         const user = c.get("user");
-        const data = c.req.valid("json");
-        const result = await accountsService.user.setAvatar({
-          actor: toAccountsActor(user),
-          id: user.id,
-          dataUrl: data.dataUrl,
-        });
+        const result = await accountsService.user.updateAvatar({ actor: toAccountsActor(user), id: user.id, change: c.req.valid("json") });
         if (!result.ok) return result;
-        return ok({ message: "Avatar updated.", avatarHash: result.data.avatarHash });
+        return ok({ message: "Avatar updated.", ...result.data });
       }),
   )
 
@@ -799,7 +820,7 @@ const app = new Hono<AuthContext>()
       tags: ["Me"],
       summary: "Sign out every other sign-in",
       description:
-        "End other sign-ins and rotate this browser's cookie while preserving its sign-in time and expiry; signInAgain is true if this browser could not be kept. Cloud Login phones stay paired. API keys, passkeys and mandates stay valid.",
+        "End other sign-ins and rotate this browser's cookie while preserving its sign-in time and expiry; signInAgain is true if this browser could not be kept. Cloud Login devices stay paired. API keys, passkeys and mandates stay valid.",
       ...requiresAuth,
       responses: {
         200: jsonResponse(SignOutOthersResponseSchema, "Other sign-ins ended"),

package/src/api/pwa-phone.ts

@@ -1,11 +1,26 @@
 import { type Context, Hono } from "hono";
 import { deleteCookie, getCookie, setCookie } from "hono/cookie";
+import { describeRoute } from "hono-openapi";
+import { registeredPwaBuilds } from "../_internal/runtime-watcher";
 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 {
+  PWA_AUTH_PATH,
+  PWA_COOKIES,
+  PWA_LIMITS,
+  PWA_SCOPE,
+  PwaClaimSchema,
+  PwaCompleteResultSchema,
+  PwaDeviceDecisionSchema,
+  type PwaLaunchState,
+  PwaRenameSchema,
+} from "../contracts/pwa";
+import { launchTarget } from "../contracts/pwa-location";
+import { type AuthContext, auth, getLocale, jsonResponse, 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";
 
+export { launchTarget } from "../contracts/pwa-location";
+
 const PAIRING_COOKIE_PATH = `${PWA_AUTH_PATH}/pairings`;
 const cookie = { httpOnly: true, secure: !env.IS_DEVELOPMENT } as const;
 
@@ -19,7 +34,9 @@ const setAppCredentials = (c: Context, credentials: PwaCredentials) => {
     maxAge: PWA_LIMITS.idleDays * 86_400,
   });
 };
+const clearLastAddress = (c: Context) => deleteCookie(c, PWA_COOKIES.lastAddress, { path: PWA_SCOPE, secure: true, sameSite: "Lax" });
 const clearAppCredentials = (c: Context) => {
+  clearLastAddress(c);
   deleteCookie(c, PWA_COOKIES.session, { ...cookie, path: "/" });
   deleteCookie(c, PWA_COOKIES.device, { ...cookie, path: PWA_AUTH_PATH });
 };
@@ -35,27 +52,6 @@ const webSession = async (c: Context) => {
   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 & {
@@ -98,29 +94,68 @@ export const createPwaPhoneRoutes = (options: PwaPhoneRouteOptions) => {
       });
       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;
-      }
-    })
+    .post(
+      "/pairings/complete",
+      describeRoute({
+        tags: ["Cloud app"],
+        summary: "Poll or complete a claimed pairing",
+        description:
+          "Requires the HttpOnly completion cookie from claim. Administrative code confirmation returns confirmation_required with the target, administrator and a pairing-bound decision token; polling alone never completes it. Only a subsequent explicit device decision permits credentials. Self-pairing is unchanged.",
+        responses: {
+          200: jsonResponse(PwaCompleteResultSchema, "Paired"),
+          202: jsonResponse(PwaCompleteResultSchema, "Waiting or device decision required"),
+        },
+      }),
+      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" || result.state === "confirmation_required") return c.json(result, 202);
+          if (result.state === "rejected") {
+            clearPairing(c);
+            return c.json(result);
+          }
+          if (result.credentials) setAppCredentials(c, result.credentials);
+          clearLastAddress(c);
+          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;
+        }
+      },
+    )
+    .post(
+      "/pairings/decision",
+      describeRoute({
+        tags: ["Cloud app"],
+        summary: "Accept or reject administrative Cloud app pairing on the device",
+        description:
+          "Requires both the claim's HttpOnly completion cookie and the confirmationToken returned for this pairing after the administrator matched the code. decision is confirm or reject. Repeating the same decision is idempotent. Confirm permits a subsequent complete request; reject issues no credentials.",
+        responses: {
+          204: { description: "Device decision recorded" },
+          403: { description: "Invalid decision token" },
+          409: { description: "Pairing is not awaiting this decision" },
+          410: { description: "Pairing expired" },
+        },
+      }),
+      v("json", PwaDeviceDecisionSchema, pwaInvalidRequest),
+      async (c) => {
+        requireShell(c);
+        await service.decidePairing(getCookie(c, PWA_COOKIES.pairing), c.req.valid("json"));
+        return c.body(null, 204);
+      },
+    )
     .get("/session/launch", async (c) => {
       const to = launchTarget(c.req.query("to"));
       if (!shellAvailable(c)) return c.redirect(stateUrl("unavailable"), 302);
@@ -129,7 +164,11 @@ export const createPwaPhoneRoutes = (options: PwaPhoneRouteOptions) => {
         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);
+        if (result.outcome === "ended") {
+          clearAppCredentials(c);
+          // Only this answer may delete the drafts: "?pwa=ended" alone is an address anyone can open.
+          setCookie(c, PWA_COOKIES.ended, "1", { ...cookie, sameSite: "Lax", path: PWA_SCOPE, maxAge: 300 });
+        }
         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.
@@ -152,7 +191,7 @@ export const createPwaPhoneRoutes = (options: PwaPhoneRouteOptions) => {
       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 } : {}) });
+      return c.json({ builds: registeredPwaBuilds(), 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);

package/src/api/pwa.ts

@@ -28,7 +28,7 @@ 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.",
+  REAUTHENTICATE: "Sign in again to pair a device.",
   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.",
@@ -40,7 +40,7 @@ const MESSAGES: Record<PwaError["code"], string> = {
   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.",
+  UNPAIRED: "This device is not paired.",
 };
 
 /** `{ code, message }` with a safe English message; the UI maps codes to its own catalog. */
@@ -95,7 +95,7 @@ const webActor = async (c: Context) => {
   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 };
+  return { userId: session.user.id, sid: session.data.sid, admin: session.user.roles.includes("admin") };
 };
 
 /** The phone this request also comes from (Chrome on a paired Android phone shares the app's cookies). */
@@ -119,7 +119,7 @@ export const createPwaRoutes = (options: PwaRouteOptions = {}) => {
       "/pairings",
       describeRoute({
         tags,
-        summary: "Start pairing a phone",
+        summary: "Start pairing a device",
         description: "Needs a web sign-in from the last ten minutes. The link secret is returned once.",
         responses: { 201: jsonResponse(PwaPairingStartResultSchema, "Pairing started") },
       }),
@@ -129,13 +129,33 @@ export const createPwaRoutes = (options: PwaRouteOptions = {}) => {
         return c.json(await service.startPairing(actor), 201);
       },
     )
+    .post(
+      "/users/:userId/pairings",
+      describeRoute({
+        tags,
+        summary: "Pair the Cloud app for another person",
+        description:
+          "Administrator web session only, signed in within ten minutes. App sessions and API keys are refused. The target account must be active. Uses the existing account pairing and device limits. After the administrator confirms the device code, the device must explicitly accept before credentials are issued.",
+        responses: {
+          201: jsonResponse(PwaPairingStartResultSchema, "Administrative pairing started"),
+          403: { description: "Administrator, fresh web sign-in or active account required" },
+        },
+      }),
+      v("param", z.object({ userId: z.string().uuid() }), pwaInvalidRequest),
+      async (c) => {
+        const actor = await webActor(c);
+        if (!actor.admin) throw new PwaError("FORBIDDEN", 403);
+        if (!shellAvailable(c)) throw new PwaError("UNAVAILABLE", 503);
+        return c.json(await service.startUserPairing(actor, c.req.valid("param").userId), 201);
+      },
+    )
     .get(
       "/pairings/:id",
       describeRoute({
         tags,
         summary: "Read a pairing",
         description:
-          "Only for the web session that started it. Never returns the code. A pending read is held for up to one poll interval and answers as soon as the phone claims the link.",
+          "Only for the web session that started it. Never returns the code. A pending read is held for up to one poll interval and answers as soon as the device claims the link.",
         responses: { 200: jsonResponse(PwaPairingStatusSchema, "Pairing state") },
       }),
       v("param", IdParamSchema, pwaInvalidRequest),
@@ -147,7 +167,13 @@ export const createPwaRoutes = (options: PwaRouteOptions = {}) => {
     )
     .post(
       "/pairings/:id/confirm",
-      describeRoute({ tags, summary: "Confirm a pairing with the code the phone shows", responses: { 204: { description: "Confirmed" } } }),
+      describeRoute({
+        tags,
+        summary: "Confirm a pairing with the code the device shows",
+        description:
+          "Administrative pairings enter awaiting_device; only the claiming device can then accept or reject. Self-pairing proceeds as before.",
+        responses: { 204: { description: "Confirmed" } },
+      }),
       v("param", IdParamSchema, pwaInvalidRequest),
       v("json", PwaPairingConfirmSchema, pwaInvalidRequest),
       async (c) => {
@@ -166,7 +192,7 @@ export const createPwaRoutes = (options: PwaRouteOptions = {}) => {
     )
     .get(
       "/devices",
-      describeRoute({ tags, summary: "List paired phones", responses: { 200: jsonResponse(PwaDeviceListSchema, "Active phones") } }),
+      describeRoute({ tags, summary: "List paired devices", responses: { 200: jsonResponse(PwaDeviceListSchema, "Active devices") } }),
       async (c) => {
         const actor = await webActor(c);
         return c.json({ items: await service.list(actor, await currentDeviceId(c, actor.userId)) });
@@ -174,7 +200,7 @@ export const createPwaRoutes = (options: PwaRouteOptions = {}) => {
     )
     .delete(
       "/devices/:id",
-      describeRoute({ tags, summary: "Remove a paired phone", responses: { 204: { description: "Removed; idempotent" } } }),
+      describeRoute({ tags, summary: "Remove a paired device", responses: { 204: { description: "Removed; idempotent" } } }),
       v("param", IdParamSchema, pwaInvalidRequest),
       async (c) => {
         await service.revoke(await webActor(c), c.req.valid("param").id);