@cosmicdrift/kumiko-bundled-features 0.250.0 → 0.252.0

package/src/crypto-shredding/__tests__/forget-subject-record.integration.test.ts

@@ -0,0 +1,291 @@
+// crypto-shredding forget-subject over a "record" subject (kumiko-framework#2786):
+//
+//   - a row-scoped field (personal: { of: "id" } → recordOwned) shreds via
+//     forget-subject with { subject: { kind: "record", entity, id } }
+//   - the raw kumiko_events ciphertext stays permanently under the
+//     record:<entity>:<id> prefix — decrypting it separately proves the
+//     erase, not just the projection read path
+//   - the record namespace never collides with a "user" subject that
+//     happens to share the same uuid
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configurePiiSubjectKms,
+  decryptPiiFieldValues,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+  PII_CIPHERTEXT_PREFIX,
+  PII_ERASED_SENTINEL,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import {
+  buildEntityTable,
+  createEventStoreExecutor,
+  createTenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { resetPiiSubjectKmsForTests, resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
+import { createConfigFeature } from "../../config";
+import { createTenantFeature } from "../../tenant";
+import { tenantMembershipsTable } from "../../tenant/membership-table";
+import { RECORD_ENTITY_NOT_REGISTERED, TARGET_RECORD_NOT_ADMIN_TENANT } from "../constants";
+import { createCryptoShreddingFeature } from "../feature";
+
+const FORGET = "crypto-shredding:write:forget-subject";
+const RECORD_PROBE_ENTITY_NAME = "recordProbe";
+const REASON = "authority request #2786 (Art. 17 row-subject)";
+
+const recordProbeEntity = createEntity({
+  table: "read_forget_subject_record_probe",
+  fields: {
+    body: createTextField({
+      required: true,
+      maxLength: 200,
+      personal: { of: "id" },
+      find: "none",
+    }),
+  },
+});
+const recordProbeTable = buildEntityTable("forgetSubjectRecordProbe", recordProbeEntity);
+const recordProbeFeature = defineFeature("forget-subject-record-probe", (r) => {
+  r.entity(RECORD_PROBE_ENTITY_NAME, recordProbeEntity);
+});
+
+function recordProbeExecutor() {
+  return createEventStoreExecutor(recordProbeTable, recordProbeEntity, {
+    entityName: RECORD_PROBE_ENTITY_NAME,
+  });
+}
+
+const TENANT: TenantId = testTenantId(21);
+
+const dpoUser = {
+  id: "cccccccc-cccc-4ccc-8ccc-000000000001",
+  tenantId: TENANT,
+  roles: ["DataProtectionOfficer"],
+};
+
+let stack: TestStack;
+let kms: InMemoryKmsAdapter;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createCryptoShreddingFeature(), recordProbeFeature],
+  });
+  await unsafeCreateEntityTable(stack.db, recordProbeEntity, RECORD_PROBE_ENTITY_NAME);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await resetTestTables(stack.db, [recordProbeTable, eventsTable]);
+  kms = new InMemoryKmsAdapter();
+  configurePiiSubjectKms(kms);
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+});
+
+describe("crypto-shredding :: forget-subject (record subject, #2786)", () => {
+  test("erases the row's ciphertext under the record namespace, proven via decrypt; a same-uuid user-forget never touches it", async () => {
+    const tenantDb = createTenantDb(stack.db, TENANT, "system");
+    const plaintext = "confidential support note";
+    const created = await recordProbeExecutor().create({ body: plaintext }, dpoUser, tenantDb);
+    if (!created.isSuccess) throw new Error("create failed");
+    const rowId = String(created.data.id);
+
+    const beforeShred = await recordProbeExecutor().detail({ id: rowId }, dpoUser, tenantDb);
+    expect(beforeShred?.["body"]).toBe(plaintext);
+
+    // Namespace separation, checked BEFORE the record subject is touched: a
+    // user-forget for the row's own uuid must leave the record row readable
+    // — record:<entity>:<id> and user:<id> are different DEKs even when the
+    // uuid is identical.
+    await stack.http.writeOk(
+      FORGET,
+      { subject: { kind: "user", userId: rowId }, reason: REASON },
+      dpoUser,
+    );
+    const afterBystanderForget = await recordProbeExecutor().detail(
+      { id: rowId },
+      dpoUser,
+      tenantDb,
+    );
+    expect(afterBystanderForget?.["body"]).toBe(plaintext);
+
+    const result = await stack.http.writeOk<{ subjectKey: string }>(
+      FORGET,
+      {
+        subject: { kind: "record", entity: RECORD_PROBE_ENTITY_NAME, id: rowId },
+        reason: REASON,
+      },
+      dpoUser,
+    );
+    expect(result.subjectKey).toBe(`record:${RECORD_PROBE_ENTITY_NAME}:${rowId}`);
+
+    const afterShred = await recordProbeExecutor().detail({ id: rowId }, dpoUser, tenantDb);
+    expect(afterShred?.["body"]).toBe(PII_ERASED_SENTINEL);
+
+    const createdEvents = (await selectMany(stack.db, eventsTable, {
+      aggregateId: rowId,
+      type: `${RECORD_PROBE_ENTITY_NAME}.created`,
+    })) as Array<{ payload: Record<string, unknown> }>;
+    expect(createdEvents).toHaveLength(1);
+    const rawBody = createdEvents[0]?.payload["body"];
+    expect(typeof rawBody).toBe("string");
+    expect(isPiiCiphertext(rawBody)).toBe(true);
+    expect(String(rawBody)).toStartWith(
+      `${PII_CIPHERTEXT_PREFIX}record:${RECORD_PROBE_ENTITY_NAME}:${rowId}:`,
+    );
+    expect(String(rawBody)).not.toContain(plaintext);
+
+    const decrypted = await decryptPiiFieldValues({ body: rawBody }, ["body"], kms, {
+      requestId: "test",
+    });
+    expect(decrypted["body"]).toBe(PII_ERASED_SENTINEL);
+  });
+
+  // Empirical: update()'s previous-row re-encrypt (encryptForStorage(previous))
+  // sees the erased sentinel and passes it through unchanged (pii-field-
+  // encryption.ts's isPiiCiphertext/PII_ERASED_SENTINEL short-circuit) — but
+  // the NEW value in `changes` is real plaintext, so it still needs a DEK.
+  // getOrCreateDek's getKey call on a tombstoned subject throws KeyErasedError,
+  // which propagates out of update() uncaught (only version-conflict errors
+  // are caught there). Not record-specific: the same getOrCreateDek path runs
+  // for a user/tenant PII field after that subject is forgotten.
+  test("update on an already-shredded row rejects instead of writing a fresh plaintext value", async () => {
+    const tenantDb = createTenantDb(stack.db, TENANT, "system");
+    const created = await recordProbeExecutor().create(
+      { body: "pre-shred content" },
+      dpoUser,
+      tenantDb,
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+    const rowId = String(created.data.id);
+
+    await stack.http.writeOk(
+      FORGET,
+      { subject: { kind: "record", entity: RECORD_PROBE_ENTITY_NAME, id: rowId }, reason: REASON },
+      dpoUser,
+    );
+
+    await expect(
+      recordProbeExecutor().update(
+        { id: rowId, changes: { body: "post-shred content" } },
+        dpoUser,
+        tenantDb,
+        { skipOptimisticLock: true },
+      ),
+    ).rejects.toThrow(`Subject key erased: record:${RECORD_PROBE_ENTITY_NAME}:${rowId}`);
+  });
+});
+
+// mh#349 / #2786: resolveTenantScopeDenial's record branch has its own
+// `!features.has("tenant")` fail-open — a denial test against the top-of-file
+// stack (crypto-shredding only) would pass without proving anything, since
+// the tenant gate never even runs there. This describe mounts a separate
+// stack with the tenant feature actually present so the two denial branches
+// (RECORD_ENTITY_NOT_REGISTERED, TARGET_RECORD_NOT_ADMIN_TENANT) get real
+// coverage.
+describe("crypto-shredding :: forget-subject (record subject) tenant gate, #2786", () => {
+  let gateStack: TestStack;
+  let gateKms: InMemoryKmsAdapter;
+
+  const GATE_TENANT_A: TenantId = testTenantId(22);
+  const GATE_TENANT_B: TenantId = testTenantId(23);
+
+  const dpoTenantA = {
+    id: "cccccccc-cccc-4ccc-8ccc-000000000002",
+    tenantId: GATE_TENANT_A,
+    roles: ["DataProtectionOfficer"],
+  };
+  const dpoTenantB = {
+    id: "cccccccc-cccc-4ccc-8ccc-000000000003",
+    tenantId: GATE_TENANT_B,
+    roles: ["DataProtectionOfficer"],
+  };
+
+  beforeAll(async () => {
+    gateStack = await setupTestStack({
+      features: [
+        createCryptoShreddingFeature(),
+        createConfigFeature(),
+        createTenantFeature(),
+        recordProbeFeature,
+      ],
+    });
+    await unsafeCreateEntityTable(gateStack.db, recordProbeEntity, RECORD_PROBE_ENTITY_NAME);
+    await unsafePushTables(gateStack.db, { tenantMembershipsTable });
+    await createEventsTable(gateStack.db);
+  });
+
+  afterAll(async () => {
+    await gateStack.cleanup();
+  });
+
+  beforeEach(async () => {
+    await resetTestTables(gateStack.db, [recordProbeTable, eventsTable]);
+    gateKms = new InMemoryKmsAdapter();
+    configurePiiSubjectKms(gateKms);
+  });
+
+  afterEach(() => {
+    resetPiiSubjectKmsForTests();
+  });
+
+  test("DPO from another tenant cannot forget a record subject owned by a foreign tenant → denied, key survives", async () => {
+    const tenantADb = createTenantDb(gateStack.db, GATE_TENANT_A, "system");
+    const plaintext = "tenant A confidential note";
+    const created = await recordProbeExecutor().create({ body: plaintext }, dpoTenantA, tenantADb);
+    if (!created.isSuccess) throw new Error("create failed");
+    const rowId = String(created.data.id);
+
+    const err = await gateStack.http.writeErr(
+      FORGET,
+      {
+        subject: { kind: "record", entity: RECORD_PROBE_ENTITY_NAME, id: rowId },
+        reason: REASON,
+      },
+      dpoTenantB,
+    );
+    expect(err.httpStatus).toBe(403);
+    expect((err.details as { reason?: string } | undefined)?.reason).toBe(
+      TARGET_RECORD_NOT_ADMIN_TENANT,
+    );
+
+    const stillReadable = await recordProbeExecutor().detail({ id: rowId }, dpoTenantA, tenantADb);
+    expect(stillReadable?.["body"]).toBe(plaintext);
+  });
+
+  test("record subject naming an unregistered entity is denied, not resolved into raw SQL", async () => {
+    const err = await gateStack.http.writeErr(
+      FORGET,
+      {
+        subject: { kind: "record", entity: "notARegisteredEntity", id: crypto.randomUUID() },
+        reason: REASON,
+      },
+      dpoTenantA,
+    );
+    expect(err.httpStatus).toBe(403);
+    expect((err.details as { reason?: string } | undefined)?.reason).toBe(
+      RECORD_ENTITY_NOT_REGISTERED,
+    );
+  });
+});

package/src/crypto-shredding/constants.ts

@@ -6,3 +6,5 @@ export const SUBJECT_FORGET_DENIED_EVENT_NAME = "crypto-shredding:event:forget-d
 export const CRYPTO_SHREDDING_AGGREGATE_TYPE = "crypto-shredding-subject";
 
 export const TARGET_TENANT_NOT_ADMIN_TENANT = "target_tenant_not_admin_tenant" as const;
+export const RECORD_ENTITY_NOT_REGISTERED = "record_entity_not_registered" as const;
+export const TARGET_RECORD_NOT_ADMIN_TENANT = "target_record_not_admin_tenant" as const;

package/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -9,10 +9,12 @@ import {
 import {
   type DbRunner,
   nullBlindIndexesForSubject,
+  recordRowExistsInTenant,
   subjectRowExistsInTenant,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
   defineWriteHandler,
+  type EntityDefinition,
   type FeatureDefinition,
   type HandlerContext,
   type SessionUser,
@@ -38,14 +40,24 @@ import {
 } from "../../user-data-rights";
 import {
   CRYPTO_SHREDDING_AGGREGATE_TYPE,
+  RECORD_ENTITY_NOT_REGISTERED,
   SUBJECT_FORGET_DENIED_EVENT_NAME,
   SUBJECT_FORGOTTEN_EVENT_NAME,
+  TARGET_RECORD_NOT_ADMIN_TENANT,
   TARGET_TENANT_NOT_ADMIN_TENANT,
 } from "../constants";
 
+// Registry entity names are identifier-shaped; ":" would break the subject-key round-trip.
+const RECORD_ENTITY_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
 export const subjectIdSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("user"), userId: z.uuid() }),
   z.object({ kind: z.literal("tenant"), tenantId: z.uuid() }),
+  z.object({
+    kind: z.literal("record"),
+    entity: z.string().regex(RECORD_ENTITY_PATTERN),
+    id: z.uuid(),
+  }),
 ]);
 
 export const forgetSubjectSchema = z.object({
@@ -61,7 +73,7 @@ export const subjectForgottenSchema = z.object({
 
 export const subjectForgetDeniedSchema = z.object({
   subjectKeyDigest: z.string().min(1),
-  subjectKind: z.enum(["user", "tenant"]),
+  subjectKind: z.enum(["user", "tenant", "record"]),
   reason: z.string().min(10),
   forgottenBy: z.string().min(1),
   actorTenantId: z.string().min(1),
@@ -70,6 +82,36 @@ export const subjectForgetDeniedSchema = z.object({
 
 type SubjectIdInput = z.infer<typeof subjectIdSchema>;
 
+// Exhaustive switch so a 4th subject kind fails to compile instead of
+// silently aggregating under the wrong id.
+function subjectAggregateId(raw: SubjectIdInput): string {
+  switch (raw.kind) {
+    case "user":
+      return raw.userId;
+    case "tenant":
+      return raw.tenantId;
+    case "record":
+      return raw.id;
+    default: {
+      const exhaustiveCheck: never = raw;
+      throw new Error(`Unhandled subject kind: ${JSON.stringify(exhaustiveCheck)}`);
+    }
+  }
+}
+
+// The record subject names its own entity — resolve it against the registry
+// instead of trusting the payload straight into resolveTableName/SQL (#2786).
+function findRegisteredEntity(
+  features: ReadonlyMap<string, FeatureDefinition>,
+  entityName: string,
+): EntityDefinition | undefined {
+  for (const feature of features.values()) {
+    const entity = feature.entities?.[entityName];
+    if (entity) return entity;
+  }
+  return undefined;
+}
+
 // Tenant-scope guard (mh#349): DataProtectionOfficer is a tenant-scoped role,
 // but the handler otherwise erases ANY subject cross-tenant on a raw
 // (un-scoped) client — a Tenant-A DPO who learns a Tenant-B subject id
@@ -90,6 +132,30 @@ async function resolveTenantScopeDenial(
     );
   }
 
+  if (raw.kind === "record") {
+    // Same fail-open rule as the user branch below — without the tenant
+    // feature there is no tenant concept to enforce.
+    if (!features.has("tenant")) return undefined;
+    const entity = findRegisteredEntity(features, raw.entity);
+    if (!entity) {
+      return writeFailure(
+        new AccessDeniedError({ details: { reason: RECORD_ENTITY_NOT_REGISTERED } }),
+      );
+    }
+    const ownedInTenant = await recordRowExistsInTenant(
+      db,
+      features,
+      raw.entity,
+      raw.id,
+      user.tenantId,
+    );
+    return ownedInTenant
+      ? undefined
+      : writeFailure(
+          new AccessDeniedError({ details: { reason: TARGET_RECORD_NOT_ADMIN_TENANT } }),
+        );
+  }
+
   // Without the tenant feature there's no membership table to check against —
   // no scoping concept exists to enforce (single/no-tenant apps only;
   // ponytail: fail-open here, not a gap in multi-tenant apps).
@@ -188,7 +254,7 @@ export const forgetSubjectWrite = defineWriteHandler({
   schema: forgetSubjectSchema,
   access: { roles: [ROLES.DataProtectionOfficer, ROLES.SystemAdmin] },
   description:
-    "Irreversibly crypto-shreds one user or tenant subject by erasing its encryption key, nulling its blind indexes, purging its search documents and closing the user's login, for supervisory-authority requests and operator recovery outside the automated Art. 17 cleanup pipeline.",
+    "Irreversibly crypto-shreds one user, tenant or record subject by erasing its encryption key, nulling its blind indexes, purging its search documents and closing the user's login, for supervisory-authority requests and operator recovery outside the automated Art. 17 cleanup pipeline.",
   // Erasing the subject key is irreversible: there is no undo, so an agent must
   // not be able to reach it at all.
   agent: { expose: false },
@@ -208,7 +274,9 @@ export const forgetSubjectWrite = defineWriteHandler({
     const subject: SubjectId =
       raw.kind === "user"
         ? { kind: "user", userId: raw.userId }
-        : { kind: "tenant", tenantId: raw.tenantId as TenantId }; // @cast-boundary uuid-validated command payload → branded id
+        : raw.kind === "tenant"
+          ? { kind: "tenant", tenantId: raw.tenantId as TenantId } // @cast-boundary uuid-validated command payload → branded id
+          : { kind: "record", entity: raw.entity, id: raw.id };
     const subjectKey = subjectIdToKey(subject);
 
     const tenantScopeDenial = await resolveTenantScopeDenial(
@@ -288,7 +356,7 @@ export const forgetSubjectWrite = defineWriteHandler({
     }
 
     await ctx.unsafeAppendEvent({
-      aggregateId: raw.kind === "user" ? raw.userId : raw.tenantId,
+      aggregateId: subjectAggregateId(raw),
       aggregateType: CRYPTO_SHREDDING_AGGREGATE_TYPE,
       type: SUBJECT_FORGOTTEN_EVENT_NAME,
       payload: {

package/src/subscription-stripe/__tests__/feature.test.ts

@@ -109,6 +109,8 @@ describe("constants — Stripe-event-types die wir mappen", () => {
       "customer.subscription.deleted",
       "invoice.paid",
       "invoice.payment_failed",
+      "checkout.session.completed",
+      "checkout.session.async_payment_succeeded",
     ]);
   });
 });

package/src/subscription-stripe/__tests__/payment-checkout.test.ts

@@ -0,0 +1,167 @@
+// Unit tests for the one-off-payment branch of verifyAndParseStripeWebhook
+// (checkout.session.completed / .async_payment_succeeded). Split out of
+// verify-webhook.test.ts — that file's fixtures stay subscription/invoice-
+// only, this one owns every checkout.session.* fixture.
+
+import { describe, expect, test } from "bun:test";
+import { BillingEventKinds } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import Stripe from "stripe";
+import type { StripeWebhookRuntime } from "../runtime";
+import { verifyAndParseStripeWebhook } from "../verify-webhook";
+
+const TEST_SECRET = "whsec_test_secret_12345";
+const TEST_API_KEY = "sk_test_dummy_apikey";
+
+const stripeForFixtures = new Stripe(TEST_API_KEY);
+
+async function signEvent(payload: string, secret = TEST_SECRET): Promise<string> {
+  return stripeForFixtures.webhooks.generateTestHeaderStringAsync({ payload, secret });
+}
+
+function buildCheckoutSessionEvent(overrides: {
+  eventType?: string;
+  eventId?: string;
+  sessionId?: string;
+  mode?: string;
+  paymentStatus?: string;
+}) {
+  return {
+    id: overrides.eventId ?? "evt_checkout_001",
+    object: "event",
+    api_version: "2026-04-22.dahlia",
+    created: 1_770_000_000,
+    type: overrides.eventType ?? "checkout.session.completed",
+    livemode: false,
+    pending_webhooks: 1,
+    request: { id: null, idempotency_key: null },
+    data: {
+      object: {
+        id: overrides.sessionId ?? "cs_test_001",
+        object: "checkout.session",
+        mode: overrides.mode ?? "payment",
+        payment_status: overrides.paymentStatus ?? "paid",
+      },
+    },
+  };
+}
+
+/** Stub-client: real Stripe.webhooks (sig-verify), fake checkout.sessions.retrieve
+ *  (the lazy-fetch). No real network precedent for this call in the suite, so a
+ *  stub result is the intended pattern (advisor-endorsed), not a mock-out of
+ *  application logic under test. */
+function webhookRuntimeWithRetrieve(
+  retrieve: () => Promise<unknown>,
+  webhookSecret = TEST_SECRET,
+): StripeWebhookRuntime {
+  const stripe = {
+    webhooks: stripeForFixtures.webhooks,
+    checkout: { sessions: { retrieve } },
+  } as unknown as Stripe; // @cast-boundary engine-bridge
+  return { resolve: async () => ({ stripe, webhookSecret }) };
+}
+
+function throwingRetrieve(): Promise<never> {
+  throw new Error("checkout.sessions.retrieve must not be called for a non-payment/unpaid session");
+}
+
+function buildExpandedSession(overrides: {
+  sessionId?: string;
+  tenantId?: string;
+  priceId?: string;
+  customerId?: string;
+}) {
+  return {
+    id: overrides.sessionId ?? "cs_test_001",
+    customer: overrides.customerId ?? "cus_test_checkout",
+    payment_intent: {
+      id: "pi_test_001",
+      metadata: { tenantId: overrides.tenantId ?? "tenant-test-1" },
+      customer: overrides.customerId ?? "cus_test_checkout",
+    },
+    line_items: {
+      object: "list",
+      data: [{ id: "li_test_001", price: { id: overrides.priceId ?? "price_topup_test" } }],
+    },
+  };
+}
+
+describe("verifyAndParseStripeWebhook — one-off payment (checkout.session.*)", () => {
+  test("mode: 'subscription' → no PaymentEvent, lazy-fetch never called", async () => {
+    const verify = verifyAndParseStripeWebhook(webhookRuntimeWithRetrieve(throwingRetrieve), {
+      priceToTier: {},
+    });
+    const payload = JSON.stringify(
+      buildCheckoutSessionEvent({ mode: "subscription", paymentStatus: "paid" }),
+    );
+    const sig = await signEvent(payload);
+
+    const event = await verify(payload, { "stripe-signature": sig });
+    expect(event).toBeNull();
+  });
+
+  test("checkout.session.completed with payment_status: 'unpaid' → no PaymentEvent", async () => {
+    const verify = verifyAndParseStripeWebhook(webhookRuntimeWithRetrieve(throwingRetrieve), {
+      priceToTier: {},
+    });
+    const payload = JSON.stringify(
+      buildCheckoutSessionEvent({
+        eventType: "checkout.session.completed",
+        mode: "payment",
+        paymentStatus: "unpaid",
+      }),
+    );
+    const sig = await signEvent(payload);
+
+    const event = await verify(payload, { "stripe-signature": sig });
+    expect(event).toBeNull();
+  });
+
+  test("checkout.session.async_payment_succeeded, mode: payment, paid → PaymentEvent", async () => {
+    const verify = verifyAndParseStripeWebhook(
+      webhookRuntimeWithRetrieve(async () => buildExpandedSession({})),
+      { priceToTier: {} },
+    );
+    const payload = JSON.stringify(
+      buildCheckoutSessionEvent({
+        eventType: "checkout.session.async_payment_succeeded",
+        eventId: "evt_checkout_async_001",
+        mode: "payment",
+        paymentStatus: "paid",
+      }),
+    );
+    const sig = await signEvent(payload);
+
+    const event = await verify(payload, { "stripe-signature": sig });
+    expect(event).not.toBeNull();
+    if (!event || event.kind !== BillingEventKinds.payment) {
+      throw new Error("expected a PaymentEvent");
+    }
+    expect(event.providerEventId).toBe("evt_checkout_async_001");
+    expect(event.providerName).toBe("stripe");
+    expect(event.tenantId).toBe("tenant-test-1");
+    expect(event.priceId).toBe("price_topup_test");
+    expect(event.providerCustomerId).toBe("cus_test_checkout");
+  });
+
+  test("checkout.session.completed, mode: payment, paid, missing tenantId metadata → null", async () => {
+    const verify = verifyAndParseStripeWebhook(
+      webhookRuntimeWithRetrieve(async () => ({
+        ...buildExpandedSession({}),
+        payment_intent: { id: "pi_test_002", metadata: {}, customer: "cus_test_checkout" },
+      })),
+      { priceToTier: {} },
+    );
+    const payload = JSON.stringify(
+      buildCheckoutSessionEvent({
+        eventType: "checkout.session.completed",
+        eventId: "evt_checkout_no_tenant",
+        mode: "payment",
+        paymentStatus: "paid",
+      }),
+    );
+    const sig = await signEvent(payload);
+
+    const event = await verify(payload, { "stripe-signature": sig });
+    expect(event).toBeNull();
+  });
+});