@cosmicdrift/kumiko-samples 0.363.0 → 0.364.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.363.0",
+  "version": "0.364.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.363.0",
+  "version": "0.364.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -106,6 +106,7 @@
     "./shared/single-use-token-store": "./src/shared/single-use-token-store.ts",
     "./shared/signed-token": "./src/shared/signed-token.ts",
     "./shared/row-bound-grant": "./src/shared/row-bound-grant.ts",
+    "./shared/mail-template-body": "./src/shared/mail-template-body.ts",
     "./delivery": "./src/delivery/index.ts",
     "./delivery/web": "./src/delivery/web/index.ts",
     "./channel-in-app": "./src/channel-in-app/index.ts",
@@ -180,6 +181,7 @@
     "pdf-lib": "^1.17.1",
     "qrcode": "^1.5.4",
     "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "sharp": "^0.35.5",
     "stripe": "^22.6.2",
     "tailwind-merge": "^3.6.0",
@@ -527,6 +529,10 @@
         "types": "./dist/shared/row-bound-grant.d.ts",
         "default": "./dist/shared/row-bound-grant.js"
       },
+      "./shared/mail-template-body": {
+        "types": "./dist/shared/mail-template-body.d.ts",
+        "default": "./dist/shared/mail-template-body.js"
+      },
       "./delivery": {
         "types": "./dist/delivery/index.d.ts",
         "default": "./dist/delivery/index.js"

package/packages/bundled-features/src/audit/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Audit list pages by id unless sorted by type",
+    "detail": "An explicit createdAt sort pages in id order so keyset pagination no longer skips rows."
+  },
   {
     "version": "0.361.0",
     "type": "fix",

package/packages/bundled-features/src/audit/handlers/list.query.ts

@@ -117,11 +117,16 @@ export const listQuery = defineQueryHandler({
       createdAt: unknown;
       createdBy: string;
     }>(ctx.db, eventsTable, where, {
-      // `id` as tie-breaker keeps the order total, so pages never overlap.
-      orderBy: [
-        { col: p.sort === "type" ? "type" : "createdAt", direction },
-        { col: "id", direction },
-      ],
+      // The id cursor only resumes an id-ordered listing. created_at comes from the
+      // transaction start and can run against insert order, so ordering by it would let
+      // a page boundary skip rows; only the type sort leaves id order (and is one page).
+      orderBy:
+        p.sort === "type"
+          ? [
+              { col: "type", direction },
+              { col: "id", direction },
+            ]
+          : [{ col: "id", direction }],
       limit: p.limit,
     });
 

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

@@ -7,23 +7,26 @@
 
 import {
   makeDispatchSystemWrite,
-  type SystemDispatchArgs,
+  makeDispatchWriteAs,
+  type RoleDispatchArgs,
 } from "@cosmicdrift/kumiko-framework/api";
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import {
   ConfigScopes,
   createSystemUser,
+  type Registry,
   type TenantId,
   type WriteResult,
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { Dispatcher } from "@cosmicdrift/kumiko-framework/pipeline";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import type { Redis } from "ioredis";
 // kumiko-lint-ignore cross-feature-import bootstrap sets per-tenant config through the config feature's write handler
 import { ConfigHandlers } from "../config/constants.js";
 // kumiko-lint-ignore cross-feature-import bootstrap compares against the stored config row to stay idempotent
-import { findConfigRow } from "../config/write-helpers.js";
+import { configRowHoldsValue, findConfigRow } from "../config/write-helpers.js";
 // kumiko-lint-ignore cross-feature-import bootstrap provisions tenant + invitation rows owned by the tenant feature
 import { TenantHandlers } from "../tenant/constants.js";
 // kumiko-lint-ignore cross-feature-import bootstrap provisions tenant + invitation rows owned by the tenant feature
@@ -55,9 +58,7 @@ export type BootstrapSeedDeps = {
   /** Writes as the system user with the given tenant roles in the seeded
    *  tenant; use it when the app gates tenant data on its own roles rather
    *  than SystemAdmin. */
-  readonly dispatchWriteAs: (
-    args: Pick<SystemDispatchArgs, "handlerQn" | "payload"> & { readonly roles: readonly string[] },
-  ) => Promise<WriteResult>;
+  readonly dispatchWriteAs: (args: Omit<RoleDispatchArgs, "tenantId">) => Promise<WriteResult>;
 };
 
 export type BootstrapConfigValue = string | number | boolean;
@@ -96,6 +97,10 @@ export type BootstrapDeps = {
   readonly db: DbConnection;
   readonly redis: Redis;
   readonly dispatcher: Dispatcher;
+  /** With these, a rerun can compare `encrypted`/`piiEncrypted` config keys by
+   *  their decrypted value; without them such keys are rewritten on every run. */
+  readonly registry?: Registry;
+  readonly configCipher?: EnvelopeCipher;
 };
 
 export type BootstrapTenantOutcome = "created" | "exists";
@@ -216,7 +221,18 @@ async function applyTenantConfig(
   const applied: string[] = [];
   for (const [key, value] of Object.entries(tenant.config ?? {})) {
     const existing = await findConfigRow(deps.db, key, tenant.id, null);
-    if (existing?.value === JSON.stringify(value)) continue;
+    const serialized = JSON.stringify(value);
+    if (
+      await configRowHoldsValue(
+        existing,
+        deps.registry?.getConfigKey(key),
+        deps.configCipher,
+        key,
+        serialized,
+      )
+    ) {
+      continue;
+    }
     const result = await deps.dispatcher.write(
       ConfigHandlers.set,
       { key, value, scope: ConfigScopes.tenant },
@@ -266,6 +282,11 @@ async function decideInvite(
     return "role-mismatch";
   }
   if (invitation.status === INVITATION_STATUS.accepted) return "active";
+  // The plan dropped a global role (e.g. an admin moved to tenants[].invites):
+  // the stored invitation would still grant it on accept, so it is re-issued.
+  if (storedGlobalRoles.some((role) => !invite.globalRoles.some((planned) => planned === role))) {
+    return "resent";
+  }
   if (await hasLiveInviteToken(deps.redis, invitation.id)) return "pending";
   return "resent";
 }
@@ -280,6 +301,7 @@ export async function bootstrapTenants(
 ): Promise<BootstrapReport> {
   const plannedInvites = planInvites(plan);
   const dispatchSystemWrite = makeDispatchSystemWrite(deps.dispatcher);
+  const dispatchWriteAsRoles = makeDispatchWriteAs(deps.dispatcher);
 
   const tenants: Array<BootstrapReport["tenants"][number]> = [];
   for (const tenant of plan.tenants) {
@@ -290,8 +312,7 @@ export async function bootstrapTenants(
         tenantId: tenant.id,
         db: deps.db,
         dispatchSystemWrite,
-        dispatchWriteAs: ({ handlerQn, payload, roles }) =>
-          deps.dispatcher.write(handlerQn, payload, createSystemUser(tenant.id, roles)),
+        dispatchWriteAs: (args) => dispatchWriteAsRoles({ ...args, tenantId: tenant.id }),
       });
     }
     const configApplied = await applyTenantConfig(deps, tenant);

package/packages/bundled-features/src/auth-email-password/changes.json

@@ -1,4 +1,41 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "A loginUrl builder that throws no longer crashes the app tree",
+    "detail": "The auth gate resolves the login redirect once per location change and, when the builder returns an invalid URL or throws, logs the error and shows the built-in login screen instead of throwing during render."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "How to send an auth mail after the render*Email helpers were removed in 0.363.0",
+    "detail": "No runtime change. The 0.363.0 breaking entry lists renderActivationEmail, renderResetPasswordEmail, renderUnlockAccountEmail, renderVerifyEmail and renderInviteEmail as removed but does not say how app code that rendered one of these mails itself now sends it. This entry adds that recipe.",
+    "migration": "App code that rendered an auth mail itself and passed the result as `data`, for example `notify(\"auth-email-password:signup-activation\", { route: { email }, data: renderActivationEmail({ url, expiresAt, locale, appName }), priority: \"critical\" })`, breaks twice since 0.363.0: the helper is gone and the notification type is now `auth-email-password:notify:signup-activation`. The stored template renders subject and body; the app only passes template variables.\nFor a signup activation link, call `issueSignupActivation({ redis, notify: ctx.notify, email, appUrl, appName, locale, timeZone, tokenTtlMinutes, onTokenStored })` from `@cosmicdrift/kumiko-bundled-features/auth-email-password` (only redis, notify, email and appUrl are required). It drops any live signup token for the email, stores a new one under the keys signup-confirm reads and sends the mail. `appUrl` is the bare activation page; a function `(locale) => url` picks the page per locale.\nIf the app stores the token itself and only needs the mail, call `ctx.notify(AuthMailNotificationTypes.signupActivation, { route: { email }, data: { appName, actionUrl, validFor, validUntil }, locale, priority: \"critical\" })`. `AuthMailNotificationTypes` comes from `@cosmicdrift/kumiko-bundled-features/auth-email-password`. All four variables are required strings: ctx.notify checks them against the declared template variables and throws an InternalError on a missing or invalid one, which fails the write. `actionUrl` is the page URL with `token=<encodeURIComponent(token)>` appended as a query parameter and must be an http, https or mailto URL. `validFor` and `validUntil` come from `tokenMailExpiry({ expiresAt, issuedAt, timeZone }, locale)` in `@cosmicdrift/kumiko-bundled-features/auth-email-password/email-templates`. Only send a `locale` that has a template for the type, because the renderer has no locale fallback and a locale without a template sends nothing: use `resolveMailLocale(locale)` when `hasMailTranslationKey(resolveMailLocale(locale), \"auth.mail.activation.subject\")` is true (both from `@cosmicdrift/kumiko-framework/i18n`), otherwise `\"en\"`. The other mails use the subject keys `auth.mail.reset.subject`, `auth.mail.unlock.subject`, `auth.mail.verify.subject` and `auth.mail.invite.subject`.\nThe other auth mails work the same way with `AuthMailNotificationTypes.passwordReset`, `.accountUnlock`, `.emailVerification` and `.invite`; the invite mail also needs a `role` variable."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "seedAdminGuarded rewrites the admin email only when its blind index is missing or stale",
+    "detail": "rewriteSeededUserEmail returns early when the stored email blind index already matches the expected value, so repeated boots no longer re-encrypt the email and grow the user event stream. The row version is now checked with a type guard instead of a cast."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Bootstrap reruns no longer rewrite encrypted config or restore dropped global roles",
+    "detail": "Declarative bootstrap compares encrypted and piiEncrypted config keys by their decrypted value, so a matching rerun writes nothing, and re-issues an invitation whose stored global roles are no longer in the plan. makeDispatchWriteAs is exported from the framework api."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Email payload buckets ignore plus-tags and case; auth requests are capped at 3 per 15 minutes",
+    "detail": "additionalRateLimits accepts normalize: email, which lowercases and strips the plus-tag before hashing, and bucket keys are scoped by tenant and handler. Signup and token requests (reset, unlock, verification) and the waitlist default use it with a 3-request, 900-second window."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Password change and logout work for members with only an app role or TenantAdmin",
+    "detail": "Both handlers required User, Admin or SystemAdmin and answered 403 access_denied for invited members holding a single custom role. They are now open to every signed-in user, like the other self-service handlers; anonymous callers are still rejected."
+  },
   {
     "version": "0.363.0",
     "type": "breaking",

package/packages/bundled-features/src/auth-email-password/email-rate-limits.ts

@@ -0,0 +1,16 @@
+import type { PayloadRateLimitOption } from "@cosmicdrift/kumiko-types/handlers";
+
+// The bucket counts across all IPs, so a long window would let an attacker who
+// knows an address lock its owner out of recovery/signup for the whole window.
+// A short one still throttles mail bombing but clears within minutes.
+export const AUTH_EMAIL_RATE_LIMIT_WINDOW_SECONDS = 15 * 60;
+export const AUTH_EMAIL_RATE_LIMIT_MAX_REQUESTS = 3;
+
+export const AUTH_EMAIL_PAYLOAD_RATE_LIMITS: readonly PayloadRateLimitOption[] = [
+  {
+    per: { payloadField: "email" },
+    limit: AUTH_EMAIL_RATE_LIMIT_MAX_REQUESTS,
+    windowSeconds: AUTH_EMAIL_RATE_LIMIT_WINDOW_SECONDS,
+    normalize: "email",
+  },
+];

package/packages/bundled-features/src/auth-email-password/handlers/change-password.write.ts

@@ -1,5 +1,4 @@
 import {
-  access,
   createSystemUser,
   defineWriteHandler,
   SYSTEM_TENANT_ID,
@@ -20,7 +19,12 @@ export const changePasswordWrite = defineWriteHandler({
     oldPassword: z.string().min(1),
     newPassword: passwordSchema,
   }),
-  access: { roles: access.authenticated },
+  access: {
+    openToAll: {
+      reason:
+        "Self-service: acts only on event.user.id and re-checks the caller's current password; invited members hold only an app role, so a fixed role list would lock them out.",
+    },
+  },
   escapeHatch: {
     grants: ["systemIdentity"],
     reason:

package/packages/bundled-features/src/auth-email-password/handlers/logout.write.ts

@@ -1,4 +1,4 @@
-import { access, defineWriteHandler, stepsPipeline } from "@cosmicdrift/kumiko-framework/engine";
+import { defineWriteHandler, stepsPipeline } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 
 // Logout — JWT is stateless, so server-side we only return OK. A future
@@ -7,7 +7,12 @@ import * as z from "zod";
 export const logoutWrite = defineWriteHandler({
   name: "logout",
   schema: z.object({}),
-  access: { roles: access.authenticated },
+  access: {
+    openToAll: {
+      reason:
+        "Self-service: touches no data, any signed-in member must be able to sign out regardless of which role they hold.",
+    },
+  },
   description:
     "Acknowledges a sign-out for the authenticated caller so the client can discard its token; the JWT is stateless, so no server-side session state changes here.",
   perform: stepsPipeline(({ r }) => [

package/packages/bundled-features/src/auth-email-password/handlers/signup-request.write.ts

@@ -25,6 +25,7 @@ import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { findSignupHandoverProvider, type SignupHandoverBinding } from "../../shared/index.js";
+import { AUTH_EMAIL_PAYLOAD_RATE_LIMITS } from "../email-rate-limits.js";
 import type { AuthMailLocale } from "../email-templates.js";
 import { resolveHandlerMailLocale } from "../magic-link-mail.js";
 import { AUTH_SELF_REGISTRATION_FEATURE } from "../self-registration-toggle.js";
@@ -79,7 +80,7 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
     schema: SignupRequestSchema,
     access: { roles: ["anonymous"] },
     rateLimit: { per: "ip+handler", limit: 10, windowSeconds: 60 },
-    additionalRateLimits: [{ per: { payloadField: "email" }, limit: 3, windowSeconds: 86400 }],
+    additionalRateLimits: AUTH_EMAIL_PAYLOAD_RATE_LIMITS,
     description:
       "Starts magic-link self-registration by mailing a fresh activation link to an address and invalidating any link still outstanding for it; the answer looks the same whether or not the address is already registered.",
     escapeHatch: { reason: HANDOVER_GRANT_VERIFY_REASON, grants: ["unsafeRaw"] },

package/packages/bundled-features/src/auth-email-password/handlers/token-request-handler.ts

@@ -19,6 +19,7 @@ import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { UserQueries } from "../../user/index.js";
 import { type AuthUserRow, parseAuthUserRow } from "../auth-user-row.js";
+import { AUTH_EMAIL_PAYLOAD_RATE_LIMITS } from "../email-rate-limits.js";
 import type { AuthMailLocale } from "../email-templates.js";
 import { dispatchMagicLinkMail, resolveHandlerMailLocale } from "../magic-link-mail.js";
 
@@ -99,7 +100,7 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
     schema: RequestTokenSchema,
     access: { roles: ["anonymous"] },
     rateLimit: { per: "ip+handler", limit: 10, windowSeconds: 60 },
-    additionalRateLimits: [{ per: { payloadField: "email" }, limit: 5, windowSeconds: 86400 }],
+    additionalRateLimits: AUTH_EMAIL_PAYLOAD_RATE_LIMITS,
     escapeHatch: {
       grants: ["systemIdentity"],
       reason:

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,40 @@
 [
+  {
+    "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;
+  }
+}