@k2b/cloud 0.47.0 → 0.49.0

package/src/cli/admin/index.ts

@@ -5,7 +5,9 @@
  * them. The groups map to the admin UI areas, so a command and the page that
  * shows the same data stay easy to find together.
  */
+
 import { defineCliCommands } from "../commands";
+import { type CloudCliContext, localizeCloudCliText } from "../index";
 import { accountAdministrationCommands } from "./account-administration";
 import { accountCategoryCommands } from "./account-categories";
 import { agentCommands } from "./agents";
@@ -14,6 +16,7 @@ import { aiQuotaCommands } from "./ai-quotas";
 import { aiSkillCommands } from "./ai-skills";
 import { aiUsageCommands } from "./ai-usage";
 import { appCredentialCommands } from "./app-credentials";
+import { appDomainCommands } from "./app-domains";
 import { appKeyCommands } from "./app-keys";
 import { appSignInCommands } from "./app-sign-in";
 import { dataCommands } from "./data";
@@ -35,91 +38,107 @@ import { telemetryCommands } from "./telemetry";
 import { webhookCommands } from "./webhooks";
 import { workflowCommands } from "./workflows";
 
-export default defineCliCommands({
-  name: "admin",
-  summary: "Inspect and operate Cloud administration surfaces.",
-  groupSummaries: {
-    accounts: "Manage account policy and account administration.",
-    ai: "Manage AI models, quotas, Skills, and usage.",
-    "ai models": "Manage AI model configuration.",
-    "ai providers": "Manage AI provider connections.",
-    "ai variants": "Manage named model variants.",
-    "ai classes": "Manage model classes and tools.",
-    "ai quotas background": "Inspect and release the background emergency stop.",
-    "ai skills": "Inspect Assistant Skills and trusted templates.",
-    "ai usage": "Inspect AI runs and usage facets.",
-    announcements: "Manage platform announcements and banners.",
-    "app-credentials": "Manage per-application credentials for background work.",
-    agents: "Create, list, revoke, and re-key agent accounts with OAuth client credentials, and change their pictures.",
-    "agents avatar": "Show and change an agent's picture: its robot parts or a photo.",
-    "app-sign-in": "Manage app sign-in and pairing.",
-    apps: "Inspect registered apps and manage app keys.",
-    "apps keys": "Create, list, and revoke Ed25519 app keys.",
-    documentation: "Manage the administration documentation website.",
-    geoip: "Replace and inspect sign-in location databases.",
-    jobs: "Inspect background jobs and their runs.",
-    logs: "Search, inspect, and clean up retained logs.",
-    metrics: "Inspect collectors and manage metrics access.",
-    "metrics tokens": "Manage metrics bearer tokens.",
-    nats: "Inspect NATS nodes, streams, and consumers.",
-    "nats consumers": "Inspect NATS consumers.",
-    "nats streams": "Find NATS streams and buckets.",
-    "notification-batches": "Manage account notification batches.",
-    "outgoing-mail": "Manage outgoing mail sender profiles, application access, and the send log.",
-    "outgoing-mail profiles": "Manage outgoing mail sender profiles.",
-    "outgoing-mail apps": "Manage application outgoing mail access.",
-    "outgoing-mail log": "Read and cancel application mail in the send log.",
-    "outgoing-mail retention": "Show or change how long the send log keeps mail.",
-    notifications: "Inspect and resend email notifications.",
-    postgres: "Inspect Postgres diagnostics.",
-    redis: "Inspect Valkey diagnostics.",
-    routes: "Inspect gateway routes.",
-    settings: "Inspect environment migration and change administrator settings.",
-    sync: "Inspect Sync resources, schedules, and dead letters.",
-    "sync dead-letters": "Inspect, replay, requeue, or remove dead letters.",
-    "sync resources": "List Sync resource declarations.",
-    "sync schedules": "Inspect and run Sync schedules.",
-    "sync schedules runs": "Read Sync schedule run results.",
-    telemetry: "Inspect request telemetry.",
-    webhooks: "Manage gateway health webhooks.",
-    workflows: "Inspect and operate workflow runs and effects.",
-    "app-sign-in config": "Manage the trusted app website and pairing policy.",
-    "accounts config": "Manage account types and sign-in visibility.",
-    "accounts administration": "Manage account requests and account/group follow-up notices.",
-    "ai quotas": "Manage direct Assistant chat limits and consumption.",
-    "ai quotas config": "Export and replace quota policies with revision checks.",
-    legal: "Manage Terms, Privacy, and Imprint.",
-    linux: "Prepare Linux identities.",
-    "linux config": "Manage Linux identity defaults and allocation range.",
-  },
-  commands: [
-    ...appCredentialCommands,
-    ...appKeyCommands,
-    ...agentCommands,
-    ...documentationCommands,
-    ...appSignInCommands,
-    ...accountCategoryCommands,
-    ...accountAdministrationCommands,
-    ...aiUsageCommands,
-    ...aiModelCommands,
-    ...aiQuotaCommands,
-    ...aiSkillCommands,
-    ...instanceCommands,
-    ...gatewayCommands,
-    ...logCommands,
-    ...telemetryCommands,
-    ...jobCommands,
-    ...legalCommands,
-    ...geoipCommands,
-    ...linuxCommands,
-    ...workflowCommands,
-    ...dataCommands,
-    ...notificationCommands,
-    ...outgoingMailCommands,
-    ...webhookCommands,
-    ...metricsCommands,
-    ...natsCommands,
-    ...syncCommands,
-    ...settingsCommands,
-  ],
-});
+const build = (locale?: string) =>
+  defineCliCommands({
+    name: "admin",
+    summary: "Inspect and operate Cloud administration surfaces.",
+    groupSummaries: {
+      accounts: "Manage account policy and account administration.",
+      ai: "Manage AI models, quotas, Skills, and usage.",
+      "ai models": "Manage AI model configuration.",
+      "ai providers": "Manage AI provider connections.",
+      "ai variants": "Manage named model variants.",
+      "ai classes": "Manage model classes and tools.",
+      "ai quotas background": "Inspect and release the background emergency stop.",
+      "ai skills": "Inspect Assistant Skills and trusted templates.",
+      "ai usage": "Inspect AI runs and usage facets.",
+      announcements: "Manage platform announcements and banners.",
+      "app-credentials": "Manage per-application credentials for background work.",
+      agents: "Create, list, revoke, and re-key agent accounts with OAuth client credentials, and change their pictures.",
+      "agents avatar": "Show and change an agent's picture: its robot parts or a photo.",
+      "app-sign-in": "Manage app sign-in and pairing.",
+      apps: localizeCloudCliText(locale, {
+        en: "Inspect registered apps and manage app keys and domains.",
+        de: "Registrierte Apps prüfen und App-Schlüssel und App-Domains verwalten.",
+      }),
+      "apps domains": localizeCloudCliText(locale, {
+        en: "Assign app domains and inspect DNS, TLS and gateway reachability.",
+        de: "App-Domains zuordnen und DNS, TLS und Gateway-Erreichbarkeit prüfen.",
+      }),
+      "apps keys": "Create, list, and revoke Ed25519 app keys.",
+      documentation: "Manage the administration documentation website.",
+      geoip: "Replace and inspect sign-in location databases.",
+      jobs: "Inspect background jobs and their runs.",
+      logs: "Search, inspect, and clean up retained logs.",
+      metrics: "Inspect collectors and manage metrics access.",
+      "metrics tokens": "Manage metrics bearer tokens.",
+      nats: "Inspect NATS nodes, streams, and consumers.",
+      "nats consumers": "Inspect NATS consumers.",
+      "nats streams": "Find NATS streams and buckets.",
+      "notification-batches": "Manage account notification batches.",
+      "outgoing-mail": "Manage outgoing mail sender profiles, application access, and the send log.",
+      "outgoing-mail profiles": "Manage outgoing mail sender profiles.",
+      "outgoing-mail apps": "Manage application outgoing mail access.",
+      "outgoing-mail log": "Read and cancel application mail in the send log.",
+      "outgoing-mail retention": "Show or change how long the send log keeps mail.",
+      notifications: "Inspect and resend email notifications.",
+      postgres: "Inspect Postgres diagnostics.",
+      redis: "Inspect Valkey diagnostics.",
+      routes: "Inspect gateway routes.",
+      settings: "Inspect environment migration and change administrator settings.",
+      sync: "Inspect Sync resources, schedules, and dead letters.",
+      "sync dead-letters": "Inspect, replay, requeue, or remove dead letters.",
+      "sync resources": "List Sync resource declarations.",
+      "sync schedules": "Inspect and run Sync schedules.",
+      "sync schedules runs": "Read Sync schedule run results.",
+      telemetry: "Inspect request telemetry.",
+      webhooks: "Manage gateway health webhooks.",
+      workflows: "Inspect and operate workflow runs and effects.",
+      "app-sign-in config": "Manage the trusted app website and pairing policy.",
+      "accounts config": "Manage account types and sign-in visibility.",
+      "accounts administration": "Manage account requests and account/group follow-up notices.",
+      "ai quotas": "Manage direct Assistant chat limits and consumption.",
+      "ai quotas config": "Export and replace quota policies with revision checks.",
+      legal: "Manage Terms, Privacy, and Imprint.",
+      linux: "Prepare Linux identities.",
+      "linux config": "Manage Linux identity defaults and allocation range.",
+    },
+    commands: [
+      ...appCredentialCommands,
+      ...appKeyCommands,
+      ...appDomainCommands(locale),
+      ...agentCommands,
+      ...documentationCommands,
+      ...appSignInCommands,
+      ...accountCategoryCommands,
+      ...accountAdministrationCommands,
+      ...aiUsageCommands,
+      ...aiModelCommands,
+      ...aiQuotaCommands,
+      ...aiSkillCommands,
+      ...instanceCommands,
+      ...gatewayCommands,
+      ...logCommands,
+      ...telemetryCommands,
+      ...jobCommands,
+      ...legalCommands,
+      ...geoipCommands,
+      ...linuxCommands,
+      ...workflowCommands,
+      ...dataCommands,
+      ...notificationCommands,
+      ...outgoingMailCommands,
+      ...webhookCommands,
+      ...metricsCommands,
+      ...natsCommands,
+      ...syncCommands,
+      ...settingsCommands,
+    ],
+  });
+
+const admin = build();
+export default {
+  ...admin,
+  help: (locale?: string) => build(locale).help?.(locale) ?? "",
+  run: (ctx: CloudCliContext) => build(ctx.options.locale).run(ctx),
+};

package/src/config/env.ts

@@ -164,17 +164,23 @@ const registry = defineEnv({
     schema: z.string(),
     scope: "secret",
     secretFile: true,
-    doc: "Core and OAuth only: 64-hex secret that lets the OAuth app request token signatures from Core; generate independently with `openssl rand -hex 32`.",
+    doc: "Deprecated: Core and OAuth legacy 64-hex broker secret, used only when OAuth has no app key. Configure an OAuth app key instead; retained for this release.",
+  },
+  CLOUD_APP_KEY: {
+    schema: z.string(),
+    scope: "secret",
+    secretFile: true,
+    doc: "App Ed25519 private key for startup bootstrap, background calls and OAuth issuance; alternatively mount CLOUD_APP_KEY_FILE. Requires the direct Core origin. Core and Gateway refuse app keys. Keep infrastructure env until the platform-client import migration is complete.",
   },
   CLOUD_CORE_INTERNAL_ORIGIN: {
     schema: z.string(),
-    doc: "Direct Core listener origin for OAuth issuance, mandate-backed background work and internal callbacks; host-run callers use the Core port, not the gateway.",
+    doc: "Direct Core listener origin for app connection bootstrap, OAuth issuance, mandate-backed background work and internal callbacks; never the gateway. Cross-host bootstrap requires verified TLS; install private CAs through NODE_EXTRA_CA_CERTS before the first fetch.",
   },
   CLOUD_APP_CREDENTIAL: {
     schema: z.string(),
     scope: "secret",
     secretFile: true,
-    doc: "Optional host-run app override for the automatically delivered app workload credential; provision through Core's admin workload API with `identity:invoke`.",
+    doc: "Deprecated: host-run override for the automatically delivered workload credential when no app key is configured; use CLOUD_APP_KEY or CLOUD_APP_KEY_FILE instead. Retained for this release.",
   },
   CLOUD_IDENTITY_JWKS_ORIGIN: {
     schema: z.string(),
@@ -182,7 +188,7 @@ const registry = defineEnv({
   },
   CLOUD_OAUTH_JWKS_ORIGIN: {
     schema: z.string(),
-    doc: "Optional private origin of the OAuth listener for OAuth JWKS; unset fetches keys from the public issuer origin.",
+    doc: "Deprecated: explicit legacy OAuth JWKS origin, honored for this release. Unset uses Core internal OAuth JWKS through CLOUD_CORE_INTERNAL_ORIGIN, then the public issuer origin.",
   },
 
   // Build and standalone development

package/src/contracts/app-domains.ts

@@ -0,0 +1,91 @@
+import type { SQL } from "bun";
+import { PWA_COOKIES } from "./pwa";
+
+/**
+ * App public surface and app domains: the contract Core, the platform, and the gateway share.
+ *
+ * An app with `defineApp({ public: true })` serves `app.public`. The platform mounts that router below
+ * `PUBLIC_SURFACE_PREFIX` on the app upstream. Only the gateway sends requests there, for a host an
+ * administrator assigned to the app, and sets `PUBLIC_HOST_HEADER` to the request authority (that host plus the
+ * client's port, if its Host header had one). The gateway strips both
+ * the prefix and the header from every incoming request on every host.
+ */
+export const PUBLIC_SURFACE_PREFIX = "/_cloud/public";
+export const PUBLIC_HOST_HEADER = "X-Cloud-Public-Host";
+
+/** The only Cloud path on an app domain: `GET <prefix><nonce>` answers the nonce while Core checks the domain. */
+export const DOMAIN_CHECK_PATH_PREFIX = "/_cloud/domain-check/";
+/**
+ * Valkey key Core sets before it requests the check path, with TTL `DOMAIN_CHECK_TTL_SECONDS`. Its value is a
+ * separate random answer that never appears in the request; the gateway responds with it, so an unrelated server
+ * that echoes the path cannot pass the check.
+ */
+export const domainCheckKey = (host: string, nonce: string): string => `cloud:domain-check:${host}:${nonce}`;
+export const DOMAIN_CHECK_TTL_SECONDS = 60;
+
+export type AppDomain = {
+  /** Normalized host: lowercase ASCII (IDNA), no port, no wildcard. */
+  host: string;
+  appId: string;
+  /** Another domain of the same app; requests then answer 301 (GET/HEAD) or 308 with path and query kept. */
+  redirectTo: string | null;
+  createdAt: string;
+};
+
+/** Durable assignment, owned by Core's migration. Readers before that migration see no table and no domains. */
+export const APP_DOMAINS_DDL = `
+  CREATE TABLE IF NOT EXISTS settings.app_domains (
+    host TEXT PRIMARY KEY,
+    app_id TEXT NOT NULL,
+    redirect_to TEXT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+  )
+`;
+
+const HOST_LABEL = /^(?!-)[a-z0-9-]{1,63}(?<!-)$/;
+
+/** Returns the normalized host, or null when `input` is not a single DNS host name without port or wildcard. */
+export const normalizeAppDomainHost = (input: string): string | null => {
+  const trimmed = input.trim().replace(/\.$/, "");
+  if (!trimmed || /[/\\:@?#*\s]/.test(trimmed)) return null;
+  let host: string;
+  try {
+    host = new URL(`http://${trimmed}`).hostname;
+  } catch {
+    return null;
+  }
+  if (host.length > 253 || /^\d+(\.\d+){3}$/.test(host) || host.startsWith("[")) return null;
+  const labels = host.split(".");
+  if (labels.length < 2 && !host.endsWith("localhost")) return null;
+  return labels.every((label) => HOST_LABEL.test(label)) ? host : null;
+};
+
+/** Reads all assignments. A database without Core's table yet has none. */
+export const readAppDomains = async (db: SQL): Promise<AppDomain[]> => {
+  try {
+    const rows = await db<{ host: string; app_id: string; redirect_to: string | null; created_at: Date }[]>`
+      SELECT host, app_id, redirect_to, created_at FROM settings.app_domains ORDER BY host
+    `;
+    return rows.map((row) => ({ host: row.host, appId: row.app_id, redirectTo: row.redirect_to, createdAt: row.created_at.toISOString() }));
+  } catch (error) {
+    const code = error && typeof error === "object" && "errno" in error ? String(error.errno) : "";
+    if (code === "42P01") return [];
+    throw error;
+  }
+};
+
+/** Whether a registry entry declares `public: true`, read structurally so older entries stay valid. */
+export const declaresPublicSurface = (entry: object): boolean => "public" in entry && entry.public === true;
+
+/** Cookies that carry a Cloud credential. The gateway removes them from every request to a public surface. */
+export const isCloudCredentialCookie = (name: string): boolean =>
+  name === "session_token" ||
+  name === PWA_COOKIES.session ||
+  name === PWA_COOKIES.device ||
+  name === PWA_COOKIES.pairing ||
+  name === "cloud_browser" ||
+  name === "__Host-cloud_browser" ||
+  name.startsWith("__Secure-cloud-app-pwa-") ||
+  // Access proofs that built-in apps set on the Cloud host.
+  name === "mail_attachment_grant" ||
+  name === "filesv2-share-access";

package/src/contracts/app-status.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { CapabilityAppIdSchema, type CapabilityManifest } from "./capabilities";
+import { type CapabilityContractIssue, capabilityContractIssues } from "./capability-compatibility";
+
+export const AppStatusWindowSchema = z.enum(["1h", "6h", "24h", "7d", "30d"]);
+export type AppStatusWindow = z.infer<typeof AppStatusWindowSchema>;
+export const AppStatusSummaryInputSchema = z
+  .object({
+    appIds: z.array(CapabilityAppIdSchema).min(1).max(200).describe("Application IDs whose status is requested."),
+    window: AppStatusWindowSchema.describe("Traffic observation window."),
+  })
+  .strict();
+export const AppStatusDetailInputSchema = z
+  .object({
+    appId: CapabilityAppIdSchema.describe("Application ID."),
+    window: AppStatusWindowSchema.describe("Traffic observation window."),
+    cursor: z.string().min(1).max(2048).optional().describe("Opaque continuation cursor from this provider."),
+  })
+  .strict();
+export const AppStatusForgetInputSchema = z.object({ appId: CapabilityAppIdSchema.describe("Offline application ID to forget.") }).strict();
+const count = z.number().int().nonnegative();
+export const AppStatusTrafficSchema = z
+  .object({
+    requests: count,
+    errors: count,
+    avgMs: z.number().nonnegative().nullable(),
+  })
+  .strict();
+export const AppStatusLinkSchema = z
+  .object({
+    kind: z.enum(["logs", "metrics", "routes", "capabilities"]).optional(),
+    label: z.string().min(1).max(120),
+    href: z
+      .string()
+      .max(2048)
+      .regex(/^\/admin\/[^\\\s\u0000-\u001f\u007f]*$/),
+  })
+  .strict();
+export const AppStatusAppSchema = z
+  .object({
+    appId: CapabilityAppIdSchema.describe("Application ID."),
+    traffic: AppStatusTrafficSchema.nullable(),
+    links: z.array(AppStatusLinkSchema).max(4),
+    lastSeenAt: z.string().datetime({ offset: true }).nullable().optional(),
+  })
+  .strict();
+export const AppStatusSummaryDataSchema = z
+  .object({
+    // Requested apps plus the fifty provider-only apps; their rows carry lastSeenAt.
+    apps: z.array(AppStatusAppSchema).max(250),
+    otherApps: z.array(CapabilityAppIdSchema).max(50),
+  })
+  .strict();
+export const AppStatusDetailDataSchema = z
+  .object({
+    routes: z.array(z.object({ prefix: z.string().min(1).max(2048), requests: count, errors: count }).strict()).max(200),
+    failedRequests: z
+      .array(
+        z
+          .object({
+            at: z.string().datetime({ offset: true }),
+            method: z.string().min(1).max(32),
+            path: z.string().min(1).max(2048),
+            status: z.number().int().min(100).max(599),
+          })
+          .strict(),
+      )
+      .max(50),
+    totalFailedRequests: count.nullable().optional(),
+    nextCursor: z.string().min(1).max(2048).nullable(),
+  })
+  .strict();
+export const AppStatusForgetDataSchema = z.object({ forgotten: z.boolean() }).strict();
+export type AppStatusSummaryData = z.infer<typeof AppStatusSummaryDataSchema>;
+export type AppStatusDetailData = z.infer<typeof AppStatusDetailDataSchema>;
+
+/** Shared role validation at startup, registry read, and consumer discovery. */
+export const appStatusIssues = (manifest: CapabilityManifest): CapabilityContractIssue[] => {
+  const role = manifest.appStatus;
+  if (!role) return [];
+  const issues: CapabilityContractIssue[] = [];
+  for (const [localId, input, data] of [
+    [role.summary, AppStatusSummaryInputSchema, AppStatusSummaryDataSchema],
+    [role.detail, AppStatusDetailInputSchema, AppStatusDetailDataSchema],
+  ] as const) {
+    const query = manifest.queries.find((query) => query.localId === localId);
+    if (!query) issues.push({ code: "kind", path: "$", message: `Missing app-status Query ${localId}` });
+    else {
+      issues.push(...capabilityContractIssues({ kind: "query", input, data }, { kind: "query", operation: query }));
+      if (query.appOnly || query.openWorld)
+        issues.push({ code: "kind", path: "$", message: "App-status Queries must be closed-world and person-readable" });
+    }
+  }
+  const action = manifest.actions.find((action) => action.localId === role.forget);
+  if (!action) issues.push({ code: "kind", path: "$", message: `Missing app-status Action ${role.forget}` });
+  else
+    issues.push(
+      ...capabilityContractIssues(
+        { kind: "action", input: AppStatusForgetInputSchema, data: AppStatusForgetDataSchema, idempotency: "required" },
+        { kind: "action", operation: action },
+      ),
+    );
+  return issues;
+};

package/src/contracts/capabilities.ts

@@ -12,6 +12,7 @@ import { z } from "zod";
 import type { RequestAuthority } from "../server/middleware/auth";
 import type { AppEventDefinition, AppEventSubscriptionDefinition } from "./app-events";
 import { CommandPathSchema } from "./commands";
+import { type PlatformPermission, PlatformPermissionSchema } from "./outgoing-mail";
 import type { AccessSubject, RequestActor, User } from "./shared";
 import { AuthenticatedPrincipalSchema } from "./shared";
 
@@ -955,12 +956,12 @@ export type CapabilityPresentationCatalog = {
 
 /** App authority has no grant-bearing subject, user, nested exchange, or interactive credential. */
 export type CapabilityAppExecutionContext = {
-  actor: { kind: "app"; appId: string };
+  actor: { kind: "app"; appId: string; keyId?: string };
   accessSubject: { type: "none" };
   user: null;
   authority?: never;
   query?: never;
-  idempotencyKey?: never;
+  idempotencyKey?: string;
   locale: string;
   requestId: string;
   origin: CapabilityOrigin;
@@ -968,8 +969,18 @@ export type CapabilityAppExecutionContext = {
   signal: AbortSignal;
 };
 
+/** Explicit provider entry for calls paid for and authorized as the calling application. */
+export type CapabilityAppHandler<Input extends z.ZodType, Data extends z.ZodType> = {
+  permission: PlatformPermission;
+  run: (
+    input: z.output<Input>,
+    context: CapabilityAppExecutionContext,
+  ) => CapabilityInvocationResult<z.output<Data>> | Promise<CapabilityInvocationResult<z.output<Data>>>;
+};
+
 export type CapabilityQueryDefinition<Input extends z.ZodType = z.ZodType<any>, Data extends z.ZodType = z.ZodType<any>> = {
   appOnly?: never;
+  app?: CapabilityAppHandler<Input, Data>;
   title: string;
   description: string;
   input: Input;
@@ -988,6 +999,7 @@ export type CapabilityActionApprovalPolicy = "rememberable" | "none";
 
 export type CapabilityActionDefinition<Input extends z.ZodType = z.ZodType<any>, Data extends z.ZodType = z.ZodType<any>> = {
   appOnly?: never;
+  app?: CapabilityAppHandler<Input, Data>;
   title: string;
   description: string;
   input: Input;
@@ -1039,6 +1051,8 @@ export type CapabilityFileProviderDeclaration = { list: string; read: string; sa
 
 export type CapabilityCalendarSourceDeclaration = { calendars: string; events: string; update?: string; move?: string; delete?: string };
 
+export type CapabilityAppStatusDeclaration = { summary: string; detail: string; forget: string };
+
 export type CapabilityDiscussionsDeclaration = { item: string; containers: string; activity?: string };
 
 export type CapabilityDefinitions = {
@@ -1051,6 +1065,7 @@ export type CapabilityDefinitions = {
   fileProvider?: CapabilityFileProviderDeclaration;
   calendarSource?: CapabilityCalendarSourceDeclaration;
   discussions?: CapabilityDiscussionsDeclaration;
+  appStatus?: CapabilityAppStatusDeclaration;
   events?: CapabilityDefinitionCatalog<AppEventDefinition>;
   subscribes?: CapabilityDefinitionCatalog<AppEventSubscriptionDefinition>;
 };
@@ -1101,6 +1116,7 @@ const CapabilityOperationManifestBaseSchema = z
     inputSchema: z.record(z.string(), z.unknown()),
     dataSchema: z.record(z.string(), z.unknown()),
     stream: CapabilityStreamPolicySchema.optional(),
+    appPermission: PlatformPermissionSchema.optional(),
     schemaHash: z.string().regex(/^[a-f0-9]{64}$/),
   })
   .strict();
@@ -1179,6 +1195,14 @@ export const CapabilityResourcePageManifestSchema = z
   })
   .strict();
 
+export const CapabilityAppStatusManifestSchema = z
+  .object({
+    summary: CapabilityLocalIdSchema,
+    detail: CapabilityLocalIdSchema,
+    forget: CapabilityLocalIdSchema,
+  })
+  .strict();
+
 export const CapabilityDiscussionsManifestSchema = z
   .object({
     item: CapabilityLocalIdSchema,
@@ -1268,6 +1292,7 @@ const readableManifest = (value: unknown, personCatalog = false): unknown => {
     resourcePages: sentPages,
     resourceTypes: sentModels,
     discussions: sentDiscussions,
+    appStatus: sentAppStatus,
     ...rest
   } = sent;
   const models = readEntries(sentModels ?? [], CapabilityResourceTypeModelSchema) ?? [];
@@ -1309,6 +1334,14 @@ const readableManifest = (value: unknown, personCatalog = false): unknown => {
     (!role.data.activity || queryIds.has(role.data.activity))
       ? role.data
       : undefined;
+  const statusRole = CapabilityAppStatusManifestSchema.safeParse(sentAppStatus);
+  const appStatus =
+    statusRole.success &&
+    queryIds.has(statusRole.data.summary) &&
+    queryIds.has(statusRole.data.detail) &&
+    readableActions.some((action) => action.localId === statusRole.data.forget)
+      ? statusRole.data
+      : undefined;
   const provider = CapabilityFileProviderManifestSchema.safeParse(sentProvider);
   const calendar = CapabilityCalendarSourceManifestSchema.safeParse(sentCalendarSource);
   const pageCounts = new Map<string, number>();
@@ -1328,6 +1361,7 @@ const readableManifest = (value: unknown, personCatalog = false): unknown => {
     ...rest,
     ...(sentModels !== undefined ? { resourceTypes } : {}),
     ...(discussions ? { discussions } : {}),
+    ...(appStatus ? { appStatus } : {}),
     ...(sentPages !== undefined ? { resourcePages } : {}),
     ...(provider.success ? { fileProvider: provider.data } : {}),
     ...(calendar.success ? { calendarSource: calendar.data } : {}),
@@ -1371,6 +1405,7 @@ export const CapabilityManifestSchema = z.preprocess(
     fileProvider: CapabilityFileProviderManifestSchema.optional(),
     calendarSource: CapabilityCalendarSourceManifestSchema.optional(),
     discussions: CapabilityDiscussionsManifestSchema.optional(),
+    appStatus: CapabilityAppStatusManifestSchema.optional(),
     resourceTypes: z.array(CapabilityResourceTypeModelSchema).max(MAX_MANIFEST_ENTRIES).optional(),
     policies: z.record(CapabilityLocalIdSchema, CapabilityActionPolicySchema).optional(),
     events: z.array(CapabilityEventManifestSchema).max(MAX_MANIFEST_ENTRIES).optional(),

package/src/contracts/index.ts

@@ -3,6 +3,7 @@ export * from "./announcements";
 export * from "./app";
 export * from "./app-approval";
 export * from "./app-details";
+export * from "./app-status";
 export * from "./avatar";
 export * from "./calendar-source";
 export * from "./calendar-view";

package/src/contracts/outgoing-mail.ts

@@ -2,7 +2,7 @@ import type { PageParams, Paginated, ServiceError } from "@k2b/stdlib";
 import { z } from "zod";
 import { type RequestActor, ServiceAccountSchema, UserSchema } from "./shared";
 
-export const PlatformPermissionSchema = z.enum(["mail:send", "mail:read", "resources:readers"]);
+export const PlatformPermissionSchema = z.enum(["mail:send", "mail:read", "resources:readers", "geo:query"]);
 export type PlatformPermission = z.infer<typeof PlatformPermissionSchema>;
 export const MailRetentionSchema = z.object({ contentDays: z.int().min(1).max(36500), recordDays: z.int().min(1).max(36500) }).strict();
 export type MailRetention = z.infer<typeof MailRetentionSchema> & {

package/src/contracts/registry.ts

@@ -83,6 +83,8 @@ export type AppRuntimeMetadata = {
 };
 
 export type AppRegistryEntry = {
+  /** Opt-in public site, served only through the app public router. */
+  public?: true;
   access?: AppAccessRule;
   platformPermissions?: readonly PlatformPermission[];
   id: string;

package/src/events/app-event-delivery.ts

@@ -1,8 +1,8 @@
 import type { Topic, TopicConfig } from "@k2b/sync";
-import { sql } from "bun";
 import { assertAppEventSize } from "../_internal/app-event-schemas";
 import { lazySync } from "../_internal/process-sync";
 import { type AppEventEnvelope, AppEventEnvelopeSchema } from "../contracts/app-events";
+import { sql } from "../runtime/clients";
 import { logger } from "../services/logging";
 import { createPgOutbox } from "../services/outbox";
 

package/src/events/live-delivery.ts

@@ -1,7 +1,8 @@
 import type { Topic, TopicConfig } from "@k2b/sync";
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
 import type { z } from "zod";
 import { lazySync } from "../_internal/process-sync";
+import { sql } from "../runtime/clients";
 import { logger } from "../services/logging";
 import { createPgOutbox } from "../services/outbox";
 import type { LiveEnvelope } from "./live-engine";

package/src/index.ts

@@ -64,6 +64,7 @@ export { createRedis, createSql, redis, type SqlPoolOptions, sql } from "./runti
 export {
   type ConnectionSource,
   connections,
+  type PlatformBootstrapMetadata,
   type PlatformConnectionSources,
   type PlatformConnections,
   type PlatformConnectionValues,