@k2b/cloud 0.41.0 → 0.42.0

package/src/services/geo/admin.ts

@@ -0,0 +1,262 @@
+import { type SQL, sql } from "bun";
+import { HTTPException } from "hono/http-exception";
+import {
+  GEO_USAGE_GROUPS,
+  type GeoAdminPerson,
+  type GeoAdminStatus,
+  type GeoAdminUsage,
+  type GeoBudgetField,
+  type GeoBudgetFieldError,
+  type GeoBudgetInput,
+  type GeoKeyError,
+  geoKeyProblem,
+  validateGeoBudget,
+} from "../../contracts/geo-admin";
+import { audit } from "../audit";
+import { toPgTextArray } from "../postgres";
+import * as settings from "../settings";
+import { decryptValue } from "../settings/crypto";
+import { SETTINGS_MAP, validateSettingValue } from "../settings/defaults";
+import { assertGeoBudgetPair } from "../settings/geo-budget";
+import { GeoProviderError } from "./errors";
+import { GeoapifyAdapter } from "./geoapify";
+import { geoPeriods } from "./ledger";
+import { GEO_PLANS, readGeoConfig } from "./settings";
+
+type Actor = { id: string; roles: readonly string[]; uid?: string; provider?: string };
+
+const KEY = "geo.api_key";
+const PLAN_KEY = "geo.plan";
+const BUDGET_FIELDS: ReadonlyArray<[GeoBudgetField, string]> = [
+  ["customRps", "geo.custom_rps"],
+  ["customDailyCredits", "geo.custom_daily_credits"],
+  ["monthlyCredits", "geo.monthly_budget_credits"],
+  ["personDailyCredits", "geo.person_daily_credits"],
+];
+const BUDGET_KEYS = [PLAN_KEY, ...BUDGET_FIELDS.map(([, name]) => name)];
+const KEY_ACTION = "core.geo.key_set";
+const BUDGET_ACTION = "core.geo.budget_changed";
+/** A known place for the verification lookup; any answer that is not a key refusal proves the key works. */
+const PROBE = { point: { lat: 48.3984, lon: 9.9916 } };
+
+export class GeoAdminError extends Error {
+  constructor(
+    readonly body: GeoKeyError | { code: "geo_budget_invalid"; errors: Partial<Record<GeoBudgetField, GeoBudgetFieldError>> },
+    readonly status: 400 | 422 | 502,
+  ) {
+    super(body.code); // Never carries the key or a provider body.
+    this.name = "GeoAdminError";
+  }
+}
+
+const requireAdmin = (actor: Actor) => {
+  if (!actor.roles.includes("admin")) throw new HTTPException(403, { message: "Administrator access required." });
+};
+const readableSetting = async (key: string, ciphertext: string): Promise<boolean> => {
+  const def = SETTINGS_MAP.get(key);
+  try {
+    return !!def && validateSettingValue(def, await decryptValue(ciphertext)).ok;
+  } catch {
+    return false;
+  }
+};
+const invalidate = async (keys: readonly string[]) => {
+  try {
+    await settings.invalidateSettingsCache(keys);
+  } catch (error) {
+    console.error("[geo] committed settings but failed to invalidate the shared cache; TTL recovery remains active", error);
+  }
+};
+const auditActor = (actor: Actor) => ({ userId: actor.id, uid: actor.uid, provider: actor.provider, roles: actor.roles });
+
+type Verify = (apiKey: string, signal?: AbortSignal) => Promise<void>;
+export const verifyGeoapifyKey =
+  (adapter = new GeoapifyAdapter()): Verify =>
+  async (apiKey, signal) => {
+    try {
+      await adapter.reverse(PROBE, apiKey, "en", signal);
+    } catch (error) {
+      if (error instanceof GeoProviderError && error.keyRejected) throw new GeoAdminError({ code: "geo_key_rejected" }, 422);
+      // Timeouts, rate limits, malformed answers and unreachable hosts prove nothing about the key.
+      throw new GeoAdminError({ code: "geo_key_unverified" }, 502);
+    }
+  };
+
+export const createGeoAdmin = (options: { db?: SQL; verify?: Verify; now?: () => Date } = {}) => {
+  const db = options.db ?? sql;
+  const verify = options.verify ?? verifyGeoapifyKey();
+  const now = options.now ?? (() => new Date());
+
+  /**
+   * The person behind the stored value: the audit event written in the same transaction as the newest of these rows
+   * carries that transaction's exact timestamp, and so does every row that event wrote.
+   */
+  const changedBy = async (action: string, keys: readonly string[]): Promise<GeoAdminPerson | null> => {
+    const [row] = await db<{ actor_user_id: string; name: string | null }[]>`
+      SELECT e.actor_user_id, COALESCE(NULLIF(u.display_name, ''), u.uid) AS name
+      FROM audit.events e LEFT JOIN auth.users u ON u.id = e.actor_user_id
+      WHERE e.action = ${action} AND e.actor_user_id IS NOT NULL
+        AND e.created_at = (SELECT max(updated_at) FROM settings.entries WHERE key = ANY(${toPgTextArray([...keys])}::text[]))
+        -- Every row this event wrote must still carry its stamp; a later write by another transaction names nobody.
+        AND NOT EXISTS (
+          SELECT 1 FROM settings.entries s WHERE s.key = ANY(${toPgTextArray([...keys])}::text[])
+            AND (e.metadata -> substr(s.key, 5)) IS NOT NULL AND s.updated_at <> e.created_at
+        )
+      ORDER BY e.id DESC LIMIT 1`;
+    return row ? { id: row.actor_user_id, name: row.name ?? row.actor_user_id } : null;
+  };
+
+  const status = async (actor: Actor): Promise<GeoAdminStatus> => {
+    requireAdmin(actor);
+    const [config, states, rows, keyBy, budgetBy] = await Promise.all([
+      readGeoConfig(),
+      settings.readStates([KEY, ...BUDGET_KEYS]),
+      db<{ key: string; updated_at: Date }[]>`
+        SELECT key, updated_at FROM settings.entries WHERE key = ANY(${toPgTextArray([KEY, ...BUDGET_KEYS])}::text[])`,
+      changedBy(KEY_ACTION, [KEY]),
+      changedBy(BUDGET_ACTION, BUDGET_KEYS),
+    ]);
+    const updated = new Map(rows.map((row) => [row.key, new Date(row.updated_at)]));
+    const key = states.get(KEY);
+    const keyState = key?.stored === "unreadable" ? "unreadable" : key?.stored === "readable" && String(key.value).trim() ? "set" : "none";
+    const keyAt = keyState === "none" ? null : (updated.get(KEY) ?? null);
+    const budgetTimes = BUDGET_KEYS.flatMap((name) => updated.get(name)?.getTime() ?? []);
+    const budgetAt = budgetTimes.length ? new Date(Math.max(...budgetTimes)) : null;
+    return {
+      key: { state: keyState, setAt: keyAt?.toISOString() ?? null, setBy: keyState === "set" ? keyBy : null },
+      budget: {
+        plan: config.plan,
+        customRps: config.customRps,
+        customDailyCredits: config.customDailyCredits,
+        monthlyCredits: config.monthlyCredits,
+        personDailyCredits: config.personDailyCredits,
+        unreadable: [["plan", PLAN_KEY] as const, ...BUDGET_FIELDS].flatMap(([field, name]) =>
+          states.get(name)?.stored === "unreadable" ? [field] : [],
+        ),
+        changedAt: budgetAt?.toISOString() ?? null,
+        changedBy: budgetAt ? budgetBy : null,
+      },
+      plans: GEO_PLANS,
+      timezone: config.timezone,
+    };
+  };
+
+  const usage = async (actor: Actor): Promise<GeoAdminUsage> => {
+    requireAdmin(actor);
+    const config = await readGeoConfig();
+    const periods = geoPeriods(now(), config.timezone);
+    const plan = config.plan === "custom" ? { dailyCredits: config.customDailyCredits } : GEO_PLANS[config.plan];
+    const [[month], [today], shares] = await Promise.all([
+      db<
+        { used: number }[]
+      >`SELECT used::float8 AS used FROM geo.usage WHERE scope = 'cloud' AND subject = '*' AND period = ${periods.cloud.period}`,
+      db<{ used: number; at_limit: number }[]>`
+        SELECT COALESCE(sum(used), 0)::float8 AS used, count(*) FILTER (WHERE used >= ${config.personDailyCredits * 1000})::int AS at_limit
+        FROM geo.usage WHERE scope = 'person' AND period = ${periods.person.period}`,
+      db<{ function_group: string; used: number }[]>`
+        SELECT function_group, used::float8 AS used FROM geo.shares WHERE scope = 'cloud' AND subject = '*' AND period = ${periods.cloud.period}`,
+    ]);
+    return {
+      month: {
+        period: periods.cloud.period,
+        used: (month?.used ?? 0) / 1000,
+        limit: config.monthlyCredits,
+        resetsAt: periods.cloud.resetsAt,
+      },
+      today: {
+        period: periods.person.period,
+        used: (today?.used ?? 0) / 1000,
+        allowance: plan.dailyCredits,
+        resetsAt: periods.person.resetsAt,
+      },
+      shares: GEO_USAGE_GROUPS.map((group) => ({
+        group,
+        credits: (shares.find((row) => row.function_group === group)?.used ?? 0) / 1000,
+      })),
+      peopleAtLimit: today?.at_limit ?? 0,
+      timezone: config.timezone,
+    };
+  };
+
+  return {
+    status,
+    usage,
+    /** Store a key only after Geoapify accepted it; until then the previous key stays active. */
+    async setKey(actor: Actor, raw: string, signal?: AbortSignal): Promise<GeoAdminStatus> {
+      requireAdmin(actor);
+      const apiKey = raw.trim();
+      const problem = geoKeyProblem(apiKey);
+      if (problem) throw new GeoAdminError({ code: problem }, 400);
+      await verify(apiKey, signal);
+      signal?.throwIfAborted();
+      const before = (await settings.readStates([KEY])).get(KEY)?.stored ?? "none";
+      await db.begin(async (tx) => {
+        // The person replaces whatever is stored, including a value this installation cannot read.
+        await settings.set(KEY, apiKey, tx, { replaceUnreadable: true });
+        await audit.record(
+          { action: KEY_ACTION, outcome: "allowed", actor: auditActor(actor), metadata: { replaced: before !== "none" } },
+          tx,
+        );
+      });
+      await invalidate([KEY]);
+      return status(actor);
+    },
+    async removeKey(actor: Actor): Promise<GeoAdminStatus> {
+      requireAdmin(actor);
+      await db.begin(async (tx) => {
+        const [row] = await tx<{ key: string }[]>`DELETE FROM settings.entries WHERE key = ${KEY} RETURNING key`;
+        if (row) await audit.record({ action: "core.geo.key_removed", outcome: "allowed", actor: auditActor(actor) }, tx);
+      });
+      await invalidate([KEY]);
+      return status(actor);
+    },
+    async saveBudget(actor: Actor, input: GeoBudgetInput): Promise<GeoAdminStatus> {
+      requireAdmin(actor);
+      const errors = validateGeoBudget(input);
+      if (Object.keys(errors).length) throw new GeoAdminError({ code: "geo_budget_invalid", errors }, 400);
+      const updates: Record<string, unknown> = {
+        [PLAN_KEY]: input.plan,
+        ...Object.fromEntries(
+          BUDGET_FIELDS.filter(([field]) => input.plan === "custom" || !field.startsWith("custom")).map(([field, name]) => [
+            name,
+            input[field],
+          ]),
+        ),
+      };
+      // Geo stays off while any geo setting is unreadable. A standard plan hides the custom fields, so saving it
+      // resets their unreadable values to the defaults instead of leaving geo off behind a field nobody sees.
+      const inactive = BUDGET_FIELDS.flatMap(([, name]) => (name in updates ? [] : [name]));
+      const resets: string[] = [];
+      await db.begin(async (tx) => {
+        // Same lock and final-pair rule as every other writer of these settings.
+        await assertGeoBudgetPair(tx, updates, []);
+        // Saving the form is the explicit replacement of a value this installation cannot read.
+        for (const [name, value] of Object.entries(updates)) await settings.set(name, value, tx, { replaceUnreadable: true });
+        // Decided under the row lock: a value another writer repaired meanwhile stays.
+        const rows = await tx<{ key: string; value: string }[]>`
+          SELECT key, value FROM settings.entries WHERE key = ANY(${toPgTextArray(inactive)}::text[]) FOR UPDATE`;
+        for (const row of rows) {
+          if (await readableSetting(row.key, row.value)) continue;
+          await tx`DELETE FROM settings.entries WHERE key = ${row.key}`;
+          resets.push(row.key);
+        }
+        await audit.record(
+          {
+            action: BUDGET_ACTION,
+            outcome: "allowed",
+            actor: auditActor(actor),
+            metadata: {
+              ...Object.fromEntries(Object.entries(updates).map(([name, value]) => [name.slice(4), value])),
+              ...(resets.length ? { resets: resets.map((name) => name.slice(4)) } : {}),
+            },
+          },
+          tx,
+        );
+      });
+      await invalidate([...Object.keys(updates), ...resets]);
+      return status(actor);
+    },
+  };
+};
+
+export const geoAdmin = createGeoAdmin();

package/src/services/geo/bucket.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import type { GeoFunction } from "../../contracts/geo";
+import { requestCacheRedis } from "../request-cache-redis";
+import { busy, GeoError } from "./errors";
+
+export type GeoRedis = { send(command: string, args: string[]): Promise<unknown> };
+export const GEO_TIMEOUT_MS = { autocomplete: 2500, geocode: 5000, reverse: 5000, places: 8000, route: 15000, tiles: 10000 } as const;
+// One token bucket for all paid APIs; a separate lease set for each function.
+const ACQUIRE = `
+local clock = redis.call('TIME')
+local now = tonumber(clock[1]) * 1000 + tonumber(clock[2]) / 1000
+local rate = tonumber(ARGV[1])
+local leaseMs = tonumber(ARGV[2])
+local cap = tonumber(ARGV[3])
+redis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now)
+if redis.call('ZCARD', KEYS[2]) >= cap then
+  local first = redis.call('ZRANGE', KEYS[2], 0, 0, 'WITHSCORES')
+  return {0, math.max(1, math.ceil((tonumber(first[2]) - now) / 1000))}
+end
+local old = redis.call('HMGET', KEYS[1], 'tokens', 'at')
+local tokens = math.min(rate, tonumber(old[1]) or rate)
+local at = tonumber(old[2]) or now
+tokens = math.min(rate, tokens + math.max(0, now - at) * rate / 1000)
+if tokens < 1 then return {0, math.max(1, math.ceil((1 - tokens) / rate))} end
+redis.call('HSET', KEYS[1], 'tokens', tokens - 1, 'at', now)
+redis.call('PEXPIRE', KEYS[1], math.ceil(leaseMs + 1000))
+redis.call('ZADD', KEYS[2], now + leaseMs, ARGV[4])
+redis.call('PEXPIRE', KEYS[2], math.ceil(leaseMs + 1000))
+return {1, 0}
+`;
+export const createGeoBucket = (options: { redis?: () => Promise<GeoRedis>; randomId?: () => string; prefix?: string } = {}) => {
+  const client = options.redis ?? requestCacheRedis;
+  const prefix = options.prefix ?? "geo:{admission}:v1";
+  return {
+    async acquire(fn: GeoFunction | "tiles", rps: number) {
+      try {
+        if (!Number.isFinite(rps) || rps < 1) throw busy();
+        const id = options.randomId ? options.randomId() : crypto.randomUUID();
+        const redis = await client();
+        const key = `${prefix}:flight:${fn}`;
+        const reply = z
+          .tuple([z.number(), z.number()])
+          .parse(
+            await redis.send("EVAL", [
+              ACQUIRE,
+              "2",
+              `${prefix}:bucket${fn === "tiles" ? ":tiles" : ""}`,
+              key,
+              String(rps),
+              String(GEO_TIMEOUT_MS[fn] + 1000),
+              String(Math.ceil((rps * GEO_TIMEOUT_MS[fn]) / 1000)),
+              id,
+            ]),
+          );
+        if (reply[0] !== 1) throw busy(Math.max(1, reply[1]));
+        return async () => {
+          await redis.send("ZREM", [key, id]).catch(() => {});
+        };
+      } catch (error) {
+        if (error instanceof GeoError) throw error;
+        // Fail closed, but leave a trace: a script or client defect must not look like ordinary load.
+        console.error("[geo] Admission refused after a Valkey failure", { error: error instanceof Error ? error.name : typeof error });
+        throw busy();
+      }
+    },
+  };
+};

package/src/services/geo/cache.ts

@@ -0,0 +1,57 @@
+import { createHash } from "node:crypto";
+import type { z } from "zod";
+import type { GeoFunction } from "../../contracts/geo";
+import { requestCacheRedis } from "../request-cache-redis";
+import type { GeoRedis } from "./bucket";
+
+export const GEO_ADAPTER_VERSION = "geoapify-v2";
+export const GEO_MAX_JSON_BYTES = 256 * 1024;
+// Raw provider geometry is compacted before entering the public result/cache budget.
+export const GEO_MAX_ROUTE_RESPONSE_BYTES = 26 * GEO_MAX_JSON_BYTES;
+const hash = (value: string) => createHash("sha256").update(value).digest("hex");
+export const normalizeGeoInput = (input: unknown, fn: GeoFunction, path = ""): unknown => {
+  const field = path.split(".").at(-1);
+  if (typeof input === "string" && fn === "route") return field === "polyline6" ? hash(input) : input;
+  if (typeof input === "string") return field === "polyline6" ? hash(input) : input.toLowerCase().trim().replace(/\s+/g, " ");
+  if (typeof input === "number") {
+    if (fn !== "route" && ["lat", "lon", "west", "south", "east", "north"].includes(field ?? ""))
+      return Number(input.toFixed(fn === "autocomplete" && (path === "bias.lat" || path === "bias.lon") ? 2 : 5));
+    return input;
+  }
+  if (Array.isArray(input)) {
+    const values = input.map((value) => normalizeGeoInput(value, fn, path));
+    return field === "categories" || field === "avoid" ? values.sort() : values;
+  }
+  if (input && typeof input === "object")
+    return Object.fromEntries(
+      Object.entries(input)
+        .filter(([, value]) => value !== undefined)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => [key, normalizeGeoInput(value, fn, path ? `${path}.${key}` : key)]),
+    );
+  return input;
+};
+export const geoCacheKey = (fn: GeoFunction, input: unknown, locale: string) =>
+  `geo:cache:v1:${hash(JSON.stringify([GEO_ADAPTER_VERSION, fn, locale, normalizeGeoInput(input, fn)]))}`;
+export const createGeoCache = (client: () => Promise<GeoRedis> = requestCacheRedis) => ({
+  async get<T>(key: string, schema: z.ZodType<T>): Promise<T | null> {
+    try {
+      const value = await (await client()).send("GET", [key]);
+      if (typeof value !== "string" || Buffer.byteLength(value) > GEO_MAX_JSON_BYTES) return null;
+      const parsed = schema.safeParse(JSON.parse(value));
+      return parsed.success ? parsed.data : null;
+    } catch {
+      return null;
+    }
+  },
+  async put(key: string, fn: GeoFunction, value: unknown, empty: boolean) {
+    try {
+      const json = JSON.stringify(value);
+      if (Buffer.byteLength(json) > GEO_MAX_JSON_BYTES) return;
+      const ttl = empty ? 3600 : fn === "autocomplete" ? 7 * 86400 : fn === "places" || fn === "route" ? 86400 : 30 * 86400;
+      await (await client()).send("SET", [key, json, "EX", String(ttl)]);
+    } catch {
+      /* Cache failure does not change an admitted response. */
+    }
+  },
+});

package/src/services/geo/costs.ts

@@ -0,0 +1,5 @@
+import type { GeoFunction } from "../../contracts/geo";
+export type GeoCostStep = { fn: GeoFunction; limit?: number };
+/** Integer millicredits. Use requested limits, including for empty and short responses. */
+export const geoReferenceCost = ({ fn, limit = 20 }: GeoCostStep): number => (fn === "places" ? Math.ceil(limit / 20) : 1) * 1000;
+export const geoReserveCost = (chain: readonly GeoCostStep[]): number => chain.reduce((sum, step) => sum + geoReferenceCost(step), 0);

package/src/services/geo/errors.ts

@@ -0,0 +1,41 @@
+import type { CapabilityErrorStatus } from "../../contracts/capabilities";
+import type { GeoErrorCode } from "../../contracts/geo";
+
+export class GeoError extends Error {
+  constructor(
+    readonly code: GeoErrorCode,
+    readonly details: Record<string, unknown> = {},
+  ) {
+    super(code); // Never retain a provider body, request, credential, or transport cause.
+    this.name = "GeoError";
+    if (code === "GEO_PROVIDER_FAILED") this.details = { costs: { settledCredits: 0, unknownCredits: 0 }, ...details };
+  }
+  get status(): CapabilityErrorStatus {
+    if (this.code === "GEO_FORBIDDEN") return 403;
+    if (this.code === "GEO_BUSY") return 429;
+    if (this.code === "GEO_PROVIDER_FAILED") return 502;
+    if (this.code === "GEO_NOT_CONFIGURED") return 503;
+    if (this.code === "GEO_BUDGET_EXHAUSTED") return 429;
+    if (this.code === "GEO_ADDRESS_NOT_FOUND") return 404;
+    if (this.code === "GEO_ADDRESS_AMBIGUOUS") return 409;
+    return 400;
+  }
+}
+export const limitExceeded = (limit: string, max: number, actual: number): never => {
+  throw new GeoError("GEO_LIMIT_EXCEEDED", { limit, max, actual });
+};
+export const busy = (retryAfterSeconds = 1) => new GeoError("GEO_BUSY", { retryAfterSeconds });
+
+export class GeoProviderError extends GeoError {
+  constructor(
+    code: "GEO_PROVIDER_FAILED" | "GEO_BUSY",
+    readonly charge: "none" | "known" | "unknown",
+    readonly keyRejected = false,
+    readonly referenceDistanceMeters?: number,
+  ) {
+    super(code, {
+      ...(code === "GEO_BUSY" ? { retryAfterSeconds: 1 } : {}),
+      ...(keyRejected ? { adminHint: "Geoapify rejected the key. Check geo.api_key in Core settings." } : {}),
+    });
+  }
+}

package/src/services/geo/fixtures/README.md

@@ -0,0 +1,17 @@
+# Geoapify response fixtures
+
+These fixtures are adapted from the public Geoapify OpenAPI examples at
+[geoapify/geoapify-openapi-specs](https://github.com/geoapify/geoapify-openapi-specs/tree/dd07a5f).
+They cover autocomplete, forward and reverse geocoding, and Places GeoJSON.
+`along.json` uses the Places response shape; the service test supplies
+synthetic corridor coordinates to check ordering, the window, and distance.
+`routing.json` and `route.test-fixture.ts` supply entirely synthetic stopover
+legs and waypoint permutations in the documented Routing JSON response shape (`format=json`). Optimized waypoint
+order uses `results[0].waypoints` as documented by the provider. Waypoint
+locations may differ from geometry endpoints, as in the published JSON example;
+no input-to-road snap-distance tolerance is assumed. Raw route responses are bounded at 26 ×
+256 KiB, then compacted to the 256 KiB public result budget.
+Opening hours use the documented `datasource.raw.opening_hours` field.
+
+Tests use only the placeholder key `test-placeholder-key` and a frozen clock.
+No fixture was obtained through an authenticated provider request.