@k2b/cloud 0.41.0 → 0.42.0

package/src/services/outgoing-mail/store.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { type SQL, sql } from "bun";
 import { listApps } from "../../_internal/registry";
 import {
@@ -25,7 +26,7 @@ export class OutgoingMailError extends Error {
   constructor(
     public readonly code: MailErrorCode,
     message: string,
-    public readonly status: 400 | 403 | 404 | 409 | 502 = 400,
+    public readonly status: 400 | 403 | 404 | 409 | 502 | 503 = 400,
   ) {
     super(message);
   }
@@ -245,8 +246,8 @@ const appsState = async (
   const registered = registeredApps ?? (await listApps());
   const { access, grants } = await accessRows(db);
   const [profile] = await db<{ key: string }[]>`SELECT key FROM outgoing_mail.profiles WHERE is_default`;
-  const logGrants = await db<{ app_id: string; source_app_id: string }[]>`
-    SELECT app_id, source_app_id FROM outgoing_mail.app_log_access ORDER BY source_app_id`;
+  const logGrants = await db<{ app_id: string; source_app_id: string; level: string }[]>`
+    SELECT app_id, source_app_id, level FROM outgoing_mail.app_log_access ORDER BY source_app_id`;
   const ids = new Set([...registered.map((app) => app.id), ...access.map((a) => a.app_id), ...logGrants.map((g) => g.app_id)]);
   const items = [...ids]
     .map((appId): AdminMailApp => {
@@ -264,6 +265,12 @@ const appsState = async (
             : logGrants
                 .filter((g) => g.app_id === appId && g.source_app_id !== "core" && g.source_app_id !== appId)
                 .map((g) => g.source_app_id),
+        logContentApps:
+          appId === "core"
+            ? []
+            : logGrants
+                .filter((g) => g.app_id === appId && g.source_app_id !== "core" && g.source_app_id !== appId && g.level === "content")
+                .map((g) => g.source_app_id),
         mode,
         profiles: mode === "selected" ? grants.filter((g) => g.app_id === appId).map((g) => g.key) : [],
       };
@@ -300,6 +307,7 @@ const setAppAccess = async (appId: string, value: MailAppAccess, context: MailAu
         declared: false,
         readDeclared: false,
         logApps: [],
+        logContentApps: [],
         mode: "default",
         profiles: [],
       }
@@ -312,19 +320,40 @@ const logAppsFor = async (appId: string): Promise<string[]> => {
     WHERE app_id = ${appId} AND source_app_id <> 'core' AND source_app_id <> app_id ORDER BY source_app_id`;
   return rows.map((row) => row.source_app_id);
 };
+/** Full exact IDs remain distinguishable after audit metadata string truncation. */
+export const mailAppIdSha256 = (appId: string): string => createHash("sha256").update(appId, "utf8").digest("hex");
+const grantAuditGroups = (grants: { source_app_id: string; level: string }[]) => {
+  const entries = grants.map((grant) => ({
+    appId: grant.source_app_id,
+    appIdSha256: mailAppIdSha256(grant.source_app_id),
+    level: grant.level,
+  }));
+  // Audit arrays retain at most 50 entries; the public grant limit is 100.
+  return [entries.slice(0, 50), entries.slice(50)];
+};
 const setAppLogAccess = async (appId: string, value: MailLogAccess, context: MailAuditContext): Promise<AdminMailApp> => {
   const reader = MailLogAppIdSchema.safeParse(appId);
   const parsed = MailLogAccessSchema.safeParse(value);
   if (!reader.success || appId === "core" || !parsed.success || parsed.data.apps.includes(appId))
     throw new OutgoingMailError("bad_input", "Choose a valid reader and distinct source apps other than Core or the reader itself.");
   const apps = [...parsed.data.apps].sort();
+  const contentApps = parsed.data.contentApps ?? [];
   const registered = await listApps();
   return locked(async (tx) => {
+    const before = await tx<{ source_app_id: string; level: string }[]>`
+      SELECT source_app_id, level FROM outgoing_mail.app_log_access WHERE app_id = ${appId} ORDER BY source_app_id`;
     await tx`DELETE FROM outgoing_mail.app_log_access WHERE app_id = ${appId}`;
-    await tx`INSERT INTO outgoing_mail.app_log_access(app_id, source_app_id, created_by)
-      SELECT ${appId}, source_app_id, ${context.actor.userId ?? null}
+    await tx`INSERT INTO outgoing_mail.app_log_access(app_id, source_app_id, created_by, level)
+      SELECT ${appId}, source_app_id, ${context.actor.userId ?? null},
+        CASE WHEN source_app_id = ANY(${toPgTextArray(contentApps)}::text[]) THEN 'content' ELSE 'metadata' END
       FROM unnest(${toPgTextArray(apps)}::text[]) AS source_app_id`;
-    await record(tx, context, "app_log_access.update", appId, { apps });
+    await record(tx, context, "app_log_access.update", appId, {
+      apps,
+      readingAppId: appId,
+      readingAppIdSha256: mailAppIdSha256(appId),
+      before: grantAuditGroups(before),
+      after: grantAuditGroups(apps.map((id) => ({ source_app_id: id, level: contentApps.includes(id) ? "content" : "metadata" }))),
+    });
     return (
       (await appsState(tx, registered)).items.find((app) => app.appId === appId) ?? {
         appId,
@@ -333,6 +362,7 @@ const setAppLogAccess = async (appId: string, value: MailLogAccess, context: Mai
         declared: false,
         readDeclared: false,
         logApps: [],
+        logContentApps: [],
         mode: "default",
         profiles: [],
       }

package/src/services/outgoing-mail/test-send.ts

@@ -1,4 +1,6 @@
+import { Socket } from "node:net";
 import { audit } from "../audit";
+import { DownstreamBusyError, downstreamBudget } from "../downstream-budget";
 import { get } from "../settings";
 import { type MailAuditContext, OutgoingMailError, resolveMailCredentials } from "./store";
 import { resolveMailTransport } from "./transport";
@@ -18,22 +20,48 @@ export const outgoingMailTest = {
     // Fail before the external effect if audit storage is unavailable.
     await audit.record({ ...event, outcome: "allowed" });
     let transport: ReturnType<Awaited<ReturnType<typeof resolveMailTransport>>["build"]> | undefined;
+    const signal = AbortSignal.timeout(60_000);
+    let socket: Socket | undefined;
+    const stop = () => {
+      socket?.destroy();
+      transport?.close();
+    };
+    signal.addEventListener("abort", stop, { once: true });
+    let releaseSmtp: (() => void) | undefined;
     try {
-      const resolved = await resolveMailTransport(profile);
+      releaseSmtp = await downstreamBudget.acquire({ downstream: "smtp", timeoutMs: 60_000, signal });
+      const resolved = await resolveMailTransport(profile, signal);
+      const build = (index: number) => {
+        socket = new Socket();
+        const ownedSocket = socket;
+        ownedSocket.once("connect", () => {
+          if (signal.aborted) ownedSocket.destroy();
+        });
+        return resolved.build(index, ownedSocket);
+      };
+      let selected = 0;
       for (let index = 0; index < resolved.count; index++) {
-        transport = resolved.build(index);
+        signal.throwIfAborted();
+        transport = build(index);
         try {
           // CONN also labels socket errors after DATA. Only fall back during a
           // preflight that cannot send a message, then send once to that address.
           await transport.verify();
+          selected = index;
           break;
         } catch (error) {
+          socket?.destroy();
           transport.close();
           transport = undefined;
           if (!(error instanceof Error) || !("command" in error) || error.command !== "CONN" || index === resolved.count - 1) throw error;
         }
       }
       if (!transport) throw new Error("No validated SMTP address.");
+      // verify() closes its SMTP connection. The actual send gets a fresh
+      // owned socket to the same checked address, with no delivery fallback.
+      stop();
+      signal.throwIfAborted();
+      transport = build(selected);
       await transport.sendMail({
         from: { address: profile.fromAddress, name: profile.fromName ?? (await get<string>("app.name")) },
         to: recipient,
@@ -47,9 +75,11 @@ export const outgoingMailTest = {
         profile.smtpUser ? `\0${profile.smtpUser}\0${profile.smtpPassword ?? ""}` : null,
       ]);
       await audit.recordResultAfterSideEffect({ ...event, result: { ok: false, error: { code: "smtp_failed", message, status: 500 } } });
-      throw new OutgoingMailError("smtp_failed", message, 502);
+      throw new OutgoingMailError("smtp_failed", message, error instanceof DownstreamBusyError ? 503 : 502);
     } finally {
-      transport?.close();
+      signal.removeEventListener("abort", stop);
+      stop();
+      releaseSmtp?.();
     }
   },
 };

package/src/services/outgoing-mail/transport.ts

@@ -4,7 +4,7 @@ import { resolveMailHost } from "./resolve-host";
 import type { resolveMailCredentials } from "./store";
 
 export const resolveMailTransport = async (profile: Awaited<ReturnType<typeof resolveMailCredentials>>, signal?: AbortSignal) => {
-  const target = await resolveMailHost(profile.smtpHost, signal);
+  const target = await resolveMailHost(profile.smtpHost, signal, undefined, profile.smtpPort);
   signal?.throwIfAborted();
   const count = target.addresses.length;
   return {

package/src/services/pdf/gotenberg.ts

@@ -1,7 +1,9 @@
+import { DownstreamBusyError, downstreamBudget } from "../downstream-budget";
 import * as settings from "../settings";
 import { offlineHtml } from "./offline-html";
 
 export type GotenbergRenderErrorCode =
+  | "busy"
   | "bad_input"
   | "not_configured"
   | "html_too_large"
@@ -117,6 +119,7 @@ const abortSignal = (timeoutMs: number): AbortSignal => {
 
 const sanitizeFetchError = (error: unknown): GotenbergRenderError => {
   if (error instanceof GotenbergRenderError) return error;
+  if (error instanceof DownstreamBusyError) return new GotenbergRenderError("busy", "PDF renderer is busy; retry later.", 503);
   if (error instanceof DOMException && error.name === "TimeoutError") {
     return new GotenbergRenderError("timeout", "Gotenberg request timed out.");
   }
@@ -179,10 +182,14 @@ async function requestPdf(
   const headers = new Headers();
   const auth = basicAuthHeader(config);
   if (auth) headers.set("Authorization", auth);
+  const baseUrl = normalizeBaseUrl(config.url);
   const signal = options.signal ? AbortSignal.any([options.signal, abortSignal(config.timeoutMs)]) : abortSignal(config.timeoutMs);
+  let release: (() => void) | undefined;
   let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
   try {
-    const response = await (options.fetch ?? fetch)(`${normalizeBaseUrl(config.url)}${route}`, {
+    release = await downstreamBudget.acquire({ downstream: "gotenberg", timeoutMs: config.timeoutMs, signal });
+    signal.throwIfAborted();
+    const response = await (options.fetch ?? fetch)(`${baseUrl}${route}`, {
       method: "POST",
       headers,
       body: form,
@@ -221,6 +228,7 @@ async function requestPdf(
     throw sanitizeFetchError(error);
   } finally {
     reader?.releaseLock();
+    release?.();
   }
 }
 
@@ -285,47 +293,12 @@ export const mergePdfsWithConfig = async (
     throw new GotenbergRenderError("bad_input", "At least one PDF file is required.");
   }
 
-  const baseUrl = normalizeBaseUrl(config.url);
   const form = new FormData();
   input.files.forEach((file, index) => {
     const filename = `${String(index + 1).padStart(6, "0")}.pdf`;
-    const bytes = file.pdf.buffer.slice(file.pdf.byteOffset, file.pdf.byteOffset + file.pdf.byteLength) as ArrayBuffer;
-    form.append("files", new Blob([bytes], { type: DEFAULT_PDF_CONTENT_TYPE }), filename);
+    form.append("files", new Blob([new Uint8Array(file.pdf)], { type: DEFAULT_PDF_CONTENT_TYPE }), filename);
   });
-
-  const headers = new Headers();
-  const authHeader = basicAuthHeader(config);
-  if (authHeader) headers.set("Authorization", authHeader);
-
-  const transport = options.fetch ?? fetch;
-  let response: Response;
-  try {
-    response = await transport(`${baseUrl}/forms/pdfengines/merge`, {
-      method: "POST",
-      headers,
-      body: form,
-      signal: abortSignal(config.timeoutMs),
-    });
-  } catch (error) {
-    throw sanitizeFetchError(error);
-  }
-
-  if (!response.ok) {
-    throw new GotenbergRenderError("bad_response", `Gotenberg returned HTTP ${response.status}.`, response.status);
-  }
-
-  const buffer = await response.arrayBuffer();
-  if (buffer.byteLength > config.maxPdfBytes) {
-    throw new GotenbergRenderError(
-      "pdf_too_large",
-      `PDF output is too large (${buffer.byteLength} bytes, limit ${config.maxPdfBytes} bytes).`,
-    );
-  }
-
-  return {
-    pdf: new Uint8Array(buffer),
-    contentType: response.headers.get("content-type") || DEFAULT_PDF_CONTENT_TYPE,
-  };
+  return requestPdf("/forms/pdfengines/merge", form, config, options);
 };
 
 export const getGotenbergConfig = async (): Promise<GotenbergConfig> => ({

package/src/services/pdf/template-preview.ts

@@ -47,7 +47,7 @@ export type RenderTemplatePdfPreviewOptions = RenderHtmlToPdfOptions & {
   config?: GotenbergConfig;
 };
 
-const pdfErrorStatus = (error: GotenbergRenderError): number => (error.code === "not_configured" ? 400 : 502);
+const pdfErrorStatus = (error: GotenbergRenderError): number => (error.code === "busy" ? 503 : error.code === "not_configured" ? 400 : 502);
 
 const renderPart = (
   template: string | null | undefined,

package/src/services/public-http.ts

@@ -1,6 +1,7 @@
 import type { ClientRequest, IncomingMessage } from "node:http";
 import { type RequestOptions, request } from "node:https";
 import { resolvePublicNetworkAddresses } from "./network-security";
+import { awaitNetworkOperation, readNetworkResponse } from "./network-transport";
 
 export type PublicHttpInput = {
   url: string;
@@ -24,29 +25,21 @@ export async function requestPublicHttps(
   const url = new URL(input.url);
   if (url.protocol !== "https:" || url.username || url.password) throw new Error("HTTPS_REQUIRED");
   input.signal.throwIfAborted();
-  let cancelLookup = () => {};
-  const addresses = await Promise.race([
-    dependencies.resolve(url.hostname),
-    new Promise<never>((_, reject) => {
-      cancelLookup = () => reject(new Error("HTTP_CANCELLED"));
-      input.signal.addEventListener("abort", cancelLookup, { once: true });
-      if (input.signal.aborted) cancelLookup();
-    }),
-  ]).finally(() => input.signal.removeEventListener("abort", cancelLookup));
+  let addresses: Awaited<ReturnType<typeof resolvePublicNetworkAddresses>>;
+  try {
+    addresses = await awaitNetworkOperation(dependencies.resolve(url.hostname), input.signal);
+  } catch (error) {
+    if (input.signal.aborted) throw new Error("HTTP_CANCELLED");
+    throw error;
+  }
   input.signal.throwIfAborted();
   const target = addresses[0]!;
-  return new Promise<{ status: number; headers: Record<string, string>; body: Uint8Array }>((resolve, reject) => {
-    let settled = false;
-    const fail = () => finish(undefined);
-    const finish = (value?: { status: number; headers: Record<string, string>; body: Uint8Array }) => {
-      if (settled) return;
-      settled = true;
-      input.signal.removeEventListener("abort", abort);
-      if (value) resolve(value);
-      else reject(new Error("HTTP_FAILED"));
-    };
-    const outgoing = dependencies.request(
-      {
+  try {
+    return await readNetworkResponse<{ status: number; headers: Record<string, string>; body: Uint8Array }>({
+      request: dependencies.request,
+      signal: input.signal,
+      body: input.body,
+      options: {
         hostname: target.address,
         family: target.family,
         port: url.port || 443,
@@ -56,7 +49,7 @@ export async function requestPublicHttps(
         method: input.method,
         headers: { ...input.headers, host: url.host, "accept-encoding": "identity" },
       },
-      (incoming) => {
+      read: (incoming, finish, fail) => {
         const status = incoming.statusCode ?? 0;
         const headers: Record<string, string> = {};
         for (const name of ["content-type", "retry-after", "etag", "last-modified"]) {
@@ -65,37 +58,32 @@ export async function requestPublicHttps(
         }
         // A redirect never receives a second request or exposes a Location token.
         if (status >= 300 && status < 400 && status !== 304) {
-          incoming.destroy();
           finish({ status, headers, body: new Uint8Array() });
           return;
         }
         if (incoming.headers["content-encoding"] && incoming.headers["content-encoding"] !== "identity") {
-          incoming.destroy();
-          fail();
+          fail(new Error("HTTP_FAILED"));
+          return;
+        }
+        if (Number(incoming.headers["content-length"]) > input.maxBytes) {
+          fail(new Error("HTTP_TOO_LARGE"));
           return;
         }
         const chunks: Uint8Array[] = [];
         let bytes = 0;
         incoming.on("data", (chunk: Buffer) => {
-          if (settled) return;
+          if (incoming.destroyed) return;
           bytes += chunk.byteLength;
           if (bytes > input.maxBytes) {
-            incoming.destroy();
-            fail();
+            fail(new Error("HTTP_TOO_LARGE"));
           } else chunks.push(chunk);
         });
         incoming.on("end", () => finish({ status, headers, body: Buffer.concat(chunks, bytes) }));
-        incoming.on("error", fail);
-        incoming.on("aborted", fail);
       },
-    );
-    const abort = () => {
-      outgoing.destroy();
-      fail();
-    };
-    outgoing.on("error", fail); // Never expose errors containing injected headers.
-    input.signal.addEventListener("abort", abort, { once: true });
-    if (input.signal.aborted) abort();
-    else outgoing.end(input.body);
-  });
+    });
+  } catch (error) {
+    if (error instanceof Error && error.message === "HTTP_TOO_LARGE") throw error;
+    // Never expose errors containing injected headers.
+    throw new Error("HTTP_FAILED");
+  }
 }

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> {