@k2b/cloud 0.31.0 → 0.32.0

package/src/contracts/approvals.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { APP_APPROVAL_LIMITS } from "./app-approval";
+import { CapabilityActionReviewSchema, CapabilityAppIdSchema } from "./capabilities";
+
+export { APPROVAL_COUNTS_PATH, APPROVALS_API_PATH, APPROVALS_PAGE_PATH } from "./approval-paths";
+
+/**
+ * Pending Action approvals as every app lists and decides them: one Core route under `/api/approvals` and the
+ * `Approvals` component from `@k2b/cloud/approvals/ui`. A list shows only the signed-in person's own open requests.
+ */
+
+/** One page of a list, the same as a Cloud Login inbox page. */
+export const APPROVALS_PAGE_SIZE = APP_APPROVAL_LIMITS.pageSize;
+
+/**
+ * A client that relays decisions from an editor over the Agent Client Protocol sends this header with the value
+ * `acp`. Such a client may reject any request, but approves only `standard` ones. Cloud cannot verify the header: it is
+ * the bridge's own declaration, which keeps the editor that drives the bridge from approving a `confirm` request.
+ */
+export const APPROVAL_CLIENT_HEADER = "x-cloud-client";
+export const APPROVAL_ACP_CLIENT = "acp";
+
+export const ApprovalListQuerySchema = z
+  .object({
+    /** Requests whose effect belongs to this app, or that this app asked for. */
+    app: CapabilityAppIdSchema.optional(),
+    /** Requests whose review links to this same-origin path, such as the draft a send Action would send. */
+    link: z.string().startsWith("/").max(2048).optional(),
+    cursor: z.string().min(1).max(200).optional(),
+  })
+  .strict();
+export type ApprovalListQuery = z.infer<typeof ApprovalListQuerySchema>;
+
+export const PendingApprovalSchema = z
+  .object({
+    id: z.uuid(),
+    /** The app that owns the effect, named from the registry in the reader's language. */
+    app: z.object({ id: z.string(), name: z.string(), icon: z.string().nullable() }).strict(),
+    action: z.string(),
+    /** `confirm` asks every time and never offers to remember; `standard` may offer it. */
+    assurance: z.enum(["standard", "confirm"]),
+    /** What the person reads: the first line names the app and the Action, later lines add `Label: value` details. */
+    sentence: z.string(),
+    /** The owning app's review as the person saw it when Cloud asked. */
+    review: CapabilityActionReviewSchema.nullable(),
+    /** Where the request waits. The title is chat content, written by a person or a model, never Cloud's own words. */
+    requester: z.object({ kind: z.literal("chat"), appId: z.string(), title: z.string().nullable(), href: z.string() }).strict(),
+    /** Ways the person may remember this approval, the same the chat card offers. */
+    remember: z.object({ chat: z.boolean(), always: z.boolean(), website: z.boolean() }).strict(),
+    createdAt: z.string(),
+    expiresAt: z.string(),
+  })
+  .strict();
+export type PendingApproval = z.infer<typeof PendingApprovalSchema>;
+
+export const ApprovalPageSchema = z
+  .object({
+    items: z.array(PendingApprovalSchema).max(APPROVALS_PAGE_SIZE),
+    nextCursor: z.string().nullable(),
+    /** Open requests that match the query, across all pages. */
+    count: z.number().int().nonnegative(),
+    /** Open requests of the person that do not match the query; 0 without `app` or `link`. */
+    elsewhere: z.number().int().nonnegative(),
+  })
+  .strict();
+export type ApprovalPage = z.infer<typeof ApprovalPageSchema>;
+
+export const ApprovalCountsSchema = z
+  .object({
+    total: z.number().int().nonnegative(),
+    /** Per app ID: open requests whose effect belongs to the app or that the app asked for, as `?app=` lists them. */
+    apps: z.record(z.string(), z.number().int().positive()),
+  })
+  .strict();
+export type ApprovalCounts = z.infer<typeof ApprovalCountsSchema>;
+
+export const ApprovalDecisionInputSchema = z.object({ approved: z.boolean(), remember: z.enum(["chat", "always"]).optional() }).strict();
+export type ApprovalDecisionInput = z.infer<typeof ApprovalDecisionInputSchema>;
+
+export const ApprovalDecisionResultSchema = z.object({ status: z.enum(["approved", "rejected"]) }).strict();
+export type ApprovalDecisionResult = z.infer<typeof ApprovalDecisionResultSchema>;

package/src/contracts/command-path.ts

@@ -0,0 +1,17 @@
+/** Commands carry small public references/options, never document bodies or secrets. */
+export const COMMAND_MAX_URL_LENGTH = 8192;
+
+/** The same-origin path rule of `CommandPathSchema`, without its length limit. */
+export const isCommandPathSyntax = (value: string): boolean => {
+  if (!value.startsWith("/") || /[\\\u0000-\u0020]/u.test(value)) return false;
+  try {
+    const url = new URL(value, "https://cloud.invalid");
+    // Dot segments can resolve to `//host`, which a browser reads as another host.
+    return url.origin === "https://cloud.invalid" && !url.pathname.startsWith("//");
+  } catch {
+    return false;
+  }
+};
+
+/** Whether `value` is a Cloud path that `CommandPathSchema` accepts; loads no validators. */
+export const isCommandPath = (value: string): boolean => (value.length <= 2000 || [...value].length <= 2000) && isCommandPathSyntax(value);

package/src/contracts/commands.ts

@@ -1,20 +1,10 @@
 import { z } from "zod";
+import { COMMAND_MAX_URL_LENGTH, isCommandPathSyntax } from "./command-path";
 
-/** Commands carry small public references/options, never document bodies or secrets. */
-export const COMMAND_MAX_URL_LENGTH = 8192;
-export const CommandPathSchema = z
-  .string()
-  .max(2000)
-  .refine((value) => {
-    if (!value.startsWith("/") || /[\\\u0000-\u0020]/u.test(value)) return false;
-    try {
-      const url = new URL(value, "https://cloud.invalid");
-      // Dot segments can resolve to `//host`, which a browser reads as another host.
-      return url.origin === "https://cloud.invalid" && !url.pathname.startsWith("//");
-    } catch {
-      return false;
-    }
-  }, "Expected a Cloud path");
+export { COMMAND_MAX_URL_LENGTH, isCommandPath } from "./command-path";
+
+// Keep the size error separate from the syntax error, as before.
+export const CommandPathSchema = z.string().max(2000).refine(isCommandPathSyntax, "Expected a Cloud path");
 
 export const CommandOptionsSchema = z.object({ returnTo: CommandPathSchema.optional() }).strict();
 export type CommandOptions = z.infer<typeof CommandOptionsSchema>;

package/src/contracts/shared.ts

@@ -248,7 +248,12 @@ export const ServiceAccountCredentialSchema = z.object({
 });
 export type ServiceAccountCredential = z.infer<typeof ServiceAccountCredentialSchema>;
 
+export const AI_INFERENCE_SCOPE = "ai:inference" as const;
+
+export const isModelsOnlyApiKey = (credential: { scopes: readonly string[] }): boolean => credential.scopes.includes(AI_INFERENCE_SCOPE);
+
 export const CreateUserApiKeySchema = z.object({
+  access: z.enum(["full", "models"]).optional(),
   name: z.string().trim().min(1).max(120),
   expiresAt: z.string().datetime().nullable().optional(),
 });

package/src/events/live-protocol.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+export type { LiveServerMessage } from "./live-server-message";
+
 /** Messages a live socket accepts: subscriptions only. Writes go over HTTP. */
 export const LiveClientMessageSchema = z.discriminatedUnion("t", [
   z
@@ -28,4 +30,3 @@ export const LiveServerMessageSchema = z.discriminatedUnion("t", [
   z.object({ t: z.literal("revoked"), id: z.string(), code: z.enum(["not_found", "access_denied"]) }),
   z.object({ t: z.literal("error"), code: z.string(), message: z.string() }),
 ]);
-export type LiveServerMessage = z.infer<typeof LiveServerMessageSchema>;

package/src/events/live-server-message.ts

@@ -0,0 +1,40 @@
+/** The server's live wire messages; validation equivalence is checked against live-protocol. */
+export type LiveServerMessage =
+  | { t: "ready"; id: string; cursor: string }
+  | { t: "event"; id: string; cursor: string; data: unknown }
+  | { t: "progress"; cursor: string }
+  | { t: "resync"; id: string; cursor: string }
+  | { t: "revoked"; id: string; code: "not_found" | "access_denied" }
+  | { t: "error"; code: string; message: string };
+
+/** Strip undeclared keys just like the server-message schema. */
+export const parseLiveServerMessage = (value: unknown): LiveServerMessage | null => {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || !("t" in value)) return null;
+  switch (value.t) {
+    case "ready":
+    case "resync":
+    case "event": {
+      if (!("id" in value) || typeof value.id !== "string" || !("cursor" in value) || typeof value.cursor !== "string") return null;
+      if (value.t === "event") {
+        // Zod v4 requires the key even though its value is unknown (and may be undefined).
+        return "data" in value ? { t: value.t, id: value.id, cursor: value.cursor, data: value.data } : null;
+      }
+      return { t: value.t, id: value.id, cursor: value.cursor };
+    }
+    case "progress":
+      return "cursor" in value && typeof value.cursor === "string" ? { t: value.t, cursor: value.cursor } : null;
+    case "revoked":
+      return "id" in value &&
+        typeof value.id === "string" &&
+        "code" in value &&
+        (value.code === "not_found" || value.code === "access_denied")
+        ? { t: value.t, id: value.id, code: value.code }
+        : null;
+    case "error":
+      return "code" in value && typeof value.code === "string" && "message" in value && typeof value.message === "string"
+        ? { t: value.t, code: value.code, message: value.message }
+        : null;
+    default:
+      return null;
+  }
+};

package/src/events/testing.ts

@@ -0,0 +1,88 @@
+import { CursorMismatchError, RetentionGapError, type TopicEvent } from "@k2b/sync";
+import type { LiveEnvelope, LiveTopic } from "./live-engine";
+
+/** Publishes an application's real outbox without starting its application. */
+export { startLiveOutbox } from "./live";
+export {
+  /** Creates the real delivery engine for application channel tests. */
+  createLiveEngine,
+  /** Platform bounds; restore any intervals shortened by a test. */
+  LIVE_LIMITS,
+  /** The delivery engine used by channel tests. */
+  type LiveEngine,
+  /** One application's update, access change, or resync hint. */
+  type LiveEnvelope,
+  /** The topic operations consumed by the delivery engine. */
+  type LiveTopic,
+} from "./live-engine";
+
+/** A memory topic with Sync cursor and retention rules, plus publish and trim controls. */
+export const createMemoryLiveTopic = () => {
+  const name = crypto.randomUUID().replaceAll("-", "");
+  let sequence = 0;
+  let first = 1;
+  const events: TopicEvent<LiveEnvelope>[] = [];
+  const wakes = new Set<() => void>();
+  const cursorAt = (seq: number) => `s6t.${name}.${seq}`;
+  const cursorSequence = (cursor: string) => {
+    const match = /^s6t\.([a-z0-9]+)\.(\d+)$/.exec(cursor);
+    if (!match || match[1] !== name) throw new CursorMismatchError("The cursor belongs to another topic");
+    return Number(match[2]);
+  };
+  const checkGap = (position: number) => {
+    if (position + 1 < first) throw new RetentionGapError(cursorAt(position + 1), cursorAt(first), cursorAt(first - 1));
+  };
+  return {
+    cursorAt,
+    cursorSequence,
+    head: async () => cursorAt(sequence),
+    publish: (data: LiveEnvelope) => {
+      events.push({
+        data,
+        eventId: String(++sequence),
+        cursor: cursorAt(sequence),
+        sequence,
+        tenantId: "default",
+        publishedAt: new Date(),
+      });
+      for (const wake of wakes) wake();
+    },
+    trim: (count: number) => {
+      events.splice(0, Math.max(0, count));
+      first = events[0]?.sequence ?? sequence + 1;
+    },
+    replay: (options: { after?: string; until?: string } = {}): AsyncIterable<TopicEvent<LiveEnvelope>> => {
+      const after = cursorSequence(options.after ?? cursorAt(0));
+      const until = options.until ? cursorSequence(options.until) : sequence;
+      checkGap(after);
+      const batch = events.filter((event) => event.sequence > after && event.sequence <= until);
+      return (async function* () {
+        yield* batch;
+      })();
+    },
+    follow: (options: { after?: string; signal?: AbortSignal } = {}): AsyncIterable<TopicEvent<LiveEnvelope>> => {
+      let position = cursorSequence(options.after ?? cursorAt(0));
+      return (async function* () {
+        while (!options.signal?.aborted) {
+          checkGap(position);
+          for (const event of events.filter((event) => event.sequence > position)) {
+            position = event.sequence;
+            yield event;
+          }
+          // Publication during a yielded batch must not be lost before we wait.
+          if (sequence > position) continue;
+          await new Promise<void>((resolve) => {
+            const wake = () => {
+              wakes.delete(wake);
+              options.signal?.removeEventListener("abort", wake);
+              resolve();
+            };
+            wakes.add(wake);
+            options.signal?.addEventListener("abort", wake, { once: true });
+            if (options.signal?.aborted) wake();
+          });
+        }
+      })();
+    },
+  } satisfies LiveTopic & { publish(data: LiveEnvelope): void; trim(count: number): void };
+};

package/src/server/index.ts

@@ -1,4 +1,5 @@
 export { buildMetadata } from "../_internal/build-metadata";
+export { loadPendingApprovals } from "../api/approvals-loader";
 export { expectUserBackedActor, getUserBackedActor, isAppSessionActor, userFromActor } from "./actor";
 export type { ApiErrorBody, ApiErrorResponse, ApiErrorStatus } from "./api";
 export { api, respond, respondMessage } from "./api";
@@ -39,6 +40,7 @@ export {
   validator,
 } from "./middleware";
 export { RateLimitError, type RateLimiter, type RateLimiterConfig, type RateLimitResult, ratelimit } from "./ratelimit";
+export { REQUEST_IDLE_TIMEOUT_MAX_SECONDS, REQUEST_IDLE_TIMEOUT_SECONDS, setRequestTimeout } from "./request-timeout";
 export type {
   AccessEntry,
   AccessPrincipalColumns,

package/src/server/middleware/auth.ts

@@ -1,7 +1,15 @@
 import type { Context } from "hono";
 import { createMiddleware } from "hono/factory";
 import { measureServerPhase } from "../../_internal/server-timing";
-import type { MessageResponse, Role, RoleOrSpecial, User, UserProfile, UserProvider } from "../../contracts/shared";
+import {
+  AI_INFERENCE_SCOPE,
+  type MessageResponse,
+  type Role,
+  type RoleOrSpecial,
+  type User,
+  type UserProfile,
+  type UserProvider,
+} from "../../contracts/shared";
 import { isAccountExpired } from "../../services/account-model";
 import { isReservedWorkloadApiCredential } from "../../services/identity/workload-auth";
 import { oauthTokens } from "../../services/oauth-tokens";
@@ -161,6 +169,8 @@ const loadAuthenticatedActorUncached = async (
     // App workload keys enter only through Core's dedicated broker/authority
     // handlers, which authenticate their exact app binding directly.
     if (isReservedWorkloadApiCredential(authResult)) return { token: null, user: null, actor: null };
+    // Restrict by rejection: a forgotten route check makes a models-only key work nowhere, never grants full access.
+    if (authResult.credential.scopes.includes(AI_INFERENCE_SCOPE)) return { token: null, user: null, actor: null };
     if (authResult.delegatedUser && isAccountExpired(authResult.delegatedUser.accountExpires)) {
       return { token: null, user: null, actor: null };
     }

package/src/server/request-timeout.ts

@@ -0,0 +1,22 @@
+import type { Context } from "hono";
+
+/** Idle timeout of every Cloud app server and the gateway: Bun's default, kept explicit. */
+export const REQUEST_IDLE_TIMEOUT_SECONDS = 10;
+/**
+ * Longest a request may stay silent; the gateway waits this long for an app's response headers.
+ * Stays below Bun's 255-second limit with headroom for the gateway's coarse upstream timer.
+ */
+export const REQUEST_IDLE_TIMEOUT_MAX_SECONDS = 240;
+
+/**
+ * Restart this request's bounded idle timer while waiting to answer.
+ * Bun retains the raised timeout on the keep-alive socket after the response,
+ * so restore REQUEST_IDLE_TIMEOUT_SECONDS once the handler starts answering.
+ */
+export const setRequestTimeout = (c: Context, seconds: number): void => {
+  if (!Number.isInteger(seconds) || seconds < 1 || seconds > REQUEST_IDLE_TIMEOUT_MAX_SECONDS)
+    throw new RangeError(`Request idle timeout must be an integer between 1 and ${REQUEST_IDLE_TIMEOUT_MAX_SECONDS} seconds`);
+  const server: unknown = c.env;
+  if (typeof server === "object" && server !== null && "timeout" in server && typeof server.timeout === "function")
+    server.timeout(c.req.raw, seconds);
+};

package/src/server/services/access.ts

@@ -438,12 +438,13 @@ const uuidArrayWithNulls = (values: readonly (string | null)[]): string => `{${v
  * channel's `authorize`.
  */
 export const getEffectivePermissions = async (params: {
-  accessIds: string[];
+  /** Grant IDs, or a subquery selecting one uuid column from the resource's junction table. */
+  accessIds: string[] | SQLQuery;
   subjects: readonly AccessSubject[];
 }): Promise<PermissionLevel[]> => {
   const { accessIds, subjects } = params;
   if (subjects.length === 0) return [];
-  if (accessIds.length === 0) return subjects.map(() => "none");
+  if (Array.isArray(accessIds) && accessIds.length === 0) return subjects.map(() => "none");
   const userIds = subjects.map((subject) => (subject.type === "user" ? subject.userId : null));
   const serviceAccountIds = subjects.map((subject) => (subject.type === "service_account" ? subject.serviceAccountId : null));
   // The tiers of buildAccessPrincipalTierConditions, evaluated per row of `s`; every subject here is authenticated.
@@ -451,7 +452,7 @@ export const getEffectivePermissions = async (params: {
     SELECT s.position::int AS position, (
       SELECT a.permission
       FROM auth.access a
-      WHERE a.id = ANY(${toPgUuidArray(accessIds)}::uuid[])
+      WHERE ${Array.isArray(accessIds) ? sql`a.id = ANY(${toPgUuidArray(accessIds)}::uuid[])` : sql`a.id IN (${accessIds})`}
         AND (
           a.service_account_id = s.service_account_id
           OR a.user_id = s.user_id

package/src/services/app-approval.ts

@@ -3,8 +3,11 @@ import { lazySync } from "../_internal/process-sync";
 import { env } from "../config/env";
 import { type AccountCategory, accountCategory } from "../contracts/account-categories";
 import {
+  APP_APPROVAL_FEATURES,
   APP_APPROVAL_PATH,
   APP_APPROVAL_PROTOCOL,
+  type AppActionSummary,
+  type AppActionView,
   type AppDevicePublicKey,
   AppDevicePublicKeySchema,
   type AppDeviceRequest,
@@ -147,8 +150,28 @@ export type AppLoginDecisionHints = {
   /** Settles on the first hint for this request, or when `signal` aborts. */
   wait(requestId: string, signal: AbortSignal): Promise<void>;
 };
+/** Open Action approvals of a device's account, as the device shows and decides them. */
+export type AppDeviceActions = {
+  inbox(input: { userId: string; issuer: string }): Promise<{ actions: AppActionSummary[]; moreActions: number }>;
+  view(input: { userId: string; issuer: string; actionId: string }): Promise<AppActionView | null>;
+  /** True when this decision applied; false when the request is gone, decided, expired, or its view changed. */
+  decide(input: {
+    userId: string;
+    deviceId: string;
+    issuer: string;
+    actionId: string;
+    digest: string;
+    approved: boolean;
+  }): Promise<boolean>;
+};
+// Bundle Action wake-ups for 30 seconds while the previously woken request is still open.
+// Cloud Login gives Actions a separate 30-per-token budget in five minutes, preserving the full sign-in budget.
+const ACTION_WAKE_SECONDS = 30;
 /** Best-effort sign-in wake-ups through the trusted authenticator; returns the HTTP status. */
-export type AppLoginPushSender = (appOrigin: string, body: { token: string; cloudOrigin: string; requestRef: string }) => Promise<number>;
+export type AppLoginPushSender = (
+  appOrigin: string,
+  body: { token: string; cloudOrigin: string; requestRef: string; kind?: "action" },
+) => Promise<number>;
 export const fetchPushSender: AppLoginPushSender = async (appOrigin, body) => {
   const response = await fetch(`${appOrigin}/push/notify`, {
     method: "POST",
@@ -265,6 +288,36 @@ export const createAppApprovalService = (
   return {
     config,
     cleanup,
+    wakeForAction: async (approvalId: string): Promise<void> => {
+      try {
+        const cfg = await config(false);
+        if (!cfg.enabled || !cfg.appOrigin) return;
+        const rows = await db<{ push_token: string; user_id: string }[]>`
+          UPDATE auth.app_devices d SET action_wake_at=now(), action_wake_ref=${approvalId}::uuid
+          WHERE d.id IN (
+            SELECT device.id FROM auth.app_devices device JOIN approvals.requests r ON r.approver_user_id=device.user_id
+            WHERE r.id=${approvalId}::uuid AND r.status='pending' AND r.expires_at > now()
+              AND EXISTS (SELECT 1 FROM ai.pending_actions p JOIN ai.turns t ON t.id=p.turn_id
+                WHERE p.approval_id=r.id AND p.status='pending' AND t.run_config->>'signedInSession' IS NULL)
+              AND device.issuer=${cfg.issuer} AND device.revoked_at IS NULL AND device.push_token IS NOT NULL
+              AND device.actions_at IS NOT NULL
+            LIMIT ${limits.devicesPerAccount}
+          ) AND (d.action_wake_at IS NULL OR d.action_wake_at <= now() - ${ACTION_WAKE_SECONDS} * interval '1 second'
+            OR NOT EXISTS (SELECT 1 FROM approvals.requests w
+              WHERE w.id=d.action_wake_ref AND w.status='pending' AND w.expires_at > now()))
+          RETURNING d.push_token,d.user_id`;
+        const tokens = new Map(rows.map((row) => [row.push_token, row.user_id]));
+        await Promise.all(
+          Array.from(tokens, async ([token, userId]) => {
+            const status = await push(cfg.appOrigin, { token, cloudOrigin: cfg.issuer, requestRef: approvalId, kind: "action" });
+            if (status === 410)
+              await db`UPDATE auth.app_devices SET push_token=NULL WHERE issuer=${cfg.issuer} AND user_id=${userId}::uuid AND push_token=${token}`;
+          }),
+        );
+      } catch (error) {
+        log.warn("App action push wake-up failed", { error: error instanceof Error ? error.name : "UnknownError" });
+      }
+    },
     maintain: async (notify: (notice: AppDeviceEnrollmentNotice) => Promise<unknown>, signal?: AbortSignal) => {
       await cleanup();
       const rows = await db<(DeviceRow & { has_email: boolean })[]>`
@@ -289,6 +342,7 @@ export const createAppApprovalService = (
         api: cfg.issuer + APP_APPROVAL_PATH,
         appOrigin: cfg.appOrigin,
         algorithm: "ES256",
+        features: [...APP_APPROVAL_FEATURES],
         limits,
       };
     },
@@ -478,7 +532,7 @@ export const createAppApprovalService = (
       if (owner) void wake(cfg, owner, id);
       return { requestId: id, browserSecret, comparison: code, expiresAt: iso(expiresAt), pollAfterSeconds: limits.pollSeconds };
     },
-    deviceCommand: async (request: AppDeviceRequest) => {
+    deviceCommand: async (request: AppDeviceRequest, actions: AppDeviceActions) => {
       const cfg = await config();
       const { proof, signature } = request;
       const now = Math.floor(Date.now() / 1000);
@@ -521,23 +575,27 @@ export const createAppApprovalService = (
           await record(tx, "device.revoke", device.user_id, device.id);
           return { state: "revoked" as const };
         }
-        if (command.operation === "pending") {
+        if (command.operation === "action" || command.operation === "act")
+          return { operation: command.operation, userId: device.user_id, deviceId: device.id };
+        if (command.operation === "pending" || command.operation === "inbox") {
           const user = await eligible(tx, device.user_id);
           const rows = await tx<
             LoginRow[]
           >`SELECT * FROM auth.app_logins WHERE issuer=${cfg.issuer} AND user_id=${device.user_id}::uuid AND state='pending' AND expires_at>now() AND auth_epoch=${user.auth_epoch} AND category=${accountCategory(user)} ORDER BY created_at LIMIT ${limits.pendingPerAccount}`;
-          return {
-            requests: rows.map(
-              (row): AppPendingLogin => ({
-                requestId: row.id,
-                challenge: row.challenge,
-                comparison: row.comparison,
-                createdAt: iso(row.created_at),
-                expiresAt: iso(row.expires_at),
-              }),
-            ),
-            pollAfterSeconds: limits.pollSeconds,
-          };
+          const requests = rows.map(
+            (row): AppPendingLogin => ({
+              requestId: row.id,
+              challenge: row.challenge,
+              comparison: row.comparison,
+              createdAt: iso(row.created_at),
+              expiresAt: iso(row.expires_at),
+            }),
+          );
+          if (command.operation === "inbox") {
+            await tx`UPDATE auth.app_devices SET actions_at=now() WHERE id=${device.id}::uuid`;
+            return { operation: "inbox" as const, userId: device.user_id, logins: requests };
+          }
+          return { requests, pollAfterSeconds: limits.pollSeconds };
         }
         const [row] = await tx<
           LoginRow[]
@@ -558,6 +616,36 @@ export const createAppApprovalService = (
         await record(tx, `login.${command.decision}`, device.user_id, device.id, { requestId: row.id });
         return { state };
       });
+      if (outcome.operation !== undefined) {
+        const command = proof.command;
+        const input = { userId: outcome.userId, issuer: cfg.issuer };
+        if (outcome.operation === "inbox") {
+          const inbox = { logins: outcome.logins, ...(await actions.inbox(input)), pollAfterSeconds: limits.pollSeconds };
+          // Multibyte summaries share the unchanged response budget with pending sign-ins.
+          while (inbox.actions.length && new TextEncoder().encode(JSON.stringify(inbox)).length > limits.bodyBytes) {
+            inbox.actions.pop();
+            inbox.moreActions++;
+          }
+          return inbox;
+        }
+        if (command.operation === "action") {
+          const view = await actions.view({ ...input, actionId: command.actionId });
+          return view ?? reject("CONFLICT", 409);
+        }
+        if (command.operation === "act") {
+          const approved = command.decision === "approve";
+          const applied = await actions.decide({
+            ...input,
+            deviceId: outcome.deviceId,
+            actionId: command.actionId,
+            digest: command.digest,
+            approved,
+          });
+          if (!applied) return reject("CONFLICT", 409);
+          return { state: approved ? ("approved" as const) : ("denied" as const) };
+        }
+        return reject("INVALID_REQUEST", 400);
+      }
       // Only after commit: the waiting browser re-reads Postgres, so a hint never grants anything.
       if (proof.command.operation === "decide") hints.publish(proof.command.requestId);
       return outcome;

package/src/services/approvals/cursor.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+
+const CursorSchema = z.object({ createdAt: z.iso.datetime(), id: z.uuid() }).strict();
+type ApprovalCursor = z.infer<typeof CursorSchema>;
+
+export const encodeApprovalCursor = (cursor: ApprovalCursor): string => Buffer.from(JSON.stringify(cursor)).toString("base64url");
+export const decodeApprovalCursor = (cursor: string): ApprovalCursor | null => {
+  try {
+    if (!/^[A-Za-z0-9_-]{1,200}$/.test(cursor)) return null;
+    const parsed = CursorSchema.safeParse(JSON.parse(Buffer.from(cursor, "base64url").toString()));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+};