@k2b/cloud 0.46.0 → 0.48.0

package/src/capabilities/server-invoke.ts

@@ -1,8 +1,10 @@
 import { z } from "zod";
+import { refreshAppWorkloadCredential } from "../_internal/workload-credential";
 import { dispatchCapability, loadCapabilityCatalogPage } from "../api/capabilities";
 import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
   CAPABILITY_MAX_CATALOG_BYTES,
+  CAPABILITY_MAX_RESULT_BYTES,
   CapabilityCatalogSchema,
   type CapabilityOrigin,
   capabilityResultSchema,
@@ -35,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. */
@@ -112,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",
@@ -121,38 +127,76 @@ 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
+          ? {
+              kind: invocation.kind,
+              targetApp: invocation.appId,
+              capabilityId: invocation.capabilityId,
+              input: invocation.input,
+              ...(caller.mandate ? { mandateId: caller.mandate.id, mandateRevision: caller.mandate.revision } : {}),
+              ...(invocation.idempotencyKey ? { idempotencyKey: invocation.idempotencyKey } : {}),
+              ...(caller.requestId || caller.traceparent || caller.tracestate || caller.locale
+                ? {
+                    metadata: {
+                      ...(caller.requestId ? { requestId: caller.requestId } : {}),
+                      ...(caller.traceparent ? { traceparent: caller.traceparent } : {}),
+                      ...(caller.tracestate ? { tracestate: caller.tracestate } : {}),
+                      ...(caller.locale ? { locale: caller.locale } : {}),
+                    },
+                  }
+                : {}),
+            }
+          : { 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 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)) {
+      await response.body?.cancel();
+      let token: string | undefined;
+      try {
+        token = await refreshAppWorkloadCredential(workloadAppId);
+      } catch {
+        // This rejection happened before dispatch; credential state is retryable unavailability.
+      }
+      if (token) retryRequest.headers.set("authorization", `Bearer ${token}`);
+      response = await send(retryRequest);
+      if (credentialRejected(response)) {
+        await response.body?.cancel();
+        return unavailable(undefined, undefined, caller.locale ?? undefined);
+      }
     }
-    const response = await (
-      caller.transport ?? ((request: Request) => fetch(request, caller.workload ? { redirect: "error" } : undefined))
-    )(
-      new Request(request, {
-        body: JSON.stringify(
-          caller.mandate || caller.workload
-            ? {
-                kind: invocation.kind,
-                targetApp: invocation.appId,
-                capabilityId: invocation.capabilityId,
-                input: invocation.input,
-                ...(caller.mandate ? { mandateId: caller.mandate.id, mandateRevision: caller.mandate.revision } : {}),
-                ...(invocation.idempotencyKey ? { idempotencyKey: invocation.idempotencyKey } : {}),
-                ...(caller.requestId || caller.traceparent || caller.tracestate || caller.locale
-                  ? {
-                      metadata: {
-                        ...(caller.requestId ? { requestId: caller.requestId } : {}),
-                        ...(caller.traceparent ? { traceparent: caller.traceparent } : {}),
-                        ...(caller.tracestate ? { tracestate: caller.tracestate } : {}),
-                        ...(caller.locale ? { locale: caller.locale } : {}),
-                      },
-                    }
-                  : {}),
-              }
-            : { input: invocation.input },
-        ),
-      }),
+    return readCapabilityResponse(
+      response,
+      capabilityResultSchema(dataSchema, { consumer: true }),
+      CAPABILITY_MAX_RESULT_BYTES,
+      caller.consumeResponseBytes ? combineCapabilitySignals(caller.signal, invocation.signal) : undefined,
+      caller.consumeResponseBytes,
     );
-    return readCapabilityResponse(response, capabilityResultSchema(dataSchema, { consumer: true }));
   } catch (cause) {
     return unavailable(cause, invocation, caller.locale ?? undefined);
   }

package/src/capabilities/server.ts

@@ -182,7 +182,7 @@ export {
   readCalendarEvents,
 } from "./calendar-sources";
 export { type DiscussionProvider, discussionProviders } from "./discussion-providers";
-export { type ResourceReadersResult, readResourcePrincipals } from "./resource-readers";
+export { ResourceReaderRateLimited, type ResourceReadersResult, readResourcePrincipals } from "./resource-readers";
 export {
   actionReview,
   type CapabilityReviewForms,

package/src/capabilities/types.ts

@@ -2,7 +2,7 @@ import type { z } from "zod";
 import type { CapabilityActionReviewData, CapabilityCatalog, CapabilityErrorSchema, CapabilityResult } from "../contracts/capabilities";
 
 export type CapabilityKind = "query" | "action";
-export type CapabilityClientError = z.infer<typeof CapabilityErrorSchema> & { status: number };
+export type CapabilityClientError = z.infer<typeof CapabilityErrorSchema> & { status: number; retryAfterMs?: number };
 export type CapabilityResultState<T> = { ok: true; data: T } | { ok: false; error: CapabilityClientError };
 export type CapabilityClientResult<T> = CapabilityResultState<CapabilityResult<T>>;
 export type CapabilityReviewClientResult = CapabilityResultState<CapabilityActionReviewData>;

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

@@ -10,6 +10,7 @@ const metadata = z.object({
   status: z.string(),
   tokenPrefix: z.string(),
   expiresAt: z.string().nullable(),
+  serviceAccount: z.object({ status: z.string() }).optional(),
 });
 
 export const appCredentialCommands = [
@@ -33,12 +34,15 @@ export const appCredentialCommands = [
         .object({ items: z.array(metadata), page: z.number(), perPage: z.number(), total: z.number(), hasNext: z.boolean() })
         .parse(await apiGet(ctx, `${path(args.app)}?page=${flags.page}&perPage=${flags.perPage}`));
       if (!printStructured(ctx, listing))
-        ctx.table(listing.items, [
-          { key: "id", label: "ID" },
-          { key: "name", label: "Name" },
-          { key: "status", label: "Status" },
-          { key: "expiresAt", label: "Expires" },
-        ]);
+        ctx.table(
+          listing.items.map((item) => ({ ...item, status: item.serviceAccount?.status === "disabled" ? "disabled" : item.status })),
+          [
+            { key: "id", label: "ID" },
+            { key: "name", label: "Name" },
+            { key: "status", label: "Status" },
+            { key: "expiresAt", label: "Expires" },
+          ],
+        );
     },
   }),
   command("app-credentials create", {
@@ -62,8 +66,29 @@ export const appCredentialCommands = [
       if (!printStructured(ctx, result)) ctx.print(result.token);
     },
   }),
+  ...(["enable", "disable"] as const).map((action) =>
+    command(`app-credentials ${action}`, {
+      summary: `${action === "enable" ? "Enable" : "Disable"} workload issuance and calls for every instance of an app`,
+      args: { app: arg.required({ valueLabel: "app" }) },
+      flags: { yes: confirmFlag(`${action} this app's workload access`) },
+      async run({ ctx, args, flags }) {
+        if (!flags.yes)
+          throw new Error(
+            cliText(ctx, {
+              en: "Changing app workload access requires --yes.",
+              de: "App-Hintergrundzugriff ändern erfordert --yes.",
+            }),
+          );
+        const result = await apiJson(ctx, "PATCH", `${root}/${encodeURIComponent(args.app)}`, {
+          status: action === "enable" ? "active" : "disabled",
+        });
+        if (!printStructured(ctx, result))
+          ctx.print(cliText(ctx, { en: "App workload access updated.", de: "App-Hintergrundzugriff aktualisiert." }));
+      },
+    }),
+  ),
   command("app-credentials revoke", {
-    summary: "Revoke one exact app credential; its background calls will stop",
+    summary: "Revoke an app credential; runtime credentials also disable app-wide workload access",
     args: { app: arg.required({ valueLabel: "app" }), credential: arg.required({ valueLabel: "credential" }) },
     flags: { yes: confirmFlag("Revoke this app credential") },
     async run({ ctx, args, flags }) {

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

@@ -0,0 +1,226 @@
+import { createHash } from "node:crypto";
+import { chmod, chown, link, lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+import { appKeyFingerprint, deriveAppPublicKey, formatAppKey, generateAppKeyPair, validateAppKeyAppId } from "../../app-key";
+import { arg, command, confirmFlag, flag, printStructured } from "../index";
+import { apiGet, apiJson } from "./shared";
+
+const keyPath = (appId: string) => `/api/admin/apps/${encodeURIComponent(appId)}/keys`;
+const registrationSchema = z.object({
+  keyId: z.uuid(),
+  installationId: z.uuid(),
+  fingerprint: z.string().regex(/^[0-9a-f]{32}$/),
+  status: z.enum(["active", "expired", "revoked"]),
+  accountStatus: z.enum(["active", "disabled"]),
+});
+const enrollmentSchema = z
+  .object({ version: z.literal(1), server: z.string(), appId: z.string(), seed: z.string(), publicKey: z.string() })
+  .strict();
+export type AppKeyArtifactFormat = "file" | "env" | "compose" | "k8s-secret";
+
+export const renderAppKeyArtifact = (appId: string, privateKey: string, format: AppKeyArtifactFormat): string => {
+  validateAppKeyAppId(appId);
+  if (format === "file") return `${privateKey}\n`;
+  if (format === "env") return `CLOUD_APP_KEY=${privateKey}\n`;
+  if (format === "compose") return `services:\n  ${appId}:\n    environment:\n      CLOUD_APP_KEY: ${JSON.stringify(privateKey)}\n`;
+  const secretName =
+    appId.length <= 50
+      ? `${appId}-app-key`
+      : `${appId.slice(0, 40)}-${createHash("sha256").update(appId).digest("hex").slice(0, 8)}-app-key`;
+  return `apiVersion: v1\nkind: Secret\nmetadata:\n  name: ${secretName}\ntype: Opaque\nstringData:\n  CLOUD_APP_KEY: ${JSON.stringify(privateKey)}\n`;
+};
+
+const isCode = (error: unknown, code: string): boolean => error instanceof Error && "code" in error && error.code === code;
+const owner = async (path: string, uid?: number) => {
+  await chmod(path, 0o600);
+  if (uid !== undefined) await chown(path, uid, -1);
+};
+
+/** Publish the fully written, fsynced artifact atomically. Exclusive publication
+ * elects the same provisional key even when two CLI processes start together. */
+const atomicWrite = async (path: string, value: string, options: { exclusive?: boolean; uid?: number } = {}): Promise<boolean> => {
+  const temporary = `${path}.${crypto.randomUUID()}.tmp`;
+  const handle = await open(temporary, "wx", 0o600);
+  try {
+    await handle.writeFile(value, "utf8");
+    await handle.sync();
+    await owner(temporary, options.uid);
+    await handle.close();
+    let published = true;
+    if (options.exclusive) {
+      try {
+        await link(temporary, path);
+      } catch (error) {
+        if (!isCode(error, "EEXIST")) throw error;
+        published = false;
+      }
+    } else await rename(temporary, path);
+    const directory = await open(resolve(path, ".."), "r");
+    try {
+      await directory.sync();
+    } finally {
+      await directory.close();
+    }
+    return published;
+  } finally {
+    await handle.close();
+    await unlink(temporary).catch((error: unknown) => {
+      if (!isCode(error, "ENOENT")) throw error;
+    });
+  }
+};
+
+export const enrollAppKey = async (input: {
+  appId: string;
+  server: string;
+  outDir: string;
+  format: AppKeyArtifactFormat;
+  uid?: number;
+  name?: string;
+  register: (body: { publicKey: string; name?: string }) => Promise<unknown>;
+}) => {
+  validateAppKeyAppId(input.appId);
+  if (input.uid !== undefined && process.getuid?.() !== 0 && process.getuid?.() !== input.uid)
+    throw new Error("--uid requires root or the current user ID");
+  const outDir = resolve(input.outDir);
+  await mkdir(outDir, { recursive: true, mode: 0o700 });
+  const provisional = join(outDir, `.${input.appId}.enrollment.json`);
+  const extension = { file: "key", env: "env", compose: "compose.yaml", "k8s-secret": "secret.yaml" }[input.format];
+  const file = join(outDir, `${input.appId}.${extension}`);
+  const server = input.server.replace(/\/$/, "");
+  let state: z.infer<typeof enrollmentSchema>;
+  try {
+    state = enrollmentSchema.parse(JSON.parse(await readFile(provisional, "utf8")));
+  } catch (error) {
+    if (!isCode(error, "ENOENT"))
+      throw new Error(`Cannot read enrollment state for ${input.appId}; preserve it and repair the file before retrying`);
+    try {
+      await lstat(file);
+      throw new Error("Output already exists without an enrollment record; preserve it and use a new output directory");
+    } catch (error) {
+      if (!isCode(error, "ENOENT")) throw error;
+    }
+    const pair = await generateAppKeyPair();
+    await atomicWrite(provisional, JSON.stringify({ version: 1, server, appId: input.appId, ...pair }), {
+      exclusive: true,
+      uid: input.uid,
+    });
+    state = enrollmentSchema.parse(JSON.parse(await readFile(provisional, "utf8")));
+  }
+  if (state.server !== server || state.appId !== input.appId)
+    throw new Error("Enrollment belongs to a different server or app; use another output directory");
+  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 } : {}) }),
+  );
+  if (registered.fingerprint !== (await appKeyFingerprint(state.publicKey)))
+    throw new Error("Core returned a different app-key fingerprint");
+  if (registered.status !== "active")
+    throw new Error(`The enrolled key is ${registered.status}; use a new output directory to generate a replacement key`);
+  if (registered.accountStatus !== "active") throw new Error("The app service account is disabled; enable it before using this key");
+  const privateKey = formatAppKey({
+    appId: input.appId,
+    installationId: registered.installationId,
+    keyId: registered.keyId,
+    seed: state.seed,
+  });
+  await atomicWrite(file, renderAppKeyArtifact(input.appId, privateKey, input.format), { uid: input.uid });
+  // Retain the provisional seed for safe repeats after any lost API/file response.
+  // A rotation uses a new directory; repeating create never silently rotates.
+  return { appId: input.appId, ...registered, file, ...(input.format === "file" ? { environment: { CLOUD_APP_KEY_FILE: file } } : {}) };
+};
+
+export const resolveAppKeyApps = async (positional: string[], all: boolean, apps?: string): Promise<string[]> => {
+  if (all && (positional.length > 0 || !apps)) throw new Error("--all requires --apps <comma-separated-list|file> and no positional apps");
+  if (!all && apps) throw new Error("--apps requires --all");
+  let selected = positional;
+  if (all && apps) {
+    let raw: string;
+    try {
+      raw = await readFile(apps, "utf8");
+    } catch (error) {
+      if (!isCode(error, "ENOENT")) throw error;
+      raw = apps;
+    }
+    selected = raw.split(/[\s,]+/).filter(Boolean);
+  }
+  if (selected.length === 0) throw new Error("Name at least one app or use --all --apps <list|file>");
+  return [...new Set(selected.map(validateAppKeyAppId))];
+};
+
+export const appKeyCommands = [
+  command("apps keys create", {
+    summary: "Generate app keys locally and resume enrollment into owner-only files",
+    args: { apps: arg.rest({ valueLabel: "app" }) },
+    flags: {
+      all: flag.boolean({ description: "Enroll the explicit --apps list" }),
+      apps: flag.string({ description: "Comma/space-separated app IDs or a file containing that list" }),
+      outDir: flag.string({ required: true, description: "Directory for secret artifacts and resumable enrollment state" }),
+      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" }),
+    },
+    async run({ ctx, args, flags }) {
+      const apps = await resolveAppKeyApps(args.apps, flags.all, flags.apps);
+      const results = [];
+      for (const appId of apps)
+        results.push(
+          await enrollAppKey({
+            appId,
+            server: ctx.options.server,
+            outDir: flags.outDir!,
+            format: flags.format ?? "file",
+            uid: flags.uid,
+            name: flags.name,
+            register: (body) => apiJson(ctx, "POST", keyPath(appId), body),
+          }),
+        );
+      if (!printStructured(ctx, results))
+        ctx.table(results, [
+          { key: "appId", label: "App" },
+          { key: "keyId", label: "Key ID" },
+          { key: "file", label: "File" },
+        ]);
+    },
+  }),
+  command("apps keys list", {
+    summary: "List one app's public keys and lifecycle metadata",
+    args: { app: arg.required({ valueLabel: "app" }) },
+    flags: { page: flag.int({ min: 1, default: 1 }), perPage: flag.int({ min: 1, max: 500, default: 100 }) },
+    async run({ ctx, args, flags }) {
+      validateAppKeyAppId(args.app);
+      const result = z
+        .object({
+          installationId: z.uuid(),
+          items: z.array(
+            z
+              .object({ keyId: z.string(), name: z.string(), fingerprint: z.string(), status: z.string(), accountStatus: z.string() })
+              .passthrough(),
+          ),
+        })
+        .passthrough()
+        .parse(await apiGet(ctx, `${keyPath(args.app)}?page=${flags.page}&perPage=${flags.perPage}`));
+      if (!printStructured(ctx, result))
+        ctx.table(result.items, [
+          { key: "keyId", label: "Key ID" },
+          { key: "name", label: "Name" },
+          { key: "fingerprint", label: "Fingerprint" },
+          { key: "status", label: "Status" },
+          { key: "accountStatus", label: "Account" },
+        ]);
+    },
+  }),
+  command("apps keys revoke", {
+    summary: "Revoke one app key idempotently",
+    args: { app: arg.required({ valueLabel: "app" }), keyId: arg.required({ valueLabel: "keyId" }) },
+    flags: { yes: confirmFlag("Revoke this app key") },
+    async run({ ctx, args, flags }) {
+      if (!flags.yes) throw new Error("Revoking an app key requires --yes");
+      validateAppKeyAppId(args.app);
+      const result = await apiJson(ctx, "DELETE", `${keyPath(args.app)}/${z.uuid().parse(args.keyId)}`);
+      if (!printStructured(ctx, result)) ctx.print("App key revoked.");
+    },
+  }),
+];