@cosmicdrift/kumiko-samples 0.338.0 → 0.340.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.338.0",
+  "version": "0.340.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.338.0",
+  "version": "0.340.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>",
@@ -107,6 +107,10 @@
     "./channel-in-app": "./src/channel-in-app/index.ts",
     "./channel-email": "./src/channel-email/index.ts",
     "./channel-push": "./src/channel-push/index.ts",
+    "./channel-slack": "./src/channel-slack/index.ts",
+    "./channel-discord": "./src/channel-discord/index.ts",
+    "./channel-teams": "./src/channel-teams/index.ts",
+    "./channel-telegram": "./src/channel-telegram/index.ts",
     "./renderer-simple": "./src/renderer-simple/index.ts",
     "./files-provider-s3": "./src/files-provider-s3/index.ts",
     "./rate-limiting": "./src/rate-limiting/index.ts",
@@ -514,6 +518,22 @@
         "types": "./dist/channel-push/index.d.ts",
         "default": "./dist/channel-push/index.js"
       },
+      "./channel-slack": {
+        "types": "./dist/channel-slack/index.d.ts",
+        "default": "./dist/channel-slack/index.js"
+      },
+      "./channel-discord": {
+        "types": "./dist/channel-discord/index.d.ts",
+        "default": "./dist/channel-discord/index.js"
+      },
+      "./channel-teams": {
+        "types": "./dist/channel-teams/index.d.ts",
+        "default": "./dist/channel-teams/index.js"
+      },
+      "./channel-telegram": {
+        "types": "./dist/channel-telegram/index.d.ts",
+        "default": "./dist/channel-telegram/index.js"
+      },
       "./renderer-simple": {
         "types": "./dist/renderer-simple/index.d.ts",
         "default": "./dist/renderer-simple/index.js"

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

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.339.0",
+    "type": "improvement",
+    "title": "emailPasswordClient({ loginUrl, postLogoutUrl }) sends unauthenticated visitors to an external login page with a same-origin next path and navigates there on logout",
+    "detail": "emailPasswordClient accepts loginUrl and postLogoutUrl for external login pages",
+    "migration": "No code change needed."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

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

@@ -159,9 +159,7 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
       let committed = false;
       try {
         const invitation = await fetchOne<InvitationRow>(
-          ctx.db.unsafeRaw(
-            "reads the pending invitation by id; the invitee is not yet a member of the invitation's tenant",
-          ),
+          ctx.db.unsafeRaw(),
           tenantInvitationsTable,
           { id: invitationId },
         );
@@ -214,9 +212,7 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
 
         const userId = userRow.id;
 
-        const dbConn = ctx.db.unsafeRaw(
-          "adds the membership and accepts the invitation in the invitation's tenant, which differs from the caller's tenant",
-        );
+        const dbConn = ctx.db.unsafeRaw();
 
         const grant = await grantInvitedMembershipRole(dbConn, {
           userId,

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

@@ -63,10 +63,6 @@ const invitationExecutor = createEventStoreExecutor(
 
 const INVITE_ACCEPT_ESCAPE_HATCH_REASON =
   "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.";
-const READ_PENDING_INVITATION_REASON =
-  "reads the pending invitation by id; the invitee is not yet a member of the invitation's tenant";
-const ADD_MEMBERSHIP_INVITATION_TENANT_REASON =
-  "adds the membership and accepts the invitation in the invitation's tenant, which differs from the caller's tenant";
 
 export function createInviteAcceptHandler() {
   return defineWriteHandler<"invite-accept", typeof InviteAcceptSchema, InviteAcceptData>({
@@ -116,7 +112,7 @@ export function createInviteAcceptHandler() {
       let committed = false;
       try {
         const invitation = await fetchOne<InvitationRow>(
-          ctx.db.unsafeRaw(READ_PENDING_INVITATION_REASON),
+          ctx.db.unsafeRaw(),
           tenantInvitationsTable,
           { id: invitationId },
         );
@@ -147,7 +143,7 @@ export function createInviteAcceptHandler() {
 
         // Executor instead of dispatcher.writeAs(addMember): addMember only
         // accepts SystemAdmin, createSystemUser carries "system".
-        const dbConn = ctx.db.unsafeRaw(ADD_MEMBERSHIP_INVITATION_TENANT_REASON);
+        const dbConn = ctx.db.unsafeRaw();
         const grant = await grantInvitedMembershipRole(dbConn, {
           userId: event.user.id,
           tenantId: invitationTenantId,

package/packages/bundled-features/src/auth-email-password/handlers/invite-info.query.ts

@@ -65,11 +65,9 @@ export const inviteInfoQuery = defineQueryHandler({
       readonly id: string;
     };
 
-    const invitation = await fetchOne<InvitationRow>(
-      ctx.db.unsafeRaw(READ_PENDING_INVITATION_REASON),
-      tenantInvitationsTable,
-      { id: invitationId },
-    );
+    const invitation = await fetchOne<InvitationRow>(ctx.db.unsafeRaw(), tenantInvitationsTable, {
+      id: invitationId,
+    });
     if (!invitation || invitation.status !== INVITATION_STATUS.pending) {
       throwInvalidInviteToken();
     }

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

@@ -79,10 +79,6 @@ const invitationExecutor = createEventStoreExecutor(
 
 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.";
-const READ_PENDING_INVITATION_REASON =
-  "reads the pending invitation by id; the invitee is not yet a member of the invitation's tenant";
-const CREATE_USER_AND_MEMBERSHIP_INVITATION_TENANT_REASON =
-  "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() {
   return defineWriteHandler<
@@ -123,7 +119,7 @@ export function createInviteSignupCompleteHandler() {
       let committed = false;
       try {
         const invitation = await fetchOne<InvitationRow>(
-          ctx.db.unsafeRaw(READ_PENDING_INVITATION_REASON),
+          ctx.db.unsafeRaw(),
           tenantInvitationsTable,
           { id: invitationId },
         );
@@ -155,9 +151,7 @@ export function createInviteSignupCompleteHandler() {
         // signup-confirm), emailVerified=true wegen Magic-Link.
         // @cast-boundary db-runner — helpers use only the query API that
         // DbConnection and DbTx share.
-        const dbConn = ctx.db.unsafeRaw(
-          CREATE_USER_AND_MEMBERSHIP_INVITATION_TENANT_REASON,
-        ) as DbConnection;
+        const dbConn = ctx.db.unsafeRaw() as DbConnection;
         const { id: userId } = await seedUserWithPassword(dbConn, {
           email: invitationEmail,
           password: event.payload.password,

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

@@ -160,7 +160,7 @@ export function createSignupConfirmHandler() {
         // Fallback bei Kollision (siehe generateUniqueName).
         // @cast-boundary db-runner — helpers use only the query API that
         // DbConnection and DbTx share.
-        const dbConn = ctx.db.unsafeRaw(SIGNUP_CONFIRM_PROVISION_REASON) as DbConnection;
+        const dbConn = ctx.db.unsafeRaw() as DbConnection;
 
         const tenantKey = await generateUniqueName({
           isAvailable: async (slug) => {

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

@@ -172,7 +172,7 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
         } else {
           try {
             const verified = await provider.verifyGrant({
-              db: ctx.db.unsafeRaw(HANDOVER_GRANT_VERIFY_REASON),
+              db: ctx.db.unsafeRaw(),
               registry: ctx.registry,
               entityType,
               token: grantToken,

package/packages/bundled-features/src/auth-email-password/web/auth-gate.tsx

@@ -10,6 +10,7 @@
 // Screen rein konfigurieren, ohne den Gate selbst ersetzen zu müssen.
 
 import { type ComponentType, type ReactNode, useEffect, useState } from "react";
+import { assertNavigableUrl, buildLoginRedirectUrl } from "./auth-redirect.js";
 import { LoginScreen, type LoginScreenProps } from "./login-screen.js";
 import { SessionProvider, useSession } from "./session.js";
 import { SessionBootstrapErrorScreen } from "./session-bootstrap-error.js";
@@ -149,13 +150,42 @@ export function createLoginRoute(
   return LoginRoute;
 }
 
-export function makeAuthGate(opts: LoginRouteOptions = {}): ComponentType<{
+export type AuthGateOptions = LoginRouteOptions & {
+  /** Login page outside the SPA (root-relative path or http(s) URL). Unauthenticated
+   *  visitors are sent there with `next=<current path>`; the built-in login screen
+   *  is not rendered. */
+  readonly loginUrl?: string;
+};
+
+export type SessionAuthGateOptions = AuthGateOptions & {
+  /** Where logout navigates to (root-relative path or http(s) URL). Without it, logout reloads the page. */
+  readonly postLogoutUrl?: string;
+};
+
+function redirectToLoginUrl(loginUrl: string): void {
+  const { origin, pathname, search, hash } = window.location;
+  // Compared before `next` is appended: the target always differs from the current
+  // URL once it carries next, so a gate mounted on the login page itself would loop.
+  const loginLocation = new URL(loginUrl, origin);
+  if (loginLocation.origin === origin && loginLocation.pathname === pathname) return;
+  window.location.replace(buildLoginRedirectUrl(loginUrl, `${pathname}${search}${hash}`, origin));
+}
+
+export function makeAuthGate(opts: AuthGateOptions = {}): ComponentType<{
   children: ReactNode;
 }> {
+  const { loginUrl } = opts;
+  if (loginUrl !== undefined) assertNavigableUrl(loginUrl, "loginUrl");
   const LoginRoute = createLoginRoute(opts);
   function AuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     const { status } = useSession();
+    const redirectsToLoginUrl = loginUrl !== undefined && status === "unauthenticated";
+    // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
+    useEffect(() => {
+      if (redirectsToLoginUrl) redirectToLoginUrl(loginUrl);
+    }, [redirectsToLoginUrl]);
     if (status === "authenticated") return <>{children}</>;
+    if (redirectsToLoginUrl) return null;
     return <LoginRoute />;
   }
   return AuthGate;
@@ -164,13 +194,15 @@ export function makeAuthGate(opts: LoginRouteOptions = {}): ComponentType<{
 // SessionProvider + AuthGate as one gate, so a public gate in front (e.g.
 // /calculator) doesn't mount the session bootstrap — createKumikoApp stacks
 // providers outside all gates, so SessionProvider can't be a provider anymore.
-export function makeSessionAuthGate(opts: LoginRouteOptions = {}): ComponentType<{
+export function makeSessionAuthGate(opts: SessionAuthGateOptions = {}): ComponentType<{
   children: ReactNode;
 }> {
+  const { postLogoutUrl } = opts;
+  if (postLogoutUrl !== undefined) assertNavigableUrl(postLogoutUrl, "postLogoutUrl");
   const AuthGate = makeAuthGate(opts);
   function SessionAuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     return (
-      <SessionProvider>
+      <SessionProvider postLogoutUrl={postLogoutUrl}>
         <AuthGate>{children}</AuthGate>
       </SessionProvider>
     );

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

@@ -0,0 +1,60 @@
+// @runtime client
+// Redirect targets for external login pages. `next` travels through the query
+// string, so anything read back from it is untrusted: only same-origin
+// root-relative paths pass (no "//host", no "/\host", no scheme).
+
+export const NEXT_QUERY_PARAM = "next";
+
+function hasControlOrWhitespace(candidate: string): boolean {
+  for (let i = 0; i < candidate.length; i++) {
+    const code = candidate.charCodeAt(i);
+    if (code <= 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+// The URL parse is a backstop: browsers strip tabs/newlines, so "/\t/evil.com"
+// would otherwise normalize to "//evil.com" past the leading-slash check.
+export function isSafeNextPath(candidate: unknown): candidate is string {
+  if (typeof candidate !== "string" || !candidate.startsWith("/")) return false;
+  if (candidate[1] === "/" || candidate.includes("\\")) return false;
+  if (hasControlOrWhitespace(candidate)) return false;
+  try {
+    const parsed = new URL(candidate, "https://next.invalid");
+    return parsed.origin === "https://next.invalid" && !parsed.pathname.startsWith("//");
+  } catch {
+    return false;
+  }
+}
+
+export function readNextFromSearch(search: string): string | null {
+  const candidate = new URLSearchParams(search).get(NEXT_QUERY_PARAM);
+  return isSafeNextPath(candidate) ? candidate : null;
+}
+
+// loginUrl/postLogoutUrl come from app code (trusted), but a typo like
+// "javascript:" must fail at startup instead of becoming a navigation target.
+export function assertNavigableUrl(url: string, optionName: string): void {
+  // skip: a safe root-relative path needs no protocol check
+  if (url.startsWith("/") && isSafeNextPath(url)) return;
+  let protocol: string;
+  try {
+    protocol = new URL(url).protocol;
+  } catch {
+    throw new Error(`${optionName} must be a root-relative path or an http(s) URL, got "${url}"`);
+  }
+  if (protocol !== "http:" && protocol !== "https:") {
+    throw new Error(`${optionName} must be a root-relative path or an http(s) URL, got "${url}"`);
+  }
+}
+
+export function buildLoginRedirectUrl(
+  loginUrl: string,
+  returnPath: string,
+  currentOrigin: string,
+): string {
+  const target = new URL(loginUrl, currentOrigin);
+  if (isSafeNextPath(returnPath)) target.searchParams.set(NEXT_QUERY_PARAM, returnPath);
+  const isSameOrigin = target.origin === currentOrigin;
+  return isSameOrigin ? `${target.pathname}${target.search}${target.hash}` : target.href;
+}

package/packages/bundled-features/src/auth-email-password/web/client-plugin.ts

@@ -9,6 +9,7 @@ import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ComponentType, ReactNode } from "react";
 import { defaultTranslations, mergeTranslations } from "../i18n.js";
 import {
+  type AuthGateOptions,
   type MfaSetupComponentProps,
   type MfaVerifyComponentProps,
   makeSessionAuthGate,
@@ -32,6 +33,13 @@ export type EmailPasswordClientOptions = {
    *  as mfaVerifyScreen above. Apps not mounting auth-mfa simply don't
    *  pass this. */
   readonly mfaSetupScreen?: ComponentType<MfaSetupComponentProps>;
+  /** Login page outside the SPA (root-relative path or http(s) URL). Unauthenticated
+   *  visitors are redirected there with `next=<current path>` instead of seeing the
+   *  built-in login screen. Read `next` back with readNextFromSearch (same-origin
+   *  paths only). */
+  readonly loginUrl?: AuthGateOptions["loginUrl"];
+  /** Where logout navigates to (root-relative path or http(s) URL). Default: reload. */
+  readonly postLogoutUrl?: string;
   /** Key-Overrides pro Locale. Wird mit den Default-Bundles (de/en)
    *  aus `translations.ts` gemerged — jeder hier gesetzte Key gewinnt.
    *  Für Branding ("Sign in" → "Login to Acme") oder weitere Sprachen
@@ -62,6 +70,8 @@ export function emailPasswordClient(
         loginScreenProps: options.loginScreenProps,
         mfaVerifyScreen: options.mfaVerifyScreen,
         mfaSetupScreen: options.mfaSetupScreen,
+        loginUrl: options.loginUrl,
+        postLogoutUrl: options.postLogoutUrl,
       }),
     ],
     translations,

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

@@ -32,11 +32,19 @@ export {
 export type { AuthCardProps, AuthShellRenderer } from "./auth-form-primitives.js";
 export { AuthCard, AuthShellProvider, useAuthShell } from "./auth-form-primitives.js";
 export type {
+  AuthGateOptions,
   LoginRouteOptions,
   MfaSetupComponentProps,
   MfaVerifyComponentProps,
+  SessionAuthGateOptions,
 } from "./auth-gate.js";
 export { createLoginRoute, makeAuthGate, makeSessionAuthGate } from "./auth-gate.js";
+export {
+  buildLoginRedirectUrl,
+  isSafeNextPath,
+  NEXT_QUERY_PARAM,
+  readNextFromSearch,
+} from "./auth-redirect.js";
 export type {
   EmailPasswordClientFeature,
   EmailPasswordClientOptions,

package/packages/bundled-features/src/auth-email-password/web/session.tsx

@@ -152,7 +152,14 @@ function toBootstrapFailure(err: unknown): SessionBootstrapFailure {
   return { httpStatus: null, retryAfterSeconds: null, failedAtEpochMs: Date.now() };
 }
 
-export function SessionProvider({ children }: { readonly children: ReactNode }): ReactNode {
+export function SessionProvider({
+  children,
+  postLogoutUrl,
+}: {
+  readonly children: ReactNode;
+  /** Logout navigates here instead of reloading. Validated by makeSessionAuthGate. */
+  readonly postLogoutUrl?: string;
+}): ReactNode {
   const [state, setState] = useState<SessionState>(INITIAL);
 
   // Never rejects, so bootstrap can't strand the UI on "loading" forever.
@@ -197,6 +204,12 @@ export function SessionProvider({ children }: { readonly children: ReactNode }):
 
   const logout = useCallback<SessionApi["logout"]>(async () => {
     await logoutApi();
+    if (postLogoutUrl !== undefined && typeof window !== "undefined") {
+      // State stays untouched: flipping to unauthenticated would let an AuthGate
+      // with loginUrl race this navigation to its own redirect.
+      window.location.assign(postLogoutUrl);
+      return;
+    }
     setState(UNAUTHENTICATED);
     // Hard-Reload: React-Tree, dispatcher-live-Caches, EventSource —
     // alles fliegt auf Null. Nach Logout ist das der billigste Weg zu
@@ -205,7 +218,7 @@ export function SessionProvider({ children }: { readonly children: ReactNode }):
     if (typeof window !== "undefined") {
       window.location.reload();
     }
-  }, []);
+  }, [postLogoutUrl]);
 
   const switchTenant = useCallback<SessionApi["switchTenant"]>(async (tenantId) => {
     await switchTenantApi(tenantId);

package/packages/bundled-features/src/auth-mfa/feature.ts

@@ -151,7 +151,7 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
         mfaReencryptJob(
           payload,
           ctx,
-          ctx.db.unsafeRaw(REENCRYPT_ESCAPE_HATCH_REASON) as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+          ctx.db.unsafeRaw() as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
         ),
     });
 

package/packages/bundled-features/src/auth-mfa/handlers/enable-confirm-preauth.write.ts

@@ -133,13 +133,7 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
 
       // "system" mode: no session exists yet, tenantId comes from the
       // verified token, mirroring enable-start-preauth.write.ts.
-      const scopedDb = createTenantDb(
-        ctx.db.unsafeRaw(
-          "reads the MFA enrollment of the tenant named in the signed login/setup token, not the guest dispatch tenant",
-        ),
-        tenantId,
-        "system",
-      );
+      const scopedDb = createTenantDb(ctx.db.unsafeRaw(), tenantId, "system");
       const scopedUser: SessionUser = { id: userId, tenantId, roles: ["User"] };
       const existing = await findUserMfaRow(scopedDb, scopedUser);
       if (existing) return mfaAlreadyEnabled();

package/packages/bundled-features/src/auth-mfa/handlers/enable-start-preauth.write.ts

@@ -62,11 +62,7 @@ export function createEnableStartPreauthHandler(opts: EnableStartPreauthOptions)
       // "system" mode: the guest dispatch identity's own tenantId is
       // meaningless here — the preauthSetupToken is the source of truth
       // for which tenant's row to read, mirroring verify.write.ts.
-      const scopedDb = createTenantDb(
-        ctx.db.unsafeRaw(ENABLE_START_PREAUTH_TENANT_REASON),
-        tenantId,
-        "system",
-      );
+      const scopedDb = createTenantDb(ctx.db.unsafeRaw(), tenantId, "system");
       const scopedUser: SessionUser = { id: userId, tenantId, roles: ["User"] };
       const existing = await findUserMfaRow(scopedDb, scopedUser);
       if (existing) return mfaAlreadyEnabled();

package/packages/bundled-features/src/auth-mfa/handlers/verify.write.ts

@@ -97,13 +97,7 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
       // "system" mode: this handler runs with a guest identity whose own
       // tenantId is meaningless here — the challenge token is the source
       // of truth for which tenant's row to read.
-      const scopedDb = createTenantDb(
-        ctx.db.unsafeRaw(
-          "reads the MFA enrollment of the tenant named in the signed login/setup token, not the guest dispatch tenant",
-        ),
-        tenantId,
-        "system",
-      );
+      const scopedDb = createTenantDb(ctx.db.unsafeRaw(), tenantId, "system");
       const scopedUser: SessionUser = { id: userId, tenantId, roles: ["User"] };
       const row = await findUserMfaRow(scopedDb, scopedUser);
       // MFA got disabled between login and verify (race, or a stale

package/packages/bundled-features/src/auth-mfa/mfa-code-verifier.ts

@@ -29,11 +29,7 @@ export function createMfaCodeVerifier(): MfaCodeVerifier {
       reason:
         "reads the MFA enrollment of the user being re-authenticated on the caller's handler context; the calling handler declares its own escapeHatch",
     });
-    const scopedDb = createTenantDb(
-      ctx.db.unsafeRaw("reads the MFA enrollment of the user being re-authenticated"),
-      tenantId,
-      "system",
-    );
+    const scopedDb = createTenantDb(ctx.db.unsafeRaw(), tenantId, "system");
     const row = await findUserMfaRow(scopedDb, { id: userId, tenantId, roles: [] });
     if (!row) return { enrolled: false, ok: false };
     // Fail closed without ctx.redis, matching disable.write.ts/verify.write.ts —

package/packages/bundled-features/src/auth-mfa/mfa-status-checker.ts

@@ -46,13 +46,7 @@ export function createMfaStatusChecker(opts: {
       reason:
         "reads the MFA enrollment of the tenant named in the signed login/setup token, not the guest dispatch tenant, on the caller's handler context; the calling handler declares its own escapeHatch",
     });
-    const scopedDb = createTenantDb(
-      ctx.db.unsafeRaw(
-        "reads the MFA enrollment of the tenant named in the signed login/setup token, not the guest dispatch tenant",
-      ),
-      tenantId,
-      "system",
-    );
+    const scopedDb = createTenantDb(ctx.db.unsafeRaw(), tenantId, "system");
     const scopedUser: SessionUser = { id: userId, tenantId, roles: ["User"] };
     const row = await findUserMfaRow(scopedDb, scopedUser);
 

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

@@ -1,4 +1,45 @@
 [
+  {
+    "version": "0.340.0",
+    "type": "improvement",
+    "title": "Payment and subscription projections use typed bun-db helpers",
+    "detail": "`payment-received` inserts through `insertOnConflictDoNothing`, subscription events upsert through `upsertOnConflict`. The raw `db/queries/payment-projection.ts` and `subscription-projection.ts` modules are gone.",
+    "migration": "keine"
+  },
+  {
+    "version": "0.339.0",
+    "type": "improvement",
+    "title": "Missing or unchecked checkout consent returns 422 consent_required",
+    "detail": "The consent payload is optional in the `start-plan-checkout` and `create-checkout-session` input schemas and its two flags are plain booleans. `prepareConsent` throws `UnprocessableError(\"consent_required\")` with `billing-foundation.errors.consentRequired` when consumer protection is on and the consent is missing or either flag is not true.",
+    "migration": "Clients that treated the previous `400` validation error for a missing consent as the signal must check for `422` with `reason: \"consent_required\"`."
+  },
+  {
+    "version": "0.339.0",
+    "type": "fix",
+    "title": "Contract confirmation, termination receipt and cancellation pages use \"du\"",
+    "detail": "The German contract confirmation mail, the termination and withdrawal receipt mail, the public cancellation pages and the subscription and payment submit messages address the customer with \"du\". The recorded consent statements are first-person and unchanged, so `consentTextVersion` stays the same."
+  },
+  {
+    "version": "0.339.0",
+    "type": "fix",
+    "title": "The § 312k confirm POST forwards the visitor's host to /api/write",
+    "detail": "The `/legal/kuendigen` and `/legal/cancel` pages re-enter `/api/write` through the app. The re-entry now carries `Host`, `X-Forwarded-Host`, `X-Forwarded-Proto`, `X-Tenant` and the `kumiko_tenant` cookie as the visitor sent them, so a host-based `tenantResolver` resolves the same tenant as for a direct call; before, it saw no host and every confirm failed with `400 tenant_required`. The session cookie, `Authorization` and `X-Forwarded-For` are not forwarded.",
+    "migration": "keine"
+  },
+  {
+    "version": "0.339.0",
+    "type": "improvement",
+    "title": "consumerProtection.terminationScope \"platform\" for hosts without a tenant",
+    "detail": "`consumerProtection.terminationScope` is `\"tenant-host\"` (default, unchanged) or `\"platform\"`. With `\"platform\"`, `request-contract-termination` is flagged `tenantlessAnonymous` and also runs on a host whose resolver returns no tenant: it finds the contract by the declarant's email as before, records on the matched tenant's subscription stream, and answers every outcome identically. An unknown option value fails at `createBillingFoundationFeature`.",
+    "migration": "Apps that serve the pages on a platform apex (publicstatus) set `consumerProtection.terminationScope: \"platform\"`. Other apps change nothing."
+  },
+  {
+    "version": "0.339.0",
+    "type": "improvement",
+    "title": "Public termination declarations cancel at the provider in a job",
+    "detail": "For the public channel, `request-contract-termination` no longer calls the provider in the request. A matched request appends the PII-free `contract-termination-declared` event (`requestId`, `declarationType`, `terminationKind`, `receivedAtIso`, `locale`) via the system-only `declare-contract-termination`; the job `cancel-on-public-termination-declared` then runs `record-contract-termination`, which asks the provider for `cancel_at_period_end` and appends `contract-termination-requested` with the outcome. Matched and unmatched requests do the same work in the request, so the response time does not reveal whether the email is a customer. The job is idempotent per `requestId`. A provider without `cancelSubscription`, a provider error or a missing subscription now sends a separate operator notice with request id and tenant id but no name or email. A public withdrawal still makes no provider call. The account path (`terminate-contract`) stays synchronous.",
+    "migration": "Code that expected `contract-termination-requested` right after the public request must wait for the job (in tests: `drainJobs`)."
+  },
   {
     "version": "0.338.0",
     "type": "improvement",

package/packages/bundled-features/src/billing-foundation/constants.ts

@@ -54,6 +54,10 @@ export const SubscriptionFoundationHandlers = {
    *  subscription stream and asks the provider to cancel (consumerProtection
    *  only). */
   recordContractTermination: "billing-foundation:write:record-contract-termination",
+  /** System-only: records that a public declaration reached a tenant's
+   *  subscription stream; the event triggers the provider cancel job
+   *  (consumerProtection only). */
+  declareContractTermination: "billing-foundation:write:declare-contract-termination",
   /** System-only: records a public declaration no single tenant could be
    *  matched to, on a system-tenant stream (consumerProtection only). */
   recordUnmatchedContractTermination:
@@ -235,3 +239,10 @@ export const DEFAULT_PURCHASE_ROLES = ["TenantAdmin", "SystemAdmin"] as const;
 // Stripe-priceIds vs PayPal-plan-ids vs Apple-product-ids
 // unterschiedliche IDs sind. Jeder Plugin definiert seinen eigenen
 // `<plugin-name>:config:price-to-tier`-Key.
+
+export const TERMINATION_SCOPES = ["tenant-host", "platform"] as const;
+export type TerminationScope = (typeof TERMINATION_SCOPES)[number];
+
+export function isTerminationScope(value: unknown): value is TerminationScope {
+  return (TERMINATION_SCOPES as readonly unknown[]).includes(value);
+}

package/packages/bundled-features/src/billing-foundation/consumer-protection/confirmation-mail.ts

@@ -25,17 +25,17 @@ const LABELS: Readonly<Record<ConsentLocale, ConfirmationLabels>> = {
   de: {
     subject: "Vertragsbestätigung",
     intro:
-      "vielen Dank für Ihre Bestellung. Hiermit bestätigen wir den Vertragsschluss mit folgendem Inhalt.",
+      "vielen Dank für deine 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",
+    consentHeading: "Deine Zustimmungen",
     consentGivenAt: "Erteilt am",
     termsHeading: "Allgemeine Geschäftsbedingungen",
-    contact: "Fragen zu Ihrem Vertrag richten Sie bitte an",
+    contact: "Fragen zu deinem Vertrag richtest du bitte an",
     every: "alle",
     intervals: {
       day: { one: "Tag", many: "Tage" },

package/packages/bundled-features/src/billing-foundation/consumer-protection/consent-gate.ts

@@ -23,10 +23,12 @@ import { consentTextVersion, resolveConsentLocale, submitMessageFor } from "./co
 
 export type CheckoutMode = "subscription" | "payment";
 
+// Optional at the schema level so a missing/unchecked consent reaches
+// prepareConsent and fails as 422 consent_required, not as a zod 400.
 export const consentPayloadSchema = z
   .object({
-    earlyPerformanceRequested: z.literal(true),
-    withdrawalLossAcknowledged: z.literal(true),
+    earlyPerformanceRequested: z.boolean(),
+    withdrawalLossAcknowledged: z.boolean(),
     consentTextVersion: z.string().min(1).max(64),
     locale: z.string().min(2).max(35),
   })
@@ -55,9 +57,15 @@ export type ConsentPriceDetails = {
 export async function prepareConsent(
   ctx: HandlerContext,
   options: ConsumerProtectionOptions,
-  consent: ConsentPayload,
+  consent: ConsentPayload | undefined,
   mode: CheckoutMode,
 ): Promise<PreparedConsent> {
+  if (!consent?.earlyPerformanceRequested || !consent.withdrawalLossAcknowledged) {
+    throw new UnprocessableError("consent_required", {
+      i18nKey: "billing-foundation.errors.consentRequired",
+      message: "billing-foundation: both consent flags must be true to start a checkout",
+    });
+  }
   const locale = resolveConsentLocale(consent.locale);
   if (consent.consentTextVersion !== consentTextVersion(locale)) {
     throw new UnprocessableError("consent_text_outdated", {

package/packages/bundled-features/src/billing-foundation/consumer-protection/consent-text.ts

@@ -24,9 +24,9 @@ export const CONSENT_TEXTS: Readonly<Record<ConsentLocale, ConsentTexts>> = {
     withdrawalLoss:
       "Ich nehme zur Kenntnis, dass ich mein Widerrufsrecht verliere, sobald der Vertrag von dem Anbieter vollständig erfüllt ist, bei digitalen Inhalten sobald die Ausführung begonnen hat, nachdem ich ausdrücklich zugestimmt habe und bestätigt habe, dass ich dadurch mein Widerrufsrecht verliere.",
     subscriptionSubmitMessage:
-      "Kostenpflichtiges Abonnement: Es verlängert sich zum Ende jedes Abrechnungszeitraums automatisch, bis Sie es kündigen. Sie können jederzeit zum Ende des laufenden Zeitraums kündigen.",
+      "Kostenpflichtiges Abonnement: Es verlängert sich zum Ende jedes Abrechnungszeitraums automatisch, bis du es kündigst. Du kannst jederzeit zum Ende des laufenden Zeitraums kündigen.",
     paymentSubmitMessage:
-      "Kostenpflichtige Einmalzahlung: Mit Klick auf den Button verpflichten Sie sich zur Zahlung.",
+      "Kostenpflichtige Einmalzahlung: Mit Klick auf den Button verpflichtest du dich zur Zahlung.",
   },
   en: {
     earlyPerformance: