@cosmicdrift/kumiko-bundled-features 0.337.1 → 0.338.0

package/dist/agent-tools/tool-catalog.js

@@ -1,4 +1,4 @@
-import { hasAccess } from "@cosmicdrift/kumiko-framework/engine";
+import { hasAccess, normalizeAccessEntry } from "@cosmicdrift/kumiko-framework/engine";
 import { FILTER_OPS, isRecord } from "./filter-ops.js";
 const MAX_TOOL_NAME_LENGTH = 64;
 /** Field types that declare `filterable` (per `packages/framework/src/engine/types/fields.ts`).
@@ -74,14 +74,28 @@ function isDetailHandlerQn(qn, entityName) {
 function isExplicitlyAgentHidden(def) {
     return def.agent?.expose === false;
 }
-function addToolsForListHandler(registry, qn, entityName, entity, sink) {
+/** The model's filters feed the WHERE clause, and only the output is field-filtered — a field
+ *  whose read access is role- or row-restricted would leak through `totalCount` and hit/miss
+ *  probing. Only fields every one of these roles may read without a row condition are offered. */
+function isReadableWithoutRowCondition(field, roles) {
+    const accessMap = normalizeAccessEntry(field.access?.read);
+    if (!accessMap || Object.keys(accessMap).length === 0)
+        return true;
+    return roles.every((role) => accessMap[role] === "all");
+}
+/** Entity CRUD tools are registry-derived, so an explicit `agent.risk` on the handler is read
+ *  here; without a hint the read tools stay "low". */
+function entityHandlerRisk(registry, qn) {
+    return registry.getAllQueryHandlers().get(qn)?.agent?.risk ?? "low";
+}
+function addToolsForListHandler(registry, qn, entityName, entity, roles, sink) {
     const searchableFields = registry.getSearchableFields(entityName);
     if (searchableFields.length > 0) {
         const tool = buildSearchTool(entityName, searchableFields);
         addTool(sink, tool, { kind: "search", entityName, qn });
     }
     for (const [fieldName, field] of Object.entries(entity.fields)) {
-        if (!isFilterable(field))
+        if (!isFilterable(field) || !isReadableWithoutRowCondition(field, roles))
             continue;
         const fieldSchema = jsonSchemaTypeForField(field);
         if (!fieldSchema)
@@ -98,7 +112,7 @@ function entityDisplayLabel(entity, entityName, locale) {
         return label;
     return entityName;
 }
-function buildGetTool(entityName, qn, label) {
+function buildGetTool(entityName, qn, label, risk) {
     return {
         tool: {
             name: `get_${entityName}`,
@@ -110,7 +124,7 @@ function buildGetTool(entityName, qn, label) {
                 additionalProperties: false,
             },
         },
-        descriptor: { kind: "server", op: "query", qn, risk: "low", entity: entityName, detail: true },
+        descriptor: { kind: "server", op: "query", qn, risk, entity: entityName, detail: true },
     };
 }
 function buildListInputSchema(searchableFields, filterableFields) {
@@ -140,7 +154,7 @@ function buildListInputSchema(searchableFields, filterableFields) {
     properties["limit"] = { type: "integer", minimum: 1, maximum: 200 };
     return { type: "object", properties, required: [], additionalProperties: false };
 }
-function buildListTool(entityName, qn, label, searchableFields, filterableFields) {
+function buildListTool(entityName, qn, label, searchableFields, filterableFields, risk) {
     const descriptionParts = [`List ${label} records.`];
     if (searchableFields.length > 0) {
         descriptionParts.push(`Free-text search over: ${searchableFields.join(", ")}.`);
@@ -159,16 +173,22 @@ function buildListTool(entityName, qn, label, searchableFields, filterableFields
             kind: "server",
             op: "query",
             qn,
-            risk: "low",
+            risk,
             entity: entityName,
             list: { searchableFields, filterableFields },
         },
     };
 }
-function filterableFieldsOf(entity) {
+function filterableFieldsOf(entity, definition, roles) {
     if (!entity)
         return [];
-    return entity.fields.filter((field) => field.filterable === true).map((field) => field.name);
+    return entity.fields
+        .filter((field) => field.filterable === true)
+        .map((field) => field.name)
+        .filter((name) => {
+        const fieldDefinition = definition?.fields[name];
+        return fieldDefinition !== undefined && isReadableWithoutRowCondition(fieldDefinition, roles);
+    });
 }
 function compareByCodePoint(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
@@ -321,7 +341,7 @@ function addRegistrySearchTools(registry, roleFilter, denyQns, sink) {
         const entity = registry.getEntity(entityName);
         if (!entity)
             continue;
-        addToolsForListHandler(registry, qn, entityName, entity, sink);
+        addToolsForListHandler(registry, qn, entityName, entity, roleFilter.roles, sink);
     }
 }
 function collectEntityHandlerQns(registry, roleFilter, denyQns) {
@@ -352,21 +372,21 @@ function collectEntityHandlerQns(registry, roleFilter, denyQns) {
     }
     return { detailQnByEntity, listQnByEntity, entityListDetailQns };
 }
-function addGetTools(detailQnByEntity, entityByName, locale, sink) {
+function addGetTools(registry, detailQnByEntity, entityByName, locale, sink) {
     const getEntries = [...detailQnByEntity.entries()].sort((a, b) => compareByCodePoint(a[0], b[0]));
     for (const [entityName, qn] of getEntries) {
         const label = entityDisplayLabel(entityByName.get(entityName), entityName, locale);
-        const { tool, descriptor } = buildGetTool(entityName, qn, label);
+        const { tool, descriptor } = buildGetTool(entityName, qn, label, entityHandlerRisk(registry, qn));
         addTool(sink, tool, descriptor);
     }
 }
-function addListTools(registry, listQnByEntity, entityByName, locale, sink) {
+function addListTools(registry, listQnByEntity, entityByName, roles, locale, sink) {
     const listEntries = [...listQnByEntity.entries()].sort((a, b) => compareByCodePoint(a[0], b[0]));
     for (const [entityName, qn] of listEntries) {
         const label = entityDisplayLabel(entityByName.get(entityName), entityName, locale);
         const searchableFields = registry.getSearchableFields(entityName);
-        const filterableFields = filterableFieldsOf(entityByName.get(entityName));
-        const { tool, descriptor } = buildListTool(entityName, qn, label, searchableFields, filterableFields);
+        const filterableFields = filterableFieldsOf(entityByName.get(entityName), registry.getEntity(entityName), roles);
+        const { tool, descriptor } = buildListTool(entityName, qn, label, searchableFields, filterableFields, entityHandlerRisk(registry, qn));
         addTool(sink, tool, descriptor);
     }
 }
@@ -455,8 +475,8 @@ export function buildToolCatalog(registry, manifest, options) {
     const denyQns = new Set(options.denyQns ?? []);
     addRegistrySearchTools(registry, roleFilter, denyQns, sink);
     const { detailQnByEntity, listQnByEntity, entityListDetailQns } = collectEntityHandlerQns(registry, roleFilter, denyQns);
-    addGetTools(detailQnByEntity, entityByName, locale, sink);
-    addListTools(registry, listQnByEntity, entityByName, locale, sink);
+    addGetTools(registry, detailQnByEntity, entityByName, locale, sink);
+    addListTools(registry, listQnByEntity, entityByName, roleFilter.roles, locale, sink);
     addQueryHandlerTools(manifest, entityListDetailQns, denyQns, sink);
     if (options.mode !== "read-only") {
         addWriteHandlerTools(manifest, detailQnByEntity, denyQns, sink);

package/dist/auth-email-password/handlers/invite-accept-with-login.write.js

@@ -53,6 +53,7 @@ export function createInviteAcceptWithLoginHandler(opts = {}) {
         access: { roles: ["anonymous"] },
         rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
         escapeHatch: {
+            grants: ["unsafeRaw"],
             reason: "Anonymous invite-accept has no session in the invited tenant yet — checks existing " +
                 "membership via ctx.queryAs(SYSTEM, tenant:query:memberships) of the invitation's tenant. " +
                 "Also reads the pending invitation by id (the invitee is not yet a member of the " +

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

@@ -51,6 +51,7 @@ export function createInviteAcceptHandler() {
         },
         agent: { expose: false },
         escapeHatch: {
+            grants: ["unsafeRaw"],
             reason: INVITE_ACCEPT_ESCAPE_HATCH_REASON,
         },
         // kumiko-lint-ignore complexity-budget invite branches (auth/anon/burn) stay in one handler

package/dist/auth-email-password/handlers/invite-info.query.js

@@ -34,6 +34,7 @@ export const inviteInfoQuery = defineQueryHandler({
     rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     agent: { expose: false },
     escapeHatch: {
+        grants: ["unsafeRaw"],
         reason: READ_PENDING_INVITATION_REASON,
     },
     description: "Anonymous, read-only invite lookup for the invite-acceptance page: reveals the invited " +

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

@@ -51,6 +51,7 @@ export function createInviteSignupCompleteHandler() {
         rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
         agent: { expose: false },
         escapeHatch: {
+            grants: ["unsafeRaw", "globalWrites"],
             reason: INVITE_SIGNUP_COMPLETE_ESCAPE_HATCH_REASON,
         },
         handler: async (event, ctx) => {

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

@@ -78,6 +78,7 @@ export function createSignupConfirmHandler() {
         rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
         agent: { expose: false },
         escapeHatch: {
+            grants: ["unsafeRaw", "systemIdentity"],
             reason: SIGNUP_CONFIRM_PROVISION_REASON,
         },
         handler: async (event, ctx) => {

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

@@ -55,7 +55,7 @@ export function createSignupRequestHandler(opts) {
         access: { roles: ["anonymous"] },
         rateLimit: { per: "ip+handler", limit: 10, windowSeconds: 60 },
         description: "Starts magic-link self-registration by mailing a fresh activation link to an address and invalidating any link still outstanding for it; the answer looks the same whether or not the address is already registered.",
-        escapeHatch: { reason: HANDOVER_GRANT_VERIFY_REASON },
+        escapeHatch: { reason: HANDOVER_GRANT_VERIFY_REASON, grants: ["unsafeRaw"] },
         handler: async (event, ctx) => {
             // Silent no-op when off, matching the route's own always-200
             // anti-enumeration contract (registerTokenRequestRoute swallows every

package/dist/auth-mfa/handlers/enable-start-preauth.write.js

@@ -30,6 +30,7 @@ export function createEnableStartPreauthHandler(opts) {
         // Same secret-bearing result as enable-start.
         agent: { expose: false },
         escapeHatch: {
+            grants: ["unsafeRaw"],
             reason: ENABLE_START_PREAUTH_TENANT_REASON,
         },
         handler: async (event, ctx) => {

package/dist/billing-foundation/aggregate-id.d.ts

@@ -18,3 +18,5 @@ export declare function paymentAggregateId(tenantId: string): string;
  *  providerEventId)` rather than the event-store's bigserial `event.id` (not
  *  a UUID) or the shared per-tenant aggregateId (one row per payment). */
 export declare function paymentRowId(tenantId: string, providerName: string, providerEventId: string): string;
+/** Stream id of one unmatched termination declaration, derived from its request id. */
+export declare function terminationUnmatchedAggregateId(requestId: string): string;

package/dist/billing-foundation/aggregate-id.js

@@ -16,6 +16,9 @@ const PAYMENT_NAMESPACE = "dec0b897-646d-4da3-be3c-e9a35a83f4e0";
  *  UUID, so it can't back a uuid-typed PK. Generated 2026-09-11, set in
  *  stone (same rationale as the two namespaces above). */
 const PAYMENT_ROW_NAMESPACE = "3a1c9f4e-6b2d-4c8a-9e5f-7d4b1a2c8e6f";
+/** Namespace for the system-tenant stream of an unmatched termination
+ *  declaration (one stream per request). Generated 2026-10-03, set in stone. */
+const TERMINATION_UNMATCHED_NAMESPACE = "7e2f4b9a-3c1d-4a68-8d05-b6c9e1f27a34";
 /**
  * Deterministic aggregate-id für die subscription eines Plattform-
  * Tenants. EINE Subscription pro Tenant (Add-Ons sind line-items in
@@ -51,3 +54,8 @@ export function paymentRowId(tenantId, providerName, providerEventId) {
     // the payment with no error anywhere.
     return uuidv5(`${tenantId}:${providerName}:${providerEventId}`, PAYMENT_ROW_NAMESPACE);
 }
+/** Stream id of one unmatched termination declaration, derived from its request id. */
+// @wrapper-known uuid-domain
+export function terminationUnmatchedAggregateId(requestId) {
+    return uuidv5(requestId, TERMINATION_UNMATCHED_NAMESPACE);
+}

package/dist/billing-foundation/checkout-core.d.ts

@@ -88,6 +88,9 @@ export type OpenCheckoutInput = {
     readonly cancelUrl: string;
     readonly providerCustomerId?: string;
     readonly mode?: "subscription" | "payment";
+    readonly consentId?: string;
+    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

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

@@ -282,6 +282,9 @@ export async function openCheckout(ctx, options, input) {
         // pre-hardening wire-contract for callers that never sent `mode`
         // (create-checkout-session's own regression pin).
         ...(input.mode && { mode: input.mode }),
+        ...(input.consentId && { consentId: input.consentId }),
+        ...(input.locale && { locale: input.locale }),
+        ...(input.submitMessage && { submitMessage: input.submitMessage }),
     });
     return { url: result.url, providerName: input.providerName };
 }

package/dist/billing-foundation/constants.d.ts

@@ -2,6 +2,12 @@
 import { Temporal as TemporalPolyfill } from "temporal-polyfill";
 export declare const BILLING_FOUNDATION_FEATURE: "billing-foundation";
 export declare const SUBSCRIPTION_PROVIDER_EXTENSION: "subscriptionProvider";
+/** delivery notification type of the § 312f contract confirmation mail. */
+export declare const CONTRACT_CONFIRMATION_NOTIFICATION_TYPE: "billing-foundation:contract-confirmation";
+/** delivery notification types of the § 312k termination receipt and the
+ *  operator notice. */
+export declare const CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE: "billing-foundation:contract-termination-receipt";
+export declare const CONTRACT_TERMINATION_OPERATOR_NOTIFICATION_TYPE: "billing-foundation:contract-termination-operator-notice";
 export declare const SubscriptionFoundationHandlers: {
     /** Programmatic entry-point für den webhook-handler. Receives the
      *  parsed SubscriptionEvent (vom Plugin schon verifiziert) + macht
@@ -22,6 +28,22 @@ export declare const SubscriptionFoundationHandlers: {
      *  (payment-aggregate), separate from the subscription-aggregate — a
      *  payment is not a subscription-state transition. */
     readonly processPaymentEvent: "billing-foundation:write:process-payment-event";
+    /** System-only: sends the § 312f contract confirmation mail for a recorded
+     *  checkout consent (consumerProtection only). */
+    readonly issueContractConfirmation: "billing-foundation:write:issue-contract-confirmation";
+    /** System-only: records a termination/withdrawal on the tenant's
+     *  subscription stream and asks the provider to cancel (consumerProtection
+     *  only). */
+    readonly recordContractTermination: "billing-foundation:write:record-contract-termination";
+    /** System-only: records a public declaration no single tenant could be
+     *  matched to, on a system-tenant stream (consumerProtection only). */
+    readonly recordUnmatchedContractTermination: "billing-foundation:write:record-unmatched-contract-termination";
+    /** Anonymous § 312k cancellation/withdrawal declaration (consumerProtection
+     *  only). */
+    readonly requestContractTermination: "billing-foundation:write:request-contract-termination";
+    /** Tenant-Admin terminates or withdraws from the contract of their own
+     *  tenant (consumerProtection only). */
+    readonly terminateContract: "billing-foundation:write:terminate-contract";
     /** Tenant-Admin/purchase-role picks a plan tier from the catalog with no
      *  existing non-terminal subscription — starts a hosted checkout for the
      *  matching price. Only registered when `createBillingFoundationFeature`
@@ -47,6 +69,9 @@ export declare const SubscriptionFoundationQueries: {
      *  current tier and per-plan action. Only registered when a `catalog` is
      *  configured. */
     readonly billingPlans: "billing-foundation:query:billing-plans";
+    /** System-only probe: does the caller tenant hold a non-terminal
+     *  subscription (consumerProtection only). */
+    readonly terminableSubscription: "billing-foundation:query:terminable-subscription";
 };
 export declare const SubscriptionEventTypes: {
     readonly created: "subscription.created";
@@ -69,6 +94,12 @@ export declare const BillingEventKinds: {
     readonly payment: "payment";
 };
 export type BillingEventKind = (typeof BillingEventKinds)[keyof typeof BillingEventKinds];
+export declare const SubscriptionCancelTimings: {
+    readonly periodEnd: "period-end";
+    readonly immediately: "immediately";
+};
+export type SubscriptionCancelTiming = (typeof SubscriptionCancelTimings)[keyof typeof SubscriptionCancelTimings];
+export declare function parseProviderConsentId(raw: unknown): string | undefined;
 export declare const BILLING_PLANS_SCREEN_ID: "billing-plans";
 export declare const BILLING_PLANS_PANEL_COMPONENT: "BillingPlansPanel";
 export declare const BillingPlanActions: {

package/dist/billing-foundation/constants.js

@@ -12,6 +12,12 @@ export const BILLING_FOUNDATION_FEATURE = "billing-foundation";
 // Extension-point name fuer Provider-Plugins (subscription-stripe,
 // subscription-mollie, ...).
 export const SUBSCRIPTION_PROVIDER_EXTENSION = "subscriptionProvider";
+/** delivery notification type of the § 312f contract confirmation mail. */
+export const CONTRACT_CONFIRMATION_NOTIFICATION_TYPE = "billing-foundation:contract-confirmation";
+/** delivery notification types of the § 312k termination receipt and the
+ *  operator notice. */
+export const CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE = "billing-foundation:contract-termination-receipt";
+export const CONTRACT_TERMINATION_OPERATOR_NOTIFICATION_TYPE = "billing-foundation:contract-termination-operator-notice";
 // Qualified write handler names (QN format: scope:type:name).
 export const SubscriptionFoundationHandlers = {
     /** Programmatic entry-point für den webhook-handler. Receives the
@@ -33,6 +39,22 @@ export const SubscriptionFoundationHandlers = {
      *  (payment-aggregate), separate from the subscription-aggregate — a
      *  payment is not a subscription-state transition. */
     processPaymentEvent: "billing-foundation:write:process-payment-event",
+    /** System-only: sends the § 312f contract confirmation mail for a recorded
+     *  checkout consent (consumerProtection only). */
+    issueContractConfirmation: "billing-foundation:write:issue-contract-confirmation",
+    /** System-only: records a termination/withdrawal on the tenant's
+     *  subscription stream and asks the provider to cancel (consumerProtection
+     *  only). */
+    recordContractTermination: "billing-foundation:write:record-contract-termination",
+    /** System-only: records a public declaration no single tenant could be
+     *  matched to, on a system-tenant stream (consumerProtection only). */
+    recordUnmatchedContractTermination: "billing-foundation:write:record-unmatched-contract-termination",
+    /** Anonymous § 312k cancellation/withdrawal declaration (consumerProtection
+     *  only). */
+    requestContractTermination: "billing-foundation:write:request-contract-termination",
+    /** Tenant-Admin terminates or withdraws from the contract of their own
+     *  tenant (consumerProtection only). */
+    terminateContract: "billing-foundation:write:terminate-contract",
     /** Tenant-Admin/purchase-role picks a plan tier from the catalog with no
      *  existing non-terminal subscription — starts a hosted checkout for the
      *  matching price. Only registered when `createBillingFoundationFeature`
@@ -59,6 +81,9 @@ export const SubscriptionFoundationQueries = {
      *  current tier and per-plan action. Only registered when a `catalog` is
      *  configured. */
     billingPlans: "billing-foundation:query:billing-plans",
+    /** System-only probe: does the caller tenant hold a non-terminal
+     *  subscription (consumerProtection only). */
+    terminableSubscription: "billing-foundation:query:terminable-subscription",
 };
 // Normalized subscription-event types — provider-agnostic.
 // Alle Provider-Plugins normalisieren ihre eigenen event-types auf einen
@@ -90,6 +115,16 @@ export const BillingEventKinds = {
     subscription: "subscription",
     payment: "payment",
 };
+export const SubscriptionCancelTimings = {
+    periodEnd: "period-end",
+    immediately: "immediately",
+};
+// consentId is echoed back by the provider (checkout metadata), so it is
+// untrusted input: bounded length, id-ish charset only.
+const CONSENT_ID_PATTERN = /^[A-Za-z0-9_-]{1,100}$/;
+export function parseProviderConsentId(raw) {
+    return typeof raw === "string" && CONSENT_ID_PATTERN.test(raw) ? raw : undefined;
+}
 // Billing-plans screen/panel identifiers — the dormant dashboard app-builders
 // mount their own catalog-derived nav entry onto.
 export const BILLING_PLANS_SCREEN_ID = "billing-plans";

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

@@ -0,0 +1,21 @@
+import type { CheckoutConsentRecordedPayload } from "../events.js";
+export type ContractConfirmationContent = {
+    readonly subject: string;
+    readonly header: string;
+    readonly sections: readonly {
+        readonly text: string;
+    }[];
+    readonly footer: string;
+};
+export type RenderContractConfirmationArgs = {
+    readonly consent: CheckoutConsentRecordedPayload;
+    readonly consentGivenAtIso: string;
+    readonly contractStartIso: string;
+    readonly currentPeriodEndIso?: string;
+    readonly vatNote: Readonly<Record<string, string>>;
+    readonly operatorEmail: string;
+    readonly termsContent: string;
+};
+/** Structured mail content (header/sections/footer) for the email channel's
+ *  renderer; the renderer owns HTML escaping, this only builds plain text. */
+export declare function renderContractConfirmation(args: RenderContractConfirmationArgs): ContractConfirmationContent;

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

@@ -0,0 +1,125 @@
+import { Temporal } from "temporal-polyfill";
+import { CONSENT_TEXTS, resolveConsentLocale } from "./consent-text.js";
+const LABELS = {
+    de: {
+        subject: "Vertragsbestätigung",
+        intro: "vielen Dank für Ihre Bestellung. Hiermit bestätigen wir den Vertragsschluss mit folgendem Inhalt.",
+        plan: "Tarif",
+        oneOffPayment: "Einmalzahlung",
+        price: "Preis",
+        oneOff: "einmalig",
+        contractStart: "Vertragsbeginn",
+        currentPeriodEnd: "Aktueller Abrechnungszeitraum bis",
+        consentHeading: "Ihre Zustimmungen",
+        consentGivenAt: "Erteilt am",
+        termsHeading: "Allgemeine Geschäftsbedingungen",
+        contact: "Fragen zu Ihrem Vertrag richten Sie bitte an",
+        every: "alle",
+        intervals: {
+            day: { one: "Tag", many: "Tage" },
+            week: { one: "Woche", many: "Wochen" },
+            month: { one: "Monat", many: "Monate" },
+            year: { one: "Jahr", many: "Jahre" },
+        },
+    },
+    en: {
+        subject: "Contract confirmation",
+        intro: "thank you for your order. We hereby confirm the conclusion of the contract with the following content.",
+        plan: "Plan",
+        oneOffPayment: "One-off payment",
+        price: "Price",
+        oneOff: "one-off",
+        contractStart: "Contract start",
+        currentPeriodEnd: "Current billing period ends",
+        consentHeading: "Your consents",
+        consentGivenAt: "Given on",
+        termsHeading: "Terms and conditions",
+        contact: "Questions about your contract go to",
+        every: "every",
+        intervals: {
+            day: { one: "day", many: "days" },
+            week: { one: "week", many: "weeks" },
+            month: { one: "month", many: "months" },
+            year: { one: "year", many: "years" },
+        },
+    },
+};
+function formatPrice(consent, locale) {
+    const labels = LABELS[locale];
+    if (consent.unitAmount === null || consent.currency === null)
+        return "-";
+    let amount;
+    try {
+        const format = new Intl.NumberFormat(locale, { style: "currency", currency: consent.currency });
+        const fractionDigits = format.resolvedOptions().maximumFractionDigits ?? 2;
+        amount = format.format(consent.unitAmount / 10 ** fractionDigits);
+    }
+    catch {
+        // Currency codes come from the provider; an unknown one must not block the mail.
+        amount = `${consent.unitAmount} ${consent.currency.toUpperCase()}`;
+    }
+    if (consent.interval === null)
+        return `${amount} (${labels.oneOff})`;
+    const unit = labels.intervals[consent.interval];
+    const count = consent.intervalCount ?? 1;
+    const intervalText = unit === undefined
+        ? consent.interval
+        : count === 1
+            ? unit.one
+            : `${labels.every} ${count} ${unit.many}`;
+    return count === 1 ? `${amount} / ${intervalText}` : `${amount}, ${intervalText}`;
+}
+function formatDate(iso, locale) {
+    let epochMilliseconds;
+    try {
+        epochMilliseconds = Temporal.Instant.from(iso).epochMilliseconds;
+    }
+    catch {
+        return iso;
+    }
+    return new Intl.DateTimeFormat(locale, {
+        dateStyle: "long",
+        timeStyle: "short",
+        timeZone: "UTC",
+    }).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) {
+    const locale = resolveConsentLocale(args.consent.locale);
+    const labels = LABELS[locale];
+    const texts = CONSENT_TEXTS[locale];
+    const { consent } = args;
+    const contractLines = [
+        `${labels.plan}: ${consent.tier ?? labels.oneOffPayment}`,
+        `${labels.price}: ${formatPrice(consent, locale)}`,
+        `${labels.contractStart}: ${formatDate(args.contractStartIso, locale)}`,
+        ...(args.currentPeriodEndIso !== undefined
+            ? [`${labels.currentPeriodEnd}: ${formatDate(args.currentPeriodEndIso, locale)}`]
+            : []),
+    ];
+    const vatNote = args.vatNote[locale] ?? args.vatNote[resolveConsentLocale()];
+    return {
+        subject: labels.subject,
+        header: labels.subject,
+        sections: [
+            { text: labels.intro },
+            ...contractLines.map((text) => ({ text })),
+            ...(vatNote !== undefined ? [{ text: vatNote }] : []),
+            { text: labels.consentHeading },
+            { text: texts.earlyPerformance },
+            { text: texts.withdrawalLoss },
+            { text: `${labels.consentGivenAt}: ${formatDate(args.consentGivenAtIso, locale)}` },
+            { text: labels.termsHeading },
+            ...paragraphs(args.termsContent),
+        ],
+        footer: `${labels.contact} ${args.operatorEmail}`,
+    };
+}

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

@@ -0,0 +1,32 @@
+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";
+export declare const consentPayloadSchema: z.ZodObject<{
+    earlyPerformanceRequested: z.ZodLiteral<true>;
+    withdrawalLossAcknowledged: z.ZodLiteral<true>;
+    consentTextVersion: z.ZodString;
+    locale: z.ZodString;
+}, z.core.$strict>;
+export type ConsentPayload = z.infer<typeof consentPayloadSchema>;
+export type PreparedConsent = {
+    readonly consentId: string;
+    readonly mode: CheckoutMode;
+    readonly locale: string;
+    readonly submitMessage: string;
+    readonly consentTextVersion: string;
+    readonly termsHash: string;
+    readonly termsTemplateVersion: number;
+};
+export type ConsentPriceDetails = {
+    readonly tier: string | null;
+    readonly priceId: string;
+    readonly price: Pick<ProviderPrice, "unitAmount" | "currency" | "interval" | "intervalCount"> | null;
+};
+export declare function prepareConsent(ctx: HandlerContext, options: ConsumerProtectionOptions, consent: ConsentPayload, mode: CheckoutMode): Promise<PreparedConsent>;
+export declare function consentCheckoutFields(prepared: PreparedConsent): {
+    readonly consentId: string;
+    readonly locale: string;
+    readonly submitMessage: string;
+};
+export declare function recordConsent(ctx: HandlerContext, prepared: PreparedConsent, details: ConsentPriceDetails): Promise<void>;

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

@@ -0,0 +1,88 @@
+// 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 { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+import { requireTemplateResolver, TEXT_BLOCK_KIND, TemplateNotFoundError, } from "../../template-resolver/index.js";
+import { paymentAggregateId, subscriptionAggregateId } from "../aggregate-id.js";
+import { CHECKOUT_CONSENT_RECORDED_EVENT_QN, PAYMENT_AGGREGATE_TYPE, SUBSCRIPTION_AGGREGATE_TYPE, } from "../events.js";
+import { consentTextVersion, resolveConsentLocale, submitMessageFor } from "./consent-text.js";
+export const consentPayloadSchema = z
+    .object({
+    earlyPerformanceRequested: z.literal(true),
+    withdrawalLossAcknowledged: z.literal(true),
+    consentTextVersion: z.string().min(1).max(64),
+    locale: z.string().min(2).max(35),
+})
+    .strict();
+export async function prepareConsent(ctx, options, consent, mode) {
+    const locale = resolveConsentLocale(consent.locale);
+    if (consent.consentTextVersion !== consentTextVersion(locale)) {
+        throw new UnprocessableError("consent_text_outdated", {
+            i18nKey: "billing-foundation.errors.consentTextOutdated",
+            message: `billing-foundation: consent text version "${consent.consentTextVersion}" is not current for locale "${locale}"`,
+        });
+    }
+    const resolver = requireTemplateResolver(ctx, "billing-foundation");
+    let terms;
+    try {
+        terms = await resolver.resolveTemplate({
+            tenantId: ctx.user.tenantId,
+            slug: options.termsTextBlock,
+            kind: TEXT_BLOCK_KIND,
+            locale,
+        });
+    }
+    catch (error) {
+        if (error instanceof TemplateNotFoundError) {
+            throw new UnprocessableError("terms_unavailable", {
+                i18nKey: "billing-foundation.errors.termsUnavailable",
+                message: `billing-foundation: terms text block "${options.termsTextBlock}" could not be resolved`,
+                cause: error,
+            });
+        }
+        throw error;
+    }
+    return {
+        consentId: generateId(),
+        mode,
+        locale,
+        submitMessage: submitMessageFor(locale, mode),
+        consentTextVersion: consent.consentTextVersion,
+        termsHash: createHash("sha256").update(terms.content).digest("hex"),
+        termsTemplateVersion: terms.version,
+    };
+}
+export function consentCheckoutFields(prepared) {
+    return {
+        consentId: prepared.consentId,
+        locale: prepared.locale,
+        submitMessage: prepared.submitMessage,
+    };
+}
+export async function recordConsent(ctx, prepared, details) {
+    const payload = {
+        consentId: prepared.consentId,
+        mode: prepared.mode,
+        tier: details.tier,
+        priceId: details.priceId,
+        unitAmount: details.price?.unitAmount ?? null,
+        currency: details.price?.currency ?? null,
+        interval: details.price?.interval ?? null,
+        intervalCount: details.price?.intervalCount ?? null,
+        consentTextVersion: prepared.consentTextVersion,
+        termsHash: prepared.termsHash,
+        termsTemplateVersion: prepared.termsTemplateVersion,
+        locale: prepared.locale,
+        actorUserId: String(ctx.user.id),
+    };
+    const tenantId = ctx.user.tenantId;
+    const isSubscription = prepared.mode === "subscription";
+    await ctx.unsafeAppendEvent({
+        aggregateId: isSubscription ? subscriptionAggregateId(tenantId) : paymentAggregateId(tenantId),
+        aggregateType: isSubscription ? SUBSCRIPTION_AGGREGATE_TYPE : PAYMENT_AGGREGATE_TYPE,
+        type: CHECKOUT_CONSENT_RECORDED_EVENT_QN,
+        payload,
+    });
+}

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

@@ -0,0 +1,5 @@
+export declare const CONSENT_LOCALES: readonly ["de", "en"];
+export type ConsentLocale = (typeof CONSENT_LOCALES)[number];
+export declare const FALLBACK_CONSENT_LOCALE: ConsentLocale;
+/** Exact match, else the language part ("de-AT" → "de"), else the fallback. */
+export declare function resolveConsentLocale(input?: string): ConsentLocale;