@cosmicdrift/kumiko-framework 0.319.0 → 0.320.0

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,
       });
     });
   }

package/src/api/client-ip.ts

@@ -0,0 +1,91 @@
+import type { Context } from "hono";
+
+// Single source for client-IP extraction, shared by every IP-keyed rate
+// limit and audit field. Deriving the caller IP independently per call site
+// makes it easy for one to silently trust the first XFF entry, which is
+// attacker-controlled unless the exact number of trusted reverse proxies is
+// known.
+//
+// Algorithm for `trustedProxyHops`:
+//   0 (default): don't trust any proxy header — only the socket address
+//   counts. A spoofed XFF is ignored outright.
+//   >=1: each trusted proxy hop APPENDS (not overwrites) its peer address to
+//   XFF (e.g. nginx `$proxy_add_x_forwarded_for`), so the real client sits
+//   at `entries[length - hops]`. Anything a client itself prepended lands
+//   further left and is ignored. A chain shorter than `hops` falls back to
+//   `x-real-ip` (no hop-count semantics of its own), then the socket address.
+// A bucket is never skipped: without any usable value the fallback is a
+// fixed "unknown" string, which collapses affected callers into one shared
+// bucket rather than letting them bypass the limit entirely.
+export const UNKNOWN_CLIENT_IP = "unknown";
+
+export type ClientIpHeaderSource = {
+  readonly header: (name: string) => string | undefined;
+  readonly socketAddress?: string;
+};
+
+export type ClientIpResolver = {
+  readonly resolve: (source: ClientIpHeaderSource) => string;
+};
+
+// The socket address rides in as Hono's `Env` (2nd `app.fetch` arg, read
+// back via `c.env`) as a bare string, never the raw Bun `Server` — a
+// `Server.requestIP()` only resolves for the exact Request instance Bun
+// created, and a cloned/rebuilt Request (tryHonoFirst's req.clone(), etc.)
+// would silently return null. The address is extracted once at the
+// outermost Bun.serve fetch handler and threaded down as a plain value.
+export function extractSocketAddress(env: unknown): string | undefined {
+  return typeof env === "string" && env.length > 0 ? env : undefined;
+}
+
+export function assertValidTrustedProxyHops(value: number | undefined, context: string): void {
+  if (value !== undefined && (!Number.isInteger(value) || value < 0)) {
+    throw new Error(`${context}: trustedProxyHops must be a non-negative integer, got ${value}.`);
+  }
+}
+
+// Instance-scoped, NOT a module singleton: the warn-once flag must reset
+// per server boot (and per test), otherwise the first test to trigger it
+// consumes the warning for the whole process and later tests can't observe
+// it.
+export function createClientIpResolver(
+  trustedProxyHops: number,
+  context = "resolveClientIp",
+): ClientIpResolver {
+  assertValidTrustedProxyHops(trustedProxyHops, context);
+  let warnedUnexpectedForwardedFor = false;
+
+  function resolve(source: ClientIpHeaderSource): string {
+    const xff = source.header("x-forwarded-for");
+    if (trustedProxyHops === 0) {
+      if (xff !== undefined && xff.trim().length > 0 && !warnedUnexpectedForwardedFor) {
+        warnedUnexpectedForwardedFor = true;
+        console.warn(
+          "[kumiko] received X-Forwarded-For but trustedProxyHops is 0 (no proxy trusted) — " +
+            "ignoring it. Running behind a proxy? Set trustedProxyHops, otherwise all clients " +
+            "share one rate-limit bucket.",
+        );
+      }
+      return source.socketAddress ?? UNKNOWN_CLIENT_IP;
+    }
+    const entries = (xff ?? "")
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter((entry) => entry.length > 0);
+    if (entries.length >= trustedProxyHops) {
+      return entries[entries.length - trustedProxyHops] ?? UNKNOWN_CLIENT_IP;
+    }
+    const realIp = source.header("x-real-ip")?.trim();
+    if (realIp) return realIp;
+    return source.socketAddress ?? UNKNOWN_CLIENT_IP;
+  }
+
+  return { resolve };
+}
+
+export function clientIpSourceFromHonoContext(c: Context): ClientIpHeaderSource {
+  return {
+    header: (name) => c.req.header(name),
+    socketAddress: extractSocketAddress(c.env),
+  };
+}

package/src/api/index.ts

@@ -28,6 +28,14 @@ export {
   createInMemoryLoginRateLimiter,
   createRedisLoginRateLimiter,
 } from "./auth-routes";
+export type { ClientIpHeaderSource, ClientIpResolver } from "./client-ip";
+export {
+  assertValidTrustedProxyHops,
+  clientIpSourceFromHonoContext,
+  createClientIpResolver,
+  extractSocketAddress,
+  UNKNOWN_CLIENT_IP,
+} from "./client-ip";
 export type {
   AnonymousExtraRoute,
   AnonymousExtraRouteDeps,
@@ -57,6 +65,12 @@ export {
 export type { JwtHelper, JwtKeyring, JwtPayload } from "./jwt";
 export { createJwtHelper, loadJwtSecretOrKeyring } from "./jwt";
 export { patAllows, qnMatches } from "./pat-scope";
+export type {
+  PostAuthLandingArgs,
+  PostAuthLandingFlow,
+  PostAuthLandingResolver,
+} from "./post-auth-landing";
+export { isSafeLandingPath } from "./post-auth-landing";
 export type { RedisSseBroker, RedisSseBrokerOptions } from "./redis-sse-broker";
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker } from "./redis-sse-broker";
 export { type RequestContextData, requestContext } from "./request-context";
@@ -64,6 +78,7 @@ export {
   buildRequestContextDataFromRequest,
   requestIdMiddleware,
 } from "./request-id-middleware";
+export { DEFAULT_MAX_REQUEST_BYTES } from "./route-registrars";
 export { createApiRoutes } from "./routes";
 export type { KumikoServer, ServerOptions } from "./server";
 export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite } from "./server";