@cosmicdrift/kumiko-bundled-features 0.342.0 → 0.344.0

package/dist/audit/constants.d.ts

@@ -13,6 +13,10 @@ export declare const AuditQueries: {
 export declare const AUDIT_LOG_SCREEN_ID: "audit-log";
 /** Single-event detail screen, breadcrumb-linked to the audit-log list. */
 export declare const AUDIT_LOG_DETAIL_SCREEN_ID: "audit-log-detail";
-/** 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 declare const ESCAPE_HATCH_RETENTION_DAYS_KEY: "audit:config:escape-hatch-retention-days";
 export declare const DEFAULT_ESCAPE_HATCH_RETENTION_DAYS = 90;

package/dist/audit/constants.js

@@ -18,6 +18,10 @@ export const AuditQueries = {
 export const AUDIT_LOG_SCREEN_ID = "audit-log";
 /** Single-event detail screen, breadcrumb-linked to the audit-log list. */
 export const AUDIT_LOG_DETAIL_SCREEN_ID = "audit-log-detail";
-/** 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";
 export const DEFAULT_ESCAPE_HATCH_RETENTION_DAYS = 90;

package/dist/audit/escape-hatch-audit-sink.d.ts

@@ -7,6 +7,7 @@ export declare const escapeHatchUsedSchema: z.ZodObject<{
     handler: z.ZodString;
     kind: z.ZodEnum<{
         "acknowledge-cross-tenant": "acknowledge-cross-tenant";
+        "cross-tenant-read": "cross-tenant-read";
         "global-write": "global-write";
         "identity-switch": "identity-switch";
         "unsafe-all-tenants": "unsafe-all-tenants";

package/dist/audit/escape-hatch-audit-sink.js

@@ -11,6 +11,7 @@ const escapeHatchKinds = [
     "global-write",
     "identity-switch",
     "unsafe-all-tenants",
+    "cross-tenant-read",
 ];
 export const escapeHatchUsedSchema = z.object({
     handler: z.string(),

package/dist/audit/run-escape-hatch-retention.d.ts

@@ -1,10 +1,11 @@
 import type { DbConnection, DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import { type ConfigResolver, type Registry } from "@cosmicdrift/kumiko-framework/engine";
-import { type PruneEventsResult } from "@cosmicdrift/kumiko-framework/pipeline";
 export declare function isDbConnection(runner: DbRunner): runner is DbConnection;
 export declare function runEscapeHatchRetention(args: {
     readonly db: DbRunner;
     readonly registry: Registry;
     readonly configResolver: ConfigResolver | undefined;
     readonly userId: string;
-}): Promise<PruneEventsResult>;
+}): Promise<{
+    readonly deletedCount: number;
+}>;

package/dist/audit/run-escape-hatch-retention.js

@@ -1,8 +1,13 @@
-import { SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { COMPLIANCE_PROFILES, subtractRetentionSpec, } from "@cosmicdrift/kumiko-framework/compliance";
+import { parseTenantId, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
+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) {
     return "begin" in runner && typeof runner.begin === "function";
@@ -14,14 +19,73 @@ async function resolveRetentionDays(args) {
     const raw = await config(ESCAPE_HATCH_RETENTION_DAYS_KEY);
     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;
+// Overrides may only lengthen retention: the earlier cutoff (same `now`) is the longer period.
+function earlierInstant(a, b) {
+    return Temporal.Instant.compare(a, b) <= 0 ? a : b;
+}
+async function resolveTenantCutoff(db, tenantId, now) {
+    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) {
+    const parsed = escapeHatchUsedSchema.safeParse(payload);
+    return parsed.success ? parseTenantId(parsed.data.targetTenantId) : null;
+}
+async function pruneByTenantProfiles(db) {
+    const rows = await selectMany(db, eventsTable, {
+        aggregateType: ESCAPE_HATCH_USE_AGGREGATE_TYPE,
+    });
+    const now = getTemporal().Now.instant();
+    const cutoffByTenant = new Map();
+    const cutoffOf = async (tenantId) => {
+        const cached = cutoffByTenant.get(tenantId);
+        if (cached)
+            return cached;
+        const cutoff = await resolveTenantCutoff(db, tenantId, now);
+        cutoffByTenant.set(tenantId, cutoff);
+        return cutoff;
+    };
+    const expiredAggregateIds = [];
+    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) {
     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/dist/auth-email-password/email-templates.d.ts

@@ -6,6 +6,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;

package/dist/auth-email-password/email-templates.js

@@ -15,31 +15,31 @@ export const AUTH_MAIL_EN = {
     "auth.mail.reset.greeting": "Hi,",
     "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",
     "auth.mail.invite.greeting": "Hi,",
     "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.",
 };
 registerMailTranslations("en", AUTH_MAIL_EN);
@@ -73,7 +73,7 @@ export function renderResetPasswordEmail(args) {
         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"),
     });
 }
@@ -87,7 +87,7 @@ export function renderUnlockAccountEmail(args) {
         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"),
     });
 }
@@ -101,7 +101,7 @@ export function renderVerifyEmail(args) {
         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"),
     });
 }
@@ -115,7 +115,7 @@ export function renderActivationEmail(args) {
         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"),
     });
 }
@@ -129,19 +129,72 @@ export function renderInviteEmail(args) {
         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) {
+const MS_PER_MINUTE = 60_000;
+const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+const MS_PER_DAY = 24 * MS_PER_HOUR;
+// 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) {
+    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, locale) {
+    const { amount, unit } = durationParts(ms);
+    const options = { 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) {
-    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, locale, timeZone) {
+    const build = (tag, zone) => {
+        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, locale) {
+    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/dist/auth-email-password/handlers/invite-create.write.js

@@ -67,7 +67,8 @@ async function issueInvitation(opts, ttlSeconds, request, inviter, ctx, refuseAc
     }
     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.
     const existing = await ctx.db.fetchOne(tenantInvitationsTable, { tenantId, email });
@@ -126,6 +127,8 @@ async function issueInvitation(opts, ttlSeconds, request, inviter, ctx, refuseAc
         appUrl: opts.appUrl,
         token,
         expiresAt: expiresAt.toString(),
+        issuedAt: issuedAt.toString(),
+        timeZone: ctx.tz.user,
         ...(opts.appName !== undefined && { appName: opts.appName }),
         locale,
     });

package/dist/auth-email-password/handlers/signup-request.write.js

@@ -104,7 +104,8 @@ export function createSignupRequestHandler(opts) {
             // uses randomBytes from node:crypto, the same source as CSRF/
             // 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 });
             // A handover grant in this request re-verifies and replaces the prior
@@ -158,6 +159,8 @@ export function createSignupRequestHandler(opts) {
                 appUrl: opts.appUrl,
                 token,
                 expiresAt: expiresAtIso,
+                issuedAt: issuedAt.toString(),
+                timeZone: ctx.tz.user,
                 ...(opts.appName !== undefined && { appName: opts.appName }),
                 locale,
             });

package/dist/auth-email-password/handlers/token-request-handler.js

@@ -55,6 +55,7 @@ export function createTokenRequestHandler(spec, opts) {
                 return { isSuccess: true, data };
             }
             const { token, expiresAt } = spec.sign(user.id, ttl, opts.hmacSecret);
+            const issuedAt = expiresAt.subtract({ minutes: ttl }).toString();
             const locale = resolveHandlerMailLocale(ctx, opts.locale);
             await dispatchMagicLinkMail(ctx.notify, {
                 handlerName: spec.handlerName,
@@ -67,6 +68,8 @@ export function createTokenRequestHandler(spec, opts) {
                 appUrl: opts.appUrl,
                 token,
                 expiresAt: expiresAt.toString(),
+                issuedAt,
+                timeZone: ctx.tz.user,
                 ...(opts.appName !== undefined && { appName: opts.appName }),
                 locale,
             });

package/dist/auth-email-password/magic-link-mail.d.ts

@@ -12,6 +12,8 @@ export type MagicLinkMailParams = {
     readonly expiresAt: string;
     readonly appName?: string;
     readonly locale?: AuthMailLocale;
+    readonly issuedAt?: string;
+    readonly timeZone?: string;
 };
 export declare function resolveHandlerMailLocale(ctx: {
     readonly locale?: string;

package/dist/auth-email-password/magic-link-mail.js

@@ -40,6 +40,8 @@ export async function dispatchMagicLinkMail(notify, spec, params) {
         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/dist/billing-foundation/checkout-core.d.ts

@@ -92,11 +92,22 @@ export type OpenCheckoutInput = {
     readonly locale?: string;
     readonly submitMessage?: string;
 };
-/** 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. */
+type CheckoutCapableProvider = SubscriptionProviderPlugin & {
+    readonly createCheckoutSession: NonNullable<SubscriptionProviderPlugin["createCheckoutSession"]>;
+};
+/** 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 declare function assertCheckoutAllowed(ctx: HandlerContext, options: OpenCheckoutOptions, input: OpenCheckoutInput): Promise<CheckoutCapableProvider>;
+export declare function startProviderCheckout(ctx: HandlerContext, plugin: CheckoutCapableProvider, input: OpenCheckoutInput): Promise<{
+    readonly url: string;
+    readonly providerName: string;
+}>;
+/** The one checkout entry-point start-plan-checkout, switch-plan and the
+ *  non-consumer-protection create-checkout-session funnel through. */
 export declare function openCheckout(ctx: HandlerContext, options: OpenCheckoutOptions, input: OpenCheckoutInput): Promise<{
     readonly url: string;
     readonly providerName: string;
 }>;
+export {};

package/dist/billing-foundation/checkout-core.js

@@ -234,13 +234,16 @@ function assertOneOffPriceAllowed(plugin, input) {
         });
     }
 }
-/** 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(ctx, options, input) {
+function canCreateCheckoutSession(plugin) {
+    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, options, input) {
     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.`);
     }
     // Checked before the redirect-origin hardening for every mode — a
@@ -272,6 +275,9 @@ export async function openCheckout(ctx, options, input) {
             });
         }
     }
+    return plugin;
+}
+export async function startProviderCheckout(ctx, plugin, input) {
     const result = await plugin.createCheckoutSession(ctx, {
         priceId: input.priceId,
         tenantId: ctx.user.tenantId,
@@ -288,3 +294,9 @@ export async function openCheckout(ctx, options, input) {
     });
     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, options, input) {
+    const plugin = await assertCheckoutAllowed(ctx, options, input);
+    return startProviderCheckout(ctx, plugin, input);
+}

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

@@ -1,14 +1,24 @@
 import type { CheckoutConsentRecordedPayload } from "../events.js";
+export type ContractConfirmationSection = {
+    readonly text: string;
+} | {
+    readonly heading: string;
+} | {
+    readonly markdown: string;
+};
 export type ContractConfirmationContent = {
     readonly subject: string;
     readonly header: string;
-    readonly sections: readonly {
-        readonly text: string;
-    }[];
+    readonly sections: readonly ContractConfirmationSection[];
     readonly footer: string;
 };
 export type RenderContractConfirmationArgs = {
     readonly consent: CheckoutConsentRecordedPayload;
+    readonly timeZone: string;
+    /** Translated plan name; falls back to the raw tier. */
+    readonly tierLabel?: string;
+    /** Translated purchased item for one-off payments; falls back to the generic label. */
+    readonly itemLabel?: string;
     readonly consentGivenAtIso: string;
     readonly contractStartIso: string;
     readonly currentPeriodEndIso?: string;

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

@@ -3,8 +3,9 @@ import { CONSENT_TEXTS, resolveConsentLocale } from "./consent-text.js";
 const LABELS = {
     de: {
         subject: "Vertragsbestätigung",
-        intro: "vielen Dank für deine Bestellung. Hiermit bestätigen wir den Vertragsschluss mit folgendem Inhalt.",
+        intro: "Vielen Dank für deine Bestellung. Hiermit bestätigen wir den Vertragsschluss mit folgendem Inhalt.",
         plan: "Tarif",
+        item: "Leistung",
         oneOffPayment: "Einmalzahlung",
         price: "Preis",
         oneOff: "einmalig",
@@ -24,8 +25,9 @@ const LABELS = {
     },
     en: {
         subject: "Contract confirmation",
-        intro: "thank you for your order. We hereby confirm the conclusion of the contract with the following content.",
+        intro: "Thank you for your order. We hereby confirm the conclusion of the contract with the following content.",
         plan: "Plan",
+        item: "Item",
         oneOffPayment: "One-off payment",
         price: "Price",
         oneOff: "one-off",
@@ -69,7 +71,7 @@ function formatPrice(consent, locale) {
             : `${labels.every} ${count} ${unit.many}`;
     return count === 1 ? `${amount} / ${intervalText}` : `${amount}, ${intervalText}`;
 }
-function formatDate(iso, locale) {
+function formatDate(iso, locale, timeZone) {
     let epochMilliseconds;
     try {
         epochMilliseconds = Temporal.Instant.from(iso).epochMilliseconds;
@@ -78,18 +80,15 @@ function formatDate(iso, locale) {
         return iso;
     }
     return new Intl.DateTimeFormat(locale, {
-        dateStyle: "long",
-        timeStyle: "short",
-        timeZone: "UTC",
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+        timeZone,
+        timeZoneName: "short",
     }).format(epochMilliseconds);
 }
-function paragraphs(text) {
-    return text
-        .split(/\n{2,}/)
-        .map((part) => part.trim())
-        .filter((part) => part.length > 0)
-        .map((part) => ({ text: part }));
-}
 /** 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) {
@@ -97,12 +96,16 @@ export function renderContractConfirmation(args) {
     const labels = LABELS[locale];
     const texts = CONSENT_TEXTS[locale];
     const { consent } = 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 = [
-        `${labels.plan}: ${consent.tier ?? labels.oneOffPayment}`,
+        subjectLine,
         `${labels.price}: ${formatPrice(consent, locale)}`,
-        `${labels.contractStart}: ${formatDate(args.contractStartIso, locale)}`,
+        `${labels.contractStart}: ${formatDate(args.contractStartIso, locale, timeZone)}`,
         ...(args.currentPeriodEndIso !== undefined
-            ? [`${labels.currentPeriodEnd}: ${formatDate(args.currentPeriodEndIso, locale)}`]
+            ? [`${labels.currentPeriodEnd}: ${formatDate(args.currentPeriodEndIso, locale, timeZone)}`]
             : []),
     ];
     const vatNote = args.vatNote[locale] ?? args.vatNote[resolveConsentLocale()];
@@ -113,12 +116,12 @@ export function renderContractConfirmation(args) {
             { text: labels.intro },
             ...contractLines.map((text) => ({ text })),
             ...(vatNote !== undefined ? [{ text: vatNote }] : []),
-            { text: labels.consentHeading },
+            { heading: labels.consentHeading },
             { text: texts.earlyPerformance },
             { text: texts.withdrawalLoss },
-            { text: `${labels.consentGivenAt}: ${formatDate(args.consentGivenAtIso, locale)}` },
-            { text: labels.termsHeading },
-            ...paragraphs(args.termsContent),
+            { text: `${labels.consentGivenAt}: ${formatDate(args.consentGivenAtIso, locale, timeZone)}` },
+            { heading: labels.termsHeading },
+            { markdown: args.termsContent },
         ],
         footer: `${labels.contact} ${args.operatorEmail}`,
     };

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

@@ -1,4 +1,4 @@
-import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import type { ConsumerProtectionOptions, ProviderPrice } from "../types.js";
 export type CheckoutMode = "subscription" | "payment";
@@ -18,10 +18,15 @@ export type PreparedConsent = {
     readonly termsHash: string;
     readonly termsTemplateVersion: number;
 };
+export type OrderItem = {
+    readonly labelKey: string;
+    readonly params?: Readonly<Record<string, string | number>>;
+};
 export type ConsentPriceDetails = {
     readonly tier: string | null;
     readonly priceId: string;
     readonly price: Pick<ProviderPrice, "unitAmount" | "currency" | "interval" | "intervalCount"> | null;
+    readonly orderItem?: OrderItem;
 };
 export declare function prepareConsent(ctx: HandlerContext, options: ConsumerProtectionOptions, consent: ConsentPayload | undefined, mode: CheckoutMode): Promise<PreparedConsent>;
 export declare function consentCheckoutFields(prepared: PreparedConsent): {

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

@@ -1,6 +1,7 @@
 // Consent gate shared by start-plan-checkout and create-checkout-session:
 // 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 { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
@@ -36,7 +37,7 @@ export async function prepareConsent(ctx, options, consent, mode) {
     let terms;
     try {
         terms = await resolver.resolveTemplate({
-            tenantId: ctx.user.tenantId,
+            tenantId: SYSTEM_TENANT_ID,
             slug: options.termsTextBlock,
             kind: TEXT_BLOCK_KIND,
             locale,
@@ -84,6 +85,10 @@ export async function recordConsent(ctx, prepared, details) {
         termsTemplateVersion: prepared.termsTemplateVersion,
         locale: prepared.locale,
         actorUserId: String(ctx.user.id),
+        ...(details.orderItem && {
+            itemLabelKey: details.orderItem.labelKey,
+            ...(details.orderItem.params && { itemLabelParams: details.orderItem.params }),
+        }),
     };
     const tenantId = ctx.user.tenantId;
     const isSubscription = prepared.mode === "subscription";