@cosmicdrift/kumiko-bundled-features 0.343.0 → 0.345.0

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

@@ -1,4 +1,4 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { aggregateWhere, 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";
@@ -38,10 +38,14 @@ 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,
+async function storingTenantIds(db) {
+    const groups = await aggregateWhere(db, eventsTable, { measure: { fn: "count" }, groupBy: [{ field: "tenantId" }] }, { aggregateType: ESCAPE_HATCH_USE_AGGREGATE_TYPE });
+    return groups.flatMap((group) => {
+        const tenantId = parseTenantId(group.keys[0]);
+        return tenantId ? [tenantId] : [];
     });
+}
+async function pruneByTenantProfiles(db) {
     const now = getTemporal().Now.instant();
     const cutoffByTenant = new Map();
     const cutoffOf = async (tenantId) => {
@@ -52,15 +56,24 @@ async function pruneByTenantProfiles(db) {
         cutoffByTenant.set(tenantId, cutoff);
         return cutoff;
     };
+    // The effective cutoff is never later than the storing tenant's, so only rows older than
+    // that one can expire; everything younger stays in the database.
     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);
+    for (const storingTenantId of await storingTenantIds(db)) {
+        const storeCutoff = await cutoffOf(storingTenantId);
+        const candidates = await selectMany(db, eventsTable, {
+            aggregateType: ESCAPE_HATCH_USE_AGGREGATE_TYPE,
+            tenantId: storingTenantId,
+            createdAt: { lt: storeCutoff },
+        });
+        for (const row of candidates) {
+            const targetTenantId = targetTenantOf(row.payload);
+            const cutoff = targetTenantId
+                ? earlierInstant(storeCutoff, await cutoffOf(targetTenantId))
+                : storeCutoff;
+            if (Temporal.Instant.compare(row.createdAt, cutoff) < 0) {
+                expiredAggregateIds.push(row.aggregateId);
+            }
         }
     }
     let deletedCount = 0;

package/dist/auth-email-password/constants.d.ts

@@ -17,6 +17,7 @@ export declare const AuthHandlers: {
     readonly inviteAccept: "auth-email-password:write:invite-accept";
     readonly inviteAcceptWithLogin: "auth-email-password:write:invite-accept-with-login";
     readonly inviteSignupComplete: "auth-email-password:write:invite-signup-complete";
+    readonly switchTenantMfaGate: "auth-email-password:write:switch-tenant-mfa-gate";
     readonly inviteCancel: "auth-email-password:write:invite-cancel";
 };
 export declare const AuthQueries: {

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

@@ -44,6 +44,7 @@ export const AuthHandlers = {
     inviteAccept: "auth-email-password:write:invite-accept",
     inviteAcceptWithLogin: "auth-email-password:write:invite-accept-with-login",
     inviteSignupComplete: "auth-email-password:write:invite-signup-complete",
+    switchTenantMfaGate: "auth-email-password:write:switch-tenant-mfa-gate",
     inviteCancel: "auth-email-password:write:invite-cancel",
 };
 // Qualified query names. Anonymous-readable status so the (unauthenticated)

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

@@ -17,6 +17,7 @@ import { createResetPasswordHandler } from "./handlers/reset-password.write.js";
 import { selfRegistrationStatusQuery } from "./handlers/self-registration-status.query.js";
 import { createSignupConfirmHandler } from "./handlers/signup-confirm.write.js";
 import { createSignupRequestHandler, } from "./handlers/signup-request.write.js";
+import { createSwitchTenantMfaGateHandler } from "./handlers/switch-tenant-mfa-gate.write.js";
 import { createVerifyEmailHandler } from "./handlers/verify-email.write.js";
 /**
  * Env-vars contract for the `auth-email-password` feature.
@@ -101,6 +102,9 @@ export function createAuthEmailPasswordFeature(opts = {}) {
             changePassword: r.writeHandler(changePasswordWrite),
             logout: r.writeHandler(logoutWrite),
         };
+        if (opts.mfaStatusChecker) {
+            r.writeHandler(createSwitchTenantMfaGateHandler({ mfaStatusChecker: opts.mfaStatusChecker }));
+        }
         if (opts.passwordReset) {
             r.writeHandler(createRequestPasswordResetHandler(opts.passwordReset));
             r.writeHandler(createResetPasswordHandler(opts.passwordReset));
@@ -119,7 +123,7 @@ export function createAuthEmailPasswordFeature(opts = {}) {
         };
         if (opts.signup) {
             r.writeHandler(createSignupRequestHandler(opts.signup));
-            r.writeHandler(createSignupConfirmHandler());
+            r.writeHandler(createSignupConfirmHandler({ mfaStatusChecker: opts.mfaStatusChecker }));
         }
         if (opts.invite) {
             r.writeHandler(createInviteCreateHandler(opts.invite));
@@ -132,7 +136,7 @@ export function createAuthEmailPasswordFeature(opts = {}) {
                 accountLockout: opts.accountLockout,
                 strictEmailVerification: strictVerification,
             }));
-            r.writeHandler(createInviteSignupCompleteHandler());
+            r.writeHandler(createInviteSignupCompleteHandler({ mfaStatusChecker: opts.mfaStatusChecker }));
         }
         if (opts.accountUnlock) {
             r.writeHandler(createRequestAccountUnlockHandler(opts.accountUnlock));

package/dist/auth-email-password/handlers/invite-signup-complete.write.d.ts

@@ -1,12 +1,16 @@
 import { type SessionUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { type LoginHandlerOptions, type LoginResult } from "./login.write.js";
 export type InviteSignupCompleteData = {
     readonly kind: "auth-session";
     readonly session: SessionUser;
     readonly tenantId: TenantId;
     readonly role: string;
-};
-export declare function createInviteSignupCompleteHandler(): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"invite-signup-complete", z.ZodObject<{
+} | Exclude<LoginResult, {
+    readonly kind: "auth-session";
+}>;
+export type InviteSignupCompleteOptions = Pick<LoginHandlerOptions, "mfaStatusChecker">;
+export declare function createInviteSignupCompleteHandler(opts?: InviteSignupCompleteOptions): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"invite-signup-complete", z.ZodObject<{
     token: z.ZodString;
     password: z.ZodString;
 }, z.core.$strip>, InviteSignupCompleteData, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

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

@@ -37,13 +37,14 @@ import { burnInviteToken, deleteInviteToken, getInvitationIdForToken, unburnInvi
 import { passwordSchema } from "../password-policy.js";
 // kumiko-lint-ignore cross-feature-import provisioning needs cross-feature seeding helpers
 import { seedUserWithPassword } from "../seeding.js";
+import { gateEnforceMfa } from "./login.write.js";
 const InviteSignupCompleteSchema = z.object({
     token: z.string().min(1),
     password: passwordSchema,
 });
 const invitationExecutor = createEventStoreExecutor(tenantInvitationsTable, tenantInvitationEntity, { entityName: "tenant-invitation" });
 const INVITE_SIGNUP_COMPLETE_ESCAPE_HATCH_REASON = "reads the pending invitation by id; the invitee is not yet a member of the invitation's tenant. Creates the user and adds the membership and accepts the invitation in the invitation's tenant, before any caller tenant context exists.";
-export function createInviteSignupCompleteHandler() {
+export function createInviteSignupCompleteHandler(opts = {}) {
     return defineWriteHandler({
         name: "invite-signup-complete",
         schema: InviteSignupCompleteSchema,
@@ -119,13 +120,22 @@ export function createInviteSignupCompleteHandler() {
                 }, createSystemUser(invitationTenantId), invitationTdb);
                 if (!updateResult.isSuccess)
                     return updateResult;
+                // buildSessionRoles calls stripForbiddenMembershipRoles internally —
+                // a reserved role on the invitation itself must never reach the session.
+                const mergedRoles = buildSessionRoles(invitationGlobalRoles, [invitationRole]);
+                // Same gate as invite-accept-with-login: the account exists after this
+                // call, but an MFA-gated role gets the MFA step instead of a session.
+                // It runs before the token is deleted so a throwing check leaves the link retryable.
+                const mfaGate = await gateEnforceMfa(ctx, { mfaStatusChecker: opts.mfaStatusChecker }, userId, invitationTenantId, mergedRoles);
                 await deleteInviteToken(ctx.redis, { invitationId, token: event.payload.token });
+                if (mfaGate !== undefined) {
+                    committed = true;
+                    return { isSuccess: true, data: mfaGate };
+                }
                 const session = {
                     id: userId,
                     tenantId: invitationTenantId,
-                    // buildSessionRoles calls stripForbiddenMembershipRoles internally —
-                    // a reserved role on the invitation itself must never reach the session.
-                    roles: buildSessionRoles(invitationGlobalRoles, [invitationRole]),
+                    roles: mergedRoles,
                 };
                 committed = true;
                 return {

package/dist/auth-email-password/handlers/signup-confirm.write.d.ts

@@ -1,5 +1,6 @@
 import { type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { type LoginHandlerOptions, type LoginResult } from "./login.write.js";
 export type SignupConfirmData = {
     readonly kind: "auth-session";
     readonly session: SessionUser;
@@ -8,8 +9,11 @@ export type SignupConfirmData = {
         readonly entityType: string;
         readonly id: string;
     };
-};
-export declare function createSignupConfirmHandler(): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"signup-confirm", z.ZodObject<{
+} | Exclude<LoginResult, {
+    readonly kind: "auth-session";
+}>;
+export type SignupConfirmOptions = Pick<LoginHandlerOptions, "mfaStatusChecker">;
+export declare function createSignupConfirmHandler(opts?: SignupConfirmOptions): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"signup-confirm", z.ZodObject<{
     token: z.ZodString;
     password: z.ZodString;
 }, z.core.$strip>, SignupConfirmData, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

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

@@ -32,6 +32,7 @@ import { passwordSchema } from "../password-policy.js";
 // kumiko-lint-ignore cross-feature-import provisioning needs cross-feature seeding helpers
 import { INITIAL_SIGNUP_ROLES, provisionSignupAccount } from "../seeding.js";
 import { burnSignupToken, deleteSignupHandover, deleteSignupToken, getEmailForSignupToken, getSignupHandover, unburnSignupToken, } from "../signup-token-store.js";
+import { gateEnforceMfa } from "./login.write.js";
 const SignupConfirmSchema = z.object({
     token: z.string().min(8),
     password: passwordSchema,
@@ -70,7 +71,7 @@ async function claimBoundHandover(ctx, session, binding) {
     });
     return undefined;
 }
-export function createSignupConfirmHandler() {
+export function createSignupConfirmHandler(opts = {}) {
     return defineWriteHandler({
         name: "signup-confirm",
         schema: SignupConfirmSchema,
@@ -158,11 +159,17 @@ export function createSignupConfirmHandler() {
                 const handover = handoverBinding
                     ? await claimBoundHandover(ctx, session, handoverBinding)
                     : undefined;
+                // Before the token keys go: a throwing MFA check must leave the link retryable.
+                const mfaGate = await gateEnforceMfa(ctx, { mfaStatusChecker: opts.mfaStatusChecker }, provisioned.userId, provisioned.tenantId, session.roles);
                 // Drop both token lookup keys; the burn key stays for its remaining
                 // TTL as replay protection.
                 await deleteSignupToken(ctx.redis, { email, token: event.payload.token });
                 if (handoverBinding)
                     await deleteSignupHandover(ctx.redis, event.payload.token);
+                if (mfaGate !== undefined) {
+                    committed = true;
+                    return { isSuccess: true, data: mfaGate };
+                }
                 committed = true;
                 return {
                     isSuccess: true,

package/dist/auth-email-password/handlers/switch-tenant-mfa-gate.write.d.ts

@@ -0,0 +1,9 @@
+import * as z from "zod";
+import { gateEnforceMfa, type LoginHandlerOptions } from "./login.write.js";
+export type SwitchTenantMfaGateData = {
+    readonly kind: "mfa-gate-clear";
+} | NonNullable<Awaited<ReturnType<typeof gateEnforceMfa>>>;
+export declare function createSwitchTenantMfaGateHandler(opts: Pick<LoginHandlerOptions, "mfaStatusChecker">): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"switch-tenant-mfa-gate", z.ZodObject<{
+    userId: z.ZodString;
+    tenantId: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strip>, SwitchTenantMfaGateData, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/auth-email-password/handlers/switch-tenant-mfa-gate.write.js

@@ -0,0 +1,39 @@
+import { buildSessionRoles, createSystemUser, defineWriteHandler, SYSTEM_ROLE, } from "@cosmicdrift/kumiko-framework/engine";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+import { UserQueries } from "../../user/index.js";
+import { parseAuthUserRow } from "../auth-user-row.js";
+import { noMembership } from "../errors.js";
+import { gateEnforceMfa } from "./login.write.js";
+const SwitchTenantMfaGateSchema = z.object({
+    userId: z.string().min(1),
+    tenantId: z
+        .string()
+        .min(1)
+        .transform((id) => id),
+});
+// Dispatched by POST /auth/switch-tenant with the system identity. The handler
+// resolves membership and roles itself, so the gate never trusts caller-supplied
+// roles; system-only access keeps it out of reach of /api/write callers.
+export function createSwitchTenantMfaGateHandler(opts) {
+    return defineWriteHandler({
+        name: "switch-tenant-mfa-gate",
+        schema: SwitchTenantMfaGateSchema,
+        access: { roles: [SYSTEM_ROLE] },
+        escapeHatch: {
+            reason: "reads the MFA enrollment of the switch target tenant, not the caller's current tenant, via the mfaStatusChecker callback (it uses ctx.db.unsafeRaw())",
+        },
+        agent: { expose: false },
+        description: "Runs the MFA gate of the login for a tenant switch and answers with an MFA challenge, a setup requirement, or clearance.",
+        handler: async (event, ctx) => {
+            const { userId, tenantId } = event.payload;
+            const active = await ctx.resolveActiveMembership(userId, tenantId);
+            if (active.kind === "rejected")
+                return noMembership();
+            const userRow = parseAuthUserRow(await ctx.queryAs(createSystemUser(tenantId), UserQueries.findForAuth, { id: userId }));
+            const roles = buildSessionRoles(parseRoles(userRow?.roles ?? null), active.membership.roles);
+            const mfaGate = await gateEnforceMfa(ctx, opts, userId, tenantId, roles);
+            return { isSuccess: true, data: mfaGate ?? { kind: "mfa-gate-clear" } };
+        },
+    });
+}

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

@@ -13,6 +13,7 @@
 // spec rather than duplicated across two near-identical handler bodies.
 import { createSystemUser, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { isValidIanaTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import * as z from "zod";
 import { UserQueries } from "../../user/index.js";
 import { parseAuthUserRow } from "../auth-user-row.js";
@@ -20,6 +21,11 @@ import { dispatchMagicLinkMail, resolveHandlerMailLocale } from "../magic-link-m
 const RequestTokenSchema = z.object({
     email: z.email(),
 });
+// The requester is anonymous, so ctx.tz.user is only the tenant default; the recipient's
+// own profile zone is the one the expiry should be read in.
+function recipientTimeZone(user, fallbackTimeZone) {
+    return user.timezone && isValidIanaTimeZone(user.timezone) ? user.timezone : fallbackTimeZone;
+}
 export function createTokenRequestHandler(spec, opts) {
     const ttl = opts.tokenTtlMinutes ?? spec.defaultTtlMinutes;
     return defineWriteHandler({
@@ -69,7 +75,7 @@ export function createTokenRequestHandler(spec, opts) {
                 token,
                 expiresAt: expiresAt.toString(),
                 issuedAt,
-                timeZone: ctx.tz.user,
+                timeZone: recipientTimeZone(user, ctx.tz.user),
                 ...(opts.appName !== undefined && { appName: opts.appName }),
                 locale,
             });

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

@@ -99,6 +99,7 @@ export const defaultTranslations = {
         "auth.signupComplete.submit": "Activate account",
         "auth.signupComplete.submitting": "…",
         "auth.signupComplete.missingToken": "Activation link is missing a token. Please request a new one.",
+        "auth.signupComplete.activatedMfaPending": "Your account is active. Sign in to set up two-factor authentication.",
         "auth.signupComplete.activatedTitle": "Account activated",
         "auth.signupComplete.activated": "Your account is active and you're signed in.",
         "auth.signupComplete.continue": "Continue",

package/dist/auth-email-password/web/auth-client.d.ts

@@ -112,9 +112,14 @@ export type SignupConfirmSuccess = {
     };
     readonly landingPath?: string;
 };
+export type SignupConfirmResult = ({
+    readonly kind: "signed-in";
+} & SignupConfirmSuccess) | {
+    readonly kind: "mfa-pending";
+};
 export declare function confirmSignup(token: string, password: string): Promise<{
     ok: true;
-    data: SignupConfirmSuccess;
+    data: SignupConfirmResult;
 } | {
     ok: false;
     error: AuthTokenFailure;

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

@@ -229,8 +229,12 @@ export async function confirmSignup(token, password) {
         body: JSON.stringify({ token, password }),
     });
     if (res.ok) {
-        const body = (await res.json()); // @cast-boundary engine-payload
-        return { ok: true, data: body };
+        // @cast-boundary engine-payload
+        const body = (await res.json());
+        if (body.mfaRequired === true || body.mfaSetupRequired === true) {
+            return { ok: true, data: { kind: "mfa-pending" } };
+        }
+        return { ok: true, data: { kind: "signed-in", ...body } };
     }
     return { ok: false, error: await parseTokenFailure(res) };
 }

package/dist/auth-email-password/web/signup-complete-screen.js

@@ -31,6 +31,7 @@ export function SignupCompleteScreen({ title, token: tokenProp, loggedInHref = "
     const [submitting, setSubmitting] = useState(false);
     const [error, setError] = useState(null);
     const [continueHref, setContinueHref] = useState(null);
+    const [mfaPending, setMfaPending] = useState(false);
     const doSubmit = async () => {
         setError(null);
         const issue = passwordPairIssue(password, confirmPassword);
@@ -46,6 +47,11 @@ export function SignupCompleteScreen({ title, token: tokenProp, loggedInHref = "
         const res = await confirmSignup(token, password);
         setSubmitting(false);
         if (res.ok) {
+            if (res.data.kind === "mfa-pending") {
+                setMfaPending(true);
+                setContinueHref(loginHref);
+                return;
+            }
             // Cookies are already set (auto-login). Show a confirmation with an
             // explicit continue button instead of navigating away silently —
             // the user otherwise gets no signal that activation worked.
@@ -80,7 +86,9 @@ export function SignupCompleteScreen({ title, token: tokenProp, loggedInHref = "
         return (_jsxs(AuthCard, { title: effectiveTitle, children: [_jsx("p", { className: "text-sm text-muted-foreground", children: t("auth.signupComplete.missingToken") }), _jsx(Link, { href: loginHref, variant: "muted", children: t("auth.signup.haveAccount") })] }));
     }
     if (continueHref !== null) {
-        return (_jsxs(AuthCard, { title: effectiveTitle, children: [_jsx("p", { className: "text-sm text-muted-foreground", role: "status", children: t("auth.signupComplete.activated") }), _jsx(Link, { href: continueHref, variant: "button", children: t("auth.signupComplete.continue") })] }));
+        return (_jsxs(AuthCard, { title: effectiveTitle, children: [_jsx("p", { className: "text-sm text-muted-foreground", role: "status", children: t(mfaPending
+                        ? "auth.signupComplete.activatedMfaPending"
+                        : "auth.signupComplete.activated") }), _jsx(Link, { href: continueHref, variant: "button", children: t("auth.signupComplete.continue") })] }));
     }
     return (_jsxs(AuthCard, { title: effectiveTitle, children: [_jsx("p", { className: "text-sm text-muted-foreground", children: t("auth.signupComplete.intro") }), _jsxs(Form, { onSubmit: onSubmit, children: [_jsx(Field, { id: "signup-password", label: t("auth.signupComplete.password"), required: true, children: _jsx(Input, { kind: "password", id: "signup-password", name: "signup-password", value: password, onChange: setPassword, disabled: submitting, required: true, autoComplete: "new-password" }) }), _jsx(Field, { id: "signup-confirm-password", label: t("auth.signupComplete.confirmPassword"), required: true, children: _jsx(Input, { kind: "password", id: "signup-confirm-password", name: "signup-confirm-password", value: confirmPassword, onChange: setConfirmPassword, disabled: submitting, required: true, autoComplete: "new-password" }) }), error !== null && _jsx(Banner, { variant: "error", children: error }), _jsx(Button, { type: "submit", loading: submitting, disabled: submitting, children: submitting ? t("auth.signupComplete.submitting") : t("auth.signupComplete.submit") })] })] }));
 }

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";