@cosmicdrift/kumiko-bundled-features 0.387.0 → 0.389.0

package/dist/agent-tools/index.d.ts

@@ -4,5 +4,5 @@ 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, AgentManifestFeature, AgentManifestField, AgentManifestHandler, AgentManifestNav, AgentManifestOptions, AgentManifestScreen, AgentManifestWorkspace, AgentToolMode, RegistryManifestView, RegistrySearchView, ToolCatalog, ToolCatalogOptions, ToolDefinition, ToolDispatchDescriptor, } from "./types.ts";

package/dist/agent-tools/index.js

@@ -2,4 +2,4 @@ export { AgentDocGapKinds, findAgentDocGaps, findHandlerTranslationGaps, formatA
 export { buildAgentManifest } from "./agent-manifest.js";
 export { AGENT_TOOLS_FEATURE_NAME, createAgentToolsFeature } from "./feature.js";
 export { buildToolCatalog, OPEN_FORM_TOOL_NAME, toolNameForQn } from "./tool-catalog.js";
-export { dispatchToolCall } from "./tool-dispatch.js";
+export { dispatchToolCall, TOOL_CALL_ERROR_CODES } from "./tool-dispatch.js";

package/dist/agent-tools/tool-dispatch.d.ts

@@ -37,11 +37,16 @@ export type ToolCallRequest = {
     /** Receives the cause of unexpected (5xx) failures, which the tool result never carries. */
     readonly log?: Pick<Logger, "error">;
 };
-/** 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. */
+export declare const TOOL_CALL_ERROR_CODES: {
+    readonly invalidToolCall: "invalid_tool_call";
+    readonly unknownTool: "unknown_tool";
+};
+/** 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 declare function dispatchToolCall(request: ToolCallRequest): Promise<ToolCallResult>;

package/dist/agent-tools/tool-dispatch.js

@@ -1,8 +1,18 @@
 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 } from "@cosmicdrift/kumiko-framework/logging";
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { FILTER_OPS, isRecord } from "./filter-ops.js";
+export const TOOL_CALL_ERROR_CODES = {
+    invalidToolCall: "invalid_tool_call",
+    unknownTool: "unknown_tool",
+};
+function invalidToolCall(error) {
+    return { ok: false, error, code: TOOL_CALL_ERROR_CODES.invalidToolCall };
+}
+function unknownTool(error) {
+    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";
@@ -52,14 +62,14 @@ function isFilterOp(value) {
 function buildSearchPayload(toolName, toolInput) {
     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 } };
 }
 function buildFindByPayload(toolName, fieldName, toolInput) {
     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,
@@ -75,28 +85,28 @@ function buildEntityListPayload(list, input) {
     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;
     }
     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 = [];
         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"] });
         }
@@ -147,7 +157,7 @@ async function dispatchServerQuery(descriptor, dispatcher, user, input) {
     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 };
@@ -171,15 +181,15 @@ async function dispatchServerWrite(descriptor, dispatcher, user, input, runId, t
     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 };
     }
@@ -211,37 +221,37 @@ function dispatchClientNavigate(descriptor, input) {
     if (typeof entity === "string") {
         const screenId = descriptor.entityScreens.get(entity);
         if (!screenId)
-            return { ok: false, error: `Unknown entity "${entity}" for navigation` };
+            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 } } };
     }
     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(descriptor, input) {
     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}"` };
+        return invalidToolCall(`No form screen mounted for handler "${handlerQn}"`);
     return {
         ok: true,
         data: { kind: "open_form", screenId, handlerQn, prefill: input["prefill"] ?? {} },
@@ -253,14 +263,14 @@ function isStringArray(value) {
 function dispatchClientAskUser(input) {
     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 } };
 }
@@ -274,22 +284,23 @@ function dispatchClient(descriptor, input) {
             return dispatchClientAskUser(input);
     }
 }
-/** 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) {
     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/dist/audit/feature.js

@@ -23,6 +23,7 @@ import { AUDIT_I18N } from "./web/i18n.js";
 // framework).
 export function createAuditFeature() {
     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).");
         r.uiHints({
             displayLabel: "Audit Log",

package/dist/audit/handlers/audit-events.js

@@ -12,7 +12,7 @@ import { redactPiiCiphertext } from "../../shared/index.js";
 import { eventLabelKeyOf, TECHNICAL_EVENT_TYPES } from "../event-classification.js";
 import { AUDIT_EVENT_ACTIONS, INCLUDE_TECHNICAL_FILTER, } from "../web/constants.js";
 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 = {
     cursor: z.string().regex(CURSOR_PATTERN, "cursor must be a positive integer").optional(),

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/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) {
@@ -95,6 +98,7 @@ export function createSignupRequestHandler(opts) {
                 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/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.
@@ -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/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/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;

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

@@ -1,36 +1,31 @@
 // Redirect targets for external login pages. `next` travels through the query
 // string, so anything read back from it is untrusted: only same-origin
 // root-relative paths pass (no "//host", no "/\host", no scheme).
+import { isSafeReturnPath, RETURN_TO_QUERY_PARAM, readReturnToFromSearch } from "./return-path.js";
 export const NEXT_QUERY_PARAM = "next";
-function hasControlOrWhitespace(candidate) {
-    for (let i = 0; i < candidate.length; i++) {
-        const code = candidate.charCodeAt(i);
-        if (code <= 0x20 || code === 0x7f)
-            return true;
-    }
-    return false;
-}
-// The URL parse is a backstop: browsers strip tabs/newlines, so "/\t/evil.com"
-// would otherwise normalize to "//evil.com" past the leading-slash check.
-export function isSafeNextPath(candidate) {
-    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) {
     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() {
+    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, returnTo) {
+    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() {
+    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, optionName) {

package/dist/auth-email-password/web/default-auth-pages-gate.js

@@ -1,4 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { stripBasePath, useBasePath } from "@cosmicdrift/kumiko-renderer";
 import { DEFAULT_AUTH_PATHS, DEFAULT_FORGOT_PASSWORD_PATH } from "./auth-paths.js";
 import { ConfirmAccountUnlockScreen } from "./confirm-account-unlock-screen.js";
 import { ForgotPasswordScreen } from "./forgot-password-screen.js";
@@ -7,8 +8,9 @@ import { ResetPasswordScreen } from "./reset-password-screen.js";
 function hasToken(search) {
     return (new URLSearchParams(search).get("token") ?? "") !== "";
 }
-function pickDefaultAuthPage(pathname, search) {
-    const path = pathname.length > 1 ? pathname.replace(/\/+$/, "") : pathname;
+function pickDefaultAuthPage(pathname, search, basePath) {
+    const trimmed = pathname.length > 1 ? pathname.replace(/\/+$/, "") : pathname;
+    const path = stripBasePath(trimmed, basePath);
     switch (path) {
         case DEFAULT_FORGOT_PASSWORD_PATH:
             return _jsx(ForgotPasswordScreen, {});
@@ -24,5 +26,6 @@ function pickDefaultAuthPage(pathname, search) {
 // (outer) still win on the same path. The pages are public: no session needed.
 export function DefaultAuthPagesGate({ children }) {
     const { pathname, search } = window.location;
-    return pickDefaultAuthPage(pathname, search) ?? _jsx(_Fragment, { children: children });
+    const basePath = useBasePath();
+    return pickDefaultAuthPage(pathname, search, basePath) ?? _jsx(_Fragment, { children: children });
 }

package/dist/auth-email-password/web/forgot-password-screen.d.ts

@@ -5,5 +5,8 @@ export type ForgotPasswordScreenProps = {
     /** href for the "Back to login" link in the success and form states. App-
      * specific — defaults to "/login". */
     readonly loginHref?: string;
+    /** Page the reset mail should lead back to after the new password is set; defaults to the
+     *  `returnTo` query parameter of this page. Unsafe values are dropped. */
+    readonly returnTo?: string;
 };
-export declare function ForgotPasswordScreen({ title, subtitle, loginHref, }: ForgotPasswordScreenProps): ReactNode;
+export declare function ForgotPasswordScreen({ title, subtitle, loginHref, returnTo, }: ForgotPasswordScreenProps): ReactNode;

package/dist/auth-email-password/web/forgot-password-screen.js

@@ -12,7 +12,12 @@ import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { useState } from "react";
 import { requestPasswordReset } from "./auth-client.js";
 import { AuthCard } from "./auth-form-primitives.js";
-export function ForgotPasswordScreen({ title, subtitle, loginHref = "/login", }) {
+import { readReturnToFromWindow } from "./auth-redirect.js";
+import { isSafeReturnPath } from "./return-path.js";
+function resolveReturnTo(prop) {
+    return (isSafeReturnPath(prop) ? prop : readReturnToFromWindow()) ?? undefined;
+}
+export function ForgotPasswordScreen({ title, subtitle, loginHref = "/login", returnTo, }) {
     const t = useTranslation();
     const { Form, Field, Input, Button, Banner, Link } = usePrimitives();
     const [email, setEmail] = useState("");
@@ -24,7 +29,7 @@ export function ForgotPasswordScreen({ title, subtitle, loginHref = "/login", })
         setSubmitting(true);
         setError(null);
         try {
-            const res = await requestPasswordReset(email);
+            const res = await requestPasswordReset(email, resolveReturnTo(returnTo));
             if (res.ok) {
                 setDone(true);
             }