create-ailk 0.19.0 → 0.20.0

package/templates/apps/api/src/lib/consent-store.ts

@@ -0,0 +1,335 @@
+/**
+ * The consent ledger's read boundary (#8438, spec
+ * docs/specs/8438-consent-registry-and-ledger-step-spec.md D4).
+ *
+ * `consent_grants` is append-only and a Person's current state is the newest
+ * row per purpose, so every reader here asks the database for exactly that.
+ * Nothing is read through a window: `DISTINCT ON (purpose_id) … ORDER BY
+ * purpose_id, created_at DESC, id DESC` is one indexed pass over ALL the
+ * matching rows, so no number of other rows can push an answer out
+ * (SEC-8438-2).
+ *
+ * TWO READINGS of a Person's rows (SEC-8438-1). A Person is keyed on an email
+ * anyone can type into a form, so a row an anonymous writer attached to it
+ * proves nothing about what the person themself chose:
+ *
+ *   - OWN rows: `person_id = P` and a source only a verified caller or a
+ *     signed link sent to the person can write — `sign_up`,
+ *     `account_settings`, `email_unsubscribe` (`OWN_CONSENT_SOURCES`). The
+ *     member's screens, the sign-up prompt, and every future send read only
+ *     these.
+ *   - ANY-SOURCE rows: every row with `person_id = P`, plus the cookie rows
+ *     of every visitor linked to P. The operator's Person page reads these,
+ *     marked `unverified` when the source proves nothing.
+ *
+ * Every query takes an explicit `workspaceId`, and a join to a linked
+ * visitor's rows matches `workspace_id` on both tables (SEC-8438-11) — a
+ * visitor id is client-chosen and not namespaced, so another tenant's rows
+ * under the same id must never join.
+ *
+ * This file is the ONLY non-test reader of `consent_grants` and
+ * `consent_visitor_links` (`architecture.yaml` names it as a data-access
+ * boundary, the kind `member-store.ts` is). The writes are
+ * `services/consent.ts`. Logs carry nothing: no email, visitor id, token or
+ * statement.
+ */
+import type { Prisma } from "@working-theory/database";
+import {
+  consentPurposeKind,
+  type ConsentPurposeKind,
+  type ConsentSource,
+  type SiteConsentConfig,
+} from "@working-theory/validation";
+
+import { prisma } from "./prisma.js";
+
+/** What every reader needs of a client: raw reads only. */
+export type ConsentReadClient = Pick<Prisma.TransactionClient, "$queryRaw">;
+
+/**
+ * The sources only a verified caller or a signed link can write (D4,
+ * SEC-8438-1). The SQL below names the same three literals; the store's test
+ * asserts the two agree.
+ */
+export const OWN_CONSENT_SOURCES = [
+  "sign_up",
+  "account_settings",
+  "email_unsubscribe",
+] as const satisfies readonly ConsentSource[];
+
+/** The sources whose rows prove nothing the client confirmed themself. */
+const UNVERIFIED_SOURCES: ReadonlySet<ConsentSource> = new Set([
+  "magnet",
+  "api",
+  "cookie_banner",
+  "legacy",
+]);
+
+/** Whether a row from `source` is unconfirmed by the client (D4). */
+export function isUnverifiedSource(source: ConsentSource): boolean {
+  return UNVERIFIED_SOURCES.has(source);
+}
+
+/** A history page's size (D7). */
+export const CONSENT_HISTORY_PAGE_SIZE = 500;
+
+/** The most platform rows one user can have in view (D4). */
+const PLATFORM_ROWS_MAX = 100;
+
+/** The newest ledger row for one purpose, as the readers serve it. */
+export interface ConsentStateRow {
+  id: string;
+  purposeId: string;
+  granted: boolean;
+  at: Date;
+  source: ConsentSource;
+  sourceRef: string | null;
+  policyVersion: number | null;
+}
+
+export interface ConsentHistoryRow extends ConsentStateRow {
+  locale: string;
+  statement: string;
+  subjectType: string;
+}
+
+/** A registry purpose with the newest row read for it and what that means now. */
+export interface PurposeConsentState {
+  purposeId: string;
+  kind: ConsentPurposeKind;
+  row: ConsentStateRow | null;
+  /** Granted now: the row's answer, else on for a preference and off otherwise. */
+  effective: boolean;
+}
+
+/** The effective answer for a purpose given its newest row (D4). */
+export function effectiveConsent(
+  kind: ConsentPurposeKind,
+  row: { granted: boolean } | null,
+): boolean {
+  if (row !== null) return row.granted;
+  return kind === "preference";
+}
+
+/** Fold the newest row per purpose id into the registry's purposes. */
+export function foldRowsIntoPurposes(
+  config: SiteConsentConfig,
+  rows: readonly ConsentStateRow[],
+): PurposeConsentState[] {
+  const byPurpose = new Map(rows.map((row) => [row.purposeId, row]));
+  return config.purposes.map((purpose) => {
+    const kind = consentPurposeKind(purpose);
+    const row = byPurpose.get(purpose.id) ?? null;
+    return {
+      purposeId: purpose.id,
+      kind,
+      row,
+      effective: effectiveConsent(kind, row),
+    };
+  });
+}
+
+/**
+ * The newest OWN row per purpose id for a Person, unfolded (D4): one indexed
+ * `DISTINCT ON` pass over all own rows, never a window.
+ */
+export async function ownConsentRows(
+  workspaceId: string,
+  personId: string,
+  db: ConsentReadClient = prisma,
+): Promise<ConsentStateRow[]> {
+  return db.$queryRaw<ConsentStateRow[]>`
+    SELECT DISTINCT ON (g."purpose_id")
+      g."id", g."purpose_id" AS "purposeId", g."granted", g."created_at" AS "at",
+      g."source", g."source_ref" AS "sourceRef", g."policy_version" AS "policyVersion"
+    FROM "consent_grants" g
+    WHERE g."workspace_id" = ${workspaceId}
+      AND g."person_id" = ${personId}
+      AND g."source" IN ('sign_up', 'account_settings', 'email_unsubscribe')
+    ORDER BY g."purpose_id", g."created_at" DESC, g."id" DESC`;
+}
+
+/**
+ * The newest ANY-SOURCE row per purpose id for a Person: `person_id = P` or a
+ * cookie row of a visitor linked to P, in this workspace on both tables.
+ * Includes purposes the registry no longer declares — the operator still sees
+ * what was recorded.
+ */
+export async function anySourceConsentRows(
+  workspaceId: string,
+  personId: string,
+  db: ConsentReadClient = prisma,
+): Promise<ConsentStateRow[]> {
+  return db.$queryRaw<ConsentStateRow[]>`
+    SELECT DISTINCT ON (g."purpose_id")
+      g."id", g."purpose_id" AS "purposeId", g."granted", g."created_at" AS "at",
+      g."source", g."source_ref" AS "sourceRef", g."policy_version" AS "policyVersion"
+    FROM "consent_grants" g
+    WHERE g."workspace_id" = ${workspaceId}
+      AND (
+        g."person_id" = ${personId}
+        OR (g."subject_type" = 'visitor' AND g."subject_id" IN (
+          SELECT l."visitor_id" FROM "consent_visitor_links" l
+          WHERE l."workspace_id" = ${workspaceId} AND l."person_id" = ${personId}
+        ))
+      )
+    ORDER BY g."purpose_id", g."created_at" DESC, g."id" DESC`;
+}
+
+/**
+ * A Person's OWN reading, per registry purpose (D4). The member's screens and
+ * the sign-up prompt read only this.
+ */
+export async function ownConsentState(
+  workspaceId: string,
+  personId: string,
+  config: SiteConsentConfig,
+  db: ConsentReadClient = prisma,
+): Promise<PurposeConsentState[]> {
+  return foldRowsIntoPurposes(
+    config,
+    await ownConsentRows(workspaceId, personId, db),
+  );
+}
+
+/**
+ * A Person's ANY-SOURCE reading, per registry purpose. The operator's Person
+ * page and the unsubscribe dedupe read it; a row here is never a member's own
+ * answer (D4).
+ */
+export async function anySourceConsentState(
+  workspaceId: string,
+  personId: string,
+  config: SiteConsentConfig,
+  db: ConsentReadClient = prisma,
+): Promise<PurposeConsentState[]> {
+  return foldRowsIntoPurposes(
+    config,
+    await anySourceConsentRows(workspaceId, personId, db),
+  );
+}
+
+/** One page of a Person's any-source history, newest first. */
+export interface ConsentHistoryPage {
+  rows: ConsentHistoryRow[];
+  /** The id of the page's last row when another page follows, else `null`. */
+  nextCursor: string | null;
+}
+
+/**
+ * A Person's any-source history, 500 rows a page, newest first, keyed by
+ * `(created_at, id)`. Every page is complete: nothing is truncated (D7).
+ * Returns `"invalid_cursor"` for a cursor that is not one of this Person's
+ * rows — checked inside the Person's own scope, so a row id of another
+ * Person or workspace reads exactly like an unknown one.
+ */
+export async function personConsentHistory(
+  workspaceId: string,
+  personId: string,
+  cursor: string | undefined,
+  db: ConsentReadClient = prisma,
+): Promise<ConsentHistoryPage | "invalid_cursor"> {
+  if (cursor !== undefined) {
+    const found = await db.$queryRaw<Array<{ id: string }>>`
+      SELECT g."id" FROM "consent_grants" g
+      WHERE g."workspace_id" = ${workspaceId}
+        AND g."id" = ${cursor}
+        AND (
+          g."person_id" = ${personId}
+          OR (g."subject_type" = 'visitor' AND g."subject_id" IN (
+            SELECT l."visitor_id" FROM "consent_visitor_links" l
+            WHERE l."workspace_id" = ${workspaceId} AND l."person_id" = ${personId}
+          ))
+        )
+      LIMIT 1`;
+    if (found.length === 0) return "invalid_cursor";
+  }
+  const cursorId = cursor ?? null;
+  const rows = await db.$queryRaw<ConsentHistoryRow[]>`
+    SELECT g."id", g."purpose_id" AS "purposeId", g."granted", g."created_at" AS "at",
+      g."source", g."source_ref" AS "sourceRef", g."policy_version" AS "policyVersion",
+      g."locale", g."statement", g."subject_type" AS "subjectType"
+    FROM "consent_grants" g
+    WHERE g."workspace_id" = ${workspaceId}
+      AND (
+        g."person_id" = ${personId}
+        OR (g."subject_type" = 'visitor' AND g."subject_id" IN (
+          SELECT l."visitor_id" FROM "consent_visitor_links" l
+          WHERE l."workspace_id" = ${workspaceId} AND l."person_id" = ${personId}
+        ))
+      )
+      AND (${cursorId}::text IS NULL OR (g."created_at", g."id") < (
+        SELECT c."created_at", c."id" FROM "consent_grants" c WHERE c."id" = ${cursorId}::text
+      ))
+    ORDER BY g."created_at" DESC, g."id" DESC
+    LIMIT ${CONSENT_HISTORY_PAGE_SIZE + 1}`;
+  const page = rows.slice(0, CONSENT_HISTORY_PAGE_SIZE);
+  const last = page[page.length - 1];
+  return {
+    rows: page,
+    nextCursor:
+      rows.length > CONSENT_HISTORY_PAGE_SIZE && last ? last.id : null,
+  };
+}
+
+/**
+ * The newest row recording a visitor's choice for one purpose — the cookie
+ * writer's dedupe: each CHANGE of choice is logged, a replay adds nothing
+ * (D3, SEC-8438-2).
+ */
+export async function latestVisitorChoice(
+  workspaceId: string,
+  visitorId: string,
+  purposeId: string,
+  db: ConsentReadClient = prisma,
+): Promise<{ granted: boolean; policyVersion: number | null } | null> {
+  const rows = await db.$queryRaw<
+    Array<{ granted: boolean; policyVersion: number | null }>
+  >`
+    SELECT g."granted", g."policy_version" AS "policyVersion"
+    FROM "consent_grants" g
+    WHERE g."workspace_id" = ${workspaceId}
+      AND g."subject_type" = 'visitor'
+      AND g."subject_id" = ${visitorId}
+      AND g."purpose_id" = ${purposeId}
+    ORDER BY g."created_at" DESC, g."id" DESC
+    LIMIT 1`;
+  return rows[0] ?? null;
+}
+
+/**
+ * When the caller's own `User` row was created — the sign-up window's only
+ * input (SEC-8438-5: `via: "sign_up"` is honored for a user created within
+ * the last 24 hours). `null` when no such user exists.
+ */
+export async function userCreatedAt(
+  userId: string,
+  db: Pick<Prisma.TransactionClient, "user"> = prisma,
+): Promise<Date | null> {
+  const user = await db.user.findUnique({
+    where: { id: userId },
+    select: { createdAt: true },
+  });
+  return user?.createdAt ?? null;
+}
+
+/**
+ * The owner's rows for the Working Theory platform purposes (C8): subject
+ * `user` / `userId`, newest per purpose, at most 100.
+ */
+export async function userPlatformRows(
+  workspaceId: string,
+  userId: string,
+  db: ConsentReadClient = prisma,
+): Promise<ConsentStateRow[]> {
+  return db.$queryRaw<ConsentStateRow[]>`
+    SELECT DISTINCT ON (g."purpose_id")
+      g."id", g."purpose_id" AS "purposeId", g."granted", g."created_at" AS "at",
+      g."source", g."source_ref" AS "sourceRef", g."policy_version" AS "policyVersion"
+    FROM "consent_grants" g
+    WHERE g."workspace_id" = ${workspaceId}
+      AND g."subject_type" = 'user'
+      AND g."subject_id" = ${userId}
+    ORDER BY g."purpose_id", g."created_at" DESC, g."id" DESC
+    LIMIT ${PLATFORM_ROWS_MAX}`;
+}

package/templates/apps/api/src/lib/proposal-paid-store.ts

@@ -0,0 +1,49 @@
+/**
+ * The proposal paid stamp's data boundary (#8516, spec
+ * docs/specs/8516-proposals-as-an-artifact-kind-spec.md D13).
+ *
+ * The Stripe webhook (`routes/webhooks/stripe.ts`) is a commerce primitive
+ * registered on every build, so it may import no slice-owned file —
+ * `lib/member-store.ts` is one, and importing it would pull the webhook out of
+ * every scaffold without the member slice (the #5677 failure). Its one piece
+ * write therefore lives here, in the base tree, importing only `prisma.ts`.
+ *
+ * Two statements and no others, both scoped by a workspace id AND a piece id
+ * taken from a Stripe-signed `checkout.session.completed` event's metadata —
+ * written by this server when it opened the session (`ailk_proposal`,
+ * `ailk_workspace`; `services/proposal-payments.ts`), never settable by the
+ * payer: a guarded `updateMany` that stamps an unpaid proposal paid, and a
+ * `findFirst` by the same pair reading back which session paid it. No list,
+ * no other model, no read by any other key; never called by a route.
+ * `architecture.yaml` names this file as a tenant-scope exclusion with that
+ * reason.
+ */
+import { prisma } from "./prisma.js";
+
+/**
+ * - `stamped`      — this session paid an unpaid proposal; stamped now.
+ * - `replay`       — the proposal was already stamped by THIS session.
+ * - `already_paid` — a DIFFERENT session already paid it (a second charge).
+ * - `not_found`    — no proposal of that id in that workspace.
+ */
+export type ProposalPaidOutcome = "stamped" | "replay" | "already_paid" | "not_found";
+
+/** Stamp a proposal paid by `sessionId`, at most once. */
+export async function stampProposalPaid(
+  workspaceId: string,
+  pieceId: string,
+  sessionId: string,
+  now: Date,
+): Promise<ProposalPaidOutcome> {
+  const stamped = await prisma.piece.updateMany({
+    where: { id: pieceId, workspaceId, kind: "proposal", paidAt: null },
+    data: { paidAt: now, paidSessionId: sessionId },
+  });
+  if (stamped.count > 0) return "stamped";
+  const row = await prisma.piece.findFirst({
+    where: { id: pieceId, workspaceId, kind: "proposal" },
+    select: { paidSessionId: true },
+  });
+  if (row === null) return "not_found";
+  return row.paidSessionId === sessionId ? "replay" : "already_paid";
+}

package/templates/apps/api/src/lib/rate-limit-probe.ts

@@ -0,0 +1,165 @@
+/**
+ * The live rate-limiter probe's logic (#5040 D9, FR-7). Pure: takes its
+ * `fetch` and `sleep` so the CLI bin (`bin/rate-limit-probe.ts`) and the test
+ * suite can both drive it without a real network or a real 60-second wait.
+ * See the bin's header for what it answers and why.
+ */
+
+const TEST_NET_3_PREFIX = "203.0.113.";
+
+export type ProbeFetch = (
+  url: string,
+  init: { headers: Record<string, string> },
+) => Promise<{ status: number }>;
+
+export interface RunRateLimitProbeOptions {
+  origin: string;
+  fetch: ProbeFetch;
+  limit?: number;
+  windowMs?: number;
+  sleep?: (ms: number) => Promise<void>;
+  log?: (msg: string) => void;
+}
+
+function isAllowedOrigin(origin: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(origin);
+  } catch {
+    return false;
+  }
+  if (url.protocol === "https:") return true;
+  if (url.protocol !== "http:") return false;
+  const host = url.hostname;
+  return host === "localhost" || host === "127.0.0.1" || host === "::1";
+}
+
+function randomTestNet3(exclude: ReadonlySet<string>): string {
+  let candidate: string;
+  do {
+    candidate = `${TEST_NET_3_PREFIX}${1 + Math.floor(Math.random() * 254)}`;
+  } while (exclude.has(candidate));
+  return candidate;
+}
+
+function describeError(err: unknown): string {
+  if (
+    err !== null &&
+    typeof err === "object" &&
+    "code" in err &&
+    typeof (err as { code?: unknown }).code === "string"
+  ) {
+    return (err as { code: string }).code;
+  }
+  return err instanceof Error ? err.message : String(err);
+}
+
+const PROBE_PATH = "/v1/aeo/score/example";
+
+/**
+ * Runs the two-fact probe (#5040 D9) against `origin`. Returns the process
+ * exit code the bin should use: `0` on `burst: holds`, `1` on every other
+ * conclusive-but-not-holding outcome (`limiter: not-observed`,
+ * `burst: exceeded`, `burst: inconclusive`), `2` on a refused origin or a
+ * network/status error.
+ */
+export async function runRateLimitProbe(
+  opts: RunRateLimitProbeOptions,
+): Promise<number> {
+  const {
+    origin,
+    fetch,
+    limit = 10,
+    windowMs = 60_000,
+    sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)),
+    log = (msg: string) => console.log(msg),
+  } = opts;
+
+  if (!isAllowedOrigin(origin)) {
+    log("probe: error invalid-origin");
+    return 2;
+  }
+
+  const url = `${origin}${PROBE_PATH}`;
+  const used = new Set<string>();
+  const identityA = randomTestNet3(used);
+  used.add(identityA);
+
+  async function send(identity: string): Promise<number> {
+    const res = await fetch(url, { headers: { "x-forwarded-for": identity } });
+    return res.status;
+  }
+
+  let lastStatus: number | undefined;
+  try {
+    for (let i = 0; i < limit + 1; i++) {
+      const status = await send(identityA);
+      if (status !== 200 && status !== 429) {
+        log(`probe: error ${status}`);
+        return 2;
+      }
+      lastStatus = status;
+    }
+  } catch (err) {
+    log(`probe: error ${describeError(err)}`);
+    return 2;
+  }
+
+  if (lastStatus !== 429) {
+    log("limiter: not-observed");
+    return 1;
+  }
+
+  const identityB = randomTestNet3(used);
+  used.add(identityB);
+  let survives: boolean;
+  try {
+    const status = await send(identityB);
+    if (status !== 200 && status !== 429) {
+      log(`probe: error ${status}`);
+      return 2;
+    }
+    survives = status === 200;
+  } catch (err) {
+    log(`probe: error ${describeError(err)}`);
+    return 2;
+  }
+  log(survives ? "xff: survives" : "xff: overwritten");
+
+  let burstIdentity: string;
+  if (survives) {
+    burstIdentity = randomTestNet3(used);
+  } else {
+    await sleep(windowMs + 2_000);
+    burstIdentity = identityA;
+  }
+
+  const total = 3 * limit;
+  let successes = 0;
+  try {
+    const results = await Promise.all(
+      Array.from({ length: total }, () => send(burstIdentity)),
+    );
+    for (const status of results) {
+      if (status !== 200 && status !== 429) {
+        log(`probe: error ${status}`);
+        return 2;
+      }
+      if (status === 200) successes += 1;
+    }
+  } catch (err) {
+    log(`probe: error ${describeError(err)}`);
+    return 2;
+  }
+
+  if (successes === 0) {
+    log(`burst: inconclusive (0/${total})`);
+    return 1;
+  }
+  if (successes > limit) {
+    log(`burst: exceeded (${successes}/${total})`);
+    return 1;
+  }
+  log(`burst: holds (${successes}/${total})`);
+  return 0;
+}

package/templates/apps/api/src/lib/rate-limit-store.ts

@@ -0,0 +1,142 @@
+/**
+ * The rate limiter's database store (#5040 D1/D3/D4). Counts a bucket in
+ * `rate_limit_counters` so one visitor's limit holds across every concurrent
+ * isolate on a deployment with a database — see
+ * `apps/api/src/middleware/rate-limit.ts`'s `SHARED STORE` header for the
+ * full picture (what this protects against, and what it does not).
+ *
+ * The only file naming `rate_limit_counters` outside `database/`. All SQL is
+ * `db.$queryRaw` / `db.$executeRaw` tagged templates — never `…Unsafe` — so
+ * every value is a bound parameter, never string-interpolated.
+ */
+import { createHash } from "node:crypto";
+
+import type { Prisma } from "@working-theory/database";
+
+/** One bucket's state, as both the memory and database stores report it. */
+export type RateLimitBucket = {
+  count: number;
+  windowStartMs: number;
+};
+
+/** What a store call reports when it ran against a backing database. */
+export type RateLimitStore = {
+  /** Count one request against `key`'s visitor bucket. */
+  hit(key: string, now: number, windowMs: number): Promise<RateLimitBucket>;
+  /** Count one request against `key`'s forwarding-key bucket (#7394 DD-8). */
+  hitKey(key: string, now: number, windowMs: number): Promise<RateLimitBucket>;
+  /** True when `key` has a bucket whose window has not yet ended. */
+  hasOpenWindow(key: string, now: number, windowMs: number): Promise<boolean>;
+  /** Evict expired buckets. `reason` is why the sweep fired (D6). */
+  sweep(now: number, windowMs: number, reason: "interval" | "limited"): Promise<void>;
+};
+
+/** What `createDatabaseRateLimitStore` needs of a Prisma client (D3). */
+export type RateLimitSqlClient = Pick<
+  Prisma.TransactionClient,
+  "$queryRaw" | "$executeRaw"
+>;
+
+function sha256Hex(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+/**
+ * The database store (D1/D3): one atomic upsert per hit, same window rules as
+ * the memory store. `bucketKey` is the exact string the memory store uses as
+ * its Map key; this store hashes it before it ever reaches SQL (FR-5) — the
+ * table never holds a plaintext IP or bucket key.
+ */
+export function createDatabaseRateLimitStore(
+  db: RateLimitSqlClient,
+): RateLimitStore {
+  async function countHit(
+    bucketKey: string,
+    now: number,
+    windowMs: number,
+  ): Promise<RateLimitBucket> {
+    const hash = sha256Hex(bucketKey);
+    const rows = await db.$queryRaw<
+      Array<{ count: number; window_start_ms: bigint | string }>
+    >`
+      INSERT INTO "rate_limit_counters" ("key_hash", "window_start_ms", "window_ms", "count")
+      VALUES (${hash}, ${now}::bigint, ${windowMs}::integer, 1)
+      ON CONFLICT ("key_hash") DO UPDATE SET
+        "count" = CASE WHEN ${now}::bigint - "rate_limit_counters"."window_start_ms" >= ${windowMs}::integer
+                       THEN 1 ELSE "rate_limit_counters"."count" + 1 END,
+        "window_start_ms" = CASE WHEN ${now}::bigint - "rate_limit_counters"."window_start_ms" >= ${windowMs}::integer
+                       THEN ${now}::bigint ELSE "rate_limit_counters"."window_start_ms" END,
+        "window_ms" = ${windowMs}::integer
+      RETURNING "count", "window_start_ms"
+    `;
+    const row = rows[0];
+    if (!row) {
+      throw new Error("rate_limit_counters upsert returned no row");
+    }
+    return {
+      count: Number(row.count),
+      windowStartMs: Number(row.window_start_ms),
+    };
+  }
+
+  async function hasOpenWindow(
+    bucketKey: string,
+    now: number,
+    windowMs: number,
+  ): Promise<boolean> {
+    const hash = sha256Hex(bucketKey);
+    const rows = await db.$queryRaw<Array<{ one: number }>>`
+      SELECT 1 AS "one" FROM "rate_limit_counters"
+      WHERE "key_hash" = ${hash}
+        AND ${now}::bigint - "window_start_ms" < ${windowMs}::integer
+      LIMIT 1
+    `;
+    return rows.length > 0;
+  }
+
+  return {
+    hit: (key, now, windowMs) => countHit(key, now, windowMs),
+    hitKey: (key, now, windowMs) => countHit(key, now, windowMs),
+    hasOpenWindow,
+    async sweep(now, _windowMs, reason) {
+      // D6 — the database store sweeps on the interval trigger only. Sweeping
+      // on every 429 would let an attacker buy a table scan per refused
+      // request.
+      if (reason !== "interval") return;
+      await db.$executeRaw`
+        DELETE FROM "rate_limit_counters"
+        WHERE "window_start_ms" + "window_ms" <= ${now}::bigint
+      `;
+    },
+  };
+}
+
+/**
+ * Which store a registration with no explicit `store` option uses (D4),
+ * resolved once per process and memoized by the middleware. `warn` is called
+ * exactly once for each of the two misconfiguration rows below.
+ */
+export type RateLimitStoreEnv = {
+  DATABASE_URL?: string | undefined;
+  AILK_RATE_LIMIT_STORE?: string | undefined;
+};
+
+export function resolveRateLimitStoreKind(
+  env: RateLimitStoreEnv,
+  warn: (msg: string) => void,
+): "memory" | "database" {
+  const hasDatabase = !!env.DATABASE_URL;
+  const raw = env.AILK_RATE_LIMIT_STORE;
+
+  if (raw === undefined || raw === "") {
+    return hasDatabase ? "database" : "memory";
+  }
+  if (raw === "memory") return "memory";
+  if (raw === "database") {
+    if (hasDatabase) return "database";
+    warn("AILK_RATE_LIMIT_STORE=database needs DATABASE_URL; using memory");
+    return "memory";
+  }
+  warn("AILK_RATE_LIMIT_STORE is not memory or database and is ignored");
+  return hasDatabase ? "database" : "memory";
+}