create-ailk 0.14.0 → 0.16.0

package/templates/apps/api/src/routes/webhooks/__tests__/stripe-flow-checkout.test.ts

@@ -328,3 +328,108 @@ describe("AC-5 — PII boundary", () => {
     }
   });
 });
+
+// ── #852 D6 — the hub checkout's Person (AC-3) ──────────────────────────────
+//
+// After the stamp, `recordCheckoutPerson` reads the checkout row THIS session
+// completed, then its lead, then finds or creates the Person — with
+// `session.customer` as the customer id only on a live-mode event. Observed
+// through the shared mock's delegates: the `person.findFirst` keyed on a
+// customer id is the customer-id step, so its absence means no id was passed.
+describe("the hub checkout's Person (#852 D6, AC-3)", () => {
+  const WORKSPACE = "wksp_00000000-0000-7000-8000-000000000852";
+  const LEAD = "lead_00000000-0000-7000-8000-000000000852";
+  const personFindFirst = () => jest.mocked(prisma.person.findFirst);
+  const personCalls = () =>
+    [prisma.person.findFirst, prisma.person.createMany, prisma.person.updateMany].reduce(
+      (n, fn) => n + jest.mocked(fn).mock.calls.length,
+      0,
+    );
+  const personLines = () =>
+    logCalls.filter(
+      (c) => typeof c[0] === "object" && c[0] !== null && String((c[0] as { outcome?: string }).outcome).startsWith("person_"),
+    );
+  const liveEvent = (livemode: boolean, object: Record<string, unknown> = {}) => ({
+    ...sessionEvent("checkout.session.completed", { customer: "cus_9", ...object }),
+    livemode,
+  });
+
+  beforeEach(() => {
+    (prisma.flowCheckout.findFirst as jest.Mock).mockResolvedValue({ leadId: LEAD, workspaceId: WORKSPACE });
+    (prisma.lead.findFirst as jest.Mock).mockResolvedValue({ email: EMAIL });
+  });
+
+  it("a paid live-mode hub session finds the Person of its checkout's lead with session.customer", async () => {
+    personFindFirst().mockResolvedValueOnce(null); // no Person carries cus_9 yet
+    mockVerifyWebhookSignature.mockReturnValue(liveEvent(true));
+    expect((await post()).statusCode).toBe(200);
+
+    expect(prisma.flowCheckout.findFirst).toHaveBeenCalledWith({
+      where: { id: FLOW_CHECKOUT_ID, stripeSessionId: SESSION_ID, status: "completed" },
+      select: { leadId: true, workspaceId: true },
+    });
+    expect(prisma.lead.findFirst).toHaveBeenCalledWith({
+      where: { id: LEAD, workspaceId: WORKSPACE },
+      select: { email: true },
+    });
+    expect(personFindFirst()).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { workspaceId: WORKSPACE, billingCustomerId: "cus_9" } }),
+    );
+    expect(personFindFirst()).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { workspaceId: WORKSPACE, email: EMAIL } }),
+    );
+    // The stamp settles before the Person step reads the row it completed.
+    expect((prisma.flowCheckout.updateMany as jest.Mock).mock.invocationCallOrder[0]!).toBeLessThan(
+      (prisma.flowCheckout.findFirst as jest.Mock).mock.invocationCallOrder[0]!,
+    );
+  });
+
+  it("the same session in test mode passes no customer id", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(liveEvent(false));
+    expect((await post()).statusCode).toBe(200);
+
+    expect(personFindFirst()).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { workspaceId: WORKSPACE, email: EMAIL } }),
+    );
+    for (const [args] of personFindFirst().mock.calls) {
+      expect((args as { where: Record<string, unknown> }).where).not.toHaveProperty("billingCustomerId");
+    }
+  });
+
+  it("a session naming a checkout another session completed makes no person call and logs person_skipped", async () => {
+    // The read is keyed on THIS session's id, so another session's row is no row.
+    (prisma.flowCheckout.findFirst as jest.Mock).mockResolvedValue(null);
+    mockVerifyWebhookSignature.mockReturnValue(liveEvent(true));
+    expect((await post()).statusCode).toBe(200);
+
+    expect(personCalls()).toBe(0);
+    expect(personLines().map((c) => (c[0] as { outcome: string }).outcome)).toEqual(["person_skipped"]);
+  });
+
+  it.each([
+    ["a foreign-site session", { metadata: { flowCheckoutId: FLOW_CHECKOUT_ID, site: "wksp_other-spoke" } }],
+    ["an unpaid session", { payment_status: "unpaid" }],
+    ["a session with no flowCheckoutId", { metadata: { flowSlug: "ailk-reco" } }],
+  ])("%s makes no person call", async (_label, object) => {
+    mockVerifyWebhookSignature.mockReturnValue(liveEvent(true, object));
+    expect((await post()).statusCode).toBe(200);
+    expect(prisma.flowCheckout.findFirst).not.toHaveBeenCalled();
+    expect(personCalls()).toBe(0);
+  });
+
+  it("a Person step that throws still answers 200 and logs person_failed with no email or customer id", async () => {
+    personFindFirst().mockRejectedValueOnce(new Error(`relation people down for ${EMAIL} cus_9`));
+    mockVerifyWebhookSignature.mockReturnValue(liveEvent(true));
+    expect((await post()).statusCode).toBe(200);
+
+    const lines = personLines();
+    expect(lines.map((c) => c[0])).toEqual([
+      { eventIdPrefix: "evt_test", flowCheckoutIdPrefix: FLOW_CHECKOUT_ID.substring(0, 8), outcome: "person_failed" },
+    ]);
+    for (const line of logCalls) {
+      const text = JSON.stringify(line);
+      expect(text).not.toContain(EMAIL);
+      expect(text).not.toContain("cus_9");
+    }
+  });
+});

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
@@ -61,6 +70,12 @@
  *   `"no_payment_required"` (a 100%-off promo code, #4862) — anything else
  *   logs `outcome: "unpaid"` and leaves the row `created`.
  *
+ * Checkout Person (checkout.session.completed, #852 D6):
+ *   Chained after that stamp, `recordFlowCheckoutPerson` finds or creates the
+ *   Person of the checkout row THIS session completed (matched on its own
+ *   `stripeSessionId`), with `session.customer` as the customer id only on a
+ *   live-mode event. Logs an outcome kind only; never fails the 200.
+ *
  * Dunning (invoice.payment_failed / customer.subscription.updated, #6034):
  *   Records a per-subscriber lifecycle state in a `UserData` row behind a
  *   reserved-key guard (routes/auth/user.ts). `invoice.payment_failed` arms
@@ -83,7 +98,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,
@@ -98,6 +117,10 @@ import {
   type DunningEntry,
   type DunningRecord,
 } from "../../services/dunning-policy.js";
+import {
+  recordCheckoutPerson,
+  type CheckoutPersonOutcome,
+} from "../../services/person.js";
 
 const TELEMETRY_TIMEOUT_MS = 2000;
 const DUNNING_WRITE_MAX_ATTEMPTS = 3;
@@ -299,6 +322,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,
@@ -338,11 +369,19 @@ export const stripeWebhookHandler = async (
       await Promise.all([
         fireTelemetryWithTimeout(request, "purchase-completed", props),
         billingTask,
+        // #852 D6 — the Person step runs only after the stamp has settled,
+        // so it reads the row this very session completed.
         stampFlowCheckout(request, {
           session,
           eventIdPrefix,
           outcome: "completed",
-        }),
+        }).then(() =>
+          recordFlowCheckoutPerson(request, {
+            session,
+            livemode: event.livemode === true,
+            eventIdPrefix,
+          }),
+        ),
         stampRequestPaid(request, { session, eventIdPrefix }),
       ]);
       break;
@@ -363,6 +402,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 +479,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 —
@@ -563,6 +641,59 @@ async function stampFlowCheckout(
   }
 }
 
+/**
+ * The hub checkout's Person (#852 D6): after `stampFlowCheckout`, find or
+ * create the Person of the completed checkout's lead
+ * (`services/person.ts`'s `recordCheckoutPerson`). Runs only for a paid (or
+ * nothing-due) session of THIS site — the foreign-site filter has already
+ * returned — that carries `metadata.flowCheckoutId`. The customer id's ONE
+ * source is `session.customer`, written onto the Person only for a
+ * live-mode event (SEC-852-A). A replay matches the same completed row, so a
+ * delivery whose Person step failed is repaired by the next one.
+ *
+ * Logs `{ eventIdPrefix, flowCheckoutIdPrefix, outcome }` only — never the
+ * email or the customer id. Never throws: the response stays 200.
+ */
+async function recordFlowCheckoutPerson(
+  request: FastifyRequest,
+  {
+    session,
+    livemode,
+    eventIdPrefix,
+  }: {
+    session: CheckoutSessionObject;
+    livemode: boolean;
+    eventIdPrefix: string;
+  },
+): Promise<void> {
+  const flowCheckoutId = session.metadata?.["flowCheckoutId"];
+  if (!flowCheckoutId) return;
+  if (
+    session.payment_status !== "paid" &&
+    session.payment_status !== "no_payment_required"
+  ) {
+    return;
+  }
+  const flowCheckoutIdPrefix = flowCheckoutId.substring(0, 8);
+  let outcome: CheckoutPersonOutcome;
+  try {
+    outcome = await recordCheckoutPerson({
+      flowCheckoutId,
+      stripeSessionId: session.id,
+      customer: session.customer,
+      livemode,
+    });
+  } catch {
+    outcome = "person_failed";
+  }
+  const line = { eventIdPrefix, flowCheckoutIdPrefix, outcome };
+  if (outcome === "person_failed") {
+    request.log.error(line, "flow checkout person failed — continuing");
+  } else {
+    request.log.info(line, "flow checkout person");
+  }
+}
+
 /**
  * Stamp `paidAt` on a request-and-confirm callback row (#5970 AC-3).
  *