@cosmicdrift/kumiko-framework 0.319.0 → 0.321.0

package/src/api/__tests__/post-auth-landing.test.ts

@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  isSafeLandingPath,
+  type PostAuthLandingArgs,
+  type PostAuthLandingResolver,
+  resolvePostAuthLandingPath,
+} from "../post-auth-landing";
+
+describe("isSafeLandingPath", () => {
+  const rejected: unknown[] = [
+    "//evil.com",
+    "/\\evil.com",
+    "/a\\b",
+    "/\t/evil.com",
+    "/\n/evil.com",
+    " /a",
+    "https://evil.com",
+    "javascript:alert(1)",
+    "",
+    "a/b",
+    42,
+    undefined,
+    "/.//evil.com",
+  ];
+  for (const candidate of rejected) {
+    test(`rejects ${JSON.stringify(candidate)}`, () => {
+      expect(isSafeLandingPath(candidate)).toBe(false);
+    });
+  }
+
+  const accepted: string[] = ["/", "/a/profile", "/a/vehicle-detail/abc?x=1#h"];
+  for (const candidate of accepted) {
+    test(`accepts ${JSON.stringify(candidate)}`, () => {
+      expect(isSafeLandingPath(candidate)).toBe(true);
+    });
+  }
+});
+
+describe("resolvePostAuthLandingPath", () => {
+  const args: PostAuthLandingArgs = { flow: "login", roles: ["User"], tenantId: "t1" };
+  const realWarn = console.warn;
+
+  beforeEach(() => {
+    console.warn = mock(() => {});
+  });
+  afterEach(() => {
+    console.warn = realWarn;
+  });
+
+  test("undefined resolver → undefined, no warning", () => {
+    expect(resolvePostAuthLandingPath(undefined, args)).toBeUndefined();
+    expect(console.warn).not.toHaveBeenCalled();
+  });
+
+  test("resolver returns undefined → undefined, no warning", () => {
+    expect(resolvePostAuthLandingPath(() => undefined, args)).toBeUndefined();
+    expect(console.warn).not.toHaveBeenCalled();
+  });
+
+  test("throwing resolver → undefined, logs a warning without the thrown value", () => {
+    const result = resolvePostAuthLandingPath(() => {
+      throw new Error("boom");
+    }, args);
+    expect(result).toBeUndefined();
+    expect(console.warn).toHaveBeenCalledTimes(1);
+  });
+
+  test("throwing resolver → warning carries the error class, not the consumer message", () => {
+    resolvePostAuthLandingPath(() => {
+      throw new Error("secret-token-123");
+    }, args);
+    const loggedArgs = (console.warn as unknown as { mock: { calls: unknown[][] } }).mock.calls[0];
+    expect(JSON.stringify(loggedArgs)).not.toContain("secret-token-123");
+  });
+
+  test("rejecting async resolver → undefined, async warning, rejection observed", async () => {
+    // @cast-boundary test — simulates a JS consumer bypassing the sync signature
+    const asyncResolver = (async () => {
+      throw new Error("boom");
+    }) as unknown as PostAuthLandingResolver;
+    expect(resolvePostAuthLandingPath(asyncResolver, args)).toBeUndefined();
+    await Promise.resolve();
+    expect(console.warn).toHaveBeenCalledTimes(1);
+    const loggedArgs = (console.warn as unknown as { mock: { calls: unknown[][] } }).mock.calls[0];
+    expect(String(loggedArgs?.[0])).toContain("async resolver not supported");
+  });
+
+  test("unsafe path → undefined, warns without leaking the candidate", () => {
+    const result = resolvePostAuthLandingPath(() => "//evil.com", args);
+    expect(result).toBeUndefined();
+    expect(console.warn).toHaveBeenCalledTimes(1);
+    const loggedArgs = (console.warn as unknown as { mock: { calls: unknown[][] } }).mock.calls[0];
+    expect(JSON.stringify(loggedArgs)).not.toContain("evil.com");
+  });
+
+  test("valid path → the path, no warning", () => {
+    expect(resolvePostAuthLandingPath(() => "/a/profile", args)).toBe("/a/profile");
+    expect(console.warn).not.toHaveBeenCalled();
+  });
+});

package/src/api/__tests__/request-id-middleware.test.ts

@@ -71,7 +71,11 @@ describe("requestIdMiddleware — signal propagation", () => {
   });
 });
 describe("requestIdMiddleware — ip + userAgent capture (603/2)", () => {
-  test("populates ip from x-forwarded-for and userAgent from the User-Agent header", async () => {
+  // Default trustedProxyHops=0 trusts no proxy header at all — the resolver
+  // ignores x-forwarded-for outright (a
+  // spoofable, client-controlled header) and falls back to the socket
+  // address, "unknown" here since app.request() has none.
+  test("default (trustedProxyHops=0): ignores x-forwarded-for, falls back to unknown", async () => {
     let captured: { ip: string | undefined; userAgent: string | undefined } = {
       ip: undefined,
       userAgent: undefined,
@@ -96,7 +100,36 @@ describe("requestIdMiddleware — ip + userAgent capture (603/2)", () => {
     );
 
     expect(res.status).toBe(200);
-    expect(captured.ip).toBe("203.0.113.7");
+    expect(captured.ip).toBe("unknown");
+    expect(captured.userAgent).toBe("Mozilla/5.0 (probe-test)");
+  });
+
+  test("trustedProxyHops=1: populates ip from the last (trusted-proxy-appended) x-forwarded-for entry", async () => {
+    let captured: { ip: string | undefined; userAgent: string | undefined } = {
+      ip: undefined,
+      userAgent: undefined,
+    };
+
+    const app = new Hono();
+    app.use("/probe", requestIdMiddleware({ trustedProxyHops: 1 }));
+    app.get("/probe", (c) => {
+      const ctx = requestContext.get();
+      captured = { ip: ctx?.ip, userAgent: ctx?.userAgent };
+      return c.text("ok");
+    });
+
+    const res = await app.request(
+      new Request("http://test.local/probe", {
+        method: "GET",
+        headers: {
+          "x-forwarded-for": "203.0.113.7, 10.0.0.1",
+          "user-agent": "Mozilla/5.0 (probe-test)",
+        },
+      }),
+    );
+
+    expect(res.status).toBe(200);
+    expect(captured.ip).toBe("10.0.0.1");
     expect(captured.userAgent).toBe("Mozilla/5.0 (probe-test)");
   });
 

package/src/api/__tests__/schema-route.integration.test.ts

@@ -0,0 +1,157 @@
+// kumiko-framework#3314: GET /api/schema is the only way a client gets the
+// AppSchema now — HTML never carries it. anonymousAccess is deliberately
+// wired here (like http-route-entry.integration.test.ts): without it, a
+// wrongly-mounted route (jwtGuard skipping instead of rejecting) would
+// still 401 on a missing token and mask the "anonymous user reaches the
+// schema" bug the anonymous-401 test exists to catch.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createEntity, defineFeature } from "../../engine";
+import type { TenantId } from "../../engine/types/identifiers";
+import { setupTestStack, type TestStack, TestUsers } from "../../stack";
+import { Routes } from "../api-constants";
+import { AUTH_COOKIE_NAME } from "../auth-middleware";
+
+const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
+const SCHEMA_PATH = `/api${Routes.schema}`;
+
+const schemaRouteFeature = defineFeature("schema-route-fixture", (r) => {
+  r.entity("widget", createEntity({ fields: {} }));
+  r.screen({
+    id: "widget-list",
+    type: "entityList",
+    entity: "widget",
+    columns: ["id"],
+  });
+  r.screen({
+    id: "admin-only",
+    type: "entityList",
+    entity: "widget",
+    columns: ["id"],
+    access: { roles: ["Admin"] },
+  });
+  r.nav({ id: "widget-list", label: "Widgets", screen: "widget-list" });
+  r.nav({ id: "admin-only", label: "Admin Only", screen: "admin-only" });
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [schemaRouteFeature],
+    anonymousAccess: { defaultTenantId: TENANT_ID },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("GET /api/schema", () => {
+  test("anonymous → 401, no schema leaked", async () => {
+    const res = await stack.app.request(SCHEMA_PATH);
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("unauthenticated");
+  });
+
+  test("signed-in user via Bearer token → 200 with the registry's schema, strong ETag, private/no-cache", async () => {
+    const token = await stack.jwt.sign(TestUsers.user);
+    const res = await stack.app.request(SCHEMA_PATH, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("application/json");
+    const cacheControl = res.headers.get("cache-control") ?? "";
+    expect(cacheControl).toContain("private");
+    expect(cacheControl).toContain("no-cache");
+    expect(cacheControl).not.toContain("public");
+    expect(cacheControl).not.toContain("no-store");
+    const etag = res.headers.get("etag");
+    expect(etag).toMatch(/^"/);
+    expect(etag).not.toMatch(/^W\//);
+    const body = (await res.json()) as { features: Array<{ featureName: string }> };
+    expect(body.features.length).toBeGreaterThan(0);
+    expect(body.features.some((f) => f.featureName === "schema-route-fixture")).toBe(true);
+  });
+
+  test("signed-in user via kumiko_auth cookie → 200", async () => {
+    const token = await stack.jwt.sign(TestUsers.user);
+    const res = await stack.app.request(SCHEMA_PATH, {
+      headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}` },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { features: Array<{ featureName: string }> };
+    expect(body.features.length).toBeGreaterThan(0);
+  });
+
+  test("matching If-None-Match → 304 with no body, ETag kept", async () => {
+    const token = await stack.jwt.sign(TestUsers.user);
+    const first = await stack.app.request(SCHEMA_PATH, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const etag = first.headers.get("etag");
+    expect(etag).toBeTruthy();
+
+    const second = await stack.app.request(SCHEMA_PATH, {
+      headers: { Authorization: `Bearer ${token}`, "If-None-Match": etag ?? "" },
+    });
+    expect(second.status).toBe(304);
+    expect(await second.text()).toBe("");
+    expect(second.headers.get("etag")).toBe(etag);
+  });
+
+  test("anonymous with a valid If-None-Match → still 401, not 304", async () => {
+    const token = await stack.jwt.sign(TestUsers.user);
+    const authed = await stack.app.request(SCHEMA_PATH, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const etag = authed.headers.get("etag");
+    expect(etag).toBeTruthy();
+
+    const res = await stack.app.request(SCHEMA_PATH, {
+      headers: { "If-None-Match": etag ?? "" },
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test("role projection: Admin sees the role-gated screen, User does not", async () => {
+    const adminToken = await stack.jwt.sign(TestUsers.admin);
+    const adminRes = await stack.app.request(SCHEMA_PATH, {
+      headers: { Authorization: `Bearer ${adminToken}` },
+    });
+    const adminBody = (await adminRes.json()) as {
+      features: Array<{ featureName: string; screens: Array<{ id: string }> }>;
+    };
+    const adminFixture = adminBody.features.find((f) => f.featureName === "schema-route-fixture");
+    expect(adminFixture?.screens.map((s) => s.id).sort()).toEqual(["admin-only", "widget-list"]);
+
+    const userToken = await stack.jwt.sign(TestUsers.user);
+    const userRes = await stack.app.request(SCHEMA_PATH, {
+      headers: { Authorization: `Bearer ${userToken}` },
+    });
+    const userBody = (await userRes.json()) as {
+      features: Array<{ featureName: string; screens: Array<{ id: string }> }>;
+    };
+    const userFixture = userBody.features.find((f) => f.featureName === "schema-route-fixture");
+    expect(userFixture?.screens.map((s) => s.id)).toEqual(["widget-list"]);
+
+    // Different bodies must carry different (strong) ETags.
+    expect(adminRes.headers.get("etag")).not.toBe(userRes.headers.get("etag"));
+  });
+
+  test("role projection: one role's ETag sent by a different role never 304s", async () => {
+    const adminToken = await stack.jwt.sign(TestUsers.admin);
+    const adminRes = await stack.app.request(SCHEMA_PATH, {
+      headers: { Authorization: `Bearer ${adminToken}` },
+    });
+    const adminEtag = adminRes.headers.get("etag");
+    expect(adminEtag).toBeTruthy();
+
+    const userToken = await stack.jwt.sign(TestUsers.user);
+    const userRes = await stack.app.request(SCHEMA_PATH, {
+      headers: { Authorization: `Bearer ${userToken}`, "If-None-Match": adminEtag ?? "" },
+    });
+    expect(userRes.status).toBe(200);
+  });
+});

package/src/api/api-constants.ts

@@ -36,6 +36,7 @@ export const Routes = {
   authInviteSignupComplete: "/auth/invite-signup-complete",
   authInviteInfo: "/auth/invite-info",
   files: "/files",
+  schema: "/schema",
 } as const;
 
 // Routes that must be reachable WITHOUT a valid JWT.
@@ -87,6 +88,7 @@ export const NON_PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
   // invite-accept requires a JWT (Branch 1, see PUBLIC_API_PATHS above).
   `/api${Routes.authInviteAccept}`,
   `/api${Routes.files}`,
+  `/api${Routes.schema}`,
 ]);
 
 // Opt-out from the default request-body-size cap (registerBodyLimit applies

package/src/api/auth-routes.ts

@@ -26,7 +26,14 @@ import {
   getUser,
   type TokenVerifier,
 } from "./auth-middleware";
+import {
+  type ClientIpResolver,
+  clientIpSourceFromHonoContext,
+  createClientIpResolver,
+} from "./client-ip";
 import type { JwtHelper } from "./jwt";
+import type { PostAuthLandingArgs, PostAuthLandingResolver } from "./post-auth-landing";
+import { resolvePostAuthLandingPath } from "./post-auth-landing";
 import { generateToken } from "./tokens";
 
 // Resolves the Secure cookie flag. Locked off in dev/test so Playwright
@@ -441,15 +448,26 @@ export type AuthRoutesConfig = {
   // `x-forwarded-for` (e.g. nginx `$proxy_add_x_forwarded_for`). Used to
   // derive the client IP for every auth rate-limiter (login, mfa-verify,
   // preauth-enable-start, preauth-confirm) and for requestMeta's session
-  // IP — kumiko-framework#1539. Default 0 = legacy behavior, trust the
-  // first XFF entry (or x-real-ip) unconditionally; spoofable by design,
-  // kept as the default so unconfigured deployments don't regress into a
-  // shared "unknown" bucket (mfa-verify/preauth-confirm key on bare IP, no
-  // email composite — collapsing everyone into one bucket is a DoS worse
-  // than the spoofing hole). Set this to your real proxy hop count (1 for
-  // a single ingress/reverse-proxy, 2 for edge-LB + ingress, etc.) to close
-  // the hole; see clientIpOf's doc comment for the extraction algorithm.
+  // IP via the shared resolveClientIp (see client-ip.ts for the extraction
+  // algorithm). Deprecated in favor of the
+  // top-level `trustedProxyHops` on ServerOptions/RunProdAppOptions/
+  // RunDevAppOptions, which wins when both are set — kept as a fallback so
+  // existing consumers that only set this don't regress. Default 0 = trust
+  // no proxy header, only the socket address (or "unknown") counts. Set
+  // this to your real proxy hop count (1 for a single ingress/reverse-
+  // proxy, 2 for edge-LB + ingress, etc.) when deployed behind a proxy.
   trustedProxyHops?: number;
+  // Server-computed post-auth redirect, consulted at login, mfa-verify,
+  // mfa-preauth-confirm, signup-confirm, and all three invite-accept branches.
+  // Result lands in the response as `landingPath`; an invalid path or a
+  // throwing resolver just omits the field (see post-auth-landing.ts).
+  postAuthLanding?: PostAuthLandingResolver;
+  // Shared resolver instance from buildServer — takes precedence over
+  // `trustedProxyHops` so the whole server shares exactly one resolver
+  // instance (and warn-once flag) instead of building a private one here.
+  // Only standalone callers of createAuthRoutes
+  // (no buildServer) should rely on `trustedProxyHops` instead.
+  resolver?: ClientIpResolver;
 };
 
 export type PasswordResetConfig = {
@@ -504,69 +522,6 @@ export type SignupConfig = {
   confirmHandler: string;
 };
 
-// Derives the caller IP from proxy headers, single source for the
-// rate-limiter keys below and requestMeta. kumiko-framework#1523/#1522/#1539:
-// `x-forwarded-for` is attacker-controlled unless we know how many trusted
-// proxy hops sit between the client and this process — `trustedProxyHops`
-// (AuthRoutesConfig) is that count.
-//
-//   hops === 0 (default): legacy behavior — trust the first XFF entry (or
-//   x-real-ip) at face value. Kept as the default so unconfigured
-//   deployments don't regress: collapsing everyone into a single "unknown"
-//   bucket would turn mfa-verify/preauth-confirm's pure-IP-keyed limiter
-//   into a one-request-locks-out-everyone DoS, which is worse than the
-//   spoofing hole this issue is about. Apps behind a proxy MUST set this to
-//   close the hole — see AuthRoutesConfig.trustedProxyHops.
-//
-//   hops >= 1: each trusted proxy appends (not overwrites) its peer address
-//   to XFF (e.g. nginx `$proxy_add_x_forwarded_for`), so the last `hops`
-//   entries are proxy-supplied and everything before them — including the
-//   real client — sits at `entries[length - hops]`. Anything the client
-//   itself prepended lands further left and is ignored. If the header has
-//   fewer entries than `hops`, the proxy chain is shorter than configured
-//   (misconfiguration or a bypassed hop) — fall back to x-real-ip when present,
-//   else "unknown". x-real-ip has no hop-count semantics (so it isn't used for
-//   hop math), but a shared "unknown" bucket is worse than trusting the
-//   proxy-set header when XFF is absent (common nginx X-Real-IP-only setups).
-//
-// Callers that need a hard boundary regardless of this config
-// (preauth-enable-start) additionally key on something the caller can't
-// freely choose (see preauthTokenKeyOf below).
-let warnedUnknownClientIp = false;
-function clientIpOf(
-  c: { req: { header(name: string): string | undefined } },
-  trustedProxyHops = 0,
-): string {
-  if (trustedProxyHops <= 0) {
-    return (
-      c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
-      c.req.header("x-real-ip") ??
-      "unknown"
-    );
-  }
-  const entries = (c.req.header("x-forwarded-for") ?? "")
-    .split(",")
-    .map((entry) => entry.trim())
-    .filter((entry) => entry.length > 0);
-  if (entries.length < trustedProxyHops) {
-    // nginx often sets only X-Real-IP (no XFF). Prefer that over a shared
-    // "unknown" rate-limit bucket (fw#1555) — hop-count math still doesn't
-    // apply to X-Real-IP, but a shared bucket is worse than trusting the
-    // proxy-set header when the XFF chain is shorter than configured.
-    const realIp = c.req.header("x-real-ip")?.trim();
-    if (realIp) return realIp;
-    if (!warnedUnknownClientIp) {
-      warnedUnknownClientIp = true;
-      console.warn(
-        "[kumiko] trustedProxyHops>=1 but XFF chain too short and no x-real-ip — " +
-          'all such clients share the "unknown" rate-limit bucket. Check proxy headers.',
-      );
-    }
-    return "unknown";
-  }
-  return entries[entries.length - trustedProxyHops] ?? "unknown";
-}
-
 // Second rate-limit axis for preauth-enable-start: unlike the IP, a
 // preauthSetupToken isn't freely choosable by the attacker (it's minted by
 // login.write.ts), so hashing it into a bucket key still caps the replay
@@ -575,15 +530,12 @@ function preauthTokenKeyOf(token: string): string {
   return `preauth-token:${createHash("sha256").update(token).digest("hex")}`;
 }
 
-// Extract `ip` and `user-agent` for the sessionCreator.
-// Hono's `c.req.header(...)` returns undefined for missing headers; we coerce
-// them to "unknown" rather than throwing because auth-routes are a public
-// surface and we don't want header-sniffing bugs to break login.
-function requestMeta(
-  c: { req: { header(name: string): string | undefined } },
-  trustedProxyHops = 0,
-): SessionMetadata {
-  const ip = clientIpOf(c, trustedProxyHops);
+// Extract `ip` and `user-agent` for the sessionCreator. Client-IP resolution
+// (trustedProxyHops-aware) is the shared resolveClientIp (see client-ip.ts)
+// — createAuthRoutes builds one resolver instance below and
+// closes over it here and in getClientIp.
+function requestMeta(c: Context, resolver: ClientIpResolver): SessionMetadata {
+  const ip = resolver.resolve(clientIpSourceFromHonoContext(c));
   const userAgent = c.req.header("user-agent") ?? "unknown";
   return { ip, userAgent };
 }
@@ -714,20 +666,14 @@ export function createAuthRoutes(
   const cookieSameSite = config.cookieSameSite ?? "lax";
   const cookieDomain = config.cookieDomain;
   // Single hop-count-aware IP getter for every rate-limit call site below —
-  // see AuthRoutesConfig.trustedProxyHops / clientIpOf's doc comment. Fail
-  // loud on a non-finite/negative value rather than letting it silently
-  // reach clientIpOf, where NaN/negative behaves like "chain too short"
-  // and collapses every request into the shared "unknown" bucket.
-  if (
-    config.trustedProxyHops !== undefined &&
-    (!Number.isInteger(config.trustedProxyHops) || config.trustedProxyHops < 0)
-  ) {
-    throw new Error(
-      `createAuthRoutes: trustedProxyHops must be a non-negative integer, got ${config.trustedProxyHops}.`,
-    );
-  }
-  const trustedProxyHops = config.trustedProxyHops ?? 0;
-  const getClientIp = (c: Context): string => clientIpOf(c, trustedProxyHops);
+  // see AuthRoutesConfig.trustedProxyHops and client-ip.ts's resolveClientIp
+  // doc comment. createClientIpResolver fails loud on a non-finite/negative
+  // value rather than letting it silently collapse every request into the
+  // shared "unknown" bucket.
+  const clientIpResolver =
+    config.resolver ?? createClientIpResolver(config.trustedProxyHops ?? 0, "createAuthRoutes");
+  const getClientIp = (c: Context): string =>
+    clientIpResolver.resolve(clientIpSourceFromHonoContext(c));
 
   // Shared tail of every route that ends a request logged-in: create the
   // session record (if wired), sign the JWT, set the auth+csrf cookies. Was
@@ -737,7 +683,7 @@ export function createAuthRoutes(
   async function mintSessionAndRespond(c: Context, session: SessionUser): Promise<string> {
     let sessionForJwt = session;
     if (config.sessionCreator) {
-      const sid = await config.sessionCreator(session, requestMeta(c, trustedProxyHops));
+      const sid = await config.sessionCreator(session, requestMeta(c, clientIpResolver));
       sessionForJwt = { ...session, sid };
     }
     const token = await jwt.sign(sessionForJwt);
@@ -752,6 +698,13 @@ export function createAuthRoutes(
     return token;
   }
 
+  // Spreadable landingPath fragment for the 7 auth-response call sites below
+  // — absent (not `landingPath: undefined`) when unwired/invalid/throwing.
+  function landingPathFragment(args: PostAuthLandingArgs): { readonly landingPath?: string } {
+    const landingPath = resolvePostAuthLandingPath(config.postAuthLanding, args);
+    return landingPath === undefined ? {} : { landingPath };
+  }
+
   // POST /auth/login — public endpoint (bypasses auth middleware via PUBLIC_API_PATHS).
   // The configured login handler authenticates and returns a SessionUser;
   // the route signs the JWT and hands it back to the client.
@@ -836,6 +789,11 @@ export function createAuthRoutes(
       // that references it can be handed out, otherwise a fast client could
       // arrive at an auth-middleware check before the insert commits.
       const token = await mintSessionAndRespond(c, data.session);
+      const landingPath = landingPathFragment({
+        flow: "login",
+        roles: data.session.roles,
+        tenantId: data.session.tenantId,
+      });
 
       if (rateLimiter) {
         await rateLimiter.reset(rateLimitKey);
@@ -845,6 +803,7 @@ export function createAuthRoutes(
         isSuccess: true,
         token,
         user: { id: data.session.id, tenantId: data.session.tenantId, roles: data.session.roles },
+        ...landingPath,
       });
     });
   }
@@ -907,6 +866,11 @@ export function createAuthRoutes(
       const data = result.data as { kind: "mfa-verify-success"; session: SessionUser };
 
       const token = await mintSessionAndRespond(c, data.session);
+      const landingPath = landingPathFragment({
+        flow: "login",
+        roles: data.session.roles,
+        tenantId: data.session.tenantId,
+      });
 
       if (rateLimiter) {
         await rateLimiter.reset(clientIp);
@@ -916,6 +880,7 @@ export function createAuthRoutes(
         isSuccess: true,
         token,
         user: { id: data.session.id, tenantId: data.session.tenantId, roles: data.session.roles },
+        ...landingPath,
       });
     });
   }
@@ -1054,6 +1019,11 @@ export function createAuthRoutes(
       const data = result.data as { kind: "mfa-preauth-confirm-success"; session: SessionUser };
 
       const token = await mintSessionAndRespond(c, data.session);
+      const landingPath = landingPathFragment({
+        flow: "login",
+        roles: data.session.roles,
+        tenantId: data.session.tenantId,
+      });
 
       if (rateLimiter) {
         await rateLimiter.reset(clientIp);
@@ -1063,6 +1033,7 @@ export function createAuthRoutes(
         isSuccess: true,
         token,
         user: { id: data.session.id, tenantId: data.session.tenantId, roles: data.session.roles },
+        ...landingPath,
       });
     });
   }
@@ -1169,6 +1140,13 @@ export function createAuthRoutes(
 
       // Session creation + JWT sign + cookies — see mintSessionAndRespond.
       const token = await mintSessionAndRespond(c, data.session);
+      const landingPath = landingPathFragment({
+        flow: "signup",
+        roles: data.session.roles,
+        tenantId: data.session.tenantId,
+        tenantKey: data.tenantKey,
+        ...(data.handover !== undefined && { handover: data.handover }),
+      });
 
       return c.json({
         isSuccess: true,
@@ -1189,6 +1167,7 @@ export function createAuthRoutes(
         // absent, not null, so a client that doesn't know the field sees
         // nothing unusual.
         ...(data.handover !== undefined && { handover: data.handover }),
+        ...landingPath,
       });
     });
   }
@@ -1222,11 +1201,17 @@ export function createAuthRoutes(
         role: string;
         alreadyMember: boolean;
       };
+      const landingPath = landingPathFragment({
+        flow: "invite",
+        roles: [data.role],
+        tenantId: data.tenantId,
+      });
       return c.json({
         isSuccess: true,
         tenantId: data.tenantId,
         role: data.role,
         alreadyMember: data.alreadyMember,
+        ...landingPath,
       });
     });
 
@@ -1269,6 +1254,11 @@ export function createAuthRoutes(
       }
 
       const token = await mintSessionAndRespond(c, data.session);
+      const landingPath = landingPathFragment({
+        flow: "invite",
+        roles: data.session.roles,
+        tenantId: data.tenantId,
+      });
       return c.json({
         isSuccess: true,
         token,
@@ -1279,6 +1269,7 @@ export function createAuthRoutes(
         },
         tenantId: data.tenantId,
         role: data.role,
+        ...landingPath,
       });
     });
 
@@ -1306,6 +1297,11 @@ export function createAuthRoutes(
         role: string;
       }; // @cast-boundary engine-payload
       const token = await mintSessionAndRespond(c, data.session);
+      const landingPath = landingPathFragment({
+        flow: "invite",
+        roles: data.session.roles,
+        tenantId: data.tenantId,
+      });
       return c.json({
         isSuccess: true,
         token,
@@ -1316,6 +1312,7 @@ export function createAuthRoutes(
         },
         tenantId: data.tenantId,
         role: data.role,
+        ...landingPath,
       });
     });
   }