@k2b/cloud 0.46.0 → 0.47.0

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,101 @@ 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.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 +325,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 +592,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/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 }));
 };

package/src/services/settings/store.ts

@@ -20,6 +20,7 @@ import { claimCacheFill, completeCacheFill, MISSING_SETTING } from "../cache-fil
 import { stripImageDataUrlMetadata } from "../image-metadata";
 import { toPgTextArray } from "../postgres";
 import { requestCacheRedis } from "../request-cache-redis";
+import { bindSettingValue, resolveBoundSetting, settingOwners, unwrapSettingValue } from "./binding";
 import { decryptValue, encryptValue } from "./crypto";
 import { SETTINGS, SETTINGS_MAP, type SettingDef, validateSettingValue } from "./defaults";
 import { SettingUnreadableError } from "./errors";
@@ -32,7 +33,7 @@ const REDIS_KEY = (k: string) => `settings:${k}`;
 type SqlClient = typeof sql;
 
 export type StoredSettingState = "none" | "readable" | "unreadable";
-export type SettingRead = { value: unknown; stored: StoredSettingState };
+export type SettingRead = { value: unknown; stored: StoredSettingState; bindingMismatch?: true };
 
 /**
  * Forget cached values so every container re-reads on next access.
@@ -43,7 +44,8 @@ export type SettingRead = { value: unknown; stored: StoredSettingState };
  * therefore invalidate after it commits.
  */
 export const invalidateSettingsCache = async (keys: readonly string[]): Promise<void> => {
-  if (keys.length > 0) await (await requestCacheRedis()).del(...keys.map(REDIS_KEY));
+  if (keys.length > 0)
+    await (await requestCacheRedis()).del(...keys.flatMap((key) => [key, ...(SETTINGS_MAP.get(key)?.resetOnChange ?? [])]).map(REDIS_KEY));
 };
 const REDIS_TTL_SEC = 300;
 
@@ -87,6 +89,15 @@ export const readKeyState = async (key: string, db: SqlClient = sql): Promise<Se
 export const bulkRead = async (keys: readonly string[]): Promise<Map<string, unknown>> => {
   const result = new Map<string, unknown>();
   if (keys.length === 0) return result;
+  // Bound access is read with its endpoint in one database snapshot. Never
+  // resolve it from an independently cached secret.
+  const boundKeys = keys.filter((key) => settingOwners(key).length > 0);
+  if (boundKeys.length) {
+    const bound = await readStates(boundKeys);
+    const other = await bulkRead(keys.filter((key) => !bound.has(key)));
+    for (const key of keys) result.set(key, bound.has(key) ? bound.get(key)!.value : other.get(key));
+    return result;
+  }
   let cached: Array<string | null>;
   try {
     cached = await (await requestCacheRedis()).mget(...keys.map(REDIS_KEY));
@@ -152,17 +163,29 @@ export const bulkRead = async (keys: readonly string[]): Promise<Map<string, unk
 export const readStates = async (keys: readonly string[], db: SqlClient = sql): Promise<Map<string, SettingRead>> => {
   const result = new Map<string, SettingRead>();
   if (keys.length === 0) return result;
-  const rows = await db<StoredRow[]>`SELECT key, value FROM settings.entries WHERE key = ANY(${toPgTextArray([...keys])}::text[])`;
+  const snapshotKeys = [...new Set(keys.flatMap((key) => [key, ...settingOwners(key).map((owner) => owner.key)]))];
+  const rows = await db<StoredRow[]>`SELECT key, value FROM settings.entries WHERE key = ANY(${toPgTextArray(snapshotKeys)}::text[])`;
   const byKey = new Map(rows.map((row) => [row.key, row]));
+  const resolve = async (key: string) => {
+    const row = byKey.get(key);
+    const def = SETTINGS_MAP.get(key);
+    if (!row) return resolveFallback(def);
+    const raw = await decryptValue(row.value);
+    const checked = def ? validateSettingValue(def, unwrapSettingValue(key, raw)) : { ok: true as const, value: raw };
+    if (!checked.ok) throw new SettingUnreadableError(key);
+    return checked.value;
+  };
   for (const key of keys) {
     const row = byKey.get(key);
     const def = SETTINGS_MAP.get(key);
     result.set(key, { stored: row ? "unreadable" : "none", value: resolveFallback(def) });
     if (!row) continue;
     try {
-      const value = await decryptValue(row.value);
-      const validated = def ? validateSettingValue(def, value) : { ok: true as const, value };
-      if (validated.ok) result.set(key, { stored: "readable", value: validated.value });
+      const raw = await decryptValue(row.value);
+      const bound = await resolveBoundSetting(key, raw, resolve);
+      const validated = def ? validateSettingValue(def, bound.value) : { ok: true as const, value: bound.value };
+      if (validated.ok)
+        result.set(key, { stored: "readable", value: validated.value, ...(bound.mismatch ? { bindingMismatch: true } : {}) });
     } catch {
       // Keep this process's fallback without changing the stored row or cache.
     }
@@ -220,6 +243,37 @@ export const deleteLegacyKeys = async (extraKnownKeys: readonly string[] = []):
   return { deleted };
 };
 
+/** Serialize a setting and every value it discards, including missing rows. */
+export const lockSettingChanges = async (tx: SqlClient, key: string): Promise<void> => {
+  const owners = SETTINGS.filter((def) => def.resetOnChange?.length && (def.key === key || def.resetOnChange.includes(key)));
+  for (const owner of owners.sort((a, b) => a.key.localeCompare(b.key)))
+    await tx`SELECT pg_advisory_xact_lock(hashtextextended(${`settings.change:${owner.key}`}, 0))`;
+};
+
+/** Keep an empty row so environment bootstrap cannot restore discarded access. */
+export const resetChangedSettings = async (
+  tx: SqlClient,
+  key: string,
+  value: unknown,
+  preserve: ReadonlySet<string> = new Set(),
+  prior?: SettingRead,
+): Promise<void> => {
+  const def = SETTINGS_MAP.get(key);
+  if (!def?.resetOnChange?.length) return;
+  const previous = prior ?? (await readKeyState(key, tx));
+  if (previous.stored !== "unreadable" && JSON.stringify(previous.value) === JSON.stringify(value)) return;
+  for (const target of def.resetOnChange) {
+    if (preserve.has(target)) continue;
+    const targetDef = SETTINGS_MAP.get(target);
+    if (!targetDef) throw new Error(`Unknown setting: ${target}`);
+    const empty = await encryptValue(targetDef.default);
+    await tx`
+      INSERT INTO settings.entries (key, value, updated_at) VALUES (${target}, ${empty}, now())
+      ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_at = EXCLUDED.updated_at
+    `;
+  }
+};
+
 /**
  * Encrypt the value, upsert the DB row, invalidate the Redis key.
  *
@@ -238,8 +292,16 @@ export const writeKey = async (key: string, value: unknown, db?: SqlClient, opti
 
   const storedValue =
     def.kind === "image" && typeof validated.value === "string" ? stripImageDataUrlMetadata(validated.value) : validated.value;
-  const encrypted = await encryptValue(storedValue);
   const write = async (tx: SqlClient) => {
+    await lockSettingChanges(tx, key);
+    await resetChangedSettings(tx, key, validated.value);
+    const encrypted = await encryptValue(
+      await bindSettingValue(key, storedValue, async (owner) => {
+        const state = await readKeyState(owner, tx);
+        if (state.stored === "unreadable") throw new SettingUnreadableError(owner);
+        return state.value;
+      }),
+    );
     for (let attempt = 0; attempt < 3; attempt++) {
       let [row] = await tx<{ value: string }[]>`UPDATE settings.entries SET value = value WHERE key = ${key} RETURNING value`;
       if (!row) {
@@ -256,7 +318,7 @@ export const writeKey = async (key: string, value: unknown, db?: SqlClient, opti
       if (options?.replaceUnreadable !== true) {
         let readable = false;
         try {
-          readable = validateSettingValue(def, await decryptValue(row.value)).ok;
+          readable = validateSettingValue(def, unwrapSettingValue(key, await decryptValue(row.value))).ok;
         } catch {
           // Only the key is exposed by the recovery error.
         }
@@ -283,7 +345,10 @@ export const writeKey = async (key: string, value: unknown, db?: SqlClient, opti
 
 /** Delete the DB row and invalidate Redis. With `db`, the caller owns geo budget pair validation and post-commit invalidation. */
 export const deleteKey = async (key: string, db?: SqlClient): Promise<void> => {
+  const def = SETTINGS_MAP.get(key);
   const remove = async (tx: SqlClient) => {
+    await lockSettingChanges(tx, key);
+    await resetChangedSettings(tx, key, resolveFallback(def));
     await tx`DELETE FROM settings.entries WHERE key = ${key}`;
   };
   if (db) await remove(db);

package/src/services/settings/validation.ts

@@ -0,0 +1,40 @@
+import { BlockList, isIP } from "node:net";
+import { parseNetworkAllowlist } from "../../shared/network-address";
+
+export const DEFAULT_TRUSTED_PROXIES = ["127.0.0.0/8", "::1/128", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "fc00::/7"];
+
+/** One parser for admin writes and the gateway's startup check. */
+export const trustedProxySet = (entries: readonly string[]): BlockList => {
+  const set = new BlockList();
+  for (const entry of entries) {
+    const [address = "", prefix, ...rest] = entry.split("/");
+    const version = isIP(address);
+    const max = version === 4 ? 32 : 128;
+    if (!version || rest.length || address.includes("%") || (prefix !== undefined && !/^\d{1,3}$/.test(prefix)))
+      throw new Error("Trusted proxies must contain only IP addresses or CIDR ranges");
+    const bits = prefix === undefined ? max : Number(prefix);
+    if (bits < 1 || bits > max) throw new Error("Trusted proxy CIDR prefixes must be greater than zero and within the address width");
+    set.addSubnet(address, bits, version === 4 ? "ipv4" : "ipv6");
+  }
+  return set;
+};
+
+export const validateTrustedProxies = (value: unknown): string | undefined => {
+  if (!Array.isArray(value) || !value.every((entry): entry is string => typeof entry === "string"))
+    return "Trusted proxies must be a list of strings";
+  try {
+    trustedProxySet(value);
+  } catch (error) {
+    return error instanceof Error ? error.message : "Invalid trusted proxies";
+  }
+};
+
+export const validateNetworkAllowlist = (value: unknown): string | undefined => {
+  if (!Array.isArray(value) || !value.every((entry): entry is string => typeof entry === "string"))
+    return "Network targets must be a list of strings";
+  try {
+    parseNetworkAllowlist(value);
+  } catch {
+    return "Network targets must be exact host names, IP addresses or canonical CIDRs; /0 is forbidden. Host:port and [ipv6]:port are supported.";
+  }
+};

package/src/shared/index.ts

@@ -1,5 +1,16 @@
 // Cloud-specific shared utils (NOT in stdlib)
 
+// The standalone editor owns the formula engine; Cloud preserves its existing shared API.
+export type { ErrorCode, EvalContext, EvalError, EvalResult, EvalValue, ProgressValue } from "@k2b/editor/formula";
+export {
+  createProgressValue,
+  evaluateFormula,
+  evaluateTableCell,
+  formatValue,
+  isFormula,
+  isTotalRow,
+  parseProgressValue,
+} from "@k2b/editor/formula";
 // Re-export from stdlib for backward compatibility
 // Prefer importing directly from @k2b/stdlib
 export { dates, dates as calendar, encoding, fileIcons, gradients } from "@k2b/stdlib";
@@ -49,16 +60,6 @@ export * from "./locale-preference";
 export * from "./login-method";
 export { markdown } from "./markdown";
 export { markdownCalloutSanitizeOptions } from "./markdown/callout-sanitizer";
-export type { ErrorCode, EvalContext, EvalError, EvalResult, EvalValue, ProgressValue } from "./markdown/formula";
-export {
-  createProgressValue,
-  evaluateFormula,
-  evaluateTableCell,
-  formatValue,
-  isFormula,
-  isTotalRow,
-  parseProgressValue,
-} from "./markdown/formula";
 export type { MockCover, MockCoverIcon, MockCoverOptions, MockCoverTheme } from "./mock-cover";
 export { createMockCover, createMockCoverSvg, parseDataUrl } from "./mock-cover";
 export * from "./network-address";

package/src/shared/markdown/extensions/tables.ts

@@ -20,8 +20,17 @@
  * NULL/datetime cell-formatting, no zebra columns. If you need any of
  * those, you're rendering data not prose; use the Grids app.
  */
+
+import {
+  type EvalContext,
+  evaluateFormula,
+  formatValue,
+  isFormula,
+  isTotalRow,
+  type ProgressValue,
+  parseProgressValue,
+} from "@k2b/editor/formula";
 import type { MarkedExtension, Tokens } from "marked";
-import { type EvalContext, evaluateFormula, formatValue, isFormula, isTotalRow, type ProgressValue, parseProgressValue } from "../formula";
 import { escapeHtml } from "../shared";
 
 type Align = "left" | "right" | "center" | null;