@k2b/cloud 0.31.0 → 0.32.0

package/src/approvals/messages.ts

@@ -0,0 +1,95 @@
+import { i18n } from "@k2b/stdlib";
+
+export const approvalMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      title: "Approvals",
+      open: ({ count }: { count: number }) => `${count.toLocaleString("en")} open`,
+      rejectAll: "Reject all",
+      rejectAllTitle: "Reject all open approvals?",
+      rejectAllBody: ({ count }: { count: number }) =>
+        `${count === 1 ? "The open Action does not run." : `None of the ${count.toLocaleString("en")} open Actions runs.`} Where Cloud asked, it continues with your rejection.`,
+      emptyTitle: "Nothing is waiting for you.",
+      emptyBody: "When an Action needs your approval, it appears here and in the chat it comes from.",
+      loading: "Loading approvals…",
+      loadFailed: "Approvals could not be loaded.",
+      retry: "Try again",
+      showMore: "Show more",
+      loadMoreFailed: "More approvals could not be loaded.",
+      elsewhere: ({ count }: { count: number }) => `More approvals in other apps (${count.toLocaleString("en")})`,
+      allApprovals: "All approvals",
+      fromChat: ({ title }: { title: string }) => `from chat “${title}”`,
+      fromUntitledChat: "from a chat",
+      asksEveryTime: "Asks every time",
+      expiresIn: ({ time }: { time: string }) => `Expires ${time}`,
+      details: "Details",
+      reject: "Reject",
+      approve: "Approve",
+      approveForChat: "Approve for this chat",
+      allowWebsiteForChat: "Allow this website in this chat",
+      alwaysApprove: "Always approve",
+      moreOptions: "More approval options",
+      decidedHere: "Just now, decided here",
+      notApplied: "Your decision was not applied",
+      approved: "Approved",
+      rejected: "Rejected",
+      decidedElsewhere: "Already decided elsewhere",
+      gone: "Expired or withdrawn",
+      decisionFailed: "The decision was not saved. Try again.",
+      openIn: ({ app }: { app: string }) => `Open in ${app}`,
+      editIn: ({ app }: { app: string }) => `Edit in ${app}`,
+      statusIn: ({ app }: { app: string }) => `Status in ${app}`,
+      preview: "Preview",
+      download: "Download",
+      exactlyThis: "This approval applies to exactly this Action. If it changes before it runs, Cloud asks again.",
+      approvalFor: ({ title }: { title: string }) => `Approval: ${title}`,
+      close: "Close",
+      waiting: ({ count }: { count: number }) => (count === 0 ? "nothing waiting" : `${count.toLocaleString("en")} waiting`),
+    },
+    de: {
+      title: "Freigaben",
+      open: ({ count }) => `${count.toLocaleString("de")} offen`,
+      rejectAll: "Alle ablehnen",
+      rejectAllTitle: "Alle offenen Freigaben ablehnen?",
+      rejectAllBody: ({ count }) =>
+        `${count === 1 ? "Die offene Aktion läuft nicht." : `Keine der ${count.toLocaleString("de")} offenen Aktionen läuft.`} Wo Cloud gefragt hat, geht es mit deiner Ablehnung weiter.`,
+      emptyTitle: "Nichts wartet auf dich.",
+      emptyBody: "Wenn eine Aktion deine Freigabe braucht, erscheint sie hier und im Chat, aus dem sie kommt.",
+      loading: "Freigaben werden geladen …",
+      loadFailed: "Die Freigaben konnten nicht geladen werden.",
+      retry: "Erneut versuchen",
+      showMore: "Mehr anzeigen",
+      loadMoreFailed: "Weitere Freigaben konnten nicht geladen werden.",
+      elsewhere: ({ count }) => `Weitere Freigaben in anderen Apps (${count.toLocaleString("de")})`,
+      allApprovals: "Alle Freigaben",
+      fromChat: ({ title }) => `aus Chat „${title}“`,
+      fromUntitledChat: "aus einem Chat",
+      asksEveryTime: "Fragt immer",
+      expiresIn: ({ time }) => `Läuft ab ${time}`,
+      details: "Details",
+      reject: "Ablehnen",
+      approve: "Freigeben",
+      approveForChat: "Für diesen Chat freigeben",
+      allowWebsiteForChat: "Diese Website in diesem Chat erlauben",
+      alwaysApprove: "Immer freigeben",
+      moreOptions: "Weitere Freigabeoptionen",
+      decidedHere: "Gerade eben, hier entschieden",
+      notApplied: "Deine Entscheidung wurde nicht übernommen",
+      approved: "Freigegeben",
+      rejected: "Abgelehnt",
+      decidedElsewhere: "Schon anderswo entschieden",
+      gone: "Abgelaufen oder zurückgezogen",
+      decisionFailed: "Die Entscheidung wurde nicht gespeichert. Versuche es erneut.",
+      openIn: ({ app }) => `In ${app} öffnen`,
+      editIn: ({ app }) => `In ${app} bearbeiten`,
+      statusIn: ({ app }) => `Status in ${app}`,
+      preview: "Vorschau",
+      download: "Herunterladen",
+      exactlyThis: "Diese Freigabe gilt genau für diese Aktion. Ändert sie sich, bevor sie läuft, fragt Cloud neu.",
+      approvalFor: ({ title }) => `Freigabe: ${title}`,
+      close: "Schließen",
+      waiting: ({ count }) => (count === 0 ? "nichts offen" : `${count.toLocaleString("de")} offen`),
+    },
+  },
+});

package/src/approvals/ui.ts

@@ -0,0 +1,8 @@
+/**
+ * The shared list of pending Action approvals. Every app mounts the same component for its own scope; Core serves the
+ * route behind it and decides through the platform's approval requests.
+ */
+
+export type { ApprovalsProps } from "./Approvals";
+export { default as Approvals } from "./Approvals";
+export { approvalNavCount, default as ApprovalsNavStatus } from "./ApprovalsNavStatus";

package/src/browser/app-approval.ts

@@ -4,9 +4,12 @@ export { type AppVaultBlob, type AppVaultConfig, AppVaultError, type AppVaultMet
 
 import { z } from "zod";
 import {
+  APP_ACTION_LIMITS,
   APP_APPROVAL_LIMITS,
   APP_APPROVAL_PATH,
   APP_APPROVAL_PROTOCOL,
+  type AppActionView,
+  AppActionViewSchema,
   AppDeviceCommandSchema,
   AppDeviceProofSchema,
   type AppDevicePublicKey,
@@ -19,6 +22,7 @@ import {
   AppPairingResultSchema,
   type AppPendingLogin,
   AppPendingLoginSchema,
+  appActionDigest,
   appDeviceProofMessage,
   appPairingLink,
   appPairingProofMessage,
@@ -84,6 +88,8 @@ const InfoSchema = z.object({
   appOrigin: z.string(),
   algorithm: z.literal("ES256"),
   limits: z.object(Object.fromEntries(Object.entries(APP_APPROVAL_LIMITS).map(([key, value]) => [key, z.literal(value)]))),
+  /** Absent on Clouds that serve only the first version's commands. */
+  features: z.array(z.string().max(40)).max(16).optional(),
 });
 
 /** Call only after the user explicitly trusts the issuer from a pairing link.
@@ -215,6 +221,31 @@ const connect = async (options: {
         throw new AppApprovalClientError("INVALID_RESPONSE");
       return result;
     },
+    /** Whether this Cloud serves `inbox`, `action` and `act`. Older Clouds answer those commands with HTTP 400. */
+    actions: info.features?.includes("actions") === true,
+    /** Pending sign-ins and the newest open Action approvals in one call; use it instead of `pending` where `actions` is true. */
+    inbox: async (device: AppApprovalDevice, signal?: AbortSignal) => {
+      const result = await command(device, { operation: "inbox" }, signal);
+      if (!("actions" in result)) throw new AppApprovalClientError("INVALID_RESPONSE");
+      return result;
+    },
+    /** One open Action approval. The digest is recomputed here, so a view that does not match it is never returned. */
+    action: async (device: AppApprovalDevice, actionId: string, signal?: AbortSignal): Promise<AppActionView> => {
+      const result = await command(device, { operation: "action", actionId }, signal);
+      if (!("digest" in result) || result.actionId !== actionId || (await appActionDigest(issuer, result)) !== result.digest)
+        throw new AppApprovalClientError("INVALID_RESPONSE");
+      return result;
+    },
+    /** Signs the decision over the view's digest. Only call it on an explicit choice of the person. */
+    act: async (device: AppApprovalDevice, view: AppActionView, decision: "approve" | "deny", signal?: AbortSignal) => {
+      view = AppActionViewSchema.parse(view);
+      if (Date.parse(view.expiresAt) <= Date.now() || (await appActionDigest(issuer, view)) !== view.digest)
+        throw new AppApprovalClientError("INVALID_INPUT");
+      const result = await command(device, { operation: "act", actionId: view.actionId, digest: view.digest, decision }, signal);
+      if (!("state" in result) || result.state !== (decision === "approve" ? "approved" : "denied"))
+        throw new AppApprovalClientError("INVALID_RESPONSE");
+      return result;
+    },
     /** Reads the account this device signs in and the device's own record. Older Clouds answer HTTP 400. */
     account: async (device: AppApprovalDevice, signal?: AbortSignal) => {
       const result = await command(device, { operation: "account" }, signal);
@@ -243,4 +274,5 @@ export const appApproval = {
   createKey,
   connect,
   limits: APP_APPROVAL_LIMITS,
+  actionLimits: APP_ACTION_LIMITS,
 };

package/src/browser/choose-files.tsx

@@ -1,9 +1,10 @@
 import { showFileDialog } from "@k2b/stdlib/browser";
 import { dialogCore, panelDialogWorkspaceOptions } from "@k2b/ui";
 import { createSignal } from "solid-js";
-import { type ChooseFilesOptions, FileChooser, type FileProviderList } from "./FileChooser";
+import type { ChooseFilesOptions, FileProviderList } from "./FileChooser";
 import type { FileProviderCaller } from "./file-providers";
 import type { ProviderList } from "./provider-list";
+import { importOnDemand } from "./reload";
 
 /**
  * One page's file choosing over its provider list. `caller` carries the locale and, in tests, the transport.
@@ -39,18 +40,30 @@ export const createFileChoosing = (
       );
     };
     if (!known) load();
-    return dialogCore
-      .open<File[]>(
-        (close) => <FileChooser options={options} providers={providers} retryProviders={load} caller={caller} close={close} />,
-        {
-          ...panelDialogWorkspaceOptions,
-          panelClassName: `${panelDialogWorkspaceOptions.panelClassName} cloud-file-chooser-dialog`,
-          initialFocus: (dialog) => dialog.querySelector<HTMLElement>('[role="gridcell"][tabindex="0"]'),
-          signal: options.signal,
-          history: true,
-        },
-      )
-      .then((files) => files ?? []);
+    return (async () => {
+      let abort = () => {};
+      const chooser = await Promise.race([
+        importOnDemand(() => import("./FileChooser")),
+        new Promise<undefined>((resolve) => {
+          abort = () => resolve(undefined);
+          signal?.addEventListener("abort", abort, { once: true });
+          if (signal?.aborted) abort();
+        }),
+      ]).finally(() => signal?.removeEventListener("abort", abort));
+      if (!chooser) return [];
+      return dialogCore
+        .open<File[]>(
+          (close) => <chooser.FileChooser options={options} providers={providers} retryProviders={load} caller={caller} close={close} />,
+          {
+            ...panelDialogWorkspaceOptions,
+            panelClassName: `${panelDialogWorkspaceOptions.panelClassName} cloud-file-chooser-dialog`,
+            initialFocus: (dialog) => dialog.querySelector<HTMLElement>('[role="gridcell"][tabindex="0"]'),
+            signal: options.signal,
+            history: true,
+          },
+        )
+        .then((files) => files ?? []);
+    })();
   };
 
   return chooseFiles;

package/src/browser/commands.ts

@@ -1,12 +1,12 @@
 import { toast } from "@k2b/ui";
-import { resolveCommand } from "../capabilities/client";
-import { type CommandOptions, CommandOptionsSchema, clearCommand, readCommand } from "../contracts/commands";
+import type { CommandOptions } from "../contracts/commands";
 import {
   type ContextAwareCommand,
   collectContextAwareCommands,
   requestCommandHandling,
   requestContextCommandExecution,
 } from "./command-bridge";
+import { importOnDemand } from "./reload";
 import { resourceSearchMessages } from "./resource-search-messages";
 import { requestGlobalSearch } from "./search-bridge";
 
@@ -16,17 +16,26 @@ export { registerCommandHandler, registerContextAwareCommand } from "./command-b
 
 /** Opens locally only when a mounted owner explicitly accepts; otherwise follows the app's URL. */
 export const openCommand = async (command: string, input: unknown = {}, options: CommandOptions = {}): Promise<void> => {
-  const parsedOptions = CommandOptionsSchema.parse(options);
+  const modules = await importOnDemand(() => Promise.all([import("../contracts/commands"), import("../capabilities/client")]));
+  if (!modules) return;
+  const [contracts, capabilities] = modules;
+  const parsedOptions = contracts.CommandOptionsSchema.parse(options);
   const handled = requestCommandHandling({ command, input, options: parsedOptions });
   if (handled) return handled;
-  const result = await resolveCommand(command, input, parsedOptions);
+  const result = await capabilities.resolveCommand(command, input, parsedOptions);
   if (!result.ok) throw new Error(result.error.message);
   window.location.assign(result.data.href);
 };
 
 /** Call after this page's handlers have mounted. Each entry is consumed, including invalid links. */
 export const consumeCommandLink = async (): Promise<void> => {
+  const command = new URL(window.location.href).searchParams.get("command");
+  if (!command) return;
+  const contracts = await importOnDemand(() => import("../contracts/commands"));
+  if (!contracts) return;
   const url = new URL(window.location.href);
+  if (url.searchParams.get("command") !== command) return;
+  const { clearCommand, readCommand } = contracts;
   const messages = resourceSearchMessages.resolve([document.documentElement.lang]).t;
   let target: ReturnType<typeof readCommand>;
   try {

package/src/browser/file-provider-error.ts

@@ -0,0 +1,11 @@
+/** A provider failure the chooser explains; `status` 0 means the browser is offline. */
+export class FileProviderError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = "FileProviderError";
+  }
+}

package/src/browser/file-providers.ts

@@ -15,6 +15,9 @@ import {
   fileProviderIssues,
 } from "../contracts/file-provider";
 import { LOCALE_HEADER } from "../shared/locale";
+import { FileProviderError } from "./file-provider-error";
+
+export { FileProviderError } from "./file-provider-error";
 
 /** One live application whose catalog manifest offers files, reduced to what choosing a file needs. */
 export type FileProviderSource = {
@@ -31,18 +34,6 @@ export type FileProviderSource = {
 
 export type FileProviderCaller = Pick<CapabilityHttpOptions, "fetch" | "baseUrl"> & { locale: string };
 
-/** A provider failure the chooser explains; `status` 0 means the browser is offline. */
-export class FileProviderError extends Error {
-  constructor(
-    readonly code: string,
-    message: string,
-    readonly status: number,
-  ) {
-    super(message);
-    this.name = "FileProviderError";
-  }
-}
-
 /** The page size the chooser asks for; the contract allows 1 to 100. */
 export const FILE_PROVIDER_PAGE_SIZE = 50;
 /** At most this many provider reads run at the same time. */

package/src/browser/files.tsx

@@ -1,5 +1,4 @@
 import { createFileChoosing } from "./choose-files";
-import { loadFileProviders } from "./file-providers";
 import { createProviderList } from "./provider-list";
 import { createFileSaving } from "./save-files";
 
@@ -7,7 +6,7 @@ export type { ChooseFilesOptions } from "./FileChooser";
 export { SAVE_FILES_ICON, type SavedFile, type SaveFileSource, type SaveFilesOptions } from "./save-files";
 
 const pageLocale = () => (typeof document === "undefined" ? "en" : document.documentElement.lang || "en");
-const providers = createProviderList(() => loadFileProviders({ locale: pageLocale() }));
+const providers = createProviderList(async () => (await import("./file-providers")).loadFileProviders({ locale: pageLocale() }));
 const saving = createFileSaving(providers);
 
 /**

package/src/browser/live-connection.ts

@@ -1,4 +1,4 @@
-import { type LiveServerMessage, LiveServerMessageSchema } from "../events/live-protocol";
+import { type LiveServerMessage, parseLiveServerMessage } from "../events/live-server-message";
 import { createLiveWebSocket, type LiveWebSocket } from "./live-websocket";
 
 export type LiveSubscriptionHandlers<T> = {
@@ -41,8 +41,7 @@ const shared = new Map<string, Shared>();
 
 const parseMessage = (raw: string): LiveServerMessage | null => {
   try {
-    const parsed = LiveServerMessageSchema.safeParse(JSON.parse(raw));
-    return parsed.success ? parsed.data : null;
+    return parseLiveServerMessage(JSON.parse(raw));
   } catch {
     return null;
   }

package/src/browser/provider-list.ts

@@ -1,5 +1,6 @@
 import { createSignal } from "solid-js";
-import { FileProviderError, type FileProviderSource } from "./file-providers";
+import { FileProviderError } from "./file-provider-error";
+import type { FileProviderSource } from "./file-providers";
 
 /** The catalog refuses the caller, such as a visitor of a public page or a session that has just expired. */
 const refused = (error: unknown) => error instanceof FileProviderError && (error.status === 401 || error.status === 403);

package/src/browser/save-files.tsx

@@ -1,10 +1,11 @@
 import { dialogCore, IconButton, type IconButtonProps, panelDialogWorkspaceOptions, toast, useLocale } from "@k2b/ui";
 import { createSignal, type JSX, splitProps } from "solid-js";
 import type { FileProviderList } from "./FileChooser";
-import { FileSaver, type SavedFile } from "./FileSaver";
+import type { SavedFile } from "./FileSaver";
 import { fileChooserMessages } from "./file-chooser-messages";
 import type { FileProviderCaller, SaveFileSource } from "./file-providers";
 import type { ProviderList } from "./provider-list";
+import { importOnDemand } from "./reload";
 
 export type { SavedFile } from "./FileSaver";
 export type { SaveFileSource } from "./file-providers";
@@ -40,9 +41,19 @@ export const createFileSaving = (
     if (!known) load();
     const saved: SavedFile[] = [];
     const running = new Set<Promise<void>>();
+    let abort = () => {};
+    const saver = await Promise.race([
+      importOnDemand(() => import("./FileSaver")),
+      new Promise<undefined>((resolve) => {
+        abort = () => resolve(undefined);
+        options.signal?.addEventListener("abort", abort, { once: true });
+        if (options.signal?.aborted) abort();
+      }),
+    ]).finally(() => options.signal?.removeEventListener("abort", abort));
+    if (!saver) return [];
     await dialogCore.open<void>(
       (close) => (
-        <FileSaver
+        <saver.FileSaver
           files={files}
           providers={providers}
           retryProviders={load}

package/src/cli/account.ts

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { isModelsOnlyApiKey } from "../contracts/shared";
 import { arg, type CliInputFlagValue, type CloudCliContext, command, confirmFlag, defineCliCommands, flag, readCliInput } from "./index";
 
 type User = {
@@ -31,6 +32,7 @@ type User = {
 };
 
 type ApiKey = {
+  scopes: string[];
   id: string;
   name: string;
   status: "active" | "revoked";
@@ -121,6 +123,7 @@ const apiKeyRows = (keys: ApiKey[]) =>
     id: key.id,
     name: key.name,
     prefix: key.tokenPrefix,
+    access: isModelsOnlyApiKey(key) ? "models" : "full",
     expires: key.expiresAt ?? "never",
     lastUsed: key.lastUsedAt ?? "never",
     created: key.createdAt,
@@ -283,6 +286,7 @@ export default defineCliCommands({
         printJsonOrTable(ctx, result, apiKeyRows(result.items), [
           { key: "name" },
           { key: "prefix" },
+          { key: "access" },
           { key: "expires" },
           { key: "lastUsed" },
           { key: "id" },
@@ -294,15 +298,30 @@ export default defineCliCommands({
       args: { name: arg.required({ valueLabel: "name", description: "API key name" }) },
       flags: {
         expires: flag.string({ description: "ISO timestamp or duration like 90d" }),
+        access: flag.enum(["full", "models"], { default: "full", description: "Full access or models-only inference access" }),
       },
       run: async ({ ctx, args, flags }) => {
         const result = await readApi<{ credential: ApiKey; token: string }>(
           ctx,
           "/api-keys",
-          jsonRequest("POST", { name: args.name, expiresAt: parseExpiry(flags.expires) }),
+          jsonRequest("POST", { name: args.name, expiresAt: parseExpiry(flags.expires), access: flags.access }),
         );
+        const modelsOnly = isModelsOnlyApiKey(result.credential);
+        if (flags.access === "models" && !modelsOnly) {
+          try {
+            await readApi<{ message: string }>(ctx, `/api-keys/${encodeURIComponent(result.credential.id)}`, jsonRequest("DELETE"));
+          } catch {
+            throw new Error(
+              `The key was created with full access and could not be revoked automatically. Run: cld account api-keys revoke ${result.credential.id} --yes`,
+            );
+          }
+          throw new Error("This Cloud does not support models-only API keys. The full-access key it created was revoked.");
+        }
         if (ctx.options.output === "json") ctx.json(result);
-        else ctx.print(`Token: ${result.token}\nPrefix: ${result.credential.tokenPrefix}\nStore this token now. It cannot be shown again.`);
+        else {
+          ctx.print(`Token: ${result.token}\nPrefix: ${result.credential.tokenPrefix}\nStore this token now. It cannot be shown again.`);
+          if (modelsOnly) ctx.print("This key works only with the OpenAI-compatible API at /api/ai/openai/v1 on this Cloud.");
+        }
       },
     }),
     command("api-keys revoke", {

package/src/cli/commands.ts

@@ -617,8 +617,10 @@ const renderFlagUsage = (key: string, spec: CliFlagSpec): string => {
 
 const renderFlagDescription = (spec: CliFlagSpec): string => {
   const parts = [spec.description];
-  if ("default" in spec && spec.default !== undefined)
-    parts.push(`Default: ${Array.isArray(spec.default) ? spec.default.join(",") : spec.default}.`);
+  const hasDefault = "default" in spec && spec.default !== undefined;
+  if ("required" in spec && spec.required && !hasDefault) parts.push("Required.");
+  if (hasDefault) parts.push(`Default: ${Array.isArray(spec.default) ? spec.default.join(",") : spec.default}.`);
   if (spec.kind === "enum") parts.push(`Values: ${spec.values.join(", ")}.`);
+  if (parts.length > 1 && parts[0] && !/[.!?:]$/.test(parts[0])) parts[0] += ".";
   return parts.filter(Boolean).join(" ");
 };

package/src/contracts/app-approval.ts

@@ -14,10 +14,29 @@ export const APP_APPROVAL_LIMITS = {
   pageSize: 20,
   pollSeconds: 5,
 } as const;
+/**
+ * Bounds of Action approvals on a device. Kept apart from `APP_APPROVAL_LIMITS`, whose every value a version 1
+ * authenticator checks when it connects. The texts are cut so that a whole inbox or Action stays within `bodyBytes`.
+ */
+export const APP_ACTION_LIMITS = {
+  inboxActions: 5,
+  nameChars: 60,
+  titleChars: 80,
+  summaryChars: 120,
+  sentenceChars: 280,
+  messageChars: 500,
+  details: 8,
+  labelChars: 40,
+  valueChars: 300,
+} as const;
+/** Commands a Cloud serves beyond the first version, announced in `/info` as `features`. */
+export const APP_APPROVAL_FEATURES = ["actions"] as const;
 
 const Id = z.string().uuid();
 const Secret = z.string().regex(/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/);
 const Signature = z.string().regex(/^[A-Za-z0-9_-]{85}[AQgw]$/);
+/** Unpadded base64url of a SHA-256 hash. */
+const Digest = Secret;
 export const AppDevicePublicKeySchema = z
   .object({
     kty: z.literal("EC"),
@@ -57,6 +76,12 @@ export const AppDeviceCommandSchema = z.discriminatedUnion("operation", [
   z.object({ operation: z.literal("account") }).strict(),
   /** Stores the authenticator's opaque push token for sign-in wake-ups on this device. */
   z.object({ operation: z.literal("push"), token: z.string().regex(/^[A-Za-z0-9_-]{43}$/) }).strict(),
+  /** Pending sign-ins and the newest open Action approvals of the signing device's account in one call. */
+  z.object({ operation: z.literal("inbox") }).strict(),
+  /** One open Action approval as the device shows it, with the digest the device recomputes before it decides. */
+  z.object({ operation: z.literal("action"), actionId: Id }).strict(),
+  /** Decides an Action approval. `digest` binds the decision to exactly the view the person saw. */
+  z.object({ operation: z.literal("act"), actionId: Id, digest: Digest, decision: z.enum(["approve", "deny"]) }).strict(),
   z
     .object({
       operation: z.literal("decide"),
@@ -96,6 +121,8 @@ export const appDeviceProofMessage = (proof: AppDeviceProof): string => {
     c.operation,
     ...(c.operation === "decide" ? [c.requestId, c.challenge, c.comparison, c.decision] : []),
     ...(c.operation === "push" ? [c.token] : []),
+    ...(c.operation === "action" ? [c.actionId] : []),
+    ...(c.operation === "act" ? [c.actionId, c.digest, c.decision] : []),
   ]);
 };
 export const appPairingProofMessage = (issuer: string, claim: Omit<z.infer<typeof AppPairingClaimSchema>, "signature">): string =>
@@ -188,6 +215,97 @@ export const AppDeviceAccountSchema = z
   })
   .strict();
 export type AppDeviceAccount = z.infer<typeof AppDeviceAccountSchema>;
+/** Plain text on one line: no control, format or bidirectional characters, so an app cannot fake Cloud's own frame. */
+const PlainText = (max: number) =>
+  z
+    .string()
+    .refine((value) => Array.from(value).length <= max, `Must contain at most ${max} code points`)
+    .regex(/^[^\p{Cc}\p{Cf}\p{Zl}\p{Zp}]*$/u);
+const ActionApp = z
+  .object({ id: PlainText(APP_ACTION_LIMITS.nameChars).min(1), name: PlainText(APP_ACTION_LIMITS.nameChars).min(1) })
+  .strict();
+const actionFields = {
+  actionId: Id,
+  /** The app that owns the effect, named from the Cloud's registry, never from the request. */
+  app: ActionApp,
+  /** The app that asked, such as the Assistant, and the title of its chat. The title is chat content, not Cloud's words. */
+  requester: z.object({ app: ActionApp, title: PlainText(APP_ACTION_LIMITS.titleChars).nullable() }).strict(),
+  /** `confirm` asks every time; `standard` could also be remembered in Cloud. A device decides both alike. */
+  assurance: z.enum(["standard", "confirm"]),
+  createdAt: DateTime,
+  expiresAt: DateTime,
+};
+/** One inbox row. `sentence` is the start of the app's sentence; read the Action for everything the person approves. */
+export const AppActionSummarySchema = z.object({ ...actionFields, sentence: PlainText(APP_ACTION_LIMITS.summaryChars).min(1) }).strict();
+export const AppActionViewSchema = z
+  .object({
+    ...actionFields,
+    /** What the Action does, in the app's words and the person's language. */
+    sentence: PlainText(APP_ACTION_LIMITS.sentenceChars).min(1),
+    /** The app's review of this call, or `null`. */
+    message: PlainText(APP_ACTION_LIMITS.messageChars).nullable(),
+    details: z
+      .array(
+        z
+          .object({
+            label: PlainText(APP_ACTION_LIMITS.labelChars).min(1),
+            value: PlainText(APP_ACTION_LIMITS.valueChars),
+            /** A date (`YYYY-MM-DD` or RFC 3339) or an RFC 3339 date-time the device shows in its own locale and time zone. */
+            format: z.enum(["date", "date-time"]).optional(),
+          })
+          .strict(),
+      )
+      .max(APP_ACTION_LIMITS.details),
+    /** Cloud shortened or left out text; the complete request is in Cloud. */
+    truncated: z.boolean(),
+    /** SHA-256 of the Action's real input. The device cannot check it; it binds the decision to that input. */
+    argsDigest: z.string().min(1).max(128),
+    digest: Digest,
+  })
+  .strict();
+export type AppActionSummary = z.infer<typeof AppActionSummarySchema>;
+export type AppActionView = z.infer<typeof AppActionViewSchema>;
+export const AppDeviceInboxSchema = z
+  .object({
+    logins: z.array(AppPendingLoginSchema).max(APP_APPROVAL_LIMITS.pendingPerAccount),
+    /** Newest first. */
+    actions: z.array(AppActionSummarySchema).max(APP_ACTION_LIMITS.inboxActions),
+    /** Open Action approvals beyond `actions`. */
+    moreActions: z.number().int().nonnegative(),
+    pollAfterSeconds: z.number().positive(),
+  })
+  .strict();
+export type AppDeviceInbox = z.infer<typeof AppDeviceInboxSchema>;
+
+/** UTF-8 of this exact JSON array is hashed into an Action's `digest`. Every field the device shows is part of it. */
+export const appActionDigestMessage = (issuer: string, view: Omit<AppActionView, "digest">): string =>
+  JSON.stringify([
+    "cloud-action-v1",
+    issuer,
+    view.actionId,
+    view.app.id,
+    view.app.name,
+    view.requester.app.id,
+    view.requester.app.name,
+    view.requester.title,
+    view.assurance,
+    view.sentence,
+    view.message,
+    view.details.map((detail) => [detail.label, detail.value, detail.format ?? null]),
+    view.truncated,
+    view.createdAt,
+    view.expiresAt,
+    view.argsDigest,
+  ]);
+/** Unpadded base64url of SHA-256 over `appActionDigestMessage`. Cloud and the device compute it alike. */
+export const appActionDigest = async (issuer: string, view: Omit<AppActionView, "digest">): Promise<string> => {
+  const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(appActionDigestMessage(issuer, view))));
+  return btoa(String.fromCharCode(...hash))
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replaceAll("=", "");
+};
+
 export const AppDeviceResponseSchema = z.union([
   z
     .object({
@@ -197,6 +315,8 @@ export const AppDeviceResponseSchema = z.union([
     .strict(),
   z.object({ state: z.enum(["approved", "denied", "revoked", "updated"]) }).strict(),
   AppDeviceAccountSchema,
+  AppDeviceInboxSchema,
+  AppActionViewSchema,
 ]);
 export const AppLoginStartResultSchema = z
   .object({ requestId: Id, browserSecret: Secret, comparison: Comparison, expiresAt: DateTime, pollAfterSeconds: z.number().positive() })

package/src/contracts/approval-paths.ts

@@ -0,0 +1,4 @@
+export const APPROVALS_API_PATH = "/api/approvals";
+export const APPROVAL_COUNTS_PATH = `${APPROVALS_API_PATH}/counts`;
+/** The Core page that lists every app's open approvals; `?app=<id>` narrows it to one app. */
+export const APPROVALS_PAGE_PATH = "/me/approvals";