@k2b/cloud 0.6.0-rc.0

package/src/services/settings/crypto.ts

@@ -0,0 +1,69 @@
+/**
+ * Encryption helpers for settings at-rest.
+ *
+ * Settings DB rows are encrypted via stdlib's `crypto.symmetric.encrypt`
+ * (AES-256-GCM with HKDF key derivation). The key material comes from
+ * `APP_SECRET` — see `getAppSecret()` for the hex/passphrase handling.
+ */
+
+import { createHash } from "node:crypto";
+import { env } from "../../config/env";
+import { crypto } from "../../server/services";
+
+/**
+ * Resolve the encryption key passed to stdlib's `crypto.symmetric.encrypt`.
+ *
+ * Stdlib derives keys via HKDF and requires the input to be a hex string
+ * (it calls `fromHex(key)` internally). Two cases:
+ *
+ *  1. APP_SECRET is already a valid hex string (any even length).
+ *     Pass it through unchanged. THIS IS THE PRODUCTION PATH — existing
+ *     deployments use hex secrets and have data encrypted with the secret
+ *     verbatim. Any transformation here would change the derived HKDF key
+ *     and make every previously encrypted settings row unreadable.
+ *
+ *  2. APP_SECRET is not valid hex (e.g. a passphrase like "supersecret").
+ *     Deterministically derive a 32-byte hex key via SHA-256. Same input
+ *     always produces the same hex output, so settings encrypted with a
+ *     non-hex secret stay decryptable across restarts.
+ *
+ * ⚠️  DO NOT change the hex-passthrough branch. Hashing a hex secret would
+ * silently break every prod instance: encrypted settings could no longer
+ * be decrypted because the HKDF input would differ from what was used at
+ * write time. The branch exists specifically to preserve backward compat
+ * with deployments that have always used hex-format APP_SECRET.
+ */
+export const getAppSecret = (): string => {
+  const raw = env.APP_SECRET.trim();
+  if (!raw) {
+    throw new Error("APP_SECRET is required to read or write encrypted settings");
+  }
+  // Case 1: already hex — pass through (backward-compat, see doc above).
+  if (raw.length % 2 === 0 && /^[0-9a-fA-F]+$/.test(raw)) {
+    return raw;
+  }
+  // Case 2: non-hex passphrase — deterministically derive hex via SHA-256.
+  return createHash("sha256").update(raw).digest("hex");
+};
+
+export const encryptValue = async (value: unknown): Promise<string> =>
+  crypto.symmetric.encrypt({
+    payload: JSON.stringify(value),
+    key: getAppSecret(),
+    stretched: false,
+  });
+
+export const decryptValue = async (value: string): Promise<unknown> => {
+  const decrypted = await crypto.symmetric.decrypt({
+    payload: value,
+    key: getAppSecret(),
+  });
+  try {
+    return JSON.parse(decrypted);
+  } catch {
+    // Decrypt succeeded but the plaintext isn't JSON. Either pre-JSON-encoding
+    // legacy data or external write — return the raw string so callers can
+    // decide. Throwing here would corrupt the read path entirely.
+    return decrypted;
+  }
+};

package/src/services/settings/defaults.ts

@@ -0,0 +1,374 @@
+/**
+ * Central settings registry.
+ * Single source of truth for configurable settings, their value kinds, defaults,
+ * validation, UI metadata, and temporary env bootstrap behavior.
+ *
+ * Resolution order: DB value -> env fallback -> code default.
+ *
+ * `SettingKind` and `SettingOption` are re-exported from `contracts/shared` to
+ * keep a single source of truth (browser-safe types live there).
+ */
+
+import type { AppSettingPresentationTranslation } from "../../contracts/settings-types";
+import type { SettingKind, SettingOption } from "../../contracts/shared";
+import { ACCOUNT_ACTION_NOTICE_SAMPLE, renderAccountActionNotice } from "../../shared/account-action-notice";
+import { canonicalLocale, localeFallbackChain, normalizeLocale } from "../../shared/locale";
+import { migrateLegacyMustacheTemplate, validateLiquidTemplate } from "../../shared/template-rendering";
+import { CORE_SETTINGS } from "./core-settings";
+
+export type { SettingKind, SettingOption };
+
+type SettingEnvResolver = () => unknown;
+
+type SettingCommon = {
+  key: string;
+  label?: string;
+  description: string;
+  placeholder?: string;
+  presentation?: {
+    baseLocale: string;
+    translations: Readonly<Record<string, AppSettingPresentationTranslation>>;
+  };
+  group: string;
+  envFallback?: SettingEnvResolver;
+  envBootstrap?: SettingEnvResolver;
+};
+
+type SettingStringLikeKind = "string" | "text" | "email" | "url" | "secret" | "image" | "cron" | "timezone" | "template";
+
+type StringLikeSettingDef = SettingCommon & {
+  kind: SettingStringLikeKind;
+  default: string;
+  templateVars?: string[];
+};
+
+type BooleanSettingDef = SettingCommon & {
+  kind: "boolean";
+  default: boolean;
+};
+
+type NumberSettingDef = SettingCommon & {
+  kind: "number";
+  default: number;
+  min?: number;
+  max?: number;
+};
+
+type EnumSettingDef = SettingCommon & {
+  kind: "enum";
+  default: string;
+  options: SettingOption[];
+};
+
+type StringListSettingDef = SettingCommon & {
+  kind: "string_list";
+  default: string[];
+};
+
+type NumberListSettingDef = SettingCommon & {
+  kind: "number_list";
+  default: number[];
+};
+
+export type SettingDef =
+  | StringLikeSettingDef
+  | BooleanSettingDef
+  | NumberSettingDef
+  | EnumSettingDef
+  | StringListSettingDef
+  | NumberListSettingDef;
+
+export type SettingValidationResult = { ok: true; value: SettingDef["default"] } | { ok: false; error: string };
+
+/**
+ * Convert a `defineApp({ settings })` map into the legacy array shape.
+ *
+ * `group` is derived from the dotted prefix: the bespoke admin UIs ignore it,
+ * but legacy paths still group by it.
+ */
+const compilePresentation = (value: unknown, baseLocale: string, key: string): SettingCommon["presentation"] => {
+  if (!value) return undefined;
+  const catalog = value as { translations?: Readonly<Record<string, AppSettingPresentationTranslation>> };
+  const translations: Record<string, AppSettingPresentationTranslation> = {};
+  for (const [locale, translation] of Object.entries(catalog.translations ?? {})) {
+    const canonical = canonicalLocale(locale);
+    if (!canonical) throw new Error(`Setting "${key}" presentation locale ${JSON.stringify(locale)} is invalid`);
+    if (canonical === baseLocale) throw new Error(`Setting "${key}" presentation must not repeat base locale ${baseLocale}`);
+    if (translations[canonical]) throw new Error(`Setting "${key}" presentation locale ${canonical} is duplicated`);
+    translations[canonical] = Object.freeze({ ...translation });
+  }
+  return Object.freeze({ baseLocale, translations: Object.freeze(translations) });
+};
+
+export const toLegacySettingDefs = (settings: Record<string, unknown>, requestedBaseLocale = "en"): SettingDef[] => {
+  const baseLocale = normalizeLocale(requestedBaseLocale);
+  return Object.entries(settings).map(([key, def]) => {
+    const d = def as Record<string, unknown>;
+    return {
+      key,
+      group: key.split(".")[0] ?? "app",
+      kind: d.kind as SettingDef["kind"],
+      // The cast loses the per-kind discriminated default type but the data is
+      // correct; validateSettingValue re-validates against kind anyway.
+      default: d.default as never,
+      label: d.label as string | undefined,
+      description: (d.description as string | undefined) ?? "",
+      placeholder: d.placeholder as string | undefined,
+      presentation: compilePresentation(d.presentation, baseLocale, key),
+      envFallback: d.envFallback as (() => unknown) | undefined,
+      envBootstrap: d.envBootstrap as (() => unknown) | undefined,
+      templateVars: d.templateVars as readonly string[] | undefined,
+      options: d.options as ReadonlyArray<{ value: string; label: string }> | undefined,
+      min: d.min as number | undefined,
+      max: d.max as number | undefined,
+    } as SettingDef;
+  });
+};
+
+export const resolveSettingPresentation = (
+  def: SettingDef,
+  requestedLocale?: string,
+): { label: string; description: string; placeholder?: string; options?: SettingOption[] } => {
+  const base = {
+    label: getSettingLabel(def),
+    description: def.description,
+    placeholder: def.placeholder,
+    options: "options" in def ? def.options : undefined,
+  };
+  if (!requestedLocale || !def.presentation) return base;
+  const overlays = new Map(Object.entries(def.presentation.translations));
+  const resolved = localeFallbackChain(requestedLocale, def.presentation.baseLocale)
+    .filter((locale) => locale !== def.presentation!.baseLocale)
+    .reverse()
+    .reduce((value, locale) => ({ ...value, ...overlays.get(locale) }), {} as AppSettingPresentationTranslation);
+  return {
+    label: resolved.label ?? base.label,
+    description: resolved.description ?? base.description,
+    placeholder: resolved.placeholder ?? base.placeholder,
+    options: base.options?.map((option) => ({ ...option, label: resolved.options?.[option.value] ?? option.label })),
+  };
+};
+
+export const SETTINGS: SettingDef[] = [
+  // Platform settings — app.*, ai.*, gotenberg.*, freeipa.*, user.*,
+  // notifications.*, mail.*, security.*, legal.* — are declared once in
+  // core-settings.ts and derived here so every container registers them, not
+  // just the one that renders their admin UI.
+  //
+  // App-scoped settings do NOT belong here: an app declares them in its own
+  // defineApp({ settings }) and renders its own admin form.
+  ...toLegacySettingDefs(CORE_SETTINGS),
+];
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+const toStringValue = (value: unknown): string | null => {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return null;
+};
+
+const parseStringList = (value: unknown): string[] | null => {
+  const rawValues = Array.isArray(value)
+    ? value.flatMap((entry) => (typeof entry === "string" ? entry.split(/[,\n]/) : typeof entry === "number" ? [String(entry)] : []))
+    : typeof value === "string"
+      ? value.split(/[,\n]/)
+      : null;
+
+  if (!rawValues) return null;
+
+  return [...new Set(rawValues.map((entry) => entry.trim()).filter(Boolean))];
+};
+
+const parseNumberList = (value: unknown): number[] | null => {
+  const rawValues = Array.isArray(value) ? value : typeof value === "string" ? value.split(/[,\n]/).map((entry) => entry.trim()) : null;
+
+  if (!rawValues) return null;
+
+  const parsed = rawValues
+    .map((entry) => (typeof entry === "number" ? entry : Number(entry)))
+    .filter((entry) => Number.isInteger(entry) && entry > 0);
+
+  return [...new Set(parsed)].sort((a, b) => b - a);
+};
+
+const isValidCron = (value: string): boolean => {
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  return trimmed.split(/\s+/).length === 5;
+};
+
+const isValidTimezone = (value: string): boolean => {
+  try {
+    new Intl.DateTimeFormat(undefined, { timeZone: value });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const isNonEmptyStringKind = (kind: SettingKind): kind is Exclude<SettingKind, "boolean" | "number" | "string_list" | "number_list"> =>
+  kind !== "boolean" && kind !== "number" && kind !== "string_list" && kind !== "number_list";
+
+export const getSettingLabel = (def: SettingDef): string => {
+  if (def.label) return def.label;
+  return def.key
+    .split(".")
+    .slice(1)
+    .join(" ")
+    .replaceAll("_", " ")
+    .replace(/\b\w/g, (match) => match.toUpperCase());
+};
+
+export const normalizeSettingValue = (def: SettingDef, raw: unknown): unknown => {
+  switch (def.kind) {
+    case "boolean":
+      if (typeof raw === "boolean") return raw;
+      if (typeof raw === "string") {
+        const trimmed = raw.trim().toLowerCase();
+        if (trimmed === "true") return true;
+        if (trimmed === "false") return false;
+      }
+      return raw;
+    case "number":
+      if (typeof raw === "number" && Number.isFinite(raw)) return raw;
+      if (typeof raw === "string" && raw.trim()) {
+        const parsed = Number(raw.trim());
+        return Number.isFinite(parsed) ? parsed : raw;
+      }
+      return raw;
+    case "string_list":
+      return parseStringList(raw) ?? raw;
+    case "number_list":
+      return parseNumberList(raw) ?? raw;
+    case "enum": {
+      const value = toStringValue(raw);
+      return value === null ? raw : value.trim();
+    }
+    default: {
+      const value = toStringValue(raw);
+      if (value === null) return raw;
+      return def.kind === "text" || def.kind === "template" ? value : value.trim();
+    }
+  }
+};
+
+export const validateSettingValue = (def: SettingDef, raw: unknown): SettingValidationResult => {
+  const value = normalizeSettingValue(def, raw);
+
+  if (def.key === "app.documentation_url") {
+    try {
+      if (typeof value !== "string" || !/^https?:\/\//i.test(value)) throw new Error("Invalid URL");
+      const url = new URL(value);
+      if (url.username || url.password || url.search || url.hash) throw new Error("Invalid base URL");
+      return { ok: true, value: url.href.replace(/\/+$/, "") };
+    } catch {
+      return { ok: false, error: "Documentation website must be an absolute HTTP(S) base URL without credentials, query or fragment" };
+    }
+  }
+
+  switch (def.kind) {
+    case "boolean":
+      return typeof value === "boolean" ? { ok: true, value } : { ok: false, error: `${getSettingLabel(def)} must be true or false` };
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        return { ok: false, error: `${getSettingLabel(def)} must be a valid number` };
+      }
+      if (def.min !== undefined && value < def.min) {
+        return { ok: false, error: `${getSettingLabel(def)} must be at least ${def.min}` };
+      }
+      if (def.max !== undefined && value > def.max) {
+        return { ok: false, error: `${getSettingLabel(def)} must be at most ${def.max}` };
+      }
+      return { ok: true, value };
+    case "string_list":
+      return Array.isArray(value) && value.every((entry) => typeof entry === "string")
+        ? { ok: true, value }
+        : { ok: false, error: `${getSettingLabel(def)} must be a list of strings` };
+    case "number_list":
+      return Array.isArray(value) && value.every((entry) => typeof entry === "number" && Number.isInteger(entry) && entry > 0)
+        ? { ok: true, value }
+        : { ok: false, error: `${getSettingLabel(def)} must be a list of positive whole numbers` };
+    case "enum":
+      if (typeof value !== "string") {
+        return { ok: false, error: `${getSettingLabel(def)} must be a valid option` };
+      }
+      return def.options.some((option) => option.value === value)
+        ? { ok: true, value }
+        : { ok: false, error: `${getSettingLabel(def)} must be one of: ${def.options.map((option) => option.value).join(", ")}` };
+    case "email":
+      if (typeof value !== "string") return { ok: false, error: `${getSettingLabel(def)} must be a valid email address` };
+      return value.length === 0 || EMAIL_RE.test(value)
+        ? { ok: true, value }
+        : { ok: false, error: `${getSettingLabel(def)} must be a valid email address` };
+    case "url":
+    case "image":
+      if (typeof value !== "string") return { ok: false, error: `${getSettingLabel(def)} must be a valid URL` };
+      if (!value.length) return { ok: true, value };
+      try {
+        new URL(value);
+        return { ok: true, value };
+      } catch {
+        return { ok: false, error: `${getSettingLabel(def)} must be a valid URL` };
+      }
+    case "cron":
+      return typeof value === "string" && isValidCron(value)
+        ? { ok: true, value }
+        : { ok: false, error: `${getSettingLabel(def)} must be a valid five-field cron expression` };
+    case "timezone":
+      if (typeof value !== "string") return { ok: false, error: `${getSettingLabel(def)} must be a valid IANA timezone` };
+      return value.length === 0 || isValidTimezone(value)
+        ? { ok: true, value }
+        : { ok: false, error: `${getSettingLabel(def)} must be a valid IANA timezone` };
+    case "template": {
+      if (typeof value !== "string") return { ok: false, error: `${getSettingLabel(def)} must be text` };
+      const migrated = migrateLegacyMustacheTemplate(value);
+      const valid = validateLiquidTemplate(migrated);
+      if (valid.ok && def.key === "user.action_notice") {
+        try {
+          renderAccountActionNotice(migrated, ACCOUNT_ACTION_NOTICE_SAMPLE);
+        } catch (error) {
+          return { ok: false, error: error instanceof Error ? error.message : "Invalid account action notice" };
+        }
+      }
+      return valid.ok ? { ok: true, value: migrated } : { ok: false, error: `${getSettingLabel(def)} ${valid.error}` };
+    }
+    default:
+      if (!isNonEmptyStringKind(def.kind)) {
+        return { ok: false, error: `${getSettingLabel(def)} is invalid` };
+      }
+      return typeof value === "string" ? { ok: true, value } : { ok: false, error: `${getSettingLabel(def)} must be text` };
+  }
+};
+
+/** Lookup map for quick access by key */
+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;
+
+export function registerSettings(defs: SettingDef[]): void {
+  for (const def of defs) {
+    const existingIndex = SETTINGS.findIndex((setting) => setting.key === def.key);
+    if (existingIndex >= 0) {
+      // Re-registering the same definition is normal: core passes CORE_SETTINGS
+      // to defineApp, which re-registers what SETTINGS already derived. A
+      // *conflicting* re-registration means two declarations have drifted, and
+      // 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]));
+      if (conflicts.length > 0) {
+        throw new Error(
+          `Setting "${def.key}" is registered twice with different ${conflicts.join(", ")}. ` +
+            "Declare it once — platform settings belong in services/settings/core-settings.ts, " +
+            "app settings in that app's defineApp({ settings }).",
+        );
+      }
+      SETTINGS[existingIndex] = def;
+    } else {
+      SETTINGS.push(def);
+    }
+    SETTINGS_MAP.set(def.key, def);
+  }
+}

package/src/services/settings/index.ts

@@ -0,0 +1,215 @@
+/**
+ * Settings service — runtime-configurable settings backed by Postgres.
+ *
+ * Resolution order: DB value -> env fallback -> code default.
+ *
+ * Custom DB values are encrypted at rest using APP_SECRET. All read/write
+ * goes through the Redis cache-aside layer in `./store.ts` (5-minute TTL).
+ * `loadCache()` runs once at boot to normalize legacy rows and bootstrap
+ * env-backed entries into Postgres.
+ */
+
+import { redis, sql } from "bun";
+import { decryptValue, encryptValue, getAppSecret } from "./crypto";
+import { SETTINGS, SETTINGS_MAP, resolveSettingPresentation, type SettingDef, validateSettingValue } from "./defaults";
+import { bulkRead, deleteKey, invalidateSettingsCache, readKey, writeKey } from "./store";
+
+type SqlClient = typeof sql;
+
+type StoredRow = { key: string; value: string };
+type PendingRow = { key: string; value: unknown; rewrite: boolean; existed: boolean };
+type NormalizationStats = {
+  encryptedLoaded: number;
+  normalizedUpdated: number;
+  envBootstrapped: number;
+  invalidSkipped: number;
+};
+
+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?.();
+  if (!def || raw === undefined) return undefined;
+
+  const validated = validateSettingValue(def, raw);
+  if (!validated.ok) {
+    console.warn(`[settings] ignoring invalid ${mode} value for "${def.key}": ${validated.error}`);
+    return undefined;
+  }
+
+  return validated.value;
+};
+
+const shouldBootstrapValue = (def: SettingDef, value: unknown): boolean => {
+  if (value === undefined || value === null) return false;
+
+  switch (def.kind) {
+    case "boolean":
+      return value === true;
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "string_list":
+    case "number_list":
+      return Array.isArray(value) && value.length > 0;
+    default:
+      return typeof value === "string" && value.trim().length > 0;
+  }
+};
+
+const upsertEncryptedRow = async (key: string, value: unknown): Promise<void> => {
+  const encryptedValue = await encryptValue(value);
+  await sql`
+    INSERT INTO settings.entries (key, value, updated_at)
+    VALUES (${key}, ${encryptedValue}, now())
+    ON CONFLICT (key)
+    DO UPDATE SET value = ${encryptedValue}, updated_at = now()
+  `;
+  await redis.del(REDIS_KEY(key));
+};
+
+const normalizeStoredEntries = async (): Promise<{ rows: Array<{ key: string; value: unknown }>; stats: NormalizationStats }> => {
+  const rows = await sql<StoredRow[]>`SELECT key, value FROM settings.entries`;
+  const stats: NormalizationStats = {
+    encryptedLoaded: 0,
+    normalizedUpdated: 0,
+    envBootstrapped: 0,
+    invalidSkipped: 0,
+  };
+  const pendingRows = new Map<string, PendingRow>();
+
+  for (const row of rows) {
+    try {
+      const value = await decryptValue(row.value);
+      pendingRows.set(row.key, { key: row.key, value, rewrite: false, existed: true });
+      stats.encryptedLoaded += 1;
+    } catch {
+      console.warn(`[settings] skipping invalid stored value for "${row.key}"`);
+      stats.invalidSkipped += 1;
+    }
+  }
+
+  const normalized: Array<{ key: string; value: unknown }> = [];
+
+  for (const [key, row] of pendingRows.entries()) {
+    const def = SETTINGS_MAP.get(key);
+    if (!def) {
+      console.warn(`[settings] skipping unknown stored key "${key}"`);
+      stats.invalidSkipped += 1;
+      continue;
+    }
+
+    const validated = validateSettingValue(def, row.value);
+    if (!validated.ok) {
+      console.warn(`[settings] skipping invalid value for "${key}": ${validated.error}`);
+      stats.invalidSkipped += 1;
+      continue;
+    }
+
+    normalized.push({ key, value: validated.value });
+
+    if (row.rewrite || !row.existed || !isEqual(row.value, validated.value)) {
+      await upsertEncryptedRow(key, validated.value);
+      stats.normalizedUpdated += 1;
+    }
+  }
+
+  return { rows: normalized, stats };
+};
+
+const bootstrapEnvBackedEntries = async (config: {
+  rows: Array<{ key: string; value: unknown }>;
+  stats: NormalizationStats;
+}): Promise<Array<{ key: string; value: unknown }>> => {
+  const rowsByKey = new Map(config.rows.map((row) => [row.key, row.value]));
+
+  for (const def of SETTINGS) {
+    if (rowsByKey.has(def.key)) continue;
+
+    const envValue = resolveEnvValue(def, "bootstrap");
+    if (!shouldBootstrapValue(def, envValue)) continue;
+
+    await upsertEncryptedRow(def.key, envValue);
+    rowsByKey.set(def.key, envValue);
+    config.stats.envBootstrapped += 1;
+  }
+
+  return [...rowsByKey.entries()].map(([key, value]) => ({ key, value }));
+};
+
+/**
+ * Boot-time normalization + env-bootstrap. Runs once at startup. Does NOT
+ * populate any in-process cache — every read goes through Redis cache-aside
+ * (`store.ts`) at request time.
+ */
+export async function loadCache(): Promise<void> {
+  getAppSecret();
+  const { rows, stats } = await normalizeStoredEntries();
+  const bootstrappedRows = await bootstrapEnvBackedEntries({ rows, stats });
+
+  console.log(
+    `[settings] loaded ${bootstrappedRows.length} custom setting(s) (${stats.encryptedLoaded} encrypted, ${stats.normalizedUpdated} normalized, ${stats.envBootstrapped} env-bootstrapped, ${stats.invalidSkipped} skipped)`,
+  );
+}
+
+/**
+ * Read a setting via the Redis cache-aside layer (always within Redis-TTL
+ * fresh). Resolution: Redis cache → Postgres → env-fallback → code default.
+ */
+export async function get<T = unknown>(key: string): Promise<T> {
+  return readKey(key) as Promise<T>;
+}
+
+/**
+ * Write a setting. Pass `db` to run inside a caller's transaction — then the
+ * caller must also call `invalidateSettingsCache` once it commits.
+ */
+export async function set(key: string, value: unknown, db?: SqlClient): Promise<void> {
+  await writeKey(key, value, db);
+}
+
+export async function remove(key: string, db?: SqlClient): Promise<void> {
+  await deleteKey(key, db);
+}
+
+import type { SettingEntry } from "../../contracts/shared";
+
+export { invalidateSettingsCache } from "./store";
+export type { SettingEntry } from "../../contracts/shared";
+
+export async function getAll(locale?: string): Promise<SettingEntry[]> {
+  // Determine which keys have a custom row in Postgres (vs. falling back to
+  // env / code default). One indexed scan, then bulk-read all values.
+  const customRows = await sql<{ key: string }[]>`SELECT key FROM settings.entries`;
+  const customKeys = new Set(customRows.map((row) => row.key));
+
+  const allKeys = SETTINGS.map((def) => def.key);
+  const values = await bulkRead(allKeys);
+
+  return SETTINGS.map((def) => {
+    const presentation = resolveSettingPresentation(def, locale);
+    const isCustom = customKeys.has(def.key);
+    const envFallback = resolveEnvValue(def, "fallback");
+    const resetValue = envFallback ?? def.default;
+
+    return {
+      key: def.key,
+      label: presentation.label,
+      kind: def.kind,
+      description: presentation.description ?? "",
+      placeholder: presentation.placeholder,
+      group: def.group,
+      value: values.get(def.key),
+      default: def.default,
+      resetValue: def.kind === "secret" ? "" : resetValue,
+      valueSource: isCustom ? "custom" : envFallback === undefined ? "default" : "env",
+      resetValueSource: envFallback === undefined ? "default" : "env",
+      isCustom,
+      templateVars: "templateVars" in def ? def.templateVars : undefined,
+      options: presentation.options,
+      min: "min" in def ? def.min : undefined,
+      max: "max" in def ? def.max : undefined,
+    };
+  });
+}

package/src/services/settings/namespace.ts

@@ -0,0 +1,9 @@
+import { get, getAll, loadCache, remove, set } from "./index";
+
+export const settings = {
+  loadCache,
+  get,
+  set,
+  remove,
+  getAll,
+};