@k2b/cloud 0.46.0 → 0.47.0

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

package/src/config/define-env.ts

@@ -4,10 +4,12 @@
  * Every runtime environment variable is declared once with a schema, a
  * default, a scope and a one-sentence doc. Registries read `process.env`
  * lazily: each key is parsed on access, so tests can change variables and
- * consumers never depend on an import-time snapshot. `.env.example`,
+ * consumers never depend on an import-time snapshot. Configured secret files
+ * are also validated when the registry is created. `.env.example`,
  * `.env.prod.example` and the configuration reference are generated from the
  * `$specs` of every registry by `scripts/generate-config-docs.ts`.
  */
+import { readFileSync } from "node:fs";
 import { z } from "zod";
 
 /**
@@ -17,7 +19,7 @@ import { z } from "zod";
 export type EnvScope = "runtime" | "secret" | "development";
 
 export type EnvSpec<T> = {
-  /** Parses the trimmed raw value. Empty and unset values never reach the schema. */
+  /** Parses the raw value (trimmed for env, one trailing newline removed for files). Empty and unset values never reach the schema. */
   schema: z.ZodType<T, unknown>;
   /** Used when the variable is unset or empty; a function is evaluated on every access. */
   default?: T | (() => T);
@@ -31,6 +33,8 @@ export type EnvSpec<T> = {
   required?: boolean;
   /** Alternative variable names, consulted after the canonical key. */
   aliases?: string[];
+  /** Allow NAME_FILE to supply the secret. Configured files are validated when the registry is created. */
+  secretFile?: boolean;
 };
 
 export type EnvSpecs = Record<string, EnvSpec<unknown>>;
@@ -42,20 +46,59 @@ type EnvValue<S extends EnvSpec<unknown>> = S extends { default: unknown } | { r
 export type EnvRegistry<S extends EnvSpecs> = { readonly [K in keyof S]: EnvValue<S[K]> } & {
   readonly $specs: S;
   readonly $keys: readonly string[];
+  /** Read only an explicitly supplied value, without the code default. */
+  readonly $readPresent: <K extends keyof S & string>(key: K) => z.output<S[K]["schema"]> | undefined;
 };
 
-const rawValue = (key: string, aliases: string[] = []): string | undefined => {
-  for (const name of [key, ...aliases]) {
+/** Effective value source; empty values fall through to the default or unset. */
+export type EnvSource = "env" | "alias" | "file" | "default" | "unset";
+
+type RawEnv = { value: string | undefined; source: "env" | "alias" | "file" | "unset" };
+
+// A mounted secret is a startup input, not a live configuration channel. A new
+// path is still observed when tests or tooling deliberately change process.env.
+const fileValues = new WeakMap<EnvSpec<unknown>, { path: string; value: string }>();
+
+const rawValue = (key: string, spec: EnvSpec<unknown>): RawEnv => {
+  const names = [key, ...(spec.aliases ?? [])];
+  const fileKey = `${key}_FILE`;
+  const path = spec.secretFile ? process.env[fileKey]?.trim() || undefined : undefined;
+  if (path !== undefined) {
+    const conflict = names.find((name) => process.env[name]?.trim());
+    if (conflict) throw new Error(`${conflict} and ${fileKey} must not both be set`);
+    const cached = fileValues.get(spec);
+    let value = cached?.path === path ? cached.value : undefined;
+    if (value === undefined) {
+      try {
+        value = readFileSync(path, "utf8");
+      } catch {
+        // File errors must identify the source without including contents or an underlying error.
+        throw new Error(`${fileKey} could not read file ${JSON.stringify(path)}`);
+      }
+      if (value.endsWith("\r\n")) value = value.slice(0, -2);
+      else if (value.endsWith("\n")) value = value.slice(0, -1);
+      fileValues.set(spec, { path, value });
+    }
+    return { value: value === "" ? undefined : value, source: value === "" ? "unset" : "file" };
+  }
+  for (const name of names) {
     const value = process.env[name]?.trim();
-    if (value) return value;
+    if (value) return { value, source: name === key ? "env" : "alias" };
   }
-  return undefined;
+  return { value: undefined, source: "unset" };
+};
+
+/** Inspect the effective source without evaluating defaults; invalid file configuration throws as on value access. */
+export const envSource = <S extends EnvSpecs>(registry: EnvRegistry<S>, key: keyof S & string): EnvSource => {
+  const spec = registry.$specs[key]!;
+  const { source } = rawValue(key, spec);
+  return source === "unset" && spec.default !== undefined ? "default" : source;
 };
 
 const isFactory = <T>(value: T | (() => T)): value is () => T => typeof value === "function";
 
 export const readEnv = <T>(key: string, spec: EnvSpec<T>): T | undefined => {
-  const raw = rawValue(key, spec.aliases);
+  const { value: raw } = rawValue(key, spec);
   if (raw === undefined) {
     if (spec.default !== undefined) return isFactory(spec.default) ? spec.default() : spec.default;
     if (spec.required) throw new Error(`${key} is required`);
@@ -63,6 +106,7 @@ export const readEnv = <T>(key: string, spec: EnvSpec<T>): T | undefined => {
   }
   const parsed = spec.schema.safeParse(raw);
   if (!parsed.success) {
+    if (spec.secretFile) throw new Error(`${key} is invalid`);
     const reason = parsed.error.issues.map((issue) => issue.message).join("; ") || "is invalid";
     throw new Error(`${key} ${reason}`);
   }
@@ -71,8 +115,19 @@ export const readEnv = <T>(key: string, spec: EnvSpec<T>): T | undefined => {
 
 export const defineEnv = <S extends EnvSpecs>(specs: S): EnvRegistry<S> => {
   const keys = Object.freeze(Object.keys(specs));
-  const registry: Record<string, unknown> = { $specs: specs, $keys: keys };
+  const registry: Record<string, unknown> = {
+    $specs: specs,
+    $keys: keys,
+    $readPresent: (key: string) => {
+      const spec = specs[key];
+      if (!spec) throw new Error(`Unknown environment variable: ${key}`);
+      return readEnv(key, { ...spec, default: undefined, required: false });
+    },
+  };
   for (const key of keys) {
+    const spec = specs[key]!;
+    // Fail during module initialization, even when this secret is first used by a later request.
+    if (spec.secretFile && process.env[`${key}_FILE`]?.trim()) readEnv(key, spec);
     Object.defineProperty(registry, key, { enumerable: true, configurable: true, get: () => readEnv(key, specs[key]!) });
   }
   // The getters above are the only way to build a typed lazy object.

package/src/config/env.ts

@@ -4,23 +4,14 @@
  * `src/env.ts`; values are parsed lazily on access (see `define-env.ts`).
  */
 import { z } from "zod";
+import { DEFAULT_TRUSTED_PROXIES } from "../services/settings/validation";
 import { defineEnv, envBoolean, envList } from "./define-env";
+import { DEFAULT_WORKFLOW_AI_BUDGET, workflowAiBudgetSchema } from "./workflow-ai";
 
 const syncReplicas = z
   .enum(["1", "3", "5"], { error: "must be 1, 3, or 5" })
   .transform((value): 1 | 3 | 5 => (value === "1" ? 1 : value === "3" ? 3 : 5));
 
-const budgetSchema = z
-  .object({
-    maxStepsPerSource: z.number().int().positive(),
-    tasksPerMinute: z.number().int().positive(),
-    burst: z.number().int().positive(),
-    sourcesPer24Hours: z.number().int().positive(),
-    scopeConcurrent: z.number().int().positive(),
-    globalConcurrent: z.number().int().positive(),
-  })
-  .strict();
-
 const registry = defineEnv({
   // Process
   NODE_ENV: {
@@ -35,6 +26,7 @@ const registry = defineEnv({
   // Infrastructure
   DATABASE_URL: {
     schema: z.string(),
+    aliases: ["DATABASEURL", "TLS_DATABASE_URL", "POSTGRES_URL", "PGURL", "PG_URL", "TLS_POSTGRES_DATABASE_URL"],
     example: "postgresql://ipa:ipa@localhost:5432/ipa",
     doc: "Postgres connection read by Bun SQL and by application-owned pools.",
   },
@@ -54,7 +46,7 @@ const registry = defineEnv({
     schema: z.string(),
     default: "",
     example: "dev",
-    doc: "Sync namespace shared by every app of one installation; isolates its NATS resources from other installations on the same cluster.",
+    doc: "Sync namespace shared by every app of one installation; separates NATS resource names, not access. Use one NATS account per installation.",
   },
   SYNC_REPLICAS: {
     schema: syncReplicas,
@@ -88,9 +80,9 @@ const registry = defineEnv({
           return z.NEVER;
         }
       })
-      .pipe(budgetSchema),
-    default: { maxStepsPerSource: 2, tasksPerMinute: 10, burst: 20, sourcesPer24Hours: 2_000, scopeConcurrent: 1, globalConcurrent: 4 },
-    doc: "JSON scoped workflow inference budget: active or successful logical requests per source/24h, token-bucket admission per minute and burst, distinct sources per rolling 24h, outstanding tasks per scope and globally; capacity/rate overload uses bounded workflow retries, daily/source limits fail visibly, and cache hits consume no reservation.",
+      .pipe(workflowAiBudgetSchema),
+    default: DEFAULT_WORKFLOW_AI_BUDGET,
+    doc: "Deprecated: bootstraps `ai.workflow_budget` once when no stored value exists; remove after `cld admin settings status --env` succeeds. JSON scoped workflow inference budget: active or successful logical requests per source/24h, token-bucket admission per minute and burst, distinct sources per rolling 24h, outstanding tasks per scope and globally; capacity/rate overload uses bounded workflow retries, daily/source limits fail visibly, and cache hits consume no reservation.",
   },
 
   // Workflow inference: p95 ~4s in the pilot; 60s bounds a whole attempt,
@@ -98,12 +90,12 @@ const registry = defineEnv({
   WORKFLOW_AI_ATTEMPT_TIMEOUT_MS: {
     schema: z.coerce.number().int().positive(),
     default: 60_000,
-    doc: "Absolute workflow AI attempt budget in milliseconds, including admission and repair; expiry aborts the provider and follows the bounded retry policy.",
+    doc: "Deprecated: bootstraps `ai.workflow_attempt_timeout_ms` once when no stored value exists; remove after `cld admin settings status --env` succeeds. Absolute workflow AI attempt budget in milliseconds, including admission and repair; expiry aborts the provider and follows the bounded retry policy.",
   },
   WORKFLOW_AI_QUEUE_TIMEOUT_MS: {
     schema: z.coerce.number().int().positive(),
     default: 60_000,
-    doc: "Maximum workflow AI queue wait in milliseconds; recovery fails overdue or lost deliveries visibly so an operator can retry the workflow.",
+    doc: "Deprecated: bootstraps `ai.workflow_queue_timeout_ms` once when no stored value exists; remove after `cld admin settings status --env` succeeds. Maximum workflow AI queue wait in milliseconds; recovery fails overdue or lost deliveries visibly so an operator can retry the workflow.",
   },
 
   // Installation
@@ -115,12 +107,13 @@ const registry = defineEnv({
   GOTENBERG_URL: {
     schema: z.string(),
     example: "http://localhost:3001",
-    doc: "Internal Gotenberg base URL used to bootstrap the `gotenberg.url` PDF rendering setting; the stored setting wins once written.",
+    doc: "Deprecated: env only bootstraps `gotenberg.url`; remove after `cld admin settings status --env` succeeds. Internal Gotenberg base URL used to bootstrap the `gotenberg.url` PDF rendering setting; the stored setting wins once written.",
   },
   APP_SECRET: {
     schema: z.string(),
     default: "",
     scope: "secret",
+    secretFile: true,
     example: "change-me-generate-with-openssl-rand-hex-32",
     doc: "Deployment-wide secret for at-rest settings encryption and signed cursors; generate once with `openssl rand -hex 32` and never change it after data has been written.",
   },
@@ -128,37 +121,49 @@ const registry = defineEnv({
     schema: z.string(),
     default: "",
     scope: "secret",
+    secretFile: true,
     doc: "Core only: temporary first-administrator or recovery login token; remove it after normal administrator sign-in works.",
   },
 
+  // Gateway trust boundary
+  GATEWAY_TRUSTED_PROXIES: {
+    schema: envList,
+    default: DEFAULT_TRUSTED_PROXIES,
+    doc: "Deprecated: bootstraps `gateway.trusted_proxies` once when no stored value exists; remove after `cld admin settings status --env` succeeds. Comma-separated IP addresses or CIDR ranges of the reverse proxies allowed to name the client in `X-Forwarded-For`; the default trusts loopback and private networks, which covers Traefik on a Docker network. Set the proxy's exact address or subnet when clients on private networks reach the gateway directly or through a proxy that appends to their `X-Forwarded-For`. Invalid bootstrap input with no stored row and invalid stored proxy lists stop gateway startup.",
+  },
+
   // Outbound network
   OUTGOING_MAIL_ALLOWED_TARGETS: {
     schema: envList,
     default: [],
     scope: "runtime",
-    doc: "Comma-separated host names, IP addresses and CIDR ranges on internal networks allowed for outgoing mail SMTP and bounce IMAP connections; unset allows only public targets, an explicit value replaces this default, and invalid entries including `/0` stop the owning process at startup.",
+    doc: "Deprecated: bootstraps `outgoing_mail.allowed_targets` once when no stored value exists; remove after `cld admin settings status --env` succeeds. Comma-separated host names, IP addresses and CIDR ranges on internal networks allowed for outgoing mail SMTP and bounce IMAP connections; unset allows only public targets, an explicit value replaces this default, and invalid entries including `/0` are ignored with a bootstrap warning.",
   },
 
   // Identity and OAuth
   CLOUD_IDENTITY_KEY_ENCRYPTION_KEY: {
     schema: z.string(),
     scope: "secret",
+    secretFile: true,
     example: "change-me-generate-with-openssl-rand-hex-32",
     doc: "Core only: 64-hex KEK for platform identity signing keys stored in Postgres; generate once with `openssl rand -hex 32` and never distribute it to other apps.",
   },
   CLOUD_IDENTITY_NEXT_KEY: {
     schema: z.string(),
     scope: "secret",
+    secretFile: true,
     doc: "Core only: pre-distributed next KEK before promoting it to current; cannot be combined with `CLOUD_IDENTITY_PREVIOUS_KEY`.",
   },
   CLOUD_IDENTITY_PREVIOUS_KEY: {
     schema: z.string(),
     scope: "secret",
+    secretFile: true,
     doc: "Core only: old KEK set during an explicit rolling rewrap of stored identity signing keys, then removed.",
   },
   CLOUD_OAUTH_BROKER_SECRET: {
     schema: z.string(),
     scope: "secret",
+    secretFile: true,
     doc: "Core and OAuth only: 64-hex secret that lets the OAuth app request token signatures from Core; generate independently with `openssl rand -hex 32`.",
   },
   CLOUD_CORE_INTERNAL_ORIGIN: {
@@ -168,11 +173,12 @@ const registry = defineEnv({
   CLOUD_APP_CREDENTIAL: {
     schema: z.string(),
     scope: "secret",
-    doc: "App-bound workload credential provisioned through Core's admin workload API; background apps such as Mail need one with `identity:invoke`.",
+    secretFile: true,
+    doc: "Optional host-run app override for the automatically delivered app workload credential; provision through Core's admin workload API with `identity:invoke`.",
   },
   CLOUD_IDENTITY_JWKS_ORIGIN: {
     schema: z.string(),
-    doc: "Optional private origin of the Core listener for session and invocation JWKS; unset fetches keys from the public issuer origin.",
+    doc: "Deprecated: use `CLOUD_CORE_INTERNAL_ORIGIN`; the explicit old origin remains honored for this release. Optional private origin of the Core listener for session and invocation JWKS; unset uses `CLOUD_CORE_INTERNAL_ORIGIN`, then the public issuer origin.",
   },
   CLOUD_OAUTH_JWKS_ORIGIN: {
     schema: z.string(),

package/src/config/index.ts

@@ -4,5 +4,16 @@
  * by application `src/env.ts` files. SSR config is per-app via defineApp().
  */
 
-export { defineEnv, type EnvRegistry, type EnvScope, type EnvSpec, type EnvSpecs, envBoolean, envList, envString } from "./define-env";
+export {
+  defineEnv,
+  type EnvRegistry,
+  type EnvScope,
+  type EnvSource,
+  type EnvSpec,
+  type EnvSpecs,
+  envBoolean,
+  envList,
+  envSource,
+  envString,
+} from "./define-env";
 export { env } from "./env";

package/src/config/workflow-ai.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+export const workflowAiBudgetSchema = z
+  .object({
+    maxStepsPerSource: z.number().int().positive(),
+    tasksPerMinute: z.number().int().positive(),
+    burst: z.number().int().positive(),
+    sourcesPer24Hours: z.number().int().positive(),
+    scopeConcurrent: z.number().int().positive(),
+    globalConcurrent: z.number().int().positive(),
+  })
+  .strict();
+export const DEFAULT_WORKFLOW_AI_BUDGET = {
+  maxStepsPerSource: 2,
+  tasksPerMinute: 10,
+  burst: 20,
+  sourcesPer24Hours: 2_000,
+  scopeConcurrent: 1,
+  globalConcurrent: 4,
+};
+export const validateWorkflowAiBudget = (value: unknown): string | undefined => {
+  try {
+    if (typeof value === "string" && workflowAiBudgetSchema.safeParse(JSON.parse(value)).success) return;
+  } catch {
+    /* invalid JSON */
+  }
+  return "Workflow AI budget must be a JSON object with positive whole numbers for maxStepsPerSource, tasksPerMinute, burst, sourcesPer24Hours, scopeConcurrent and globalConcurrent, without extra fields";
+};