@cosmicdrift/kumiko-samples 0.387.0 → 0.389.0

package/package.json

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

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.387.0",
+  "version": "0.389.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -63,6 +63,7 @@
     "./billing-foundation": "./src/billing-foundation/index.ts",
     "./billing-foundation/web": "./src/billing-foundation/web/index.ts",
     "./subscription-stripe": "./src/subscription-stripe/index.ts",
+    "./subscription-dodo": "./src/subscription-dodo/index.ts",
     "./subscription-mollie": "./src/subscription-mollie/index.ts",
     "./foundation-shared": "./src/foundation-shared/index.ts",
     "./auth-foundation": "./src/auth-foundation/index.ts",
@@ -359,6 +360,10 @@
         "types": "./dist/subscription-stripe/index.d.ts",
         "default": "./dist/subscription-stripe/index.js"
       },
+      "./subscription-dodo": {
+        "types": "./dist/subscription-dodo/index.d.ts",
+        "default": "./dist/subscription-dodo/index.js"
+      },
       "./subscription-mollie": {
         "types": "./dist/subscription-mollie/index.d.ts",
         "default": "./dist/subscription-mollie/index.js"
@@ -728,6 +733,8 @@
     "@testing-library/user-event": "^14.6.1",
     "@cosmicdrift/kumiko-locale-de": "workspace:*",
     "@cosmicdrift/kumiko-locale-es": "workspace:*",
+    "@cosmicdrift/kumiko-locale-fr": "workspace:*",
+    "@cosmicdrift/kumiko-locale-it": "workspace:*",
     "@cosmicdrift/kumiko-renderer-mail-html": "workspace:*",
     "jsqr": "^1.4.0",
     "unpdf": "^1.8.1",

package/packages/bundled-features/src/agent-tools/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "Local agent tool errors carry a code",
+    "detail": "dispatchToolCall returns code invalid_tool_call for validation errors and unknown_tool for an unknown tool name, instead of a result without code. TOOL_CALL_ERROR_CODES names both."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "dispatchToolCall documents which failures carry a code",
+    "detail": "Only handler and dispatcher failures carry a code; local validation errors such as an unknown tool or bad arguments come back without one, and the JSDoc now says so."
+  },
   {
     "version": "0.366.0",
     "type": "improvement",

package/packages/bundled-features/src/agent-tools/index.ts

@@ -9,7 +9,7 @@ export { buildAgentManifest } from "./agent-manifest.ts";
 export { AGENT_TOOLS_FEATURE_NAME, createAgentToolsFeature } from "./feature.ts";
 export { buildToolCatalog, OPEN_FORM_TOOL_NAME, toolNameForQn } from "./tool-catalog.ts";
 export type { ToolCallRequest, ToolCallResult, ToolDispatcher } from "./tool-dispatch.ts";
-export { dispatchToolCall } from "./tool-dispatch.ts";
+export { dispatchToolCall, TOOL_CALL_ERROR_CODES } from "./tool-dispatch.ts";
 export type {
   AgentManifest,
   AgentManifestEntity,

package/packages/bundled-features/src/agent-tools/tool-dispatch.ts

@@ -1,6 +1,6 @@
 import type { SessionUser, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
 import { isKumikoError } from "@cosmicdrift/kumiko-framework/errors";
-import { runAsDirectCallEntry } from "@cosmicdrift/kumiko-framework/internal/request-context";
+import { runAsAgentToolCallEntry } from "@cosmicdrift/kumiko-framework/internal/request-context";
 import { createFallbackLogger, type Logger } from "@cosmicdrift/kumiko-framework/logging";
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { FILTER_OPS, isRecord } from "./filter-ops.ts";
@@ -58,6 +58,21 @@ type ToolFailure = {
 
 type FailureClassifier = (failure: ToolFailure, cause: unknown) => ToolCallResult;
 
+export const TOOL_CALL_ERROR_CODES = {
+  invalidToolCall: "invalid_tool_call",
+  unknownTool: "unknown_tool",
+} as const;
+
+type ToolCallFailure = Extract<ToolCallResult, { readonly ok: false }>;
+
+function invalidToolCall(error: string): ToolCallFailure {
+  return { ok: false, error, code: TOOL_CALL_ERROR_CODES.invalidToolCall };
+}
+
+function unknownTool(error: string): ToolCallFailure {
+  return { ok: false, error, code: TOOL_CALL_ERROR_CODES.unknownTool };
+}
+
 const HTTP_TOO_MANY_REQUESTS = 429;
 const HTTP_SERVER_ERROR = 500;
 const UNEXPECTED_FAILURE_MESSAGE = "Tool failed unexpectedly";
@@ -108,7 +123,7 @@ type FilterOp = (typeof FILTER_OPS)[number];
 
 type PayloadResult =
   | { readonly ok: true; readonly value: Readonly<Record<string, unknown>> }
-  | { readonly ok: false; readonly error: string };
+  | ToolCallFailure;
 
 function isFilterOp(value: unknown): value is FilterOp {
   return isOneOf(FILTER_OPS, value);
@@ -120,7 +135,7 @@ function buildSearchPayload(
 ): PayloadResult {
   const query = toolInput["query"];
   if (typeof query !== "string" || query.length === 0) {
-    return { ok: false, error: `Tool "${toolName}" requires a non-empty string "query" argument` };
+    return invalidToolCall(`Tool "${toolName}" requires a non-empty string "query" argument`);
   }
   return { ok: true, value: { search: query, limit: SEARCH_RESULT_LIMIT } };
 }
@@ -132,7 +147,7 @@ function buildFindByPayload(
 ): PayloadResult {
   const value = toolInput[fieldName];
   if (value === undefined) {
-    return { ok: false, error: `Tool "${toolName}" requires a "${fieldName}" argument` };
+    return invalidToolCall(`Tool "${toolName}" requires a "${fieldName}" argument`);
   }
   return {
     ok: true,
@@ -156,10 +171,10 @@ function buildEntityListPayload(
   const search = input["search"];
   if (search !== undefined) {
     if (typeof search !== "string") {
-      return { ok: false, error: `"search" must be a string` };
+      return invalidToolCall(`"search" must be a string`);
     }
     if (list.searchableFields.length === 0) {
-      return { ok: false, error: "This entity has no searchable fields" };
+      return invalidToolCall("This entity has no searchable fields");
     }
     payload["search"] = search;
   }
@@ -167,18 +182,18 @@ function buildEntityListPayload(
   const filters = input["filters"];
   if (filters !== undefined) {
     if (!Array.isArray(filters)) {
-      return { ok: false, error: `"filters" must be an array` };
+      return invalidToolCall(`"filters" must be an array`);
     }
     const validated: Array<{ field: string; op: FilterOp; value: unknown }> = [];
     for (const entry of filters) {
       if (!isRecord(entry) || typeof entry["field"] !== "string" || !("value" in entry)) {
-        return { ok: false, error: `Each filter must be { field, op, value }` };
+        return invalidToolCall(`Each filter must be { field, op, value }`);
       }
       if (!list.filterableFields.includes(entry["field"])) {
-        return { ok: false, error: `Field "${entry["field"]}" is not filterable on this entity` };
+        return invalidToolCall(`Field "${entry["field"]}" is not filterable on this entity`);
       }
       if (!isFilterOp(entry["op"])) {
-        return { ok: false, error: `Unsupported filter operator "${String(entry["op"])}"` };
+        return invalidToolCall(`Unsupported filter operator "${String(entry["op"])}"`);
       }
       validated.push({ field: entry["field"], op: entry["op"], value: entry["value"] });
     }
@@ -250,7 +265,7 @@ async function dispatchServerQuery(
   if (descriptor.detail) {
     const id = input["id"];
     if (typeof id !== "string" || id.length === 0) {
-      return { ok: false, error: `This tool requires a non-empty string "id" argument` };
+      return invalidToolCall(`This tool requires a non-empty string "id" argument`);
     }
     const data = await dispatcher.query(descriptor.qn, { id }, user);
     return { ok: true, data };
@@ -285,16 +300,16 @@ async function dispatchServerWrite(
   if (descriptor.injectsVersion) {
     const id = input["id"];
     if (typeof id !== "string" || id.length === 0) {
-      return { ok: false, error: `This tool requires a non-empty string "id" argument` };
+      return invalidToolCall(`This tool requires a non-empty string "id" argument`);
     }
     if (!descriptor.detailQn) {
-      return { ok: false, error: "Tool is misconfigured: no detail handler to read version from" };
+      return invalidToolCall("Tool is misconfigured: no detail handler to read version from");
     }
     const current = await dispatcher.query(descriptor.detailQn, { id }, user);
     const version =
       isRecord(current) && typeof current["version"] === "number" ? current["version"] : undefined;
     if (version === undefined) {
-      return { ok: false, error: `Could not read the current "version" for id "${id}"` };
+      return invalidToolCall(`Could not read the current "version" for id "${id}"`);
     }
     payload = { ...input, version };
   }
@@ -336,10 +351,10 @@ function dispatchClientNavigate(
   const entity = input["entity"];
   if (typeof entity === "string") {
     const screenId = descriptor.entityScreens.get(entity);
-    if (!screenId) return { ok: false, error: `Unknown entity "${entity}" for navigation` };
+    if (!screenId) return invalidToolCall(`Unknown entity "${entity}" for navigation`);
     const id = input["id"];
     if (typeof id !== "string" || id.length === 0) {
-      return { ok: false, error: `Navigating to "${entity}" requires a non-empty string "id"` };
+      return invalidToolCall(`Navigating to "${entity}" requires a non-empty string "id"`);
     }
     return { ok: true, data: { kind: "navigate", screenId, params: { id } } };
   }
@@ -347,19 +362,19 @@ function dispatchClientNavigate(
   const screenId = input["screenId"];
   if (typeof screenId === "string") {
     if (!descriptor.screenIds.has(screenId)) {
-      return { ok: false, error: `Unknown screen "${screenId}"` };
+      return invalidToolCall(`Unknown screen "${screenId}"`);
     }
     const params = input["params"];
     if (params !== undefined) {
       if (!isRecord(params) || Object.values(params).some((value) => typeof value !== "string")) {
-        return { ok: false, error: `"params" must be an object of string values` };
+        return invalidToolCall(`"params" must be an object of string values`);
       }
       return { ok: true, data: { kind: "navigate", screenId, params } };
     }
     return { ok: true, data: { kind: "navigate", screenId, params: {} } };
   }
 
-  return { ok: false, error: `navigate requires either { entity, id } or { screenId }` };
+  return invalidToolCall(`navigate requires either { entity, id } or { screenId }`);
 }
 
 function dispatchClientOpenForm(
@@ -368,10 +383,10 @@ function dispatchClientOpenForm(
 ): ToolCallResult {
   const handlerQn = input["handlerQn"];
   if (typeof handlerQn !== "string") {
-    return { ok: false, error: `open_form requires a string "handlerQn" argument` };
+    return invalidToolCall(`open_form requires a string "handlerQn" argument`);
   }
   const screenId = descriptor.formScreens.get(handlerQn);
-  if (!screenId) return { ok: false, error: `No form screen mounted for handler "${handlerQn}"` };
+  if (!screenId) return invalidToolCall(`No form screen mounted for handler "${handlerQn}"`);
   return {
     ok: true,
     data: { kind: "open_form", screenId, handlerQn, prefill: input["prefill"] ?? {} },
@@ -385,14 +400,14 @@ function isStringArray(value: unknown): value is readonly string[] {
 function dispatchClientAskUser(input: Readonly<Record<string, unknown>>): ToolCallResult {
   const question = input["question"];
   if (typeof question !== "string" || question.length === 0) {
-    return { ok: false, error: `ask_user requires a non-empty string "question" argument` };
+    return invalidToolCall(`ask_user requires a non-empty string "question" argument`);
   }
   const options = input["options"];
   if (options === undefined) {
     return { ok: true, data: { kind: "ask_user", question } };
   }
   if (!isStringArray(options)) {
-    return { ok: false, error: `ask_user "options" argument must be an array of strings` };
+    return invalidToolCall(`ask_user "options" argument must be an array of strings`);
   }
   return { ok: true, data: { kind: "ask_user", question, options } };
 }
@@ -411,23 +426,24 @@ function dispatchClient(
   }
 }
 
-/** Executes one LLM-issued tool call. Never throws — a missing tool, a missing argument, a
- *  disallowed filter field, or a rejected handler call (cap check, validation, ...) all come
- *  back as `{ ok: false }` so the agent loop can feed the error back to the model instead of
- *  crashing. Client errors (< 500) keep their message and carry a `code`; 429 adds
- *  `retryable`. Server-side failures (>= 500, unknown throws) are logged and returned as a
- *  generic message so internals never reach the model. `request.user` must be the caller's real identity — every server-kind tool runs
- *  through the same permission-checked dispatcher pipeline as a normal HTTP request. */
+/** Executes one LLM-issued tool call. Never throws: every failure comes back as `{ ok: false }`
+ *  so the agent loop can feed the error back to the model instead of crashing.
+ *  Every failure carries a `code`: the handler's own code for handler and dispatcher failures
+ *  (429 adds `retryable`), `invalid_tool_call` for bad arguments and `unknown_tool` for a tool
+ *  that is not in the table. Client errors (< 500) keep their message, server failures (>= 500,
+ *  unknown throws) are logged and returned as a generic message.
+ *  `request.user` must be the caller's real identity: server-kind tools run through the same
+ *  permission-checked pipeline as an HTTP request. */
 export async function dispatchToolCall(request: ToolCallRequest): Promise<ToolCallResult> {
   const { dispatcher, user, toolName, input, dispatchTable, runId, toolCallId } = request;
   const classifyFailure = createFailureClassifier(toolName, request.log ?? fallbackLog);
   const descriptor = dispatchTable.get(toolName);
   if (!descriptor) {
-    return { ok: false, error: `Unknown tool "${toolName}"` };
+    return unknownTool(`Unknown tool "${toolName}"`);
   }
 
   try {
-    return await runAsDirectCallEntry(async () => {
+    return await runAsAgentToolCallEntry(async () => {
       switch (descriptor.kind) {
         case "search":
           return await dispatchSearch(descriptor, dispatcher, user, toolName, input);

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

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Oversized audit cursor is documented as a 400 validation error",
+    "detail": "The cursor pattern comment now names the validation error (400) the API actually returns instead of 422."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Tests cover nested agent grants, erased subjects and anonymous change-password",
+    "detail": "Integration tests now check that a delegating tool handler keeps the cross-tenant-read marker closed, that an erased subject gets no consumer-protection mail, and that the anonymous change-password check runs once; the audit seed helper uses withEnv."
+  },
   {
     "version": "0.384.0",
     "type": "improvement",

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

@@ -49,6 +49,7 @@ export function createAuditFeature(): FeatureDefinition {
   return defineFeature(
     "audit",
     (r) => {
+      r.adoptsBundledLists();
       r.describe(
         "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. A SystemAdmin can pass `scope: \"system\"` to read the app-instance system events such as `app.started`, and reads the events of every tenant (system tenant excluded) through `audit:query:list-all-tenants` and the `audit-log-all-tenants` screen. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
       );

package/packages/bundled-features/src/audit/handlers/audit-events.ts

@@ -20,7 +20,7 @@ import {
 
 const MAX_LIMIT = 100;
 
-// At most 18 digits keeps the id inside bigint, so an oversized cursor or id is a 422, not a 500.
+// At most 18 digits keeps the id inside bigint, so an oversized cursor or id is a validation error (400), not a 500.
 const CURSOR_PATTERN = /^\d{1,18}$/;
 
 export const auditListPayloadShape = {

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

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "Optional returnTo for password reset and signup",
+    "detail": "Password reset and signup accept an optional returnTo path. A safe value (same-origin path, no dot segments) is appended to the mailed link as a query parameter, the reset and signup-complete screens follow it, and the login screen forwards its next to the forgot-password and signup links. Invalid values are dropped silently and never block the mail. isSafeReturnPath and readReturnToFromSearch are exported from the web barrel. isSafeNextPath now uses the same check, so a next with a dot segment such as \"/a/../b\" is no longer followed."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "CurrentUser carries tenantId, logout clears remembered list state",
+    "detail": "The session CurrentUser has an optional tenantId used to scope remembered list state; logout removes all kumiko.list.* storage entries."
+  },
   {
     "version": "0.385.0",
     "type": "improvement",

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/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 =
@@ -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 }),

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 = {
@@ -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/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/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 }),
     },
   );
 

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

@@ -226,12 +226,13 @@ async function parseTokenFailure(res: Response): Promise<AuthTokenFailure> {
 // found. 429 → typed rate-limit failure. 5xx → unknown-error.
 export async function requestPasswordReset(
   email: string,
+  returnTo?: string,
 ): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
   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 };
   return { ok: false, error: await parseTokenFailure(res) };
@@ -332,12 +333,17 @@ export async function requestSignup(
   // travels any further than this request — never in the URL, the mail,
   // or the confirm response.
   handover?: { readonly entityType: string; readonly token: string },
+  returnTo?: string,
 ): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
   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 };
   return { ok: false, error: await parseTokenFailure(res) };

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

@@ -2,35 +2,37 @@
 // string, so anything read back from it is untrusted: only same-origin
 // root-relative paths pass (no "//host", no "/\host", no scheme).
 
-export const NEXT_QUERY_PARAM = "next";
+import { isSafeReturnPath, RETURN_TO_QUERY_PARAM, readReturnToFromSearch } from "./return-path.ts";
 
-function hasControlOrWhitespace(candidate: string): boolean {
-  for (let i = 0; i < candidate.length; i++) {
-    const code = candidate.charCodeAt(i);
-    if (code <= 0x20 || code === 0x7f) return true;
-  }
-  return false;
-}
+export const NEXT_QUERY_PARAM = "next";
 
-// The URL parse is a backstop: browsers strip tabs/newlines, so "/\t/evil.com"
-// would otherwise normalize to "//evil.com" past the leading-slash check.
-export function isSafeNextPath(candidate: unknown): candidate is string {
-  if (typeof candidate !== "string" || !candidate.startsWith("/")) return false;
-  if (candidate[1] === "/" || candidate.includes("\\")) return false;
-  if (hasControlOrWhitespace(candidate)) return false;
-  try {
-    const parsed = new URL(candidate, "https://next.invalid");
-    return parsed.origin === "https://next.invalid" && !parsed.pathname.startsWith("//");
-  } catch {
-    return false;
-  }
-}
+export const isSafeNextPath = isSafeReturnPath;
 
 export function readNextFromSearch(search: string): string | null {
   const candidate = new URLSearchParams(search).get(NEXT_QUERY_PARAM);
   return isSafeNextPath(candidate) ? candidate : null;
 }
 
+// The returnTo a mail link or sibling auth page carried in this page's own URL; null on native, where there is no window.
+export function readReturnToFromWindow(): string | null {
+  return typeof window === "undefined" ? null : readReturnToFromSearch(window.location.search);
+}
+
+// Adds returnTo to an href of a sibling auth page; a missing value leaves the href untouched.
+export function appendReturnTo(href: string, returnTo: string | null): string {
+  if (returnTo === null) return href;
+  const hashAt = href.indexOf("#");
+  const base = hashAt === -1 ? href : href.slice(0, hashAt);
+  const hash = hashAt === -1 ? "" : href.slice(hashAt);
+  const separator = base.includes("?") ? "&" : "?";
+  return `${base}${separator}${RETURN_TO_QUERY_PARAM}=${encodeURIComponent(returnTo)}${hash}`;
+}
+
+// The safe `next` of this page's URL; null on native, where there is no window.
+export function readNextFromWindow(): string | null {
+  return typeof window === "undefined" ? null : readNextFromSearch(window.location.search);
+}
+
 // loginUrl/postLogoutUrl come from app code (trusted), but a typo like
 // "javascript:" must fail at startup instead of becoming a navigation target.
 export function assertNavigableUrl(url: string, optionName: string): void {

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

@@ -1,3 +1,4 @@
+import { stripBasePath, useBasePath } from "@cosmicdrift/kumiko-renderer";
 import type { ReactNode } from "react";
 import { DEFAULT_AUTH_PATHS, DEFAULT_FORGOT_PASSWORD_PATH } from "./auth-paths.ts";
 import { ConfirmAccountUnlockScreen } from "./confirm-account-unlock-screen.tsx";
@@ -9,8 +10,9 @@ function hasToken(search: string): boolean {
   return (new URLSearchParams(search).get("token") ?? "") !== "";
 }
 
-function pickDefaultAuthPage(pathname: string, search: string): ReactNode {
-  const path = pathname.length > 1 ? pathname.replace(/\/+$/, "") : pathname;
+function pickDefaultAuthPage(pathname: string, search: string, basePath: string): ReactNode {
+  const trimmed = pathname.length > 1 ? pathname.replace(/\/+$/, "") : pathname;
+  const path = stripBasePath(trimmed, basePath);
   switch (path) {
     case DEFAULT_FORGOT_PASSWORD_PATH:
       return <ForgotPasswordScreen />;
@@ -27,5 +29,6 @@ function pickDefaultAuthPage(pathname: string, search: string): ReactNode {
 // (outer) still win on the same path. The pages are public: no session needed.
 export function DefaultAuthPagesGate({ children }: { readonly children: ReactNode }): ReactNode {
   const { pathname, search } = window.location;
-  return pickDefaultAuthPage(pathname, search) ?? <>{children}</>;
+  const basePath = useBasePath();
+  return pickDefaultAuthPage(pathname, search, basePath) ?? <>{children}</>;
 }