create-ailk 0.13.0 → 0.15.0

package/templates/apps/api/src/routes/leads/index.ts

@@ -42,6 +42,28 @@
  * unchanged. So does a keyless request whose hub-status read fails before the
  * process has any answer: lead capture is never lost (#7633, conductor
  * amendment to NFR3). The body's `siteId` stays ignored on every branch.
+ *
+ * IDEMPOTENCY KEY (#7869, roadmap D5). `POST /v1/leads/submit` accepts an
+ * optional `Idempotency-Key` header: 16 to 255 visible ASCII characters, and
+ * it must be UNGUESSABLE (a UUID, a Stripe Checkout Session id) — a key is
+ * first-write-wins inside its workspace, so a short or predictable one could
+ * be claimed by someone else first (SEC-7869-1). It is checked after the
+ * tenant gate and before `routeLead`; a malformed key is `400 invalid_input`
+ * with no read or write. A repeat of a stored key in the same workspace with
+ * the same `email`, `source` and `payload` answers the first lead's 201 and
+ * writes nothing; with anything different it is `422
+ * idempotency_key_reused`. The key dedupes only where a `Lead` row exists —
+ * `inbox` delivery — so a first write that fell back to email or a local
+ * file leaves nothing to find, and its retry writes again. `subscribe` and
+ * `callback` never read the header. The key is never logged or echoed.
+ *
+ * API↔MCP PARITY for the header (#7869 D9, roadmap §12 Q5): NO guard entry.
+ * The guard binds a route's arguments to the validation export its handler
+ * `.safeParse`s on `request.params|query|body`; the header check below is a
+ * regex test, not such a parse, so this route still binds as
+ * `api-args-unbound` and the `capture_lead` row is unchanged. The 201 body's
+ * field set is unchanged too, and `capture_lead` sends no header. If the
+ * guard ever models headers, this becomes an API-side `arg-only-in`.
  */
 
 import { track } from "@working-theory/analytics/server";
@@ -58,6 +80,9 @@ import {
 import { resolveCallerSite } from "../../services/public-site-resolver.js";
 import { sendRequestConfirmLink } from "../../services/request-confirm.js";
 
+/** #7869 D1 — 16 to 255 visible ASCII characters; no spaces, no list. */
+const IDEMPOTENCY_KEY_PATTERN = /^[\x21-\x7E]{16,255}$/;
+
 /**
  * Read a named string field from the body, falling back to the same-named
  * field inside `body.payload` when the top-level value is absent — the
@@ -199,12 +224,46 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
         workspaceId = resolved;
       }
 
+      // #7869 D1 — after the tenant gate, before any read or write. Node
+      // lower-cases header names, and joins a duplicated header with ", ",
+      // which the pattern refuses.
+      let idempotencyKey: string | undefined;
+      if (kind === "submit") {
+        const rawKey = request.headers["idempotency-key"];
+        if (rawKey !== undefined) {
+          if (
+            typeof rawKey !== "string" ||
+            !IDEMPOTENCY_KEY_PATTERN.test(rawKey)
+          ) {
+            return reply.status(400).send({
+              error: "invalid_input",
+              message:
+                "Idempotency-Key must be 16 to 255 visible ASCII characters.",
+            });
+          }
+          idempotencyKey = rawKey;
+        }
+      }
+
       const result = await routeLead(
         buildInput(kind, body, workspaceId),
         sourceMeta,
+        idempotencyKey === undefined ? {} : { idempotencyKey },
       );
 
       if (!result.ok) {
+        if (result.error.kind === "idempotency_conflict") {
+          // #7869 D6 — the operator's signal that a keyed lead was refused.
+          // Never the key, the email or the payload.
+          request.log.warn(
+            { kind, siteId: workspaceId, outcome: "idempotency_conflict" },
+            "lead idempotency_conflict",
+          );
+          return reply.status(422).send({
+            error: "idempotency_key_reused",
+            message: "This Idempotency-Key was used for a different lead.",
+          });
+        }
         if (result.error.kind === "invalid_input") {
           return reply
             .status(400)
@@ -252,6 +311,7 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
           ip: sourceMeta.ip,
           persisted: result.persisted,
           emailKind,
+          replayed: result.replayed === true,
         },
         "lead routed",
       );
@@ -292,12 +352,15 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
       }
 
       // Fire-and-forget: track() never throws; no need to hold the response.
-      void track("lead-captured", {
-        source: body["source"] as string | undefined,
-        locale: (body["payload"] as Record<string, unknown> | undefined)?.[
-          "locale"
-        ] as string | undefined,
-      });
+      // #7869 D6 — a replay records nothing new: the first write counted it.
+      if (!result.replayed) {
+        void track("lead-captured", {
+          source: body["source"] as string | undefined,
+          locale: (body["payload"] as Record<string, unknown> | undefined)?.[
+            "locale"
+          ] as string | undefined,
+        });
+      }
 
       return reply.status(201).send({
         id: result.id,

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

@@ -132,6 +132,45 @@ and the row is still stamped — the quote is never overwritten. The stamp
 runs beside the telemetry + billing tasks, never instead of them, and an
 event without the key never touches `flowCheckout`. Always 200.
 
+## Site filter (#7868)
+
+The hub's Stripe account is shared with its spoke sites, so this endpoint
+receives every site's events. A Checkout session says which site opened it
+through `metadata.site`.
+
+- **The stamp.** Every session the hub creates — `POST /v1/checkout/sessions`
+  and the recommender's quoted checkout (`POST /v1/flows/:slug/checkout`) —
+  carries `metadata.site` = `currentSiteId()`: `AILK_SITE_ID`, else
+  `"default"`. The key, the stamp and the foreign test are defined once in
+  `lib/site.ts` (`SITE_STAMP_KEY`, `siteStamp()`, `isForeignSiteStamp()`).
+  No request field can set or override it.
+- **The filter.** A `checkout.session.completed` or `checkout.session.expired`
+  whose `metadata.site` is a non-empty string other than `currentSiteId()` is
+  another site's. The handler takes no action — no telemetry, billing bind,
+  recommender stamp or request-paid stamp — logs `outcome: "foreign_site"`
+  with the foreign `stamp` (first 64 characters) and the hub's `ownSite`, and
+  answers 200. The comparison is exact and case-sensitive. The event is still
+  marked seen, so a redelivery is the usual duplicate short-circuit.
+- **Unstamped is own.** A session with no stamp, or an empty one, is the hub's
+  and is handled as before: hub Payment Links, hosted invoices, portal events
+  and sessions opened before the stamp shipped carry none, so strict equality
+  would stop hub checkout (roadmap D4).
+- **One alias per deployment.** Two deployments on one Stripe account that
+  both leave `AILK_SITE_ID` unset both stamp `"default"` and treat each
+  other's sessions as their own — give each a distinct `AILK_SITE_ID`. The
+  alias is a deployment-wide constant: every instance and environment on the
+  account must agree on it, and change it only while no Checkout session is
+  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 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.
+
 ## Dunning (#6034)
 
 Two arms record a per-subscriber lifecycle state so a failed renewal is no

package/templates/apps/api/src/routes/webhooks/__tests__/stripe-site-filter.test.ts

@@ -0,0 +1,366 @@
+/**
+ * POST /api/webhooks/stripe — the hub's site filter (#7868).
+ *
+ * A Checkout session stamped `metadata.site` for ANOTHER site (a spoke on the
+ * shared Stripe account) produces no hub side effect on
+ * `checkout.session.completed` or `.expired`, and answers 200. An unstamped
+ * session, an empty stamp, and the hub's own stamp are handled exactly as
+ * today (roadmap D4). Spec D3/D7, AC-2 … AC-4.
+ *
+ * The stripe-flow-checkout.test.ts harness: the commerce claim mocked present,
+ * the prisma manual mock, `verifyWebhookSignature` mocked at the package
+ * boundary, the idempotency store reset per test. The seven existing
+ * `stripe*.test.ts` suites are the regression floor and are not edited.
+ */
+import type { FastifyInstance } from "fastify";
+import Fastify from "fastify";
+
+const mockTrack = jest.fn().mockResolvedValue(undefined);
+jest.mock("@working-theory/license", () => ({
+  checkLicense: jest.fn().mockResolvedValue({
+    tier: "pro",
+    plan: "pro-monthly",
+    features: ["commerce"],
+    expiresAt: null,
+    revoked: false,
+  }),
+}));
+
+jest.mock("@working-theory/analytics/server", () => ({
+  track: (...args: unknown[]) => mockTrack(...args),
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../../../lib/prisma.js");
+
+const mockVerifyWebhookSignature = jest.fn();
+class MockStripeWebhookSignatureError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StripeWebhookSignatureError";
+  }
+}
+jest.mock("@working-theory/stripe-client", () => ({
+  verifyWebhookSignature: (...args: unknown[]) => mockVerifyWebhookSignature(...args),
+  StripeWebhookSignatureError: MockStripeWebhookSignatureError,
+  assertSandboxKey: jest.fn(),
+  createCheckoutSession: jest.fn(),
+  getStripeClient: jest.fn(),
+  STRIPE_API_VERSION: "2024-06-20",
+  StripeConfigError: class StripeConfigError extends Error {},
+  UnknownProductCodeError: class UnknownProductCodeError extends Error {},
+  WEBHOOK_TOLERANCE_SECONDS: 300,
+}));
+
+import * as configModule from "../../../config/index.js";
+import { stripeWebhookHandler } from "../stripe.js";
+import { __resetIdempotencyStore } from "../../../lib/webhook-idempotency.js";
+import { prisma } from "../../../lib/prisma.js";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+const SESSION_ID = "cs_test_session_12345678901234567890";
+const CUSTOMER_ID = "cus_test_12345678901234567890";
+const EMAIL = "spoke-buyer@example.com";
+const AMOUNT_TOTAL = 24917;
+const USER_ID = "usr_buyer_7868";
+const ORG_ID = "org_buyer_7868";
+
+/**
+ * A session that reaches every one of the four `completed` tasks if it is
+ * dispatched: telemetry, the billing bind (customer + `ailk_user_id`), the
+ * recommender stamp (`flowCheckoutId`) and the request-paid stamp
+ * (`payment_link`, paid).
+ */
+function sessionEvent(
+  type: "checkout.session.completed" | "checkout.session.expired",
+  metadata: Record<string, unknown> = {},
+) {
+  return {
+    id: "evt_test_12345678abcdef",
+    type,
+    data: {
+      object: {
+        id: SESSION_ID,
+        payment_status: "paid",
+        payment_link: "plink_test_1234567890",
+        amount_total: AMOUNT_TOTAL,
+        currency: "usd",
+        customer: CUSTOMER_ID,
+        customer_details: { email: EMAIL },
+        metadata: {
+          flowCheckoutId: "flchk_test_1",
+          flowSlug: "ailk-reco",
+          offerKey: "pro",
+          ailk_user_id: USER_ID,
+          ...metadata,
+        },
+      },
+    },
+  };
+}
+
+type LogCall = [unknown, string?];
+const logCalls: LogCall[] = [];
+
+async function buildTestServer(): Promise<FastifyInstance> {
+  const server = Fastify({ logger: false });
+  await server.register(async (webhooksScope) => {
+    webhooksScope.addContentTypeParser("application/json", { parseAs: "buffer" }, (_req, body, done) => {
+      done(null, body);
+    });
+    webhooksScope.addHook("onRequest", async (request) => {
+      for (const level of ["info", "warn", "error"] as const) {
+        const original = request.log[level].bind(request.log);
+        request.log[level] = ((...args: unknown[]) => {
+          logCalls.push(args as LogCall);
+          return (original as (...a: unknown[]) => void)(...args);
+        }) as typeof request.log.info;
+      }
+    });
+    webhooksScope.post("/v1/webhooks/stripe", stripeWebhookHandler);
+  });
+  await server.ready();
+  return server;
+}
+
+const VALID_BODY = Buffer.from(JSON.stringify({ type: "test" }));
+const HEADERS = { "content-type": "application/json", "stripe-signature": "t=1234,v1=abc" };
+const ORIGINAL_AILK_SITE_ID = process.env.AILK_SITE_ID;
+
+let server: FastifyInstance;
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+  logCalls.length = 0;
+  __resetIdempotencyStore();
+  delete process.env.AILK_SITE_ID;
+  jest.replaceProperty(configModule, "config", {
+    ...configModule.config,
+    STRIPE_WEBHOOK_SECRET: "whsec_test_secret",
+  });
+  (prisma.flowCheckout.findUnique as jest.Mock).mockResolvedValue({ amountMinor: AMOUNT_TOTAL });
+  (prisma.flowCheckout.updateMany as jest.Mock).mockResolvedValue({ count: 1 });
+  (prisma.callback.updateMany as jest.Mock).mockResolvedValue({ count: 1 });
+  (prisma.user.findFirst as jest.Mock).mockResolvedValue(null);
+  (prisma.user.findUnique as jest.Mock).mockResolvedValue(null);
+  (prisma.organization.findFirst as jest.Mock).mockResolvedValue(null);
+  (prisma.organization.update as jest.Mock).mockResolvedValue({});
+  server = await buildTestServer();
+});
+
+afterEach(async () => {
+  await server.close();
+  jest.restoreAllMocks();
+  if (ORIGINAL_AILK_SITE_ID === undefined) delete process.env.AILK_SITE_ID;
+  else process.env.AILK_SITE_ID = ORIGINAL_AILK_SITE_ID;
+});
+
+async function post() {
+  return server.inject({ method: "POST", url: "/v1/webhooks/stripe", payload: VALID_BODY, headers: HEADERS });
+}
+
+function foreignSiteLogs() {
+  return logCalls.filter(
+    ([obj]) => typeof obj === "object" && obj !== null && (obj as Record<string, unknown>)["outcome"] === "foreign_site",
+  );
+}
+
+function expectNoHubSideEffect() {
+  expect(mockTrack).not.toHaveBeenCalled();
+  expect(prisma.flowCheckout.findUnique).not.toHaveBeenCalled();
+  expect(prisma.flowCheckout.updateMany).not.toHaveBeenCalled();
+  expect(prisma.callback.updateMany).not.toHaveBeenCalled();
+  expect(prisma.user.findFirst).not.toHaveBeenCalled();
+  expect(prisma.user.findUnique).not.toHaveBeenCalled();
+  expect(prisma.user.update).not.toHaveBeenCalled();
+  expect(prisma.user.updateMany).not.toHaveBeenCalled();
+  expect(prisma.organization.findFirst).not.toHaveBeenCalled();
+  expect(prisma.organization.update).not.toHaveBeenCalled();
+}
+
+function expectHandledAsToday() {
+  expect(mockTrack).toHaveBeenCalledTimes(1);
+  expect(mockTrack).toHaveBeenCalledWith(
+    "purchase-completed",
+    expect.objectContaining({ amount: AMOUNT_TOTAL, eventType: "checkout.session.completed" }),
+  );
+  expect(prisma.flowCheckout.updateMany).toHaveBeenCalledTimes(1);
+  expect(prisma.callback.updateMany).toHaveBeenCalledTimes(1);
+  expect(prisma.user.findFirst).toHaveBeenCalledWith({
+    where: { billingProvider: "stripe", billingCustomerId: CUSTOMER_ID },
+  });
+  expect(foreignSiteLogs()).toHaveLength(0);
+}
+
+// ── Case 1 — a foreign `completed` produces no hub side effect (AC-2) ───────
+
+describe("case 1 — a completed session stamped for another site", () => {
+  it("answers 200 and runs none of the four tasks", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "samhenry" }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ received: true });
+    expectNoHubSideEffect();
+  });
+
+  it("logs one foreign_site line carrying the stamp and the own site, and no buyer field or amount", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "samhenry" }),
+    );
+    await post();
+
+    const lines = foreignSiteLogs();
+    expect(lines).toHaveLength(1);
+    expect(lines[0]![0]).toEqual({
+      eventType: "checkout.session.completed",
+      eventIdPrefix: "evt_test",
+      outcome: "foreign_site",
+      stamp: "samhenry",
+      ownSite: "default",
+    });
+
+    const logged = JSON.stringify(logCalls);
+    expect(logged).not.toContain(EMAIL);
+    expect(logged).not.toContain(String(AMOUNT_TOTAL));
+    expect(logged).not.toContain(USER_ID);
+  });
+
+  it("logs exactly the first 64 characters of a long foreign stamp", async () => {
+    const longStamp = "s".repeat(36) + "t".repeat(64);
+    expect(longStamp).toHaveLength(100);
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: longStamp }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectNoHubSideEffect();
+    const lines = foreignSiteLogs();
+    expect(lines).toHaveLength(1);
+    expect((lines[0]![0] as Record<string, unknown>)["stamp"]).toBe(longStamp.slice(0, 64));
+  });
+});
+
+// ── Case 2 — a foreign session never reaches the Organization write ─────────
+
+describe("case 2 — a foreign session carrying metadata.organizationId", () => {
+  it("writes no Organization", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "samhenry", organizationId: ORG_ID }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectNoHubSideEffect();
+  });
+});
+
+// ── Case 3 — a foreign `expired` stamps no FlowCheckout (AC-3) ──────────────
+
+describe("case 3 — an expired session stamped for another site", () => {
+  it("answers 200 and never expires a hub FlowCheckout", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.expired", { site: "samhenry" }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ received: true });
+    expect(prisma.flowCheckout.updateMany).not.toHaveBeenCalled();
+    const lines = foreignSiteLogs();
+    expect(lines).toHaveLength(1);
+    expect(lines[0]![0]).toMatchObject({
+      eventType: "checkout.session.expired",
+      stamp: "samhenry",
+      ownSite: "default",
+    });
+  });
+});
+
+// ── Cases 4–7 — own and unstamped sessions are handled as today (AC-4) ──────
+
+describe("cases 4–7 — an unstamped, own-stamped or empty-stamped session is the hub's own", () => {
+  it("case 4 — an unstamped session runs every task, as today", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(sessionEvent("checkout.session.completed"));
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectHandledAsToday();
+  });
+
+  it("case 5 — a session stamped with the default alias, AILK_SITE_ID unset, runs every task", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "default" }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectHandledAsToday();
+  });
+
+  it("case 6 — under AILK_SITE_ID=wksp_hub, a wksp_hub stamp is own", async () => {
+    process.env.AILK_SITE_ID = "wksp_hub";
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "wksp_hub" }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectHandledAsToday();
+  });
+
+  it("case 6 — under AILK_SITE_ID=wksp_hub, a default stamp is foreign", async () => {
+    process.env.AILK_SITE_ID = "wksp_hub";
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "default" }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectNoHubSideEffect();
+    const lines = foreignSiteLogs();
+    expect(lines).toHaveLength(1);
+    expect(lines[0]![0]).toMatchObject({ stamp: "default", ownSite: "wksp_hub" });
+  });
+
+  it("case 7 — an empty stamp is unstamped, and runs every task", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "" }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectHandledAsToday();
+  });
+});
+
+// ── Case 8 — the event-id dedup is unchanged ────────────────────────────────
+
+describe("case 8 — a foreign event delivered twice", () => {
+  it("is marked seen, so the redelivery takes the duplicate short-circuit", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { site: "samhenry" }),
+    );
+    const first = await post();
+    expect(first.statusCode).toBe(200);
+    expect(foreignSiteLogs()).toHaveLength(1);
+
+    // Each delivery's lines are read on their own: the harness re-wraps the
+    // shared request logger per request, so a second request logs each line
+    // more than once.
+    logCalls.length = 0;
+    const second = await post();
+
+    expect(second.statusCode).toBe(200);
+    expect(JSON.parse(second.body)).toEqual({ received: true });
+    expect(foreignSiteLogs()).toHaveLength(0);
+    expect(logCalls.map(([, msg]) => msg)).toContain(
+      "duplicate stripe webhook event — idempotent short-circuit",
+    );
+    expectNoHubSideEffect();
+  });
+});

package/templates/apps/api/src/routes/webhooks/stripe.ts

@@ -31,6 +31,15 @@
  * Successful dispatch always 200s — including unknown event types.
  * Telemetry failures are caught, logged, and do NOT change the response.
  *
+ * Site filter (#7868):
+ *   The Stripe account is shared with spoke sites, so this endpoint receives
+ *   their Checkout sessions too. A `checkout.session.completed` or `.expired`
+ *   whose `metadata.site` is a non-empty string naming another site
+ *   (`isForeignSiteStamp`, lib/site.ts) takes no action: it logs
+ *   `outcome: "foreign_site"` and answers 200. An unstamped session is the
+ *   hub's own (roadmap D4) and is handled as before. The hub stamps its own
+ *   sessions through `siteStamp()`. See README.md § Site filter (#7868).
+ *
  * Billing upsert (customer.created / checkout.session.completed):
  *   Billing-entity routing (org-scoped billing, #3601, spec D2): a checkout
  *   carrying metadata.organizationId links the Organization (multi-tenant
@@ -83,7 +92,11 @@ import {
   LICENSE_UNDETERMINED_RETRY_AFTER_SECONDS,
   LICENSE_UNDETERMINED_STATUS,
 } from "../../lib/require-commerce-claim.js";
-import { currentSiteId } from "../../lib/site.js";
+import {
+  currentSiteId,
+  isForeignSiteStamp,
+  SITE_STAMP_KEY,
+} from "../../lib/site.js";
 import {
   StripeWebhookSignatureError,
   toSubscriptionLifecycleStatus,
@@ -299,6 +312,14 @@ export const stripeWebhookHandler = async (
     }
     case "checkout.session.completed": {
       const session = event.data.object as CheckoutSessionObject;
+      if (isForeignSiteStamp(session.metadata)) {
+        logForeignSiteSkip(request, {
+          stamp: session.metadata?.[SITE_STAMP_KEY],
+          eventType: event.type,
+          eventIdPrefix,
+        });
+        break;
+      }
       const props = {
         amount: session.amount_total ?? undefined,
         currency: session.currency ?? undefined,
@@ -363,6 +384,14 @@ export const stripeWebhookHandler = async (
     }
     case "checkout.session.expired": {
       const session = event.data.object as CheckoutSessionObject;
+      if (isForeignSiteStamp(session.metadata)) {
+        logForeignSiteSkip(request, {
+          stamp: session.metadata?.[SITE_STAMP_KEY],
+          eventType: event.type,
+          eventIdPrefix,
+        });
+        break;
+      }
       if (!session.metadata?.["flowCheckoutId"]) {
         // Not a recommender session — the same low-noise line the default
         // arm emitted for this event before #4838 handled it.
@@ -432,6 +461,37 @@ type CheckoutSessionObject = {
   metadata?: Record<string, string> | null;
 };
 
+/**
+ * The one log line for a session another site stamped (#7868 D3). Carries the
+ * foreign stamp (first 64 characters) and this site's own alias, so a spoke
+ * event correctly skipped can be told from a hub event whose alias drifted —
+ * site labels only: it takes the stamp, never the session, so no buyer field
+ * or amount can reach it.
+ */
+function logForeignSiteSkip(
+  request: FastifyRequest,
+  {
+    stamp,
+    eventType,
+    eventIdPrefix,
+  }: {
+    stamp: string | undefined;
+    eventType: string;
+    eventIdPrefix: string;
+  },
+): void {
+  request.log.info(
+    {
+      eventType,
+      eventIdPrefix,
+      outcome: "foreign_site",
+      stamp: stamp?.slice(0, 64),
+      ownSite: currentSiteId(),
+    },
+    "checkout session stamped for another site — skipped",
+  );
+}
+
 /**
  * Minimal projected shape of a Stripe Invoice object for the dunning arms
  * (#6034 FR-1). `subscription` and `customer` are EXPANDABLE Stripe fields —