create-ailk 0.22.0 → 0.24.0

package/templates/apps/api/src/lib/site.ts

@@ -144,7 +144,10 @@ export async function resolveWorkspaceIdForAlias(
     const row = await resolveSentinelWorkspaceRow(prisma);
     return row?.id ?? null;
   }
-  const row = await prisma.workspace.findUnique({ where: { id: alias } });
+  const row = await prisma.workspace.findUnique({
+    where: { id: alias },
+    select: { id: true },
+  });
   return row ? alias : null;
 }
 

package/templates/apps/api/src/lib/stripe.ts

@@ -8,11 +8,14 @@
  * '@working-theory/stripe-client' — single chokepoint for AILK-internal ergonomics
  * (logger context, request-id propagation) without touching every consumer.
  */
+import { logger } from "@working-theory/observability";
 import {
   admitLiveRestrictedKey,
   assertSandboxKey,
+  createStripeClientForKey,
   getStripeClient,
   StripeConfigError,
+  type StripeConnectionMode,
 } from "@working-theory/stripe-client";
 
 export {
@@ -26,24 +29,39 @@ export {
   // Both are on main (#6850, #6862); #8450 is the narrowing this guarded —
   // `assertAdmittedStripeKey` below. This export itself stays sandbox-only.
   assertSandboxKey,
+  // The plan checkout's mode assertion and terms-box failure (#9067 D3 step 9).
+  CheckoutModeMismatchError,
+  // The Organization connection's key classifier (#8906, #8907 D4).
+  classifyStripeKey,
   createAdHocPrice,
   createBillingPortalSession,
   createCheckoutSession,
+  // The Offerings checkout's per-client calls (#8931 D6), on the connection's client.
+  createCheckoutSessionForPrice,
   createPaymentLink,
   createQuotedCheckoutSession,
+  // Start trial's hosted trial session (#9342 DD2), on the Organization's client.
+  createTrialCheckoutSession,
+  expireCheckoutSessionWith,
+  findActivePriceByLookupKey,
   getStripeClient,
+  // Working Theory's own absolute policies for the plan checkout's terms box (#9067 D3 step 9).
+  PLATFORM_TERMS_OF_SERVICE,
   // Checkout session read (#6084 D9) — re-exported through this sole
   // Stripe-touching chokepoint, same as every other Stripe call here.
   retrieveCheckoutSession,
   STRIPE_API_VERSION,
   StripeConfigError,
   StripeWebhookSignatureError,
+  TermsOfServiceUrlMissingError,
   toSubscriptionLifecycleStatus,
   // Signed-in Checkout (#6866 D8) — a pinned customer Stripe rejects.
   UnknownCustomerError,
   UnknownProductCodeError,
   UnknownSessionError,
   verifyWebhookSignature,
+  // The per-Organization webhook's verify (#8932 D3): the row's secret, no env key.
+  verifyWebhookSignatureKeyless,
   WEBHOOK_TOLERANCE_SECONDS,
 } from "@working-theory/stripe-client";
 
@@ -55,15 +73,19 @@ export type {
   CreateBillingPortalSessionOutput,
   CreatePaymentLinkInput,
   CreatePaymentLinkOutput,
+  CreateCheckoutSessionForPriceInput,
   CreateCheckoutSessionInput,
   CreateCheckoutSessionOutput,
   CreateCheckoutSessionParams,
   CreateQuotedCheckoutSessionInput,
   CreateQuotedCheckoutSessionOutput,
+  CreateTrialCheckoutSessionInput,
   RetrieveCheckoutSessionInput,
   RetrieveCheckoutSessionOutput,
   Stripe,
   StripeCheckoutSession,
+  StripeConnectionMode,
+  StripeKeyClass,
   StripeWebhookEvent,
 } from "@working-theory/stripe-client";
 
@@ -81,9 +103,10 @@ let liveKeyAdmitted = false;
  * rule, with one fail-closed delta (PR #8470 security review R-1): on Vercel
  * (`VERCEL` set) a missing `VERCEL_ENV` is not production, because
  * `vercel.json` sets `NODE_ENV=production` in every environment, Preview
- * included.
+ * included. Exported for the Organization connection's go-live check and
+ * its live-row guard (#8907 D3, D8 step 6); the body is unchanged.
  */
-function isProductionBuild(): boolean {
+export function isProductionBuild(): boolean {
   if (process.env.VERCEL_ENV !== undefined) {
     return process.env.VERCEL_ENV === "production";
   }
@@ -145,6 +168,35 @@ export function assertAdmittedStripeKey(key: string): void {
   assertSandboxKey(key);
 }
 
+/**
+ * A fresh Stripe client from ONE Organization's own key (#8907 D12, #8906
+ * F-T1 to F-T3), or `null` when the factory refuses it: the factory's only
+ * caller, so `productionBuild` is always the strict predicate above and never
+ * a caller's boolean. It reads and sets no process flag — `stripeKeyMode()`
+ * is untouched — so one process holds a live Organization and a test one
+ * (contract K6, K7). A refusal logs `{ organizationId, reason }` only.
+ * `architecture.yaml` confines its callers to exact paths.
+ */
+export function stripeClientForConnection(input: {
+  organizationId: string;
+  key: string;
+  mode: StripeConnectionMode;
+  liveAt: Date | null;
+}): ReturnType<typeof createStripeClientForKey> {
+  return createStripeClientForKey({
+    organizationId: input.organizationId,
+    key: input.key,
+    mode: input.mode,
+    liveAt: input.liveAt,
+    productionBuild: isProductionBuild(),
+    log: (refusal) =>
+      logger.warn(
+        { organizationId: refusal.organizationId, reason: refusal.reason },
+        "[stripe] connection key refused for its mode",
+      ),
+  });
+}
+
 /** The key class this process admitted at boot: `"live"` only after `admitApiStripeKey()` did. */
 export function stripeKeyMode(): "test" | "live" {
   return liveKeyAdmitted ? "live" : "test";
@@ -165,14 +217,22 @@ export async function expireCheckoutSession(stripeSessionId: string): Promise<vo
   await getStripeClient().checkout.sessions.expire(stripeSessionId);
 }
 
-/** #8171 D7 — what the Billing page shows: the plan's name and the card on file. */
+/**
+ * #8171 D7 — what the Billing page shows: the plan's name and the card on
+ * file. #9067 D6 adds the renewal date and the site count, read from the
+ * same subscription.
+ */
 export type CustomerBillingSummary = {
   planName: string | null;
   paymentMethod: { brand: string; last4: string; expMonth: number; expYear: number } | null;
+  renewsAt: string | null;
+  sites: number | null;
 };
 
 /** A subscription status that still names the customer's plan (#8171 C10). */
 const CURRENT_SUBSCRIPTION_STATUSES = new Set(["active", "trialing", "past_due", "unpaid"]);
+/** A subscription status that renews at its period end (#9067 C3). */
+const RENEWING_SUBSCRIPTION_STATUSES = new Set(["active", "trialing", "past_due"]);
 const PLAN_NAME_MAX = 200;
 
 /**
@@ -224,7 +284,20 @@ export async function readCustomerBillingSummary(
           ?.default_payment_method ?? null;
   }
 
-  return { planName, paymentMethod: cardOf(method) };
+  // #9067 C3, D6 — under `dahlia` the period end lives on the item, and a
+  // subscription set to cancel names no renewal.
+  const item = current?.items.data[0];
+  const renews =
+    current !== undefined &&
+    RENEWING_SUBSCRIPTION_STATUSES.has(current.status) &&
+    current.cancel_at_period_end !== true &&
+    current.cancel_at == null &&
+    typeof item?.current_period_end === "number";
+  const renewsAt = renews ? new Date(item.current_period_end * 1000).toISOString() : null;
+  const quantity = item?.quantity;
+  const sites = typeof quantity === "number" && Number.isInteger(quantity) && quantity >= 1 ? quantity : null;
+
+  return { planName, paymentMethod: cardOf(method), renewsAt, sites };
 }
 
 /** A `card` payment method's presentation fields, or `null` for anything else. */

package/templates/apps/api/src/lib/webhook-idempotency.ts

@@ -82,11 +82,75 @@ export function markSeen(eventId: string, nowMs: number = Date.now()): void {
   }
 }
 
+// ─── Per-Organization store (#8932 D8, contract W10) ─────────────────────────
+//
+// The per-Organization endpoint (`POST /v1/webhooks/stripe/:connectionToken`)
+// dedupes in its OWN map, keyed `<organizationId>:<eventId>`, so neither
+// endpoint's dedup can swallow the other's event (SEC-8879-1) and two
+// Organizations sharing one Stripe account never collide (an Organization id
+// holds no `:`). Same TTL, soft cap and sweep rules as the legacy pair above;
+// the legacy `hasSeen`/`markSeen` never read it. Correctness rests on the
+// lead's database key, not on this map.
+
+const orgStore = new Map<string, Entry>();
+let orgInsertsSinceLastSweep = 0;
+
+function orgKey(organizationId: string, eventId: string): string {
+  return `${organizationId}:${eventId}`;
+}
+
+function sweepOrgExpired(nowMs: number): void {
+  for (const [key, entry] of orgStore) {
+    if (nowMs - entry.insertedAtMs >= IDEMPOTENCY_TTL_MS) {
+      orgStore.delete(key);
+    }
+  }
+  orgInsertsSinceLastSweep = 0;
+}
+
+/** `hasSeen`'s twin for one Organization's endpoint. */
+export function hasSeenForOrganization(
+  organizationId: string,
+  eventId: string,
+  nowMs: number = Date.now(),
+): boolean {
+  const key = orgKey(organizationId, eventId);
+  const entry = orgStore.get(key);
+  if (!entry) return false;
+  if (nowMs - entry.insertedAtMs >= IDEMPOTENCY_TTL_MS) {
+    orgStore.delete(key);
+    return false;
+  }
+  return true;
+}
+
+/** `markSeen`'s twin for one Organization's endpoint. */
+export function markSeenForOrganization(
+  organizationId: string,
+  eventId: string,
+  nowMs: number = Date.now(),
+): void {
+  const key = orgKey(organizationId, eventId);
+  if (!orgStore.has(key)) {
+    orgStore.set(key, { insertedAtMs: nowMs });
+  }
+
+  orgInsertsSinceLastSweep += 1;
+  if (
+    orgStore.size > SOFT_CAP ||
+    orgInsertsSinceLastSweep >= SWEEP_INTERVAL_INSERTS
+  ) {
+    sweepOrgExpired(nowMs);
+  }
+}
+
 /**
- * Test-only reset. Clears all dedup state between test cases so they do not
- * interfere with each other.
+ * Test-only reset. Clears all dedup state — both stores — between test cases
+ * so they do not interfere with each other.
  */
 export function __resetIdempotencyStore(): void {
   store.clear();
   insertsSinceLastSweep = 0;
+  orgStore.clear();
+  orgInsertsSinceLastSweep = 0;
 }

package/templates/apps/api/src/middleware/__tests__/rate-limit.test.ts

@@ -22,6 +22,9 @@ import {
   buildTrustedKeyDigests,
   DEFAULT_PER_IP_PER_MINUTE_STRICT,
   resolveRateLimitIdentity,
+  siteKeyReader,
+  SITE_KEYED_ROUTES,
+  DEFAULT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE,
   type RateLimitOptions,
 } from "../rate-limit.js";
 
@@ -845,6 +848,7 @@ describe("per-visitor forwarding, scope namespace and per-scope env limit (#7394
         { method: "POST", url: "/v1/project-listings" },
         { method: "PATCH", url: "/v1/project-listings/drafts/:id" },
         { method: "POST", url: "/v1/project-listings/drafts/:id/submit" },
+        { method: "GET", url: "/v1/deliverables/open/:slug" },
       ]);
     });
   });
@@ -1189,3 +1193,217 @@ describe("per-visitor forwarding, scope namespace and per-scope env limit (#7394
     });
   });
 });
+
+describe("the sign-up evidence read is counted per site key (#8805)", () => {
+  const SIGN_UP = "/v1/consent/sign-up";
+  const WEB_EGRESS = "198.51.100.20";
+  const VALID = "ailk_spk_valid-site-key";
+  const SPOKE_ID = "spoke_01920000-0000-7000-8000-0000000000b1";
+  const ENV_KEYS = [
+    "AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_MINUTE",
+    "AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE",
+  ] as const;
+  const priorEnv = new Map<string, string | undefined>(
+    ENV_KEYS.map((name) => [name, process.env[name]]),
+  );
+
+  let app: FastifyInstance | undefined;
+  let verify: jest.Mock<Promise<string | null>, [unknown]>;
+  let logLines: Array<Record<string, unknown>>;
+
+  function signUpApp(opts: Partial<RateLimitOptions> = {}): FastifyInstance {
+    const instance = Fastify({
+      trustProxy: true,
+      logger: {
+        level: "warn",
+        stream: {
+          write(msg: string) {
+            logLines.push(JSON.parse(msg) as Record<string, unknown>);
+          },
+        },
+      },
+    });
+    instance.register(rateLimitMiddleware, {
+      perIpPerMinute: DEFAULT_PER_IP_PER_MINUTE_STRICT,
+      perKeyPerMinute: 25,
+      scope: "signupevidence",
+      siteKeyOf: siteKeyReader(verify),
+      ...opts,
+    });
+    instance.get(SIGN_UP, async () => ({ ok: true }));
+    instance.get("/v1/other", async () => ({ ok: true }));
+    return instance;
+  }
+
+  async function statuses(
+    count: number,
+    headers: Record<string, string>,
+    url: string = SIGN_UP,
+  ): Promise<number[]> {
+    if (!app) throw new Error("no app");
+    const codes: number[] = [];
+    for (let i = 0; i < count; i++) {
+      const res = await app.inject({ method: "GET", url, headers });
+      codes.push(res.statusCode);
+    }
+    return codes;
+  }
+
+  const keyed = (ip: string = WEB_EGRESS, key: string = VALID) => ({
+    "x-forwarded-for": ip,
+    "x-ailk-spoke-key": key,
+  });
+
+  beforeEach(() => {
+    __resetBuckets();
+    logLines = [];
+    for (const name of ENV_KEYS) delete process.env[name];
+    verify = jest.fn((req: unknown) => {
+      const headers = (req as { headers: Record<string, unknown> }).headers;
+      return Promise.resolve(
+        headers["x-ailk-spoke-key"] === VALID ? SPOKE_ID : null,
+      );
+    });
+  });
+
+  afterEach(async () => {
+    if (app) await app.close();
+    app = undefined;
+  });
+
+  afterAll(() => {
+    for (const [name, value] of priorEnv) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  });
+
+  it("lists GET /v1/consent/sign-up as the one site-keyed route", () => {
+    expect(SITE_KEYED_ROUTES).toEqual([{ method: "GET", url: SIGN_UP }]);
+  });
+
+  it("names a per-key default well above the per-IP 10", () => {
+    expect(DEFAULT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE).toBe(120);
+  });
+
+  it("admits keyed requests from one IP past 10 a minute, up to the key ceiling, then 429", async () => {
+    app = signUpApp();
+    await app.ready();
+    const codes = await statuses(26, keyed());
+    expect(codes.slice(0, 25).every((code) => code === 200)).toBe(true);
+    expect(codes[25]).toBe(429);
+  });
+
+  it("refuses the eleventh keyless request from one IP with 429", async () => {
+    app = signUpApp();
+    await app.ready();
+    const codes = await statuses(11, { "x-forwarded-for": WEB_EGRESS });
+    expect(codes.slice(0, 10).every((code) => code === 200)).toBe(true);
+    expect(codes[10]).toBe(429);
+    expect(verify).not.toHaveBeenCalled();
+  });
+
+  it("keeps an invalid key on the per-IP 10 a minute", async () => {
+    app = signUpApp();
+    await app.ready();
+    const codes = await statuses(11, keyed(WEB_EGRESS, "ailk_spk_forged"));
+    expect(codes.slice(0, 10).every((code) => code === 200)).toBe(true);
+    expect(codes[10]).toBe(429);
+  });
+
+  it("an anonymous caller spoofing the web's X-Forwarded-For cannot spend the keyed budget", async () => {
+    app = signUpApp();
+    await app.ready();
+    // The spoofer fills the per-IP bucket of the web's own egress address…
+    const spoofed = await statuses(30, { "x-forwarded-for": WEB_EGRESS });
+    expect(spoofed[10]).toBe(429);
+    // …and with a forged key too.
+    await statuses(30, keyed(WEB_EGRESS, "ailk_spk_forged"));
+    // The keyed caller behind that address still has its whole budget.
+    const codes = await statuses(25, keyed());
+    expect(codes.every((code) => code === 200)).toBe(true);
+  });
+
+  it("many web instances behind one egress share the key bucket, not an IP bucket", async () => {
+    app = signUpApp();
+    await app.ready();
+    const codes: number[] = [];
+    for (let i = 0; i < 26; i++) {
+      codes.push(...(await statuses(1, keyed(`203.0.113.${i + 1}`))));
+    }
+    expect(codes.slice(0, 25).every((code) => code === 200)).toBe(true);
+    expect(codes[25]).toBe(429);
+  });
+
+  it("a verification failure counts the request per IP, never unlimited", async () => {
+    verify.mockRejectedValue(new Error("db down: postgres://secret"));
+    app = signUpApp();
+    await app.ready();
+    const codes = await statuses(11, keyed());
+    expect(codes[10]).toBe(429);
+    const line = logLines.find(
+      (l) => l["event"] === "rate_limit_site_key_unverified",
+    );
+    expect(line).toBeDefined();
+    expect(JSON.stringify(logLines)).not.toContain("postgres://secret");
+    expect(JSON.stringify(logLines)).not.toContain(VALID);
+  });
+
+  it("a lookup that outlasts its timeout counts the request per IP", async () => {
+    verify.mockImplementation(() => new Promise<string | null>(() => undefined));
+    app = signUpApp({ siteKeyOf: siteKeyReader(verify, 5) });
+    await app.ready();
+    const codes = await statuses(11, keyed());
+    expect(codes.slice(0, 10).every((code) => code === 200)).toBe(true);
+    expect(codes[10]).toBe(429);
+    expect(
+      logLines.some((l) => l["event"] === "rate_limit_site_key_unverified"),
+    ).toBe(true);
+  });
+
+  it("ignores a key on any route but the sign-up evidence read", async () => {
+    app = signUpApp();
+    await app.ready();
+    const codes = await statuses(11, keyed(), "/v1/other");
+    expect(codes[10]).toBe(429);
+    expect(verify).not.toHaveBeenCalled();
+  });
+
+  it("verifies the key once per request, however many limiters read it", async () => {
+    const reader = siteKeyReader(verify);
+    app = signUpApp({ siteKeyOf: reader });
+    // A second reader of the same request, as the server-wide limiter is.
+    app.addHook("onRequest", async (req) => {
+      await reader(req);
+    });
+    await app.ready();
+    await statuses(3, keyed());
+    expect(verify).toHaveBeenCalledTimes(3);
+  });
+
+  it("reads AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE over the code value", async () => {
+    process.env.AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE = "12";
+    app = signUpApp();
+    await app.ready();
+    const codes = await statuses(13, keyed());
+    expect(codes.slice(0, 12).every((code) => code === 200)).toBe(true);
+    expect(codes[12]).toBe(429);
+  });
+
+  it("logs a keyed 429 with bucket site and the spoke id, never the key", async () => {
+    app = signUpApp({ perKeyPerMinute: 1 });
+    await app.ready();
+    await statuses(2, keyed());
+    const line = logLines.find((l) => l["msg"] === "rate_limited");
+    expect(line).toMatchObject({
+      ip: `site,${SPOKE_ID}`,
+      bucket: "site",
+    });
+    expect(JSON.stringify(logLines)).not.toContain(VALID);
+  });
+
+  it("rejects siteKeyOf without a scope", async () => {
+    app = signUpApp({ scope: undefined });
+    await expect(app.ready()).rejects.toThrow(/scope/);
+  });
+});

package/templates/apps/api/src/middleware/__tests__/write-budget.test.ts

@@ -0,0 +1,174 @@
+/**
+ * @file write-budget.test.ts
+ * @description The Stripe connection write budget (#8907 D9, AC-12; contract
+ * K10) — `chargeWriteBudget` in middleware/rate-limit.ts.
+ *
+ * It counts every write against an hourly per-Organization and per-person
+ * bucket in its OWN database store — never the process default — so neither
+ * `AILK_RATE_LIMIT_STORE=memory` nor the per-minute sweep of the shared maps
+ * can reset an hourly bucket (SEC-8907-2). A store that rejects falls back to
+ * a module-private count the sweep never touches, capped at `MAX_BUCKETS`.
+ */
+import Fastify from "fastify";
+
+import type { RateLimitBucket, RateLimitStore } from "../../lib/rate-limit-store.js";
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary; the budget's store is replaced below, so no client is ever built.
+jest.mock("../../lib/prisma.js", () => ({ prisma: {} }));
+
+const mockCreateDatabaseStore = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- the database store's constructor is the seam the case under test is about: the budget must build its own database store whatever AILK_RATE_LIMIT_STORE says
+jest.mock("../../lib/rate-limit-store.js", () => ({
+  ...jest.requireActual("../../lib/rate-limit-store.js"),
+  createDatabaseRateLimitStore: (...args: unknown[]) => mockCreateDatabaseStore(...args),
+}));
+
+import {
+  __bucketCount,
+  __resetBuckets,
+  __setWriteBudgetStoreForTests,
+  __writeBudgetFallbackCount,
+  chargeWriteBudget,
+  MAX_BUCKETS,
+  rateLimitMiddleware,
+  STRIPE_CONNECTION_WRITES_PER_ORG_PER_HOUR,
+  STRIPE_CONNECTION_WRITES_PER_USER_PER_HOUR,
+} from "../rate-limit.js";
+
+const HOUR = 60 * 60 * 1000;
+const T0 = 1_800_000_000_000;
+
+/** A `hitKey` that counts per key and window, as the database store's upsert does. */
+function countingStore(): RateLimitStore & { hitKey: jest.Mock; keys: Map<string, RateLimitBucket> } {
+  const keys = new Map<string, RateLimitBucket>();
+  const hitKey = jest.fn(async (key: string, now: number, windowMs: number) => {
+    let bucket = keys.get(key);
+    if (!bucket || now - bucket.windowStartMs >= windowMs) {
+      bucket = { count: 0, windowStartMs: now };
+      keys.set(key, bucket);
+    }
+    bucket.count += 1;
+    return { ...bucket };
+  });
+  return {
+    keys,
+    hitKey,
+    hit: jest.fn(),
+    hasOpenWindow: jest.fn(),
+    sweep: jest.fn(),
+  };
+}
+
+function rejectingStore(): RateLimitStore {
+  return {
+    hitKey: jest.fn().mockRejectedValue(new Error("db down")),
+    hit: jest.fn(),
+    hasOpenWindow: jest.fn(),
+    sweep: jest.fn(),
+  };
+}
+
+const charge = (key: string, now: number, limit = STRIPE_CONNECTION_WRITES_PER_ORG_PER_HOUR) =>
+  chargeWriteBudget({ scope: "stripeconn", charges: [{ key, limit }], windowMs: HOUR, now });
+
+beforeEach(() => {
+  __resetBuckets();
+  mockCreateDatabaseStore.mockReset();
+});
+
+afterAll(() => __setWriteBudgetStoreForTests(undefined));
+
+describe("chargeWriteBudget (#8907 D9)", () => {
+  it("answers ok ten times for one Organization, refuses the eleventh, and opens again an hour later", async () => {
+    __setWriteBudgetStoreForTests(countingStore());
+    for (let i = 0; i < 10; i++) {
+      expect(await charge("org,org_a", T0 + i * 1000)).toEqual({ ok: true });
+    }
+    const refused = await charge("org,org_a", T0 + 10_000);
+    expect(refused.ok).toBe(false);
+    if (refused.ok) throw new Error("expected a refusal");
+    expect(refused.retryAfterSeconds).toBeGreaterThanOrEqual(1);
+    expect(refused.retryAfterSeconds).toBeLessThanOrEqual(3600);
+    expect(await charge("org,org_a", T0 + HOUR)).toEqual({ ok: true });
+  });
+
+  it("counts a person's key independently, at its own limit", async () => {
+    __setWriteBudgetStoreForTests(countingStore());
+    for (let i = 0; i < 11; i++) await charge("org,org_a", T0 + i);
+    for (let i = 0; i < STRIPE_CONNECTION_WRITES_PER_USER_PER_HOUR; i++) {
+      expect(await charge("user,user_a", T0 + i, STRIPE_CONNECTION_WRITES_PER_USER_PER_HOUR)).toEqual({
+        ok: true,
+      });
+    }
+    expect((await charge("user,user_a", T0 + 30, STRIPE_CONNECTION_WRITES_PER_USER_PER_HOUR)).ok).toBe(
+      false,
+    );
+  });
+
+  it("refuses when any charge is over, and counts every charge every time", async () => {
+    const store = countingStore();
+    __setWriteBudgetStoreForTests(store);
+    const both = (now: number) =>
+      chargeWriteBudget({
+        scope: "stripeconn",
+        charges: [
+          { key: "org,org_a", limit: 10 },
+          { key: "user,user_a", limit: 20 },
+        ],
+        windowMs: HOUR,
+        now,
+      });
+    for (let i = 0; i < 10; i++) expect((await both(T0 + i)).ok).toBe(true);
+    expect((await both(T0 + 10)).ok).toBe(false);
+    expect(store.keys.get("writebudget:stripeconn|org,org_a")?.count).toBe(11);
+    expect(store.keys.get("writebudget:stripeconn|user,user_a")?.count).toBe(11);
+  });
+
+  it("is not reset by the middleware's per-minute sweep of its shared maps", async () => {
+    // A rejecting store sends every count to the fallback, the one state a
+    // shared-map sweep could reach if the budget lived there.
+    __setWriteBudgetStoreForTests(rejectingStore());
+    const past = Date.now() - 30 * 60 * 1000;
+    for (let i = 0; i < 10; i++) expect((await charge("org,org_b", past)).ok).toBe(true);
+
+    const app = Fastify();
+    await app.register(rateLimitMiddleware, { windowMs: 60_000, perIpPerMinute: 1_000 });
+    app.get("/ping", async () => ({ ok: true }));
+    await app.ready();
+    // 101 requests reach the interval sweep (`evictStaleBuckets`) at least once.
+    for (let i = 0; i < 101; i++) await app.inject({ method: "GET", url: "/ping" });
+    await app.close();
+
+    expect((await charge("org,org_b", past)).ok).toBe(false);
+  });
+
+  it("falls back to a private count capped at MAX_BUCKETS when the store rejects", async () => {
+    __setWriteBudgetStoreForTests(rejectingStore());
+    for (let i = 0; i < MAX_BUCKETS + 5; i++) await charge(`org,org_${i}`, T0);
+    expect(__writeBudgetFallbackCount()).toBe(MAX_BUCKETS);
+    // The newest entry survived the cap, the oldest did not.
+    for (let i = 0; i < 10; i++) await charge(`org,org_${MAX_BUCKETS + 4}`, T0);
+    expect((await charge(`org,org_${MAX_BUCKETS + 4}`, T0)).ok).toBe(false);
+    expect((await charge("org,org_0", T0)).ok).toBe(true);
+  });
+
+  it("uses its own database store even with AILK_RATE_LIMIT_STORE=memory, and never the shared maps", async () => {
+    const before = { DATABASE_URL: process.env.DATABASE_URL, STORE: process.env.AILK_RATE_LIMIT_STORE };
+    process.env.DATABASE_URL = "postgres://budget.invalid/db";
+    process.env.AILK_RATE_LIMIT_STORE = "memory";
+    try {
+      const store = countingStore();
+      mockCreateDatabaseStore.mockReturnValue(store);
+      __setWriteBudgetStoreForTests(undefined);
+      expect((await charge("org,org_c", T0)).ok).toBe(true);
+      expect(mockCreateDatabaseStore).toHaveBeenCalledTimes(1);
+      expect(store.hitKey).toHaveBeenCalledWith("writebudget:stripeconn|org,org_c", T0, HOUR);
+      expect(__bucketCount()).toBe(0);
+    } finally {
+      process.env.DATABASE_URL = before.DATABASE_URL;
+      process.env.AILK_RATE_LIMIT_STORE = before.STORE;
+      if (before.DATABASE_URL === undefined) delete process.env.DATABASE_URL;
+      if (before.STORE === undefined) delete process.env.AILK_RATE_LIMIT_STORE;
+    }
+  });
+});