@cosmicdrift/kumiko-bundled-features 0.318.0 → 0.320.0

package/src/auth-email-password/constants.ts

@@ -1,9 +1,9 @@
 // @runtime client
-// Pure string-Konstanten — keine DB/Node-builtins. Mit `@runtime client`
-// markiert damit auch Browser-Code (Members-Screen etc.) sie importieren
-// kann ohne dass die runtime-isolation-Guard schreit. Runtime darf
-// "client"-Files importieren (siehe RUNTIME_RULES), also bleibt auch
-// der server-side Zugriff (handlers, dispatcher) erhalten.
+// Pure string constants — no DB/Node builtins. Marked `@runtime client` so
+// browser code (Members screen etc.) can import them too without the
+// runtime-isolation guard complaining. Runtime may import "client" files
+// (see RUNTIME_RULES), so server-side access (handlers, dispatcher) stays
+// intact as well.
 export const AUTH_EMAIL_PASSWORD_FEATURE = "auth-email-password" as const;
 
 // Minimum length for reset/verify hmacSecret — mirrors the ≥32-char
@@ -25,20 +25,20 @@ export const AuthHandlers = {
   // Redis lockout state.
   requestAccountUnlock: "auth-email-password:write:request-account-unlock",
   confirmAccountUnlock: "auth-email-password:write:confirm-account-unlock",
-  // Magic-Link Self-Signup (Pre-Activation-Token-Pattern). request mintet
-  // einen opaken Random-Token, speichert ihn bidirektional in Redis und
-  // sendet eine Aktivierungs-Mail. confirm löst den Token ein und legt
-  // user + tenant + Admin-Membership atomar an. emailVerified=true ab
-  // Sekunde 0 — der Klick auf den Mail-Link IST der Beweis.
+  // Magic-link self-signup (pre-activation-token pattern). Request mints an
+  // opaque random token, stores it bidirectionally in Redis and sends an
+  // activation email. Confirm redeems the token and creates
+  // user + tenant + Admin membership atomically. emailVerified=true from
+  // second 0 — clicking the mail link IS the proof.
   signupRequest: "auth-email-password:write:signup-request",
   signupConfirm: "auth-email-password:write:signup-confirm",
-  // Tenant-Invite Magic-Link (Admin lädt User in existing Tenant ein).
-  // Drei separate accept-Endpoints für klare Branch-Separation:
-  //   inviteCreate: Admin → POST email + role
-  //   inviteAccept: logged-in User → POST token (membership-add)
-  //   inviteAcceptWithLogin: anon User mit existing email → POST token + email + password
-  //   inviteSignupComplete: anon User mit neuer email → POST token + password
-  //   inviteCancel: Admin cancelt pending invite
+  // Tenant-invite magic-link (admin invites a user into an existing tenant).
+  // Three separate accept endpoints for clear branch separation:
+  //   inviteCreate: admin → POST email + role
+  //   inviteAccept: logged-in user → POST token (membership-add)
+  //   inviteAcceptWithLogin: anon user with existing email → POST token + email + password
+  //   inviteSignupComplete: anon user with new email → POST token + password
+  //   inviteCancel: admin cancels a pending invite
   inviteCreate: "auth-email-password:write:invite-create",
   inviteAccept: "auth-email-password:write:invite-accept",
   inviteAcceptWithLogin: "auth-email-password:write:invite-accept-with-login",
@@ -76,20 +76,20 @@ export const AuthErrors = {
   // code so a probing client can't distinguish tampered from stale.
   invalidUnlockToken: "invalid_unlock_token",
   unlockNotConfigured: "account_unlock_not_configured",
-  // Self-Signup: alle confirm-Failures (unbekannter Token, schon
-  // konsumiert, abgelaufen) collapsen auf diesen Code — gleicher
-  // anti-enumeration-Trade-off wie reset/verify.
+  // Self-signup: all confirm failures (unknown token, already
+  // consumed, expired) collapse onto this code — same
+  // anti-enumeration trade-off as reset/verify.
   invalidSignupToken: "invalid_signup_token",
   signupNotConfigured: "signup_not_configured",
-  // Self-Signup: confirm lehnt eine bereits registrierte Email ab statt den
-  // bestehenden User wiederzuverwenden (Account-Takeover, #365). KEIN
-  // anti-enumeration-collapse wie invalidSignupToken: wer hier ankommt,
-  // kontrolliert die Inbox (hat den Magic-Link), das Reveal "Email existiert"
-  // ist also keine neue Info.
+  // Self-signup: confirm rejects an already-registered email instead of
+  // reusing the existing user (account takeover, #365). NO
+  // anti-enumeration collapse like invalidSignupToken: whoever gets here
+  // controls the inbox (has the magic link), so revealing "email exists"
+  // is not new information.
   signupEmailAlreadyRegistered: "signup_email_already_registered",
-  // Invite-Flow: alle Token-Failures collapsen auf invalidInviteToken
-  // (anti-enumeration). emailMismatch wenn der invitee versucht den
-  // Link mit einer anderen Email zu accepten als die eingeladene.
+  // Invite flow: all token failures collapse onto invalidInviteToken
+  // (anti-enumeration). emailMismatch when the invitee tries to accept the
+  // link with a different email than the one invited.
   invalidInviteToken: "invalid_invite_token",
   inviteEmailMismatch: "invite_email_mismatch",
   inviteAlreadyMember: "invite_already_member",
@@ -100,17 +100,17 @@ export const AuthErrors = {
   // deliberate enumeration trade-off: the lockout event itself is already
   // observable to the attacker, and legit users benefit from a clear signal.
   accountLocked: "account_locked",
-  // S2.U6 (DSGVO Art. 18) — Account ist im Restricted-Status. Login wird
-  // explicit verweigert mit eigenem Code (nicht zu invalid_credentials
-  // collapsen) damit UI sagen kann "Account ist aktuell pausiert, hier
-  // klicken zum Aufheben". Enumeration-leak akzeptiert: Restriction ist
-  // user-initiiert, der User weiss dass sein Konto restricted ist.
+  // S2.U6 (GDPR Art. 18) — account is in Restricted status. Login is
+  // explicitly refused with its own code (not collapsed into
+  // invalid_credentials) so the UI can say "account is currently paused,
+  // click here to lift it". Enumeration leak accepted: restriction is
+  // user-initiated, the user already knows their account is restricted.
   accountRestricted: "account_restricted",
-  // Account ist im DeletionRequested- oder Deleted-Status. Anders als
-  // Restricted ist das nicht reversibel via Login → wir collapsen auf
-  // invalid_credentials damit Forget-Pfad nicht via Login enumerierbar
-  // wird (User der "Konto loeschen" geklickt hat soll nicht erneut sehen
-  // dass die Email-Adresse noch in der DB existiert).
+  // Account is in DeletionRequested or Deleted status. Unlike
+  // Restricted, this is not reversible via login → we collapse onto
+  // invalid_credentials so the forget-path isn't enumerable via login
+  // (a user who clicked "delete account" shouldn't see again that their
+  // email address still exists in the DB).
 } as const;
 
 // Account-lockout defaults — overridable via
@@ -132,12 +132,12 @@ export const AUTH_RESET_DEFAULT_TTL_MINUTES = 15;
 // replaying the same token re-sets the same flag.
 export const AUTH_VERIFY_DEFAULT_TTL_MINUTES = 24 * 60;
 
-// Self-Signup: 24h Default. Lang genug damit User nicht denken muss
-// "schnell aktivieren" — ein Mail-Link der morgen früh noch geht ist
-// User-Friendly. Kürzere TTLs werfen Resend-Spam weil User vergessen.
+// Self-signup: 24h default. Long enough that the user doesn't have to
+// think "activate quickly" — a mail link that still works tomorrow morning
+// is user-friendly. Shorter TTLs cause resend-spam because users forget.
 export const AUTH_SIGNUP_DEFAULT_TTL_MINUTES = 24 * 60;
 
-// Tenant-Invite: 7 Tage Default. Industry-Standard (GitHub, Linear,
-// Slack); invitees brauchen oft länger zum Reagieren als bei Self-
-// Signup wo die User-Intention frisch ist.
+// Tenant invite: 7 days default. Industry standard (GitHub, Linear,
+// Slack); invitees often need longer to respond than in self-signup,
+// where the user's intent is fresh.
 export const AUTH_INVITE_DEFAULT_TTL_MINUTES = 7 * 24 * 60;

package/src/auth-email-password/index.ts

@@ -6,7 +6,7 @@
 // hashPassword/verifyPassword; removing it is a breaking change that needs
 // its own changeset + deliberate deprecation window, not a silent drop.
 export { hashPassword, verifyPassword } from "../shared/password-hashing";
-export { type AuthPaths, DEFAULT_AUTH_PATHS, makeAuthPaths } from "./auth-paths";
+export { type AuthPath, type AuthPaths, DEFAULT_AUTH_PATHS, makeAuthPaths } from "./auth-paths";
 export { AUTH_EMAIL_PASSWORD_FEATURE, AuthErrors, AuthHandlers, AuthQueries } from "./constants";
 // Renderers for the auth mails. All four magic-link flows (reset, verify,
 // signup-activation, invite) emit structured AuthMailContent through delivery

package/src/auth-email-password/web/__tests__/auth-form-logic.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, test } from "bun:test";
-import { passwordPairIssue, resolveLoggedInHref, retryAfterMinutes } from "../auth-form-logic";
+import {
+  passwordPairIssue,
+  resolveLoggedInHref,
+  resolvePostAuthHref,
+  retryAfterMinutes,
+} from "../auth-form-logic";
 
 describe("passwordPairIssue", () => {
   test("too_short when under min length", () => {
@@ -71,3 +76,31 @@ describe("resolveLoggedInHref", () => {
     ).toBe("/t1/Editor");
   });
 });
+
+describe("resolvePostAuthHref", () => {
+  type SignupArgs = { tenantKey: string; roles: readonly string[] };
+
+  test("server landingPath wins over loggedInHref", () => {
+    expect(
+      resolvePostAuthHref<SignupArgs>("/a/vehicle-create", "/", {
+        tenantKey: "acme",
+        roles: ["User"],
+      }),
+    ).toBe("/a/vehicle-create");
+  });
+
+  test("undefined landingPath falls back to loggedInHref (string form)", () => {
+    expect(
+      resolvePostAuthHref<SignupArgs>(undefined, "/fixed", { tenantKey: "acme", roles: [] }),
+    ).toBe("/fixed");
+  });
+
+  test("undefined landingPath falls back to loggedInHref (function form)", () => {
+    expect(
+      resolvePostAuthHref<SignupArgs>(undefined, ({ tenantKey }) => `/${tenantKey}/`, {
+        tenantKey: "acme",
+        roles: [],
+      }),
+    ).toBe("/acme/");
+  });
+});

package/src/auth-email-password/web/__tests__/invite-accept-screen.test.tsx

@@ -121,6 +121,36 @@ describe("InviteAcceptScreen — logged-in branch", () => {
     });
   });
 
+  test("server landingPath gewinnt über loggedInHref", async () => {
+    globalThis.fetch = mock(
+      async () =>
+        new Response(
+          JSON.stringify({
+            tenantId: "tenant-new",
+            role: "Dealer",
+            alreadyMember: false,
+            landingPath: "/a/vehicle-create",
+          }),
+          { status: 200 },
+        ),
+    ) as unknown as typeof fetch;
+    const assign = mock<(url: string) => void>();
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      writable: true,
+      value: { href: originalLocation.href, search: originalLocation.search, assign },
+    });
+
+    renderWithProviders(
+      <InviteAcceptScreen token="tok-123" loggedInHref={({ tenantId }) => `/${tenantId}/home`} />,
+      { session: makeSessionApi({ status: "authenticated" }) },
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Accept" }));
+    await waitFor(() => {
+      expect(assign).toHaveBeenCalledWith("/a/vehicle-create");
+    });
+  });
+
   test("String-Form bleibt unverändert gültig", async () => {
     const assign = mock<(url: string) => void>();
     Object.defineProperty(window, "location", {

package/src/auth-email-password/web/__tests__/signup-complete-screen.test.tsx

@@ -245,6 +245,32 @@ describe("SignupCompleteScreen", () => {
     expect(receivedArgs).toStrictEqual({ tenantKey: "acme", roles: ["User"] });
   });
 
+  test("server landingPath gewinnt über loggedInHref", async () => {
+    globalThis.fetch = mock(
+      async () =>
+        new Response(
+          JSON.stringify({
+            user: { id: "u1", tenantId: "t1", roles: ["User"] },
+            tenantKey: "acme",
+            landingPath: "/a/vehicle-create",
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        ),
+    ) as unknown as typeof fetch;
+
+    renderWithProviders(
+      <SignupCompleteScreen token="abc-token" loggedInHref={({ tenantKey }) => `/${tenantKey}/`} />,
+    );
+    fillPasswords("validpass1", "validpass1");
+    fireEvent.click(screen.getByRole("button", { name: "Activate account" }));
+
+    await waitFor(() => {
+      expect(screen.getByRole("link", { name: "Continue" }).getAttribute("href")).toBe(
+        "/a/vehicle-create",
+      );
+    });
+  });
+
   test("mismatch → client-side error, kein fetch-Call", async () => {
     const fetchMock = mock(async () => new Response(null, { status: 200 }));
     globalThis.fetch = fetchMock as unknown as typeof fetch;

package/src/auth-email-password/web/auth-client.ts

@@ -33,6 +33,9 @@ export type LoginResponse = {
     readonly tenantId: string;
     readonly roles: readonly string[];
   };
+  // Present only when the server's auth.postAuthLanding resolver returned a
+  // valid path — see auth-routes.ts. Screens prefer this over loggedInHref.
+  readonly landingPath?: string;
 };
 
 // Reason codes the login-handler is known to emit today (login-screen.tsx's
@@ -93,6 +96,14 @@ export type LoginResult =
   | { readonly kind: "mfa-setup-required"; readonly preauthSetupToken: string }
   | { readonly kind: "failure"; readonly error: LoginFailure };
 
+function toLoginResponse(
+  token: string,
+  user: LoginResponse["user"],
+  landingPath: unknown,
+): LoginResponse {
+  return typeof landingPath === "string" ? { token, user, landingPath } : { token, user };
+}
+
 // POST /api/auth/login. Success → token + user; MFA-enrolled user → a
 // challenge token the caller completes via auth-mfa's verify screen;
 // unenrolled user blocked by enforcement policy → mfa-setup-required;
@@ -118,6 +129,7 @@ export async function login(req: LoginRequest): Promise<LoginResult> {
     challengeToken?: string;
     mfaSetupRequired?: boolean;
     preauthSetupToken?: string;
+    landingPath?: string;
     error?:
       | {
           code?: string;
@@ -140,7 +152,7 @@ export async function login(req: LoginRequest): Promise<LoginResult> {
       return { kind: "failure", error: { reason: "mfa_setup_required" } };
     }
     if (body.token !== undefined && body.user !== undefined) {
-      return { kind: "success", data: { token: body.token, user: body.user } };
+      return { kind: "success", data: toLoginResponse(body.token, body.user, body.landingPath) };
     }
   }
   // Der Server schickt error entweder als string ("invalid_body") oder als
@@ -343,6 +355,9 @@ export type SignupConfirmSuccess = {
   // Present only when a bound handover grant existed and its claim
   // succeeded — see signup-confirm.write.ts.
   readonly handover?: { readonly entityType: string; readonly id: string };
+  // Present only when the server's auth.postAuthLanding resolver returned a
+  // valid path — see auth-routes.ts.
+  readonly landingPath?: string;
 };
 
 export async function confirmSignup(

package/src/auth-email-password/web/auth-form-logic.ts

@@ -28,3 +28,13 @@ export function resolveLoggedInHref<Args>(
 ): string {
   return typeof href === "function" ? href(args) : href;
 }
+
+/** The server's `landingPath` (auth.postAuthLanding) wins over the screen's
+ *  loggedInHref prop — that prop is a deprecated per-app fallback. */
+export function resolvePostAuthHref<Args>(
+  landingPath: string | undefined,
+  href: string | ((args: Args) => string),
+  args: Args,
+): string {
+  return landingPath ?? resolveLoggedInHref(href, args);
+}

package/src/auth-email-password/web/invite-accept-screen.tsx

@@ -19,7 +19,7 @@
 import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type FormEvent, type ReactNode, useContext, useState } from "react";
 import { csrfHeader } from "./auth-client";
-import { resolveLoggedInHref } from "./auth-form-logic";
+import { resolvePostAuthHref } from "./auth-form-logic";
 import { AuthCard, useUrlToken } from "./auth-form-primitives";
 import { SessionContext, UNAUTHENTICATED } from "./session";
 
@@ -29,7 +29,9 @@ export type InviteAcceptScreenProps = {
   /** Where to redirect on success. Default "/" — multi-tenant apps can pass
    *  `(data) => "/${data.tenantId}/"`. Function-form receives the roles this
    *  flow grants in the target tenant; branch 1 reports the invitation's
-   *  role, which for an existing member is not their full role set there. */
+   *  role, which for an existing member is not their full role set there.
+   *  @deprecated Configure auth.postAuthLanding on the server; its landingPath wins.
+   *  Kept as fallback. */
   readonly loggedInHref?:
     | string
     | ((args: { tenantId: string; roles: readonly string[] }) => string);
@@ -46,6 +48,9 @@ type InviteAcceptResponse = {
   readonly tenantId: string;
   readonly role?: string;
   readonly user?: { readonly roles?: readonly string[] };
+  // Present only when the server's auth.postAuthLanding resolver returned a
+  // valid path — see auth-routes.ts.
+  readonly landingPath?: string;
 };
 
 function grantedRoles(data: InviteAcceptResponse): readonly string[] {
@@ -92,7 +97,7 @@ export function InviteAcceptScreen({
       // @cast-boundary engine-payload — auth route JSON
       const data = (await res.json()) as InviteAcceptResponse;
       window.location.assign(
-        resolveLoggedInHref(loggedInHref, {
+        resolvePostAuthHref(data.landingPath, loggedInHref, {
           tenantId: data.tenantId,
           roles: grantedRoles(data),
         }),
@@ -117,7 +122,7 @@ export function InviteAcceptScreen({
       // @cast-boundary engine-payload — auth route JSON
       const data = (await res.json()) as InviteAcceptResponse;
       window.location.assign(
-        resolveLoggedInHref(loggedInHref, {
+        resolvePostAuthHref(data.landingPath, loggedInHref, {
           tenantId: data.tenantId,
           roles: grantedRoles(data),
         }),
@@ -142,7 +147,7 @@ export function InviteAcceptScreen({
       // @cast-boundary engine-payload — auth route JSON
       const data = (await res.json()) as InviteAcceptResponse;
       window.location.assign(
-        resolveLoggedInHref(loggedInHref, {
+        resolvePostAuthHref(data.landingPath, loggedInHref, {
           tenantId: data.tenantId,
           roles: grantedRoles(data),
         }),

package/src/auth-email-password/web/signup-complete-screen.tsx

@@ -10,15 +10,17 @@
 // server-side token pass `token` as a prop instead.
 //
 // On success: shows a confirmation (account active, signed in) with a
-// button to loggedInHref, instead of navigating away immediately — the
-// server already logged the user in via cookies, but a silent redirect
-// leaves no signal that activation worked. Default pattern is "/" — apps
-// with multi-tenant routing pass `(data) => "/" + data.tenantKey + "/"`.
+// button to the continue target, instead of navigating away immediately —
+// the server already logged the user in via cookies, but a silent redirect
+// leaves no signal that activation worked. Server-side auth.postAuthLanding
+// (landingPath) wins over loggedInHref; loggedInHref is the deprecated
+// per-app fallback. Default pattern is "/" — apps with multi-tenant routing
+// pass `(data) => "/" + data.tenantKey + "/"`.
 
 import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type FormEvent, type ReactNode, useState } from "react";
 import { confirmSignup, type SignupConfirmSuccess } from "./auth-client";
-import { passwordPairIssue, resolveLoggedInHref } from "./auth-form-logic";
+import { passwordPairIssue, resolvePostAuthHref } from "./auth-form-logic";
 import { AuthCard, useUrlToken } from "./auth-form-primitives";
 
 export type SignupCompleteScreenProps = {
@@ -27,7 +29,9 @@ export type SignupCompleteScreenProps = {
   readonly token?: string;
   /** Where to send the user after activation. Function-form receives the tenantKey, the
    *  roles granted by this flow in that tenant, and the claimed `handover` entity when
-   *  signup claimed a try-first grant. Default "/". */
+   *  signup claimed a try-first grant. Default "/".
+   *  @deprecated Configure auth.postAuthLanding on the server; its landingPath wins.
+   *  Kept as fallback. */
   readonly loggedInHref?:
     | string
     | ((args: {
@@ -73,7 +77,7 @@ export function SignupCompleteScreen({
       // explicit continue button instead of navigating away silently —
       // the user otherwise gets no signal that activation worked.
       setContinueHref(
-        resolveLoggedInHref(loggedInHref, {
+        resolvePostAuthHref(res.data.landingPath, loggedInHref, {
           tenantKey: res.data.tenantKey,
           roles: res.data.user.roles,
           ...(res.data.handover !== undefined && { handover: res.data.handover }),

package/src/auth-mfa/web/mfa-client.ts

@@ -32,6 +32,7 @@ export async function verifyMfaChallenge(
     isSuccess?: boolean;
     token?: string;
     user?: LoginResponse["user"];
+    landingPath?: string;
     error?:
       | {
           code?: string;
@@ -41,7 +42,14 @@ export async function verifyMfaChallenge(
       | string;
   };
   if (body.isSuccess === true && body.token !== undefined && body.user !== undefined) {
-    return { kind: "success", data: { token: body.token, user: body.user } };
+    return {
+      kind: "success",
+      data: {
+        token: body.token,
+        user: body.user,
+        ...(typeof body.landingPath === "string" && { landingPath: body.landingPath }),
+      },
+    };
   }
   const err = body.error;
   if (typeof err === "string") {
@@ -156,6 +164,7 @@ export async function confirmMfaSetupPreauth(
     isSuccess?: boolean;
     token?: string;
     user?: LoginResponse["user"];
+    landingPath?: string;
     error?:
       | {
           code?: string;
@@ -165,7 +174,14 @@ export async function confirmMfaSetupPreauth(
       | string;
   };
   if (body.isSuccess === true && body.token !== undefined && body.user !== undefined) {
-    return { kind: "success", data: { token: body.token, user: body.user } };
+    return {
+      kind: "success",
+      data: {
+        token: body.token,
+        user: body.user,
+        ...(typeof body.landingPath === "string" && { landingPath: body.landingPath }),
+      },
+    };
   }
   const err = body.error;
   if (typeof err === "string") {

package/src/billing-foundation/__tests__/billing-foundation.integration.test.ts

@@ -77,6 +77,7 @@ const mockProviderFeature = defineFeature("test-mock-provider", (r) => {
     // exercise — the hardened create-checkout-session now requires every
     // mode:"subscription" priceId to resolve through priceToTier.
     priceToTier: { price_pro_test: "pro", price_business_test: "business" },
+    oneOffPriceIds: ["price_topup_test"],
     createCheckoutSession: async (_ctx, options) => {
       mockCheckoutCalls.push({
         priceId: options.priceId,
@@ -178,6 +179,7 @@ function buildEvent(
     providerCustomerId: string;
     providerSubscriptionId: string;
     currentPeriodEndIso: string;
+    cancelAtIso: string | null;
     rawPayload: string;
   }> = {},
 ) {
@@ -190,6 +192,12 @@ function buildEvent(
     status: overrides.status ?? SubscriptionStatuses.active,
     tier: overrides.tier ?? "pro",
     currentPeriodEndIso: overrides.currentPeriodEndIso ?? "2026-06-01T00:00:00Z",
+    // `cancelAtIso` stays entirely absent from the payload unless an override
+    // sets it — undefined (key omitted) vs. null (explicit clear) is the
+    // 3-way distinction cancelAtSetFromPayload relies on; a `?? undefined`
+    // default here would collapse "omitted" into "explicit null" and hide a
+    // regression where a later event without the field wipes a prior value.
+    ...(overrides.cancelAtIso !== undefined && { cancelAtIso: overrides.cancelAtIso }),
     rawPayload: overrides.rawPayload ?? '{"raw":"payload"}',
   };
 }
@@ -677,7 +685,7 @@ describe("scenario 7: create-portal-session — Plugin-routing", () => {
 
     const result = (await stack.http.writeOk(
       "billing-foundation:write:create-portal-session",
-      { returnUrl: "https://example.com/return" },
+      {},
       admin,
     )) as Record<string, unknown>;
 
@@ -687,11 +695,13 @@ describe("scenario 7: create-portal-session — Plugin-routing", () => {
     // Drift-pin: portal-handler liest providerCustomerId AUS DER DB
     // (subscription-row), nicht aus der payload. Wenn ein Refactor das
     // umstellt (= Tenant könnte fremde portal-sessions öffnen), würde
-    // mockPortalCalls den falschen customer-id sehen.
+    // mockPortalCalls den falschen customer-id sehen. returnUrl is now
+    // server-computed (portalReturnUrl) — no catalog mounted here, so it
+    // collapses onto baseUrl itself.
     expect(mockPortalCalls).toHaveLength(1);
     expect(mockPortalCalls[0]).toEqual({
       providerCustomerId: "cus_3013",
-      returnUrl: "https://example.com/return",
+      returnUrl: "https://example.com",
     });
   });
 
@@ -699,7 +709,7 @@ describe("scenario 7: create-portal-session — Plugin-routing", () => {
     const admin = adminFor(3011);
     const error = await stack.http.writeErr(
       "billing-foundation:write:create-portal-session",
-      { returnUrl: "https://example.com/return" },
+      {},
       admin,
     );
     expect(JSON.stringify(error)).toMatch(/no active subscription/);
@@ -746,6 +756,68 @@ describe("scenario 8: cancel-event setzt status auf canceled, behält subscripti
   });
 });
 
+describe("scenario 8b: cancelAt — set / leave-unchanged / clear across events", () => {
+  test("event without cancelAtIso key keeps a prior value; explicit null clears it", async () => {
+    const admin = adminFor(3009);
+
+    // 1. create with cancelAt set — a Stripe cancel_at_period_end webhook.
+    await stack.http.writeOk(
+      SubscriptionFoundationHandlers.processEvent,
+      buildEvent({
+        providerEventId: "evt_3009_create",
+        providerCustomerId: "cus_3009",
+        providerSubscriptionId: "sub_3009",
+        cancelAtIso: "2026-07-01T00:00:00Z",
+      }),
+      admin,
+    );
+    let subs = (await stack.http.queryOk(
+      "billing-foundation:query:subscription:list",
+      {},
+      admin,
+    )) as { rows: Array<Record<string, unknown>> };
+    expect(subs.rows[0]?.["cancelAt"]).toBe("2026-07-01T00:00:00Z");
+
+    // 2. an unrelated update event that never mentions cancelAtIso (e.g. a
+    // price/tier change) must NOT wipe the previously recorded cancelAt.
+    await stack.http.writeOk(
+      SubscriptionFoundationHandlers.processEvent,
+      buildEvent({
+        providerEventId: "evt_3009_update",
+        type: SubscriptionEventTypes.updated,
+        providerCustomerId: "cus_3009",
+        providerSubscriptionId: "sub_3009",
+        tier: "business",
+      }),
+      admin,
+    );
+    subs = (await stack.http.queryOk("billing-foundation:query:subscription:list", {}, admin)) as {
+      rows: Array<Record<string, unknown>>;
+    };
+    expect(subs.rows[0]?.["tier"]).toBe("business");
+    expect(subs.rows[0]?.["cancelAt"]).toBe("2026-07-01T00:00:00Z");
+
+    // 3. reactivation — an update event with cancelAtIso explicitly null
+    // clears it.
+    await stack.http.writeOk(
+      SubscriptionFoundationHandlers.processEvent,
+      buildEvent({
+        providerEventId: "evt_3009_reactivate",
+        type: SubscriptionEventTypes.updated,
+        providerCustomerId: "cus_3009",
+        providerSubscriptionId: "sub_3009",
+        tier: "business",
+        cancelAtIso: null,
+      }),
+      admin,
+    );
+    subs = (await stack.http.queryOk("billing-foundation:query:subscription:list", {}, admin)) as {
+      rows: Array<Record<string, unknown>>;
+    };
+    expect(subs.rows[0]?.["cancelAt"]).toBeNull();
+  });
+});
+
 // scenario 9 (subscriptionTenantDestroyHook direct-call, default+HGB branches) removed:
 // covered end-to-end by billing-foundation/__tests__/tenant-destroy.integration.test.ts,
 // which drives the real tenant-lifecycle sweep instead of hand-feeding the hook.