@k2b/cloud 0.47.0 → 0.48.0

package/src/api/app-bootstrap.ts

@@ -0,0 +1,131 @@
+import type { SQL } from "bun";
+import { Hono, type MiddlewareHandler } from "hono";
+import { getConnInfo } from "hono/bun";
+import {
+  BOOTSTRAP_BODY,
+  BOOTSTRAP_PATH,
+  BOOTSTRAP_RESPONSE_BYTES,
+  BootstrapConnectionsSchema,
+  BootstrapResponseSchema,
+} from "../runtime/bootstrap-protocol";
+import { connections } from "../runtime/connections";
+import { clientIpBucket } from "../server/client-ip";
+import { type RateLimitResult, ratelimit } from "../server/ratelimit";
+import { authenticateBootstrap, BootstrapProofError, bootstrapRateLimit, consumeBootstrapProof } from "../services/app-bootstrap";
+import { touchAppKey } from "../services/app-keys";
+
+type BootstrapContext = { Variables: { bootstrapBody: Uint8Array<ArrayBuffer> } };
+
+/** Count actual bytes even when Content-Length is missing or forged. Never await cancellation. */
+const limitBody: MiddlewareHandler<BootstrapContext> = async (c, next) => {
+  const max = Buffer.byteLength(BOOTSTRAP_BODY);
+  const reject = () => c.json({ code: "body_too_large" }, 413);
+  if (Number(c.req.header("Content-Length")) > max) {
+    void c.req.raw.body?.cancel().catch(() => undefined);
+    return reject();
+  }
+  const reader = c.req.raw.body?.getReader();
+  const bytes = new Uint8Array(max);
+  let total = 0;
+  if (reader) {
+    try {
+      while (true) {
+        const chunk = await reader.read();
+        if (chunk.done) break;
+        if (total + chunk.value.byteLength > max) {
+          void reader.cancel().catch(() => undefined);
+          return reject();
+        }
+        bytes.set(chunk.value, total);
+        total += chunk.value.byteLength;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  c.set("bootstrapBody", bytes.slice(0, total));
+  await next();
+};
+
+type Dependencies = {
+  db?: SQL;
+  ingress?: MiddlewareHandler;
+  admit?: (keyId: string) => Promise<RateLimitResult>;
+};
+const admit = async (kind: "ingress" | "key", identifier: string) => {
+  // Use the installation's existing per-second security budget, in separate ingress and authenticated-key buckets.
+  const limit = await bootstrapRateLimit();
+  return ratelimit({ id: `app-bootstrap-${kind}`, limit }).check(identifier);
+};
+
+const ingress: MiddlewareHandler<BootstrapContext> = async (c, next) => {
+  // Bootstrap uses the direct Core socket. Unknown peers share one bounded bucket.
+  let peer = "unknown";
+  try {
+    peer = getConnInfo(c).remote.address ?? peer;
+  } catch {
+    /* In-process requests have no socket. */
+  }
+  const rate = await admit("ingress", clientIpBucket(peer));
+  if (rate.limited) {
+    c.header("Retry-After", String(Math.max(1, Math.ceil(rate.resetIn / 1000))));
+    return c.json({ code: "bootstrap_ingress_limited" }, 429);
+  }
+  await next();
+};
+
+/** Core-only mount. Capture the startup snapshot once, including NATS file contents. */
+export const createAppBootstrapRoutes = (dependencies: Dependencies = {}) => {
+  const { database, valkey, nats, appSecret } = connections();
+  const snapshot = BootstrapConnectionsSchema.parse({ database, valkey, nats, appSecret });
+  // Refuse an undeliverable Core configuration at startup, using the largest valid identity.
+  const largestIdentity = {
+    installationId: "11111111-1111-4111-8111-111111111111",
+    appId: "a".repeat(80),
+    keyId: "22222222-2222-4222-8222-222222222222",
+  };
+  if (Buffer.byteLength(JSON.stringify({ identity: largestIdentity, connections: snapshot })) > BOOTSTRAP_RESPONSE_BYTES)
+    throw new Error("Bootstrap response exceeds protocol budget");
+  // The startup snapshot includes appId/sources; only the delivery contract goes on the wire.
+  return new Hono<BootstrapContext>()
+    .onError(() =>
+      Response.json({ code: "bootstrap_unavailable" }, { status: 503, headers: { "Cache-Control": "no-store", "Retry-After": "1" } }),
+    )
+    .post(
+      BOOTSTRAP_PATH,
+      async (c, next) => {
+        c.header("Cache-Control", "no-store");
+        await next();
+      },
+      // The v1 request is exactly two UTF-8 bytes. This runs before proof parsing, even for invalid proofs.
+      limitBody,
+      dependencies.ingress ?? ingress,
+      async (c) => {
+        const url = new URL(c.req.url);
+        if (url.search) return c.json({ code: "invalid_request" }, 400);
+        const body = c.get("bootstrapBody");
+        const header = c.req.header("Authorization") ?? "";
+        if (!header.startsWith("Bearer ")) return c.json({ code: "invalid_proof" }, 401);
+        let verified: Awaited<ReturnType<typeof authenticateBootstrap>>;
+        try {
+          verified = await authenticateBootstrap(header.slice(7), { method: c.req.method, path: url.pathname, body }, dependencies.db);
+        } catch (error) {
+          if (error instanceof BootstrapProofError) return c.json({ code: error.code }, error.code === "invalid_proof" ? 401 : 403);
+          throw error;
+        }
+        if (new TextDecoder().decode(body) !== BOOTSTRAP_BODY) return c.json({ code: "invalid_request" }, 400);
+        const { identity, jti, exp } = verified;
+        const rate = dependencies.admit ? await dependencies.admit(identity.keyId) : await admit("key", identity.keyId);
+        if (rate.limited) {
+          c.header("Retry-After", String(Math.max(1, Math.ceil(rate.resetIn / 1000))));
+          return c.json({ code: "bootstrap_rate_limited" }, 429);
+        }
+        if (!(await consumeBootstrapProof(identity.keyId, jti, exp, dependencies.db))) return c.json({ code: "replayed_proof" }, 403);
+        await touchAppKey(identity, dependencies.db);
+        const response = JSON.stringify(BootstrapResponseSchema.parse({ identity, connections: snapshot }));
+        if (Buffer.byteLength(response) > BOOTSTRAP_RESPONSE_BYTES) throw new Error("Bootstrap response exceeds protocol budget");
+        c.header("Content-Type", "application/json");
+        return c.body(response);
+      },
+    );
+};

package/src/api/capabilities.ts

@@ -297,6 +297,8 @@ export type CapabilityDispatchParams = {
   callingAppId?: string;
   /** Internal observation only: called immediately before attempting the app request. */
   onUpstreamAttempt?: () => void;
+  /** Core-only aggregate budget, charged on upstream bytes before parsing or validation. */
+  consumeResponseBytes?: (bytes: number) => void;
   dependencies?: CapabilityDispatchDependencies;
 };
 
@@ -789,7 +791,12 @@ const runCapabilityDispatch = async (
   let upstreamBody: Awaited<ReturnType<typeof readBoundedJson>>;
   try {
     upstreamBody = await deadline.wait(() =>
-      readBoundedJson(response, params.review ? CAPABILITY_MAX_REVIEW_RESPONSE_BYTES : CAPABILITY_MAX_RESULT_BYTES, signal),
+      readBoundedJson(
+        response,
+        params.review ? CAPABILITY_MAX_REVIEW_RESPONSE_BYTES : CAPABILITY_MAX_RESULT_BYTES,
+        signal,
+        params.consumeResponseBytes,
+      ),
     );
   } catch {
     if (actionWithoutRetrySafety) return settle(outcomeUnknown(), "uncertain");

package/src/api/index.ts

@@ -26,6 +26,7 @@ import adminAiProjectsRoutes from "./admin-ai-projects";
 import adminAiQuotaRoutes from "./admin-ai-quotas";
 import adminAiSkillsRoutes from "./admin-ai-skills";
 import adminAiUsageRoutes from "./admin-ai-usage";
+import adminAppDomainRoutes from "./admin-app-domains";
 import adminAppKeyRoutes from "./admin-app-keys";
 import adminCoreSettingsRoutes from "./admin-core-settings";
 import adminDirectorySharesRoutes from "./admin-directory-shares";
@@ -107,6 +108,7 @@ const buildCoreApi = (options: CoreApiOptions) => {
     .route("/admin/core/geo", adminGeoRoutes)
     .route("/admin/identity/directory-shares", adminDirectorySharesRoutes)
     .route("/admin/identity", adminIdentityRoutes)
+    .route("/admin/apps", adminAppDomainRoutes)
     .route("/admin/apps", adminAppKeyRoutes)
     .route("/admin/sync", createSyncOpsProxyRoutes())
     .route("/admin/lifecycle", adminLifecycleRoutes)
@@ -135,8 +137,11 @@ export const createCoreApiRouter = (options: CoreApiOptions) => {
   return { api };
 };
 
+export { createAdminAppDomainRoutes } from "./admin-app-domains";
 export { createAdminAppKeyRoutes } from "./admin-app-keys";
 export { createAppAccessRoutes } from "./app-access";
+/** Core-owned internal startup protocol; applications use @k2b/cloud/start. */
+export { createAppBootstrapRoutes } from "./app-bootstrap";
 export {
   CLOUD_MCP_PATH,
   CLOUD_MCP_PROTECTED_RESOURCE_PATH,

package/src/capabilities/response.ts

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

package/src/capabilities/server-invoke.ts

@@ -4,6 +4,7 @@ import { dispatchCapability, loadCapabilityCatalogPage } from "../api/capabiliti
 import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
   CAPABILITY_MAX_CATALOG_BYTES,
+  CAPABILITY_MAX_RESULT_BYTES,
   CapabilityCatalogSchema,
   type CapabilityOrigin,
   capabilityResultSchema,
@@ -36,6 +37,8 @@ export type CapabilityCaller = {
   /** BCP 47 locale of the originating request, forwarded as invocation metadata. */
   locale?: string | null;
   signal?: AbortSignal;
+  /** Request-local aggregate response budget; called before result validation for every received chunk. */
+  consumeResponseBytes?: (bytes: number) => void;
   /** App-only query authority. The workload credential goes only to Core. */
   workload?: { appId: string };
   /** Durable background authority. `authorization` must be the owning app's workload credential. */
@@ -113,6 +116,8 @@ const invokeCapabilityWithResultSchema = async <TDataSchema extends z.ZodType, T
     if (caller.authority) {
       if (caller.authorization || caller.cookie || caller.mandate || caller.workload || caller.transport)
         throw new Error("Use exactly one capability authority source");
+      let charged = false;
+      const charge = caller.consumeResponseBytes;
       const outcome = await dispatchCapability({
         request,
         kind: invocation.kind === "query" ? "queries" : "actions",
@@ -122,8 +127,23 @@ const invokeCapabilityWithResultSchema = async <TDataSchema extends z.ZodType, T
         authority: caller.authority,
         locale: caller.locale ?? undefined,
         origin: caller.origin ?? "app",
+        ...(charge
+          ? {
+              consumeResponseBytes: (bytes: number) => {
+                charged = true;
+                charge(bytes);
+              },
+            }
+          : {}),
       });
-      return readCapabilityResponse(outcome, capabilityResultSchema(dataSchema, { consumer: true }));
+      return readCapabilityResponse(
+        outcome,
+        capabilityResultSchema(dataSchema, { consumer: true }),
+        CAPABILITY_MAX_RESULT_BYTES,
+        // Only a budgeted caller cancels reading a response that already arrived; others keep the received result.
+        charge ? combineCapabilitySignals(caller.signal, invocation.signal) : undefined,
+        charged ? undefined : charge,
+      );
     }
     const brokerRequest = new Request(request, {
       body: JSON.stringify(
@@ -170,7 +190,13 @@ const invokeCapabilityWithResultSchema = async <TDataSchema extends z.ZodType, T
         return unavailable(undefined, undefined, caller.locale ?? undefined);
       }
     }
-    return readCapabilityResponse(response, capabilityResultSchema(dataSchema, { consumer: true }));
+    return readCapabilityResponse(
+      response,
+      capabilityResultSchema(dataSchema, { consumer: true }),
+      CAPABILITY_MAX_RESULT_BYTES,
+      caller.consumeResponseBytes ? combineCapabilitySignals(caller.signal, invocation.signal) : undefined,
+      caller.consumeResponseBytes,
+    );
   } catch (cause) {
     return unavailable(cause, invocation, caller.locale ?? undefined);
   }

package/src/cli/admin/app-domains.ts

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import { arg, type CloudCliContext, cliText, command, confirmFlag, flag, localizeCloudCliText, printStructured } from "../index";
+import { apiGet, apiJson } from "./shared";
+
+const step = z.object({ ok: z.boolean(), detail: z.string() });
+const status = z.object({ checkedAt: z.string(), dns: step, certificate: step.nullable(), reachable: step.nullable() });
+const domain = z.object({
+  host: z.string(),
+  redirectTo: z.string().nullable(),
+  createdAt: z.string(),
+  active: z.boolean(),
+  status: status.nullable(),
+});
+const path = (appId: string, host?: string) =>
+  `/api/admin/apps/${encodeURIComponent(appId)}/domains${host === undefined ? "" : `/${encodeURIComponent(host)}`}`;
+const appArgs = { appId: arg.required({ valueLabel: "appId" }) };
+const domainArgs = { ...appArgs, host: arg.required({ valueLabel: "host" }) };
+const show = (ctx: CloudCliContext, raw: unknown, domains: z.infer<typeof domain>[]) => {
+  if (printStructured(ctx, raw)) return;
+  const checked = (result: z.infer<typeof step> | null | undefined) =>
+    result == null ? "-" : result.ok ? "ok" : cliText(ctx, { en: "failed", de: "fehlgeschlagen" });
+  ctx.table(
+    domains.map((item) => ({
+      host: item.host,
+      redirect: item.redirectTo ?? "-",
+      active: item.active,
+      dns: checked(item.status?.dns),
+      certificate: checked(item.status?.certificate),
+      reachable: checked(item.status?.reachable),
+    })),
+    [
+      { key: "host", label: "Host" },
+      { key: "redirect", label: cliText(ctx, { en: "Redirect", de: "Weiterleitung" }) },
+      { key: "active", label: cliText(ctx, { en: "Active", de: "Aktiv" }) },
+      { key: "dns", label: "DNS" },
+      { key: "certificate", label: cliText(ctx, { en: "Certificate", de: "Zertifikat" }) },
+      { key: "reachable", label: cliText(ctx, { en: "Reachable", de: "Erreichbar" }) },
+    ],
+  );
+};
+
+export const appDomainCommands = (locale?: string) => {
+  const t = (en: string, de: string) => localizeCloudCliText(locale, { en, de });
+  return [
+    command("apps domains ls", {
+      summary: t(
+        "List app domains, redirects and DNS/TLS/gateway status",
+        "App-Domains, Weiterleitungen und DNS/TLS/Gateway-Status auflisten",
+      ),
+      args: appArgs,
+      async run({ ctx, args }) {
+        const result = z.object({ domains: z.array(domain) }).parse(await apiGet(ctx, path(args.appId)));
+        show(ctx, result, result.domains);
+      },
+    }),
+    command("apps domains add", {
+      summary: t(
+        "Assign a domain to a registered app and start its first check",
+        "Eine Domain einer bekannten App zuordnen und erstmals prüfen",
+      ),
+      args: domainArgs,
+      flags: {
+        redirectTo: flag.string({
+          description: t("Another domain of this app without a redirect", "Eine andere Domain dieser App ohne Weiterleitung"),
+        }),
+      },
+      async run({ ctx, args, flags }) {
+        const result = domain.parse(
+          await apiJson(ctx, "POST", path(args.appId), { host: args.host, ...(flags.redirectTo ? { redirectTo: flags.redirectTo } : {}) }),
+        );
+        show(ctx, result, [result]);
+      },
+    }),
+    command("apps domains set", {
+      summary: t("Set or clear an app domain redirect", "Eine Domain-Weiterleitung setzen oder entfernen"),
+      args: domainArgs,
+      flags: {
+        redirectTo: flag.string({
+          description: t("Another domain of this app without a redirect", "Eine andere Domain dieser App ohne Weiterleitung"),
+        }),
+        noRedirect: flag.boolean({ description: t("Clear the redirect", "Die Weiterleitung entfernen") }),
+      },
+      async run({ ctx, args, flags }) {
+        if (Boolean(flags.redirectTo) === flags.noRedirect)
+          throw new Error(
+            cliText(ctx, {
+              en: "Use exactly one of --redirect-to or --no-redirect.",
+              de: "Nutze genau eine Option: --redirect-to oder --no-redirect.",
+            }),
+          );
+        const result = domain.parse(
+          await apiJson(ctx, "PATCH", path(args.appId, args.host), { redirectTo: flags.noRedirect ? null : flags.redirectTo }),
+        );
+        show(ctx, result, [result]);
+      },
+    }),
+    command("apps domains rm", {
+      summary: t("Remove an unreferenced app domain assignment", "Eine App-Domain ohne eingehende Weiterleitungen entfernen"),
+      args: domainArgs,
+      flags: { yes: confirmFlag(t("Remove this domain assignment", "Diese Domain-Zuordnung entfernen")) },
+      async run({ ctx, args, flags }) {
+        if (!flags.yes)
+          throw new Error(cliText(ctx, { en: "Removing a domain requires --yes.", de: "Das Entfernen einer Domain erfordert --yes." }));
+        const result = await apiJson(ctx, "DELETE", path(args.appId, args.host));
+        if (!printStructured(ctx, result)) ctx.print(cliText(ctx, { en: "Domain removed.", de: "Domain entfernt." }));
+      },
+    }),
+    command("apps domains check", {
+      summary: t(
+        "Check DNS, certificate and gateway reachability, at most once per 60 seconds",
+        "DNS, Zertifikat und Gateway-Erreichbarkeit höchstens einmal pro 60 Sekunden prüfen",
+      ),
+      args: domainArgs,
+      async run({ ctx, args }) {
+        const result = z.object({ status: status.nullable() }).parse(await apiJson(ctx, "POST", `${path(args.appId, args.host)}/check`));
+        if (printStructured(ctx, result)) return;
+        if (!result.status) {
+          ctx.print(
+            cliText(ctx, {
+              en: "The first check is running. List the domains again shortly.",
+              de: "Die erste Prüfung läuft. Liste die Domains gleich erneut auf.",
+            }),
+          );
+          return;
+        }
+        ctx.table(
+          (["dns", "certificate", "reachable"] as const).map((key) => {
+            const value = result.status![key];
+            return { step: key, ok: value?.ok ?? "-", detail: value?.detail ?? "-" };
+          }),
+          [
+            { key: "step", label: cliText(ctx, { en: "Step", de: "Schritt" }) },
+            { key: "ok", label: "OK" },
+            { key: "detail", label: "Detail" },
+          ],
+        );
+      },
+    }),
+  ];
+};

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

@@ -166,9 +166,15 @@ const registry = defineEnv({
     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`.",
   },
+  CLOUD_APP_KEY: {
+    schema: z.string(),
+    scope: "secret",
+    secretFile: true,
+    doc: "App Ed25519 private key for startup connection bootstrap; 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(),