@cosmicdrift/kumiko-bundled-features 0.363.0 → 0.365.0

package/dist/auth-email-password/web/auth-gate.js

@@ -10,7 +10,7 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 // (nur `{ children }`-Prop). Der Sample kann so einen eigenen Login-
 // Screen rein konfigurieren, ohne den Gate selbst ersetzen zu müssen.
 import { useLocale } from "@cosmicdrift/kumiko-renderer";
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { assertNavigableUrl, buildLoginRedirectUrl, followNextOrLandingAfterLogin, } from "./auth-redirect.js";
 import { LoginScreen } from "./login-screen.js";
 import { SessionProvider, useSession } from "./session.js";
@@ -102,6 +102,17 @@ export function resolveLoginRedirect(loginUrl, locale, { origin, pathname, searc
         url: typeof loginUrl === "function" ? target : buildLoginRedirectUrl(target, returnPath, origin),
     };
 }
+// 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, locale, location) {
+    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 = {}) {
     const { loginUrl } = opts;
     if (typeof loginUrl === "string")
@@ -110,9 +121,10 @@ export function makeAuthGate(opts = {}) {
     function AuthGate({ children }) {
         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/dist/auth-mfa/handlers/disable.write.d.ts

@@ -7,4 +7,4 @@ export declare function createDisableHandler(opts: DisableOptions): import("@cos
     code: z.ZodString;
 }, z.core.$strip>, {
     disabled: boolean;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/auth-mfa/handlers/enable-confirm-preauth.write.d.ts

@@ -13,4 +13,4 @@ export declare function createEnableConfirmPreauthHandler(opts: EnableConfirmPre
 }, z.core.$strip>, {
     kind: string;
     session: SessionUser;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/auth-mfa/handlers/enable-confirm.write.d.ts

@@ -9,4 +9,4 @@ export declare function createEnableConfirmHandler(opts: EnableConfirmOptions):
     code: z.ZodString;
 }, z.core.$strip>, {
     enabled: boolean;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/auth-mfa/handlers/enable-start-preauth.write.d.ts

@@ -11,4 +11,4 @@ export declare function createEnableStartPreauthHandler(opts: EnableStartPreauth
     setupToken: string;
     otpauthUri: string;
     recoveryCodes: string[];
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/auth-mfa/handlers/enable-start.write.d.ts

@@ -10,4 +10,4 @@ export declare function createEnableStartHandler(opts: EnableStartOptions): impo
     otpauthUri: string;
     totpSecret: string;
     recoveryCodes: string[];
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/auth-mfa/handlers/regenerate-recovery.write.d.ts

@@ -6,4 +6,4 @@ export declare function createRegenerateRecoveryHandler(opts: RegenerateRecovery
     code: z.ZodString;
 }, z.core.$strip>, {
     recoveryCodes: string[];
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/auth-mfa/handlers/verify.write.d.ts

@@ -11,4 +11,4 @@ export declare function createMfaVerifyHandler(opts: MfaVerifyOptions): import("
 }, z.core.$strip>, {
     kind: string;
     session: SessionUser;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/billing-foundation/consumer-protection/confirmation-mail.js

@@ -1,4 +1,7 @@
+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 { resolveConsentLocale } from "./consent-text.js";
 export const CONFIRMATION_LABELS = {
     de: {
@@ -89,13 +92,57 @@ function formatDate(iso, locale, timeZone) {
         timeZoneName: "short",
     }).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) {
+    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) {
-    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 }));
 }
 export function contractConfirmationVariables(args) {

package/dist/billing-foundation/consumer-protection/consent-gate.d.ts

@@ -22,6 +22,9 @@ export type OrderItem = {
     readonly labelKey: string;
     readonly params?: Readonly<Record<string, string | number>>;
 };
+/** Throws an InternalError (an app configuration fault, not a buyer error) for a
+ *  label the consent event could not store. */
+export declare function assertValidOrderItem(item: OrderItem | undefined, priceId: string): void;
 export type ConsentPriceDetails = {
     readonly tier: string | null;
     readonly priceId: string;

package/dist/billing-foundation/consumer-protection/consent-gate.js

@@ -2,12 +2,12 @@
 // validate + prepare before the provider call, record only after it succeeded.
 import { createHash } from "node:crypto";
 import { 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 { requireTemplateResolver, TEXT_BLOCK_KIND, TemplateNotFoundError, } from "../../template-resolver/index.js";
 import { paymentAggregateId, subscriptionAggregateId } from "../aggregate-id.js";
-import { CHECKOUT_CONSENT_RECORDED_EVENT_QN, PAYMENT_AGGREGATE_TYPE, SUBSCRIPTION_AGGREGATE_TYPE, } from "../events.js";
+import { CHECKOUT_CONSENT_RECORDED_EVENT_QN, checkoutConsentRecordedPayloadSchema, PAYMENT_AGGREGATE_TYPE, SUBSCRIPTION_AGGREGATE_TYPE, } from "../events.js";
 import { consentTextVersion, resolveConsentLocale, submitMessageFor } from "./consent-text.js";
 // Optional at the schema level so a missing/unchecked consent reaches
 // prepareConsent and fails as 422 consent_required, not as a zod 400.
@@ -19,6 +19,25 @@ export const consentPayloadSchema = z
     locale: z.string().min(2).max(35),
 })
     .strict();
+// 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, priceId) {
+    // 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 async function prepareConsent(ctx, options, consent, mode) {
     if (!consent?.earlyPerformanceRequested || !consent.withdrawalLossAcknowledged) {
         throw new UnprocessableError("consent_required", {

package/dist/billing-foundation/consumer-protection/mail-notifications.js

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

package/dist/billing-foundation/consumer-protection/register-termination.js

@@ -16,7 +16,17 @@ export function registerContractTermination(r, options, consumerProtection) {
     // 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).
-    r.job("cancel-on-public-termination-declared", { trigger: { on: CONTRACT_TERMINATION_DECLARED_EVENT_QN }, runIn: "worker" }, async (payload, ctx) => {
+    // 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",
+        concurrency: "sequential",
+        retries: 3,
+        backoff: "exponential",
+    }, async (payload, ctx) => {
         const declared = contractTerminationDeclaredPayloadSchema.safeParse(payload);
         // skip: trigger event carries no usable declaration
         if (!declared.success)

package/dist/billing-foundation/consumer-protection/termination-mail.d.ts

@@ -30,15 +30,17 @@ export type TerminationDeclaration = {
 /** The operator notice for a provider problem has no declarant data at all. */
 export type OperatorNoticeDeclaration = Pick<TerminationDeclaration, "declarationType" | "terminationKind"> & Partial<Omit<TerminationDeclaration, "declarationType" | "terminationKind">>;
 export declare function formatReceivedAt(iso: string, locale: ConsentLocale): string;
+/** 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 declare function terminationReceiptVariables(args: TerminationReceiptArgs): TerminationReceiptVariables;
 export type OperatorNoticeArgs = {
     readonly locale: ConsentLocale;

package/dist/billing-foundation/consumer-protection/termination-mail.js

@@ -32,8 +32,7 @@ function declarationLines(declaration, locale) {
     ];
     return lines.map((text) => ({ text }));
 }
-/** 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) {
     const texts = TERMINATION_TEXTS[args.locale];
     return {

package/dist/billing-foundation/consumer-protection/termination-receipt-limit.d.ts

@@ -0,0 +1,6 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+export declare const RECEIPT_MAILS_PER_RECIPIENT = 3;
+export declare const RECEIPT_WINDOW_SECONDS: number;
+/** 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 declare function mayMailReceipt(ctx: HandlerContext, email: string): Promise<boolean>;

package/dist/billing-foundation/consumer-protection/termination-receipt-limit.js

@@ -0,0 +1,34 @@
+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, email) {
+    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, email) {
+    // 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/dist/billing-foundation/consumer-protection/termination-record.d.ts

@@ -49,6 +49,8 @@ export type RecordContractTerminationResult = {
     readonly effectiveAtIso: string | null;
     readonly providerCancel: ProviderCancelOutcome;
     readonly noticeReason: Extract<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 declare const recordUnmatchedContractTerminationSchema: z.ZodObject<{
     requestId: z.ZodString;

package/dist/billing-foundation/consumer-protection/termination-record.js

@@ -12,6 +12,7 @@ import { CONTRACT_TERMINATION_CHANNELS, CONTRACT_TERMINATION_DECLARATION_TYPES,
 import { getSubscriptionForTenant } from "../get-subscription-for-tenant.js";
 import { CONSENT_LOCALES, FALLBACK_CONSENT_LOCALE } from "./consent-locale.js";
 import { notifyOperator } from "./termination-notify.js";
+import { isWithinWithdrawalPeriod } from "./withdrawal-period.js";
 const REQUESTED_CANCEL_TIMINGS = [
     SubscriptionCancelTimings.periodEnd,
     SubscriptionCancelTimings.immediately,
@@ -148,10 +149,14 @@ export function createRecordContractTerminationHandler(options, consumerProtecti
                         effectiveAtIso: alreadyRecorded.effectiveAtIso,
                         providerCancel: alreadyRecorded.providerCancel,
                         noticeReason: null,
+                        withdrawalPeriodExpired: false,
                     },
                 };
             }
-            const { providerCancel, effectiveAtIso, noticeReason } = await cancelAtProvider(ctx, tenantId, payload.when, receivedAtIso);
+            const withdrawalPeriodExpired = payload.declarationType === "withdrawal" &&
+                payload.when === SubscriptionCancelTimings.immediately &&
+                !isWithinWithdrawalPeriod(stream.events, options.now());
+            const { providerCancel, effectiveAtIso, noticeReason } = await cancelAtProvider(ctx, tenantId, withdrawalPeriodExpired ? SubscriptionCancelTimings.periodEnd : payload.when, receivedAtIso);
             const recorded = {
                 requestId: payload.requestId,
                 declarationType: payload.declarationType,
@@ -161,7 +166,14 @@ export function createRecordContractTerminationHandler(options, consumerProtecti
                 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,
             });
@@ -189,6 +201,7 @@ export function createRecordContractTerminationHandler(options, consumerProtecti
                     effectiveAtIso,
                     providerCancel,
                     noticeReason,
+                    withdrawalPeriodExpired,
                 },
             };
         },

package/dist/billing-foundation/consumer-protection/termination-request.js

@@ -14,7 +14,7 @@ import { purchaseRolesOf } from "../plan-catalog.js";
 import { resolveConsentLocale } from "./consent-text.js";
 import { terminationReceiptVariables } from "./termination-mail.js";
 import { notifyOperator, requireNotify } from "./termination-notify.js";
-const TENANT_ADMIN_ROLE = "TenantAdmin";
+import { mayMailReceipt } from "./termination-receipt-limit.js";
 const EXTRAORDINARY_REASON_MESSAGE = "reason is required for an extraordinary termination";
 const authUserRowSchema = z.object({
     id: z.string().min(1),
@@ -53,27 +53,36 @@ function needsOperatorNotice(declaration) {
     ];
 }
 async function sendTerminationMails(ctx, consumerProtection, plan) {
-    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"];
     // skip: no operator notice needed for this declaration
-    if (plan.reasons.length === 0)
+    if (reasons.length === 0)
         return;
-    await notifyOperator(ctx, consumerProtection, plan);
+    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, requestTenantId, email) {
+async function findTerminableTenantIds(ctx, options, requestTenantId, email) {
     declareEscapeHatch({
         reason: "anonymous declarant has no session — finds the contract by email via user:find-for-auth and tenant:memberships as a system user; the calling handler declares its own escapeHatch",
     });
@@ -85,9 +94,10 @@ async function findTerminableTenantIds(ctx, requestTenantId, email) {
     }));
     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)),
     ];
     const terminable = [];
@@ -105,7 +115,6 @@ export function createRequestContractTerminationHandler(options, consumerProtect
         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: "Anonymous declarant has no session — finds the contract by email via ctx.queryAs(system, user:find-for-auth) and tenant:memberships; the tenant written to comes only from those lookups.",
@@ -119,7 +128,7 @@ export function createRequestContractTerminationHandler(options, consumerProtect
             const reasons = [];
             const locale = resolveConsentLocale(payload.locale);
             let matchedTenantId;
-            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;
@@ -168,7 +177,7 @@ export function createRequestContractTerminationHandler(options, consumerProtect
 export function createTerminateContractHandler(options, consumerProtection) {
     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.",
+        description: "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: {
@@ -214,6 +223,7 @@ export function createTerminateContractHandler(options, consumerProtection) {
                 },
                 reasons: [
                     ...(data.noticeReason !== null ? [data.noticeReason] : []),
+                    ...(data.withdrawalPeriodExpired ? ["withdrawal_period_expired"] : []),
                     ...needsOperatorNotice(payload),
                 ],
                 tenantId,

package/dist/billing-foundation/consumer-protection/termination-texts.d.ts

@@ -58,6 +58,6 @@ export type PageTexts = {
     readonly rateLimitedTitle: string;
     readonly rateLimitedBody: string;
 };
-export declare const OPERATOR_NOTICE_REASONS: readonly ["unmatched", "ambiguous", "withdrawal", "extraordinary", "provider_cannot_cancel", "provider_error", "no_active_subscription", "recording_failed"];
+export declare const OPERATOR_NOTICE_REASONS: readonly ["unmatched", "ambiguous", "withdrawal", "extraordinary", "provider_cannot_cancel", "provider_error", "no_active_subscription", "recording_failed", "withdrawal_period_expired", "receipt_rate_limited"];
 export type OperatorNoticeReason = (typeof OPERATOR_NOTICE_REASONS)[number];
 export declare const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>>;

package/dist/billing-foundation/consumer-protection/termination-texts.js

@@ -7,6 +7,8 @@ export const OPERATOR_NOTICE_REASONS = [
     "provider_error",
     "no_active_subscription",
     "recording_failed",
+    "withdrawal_period_expired",
+    "receipt_rate_limited",
 ];
 export const TERMINATION_TEXTS = {
     de: {
@@ -46,6 +48,8 @@ export const TERMINATION_TEXTS = {
             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",
@@ -125,6 +129,8 @@ export const TERMINATION_TEXTS = {
             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/dist/billing-foundation/consumer-protection/withdrawal-period.d.ts

@@ -0,0 +1,10 @@
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+export declare const WITHDRAWAL_PERIOD_DAYS = 14;
+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 declare function isWithinWithdrawalPeriod(events: readonly PeriodStartEvent[], now: Temporal.Instant): boolean;
+export {};

package/dist/billing-foundation/consumer-protection/withdrawal-period.js

@@ -0,0 +1,26 @@
+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 = new Set([
+    CHECKOUT_CONSENT_RECORDED_EVENT_QN,
+    SUBSCRIPTION_CREATED_EVENT_QN,
+]);
+/** 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, now) {
+    let latestStart;
+    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;
+}

package/dist/billing-foundation/handlers/create-checkout-session.write.js

@@ -21,10 +21,10 @@
 // billing-foundation:write:switch-plan instead. Plan-driven callers should
 // prefer start-plan-checkout/switch-plan over calling this handler with a
 // hand-picked priceId.
-import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { InternalError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { assertCheckoutAllowed, openCheckout, startProviderCheckout, } from "../checkout-core.js";
-import { consentCheckoutFields, consentPayloadSchema, prepareConsent, recordConsent, } from "../consumer-protection/consent-gate.js";
+import { assertValidOrderItem, consentCheckoutFields, consentPayloadSchema, prepareConsent, recordConsent, } from "../consumer-protection/consent-gate.js";
 const createCheckoutSessionSchema = z.object({
     /** Welcher Provider — entityName eines registrierten subscription-
      *  Plugins ("stripe" / "paypal" / ...). */
@@ -75,10 +75,11 @@ export function createCheckoutSessionHandler(options) {
             }
             const mode = payload.mode ?? "subscription";
             const plugin = await assertCheckoutAllowed(ctx, openOptions, checkoutInput);
-            const price = await lookupPrice(ctx, plugin, payload.priceId);
+            const price = await lookupPrice(ctx, plugin, payload.providerName, payload.priceId);
             const orderItem = mode === "payment"
                 ? await consumerProtection.oneOffItemLabel?.(ctx, payload.priceId)
                 : undefined;
+            assertValidOrderItem(orderItem, payload.priceId);
             const consent = await prepareConsent(ctx, consumerProtection, payload.consent, mode);
             const result = await startProviderCheckout(ctx, plugin, {
                 ...checkoutInput,
@@ -99,10 +100,15 @@ export function createCheckoutSessionHandler(options) {
 }
 // The price is part of the consent record, so it must be known before the
 // buyer is sent to the provider.
-async function lookupPrice(ctx, plugin, priceId) {
+async function lookupPrice(ctx, plugin, providerName, priceId) {
+    if (!plugin.retrievePrices) {
+        throw new InternalError({
+            message: `billing-foundation: provider "${providerName}" lacks retrievePrices, required by consumerProtection`,
+        });
+    }
     let price;
     try {
-        const prices = (await plugin.retrievePrices?.(ctx, [priceId])) ?? [];
+        const prices = await plugin.retrievePrices(ctx, [priceId]);
         price = prices.find((p) => p.priceId === priceId);
     }
     catch (cause) {