@k2b/cloud 0.40.0 → 0.42.0

package/src/services/session/index.ts

@@ -25,9 +25,12 @@ import {
   type SignInMethod,
   setBrowserCookie,
 } from "../known-browsers";
+import { logger } from "../logging";
 import * as settings from "../settings";
 import { loadJwtSession, loadJwtSessionIdentity } from "./user";
 
+const log = logger("auth:session");
+
 export type SessionKind = "web" | "app";
 
 export type SessionData = {
@@ -90,12 +93,13 @@ const verifyForRequest = (c: Context, token: string): Promise<CloudSessionClaims
 /** Moves the account's authentication epoch, which ends every session issued before it.
  * Request-time expiry uses only this: device operations check expiry themselves and an
  * administrator can lift it, so revoking devices would depend on which request came first. */
-const endSessions = async (db: SQL, userId: string): Promise<void> => {
-  const [updated] = await db<Array<{ id: string }>>`
+const endSessions = async (db: SQL, userId: string): Promise<number> => {
+  const [updated] = await db<Array<{ auth_epoch: string | number | bigint }>>`
     UPDATE auth.users SET auth_epoch = auth_epoch + 1
-    WHERE id = ${userId}::uuid RETURNING id
+    WHERE id = ${userId}::uuid RETURNING auth_epoch
   `;
   if (!updated) throw new Error("Cannot revoke sessions for an unknown user");
+  return Number(updated.auth_epoch);
 };
 
 const authenticateVerified = async (credential: CloudSessionClaims): Promise<AuthenticatedSession | null> => {
@@ -291,7 +295,7 @@ const issueJwtSession = async (
   options: SessionIssueOptions,
   attempt = 0,
   committedNotice: NewBrowserSignInNotice | null = null,
-): Promise<{ token: string; notice: NewBrowserSignInNotice | null }> => {
+): Promise<{ token: string; expiresAt: Date; notice: NewBrowserSignInNotice | null }> => {
   const signer = await prepareIdentitySigner("session");
   let family: PreparedFamily;
   try {
@@ -305,7 +309,7 @@ const issueJwtSession = async (
   }
   const token = await signFamily(family);
   const notice = committedNotice ?? family.notice;
-  if (token) return { token, notice };
+  if (token) return { token, expiresAt: family.expiresAt, notice };
   if (attempt === 0) return issueJwtSession(c, userId, { ...options, sid: undefined }, 1, notice);
   throw new Error("Cloud session signer changed repeatedly during issuance");
 };
@@ -346,6 +350,176 @@ const issueInTransaction = async <T>(
   }
 };
 
+/** Revokes the account's active mobile app phones and records each phone. */
+const revokePhones = async (
+  tx: SQL,
+  userId: string,
+  reason: "sign_out_everywhere" | "sign_out_others" | "password_change" | "password_reset",
+): Promise<void> => {
+  const phones = await tx<Array<{ id: string }>>`
+    UPDATE auth.pwa_devices SET revoked_at = now(), revocation_reason = ${reason}
+    WHERE user_id = ${userId}::uuid AND revoked_at IS NULL RETURNING id
+  `;
+  for (const phone of phones)
+    await audit.record(
+      {
+        action: "auth.pwa.device.revoke",
+        outcome: "allowed",
+        target: { type: "pwa_device", id: phone.id },
+        metadata: { targetUserId: userId, provenance: "system", reason },
+      },
+      tx,
+    );
+};
+
+/** Copies a web family to a new sid, epoch and signer; sign-in time, expiry, origin and the Cloud Login device
+ * that approved it stay the same, so removing that device still ends the copy. */
+const copyFamily = async (tx: SQL, from: string, to: { sid: string; authEpoch: number; kid: string }): Promise<void> => {
+  await tx`
+    INSERT INTO auth.session_families (
+      sid, user_id, auth_epoch, signing_kid, issued_at, expires_at, created_request_id, created_user_agent, legal_pending,
+      pwa_device_id, app_device_id
+    )
+    SELECT ${to.sid}::uuid, user_id, ${to.authEpoch}, ${to.kid}, issued_at, expires_at,
+      created_request_id, created_user_agent, legal_pending, pwa_device_id, app_device_id
+    FROM auth.session_families WHERE sid = ${from}::uuid
+  `;
+};
+
+/** Ends other sign-ins and moves the chosen browser to a new session id with its sign-in time and expiry.
+ * The epoch change ends the account's other browser sessions, its OAuth sign-ins and access tokens, and pending
+ * Cloud Login pairings and device changes; mobile app phones are revoked with an audit entry per phone. Unlike
+ * `revokeAllForUser`, Cloud Login devices stay paired. API keys, passkeys and mandates stay valid.
+ * `keep` is the browser sign-in the request authenticated, with the epoch it was authenticated at. The kept
+ * family is revoked and replaced, so every check by session id rejects old copies of its cookie, and a
+ * request that a concurrent change already ended keeps nothing.
+ * If preparing the signer fails or it stays inactive after one retry, ends all sign-ins without keeping a browser.
+ * If its signer changes after commit, retries once with a new family unless another sign-out intervened.
+ * `kept` is null when no browser was kept: no `keep`, its epoch is no longer current, the family was not
+ * a current active web session of the account, or signing it after the change failed. That browser must
+ * sign in again. */
+const endOtherSignIns = async (
+  userId: string,
+  options: { keep?: { sid: string; authEpoch: number } | null; reason: "password_change" | "password_reset" | "sign_out_others" },
+): Promise<{ kept: { token: string; expiresAt: Date } | null }> => {
+  const extendSigner = async (tx: SQL, signer: PreparedIdentitySigner, expiresAt: Date): Promise<void> => {
+    const [activeKey] = await tx<Array<{ kid: string }>>`
+      UPDATE auth.signing_keys
+      SET verify_until = GREATEST(verify_until, ${new Date(expiresAt.getTime() + IDENTITY_CLOCK_TOLERANCE_SECONDS * 1_000 + IDENTITY_ROLLOUT_MARGIN_MS)})
+      WHERE kid = ${signer.kid} AND purpose = 'session' AND state = 'active' AND sign_until > now()
+      RETURNING kid
+    `;
+    if (!activeKey) throw new Error(SIGNER_INACTIVE);
+  };
+  let keep = options.keep ?? null;
+  for (let attempt = 0; ; attempt += 1) {
+    let signer: PreparedIdentitySigner | null = null;
+    if (keep) {
+      try {
+        signer = await prepareIdentitySigner("session");
+      } catch {
+        log.warn("Could not prepare session signer; ending all sign-ins", { userId });
+        keep = null;
+      }
+    }
+    let family: PreparedFamily | null;
+    try {
+      family = await sql.begin(async (tx): Promise<PreparedFamily | null> => {
+        const [user] = await tx<Array<{ auth_epoch: string | number | bigint }>>`
+          SELECT auth_epoch FROM auth.users WHERE id = ${userId}::uuid FOR NO KEY UPDATE
+        `;
+        if (!user) throw new Error("Cannot revoke sessions for an unknown user");
+        const [kept] =
+          keep && Number(user.auth_epoch) === keep.authEpoch
+            ? // Locking the key orders this keep before a concurrent emergency key revocation. It is the
+              // lock extendSigner takes for the same current key, so concurrent keeps queue instead of deadlocking.
+              await tx<Array<{ sid: string; issued_at: Date; expires_at: Date }>>`
+              SELECT sf.sid, sf.issued_at, sf.expires_at FROM auth.session_families sf
+              JOIN auth.signing_keys sk ON sk.kid = sf.signing_kid AND sk.state <> 'revoked'
+              WHERE sf.sid = ${keep.sid}::uuid AND sf.user_id = ${userId}::uuid
+                AND sf.pwa_device_id IS NULL AND sf.revoked_at IS NULL AND sf.expires_at > now()
+                AND sf.auth_epoch = ${user.auth_epoch}
+              FOR UPDATE OF sf FOR NO KEY UPDATE OF sk
+            `
+            : [];
+        const authEpoch = await endSessions(tx, userId);
+        let prepared: PreparedFamily | null = null;
+        if (kept && signer) {
+          const issuedAt = new Date(kept.issued_at);
+          const expiresAt = new Date(kept.expires_at);
+          await extendSigner(tx, signer, expiresAt);
+          const sid = crypto.randomUUID();
+          await copyFamily(tx, kept.sid, { sid, authEpoch, kid: signer.kid });
+          await tx`
+            UPDATE auth.session_families SET revoked_at = now(), revocation_reason = 'rotated'
+            WHERE sid = ${kept.sid}::uuid
+          `;
+          prepared = {
+            userId,
+            sid,
+            authEpoch,
+            issuedAt,
+            expiresAt,
+            signer,
+            options: { ttlSeconds: (expiresAt.getTime() - issuedAt.getTime()) / 1_000, recordLogin: false },
+            notice: null,
+          };
+        }
+        await revokePhones(tx, userId, options.reason);
+        return prepared;
+      });
+    } catch (error) {
+      if (signer && isSignerInactive(error)) {
+        if (attempt === 0) {
+          invalidateIdentitySignerCache("session", signer.kid);
+          continue;
+        }
+        if (attempt === 1) {
+          log.warn("Session signer stayed inactive; ending all sign-ins", { userId });
+          keep = null;
+          continue;
+        }
+      }
+      throw error;
+    }
+    if (!family) return { kept: null };
+    try {
+      const token = await signFamily(family);
+      if (token) return { kept: { token, expiresAt: family.expiresAt } };
+      const freshSigner = await prepareIdentitySigner("session");
+      const replacement = await sql.begin(async (tx): Promise<PreparedFamily | null> => {
+        const [user] = await tx<Array<{ auth_epoch: string | number | bigint }>>`
+          SELECT auth_epoch FROM auth.users WHERE id = ${userId}::uuid FOR NO KEY UPDATE
+        `;
+        if (!user || Number(user.auth_epoch) !== family.authEpoch) return null;
+        // Device removal can skip this already-revoked family, so the replacement must recheck its device.
+        const [revoked] = await tx<Array<{ sid: string }>>`
+          SELECT sf.sid FROM auth.session_families sf
+          WHERE sf.sid = ${family.sid}::uuid AND sf.user_id = ${userId}::uuid
+            AND sf.revocation_reason = 'signer_revoked_during_issuance'
+            AND (sf.app_device_id IS NULL OR EXISTS (
+              SELECT 1 FROM auth.app_devices d WHERE d.id = sf.app_device_id AND d.revoked_at IS NULL
+            )) FOR UPDATE
+        `;
+        if (!revoked) return null;
+        await extendSigner(tx, freshSigner, family.expiresAt);
+        const sid = crypto.randomUUID();
+        await copyFamily(tx, revoked.sid, { sid, authEpoch: family.authEpoch, kid: freshSigner.kid });
+        return { ...family, sid, signer: freshSigner };
+      });
+      if (!replacement) return { kept: null };
+      const replacementToken = await signFamily(replacement);
+      if (!replacementToken) throw new Error("Cloud session signer changed repeatedly during issuance");
+      return { kept: { token: replacementToken, expiresAt: replacement.expiresAt } };
+    } catch (error) {
+      log.warn("Could not keep browser signed in after ending other sign-ins", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return { kept: null };
+    }
+  }
+};
+
 /** Today's web credential: an explicit non-API bearer, otherwise the `session_token` cookie. */
 const getWebOrBearerToken = (c: Context): string | null => {
   const authorization = c.req.header("Authorization");
@@ -416,7 +590,11 @@ export const session = {
     const ttlSeconds = Math.floor(expiryHours * 60 * 60);
     const cookie = readBrowserCookie(c) ?? newBrowserCookie();
     const { browser, os, country, city } = describeRequest(c);
-    const { token: clientToken, notice } = await issueJwtSession(c, userId, {
+    const {
+      token: clientToken,
+      expiresAt,
+      notice,
+    } = await issueJwtSession(c, userId, {
       ttlSeconds,
       authEpoch: signIn.authEpoch,
       appDeviceId: signIn.appDeviceId,
@@ -435,17 +613,25 @@ export const session = {
     // Handoff precedes the response so the person signing in cannot turn the notice off first.
     if (signIn.notify !== null && notice) await announceNewBrowser(signIn.notify, notice);
 
-    setCookie(c, "session_token", clientToken, {
+    session.setWebCookie(c, clientToken, expiresAt);
+    setBrowserCookie(c, cookie);
+    return clientToken;
+  },
+
+  /** Sets the `session_token` cookie the way `create` does. Use it for the token that `endOtherSignIns` keeps:
+   * the max age runs to `expiresAt`, so that browser keeps its original expiry. */
+  setWebCookie: (c: Context, token: string, expiresAt: Date): void => {
+    setCookie(c, "session_token", token, {
       httpOnly: true,
       secure: !env.IS_DEVELOPMENT,
       sameSite: "Lax",
-      maxAge: ttlSeconds,
+      maxAge: Math.max(0, Math.floor((expiresAt.getTime() - Date.now()) / 1_000)),
       path: "/",
     });
-    setBrowserCookie(c, cookie);
-    return clientToken;
   },
 
+  endOtherSignIns,
+
   revoke: revokeToken,
 
   /** Signs out the web session (or an explicit bearer session). The mobile app's session is unaffected. */
@@ -457,25 +643,12 @@ export const session = {
 
   issueInTransaction,
 
-  /** Signs the account out everywhere: every session, every paired sign-in device and every paired phone, audited per device. */
-  revokeAllForUser: async (userId: string): Promise<void> => {
-    await sql.begin(async (tx) => {
-      await endSessions(tx, userId);
-      // The epoch change already ends the phones; revoking them keeps lists and the audit log truthful.
-      const phones = await tx<Array<{ id: string }>>`
-        UPDATE auth.pwa_devices SET revoked_at = now(), revocation_reason = 'sign_out_everywhere'
-        WHERE user_id = ${userId}::uuid AND revoked_at IS NULL RETURNING id
-      `;
-      for (const phone of phones)
-        await audit.record(
-          {
-            action: "auth.pwa.device.revoke",
-            outcome: "allowed",
-            target: { type: "pwa_device", id: phone.id },
-            metadata: { targetUserId: userId, provenance: "system", reason: "sign_out_everywhere" },
-          },
-          tx,
-        );
+  /** Signs the account out everywhere: every session, every paired sign-in device and every paired phone, audited per device.
+   * Returns the new authentication epoch so a following sign-in can stay bound to this sign-out. */
+  revokeAllForUser: async (userId: string): Promise<number> => {
+    return sql.begin(async (tx) => {
+      const authEpoch = await endSessions(tx, userId);
+      await revokePhones(tx, userId, "sign_out_everywhere");
       // A paired device approves new sign-ins on its own, so a lost one would outlive the epoch change.
       const devices = await tx<Array<{ id: string }>>`
         UPDATE auth.app_devices SET revoked_at = now() WHERE user_id = ${userId}::uuid AND revoked_at IS NULL RETURNING id
@@ -490,6 +663,7 @@ export const session = {
           },
           tx,
         );
+      return authEpoch;
     });
   },
 

package/src/services/settings/app.ts

@@ -13,6 +13,7 @@ import { ImageMetadataError } from "../image-metadata";
 import type { SettingEntry } from ".";
 import * as settingsPrimitives from ".";
 import { SETTINGS_MAP, validateSettingValue } from "./defaults";
+import { GeoBudgetSettingError } from "./geo-budget";
 import { SettingUnreadableError } from "./store";
 
 /**
@@ -69,7 +70,8 @@ export const settingsService = {
         return ok(undefined);
       } catch (error) {
         // Preserve the typed HTTP status and recovery code through Hono.
-        if (error instanceof ImageMetadataError || error instanceof SettingUnreadableError) throw error;
+        if (error instanceof ImageMetadataError || error instanceof SettingUnreadableError || error instanceof GeoBudgetSettingError)
+          throw error;
         const message = error instanceof Error ? error.message : String(error);
         if (message.startsWith("Unknown setting:")) {
           return fail(err.badInput(message));
@@ -85,6 +87,7 @@ export const settingsService = {
         await settingsPrimitives.remove(config.key);
         return ok(undefined);
       } catch (error) {
+        if (error instanceof GeoBudgetSettingError) throw error;
         return fail(err.internal(`Failed to reset setting: ${error instanceof Error ? error.message : String(error)}`));
       }
     },

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

@@ -1,4 +1,5 @@
 import { env } from "../../config/env";
+import { GEO_MAX_CREDITS, GEO_MAX_RPS } from "../../contracts/geo-admin";
 
 /**
  * Platform-owned settings, declared in the `defineApp({ settings: ... })` shape.
@@ -204,6 +205,93 @@ export const CORE_SETTINGS = {
     description: "Five-field cron schedule used by all automatic cleanup jobs in app.timezone",
   },
 
+  // ── Places and addresses ──────────────────────────────────────────────
+  "geo.api_key": {
+    kind: "secret",
+    label: "Geoapify API key",
+    description: "Used only for HTTPS requests to the fixed EU endpoint.",
+    default: "",
+    presentation: {
+      translations: { de: { label: "Geoapify-Schlüssel", description: "Nur für HTTPS-Anfragen an den festen EU-Endpunkt." } },
+    },
+  },
+  "geo.plan": {
+    kind: "enum",
+    label: "Geoapify plan",
+    description: "Sets requests per second and the provider daily allowance.",
+    default: "free",
+    options: [
+      { value: "free", label: "Free" },
+      { value: "api10", label: "API 10" },
+      { value: "api25", label: "API 25" },
+      { value: "api50", label: "API 50" },
+      { value: "api100", label: "API 100" },
+      { value: "api250", label: "API 250" },
+      { value: "custom", label: "Custom" },
+    ],
+    presentation: {
+      translations: {
+        de: {
+          label: "Geoapify-Tarif",
+          description: "Bestimmt Anfragen pro Sekunde und das Tageskontingent des Anbieters.",
+          options: { custom: "Eigener" },
+        },
+      },
+    },
+  },
+  "geo.custom_rps": {
+    kind: "number",
+    label: "Custom requests per second",
+    description: "Used only with the custom plan.",
+    default: 5,
+    integer: true,
+    min: 1,
+    max: GEO_MAX_RPS,
+    presentation: { translations: { de: { label: "Eigene Anfragen pro Sekunde", description: "Gilt nur beim eigenen Tarif." } } },
+  },
+  "geo.custom_daily_credits": {
+    kind: "number",
+    label: "Custom daily provider credits",
+    description: "Provider allowance; used only with the custom plan.",
+    default: 3000,
+    integer: true,
+    min: 1,
+    max: GEO_MAX_CREDITS,
+    presentation: {
+      translations: { de: { label: "Eigene tägliche Anbieter-Credits", description: "Anbieterkontingent; gilt nur beim eigenen Tarif." } },
+    },
+  },
+  "geo.monthly_budget_credits": {
+    kind: "number",
+    label: "Monthly geo budget (credits)",
+    description: "Cloud-wide hard limit per calendar month in app.timezone.",
+    default: 90000,
+    integer: true,
+    min: 0,
+    max: GEO_MAX_CREDITS,
+    presentation: {
+      translations: { de: { label: "Monatsbudget Geo (Credits)", description: "Harte Cloud-Grenze je Kalendermonat in app.timezone." } },
+    },
+  },
+  "geo.person_daily_credits": {
+    kind: "number",
+    label: "Daily geo credits per person",
+    description: "Hard limit per access subject and local day; must not exceed the monthly budget. Agents and service accounts count too.",
+    default: 300,
+    integer: true,
+    min: 0,
+    max: GEO_MAX_CREDITS,
+    presentation: {
+      translations: {
+        de: {
+          label: "Tägliche Geo-Credits pro Person",
+          description:
+            "Harte Grenze je Zugriffsidentität und lokalem Tag; darf das Monatsbudget nicht überschreiten. Gilt auch für Agenten und Dienstkonten.",
+        },
+      },
+    },
+  },
+
   // ── AI ──────────────────────────────────────────────────────────────────
   "ai.enabled": {
     kind: "boolean",

package/src/services/settings/defaults.ts

@@ -162,7 +162,13 @@ export const SETTINGS: SettingDef[] = [
   ...toLegacySettingDefs(CORE_SETTINGS),
 ];
 
-const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+// Keep the existing permissive grammar without ambiguous regex backtracking.
+const isEmail = (value: string): boolean => {
+  const at = value.indexOf("@");
+  if (at < 1 || value.indexOf("@", at + 1) !== -1 || /\s/.test(value)) return false;
+  const dot = value.indexOf(".", at + 2);
+  return dot !== -1 && dot < value.length - 1;
+};
 
 const toStringValue = (value: unknown): string | null => {
   if (typeof value === "string") return value;
@@ -303,7 +309,7 @@ export const validateSettingValue = (def: SettingDef, raw: unknown): SettingVali
         : { 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)
+      return value.length === 0 || isEmail(value)
         ? { ok: true, value }
         : { ok: false, error: `${getSettingLabel(def)} must be a valid email address` };
     case "url":

package/src/services/settings/errors.ts

@@ -0,0 +1,11 @@
+import { HTTPException } from "hono/http-exception";
+
+export class SettingUnreadableError extends HTTPException {
+  readonly code = "setting_unreadable" as const;
+
+  constructor(readonly key: string) {
+    const message = `The stored value of setting "${key}" cannot be read by this application. Replace it with a new value or reset it to the default.`;
+    super(409, { message, res: Response.json({ code: "setting_unreadable", message }, { status: 409 }) });
+    this.name = "SettingUnreadableError";
+  }
+}

package/src/services/settings/geo-budget.ts

@@ -0,0 +1,40 @@
+import type { sql } from "bun";
+import { HTTPException } from "hono/http-exception";
+import { decryptValue } from "./crypto";
+import { SETTINGS_MAP, validateSettingValue } from "./defaults";
+import { SettingUnreadableError } from "./errors";
+
+const MONTH = "geo.monthly_budget_credits";
+const DAY = "geo.person_daily_credits";
+export class GeoBudgetSettingError extends HTTPException {
+  readonly code = "geo_budget_invalid";
+  constructor() {
+    const message = "Daily geo credits must not exceed the monthly geo budget";
+    super(400, {
+      message,
+      res: Response.json({ code: "geo_budget_invalid", message, errors: { [DAY]: message, [MONTH]: message } }, { status: 400 }),
+    });
+  }
+}
+/** Validate the final pair once, holding the lock until the caller commits all mutations. */
+export const assertGeoBudgetPair = async (tx: typeof sql, updates: Record<string, unknown>, resets: readonly string[]): Promise<void> => {
+  if (![MONTH, DAY].some((key) => Object.hasOwn(updates, key) || resets.includes(key))) return;
+  await tx`SELECT pg_advisory_xact_lock(hashtextextended('core.geo.budget-settings', 0))`;
+  const resolve = async (key: string): Promise<unknown> => {
+    if (Object.hasOwn(updates, key)) return updates[key];
+    const def = SETTINGS_MAP.get(key);
+    if (resets.includes(key)) return def?.default;
+    const [row] = await tx<{ value: string }[]>`SELECT value FROM settings.entries WHERE key=${key}`;
+    if (!row) return def?.default;
+    try {
+      const value = await decryptValue(row.value);
+      if (def && validateSettingValue(def, value).ok) return value;
+    } catch {
+      // Recovery can replace or reset a row without decrypting its old value.
+    }
+    throw new SettingUnreadableError(key);
+  };
+  const month = await resolve(MONTH);
+  const day = await resolve(DAY);
+  if (typeof month !== "number" || typeof day !== "number" || day > month) throw new GeoBudgetSettingError();
+};

package/src/services/settings/index.ts

@@ -185,14 +185,15 @@ export async function get<T = unknown>(key: string): Promise<T> {
 
 /**
  * Write a setting. Pass `db` to run inside a caller's transaction — then the
- * caller must also call `invalidateSettingsCache` once it commits.
+ * caller owns geo budget pair validation before mutations and must call
+ * `invalidateSettingsCache` once it commits.
  */
 export async function set(key: string, value: unknown, db?: SqlClient, options?: { replaceUnreadable?: boolean }): Promise<void> {
   await writeKey(key, value, db, options);
 }
 
-export async function read(key: string): Promise<SettingRead> {
-  return readKeyState(key);
+export async function read(key: string, db?: SqlClient): Promise<SettingRead> {
+  return readKeyState(key, db);
 }
 
 export async function remove(key: string, db?: SqlClient): Promise<void> {

package/src/services/settings/store.ts

@@ -22,6 +22,10 @@ import { toPgTextArray } from "../postgres";
 import { requestCacheRedis } from "../request-cache-redis";
 import { decryptValue, encryptValue } from "./crypto";
 import { SETTINGS, SETTINGS_MAP, type SettingDef, validateSettingValue } from "./defaults";
+import { SettingUnreadableError } from "./errors";
+import { assertGeoBudgetPair } from "./geo-budget";
+
+export { SettingUnreadableError } from "./errors";
 
 const REDIS_KEY = (k: string) => `settings:${k}`;
 
@@ -30,16 +34,6 @@ type SqlClient = typeof sql;
 export type StoredSettingState = "none" | "readable" | "unreadable";
 export type SettingRead = { value: unknown; stored: StoredSettingState };
 
-export class SettingUnreadableError extends HTTPException {
-  readonly code = "setting_unreadable" as const;
-
-  constructor(readonly key: string) {
-    const message = `The stored value of setting "${key}" cannot be read by this application. Replace it with a new value or reset it to the default.`;
-    super(409, { message, res: Response.json({ code: "setting_unreadable", message }, { status: 409 }) });
-    this.name = "SettingUnreadableError";
-  }
-}
-
 /**
  * Forget cached values so every container re-reads on next access.
  *
@@ -83,8 +77,8 @@ const resolveFallback = (def: SettingDef | undefined): unknown => {
  */
 export const readKey = async (key: string): Promise<unknown> => (await bulkRead([key])).get(key);
 
-export const readKeyState = async (key: string): Promise<SettingRead> => {
-  const state = (await readStates([key])).get(key);
+export const readKeyState = async (key: string, db: SqlClient = sql): Promise<SettingRead> => {
+  const state = (await readStates([key], db)).get(key);
   if (!state) throw new Error(`Missing read state for setting "${key}"`);
   return state;
 };
@@ -155,10 +149,10 @@ export const bulkRead = async (keys: readonly string[]): Promise<Map<string, unk
  * State reads go directly to Postgres without reading or filling the cache;
  * value reads (`get`, snapshot) keep using the cache.
  */
-export const readStates = async (keys: readonly string[]): Promise<Map<string, SettingRead>> => {
+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 sql<StoredRow[]>`SELECT key, value FROM settings.entries WHERE key = ANY(${toPgTextArray([...keys])}::text[])`;
+  const rows = await db<StoredRow[]>`SELECT key, value FROM settings.entries WHERE key = ANY(${toPgTextArray([...keys])}::text[])`;
   const byKey = new Map(rows.map((row) => [row.key, row]));
   for (const key of keys) {
     const row = byKey.get(key);
@@ -233,6 +227,8 @@ export const deleteLegacyKeys = async (extraKnownKeys: readonly string[] = []):
  * the caller explicitly replaces them. The row check and write share a transaction.
  * Lock with a no-op UPDATE so ROW EXCLUSIVE is acquired before the row lock,
  * preserving lock order with table-level SHARE locks (#1303 review).
+ * A caller passing `db` owns geo budget pair validation before mutations and
+ * cache invalidation after commit.
  */
 export const writeKey = async (key: string, value: unknown, db?: SqlClient, options?: { replaceUnreadable?: boolean }): Promise<void> => {
   const def = SETTINGS_MAP.get(key);
@@ -274,16 +270,28 @@ export const writeKey = async (key: string, value: unknown, db?: SqlClient, opti
     throw new Error(`Could not write setting "${key}" after 3 attempts`);
   };
   if (db) await write(db);
-  else await sql.begin(write);
+  else
+    await sql.begin(async (tx) => {
+      await assertGeoBudgetPair(tx, { [key]: validated.value }, []);
+      await write(tx);
+    });
 
   // Passing a transaction means the caller owns invalidation, because the row
   // is not visible to anyone else until they commit.
   if (!db) await invalidateSettingsCache([key]);
 };
 
-/** Delete the DB row and invalidate Redis. See writeKey for the `db` contract. */
+/** 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> => {
-  await (db ?? sql)`DELETE FROM settings.entries WHERE key = ${key}`;
+  const remove = async (tx: SqlClient) => {
+    await tx`DELETE FROM settings.entries WHERE key = ${key}`;
+  };
+  if (db) await remove(db);
+  else
+    await sql.begin(async (tx) => {
+      await assertGeoBudgetPair(tx, {}, [key]);
+      await remove(tx);
+    });
   if (!db) await invalidateSettingsCache([key]);
 };