@k2b/cloud 0.43.0 → 0.45.0

package/src/api/auth/account-mismatch.ts

@@ -0,0 +1,24 @@
+import { i18n } from "@k2b/stdlib";
+import type { Context } from "hono";
+import { getLocale } from "../../server/locale";
+
+const messages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      recovery: "Use another sign-in method to confirm your identity. To recover an account, sign out first.",
+      mismatch: "Sign in with the account already open in this browser. If your session expired, open the sign-in page and start again.",
+    },
+    de: {
+      recovery: "Bestätige deine Identität mit einer anderen Anmeldemethode. Zur Kontowiederherstellung melde dich zuerst ab.",
+      mismatch:
+        "Melde dich mit dem Konto an, das in diesem Browser geöffnet ist. Falls deine Sitzung abgelaufen ist, öffne die Anmeldeseite und beginne erneut.",
+    },
+  },
+});
+
+export const accountMismatchResponse = (c: Context) =>
+  c.json({ code: "ACCOUNT_MISMATCH", message: messages.resolve([getLocale(c)]).t.mismatch }, 403);
+
+export const confirmationRecoveryResponse = (c: Context) =>
+  c.json({ code: "CONFIRMATION_METHOD_UNAVAILABLE", message: messages.resolve([getLocale(c)]).t.recovery }, 403);

package/src/api/auth.ts

@@ -4,15 +4,18 @@ import { describeRoute } from "hono-openapi";
 import { z } from "zod";
 import { env } from "../config";
 import { ChangeExpiredPasswordSchema } from "../contracts";
+import { coreUserEventPublisher } from "../events/core-user-created";
 import { type AuthContext, auth, getLocale, jsonResponse, rateLimit, respond, v } from "../server";
 import { accounts, audit, authFlows, getFreeIpaConfig, logger, webauthn } from "../services";
 import { isAccountCategoryAllowed } from "../services/account-category-policy";
 import type { AuthNotificationSender } from "../services/auth-flows/notification-sender";
 import { legalConsent } from "../services/legal-consent";
-import { SessionEpochChangedError } from "../services/session";
+import { SessionAccountMismatchError, SessionEpochChangedError } from "../services/session";
 import * as categorySettings from "../services/settings";
 import { publicCloudOrigin } from "../shared/app-url";
 
+import { accountMismatchResponse, confirmationRecoveryResponse } from "./auth/account-mismatch";
+
 const log = logger("auth");
 
 import { ErrorResponseSchema, MessageResponseSchema } from "../contracts";
@@ -33,7 +36,19 @@ const jsonError = (c: Context, message: string, status: 400 | 401 | 500 | 503) =
 /** Authentication routes: login, logout. */
 export const createAuthRoutes = (notificationSender: AuthNotificationSender) =>
   new Hono<AuthContext>()
+    .onError((error, c) => {
+      if (error instanceof SessionAccountMismatchError) return accountMismatchResponse(c);
+      throw error;
+    })
     .use(rateLimit())
+    .use(async (c, next) => {
+      if (
+        c.req.header("X-Cloud-Reauthenticate") === "1" &&
+        ["/admin-login", "/change-expired-password", "/password-reset/complete"].some((path) => c.req.path.endsWith(path))
+      )
+        return confirmationRecoveryResponse(c);
+      return next();
+    })
     .post(
       "/legal-consent",
       describeRoute({ tags: ["Auth"], summary: "Explicitly accept terms after sign-in; unlock the pending session" }),
@@ -147,13 +162,20 @@ export const createAuthRoutes = (notificationSender: AuthNotificationSender) =>
         tags: ["Auth"],
         summary: "Logout",
         description:
-          "Idempotent: clears the session cookie and revokes the current credential if present. No authentication required — logout must always succeed.",
+          "Idempotent: clears the session cookie and revokes the current credential if present. No authentication required. An optional X-Cloud-Logout-User header binds revocation to that user UUID (or none) without writing the shared browser cookie; a changed account returns 409 without revocation.",
+        parameters: [{ in: "header", name: "X-Cloud-Logout-User", required: false, schema: { type: "string" } }],
         responses: {
           200: jsonResponse(MessageResponseSchema, "Session invalidated"),
+          400: jsonResponse(ErrorResponseSchema, "Invalid expected account"),
+          409: jsonResponse(ErrorResponseSchema, "Browser account changed"),
         },
       }),
       async (c) => {
-        await auth.session.delete(c);
+        const expected = c.req.header("x-cloud-logout-user");
+        if (expected !== undefined && expected !== "none" && !z.string().uuid().safeParse(expected).success)
+          return c.json({ message: "Invalid expected account" }, 400);
+        if (!(await auth.session.delete(c, expected === "none" ? null : expected)))
+          return c.json({ message: "Browser account changed; reload before signing out" }, 409);
         log.info("Logout");
         return c.json({ message: "Logged out" });
       },
@@ -301,7 +323,7 @@ export const createAuthRoutes = (notificationSender: AuthNotificationSender) =>
         tags: ["Auth"],
         summary: "Complete password reset",
         description:
-          "Use a one-time reset token to first sign the account out everywhere, including unpairing Cloud Login and mobile app phones, then set the password, sign out everywhere again and create the new browser session. If signing out everywhere fails before the change, the password stays unchanged; if it fails after the change, no session is issued. Both answer 500, and a new reset link is required. signOutOthersFailed is false whenever a session is issued.",
+          "Use a one-time reset token to first sign the account out everywhere, including unpairing Cloud Login and mobile app devices, then set the password, sign out everywhere again and create the new browser session. If signing out everywhere fails before the change, the password stays unchanged; if it fails after the change, no session is issued. Both answer 500, and a new reset link is required. signOutOthersFailed is false whenever a session is issued.",
         responses: {
           200: jsonResponse(PasswordChangeAuthResponseSchema, "Password reset completed and session created"),
           400: jsonResponse(ErrorResponseSchema, "Password reset failed"),
@@ -399,14 +421,22 @@ export const createAuthRoutes = (notificationSender: AuthNotificationSender) =>
         // prior `DO NOTHING` could log into a pre-existing `uid='admin'` row that
         // was locally demoted (non-admin local user, or even an IPA row named
         // admin), silently bypassing the intent of the emergency endpoint.
-        await sql`
+        await sql.begin(async (tx) => {
+          const [created] = await tx<{ id: string; inserted: boolean }[]>`
         INSERT INTO auth.users (uid, provider, profile, admin, given_name, sn, display_name)
         VALUES ('admin', 'local', 'user', true, 'Admin', '', 'Admin')
         ON CONFLICT (uid) DO UPDATE SET
           provider = 'local',
           profile = 'user',
           admin = true
+        RETURNING id, (xmax = 0) AS inserted
       `;
+          if (created?.inserted)
+            await coreUserEventPublisher().publish(tx, "user.created", {
+              subject: created.id,
+              data: { userId: created.id, provider: "local" },
+            });
+        });
 
         const user = await accounts.users.get({ uid: "admin" });
         if (!user) return jsonError(c, "Failed to resolve admin user.", 500);

package/src/api/capabilities.ts

@@ -1,6 +1,7 @@
 import { Hono, type MiddlewareHandler } from "hono";
 import { describeRoute } from "hono-openapi";
 import { z } from "zod";
+import { type CatalogSubscription, projectAppEventCatalog, readCatalogSubscriptions } from "../_internal/app-event-catalog";
 import { readBoundedJson } from "../_internal/bounded-json";
 import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
 import {
@@ -112,6 +113,7 @@ const CapabilityCatalogQuerySchema = z
   .strict();
 export type CapabilityRouteDependencies = {
   listApps?: () => Promise<AppRegistryEntry[]>;
+  eventSubscriptions?: () => Promise<CatalogSubscription[]>;
   getCapability?: (appId: string) => Promise<CapabilityRegistryEntry | null>;
   fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
   authenticate?: MiddlewareHandler<AuthContext>;
@@ -165,7 +167,7 @@ const invocationAuthorityFromMandate = (authority: {
 
 export const loadCapabilityCatalogPage = async (
   query: { cursor?: string; limit: number },
-  dependencies: Pick<CapabilityRouteDependencies, "listApps" | "getCapability"> = {},
+  dependencies: Pick<CapabilityRouteDependencies, "listApps" | "getCapability" | "eventSubscriptions"> = {},
   locale?: string,
   authority: RequestAuthority | null = null,
 ): Promise<CapabilityCatalog> => {
@@ -178,6 +180,21 @@ export const loadCapabilityCatalogPage = async (
   const liveApps = entries
     .filter((entry) => entry.capabilities?.protocolVersion === CAPABILITY_PROTOCOL_VERSION)
     .sort((left, right) => left.id.localeCompare(right.id));
+  const resolved = new Map<string, CapabilityRegistryEntry | null>();
+  const lookup = async (appId: string) => {
+    if (!resolved.has(appId)) resolved.set(appId, await capabilityLookup(appId));
+    return resolved.get(appId) ?? null;
+  };
+  let subscriptions: CatalogSubscription[] | undefined;
+  const loadSubscribers = async () => {
+    if (!subscriptions) {
+      const visibleApps = new Set(liveApps.map((entry) => entry.id));
+      subscriptions = (await (dependencies.eventSubscriptions ?? readCatalogSubscriptions)()).filter((subscription) =>
+        visibleApps.has(subscription.appId),
+      );
+    }
+    return subscriptions;
+  };
   const start = query.cursor ? liveApps.findIndex((entry) => entry.id > query.cursor!) : 0;
   const offset = start < 0 ? liveApps.length : start;
   const apps: CapabilityCatalog["apps"] = [];
@@ -192,22 +209,29 @@ export const loadCapabilityCatalogPage = async (
   ).byteLength;
   for (const entry of liveApps.slice(offset)) {
     if (apps.length === query.limit) break;
-    const capability = await capabilityLookup(entry.id);
+    const capability = await lookup(entry.id);
     if (!capability || capability.manifest.manifestHash !== entry.capabilities?.manifestHash) {
       lastScannedAppId = entry.id;
       continue;
     }
     const presentedEntry = locale ? resolveAppPresentation(entry, locale) : entry;
+    const manifest = locale
+      ? resolveCapabilityManifestPresentation(capability.manifest, capability.presentation, locale)
+      : capability.manifest;
     const projected = {
       appId: capability.appId,
       appName: presentedEntry.name,
       appIcon: capability.appIcon,
       appDescription: presentedEntry.description,
-      manifest: locale ? resolveCapabilityManifestPresentation(capability.manifest, capability.presentation, locale) : capability.manifest,
+      manifest,
+      ...(manifest.events ? { events: projectAppEventCatalog(manifest, manifest.events.length ? await loadSubscribers() : []) } : {}),
     };
     const projectedBytes = new TextEncoder().encode(JSON.stringify(projected)).byteLength;
     const separatingCommas = apps.length;
-    if (apps.length > 0 && envelopeBytes + bytes + separatingCommas + projectedBytes > CAPABILITY_MAX_CATALOG_BYTES) break;
+    if (envelopeBytes + bytes + separatingCommas + projectedBytes > CAPABILITY_MAX_CATALOG_BYTES) {
+      if (!apps.length) throw new RangeError("An app's event catalog exceeds the catalog response byte limit");
+      break;
+    }
     apps.push(projected);
     bytes += projectedBytes;
     lastScannedAppId = entry.id;

package/src/api/index.ts

@@ -21,6 +21,7 @@ import { aiProjectsRoutes } from "../ai/projects-routes";
 import { aiRoutes } from "../ai/routes";
 import { aiSkillsRoutes } from "../ai/skills-routes";
 import accountsEntitiesRoutes from "./accounts-entities";
+import adminAiRoutes from "./admin-ai";
 import adminAiProjectsRoutes from "./admin-ai-projects";
 import adminAiQuotaRoutes from "./admin-ai-quotas";
 import adminAiSkillsRoutes from "./admin-ai-skills";
@@ -36,6 +37,7 @@ import adminOutgoingMailRoutes from "./admin-outgoing-mail";
 import adminRailRoutes from "./admin-rail";
 import { adminAnnouncementRoutes, announcementRoutes } from "./announcements";
 import { createAppApprovalRoutes } from "./app-approval";
+import { createAppEventRoutes } from "./app-events";
 import { approvalRoutes } from "./approvals";
 import { appDiscoveryRoutes } from "./apps";
 import { createAuthRoutes } from "./auth";
@@ -45,6 +47,7 @@ import { createHelpRoutes } from "./help";
 import { createMcpRoutes } from "./mcp";
 import meRoutes from "./me";
 import { createPwaRoutes } from "./pwa";
+import { createResourceResolveRoutes } from "./resource-resolve";
 import { createSearchRoutes } from "./search";
 import { createSyncOpsProxyRoutes } from "./sync-ops";
 import { createWidgetRoutes } from "./widgets";
@@ -85,8 +88,11 @@ const buildCoreApi = (options: CoreApiOptions) => {
     .route("/accounts", accountsEntitiesRoutes)
     .route("/geo", geoRoutes)
     .route("/apps", appDiscoveryRoutes)
+    .route("/app-events", createAppEventRoutes())
+    .route("/resources", createResourceResolveRoutes())
     .route("/approvals", approvalRoutes)
     .route("/announcements", announcementRoutes)
+    .route("/admin/core/ai", adminAiRoutes)
     .route("/admin/core/ai-usage", adminAiUsageRoutes)
     .route("/admin/core/ai-quotas", adminAiQuotaRoutes)
     .route("/admin/core/ai-projects", adminAiProjectsRoutes)
@@ -136,4 +142,4 @@ export {
   createMcpRoutes,
   publicCloudOrigin,
 } from "./mcp";
-export { resolveCloudResourceHref } from "./resource-links";
+export { resolveCloudResourceHref, resolveCloudResourceUrl } from "./resource-links";

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,
@@ -64,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 =
@@ -73,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>;
@@ -206,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 = (
@@ -343,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) }] };
 };
@@ -490,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,
@@ -582,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);

package/src/api/me.ts

@@ -324,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"),
@@ -343,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"),
       },
@@ -818,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,10 +1,21 @@
 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 {
+  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, rateLimit, v } from "../server";
+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";
 
@@ -83,30 +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);
-        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/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);