@cosmicdrift/kumiko-samples 0.363.0 → 0.365.0

package/LICENSE

@@ -4,7 +4,7 @@ Parameters
 
 Licensor:             Marc Frost
 
-Licensed Work:        @cosmicdrift/kumiko-testing
+Licensed Work:        @cosmicdrift/kumiko-samples
                       The Licensed Work is © 2026 Marc Frost.
 
 Additional Use Grant: 

package/package.json

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

package/packages/bundled-features/package.json

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

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

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Escape-hatch retention keeps the operator floor and deletes in bounded batches",
+    "detail": "An explicitly configured retention key now acts as a lower bound for tenant compliance-profile cutoffs, so a tenant profile can no longer delete events younger than the operator allows. A key left at its default does not count. Pruning runs in batches of 5000 events, each in its own transaction, until a batch comes back short."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Audit retention events always use the system user",
+    "detail": "Events written by the audit feature no longer fall back to the calling user id and always record the system user."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Audit list pages by id unless sorted by type",
+    "detail": "An explicit createdAt sort pages in id order so keyset pagination no longer skips rows."
+  },
   {
     "version": "0.361.0",
     "type": "fix",

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

@@ -76,7 +76,7 @@ export function createAuditFeature(): FeatureDefinition {
             db: ctx.db.unsafeRaw(),
             registry: ctx.registry,
             configResolver: ctx.configResolver,
-            userId: ctx._userId ?? SYSTEM_USER_ID,
+            userId: SYSTEM_USER_ID,
           });
         },
       });

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

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

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

@@ -1,4 +1,8 @@
-import { aggregateWhere, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  aggregateWhere,
+  runnerCanBeginTransaction,
+  selectMany,
+} from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   COMPLIANCE_PROFILES,
   subtractRetentionSpec,
@@ -27,7 +31,7 @@ import {
 
 // pruneEvents opens its own transaction, so a runner that cannot begin one (a tx handle) is rejected instead of nested.
 export function isDbConnection(runner: DbRunner): runner is DbConnection {
-  return "begin" in runner && typeof runner.begin === "function";
+  return runnerCanBeginTransaction(runner);
 }
 
 async function resolveRetentionDays(args: {
@@ -48,9 +52,30 @@ async function resolveRetentionDays(args: {
   return typeof raw === "number" && raw >= 1 ? raw : DEFAULT_ESCAPE_HATCH_RETENTION_DAYS;
 }
 
+// Only an operator-set value counts: the key's declared default must not override the tenant profiles.
+async function resolveExplicitRetentionDays(args: {
+  readonly registry: Registry;
+  readonly configResolver: ConfigResolver | undefined;
+  readonly db: DbConnection;
+  readonly userId: string;
+}): Promise<number | undefined> {
+  const keyDef = args.registry.getConfigKey(ESCAPE_HATCH_RETENTION_DAYS_KEY);
+  if (!args.configResolver || !keyDef) return undefined;
+  const { value, source } = await args.configResolver.getWithSource(
+    ESCAPE_HATCH_RETENTION_DAYS_KEY,
+    keyDef,
+    SYSTEM_TENANT_ID,
+    args.userId,
+    args.db,
+  );
+  const isOperatorSet = source !== "default" && source !== "missing";
+  return isOperatorSet && typeof value === "number" && value >= 1 ? value : undefined;
+}
+
 // 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;
+const PRUNE_BATCH_SIZE = 5000;
 
 type AuditEventRow = {
   readonly aggregateId: string;
@@ -68,11 +93,13 @@ async function resolveTenantCutoff(
   db: DbConnection,
   tenantId: TenantId,
   now: Temporal.Instant,
+  operatorFloor: Temporal.Instant | undefined,
 ): Promise<Temporal.Instant> {
   const { profile } = await resolveProfileForTenant({ db, tenantId });
   const effective = subtractRetentionSpec(now, profile.auditLog.retention);
   const base = subtractRetentionSpec(now, COMPLIANCE_PROFILES[profile.key].auditLog.retention);
-  return earlierInstant(effective, base);
+  const profileCutoff = earlierInstant(effective, base);
+  return operatorFloor ? earlierInstant(profileCutoff, operatorFloor) : profileCutoff;
 }
 
 // A cross-tenant audit (e.g. identity-switch) lives under the actor's tenant but must also
@@ -95,13 +122,20 @@ async function storingTenantIds(db: DbConnection): Promise<readonly TenantId[]>
   });
 }
 
-async function pruneByTenantProfiles(db: DbConnection): Promise<number> {
+async function pruneByTenantProfiles(
+  db: DbConnection,
+  operatorRetentionDays: number | undefined,
+): Promise<number> {
   const now = getTemporal().Now.instant();
+  const operatorFloor =
+    operatorRetentionDays === undefined
+      ? undefined
+      : now.subtract({ hours: operatorRetentionDays * 24 });
   const cutoffByTenant = new Map<TenantId, Temporal.Instant>();
   const cutoffOf = async (tenantId: TenantId): Promise<Temporal.Instant> => {
     const cached = cutoffByTenant.get(tenantId);
     if (cached) return cached;
-    const cutoff = await resolveTenantCutoff(db, tenantId, now);
+    const cutoff = await resolveTenantCutoff(db, tenantId, now, operatorFloor);
     cutoffByTenant.set(tenantId, cutoff);
     return cutoff;
   };
@@ -139,11 +173,32 @@ async function pruneByTenantProfiles(db: DbConnection): Promise<number> {
   return deletedCount;
 }
 
+async function pruneInBatches(
+  db: DbConnection,
+  olderThanDays: number,
+  batchSize = PRUNE_BATCH_SIZE,
+): Promise<number> {
+  const olderThan = getTemporal()
+    .Now.instant()
+    .subtract({ hours: olderThanDays * 24 });
+  let deletedCount = 0;
+  for (;;) {
+    const batch = await pruneEvents(db, {
+      aggregateTypes: [ESCAPE_HATCH_USE_AGGREGATE_TYPE],
+      olderThan,
+      batchSize,
+    });
+    deletedCount += batch.deletedCount;
+    if (batch.deletedCount < batchSize) return deletedCount;
+  }
+}
+
 export async function runEscapeHatchRetention(args: {
   readonly db: DbRunner;
   readonly registry: Registry;
   readonly configResolver: ConfigResolver | undefined;
   readonly userId: string;
+  readonly batchSize?: number;
 }): Promise<{ readonly deletedCount: number }> {
   const { db } = args;
   if (!isDbConnection(db)) {
@@ -152,12 +207,9 @@ export async function runEscapeHatchRetention(args: {
 
   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 pruneInBatches(db, olderThanDays, args.batchSize) };
   }
 
-  return { deletedCount: await pruneByTenantProfiles(db) };
+  const operatorRetentionDays = await resolveExplicitRetentionDays({ ...args, db });
+  return { deletedCount: await pruneByTenantProfiles(db, operatorRetentionDays) };
 }

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

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

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

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

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

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

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

@@ -30,6 +30,7 @@ import {
 } from "./handlers/signup-request.write.js";
 import { createSwitchTenantMfaGateHandler } from "./handlers/switch-tenant-mfa-gate.write.js";
 import { createVerifyEmailHandler } from "./handlers/verify-email.write.js";
+import { AUTH_EMAIL_PASSWORD_MAIL_I18N } from "./mail-i18n.js";
 import {
   AUTH_MAIL_VARIABLES,
   authMailLocalizedTemplate,
@@ -113,13 +114,8 @@ export type AccountLockoutOptions = {
   readonly lockoutDurationMinutes?: number;
 };
 
-// Magic-Link Self-Signup. Wenn gesetzt, registriert das Feature die
-// signup-request + signup-confirm-Handler. Der Token-Store (Redis)
-// kommt aus ctx.redis — tokenTtlMinutes ist der einzige Knopf
-// (Token-Material ist generateToken() = 256 Bit randomBytes, fest;
-// Memory feedback_no_options_without_need: keine Knöpfe ohne Bedarf).
-// Anders als reset/verify gibt's kein hmacSecret hier, weil der Token
-// opaque random ist (Redis ist Source of Truth).
+// Unlike reset/verify there is no hmacSecret: the signup token is opaque random
+// (256 bit) and Redis is the source of truth, so tokenTtlMinutes is the only knob.
 export type SignupOptions = SignupRequestOptions;
 
 // Tenant-Invite Magic-Link. Wenn gesetzt, registriert das Feature die
@@ -207,6 +203,7 @@ export function createAuthEmailPasswordFeature(
     // of silently dropping the mail.
     if (sendsMagicLinkMail(opts)) r.requires("delivery");
     r.envSchema(authEmailPasswordEnvSchema);
+    r.translations({ keys: AUTH_EMAIL_PASSWORD_MAIL_I18N });
 
     // Declared unconditionally: apps also issue the activation link from their
     // own flows (issueSignupActivation) without enabling the signup option.

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

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

package/packages/bundled-features/src/auth-email-password/handlers/invite-accept-with-login.write.ts

@@ -121,9 +121,8 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
     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 " +
+        "Anonymous invite-accept has no session in the invited tenant yet — reads the pending " +
+        "invitation by id (the invitee is not yet a member of the " +
         "invitation's tenant), adds the membership and accepts the invitation in the " +
         "invitation's tenant, which differs from the caller's tenant, and reads the MFA " +
         "enrollment of that tenant via the mfaStatusChecker callback.",

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

@@ -32,6 +32,7 @@ import {
   type WriteFailure,
   writeFailure,
 } from "@cosmicdrift/kumiko-framework/errors";
+import { isValidLocaleTag } from "@cosmicdrift/kumiko-framework/i18n";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 // kumiko-lint-ignore cross-feature-import invite-flow lebt in auth-email-password (Magic-Link-Pattern), DB-row-owner ist tenant-feature
@@ -50,7 +51,7 @@ import {
   unassignableMembershipRoleError,
 } from "../../tenant/membership-roles.js";
 // kumiko-lint-ignore cross-feature-import global-role options are owned by the user feature
-import { GLOBAL_ROLE_OPTIONS } from "../../user/constants.js";
+import { GLOBAL_ROLE_OPTIONS, type GlobalRole } from "../../user/constants.js";
 // kumiko-lint-ignore cross-feature-import invitee lookup by email reads the user row
 import { userTable } from "../../user/schema/user.js";
 import { AUTH_INVITE_DEFAULT_TTL_MINUTES } from "../constants.js";
@@ -60,8 +61,6 @@ import { invalidateExistingInviteToken, storeInviteToken } from "../invite-token
 import { dispatchMagicLinkMail, resolveHandlerMailLocale } from "../magic-link-mail.js";
 import { AuthMailNotificationTypes } from "../mail-notifications.js";
 
-type GlobalRole = (typeof GLOBAL_ROLE_OPTIONS)[number];
-
 const InviteCreateSchema = z.object({
   email: z.email(),
   role: z.string().min(1).max(50),
@@ -116,6 +115,7 @@ type InviteIssueRequest = {
   readonly email: string;
   readonly role: string;
   readonly globalRoles: readonly GlobalRole[];
+  readonly locale?: string | undefined;
 };
 
 function checkAssignableInviteRole(
@@ -239,7 +239,7 @@ async function issueInvitation(
   const token = generateToken();
   await storeInviteToken(ctx.redis, { invitationId, token, ttlSeconds });
 
-  const locale = resolveHandlerMailLocale(ctx, opts.locale);
+  const locale = request.locale ?? resolveHandlerMailLocale(ctx, opts.locale);
 
   await dispatchMagicLinkMail(
     ctx.notify,
@@ -317,6 +317,8 @@ const SystemInviteCreateSchema = z.object({
   email: z.email(),
   role: z.string().min(1).max(50),
   globalRoles: z.array(z.enum(GLOBAL_ROLE_OPTIONS)).max(GLOBAL_ROLE_OPTIONS.length).default([]),
+  // Preferred over the request locale: provisioning callers know the invitee's language.
+  locale: z.string().max(35).refine(isValidLocaleTag, "invalid locale tag").optional(),
 });
 
 // System-only sibling of invite-create: the only path that can put global

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

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

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

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

package/packages/bundled-features/src/auth-email-password/handlers/switch-tenant-mfa-gate.write.ts

@@ -21,7 +21,7 @@ const SwitchTenantMfaGateSchema = z.object({
 });
 
 export type SwitchTenantMfaGateData =
-  | { readonly kind: "mfa-gate-clear" }
+  | { readonly kind: "mfa-gate-clear"; readonly roles: readonly string[] }
   | NonNullable<Awaited<ReturnType<typeof gateEnforceMfa>>>;
 
 // Dispatched by POST /auth/switch-tenant with the system identity. The handler
@@ -54,7 +54,7 @@ export function createSwitchTenantMfaGateHandler(
       );
       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" } };
+      return { isSuccess: true, data: mfaGate ?? { kind: "mfa-gate-clear", roles } };
     },
   });
 }

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

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