@k2b/cloud 0.39.0 → 0.41.0

package/src/services/geoip/store.ts

@@ -0,0 +1,30 @@
+import { sql } from "bun";
+import { GEOIP_MAX_DATABASE_BYTES, type GeoIpKind } from "../../contracts/geoip";
+import type { GeoIpUploads } from "../../server/request-context/geoip";
+
+const SLICE_BYTES = 8 * 1024 * 1024;
+export const createGeoIpUploads = (db: typeof sql = sql): GeoIpUploads => ({
+  async versions() {
+    const rows = await db<{ kind: GeoIpKind; sha256: string }[]>`SELECT kind, sha256 FROM geoip.databases`;
+    return Object.fromEntries(rows.map((row) => [row.kind, row.sha256]));
+  },
+  async read(kind, sha256) {
+    const [row] = await db<{ size: number }[]>`
+      SELECT octet_length(data) AS size FROM geoip.databases WHERE kind = ${kind} AND sha256 = ${sha256}`;
+    if (!row) return null;
+    if (row.size < 1 || row.size > GEOIP_MAX_DATABASE_BYTES) throw new Error("Invalid GeoIP database size");
+    const bytes = Buffer.allocUnsafe(row.size);
+    for (let offset = 0; offset < bytes.length; offset += SLICE_BYTES) {
+      const length = Math.min(SLICE_BYTES, bytes.length - offset);
+      const [slice] = await db<{ data: Uint8Array }[]>`
+        SELECT substring(data FROM ${offset + 1} FOR ${length}) AS data
+        FROM geoip.databases WHERE kind = ${kind} AND sha256 = ${sha256}`;
+      if (!slice) return null;
+      if (slice.data.byteLength !== length) throw new Error("Incomplete GeoIP database slice");
+      bytes.set(slice.data, offset);
+    }
+    return bytes;
+  },
+});
+
+export const geoIpUploads = createGeoIpUploads();

package/src/services/geoip/upload.ts

@@ -0,0 +1,150 @@
+import { Readable } from "node:stream";
+import { createGunzip } from "node:zlib";
+import { Reader } from "mmdb-lib";
+import { GEOIP_MAX_DATABASE_BYTES, GEOIP_MAX_REQUEST_BYTES, type GeoIpErrorCode, type GeoIpKind } from "../../contracts/geoip";
+import { hasBoundedMmdbMetadata, openGeoIpDatabase, truncateUtf8 } from "../../server/request-context/geoip";
+
+const probeAddresses = [
+  ...Array.from({ length: 512 }, (_, i) => [`${i >> 1}.${(i % 2) * 128}.0.0`, `${(0x2000 + i * 16).toString(16)}::`]).flat(),
+  "1.1.1.1",
+  "8.8.8.8",
+  "9.9.9.9",
+  "2001:4860:4860::8888",
+  "2606:4700:4700::1111",
+  "2a01:4f8::1",
+];
+
+const errors = {
+  geoip_request_too_large: { status: 413, message: "The request body exceeds 128 MiB. Upload the .mmdb.gz file." },
+  geoip_too_large: { status: 413, message: "The GeoIP database exceeds 192 MiB unpacked." },
+  geoip_empty: { status: 400, message: "The GeoIP upload is empty." },
+  geoip_invalid: { status: 422, message: "Upload a valid IPv6 MMDB database with a build date." },
+  geoip_unsupported_type: { status: 422, message: "Upload a City or ASN MMDB database." },
+  geoip_upload_busy: { status: 409, message: "Another GeoIP upload is being processed. Try again shortly." },
+} as const;
+export class GeoIpError extends Error {
+  readonly status;
+  constructor(public readonly code: GeoIpErrorCode) {
+    super(errors[code].message);
+    this.status = errors[code].status;
+  }
+}
+
+/** Backpressure reaches the request; both limits are enforced before retaining a chunk. */
+export const readGeoIpUpload = async (body: ReadableStream<Uint8Array>, contentLength?: number): Promise<Buffer> => {
+  if (contentLength !== undefined && contentLength > GEOIP_MAX_REQUEST_BYTES) throw new GeoIpError("geoip_request_too_large");
+  const reader = body.getReader();
+  let requestBytes = 0;
+  async function* counted() {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) return;
+      requestBytes += chunk.value.byteLength;
+      if (requestBytes > GEOIP_MAX_REQUEST_BYTES) throw new GeoIpError("geoip_request_too_large");
+      if (chunk.value.byteLength) yield chunk.value;
+    }
+  }
+  let source: Readable | undefined;
+  let gunzip: ReturnType<typeof createGunzip> | undefined;
+  try {
+    const chunks = counted();
+    const prefix: Uint8Array[] = [];
+    let prefixBytes = 0;
+    while (prefixBytes < 2) {
+      const next = await chunks.next();
+      if (next.done) break;
+      prefix.push(next.value);
+      prefixBytes += next.value.byteLength;
+    }
+    if (!prefixBytes) throw new GeoIpError("geoip_empty");
+    const first = prefix[0]!;
+    const gzip = first[0] === 0x1f && (first.byteLength > 1 ? first[1] : prefix[1]?.[0]) === 0x8b;
+    source = Readable.from(
+      (async function* () {
+        yield* prefix;
+        yield* chunks;
+      })(),
+    );
+    let output = source;
+    if (gzip) {
+      gunzip = createGunzip();
+      source.on("error", (error) => gunzip?.destroy(error));
+      output = source.pipe(gunzip);
+    }
+    // A resizable backing store avoids retaining all chunks plus a second full-size concatenation.
+    const storage = new ArrayBuffer(0, { maxByteLength: GEOIP_MAX_DATABASE_BYTES });
+    let size = 0;
+    for await (const chunk of output) {
+      if (!(chunk instanceof Uint8Array)) throw new GeoIpError("geoip_invalid");
+      if (size + chunk.byteLength > GEOIP_MAX_DATABASE_BYTES) throw new GeoIpError("geoip_too_large");
+      const needed = size + chunk.byteLength;
+      if (needed > storage.byteLength)
+        storage.resize(Math.min(GEOIP_MAX_DATABASE_BYTES, Math.ceil(needed / (8 * 1024 * 1024)) * 8 * 1024 * 1024));
+      new Uint8Array(storage).set(chunk, size);
+      size = needed;
+    }
+    if (!size) throw new GeoIpError("geoip_empty");
+    storage.resize(size);
+    return Buffer.from(storage);
+  } catch (error) {
+    if (error instanceof GeoIpError) throw error;
+    throw new GeoIpError("geoip_invalid");
+  } finally {
+    source?.destroy();
+    gunzip?.destroy();
+    await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+};
+
+export const parseGeoIpUpload = (bytes: Uint8Array) => {
+  if (!hasBoundedMmdbMetadata(bytes)) throw new GeoIpError("geoip_invalid");
+  try {
+    const metadata = new Reader(Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)).metadata;
+    const type = metadata.databaseType.toLowerCase();
+    const kind: GeoIpKind | null = type.includes("city") ? "city" : type.includes("asn") ? "asn" : null;
+    if (!kind) throw new GeoIpError("geoip_unsupported_type");
+    const database = openGeoIpDatabase(kind, bytes, "uploaded");
+    if (!database || Buffer.byteLength(metadata.databaseType) > 128) throw new GeoIpError("geoip_invalid");
+    const description: unknown = metadata.description;
+    const english =
+      typeof description === "object" && description !== null && "en" in description && typeof description.en === "string"
+        ? description.en
+        : "";
+    const languages: unknown = metadata.languages;
+    const subset = {
+      databaseType: metadata.databaseType,
+      buildEpoch: metadata.buildEpoch.toISOString(),
+      ipVersion: metadata.ipVersion,
+      // `languages` is optional in MMDB metadata; mmdb-lib leaves it undefined despite its type.
+      languages: (Array.isArray(languages) ? languages : [])
+        .filter((language): language is string => typeof language === "string")
+        .slice(0, 16)
+        .map((language) => truncateUtf8(language, 32)),
+      description: { en: truncateUtf8(english, 256) },
+      nodeCount: metadata.nodeCount,
+      recordSize: metadata.recordSize,
+      size: bytes.byteLength,
+    };
+    if (
+      subset.databaseType.includes("\0") ||
+      subset.description.en.includes("\0") ||
+      subset.languages.some((language) => language.includes("\0"))
+    )
+      throw new GeoIpError("geoip_invalid");
+    // Pretty JSON is larger than PostgreSQL jsonb text, including its separator spaces.
+    if (Buffer.byteLength(JSON.stringify(subset, null, 1)) > 4096) throw new GeoIpError("geoip_invalid");
+    // A bounded probe catches gross corruption, not every bad record; request lookups still fail closed. Each
+    // address is one lookup that keeps nothing: at most 32 KiB of decode work and one decoded record in memory.
+    // A crafted file with records at that cap can block this Core process for about ten seconds; normal files take
+    // milliseconds.
+    for (const address of probeAddresses) {
+      const record = database.get(address);
+      if (record !== null && (typeof record !== "object" || Array.isArray(record))) throw new GeoIpError("geoip_invalid");
+    }
+    return { kind, database, metadata: subset };
+  } catch (error) {
+    if (error instanceof GeoIpError) throw error;
+    throw new GeoIpError("geoip_invalid");
+  }
+};

package/src/services/identity/routes.ts

@@ -2,9 +2,13 @@ import { type Context, Hono } from "hono";
 import { CLOUD_INVOCATION_JWKS_PATH, CLOUD_SESSION_JWKS_PATH, IDENTITY_JWKS_MAX_AGE_SECONDS } from "./constants";
 import { listIdentityJwks } from "./key-ring";
 
+// If-None-Match uses weak comparison, including lists and the wildcard.
+const matchesEtag = (header: string | undefined, etag: string): boolean =>
+  header?.trim() === "*" || (header?.match(/(?:W\/)?"[^"]*"/g) ?? []).some((tag) => tag.replace(/^W\//, "") === etag.replace(/^W\//, ""));
+
 const serveJwks = (purpose: "session" | "invocation") => async (c: Context) => {
   const jwks = await listIdentityJwks(purpose);
-  if (c.req.header("if-none-match") === jwks.etag) {
+  if (matchesEtag(c.req.header("if-none-match"), jwks.etag)) {
     c.header("ETag", jwks.etag);
     c.header("Cache-Control", `public, max-age=${IDENTITY_JWKS_MAX_AGE_SECONDS}, must-revalidate`);
     return c.body(null, 304);

package/src/services/index.ts

@@ -246,3 +246,16 @@ export {
   resolveAllowedNetworkAddresses,
 } from "./network-security";
 export type { NetworkLookup, PublicNetworkAddress } from "./network-security";
+
+export { geoip } from "./geoip";
+export {
+  knownBrowsers,
+  KNOWN_BROWSER_LIMITS,
+  SIGN_IN_METHODS,
+  type SignInMethod,
+  type NewBrowserSignInNotice,
+  type NewBrowserSignInNotifier,
+} from "./known-browsers";
+export { LASTING_ACCESS_SIGN_IN_SECONDS, requireConfirmedBrowserSignIn } from "./session/recent";
+
+export { deviceOffersApproval } from "./approvals/device";

package/src/services/known-browsers.ts

@@ -0,0 +1,312 @@
+import { type SQL, sql } from "bun";
+import type { Context } from "hono";
+import { getCookie, setCookie } from "hono/cookie";
+import { z } from "zod";
+import { env } from "../config/env";
+import { APP_LOGIN_CONTEXT_BROWSERS, APP_LOGIN_CONTEXT_OSES } from "../contracts/app-approval";
+import { type BrowserCode, type OsCode, truncateUtf8 } from "../server/request-context";
+import { logger } from "./logging";
+
+export const SIGN_IN_METHODS = [
+  "password",
+  "passkey",
+  "email_code",
+  "cloud_login",
+  "password_reset",
+  "expired_password",
+  "admin_token",
+] as const;
+export type SignInMethod = (typeof SIGN_IN_METHODS)[number];
+export type NewBrowserSignInNotice = {
+  browserId: string;
+  userId: string;
+  firstName: string | null;
+  browser: BrowserCode;
+  os: OsCode;
+  country: string | null;
+  city: string | null;
+  signedInAt: string;
+  method: SignInMethod;
+  device: string | null;
+  locale: string | null;
+};
+export type NewBrowserSignInNotifier = (notice: NewBrowserSignInNotice) => Promise<unknown>;
+const log = logger("known-browsers");
+const noticeSnapshot = z.object({
+  browser: z.enum(APP_LOGIN_CONTEXT_BROWSERS),
+  os: z.enum(APP_LOGIN_CONTEXT_OSES),
+  country: z
+    .string()
+    .regex(/^[A-Z]{2}$/)
+    .nullable(),
+  city: z.string().max(96).nullable(),
+  signedInAt: z.string().datetime(),
+  method: z.enum(SIGN_IN_METHODS),
+  device: z.string().min(1).max(80).nullable(),
+  locale: z.string().min(1).max(35).nullable(),
+});
+
+/** The greeting name, as the notice carries it: trimmed and at most 100 characters; profile names have no length limit. */
+export const noticeFirstName = (name: string | null | undefined): string | null =>
+  Array.from(name?.trim() ?? "")
+    .slice(0, 100)
+    .join("")
+    .trim() || null;
+
+export const KNOWN_BROWSER_LIMITS = {
+  retentionDays: 90,
+  browsersPerAccount: 100,
+  countriesPerAccount: 50,
+  introDays: 14,
+  noticeBatch: 100,
+  cleanupBatch: 1000,
+  cleanupBatchesPerRun: 10,
+} as const;
+const DAY_MS = 86_400_000;
+const cutoffAt = (now: Date) => new Date(now.getTime() - KNOWN_BROWSER_LIMITS.retentionDays * DAY_MS);
+const cookieName = (development: boolean) => (development ? "cloud_browser" : "__Host-cloud_browser");
+const validCookie = (value: string | undefined): value is string =>
+  value !== undefined && value.length === 43 && /^[A-Za-z0-9_-]{43}$/.test(value);
+
+export const readBrowserCookie = (c: Context, development = env.IS_DEVELOPMENT): string | null => {
+  const value = getCookie(c, cookieName(development));
+  return validCookie(value) ? value : null;
+};
+export const newBrowserCookie = (): string => Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString("base64url");
+export const setBrowserCookie = (c: Context, value: string, development = env.IS_DEVELOPMENT): void => {
+  setCookie(c, cookieName(development), value, {
+    httpOnly: true,
+    secure: !development,
+    sameSite: "Strict",
+    path: "/",
+    maxAge: KNOWN_BROWSER_LIMITS.retentionDays * 86_400,
+  });
+};
+
+/** SHA-256 over canonical UUID text followed immediately by the cookie text; stored as raw bytea. */
+export const browserHash = (userId: string, cookie: string): Buffer =>
+  new Bun.CryptoHasher("sha256").update(userId.toLowerCase()).update(cookie).digest();
+
+type SignIn = {
+  userId: string;
+  cookie: string;
+  firstName: string | null;
+  method: SignInMethod;
+  device: string | null;
+  locale: string | null;
+  browser: BrowserCode;
+  os: OsCode;
+  country: string | null;
+  city: string | null;
+  now: Date;
+  announce: boolean;
+};
+
+/** Caller holds the existing session issuance lock on this account's auth.users row. */
+export const rememberSignIn = async (tx: SQL, input: SignIn): Promise<NewBrowserSignInNotice | null> => {
+  const { userId, cookie, browser, os, now } = input;
+  const country = input.country?.length === 2 && /^[A-Z]{2}$/.test(input.country) ? input.country : null;
+  const city = input.city === null ? null : truncateUtf8(input.city, 96);
+  const cutoff = cutoffAt(now);
+  const [row] = await tx<{ id: string; first_seen_at: Date }[]>`
+    INSERT INTO auth.known_browsers (user_id, browser_hash, browser, os, country, city, first_seen_at, last_seen_at)
+    VALUES (${userId}::uuid, ${browserHash(userId, cookie)}, ${browser}, ${os}, ${country}, ${city}, ${now}, ${now})
+    ON CONFLICT (user_id, browser_hash) DO UPDATE SET
+      browser = EXCLUDED.browser, os = EXCLUDED.os, country = EXCLUDED.country, city = EXCLUDED.city,
+      last_seen_at = EXCLUDED.last_seen_at,
+      first_seen_at = CASE WHEN known_browsers.last_seen_at <= ${cutoff} THEN EXCLUDED.first_seen_at ELSE known_browsers.first_seen_at END,
+      notified_at = CASE WHEN known_browsers.last_seen_at <= ${cutoff} THEN NULL ELSE known_browsers.notified_at END
+    RETURNING id, first_seen_at
+  `;
+  await tx`
+    DELETE FROM auth.known_browsers WHERE user_id = ${userId}::uuid AND (
+      last_seen_at <= ${cutoff} OR id IN (
+        SELECT id FROM auth.known_browsers WHERE user_id = ${userId}::uuid
+        ORDER BY last_seen_at DESC, id DESC OFFSET ${KNOWN_BROWSER_LIMITS.browsersPerAccount}
+      )
+    )
+  `;
+  if (country) {
+    await tx`
+      INSERT INTO auth.sign_in_countries (user_id, country, last_seen_at) VALUES (${userId}::uuid, ${country}, ${now})
+      ON CONFLICT (user_id, country) DO UPDATE SET last_seen_at = EXCLUDED.last_seen_at
+    `;
+    await tx`
+      DELETE FROM auth.sign_in_countries WHERE user_id = ${userId}::uuid AND (
+        last_seen_at <= ${cutoff} OR country IN (
+          SELECT country FROM auth.sign_in_countries WHERE user_id = ${userId}::uuid
+          ORDER BY last_seen_at DESC, country OFFSET ${KNOWN_BROWSER_LIMITS.countriesPerAccount}
+        )
+      )
+    `;
+    await tx`UPDATE auth.device_trust_state SET geoip_since = ${now} WHERE id = true AND geoip_since IS NULL`;
+  }
+  if (!row || row.first_seen_at.getTime() !== now.getTime()) return null;
+  if (!input.announce || (await trustState(tx, now)).introActive) {
+    await tx`UPDATE auth.known_browsers SET notified_at = ${now}, notice = NULL, notice_attempted_at = NULL WHERE id = ${row.id}::uuid`;
+    return null;
+  }
+  const snapshot = {
+    browser,
+    os,
+    country,
+    city,
+    signedInAt: now.toISOString(),
+    method: input.method,
+    device: input.method === "cloud_login" && input.device ? truncateUtf8(input.device, 80) : null,
+    locale: input.locale && input.locale.length <= 35 ? input.locale : null,
+  };
+  await tx`UPDATE auth.known_browsers SET notified_at = NULL, notice = ${JSON.stringify(snapshot)}::text::jsonb, notice_attempted_at = NULL WHERE id = ${row.id}::uuid`;
+  return { ...snapshot, browserId: row.id, userId, firstName: input.firstName };
+};
+
+/** A failed handoff stays pending. Only the error class enters logs. */
+export const announceNewBrowser = async (
+  notify: NewBrowserSignInNotifier,
+  notice: NewBrowserSignInNotice,
+  db: SQL = sql,
+): Promise<boolean> => {
+  try {
+    await notify(notice);
+    await db`UPDATE auth.known_browsers SET notified_at = now(), notice = NULL, notice_attempted_at = NULL WHERE id = ${notice.browserId}::uuid AND notified_at IS NULL`;
+    return true;
+  } catch (error) {
+    log.warn("New-browser notice failed", { error: error instanceof Error ? error.name : "UnknownError" });
+    // The next batch starts with notices tried least recently, so failing ones cannot hold back the others.
+    try {
+      await db`UPDATE auth.known_browsers SET notice_attempted_at = now() WHERE id = ${notice.browserId}::uuid AND notified_at IS NULL`;
+    } catch {
+      // Without the mark the notice keeps its place in the queue; it stays pending either way.
+    }
+    return false;
+  }
+};
+
+export const maintainNotices = async (
+  db: SQL,
+  notify: NewBrowserSignInNotifier,
+  { signal, batchSize = KNOWN_BROWSER_LIMITS.noticeBatch }: { signal?: AbortSignal; batchSize?: number } = {},
+): Promise<number> => {
+  if (!Number.isSafeInteger(batchSize) || batchSize < 1) throw new Error("New-browser notices require a positive batch size");
+  signal?.throwIfAborted();
+  const rows = await db<{ id: string; user_id: string; notice: unknown; given_name: string | null }[]>`
+    SELECT kb.id, kb.user_id, kb.notice, u.given_name FROM auth.known_browsers kb JOIN auth.users u ON u.id = kb.user_id
+    WHERE kb.notified_at IS NULL AND kb.notice IS NOT NULL AND kb.last_seen_at > ${cutoffAt(new Date())}
+    ORDER BY kb.notice_attempted_at NULLS FIRST, kb.first_seen_at, kb.id LIMIT ${batchSize}
+  `;
+  let handedOver = 0;
+  for (const row of rows) {
+    signal?.throwIfAborted();
+    const parsed = noticeSnapshot.safeParse(row.notice);
+    if (!parsed.success) {
+      await db`UPDATE auth.known_browsers SET notified_at = now(), notice = NULL, notice_attempted_at = NULL WHERE id = ${row.id}::uuid AND notified_at IS NULL`;
+      log.warn("Invalid new-browser notice discarded", { error: "InvalidSnapshot" });
+      continue;
+    }
+    if (
+      await announceNewBrowser(
+        notify,
+        { ...parsed.data, browserId: row.id, userId: row.user_id, firstName: noticeFirstName(row.given_name) },
+        db,
+      )
+    )
+      handedOver++;
+  }
+  return handedOver;
+};
+
+export const findBrowser = async (
+  db: SQL,
+  { userId, cookie, now }: { userId?: string | null; cookie: string | null; now: Date },
+): Promise<{ firstSeenAt: Date } | null> => {
+  const id = userId ?? crypto.randomUUID();
+  const [row] = await db<{ first_seen_at: Date }[]>`
+    SELECT first_seen_at FROM auth.known_browsers
+    WHERE user_id = ${id}::uuid AND browser_hash = ${browserHash(id, cookie ?? newBrowserCookie())} AND last_seen_at > ${cutoffAt(now)}
+  `;
+  return userId && cookie && row ? { firstSeenAt: row.first_seen_at } : null;
+};
+
+export const countrySeen = async (
+  db: SQL,
+  { userId, country, now }: { userId?: string | null; country: string | null; now: Date },
+): Promise<boolean> => {
+  const [row] = await db<{ present: boolean }[]>`
+    SELECT EXISTS (SELECT 1 FROM auth.sign_in_countries
+      WHERE user_id = ${userId ?? crypto.randomUUID()}::uuid AND country = ${country} AND last_seen_at > ${cutoffAt(now)}) AS present
+  `;
+  return Boolean(userId && row?.present);
+};
+
+/** Both country facts use the same retention window and one query, including decoys. */
+export const countryHistory = async (
+  db: SQL,
+  { userId, country, now }: { userId?: string | null; country: string | null; now: Date },
+): Promise<{ seen: boolean; any: boolean }> => {
+  const [row] = await db<{ seen: boolean; any: boolean }[]>`
+    SELECT COALESCE(bool_or(country = ${country}), false) AS seen, count(*) > 0 AS "any"
+    FROM auth.sign_in_countries WHERE user_id = ${userId ?? crypto.randomUUID()}::uuid AND last_seen_at > ${cutoffAt(now)}
+  `;
+  return { seen: Boolean(userId && row?.seen), any: Boolean(userId && row?.any) };
+};
+
+export const trustState = async (
+  db: SQL,
+  now: Date,
+): Promise<{ startedAt: Date | null; geoipSince: Date | null; introActive: boolean }> => {
+  const [row] = await db<{ started_at: Date; geoip_since: Date | null }[]>`
+    SELECT started_at, geoip_since FROM auth.device_trust_state WHERE id = true
+  `;
+  return {
+    startedAt: row?.started_at ?? null,
+    geoipSince: row?.geoip_since ?? null,
+    introActive: !row || now.getTime() < row.started_at.getTime() + KNOWN_BROWSER_LIMITS.introDays * DAY_MS,
+  };
+};
+
+export const cleanup = async (
+  db: SQL,
+  {
+    now = new Date(),
+    signal,
+    batchSize = KNOWN_BROWSER_LIMITS.cleanupBatch,
+    maxBatches = KNOWN_BROWSER_LIMITS.cleanupBatchesPerRun,
+  }: { now?: Date; signal?: AbortSignal; batchSize?: number; maxBatches?: number } = {},
+): Promise<{ browsers: number; countries: number }> => {
+  if (!Number.isSafeInteger(batchSize) || batchSize < 1 || !Number.isSafeInteger(maxBatches) || maxBatches < 0)
+    throw new Error("Known-browser cleanup requires a positive batch size and a non-negative batch count");
+  const cutoff = cutoffAt(now);
+  const counts = { browsers: 0, countries: 0 };
+  // Cleanup never waits for a sign-in: rows a sign-in holds are skipped (waiting could deadlock with its own
+  // eviction of the account's other expired rows), and the outer cutoff re-checks a row refreshed meanwhile.
+  // A short batch can therefore mean such a skip; the next run continues the backlog. The batch is a
+  // materialized CTE because a locking LIMIT subquery inside IN (...) may run more than once and exceed it.
+  for (let batch = 0; batch < maxBatches && !signal?.aborted; batch++) {
+    const rows = await db`
+      WITH batch AS MATERIALIZED (
+        SELECT id FROM auth.known_browsers WHERE last_seen_at <= ${cutoff} ORDER BY last_seen_at LIMIT ${batchSize}
+        FOR UPDATE SKIP LOCKED
+      )
+      DELETE FROM auth.known_browsers kb USING batch
+      WHERE kb.id = batch.id AND kb.last_seen_at <= ${cutoff} RETURNING kb.id
+    `;
+    counts.browsers += rows.length;
+    if (rows.length < batchSize) break;
+  }
+  for (let batch = 0; batch < maxBatches && !signal?.aborted; batch++) {
+    const rows = await db`
+      WITH batch AS MATERIALIZED (
+        SELECT user_id, country FROM auth.sign_in_countries WHERE last_seen_at <= ${cutoff} ORDER BY last_seen_at LIMIT ${batchSize}
+        FOR UPDATE SKIP LOCKED
+      )
+      DELETE FROM auth.sign_in_countries sc USING batch
+      WHERE sc.user_id = batch.user_id AND sc.country = batch.country AND sc.last_seen_at <= ${cutoff} RETURNING sc.user_id
+    `;
+    counts.countries += rows.length;
+    if (rows.length < batchSize) break;
+  }
+  return counts;
+};
+
+/** Core-internal persistence and maintenance; no request surface. */
+export const knownBrowsers = { findBrowser, countrySeen, countryHistory, trustState, cleanup, maintainNotices };

package/src/services/login-address-store.ts

@@ -0,0 +1,51 @@
+import { timingSafeEqual } from "node:crypto";
+import { z } from "zod";
+import { requestCacheRedis } from "./request-cache-redis";
+
+const AddressProofSchema = z.object({ salt: z.string().regex(/^[a-f0-9]{32}$/), digest: z.string().regex(/^[a-f0-9]{64}$/) }).strict();
+export type AppLoginAddressProof = z.infer<typeof AddressProofSchema>;
+export type AppLoginAddressStore = {
+  remember(requestId: string, proof: AppLoginAddressProof, expiresAt: Date): Promise<void>;
+  read(requestIds: string[]): Promise<Map<string, AppLoginAddressProof>>;
+  forget(requestId: string): Promise<void>;
+};
+export const appLoginAddressKey = (requestId: string) => `cloud:app-login-address:${requestId}`;
+const digest = (salt: string, prefix: string) => new Bun.CryptoHasher("sha256").update(Buffer.from(salt, "hex")).update(prefix).digest();
+export const appLoginAddressProof = (prefix: string): AppLoginAddressProof => {
+  const salt = Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString("hex");
+  return { salt, digest: digest(salt, prefix).toString("hex") };
+};
+export const appLoginAddressMatches = (proof: AppLoginAddressProof, prefix: string): boolean => {
+  const parsed = AddressProofSchema.safeParse(proof);
+  return parsed.success && timingSafeEqual(Buffer.from(parsed.data.digest, "hex"), digest(parsed.data.salt, prefix));
+};
+
+/** Fail-fast cache client; service callers catch every failure after their SQL commit. */
+export const valkeyAppLoginAddressStore: AppLoginAddressStore = {
+  remember: async (requestId, proof, expiresAt) => {
+    await (await requestCacheRedis()).send("SET", [
+      appLoginAddressKey(requestId),
+      JSON.stringify(proof),
+      "PXAT",
+      String(expiresAt.getTime()),
+    ]);
+  },
+  read: async (requestIds) => {
+    const proofs = new Map<string, AppLoginAddressProof>();
+    if (!requestIds.length) return proofs;
+    const values = await (await requestCacheRedis()).mget(...requestIds.map(appLoginAddressKey));
+    for (const [index, value] of values.entries()) {
+      if (!value) continue;
+      try {
+        const parsed = AddressProofSchema.safeParse(JSON.parse(value));
+        if (parsed.success) proofs.set(requestIds[index]!, parsed.data);
+      } catch {
+        // Invalid cache entries are absent hints, never sign-in failures.
+      }
+    }
+    return proofs;
+  },
+  forget: async (requestId) => {
+    await (await requestCacheRedis()).del(appLoginAddressKey(requestId));
+  },
+};