@k2b/cloud 0.46.0 → 0.48.0

package/src/cli/admin/index.ts

@@ -5,7 +5,9 @@
  * them. The groups map to the admin UI areas, so a command and the page that
  * shows the same data stay easy to find together.
  */
+
 import { defineCliCommands } from "../commands";
+import { type CloudCliContext, localizeCloudCliText } from "../index";
 import { accountAdministrationCommands } from "./account-administration";
 import { accountCategoryCommands } from "./account-categories";
 import { agentCommands } from "./agents";
@@ -14,6 +16,8 @@ import { aiQuotaCommands } from "./ai-quotas";
 import { aiSkillCommands } from "./ai-skills";
 import { aiUsageCommands } from "./ai-usage";
 import { appCredentialCommands } from "./app-credentials";
+import { appDomainCommands } from "./app-domains";
+import { appKeyCommands } from "./app-keys";
 import { appSignInCommands } from "./app-sign-in";
 import { dataCommands } from "./data";
 import { documentationCommands } from "./documentation";
@@ -28,92 +32,113 @@ 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";
 import { workflowCommands } from "./workflows";
 
-export default defineCliCommands({
-  name: "admin",
-  summary: "Inspect and operate Cloud administration surfaces.",
-  groupSummaries: {
-    accounts: "Manage account policy and account administration.",
-    ai: "Manage AI models, quotas, Skills, and usage.",
-    "ai models": "Manage AI model configuration.",
-    "ai providers": "Manage AI provider connections.",
-    "ai variants": "Manage named model variants.",
-    "ai classes": "Manage model classes and tools.",
-    "ai quotas background": "Inspect and release the background emergency stop.",
-    "ai skills": "Inspect Assistant Skills and trusted templates.",
-    "ai usage": "Inspect AI runs and usage facets.",
-    announcements: "Manage platform announcements and banners.",
-    "app-credentials": "Manage per-application credentials for background work.",
-    agents: "Create, list, revoke, and re-key agent accounts with OAuth client credentials, and change their pictures.",
-    "agents avatar": "Show and change an agent's picture: its robot parts or a photo.",
-    "app-sign-in": "Manage app sign-in and pairing.",
-    apps: "Inspect and remove registered apps.",
-    documentation: "Manage the administration documentation website.",
-    geoip: "Replace and inspect sign-in location databases.",
-    jobs: "Inspect background jobs and their runs.",
-    logs: "Search, inspect, and clean up retained logs.",
-    metrics: "Inspect collectors and manage metrics access.",
-    "metrics tokens": "Manage metrics bearer tokens.",
-    nats: "Inspect NATS nodes, streams, and consumers.",
-    "nats consumers": "Inspect NATS consumers.",
-    "nats streams": "Find NATS streams and buckets.",
-    "notification-batches": "Manage account notification batches.",
-    "outgoing-mail": "Manage outgoing mail sender profiles, application access, and the send log.",
-    "outgoing-mail profiles": "Manage outgoing mail sender profiles.",
-    "outgoing-mail apps": "Manage application outgoing mail access.",
-    "outgoing-mail log": "Read and cancel application mail in the send log.",
-    "outgoing-mail retention": "Show or change how long the send log keeps mail.",
-    notifications: "Inspect and resend email notifications.",
-    postgres: "Inspect Postgres diagnostics.",
-    redis: "Inspect Valkey diagnostics.",
-    routes: "Inspect gateway routes.",
-    sync: "Inspect Sync resources, schedules, and dead letters.",
-    "sync dead-letters": "Inspect, replay, requeue, or remove dead letters.",
-    "sync resources": "List Sync resource declarations.",
-    "sync schedules": "Inspect and run Sync schedules.",
-    "sync schedules runs": "Read Sync schedule run results.",
-    telemetry: "Inspect request telemetry.",
-    webhooks: "Manage gateway health webhooks.",
-    workflows: "Inspect and operate workflow runs and effects.",
-    "app-sign-in config": "Manage the trusted app website and pairing policy.",
-    "accounts config": "Manage account types and sign-in visibility.",
-    "accounts administration": "Manage account requests and account/group follow-up notices.",
-    "ai quotas": "Manage direct Assistant chat limits and consumption.",
-    "ai quotas config": "Export and replace quota policies with revision checks.",
-    legal: "Manage Terms, Privacy, and Imprint.",
-    linux: "Prepare Linux identities.",
-    "linux config": "Manage Linux identity defaults and allocation range.",
-  },
-  commands: [
-    ...appCredentialCommands,
-    ...agentCommands,
-    ...documentationCommands,
-    ...appSignInCommands,
-    ...accountCategoryCommands,
-    ...accountAdministrationCommands,
-    ...aiUsageCommands,
-    ...aiModelCommands,
-    ...aiQuotaCommands,
-    ...aiSkillCommands,
-    ...instanceCommands,
-    ...gatewayCommands,
-    ...logCommands,
-    ...telemetryCommands,
-    ...jobCommands,
-    ...legalCommands,
-    ...geoipCommands,
-    ...linuxCommands,
-    ...workflowCommands,
-    ...dataCommands,
-    ...notificationCommands,
-    ...outgoingMailCommands,
-    ...webhookCommands,
-    ...metricsCommands,
-    ...natsCommands,
-    ...syncCommands,
-  ],
-});
+const build = (locale?: string) =>
+  defineCliCommands({
+    name: "admin",
+    summary: "Inspect and operate Cloud administration surfaces.",
+    groupSummaries: {
+      accounts: "Manage account policy and account administration.",
+      ai: "Manage AI models, quotas, Skills, and usage.",
+      "ai models": "Manage AI model configuration.",
+      "ai providers": "Manage AI provider connections.",
+      "ai variants": "Manage named model variants.",
+      "ai classes": "Manage model classes and tools.",
+      "ai quotas background": "Inspect and release the background emergency stop.",
+      "ai skills": "Inspect Assistant Skills and trusted templates.",
+      "ai usage": "Inspect AI runs and usage facets.",
+      announcements: "Manage platform announcements and banners.",
+      "app-credentials": "Manage per-application credentials for background work.",
+      agents: "Create, list, revoke, and re-key agent accounts with OAuth client credentials, and change their pictures.",
+      "agents avatar": "Show and change an agent's picture: its robot parts or a photo.",
+      "app-sign-in": "Manage app sign-in and pairing.",
+      apps: localizeCloudCliText(locale, {
+        en: "Inspect registered apps and manage app keys and domains.",
+        de: "Registrierte Apps prüfen und App-Schlüssel und App-Domains verwalten.",
+      }),
+      "apps domains": localizeCloudCliText(locale, {
+        en: "Assign app domains and inspect DNS, TLS and gateway reachability.",
+        de: "App-Domains zuordnen und DNS, TLS und Gateway-Erreichbarkeit prüfen.",
+      }),
+      "apps keys": "Create, list, and revoke Ed25519 app keys.",
+      documentation: "Manage the administration documentation website.",
+      geoip: "Replace and inspect sign-in location databases.",
+      jobs: "Inspect background jobs and their runs.",
+      logs: "Search, inspect, and clean up retained logs.",
+      metrics: "Inspect collectors and manage metrics access.",
+      "metrics tokens": "Manage metrics bearer tokens.",
+      nats: "Inspect NATS nodes, streams, and consumers.",
+      "nats consumers": "Inspect NATS consumers.",
+      "nats streams": "Find NATS streams and buckets.",
+      "notification-batches": "Manage account notification batches.",
+      "outgoing-mail": "Manage outgoing mail sender profiles, application access, and the send log.",
+      "outgoing-mail profiles": "Manage outgoing mail sender profiles.",
+      "outgoing-mail apps": "Manage application outgoing mail access.",
+      "outgoing-mail log": "Read and cancel application mail in the send log.",
+      "outgoing-mail retention": "Show or change how long the send log keeps mail.",
+      notifications: "Inspect and resend email notifications.",
+      postgres: "Inspect Postgres diagnostics.",
+      redis: "Inspect Valkey diagnostics.",
+      routes: "Inspect gateway routes.",
+      settings: "Inspect environment migration and change administrator settings.",
+      sync: "Inspect Sync resources, schedules, and dead letters.",
+      "sync dead-letters": "Inspect, replay, requeue, or remove dead letters.",
+      "sync resources": "List Sync resource declarations.",
+      "sync schedules": "Inspect and run Sync schedules.",
+      "sync schedules runs": "Read Sync schedule run results.",
+      telemetry: "Inspect request telemetry.",
+      webhooks: "Manage gateway health webhooks.",
+      workflows: "Inspect and operate workflow runs and effects.",
+      "app-sign-in config": "Manage the trusted app website and pairing policy.",
+      "accounts config": "Manage account types and sign-in visibility.",
+      "accounts administration": "Manage account requests and account/group follow-up notices.",
+      "ai quotas": "Manage direct Assistant chat limits and consumption.",
+      "ai quotas config": "Export and replace quota policies with revision checks.",
+      legal: "Manage Terms, Privacy, and Imprint.",
+      linux: "Prepare Linux identities.",
+      "linux config": "Manage Linux identity defaults and allocation range.",
+    },
+    commands: [
+      ...appCredentialCommands,
+      ...appKeyCommands,
+      ...appDomainCommands(locale),
+      ...agentCommands,
+      ...documentationCommands,
+      ...appSignInCommands,
+      ...accountCategoryCommands,
+      ...accountAdministrationCommands,
+      ...aiUsageCommands,
+      ...aiModelCommands,
+      ...aiQuotaCommands,
+      ...aiSkillCommands,
+      ...instanceCommands,
+      ...gatewayCommands,
+      ...logCommands,
+      ...telemetryCommands,
+      ...jobCommands,
+      ...legalCommands,
+      ...geoipCommands,
+      ...linuxCommands,
+      ...workflowCommands,
+      ...dataCommands,
+      ...notificationCommands,
+      ...outgoingMailCommands,
+      ...webhookCommands,
+      ...metricsCommands,
+      ...natsCommands,
+      ...syncCommands,
+      ...settingsCommands,
+    ],
+  });
+
+const admin = build();
+export default {
+  ...admin,
+  help: (locale?: string) => build(locale).help?.(locale) ?? "",
+  run: (ctx: CloudCliContext) => build(ctx.options.locale).run(ctx),
+};

package/src/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,51 +121,70 @@ 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_APP_KEY: {
+    schema: z.string(),
+    scope: "secret",
+    secretFile: true,
+    doc: "App Ed25519 private key for startup connection bootstrap; alternatively mount CLOUD_APP_KEY_FILE. Requires the direct Core origin. Core and Gateway refuse app keys. Keep infrastructure env until the platform-client import migration is complete.",
+  },
   CLOUD_CORE_INTERNAL_ORIGIN: {
     schema: z.string(),
-    doc: "Direct Core listener origin for OAuth issuance, mandate-backed background work and internal callbacks; host-run callers use the Core port, not the gateway.",
+    doc: "Direct Core listener origin for app connection bootstrap, OAuth issuance, mandate-backed background work and internal callbacks; never the gateway. Cross-host bootstrap requires verified TLS; install private CAs through NODE_EXTRA_CA_CERTS before the first fetch.",
   },
   CLOUD_APP_CREDENTIAL: {
     schema: z.string(),
     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";
+};