create-ailk 0.22.0 → 0.23.0

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

@@ -65,7 +65,8 @@
  * (#7644) — `GET /v1/schedule/availability` and `POST /v1/schedule/book` — and
  * since #7479 the three listing-draft calls a spoke makes for its applicant
  * (`POST /v1/project-listings`, `PATCH /v1/project-listings/drafts/:id`,
- * `POST /v1/project-listings/drafts/:id/submit`). The global limiter (`server.ts`) passes the hub's digests, so a listed call is
+ * `POST /v1/project-listings/drafts/:id/submit`), and since #8848 the open
+ * file read (`GET /v1/deliverables/open/:slug`). The global limiter (`server.ts`) passes the hub's digests, so a listed call is
  * counted per visitor there; a scope's own limiter does so only when its
  * registration passes `trustedKeyDigests` too, as the leads and schedule
  * scopes do. A believed visitor is
@@ -76,6 +77,21 @@
  * request keys on `req.ip`, as before. Spec:
  * docs/specs/7394-the-leads-rate-limit-scope-spec.md.
  *
+ * Per-site-key sign-up evidence (#8805): the web's server reads
+ * `GET /v1/consent/sign-up` on every sign-up, and every web instance behind
+ * one egress address shared one per-IP bucket, which an anonymous caller
+ * spoofing that address's `X-Forwarded-For` could fill. A registration that
+ * passes `siteKeyOf` (built by `siteKeyReader`) counts a request on one of
+ * the `SITE_KEYED_ROUTES` that presents a VERIFIED site key
+ * (`x-ailk-spoke-key`, the key the web's api-client already sends) against
+ * that key's own `site,<spokeId>` bucket and the scope's per-key ceiling
+ * only — never an IP bucket. No other identity starts with `site,` (`req.ip`
+ * holds no comma, a forwarded visitor is `v<n>,<ip>`), so no unkeyed caller
+ * can reach it. An invalid or absent key, or a verification that fails or
+ * outlasts `SITE_KEY_TIMEOUT_MS`, is counted on `req.ip` as before. The key changes
+ * the request's rate-limit identity and nothing else: the route still serves
+ * the deployment's own site workspace.
+ *
  * Scope namespace and env limit (#7394): a registration with a `scope` keys
  * its buckets as `<scope>|<identity>`, so its count is not shared with any
  * other registration, and reads its limits from
@@ -146,6 +162,13 @@ export type RateLimitOptions = {
    * visitors (#7394). Default: 300.
    */
   perKeyPerMinute?: number;
+  /**
+   * The verified site key a request presents, as its spoke id, or `null`
+   * (#8805). Build it with `siteKeyReader`. A request it names is counted
+   * against `<scope>|site,<spokeId>` and `perKeyPerMinute` only, never an IP
+   * bucket. Needs a `scope`.
+   */
+  siteKeyOf?: (req: FastifyRequest) => Promise<string | null>;
   /**
    * Override the process-default store (#5040 D4). Test-only, like
    * `maxBuckets` — no production caller overrides this.
@@ -181,6 +204,14 @@ export const MAX_BUCKETS = 10_000;
  */
 export const DEFAULT_SCHEDULE_PER_KEY_PER_MINUTE = 60;
 
+/**
+ * The sign-up evidence read's per-site-key ceiling (#8805). The web's cache
+ * keeps each instance to about one read a minute per enabled locale, so this
+ * covers many instances of one site at once.
+ * `AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE` overrides it.
+ */
+export const DEFAULT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE = 120;
+
 /**
  * How long a database-store call may run before the middleware falls back to
  * the memory store for that request (#5040 D5). `RateLimitOptions.storeTimeoutMs`
@@ -218,8 +249,75 @@ export const FORWARDED_VISITOR_ROUTES: readonly Readonly<{
   { method: "POST", url: "/v1/project-listings" },
   { method: "PATCH", url: "/v1/project-listings/drafts/:id" },
   { method: "POST", url: "/v1/project-listings/drafts/:id/submit" },
+  // #8848 D5 — an ungated file's bytes, which a site's own route handler
+  // reads for its visitor (`/reports/<slug>/file`), in `deliverableopen`.
+  { method: "GET", url: "/v1/deliverables/open/:slug" },
 ];
 
+/**
+ * The only (method, route) pairs on which a verified site key is the
+ * caller's rate-limit identity (#8805): the sign-up agreements' evidence read.
+ */
+export const SITE_KEYED_ROUTES: readonly Readonly<{
+  method: "GET";
+  url: string;
+}>[] = [{ method: "GET", url: "/v1/consent/sign-up" }];
+
+/**
+ * A verified site key's identity prefix. No other identity starts with it:
+ * `req.ip` never holds a comma, and a forwarded visitor is `v<n>,<ip>`.
+ */
+export const SITE_KEY_IDENTITY_PREFIX = "site,";
+
+/**
+ * How long a site-key lookup may run before the request is counted per IP
+ * instead (#8805) — the store's own bound (#5040 D5).
+ */
+export const SITE_KEY_TIMEOUT_MS = 1_000;
+
+const SITE_KEY_HEADER = "x-ailk-spoke-key";
+
+/**
+ * The `siteKeyOf` reader (#8805). `verify` turns a request's site key into
+ * its spoke id, or `null` for a key that is not a registered, unrevoked one;
+ * it is called only for a request on one of the `SITE_KEYED_ROUTES` that
+ * carries a non-empty `x-ailk-spoke-key`, and at most once per request, so
+ * the global limiter and the scope's own share one lookup. A `verify` that
+ * throws, or has not answered within `timeoutMs`, reads as `null` — the
+ * request is counted per IP, never unlimited — and logs the error's name only.
+ */
+export function siteKeyReader(
+  verify: (req: FastifyRequest) => Promise<string | null>,
+  timeoutMs: number = SITE_KEY_TIMEOUT_MS,
+): (req: FastifyRequest) => Promise<string | null> {
+  const verified = new WeakMap<FastifyRequest, Promise<string | null>>();
+  return (req) => {
+    const url = req.routeOptions.url ?? "";
+    const listed = SITE_KEYED_ROUTES.some(
+      (route) => route.method === req.method && route.url === url,
+    );
+    const presented = req.headers[SITE_KEY_HEADER];
+    if (!listed || typeof presented !== "string" || presented.trim() === "") {
+      return Promise.resolve(null);
+    }
+    let pending = verified.get(req);
+    if (pending === undefined) {
+      pending = withTimeout(verify(req), timeoutMs).catch((err: unknown) => {
+        req.log.warn(
+          {
+            event: "rate_limit_site_key_unverified",
+            err: err instanceof Error ? err.name : "unknown",
+          },
+          "rate_limit_site_key_unverified",
+        );
+        return null;
+      });
+      verified.set(req, pending);
+    }
+    return pending;
+  };
+}
+
 const VISITOR_IP_HEADER = "x-ailk-visitor-ip";
 const FORWARD_KEY_HEADER = "x-ailk-visitor-forward-key";
 const MIN_FORWARD_KEY_LENGTH = 32;
@@ -593,6 +691,10 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
     done(new Error("rate-limit trustedKeyDigests needs a scope"));
     return;
   }
+  if (opts.siteKeyOf !== undefined && scope === undefined) {
+    done(new Error("rate-limit siteKeyOf needs a scope"));
+    return;
+  }
 
   const warn = (msg: string) => fastify.log.warn(msg);
   const perIpPerMinute = resolveScopedLimit(
@@ -608,7 +710,7 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
     opts.perKeyPerMinute ?? DEFAULT_PER_KEY_PER_MINUTE,
     warn,
   );
-  const { ipFromRequest } = opts;
+  const { ipFromRequest, siteKeyOf } = opts;
   const identityOf: (req: FastifyRequest) => {
     identity: string;
     keyIndex: number | null;
@@ -631,6 +733,7 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
     activeStore: RateLimitStore,
     ip: string,
     keyIndex: number | null,
+    siteId: string | null,
     now: number,
     sweepOnInterval: boolean,
   ): Promise<{
@@ -642,6 +745,23 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
       await activeStore.sweep(now, windowMs, "interval");
     }
 
+    // #8805: a verified site key is counted against its own bucket and the
+    // per-key ceiling only — no IP bucket is read or opened.
+    if (siteId !== null) {
+      const siteBucket = await activeStore.hitKey(
+        bucketKey(`${SITE_KEY_IDENTITY_PREFIX}${siteId}`),
+        now,
+        windowMs,
+      );
+      const siteOver = siteBucket.count > perKeyPerMinute;
+      if (siteOver) await activeStore.sweep(now, windowMs, "limited");
+      return {
+        tripped: siteOver ? siteBucket : undefined,
+        visitorOver: false,
+        keyOver: siteOver,
+      };
+    }
+
     // #7394 DD-8: a keyed request also counts against its key's own
     // bucket, even when the visitor bucket is already over its limit.
     const keyBucket =
@@ -675,7 +795,11 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
     "onRequest",
     async (req: FastifyRequest, reply: FastifyReply) => {
       const now = getClock().now();
-      const { identity: ip, keyIndex } = identityOf(req);
+      const siteId = siteKeyOf ? await siteKeyOf(req) : null;
+      const { identity: ip, keyIndex } =
+        siteId === null
+          ? identityOf(req)
+          : { identity: `${SITE_KEY_IDENTITY_PREFIX}${siteId}`, keyIndex: null };
 
       requestsSinceLastClean += 1;
       const sweepOnInterval = requestsSinceLastClean >= CLEAN_INTERVAL_REQUESTS;
@@ -697,7 +821,7 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
       };
       try {
         outcome = await withTimeout(
-          countRequest(primaryStore, ip, keyIndex, now, sweepOnInterval),
+          countRequest(primaryStore, ip, keyIndex, siteId, now, sweepOnInterval),
           storeTimeoutMs,
         );
       } catch (err) {
@@ -710,6 +834,7 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
           fallbackStore,
           ip,
           keyIndex,
+          siteId,
           now,
           sweepOnInterval,
         );
@@ -730,6 +855,7 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
         const pathOnly = req.url.split("?")[0] ?? req.url;
         // A keyed 429 names the bucket that tripped and the key's position,
         // so a misused key can be traced to its spoke; never the key itself.
+        // A site-keyed 429 (#8805) names `bucket: "site"` and the spoke id.
         req.log.warn(
           {
             ip,
@@ -739,6 +865,7 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
               bucket: visitorOver ? "visitor" : "key",
               keyIndex,
             }),
+            ...(siteId !== null && { bucket: "site" }),
           },
           RATE_LIMITED,
         );
@@ -759,3 +886,98 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
 (rateLimitMiddleware as FastifyPluginCallback & { [key: symbol]: boolean })[
   Symbol.for("skip-override")
 ] = true;
+
+// ─── The Stripe connection write budget (#8907 D9, contract K10) ────────────
+
+/** One Organization's connection writes in an hour (K10). */
+export const STRIPE_CONNECTION_WRITES_PER_ORG_PER_HOUR = 10;
+/** One person's connection writes in an hour, across Organizations (K10). */
+export const STRIPE_CONNECTION_WRITES_PER_USER_PER_HOUR = 20;
+
+/** One bucket a write is counted against: `org,<id>` or `user,<id>`. */
+export type WriteBudgetCharge = { key: string; limit: number };
+
+export type WriteBudgetResult = { ok: true } | { ok: false; retryAfterSeconds: number };
+
+/**
+ * The budget's own database store (D9, SEC-8907-2) — never the process
+ * default, so `AILK_RATE_LIMIT_STORE=memory` can never send an hourly bucket
+ * into the shared `keyBuckets` map a per-minute sweep clears. Each database
+ * row keeps its own `window_ms`, so no sweep shortens it.
+ */
+let writeBudgetStore: RateLimitStore | undefined;
+
+/**
+ * Where a request is counted while the database store rejects or times out.
+ * Module-private and never touched by `evictStaleBuckets`; capped at
+ * `MAX_BUCKETS`, the oldest entry dropped first, and an entry replaced only
+ * once its own window has ended. Per instance while the database is
+ * degraded — the residual SEC-8907-15 accepts.
+ */
+const writeBudgetFallback = new Map<string, RateLimitBucket>();
+
+function fallbackHit(key: string, now: number, windowMs: number): RateLimitBucket {
+  let bucket = writeBudgetFallback.get(key);
+  if (!bucket || now - bucket.windowStartMs >= windowMs) {
+    writeBudgetFallback.delete(key);
+    if (writeBudgetFallback.size >= MAX_BUCKETS) {
+      const oldestKey = writeBudgetFallback.keys().next().value;
+      if (oldestKey !== undefined) writeBudgetFallback.delete(oldestKey);
+    }
+    bucket = { count: 0, windowStartMs: now };
+    writeBudgetFallback.set(key, bucket);
+  }
+  bucket.count += 1;
+  return bucket;
+}
+
+/**
+ * Count one write against every charge's bucket and answer whether all of
+ * them are still within their limit (D9). Every call counts — a refused key
+ * costs a write too, so the probes are never a key-validity oracle. On a
+ * refusal, `retryAfterSeconds` is the latest window end among the refusing
+ * buckets, at least 1.
+ */
+export async function chargeWriteBudget(input: {
+  scope: string;
+  charges: readonly WriteBudgetCharge[];
+  windowMs: number;
+  now: number;
+  warn?: (obj: Record<string, unknown>, msg: string) => void;
+}): Promise<WriteBudgetResult> {
+  const { scope, charges, windowMs, now } = input;
+  writeBudgetStore ??= createDatabaseRateLimitStore(prisma);
+  const activeStore = writeBudgetStore;
+
+  let retryAfterSeconds = 0;
+  for (const charge of charges) {
+    const key = `writebudget:${scope}|${charge.key}`;
+    let bucket: RateLimitBucket;
+    try {
+      bucket = await withTimeout(activeStore.hitKey(key, now, windowMs), STORE_TIMEOUT_MS);
+    } catch (err) {
+      warnFallback(
+        input.warn ?? (() => undefined),
+        now,
+        err instanceof RateLimitStoreTimeoutError ? "timeout" : "error",
+      );
+      bucket = fallbackHit(key, now, windowMs);
+    }
+    if (bucket.count > charge.limit) {
+      const endsInMs = bucket.windowStartMs + windowMs - now;
+      retryAfterSeconds = Math.max(retryAfterSeconds, Math.ceil(endsInMs / 1000), 1);
+    }
+  }
+  return retryAfterSeconds > 0 ? { ok: false, retryAfterSeconds } : { ok: true };
+}
+
+/** Test-only: replace the budget's store, as the middleware's `store` option does for a registration. */
+export function __setWriteBudgetStoreForTests(store: RateLimitStore | undefined): void {
+  writeBudgetStore = store;
+  writeBudgetFallback.clear();
+}
+
+/** Test-only: the fallback map's size. */
+export function __writeBudgetFallbackCount(): number {
+  return writeBudgetFallback.size;
+}

package/templates/apps/api/src/openapi/spec.ts

@@ -758,12 +758,14 @@ export function buildOpenApiSpec(
             "lead's id with a 201; with anything different it is a 422. Keys are " +
             "scoped per workspace, are first-write-wins, and should be unguessable " +
             "(a UUID, a Stripe Checkout Session id). Without a database there is no " +
-            "stored lead to match, so the key has no effect. A contact lead — " +
-            "`source` `contact-form`, `conversational-intake` or `flow:contact` — " +
-            "must carry `consent: true` (the visitor accepted the site's terms), " +
+            "stored lead to match, so the key has no effect. A consent-bearing lead — " +
+            "`source` `contact-form`, `conversational-intake`, `flow:contact` or " +
+            "`flow:job-application` — must carry `consent: true` (the visitor " +
+            "accepted the site's terms), " +
             "else it is a 400 `consent_required`; the server then records " +
             "`payload.consent` (`statement`, `acceptedAt`) itself, replacing any the " +
-            "caller sent. Other sources do not read `consent`.",
+            "caller sent, and leaves it out of the Idempotency-Key replay " +
+            "comparison. Other sources do not read `consent`.",
           parameters: [
             {
               name: "Idempotency-Key",
@@ -795,8 +797,8 @@ export function buildOpenApiSpec(
             "400": {
               description:
                 "Validation error — invalid request body, or a malformed " +
-                "Idempotency-Key; or `consent_required`, a contact lead without " +
-                "`consent: true`",
+                "Idempotency-Key; or `consent_required`, a consent-bearing lead " +
+                "(a contact lead or a job application) without `consent: true`",
               content: {
                 "application/json": {
                   schema: {
@@ -1488,7 +1490,8 @@ export function buildOpenApiSpec(
               type: "boolean",
               description:
                 "`true` when the visitor accepted the site's terms. Required (as " +
-                "`true`) for a contact lead; read for no other source, and never " +
+                "`true`) for a consent-bearing lead — a contact lead or a job " +
+                "application; read for no other source, and never " +
                 "stored as sent — the server records `payload.consent` instead.",
             },
             payload: {