@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

package/packages/bundled-features/src/auth-foundation/types.ts

@@ -48,10 +48,10 @@ export type AuthProviderPlugin = {
 
 export function isValidTokenShape(shape: unknown): shape is TokenShape {
   if (typeof shape !== "object" || shape === null || !("kind" in shape)) return false;
-  const kind = (shape as { kind: unknown }).kind;
+  const kind = shape.kind;
   if (kind === "jwt") return true;
   if (kind === "prefix") {
-    const prefix = "prefix" in shape ? (shape as { prefix: unknown }).prefix : undefined;
+    const prefix = "prefix" in shape ? shape.prefix : undefined;
     return typeof prefix === "string" && prefix.length > 0;
   }
   return false;
@@ -64,9 +64,9 @@ export function isAuthProviderPlugin(o: unknown): o is AuthProviderPlugin {
     typeof o === "object" &&
     o !== null &&
     "build" in o &&
-    typeof (o as { build: unknown }).build === "function" &&
+    typeof o.build === "function" &&
     "shape" in o &&
-    isValidTokenShape((o as { shape: unknown }).shape)
+    isValidTokenShape(o.shape)
   );
 }
 
@@ -105,12 +105,7 @@ export type SessionStoreProvider = {
 };
 
 export function isSessionStoreProvider(o: unknown): o is SessionStoreProvider {
-  return (
-    typeof o === "object" &&
-    o !== null &&
-    "build" in o &&
-    typeof (o as { build: unknown }).build === "function"
-  );
+  return typeof o === "object" && o !== null && "build" in o && typeof o.build === "function";
 }
 
 // Tenant-resolution extension points (#1373). Both are single-provider and
@@ -154,19 +149,14 @@ export function isTenantResolverProvider(o: unknown): o is TenantResolverProvide
     typeof o === "object" &&
     o !== null &&
     "build" in o &&
-    typeof (o as { build: unknown }).build === "function" &&
+    typeof o.build === "function" &&
     "trust" in o &&
-    isTenantResolverTrust((o as { trust: unknown }).trust)
+    isTenantResolverTrust(o.trust)
   );
 }
 
 export function isTenantExistenceProvider(o: unknown): o is TenantExistenceProvider {
-  return (
-    typeof o === "object" &&
-    o !== null &&
-    "build" in o &&
-    typeof (o as { build: unknown }).build === "function"
-  );
+  return typeof o === "object" && o !== null && "build" in o && typeof o.build === "function";
 }
 
 // r.useExtension options-shape for auth-foundation's four extension points.

package/packages/bundled-features/src/auth-mfa/feature.ts

@@ -53,11 +53,9 @@ export function bindMfaRevokeAllOtherSessionsFromFeature(
 ): BindMfaRevokeAllOtherSessions | undefined {
   const exports = feature.exports;
   if (exports && typeof exports === "object" && "bindRevokeAllOtherSessions" in exports) {
-    const { bindRevokeAllOtherSessions } = exports as {
-      bindRevokeAllOtherSessions: unknown;
-    };
+    const { bindRevokeAllOtherSessions } = exports;
     if (typeof bindRevokeAllOtherSessions === "function") {
-      // @cast-boundary exports-walk — feature.exports is untyped by design
+      // @cast-boundary feature-exports — feature.exports is untyped by design
       return bindRevokeAllOtherSessions as BindMfaRevokeAllOtherSessions;
     }
   }
@@ -71,9 +69,9 @@ export function mfaStatusCheckerFromFeature(
 ): MfaStatusChecker | undefined {
   const exports = feature.exports;
   if (exports && typeof exports === "object" && "checkMfaStatus" in exports) {
-    const { checkMfaStatus } = exports as { checkMfaStatus: unknown };
+    const { checkMfaStatus } = exports;
     if (typeof checkMfaStatus === "function") {
-      // @cast-boundary exports-walk — feature.exports is untyped by design
+      // @cast-boundary feature-exports — feature.exports is untyped by design
       return checkMfaStatus as MfaStatusChecker;
     }
   }
@@ -87,9 +85,9 @@ export function mfaStatusCheckerFromFeature(
 export function mfaVerifierFromFeature(feature: FeatureDefinition): MfaCodeVerifier | undefined {
   const exports = feature.exports;
   if (exports && typeof exports === "object" && "verifyMfaCode" in exports) {
-    const { verifyMfaCode } = exports as { verifyMfaCode: unknown };
+    const { verifyMfaCode } = exports;
     if (typeof verifyMfaCode === "function") {
-      // @cast-boundary exports-walk — feature.exports is untyped by design
+      // @cast-boundary feature-exports — feature.exports is untyped by design
       return verifyMfaCode as MfaCodeVerifier;
     }
   }
@@ -107,9 +105,9 @@ export function bindRevokeAllPatTokensFromFeature(
 ): BindRevokeAllPatTokens | undefined {
   const exports = feature.exports;
   if (exports && typeof exports === "object" && "bindRevokeAllPatTokens" in exports) {
-    const { bindRevokeAllPatTokens } = exports as { bindRevokeAllPatTokens: unknown };
+    const { bindRevokeAllPatTokens } = exports;
     if (typeof bindRevokeAllPatTokens === "function") {
-      // @cast-boundary exports-walk — feature.exports is untyped by design
+      // @cast-boundary feature-exports — feature.exports is untyped by design
       return bindRevokeAllPatTokens as BindRevokeAllPatTokens;
     }
   }

package/packages/bundled-features/src/auth-mfa/hmac-token-codec.ts

@@ -1,5 +1,6 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 
 function hmacSign(input: string, secret: string): string {
   return createHmac("sha256", secret).update(input).digest("base64url");
@@ -20,11 +21,10 @@ export function createHmacTokenCodec<
   function splitEncodedBody(
     value: unknown,
   ): { readonly payload: TPayload; readonly expiresAtMs: number } | null {
-    if (typeof value !== "object" || value === null) return null;
-    const v = value as Record<string, unknown>;
-    const expiresAtMs = v["expiresAtMs"];
+    if (!isPlainObject(value)) return null;
+    const expiresAtMs = value["expiresAtMs"];
     if (typeof expiresAtMs !== "number") return null;
-    const { expiresAtMs: _drop, ...rest } = v;
+    const { expiresAtMs: _drop, ...rest } = value;
     return isPayload(rest) ? { payload: rest, expiresAtMs } : null;
   }
 

package/packages/bundled-features/src/auth-mfa/mfa-challenge-token.ts

@@ -1,5 +1,6 @@
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { createHmacTokenCodec, type HmacTokenVerifyResult } from "./hmac-token-codec.js";
 
 export type MfaChallengePayload = {
@@ -8,9 +9,8 @@ export type MfaChallengePayload = {
 };
 
 function isPayload(value: unknown): value is MfaChallengePayload {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value as Record<string, unknown>;
-  return typeof v["userId"] === "string" && typeof v["tenantId"] === "string";
+  if (!isPlainObject(value)) return false;
+  return typeof value["userId"] === "string" && typeof value["tenantId"] === "string";
 }
 
 // Domain-separated from mfa-preauth-setup (see hmac-token-codec). Single-use is

package/packages/bundled-features/src/auth-mfa/mfa-preauth-setup-token.ts

@@ -1,5 +1,6 @@
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { createHmacTokenCodec, type HmacTokenVerifyResult } from "./hmac-token-codec.js";
 
 export type MfaPreauthSetupPayload = {
@@ -8,9 +9,8 @@ export type MfaPreauthSetupPayload = {
 };
 
 function isPayload(value: unknown): value is MfaPreauthSetupPayload {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value as Record<string, unknown>;
-  return typeof v["userId"] === "string" && typeof v["tenantId"] === "string";
+  if (!isPlainObject(value)) return false;
+  return typeof value["userId"] === "string" && typeof value["tenantId"] === "string";
 }
 
 // Domain "mfa-preauth-setup" must never equal the challenge domain: a setup

package/packages/bundled-features/src/auth-mfa/mfa-setup-token.ts

@@ -11,6 +11,7 @@
 // generated secret material, not just re-derive it from a lookup.
 import { createHmac, timingSafeEqual } from "node:crypto";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 
 export type MfaSetupPayload = {
   readonly userId: string;
@@ -47,15 +48,14 @@ export type VerifyMfaSetupResult =
   | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
 
 function isEncodedBody(value: unknown): value is EncodedBody {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value as Record<string, unknown>;
+  if (!isPlainObject(value)) return false;
   return (
-    typeof v["userId"] === "string" &&
-    typeof v["totpSecretBase32"] === "string" &&
-    Array.isArray(v["recoveryCodeHashes"]) &&
-    v["recoveryCodeHashes"].every((h) => typeof h === "string") &&
-    typeof v["expiresAtMs"] === "number" &&
-    (v["tenantId"] === undefined || typeof v["tenantId"] === "string")
+    typeof value["userId"] === "string" &&
+    typeof value["totpSecretBase32"] === "string" &&
+    Array.isArray(value["recoveryCodeHashes"]) &&
+    value["recoveryCodeHashes"].every((h) => typeof h === "string") &&
+    typeof value["expiresAtMs"] === "number" &&
+    (value["tenantId"] === undefined || typeof value["tenantId"] === "string")
   );
 }
 

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

@@ -1,4 +1,47 @@
 [
+  {
+    "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",
+    "title": "Contract confirmation and termination mails use template variables",
+    "detail": "contract-confirmation, contract-termination-receipt and contract-termination-operator-notice are r.notification declarations with variables and localized templates (de, en). The notification types are qualified names now (billing-foundation:notify:<name>). The notify data is the template variable object (subject, details, contractLines, termsParagraphs, operatorEmail), not sections.",
+    "migration": "Update delivery preferences and tests that referenced the old type strings, and anything that listens to the notification data. An app that mounts it without includeBundled needs template-resolver, renderer-foundation and @cosmicdrift/kumiko-renderer-mail-html at boot (composeRendererStack() from dev-server mounts all of them), plus a delivery with the channel-email feature; apps without the template tables need a schema migration (`kumiko schema generate`)."
+  },
   {
     "version": "0.354.0",
     "type": "breaking",

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

@@ -1,6 +1,7 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
 // @runtime client
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 
 // Feature name
 export const BILLING_FOUNDATION_FEATURE = "billing-foundation" as const;
@@ -11,14 +12,14 @@ export const SUBSCRIPTION_PROVIDER_EXTENSION = "subscriptionProvider" as const;
 
 /** delivery notification type of the § 312f contract confirmation mail. */
 export const CONTRACT_CONFIRMATION_NOTIFICATION_TYPE =
-  "billing-foundation:contract-confirmation" as const;
+  "billing-foundation:notify:contract-confirmation" as const;
 
 /** delivery notification types of the § 312k termination receipt and the
  *  operator notice. */
 export const CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE =
-  "billing-foundation:contract-termination-receipt" as const;
+  "billing-foundation:notify:contract-termination-receipt" as const;
 export const CONTRACT_TERMINATION_OPERATOR_NOTIFICATION_TYPE =
-  "billing-foundation:contract-termination-operator-notice" as const;
+  "billing-foundation:notify:contract-termination-operator-notice" as const;
 
 // Qualified write handler names (QN format: scope:type:name).
 export const SubscriptionFoundationHandlers = {
@@ -230,5 +231,5 @@ export const TERMINATION_SCOPES = ["tenant-host", "platform"] as const;
 export type TerminationScope = (typeof TERMINATION_SCOPES)[number];
 
 export function isTerminationScope(value: unknown): value is TerminationScope {
-  return (TERMINATION_SCOPES as readonly unknown[]).includes(value);
+  return isOneOf(TERMINATION_SCOPES, value);
 }

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

@@ -1,6 +1,12 @@
+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 { CONSENT_TEXTS, type ConsentLocale, resolveConsentLocale } from "./consent-text.js";
+import { type ConsentLocale, resolveConsentLocale } from "./consent-text.js";
 
 // Inline de/en like the consent texts: the confirmation repeats the legal
 // wording the buyer agreed to, so it cannot follow the en-only i18n convention.
@@ -22,7 +28,7 @@ type ConfirmationLabels = {
   readonly every: string;
 };
 
-const LABELS: Readonly<Record<ConsentLocale, ConfirmationLabels>> = {
+export const CONFIRMATION_LABELS: Readonly<Record<ConsentLocale, ConfirmationLabels>> = {
   de: {
     subject: "Vertragsbestätigung",
     intro:
@@ -71,19 +77,17 @@ const LABELS: Readonly<Record<ConsentLocale, ConfirmationLabels>> = {
   },
 };
 
-export type ContractConfirmationSection =
-  | { readonly text: string }
-  | { readonly heading: string }
-  | { readonly markdown: string };
+type TextRow = { readonly text: string };
 
-export type ContractConfirmationContent = {
-  readonly subject: string;
-  readonly header: string;
-  readonly sections: readonly ContractConfirmationSection[];
-  readonly footer: string;
+/** Variables of the contract confirmation template. */
+export type ContractConfirmationVariables = {
+  readonly contractLines: readonly TextRow[];
+  readonly consentGivenAt: string;
+  readonly termsParagraphs: readonly TextRow[];
+  readonly operatorEmail: string;
 };
 
-export type RenderContractConfirmationArgs = {
+export type ContractConfirmationArgs = {
   readonly consent: CheckoutConsentRecordedPayload;
   readonly timeZone: string;
   /** Translated plan name; falls back to the raw tier. */
@@ -99,7 +103,7 @@ export type RenderContractConfirmationArgs = {
 };
 
 function formatPrice(consent: CheckoutConsentRecordedPayload, locale: ConsentLocale): string {
-  const labels = LABELS[locale];
+  const labels = CONFIRMATION_LABELS[locale];
   if (consent.unitAmount === null || consent.currency === null) return "-";
   let amount: string;
   try {
@@ -140,45 +144,87 @@ function formatDate(iso: string, locale: ConsentLocale, timeZone: string): strin
   }).format(epochMilliseconds);
 }
 
-/** Structured mail content (header/sections/footer) for the email channel's
- *  renderer; the renderer owns HTML escaping, this only builds plain text. */
-export function renderContractConfirmation(
-  args: RenderContractConfirmationArgs,
-): ContractConfirmationContent {
+// 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 inlineHtmlMarkdown
+    .parse(markdown, { async: false })
+    .split(/\n\s*\n/)
+    .map((row) => row.replace(/\s+/g, " ").trim())
+    .filter((row) => row.length > 0)
+    .map((text) => ({ text }));
+}
+
+export function contractConfirmationVariables(
+  args: ContractConfirmationArgs,
+): ContractConfirmationVariables {
   const locale = resolveConsentLocale(args.consent.locale);
-  const labels = LABELS[locale];
-  const texts = CONSENT_TEXTS[locale];
-  const { consent } = args;
+  const labels = CONFIRMATION_LABELS[locale];
+  const { consent, timeZone } = args;
 
-  const { timeZone } = args;
   const subjectLine =
     consent.mode === "payment"
       ? `${labels.item}: ${args.itemLabel ?? labels.oneOffPayment}`
       : `${labels.plan}: ${args.tierLabel ?? consent.tier ?? labels.oneOffPayment}`;
-  const contractLines = [
-    subjectLine,
-    `${labels.price}: ${formatPrice(consent, locale)}`,
-    `${labels.contractStart}: ${formatDate(args.contractStartIso, locale, timeZone)}`,
-    ...(args.currentPeriodEndIso !== undefined
-      ? [`${labels.currentPeriodEnd}: ${formatDate(args.currentPeriodEndIso, locale, timeZone)}`]
-      : []),
-  ];
   const vatNote = args.vatNote[locale] ?? args.vatNote[resolveConsentLocale()];
 
   return {
-    subject: labels.subject,
-    header: labels.subject,
-    sections: [
-      { text: labels.intro },
-      ...contractLines.map((text) => ({ text })),
-      ...(vatNote !== undefined ? [{ text: vatNote }] : []),
-      { heading: labels.consentHeading },
-      { text: texts.earlyPerformance },
-      { text: texts.withdrawalLoss },
-      { text: `${labels.consentGivenAt}: ${formatDate(args.consentGivenAtIso, locale, timeZone)}` },
-      { heading: labels.termsHeading },
-      { markdown: args.termsContent },
-    ],
-    footer: `${labels.contact} ${args.operatorEmail}`,
+    contractLines: [
+      subjectLine,
+      `${labels.price}: ${formatPrice(consent, locale)}`,
+      `${labels.contractStart}: ${formatDate(args.contractStartIso, locale, timeZone)}`,
+      ...(args.currentPeriodEndIso !== undefined
+        ? [`${labels.currentPeriodEnd}: ${formatDate(args.currentPeriodEndIso, locale, timeZone)}`]
+        : []),
+      ...(vatNote !== undefined ? [vatNote] : []),
+    ].map((text) => ({ text })),
+    consentGivenAt: formatDate(args.consentGivenAtIso, locale, timeZone),
+    termsParagraphs: termsParagraphsOf(args.termsContent),
+    operatorEmail: args.operatorEmail,
   };
 }

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/issue-confirmation.ts

@@ -27,7 +27,7 @@ import {
   SUBSCRIPTION_AGGREGATE_TYPE,
 } from "../events.js";
 import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from "../types.js";
-import { renderContractConfirmation } from "./confirmation-mail.js";
+import { contractConfirmationVariables } from "./confirmation-mail.js";
 import { resolveConsentLocale } from "./consent-text.js";
 
 export const issueContractConfirmationSchema = z
@@ -185,7 +185,7 @@ export function createIssueContractConfirmationHandler(
           : undefined;
 
       const issuedAtIso = options.now().toString();
-      const content = renderContractConfirmation({
+      const variables = contractConfirmationVariables({
         consent,
         timeZone: pickTimeZone(recipient.data.timezone, ctx.tz.tenant),
         ...(tierLabel !== undefined && { tierLabel }),
@@ -220,7 +220,7 @@ export function createIssueContractConfirmationHandler(
 
       await ctx.notify(CONTRACT_CONFIRMATION_NOTIFICATION_TYPE, {
         route: { email: recipient.data.email },
-        data: content,
+        data: variables,
         locale,
         priority: "critical",
       });

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

@@ -0,0 +1,118 @@
+import {
+  type FeatureRegistrar,
+  type NotificationLocalizedTemplate,
+  type TemplateVariables,
+  templateVariable,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { mailHeading, mailParagraph, mailRepeatedRows } from "../../shared/index.js";
+import { CONFIRMATION_LABELS } from "./confirmation-mail.js";
+import { CONSENT_LOCALES, CONSENT_TEXTS, type ConsentLocale } from "./consent-text.js";
+import { TERMINATION_TEXTS } from "./termination-texts.js";
+
+// Slot syntax for the translated texts: `{name}` becomes a template variable.
+const OPERATOR_EMAIL_SLOT = "{operatorEmail}";
+
+const textRows = (): TemplateVariables[string] =>
+  templateVariable.list({ text: templateVariable.text({ required: true }) }, { required: true });
+
+export const TERMINATION_RECEIPT_VARIABLES: TemplateVariables = {
+  subject: templateVariable.text({ required: true }),
+  receivedAt: templateVariable.text({ required: true }),
+  requestId: templateVariable.text({ required: true }),
+  details: textRows(),
+  operatorEmail: templateVariable.text({ required: true }),
+};
+
+export const OPERATOR_NOTICE_VARIABLES: TemplateVariables = {
+  subject: templateVariable.text({ required: true }),
+  lines: textRows(),
+  operatorEmail: templateVariable.text({ required: true }),
+};
+
+export const CONTRACT_CONFIRMATION_VARIABLES: TemplateVariables = {
+  contractLines: textRows(),
+  consentGivenAt: templateVariable.text({ required: true }),
+  termsParagraphs: templateVariable.list(
+    { text: templateVariable.richText({ required: true }) },
+    { required: true },
+  ),
+  operatorEmail: templateVariable.text({ required: true }),
+};
+
+function perLocale(
+  build: (locale: ConsentLocale) => { body: string; subject: string },
+): NotificationLocalizedTemplate {
+  return Object.fromEntries(
+    CONSENT_LOCALES.map((locale) => {
+      const { body, subject } = build(locale);
+      return [locale, { body, meta: { subject, category: "transactional" as const } }];
+    }),
+  );
+}
+
+export function terminationReceiptTemplate(): NotificationLocalizedTemplate {
+  return perLocale((locale) => {
+    const texts = TERMINATION_TEXTS[locale];
+    return {
+      subject: "{{subject}}",
+      body: [
+        mailParagraph(texts.receiptGreeting),
+        mailParagraph(texts.receiptIntro),
+        mailParagraph(`${texts.receivedAt}: {receivedAt}`),
+        mailParagraph(`${texts.requestId}: {requestId}`),
+        mailRepeatedRows("details", "text"),
+        mailParagraph(texts.receiptNextSteps),
+        mailParagraph(texts.receiptRevoke(OPERATOR_EMAIL_SLOT)),
+        mailParagraph(`${texts.contact} {operatorEmail}`),
+      ].join(""),
+    };
+  });
+}
+
+export function operatorNoticeTemplate(): NotificationLocalizedTemplate {
+  return perLocale((locale) => ({
+    subject: "{{subject}}",
+    body: [
+      mailParagraph(TERMINATION_TEXTS[locale].operatorIntro),
+      mailRepeatedRows("lines", "text"),
+      mailParagraph("{operatorEmail}"),
+    ].join(""),
+  }));
+}
+
+export function contractConfirmationTemplate(): NotificationLocalizedTemplate {
+  return perLocale((locale) => {
+    const labels = CONFIRMATION_LABELS[locale];
+    const consent = CONSENT_TEXTS[locale];
+    return {
+      subject: labels.subject,
+      body: [
+        mailParagraph(labels.intro),
+        mailRepeatedRows("contractLines", "text"),
+        mailHeading(labels.consentHeading),
+        mailParagraph(consent.earlyPerformance),
+        mailParagraph(consent.withdrawalLoss),
+        mailParagraph(`${labels.consentGivenAt}: {consentGivenAt}`),
+        mailHeading(labels.termsHeading),
+        mailRepeatedRows("termsParagraphs", "text"),
+        mailParagraph(`${labels.contact} {operatorEmail}`),
+      ].join(""),
+    };
+  });
+}
+
+// The registered notification names are the tail of the QN types in constants.ts.
+export function registerConsumerProtectionMails(r: FeatureRegistrar): void {
+  r.notification("contract-confirmation", {
+    variables: CONTRACT_CONFIRMATION_VARIABLES,
+    localizedTemplate: contractConfirmationTemplate,
+  });
+  r.notification("contract-termination-receipt", {
+    variables: TERMINATION_RECEIPT_VARIABLES,
+    localizedTemplate: terminationReceiptTemplate,
+  });
+  r.notification("contract-termination-operator-notice", {
+    variables: OPERATOR_NOTICE_VARIABLES,
+    localizedTemplate: operatorNoticeTemplate,
+  });
+}