@cosmicdrift/kumiko-samples 0.378.0 → 0.379.0

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-revoke.ts

@@ -0,0 +1,202 @@
+// "This cancellation was not me": the signed link in the receipt mail of a
+// matched public declaration takes the cancellation back until it takes effect.
+// The anonymous handler only routes to the declaration's tenant; the system
+// handler checks the token and does the work.
+
+import { createHash, timingSafeEqual } from "node:crypto";
+import {
+  access,
+  createSystemUser,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import * as z from "zod";
+import { subscriptionAggregateId } from "../aggregate-id.ts";
+import {
+  CONTRACT_TERMINATION_DECLARED_EVENT_QN,
+  CONTRACT_TERMINATION_REQUESTED_EVENT_QN,
+  CONTRACT_TERMINATION_REVOKED_EVENT_QN,
+  type ContractTerminationRevokedPayload,
+  contractTerminationDeclaredPayloadSchema,
+  contractTerminationRequestedPayloadSchema,
+  SUBSCRIPTION_AGGREGATE_TYPE,
+} from "../events.ts";
+import { getSubscriptionForTenant } from "../get-subscription-for-tenant.ts";
+import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from "../types.ts";
+import { SubscriptionFoundationHandlers } from "../web/constants.ts";
+import type { ConsentLocale } from "./consent-text.ts";
+import { notifyOperator } from "./termination-notify.ts";
+import { hasRevocation, resumeAtProvider } from "./termination-record.ts";
+import type { OperatorNoticeReason } from "./termination-texts.ts";
+
+export const REVOCATION_PATHS: Readonly<Record<ConsentLocale, string>> = {
+  de: "/legal/kuendigen/zuruecknehmen",
+  en: "/legal/cancel/revoke",
+};
+
+const TOKEN_BYTES = 32;
+
+export type RevocationOutcome = "revoked" | "already-revoked" | "too-late" | "invalid";
+
+export function createRevocationToken(): { readonly token: string; readonly tokenHash: string } {
+  const token = Buffer.from(crypto.getRandomValues(new Uint8Array(TOKEN_BYTES))).toString(
+    "base64url",
+  );
+  return { token, tokenHash: hashRevocationToken(token) };
+}
+
+function hashRevocationToken(token: string): string {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+function tokenMatchesHash(token: string, expectedHash: string): boolean {
+  const actual = Buffer.from(hashRevocationToken(token));
+  const expected = Buffer.from(expectedHash);
+  return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+
+export function revocationUrl(args: {
+  readonly baseUrl: string;
+  readonly locale: ConsentLocale;
+  readonly requestId: string;
+  readonly token: string;
+  readonly tenantId: string;
+}): string {
+  // Origin only: a baseUrl path prefix would not match the routes mounted at the root.
+  const url = new URL(REVOCATION_PATHS[args.locale], new URL(args.baseUrl).origin);
+  url.searchParams.set("r", args.requestId);
+  url.searchParams.set("t", args.token);
+  url.searchParams.set("tenant", args.tenantId);
+  return url.toString();
+}
+
+const revocationFieldsSchema = {
+  requestId: z.string().min(1).max(100),
+  token: z.string().min(1).max(200),
+};
+
+export const revokeContractTerminationSchema = z
+  .object({ ...revocationFieldsSchema, tenantId: z.uuid() })
+  .strict();
+
+export const recordContractTerminationRevocationSchema = z.object(revocationFieldsSchema).strict();
+
+function parseOutcome(data: unknown): RevocationOutcome {
+  const parsed = z
+    .object({ outcome: z.enum(["revoked", "already-revoked", "too-late", "invalid"]) })
+    .safeParse(data);
+  return parsed.success ? parsed.data.outcome : "invalid";
+}
+
+export function createRevokeContractTerminationHandler(): WriteHandlerDef {
+  return {
+    name: "revoke-contract-termination",
+    description:
+      'Public "this was not me" link of the § 312k receipt mail: takes a public cancellation back until it takes effect; an unknown request and a wrong token answer the same.',
+    schema: revokeContractTerminationSchema,
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 5, windowSeconds: 600 },
+    // The link only knows baseUrl, which may be a host that resolves no tenant; the token alone authorizes.
+    tenantlessAnonymous: true,
+    escapeHatch: {
+      reason:
+        "Anonymous revoker has no session — writes as the system user of the tenant named in the link; only a declared event in that tenant whose revocationTokenHash matches the link token lets the revocation through, every other case answers the same generic invalid.",
+    },
+    handler: async (event, ctx) => {
+      // @cast-boundary engine-payload — dispatcher-zod-validated payload
+      const payload = event.payload as z.infer<typeof revokeContractTerminationSchema>;
+      const result = await ctx.writeAs(
+        createSystemUser(payload.tenantId),
+        SubscriptionFoundationHandlers.recordContractTerminationRevocation,
+        { requestId: payload.requestId, token: payload.token },
+      );
+      return {
+        isSuccess: true as const,
+        data: { outcome: result.isSuccess ? parseOutcome(result.data) : "invalid" },
+      };
+    },
+  };
+}
+
+export function createRecordContractTerminationRevocationHandler(
+  options: ResolvedBillingFoundationOptions,
+  consumerProtection: ConsumerProtectionOptions,
+): WriteHandlerDef {
+  return {
+    name: "record-contract-termination-revocation",
+    agent: { expose: false },
+    schema: recordContractTerminationRevocationSchema,
+    access: { roles: access.system },
+    handler: async (event, ctx) => {
+      // @cast-boundary engine-payload — dispatcher-zod-validated payload
+      const payload = event.payload as z.infer<typeof recordContractTerminationRevocationSchema>;
+      const tenantId = event.user.tenantId;
+      const outcome = (value: RevocationOutcome) => ({
+        isSuccess: true as const,
+        data: { outcome: value },
+      });
+      const stream = await ctx.fetchForWriting({
+        aggregateId: subscriptionAggregateId(tenantId),
+        aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
+      });
+
+      const declared = stream.events
+        .filter((e) => e.type === CONTRACT_TERMINATION_DECLARED_EVENT_QN)
+        .map((e) => contractTerminationDeclaredPayloadSchema.safeParse(e.payload).data)
+        .find((candidate) => candidate?.requestId === payload.requestId);
+      if (
+        declared?.revocationTokenHash === undefined ||
+        !tokenMatchesHash(payload.token, declared.revocationTokenHash)
+      ) {
+        return outcome("invalid");
+      }
+      if (hasRevocation(stream.events, payload.requestId)) return outcome("already-revoked");
+
+      const requested = stream.events
+        .filter((e) => e.type === CONTRACT_TERMINATION_REQUESTED_EVENT_QN)
+        .map((e) => contractTerminationRequestedPayloadSchema.safeParse(e.payload).data)
+        .find((candidate) => candidate?.requestId === payload.requestId);
+      const subscription = await getSubscriptionForTenant(ctx, tenantId);
+      const effectiveAtIso = requested?.effectiveAtIso ?? subscription?.currentPeriodEnd.toString();
+      const now = options.now();
+      if (
+        effectiveAtIso !== undefined &&
+        Temporal.Instant.compare(now, Temporal.Instant.from(effectiveAtIso)) >= 0
+      ) {
+        return outcome("too-late");
+      }
+
+      const reasons: OperatorNoticeReason[] = ["revoked"];
+      if (requested?.providerCancel === "period-end") {
+        reasons.push(...(await resumeAtProvider(ctx, subscription)));
+      }
+      // Re-fetch after the external call, like record-contract-termination.
+      const streamAfterProviderCall = await ctx.fetchForWriting({
+        aggregateId: subscriptionAggregateId(tenantId),
+        aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
+      });
+      const revoked: ContractTerminationRevokedPayload = {
+        requestId: payload.requestId,
+        revokedAtIso: now.toString(),
+      };
+      await streamAfterProviderCall.appendOne({
+        type: CONTRACT_TERMINATION_REVOKED_EVENT_QN,
+        payload: revoked,
+      });
+      await notifyOperator(ctx, consumerProtection, {
+        locale: declared.locale,
+        requestId: declared.requestId,
+        receivedAtIso: declared.receivedAtIso,
+        channel: "public",
+        declaration: {
+          declarationType: declared.declarationType,
+          terminationKind: declared.terminationKind,
+        },
+        reasons,
+        tenantId,
+        ...(requested !== undefined && { providerCancel: requested.providerCancel }),
+      });
+      return outcome("revoked");
+    },
+  };
+}

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-texts.ts

@@ -19,6 +19,8 @@ export type TerminationTexts = {
   readonly receiptIntro: string;
   readonly receiptNextSteps: string;
   readonly receiptRevoke: (operatorEmail: string) => string;
+  readonly receiptNotMe: string;
+  readonly receiptNotMeLink: string;
   readonly contact: string;
   readonly operatorSubject: Readonly<Record<ContractTerminationDeclarationType, string>>;
   readonly operatorIntro: string;
@@ -61,6 +63,21 @@ export type PageTexts = {
   readonly errorGeneric: string;
   readonly rateLimitedTitle: string;
   readonly rateLimitedBody: string;
+  readonly revoke: RevokePageTexts;
+};
+
+export type RevokePageTexts = {
+  readonly confirmTitle: string;
+  readonly confirmLead: string;
+  readonly confirmButton: string;
+  readonly revokedTitle: string;
+  readonly revokedBody: string;
+  readonly alreadyRevokedTitle: string;
+  readonly alreadyRevokedBody: string;
+  readonly tooLateTitle: string;
+  readonly tooLateBody: string;
+  readonly invalidTitle: string;
+  readonly invalidBody: string;
 };
 
 export const OPERATOR_NOTICE_REASONS = [
@@ -74,6 +91,9 @@ export const OPERATOR_NOTICE_REASONS = [
   "recording_failed",
   "withdrawal_period_expired",
   "receipt_rate_limited",
+  "revoked",
+  "revocation_resume_manual",
+  "revocation_resume_failed",
 ] as const;
 export type OperatorNoticeReason = (typeof OPERATOR_NOTICE_REASONS)[number];
 
@@ -103,6 +123,9 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
       "Wir prüfen deine Erklärung und melden uns, sobald sie bearbeitet ist oder wir Rückfragen haben.",
     receiptRevoke: (operatorEmail) =>
       `Hast du diese Erklärung nicht abgegeben oder möchtest du sie zurücknehmen? Schreib uns bitte umgehend an ${operatorEmail}.`,
+    receiptNotMe:
+      "Wurde diese Erklärung nicht von dir abgegeben? Dann nimm die Kündigung bis zu ihrem Wirksamwerden hier zurück:",
+    receiptNotMeLink: "Diese Kündigung war ich nicht",
     contact: "Fragen richtest du bitte an",
     operatorSubject: {
       termination: "Kündigung: Bearbeitung nötig",
@@ -122,6 +145,12 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
         "Widerruf nach Ablauf der Widerrufsfrist: zum Periodenende gekündigt, Anspruch prüfen",
       receipt_rate_limited:
         "Keine Eingangsbestätigung versendet: Limit pro Empfängeradresse erreicht",
+      revoked:
+        "Die Erklärung wurde vom Postfachinhaber über „Diese Kündigung war ich nicht“ zurückgenommen",
+      revocation_resume_manual:
+        "Die Kündigung beim Zahlungsanbieter bitte manuell zurücknehmen (keine Schnittstelle dafür)",
+      revocation_resume_failed:
+        "Die Kündigung beim Zahlungsanbieter konnte nicht zurückgenommen werden, bitte manuell zurücknehmen",
     },
     noticeReasons: "Grund der Benachrichtigung",
     channel: "Kanal",
@@ -163,6 +192,22 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
       rateLimitedTitle: "Zu viele Anfragen",
       rateLimitedBody:
         "Von deiner Adresse kamen zu viele Anfragen. Bitte versuch es später erneut.",
+      revoke: {
+        confirmTitle: "Kündigung zurücknehmen?",
+        confirmLead:
+          "Mit dem Klick auf den Button unten nimmst du die Kündigung zurück. Dein Vertrag läuft dann weiter.",
+        confirmButton: "Diese Kündigung war ich nicht",
+        revokedTitle: "Die Kündigung ist zurückgenommen",
+        revokedBody: "Dein Vertrag läuft weiter. Wir haben den Betreiber informiert.",
+        alreadyRevokedTitle: "Schon zurückgenommen",
+        alreadyRevokedBody: "Diese Kündigung wurde bereits zurückgenommen.",
+        tooLateTitle: "Zu spät für die Rücknahme",
+        tooLateBody:
+          "Die Kündigung ist bereits wirksam geworden. Bitte schreib dem Betreiber, die Adresse steht in der Eingangsbestätigung.",
+        invalidTitle: "Link ungültig",
+        invalidBody:
+          "Dieser Link ist ungültig oder abgelaufen. Bitte schreib dem Betreiber, die Adresse steht in der Eingangsbestätigung.",
+      },
     },
   },
   en: {
@@ -190,6 +235,9 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
       "We will review your declaration and get back to you once it is processed or if we have questions.",
     receiptRevoke: (operatorEmail) =>
       `If you did not make this declaration or want to take it back, please write to ${operatorEmail} right away.`,
+    receiptNotMe:
+      "Did you not make this declaration? Then take the termination back here until it takes effect:",
+    receiptNotMeLink: "I did not request this cancellation",
     contact: "Questions go to",
     operatorSubject: {
       termination: "Termination: action needed",
@@ -208,6 +256,12 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
       withdrawal_period_expired:
         "Withdrawal after the withdrawal period: cancelled at period end, review the claim",
       receipt_rate_limited: "No receipt mail sent: the per-recipient limit was reached",
+      revoked:
+        'The declaration was taken back by the mailbox owner ("I did not request this cancellation")',
+      revocation_resume_manual:
+        "Undo the cancellation at the payment provider manually (no API for it)",
+      revocation_resume_failed:
+        "Undoing the cancellation at the payment provider failed, undo it manually",
     },
     noticeReasons: "Reason for this notice",
     channel: "Channel",
@@ -248,6 +302,22 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
       errorGeneric: "Your declaration could not be processed. Please try again.",
       rateLimitedTitle: "Too many requests",
       rateLimitedBody: "Too many requests came from your address. Please try again later.",
+      revoke: {
+        confirmTitle: "Take the cancellation back?",
+        confirmLead:
+          "Click the button below to take the cancellation back. Your contract then continues.",
+        confirmButton: "I did not request this cancellation",
+        revokedTitle: "The cancellation was taken back",
+        revokedBody: "Your contract continues. We informed the operator.",
+        alreadyRevokedTitle: "Already taken back",
+        alreadyRevokedBody: "This cancellation was already taken back.",
+        tooLateTitle: "Too late to take it back",
+        tooLateBody:
+          "The cancellation has already taken effect. Please write to the operator, the address is in the receipt.",
+        invalidTitle: "Invalid link",
+        invalidBody:
+          "This link is invalid or has expired. Please write to the operator, the address is in the receipt.",
+      },
     },
   },
 };

package/packages/bundled-features/src/billing-foundation/events.ts

@@ -11,8 +11,8 @@
 // type ohne payload-discriminator.
 
 import * as z from "zod";
-import { BILLING_FOUNDATION_FEATURE, SubscriptionStatuses } from "./constants.ts";
-import { CONSENT_LOCALES } from "./consumer-protection/consent-locale.ts";
+import { BILLING_FOUNDATION_FEATURE, SubscriptionStatuses } from "./web/constants.ts";
+import { CONSENT_LOCALES } from "./web/consumer-protection/consent-locale.ts";
 
 // Aggregate-type für den event-store. Eine subscription pro Tenant ist
 // ein stream; der subscriptionAggregateId-helper liefert die stream-id.
@@ -67,6 +67,8 @@ export const subscriptionEventPayloadSchema = z.object({
   // doesn't report cancelAt at all — projection.ts tells the two apart.
   cancelAtIso: z.string().min(1).nullable().optional(),
   consentId: z.string().min(1).max(100).optional(),
+  // When the provider emitted the event; lets process-event drop late deliveries.
+  providerEventAtIso: z.iso.datetime().optional(),
 });
 export type SubscriptionEventPayload = z.infer<typeof subscriptionEventPayloadSchema>;
 
@@ -211,11 +213,27 @@ export const contractTerminationDeclaredPayloadSchema = z.object({
   terminationKind: z.enum(CONTRACT_TERMINATION_KINDS),
   receivedAtIso: z.string().min(1),
   locale: z.enum(CONSENT_LOCALES),
+  // sha256 hex of the "this was not me" link token; events written before the
+  // link existed carry none and cannot be revoked.
+  revocationTokenHash: z.string().length(64).optional(),
 });
 export type ContractTerminationDeclaredPayload = z.infer<
   typeof contractTerminationDeclaredPayloadSchema
 >;
 
+// The mailbox owner took a public declaration back ("this was not me").
+export const CONTRACT_TERMINATION_REVOKED_EVENT_SHORT = "contract-termination-revoked" as const;
+export const CONTRACT_TERMINATION_REVOKED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${CONTRACT_TERMINATION_REVOKED_EVENT_SHORT}` as const;
+
+export const contractTerminationRevokedPayloadSchema = z.object({
+  requestId: z.string().min(1).max(100),
+  revokedAtIso: z.string().min(1),
+});
+export type ContractTerminationRevokedPayload = z.infer<
+  typeof contractTerminationRevokedPayloadSchema
+>;
+
 export const CONTRACT_TERMINATION_UNMATCHED_AGGREGATE_TYPE =
   "contract-termination-unmatched" as const;
 export const CONTRACT_TERMINATION_UNMATCHED_EVENT_SHORT = "contract-termination-unmatched" as const;

package/packages/bundled-features/src/billing-foundation/feature.ts

@@ -56,11 +56,6 @@ import {
   type FeatureDefinition,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import {
-  BILLING_FOUNDATION_FEATURE,
-  SUBSCRIPTION_PROVIDER_EXTENSION,
-  SubscriptionFoundationHandlers,
-} from "./constants.ts";
 import { registerConsumerProtection } from "./consumer-protection/register-consent.ts";
 import { paymentEntity, subscriptionEntity } from "./entities.ts";
 import {
@@ -110,6 +105,11 @@ import {
 } from "./tenant-destroy-hook.ts";
 import type { BillingFoundationOptions, ResolvedBillingFoundationOptions } from "./types.ts";
 import { validateOptions } from "./validate-options.ts";
+import {
+  BILLING_FOUNDATION_FEATURE,
+  SUBSCRIPTION_PROVIDER_EXTENSION,
+  SubscriptionFoundationHandlers,
+} from "./web/constants.ts";
 
 export function createBillingFoundationFeature<TTier extends string = string>(
   options: BillingFoundationOptions<TTier> = {},

package/packages/bundled-features/src/billing-foundation/handlers/process-event.write.ts

@@ -17,14 +17,10 @@ import {
   encryptPiiFieldValues,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { HandlerContext, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { subscriptionAggregateId } from "../aggregate-id.ts";
-import {
-  isSubscriptionBlockingCheckout,
-  isSwitchableSubscriptionStatus,
-  SubscriptionEventTypes,
-  SubscriptionStatuses,
-} from "../constants.ts";
 import { SUBSCRIPTION_PII_FIELDS, subscriptionEntity } from "../entities.ts";
 import {
   INVOICE_PAID_EVENT_QN,
@@ -37,6 +33,13 @@ import {
   type SubscriptionEventPayload,
 } from "../events.ts";
 import { getSubscriptionForTenant, type SubscriptionView } from "../get-subscription-for-tenant.ts";
+import {
+  BILLING_SUBSCRIPTION_LOCK_NAMESPACE,
+  isSubscriptionBlockingCheckout,
+  isSwitchableSubscriptionStatus,
+  SubscriptionEventTypes,
+  SubscriptionStatuses,
+} from "../web/constants.ts";
 
 // =============================================================================
 // Input-Schema = der normalisierte SubscriptionEvent (ohne tenantId, der
@@ -70,6 +73,7 @@ export const processEventSchema = z.object({
   tier: z.string().min(1).max(50),
   currentPeriodEndIso: z.string().min(1),
   cancelAtIso: z.string().min(1).nullable().optional(),
+  providerEventAtIso: z.iso.datetime().optional(),
   consentId: z.string().min(1).max(100).optional(),
 });
 export type ProcessEventPayload = z.infer<typeof processEventSchema>;
@@ -83,6 +87,37 @@ const NORMALIZED_TO_ES_EVENT: Readonly<Record<string, string>> = {
   [SubscriptionEventTypes.invoicePaymentFailed]: INVOICE_PAYMENT_FAILED_EVENT_QN,
 } satisfies Readonly<Record<string, string>>;
 
+const STATE_EVENT_TYPES: ReadonlySet<string> = new Set([
+  SubscriptionEventTypes.created,
+  SubscriptionEventTypes.updated,
+  SubscriptionEventTypes.canceled,
+]);
+
+function isLateStateEvent(
+  storedEvents: readonly {
+    readonly payload: unknown;
+    readonly metadata: { readonly headers?: Record<string, unknown> };
+  }[],
+  payload: ProcessEventPayload,
+): boolean {
+  if (payload.providerEventAtIso === undefined || !STATE_EVENT_TYPES.has(payload.type)) {
+    return false;
+  }
+  const incoming = Temporal.Instant.from(payload.providerEventAtIso);
+  return storedEvents.some((stored) => {
+    const storedAt = propertyOf(stored.payload, "providerEventAtIso");
+    if (stored.metadata.headers?.["providerName"] !== payload.providerName) return false;
+    if (typeof storedAt !== "string") return false;
+    // A stored value that does not parse can never prove a newer event; skip it instead of
+    // failing every later delivery of this tenant's stream.
+    try {
+      return Temporal.Instant.compare(Temporal.Instant.from(storedAt), incoming) > 0;
+    } catch {
+      return false;
+    }
+  });
+}
+
 // =============================================================================
 // appendSubscriptionEvent — the append-body, shared by processEventHandler
 // (webhook path) and sync-subscription.write.ts (backfill path). Both call
@@ -90,12 +125,37 @@ const NORMALIZED_TO_ES_EVENT: Readonly<Record<string, string>> = {
 // who constructs `payload` and what `providerEventId` they use.
 // =============================================================================
 
+// A provider timestamp far in the future would make every later, genuine event look late.
+const PROVIDER_EVENT_CLOCK_SKEW_SECONDS = 300;
+
+export function clampProviderEventAt(
+  payload: ProcessEventPayload,
+  now: Temporal.Instant,
+): ProcessEventPayload {
+  if (payload.providerEventAtIso === undefined) return payload;
+  const ceiling = now.add({ seconds: PROVIDER_EVENT_CLOCK_SKEW_SECONDS });
+  return Temporal.Instant.compare(Temporal.Instant.from(payload.providerEventAtIso), ceiling) > 0
+    ? { ...payload, providerEventAtIso: ceiling.toString() }
+    : payload;
+}
+
 export async function appendSubscriptionEvent(
   ctx: HandlerContext,
   tenantId: string,
-  payload: ProcessEventPayload,
-): Promise<{ readonly duplicate: boolean; readonly subscriptionAggregateId: string }> {
+  rawPayload: ProcessEventPayload,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): Promise<{
+  readonly duplicate: boolean;
+  readonly stale?: true;
+  readonly subscriptionAggregateId: string;
+}> {
   const aggId = subscriptionAggregateId(tenantId);
+  const payload = clampProviderEventAt(rawPayload, now);
+
+  // Serialises the read (idempotency + late check) with the append: the append re-reads the
+  // stream version itself, so without the lock a concurrent delivery could slip in between and
+  // the late check would have judged an outdated stream.
+  await ctx.db.advisoryXactLock(BILLING_SUBSCRIPTION_LOCK_NAMESPACE, aggId);
 
   // ---------------------------------------------------------------
   // 1. Idempotency: load the subscription stream and check whether this
@@ -120,6 +180,16 @@ export async function appendSubscriptionEvent(
     return { duplicate: true, subscriptionAggregateId: aggId };
   }
 
+  // A state event the provider emitted before the newest one already stored is a
+  // late delivery: appending it would roll the row back (a canceled subscription
+  // would come back active). Invoice events carry the live state, not a snapshot.
+  if (isLateStateEvent(existingEvents, payload)) {
+    ctx.log?.warn(
+      `[billing-foundation:process-event] dropped late ${payload.type} ${payload.providerEventId}: a newer provider event is already stored`,
+    );
+    return { duplicate: false, stale: true, subscriptionAggregateId: aggId };
+  }
+
   // ---------------------------------------------------------------
   // 2. Map normalized event-type → ES event-FQN.
   // ---------------------------------------------------------------
@@ -175,6 +245,9 @@ export async function appendSubscriptionEvent(
     currentPeriodEndIso: payload.currentPeriodEndIso,
     ...(payload.cancelAtIso !== undefined && { cancelAtIso: payload.cancelAtIso }),
     ...(payload.consentId !== undefined && { consentId: payload.consentId }),
+    ...(payload.providerEventAtIso !== undefined && {
+      providerEventAtIso: payload.providerEventAtIso,
+    }),
   };
   const headers: SubscriptionEventHeaders = {
     providerEventId: payload.providerEventId,
@@ -243,7 +316,7 @@ export function createProcessEventHandler(now: () => Temporal.Instant): WriteHan
           },
         };
       }
-      const result = await appendSubscriptionEvent(ctx, event.user.tenantId, payload);
+      const result = await appendSubscriptionEvent(ctx, event.user.tenantId, payload, now());
       return { isSuccess: true as const, data: result };
     },
   };

package/packages/bundled-features/src/billing-foundation/handlers/switch-plan.write.ts

@@ -13,10 +13,10 @@ import {
   joinBaseUrl,
   resolveCatalogProvider,
 } from "../checkout-core.ts";
-import { isSwitchableSubscriptionStatus } from "../constants.ts";
 import { getSubscriptionForTenant } from "../get-subscription-for-tenant.ts";
 import { purchaseRolesOf, resolvePlanPrices } from "../plan-catalog.ts";
 import type { BillingFoundationOptions, BillingPlanCatalog } from "../types.ts";
+import { isSwitchableSubscriptionStatus } from "../web/constants.ts";
 
 export function createSwitchPlanHandler(
   options: BillingFoundationOptions,

package/packages/bundled-features/src/billing-foundation/handlers/sync-subscription.write.ts

@@ -18,8 +18,8 @@ import { SYSTEM_ROLE, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { findProviderPlugin } from "../checkout-core.ts";
-import { isTerminalSubscriptionStatus, SubscriptionEventTypes } from "../constants.ts";
 import { getSubscriptionForTenant } from "../get-subscription-for-tenant.ts";
+import { isTerminalSubscriptionStatus, SubscriptionEventTypes } from "../web/constants.ts";
 import { appendSubscriptionEvent } from "./process-event.write.ts";
 
 export const syncSubscriptionSchema = z.object({}).strict();

package/packages/bundled-features/src/billing-foundation/index.ts

@@ -11,38 +11,11 @@ export {
   type ResolvedProvider,
   resolveProviderPlugin,
 } from "./checkout-core.ts";
-export {
-  BILLING_FOUNDATION_FEATURE,
-  BILLING_PLANS_PANEL_COMPONENT,
-  BILLING_PLANS_SCREEN_ID,
-  type BillingEventKind,
-  BillingEventKinds,
-  type BillingPlanAction,
-  BillingPlanActions,
-  DEFAULT_PURCHASE_ROLES,
-  isSwitchableSubscriptionStatus,
-  isTerminalSubscriptionStatus,
-  parseProviderConsentId,
-  SUBSCRIPTION_PROVIDER_EXTENSION,
-  type SubscriptionCancelTiming,
-  SubscriptionCancelTimings,
-  type SubscriptionEventType,
-  SubscriptionEventTypes,
-  SubscriptionFoundationHandlers,
-  SubscriptionFoundationQueries,
-  type SubscriptionStatus,
-  SubscriptionStatuses,
-} from "./constants.ts";
 export {
   type ConsentPayload,
   consentPayloadSchema,
   type OrderItem,
 } from "./consumer-protection/consent-gate.ts";
-export {
-  CONSENT_LOCALES,
-  type ConsentLocale,
-  resolveConsentLocale,
-} from "./consumer-protection/consent-locale.ts";
 export {
   type ContractTerminationRoutesOptions,
   createContractTerminationRoutes,
@@ -99,6 +72,33 @@ export {
   type SubscriptionEvent,
   type SubscriptionProviderPlugin,
 } from "./types.ts";
+export {
+  BILLING_FOUNDATION_FEATURE,
+  BILLING_PLANS_PANEL_COMPONENT,
+  BILLING_PLANS_SCREEN_ID,
+  type BillingEventKind,
+  BillingEventKinds,
+  type BillingPlanAction,
+  BillingPlanActions,
+  DEFAULT_PURCHASE_ROLES,
+  isSwitchableSubscriptionStatus,
+  isTerminalSubscriptionStatus,
+  parseProviderConsentId,
+  SUBSCRIPTION_PROVIDER_EXTENSION,
+  type SubscriptionCancelTiming,
+  SubscriptionCancelTimings,
+  type SubscriptionEventType,
+  SubscriptionEventTypes,
+  SubscriptionFoundationHandlers,
+  SubscriptionFoundationQueries,
+  type SubscriptionStatus,
+  SubscriptionStatuses,
+} from "./web/constants.ts";
+export {
+  CONSENT_LOCALES,
+  type ConsentLocale,
+  resolveConsentLocale,
+} from "./web/consumer-protection/consent-locale.ts";
 export {
   createSubscriptionWebhookRoute,
   type SubscriptionWebhookRouteOptions,

package/packages/bundled-features/src/billing-foundation/plan-catalog.ts

@@ -5,13 +5,6 @@
 
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { isPluginBillingEnabled } from "./checkout-core.ts";
-import {
-  BillingPlanActions,
-  DEFAULT_PURCHASE_ROLES,
-  isSubscriptionBlockingCheckout,
-  isSwitchableSubscriptionStatus,
-  SubscriptionStatuses,
-} from "./constants.ts";
 import { getSubscriptionForTenant } from "./get-subscription-for-tenant.ts";
 import type {
   BillingPlanCatalog,
@@ -20,6 +13,13 @@ import type {
   ProviderPrice,
   SubscriptionProviderPlugin,
 } from "./types.ts";
+import {
+  BillingPlanActions,
+  DEFAULT_PURCHASE_ROLES,
+  isSubscriptionBlockingCheckout,
+  isSwitchableSubscriptionStatus,
+  SubscriptionStatuses,
+} from "./web/constants.ts";
 
 function userHasAnyRole(userRoles: readonly string[], allowedRoles: readonly string[]): boolean {
   return allowedRoles.some((role) => userRoles.includes(role));