@k2b/cloud 0.47.0 → 0.49.0

package/src/app-pwa/transaction.ts

@@ -1,6 +1,6 @@
 import { isPromise } from "node:util/types";
 import type { ReservedSQL, SQL, TransactionSQL } from "bun";
-import * as bun from "bun";
+import { createSql } from "../runtime/clients";
 import { REQUEST_IDLE_TIMEOUT_SECONDS } from "../server/request-timeout";
 import { boundTransaction } from "./authority";
 import { AppPwaError } from "./contracts";
@@ -22,8 +22,9 @@ const cancellationPool = (db: SQL) => {
   const connection: Record<string, string | number> = {};
   for (let index = 0; index + 1 < parts.length; index += 2) connection[parts[index]!] = parts[index + 1]!;
   connection.statement_timeout = requestBudget;
-  return new bun.SQL(`postgres://localhost?sslmode=${modes[sslMode]}`, {
+  return createSql({
     ...options,
+    adapter: "postgres",
     // Bun adds SNI to normalized prefer options. Passing that generated object
     // back as explicit TLS upgrades prefer to require. Recreate its default SNI
     // from hostname instead; explicit verification options remain unchanged.
@@ -35,6 +36,7 @@ const cancellationPool = (db: SQL) => {
     maxLifetime: REQUEST_IDLE_TIMEOUT_SECONDS,
     onconnect: undefined,
     onclose: undefined,
+    url: `postgres://localhost?sslmode=${modes[sslMode]}`,
   });
 };
 

package/src/capabilities/claims.ts

@@ -1,4 +1,5 @@
-import { sql } from "bun";
+import { sql } from "../runtime/clients";
+
 import { logger } from "../services/logging";
 
 const log = logger("capabilities:claims");

package/src/capabilities/executions.ts

@@ -1,6 +1,6 @@
-import { sql } from "bun";
 import { createCapabilityDeadline } from "../_internal/capability-timeout";
 import type { CapabilityOrigin } from "../contracts/capabilities";
+import { sql } from "../runtime/clients";
 import { REQUEST_IDLE_TIMEOUT_SECONDS } from "../server/request-timeout";
 import { pruneApprovalRequests } from "../services/approvals";
 import { logger } from "../services/logging";
@@ -65,6 +65,8 @@ export type CapabilityExecutionInput = {
   destructive: boolean;
   actorKind?: "user" | "service_account" | "app" | null;
   actorId?: string | null;
+  actorAppId?: string | null;
+  actorKeyId?: string | null;
   userId?: string | null;
   /** Recorded only when the access subject differs from the acting principal. */
   accessSubject?: { type: "user" | "service_account"; id: string } | null;
@@ -92,6 +94,8 @@ export type CapabilityExecution = {
   destructive: boolean;
   actorKind: "user" | "service_account" | "app" | null;
   actorId: string | null;
+  actorAppId?: string | null;
+  actorKeyId?: string | null;
   userId: string | null;
   accessSubjectType: "user" | "service_account" | null;
   accessSubjectId: string | null;
@@ -122,12 +126,12 @@ export const recordCapabilityExecution = async (input: CapabilityExecutionInput)
         const [row] = await db<{ id: string }[]>`
     INSERT INTO capabilities.executions (
       request_id, invocation_id, parent_invocation_id, via_app_id, origin, app_id, capability, kind, destructive,
-      actor_kind, actor_id, user_id, access_subject_type, access_subject_id,
+      actor_kind, actor_id, actor_app_id, actor_key_id, user_id, access_subject_type, access_subject_id,
       status, error_code, input_meta, output_meta, idempotency_key, replayed,
       started_at, completed_at, duration_ms
     ) VALUES (
       ${input.requestId}, ${input.invocationId ?? null}, ${input.parentInvocationId ?? null}, ${input.viaAppId ?? null}, ${input.origin}, ${input.appId}, ${input.capability}, ${input.kind}, ${input.destructive},
-      ${input.actorKind ?? null}, ${input.actorId ?? null}, ${input.userId ?? null},
+      ${input.actorKind ?? null}, ${input.actorId ?? null}, ${input.actorAppId ?? null}, ${input.actorKeyId ?? null}::uuid, ${input.userId ?? null},
       ${input.accessSubject?.type ?? null}, ${input.accessSubject?.id ?? null},
       ${input.status}, ${input.errorCode ?? null},
       ${input.inputMeta ? JSON.stringify(input.inputMeta) : null}::text::jsonb,
@@ -177,7 +181,7 @@ const columns = () => sql`
   execution.id::text AS id, execution.request_id AS "requestId",
   execution.invocation_id::text AS "invocationId", execution.parent_invocation_id::text AS "parentInvocationId", execution.via_app_id AS "viaAppId", execution.origin, execution.app_id AS "appId",
   execution.capability, execution.kind, execution.destructive,
-  execution.actor_kind AS "actorKind", execution.actor_id::text AS "actorId", execution.user_id::text AS "userId",
+  execution.actor_app_id AS "actorAppId", execution.actor_key_id::text AS "actorKeyId", execution.actor_kind AS "actorKind", execution.actor_id::text AS "actorId", execution.user_id::text AS "userId",
   execution.access_subject_type AS "accessSubjectType", execution.access_subject_id::text AS "accessSubjectId",
   execution.status, execution.error_code AS "errorCode", execution.input_meta AS "inputMeta",
   execution.output_meta AS "outputMeta", execution.idempotency_key AS "idempotencyKey", execution.replayed,

package/src/capabilities/geo-client.ts

@@ -4,7 +4,7 @@ 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. */
+/** Calls Core using the caller's interactive identity, invocation transport, app authority, or durable mandate. */
 export const geoClient = {
   mapStyle: (input: z.input<typeof geoMapContract.style.input>, caller: CapabilityCaller) =>
     invokeCapabilityWithDataSchema(

package/src/capabilities/migrate.ts

@@ -1,4 +1,4 @@
-import { sql } from "bun";
+import { sql } from "../runtime/clients";
 
 /**
  * Platform-owned capability execution history.
@@ -58,6 +58,8 @@ export const migrateCloudCapabilities = async (): Promise<void> => {
   await sql`ALTER TABLE capabilities.executions ADD COLUMN IF NOT EXISTS invocation_id UUID`.simple();
   await sql`ALTER TABLE capabilities.executions ADD COLUMN IF NOT EXISTS parent_invocation_id UUID`.simple();
   await sql`ALTER TABLE capabilities.executions ADD COLUMN IF NOT EXISTS via_app_id TEXT`.simple();
+  await sql`ALTER TABLE capabilities.executions ADD COLUMN IF NOT EXISTS actor_app_id TEXT`.simple();
+  await sql`ALTER TABLE capabilities.executions ADD COLUMN IF NOT EXISTS actor_key_id UUID`.simple();
 
   await sql`DO $$ BEGIN
     IF EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'capabilities.executions'::regclass

package/src/capabilities/resource-readers.ts

@@ -33,7 +33,7 @@ export const readResourcePrincipals = async (options: {
   const ref = CloudResourceRefSchema.parse(options.ref);
   // Core issues the credential automatically; an explicit CLOUD_APP_CREDENTIAL override wins.
   const credential = getAppWorkloadCredential();
-  if (!credential) return { state: "not_configured", reason: "no_credential" };
+  if (!env.CLOUD_APP_KEY && !credential) return { state: "not_configured", reason: "no_credential" };
   if (!env.CLOUD_CORE_INTERNAL_ORIGIN) return { state: "not_configured", reason: "no_internal_origin" };
   const callerAppId = getProcessApplicationId();
   if (!callerAppId) return { state: "not_configured", reason: "no_app_identity" };
@@ -54,7 +54,7 @@ export const readResourcePrincipals = async (options: {
     ResourceReadableDataSchema,
     {
       workload: { appId: callerAppId },
-      authorization: `Bearer ${credential}`,
+      ...(credential ? { authorization: `Bearer ${credential}` } : {}),
       signal: options.signal,
       locale: options.locale,
       requestId: options.requestId,

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

@@ -1,14 +1,18 @@
 import { z } from "zod";
+import { getProcessApplicationId } from "../_internal/process-identity";
 import { refreshAppWorkloadCredential } from "../_internal/workload-credential";
 import { dispatchCapability, loadCapabilityCatalogPage } from "../api/capabilities";
+import { env } from "../config/env";
 import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
   CAPABILITY_MAX_CATALOG_BYTES,
+  CAPABILITY_MAX_RESULT_BYTES,
   CapabilityCatalogSchema,
   type CapabilityOrigin,
   capabilityResultSchema,
 } from "../contracts/capabilities";
 import type { RequestAuthority } from "../server";
+import { sendAppRequest } from "../services/identity/app-request";
 import { coreOrigin } from "../services/identity/core-origin";
 import { capabilityMessages } from "../shared/capability-messages";
 import { LOCALE_HEADER } from "../shared/locale";
@@ -36,12 +40,24 @@ export type CapabilityCaller = {
   /** BCP 47 locale of the originating request, forwarded as invocation metadata. */
   locale?: string | null;
   signal?: AbortSignal;
-  /** App-only query authority. The workload credential goes only to Core. */
+  /** Request-local aggregate response budget; called before result validation for every received chunk. */
+  consumeResponseBytes?: (bytes: number) => void;
+  /** App-only query authority. The platform authenticates each transmission to Core. */
   workload?: { appId: string };
-  /** Durable background authority. `authorization` must be the owning app's workload credential. */
+  /** App authority authenticated only by the configured Ed25519 app key. */
+  app?: { appId: string };
+  /** Durable background authority. The platform authenticates each transmission to Core. */
   mandate?: { id: string; revision: number; callingAppId: string };
 };
 
+/** Call as the started application, without a person, service account token, or mandate. */
+export const appCaller = (options: Pick<CapabilityCaller, "locale" | "requestId" | "signal"> = {}): CapabilityCaller => {
+  const appId = getProcessApplicationId();
+  if (!appId) throw new Error("Start the application before creating its capability caller");
+  if (!env.CLOUD_APP_KEY) throw new Error("App capability calls require CLOUD_APP_KEY");
+  return { ...options, app: { appId }, origin: "app" };
+};
+
 export { coreOrigin } from "../services/identity/core-origin";
 
 export const callerRequest = async (
@@ -52,7 +68,7 @@ export const callerRequest = async (
 ): Promise<Request> => {
   const headers = new Headers();
   if (caller.authorization) headers.set("authorization", caller.authorization);
-  if (!caller.mandate && !caller.workload) {
+  if (!caller.mandate && !caller.workload && !caller.app) {
     if (caller.cookie) headers.set("cookie", caller.cookie);
     if (caller.requestId) headers.set("x-request-id", caller.requestId);
     if (caller.traceparent) headers.set("traceparent", caller.traceparent);
@@ -60,14 +76,17 @@ export const callerRequest = async (
     if (caller.locale) headers.set(LOCALE_HEADER, caller.locale);
     if (idempotencyKey) headers.set("idempotency-key", idempotencyKey);
   } else {
-    headers.set("x-cloud-app-id", caller.mandate?.callingAppId ?? caller.workload!.appId);
+    headers.set("x-cloud-app-id", caller.app?.appId ?? caller.mandate?.callingAppId ?? caller.workload!.appId);
   }
   const signal = combineCapabilitySignals(caller.signal, invocationSignal);
-  return new Request(new URL(path, await coreOrigin(caller.mandate !== undefined || caller.workload !== undefined)), {
-    method: "POST",
-    headers,
-    signal,
-  });
+  return new Request(
+    new URL(path, await coreOrigin(caller.app !== undefined || caller.mandate !== undefined || caller.workload !== undefined)),
+    {
+      method: "POST",
+      headers,
+      signal,
+    },
+  );
 };
 
 export const unavailable = (
@@ -103,16 +122,23 @@ const invokeCapabilityWithResultSchema = async <TDataSchema extends z.ZodType, T
   caller: CapabilityCaller,
 ): Promise<CapabilityClientResult<z.output<TDataSchema>>> => {
   try {
+    if (
+      caller.app &&
+      (!env.CLOUD_APP_KEY || caller.authority || caller.authorization || caller.cookie || caller.workload || caller.mandate)
+    )
+      throw new Error("App calls require one app-key authority source");
     if (caller.workload && (caller.mandate || caller.cookie || invocation.kind !== "query"))
       throw new Error("Workload authority permits only queries without a mandate or cookie");
     const path =
-      caller.mandate || caller.workload
+      caller.app || caller.mandate || caller.workload
         ? "/api/_internal/identity/v1/invoke"
         : `/api/capabilities/v1/${invocation.kind === "query" ? "queries" : "actions"}/${encodeURIComponent(invocation.appId)}/${encodeURIComponent(invocation.capabilityId)}`;
     const request = await callerRequest(caller, path, invocation.idempotencyKey, invocation.signal);
     if (caller.authority) {
-      if (caller.authorization || caller.cookie || caller.mandate || caller.workload || caller.transport)
+      if (caller.authorization || caller.cookie || caller.app || 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,13 +148,29 @@ 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(
-        caller.mandate || caller.workload
+        caller.app || caller.mandate || caller.workload
           ? {
+              ...(caller.app ? { appCaller: true } : {}),
               kind: invocation.kind,
               targetApp: invocation.appId,
               capabilityId: invocation.capabilityId,
@@ -149,13 +191,15 @@ const invokeCapabilityWithResultSchema = async <TDataSchema extends z.ZodType, T
           : { input: invocation.input },
       ),
     });
-    const send = caller.transport ?? ((request: Request) => fetch(request, caller.workload ? { redirect: "error" } : undefined));
-    // Only Core's pre-dispatch workload rejection is safe to retry, including a non-idempotent action.
-    const workloadAppId = caller.mandate?.callingAppId ?? caller.workload?.appId;
+    const workloadAppId = caller.app?.appId ?? caller.mandate?.callingAppId ?? caller.workload?.appId;
+    const send = (request: Request) =>
+      workloadAppId ? sendAppRequest(request, { appId: workloadAppId, transport: caller.transport }) : (caller.transport ?? fetch)(request);
+    // Only Core's pre-dispatch legacy rejection is safe to refresh and retry.
+    // A configured app key is never downgraded to a reusable credential.
     const retryRequest = workloadAppId ? brokerRequest.clone() : undefined;
     let response = await send(brokerRequest);
     const credentialRejected = (reply: Response) => reply.status === 401 && reply.headers.get("x-cloud-workload-auth") === "required";
-    if (workloadAppId && retryRequest && credentialRejected(response)) {
+    if (!caller.app && workloadAppId && retryRequest && !env.CLOUD_APP_KEY && credentialRejected(response)) {
       await response.body?.cancel();
       let token: string | undefined;
       try {
@@ -170,7 +214,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);
   }
@@ -202,14 +252,17 @@ export const listCapabilityCatalog = async (
     if (options.caller) {
       const caller = options.caller;
       if (options.authority) throw new Error("Use one catalog authority source");
-      if (caller.authority && (caller.authorization || caller.cookie || caller.mandate || caller.workload || caller.transport))
+      if (
+        caller.authority &&
+        (caller.authorization || caller.cookie || caller.app || caller.mandate || caller.workload || caller.transport)
+      )
         throw new Error("Use exactly one capability authority source");
       if (caller.authority)
         return {
           ok: true,
           data: await loadCapabilityCatalogPage({ cursor: options.cursor, limit }, {}, caller.locale ?? options.locale, caller.authority),
         };
-      if (caller.mandate || caller.workload) throw new Error("Calendar discovery requires request credentials");
+      if (caller.app || caller.mandate || caller.workload) throw new Error("Calendar discovery requires request credentials");
       const query = new URLSearchParams({ limit: String(limit) });
       if (options.cursor) query.set("cursor", options.cursor);
       const request = new Request(await callerRequest(caller, `/api/capabilities/v1/catalog?${query}`), { method: "GET" });

package/src/capabilities/server.ts

@@ -19,6 +19,7 @@ import type { CapabilityCatalogAppClientResult, CapabilityInvocation, Capability
 
 export type { CapabilityActionWording } from "../_internal/capability-sentences";
 export {
+  appCaller,
   type CapabilityCaller,
   invokeCapability,
   invokeCapabilityWithDataSchema,
@@ -89,7 +90,7 @@ export const reviewCapabilityAction = async <TInput = unknown>(
   caller: CapabilityCaller,
 ): Promise<CapabilityReviewClientResult> => {
   try {
-    if (caller.workload) throw new Error("App query authority cannot review Actions");
+    if (caller.app || caller.workload) throw new Error("App query authority cannot review Actions");
     if (caller.authority) {
       if (caller.authorization || caller.cookie || caller.mandate || caller.transport)
         throw new Error("Use exactly one capability authority source");

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/app-keys.ts

@@ -78,7 +78,8 @@ export const enrollAppKey = async (input: {
   format: AppKeyArtifactFormat;
   uid?: number;
   name?: string;
-  register: (body: { publicKey: string; name?: string }) => Promise<unknown>;
+  grants?: "oauth:issue"[];
+  register: (body: { publicKey: string; name?: string; grants?: "oauth:issue"[] }) => Promise<unknown>;
 }) => {
   validateAppKeyAppId(input.appId);
   if (input.uid !== undefined && process.getuid?.() !== 0 && process.getuid?.() !== input.uid)
@@ -113,7 +114,11 @@ export const enrollAppKey = async (input: {
   if ((await deriveAppPublicKey(state.seed)) !== state.publicKey) throw new Error("Enrollment public key does not match its seed");
   await owner(provisional, input.uid);
   const registered = registrationSchema.parse(
-    await input.register({ publicKey: state.publicKey, ...(input.name ? { name: input.name } : {}) }),
+    await input.register({
+      publicKey: state.publicKey,
+      ...(input.name ? { name: input.name } : {}),
+      ...(input.grants ? { grants: input.grants } : {}),
+    }),
   );
   if (registered.fingerprint !== (await appKeyFingerprint(state.publicKey)))
     throw new Error("Core returned a different app-key fingerprint");
@@ -161,8 +166,11 @@ export const appKeyCommands = [
       format: flag.enum(["file", "env", "compose", "k8s-secret"] as const, { default: "file" }),
       uid: flag.int({ min: 0, description: "File owner UID; requires root or the current UID" }),
       name: flag.string({ description: "Human-readable key name" }),
+      grant: flag.enum(["oauth:issue"] as const, { description: "Grant OAuth issuance to each new key; repeat on rotation" }),
+      noGrant: flag.boolean({ name: "no-grant", description: "Enroll new keys without grants (the default)" }),
     },
     async run({ ctx, args, flags }) {
+      if (flags.grant && flags.noGrant) throw new Error("Choose either --grant or --no-grant");
       const apps = await resolveAppKeyApps(args.apps, flags.all, flags.apps);
       const results = [];
       for (const appId of apps)
@@ -174,6 +182,7 @@ export const appKeyCommands = [
             format: flags.format ?? "file",
             uid: flags.uid,
             name: flags.name,
+            grants: flags.grant ? [flags.grant] : flags.noGrant ? [] : undefined,
             register: (body) => apiJson(ctx, "POST", keyPath(appId), body),
           }),
         );
@@ -194,6 +203,14 @@ export const appKeyCommands = [
       const result = z
         .object({
           installationId: z.uuid(),
+          lastRejectedStart: z
+            .object({
+              at: z.iso.datetime(),
+              reason: z.enum(["revoked", "expired", "disabled", "connections_not_permitted"]),
+              keyId: z.uuid().nullable(),
+            })
+            .nullable()
+            .optional(),
           items: z.array(
             z
               .object({ keyId: z.string(), name: z.string(), fingerprint: z.string(), status: z.string(), accountStatus: z.string() })
@@ -202,7 +219,11 @@ export const appKeyCommands = [
         })
         .passthrough()
         .parse(await apiGet(ctx, `${keyPath(args.app)}?page=${flags.page}&perPage=${flags.perPage}`));
-      if (!printStructured(ctx, result))
+      if (!printStructured(ctx, result)) {
+        if (result.lastRejectedStart) {
+          const rejection = result.lastRejectedStart;
+          ctx.print(`Last rejected start: ${rejection.at} · ${rejection.reason} · key ${rejection.keyId ?? "unknown"}`);
+        }
         ctx.table(result.items, [
           { key: "keyId", label: "Key ID" },
           { key: "name", label: "Name" },
@@ -210,6 +231,7 @@ export const appKeyCommands = [
           { key: "status", label: "Status" },
           { key: "accountStatus", label: "Account" },
         ]);
+      }
     },
   }),
   command("apps keys revoke", {