@cosmicdrift/kumiko-samples 0.392.2 → 0.394.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.392.2",
+  "version": "0.394.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.392.2",
+  "version": "0.394.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>",
@@ -65,12 +65,13 @@
     "./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-paddle": "./src/subscription-paddle/index.ts",
     "./subscription-mollie": "./src/subscription-mollie/index.ts",
     "./foundation-shared": "./src/foundation-shared/index.ts",
     "./auth-foundation": "./src/auth-foundation/index.ts",
     "./mail-foundation": "./src/mail-foundation/index.ts",
     "./inbound-mail-foundation": "./src/inbound-mail-foundation/index.ts",
+    "./inbound-mail-foundation/web": "./src/inbound-mail-foundation/web/index.ts",
     "./inbound-provider-inmemory": "./src/inbound-provider-inmemory/index.ts",
     "./inbound-provider-imap": "./src/inbound-provider-imap/index.ts",
     "./mail-transport-smtp": "./src/mail-transport-smtp/index.ts",
@@ -104,6 +105,7 @@
     "./auth-email-password": "./src/auth-email-password/index.ts",
     "./auth-email-password/constants": "./src/auth-email-password/web/constants.ts",
     "./auth-email-password/return-path": "./src/auth-email-password/web/return-path.ts",
+    "./auth-email-password/static-login": "./src/auth-email-password/web/static-login.ts",
     "./auth-email-password/email-templates": "./src/auth-email-password/email-templates.ts",
     "./auth-email-password/seeding": "./src/auth-email-password/seeding.ts",
     "./auth-email-password/testing": "./src/auth-email-password/testing.ts",
@@ -364,9 +366,9 @@
         "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-paddle": {
+        "types": "./dist/subscription-paddle/index.d.ts",
+        "default": "./dist/subscription-paddle/index.js"
       },
       "./subscription-mollie": {
         "types": "./dist/subscription-mollie/index.d.ts",
@@ -388,6 +390,10 @@
         "types": "./dist/inbound-mail-foundation/index.d.ts",
         "default": "./dist/inbound-mail-foundation/index.js"
       },
+      "./inbound-mail-foundation/web": {
+        "types": "./dist/inbound-mail-foundation/web/index.d.ts",
+        "default": "./dist/inbound-mail-foundation/web/index.js"
+      },
       "./inbound-provider-inmemory": {
         "types": "./dist/inbound-provider-inmemory/index.d.ts",
         "default": "./dist/inbound-provider-inmemory/index.js"
@@ -524,6 +530,10 @@
         "types": "./dist/auth-email-password/web/return-path.d.ts",
         "default": "./dist/auth-email-password/web/return-path.js"
       },
+      "./auth-email-password/static-login": {
+        "types": "./dist/auth-email-password/web/static-login.d.ts",
+        "default": "./dist/auth-email-password/web/static-login.js"
+      },
       "./auth-email-password/seeding": {
         "types": "./dist/auth-email-password/seeding.d.ts",
         "default": "./dist/auth-email-password/seeding.js"

package/packages/bundled-features/src/account-security/README.md

@@ -25,7 +25,7 @@ const features = [
 | Option | Default | Effect |
 | --- | --- | --- |
 | `access` | `openToAll` | Who may open the dashboard, e.g. `{ roles: ["Admin", "Editor"] }` |
-| `nav` | none | `{ order?, parent? }` adds a sidebar entry. Without it the screen is dormant and apps link it from the user menu |
+| `nav` | none | `{ order?, parent?, icon? }` (icon default `"user"`) adds a sidebar entry. Without it the screen is dormant and apps link it from the user menu |
 
 The MFA panels switch on `auth-mfa:query:status` (`enabled`), exported as
 `accountSecurityMfaStatusVisibility`.

package/packages/bundled-features/src/account-security/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "account-security nav has a default icon and an icon option",
+    "detail": "The nav entry shows the `user` icon by default. `nav.icon` takes any nav icon key to override it, so apps no longer need their own nav entry just for an icon."
+  },
   {
     "version": "0.376.0",
     "type": "improvement",

package/packages/bundled-features/src/account-security/feature.ts

@@ -3,6 +3,7 @@ import {
   defineFeature,
   type FeatureDefinition,
 } from "@cosmicdrift/kumiko-framework/engine";
+import type { NavIconKey } from "@cosmicdrift/kumiko-types/nav-icon";
 import {
   AuthMfaQueries,
   MFA_DISABLE_SCREEN_ID,
@@ -21,6 +22,7 @@ import { ACCOUNT_SECURITY_I18N } from "./web/i18n.ts";
 export interface AccountSecurityNavOptions {
   readonly order?: number;
   readonly parent?: string;
+  readonly icon?: NavIconKey;
 }
 
 export interface AccountSecurityFeatureOptions {
@@ -37,6 +39,7 @@ const DEFAULT_ACCESS: AccessRule = {
 };
 
 const DEFAULT_NAV_ORDER = 90;
+const DEFAULT_NAV_ICON: NavIconKey = "user";
 
 export const accountSecurityMfaStatusVisibility = {
   query: AuthMfaQueries.status,
@@ -87,10 +90,15 @@ export function createAccountSecurityFeature(
       // Explicit property assignments: the feature-AST parser reads neither
       // `??`, shorthand properties nor a conditional spread, and the boot validator treats
       // `parent: undefined` as a top-level entry.
-      const { order: navOrder = DEFAULT_NAV_ORDER, parent: navParent } = nav;
+      const {
+        order: navOrder = DEFAULT_NAV_ORDER,
+        parent: navParent,
+        icon: navIcon = DEFAULT_NAV_ICON,
+      } = nav;
       r.nav({
         id: ACCOUNT_SECURITY_SCREEN_ID,
         label: ACCOUNT_SECURITY_NAV_LABEL,
+        icon: navIcon,
         screen: ACCOUNT_SECURITY_SCREEN_QN,
         order: navOrder,
         parent: navParent,

package/packages/bundled-features/src/audit/event-classification.ts

@@ -18,6 +18,7 @@ export const AUDIT_EVENT_STANCES: Readonly<Record<string, AuditEventStance>> = {
   "cap-counter:event:rolling-incremented": TECHNICAL_EVENT,
   "cap-counter:event:rolling-released": TECHNICAL_EVENT,
   "inbound-mail-foundation:event:inbound-message-received": TECHNICAL_EVENT,
+  "inbound-mail-foundation:event:inbound-message-content-fetched": TECHNICAL_EVENT,
   "inbound-mail-foundation:event:mail-thread-updated": TECHNICAL_EVENT,
   "document-ingest-foundation:event:document-ingest-requested": TECHNICAL_EVENT,
   "document-ingest-foundation:event:document-ingest-skipped": TECHNICAL_EVENT,

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "static-login subpath for static sites",
+    "detail": "`@cosmicdrift/kumiko-bundled-features/auth-email-password/static-login` imports neither React nor the renderer. It offers `loginWithPassword` and `verifyMfaCode` (same requests as the SPA login, one result union with success, mfa-challenge, mfa-setup-required and failure incl. network and rate limit), `appReturnPath` and `postLoginPath` for the `next` filter, `forgotPasswordHref`, and `marketingLoginUrl({ localePaths, isAppPath })`, a `LoginUrlBuilder` for the auth gate that sends visitors to the marketing login with `next`. `LoginUrlBuilder` and `failureFromErrorField` are now exported from `auth-email-password/web`."
+  },
   {
     "version": "0.390.0",
     "type": "improvement",

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

@@ -9,6 +9,14 @@
 
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { CSRF_HEADER_NAME, readCsrfToken } from "@cosmicdrift/kumiko-renderer/live";
+import {
+  failureFromErrorField,
+  type LoginFailure,
+  parseRetryAfterSeconds,
+} from "./login-failure.ts";
+
+export type { KnownLoginFailureReason, LoginFailure } from "./login-failure.ts";
+export { parseRetryAfterSeconds };
 
 export type TenantSummary = {
   readonly tenantId: string;
@@ -36,28 +44,6 @@ export type LoginResponse = {
   readonly landingPath?: string;
 };
 
-// Reason codes the login-handler is known to emit today (login-screen.tsx's
-// reasonToKey maps every one of these to an i18n key). The server can also
-// send a reason this client doesn't know about yet (rolling deploys, a new
-// enforcement policy) — `string & {}` keeps that open while still giving
-// autocomplete/typo-checking on the known set, instead of collapsing both
-// to plain `string` (coding-standards: no magic strings without a union).
-export type KnownLoginFailureReason =
-  | "invalid_credentials"
-  | "no_membership"
-  | "account_locked"
-  | "email_not_verified"
-  | "rate_limited"
-  | "invalid_body"
-  | "mfa_not_supported"
-  | "mfa_setup_required";
-
-export type LoginFailure = {
-  readonly reason: KnownLoginFailureReason | (string & {});
-  readonly message?: string;
-  readonly retryAfterSeconds?: number;
-};
-
 export function csrfHeader(): Record<string, string> {
   const token = readCsrfToken();
   return token !== undefined ? { [CSRF_HEADER_NAME]: token } : {};
@@ -76,13 +62,6 @@ export class AuthRequestError extends Error {
   }
 }
 
-// Only a non-negative integer second count is usable; anything else is treated as absent.
-export function parseRetryAfterSeconds(header: string | null): number | undefined {
-  if (header === null) return undefined;
-  if (!/^\d+$/.test(header)) return undefined;
-  return Number(header);
-}
-
 // LoginResult mirrors the two-step login contract auth-routes.ts owns: a
 // straight success, an MFA challenge (auth-mfa mints the token), an
 // MFA-setup-required block (enforcement policy blocks an unenrolled user),
@@ -128,13 +107,7 @@ export async function login(req: LoginRequest): Promise<LoginResult> {
     mfaSetupRequired?: boolean;
     preauthSetupToken?: string;
     landingPath?: string;
-    error?:
-      | {
-          code?: string;
-          message?: string;
-          details?: { reason?: string; retryAfterSeconds?: number };
-        }
-      | string;
+    error?: unknown;
   };
   if (body.isSuccess === true) {
     if (body.mfaRequired === true && typeof body.challengeToken === "string") {
@@ -153,22 +126,7 @@ export async function login(req: LoginRequest): Promise<LoginResult> {
       return { kind: "success", data: toLoginResponse(body.token, body.user, body.landingPath) };
     }
   }
-  // The server sends error either as a string ("invalid_body") or as a
-  // structured object. Extract the most descriptive reason.
-  const err = body.error;
-  if (typeof err === "string") {
-    return { kind: "failure", error: { reason: err } };
-  }
-  const reason = err?.details?.reason ?? err?.code ?? "login_failed";
-  const retry = err?.details?.retryAfterSeconds;
-  return {
-    kind: "failure",
-    error: {
-      reason,
-      ...(err?.message !== undefined && { message: err.message }),
-      ...(retry !== undefined && { retryAfterSeconds: retry }),
-    },
-  };
+  return { kind: "failure", error: failureFromErrorField(body.error, "login_failed") };
 }
 
 // POST /api/auth/logout. The server revokes the session when

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

@@ -16,6 +16,10 @@ import {
   followNextOrLandingAfterLogin,
 } from "./auth-redirect.ts";
 import { LoginScreen, type LoginScreenProps } from "./login-screen.tsx";
+import type { LoginUrlBuilder } from "./login-url.ts";
+
+export type { LoginUrlBuilder };
+
 import { SessionProvider, useSession } from "./session.tsx";
 import { SessionBootstrapErrorScreen } from "./session-bootstrap-error.tsx";
 
@@ -159,10 +163,6 @@ export function createLoginRoute(
   return LoginRoute;
 }
 
-/** Builds the login page URL. `returnPath` is the current path + query + hash;
- *  append it as `next` yourself (use `NEXT_QUERY_PARAM`) if the login page should return there. */
-export type LoginUrlBuilder = (locale: string, returnPath: string) => string;
-
 export type AuthGateOptions = LoginRouteOptions & {
   /** Login page outside the SPA (root-relative path or http(s) URL), or a function
    *  that builds it per locale. Unauthenticated visitors are sent there with

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

@@ -2,9 +2,10 @@
 // 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.ts";
+import { appendReturnTo, NEXT_QUERY_PARAM } from "./login-url.ts";
+import { isSafeReturnPath, readReturnToFromSearch } from "./return-path.ts";
 
-export const NEXT_QUERY_PARAM = "next";
+export { appendReturnTo, NEXT_QUERY_PARAM };
 
 export const isSafeNextPath = isSafeReturnPath;
 
@@ -18,16 +19,6 @@ 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);

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

@@ -32,6 +32,7 @@ export { AuthCard, AuthShellProvider, useAuthShell } from "./auth-form-primitive
 export type {
   AuthGateOptions,
   LoginRouteOptions,
+  LoginUrlBuilder,
   MfaSetupComponentProps,
   MfaVerifyComponentProps,
   SessionAuthGateOptions,
@@ -57,6 +58,7 @@ export { ForgotPasswordScreen } from "./forgot-password-screen.tsx";
 export { defaultTranslations, mergeTranslations } from "./i18n.ts";
 export type { InviteAcceptScreenProps } from "./invite-accept-screen.tsx";
 export { InviteAcceptScreen } from "./invite-accept-screen.tsx";
+export { failureFromErrorField } from "./login-failure.ts";
 export type { AuthLegalLink, LoginScreenProps } from "./login-screen.tsx";
 export { LoginScreen } from "./login-screen.tsx";
 export type { RequestAccountUnlockScreenProps } from "./request-account-unlock-screen.tsx";

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

@@ -0,0 +1,54 @@
+// Pure (no DOM, no renderer): shared by the SPA clients and the static login, which must stay
+// importable from a plain script.
+
+// Reason codes the login handler is known to emit (login-screen.tsx's reasonToKey maps every one
+// of these to an i18n key). The server can also send a reason this client does not know yet
+// (rolling deploys, a new enforcement policy), so consumers type `KnownLoginFailureReason |
+// (string & {})`: autocomplete on the known set, no collapse to plain `string`.
+export type KnownLoginFailureReason =
+  | "invalid_credentials"
+  | "no_membership"
+  | "account_locked"
+  | "email_not_verified"
+  | "rate_limited"
+  | "invalid_body"
+  | "mfa_not_supported"
+  | "mfa_setup_required";
+
+export type LoginFailure = {
+  readonly reason: KnownLoginFailureReason | (string & {});
+  readonly message?: string;
+  readonly retryAfterSeconds?: number;
+};
+
+// Only a non-negative integer second count is usable; anything else is treated as absent.
+export function parseRetryAfterSeconds(header: string | null): number | undefined {
+  if (header === null) return undefined;
+  if (!/^\d+$/.test(header)) return undefined;
+  return Number(header);
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringOrUndefined(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+// The server sends `error` either as a string ("invalid_body") or as a structured object; this
+// extracts the most descriptive reason, falling back to the endpoint's generic one.
+export function failureFromErrorField(error: unknown, fallbackReason: string): LoginFailure {
+  if (typeof error === "string") return { reason: error };
+  const fields = isRecord(error) ? error : {};
+  const details = isRecord(fields["details"]) ? fields["details"] : {};
+  const reason =
+    stringOrUndefined(details["reason"]) ?? stringOrUndefined(fields["code"]) ?? fallbackReason;
+  const message = stringOrUndefined(fields["message"]);
+  const retry = details["retryAfterSeconds"];
+  return {
+    reason,
+    ...(message !== undefined && { message }),
+    ...(typeof retry === "number" && { retryAfterSeconds: retry }),
+  };
+}

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

@@ -0,0 +1,19 @@
+// Pure (no DOM, no `new URL`): the redirect vocabulary shared by the SPA gate and the static login.
+
+import { RETURN_TO_QUERY_PARAM } from "./return-path.ts";
+
+export const NEXT_QUERY_PARAM = "next";
+
+/** Builds the login page URL. `returnPath` is the current path + query + hash;
+ *  append it as `next` yourself (use `NEXT_QUERY_PARAM`) if the login page should return there. */
+export type LoginUrlBuilder = (locale: string, returnPath: string) => string;
+
+// 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}`;
+}

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

@@ -0,0 +1,183 @@
+// DOM-free login for static sites (plain Astro scripts): fetch plus pure string logic only. It
+// must not import auth-client.ts or auth-gate.tsx, which pull in the renderer, React and window
+// access at import time. Only the pure modules below are allowed.
+
+import {
+  failureFromErrorField,
+  isRecord,
+  type KnownLoginFailureReason,
+  parseRetryAfterSeconds,
+} from "./login-failure.ts";
+import { appendReturnTo, type LoginUrlBuilder, NEXT_QUERY_PARAM } from "./login-url.ts";
+import { isSafeReturnPath } from "./return-path.ts";
+
+export { NEXT_QUERY_PARAM };
+
+export const STATIC_LOGIN_FAILED_REASON = "login_failed";
+export const STATIC_MFA_VERIFY_FAILED_REASON = "mfa_verify_failed";
+export const STATIC_NETWORK_FAILURE_REASON = "network";
+export const STATIC_RATE_LIMITED_REASON = "rate_limited" satisfies KnownLoginFailureReason;
+export const STATIC_MFA_SETUP_REQUIRED_REASON =
+  "mfa_setup_required" satisfies KnownLoginFailureReason;
+
+export type StaticAuthResult =
+  | { readonly kind: "success"; readonly landingPath?: string }
+  | { readonly kind: "mfa-challenge"; readonly challengeToken: string }
+  | { readonly kind: "mfa-setup-required" }
+  | {
+      readonly kind: "failure";
+      readonly reason: KnownLoginFailureReason | (string & {});
+      readonly retryAfterSeconds?: number;
+    };
+
+function failure(
+  reason: string,
+  retryAfterSeconds?: number,
+): Extract<StaticAuthResult, { kind: "failure" }> {
+  return {
+    kind: "failure",
+    reason,
+    ...(retryAfterSeconds !== undefined && { retryAfterSeconds }),
+  };
+}
+
+function interpretBody(body: Record<string, unknown>, fallbackReason: string): StaticAuthResult {
+  if (body["isSuccess"] === true) {
+    const challengeToken = body["challengeToken"];
+    if (body["mfaRequired"] === true && typeof challengeToken === "string") {
+      return { kind: "mfa-challenge", challengeToken };
+    }
+    if (body["mfaSetupRequired"] === true) return { kind: "mfa-setup-required" };
+    if (body["token"] !== undefined && body["user"] !== undefined) {
+      const landingPath = body["landingPath"];
+      return typeof landingPath === "string"
+        ? { kind: "success", landingPath }
+        : { kind: "success" };
+    }
+  }
+  const { reason, retryAfterSeconds } = failureFromErrorField(body["error"], fallbackReason);
+  if (reason === STATIC_MFA_SETUP_REQUIRED_REASON) return { kind: "mfa-setup-required" };
+  return failure(reason, retryAfterSeconds);
+}
+
+// Same request shape as auth-client's login() and mfa-client's verifyMfaChallenge(): no CSRF
+// header because no session exists yet.
+async function postAuth(
+  path: string,
+  payload: Record<string, string>,
+  fallbackReason: string,
+): Promise<StaticAuthResult> {
+  let res: Response;
+  try {
+    res = await fetch(path, {
+      method: "POST",
+      credentials: "same-origin",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+  } catch {
+    return failure(STATIC_NETWORK_FAILURE_REASON);
+  }
+  if (res.status === 429) {
+    return failure(
+      STATIC_RATE_LIMITED_REASON,
+      parseRetryAfterSeconds(res.headers.get("Retry-After")),
+    );
+  }
+  const parsed: unknown = await res.json().catch(() => ({}));
+  return interpretBody(isRecord(parsed) ? parsed : {}, fallbackReason);
+}
+
+export function loginWithPassword(email: string, password: string): Promise<StaticAuthResult> {
+  return postAuth("/api/auth/login", { email, password }, STATIC_LOGIN_FAILED_REASON);
+}
+
+export function verifyMfaCode(challengeToken: string, code: string): Promise<StaticAuthResult> {
+  return postAuth(
+    "/api/auth/mfa/verify",
+    { challengeToken, code },
+    STATIC_MFA_VERIFY_FAILED_REASON,
+  );
+}
+
+export type IsAppPath = (pathname: string) => boolean;
+
+function pathnameOf(pathAndQuery: string): string {
+  const end = pathAndQuery.search(/[?#]/);
+  return end === -1 ? pathAndQuery : pathAndQuery.slice(0, end);
+}
+
+// `next` is read from a URL, so beyond the shared same-origin check it must also point into the
+// app; string logic only, because React Native's URL getters throw.
+export function appReturnPath(candidate: unknown, isAppPath: IsAppPath): string | null {
+  if (!isSafeReturnPath(candidate)) return null;
+  return isAppPath(pathnameOf(candidate)) ? candidate : null;
+}
+
+function readAppNext(search: string, isAppPath: IsAppPath): string | null {
+  return appReturnPath(new URLSearchParams(search).get(NEXT_QUERY_PARAM), isAppPath);
+}
+
+export function postLoginPath(options: {
+  readonly search: string;
+  readonly landingPath?: string | undefined;
+  readonly isAppPath: IsAppPath;
+  readonly fallbackPath: string;
+}): string {
+  const next = readAppNext(options.search, options.isAppPath);
+  if (next !== null) return next;
+  return appReturnPath(options.landingPath, options.isAppPath) ?? options.fallbackPath;
+}
+
+export function forgotPasswordHref(
+  forgotPasswordPath: string,
+  search: string,
+  isAppPath: IsAppPath,
+): string {
+  return appendReturnTo(forgotPasswordPath, readAppNext(search, isAppPath));
+}
+
+export type MarketingLoginPaths = {
+  readonly default: string;
+  /** Lowercase locale prefix ("de") to its login path. */
+  readonly byLocale?: Readonly<Record<string, string>>;
+};
+
+function trimTrailingSlashes(pathname: string): string {
+  return pathname.replace(/\/+$/, "");
+}
+
+export function isMarketingLoginPath(pathname: string, localePaths: MarketingLoginPaths): boolean {
+  const target = trimTrailingSlashes(pathname);
+  const loginPaths = [localePaths.default, ...Object.values(localePaths.byLocale ?? {})];
+  return loginPaths.some((loginPath) => trimTrailingSlashes(loginPath) === target);
+}
+
+function loginPathFor(locale: string, localePaths: MarketingLoginPaths): string {
+  const prefix = (locale.toLowerCase().split(/[-_]/)[0] ?? "").trim();
+  const byLocale = localePaths.byLocale;
+  if (byLocale !== undefined && Object.hasOwn(byLocale, prefix)) {
+    return byLocale[prefix] ?? localePaths.default;
+  }
+  return localePaths.default;
+}
+
+// Marketing site to app login: keeps the user's place as `next` when it is an app path, and never
+// bounces from a login page back to itself.
+export function marketingLoginUrl(options: {
+  readonly localePaths: MarketingLoginPaths;
+  readonly isAppPath: IsAppPath;
+}): LoginUrlBuilder {
+  const { localePaths, isAppPath } = options;
+  return (locale, returnPath) => {
+    const hashAt = returnPath.indexOf("#");
+    const pathAndQuery = hashAt === -1 ? returnPath : returnPath.slice(0, hashAt);
+    const pathname = pathnameOf(pathAndQuery);
+    if (isMarketingLoginPath(pathname, localePaths)) return pathname;
+    const loginPath = loginPathFor(locale, localePaths);
+    const next = appReturnPath(pathAndQuery, isAppPath);
+    return next === null
+      ? loginPath
+      : `${loginPath}?${NEXT_QUERY_PARAM}=${encodeURIComponent(next)}`;
+  };
+}