@cosmicdrift/kumiko-framework 0.319.0 → 0.321.0

package/src/api/client-ip.ts

@@ -0,0 +1,118 @@
+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}.`);
+  }
+}
+
+export const TRUSTED_PROXY_HOPS_ENV = "KUMIKO_TRUSTED_PROXY_HOPS";
+
+// Fail loud on a garbage env value rather than silently coercing to NaN:
+// a resolver built from NaN treats it like "always short chain" and returns
+// "unknown" for every request, which collapses an IP-keyed rate limiter
+// into one shared bucket for the whole deployment — a self-inflicted DoS,
+// worse than staying on the default. Digits-only (not parseInt) —
+// parseInt("0x10")/("1e3")/("2x") would silently coerce instead of failing.
+export function parseTrustedProxyHopsEnv(
+  raw: string | undefined,
+  context: string,
+): number | undefined {
+  if (raw === undefined) return undefined;
+  if (!/^\d+$/.test(raw)) {
+    throw new Error(
+      `${context}: ${TRUSTED_PROXY_HOPS_ENV} must be a non-negative integer, got "${raw}".`,
+    );
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(
+      `${context}: ${TRUSTED_PROXY_HOPS_ENV} must be a non-negative integer, got "${raw}".`,
+    );
+  }
+  return parsed;
+}
+
+// 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/extra-route.ts

@@ -32,6 +32,9 @@ export type AnonymousExtraRouteDeps = {
    *  user, same request-resolved tenant (never overridable), only under
    *  "/api/" (the only path that populates a session user). */
   readonly write: (type: string, payload: unknown) => Promise<WriteResult>;
+  /** Resolved by the server's single trustedProxyHops-aware resolver —
+   *  never read X-Forwarded-For yourself. */
+  readonly clientIp: string;
 };
 
 export type AnonymousExtraRoute = {

package/src/api/index.ts

@@ -28,6 +28,16 @@ export {
   createInMemoryLoginRateLimiter,
   createRedisLoginRateLimiter,
 } from "./auth-routes";
+export type { ClientIpHeaderSource, ClientIpResolver } from "./client-ip";
+export {
+  assertValidTrustedProxyHops,
+  clientIpSourceFromHonoContext,
+  createClientIpResolver,
+  extractSocketAddress,
+  parseTrustedProxyHopsEnv,
+  TRUSTED_PROXY_HOPS_ENV,
+  UNKNOWN_CLIENT_IP,
+} from "./client-ip";
 export type {
   AnonymousExtraRoute,
   AnonymousExtraRouteDeps,
@@ -57,6 +67,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 +80,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";

package/src/api/pat-route-guard.ts

@@ -0,0 +1,51 @@
+import type { Context, MiddlewareHandler, Next } from "hono";
+import { AccessDeniedError } from "../errors";
+import { Routes } from "./api-constants";
+import { getUser } from "./auth-middleware";
+
+// Personal Access Tokens are minted for headless dispatcher access only.
+// Every other /api/* surface (SSE, files, auth/*, feature httpRoutes,
+// entry:"user" extraRoutes) must stay off-limits to a PAT regardless of its
+// granted scopes — those routes never call assertPatAllowed, so without this
+// guard a PAT with any scope (even an empty one) authenticates everywhere a
+// cookie/JWT session would.
+const PAT_ALLOWED_API_PATHS: ReadonlySet<string> = new Set([
+  `/api${Routes.write}`,
+  `/api${Routes.batch}`,
+  `/api${Routes.query}`,
+  `/api${Routes.command}`,
+  `/api${Routes.stream}`,
+]);
+
+function isDispatcherPath(path: string): boolean {
+  return PAT_ALLOWED_API_PATHS.has(path);
+}
+
+// Must run after an auth guard has resolved getUser(c) — same wiring point
+// as buildPatRateLimitGuard. Cookie/JWT users (user.pat undefined) pass
+// through untouched.
+export function patRouteGuard(): MiddlewareHandler {
+  return async (c: Context, next: Next) => {
+    const user = getUser(c);
+    if (user?.pat && !isDispatcherPath(c.req.path)) {
+      const denied = new AccessDeniedError({
+        message:
+          "personal access tokens are only valid for the dispatcher API (write, batch, query, command, stream)",
+        details: { reason: "pat_dispatcher_routes_only" },
+      });
+      return c.json(
+        {
+          error: {
+            code: denied.code,
+            httpStatus: denied.httpStatus,
+            message: denied.message,
+            i18nKey: denied.i18nKey,
+            details: denied.details,
+          },
+        },
+        403,
+      );
+    }
+    return next();
+  };
+}

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

@@ -0,0 +1,105 @@
+// Server-computed post-auth redirect target. AuthRoutesConfig.postAuthLanding
+// lets an app decide, in ONE place, where a user lands after login/signup/
+// invite — instead of every frontend screen re-deriving it from roles/
+// tenantId via loggedInHref. The result travels in the JSON response
+// (`landingPath`) and is validated here before it ever reaches the wire: an
+// app-supplied resolver is untrusted input from the framework's perspective,
+// and a bad value would otherwise become a same-response open redirect.
+
+import { createFallbackLogger } from "../logging";
+
+export type PostAuthLandingFlow = "login" | "signup" | "invite";
+
+export type PostAuthLandingArgs = {
+  readonly flow: PostAuthLandingFlow;
+  readonly roles: readonly string[];
+  readonly tenantId: string;
+  // signup only.
+  readonly tenantKey?: string;
+  // signup only, present when signup-confirm claimed a bound handover grant.
+  readonly handover?: { readonly entityType: string; readonly id: string };
+};
+
+export type PostAuthLandingResolver = (args: PostAuthLandingArgs) => string | undefined;
+
+function hasControlOrDelCharacter(candidate: string): boolean {
+  for (let i = 0; i < candidate.length; i++) {
+    const code = candidate.charCodeAt(i);
+    if (code <= 0x1f || code === 0x7f) return true;
+  }
+  return false;
+}
+
+// Root-relative-only allowlist, stricter than the framework's existing
+// billing isRootRelativePath: rejects protocol-relative ("//host") and
+// backslash-based ("/\host") paths a browser would still resolve to a
+// different origin, and control chars/whitespace a URL parser silently
+// strips (so "/\t/evil.com" would otherwise normalize to "//evil.com" past
+// the leading-slash check). The new URL(...) parse is a backstop for
+// anything the explicit checks above missed.
+export function isSafeLandingPath(candidate: unknown): candidate is string {
+  if (typeof candidate !== "string" || candidate.length === 0) return false;
+  if (!candidate.startsWith("/")) return false;
+  const second = candidate[1];
+  if (second === "/" || second === "\\") return false;
+  if (candidate.includes("\\")) return false;
+  if (hasControlOrDelCharacter(candidate)) return false;
+  if (/\s/.test(candidate)) return false;
+  try {
+    const parsed = new URL(candidate, "https://landing.invalid");
+    if (parsed.origin !== "https://landing.invalid") return false;
+    // "/.//evil.com" clears every check above (no leading "//", no
+    // backslash) but normalizes to pathname "//evil.com" — still same-
+    // origin on first navigation, but protocol-relative if a caller ever
+    // re-resolves the bare pathname as a fresh href.
+    return !parsed.pathname.startsWith("//");
+  } catch {
+    return false;
+  }
+}
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "then" in value &&
+    typeof value.then === "function"
+  );
+}
+
+const landingLog = createFallbackLogger("auth");
+
+export function resolvePostAuthLandingPath(
+  resolver: PostAuthLandingResolver | undefined,
+  args: PostAuthLandingArgs,
+): string | undefined {
+  if (!resolver) return undefined;
+  let candidate: unknown;
+  try {
+    candidate = resolver(args);
+  } catch (error) {
+    // Consumer error messages can carry PII or secrets; log only the error class.
+    landingLog.warn("postAuthLanding threw — landingPath omitted", {
+      flow: args.flow,
+      errorName: error instanceof Error ? error.name : typeof error,
+    });
+    return undefined;
+  }
+  if (isThenable(candidate)) {
+    // A JS consumer (or a cast) can bypass the sync signature; an unobserved
+    // rejection would terminate the Bun process on every login.
+    Promise.resolve(candidate).catch(() => undefined);
+    landingLog.warn("postAuthLanding async resolver not supported — landingPath omitted", {
+      flow: args.flow,
+    });
+    return undefined;
+  }
+  if (candidate === undefined) return undefined;
+  if (!isSafeLandingPath(candidate)) {
+    landingLog.warn("postAuthLanding returned an unsafe path — landingPath omitted", {
+      flow: args.flow,
+    });
+    return undefined;
+  }
+  return candidate;
+}

package/src/api/request-context.ts

@@ -29,8 +29,10 @@ export type RequestContextData = {
   readonly causationId?: string;
   readonly signal?: AbortSignal;
   // Client IP for per-IP rate limiting (L1, L2, L3 with per: "ip*").
-  // Populated by requestIdMiddleware from x-forwarded-for or the
-  // socket address. Undefined for non-HTTP entry points (jobs, MSP).
+  // Populated by requestIdMiddleware via the shared trustedProxyHops-aware
+  // resolver (see api/client-ip.ts) — never skipped
+  // for an HTTP request, falls back to "unknown" rather than leaving this
+  // undefined. Undefined only for non-HTTP entry points (jobs, MSP).
   readonly ip?: string;
   // Raw User-Agent header — audit trails (download tokens, GDPR export
   // access) want it alongside `ip`. Undefined for non-HTTP entry points.

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

@@ -1,8 +1,16 @@
 import type { Context, Next } from "hono";
 import { resolveHeaderLocale } from "../i18n/request-locale";
 import { LOCALE_HEADER_NAME } from "./api-constants";
+import { type ClientIpResolver, createClientIpResolver, extractSocketAddress } from "./client-ip";
 import { type RequestContextData, requestContext } from "./request-context";
 
+// Fallback for the few call-sites that build a RequestContextData without a
+// caller-configured resolver (e.g. an internal system-query mount reached
+// before requestIdMiddleware ran). trustedProxyHops 0 matches the framework
+// default; callers that care about the real hop count pass their own
+// resolver instead — see requestIdMiddleware(options).
+const FALLBACK_CLIENT_IP_RESOLVER = createClientIpResolver(0, "requestIdMiddleware");
+
 const REQUEST_ID_HEADER = "X-Request-ID";
 const CORRELATION_ID_HEADER = "X-Correlation-ID";
 
@@ -34,7 +42,10 @@ function header(req: Request, name: string): string | undefined {
  * Hono's router entirely — can still populate the same AsyncLocalStorage
  * record via `requestContext.run(...)`.
  */
-export function buildRequestContextDataFromRequest(req: Request): RequestContextData {
+export function buildRequestContextDataFromRequest(
+  req: Request,
+  options?: { readonly resolver?: ClientIpResolver; readonly socketAddress?: string },
+): RequestContextData {
   const requestId = sanitizeClientId(header(req, REQUEST_ID_HEADER)) ?? requestContext.generateId();
   const correlationId = sanitizeClientId(header(req, CORRELATION_ID_HEADER)) ?? requestId;
 
@@ -42,14 +53,15 @@ export function buildRequestContextDataFromRequest(req: Request): RequestContext
   // back-press, tab close). We propagate it through requestContext so
   // framework internals can honour cancellation at long-running checkpoints.
   const signal = req.signal;
-  // Client IP for per-IP rate limiting. Trust `x-forwarded-for` when
-  // present (proxy/CDN) — first hop is the originating client. Adapter-
-  // specific socket-address fallback (bun, node) is not standardized
-  // in Hono; deployments behind a proxy should always set xff. Without
-  // either we leave `ip` undefined and skip ip-bucketed checks rather
-  // than fabricate one.
-  const xff = header(req, "x-forwarded-for");
-  const ip = xff?.split(",")[0]?.trim();
+  // Client IP for per-IP rate limiting — resolved via the shared
+  // trustedProxyHops-aware resolver. Always set for
+  // an HTTP request; falls back to "unknown" rather than skipping the
+  // ip-bucket (see createClientIpResolver).
+  const resolver = options?.resolver ?? FALLBACK_CLIENT_IP_RESOLVER;
+  const ip = resolver.resolve({
+    header: (name) => header(req, name),
+    socketAddress: options?.socketAddress,
+  });
   const userAgent = header(req, "user-agent");
   // Runs before auth-middleware, so this reaches public routes too (e.g.
   // signup-request) — that's the whole point: the active UI locale must
@@ -64,7 +76,7 @@ export function buildRequestContextDataFromRequest(req: Request): RequestContext
     correlationId,
     startedAt: performance.now(),
     ...(signal ? { signal } : {}),
-    ...(ip && ip.length > 0 ? { ip } : {}),
+    ip,
     ...(userAgent !== undefined ? { userAgent } : {}),
     ...(locale !== undefined ? { locale } : {}),
   };
@@ -76,7 +88,10 @@ export function buildRequestContextDataFromRequest(req: Request): RequestContext
  * export because most call-sites (server.ts's httpRoute→systemQuery mount,
  * `requestIdMiddleware` below) already hold a Hono `Context`.
  */
-export function buildRequestContextData(c: Context): RequestContextData {
+export function buildRequestContextData(
+  c: Context,
+  resolver?: ClientIpResolver,
+): RequestContextData {
   // Older Hono / adapter combos may leave c.req.raw unset even though it's
   // typed as Request — degrade to a bare id pair (no signal/ip/ua/locale)
   // instead of letting req.headers.get() throw on every request.
@@ -84,7 +99,10 @@ export function buildRequestContextData(c: Context): RequestContextData {
     const requestId = requestContext.generateId();
     return { requestId, correlationId: requestId, startedAt: performance.now() };
   }
-  return buildRequestContextDataFromRequest(c.req.raw);
+  return buildRequestContextDataFromRequest(c.req.raw, {
+    resolver,
+    socketAddress: extractSocketAddress(c.env),
+  });
 }
 
 /**
@@ -96,9 +114,21 @@ export function buildRequestContextData(c: Context): RequestContextData {
  * `x-correlation-id` — clients that don't care about cross-service tracing
  * still get sensible single-request correlation for free.
  */
-export function requestIdMiddleware() {
+export function requestIdMiddleware(options?: {
+  // Shared resolver instance — pass buildServer's single clientIpResolver
+  // here so the whole server shares one warn-once flag.
+  // Takes precedence over `trustedProxyHops`, which only exists for
+  // standalone callers (no buildServer).
+  readonly resolver?: ClientIpResolver;
+  readonly trustedProxyHops?: number;
+}) {
+  // Created once per middleware mount (not per request) so the warn-once
+  // flag in the resolver actually fires only once per server boot.
+  const resolver =
+    options?.resolver ??
+    createClientIpResolver(options?.trustedProxyHops ?? 0, "requestIdMiddleware");
   return async (c: Context, next: Next) => {
-    const data = buildRequestContextData(c);
+    const data = buildRequestContextData(c, resolver);
     c.header(REQUEST_ID_HEADER, data.requestId);
     c.header(CORRELATION_ID_HEADER, data.correlationId);
     c.set("requestId", data.requestId);