@cosmicdrift/kumiko-samples 0.388.0 → 0.390.0

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

@@ -168,9 +168,9 @@ async function issueInvitation(
   ctx: HandlerContext,
   refuseAccepted = false,
 ): Promise<WriteResult<InviteCreateData>> {
-  if (!ctx.redis) {
+  if (!ctx.services.redis) {
     return writeFailure(
-      new InternalError({ message: "invite-create requires ctx.redis for token store" }),
+      new InternalError({ message: "invite-create requires ctx.services.redis for token store" }),
     );
   }
 
@@ -197,7 +197,7 @@ async function issueInvitation(
     const existingVersion = existing["version"] as number; // @cast-boundary db-row
     // At most one live invite token per invitation: invalidate
     // whatever's there before minting the new one.
-    await invalidateExistingInviteToken(ctx.redis, invitationId);
+    await invalidateExistingInviteToken(ctx.services.redis, invitationId);
 
     const updateResult = await executor.update(
       {
@@ -237,7 +237,7 @@ async function issueInvitation(
   }
 
   const token = generateToken();
-  await storeInviteToken(ctx.redis, { invitationId, token, ttlSeconds });
+  await storeInviteToken(ctx.services.redis, { invitationId, token, ttlSeconds });
 
   const locale = request.locale ?? resolveHandlerMailLocale(ctx, opts.locale);
 

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

@@ -52,9 +52,9 @@ export const inviteInfoQuery = defineQueryHandler({
     "Anonymous, read-only invite lookup for the invite-acceptance page: reveals the invited " +
     "email and whether an account already exists for it, without consuming the token.",
   handler: async (query, ctx) => {
-    if (!ctx.redis) throwInvalidInviteToken();
+    if (!ctx.services.redis) throwInvalidInviteToken();
 
-    const invitationId = await getInvitationIdForToken(ctx.redis, query.payload.token);
+    const invitationId = await getInvitationIdForToken(ctx.services.redis, query.payload.token);
     if (!invitationId) throwInvalidInviteToken();
 
     type InvitationRow = {

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

@@ -103,16 +103,16 @@ export function createInviteSignupCompleteHandler(opts: InviteSignupCompleteOpti
       reason: INVITE_SIGNUP_COMPLETE_ESCAPE_HATCH_REASON,
     },
     handler: async (event, ctx) => {
-      if (!ctx.redis) {
+      if (!ctx.services.redis) {
         return writeFailure(
-          new InternalError({ message: "invite-signup-complete requires ctx.redis" }),
+          new InternalError({ message: "invite-signup-complete requires ctx.services.redis" }),
         );
       }
 
-      const invitationId = await getInvitationIdForToken(ctx.redis, event.payload.token);
+      const invitationId = await getInvitationIdForToken(ctx.services.redis, event.payload.token);
       if (!invitationId) return invalidInviteToken();
 
-      const burn = await burnInviteToken(ctx.redis, event.payload.token);
+      const burn = await burnInviteToken(ctx.services.redis, event.payload.token);
       if (burn === "already-used") return invalidInviteToken();
 
       type InvitationRow = {
@@ -187,6 +187,8 @@ export function createInviteSignupCompleteHandler(opts: InviteSignupCompleteOpti
           db: dbConn,
           tenantId: invitationTenantId,
           mode: "system",
+          reason:
+            "invitation tenant differs from the caller's tenant, the accept step updates the invitation row there",
         });
         const updateResult = await invitationExecutor.update(
           {
@@ -214,7 +216,7 @@ export function createInviteSignupCompleteHandler(opts: InviteSignupCompleteOpti
           mergedRoles,
         );
 
-        await deleteInviteToken(ctx.redis, { invitationId, token: event.payload.token });
+        await deleteInviteToken(ctx.services.redis, { invitationId, token: event.payload.token });
 
         if (mfaGate !== undefined) {
           committed = true;
@@ -239,8 +241,8 @@ export function createInviteSignupCompleteHandler(opts: InviteSignupCompleteOpti
           },
         };
       } finally {
-        if (!committed && ctx.redis) {
-          await unburnInviteToken(ctx.redis, event.payload.token);
+        if (!committed && ctx.services.redis) {
+          await unburnInviteToken(ctx.services.redis, event.payload.token);
         }
       }
     },

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

@@ -35,7 +35,7 @@ export type LoginHandlerOptions = {
   readonly strictEmailVerification?: boolean;
   // Brute-force protection: after N wrong-password attempts the account
   // locks for the configured duration. State lives in Redis (see
-  // lockout-store.ts) — if ctx.redis is unset, lockout is skipped and the
+  // lockout-store.ts) — if ctx.services.redis is unset, lockout is skipped and the
   // handler falls back to classic invalid-credentials. Counter is monotonic
   // and only resets on a successful login, so a re-lock after the cooldown
   // happens on the FIRST miss, not the Nth (strict semantic — favours
@@ -123,10 +123,10 @@ export async function gateCountUnknownUser(
   lockoutDurationMinutes: number,
 ): Promise<GateOutcome<undefined>> {
   const subject = unknownEmailLockoutSubject(ctx, email);
-  if (!ctx.redis || subject === undefined) return ok(undefined);
+  if (!ctx.services.redis || subject === undefined) return ok(undefined);
   const locked = await gateEnforceLockout(ctx, subject);
   if (!locked.ok) return locked;
-  await recordFailedAttempt(ctx.redis, subject, maxFailedAttempts, lockoutDurationMinutes);
+  await recordFailedAttempt(ctx.services.redis, subject, maxFailedAttempts, lockoutDurationMinutes);
   return ok(undefined);
 }
 
@@ -138,8 +138,8 @@ export async function gateEnforceLockout(
   ctx: HandlerContext,
   userId: string,
 ): Promise<GateOutcome<undefined>> {
-  if (!ctx.redis) return ok(undefined);
-  const state = await getLockoutState(ctx.redis, userId);
+  if (!ctx.services.redis) return ok(undefined);
+  const state = await getLockoutState(ctx.services.redis, userId);
   if (state?.lockedUntil !== null && state?.lockedUntil !== undefined) {
     const now = Date.now();
     if (state.lockedUntil > now) {
@@ -160,15 +160,20 @@ export async function gateVerifyPassword(
 ): Promise<GateOutcome<undefined>> {
   const passwordOk = await verifyPassword(found.passwordHash, password);
   if (!passwordOk) {
-    if (ctx.redis) {
-      await recordFailedAttempt(ctx.redis, found.id, maxFailedAttempts, lockoutDurationMinutes);
+    if (ctx.services.redis) {
+      await recordFailedAttempt(
+        ctx.services.redis,
+        found.id,
+        maxFailedAttempts,
+        lockoutDurationMinutes,
+      );
     }
     return reject(invalidCredentials());
   }
   // Clear before MFA — MFA has its own attempt-cap; don't password-lock
   // users who occasionally mistype across otherwise-successful logins.
-  if (ctx.redis) {
-    await clearLockoutState(ctx.redis, found.id);
+  if (ctx.services.redis) {
+    await clearLockoutState(ctx.services.redis, found.id);
   }
   return ok(undefined);
 }
@@ -216,7 +221,7 @@ export async function gateResolveMembership(
   const globalRoles = parseRoles(found.roles ?? null);
 
   for (const candidate of candidates) {
-    const active = await ctx.resolveActiveMembership(found.id, candidate.tenantId);
+    const active = await ctx.auth.resolveActiveMembership(found.id, candidate.tenantId);
     if (active.kind === "rejected") {
       // A blocked principal is blocked for every tenant, so stop here;
       // not_a_member/tenant_teardown are per-tenant — try the next candidate.
@@ -275,7 +280,7 @@ export async function gateBuildSession(
     ...(timezone !== null && timezone !== undefined && { timezone }),
     ...(locale !== null && locale !== undefined && { locale }),
   };
-  const claims = await ctx.resolveAuthClaims(baseSession);
+  const claims = await ctx.auth.resolveClaims(baseSession);
   const session: SessionUser =
     Object.keys(claims).length > 0 ? { ...baseSession, claims } : baseSession;
   return { kind: "auth-session", session };
@@ -284,7 +289,7 @@ export async function gateBuildSession(
 // Login — unauthenticated entry point. The route is wired public (no JWT
 // middleware), dispatching with the framework's anonymous identity for the
 // handler's access check. Everything inside the handler goes through
-// ctx.queryAs(system, ...) so the user feature stays the single owner of its
+// ctx.dispatch.queryAs(system, ...) so the user feature stays the single owner of its
 // table.
 export function createLoginHandler(opts: LoginHandlerOptions = {}) {
   const strictVerification = opts.strictEmailVerification === true;
@@ -305,8 +310,8 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
       grants: ["systemIdentity", "unsafeRaw"],
       reason:
         "Unauthenticated login has no caller identity yet — it looks up the user row by " +
-        "email via ctx.queryAs(SYSTEM, ...) and resolves tenant membership via " +
-        "ctx.resolveActiveMembership before a session exists. It also reads the MFA " +
+        "email via ctx.dispatch.queryAs(SYSTEM, ...) and resolves tenant membership via " +
+        "ctx.auth.resolveActiveMembership before a session exists. It also reads the MFA " +
         "enrollment of the tenant named in the signed login/setup token, not the guest " +
         "dispatch tenant, via the mfaStatusChecker callback.",
     },
@@ -318,7 +323,9 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
       const systemUser = createSystemUser(SYSTEM_USER_ID);
 
       const foundRow = parseAuthUserRow(
-        await ctx.queryAs(systemUser, UserQueries.findForAuth, { email: event.payload.email }),
+        await ctx.dispatch.queryAs(systemUser, UserQueries.findForAuth, {
+          email: event.payload.email,
+        }),
       );
       if (!foundRow?.passwordHash || foundRow.isDeleted) {
         const unknown = await gateCountUnknownUser(
@@ -352,7 +359,7 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
       if (!statusGate.ok) return statusGate.result;
 
       // Still needed for candidate ORDER (preferred tenant first) in gateResolveMembership.
-      const memberships = (await ctx.queryAs(systemUser, TENANT_MEMBERSHIPS_QUERY, {
+      const memberships = (await ctx.dispatch.queryAs(systemUser, TENANT_MEMBERSHIPS_QUERY, {
         userId: found.id,
       })) as Array<Membership>; // @cast-boundary db-runner
 

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

@@ -31,6 +31,7 @@ export function createRequestAccountUnlockHandler(opts: RequestAccountUnlockOpti
       // empty) lockout state — harmless no-op if they weren't locked.
       extraSilentSkip: () => false,
       notificationType: AuthMailNotificationTypes.accountUnlock,
+      forwardsReturnTo: false,
     },
     opts,
   );

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

@@ -28,6 +28,7 @@ export function createRequestEmailVerificationHandler(opts: RequestEmailVerifica
       // caller sees the same 200 regardless of whether a token was minted.
       extraSilentSkip: (user) => user.emailVerified === true,
       notificationType: AuthMailNotificationTypes.emailVerification,
+      forwardsReturnTo: false,
     },
     opts,
   );

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

@@ -30,6 +30,7 @@ export function createRequestPasswordResetHandler(opts: RequestPasswordResetOpti
       // state. The sessions feature handles the post-change revocation.
       extraSilentSkip: () => false,
       notificationType: AuthMailNotificationTypes.passwordReset,
+      forwardsReturnTo: true,
     },
     opts,
   );

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

@@ -31,7 +31,7 @@ export function createResetPasswordHandler(opts: ResetPasswordOptions) {
       grants: ["systemIdentity"],
       reason:
         "Anonymous token holder has no session — runConfirmTokenFlow loads and updates the " +
-        "target user via ctx.writeAs(SYSTEM, user:update) to set the new password hash.",
+        "target user via ctx.dispatch.writeAs(SYSTEM, user:update) to set the new password hash.",
     },
     agent: { expose: false },
     handler: async (event, ctx) => {
@@ -51,7 +51,8 @@ export function createResetPasswordHandler(opts: ResetPasswordOptions) {
 
       return runConfirmTokenFlow(ctx, verify.userId, verify.expiresAtMs, {
         purpose: "reset",
-        redisRequiredMessage: "password-reset requires ctx.redis to enforce token single-use",
+        redisRequiredMessage:
+          "password-reset requires ctx.services.redis to enforce token single-use",
         invalidToken: invalidResetToken,
         buildChanges: async () => ({
           passwordHash: await hashPassword(event.payload.newPassword),

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

@@ -119,16 +119,16 @@ async function claimBoundHandover(
 ): Promise<ClaimedHandover | undefined> {
   const provider = findSignupHandoverProvider(ctx.registry);
   if (!provider) {
-    ctx.log?.warn(
+    ctx.obs.log?.warn(
       "signup-confirm: handover binding present but no signupHandover provider mounted",
     );
     return undefined;
   }
   const claim = provider.mintClaim(binding);
-  const claimResult = await ctx.writeAs(session, claim.qualifiedName, claim.payload);
+  const claimResult = await ctx.dispatch.writeAs(session, claim.qualifiedName, claim.payload);
   if (claimResult.isSuccess) return { entityType: binding.entityType, id: binding.rowId };
   if (!isBenignClaimRejection(claimResult.error)) throw reraiseAsKumikoError(claimResult.error);
-  ctx.log?.warn("signup-confirm: handover grant did not redeem", {
+  ctx.obs.log?.warn("signup-confirm: handover grant did not redeem", {
     entityType: binding.entityType,
   });
   return undefined;
@@ -146,22 +146,22 @@ export function createSignupConfirmHandler(opts: SignupConfirmOptions = {}) {
       reason: SIGNUP_CONFIRM_PROVISION_REASON,
     },
     handler: async (event, ctx) => {
-      if (!ctx.redis) {
+      if (!ctx.services.redis) {
         return writeFailure(
           new InternalError({
-            message: "signup-confirm requires ctx.redis for token consumption",
+            message: "signup-confirm requires ctx.services.redis for token consumption",
           }),
         );
       }
 
       // Token lookup: nonexistent, expired, and already-consumed tokens all
       // collapse to invalid_signup_token to prevent enumeration.
-      const email = await getEmailForSignupToken(ctx.redis, event.payload.token);
+      const email = await getEmailForSignupToken(ctx.services.redis, event.payload.token);
       if (!email) return invalidSignupToken();
 
       // Single-use burn: of two parallel confirmations from different tabs,
       // one succeeds and the other receives invalid_signup_token.
-      const burn = await burnSignupToken(ctx.redis, event.payload.token);
+      const burn = await burnSignupToken(ctx.services.redis, event.payload.token);
       if (burn === "already-used") return invalidSignupToken();
 
       let committed = false;
@@ -229,7 +229,7 @@ export function createSignupConfirmHandler(opts: SignupConfirmOptions = {}) {
         // Claim BEFORE spending the signup token or the binding below and
         // before `committed` flips: if the claim throws, the `finally` still
         // unburns and the activation link stays retryable.
-        const handoverBinding = await getSignupHandover(ctx.redis, event.payload.token);
+        const handoverBinding = await getSignupHandover(ctx.services.redis, event.payload.token);
         const handover = handoverBinding
           ? await claimBoundHandover(ctx, session, handoverBinding)
           : undefined;
@@ -245,8 +245,8 @@ export function createSignupConfirmHandler(opts: SignupConfirmOptions = {}) {
 
         // Drop both token lookup keys; the burn key stays for its remaining
         // TTL as replay protection.
-        await deleteSignupToken(ctx.redis, { email, token: event.payload.token });
-        if (handoverBinding) await deleteSignupHandover(ctx.redis, event.payload.token);
+        await deleteSignupToken(ctx.services.redis, { email, token: event.payload.token });
+        if (handoverBinding) await deleteSignupHandover(ctx.services.redis, event.payload.token);
 
         if (mfaGate !== undefined) {
           committed = true;
@@ -275,10 +275,10 @@ export function createSignupConfirmHandler(opts: SignupConfirmOptions = {}) {
           },
         };
       } finally {
-        if (!committed && ctx.redis) {
+        if (!committed && ctx.services.redis) {
           // Release the burn so a retry after a DB hiccup is not blocked.
           // Keep the token lookup keys so the user can click the email link again.
-          await unburnSignupToken(ctx.redis, event.payload.token);
+          await unburnSignupToken(ctx.services.redis, event.payload.token);
         }
       }
     },

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

@@ -31,6 +31,7 @@ import { resolveHandlerMailLocale } from "../magic-link-mail.ts";
 import { AUTH_SELF_REGISTRATION_FEATURE } from "../self-registration-toggle.ts";
 import { issueSignupActivation } from "../signup-activation.ts";
 import { storeSignupHandover, takeOverSignupHandoverForResend } from "../signup-token-store.ts";
+import { MAX_RETURN_PATH_LENGTH } from "../web/return-path.ts";
 
 const SignupRequestSchema = z.object({
   email: z.email(),
@@ -43,6 +44,8 @@ const SignupRequestSchema = z.object({
       token: z.string().min(1),
     })
     .optional(),
+  // A bad returnTo must not void the signup; the mail builder drops unsafe values.
+  returnTo: z.string().max(MAX_RETURN_PATH_LENGTH).optional().catch(undefined),
 });
 
 const HANDOVER_GRANT_VERIFY_REASON =
@@ -102,13 +105,13 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
         // No email address here — this fires on every no-op request, PII
         // must not accumulate in logs just for the "was this toggled off"
         // signal a support ticket needs.
-        ctx.log?.info("signup-request skipped: self-registration disabled");
+        ctx.obs.log?.info("signup-request skipped: self-registration disabled");
         return { isSuccess: true, data: { kind: "no-op" } };
       }
-      if (!ctx.redis) {
+      if (!ctx.services.redis) {
         return writeFailure(
           new InternalError({
-            message: "signup-request requires ctx.redis for the activation-token store",
+            message: "signup-request requires ctx.services.redis for the activation-token store",
           }),
         );
       }
@@ -122,10 +125,10 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
       // resend without a fresh `handover` in the payload (the common case:
       // the visitor just retyped their email) must still carry the earlier
       // verified grant over to the new token instead of silently dropping it.
-      const priorBinding = await takeOverSignupHandoverForResend(ctx.redis, email);
+      const priorBinding = await takeOverSignupHandoverForResend(ctx.services.redis, email);
 
       const locale = resolveHandlerMailLocale(ctx, opts.locale);
-      const redis = ctx.redis;
+      const redis = ctx.services.redis;
 
       const issued = await issueSignupActivation({
         redis,
@@ -133,6 +136,7 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
         email,
         appUrl: opts.appUrl,
         timeZone: ctx.tz.user,
+        ...(event.payload.returnTo !== undefined && { returnTo: event.payload.returnTo }),
         ...(opts.tokenTtlMinutes !== undefined && { tokenTtlMinutes: opts.tokenTtlMinutes }),
         ...(opts.appName !== undefined && { appName: opts.appName }),
         ...(locale !== undefined && { locale }),
@@ -149,7 +153,7 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
             const { entityType, token: grantToken } = event.payload.handover;
             const provider = findSignupHandoverProvider(ctx.registry);
             if (!provider) {
-              ctx.log?.warn(
+              ctx.obs.log?.warn(
                 "signup-request: handover payload present but no signupHandover provider mounted",
               );
             } else {
@@ -163,10 +167,14 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
                 if (verified) {
                   binding = verified;
                 } else {
-                  ctx.log?.warn("signup-request: handover grant did not verify", { entityType });
+                  ctx.obs.log?.warn("signup-request: handover grant did not verify", {
+                    entityType,
+                  });
                 }
               } catch {
-                ctx.log?.warn("signup-request: handover grant verification threw", { entityType });
+                ctx.obs.log?.warn("signup-request: handover grant verification threw", {
+                  entityType,
+                });
               }
             }
           }

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

@@ -43,10 +43,12 @@ export function createSwitchTenantMfaGateHandler(
       "Runs the MFA gate of the login for a tenant switch and answers with an MFA challenge, a setup requirement, or clearance.",
     handler: async (event, ctx) => {
       const { userId, tenantId } = event.payload;
-      const active = await ctx.resolveActiveMembership(userId, tenantId);
+      const active = await ctx.auth.resolveActiveMembership(userId, tenantId);
       if (active.kind === "rejected") return noMembership();
       const userRow = parseAuthUserRow(
-        await ctx.queryAs(createSystemUser(tenantId), UserQueries.findForAuth, { id: userId }),
+        await ctx.dispatch.queryAs(createSystemUser(tenantId), UserQueries.findForAuth, {
+          id: userId,
+        }),
       );
       const roles = buildSessionRoles(parseRoles(userRow?.roles ?? null), active.membership.roles);
       const mfaGate = await gateEnforceMfa(ctx, opts, userId, tenantId, roles);

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

@@ -22,9 +22,12 @@ import { type AuthUserRow, parseAuthUserRow } from "../auth-user-row.ts";
 import { AUTH_EMAIL_PAYLOAD_RATE_LIMITS } from "../email-rate-limits.ts";
 import type { AuthMailLocale } from "../email-templates.ts";
 import { dispatchMagicLinkMail, resolveHandlerMailLocale } from "../magic-link-mail.ts";
+import { MAX_RETURN_PATH_LENGTH } from "../web/return-path.ts";
 
 const RequestTokenSchema = z.object({
   email: z.email(),
+  // A bad returnTo must not void the request; the mail builder drops unsafe values.
+  returnTo: z.string().max(MAX_RETURN_PATH_LENGTH).optional().catch(undefined),
 });
 
 // What the route layer reads off `result.data` after dispatching. Identical
@@ -67,6 +70,9 @@ export type TokenRequestSpec<TName extends string, TSuccessKind extends string>
   // Trigger-less r.notification dispatched via ctx.notify on success; the
   // recipient is an anonymous email, so route:{email} delivers directly.
   readonly notificationType: string;
+  // Only flows whose landing page can continue to a page (password reset) put the request's
+  // returnTo into the mail link; verification and unlock ignore it.
+  readonly forwardsReturnTo: boolean;
 };
 
 export type TokenRequestOptions = {
@@ -105,7 +111,7 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
       grants: ["systemIdentity"],
       reason:
         "Anonymous requester has no session — looks up the target user by email via " +
-        "ctx.queryAs(SYSTEM, user:findForAuth) to mint the out-of-band token.",
+        "ctx.dispatch.queryAs(SYSTEM, user:findForAuth) to mint the out-of-band token.",
     },
     description: spec.description,
     handler: async (event, ctx) => {
@@ -122,7 +128,7 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
       const systemUser = createSystemUser(event.user.tenantId);
 
       const user = parseAuthUserRow(
-        await ctx.queryAs(systemUser, UserQueries.findForAuth, {
+        await ctx.dispatch.queryAs(systemUser, UserQueries.findForAuth, {
           email: event.payload.email,
         }),
       );
@@ -159,6 +165,8 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
           timeZone: recipientTimeZone(user, ctx.tz.user),
           ...(opts.appName !== undefined && { appName: opts.appName }),
           locale,
+          ...(spec.forwardsReturnTo &&
+            event.payload.returnTo !== undefined && { returnTo: event.payload.returnTo }),
         },
       );
 

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

@@ -32,7 +32,7 @@ export function createVerifyEmailHandler(opts: VerifyEmailOptions) {
       grants: ["systemIdentity"],
       reason:
         "Anonymous token holder has no session — runConfirmTokenFlow loads and updates the " +
-        "target user via ctx.writeAs(SYSTEM, user:update) to set emailVerified.",
+        "target user via ctx.dispatch.writeAs(SYSTEM, user:update) to set emailVerified.",
     },
     agent: { expose: false },
     handler: async (event, ctx) => {
@@ -49,7 +49,8 @@ export function createVerifyEmailHandler(opts: VerifyEmailOptions) {
 
       return runConfirmTokenFlow<VerifyEmailData>(ctx, verify.userId, verify.expiresAtMs, {
         purpose: "verify",
-        redisRequiredMessage: "email-verification requires ctx.redis to enforce token single-use",
+        redisRequiredMessage:
+          "email-verification requires ctx.services.redis to enforce token single-use",
         invalidToken: invalidVerificationToken,
         buildChanges: async () => ({ emailVerified: true }),
         successData: { kind: "verified" },

package/packages/bundled-features/src/auth-email-password/magic-link-mail.ts

@@ -12,6 +12,7 @@ import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { mailT, resolveMailLocale } from "@cosmicdrift/kumiko-framework/i18n";
 import { type AuthMailLocale, tokenMailExpiry } from "./email-templates.ts";
 import { authMailTemplateLocale } from "./mail-notifications.ts";
+import { isSafeReturnPath, RETURN_TO_QUERY_PARAM } from "./web/return-path.ts";
 
 // Per-flow constants: which notification type to dispatch. fallbackAppName
 // replaces the translated default when the flow has no app name of its own.
@@ -38,15 +39,23 @@ export type MagicLinkMailParams = {
   readonly timeZone?: string;
   // Invite mails name the role the recipient is invited as.
   readonly role?: string;
+  /** Page the landing page should lead to afterwards; an unsafe value is left out of the link. */
+  readonly returnTo?: string;
 };
 
 function resolveAppUrl(appUrl: string | ((locale: string) => string), locale: string): string {
   return typeof appUrl === "function" ? appUrl(locale) : appUrl;
 }
 
-function appendToken(appUrl: string, token: string): string {
+function appendTokenAndReturnTo(
+  appUrl: string,
+  token: string,
+  returnTo: string | undefined,
+): string {
+  const query = new URLSearchParams({ token });
+  if (isSafeReturnPath(returnTo)) query.set(RETURN_TO_QUERY_PARAM, returnTo);
   const sep = appUrl.includes("?") ? "&" : "?";
-  return `${appUrl}${sep}token=${encodeURIComponent(token)}`;
+  return `${appUrl}${sep}${query.toString()}`;
 }
 
 // X-Locale on the request wins over the handler's static opts.locale, then
@@ -93,7 +102,11 @@ export async function dispatchMagicLinkMail(
     data: {
       appName:
         params.appName ?? spec.fallbackAppName ?? mailT(templateLocale, "auth.mail.appNameDefault"),
-      actionUrl: appendToken(resolveAppUrl(params.appUrl, urlLocale), params.token),
+      actionUrl: appendTokenAndReturnTo(
+        resolveAppUrl(params.appUrl, urlLocale),
+        params.token,
+        params.returnTo,
+      ),
       validFor,
       validUntil,
       ...(params.role !== undefined && { role: params.role }),

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

@@ -20,10 +20,14 @@ import {
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
-import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createSystemUser,
+  type SessionUser,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { ConflictError } from "@cosmicdrift/kumiko-framework/errors";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
-import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 import { hashPassword } from "../shared/index.ts";
 // kumiko-lint-ignore cross-feature-import auth-tests need user+tenant seed-helpers
 import { type SeedTenantHooks, seedTenant, seedTenantMembership } from "../tenant/seeding.ts";
@@ -224,10 +228,10 @@ export async function seedAdmin(
   db: DbConnection,
   options: SeedAdminOptions,
 ): Promise<{ id: string }> {
-  const by = options.by ?? TestUsers.systemAdmin;
+  const byOption = options.by === undefined ? {} : { by: options.by };
 
   for (const m of options.memberships) {
-    await seedTenant(db, { id: m.tenantId, key: m.tenantKey, name: m.tenantName, by });
+    await seedTenant(db, { id: m.tenantId, key: m.tenantKey, name: m.tenantName, ...byOption });
   }
 
   const { id: userId } = await seedUserWithPassword(db, {
@@ -236,7 +240,7 @@ export async function seedAdmin(
     displayName: options.displayName,
     ...(options.globalRoles !== undefined && { roles: options.globalRoles }),
     ...(options.emailVerified !== undefined && { emailVerified: options.emailVerified }),
-    by,
+    ...byOption,
   });
 
   for (const m of options.memberships) {
@@ -244,7 +248,7 @@ export async function seedAdmin(
       userId,
       tenantId: m.tenantId,
       roles: m.roles,
-      by,
+      ...byOption,
     });
   }
 
@@ -372,7 +376,8 @@ export async function seedAdminGuarded(
   const existingId = await findExistingUserIdForEmail(db, kms, options.email);
   if (existingId === undefined) return seedAdmin(db, options);
 
-  const by = options.by ?? TestUsers.systemAdmin;
+  const byOption = options.by === undefined ? {} : { by: options.by };
+  const by = options.by ?? createSystemUser(SYSTEM_TENANT_ID);
   const existingRow = await fetchOne(db, userTable, { id: existingId });
   if (existingRow) {
     // Re-write the email so email_bidx is recomputed; without it the account
@@ -384,12 +389,12 @@ export async function seedAdminGuarded(
     }
   }
   for (const m of options.memberships) {
-    await seedTenant(db, { id: m.tenantId, key: m.tenantKey, name: m.tenantName, by });
+    await seedTenant(db, { id: m.tenantId, key: m.tenantKey, name: m.tenantName, ...byOption });
     await seedTenantMembership(db, {
       userId: existingId,
       tenantId: m.tenantId,
       roles: m.roles,
-      by,
+      ...byOption,
     });
   }
   return { id: existingId };

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

@@ -28,6 +28,7 @@ export type IssueSignupActivationArgs = {
   readonly locale?: string;
   readonly timeZone?: string;
   readonly tokenTtlMinutes?: number;
+  readonly returnTo?: string;
   /** Runs after the token is stored and before the mail goes out. */
   readonly onTokenStored?: (stored: {
     readonly token: string;
@@ -75,6 +76,7 @@ export async function issueSignupActivation(
       ...(args.timeZone !== undefined && { timeZone: args.timeZone }),
       ...(args.appName !== undefined && { appName: args.appName }),
       ...(args.locale !== undefined && { locale: args.locale }),
+      ...(args.returnTo !== undefined && { returnTo: args.returnTo }),
     },
   );