@cosmicdrift/kumiko-bundled-features 0.388.0 → 0.390.0

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

@@ -34,12 +34,12 @@ function unknownEmailLockoutSubject(ctx, email) {
 }
 export async function gateCountUnknownUser(ctx, email, maxFailedAttempts, lockoutDurationMinutes) {
     const subject = unknownEmailLockoutSubject(ctx, email);
-    if (!ctx.redis || subject === 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);
 }
 /**
@@ -47,9 +47,9 @@ export async function gateCountUnknownUser(ctx, email, maxFailedAttempts, lockou
  * Fail-open without Redis (IP rate-limit still covers partially).
  */
 export async function gateEnforceLockout(ctx, userId) {
-    if (!ctx.redis)
+    if (!ctx.services.redis)
         return ok(undefined);
-    const state = await getLockoutState(ctx.redis, userId);
+    const state = await getLockoutState(ctx.services.redis, userId);
     if (state?.lockedUntil !== null && state?.lockedUntil !== undefined) {
         const now = Date.now();
         if (state.lockedUntil > now) {
@@ -63,15 +63,15 @@ export async function gateEnforceLockout(ctx, userId) {
 export async function gateVerifyPassword(ctx, found, password, maxFailedAttempts, lockoutDurationMinutes) {
     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);
 }
@@ -105,7 +105,7 @@ export async function gateResolveMembership(ctx, found, memberships) {
         : memberships;
     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.
@@ -149,14 +149,14 @@ export async function gateBuildSession(ctx, userId, tenantId, mergedRoles, timez
         ...(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 = Object.keys(claims).length > 0 ? { ...baseSession, claims } : baseSession;
     return { kind: "auth-session", session };
 }
 // 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 = {}) {
     const strictVerification = opts.strictEmailVerification === true;
@@ -173,8 +173,8 @@ export function createLoginHandler(opts = {}) {
         escapeHatch: {
             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.",
         },
@@ -183,7 +183,9 @@ export function createLoginHandler(opts = {}) {
         description: "Signs a user in with email and password, running the lockout, email-verification, account-status, tenant-membership and MFA gates, and answering with a session or with an MFA challenge or setup requirement.",
         handler: async (event, ctx) => {
             const systemUser = createSystemUser(SYSTEM_USER_ID);
-            const foundRow = parseAuthUserRow(await ctx.queryAs(systemUser, UserQueries.findForAuth, { email: event.payload.email }));
+            const foundRow = parseAuthUserRow(await ctx.dispatch.queryAs(systemUser, UserQueries.findForAuth, {
+                email: event.payload.email,
+            }));
             if (!foundRow?.passwordHash || foundRow.isDeleted) {
                 const unknown = await gateCountUnknownUser(ctx, event.payload.email, maxFailedAttempts, lockoutDurationMinutes);
                 if (!unknown.ok)
@@ -206,7 +208,7 @@ export function createLoginHandler(opts = {}) {
             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,
             })); // @cast-boundary db-runner
             const membershipGate = await gateResolveMembership(ctx, found, memberships);

package/dist/auth-email-password/handlers/request-account-unlock.write.d.ts

@@ -3,4 +3,5 @@ export type RequestAccountUnlockOptions = TokenRequestOptions;
 export type RequestUnlockData = TokenRequestData<"unlock-requested">;
 export declare function createRequestAccountUnlockHandler(opts: RequestAccountUnlockOptions): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"request-account-unlock", import("zod").ZodObject<{
     email: import("zod").ZodEmail;
+    returnTo: import("zod").ZodCatch<import("zod").ZodOptional<import("zod").ZodString>>;
 }, import("zod/v4/core").$strip>, TokenRequestData<"unlock-requested">, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

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

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

package/dist/auth-email-password/handlers/request-email-verification.write.d.ts

@@ -3,4 +3,5 @@ export type RequestEmailVerificationOptions = TokenRequestOptions;
 export type RequestVerificationData = TokenRequestData<"verification-requested">;
 export declare function createRequestEmailVerificationHandler(opts: RequestEmailVerificationOptions): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"request-email-verification", import("zod").ZodObject<{
     email: import("zod").ZodEmail;
+    returnTo: import("zod").ZodCatch<import("zod").ZodOptional<import("zod").ZodString>>;
 }, import("zod/v4/core").$strip>, TokenRequestData<"verification-requested">, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

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

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

package/dist/auth-email-password/handlers/request-password-reset.write.d.ts

@@ -3,4 +3,5 @@ export type RequestPasswordResetOptions = TokenRequestOptions;
 export type RequestResetData = TokenRequestData<"reset-requested">;
 export declare function createRequestPasswordResetHandler(opts: RequestPasswordResetOptions): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"request-password-reset", import("zod").ZodObject<{
     email: import("zod").ZodEmail;
+    returnTo: import("zod").ZodCatch<import("zod").ZodOptional<import("zod").ZodString>>;
 }, import("zod/v4/core").$strip>, TokenRequestData<"reset-requested">, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

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

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

package/dist/auth-email-password/handlers/reset-password.write.js

@@ -25,7 +25,7 @@ export function createResetPasswordHandler(opts) {
         escapeHatch: {
             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) => {
@@ -42,7 +42,7 @@ export function createResetPasswordHandler(opts) {
                 return invalidResetToken();
             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/dist/auth-email-password/handlers/signup-confirm.write.js

@@ -55,16 +55,16 @@ function isBenignClaimRejection(error) {
 async function claimBoundHandover(ctx, session, binding) {
     const provider = findSignupHandoverProvider(ctx.registry);
     if (!provider) {
-        ctx.log?.warn("signup-confirm: handover binding present but no signupHandover provider mounted");
+        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;
@@ -81,19 +81,19 @@ export function createSignupConfirmHandler(opts = {}) {
             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;
@@ -154,7 +154,7 @@ export function createSignupConfirmHandler(opts = {}) {
                 // 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;
@@ -162,9 +162,9 @@ export function createSignupConfirmHandler(opts = {}) {
                 const mfaGate = await gateEnforceMfa(ctx, { mfaStatusChecker: opts.mfaStatusChecker }, provisioned.userId, provisioned.tenantId, session.roles);
                 // 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 });
+                await deleteSignupToken(ctx.services.redis, { email, token: event.payload.token });
                 if (handoverBinding)
-                    await deleteSignupHandover(ctx.redis, event.payload.token);
+                    await deleteSignupHandover(ctx.services.redis, event.payload.token);
                 if (mfaGate !== undefined) {
                     committed = true;
                     return {
@@ -192,10 +192,10 @@ export function createSignupConfirmHandler(opts = {}) {
                 };
             }
             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/dist/auth-email-password/handlers/signup-request.write.d.ts

@@ -29,4 +29,5 @@ export declare function createSignupRequestHandler(opts: SignupRequestOptions):
         entityType: z.ZodString;
         token: z.ZodString;
     }, z.core.$strip>>;
+    returnTo: z.ZodCatch<z.ZodOptional<z.ZodString>>;
 }, z.core.$strip>, SignupRequestData, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

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

@@ -29,6 +29,7 @@ import { resolveHandlerMailLocale } from "../magic-link-mail.js";
 import { AUTH_SELF_REGISTRATION_FEATURE } from "../self-registration-toggle.js";
 import { issueSignupActivation } from "../signup-activation.js";
 import { storeSignupHandover, takeOverSignupHandoverForResend } from "../signup-token-store.js";
+import { MAX_RETURN_PATH_LENGTH } from "../web/return-path.js";
 const SignupRequestSchema = z.object({
     email: z.email(),
     // Cross-device try-first handover: see shared/signup-handover.ts for why the
@@ -40,6 +41,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 = "verifies a tenant-handover grant against its root row in the source tenant (read-only anchor lookup) before binding it to the signup token";
 export function createSignupRequestHandler(opts) {
@@ -70,12 +73,12 @@ export function createSignupRequestHandler(opts) {
                 // 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",
                 }));
             }
             // Email normalization lives in the store (signup-token-store). The
@@ -86,15 +89,16 @@ export function createSignupRequestHandler(opts) {
             // 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,
                 notify: ctx.notify,
                 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 }),
@@ -111,7 +115,7 @@ export function createSignupRequestHandler(opts) {
                         const { entityType, token: grantToken } = event.payload.handover;
                         const provider = findSignupHandoverProvider(ctx.registry);
                         if (!provider) {
-                            ctx.log?.warn("signup-request: handover payload present but no signupHandover provider mounted");
+                            ctx.obs.log?.warn("signup-request: handover payload present but no signupHandover provider mounted");
                         }
                         else {
                             try {
@@ -125,11 +129,15 @@ export function createSignupRequestHandler(opts) {
                                     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/dist/auth-email-password/handlers/switch-tenant-mfa-gate.write.js

@@ -24,10 +24,12 @@ export function createSwitchTenantMfaGateHandler(opts) {
         description: "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 }));
+            const userRow = parseAuthUserRow(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);
             return { isSuccess: true, data: mfaGate ?? { kind: "mfa-gate-clear", roles } };

package/dist/auth-email-password/handlers/token-request-handler.d.ts

@@ -25,6 +25,7 @@ export type TokenRequestSpec<TName extends string, TSuccessKind extends string>
     readonly notConfiguredI18nKey: string;
     readonly extraSilentSkip: (user: AuthUserRow) => boolean;
     readonly notificationType: string;
+    readonly forwardsReturnTo: boolean;
 };
 export type TokenRequestOptions = {
     readonly hmacSecret: string;
@@ -41,4 +42,5 @@ export type TokenRequestOptions = {
 };
 export declare function createTokenRequestHandler<TName extends string, TSuccessKind extends string>(spec: TokenRequestSpec<TName, TSuccessKind>, opts: TokenRequestOptions): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<TName, z.ZodObject<{
     email: z.ZodEmail;
+    returnTo: z.ZodCatch<z.ZodOptional<z.ZodString>>;
 }, z.core.$strip>, TokenRequestData<TSuccessKind>, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/auth-email-password/handlers/token-request-handler.js

@@ -19,8 +19,11 @@ import { UserQueries } from "../../user/index.js";
 import { parseAuthUserRow } from "../auth-user-row.js";
 import { AUTH_EMAIL_PAYLOAD_RATE_LIMITS } from "../email-rate-limits.js";
 import { dispatchMagicLinkMail, resolveHandlerMailLocale } from "../magic-link-mail.js";
+import { MAX_RETURN_PATH_LENGTH } from "../web/return-path.js";
 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),
 });
 // The requester is anonymous, so ctx.tz.user is only the tenant default; the recipient's
 // own profile zone is the one the expiry should be read in.
@@ -38,7 +41,7 @@ export function createTokenRequestHandler(spec, opts) {
         escapeHatch: {
             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) => {
@@ -50,7 +53,7 @@ export function createTokenRequestHandler(spec, opts) {
                 }));
             }
             const systemUser = createSystemUser(event.user.tenantId);
-            const user = parseAuthUserRow(await ctx.queryAs(systemUser, UserQueries.findForAuth, {
+            const user = parseAuthUserRow(await ctx.dispatch.queryAs(systemUser, UserQueries.findForAuth, {
                 email: event.payload.email,
             }));
             // Silent-success branches all return the SAME shape with kind="no-op".
@@ -79,6 +82,8 @@ export function createTokenRequestHandler(spec, opts) {
                 timeZone: recipientTimeZone(user, ctx.tz.user),
                 ...(opts.appName !== undefined && { appName: opts.appName }),
                 locale,
+                ...(spec.forwardsReturnTo &&
+                    event.payload.returnTo !== undefined && { returnTo: event.payload.returnTo }),
             });
             const data = {
                 kind: spec.successKind,

package/dist/auth-email-password/handlers/verify-email.write.js

@@ -23,7 +23,7 @@ export function createVerifyEmailHandler(opts) {
         escapeHatch: {
             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) => {
@@ -37,7 +37,7 @@ export function createVerifyEmailHandler(opts) {
                 return invalidVerificationToken();
             return runConfirmTokenFlow(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/dist/auth-email-password/magic-link-mail.d.ts

@@ -15,6 +15,8 @@ export type MagicLinkMailParams = {
     readonly issuedAt?: string;
     readonly timeZone?: string;
     readonly role?: string;
+    /** Page the landing page should lead to afterwards; an unsafe value is left out of the link. */
+    readonly returnTo?: string;
 };
 export declare function resolveHandlerMailLocale(ctx: {
     readonly locale?: string;

package/dist/auth-email-password/magic-link-mail.js

@@ -10,12 +10,16 @@ import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { mailT, resolveMailLocale } from "@cosmicdrift/kumiko-framework/i18n";
 import { tokenMailExpiry } from "./email-templates.js";
 import { authMailTemplateLocale } from "./mail-notifications.js";
+import { isSafeReturnPath, RETURN_TO_QUERY_PARAM } from "./web/return-path.js";
 function resolveAppUrl(appUrl, locale) {
     return typeof appUrl === "function" ? appUrl(locale) : appUrl;
 }
-function appendToken(appUrl, token) {
+function appendTokenAndReturnTo(appUrl, token, returnTo) {
+    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
 // ctx.locale's resolved default (always set — boot default / "en"). Reading
@@ -49,7 +53,7 @@ export async function dispatchMagicLinkMail(notify, spec, params) {
         route: { email: params.email },
         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/dist/auth-email-password/seeding.d.ts

@@ -1,5 +1,5 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { type SessionUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { type SeedTenantHooks } from "../tenant/seeding.ts";
 export { seedTenant, seedTenantMembership } from "../tenant/seeding.ts";
 export { seedUser } from "../user/seeding.ts";

package/dist/auth-email-password/seeding.js

@@ -13,9 +13,9 @@
 // sub-paths themselves.
 import { configuredBlindIndexKey, configuredPiiSubjectKms, decryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
+import { createSystemUser, SYSTEM_TENANT_ID, } 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.js";
 // kumiko-lint-ignore cross-feature-import auth-tests need user+tenant seed-helpers
 import { seedTenant, seedTenantMembership } from "../tenant/seeding.js";
@@ -129,9 +129,9 @@ hooks) {
  * persistent-DB mode succeeds. Returns the userId.
  */
 export async function seedAdmin(db, options) {
-    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, {
         email: options.email,
@@ -139,14 +139,14 @@ export async function seedAdmin(db, options) {
         displayName: options.displayName,
         ...(options.globalRoles !== undefined && { roles: options.globalRoles }),
         ...(options.emailVerified !== undefined && { emailVerified: options.emailVerified }),
-        by,
+        ...byOption,
     });
     for (const m of options.memberships) {
         await seedTenantMembership(db, {
             userId,
             tenantId: m.tenantId,
             roles: m.roles,
-            by,
+            ...byOption,
         });
     }
     return { id: userId };
@@ -239,7 +239,8 @@ export async function seedAdminGuarded(db, options) {
     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
@@ -251,12 +252,12 @@ export async function seedAdminGuarded(db, options) {
         }
     }
     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/dist/auth-email-password/signup-activation.d.ts

@@ -10,6 +10,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;

package/dist/auth-email-password/signup-activation.js

@@ -35,6 +35,7 @@ export async function issueSignupActivation(args) {
         ...(args.timeZone !== undefined && { timeZone: args.timeZone }),
         ...(args.appName !== undefined && { appName: args.appName }),
         ...(args.locale !== undefined && { locale: args.locale }),
+        ...(args.returnTo !== undefined && { returnTo: args.returnTo }),
     });
     return { email, token, expiresAt };
 }

package/dist/auth-email-password/web/auth-client.d.ts

@@ -54,7 +54,7 @@ export type AuthTokenFailure = {
 };
 export type ResetPasswordFailure = AuthTokenFailure;
 export type VerifyEmailFailure = AuthTokenFailure;
-export declare function requestPasswordReset(email: string): Promise<{
+export declare function requestPasswordReset(email: string, returnTo?: string): Promise<{
     ok: true;
 } | {
     ok: false;
@@ -93,7 +93,7 @@ export declare function confirmAccountUnlock(token: string): Promise<{
 export declare function requestSignup(email: string, handover?: {
     readonly entityType: string;
     readonly token: string;
-}): Promise<{
+}, returnTo?: string): Promise<{
     ok: true;
 } | {
     ok: false;

package/dist/auth-email-password/web/auth-client.js

@@ -115,12 +115,12 @@ async function parseTokenFailure(res) {
 // email doesn't exist, the caller sees `{ ok: true }` — no account
 // enumeration. Server only triggers the mail internally when a user is
 // found. 429 → typed rate-limit failure. 5xx → unknown-error.
-export async function requestPasswordReset(email) {
+export async function requestPasswordReset(email, returnTo) {
     const res = await fetch("/api/auth/request-password-reset", {
         method: "POST",
         credentials: "same-origin",
         headers: { "Content-Type": "application/json", ...csrfHeader() },
-        body: JSON.stringify({ email }),
+        body: JSON.stringify({ email, ...(returnTo !== undefined && { returnTo }) }),
     });
     if (res.ok)
         return { ok: true };
@@ -208,12 +208,16 @@ export async function requestSignup(email,
 // grant so the server can verify + rebind it to the signup token. The grant never
 // travels any further than this request — never in the URL, the mail,
 // or the confirm response.
-handover) {
+handover, returnTo) {
     const res = await fetch("/api/auth/signup-request", {
         method: "POST",
         credentials: "same-origin",
         headers: { "Content-Type": "application/json", ...csrfHeader() },
-        body: JSON.stringify({ email, ...(handover !== undefined && { handover }) }),
+        body: JSON.stringify({
+            email,
+            ...(handover !== undefined && { handover }),
+            ...(returnTo !== undefined && { returnTo }),
+        }),
     });
     if (res.ok)
         return { ok: true };

package/dist/auth-email-password/web/auth-redirect.d.ts

@@ -1,6 +1,10 @@
+import { isSafeReturnPath } from "./return-path.ts";
 export declare const NEXT_QUERY_PARAM = "next";
-export declare function isSafeNextPath(candidate: unknown): candidate is string;
+export declare const isSafeNextPath: typeof isSafeReturnPath;
 export declare function readNextFromSearch(search: string): string | null;
+export declare function readReturnToFromWindow(): string | null;
+export declare function appendReturnTo(href: string, returnTo: string | null): string;
+export declare function readNextFromWindow(): string | null;
 export declare function assertNavigableUrl(url: string, optionName: string): void;
 export declare function buildLoginRedirectUrl(loginUrl: string, returnPath: string, currentOrigin: string): string;
 export declare function followNextAfterLogin(location?: Pick<Location, "search" | "pathname" | "replace">): boolean;