create-ailk 0.19.1 → 0.21.0

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

@@ -1,13 +1,22 @@
 /**
  * Per-IP rate limit middleware for anonymous write routes.
  *
- * SINGLE-REPLICA CAVEAT: This module uses an in-process Map to store request
- * counts. Each Fastify instance maintains its own bucket state. In a
- * multi-replica deployment (e.g. 3 Vercel functions), an attacker can issue
- * up to N × perIpPerMinute requests per minute per IP, where N is the replica
- * count. For OSS v1 (single-replica), this is acceptable. A Redis-backed swap
- * is tracked in the follow-up issue "Phase 6+ — Redis-backed rate limit for
- * multi-replica deploys."
+ * SINGLE-REPLICA CAVEAT: the memory store below keeps an in-process Map of
+ * request counts. Each Fastify instance maintains its own bucket state. On a
+ * deployment with no database (or `AILK_RATE_LIMIT_STORE=memory`), an
+ * attacker can issue up to N × perIpPerMinute requests per minute per IP,
+ * where N is the replica/isolate count.
+ *
+ * SHARED STORE (#5040): on a deployment with a database, every registration
+ * defaults to counting in `rate_limit_counters` instead (D4), so one
+ * visitor's limit holds across every concurrent isolate. See
+ * `apps/api/src/lib/rate-limit-store.ts` for the store seam and
+ * `docs/specs/5040-the-api-s-rate-limiter-spec.md` D11 for the full list of
+ * what this protects against and what it does not — in short: it stops one
+ * identity from exceeding its ceiling by spreading requests over isolates,
+ * but a caller that mints a fresh identity per request (a forged
+ * `x-forwarded-for` the edge passes through unmodified) still gets a fresh
+ * bucket every time, in either store.
  *
  * Cleanup strategy: evict stale buckets on every 429 emission and every 100
  * allowed requests (bounded, O(n) over bucket count — negligible for typical
@@ -23,7 +32,9 @@
  * caps total entries independent of the time-based eviction: once at
  * capacity, a genuinely new identity evicts the single oldest-inserted entry
  * (`Map` iteration order is insertion order) before inserting itself — O(1)
- * amortized, no behavior change for any caller under the cap.
+ * amortized, no behavior change for any caller under the cap. The database
+ * store has no such cap: it relies entirely on the sweep (D6) to bound its
+ * row count.
  *
  * Trust-proxy boundary: this middleware reads req.ip, which Fastify populates
  * from the socket address and any trusted proxy headers (X-Forwarded-For) per
@@ -51,8 +62,10 @@
  * believes only alongside a hub-issued key in `x-ailk-visitor-forward-key`,
  * and only on the `FORWARDED_VISITOR_ROUTES`: the three lead writes, and
  * since #7633 the two schedule calls a site's same-origin relay forwards
- * (#7644) — `GET /v1/schedule/availability` and `POST /v1/schedule/book`. The
- * global limiter (`server.ts`) passes the hub's digests, so a listed call is
+ * (#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
  * 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
@@ -78,8 +91,17 @@ import type {
   FastifyRequest,
   FastifyReply,
   FastifyPluginCallback,
+  FastifyBaseLogger,
 } from "fastify";
 
+import { prisma } from "../lib/prisma.js";
+import {
+  createDatabaseRateLimitStore,
+  resolveRateLimitStoreKind,
+  type RateLimitBucket,
+  type RateLimitStore,
+} from "../lib/rate-limit-store.js";
+
 export type RateLimitOptions = {
   /**
    * Requests allowed per IP per window.
@@ -101,7 +123,8 @@ export type RateLimitOptions = {
   /**
    * Maximum distinct entries `buckets` may hold at once, independent of the
    * time-based eviction. Default: `MAX_BUCKETS`. Exposed for tests only —
-   * no production caller overrides this.
+   * no production caller overrides this. Has no effect on the database
+   * store, which has no entry cap of its own (D6's sweep bounds it instead).
    */
   maxBuckets?: number;
   /**
@@ -123,11 +146,15 @@ export type RateLimitOptions = {
    * visitors (#7394). Default: 300.
    */
   perKeyPerMinute?: number;
-};
-
-type Bucket = {
-  count: number;
-  windowStartMs: number;
+  /**
+   * Override the process-default store (#5040 D4). Test-only, like
+   * `maxBuckets` — no production caller overrides this.
+   */
+  store?: RateLimitStore;
+  /**
+   * Override `STORE_TIMEOUT_MS` (#5040 D5). Test-only.
+   */
+  storeTimeoutMs?: number;
 };
 
 const RATE_LIMITED = "rate_limited" as const;
@@ -154,15 +181,26 @@ export const MAX_BUCKETS = 10_000;
  */
 export const DEFAULT_SCHEDULE_PER_KEY_PER_MINUTE = 60;
 
+/**
+ * How long a database-store call may run before the middleware falls back to
+ * the memory store for that request (#5040 D5). `RateLimitOptions.storeTimeoutMs`
+ * overrides it, test-only.
+ */
+export const STORE_TIMEOUT_MS = 1_000;
+
+/** How often a `rate_limit_store_fallback` warn line may be logged (D5). */
+const FALLBACK_WARN_THROTTLE_MS = 60_000;
+
 /**
  * The only (method, route) pairs on which a forwarded visitor IP is believed
- * (#7394 DD-2): the three lead writes, and the two schedule calls a site's
+ * (#7394 DD-2): the three lead writes, the two schedule calls a site's
  * relay forwards on its visitors' behalf (#7633, the relay's security
- * review). Matched against `req.method` and `req.routeOptions.url`, the
+ * review), the two consent writes (#8438) and the three listing-draft calls
+ * (#7479). Matched against `req.method` and `req.routeOptions.url`, the
  * registered route pattern.
  */
 export const FORWARDED_VISITOR_ROUTES: readonly Readonly<{
-  method: "GET" | "POST";
+  method: "GET" | "POST" | "PATCH";
   url: string;
 }>[] = [
   { method: "POST", url: "/v1/leads/submit" },
@@ -175,6 +213,11 @@ export const FORWARDED_VISITOR_ROUTES: readonly Readonly<{
   // counted one by one rather than in one bucket keyed on its egress IP.
   { method: "POST", url: "/v1/consent/cookie" },
   { method: "POST", url: "/v1/consent/unsubscribe" },
+  // #7479 — the listing-draft lifecycle a spoke's Server Action calls on its
+  // applicant's behalf (`start`, the draft `patch`, `submit`), in `leadsScope`.
+  { method: "POST", url: "/v1/project-listings" },
+  { method: "PATCH", url: "/v1/project-listings/drafts/:id" },
+  { method: "POST", url: "/v1/project-listings/drafts/:id/submit" },
 ];
 
 const VISITOR_IP_HEADER = "x-ailk-visitor-ip";
@@ -335,16 +378,17 @@ function resolveScopedLimit(
   return fallback;
 }
 
-// Module-scoped bucket store. One entry per unique identity, per named scope
-// (#7394). Per-forwarding-key buckets live in `keyBuckets` below.
-const buckets = new Map<string, Bucket>();
+// Module-scoped bucket store (the memory store's backing state). One entry
+// per unique identity, per named scope (#7394). Per-forwarding-key buckets
+// live in `keyBuckets` below.
+const buckets = new Map<string, RateLimitBucket>();
 
 // Per-forwarding-key buckets (#7394 DD-8), kept apart from `buckets` so the
 // `maxBuckets` FIFO eviction can never drop one: a keyed caller churning
 // visitor IPs would otherwise push its own key bucket out and reset its
 // ceiling. At most one entry per configured key per named scope, so it
 // needs no capacity cap of its own.
-const keyBuckets = new Map<string, Bucket>();
+const keyBuckets = new Map<string, RateLimitBucket>();
 
 // Request counter used to trigger periodic cleanup.
 let requestsSinceLastClean = 0;
@@ -361,7 +405,6 @@ function evictStaleBuckets(now: number, windowMs: number): void {
       keyBuckets.delete(key);
     }
   }
-  requestsSinceLastClean = 0;
 }
 
 /**
@@ -382,6 +425,145 @@ export function __bucketCount(): number {
   return buckets.size;
 }
 
+/**
+ * The memory store (#5040 D1/D7): the Maps and eviction logic above, wrapped
+ * behind the `RateLimitStore` seam, unchanged in behavior. `maxBuckets` is
+ * captured per call (registrations may pass their own, test-only) but every
+ * instance still operates on the SAME shared `buckets` / `keyBuckets` Maps —
+ * there has never been more than one memory store's worth of state in this
+ * process.
+ */
+function memoryRateLimitStore(maxBuckets: number): RateLimitStore {
+  function hit(key: string, now: number, windowMs: number): Promise<RateLimitBucket> {
+    let bucket = buckets.get(key);
+
+    if (!bucket || now - bucket.windowStartMs >= windowMs) {
+      // A genuinely new distinct identity (not a window roll on an
+      // existing bucket) at capacity evicts the single oldest-inserted
+      // entry first — independent of the time-based eviction above,
+      // which only removes EXPIRED windows and may leave `buckets` at or
+      // above `maxBuckets` when every entry is still within its window.
+      if (!buckets.has(key) && buckets.size >= maxBuckets) {
+        const oldestKey = buckets.keys().next().value;
+        if (oldestKey !== undefined) {
+          buckets.delete(oldestKey);
+        }
+      }
+      bucket = { count: 0, windowStartMs: now };
+      buckets.set(key, bucket);
+    }
+
+    bucket.count += 1;
+    return Promise.resolve(bucket);
+  }
+
+  function hitKey(key: string, now: number, windowMs: number): Promise<RateLimitBucket> {
+    let bucket = keyBuckets.get(key);
+    if (!bucket || now - bucket.windowStartMs >= windowMs) {
+      bucket = { count: 0, windowStartMs: now };
+      keyBuckets.set(key, bucket);
+    }
+    bucket.count += 1;
+    return Promise.resolve(bucket);
+  }
+
+  function hasOpenWindow(key: string, now: number, windowMs: number): Promise<boolean> {
+    const bucket = buckets.get(key);
+    return Promise.resolve(
+      bucket !== undefined && now - bucket.windowStartMs < windowMs,
+    );
+  }
+
+  // D6 — the memory store sweeps on both triggers, exactly as
+  // evictStaleBuckets always has; `reason` only matters to the database
+  // store.
+  function sweep(now: number, windowMs: number): Promise<void> {
+    evictStaleBuckets(now, windowMs);
+    return Promise.resolve();
+  }
+
+  return { hit, hitKey, hasOpenWindow, sweep };
+}
+
+// The process-wide default store (#5040 D4), resolved once and memoized —
+// NOT reset by __resetBuckets(), since only a fresh module instance
+// (jest.isolateModules) changes which store the environment resolves to.
+let processStoreKind: "memory" | "database" | undefined;
+let processDatabaseStore: RateLimitStore | undefined;
+let loggedStoreKind = false;
+
+/**
+ * A rejection or timeout fired this long ago, within `FALLBACK_WARN_THROTTLE_MS`
+ * — do not log another `rate_limit_store_fallback` line yet.
+ */
+let lastFallbackWarnAt: number | undefined;
+
+/** The process default store for a registration with no explicit `store` option. */
+function resolveProcessDefaultStore(
+  warn: (msg: string) => void,
+  log: Pick<FastifyBaseLogger, "info">,
+  maxBuckets: number,
+): RateLimitStore {
+  if (processStoreKind === undefined) {
+    processStoreKind = resolveRateLimitStoreKind(
+      {
+        DATABASE_URL: process.env.DATABASE_URL,
+        AILK_RATE_LIMIT_STORE: process.env.AILK_RATE_LIMIT_STORE,
+      },
+      warn,
+    );
+  }
+  if (!loggedStoreKind) {
+    loggedStoreKind = true;
+    log.info({ rateLimitStore: processStoreKind }, "rate_limit_store");
+  }
+  if (processStoreKind === "database") {
+    processDatabaseStore ??= createDatabaseRateLimitStore(prisma);
+    return processDatabaseStore;
+  }
+  return memoryRateLimitStore(maxBuckets);
+}
+
+class RateLimitStoreTimeoutError extends Error {}
+
+/** Reject with a `RateLimitStoreTimeoutError` if `promise` has not settled within `ms`. */
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new RateLimitStoreTimeoutError("rate limit store call timed out"));
+    }, ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (err: unknown) => {
+        clearTimeout(timer);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      },
+    );
+  });
+}
+
+/**
+ * Log at most one `rate_limit_store_fallback` warn per `FALLBACK_WARN_THROTTLE_MS`
+ * per process (#5040 D5). Carries no key, IP, hash or error message.
+ */
+function warnFallback(
+  warn: (obj: Record<string, unknown>, msg: string) => void,
+  now: number,
+  reason: "error" | "timeout",
+): void {
+  if (
+    lastFallbackWarnAt !== undefined &&
+    now - lastFallbackWarnAt < FALLBACK_WARN_THROTTLE_MS
+  ) {
+    return;
+  }
+  lastFallbackWarnAt = now;
+  warn({ event: "rate_limit_store_fallback", reason }, "rate_limit_store_fallback");
+}
+
 // Break Fastify's plugin encapsulation so the onRequest hook propagates to
 // parent and sibling scopes. This is the manual equivalent of fastify-plugin's
 // `skip-override` mechanism — documented in Fastify's plugin guide.
@@ -396,6 +578,7 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
     maxBuckets = MAX_BUCKETS,
     scope,
     trustedKeyDigests = [],
+    storeTimeoutMs = STORE_TIMEOUT_MS,
   } = opts;
 
   if (scope !== undefined && !SCOPE_RE.test(scope)) {
@@ -435,45 +618,57 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
   const bucketKey = (identity: string) =>
     scope === undefined ? identity : `${scope}|${identity}`;
 
-  /** Count one request against `key`, opening a new window when needed. */
-  function hit(key: string, now: number): Bucket {
-    let bucket = buckets.get(key);
+  const fallbackStore = memoryRateLimitStore(maxBuckets);
+  const primaryStore: RateLimitStore =
+    opts.store ?? resolveProcessDefaultStore(warn, fastify.log, maxBuckets);
 
-    if (!bucket || now - bucket.windowStartMs >= windowMs) {
-      // A genuinely new distinct identity (not a window roll on an
-      // existing bucket) at capacity evicts the single oldest-inserted
-      // entry first — independent of the time-based eviction above,
-      // which only removes EXPIRED windows and may leave `buckets` at or
-      // above `maxBuckets` when every entry is still within its window.
-      if (!buckets.has(key) && buckets.size >= maxBuckets) {
-        const oldestKey = buckets.keys().next().value;
-        if (oldestKey !== undefined) {
-          buckets.delete(oldestKey);
-        }
-      }
-      bucket = { count: 0, windowStartMs: now };
-      buckets.set(key, bucket);
+  /**
+   * Run the whole request's counting against `activeStore` (D7's unchanged
+   * control flow: hitKey → keyOver → R-1 check (hasOpenWindow) → hit →
+   * tripped), plus the periodic/on-429 sweep (D6).
+   */
+  async function countRequest(
+    activeStore: RateLimitStore,
+    ip: string,
+    keyIndex: number | null,
+    now: number,
+    sweepOnInterval: boolean,
+  ): Promise<{
+    tripped: RateLimitBucket | undefined;
+    visitorOver: boolean;
+    keyOver: boolean;
+  }> {
+    if (sweepOnInterval) {
+      await activeStore.sweep(now, windowMs, "interval");
     }
 
-    bucket.count += 1;
-    return bucket;
-  }
-
-  /** True when `key` has a bucket whose window has not yet ended. */
-  function hasOpenWindow(key: string, now: number): boolean {
-    const bucket = buckets.get(key);
-    return bucket !== undefined && now - bucket.windowStartMs < windowMs;
-  }
-
-  /** Count one request against a forwarding key's own bucket (DD-8). */
-  function hitKey(key: string, now: number): Bucket {
-    let bucket = keyBuckets.get(key);
-    if (!bucket || now - bucket.windowStartMs >= windowMs) {
-      bucket = { count: 0, windowStartMs: now };
-      keyBuckets.set(key, bucket);
+    // #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 =
+      keyIndex === null
+        ? undefined
+        : await activeStore.hitKey(`${scope}|key,${keyIndex}`, now, windowMs);
+    const keyOver =
+      keyBucket !== undefined && keyBucket.count > perKeyPerMinute;
+    // A key over its ceiling opens no NEW visitor bucket (#7394 security
+    // review R-1). Each new entry can evict the oldest one in `buckets`,
+    // another scope's counter included, so without this a key holder
+    // rotating visitor IPs could wipe every strict limiter at will. A
+    // visitor whose window is still open is counted as usual.
+    const visitorKey = bucketKey(ip);
+    const bucket =
+      keyOver && !(await activeStore.hasOpenWindow(visitorKey, now, windowMs))
+        ? undefined
+        : await activeStore.hit(visitorKey, now, windowMs);
+    const visitorOver = bucket !== undefined && bucket.count > perIpPerMinute;
+    const tripped = visitorOver ? bucket : keyOver ? keyBucket : undefined;
+
+    if (tripped) {
+      // Evict stale buckets on every 429 to cap memory under abuse.
+      await activeStore.sweep(now, windowMs, "limited");
     }
-    bucket.count += 1;
-    return bucket;
+
+    return { tripped, visitorOver, keyOver };
   }
 
   fastify.addHook(
@@ -483,37 +678,50 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
       const { identity: ip, keyIndex } = identityOf(req);
 
       requestsSinceLastClean += 1;
-      if (requestsSinceLastClean >= CLEAN_INTERVAL_REQUESTS) {
-        evictStaleBuckets(now, windowMs);
+      const sweepOnInterval = requestsSinceLastClean >= CLEAN_INTERVAL_REQUESTS;
+      if (sweepOnInterval) requestsSinceLastClean = 0;
+
+      // #5040 D5 — fail open to the memory store, never to "no limit": a
+      // rejection or a timeout on ANY call of the primary store redoes the
+      // WHOLE request's counting against the memory store, so one request
+      // never mixes stores. withTimeout does not cancel the primary store's
+      // in-flight call, so a write that already landed before the failure
+      // stays counted, and a timed-out query may still land later — the
+      // request can be counted in BOTH stores, over-counting by at most
+      // one. That is the safe direction (D5): never under-counts, never
+      // lets a request through uncounted.
+      let outcome: {
+        tripped: RateLimitBucket | undefined;
+        visitorOver: boolean;
+        keyOver: boolean;
+      };
+      try {
+        outcome = await withTimeout(
+          countRequest(primaryStore, ip, keyIndex, now, sweepOnInterval),
+          storeTimeoutMs,
+        );
+      } catch (err) {
+        warnFallback(
+          (obj, msg) => fastify.log.warn(obj, msg),
+          now,
+          err instanceof RateLimitStoreTimeoutError ? "timeout" : "error",
+        );
+        outcome = await countRequest(
+          fallbackStore,
+          ip,
+          keyIndex,
+          now,
+          sweepOnInterval,
+        );
       }
 
-      // #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 =
-        keyIndex === null ? undefined : hitKey(`${scope}|key,${keyIndex}`, now);
-      const keyOver =
-        keyBucket !== undefined && keyBucket.count > perKeyPerMinute;
-      // A key over its ceiling opens no NEW visitor bucket (#7394 security
-      // review R-1). Each new entry can evict the oldest one in `buckets`,
-      // another scope's counter included, so without this a key holder
-      // rotating visitor IPs could wipe every strict limiter at will. A
-      // visitor whose window is still open is counted as usual.
-      const visitorKey = bucketKey(ip);
-      const bucket =
-        keyOver && !hasOpenWindow(visitorKey, now)
-          ? undefined
-          : hit(visitorKey, now);
-      const visitorOver = bucket !== undefined && bucket.count > perIpPerMinute;
-      const tripped = visitorOver ? bucket : keyOver ? keyBucket : undefined;
+      const { tripped, visitorOver } = outcome;
 
       if (tripped) {
         const retryAfterSeconds = Math.ceil(
           (tripped.windowStartMs + windowMs - now) / 1_000,
         );
 
-        // Evict stale buckets on every 429 to cap memory under abuse.
-        evictStaleBuckets(now, windowMs);
-
         // The path WITHOUT its query string (#5970 security review, finding 1): a
         // route may carry its credential there (`/v1/requests/:id/confirm?token=…`
         // does), and a rate-limit warning is a line an attacker can provoke at

package/templates/apps/api/src/routes/project-listings/__tests__/drafts.test.ts

@@ -974,6 +974,32 @@ describe("the draft lifecycle (#5036 D1)", () => {
     expect(row["resumeTokenHash"]).toBeNull();
   });
 
+  // #8661 D4 — a listing's slug becomes its diagnostic flow's slug, so the
+  // standard magnets' slugs are taken; any other name is unchanged.
+  it.each([
+    ["Contact", "contact-2"],
+    ["Onboarding", "onboarding-2"],
+    ["Atlas", "atlas"],
+  ])("submit: a draft named %s is stored at %s (#8661 D4, AC-2)", async (name, slug) => {
+    const { id, resumeToken } = await startDraft(app);
+    await app.inject({
+      method: "PATCH",
+      url: `/v1/project-listings/drafts/${id}`,
+      headers: bearer(resumeToken),
+      payload: { ...COMPLETE_APPLICATION, name },
+    });
+
+    const res = await app.inject({
+      method: "POST",
+      url: `/v1/project-listings/drafts/${id}/submit`,
+      headers: bearer(resumeToken),
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ ok: true, data: { id, slug } });
+    expect(rows.find((r) => r["id"] === id)!["slug"]).toBe(slug);
+  });
+
   it("submit: a spent token cannot patch or re-submit the listing", async () => {
     const { id, resumeToken } = await startDraft(app);
     await app.inject({

package/templates/apps/api/src/routes/webhooks/README.md

@@ -163,13 +163,41 @@ through `metadata.site`.
   open (a session lives up to 24 hours). A session whose stamp no longer
   matches is acked as foreign and never retried, so its hub side effects are
   lost; the `stamp` / `ownSite` pair in the log line is how to spot that drift.
-- **Not filtered.** `customer.*`, `invoice.*` and subscription events carry no
-  session metadata and are handled as before. Filtering them needs a stamp on
-  those objects, which the spoke-checkout package writes (spoke pattern
-  Phase 3).
+  A subscription keeps its stamp for its whole life and each finalized
+  invoice keeps an immutable copy of it, so a slug collision or a mis-stamp
+  on those lasts as long as the subscription — not the 24 hours a session
+  lives.
+- **Billing events (#8024).** One gate before the event switch applies the
+  same test to every `customer.*`, `customer.subscription.*` and `invoice.*`
+  event, handled type or not. It reads the stamp from the event object's own
+  metadata — the Subscription's (where spoke-checkout writes `site` through
+  `subscription_data.metadata`) or the Customer's — and, for an invoice, from
+  its own metadata, then the subscription snapshot under
+  `parent.subscription_details.metadata` (the pinned API version), then the
+  top-level `subscription_details.metadata` (an endpoint on a pre-`basil`
+  version). Any foreign source makes the event foreign; the first is logged.
+  A source is read only when `data.object.object` is the family's own type
+  (`subscription`, `customer`, `invoice`), so a `customer.source.*` card or a
+  `customer.tax_id.*` object is never read. A foreign event answers 200,
+  logs `outcome: "foreign_site"` (the same five fields), writes nothing — no
+  billing bind, request-paid stamp or dunning record — and is marked seen.
+  The decision uses the payload alone: no Stripe call.
+- **What stays unstamped.** The filter cannot see a stamp nobody wrote, so
+  these are still handled as the hub's own, exactly as before: spoke
+  customers (Checkout cannot put metadata on a customer it creates); quoted
+  spoke subscriptions and their invoices (`createQuotedCheckoutSession`
+  sends no `subscription_data` yet); a fixed spoke subscription whose `site`
+  was later removed; spoke subscriptions created before the stamp shipped,
+  or through a Payment Link or the Dashboard; and the billing app's sessions
+  and subscriptions on the shared account. Where such a subscription sits on
+  a hub User's own Stripe customer (a known buyer reused by a spoke), its
+  events keep reaching that User's dunning record.
 - **A label, not a boundary.** The stamp is written by whoever holds the
   account's secret key. It separates cooperating sites on one account, not
-  tenants.
+  tenants. Whoever holds a write key on the account can also make the hub
+  skip one of its own objects' billing events by stamping it with another
+  site, which silences the hub's dunning record for that subscription — the
+  same key can already cancel or re-price it outright.
 
 ## Dunning (#6034)