@cosmicdrift/kumiko-samples 0.342.0 → 0.344.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.342.0",
+  "version": "0.344.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.342.0",
+  "version": "0.344.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>",

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.343.0",
+    "type": "improvement",
+    "title": "escape-hatch retention follows the tenant compliance profile",
+    "detail": "The audit job `escape-hatch-retention` now deletes `escapeHatchUse` events after the `auditLog.retention` of the tenant's compliance profile. A tenant override can only lengthen that period, never go below the base retention of the selected profile. Cross-tenant audits (with `targetTenantId`, e.g. `identity-switch`) additionally follow the profile of the target tenant. The config key `audit:config:escape-hatch-retention-days` is only the fallback when compliance-profiles is not mounted.\n`pruneEvents` gains the optional `aggregateIds` option to restrict the prune to specific aggregates. `@cosmicdrift/kumiko-framework/compliance` exports `subtractRetentionSpec` and the `RetentionSpec` type for calendar-aware cutoffs (months and years)."
+  },
   {
     "version": "0.313.0",
     "type": "fix",

package/packages/bundled-features/src/audit/constants.ts

@@ -25,7 +25,11 @@ export const AUDIT_LOG_SCREEN_ID = "audit-log" as const;
 /** Single-event detail screen, breadcrumb-linked to the audit-log list. */
 export const AUDIT_LOG_DETAIL_SCREEN_ID = "audit-log-detail" as const;
 
-/** Config key (system scope) for how long `escapeHatchUse` audit events are kept. */
+/**
+ * Config key (system scope) for how long `escapeHatchUse` audit events are kept. Only a fallback
+ * for apps without compliance-profiles; with it mounted, the tenant profile's `auditLog.retention`
+ * applies (a tenant override can only lengthen it).
+ */
 export const ESCAPE_HATCH_RETENTION_DAYS_KEY = "audit:config:escape-hatch-retention-days" as const;
 
 export const DEFAULT_ESCAPE_HATCH_RETENTION_DAYS = 90;

package/packages/bundled-features/src/audit/escape-hatch-audit-sink.ts

@@ -15,6 +15,7 @@ const escapeHatchKinds = [
   "global-write",
   "identity-switch",
   "unsafe-all-tenants",
+  "cross-tenant-read",
 ] as const satisfies readonly EscapeHatchKind[];
 
 export const escapeHatchUsedSchema = z.object({

package/packages/bundled-features/src/audit/run-escape-hatch-retention.ts

@@ -1,16 +1,29 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  COMPLIANCE_PROFILES,
+  subtractRetentionSpec,
+} from "@cosmicdrift/kumiko-framework/compliance";
 import type { DbConnection, DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import {
   type ConfigResolver,
+  parseTenantId,
   type Registry,
   SYSTEM_TENANT_ID,
+  type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { type PruneEventsResult, pruneEvents } from "@cosmicdrift/kumiko-framework/pipeline";
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { pruneEvents } from "@cosmicdrift/kumiko-framework/pipeline";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { resolveProfileForTenant } from "../compliance-profiles/index.js";
 import { createConfigAccessor } from "../config/index.js";
 import {
   DEFAULT_ESCAPE_HATCH_RETENTION_DAYS,
   ESCAPE_HATCH_RETENTION_DAYS_KEY,
 } from "./constants.js";
-import { ESCAPE_HATCH_USE_AGGREGATE_TYPE } from "./escape-hatch-audit-sink.js";
+import {
+  ESCAPE_HATCH_USE_AGGREGATE_TYPE,
+  escapeHatchUsedSchema,
+} from "./escape-hatch-audit-sink.js";
 
 // pruneEvents opens its own transaction, so a runner that cannot begin one (a tx handle) is rejected instead of nested.
 export function isDbConnection(runner: DbRunner): runner is DbConnection {
@@ -35,19 +48,97 @@ async function resolveRetentionDays(args: {
   return typeof raw === "number" && raw >= 1 ? raw : DEFAULT_ESCAPE_HATCH_RETENTION_DAYS;
 }
 
+// Soft dependency: audit must stay mountable without compliance-profiles, so we probe its entity.
+const COMPLIANCE_PROFILE_ENTITY = "tenant-compliance-profile";
+const PRUNE_CHUNK_SIZE = 1000;
+
+type AuditEventRow = {
+  readonly aggregateId: string;
+  readonly tenantId: TenantId;
+  readonly createdAt: Temporal.Instant;
+  readonly payload: unknown;
+};
+
+// Overrides may only lengthen retention: the earlier cutoff (same `now`) is the longer period.
+function earlierInstant(a: Temporal.Instant, b: Temporal.Instant): Temporal.Instant {
+  return Temporal.Instant.compare(a, b) <= 0 ? a : b;
+}
+
+async function resolveTenantCutoff(
+  db: DbConnection,
+  tenantId: TenantId,
+  now: Temporal.Instant,
+): Promise<Temporal.Instant> {
+  const { profile } = await resolveProfileForTenant({ db, tenantId });
+  const effective = subtractRetentionSpec(now, profile.auditLog.retention);
+  const base = subtractRetentionSpec(now, COMPLIANCE_PROFILES[profile.key].auditLog.retention);
+  return earlierInstant(effective, base);
+}
+
+// A cross-tenant audit (e.g. identity-switch) lives under the actor's tenant but must also
+// satisfy the target tenant's retention. A malformed payload falls back to the storing tenant.
+function targetTenantOf(payload: unknown): TenantId | null {
+  const parsed = escapeHatchUsedSchema.safeParse(payload);
+  return parsed.success ? parseTenantId(parsed.data.targetTenantId) : null;
+}
+
+async function pruneByTenantProfiles(db: DbConnection): Promise<number> {
+  const rows = await selectMany<AuditEventRow>(db, eventsTable, {
+    aggregateType: ESCAPE_HATCH_USE_AGGREGATE_TYPE,
+  });
+  const now = getTemporal().Now.instant();
+  const cutoffByTenant = new Map<TenantId, Temporal.Instant>();
+  const cutoffOf = async (tenantId: TenantId): Promise<Temporal.Instant> => {
+    const cached = cutoffByTenant.get(tenantId);
+    if (cached) return cached;
+    const cutoff = await resolveTenantCutoff(db, tenantId, now);
+    cutoffByTenant.set(tenantId, cutoff);
+    return cutoff;
+  };
+
+  const expiredAggregateIds: string[] = [];
+  for (const row of rows) {
+    const targetTenantId = targetTenantOf(row.payload);
+    const storeCutoff = await cutoffOf(row.tenantId);
+    const cutoff = targetTenantId
+      ? earlierInstant(storeCutoff, await cutoffOf(targetTenantId))
+      : storeCutoff;
+    if (Temporal.Instant.compare(row.createdAt, cutoff) < 0) {
+      expiredAggregateIds.push(row.aggregateId);
+    }
+  }
+
+  let deletedCount = 0;
+  for (let i = 0; i < expiredAggregateIds.length; i += PRUNE_CHUNK_SIZE) {
+    const result = await pruneEvents(db, {
+      aggregateTypes: [ESCAPE_HATCH_USE_AGGREGATE_TYPE],
+      aggregateIds: expiredAggregateIds.slice(i, i + PRUNE_CHUNK_SIZE),
+      olderThan: now,
+    });
+    deletedCount += result.deletedCount;
+  }
+  return deletedCount;
+}
+
 export async function runEscapeHatchRetention(args: {
   readonly db: DbRunner;
   readonly registry: Registry;
   readonly configResolver: ConfigResolver | undefined;
   readonly userId: string;
-}): Promise<PruneEventsResult> {
+}): Promise<{ readonly deletedCount: number }> {
   const { db } = args;
   if (!isDbConnection(db)) {
     throw new Error("audit escape-hatch retention: a transaction-free DbConnection is required");
   }
-  const olderThanDays = await resolveRetentionDays({ ...args, db });
-  return pruneEvents(db, {
-    aggregateTypes: [ESCAPE_HATCH_USE_AGGREGATE_TYPE],
-    olderThanDays,
-  });
+
+  if (!args.registry.getEntity(COMPLIANCE_PROFILE_ENTITY)) {
+    const olderThanDays = await resolveRetentionDays({ ...args, db });
+    const { deletedCount } = await pruneEvents(db, {
+      aggregateTypes: [ESCAPE_HATCH_USE_AGGREGATE_TYPE],
+      olderThanDays,
+    });
+    return { deletedCount };
+  }
+
+  return { deletedCount: await pruneByTenantProfiles(db) };
 }

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

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.343.0",
+    "type": "improvement",
+    "title": "Mail expiry shows duration and local time with time zone",
+    "detail": "Auth mails state the link validity as a duration and in the user's time zone\nThe five token mail renderers replace the UTC timestamp with `{duration}` (for example \"1 day\") and `{when}` (medium date and short time with zone abbreviation, in the recipient's locale). `RenderTokenContentArgs` gains `issuedAt` (default now) and `timeZone` (default UTC; an invalid zone falls back to UTC); the handlers pass the token issue time and `ctx.tz.user`. German strings use \"Konto\" instead of \"Account\".",
+    "migration": "Custom `auth.mail.*.expiry` translations should use the new `{duration}` and `{when}` placeholders; `{when}` now includes the time and zone abbreviation instead of a UTC timestamp."
+  },
   {
     "version": "0.342.0",
     "type": "improvement",

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

@@ -20,21 +20,21 @@ export const AUTH_MAIL_EN: Readonly<Record<string, string>> = {
   "auth.mail.reset.intro":
     "you requested a password reset for {app}. Click the link below to set a new password:",
   "auth.mail.reset.button": "Reset password",
-  "auth.mail.reset.expiry": "The link expires on {when}.",
+  "auth.mail.reset.expiry": "The link is valid for {duration} (until {when}).",
   "auth.mail.reset.ignore":
     "If you didn't request a reset, you can safely ignore this email — your password won't change.",
   "auth.mail.verify.subject": "{app} — Verify your email",
   "auth.mail.verify.greeting": "Welcome,",
   "auth.mail.verify.intro": "please verify your email address for {app} to activate your account:",
   "auth.mail.verify.button": "Verify email",
-  "auth.mail.verify.expiry": "The link expires on {when}.",
+  "auth.mail.verify.expiry": "The link is valid for {duration} (until {when}).",
   "auth.mail.verify.ignore": "If you didn't create this account, you can ignore this email.",
   "auth.mail.activation.subject": "{app} — Activate your account",
   "auth.mail.activation.greeting": "Welcome,",
   "auth.mail.activation.intro":
     "click the link below to activate your {app} account. The next step is choosing your password:",
   "auth.mail.activation.button": "Activate account",
-  "auth.mail.activation.expiry": "The link expires on {when}.",
+  "auth.mail.activation.expiry": "The link is valid for {duration} (until {when}).",
   "auth.mail.activation.ignore":
     "If you didn't sign up, you can ignore this email — no account is created until you open the link.",
   "auth.mail.invite.subject": "{app} — Workspace invitation",
@@ -42,14 +42,14 @@ export const AUTH_MAIL_EN: Readonly<Record<string, string>> = {
   "auth.mail.invite.intro":
     "you've been invited to a {app} workspace as {role}. Click the link below to accept:",
   "auth.mail.invite.button": "Accept invitation",
-  "auth.mail.invite.expiry": "The link expires on {when}.",
+  "auth.mail.invite.expiry": "The link is valid for {duration} (until {when}).",
   "auth.mail.invite.ignore": "If you weren't expecting this invitation, you can ignore this email.",
   "auth.mail.unlock.subject": "{app} — Unlock your account",
   "auth.mail.unlock.greeting": "Hi,",
   "auth.mail.unlock.intro":
     "your {app} account was temporarily locked after several failed sign-in attempts. Click the link below to unlock it immediately:",
   "auth.mail.unlock.button": "Unlock account",
-  "auth.mail.unlock.expiry": "The link expires on {when}.",
+  "auth.mail.unlock.expiry": "The link is valid for {duration} (until {when}).",
   "auth.mail.unlock.ignore":
     "If you didn't trigger this lock, you can ignore this email — the lock expires on its own.",
 };
@@ -62,6 +62,10 @@ export type RenderTokenContentArgs = {
   readonly locale?: AuthMailLocale;
   /** Optional app name for subject + intro. Default from auth.mail.appNameDefault. */
   readonly appName?: string;
+  /** ISO instant the token was issued; the validity duration is measured from it. Default: now. */
+  readonly issuedAt?: string;
+  /** IANA zone the expiry time is shown in. Default "UTC"; an invalid zone falls back to "UTC". */
+  readonly timeZone?: string;
 };
 
 export type RenderInviteEmailArgs = RenderTokenContentArgs & { readonly role: string };
@@ -119,7 +123,7 @@ export function renderResetPasswordEmail(args: RenderTokenContentArgs): AuthMail
     intro: t(locale, "auth.mail.reset.intro", { app }),
     buttonLabel: t(locale, "auth.mail.reset.button"),
     buttonUrl: args.url,
-    expiry: t(locale, "auth.mail.reset.expiry", { when: formatExpiry(args.expiresAt) }),
+    expiry: t(locale, "auth.mail.reset.expiry", expiryParams(args, locale)),
     ignore: t(locale, "auth.mail.reset.ignore"),
   });
 }
@@ -134,7 +138,7 @@ export function renderUnlockAccountEmail(args: RenderTokenContentArgs): AuthMail
     intro: t(locale, "auth.mail.unlock.intro", { app }),
     buttonLabel: t(locale, "auth.mail.unlock.button"),
     buttonUrl: args.url,
-    expiry: t(locale, "auth.mail.unlock.expiry", { when: formatExpiry(args.expiresAt) }),
+    expiry: t(locale, "auth.mail.unlock.expiry", expiryParams(args, locale)),
     ignore: t(locale, "auth.mail.unlock.ignore"),
   });
 }
@@ -149,7 +153,7 @@ export function renderVerifyEmail(args: RenderTokenContentArgs): AuthMailContent
     intro: t(locale, "auth.mail.verify.intro", { app }),
     buttonLabel: t(locale, "auth.mail.verify.button"),
     buttonUrl: args.url,
-    expiry: t(locale, "auth.mail.verify.expiry", { when: formatExpiry(args.expiresAt) }),
+    expiry: t(locale, "auth.mail.verify.expiry", expiryParams(args, locale)),
     ignore: t(locale, "auth.mail.verify.ignore"),
   });
 }
@@ -164,7 +168,7 @@ export function renderActivationEmail(args: RenderTokenContentArgs): AuthMailCon
     intro: t(locale, "auth.mail.activation.intro", { app }),
     buttonLabel: t(locale, "auth.mail.activation.button"),
     buttonUrl: args.url,
-    expiry: t(locale, "auth.mail.activation.expiry", { when: formatExpiry(args.expiresAt) }),
+    expiry: t(locale, "auth.mail.activation.expiry", expiryParams(args, locale)),
     ignore: t(locale, "auth.mail.activation.ignore"),
   });
 }
@@ -179,20 +183,76 @@ export function renderInviteEmail(args: RenderInviteEmailArgs): AuthMailContent
     intro: t(locale, "auth.mail.invite.intro", { app, role: args.role }),
     buttonLabel: t(locale, "auth.mail.invite.button"),
     buttonUrl: args.url,
-    expiry: t(locale, "auth.mail.invite.expiry", { when: formatExpiry(args.expiresAt) }),
+    expiry: t(locale, "auth.mail.invite.expiry", expiryParams(args, locale)),
     ignore: t(locale, "auth.mail.invite.ignore"),
   });
 }
 
-function formatExpiry(iso: string): string {
+const MS_PER_MINUTE = 60_000;
+const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+const MS_PER_DAY = 24 * MS_PER_HOUR;
+
+type DurationUnit = "day" | "hour" | "minute";
+
+// Rounds to whole minutes first so a few ms between issuing and signing still
+// read as "1 day"; a larger unit is only used when it divides the span exactly.
+function durationParts(ms: number): { readonly amount: number; readonly unit: DurationUnit } {
+  const minutes = Math.max(1, Math.round(ms / MS_PER_MINUTE));
+  const minutesPerHour = MS_PER_HOUR / MS_PER_MINUTE;
+  const minutesPerDay = MS_PER_DAY / MS_PER_MINUTE;
+  if (minutes % minutesPerDay === 0) return { amount: minutes / minutesPerDay, unit: "day" };
+  if (minutes % minutesPerHour === 0) return { amount: minutes / minutesPerHour, unit: "hour" };
+  return { amount: minutes, unit: "minute" };
+}
+
+function formatDuration(ms: number, locale: string): string {
+  const { amount, unit } = durationParts(ms);
+  const options: Intl.NumberFormatOptions = { style: "unit", unit, unitDisplay: "long" };
   try {
-    const z = Temporal.Instant.from(iso).toZonedDateTimeISO("UTC");
-    return `${z.year}-${pad2(z.month)}-${pad2(z.day)} ${pad2(z.hour)}:${pad2(z.minute)} UTC`;
+    return new Intl.NumberFormat(locale, options).format(amount);
   } catch {
-    return iso;
+    return new Intl.NumberFormat("en", options).format(amount);
   }
 }
 
-function pad2(n: number): string {
-  return String(n).padStart(2, "0");
+// Intl rejects timeZoneName together with dateStyle/timeStyle, so the zone
+// abbreviation is read from a second formatter and appended.
+function formatWhen(expiresAt: Temporal.Instant, locale: string, timeZone: string): string {
+  const build = (tag: string, zone: string): string => {
+    const at = expiresAt.epochMilliseconds;
+    const dateTime = new Intl.DateTimeFormat(tag, {
+      dateStyle: "medium",
+      timeStyle: "short",
+      timeZone: zone,
+    }).format(at);
+    const zoneName = new Intl.DateTimeFormat(tag, { timeZone: zone, timeZoneName: "short" })
+      .formatToParts(at)
+      .find((part) => part.type === "timeZoneName")?.value;
+    return zoneName ? `${dateTime} ${zoneName}` : dateTime;
+  };
+  try {
+    return build(locale, timeZone);
+  } catch {
+    try {
+      return build(locale, "UTC");
+    } catch {
+      return build("en", "UTC");
+    }
+  }
+}
+
+function expiryParams(
+  args: RenderTokenContentArgs,
+  locale: string,
+): { readonly duration: string; readonly when: string } {
+  try {
+    const expiresAt = Temporal.Instant.from(args.expiresAt);
+    const issuedAt = args.issuedAt ? Temporal.Instant.from(args.issuedAt) : Temporal.Now.instant();
+    return {
+      duration: formatDuration(expiresAt.epochMilliseconds - issuedAt.epochMilliseconds, locale),
+      when: formatWhen(expiresAt, locale, args.timeZone ?? "UTC"),
+    };
+  } catch {
+    return { duration: args.expiresAt, when: args.expiresAt };
+  }
 }

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

@@ -160,7 +160,8 @@ async function issueInvitation(
 
   const email = request.email.toLowerCase();
   const tenantId = inviter.tenantId;
-  const expiresAt = Temporal.Now.instant().add({ seconds: ttlSeconds });
+  const issuedAt = Temporal.Now.instant();
+  const expiresAt = issuedAt.add({ seconds: ttlSeconds });
 
   // The unique index allows one row per (tenantId, email). Whatever its
   // status, a re-invite resets it to pending with a fresh token.
@@ -233,6 +234,8 @@ async function issueInvitation(
       appUrl: opts.appUrl,
       token,
       expiresAt: expiresAt.toString(),
+      issuedAt: issuedAt.toString(),
+      timeZone: ctx.tz.user,
       ...(opts.appName !== undefined && { appName: opts.appName }),
       locale,
     },

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

@@ -150,7 +150,8 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
       // session tokens.
       const token = generateToken();
 
-      const expiresAt = Temporal.Now.instant().add({ seconds: ttlSeconds });
+      const issuedAt = Temporal.Now.instant();
+      const expiresAt = issuedAt.add({ seconds: ttlSeconds });
       const expiresAtIso = expiresAt.toString();
 
       await storeSignupToken(ctx.redis, { email, token, ttlSeconds });
@@ -211,6 +212,8 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
           appUrl: opts.appUrl,
           token,
           expiresAt: expiresAtIso,
+          issuedAt: issuedAt.toString(),
+          timeZone: ctx.tz.user,
           ...(opts.appName !== undefined && { appName: opts.appName }),
           locale,
         },

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

@@ -137,6 +137,7 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
       }
 
       const { token, expiresAt } = spec.sign(user.id, ttl, opts.hmacSecret);
+      const issuedAt = expiresAt.subtract({ minutes: ttl }).toString();
 
       const locale = resolveHandlerMailLocale(ctx, opts.locale);
 
@@ -154,6 +155,8 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
           appUrl: opts.appUrl,
           token,
           expiresAt: expiresAt.toString(),
+          issuedAt,
+          timeZone: ctx.tz.user,
           ...(opts.appName !== undefined && { appName: opts.appName }),
           locale,
         },

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

@@ -34,6 +34,8 @@ export type MagicLinkMailParams = {
   readonly expiresAt: string;
   readonly appName?: string;
   readonly locale?: AuthMailLocale;
+  readonly issuedAt?: string;
+  readonly timeZone?: string;
 };
 
 function resolveAppUrl(appUrl: string | ((locale: string) => string), locale: string): string {
@@ -78,6 +80,8 @@ export async function dispatchMagicLinkMail(
     expiresAt: params.expiresAt,
     ...(params.locale !== undefined && { locale: params.locale }),
     ...(params.appName !== undefined && { appName: params.appName }),
+    ...(params.issuedAt !== undefined && { issuedAt: params.issuedAt }),
+    ...(params.timeZone !== undefined && { timeZone: params.timeZone }),
   });
   await notify(spec.notificationType, {
     route: { email: params.email },

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

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.344.0",
+    "type": "breaking",
+    "title": "Consumer-protection gaps - per-locale legal links, gate order, confirmation mail, exports",
+    "detail": "All changes below apply only when `createBillingFoundationFeature` gets `consumerProtection`. Apps without it behave as before.\n`ConsumerProtectionOptions.legalLinks` takes either one `LegalLinkSet` or one set per consent locale (`{ de, en }`, both required). `BillingPlansResult.consumerProtection.legalLinks` is now always `Record<\"de\" | \"en\", LegalLinkSet>`; a single set is returned for both locales. Code that reads `legalLinks.terms` from the billing-plans result must read `legalLinks[locale].terms`. `CheckoutConsentDialog` picks the set for the consent locale.\n`FALLBACK_CONSENT_LOCALE` is now `\"en\"` (was `\"de\"`). A locale other than de/en, or none, resolves to English in `resolveConsentLocale`, the consent gate, the confirmation mail's VAT note and the termination record.\n`create-checkout-session` with consumer protection now checks in this order: provider, billing enabled, redirect origins, price and subscription gates, then the live price (new `UnprocessableError` `price_unavailable` when the provider cannot return it), then the consent, then the provider call. A missing consent no longer hides a disabled provider, an existing subscription or an unknown price. Its payload schema is strict, so unknown fields are rejected. `assertCheckoutAllowed` and `startProviderCheckout` split `openCheckout` in checkout-core.\nNew option `ConsumerProtectionOptions.oneOffItemLabel(ctx, priceId)`: the server resolves the label of a one-off item (for example a credit pack). It is stored on the consent event as `itemLabelKey` / `itemLabelParams` and shown in the confirmation mail as \"Leistung\" / \"Item\". The client cannot set it.\nThe terms text block is read from the system tenant, not from the buyer's tenant, in the consent gate and the confirmation mail. A tenant-owned block with the same slug no longer changes `termsHash` or the mailed text.\nThe confirmation mail shows dates in the recipient's time zone (user zone, else tenant zone, else UTC) with the zone name, renders the terms as Markdown with real headings and shows the translated plan name (`catalog.tierLabelKey`, looked up through the registry i18n, so the key must be qualified with the registering feature; untranslated keys fall back to the raw tier). Its opening sentence starts with a capital letter.\nNew exports: `consentPayloadSchema`, `ConsentPayload`, `OrderItem`, `CONSENT_LOCALES`, `ConsentLocale`, `resolveConsentLocale`, `LegalLinkSet`. The `/web` entry adds `CheckoutConsentDialog`, `CheckoutConsentDialogProps`, `CheckoutConsentPayload`, `CONSENT_TEXT_OUTDATED_CODE`, `resolveConsentLocale`, `ConsentLocale` and `LegalLinkSet`. `CheckoutConsentDialog` `price.count` is optional, and the \"cancel at any time\" note only shows for a recurring price (`price.renewalKey` set).\nThe checkout and cancel dialogs no longer repeat the modal title as a heading, and the cancel-contract button is hidden once a cancellation is scheduled.",
+    "migration": "Only apps that pass consumerProtection are affected. BillingPlansResult.consumerProtection.legalLinks is now keyed by locale (legalLinks.de / legalLinks.en). FALLBACK_CONSENT_LOCALE changed from de to en. create-checkout-session rejects unknown payload fields when consumer protection is on."
+  },
   {
     "version": "0.341.0",
     "type": "improvement",

package/packages/bundled-features/src/billing-foundation/checkout-core.ts

@@ -329,17 +329,27 @@ function assertOneOffPriceAllowed(
   }
 }
 
-/** The one checkout entry-point create-checkout-session and
- *  start-plan-checkout both funnel through. `mode: "payment"` (one-off
- *  top-ups etc.) skips the price/subscription gates entirely — those apply
- *  to recurring subscriptions only. */
-export async function openCheckout(
+type CheckoutCapableProvider = SubscriptionProviderPlugin & {
+  readonly createCheckoutSession: NonNullable<SubscriptionProviderPlugin["createCheckoutSession"]>;
+};
+
+function canCreateCheckoutSession(
+  plugin: SubscriptionProviderPlugin,
+): plugin is CheckoutCapableProvider {
+  return plugin.createCheckoutSession !== undefined;
+}
+
+/** All gates that run before a provider checkout call: provider, billing
+ *  enabled, redirect origins, mode gates, foreign provider customer.
+ *  `mode: "payment"` (one-off top-ups etc.) skips the price/subscription
+ *  gates — those apply to recurring subscriptions only. */
+export async function assertCheckoutAllowed(
   ctx: HandlerContext,
   options: OpenCheckoutOptions,
   input: OpenCheckoutInput,
-): Promise<{ readonly url: string; readonly providerName: string }> {
+): Promise<CheckoutCapableProvider> {
   const { plugin } = resolveProviderPlugin(ctx, input.providerName);
-  if (!plugin.createCheckoutSession) {
+  if (!canCreateCheckoutSession(plugin)) {
     throw new Error(
       `subscription-foundation: provider "${input.providerName}" has no createCheckoutSession-method (e.g. Apple-IAP-only providers). Use the provider's native checkout flow.`,
     );
@@ -376,7 +386,14 @@ export async function openCheckout(
       });
     }
   }
+  return plugin;
+}
 
+export async function startProviderCheckout(
+  ctx: HandlerContext,
+  plugin: CheckoutCapableProvider,
+  input: OpenCheckoutInput,
+): Promise<{ readonly url: string; readonly providerName: string }> {
   const result = await plugin.createCheckoutSession(ctx, {
     priceId: input.priceId,
     tenantId: ctx.user.tenantId,
@@ -393,3 +410,14 @@ export async function openCheckout(
   });
   return { url: result.url, providerName: input.providerName };
 }
+
+/** The one checkout entry-point start-plan-checkout, switch-plan and the
+ *  non-consumer-protection create-checkout-session funnel through. */
+export async function openCheckout(
+  ctx: HandlerContext,
+  options: OpenCheckoutOptions,
+  input: OpenCheckoutInput,
+): Promise<{ readonly url: string; readonly providerName: string }> {
+  const plugin = await assertCheckoutAllowed(ctx, options, input);
+  return startProviderCheckout(ctx, plugin, input);
+}