@k2b/cloud 0.46.0 → 0.48.0

package/src/services/service-account-credentials.ts

@@ -221,10 +221,10 @@ const verifyApiTokenSecret = async (secret: string, storedHash: string, scopes:
   }
 };
 
-const generateUniqueTokenParts = async (): Promise<{ tokenPrefix: string; secret: string; token: string }> => {
+const generateUniqueTokenParts = async (db: SqlRunner): Promise<{ tokenPrefix: string; secret: string; token: string }> => {
   for (let i = 0; i < 5; i += 1) {
     const parts = generateTokenParts();
-    const [row] = await sql<{ exists: boolean }[]>`
+    const [row] = await db<{ exists: boolean }[]>`
       SELECT EXISTS(
         SELECT 1 FROM auth.service_account_credentials WHERE token_prefix = ${parts.tokenPrefix}
       ) AS exists
@@ -342,7 +342,7 @@ const insertApiToken = async (
     if (expiresAt.getTime() <= Date.now()) return fail(err.badInput("Expiry must be in the future"));
   }
 
-  const parts = await generateUniqueTokenParts();
+  const parts = await generateUniqueTokenParts(db);
   const secretHash = hashApiTokenSecret(parts.secret, params.scopes ?? []);
 
   try {
@@ -376,15 +376,18 @@ const insertApiToken = async (
   }
 };
 
-export const createApiToken = async (params: {
-  serviceAccountId: string;
-  name: string;
-  createdBy?: string | null;
-  expiresAt?: string | null;
-  scopes?: string[];
-}): Promise<Result<{ credential: ServiceAccountCredential; token: string }>> => {
+export const createApiToken = async (
+  params: {
+    serviceAccountId: string;
+    name: string;
+    createdBy?: string | null;
+    expiresAt?: string | null;
+    scopes?: string[];
+  },
+  options: { db?: SQL } = {},
+): Promise<Result<{ credential: ServiceAccountCredential; token: string }>> => {
   if (params.scopes?.includes(AI_INFERENCE_SCOPE)) return fail(err.badInput("ai:inference is reserved for models-only personal API keys"));
-  return insertApiToken(sql, params);
+  return insertApiToken(options.db ?? sql, params);
 };
 
 export const createUserApiToken = async (params: {
@@ -531,7 +534,7 @@ export const listForDelegatedUser = async (params: { userId: string }): Promise<
       c.last_used_at, c.created_by, c.created_at, c.revoked_at, c.revoked_by
     FROM auth.service_account_credentials c
     JOIN auth.service_accounts sa ON sa.id = c.service_account_id
-    WHERE sa.kind = 'user_delegated'
+    WHERE c.kind = 'api_token' AND sa.kind = 'user_delegated'
       AND sa.delegated_user_id = ${params.userId}::uuid
       AND c.status = 'active'
     ORDER BY c.created_at DESC
@@ -569,7 +572,7 @@ export const listOverview = async (config?: {
     FROM auth.service_account_credentials c
     JOIN auth.service_accounts sa ON sa.id = c.service_account_id
     LEFT JOIN auth.users du ON du.id = sa.delegated_user_id
-    WHERE (${serviceAccountKind}::text IS NULL OR sa.kind = ${serviceAccountKind})
+    WHERE c.kind = 'api_token' AND (${serviceAccountKind}::text IS NULL OR sa.kind = ${serviceAccountKind})
       AND (${credentialStatus}::text IS NULL OR c.status = ${credentialStatus})
       AND (${userId}::uuid IS NULL OR sa.delegated_user_id = ${userId}::uuid)
       AND (${serviceAccountId}::uuid IS NULL OR sa.id = ${serviceAccountId}::uuid)
@@ -621,7 +624,7 @@ export const listOverview = async (config?: {
     FROM auth.service_account_credentials c
     JOIN auth.service_accounts sa ON sa.id = c.service_account_id
     LEFT JOIN auth.users du ON du.id = sa.delegated_user_id
-    WHERE (${serviceAccountKind}::text IS NULL OR sa.kind = ${serviceAccountKind})
+    WHERE c.kind = 'api_token' AND (${serviceAccountKind}::text IS NULL OR sa.kind = ${serviceAccountKind})
       AND (${credentialStatus}::text IS NULL OR c.status = ${credentialStatus})
       AND (${userId}::uuid IS NULL OR sa.delegated_user_id = ${userId}::uuid)
       AND (${serviceAccountId}::uuid IS NULL OR sa.id = ${serviceAccountId}::uuid)
@@ -688,7 +691,7 @@ export const getOverview = async (params: { id: string }): Promise<ServiceAccoun
     FROM auth.service_account_credentials c
     JOIN auth.service_accounts sa ON sa.id = c.service_account_id
     LEFT JOIN auth.users du ON du.id = sa.delegated_user_id
-    WHERE c.id = ${params.id}::uuid
+    WHERE c.kind = 'api_token' AND c.id = ${params.id}::uuid
     LIMIT 1
   `;
   return row ? mapCredentialOverview(row) : null;
@@ -732,14 +735,14 @@ type RevokeCredentialInput =
 export const revoke = async (params: RevokeCredentialInput, options: { db?: SQL } = {}): Promise<Result<void>> => {
   if (!UUID_PATTERN.test(params.credentialId)) return fail(err.notFound("API key"));
 
-  const run = async (db: SQL): Promise<Result<void>> => {
+  const run = async (db: SQL, credentialId = params.credentialId): Promise<Result<void>> => {
     const [row] = await db<DbCredentialRow[]>`
       UPDATE auth.service_account_credentials
       SET status = 'revoked',
         revoked_at = now(),
         revoked_by = ${params.actor?.id ?? null}::uuid
-      WHERE id = ${params.credentialId}::uuid
-        AND status = 'active'
+      WHERE id = ${credentialId}::uuid
+        AND status = 'active' AND kind = 'api_token'
       RETURNING id, service_account_id, name, kind, status, token_prefix, scopes, expires_at,
         last_used_at, created_by, created_at, revoked_at, revoked_by
     `;
@@ -750,14 +753,14 @@ export const revoke = async (params: RevokeCredentialInput, options: { db?: SQL
           SELECT id, service_account_id, name, kind, status, token_prefix, scopes, expires_at,
             last_used_at, created_by, created_at, revoked_at, revoked_by
           FROM auth.service_account_credentials
-          WHERE id = ${params.credentialId}::uuid
+          WHERE id = ${credentialId}::uuid AND kind = 'api_token'
           LIMIT 1
         `;
     const result = row || existing?.status === "revoked" ? ok() : fail(err.notFound("API key"));
     return audit.recordResult({
       action: "service_account_credential.revoke",
       actor: params.actor ? actorForUser(params.actor) : null,
-      target: { type: "service_account_credential", id: params.credentialId, label: row?.name ?? existing?.name ?? null },
+      target: { type: "service_account_credential", id: credentialId, label: row?.name ?? existing?.name ?? null },
       metadata: {
         serviceAccountId: row?.service_account_id ?? existing?.service_account_id ?? null,
         ...(params.actor ? { adminAction: true } : { provenance: "system", service: params.system.service, reason: params.system.reason }),
@@ -766,7 +769,46 @@ export const revoke = async (params: RevokeCredentialInput, options: { db?: SQL
       db,
     });
   };
-  return options.db ? run(options.db) : sql.begin(run);
+  const revokeWithWorkload = async (db: SQL): Promise<Result<void>> => {
+    if (params.actor) {
+      const [instance] = await db<{ app_id: string; instance_id: string; service_account_id: string }[]>`
+        SELECT i.app_id, i.instance_id, c.service_account_id FROM auth.app_workload_instances i
+        JOIN auth.service_account_credentials c ON c.id = i.credential_id
+        WHERE i.credential_id = ${params.credentialId}::uuid OR i.previous_credential_id = ${params.credentialId}::uuid
+      `;
+      if (instance) {
+        // Same lock order as Core rotation. Resolve the latest generation *after* waiting,
+        // so an admin revoking the displayed token also revokes an overlapping rotation.
+        await db`SELECT id FROM auth.service_accounts WHERE id = ${instance.service_account_id}::uuid FOR UPDATE`;
+        // The account is the durable app-wide off switch, including future process instances.
+        await db`UPDATE auth.service_accounts SET status = 'disabled' WHERE id = ${instance.service_account_id}::uuid`;
+        await audit.record(
+          {
+            action: "service_account.disable",
+            outcome: "allowed",
+            actor: actorForUser(params.actor),
+            target: { type: "service_account", id: instance.service_account_id },
+            metadata: { appId: instance.app_id, serviceAccountId: instance.service_account_id, status: "disabled" },
+          },
+          db,
+        );
+        const [current] = await db<{ credential_id: string; previous_credential_id: string | null }[]>`
+          SELECT credential_id, previous_credential_id FROM auth.app_workload_instances
+          WHERE app_id = ${instance.app_id} AND instance_id = ${instance.instance_id}
+        `;
+        if (current) {
+          for (const credentialId of [current.credential_id, current.previous_credential_id]) {
+            if (!credentialId) continue;
+            const result = await run(db, credentialId);
+            if (!result.ok) return result;
+          }
+          return ok();
+        }
+      }
+    }
+    return run(db);
+  };
+  return options.db ? revokeWithWorkload(options.db) : sql.begin(revokeWithWorkload);
 };
 
 const findActiveByTokenPrefix = async (tokenPrefix: string): Promise<DbCredentialWithSecretRow | null> => {

package/src/services/settings/api.ts

@@ -27,7 +27,7 @@ import { deleteKey, readKey, readKeyState, type StoredSettingState, writeKey } f
  */
 export interface SettingsAPI<F extends Record<string, unknown>> {
   get<K extends keyof F & string>(key: K): Promise<F[K]>;
-  read<K extends keyof F & string>(key: K): Promise<{ value: F[K]; stored: StoredSettingState }>;
+  read<K extends keyof F & string>(key: K): Promise<{ value: F[K]; stored: StoredSettingState; bindingMismatch?: true }>;
   set<K extends keyof F & string>(key: K, value: F[K], options?: { replaceUnreadable?: boolean }): Promise<void>;
   remove<K extends keyof F & string>(key: K): Promise<void>;
 }
@@ -59,8 +59,8 @@ export const createSettingsAPI = <S extends AppSettingsMap>(): SettingsAPI<{
  */
 export const coreSettings = {
   get: <T = unknown>(key: string): Promise<T> => readKey(key) as Promise<T>,
-  read: <T = unknown>(key: string): Promise<{ value: T; stored: StoredSettingState }> =>
-    readKeyState(key) as Promise<{ value: T; stored: StoredSettingState }>,
+  read: <T = unknown>(key: string): Promise<{ value: T; stored: StoredSettingState; bindingMismatch?: true }> =>
+    readKeyState(key) as Promise<{ value: T; stored: StoredSettingState; bindingMismatch?: true }>,
   set: (key: string, value: unknown, options?: { replaceUnreadable?: boolean }): Promise<void> => writeKey(key, value, undefined, options),
   remove: (key: string): Promise<void> => deleteKey(key),
 };

package/src/services/settings/binding.ts

@@ -0,0 +1,45 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { SETTINGS, SETTINGS_MAP } from "./defaults";
+
+const envelope = z.object({ value: z.unknown(), bindings: z.record(z.string(), z.string()) });
+const hash = (value: unknown) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+export const settingOwners = (key: string) => SETTINGS.filter((def) => def.resetOnChange?.includes(key));
+
+/** Bind the value inside its encrypted row; no independently writable marker. */
+export const bindSettingValue = async (key: string, value: unknown, resolve: (key: string) => Promise<unknown>): Promise<unknown> => {
+  const owners = settingOwners(key);
+  if (!owners.length) return value;
+  const bindings: Record<string, string> = {};
+  for (const owner of owners) bindings[owner.key] = hash(await resolve(owner.key));
+  return { value, bindings };
+};
+
+export const unwrapSettingValue = (key: string, raw: unknown): unknown => {
+  if (!settingOwners(key).length) return raw;
+  const parsed = envelope.safeParse(raw);
+  return parsed.success ? parsed.data.value : raw;
+};
+
+export const replaceSettingValue = (key: string, raw: unknown, value: unknown): unknown => {
+  if (!settingOwners(key).length) return value;
+  const parsed = envelope.safeParse(raw);
+  return parsed.success ? { ...parsed.data, value } : value;
+};
+
+/** Missing or stale bindings require a new value, including legacy unbound rows. */
+export const resolveBoundSetting = async (
+  key: string,
+  raw: unknown,
+  resolve: (key: string) => Promise<unknown>,
+): Promise<{ value: unknown; mismatch: boolean }> => {
+  const owners = settingOwners(key);
+  const fallback = SETTINGS_MAP.get(key)?.default;
+  if (!owners.length) return { value: raw, mismatch: false };
+  const parsed = envelope.safeParse(raw);
+  if (!parsed.success) return { value: fallback, mismatch: true };
+  for (const owner of owners) {
+    if (parsed.data.bindings[owner.key] !== hash(await resolve(owner.key))) return { value: fallback, mismatch: true };
+  }
+  return { value: parsed.data.value, mismatch: false };
+};

package/src/services/settings/core-settings.ts

@@ -1,5 +1,7 @@
 import { env } from "../../config/env";
+import { DEFAULT_WORKFLOW_AI_BUDGET, validateWorkflowAiBudget } from "../../config/workflow-ai";
 import { GEO_MAX_CREDITS, GEO_MAX_RPS } from "../../contracts/geo-admin";
+import { DEFAULT_TRUSTED_PROXIES, validateNetworkAllowlist, validateTrustedProxies } from "./validation";
 
 /**
  * Platform-owned settings, declared in the `defineApp({ settings: ... })` shape.
@@ -30,6 +32,121 @@ const IPA_ACCOUNT_TRANSITION_OPTIONS = [
 ] as const;
 
 export const CORE_SETTINGS = {
+  "outgoing_mail.allowed_targets": {
+    kind: "string_list",
+    default: [],
+    label: "Outgoing mail allowed targets",
+    description: "Exact internal SMTP and IMAP hosts, IPs or CIDRs. Changes apply to new connections.",
+    envVariable: "OUTGOING_MAIL_ALLOWED_TARGETS",
+    envBootstrap: () => env.$readPresent("OUTGOING_MAIL_ALLOWED_TARGETS"),
+    validate: validateNetworkAllowlist,
+    presentation: {
+      translations: {
+        de: {
+          label: "Erlaubte Ziele für ausgehende E-Mails",
+          description: "Exakte interne SMTP- und IMAP-Hosts, IPs oder CIDRs. Änderungen gelten für neue Verbindungen.",
+        },
+      },
+    },
+  },
+  "gateway.ingress_cert_resolver": {
+    kind: "string",
+    default: "le",
+    label: "App domain certificate resolver",
+    description:
+      "Traefik certificate resolver used by app domain routers. Must name a configured ACME resolver; changes apply within five seconds.",
+    validate: (value: unknown) =>
+      typeof value === "string" && /^[a-zA-Z0-9_-]+$/.test(value)
+        ? undefined
+        : "Use a Traefik certificate resolver name (letters, digits, underscores or hyphens).",
+    presentation: {
+      translations: {
+        de: {
+          label: "Zertifikatsresolver für App-Domains",
+          description:
+            "Traefik-Zertifikatsresolver der App-Domains. Muss einen konfigurierten ACME-Resolver benennen; Änderungen wirken innerhalb von fünf Sekunden.",
+        },
+      },
+    },
+  },
+  "gateway.trusted_proxies": {
+    kind: "string_list",
+    default: DEFAULT_TRUSTED_PROXIES,
+    label: "Trusted gateway proxies",
+    description: "IP addresses or CIDRs allowed to supply forwarded client addresses. Changes take effect after gateway restart.",
+    envVariable: "GATEWAY_TRUSTED_PROXIES",
+    envBootstrap: () => env.$readPresent("GATEWAY_TRUSTED_PROXIES"),
+    validate: validateTrustedProxies,
+    presentation: {
+      translations: {
+        de: {
+          label: "Vertrauenswürdige Gateway-Proxys",
+          description:
+            "IP-Adressen oder CIDRs, die weitergeleitete Client-Adressen liefern dürfen. Änderungen wirken nach einem Gateway-Neustart.",
+        },
+      },
+    },
+  },
+  "ai.workflow_budget": {
+    kind: "text",
+    default: JSON.stringify(DEFAULT_WORKFLOW_AI_BUDGET),
+    label: "Workflow AI budget",
+    description:
+      "JSON limits for source, rate and concurrency admission. Changes apply to new work; globalConcurrent also sets worker capacity and requires restarting all AI workers.",
+    envVariable: "WORKFLOW_AI_BUDGET",
+    envBootstrap: () => {
+      const value = env.$readPresent("WORKFLOW_AI_BUDGET");
+      return value === undefined ? undefined : JSON.stringify(value);
+    },
+    validate: validateWorkflowAiBudget,
+    presentation: {
+      translations: {
+        de: {
+          label: "KI-Workflow-Budget",
+          description:
+            "JSON-Grenzen für Quellen, Rate und gleichzeitige Arbeit. Änderungen gelten für neue Arbeit; globalConcurrent bestimmt auch die Worker-Kapazität und erfordert den Neustart aller KI-Worker.",
+        },
+      },
+    },
+  },
+  "ai.workflow_attempt_timeout_ms": {
+    kind: "number",
+    default: 60000,
+    label: "Workflow AI attempt timeout (ms)",
+    description: "Absolute attempt deadline including admission and repair. Changes apply to new attempts.",
+    envVariable: "WORKFLOW_AI_ATTEMPT_TIMEOUT_MS",
+    envBootstrap: () => env.$readPresent("WORKFLOW_AI_ATTEMPT_TIMEOUT_MS"),
+    integer: true,
+    min: 1,
+    presentation: {
+      translations: {
+        de: {
+          label: "Zeitlimit je KI-Workflow-Versuch (ms)",
+          description: "Absolute Frist einschließlich Zulassung und Reparatur. Änderungen gelten für neue Versuche.",
+        },
+      },
+    },
+  },
+  "ai.workflow_queue_timeout_ms": {
+    kind: "number",
+    default: 60000,
+    label: "Workflow AI queue timeout (ms)",
+    description: "Maximum queue wait before visible failure. Changes apply to new requests and the next recovery scan.",
+    envVariable: "WORKFLOW_AI_QUEUE_TIMEOUT_MS",
+    envBootstrap: () => env.$readPresent("WORKFLOW_AI_QUEUE_TIMEOUT_MS"),
+    integer: true,
+    min: 1,
+    presentation: {
+      translations: {
+        de: {
+          label: "Wartezeitlimit für KI-Workflows (ms)",
+          description:
+            "Maximale Wartezeit bis zum sichtbaren Fehler. Änderungen gelten für neue Anfragen und den nächsten Wiederherstellungslauf.",
+        },
+      },
+    },
+  },
+
   "storage.endpoint": {
     kind: "url",
     label: "Garage S3 endpoint",
@@ -228,6 +345,7 @@ export const CORE_SETTINGS = {
     placeholder: "e.g. https://cloud.example.org",
     envFallback: () => env.APP_URL,
     envBootstrap: () => env.APP_URL,
+    envVariable: "APP_URL",
   },
   "app.home_path": {
     kind: "string",
@@ -494,8 +612,8 @@ export const CORE_SETTINGS = {
     default: "",
     description: "Internal base URL of the Gotenberg service used for HTML-to-PDF rendering.",
     placeholder: "e.g. http://gotenberg:3000",
-    envFallback: () => env.GOTENBERG_URL,
     envBootstrap: () => env.GOTENBERG_URL,
+    envVariable: "GOTENBERG_URL",
   },
   "gotenberg.username": {
     kind: "string",

package/src/services/settings/crypto.ts

@@ -1,3 +1,4 @@
+import { connections } from "../../runtime/connections";
 /**
  * Encryption helpers for settings at-rest.
  *
@@ -7,7 +8,6 @@
  */
 
 import { createHash } from "node:crypto";
-import { env } from "../../config/env";
 import { crypto } from "../../server/services";
 
 /**
@@ -34,7 +34,7 @@ import { crypto } from "../../server/services";
  * with deployments that have always used hex-format APP_SECRET.
  */
 export const getAppSecret = (): string => {
-  const raw = env.APP_SECRET.trim();
+  const raw = connections().appSecret.current.trim();
   if (!raw) {
     throw new Error("APP_SECRET is required to read or write encrypted settings");
   }

package/src/services/settings/defaults.ts

@@ -32,6 +32,12 @@ type SettingCommon = {
   group: string;
   envFallback?: SettingEnvResolver;
   envBootstrap?: SettingEnvResolver;
+  /** Environment name for migration diagnostics; values are never returned. */
+  envVariable?: string;
+  /** Discard these stored settings when this normalized value changes. */
+  resetOnChange?: readonly string[];
+  /** Additional server-side validation after kind normalization. */
+  validate?: (value: unknown) => string | undefined;
 };
 
 type SettingStringLikeKind = "string" | "text" | "email" | "url" | "secret" | "image" | "cron" | "timezone" | "template";
@@ -118,6 +124,9 @@ export const toLegacySettingDefs = (settings: Record<string, unknown>, requested
       presentation: compilePresentation(d.presentation, baseLocale, key),
       envFallback: d.envFallback as (() => unknown) | undefined,
       envBootstrap: d.envBootstrap as (() => unknown) | undefined,
+      envVariable: d.envVariable as string | undefined,
+      validate: d.validate as SettingDef["validate"],
+      resetOnChange: d.resetOnChange as readonly string[] | undefined,
       templateVars: d.templateVars as readonly string[] | undefined,
       options: d.options as ReadonlyArray<{ value: string; label: string }> | undefined,
       min: d.min as number | undefined,
@@ -262,7 +271,11 @@ export const normalizeSettingValue = (def: SettingDef, raw: unknown): unknown =>
 };
 
 export const validateSettingValue = (def: SettingDef, raw: unknown): SettingValidationResult => {
+  if (def.validate && def.kind === "string_list" && Array.isArray(raw) && raw.some((entry) => typeof entry !== "string"))
+    return { ok: false, error: `${getSettingLabel(def)} must be a list of strings` };
   const value = normalizeSettingValue(def, raw);
+  const error = def.validate?.(value);
+  if (error) return { ok: false, error };
 
   if (def.key === "app.documentation_url") {
     try {
@@ -356,7 +369,7 @@ export const validateSettingValue = (def: SettingDef, raw: unknown): SettingVali
 export const SETTINGS_MAP = new Map(SETTINGS.map((setting) => [setting.key, setting] as const));
 
 /** Fields whose divergence changes behaviour rather than just wording. */
-const CONFLICT_FIELDS = ["kind", "default", "min", "max"] as const;
+const CONFLICT_FIELDS = ["kind", "default", "min", "max", "resetOnChange"] as const;
 
 export function registerSettings(defs: SettingDef[]): void {
   for (const def of defs) {
@@ -368,7 +381,8 @@ export function registerSettings(defs: SettingDef[]): void {
       // the winner would then depend on which container loaded which module.
       const existing = SETTINGS[existingIndex] as Record<string, unknown>;
       const incoming = def as unknown as Record<string, unknown>;
-      const conflicts = CONFLICT_FIELDS.filter((field) => JSON.stringify(existing[field]) !== JSON.stringify(incoming[field]));
+      const conflicts: string[] = CONFLICT_FIELDS.filter((field) => JSON.stringify(existing[field]) !== JSON.stringify(incoming[field]));
+      if (existing.validate !== incoming.validate) conflicts.push("validate");
       if (conflicts.length > 0) {
         throw new Error(
           `Setting "${def.key}" is registered twice with different ${conflicts.join(", ")}. ` +

package/src/services/settings/env-status.ts

@@ -0,0 +1,69 @@
+import type { EnvSettingStatus } from "../../contracts/settings-env";
+import { SETTINGS, type SettingDef, validateSettingValue } from "./defaults";
+import { readStates, type SettingRead } from "./store";
+
+const equal = (a: unknown, b: unknown, jsonText = false): boolean => {
+  if (jsonText && typeof a === "string" && typeof b === "string") {
+    try {
+      return equal(JSON.parse(a), JSON.parse(b));
+    } catch {
+      return a === b;
+    }
+  }
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((v, i) => equal(v, b[i]));
+  if (a && b && typeof a === "object" && typeof b === "object") {
+    const left = Object.entries(a),
+      right = new Map(Object.entries(b));
+    return left.length === right.size && left.every(([k, v]) => right.has(k) && equal(v, right.get(k)));
+  }
+  return a === b;
+};
+
+/** Compare locally, return presence and state only, including for secret settings. */
+export const envSettingStatus = (def: SettingDef, stored: SettingRead): EnvSettingStatus => {
+  let envValue: unknown,
+    invalidEnvValue = false,
+    envValuePresent = false;
+  try {
+    const raw = (def.envBootstrap ?? def.envFallback)?.();
+    envValuePresent = raw !== undefined;
+    if (envValuePresent) {
+      const validated = validateSettingValue(def, raw);
+      if (validated.ok) envValue = validated.value;
+      else invalidEnvValue = true;
+    }
+  } catch {
+    envValuePresent = true;
+    invalidEnvValue = true;
+  }
+  const unreadableStoredValue = stored.stored === "unreadable";
+  const storedValuePresent = stored.stored !== "none";
+  const conflict =
+    envValuePresent && storedValuePresent
+      ? invalidEnvValue || unreadableStoredValue
+        ? "unknown"
+        : equal(envValue, stored.value, def.key === "ai.workflow_budget")
+          ? "none"
+          : "differs"
+      : "none";
+  return {
+    key: def.key,
+    envVariable: def.envVariable ?? null,
+    storedValuePresent,
+    envValuePresent,
+    conflict,
+    unreadableStoredValue,
+    invalidEnvValue,
+    needsAttention: invalidEnvValue || unreadableStoredValue || conflict !== "none" || (envValuePresent && !storedValuePresent),
+  };
+};
+
+export const readEnvSettingsStatus = async (): Promise<EnvSettingStatus[]> => {
+  const defs = SETTINGS.filter((def) => def.envBootstrap || def.envFallback);
+  const states = await readStates(defs.map((def) => def.key));
+  return defs.map((def) => {
+    const state = states.get(def.key);
+    if (!state) throw new Error(`Missing stored state for ${def.key}`);
+    return envSettingStatus(def, state);
+  });
+};

package/src/services/settings/index.ts

@@ -11,14 +11,24 @@
  */
 
 import { redis, sql } from "bun";
+import { bindSettingValue, replaceSettingValue, unwrapSettingValue } from "./binding";
 import { decryptValue, encryptValue, getAppSecret } from "./crypto";
 import { resolveSettingPresentation, SETTINGS, SETTINGS_MAP, type SettingDef, validateSettingValue } from "./defaults";
-import { deleteKey, readKey, readKeyState, readStates, type SettingRead, writeKey } from "./store";
+import {
+  deleteKey,
+  lockSettingChanges,
+  readKey,
+  readKeyState,
+  readStates,
+  resetChangedSettings,
+  type SettingRead,
+  writeKey,
+} from "./store";
 
 type SqlClient = typeof sql;
 
 type StoredRow = { key: string; value: string };
-type PendingRow = { value: unknown; originalCiphertext: string };
+type PendingRow = { value: unknown; originalValue: unknown; originalCiphertext: string };
 type NormalizationStats = {
   encryptedLoaded: number;
   normalizedUpdated: number;
@@ -32,7 +42,13 @@ const REDIS_KEY = (key: string) => `settings:${key}`;
 const isEqual = (left: unknown, right: unknown): boolean => JSON.stringify(left) === JSON.stringify(right);
 
 const resolveEnvValue = (def: SettingDef | undefined, mode: "fallback" | "bootstrap"): unknown => {
-  const raw = mode === "fallback" ? def?.envFallback?.() : def?.envBootstrap?.();
+  let raw: unknown;
+  try {
+    raw = mode === "fallback" ? def?.envFallback?.() : def?.envBootstrap?.();
+  } catch {
+    console.warn(`[settings] ignoring invalid ${mode} value for "${def?.key}"`);
+    return undefined;
+  }
   if (!def || raw === undefined) return undefined;
 
   const validated = validateSettingValue(def, raw);
@@ -54,7 +70,7 @@ const shouldBootstrapValue = (def: SettingDef, value: unknown): boolean => {
       return typeof value === "number" && Number.isFinite(value);
     case "string_list":
     case "number_list":
-      return Array.isArray(value) && value.length > 0;
+      return Array.isArray(value) && (value.length > 0 || def.envVariable !== undefined);
     default:
       return typeof value === "string" && value.trim().length > 0;
   }
@@ -79,7 +95,7 @@ const normalizeStoredEntries = async (): Promise<{
   for (const row of rows) {
     try {
       const value = await decryptValue(row.value);
-      pendingRows.set(row.key, { value, originalCiphertext: row.value });
+      pendingRows.set(row.key, { value: unwrapSettingValue(row.key, value), originalValue: value, originalCiphertext: row.value });
       stats.encryptedLoaded += 1;
     } catch {
       // An unreadable value is not a missing value (#1295). Usually this
@@ -113,7 +129,7 @@ const normalizeStoredEntries = async (): Promise<{
     normalized.push({ key, value: validated.value });
 
     if (!isEqual(row.value, validated.value)) {
-      const encryptedValue = await encryptValue(validated.value);
+      const encryptedValue = await encryptValue(replaceSettingValue(key, row.originalValue, validated.value));
       const updated = await sql<{ key: string }[]>`
         UPDATE settings.entries SET value = ${encryptedValue}, updated_at = now()
         WHERE key = ${key} AND value = ${row.originalCiphertext}
@@ -136,26 +152,53 @@ const bootstrapEnvBackedEntries = async (config: {
 }): Promise<Array<{ key: string; value: unknown }>> => {
   const rowsByKey = new Map(config.rows.map((row) => [row.key, row.value]));
 
-  for (const def of SETTINGS) {
-    // Existing rows block bootstrap even if unreadable, unknown, or invalid.
-    if (config.storedKeys.has(def.key)) continue;
-
-    const envValue = resolveEnvValue(def, "bootstrap");
-    if (!shouldBootstrapValue(def, envValue)) continue;
-
-    const encryptedValue = await encryptValue(envValue);
-    const inserted = await sql<{ key: string }[]>`
-      INSERT INTO settings.entries (key, value, updated_at)
-      VALUES (${def.key}, ${encryptedValue}, now())
-      ON CONFLICT (key) DO NOTHING
-      RETURNING key
-    `;
-    if (inserted.length === 0) continue;
-
-    await redis.del(REDIS_KEY(def.key));
-    rowsByKey.set(def.key, envValue);
-    config.stats.envBootstrapped += 1;
-  }
+  const imported = new Set<string>();
+  await sql.begin(async (tx) => {
+    // Import access before its endpoint regardless of declaration order.
+    const definitions = [...SETTINGS].sort((a, b) => Number(Boolean(a.resetOnChange?.length)) - Number(Boolean(b.resetOnChange?.length)));
+    for (const def of definitions) {
+      // Existing rows block bootstrap even if unreadable, unknown, or invalid.
+      if (config.storedKeys.has(def.key)) continue;
+      let envValue = resolveEnvValue(def, "bootstrap");
+      if (!shouldBootstrapValue(def, envValue)) continue;
+      await lockSettingChanges(tx, def.key);
+      let bindingRefused = false;
+      // Do not import access from an environment that names other endpoints.
+      for (const owner of SETTINGS.filter((owner) => owner.resetOnChange?.includes(def.key))) {
+        const current = await readKeyState(owner.key, tx);
+        const expected = resolveEnvValue(owner, "bootstrap") ?? resolveEnvValue(owner, "fallback") ?? owner.default;
+        if (current.stored !== "none" && (current.stored === "unreadable" || !isEqual(current.value, expected))) {
+          envValue = def.default;
+          bindingRefused = true;
+        }
+      }
+      const prior = def.resetOnChange?.length ? await readKeyState(def.key, tx) : undefined;
+      const encryptedValue = await encryptValue(
+        bindingRefused
+          ? envValue
+          : await bindSettingValue(def.key, envValue, async (owner) => {
+              const current = await readKeyState(owner, tx);
+              const ownerDef = SETTINGS_MAP.get(owner);
+              if (current.stored === "unreadable") throw new Error(`Cannot bind setting to unreadable ${owner}`);
+              return current.stored === "none" ? (resolveEnvValue(ownerDef, "bootstrap") ?? current.value) : current.value;
+            }),
+      );
+      const inserted = await tx<{ key: string }[]>`
+        INSERT INTO settings.entries (key, value, updated_at)
+        VALUES (${def.key}, ${encryptedValue}, now())
+        ON CONFLICT (key) DO NOTHING
+        RETURNING key
+      `;
+      if (inserted.length === 0) continue;
+      // A newly bootstrapped endpoint must not inherit previously stored access.
+      // Values imported together belong to the same environment configuration.
+      await resetChangedSettings(tx, def.key, envValue, imported, prior);
+      imported.add(def.key);
+      rowsByKey.set(def.key, envValue);
+    }
+  });
+  await Promise.all([...imported].map((key) => redis.del(REDIS_KEY(key), ...(SETTINGS_MAP.get(key)?.resetOnChange ?? []).map(REDIS_KEY))));
+  config.stats.envBootstrapped += imported.size;
 
   return [...rowsByKey.entries()].map(([key, value]) => ({ key, value }));
 };