@cosmicdrift/kumiko-samples 0.363.0 → 0.365.0

package/packages/bundled-features/src/auth-email-password/magic-link-mail.ts

@@ -77,24 +77,28 @@ export async function dispatchMagicLinkMail(
   // mailT already root-falls-back; appUrl must use the same negotiated tag
   // or language-in-path apps 404 on e.g. /de-AT/activate.
   const urlLocale = resolveMailLocale(locale);
+  // Template, expiry formatting and app-name fallback must share one locale,
+  // otherwise an English template shows e.g. French "3 heures".
+  const templateLocale = authMailTemplateLocale(spec.notificationType, locale);
   const { validFor, validUntil } = tokenMailExpiry(
     {
       expiresAt: params.expiresAt,
       ...(params.issuedAt !== undefined && { issuedAt: params.issuedAt }),
       ...(params.timeZone !== undefined && { timeZone: params.timeZone }),
     },
-    locale,
+    templateLocale,
   );
   await notify(spec.notificationType, {
     route: { email: params.email },
     data: {
-      appName: params.appName ?? spec.fallbackAppName ?? mailT(locale, "auth.mail.appNameDefault"),
+      appName:
+        params.appName ?? spec.fallbackAppName ?? mailT(templateLocale, "auth.mail.appNameDefault"),
       actionUrl: appendToken(resolveAppUrl(params.appUrl, urlLocale), params.token),
       validFor,
       validUntil,
       ...(params.role !== undefined && { role: params.role }),
     },
-    locale: authMailTemplateLocale(spec.notificationType, locale),
+    locale: templateLocale,
     priority: "critical",
   });
 }

package/packages/bundled-features/src/auth-email-password/mail-i18n.ts

@@ -0,0 +1,10 @@
+// @runtime client
+// Server-registered so the document designer names the seeded auth mails.
+export const AUTH_EMAIL_PASSWORD_MAIL_I18N: Readonly<Record<string, { readonly en: string }>> = {
+  "auth-email-password:feature.label": { en: "Sign-in" },
+  "auth-email-password:notify.password-reset.label": { en: "Password reset" },
+  "auth-email-password:notify.account-unlock.label": { en: "Account unlock" },
+  "auth-email-password:notify.email-verification.label": { en: "Email verification" },
+  "auth-email-password:notify.signup-activation.label": { en: "Sign-up activation" },
+  "auth-email-password:notify.invite.label": { en: "Invitation" },
+};

package/packages/bundled-features/src/auth-email-password/web/auth-gate.tsx

@@ -10,7 +10,7 @@
 // Screen rein konfigurieren, ohne den Gate selbst ersetzen zu müssen.
 
 import { useLocale } from "@cosmicdrift/kumiko-renderer";
-import { type ComponentType, type ReactNode, useEffect, useState } from "react";
+import { type ComponentType, type ReactNode, useEffect, useMemo, useState } from "react";
 import {
   assertNavigableUrl,
   buildLoginRedirectUrl,
@@ -204,6 +204,21 @@ export function resolveLoginRedirect(
   };
 }
 
+// A throwing loginUrl builder must not take the whole app tree down in render;
+// null falls through to the built-in login screen.
+function resolveLoginRedirectOrNull(
+  loginUrl: string | LoginUrlBuilder,
+  locale: string,
+  location: Pick<Location, "origin" | "pathname" | "search" | "hash">,
+): LoginRedirect | null {
+  try {
+    return resolveLoginRedirect(loginUrl, locale, location);
+  } catch (error) {
+    console.error("Auth gate: loginUrl could not be resolved, showing the built-in login", error);
+    return null;
+  }
+}
+
 export function makeAuthGate(opts: AuthGateOptions = {}): ComponentType<{
   children: ReactNode;
 }> {
@@ -213,10 +228,14 @@ export function makeAuthGate(opts: AuthGateOptions = {}): ComponentType<{
   function AuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     const { status } = useSession();
     const locale = useLocale().locale();
-    const loginRedirect =
-      loginUrl !== undefined && status === "unauthenticated"
-        ? resolveLoginRedirect(loginUrl, locale, window.location)
-        : null;
+    const { origin, pathname, search, hash } = window.location;
+    const loginRedirect = useMemo(
+      () =>
+        loginUrl !== undefined && status === "unauthenticated"
+          ? resolveLoginRedirectOrNull(loginUrl, locale, { origin, pathname, search, hash })
+          : null,
+      [status, locale, origin, pathname, search, hash],
+    );
     const redirectUrl = loginRedirect?.kind === "redirect" ? loginRedirect.url : null;
     // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
     useEffect(() => {

package/packages/bundled-features/src/billing-foundation/changes.json

@@ -1,4 +1,52 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Termination record re-reads the stream after the provider call",
+    "detail": "The cancel-at-provider call can take long, so the termination event is appended with a freshly fetched stream version instead of the one read before it."
+  },
+  {
+    "version": "0.365.0",
+    "type": "improvement",
+    "title": "Contract mails carry designer labels",
+    "detail": "Feature and notify labels for contract-confirmation, contract-termination-receipt and contract-termination-operator-notice name the contract mails in the document designer."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Stale subscription created events are ignored and manual-grant skips are logged",
+    "detail": "A created event for a subscription that is no longer current no longer replaces the active one while the current row blocks checkout, and the tier sync logs its own code when a manual grant keeps the tier."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Contract confirmation mail renders the terms' Markdown as formatting",
+    "detail": "The terms rows of the contract confirmation mail were plain text, so `**Right to cancel.**` reached the buyer with its asterisks (0.363.0) or lost its emphasis. Each row of `termsParagraphs` is now a richText value: bold, italic and http(s)/mailto/tel links render as HTML, headings become bold rows. Author HTML and images in the terms stay escaped text, and links outside those schemes stay \"label (url)\". Tenant overrides of the template keep working, the variable name and row structure are unchanged."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Terms in the contract confirmation mail no longer show raw Markdown",
+    "detail": "The terms Markdown is reduced to plain text rows: bold and italic markers are dropped, links become \"label (url)\", list items get their own row, and single line breaks inside a paragraph become spaces."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "The termination receipt rate limit keys Redis with a keyed, handler-bound digest instead of an unkeyed SHA-256 of the email",
+    "detail": "HandlerContext gains an optional rateLimitDigest(value), an HMAC bound to the running handler, so a handler can build rate-limit keys without plaintext identifiers and cannot reproduce the dispatcher's payload-bucket digests. normalizePayloadBucketValue is exported from the pipeline entry point. The receipt limit reuses it, and withholds the receipt mail (the declaration is still recorded) when no digest is wired. Payload-bucket normalization now applies Unicode NFKC first, so fullwidth lookalikes share a bucket. Existing receipt buckets restart empty; they expire after the 24 hour window."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Checkout validates the one-off order label and price lookup",
+    "detail": "An invalid oneOffItemLabel or a provider without retrievePrices fails with a configuration error before the provider is called."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Contract termination downgrades late withdrawals and caps receipt mails",
+    "detail": "A withdrawal declared after the 14-day period ends at period end (operator notice withdrawal_period_expired); the declaration is always accepted, receipt mails are capped at 3 per recipient per day and carry only enum fields, request id and time; purchaser roles come from the catalog."
+  },
   {
     "version": "0.363.0",
     "type": "breaking",

package/packages/bundled-features/src/billing-foundation/consumer-protection/confirmation-mail.ts

@@ -1,4 +1,10 @@
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { Marked } from "marked";
+import {
+  isAllowedDocumentLinkHref,
+  isDocumentPlaceholderHref,
+} from "../../template-resolver/index.js";
 import type { CheckoutConsentRecordedPayload } from "../events.js";
 import { type ConsentLocale, resolveConsentLocale } from "./consent-text.js";
 
@@ -138,13 +144,59 @@ function formatDate(iso: string, locale: ConsentLocale, timeZone: string): strin
   }).format(epochMilliseconds);
 }
 
-// The mail template only knows plain text variables, so the Markdown terms
-// become one row per paragraph; heading markers are dropped.
+// One richText row of inline HTML per Markdown block. The sanitizer shows a rejected
+// row as escaped text, so author HTML, images and refused links stay plain text.
+const ROW_END = "\n\n";
+
+function isMailLinkHref(href: string): boolean {
+  return isAllowedDocumentLinkHref(href) && !isDocumentPlaceholderHref(href);
+}
+
+const inlineHtmlMarkdown = new Marked({ gfm: false, breaks: false });
+inlineHtmlMarkdown.use({
+  renderer: {
+    heading({ tokens }) {
+      const headingHtml = this.parser.parseInline(tokens);
+      return `<strong>${headingHtml}</strong>${ROW_END}`;
+    },
+    paragraph({ tokens }) {
+      return `${this.parser.parseInline(tokens)}${ROW_END}`;
+    },
+    code: ({ text }) => `${escapeHtml(text)}${ROW_END}`,
+    blockquote({ tokens }) {
+      return this.parser.parse(tokens);
+    },
+    list({ items }) {
+      return items.map((item) => this.parser.parse(item.tokens)).join("");
+    },
+    hr: () => "",
+    space: () => "",
+    del({ tokens }) {
+      return this.parser.parseInline(tokens);
+    },
+    br: () => " ",
+    html: ({ text }) => escapeHtml(text),
+    image: ({ text }) => escapeHtml(text),
+    text(token) {
+      // Only block-level text (a list item's own text) carries inline child tokens.
+      return "tokens" in token && token.tokens
+        ? `${this.parser.parseInline(token.tokens)}${ROW_END}`
+        : escapeHtml(token.text);
+    },
+    link({ href, tokens }) {
+      const labelHtml = this.parser.parseInline(tokens);
+      if (isMailLinkHref(href)) return `<a href="${escapeHtmlAttr(href)}">${labelHtml}</a>`;
+      return labelHtml === escapeHtml(href) ? labelHtml : `${labelHtml} (${escapeHtml(href)})`;
+    },
+  },
+});
+
 function termsParagraphsOf(markdown: string): readonly TextRow[] {
-  return markdown
+  return inlineHtmlMarkdown
+    .parse(markdown, { async: false })
     .split(/\n\s*\n/)
-    .map((paragraph) => paragraph.replace(/^#{1,6}\s+/gm, "").trim())
-    .filter((paragraph) => paragraph.length > 0)
+    .map((row) => row.replace(/\s+/g, " ").trim())
+    .filter((row) => row.length > 0)
     .map((text) => ({ text }));
 }
 

package/packages/bundled-features/src/billing-foundation/consumer-protection/consent-gate.ts

@@ -3,7 +3,7 @@
 
 import { createHash } from "node:crypto";
 import { type HandlerContext, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
-import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { InternalError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
 import {
@@ -15,6 +15,7 @@ import { paymentAggregateId, subscriptionAggregateId } from "../aggregate-id.js"
 import {
   CHECKOUT_CONSENT_RECORDED_EVENT_QN,
   type CheckoutConsentRecordedPayload,
+  checkoutConsentRecordedPayloadSchema,
   PAYMENT_AGGREGATE_TYPE,
   SUBSCRIPTION_AGGREGATE_TYPE,
 } from "../events.js";
@@ -50,6 +51,26 @@ export type OrderItem = {
   readonly params?: Readonly<Record<string, string | number>>;
 };
 
+// Bounds come from the event schema the label ends up in, so an app label that
+// passes here cannot fail the append after the provider session exists.
+const orderItemSchema = z.object({
+  labelKey: checkoutConsentRecordedPayloadSchema.shape.itemLabelKey.unwrap(),
+  params: checkoutConsentRecordedPayloadSchema.shape.itemLabelParams,
+});
+
+/** Throws an InternalError (an app configuration fault, not a buyer error) for a
+ *  label the consent event could not store. */
+export function assertValidOrderItem(item: OrderItem | undefined, priceId: string): void {
+  // skip: subscription checkouts have no one-off order item
+  if (item === undefined) return;
+  const parsed = orderItemSchema.safeParse(item);
+  if (!parsed.success) {
+    throw new InternalError({
+      message: `billing-foundation: consumerProtection.oneOffItemLabel returned an invalid label for priceId "${priceId}": ${parsed.error.message}`,
+    });
+  }
+}
+
 export type ConsentPriceDetails = {
   readonly tier: string | null;
   readonly priceId: string;

package/packages/bundled-features/src/billing-foundation/consumer-protection/mail-notifications.ts

@@ -32,7 +32,10 @@ export const OPERATOR_NOTICE_VARIABLES: TemplateVariables = {
 export const CONTRACT_CONFIRMATION_VARIABLES: TemplateVariables = {
   contractLines: textRows(),
   consentGivenAt: templateVariable.text({ required: true }),
-  termsParagraphs: textRows(),
+  termsParagraphs: templateVariable.list(
+    { text: templateVariable.richText({ required: true }) },
+    { required: true },
+  ),
   operatorEmail: templateVariable.text({ required: true }),
 };
 

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

@@ -52,9 +52,19 @@ export function registerContractTermination(
   // request: matched and unmatched requests then do the same work and the
   // response time does not tell whether the email belongs to a customer.
   // The tenant comes from the stored trigger event (the job's system user).
+  // Every declaration appends to the same subscription stream, so parallel runs
+  // and a declaration arriving mid-run hit version conflicts. Sequential runs
+  // rule out the first; a retry re-reads the stream and the requestId check in
+  // record-contract-termination keeps it from recording twice.
   r.job(
     "cancel-on-public-termination-declared",
-    { trigger: { on: CONTRACT_TERMINATION_DECLARED_EVENT_QN }, runIn: "worker" },
+    {
+      trigger: { on: CONTRACT_TERMINATION_DECLARED_EVENT_QN },
+      runIn: "worker",
+      concurrency: "sequential",
+      retries: 3,
+      backoff: "exponential",
+    },
     async (payload, ctx) => {
       const declared = contractTerminationDeclaredPayloadSchema.safeParse(payload);
       // skip: trigger event carries no usable declaration

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

@@ -79,16 +79,22 @@ function declarationLines(
   return lines.map((text) => ({ text }));
 }
 
+/** The receipt carries enum fields only: free text from an anonymous caller
+ *  must not be echoed to an arbitrary address. */
+export type ReceiptDeclaration = Pick<
+  TerminationDeclaration,
+  "declarationType" | "terminationKind"
+>;
+
 export type TerminationReceiptArgs = {
   readonly locale: ConsentLocale;
   readonly requestId: string;
   readonly receivedAtIso: string;
-  readonly declaration: TerminationDeclaration;
+  readonly declaration: ReceiptDeclaration;
   readonly operatorEmail: string;
 };
 
-/** Built from the declarant's own input only: the content must not depend on
- *  whether (or how) the declaration matched a contract. */
+/** The content must not depend on whether (or how) the declaration matched a contract. */
 export function terminationReceiptVariables(
   args: TerminationReceiptArgs,
 ): TerminationReceiptVariables {

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

@@ -0,0 +1,41 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { normalizePayloadBucketValue } from "@cosmicdrift/kumiko-framework/pipeline";
+
+// The declaration itself is a statutory duty and is never refused. Only the
+// receipt mail is capped, so the endpoint cannot be used to mail one inbox
+// from the operator's sender domain.
+export const RECEIPT_MAILS_PER_RECIPIENT = 3;
+export const RECEIPT_WINDOW_SECONDS = 24 * 60 * 60;
+
+const RECEIPT_BUCKET_PREFIX = "termination-receipt";
+
+function receiptBucketKey(ctx: HandlerContext, email: string): string | undefined {
+  const digest = ctx.rateLimitDigest?.(normalizePayloadBucketValue(email, "email"));
+  return digest === undefined ? undefined : `${RECEIPT_BUCKET_PREFIX}:${digest}`;
+}
+
+/** Consumes one receipt token for the recipient. Fails closed when the limiter
+ *  errors or no digest key is wired: the declaration is already recorded, a missing receipt is the lesser harm. */
+export async function mayMailReceipt(ctx: HandlerContext, email: string): Promise<boolean> {
+  // skip: no rate limiter wired, nothing to count against
+  if (!ctx.rateLimit) return true;
+  try {
+    const bucketKey = receiptBucketKey(ctx, email);
+    if (bucketKey === undefined) {
+      ctx.log?.warn(
+        "[billing-foundation:termination] no rate-limit digest available, receipt mail withheld",
+      );
+      return false;
+    }
+    const decision = await ctx.rateLimit.check(bucketKey, {
+      limit: RECEIPT_MAILS_PER_RECIPIENT,
+      windowSeconds: RECEIPT_WINDOW_SECONDS,
+    });
+    return decision.allowed;
+  } catch (error) {
+    ctx.log?.warn(
+      `[billing-foundation:termination] receipt rate limiter failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return false;
+  }
+}

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

@@ -35,6 +35,7 @@ import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from
 import { CONSENT_LOCALES, FALLBACK_CONSENT_LOCALE } from "./consent-locale.js";
 import { notifyOperator } from "./termination-notify.js";
 import type { OperatorNoticeReason } from "./termination-texts.js";
+import { isWithinWithdrawalPeriod } from "./withdrawal-period.js";
 
 const REQUESTED_CANCEL_TIMINGS = [
   SubscriptionCancelTimings.periodEnd,
@@ -74,6 +75,8 @@ export type RecordContractTerminationResult = {
     OperatorNoticeReason,
     "provider_cannot_cancel" | "provider_error" | "no_active_subscription"
   > | null;
+  /** An account withdrawal arrived after the period: cancelled at period end instead. */
+  readonly withdrawalPeriodExpired: boolean;
 };
 
 export const recordUnmatchedContractTerminationSchema = z
@@ -210,14 +213,19 @@ export function createRecordContractTerminationHandler(
             effectiveAtIso: alreadyRecorded.effectiveAtIso,
             providerCancel: alreadyRecorded.providerCancel,
             noticeReason: null,
+            withdrawalPeriodExpired: false,
           } satisfies RecordContractTerminationResult,
         };
       }
 
+      const withdrawalPeriodExpired =
+        payload.declarationType === "withdrawal" &&
+        payload.when === SubscriptionCancelTimings.immediately &&
+        !isWithinWithdrawalPeriod(stream.events, options.now());
       const { providerCancel, effectiveAtIso, noticeReason } = await cancelAtProvider(
         ctx,
         tenantId,
-        payload.when,
+        withdrawalPeriodExpired ? SubscriptionCancelTimings.periodEnd : payload.when,
         receivedAtIso,
       );
 
@@ -230,7 +238,14 @@ export function createRecordContractTerminationHandler(
         effectiveAtIso,
         providerCancel,
       };
-      await stream.appendOne({
+      // Re-fetch after the external call: a webhook appended meanwhile would
+      // otherwise fail the append on a stale expectedVersion although the
+      // provider already cancelled.
+      const streamAfterProviderCall = await ctx.fetchForWriting({
+        aggregateId: subscriptionAggregateId(tenantId),
+        aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
+      });
+      await streamAfterProviderCall.appendOne({
         type: CONTRACT_TERMINATION_REQUESTED_EVENT_QN,
         payload: recorded,
       });
@@ -260,6 +275,7 @@ export function createRecordContractTerminationHandler(
           effectiveAtIso,
           providerCancel,
           noticeReason,
+          withdrawalPeriodExpired,
         } satisfies RecordContractTerminationResult,
       };
     },

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

@@ -33,10 +33,10 @@ import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from
 import { resolveConsentLocale } from "./consent-text.js";
 import { type TerminationDeclaration, terminationReceiptVariables } from "./termination-mail.js";
 import { notifyOperator, type OperatorNoticePlan, requireNotify } from "./termination-notify.js";
+import { mayMailReceipt } from "./termination-receipt-limit.js";
 import type { RecordContractTerminationResult } from "./termination-record.js";
 import type { OperatorNoticeReason } from "./termination-texts.js";
 
-const TENANT_ADMIN_ROLE = "TenantAdmin";
 const EXTRAORDINARY_REASON_MESSAGE = "reason is required for an extraordinary termination";
 
 const authUserRowSchema = z.object({
@@ -109,28 +109,38 @@ async function sendTerminationMails(
   consumerProtection: ConsumerProtectionOptions,
   plan: TerminationMailPlan,
 ): Promise<void> {
-  await requireNotify(ctx)(CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE, {
-    route: { email: plan.declaration.email },
-    data: terminationReceiptVariables({
+  const receiptAllowed = await mayMailReceipt(ctx, plan.declaration.email);
+  if (receiptAllowed) {
+    await requireNotify(ctx)(CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE, {
+      route: { email: plan.declaration.email },
+      data: terminationReceiptVariables({
+        locale: plan.locale,
+        requestId: plan.requestId,
+        receivedAtIso: plan.receivedAtIso,
+        declaration: {
+          declarationType: plan.declaration.declarationType,
+          terminationKind: plan.declaration.terminationKind,
+        },
+        operatorEmail: consumerProtection.operatorEmail,
+      }),
       locale: plan.locale,
-      requestId: plan.requestId,
-      receivedAtIso: plan.receivedAtIso,
-      declaration: plan.declaration,
-      operatorEmail: consumerProtection.operatorEmail,
-    }),
-    locale: plan.locale,
-    priority: "critical",
-  });
+      priority: "critical",
+    });
+  }
+  const reasons = receiptAllowed
+    ? plan.reasons
+    : [...plan.reasons, "receipt_rate_limited" as const];
   // skip: no operator notice needed for this declaration
-  if (plan.reasons.length === 0) return;
-  await notifyOperator(ctx, consumerProtection, plan);
+  if (reasons.length === 0) return;
+  await notifyOperator(ctx, consumerProtection, { ...plan, reasons });
 }
 
 // Tenants the entered email can terminate a contract for: tenants where the
-// user is TenantAdmin and the subscription is not terminal. Every identity
+// user holds a purchase role and the subscription is not terminal. Every identity
 // below comes from the trusted lookups, never from the payload.
 async function findTerminableTenantIds(
   ctx: HandlerContext,
+  options: ResolvedBillingFoundationOptions,
   requestTenantId: string,
   email: string,
 ): Promise<readonly string[]> {
@@ -148,10 +158,11 @@ async function findTerminableTenantIds(
     }),
   );
   if (!memberships.success) return [];
+  const purchaseRoles = purchaseRolesOf(options.catalog);
   const adminTenantIds = [
     ...new Set(
       memberships.data
-        .filter((membership) => membership.roles.includes(TENANT_ADMIN_ROLE))
+        .filter((membership) => membership.roles.some((role) => purchaseRoles.includes(role)))
         .map((membership) => membership.tenantId),
     ),
   ];
@@ -180,7 +191,6 @@ export function createRequestContractTerminationHandler(
     schema: requestContractTerminationSchema,
     access: { roles: ["anonymous"] },
     rateLimit: { per: "ip+handler", limit: 5, windowSeconds: 600 },
-    additionalRateLimits: [{ per: { payloadField: "email" }, limit: 3, windowSeconds: 86400 }],
     ...(consumerProtection.terminationScope === "platform" && { tenantlessAnonymous: true }),
     escapeHatch: {
       reason:
@@ -196,7 +206,12 @@ export function createRequestContractTerminationHandler(
       const locale = resolveConsentLocale(payload.locale);
       let matchedTenantId: string | undefined;
 
-      const candidates = await findTerminableTenantIds(ctx, event.user.tenantId, payload.email);
+      const candidates = await findTerminableTenantIds(
+        ctx,
+        options,
+        event.user.tenantId,
+        payload.email,
+      );
       const [onlyCandidate] = candidates;
       if (candidates.length === 1 && onlyCandidate !== undefined) {
         matchedTenantId = onlyCandidate;
@@ -257,7 +272,7 @@ export function createTerminateContractHandler(
   return {
     name: "terminate-contract",
     description:
-      "Terminates the tenant's subscription at the end of the billing period, or withdraws from the contract and cancels it immediately; sends a receipt to the caller's email.",
+      "Terminates the tenant's subscription at the end of the billing period, or withdraws from the contract and cancels it immediately within the 14-day withdrawal period (at period end after it); sends a receipt to the caller's email.",
     schema: terminateContractSchema,
     access: { roles: purchaseRolesOf(options.catalog) },
     escapeHatch: {
@@ -313,6 +328,7 @@ export function createTerminateContractHandler(
         },
         reasons: [
           ...(data.noticeReason !== null ? [data.noticeReason] : []),
+          ...(data.withdrawalPeriodExpired ? (["withdrawal_period_expired"] as const) : []),
           ...needsOperatorNotice(payload),
         ],
         tenantId,

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

@@ -72,6 +72,8 @@ export const OPERATOR_NOTICE_REASONS = [
   "provider_error",
   "no_active_subscription",
   "recording_failed",
+  "withdrawal_period_expired",
+  "receipt_rate_limited",
 ] as const;
 export type OperatorNoticeReason = (typeof OPERATOR_NOTICE_REASONS)[number];
 
@@ -116,6 +118,10 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
       provider_error: "Die Kündigung beim Zahlungsanbieter ist fehlgeschlagen",
       no_active_subscription: "Keine laufende Subscription beim Anbieter",
       recording_failed: "Die Erklärung konnte nicht gespeichert werden",
+      withdrawal_period_expired:
+        "Widerruf nach Ablauf der Widerrufsfrist: zum Periodenende gekündigt, Anspruch prüfen",
+      receipt_rate_limited:
+        "Keine Eingangsbestätigung versendet: Limit pro Empfängeradresse erreicht",
     },
     noticeReasons: "Grund der Benachrichtigung",
     channel: "Kanal",
@@ -199,6 +205,9 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
       provider_error: "Cancelling at the payment provider failed",
       no_active_subscription: "No running subscription at the provider",
       recording_failed: "The declaration could not be stored",
+      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",
     },
     noticeReasons: "Reason for this notice",
     channel: "Channel",

package/packages/bundled-features/src/billing-foundation/consumer-protection/withdrawal-period.ts

@@ -0,0 +1,35 @@
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { CHECKOUT_CONSENT_RECORDED_EVENT_QN, SUBSCRIPTION_CREATED_EVENT_QN } from "../events.js";
+
+// § 355 BGB: the withdrawal period is 14 days from conclusion of the contract.
+export const WITHDRAWAL_PERIOD_DAYS = 14;
+const HOURS_PER_DAY = 24;
+
+const PERIOD_START_EVENT_TYPES: ReadonlySet<string> = new Set([
+  CHECKOUT_CONSENT_RECORDED_EVENT_QN,
+  SUBSCRIPTION_CREATED_EVENT_QN,
+]);
+
+type PeriodStartEvent = { readonly type: string; readonly createdAt: Temporal.Instant };
+
+/** The period runs from the latest consent or subscription start on the stream.
+ *  A stream with neither has no provable start and counts as expired. */
+export function isWithinWithdrawalPeriod(
+  events: readonly PeriodStartEvent[],
+  now: Temporal.Instant,
+): boolean {
+  let latestStart: Temporal.Instant | undefined;
+  for (const event of events) {
+    if (!PERIOD_START_EVENT_TYPES.has(event.type)) continue;
+    if (
+      latestStart === undefined ||
+      event.createdAt.epochMilliseconds > latestStart.epochMilliseconds
+    ) {
+      latestStart = event.createdAt;
+    }
+  }
+  // skip: no consent or subscription-created event, nothing proves a running period
+  if (latestStart === undefined) return false;
+  const periodEnd = latestStart.add({ hours: WITHDRAWAL_PERIOD_DAYS * HOURS_PER_DAY });
+  return now.epochMilliseconds <= periodEnd.epochMilliseconds;
+}