@k2b/cloud 0.45.0 → 0.47.0

package/src/capabilities/server-invoke.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { refreshAppWorkloadCredential } from "../_internal/workload-credential";
 import { dispatchCapability, loadCapabilityCatalogPage } from "../api/capabilities";
 import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
@@ -35,6 +36,8 @@ 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. */
+  workload?: { appId: string };
   /** Durable background authority. `authorization` must be the owning app's workload credential. */
   mandate?: { id: string; revision: number; callingAppId: string };
 };
@@ -49,7 +52,7 @@ export const callerRequest = async (
 ): Promise<Request> => {
   const headers = new Headers();
   if (caller.authorization) headers.set("authorization", caller.authorization);
-  if (!caller.mandate) {
+  if (!caller.mandate && !caller.workload) {
     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);
@@ -57,10 +60,14 @@ 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);
+    headers.set("x-cloud-app-id", caller.mandate?.callingAppId ?? caller.workload!.appId);
   }
   const signal = combineCapabilitySignals(caller.signal, invocationSignal);
-  return new Request(new URL(path, await coreOrigin(caller.mandate !== undefined)), { method: "POST", headers, signal });
+  return new Request(new URL(path, await coreOrigin(caller.mandate !== undefined || caller.workload !== undefined)), {
+    method: "POST",
+    headers,
+    signal,
+  });
 };
 
 export const unavailable = (
@@ -96,12 +103,15 @@ const invokeCapabilityWithResultSchema = async <TDataSchema extends z.ZodType, T
   caller: CapabilityCaller,
 ): Promise<CapabilityClientResult<z.output<TDataSchema>>> => {
   try {
-    const path = caller.mandate
-      ? "/api/_internal/identity/v1/invoke"
-      : `/api/capabilities/v1/${invocation.kind === "query" ? "queries" : "actions"}/${encodeURIComponent(invocation.appId)}/${encodeURIComponent(invocation.capabilityId)}`;
+    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
+        ? "/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.transport)
+      if (caller.authorization || caller.cookie || caller.mandate || caller.workload || caller.transport)
         throw new Error("Use exactly one capability authority source");
       const outcome = await dispatchCapability({
         request,
@@ -115,33 +125,51 @@ const invokeCapabilityWithResultSchema = async <TDataSchema extends z.ZodType, T
       });
       return readCapabilityResponse(outcome, capabilityResultSchema(dataSchema, { consumer: true }));
     }
-    const response = await (caller.transport ?? fetch)(
-      new Request(request, {
-        body: JSON.stringify(
-          caller.mandate
-            ? {
-                kind: invocation.kind,
-                targetApp: invocation.appId,
-                capabilityId: invocation.capabilityId,
-                input: invocation.input,
-                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 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);
+      }
+    }
     return readCapabilityResponse(response, capabilityResultSchema(dataSchema, { consumer: true }));
   } catch (cause) {
     return unavailable(cause, invocation, caller.locale ?? undefined);
@@ -174,14 +202,14 @@ 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.transport))
+      if (caller.authority && (caller.authorization || caller.cookie || 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) throw new Error("Calendar discovery requires request credentials");
+      if (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

@@ -1,4 +1,8 @@
-import { resolveCapabilityActionWording, resolveCapabilityManifestPresentation } from "../_internal/capabilities";
+import {
+  isPersonVisibleCapabilityQuery,
+  resolveCapabilityActionWording,
+  resolveCapabilityManifestPresentation,
+} from "../_internal/capabilities";
 import type { CapabilityActionWording } from "../_internal/capability-sentences";
 import { getApp, getCapability } from "../_internal/registry";
 import { dispatchCapability } from "../api/capabilities";
@@ -37,18 +41,22 @@ export const getCapabilityCatalogApp = async (
   try {
     const [capability, registeredApp] = await Promise.all([getCapability(appId), getApp(appId)]);
     const presentedApp = registeredApp && locale ? resolveAppPresentation(registeredApp, locale) : registeredApp;
+    const manifest =
+      capability &&
+      (locale ? resolveCapabilityManifestPresentation(capability.manifest, capability.presentation, locale) : capability.manifest);
     return {
       ok: true,
       data:
-        capability && registeredApp && (await canUseApp(authority, registeredApp))
+        capability && registeredApp && manifest && (await canUseApp(authority, registeredApp))
           ? {
               appId: capability.appId,
               appName: presentedApp?.name ?? capability.appName,
               appIcon: capability.appIcon,
               appDescription: presentedApp?.description ?? capability.appDescription,
-              manifest: locale
-                ? resolveCapabilityManifestPresentation(capability.manifest, capability.presentation, locale)
-                : capability.manifest,
+              manifest: {
+                ...manifest,
+                queries: manifest.queries.filter(isPersonVisibleCapabilityQuery),
+              },
             }
           : null,
     };
@@ -81,6 +89,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.authority) {
       if (caller.authorization || caller.cookie || caller.mandate || caller.transport)
         throw new Error("Use exactly one capability authority source");
@@ -132,7 +141,7 @@ export async function transferCapabilityStream(
   caller: CapabilityCaller,
   body?: BodyInit,
 ): Promise<Response> {
-  if (caller.mandate) throw new Error("Capability streams do not support background mandates yet");
+  if (caller.mandate || caller.workload) throw new Error("Capability streams require request authority");
   const path = `/api/capabilities/v1/streams/${verb}`;
   const headers = new Headers();
   headers.set("x-cloud-stream-id", stream.id);
@@ -172,6 +181,8 @@ export {
   listCalendarSources,
   readCalendarEvents,
 } from "./calendar-sources";
+export { type DiscussionProvider, discussionProviders } from "./discussion-providers";
+export { ResourceReaderRateLimited, type ResourceReadersResult, readResourcePrincipals } from "./resource-readers";
 export {
   actionReview,
   type CapabilityReviewForms,

package/src/capabilities/testing.ts

@@ -14,6 +14,8 @@ import {
   type CapabilityResult,
   CapabilitySemanticLinkSchema,
   type CapabilitySlot,
+  CloudResourceReaderViewSchema,
+  type CloudResourceRef,
 } from "../contracts/capabilities";
 
 /** Compile and validate the public manifest an app would register at startup. */
@@ -36,6 +38,17 @@ export const assertResourceOpenLink = (result: Pick<CapabilityResult<unknown>, "
   return CapabilitySemanticLinkSchema.parse(link);
 };
 
+/** Assert the canonical reader presentation and, for contained types, its exact container. */
+export const assertResourceView = (result: Pick<CapabilityResult<unknown>, "data">, container?: CloudResourceRef) => {
+  const data = result.data;
+  const view = CloudResourceReaderViewSchema.parse(
+    data !== null && typeof data === "object" ? Object.getOwnPropertyDescriptor(data, "view")?.value : undefined,
+  );
+  if (container && (view.container?.ref.type !== container.type || view.container.ref.id !== container.id))
+    throw new Error("Resource reader view must identify the expected container");
+  return view;
+};
+
 /** Validate each localized review in application tests, with optional declaration context. */
 export const assertCapabilityReview = (review: unknown, context?: CapabilityReviewContext): void => {
   const parsed = CapabilityActionReviewDataSchema.safeParse(review);

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-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.");
+    },
+  }),
+];

package/src/cli/admin/index.ts

@@ -14,6 +14,7 @@ import { aiQuotaCommands } from "./ai-quotas";
 import { aiSkillCommands } from "./ai-skills";
 import { aiUsageCommands } from "./ai-usage";
 import { appCredentialCommands } from "./app-credentials";
+import { appKeyCommands } from "./app-keys";
 import { appSignInCommands } from "./app-sign-in";
 import { dataCommands } from "./data";
 import { documentationCommands } from "./documentation";
@@ -28,6 +29,7 @@ import { metricsCommands } from "./metrics";
 import { natsCommands } from "./nats";
 import { notificationCommands } from "./notifications";
 import { outgoingMailCommands } from "./outgoing-mail";
+import { settingsCommands } from "./settings";
 import { syncCommands } from "./sync";
 import { telemetryCommands } from "./telemetry";
 import { webhookCommands } from "./webhooks";
@@ -51,7 +53,8 @@ export default defineCliCommands({
     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 and remove registered apps.",
+    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.",
@@ -71,6 +74,7 @@ export default defineCliCommands({
     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.",
@@ -90,6 +94,7 @@ export default defineCliCommands({
   },
   commands: [
     ...appCredentialCommands,
+    ...appKeyCommands,
     ...agentCommands,
     ...documentationCommands,
     ...appSignInCommands,
@@ -115,5 +120,6 @@ export default defineCliCommands({
     ...metricsCommands,
     ...natsCommands,
     ...syncCommands,
+    ...settingsCommands,
   ],
 });

package/src/cli/admin/settings.ts

@@ -0,0 +1,62 @@
+import { EnvSettingsStatusSchema } from "../../contracts/settings-env";
+import { arg, command, confirmFlag, flag, printStructured } from "../index";
+import { apiGet, apiJson } from "./shared";
+
+export const settingsCommands = [
+  command("settings status", {
+    summary: "Check environment-backed settings across registered processes without printing values",
+    flags: { env: flag.boolean({ description: "Check stored values against each running application's environment" }) },
+    async run({ ctx, flags }) {
+      if (!flags.env) throw new Error("Use settings status --env.");
+      const result = EnvSettingsStatusSchema.parse(await apiGet(ctx, "/api/admin/core/settings/env/status"));
+      if (!printStructured(ctx, result)) {
+        for (const process of result.processes) {
+          ctx.print(`${process.appId}: ${process.status}`);
+          ctx.table(
+            process.settings,
+            [
+              "key",
+              "envVariable",
+              "storedValuePresent",
+              "envValuePresent",
+              "conflict",
+              "unreadableStoredValue",
+              "invalidEnvValue",
+              "needsAttention",
+            ].map((key) => ({ key })),
+          );
+        }
+      }
+      return result.needsAttention ? 1 : 0;
+    },
+  }),
+  command("settings set", {
+    summary: "Set a whole administrator setting value",
+    args: { key: arg.required() },
+    flags: {
+      value: flag.string({ required: true, description: "JSON value (quote a text value as JSON)" }),
+      app: flag.string({ description: "Owning application ID; omit for platform settings" }),
+      replaceUnreadable: flag.boolean({ description: "Explicitly replace an unreadable stored row with this whole value" }),
+      yes: confirmFlag("Confirm setting change"),
+    },
+    async run({ ctx, args, flags }) {
+      if (!flags.yes) throw new Error("Setting changes require --yes.");
+      let value: unknown;
+      try {
+        value = JSON.parse(flags.value ?? "");
+      } catch {
+        throw new Error("--value must be valid JSON.");
+      }
+      const result = flags.app
+        ? await apiJson(ctx, "PUT", `/api/admin/core/settings/env/${encodeURIComponent(flags.app)}/${encodeURIComponent(args.key)}`, {
+            value,
+            replaceUnreadable: flags.replaceUnreadable,
+          })
+        : await apiJson(ctx, "PUT", "/api/admin/core/settings", {
+            updates: { [args.key]: value },
+            replaceUnreadable: flags.replaceUnreadable ? [args.key] : [],
+          });
+      if (!printStructured(ctx, result)) ctx.print("Setting saved.");
+    },
+  }),
+];