create-ailk 0.22.0 → 0.24.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/__tests__/openapi.test.ts

@@ -3,6 +3,7 @@
  * GET /api/openapi.json — OpenAPI 3.x spec describing the public content API.
  */
 import { openapiRoutes } from "../index";
+import { buildOpenApiSpec } from "../spec";
 
 describe("GET /api/openapi.json", () => {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #506/#507: pre-existing test-hygiene violation
@@ -54,6 +55,132 @@ describe("GET /api/openapi.json", () => {
     );
   });
 
+  // #9285 AC-3 — the Stripe connection read's three answers are documented, and
+  // only on a build that registers the billing routes (multi-tenant).
+  describe("Inbox message and Person record reads (#9349 DD8, AC-10)", () => {
+    const PRIOR_ENABLED_MODULES = process.env.AILK_ENABLED_MODULES;
+    const LIST_PATH = "/v1/workspaces/{workspaceId}/messages";
+    const ITEM_PATH = "/v1/workspaces/{workspaceId}/messages/{leadId}";
+    const PERSON_PATH = "/v1/workspaces/{workspaceId}/people/{personId}";
+
+    afterEach(() => {
+      if (PRIOR_ENABLED_MODULES === undefined) {
+        delete process.env.AILK_ENABLED_MODULES;
+      } else {
+        process.env.AILK_ENABLED_MODULES = PRIOR_ENABLED_MODULES;
+      }
+    });
+
+    const dataRef = (op: { responses: Record<string, unknown> }) =>
+      (op.responses["200"] as {
+        content: {
+          "application/json": { schema: { properties: { data: { $ref: string } } } };
+        };
+      }).content["application/json"].schema.properties.data.$ref;
+
+    it("documents the two message GETs and the Person record on a multi-tenant build", async () => {
+      process.env.AILK_ENABLED_MODULES = "multi-tenant";
+      const spec = JSON.parse(
+        (await app.inject({ method: "GET", url: "/v1/openapi.json" })).body,
+      );
+
+      expect(spec.paths[LIST_PATH].get.operationId).toBe("listInboxMessages");
+      expect(dataRef(spec.paths[LIST_PATH].get)).toBe("#/components/schemas/InboxMessageList");
+      expect(spec.paths[ITEM_PATH].get.operationId).toBe("getInboxMessage");
+      expect(dataRef(spec.paths[ITEM_PATH].get)).toBe("#/components/schemas/InboxMessage");
+      expect(spec.paths[PERSON_PATH].get.operationId).toBe("getPersonRecord");
+      expect(dataRef(spec.paths[PERSON_PATH].get)).toBe("#/components/schemas/PersonRecord");
+
+      const message = spec.components.schemas.InboxMessage;
+      expect(Object.keys(message.properties).sort()).toEqual([
+        "body",
+        "createdAt",
+        "email",
+        "excerpt",
+        "handledAt",
+        "id",
+        "name",
+        "personId",
+        "source",
+      ]);
+      expect(message.additionalProperties).toBe(false);
+      expect(
+        Object.keys(spec.components.schemas.PersonRecord.properties.person.properties),
+      ).toContain("stripeCustomerUrl");
+    });
+
+    it("the PATCH on the item path stays the derived operation beside the hand-authored GET", () => {
+      process.env.AILK_ENABLED_MODULES = "multi-tenant";
+      const url = "/v1/workspaces/:workspaceId/messages/:leadId";
+      const spec = buildOpenApiSpec({}, [
+        { method: "GET", url },
+        { method: "PATCH", url },
+      ]);
+      const item = spec.paths[ITEM_PATH] as Record<
+        string,
+        { operationId: string; description: string }
+      >;
+      expect(item.get!.operationId).toBe("getInboxMessage");
+      expect(item.patch!.description).toContain(
+        "Derived from this deployment's route table",
+      );
+    });
+
+    it("advertises none of the three where the routes do not register", async () => {
+      process.env.AILK_ENABLED_MODULES = "commerce";
+      const spec = JSON.parse(
+        (await app.inject({ method: "GET", url: "/v1/openapi.json" })).body,
+      );
+      for (const path of [LIST_PATH, ITEM_PATH, PERSON_PATH]) {
+        expect(spec.paths[path]).toBeUndefined();
+      }
+    });
+  });
+
+  describe("stripe-connection read (#9285)", () => {
+    const PRIOR_ENABLED_MODULES = process.env.AILK_ENABLED_MODULES;
+
+    afterEach(() => {
+      if (PRIOR_ENABLED_MODULES === undefined) {
+        delete process.env.AILK_ENABLED_MODULES;
+      } else {
+        process.env.AILK_ENABLED_MODULES = PRIOR_ENABLED_MODULES;
+      }
+    });
+
+    it("documents the stored view, the environment source and null on a multi-tenant build", async () => {
+      process.env.AILK_ENABLED_MODULES = "multi-tenant";
+      const res = await app.inject({ method: "GET", url: "/v1/openapi.json" });
+      const spec = JSON.parse(res.body);
+
+      const get = spec.paths["/v1/billing/stripe-connection"].get;
+      expect(get.operationId).toBe("getStripeConnection");
+      expect(get.responses["200"].content["application/json"].schema.$ref).toBe(
+        "#/components/schemas/StripeConnectionReadResponse",
+      );
+
+      const { data } = spec.components.schemas.StripeConnectionReadResponse.properties;
+      expect(data.nullable).toBe(true);
+      expect(data.oneOf).toEqual([
+        { $ref: "#/components/schemas/StripeConnectionView" },
+        { $ref: "#/components/schemas/StripeEnvironmentSource" },
+      ]);
+
+      // The environment source carries the mode and nothing else.
+      const env = spec.components.schemas.StripeEnvironmentSource;
+      expect(Object.keys(env.properties).sort()).toEqual(["mode", "source"]);
+      expect(env.properties.source.enum).toEqual(["environment"]);
+      expect(env.additionalProperties).toBe(false);
+    });
+
+    it("does not advertise it where the billing routes do not register", async () => {
+      process.env.AILK_ENABLED_MODULES = "commerce";
+      const res = await app.inject({ method: "GET", url: "/v1/openapi.json" });
+      const spec = JSON.parse(res.body);
+      expect(spec.paths["/v1/billing/stripe-connection"]).toBeUndefined();
+    });
+  });
+
   // The checkout path's OpenAPI documentation is module-conditional (commerce,
   // D-47 / #5364) — mirroring the route's own registration gate in server.ts —
   // so these two assertions need the module enabled, exactly as a real