@k2b/cloud 0.40.0 → 0.42.0

package/src/capabilities/client.ts

@@ -2,8 +2,13 @@ import { z } from "zod";
 import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
   CAPABILITY_MAX_CATALOG_BYTES,
+  CAPABILITY_MAX_REVIEW_CONTENT_BYTES,
+  CAPABILITY_MAX_REVIEW_RESPONSE_BYTES,
   CapabilityActionReviewDataSchema,
   CapabilityCatalogSchema,
+  type CapabilityReviewContentRef,
+  CapabilityReviewContentRefSchema,
+  CapabilityReviewContentSchema,
   capabilityResultSchema,
 } from "../contracts/capabilities";
 import { capabilityMessages } from "../shared/capability-messages";
@@ -142,7 +147,29 @@ export const reviewCapabilityAction = async <TInput = unknown>(
       body: JSON.stringify({ input: invocation.input }),
       signal: invocation.signal,
     });
-    return readCapabilityResponse(response, CapabilityActionReviewDataSchema);
+    return await readCapabilityResponse(
+      response,
+      CapabilityActionReviewDataSchema,
+      CAPABILITY_MAX_REVIEW_RESPONSE_BYTES,
+      invocation.signal,
+    );
+  } catch (cause) {
+    return unavailable(cause, undefined, clientLocale(options.headers));
+  }
+};
+
+/** Load exactly one stored snapshot using the caller's normal Cloud authentication. A locator grants no access. */
+export const readCapabilityReviewContent = async (
+  reference: CapabilityReviewContentRef,
+  options: CapabilityHttpOptions & { signal?: AbortSignal } = {},
+) => {
+  try {
+    const ref = CapabilityReviewContentRefSchema.parse(reference);
+    const response = await (options.fetch ?? globalThis.fetch)(
+      requestUrl(options.baseUrl ?? "/api", `${ref.href.slice(4)}?digest=${encodeURIComponent(ref.digest)}`),
+      { headers: options.headers, credentials: "same-origin", cache: "no-store", signal: options.signal },
+    );
+    return await readCapabilityResponse(response, CapabilityReviewContentSchema, CAPABILITY_MAX_REVIEW_CONTENT_BYTES, options.signal);
   } catch (cause) {
     return unavailable(cause, undefined, clientLocale(options.headers));
   }

package/src/capabilities/executions.ts

@@ -1,5 +1,7 @@
 import { sql } from "bun";
+import { createCapabilityDeadline } from "../_internal/capability-timeout";
 import type { CapabilityOrigin } from "../contracts/capabilities";
+import { REQUEST_IDLE_TIMEOUT_SECONDS } from "../server/request-timeout";
 import { pruneApprovalRequests } from "../services/approvals";
 import { logger } from "../services/logging";
 import { CAPABILITY_CLAIM_RETENTION_HOURS, pruneCapabilityIdempotencyClaims } from "./claims";
@@ -101,7 +103,17 @@ export type CapabilityExecution = {
 /** Insert one execution record. Called only by the capability dispatcher and the surfaces that deny before it. */
 export const recordCapabilityExecution = async (input: CapabilityExecutionInput): Promise<string> => {
   const durationMs = Math.max(0, Math.round(input.completedAt.getTime() - input.startedAt.getTime()));
-  const [row] = await sql<{ id: string }[]>`
+  // An observational write has its own transport-headroom budget, even when
+  // the invocation already expired. Do not hold its caller on a dead database.
+  const deadline = createCapabilityDeadline(REQUEST_IDLE_TIMEOUT_SECONDS * 1000, new AbortController().signal);
+  try {
+    return await deadline.wait(() =>
+      sql.begin(async (db) => {
+        // A connection obtained after the deadline must never start the insert.
+        deadline.check();
+        await db`SELECT set_config('statement_timeout', ${`${deadline.remainingMs()}ms`}, true)`;
+        deadline.check();
+        const [row] = await db<{ id: string }[]>`
     INSERT INTO capabilities.executions (
       request_id, origin, app_id, capability, kind, destructive,
       actor_kind, actor_id, user_id, access_subject_type, access_subject_id,
@@ -117,8 +129,15 @@ export const recordCapabilityExecution = async (input: CapabilityExecutionInput)
       ${input.idempotencyKey ?? null}, ${input.replayed ?? false}, ${input.startedAt}, ${input.completedAt}, ${durationMs}
     )
     RETURNING id::text AS id
-  `;
-  return row!.id;
+        `;
+        // Roll back a late result rather than commit an abandoned transaction.
+        deadline.check();
+        return row!.id;
+      }),
+    );
+  } finally {
+    deadline.clear();
+  }
 };
 
 export type CapabilityExecutionFilter = {

package/src/capabilities/geo-client.ts

@@ -0,0 +1,57 @@
+import type { z } from "zod";
+import { geoContract } from "../contracts/geo";
+import { geoMapContract } from "../contracts/geo-map";
+import { geoRouteContract } from "../contracts/geo-route";
+import { type CapabilityCaller, invokeCapabilityWithDataSchema } from "./server";
+
+/** Calls Core using the caller's interactive identity, invocation transport, or durable mandate. */
+export const geoClient = {
+  mapStyle: (input: z.input<typeof geoMapContract.style.input>, caller: CapabilityCaller) =>
+    invokeCapabilityWithDataSchema(
+      { kind: "query", appId: "core", capabilityId: geoMapContract.style.id, input },
+      geoMapContract.style.data,
+      caller,
+    ),
+  calculateRoute: (input: z.input<typeof geoRouteContract.calculateRoute.input>, caller: CapabilityCaller) =>
+    invokeCapabilityWithDataSchema(
+      { kind: "query", appId: "core", capabilityId: geoRouteContract.calculateRoute.id, input },
+      geoRouteContract.calculateRoute.data,
+      caller,
+    ),
+  updateRoute: (input: z.input<typeof geoRouteContract.updateRoute.input>, caller: CapabilityCaller) =>
+    invokeCapabilityWithDataSchema(
+      { kind: "query", appId: "core", capabilityId: geoRouteContract.updateRoute.id, input },
+      geoRouteContract.updateRoute.data,
+      caller,
+    ),
+  autocomplete: (input: z.input<typeof geoContract.autocomplete.input>, caller: CapabilityCaller) =>
+    invokeCapabilityWithDataSchema(
+      { kind: "query", appId: "core", capabilityId: geoContract.autocomplete.id, input },
+      geoContract.autocomplete.data,
+      caller,
+    ),
+  geocode: (input: z.input<typeof geoContract.geocode.input>, caller: CapabilityCaller) =>
+    invokeCapabilityWithDataSchema(
+      { kind: "query", appId: "core", capabilityId: geoContract.geocode.id, input },
+      geoContract.geocode.data,
+      caller,
+    ),
+  reverse: (input: z.input<typeof geoContract.reverse.input>, caller: CapabilityCaller) =>
+    invokeCapabilityWithDataSchema(
+      { kind: "query", appId: "core", capabilityId: geoContract.reverse.id, input },
+      geoContract.reverse.data,
+      caller,
+    ),
+  searchPlaces: (input: z.input<typeof geoContract.searchPlaces.input>, caller: CapabilityCaller) =>
+    invokeCapabilityWithDataSchema(
+      { kind: "query", appId: "core", capabilityId: geoContract.searchPlaces.id, input },
+      geoContract.searchPlaces.data,
+      caller,
+    ),
+  availability: (caller: CapabilityCaller) =>
+    invokeCapabilityWithDataSchema(
+      { kind: "query", appId: "core", capabilityId: geoContract.availability.id, input: {} },
+      geoContract.availability.data,
+      caller,
+    ),
+};

package/src/capabilities/response.ts

@@ -7,8 +7,9 @@ export const readCapabilityResponse = async <T>(
   response: Response,
   schema: z.ZodType<T>,
   maxBytes = CAPABILITY_MAX_RESULT_BYTES,
+  signal?: AbortSignal,
 ): Promise<CapabilityResultState<T>> => {
-  const parsedBody = await readBoundedJson(response, maxBytes);
+  const parsedBody = await readBoundedJson(response, maxBytes, signal);
   if (!parsedBody.ok && parsedBody.reason === "too_large") {
     return {
       ok: false,

package/src/capabilities/review-storage.ts

@@ -0,0 +1,24 @@
+import { CapabilityReviewContentSchema } from "../contracts/capabilities";
+
+/** JSONB cannot store NUL or lone UTF-16 surrogates. Nest the content's JSON as
+ * text in the existing snapshot, preserving every code unit and the public digest. */
+export const serializeReviewSnapshot = (review: unknown): string => {
+  if (review && typeof review === "object" && "content" in review && review.content !== undefined)
+    return JSON.stringify({ ...review, content: JSON.stringify(CapabilityReviewContentSchema.parse(review.content)) });
+  return JSON.stringify(review);
+};
+
+export const parseStoredReviewContent = (value: unknown) => {
+  try {
+    return CapabilityReviewContentSchema.safeParse(typeof value === "string" ? JSON.parse(value) : value);
+  } catch {
+    return CapabilityReviewContentSchema.safeParse(null);
+  }
+};
+
+export const restoreReviewSnapshot = (review: unknown): unknown => {
+  if (!review || typeof review !== "object" || !("content" in review)) return review;
+  const content = parseStoredReviewContent(review.content);
+  // Invalid stored content must fail validation, never become a content-free review.
+  return { ...review, content: content.success ? content.data : null };
+};

package/src/capabilities/reviews.ts

@@ -14,10 +14,11 @@ export const capabilityPreviewIssues = (
   preview: CapabilityPreview | undefined,
   links: readonly CapabilitySemanticLink[] | undefined,
   sends = false,
+  completeContent = false,
 ): string[] => {
   if (!preview) return [];
   const issues: string[] = [];
-  const open = links?.some((link) => link.rel === "open");
+  const open = completeContent || links?.some((link) => link.rel === "open");
   if ("truncated" in preview && preview.truncated && !open) issues.push("A truncated preview requires an open link");
   if (preview.kind === "message") {
     if ((Object.values(preview.more ?? {}).some((count) => count > 0) || (preview.moreAttachments ?? 0) > 0) && !open)
@@ -33,9 +34,22 @@ export const capabilityReviewFormIssues = (review: CapabilityActionCallReview):
   for (const form of ["confirm", "decline"] as const)
     if (Array.from(capabilityReviewSentence(review, form, { timeZone: "UTC" })).length > 40)
       issues.push(`${form} exceeds 40 rendered characters`);
-  issues.push(...capabilityPreviewIssues(review.preview, review.links, review.ask === "sends"));
+  issues.push(...capabilityPreviewIssues(review.preview, review.links, review.ask === "sends", Boolean(review.content)));
+  if (
+    review.content &&
+    review.preview &&
+    review.content.kind !== review.preview.kind &&
+    !(review.content.kind === "message" && review.preview.kind === "page")
+  )
+    issues.push("Full content must have the same kind as its preview");
+  if (review.content?.kind === "message" && review.ask === "sends") {
+    if (!review.content.from) issues.push("Full sends content requires from");
+    if (!review.content.to.length && !review.content.cc?.length && !review.content.bcc?.length)
+      issues.push("Full sends content requires a recipient");
+  }
   try {
-    if (new TextEncoder().encode(JSON.stringify(review)).byteLength > CAPABILITY_MAX_REVIEW_BYTES) issues.push("Review exceeds 32 KiB");
+    const { content: _content, ...compact } = review;
+    if (new TextEncoder().encode(JSON.stringify(compact)).byteLength > CAPABILITY_MAX_REVIEW_BYTES) issues.push("Review exceeds 32 KiB");
   } catch {
     issues.push("Review is not JSON serializable");
   }

package/src/capabilities/server.ts

@@ -6,11 +6,13 @@ import { dispatchCapability, loadCapabilityCatalogPage } from "../api/capabiliti
 import { env } from "../config/env";
 import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
+  CAPABILITY_MAX_REVIEW_RESPONSE_BYTES,
   CapabilityActionReviewDataSchema,
   type CapabilityOrigin,
   capabilityResultSchema,
 } from "../contracts/capabilities";
 import type { RequestAuthority } from "../server";
+import { canUseApp } from "../services/app-access";
 import { get } from "../services/settings";
 import { resolveAppPresentation } from "../shared/app-presentation";
 import { publicCloudOrigin } from "../shared/app-url";
@@ -184,7 +186,7 @@ export const invokeCapabilityWithDataSchema = <TDataSchema extends z.ZodType, TI
 ): Promise<CapabilityClientResult<z.output<TDataSchema>>> => invokeCapabilityWithResultSchema(invocation, dataSchema, caller);
 
 export const listCapabilityCatalog = async (
-  options: { cursor?: string; limit?: number; locale?: string } = {},
+  options: { cursor?: string; limit?: number; locale?: string; authority?: RequestAuthority | null } = {},
 ): Promise<CapabilityCatalogClientResult> => {
   const limit = options.limit ?? 25;
   const messages = capabilityMessages(options.locale);
@@ -197,30 +199,35 @@ export const listCapabilityCatalog = async (
   try {
     return {
       ok: true,
-      data: await loadCapabilityCatalogPage({ cursor: options.cursor, limit }, {}, options.locale),
+      data: await loadCapabilityCatalogPage({ cursor: options.cursor, limit }, {}, options.locale, options.authority ?? null),
     };
   } catch {
     return { ok: false, error: { code: "APP_UNAVAILABLE", message: messages.cloudUnavailable, status: 503 } };
   }
 };
 
-export const getCapabilityCatalogApp = async (appId: string, locale?: string): Promise<CapabilityCatalogAppClientResult> => {
+export const getCapabilityCatalogApp = async (
+  appId: string,
+  locale?: string,
+  authority: RequestAuthority | null = null,
+): Promise<CapabilityCatalogAppClientResult> => {
   try {
     const [capability, registeredApp] = await Promise.all([getCapability(appId), getApp(appId)]);
     const presentedApp = registeredApp && locale ? resolveAppPresentation(registeredApp, locale) : registeredApp;
     return {
       ok: true,
-      data: capability
-        ? {
-            appId: capability.appId,
-            appName: presentedApp?.name ?? capability.appName,
-            appIcon: capability.appIcon,
-            appDescription: presentedApp?.description ?? capability.appDescription,
-            manifest: locale
-              ? resolveCapabilityManifestPresentation(capability.manifest, capability.presentation, locale)
-              : capability.manifest,
-          }
-        : null,
+      data:
+        capability && registeredApp && (await canUseApp(authority, registeredApp))
+          ? {
+              appId: capability.appId,
+              appName: presentedApp?.name ?? capability.appName,
+              appIcon: capability.appIcon,
+              appDescription: presentedApp?.description ?? capability.appDescription,
+              manifest: locale
+                ? resolveCapabilityManifestPresentation(capability.manifest, capability.presentation, locale)
+                : capability.manifest,
+            }
+          : null,
     };
   } catch {
     return { ok: false, error: { code: "APP_UNAVAILABLE", message: capabilityMessages(locale).cloudUnavailable, status: 503 } };
@@ -237,7 +244,10 @@ export const getCapabilityActionWording = async (
   appId: string,
   localId: string,
   locale?: string,
+  authority: RequestAuthority | null = null,
 ): Promise<CapabilityActionWording | null> => {
+  const registeredApp = await getApp(appId);
+  if (!registeredApp || !(await canUseApp(authority, registeredApp))) return null;
   const capability = await getCapability(appId);
   const action = capability?.manifest.actions.find((candidate) => candidate.localId === localId);
   return capability && action ? resolveCapabilityActionWording(action, capability.presentation, locale ?? DEFAULT_LOCALE) : null;
@@ -263,7 +273,12 @@ export const reviewCapabilityAction = async <TInput = unknown>(
         locale: caller.locale ?? undefined,
         origin: caller.origin ?? "app",
       });
-      return readCapabilityResponse(outcome, CapabilityActionReviewDataSchema);
+      return await readCapabilityResponse(
+        outcome,
+        CapabilityActionReviewDataSchema,
+        CAPABILITY_MAX_REVIEW_RESPONSE_BYTES,
+        combineCapabilitySignals(caller.signal, invocation.signal),
+      );
     }
     const response = await (caller.transport ?? fetch)(
       new Request(
@@ -276,7 +291,12 @@ export const reviewCapabilityAction = async <TInput = unknown>(
         { body: JSON.stringify({ input: invocation.input }) },
       ),
     );
-    return readCapabilityResponse(response, CapabilityActionReviewDataSchema);
+    return await readCapabilityResponse(
+      response,
+      CapabilityActionReviewDataSchema,
+      CAPABILITY_MAX_REVIEW_RESPONSE_BYTES,
+      combineCapabilitySignals(caller.signal, invocation.signal),
+    );
   } catch (cause) {
     return unavailable(cause, undefined, caller.locale ?? undefined);
   }

package/src/cli/access.ts

@@ -1,3 +1,4 @@
+import { principalLabel } from "../access/principal-label";
 import type { AccessEntry, EntityListItem, PermissionLevel, Principal } from "../contracts";
 import { arg, command, confirmFlag, flag, paginationFlags } from "./commands";
 import type { CloudCliContext, CloudCliTableColumn } from "./index";
@@ -120,21 +121,7 @@ const principalKey = (principal: Principal): string => {
   }
 };
 
-const entryDisplayName = (entry: AccessEntry): string => {
-  if (entry.displayName) return entry.displayName;
-  switch (entry.principal.type) {
-    case "user":
-      return entry.principal.userId;
-    case "group":
-      return entry.principal.groupId;
-    case "service_account":
-      return entry.principal.serviceAccountId;
-    case "authenticated":
-      return "All users (incl. guests)";
-    case "public":
-      return "Public";
-  }
-};
+const entryDisplayName = (entry: AccessEntry, locale?: string): string => principalLabel(entry, locale);
 
 const formatEntityCandidate = (item: EntityListItem): string => {
   if (item.kind === "user") return `${item.user.displayName} (${item.user.uid}${item.user.mail ? `, ${item.user.mail}` : ""})`;
@@ -257,17 +244,20 @@ const entryTypeLabel = (entry: AccessEntry): string => {
 };
 
 // Resource-bound service accounts back resource API keys, which are managed with those keys.
-const accessRows = (entries: AccessEntry[], options: { includeServiceAccounts?: boolean; scopes?: readonly string[] } = {}) =>
+const accessRows = (
+  entries: AccessEntry[],
+  options: { includeServiceAccounts?: boolean; scopes?: readonly string[]; locale?: string } = {},
+) =>
   entries
     .filter((entry) => options.includeServiceAccounts || entry.serviceAccountKind !== "resource_bound")
     .sort((a, b) => {
       const rank = permissionRank(b.permission) - permissionRank(a.permission);
       if (rank !== 0) return rank;
-      return entryDisplayName(a).localeCompare(entryDisplayName(b));
+      return entryDisplayName(a, options.locale).localeCompare(entryDisplayName(b, options.locale));
     })
     .map((entry) => ({
       accessId: entry.id,
-      principal: entryDisplayName(entry),
+      principal: entryDisplayName(entry, options.locale),
       type: entryTypeLabel(entry),
       permission: entry.permission,
       ...(options.scopes ? { scope: entry.scope ?? options.scopes[0] } : {}),
@@ -287,7 +277,7 @@ export const printAccessEntries = (
   options: { includeServiceAccounts?: boolean; jsonValue?: unknown; scopes?: readonly string[] } = {},
 ) => {
   if (printStructured(ctx, options.jsonValue ?? entries)) return;
-  const rows = accessRows(entries, options);
+  const rows = accessRows(entries, { ...options, locale: ctx.options.locale });
   if (rows.length === 0) {
     ctx.print("No direct grants.");
     return;
@@ -426,7 +416,7 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
       const principal = await resolveAccessPrincipal(ctx, flags as PrincipalFlags, adapter);
       const entry = await adapter.grant(ctx, resource, principal, permission, scope);
       if (!printStructured(ctx, { resource, entry }))
-        ctx.print(`Granted ${permission}${scopeSuffix(scope)} on ${resource.label} to ${entryDisplayName(entry)}.`);
+        ctx.print(`Granted ${permission}${scopeSuffix(scope)} on ${resource.label} to ${entryDisplayName(entry, ctx.options.locale)}.`);
     },
   });
 
@@ -462,13 +452,15 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
       if (existing) {
         await adapter.update(ctx, resource, existing.id, permission, scope);
         if (!printStructured(ctx, { resource, accessId: existing.id, permission, scope, action: "updated" })) {
-          ctx.print(`Updated ${entryDisplayName(existing)} to ${permission}${scopeSuffix(scope)} on ${resource.label}.`);
+          ctx.print(
+            `Updated ${entryDisplayName(existing, ctx.options.locale)} to ${permission}${scopeSuffix(scope)} on ${resource.label}.`,
+          );
         }
         return;
       }
       const entry = await adapter.grant(ctx, resource, principal, permission, scope);
       if (!printStructured(ctx, { resource, entry, action: "created" })) {
-        ctx.print(`Granted ${permission}${scopeSuffix(scope)} on ${resource.label} to ${entryDisplayName(entry)}.`);
+        ctx.print(`Granted ${permission}${scopeSuffix(scope)} on ${resource.label} to ${entryDisplayName(entry, ctx.options.locale)}.`);
       }
     },
   });
@@ -496,7 +488,7 @@ export const createAccessCommands = <TResource extends AccessResource>(adapter:
         const entry = entries.find((candidate) => principalKey(candidate.principal) === principalKey(principal));
         if (!entry) throw new Error("No direct grant for that principal.");
         accessId = entry.id;
-        label = entryDisplayName(entry);
+        label = entryDisplayName(entry, ctx.options.locale);
       } else if (principalFlagCount(flags as PrincipalFlags) > 0) {
         throw new Error("Pass either --access-id or one principal flag, not both.");
       }

package/src/cli/admin/linux.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import { type LinuxIdentityConfiguration, LinuxIdentityConfigurationSchema } from "../../contracts/posix";
 import { cliText, command, confirmFlag, flag, printStructured, readCliInput } from "../index";
 import { apiGet, apiJson, queryString } from "./shared";
@@ -31,6 +32,10 @@ export const linuxCommands = [
     flags: {
       config: flag.input({ required: true, description: "Configuration JSON: --config, --config-file, or --stdin" }),
       rangeReserved: flag.boolean({ name: "range-reserved", description: "Confirm the range is reserved across all connected systems" }),
+      replaceUnreadable: flag.boolean({
+        name: "replace-unreadable",
+        description: "Explicitly replace an unreadable stored Linux configuration",
+      }),
       yes: confirmFlag("Confirm replacing Linux identity configuration"),
     },
     async run({ ctx, flags }) {
@@ -40,7 +45,9 @@ export const linuxCommands = [
         );
       const input = await readCliInput(flags.config, { label: "Linux configuration", required: true });
       if (input === undefined) throw new Error("Missing Linux configuration.");
-      const config = LinuxIdentityConfigurationSchema.parse(JSON.parse(input));
+      const { unreadable: _unreadable, ...config } = LinuxIdentityConfigurationSchema.safeExtend({
+        unreadable: z.boolean().optional(),
+      }).parse(JSON.parse(input));
       if (config.enabled && !flags.rangeReserved)
         throw new Error(
           cliText(ctx, {
@@ -48,7 +55,11 @@ export const linuxCommands = [
             de: "Zum Aktivieren ist --range-reserved erforderlich.",
           }),
         );
-      const result = await apiJson<unknown>(ctx, "PUT", `${path}/configuration`, { config, rangeReserved: flags.rangeReserved });
+      const result = await apiJson<unknown>(ctx, "PUT", `${path}/configuration`, {
+        config,
+        rangeReserved: flags.rangeReserved,
+        ...(flags.replaceUnreadable ? { replaceUnreadable: true } : {}),
+      });
       if (!printStructured(ctx, result)) ctx.print(JSON.stringify(result, null, 2));
     },
   }),

package/src/cli/admin/outgoing-mail.ts

@@ -35,13 +35,25 @@ export const outgoingMailCommands = [
     flags: {
       contentDays: flag.string({ required: true, description: "Content retention in days" }),
       recordDays: flag.string({ required: true, description: "Record retention in days (at least content retention)" }),
+      replaceContent: flag.boolean({ name: "replace-unreadable-content", description: "Explicitly replace unreadable content retention" }),
+      replaceRecords: flag.boolean({ name: "replace-unreadable-records", description: "Explicitly replace unreadable record retention" }),
       yes: confirmFlag("Confirm changing outgoing mail retention"),
     },
     async run({ ctx, flags }) {
       confirmed(flags.yes);
       const retention = MailRetentionSchema.parse({ contentDays: Number(flags.contentDays), recordDays: Number(flags.recordDays) });
       if (retention.recordDays < retention.contentDays) throw new Error("Record retention must be at least content retention.");
-      const result = await apiJson<MailRetention>(ctx, "PUT", `${root}/retention`, retention);
+      const result = await apiJson<MailRetention>(ctx, "PUT", `${root}/retention`, {
+        ...retention,
+        ...(flags.replaceContent || flags.replaceRecords
+          ? {
+              replaceUnreadable: [
+                ...(flags.replaceContent ? ["outgoing_mail.content_retention_days"] : []),
+                ...(flags.replaceRecords ? ["outgoing_mail.record_retention_days"] : []),
+              ],
+            }
+          : {}),
+      });
       if (!printStructured(ctx, result)) print(ctx, result);
     },
   }),
@@ -183,7 +195,12 @@ export const outgoingMailCommands = [
       printJsonOrTable(
         ctx,
         result,
-        result.items.map((app) => ({ ...app, reads: app.readDeclared, profiles: app.profiles.join(","), logApps: app.logApps.join(",") })),
+        result.items.map((app) => ({
+          ...app,
+          reads: app.readDeclared,
+          profiles: app.profiles.join(","),
+          logApps: app.logApps.map((id) => `${id}:${app.logContentApps?.includes(id) ? "content" : "metadata"}`).join(","),
+        })),
         [
           { key: "appId" },
           { key: "name" },
@@ -226,15 +243,20 @@ export const outgoingMailCommands = [
     summary: "Choose which other applications' mail logs an app may read",
     args: { app: arg.required({ valueLabel: "app" }) },
     flags: {
-      apps: flag.string({ description: "Comma-separated source application IDs" }),
+      apps: flag.string({ description: "Comma-separated source application IDs (replaces all grants)" }),
+      contentApps: flag.string({ description: "Subset of --apps allowed to read text and attachment names" }),
       ownOnly: flag.boolean({ description: "Remove all other application log grants" }),
       yes: confirmFlag("Confirm application mail log access change"),
     },
     async run({ ctx, args, flags }) {
       confirmed(flags.yes);
       if ((flags.apps !== undefined) === !!flags.ownOnly) throw new Error("Choose exactly one of --apps or --own-only.");
+      if (flags.contentApps !== undefined && flags.apps === undefined) throw new Error("--content-apps requires --apps.");
       const reader = MailLogAppIdSchema.safeParse(args.app);
-      const value = MailLogAccessSchema.safeParse({ apps: flags.apps?.split(",").map((app) => app.trim()) ?? [] });
+      const value = MailLogAccessSchema.safeParse({
+        apps: flags.apps?.split(",").map((app) => app.trim()) ?? [],
+        ...(flags.contentApps !== undefined ? { contentApps: flags.contentApps.split(",").map((app) => app.trim()) } : {}),
+      });
       if (!reader.success || args.app === "core" || !value.success || value.data.apps.includes(args.app))
         throw new Error("Choose a valid reader and distinct source apps other than Core or the reader itself.");
       print(ctx, await apiJson(ctx, "PUT", `${root}/apps/${encodeURIComponent(args.app)}/log-access`, value.data));

package/src/cli/capabilities.ts

@@ -4,6 +4,8 @@ import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
   CAPABILITY_MAX_CATALOG_BYTES,
   CAPABILITY_MAX_RESULT_BYTES,
+  CAPABILITY_MAX_REVIEW_RESPONSE_BYTES,
+  CapabilityActionReviewDataSchema,
   CapabilityCatalogSchema,
   CapabilityErrorSchema,
   type CapabilityManifest,
@@ -295,6 +297,23 @@ export default defineCliCommands({
         await invoke({ ctx, kind: "queries", appId, capabilityId: reader.localId, inputValue: { id: ref.id }, manifest: app.manifest });
       },
     }),
+    command("review", {
+      summary: "Read the complete proposed Action without executing it",
+      args: { appId: arg.required({ description: "Owning app id" }), actionId: arg.required({ description: "App-local action id" }) },
+      flags: { input: flag.input({ required: true, description: "Strict JSON input; supports --input-file or --stdin" }) },
+      run: async ({ ctx, args, flags }) => {
+        const response = await ctx.fetch(
+          `/api/capabilities/v1/actions/${encodeURIComponent(args.appId)}/${encodeURIComponent(args.actionId)}/review`,
+          {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ input: await parseInput(flags.input) }),
+          },
+        );
+        const review = CapabilityActionReviewDataSchema.parse(await readCapabilityJson(response, CAPABILITY_MAX_REVIEW_RESPONSE_BYTES));
+        printGenericResult(ctx, review);
+      },
+    }),
     command("action", {
       summary: "Invoke an app mutation",
       args: {

package/src/config/env.ts

@@ -98,12 +98,6 @@ const registry = defineEnv({
     scope: "runtime",
     doc: "Comma-separated host names, IP addresses and CIDR ranges on internal networks allowed for outgoing mail SMTP and bounce IMAP connections; unset allows only public targets, an explicit value replaces this default, and invalid entries including `/0` stop the owning process at startup.",
   },
-  GEO_ALLOWED_TARGETS: {
-    schema: envList,
-    default: ["geo"],
-    scope: "runtime",
-    doc: "Comma-separated host names, IP addresses and CIDR ranges on internal networks allowed for Geo requests; unset allows public targets and `geo`, an explicit value replaces this default, and invalid entries including `/0` stop the owning process at startup.",
-  },
 
   // Identity and OAuth
   CLOUD_IDENTITY_KEY_ENCRYPTION_KEY: {

package/src/contracts/app-access.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import type { RequestAuthority } from "../server/middleware/auth";
+import { type Role, RoleSchema } from "./shared";
+
+const publicRoutes = z
+  .array(
+    z
+      .string()
+      .startsWith("/")
+      .refine((path) => !path.startsWith("//") && !/[?#]/.test(path)),
+  )
+  .readonly()
+  .optional();
+export const FixedAppAccessRuleSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("signedIn") }).strict(),
+  z.object({ kind: z.literal("noGuests") }).strict(),
+  z.object({ kind: z.literal("roles"), roles: z.array(RoleSchema).min(1).readonly() }).strict(),
+]);
+export type FixedAppAccessRule = z.infer<typeof FixedAppAccessRuleSchema>;
+export const AppAccessRuleSchema = z.union([
+  z.object({ kind: z.literal("signedIn"), publicRoutes }).strict(),
+  z.object({ kind: z.literal("noGuests"), publicRoutes }).strict(),
+  z.object({ kind: z.literal("roles"), roles: z.array(RoleSchema).min(1).readonly(), publicRoutes }).strict(),
+  z.object({ kind: z.literal("grants"), until: FixedAppAccessRuleSchema.optional(), publicRoutes }).strict(),
+]);
+/** Serializable entry rule evaluated by the platform; never application callback code. */
+export type AppAccessRule = z.infer<typeof AppAccessRuleSchema>;
+/** The optional management restriction runs in the owning application, in addition to a management grant. */
+export type AppAccessDeclaration = AppAccessRule & {
+  canManage?: (authority: RequestAuthority) => boolean | Promise<boolean>;
+};
+type PublicOptions = { publicRoutes?: readonly string[] };
+export const appAccess = {
+  signedIn: (options: PublicOptions = {}): AppAccessRule & { kind: "signedIn" } => ({ kind: "signedIn", ...options }),
+  noGuests: (options: PublicOptions = {}): AppAccessRule & { kind: "noGuests" } => ({ kind: "noGuests", ...options }),
+  roles: (roles: readonly Role[], options: PublicOptions = {}): AppAccessRule & { kind: "roles" } => ({ kind: "roles", roles, ...options }),
+  grants: (
+    options: PublicOptions & { until?: FixedAppAccessRule; canManage?: AppAccessDeclaration["canManage"] } = {},
+  ): AppAccessDeclaration => ({ kind: "grants", ...options }),
+};
+
+export const compileAppAccess = (declaration: AppAccessDeclaration | undefined): AppAccessRule | undefined => {
+  if (!declaration) return undefined;
+  const { canManage, ...rule } = declaration;
+  if (canManage && (rule.kind !== "grants" || typeof canManage !== "function"))
+    throw new Error("Only configurable app access accepts canManage");
+  return AppAccessRuleSchema.parse(rule);
+};

package/src/contracts/app-approval.ts

@@ -360,14 +360,14 @@ const actionFields = {
   createdAt: DateTime,
   expiresAt: DateTime,
 };
-/** One inbox row. `sentence` is the start of the app's sentence; read the Action for everything the person approves. */
+/** One inbox row. `sentence` is the start of the plain question; 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. */
+    /** The plain Assistant question, in the originating turn's language. */
     sentence: PlainText(APP_ACTION_LIMITS.sentenceChars).min(1),
-    /** The app's review of this call, or `null`. */
+    /** The question's reason line, or `null` for older snapshots. */
     message: PlainText(APP_ACTION_LIMITS.messageChars).nullable(),
     details: z
       .array(