@cosmicdrift/kumiko-framework 0.319.0 → 0.320.0

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

package/src/api/server.ts

@@ -2,7 +2,9 @@ import { Hono, type MiddlewareHandler } from "hono";
 import { ROLES } from "../auth/roles";
 import type { DbConnection, PgClient } from "../db/connection";
 import { createDerivativesContext } from "../derivatives/derivatives-context";
+import { buildAppSchema } from "../engine/build-app-schema";
 import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names";
+import { projectAppSchemaForRoles } from "../engine/project-app-schema-for-roles";
 import { runsInLane } from "../engine/run-in";
 import { ANONYMOUS_ROLE, createAnonymousUser, createSystemUser } from "../engine/system-user";
 import {
@@ -11,12 +13,13 @@ import {
   isFileField,
   type Registry,
   type RunIn,
+  type SessionUser,
   type TenantId,
   type WriteResult,
 } from "../engine/types";
 import { createFileContext } from "../files/file-handle";
 import type { FileRoutesOptions } from "../files/file-routes";
-import { createFileRoutes } from "../files/file-routes";
+import { createFileRoutes, readFilesRouteOptions } from "../files/file-routes";
 import { makeFileProviderResolver } from "../files/provider-resolver";
 import type { Lifecycle } from "../lifecycle";
 import {
@@ -52,8 +55,9 @@ import {
 } from "../rate-limit";
 import { deriveSearchAdapterConfig } from "../search/derive-search-adapter-config";
 import type { SearchAdapter } from "../search/types";
+import type { AppSchema } from "../ui-types/app-schema";
 import { assertUnreachable, generateId } from "../utils";
-import { NO_ROUTE_MATCH_HEADER_NAME, PUBLIC_API_PATHS } from "./api-constants";
+import { NO_ROUTE_MATCH_HEADER_NAME, PUBLIC_API_PATHS, Routes } from "./api-constants";
 import {
   type AnonymousAccessResolved,
   authMiddleware,
@@ -61,6 +65,12 @@ import {
   type TenantLifecycleStatusResolver,
 } from "./auth-middleware";
 import { type AuthRoutesConfig, createAuthRoutes, type LoginRateLimiter } from "./auth-routes";
+import {
+  assertValidTrustedProxyHops,
+  type ClientIpResolver,
+  clientIpSourceFromHonoContext,
+  createClientIpResolver,
+} from "./client-ip";
 import { csrfMiddleware } from "./csrf-middleware";
 import {
   type ExtraRouteDefinition,
@@ -69,9 +79,11 @@ import {
   ExtraRouteRejection,
   type SystemDispatchArgs,
 } from "./extra-route";
+import { computeStrongEtag, etagMatches } from "./http-cache";
 import { createJwtHelper, type JwtHelper, type JwtKeyring } from "./jwt";
 import { observabilityMiddleware } from "./observability-middleware";
 import { assertOriginGuardConfig, normalizeOrigin, originMiddleware } from "./origin-middleware";
+import { patRouteGuard } from "./pat-route-guard";
 import { piiCiphertextResponseGuard } from "./pii-leak-guard";
 import { createDefaultSseBroker, type RedisSseBroker } from "./redis-sse-broker";
 import { requestContext } from "./request-context";
@@ -102,6 +114,12 @@ export type ServerOptions = {
   eventDedup?: EventDedup;
   sseBroker?: SseBroker;
   auth?: AuthRoutesConfig;
+  // Number of trusted reverse-proxy hops for client-IP resolution — feeds
+  // requestIdMiddleware's `ip`, the L1/L2
+  // rate-limit middleware below, and createAuthRoutes. Wins over the
+  // deprecated `auth.trustedProxyHops`. Default 0 = trust no proxy header,
+  // only the socket address (or "unknown") counts — see client-ip.ts.
+  trustedProxyHops?: number;
   // No `files` option: file-storage is wired by mounting `file-foundation` +
   // a `file-provider-*` feature. Upload routes, ctx.files and the GDPR jobs
   // resolve the provider per-tenant through that single source (issue #608).
@@ -294,6 +312,17 @@ export function withFileProviderResolver(registry: Registry, context: AppContext
 }
 
 export function buildServer(options: ServerOptions): KumikoServer {
+  // Single effective hop-count for every IP-derived rate-limit + requestMeta
+  // below — the top-level option wins over the deprecated
+  // `auth.trustedProxyHops` fallback.
+  const trustedProxyHops = options.trustedProxyHops ?? options.auth?.trustedProxyHops ?? 0;
+  assertValidTrustedProxyHops(trustedProxyHops, "buildServer");
+  // Exactly ONE resolver for the whole server — the warn-once flag must fire
+  // once per boot, not once per consumer (requestIdMiddleware, L1, L2,
+  // auth-routes each sharing this same instance rather than building a
+  // private one).
+  const clientIpResolver = createClientIpResolver(trustedProxyHops, "buildServer");
+
   // File-storage is resolved per-tenant through file-foundation: a mounted
   // `file-provider-*` plugin (inmemory/s3/s3-env) is the single source for
   // uploads, ctx.files and the GDPR jobs.
@@ -668,7 +697,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
     registerMetricsRoute(app, observability.meter, options.metrics);
   }
 
-  app.use("/api/*", requestIdMiddleware());
+  app.use("/api/*", requestIdMiddleware({ resolver: clientIpResolver }));
 
   // Cap JSON bodies before rate-limit/auth/observability even run. Header-
   // check is O(1); oversized requests never allocate memory for a full body
@@ -691,12 +720,19 @@ export function buildServer(options: ServerOptions): KumikoServer {
     if (options.rateLimit?.global) {
       app.use(
         "/api/*",
-        globalIpRateLimit({ ...options.rateLimit.global, resolver: rateLimitResolver }),
+        globalIpRateLimit({
+          ...options.rateLimit.global,
+          resolver: rateLimitResolver,
+          clientIpResolver,
+        }),
       );
     }
     if (options.rateLimit?.auth) {
       const { path: l2Path = "/api/auth/*", ...l2Opts } = options.rateLimit.auth;
-      app.use(l2Path, authEndpointRateLimit({ ...l2Opts, resolver: rateLimitResolver }));
+      app.use(
+        l2Path,
+        authEndpointRateLimit({ ...l2Opts, resolver: rateLimitResolver, clientIpResolver }),
+      );
     }
   }
   // Observability span wraps everything that follows (auth, routes).
@@ -746,6 +782,15 @@ export function buildServer(options: ServerOptions): KumikoServer {
     return jwtGuard(c, next);
   });
 
+  // Fail-closed PAT scoping: a PAT-authenticated caller (user.pat set by
+  // jwtGuard's tokenVerifier above) may only reach the dispatcher routes —
+  // everywhere else on /api/* is off-limits regardless of granted scopes.
+  const patRouteGuardMiddleware = patRouteGuard();
+  app.use("/api/*", async (c, next) => {
+    if (PUBLIC_API_PATHS.has(c.req.path) || isExtraRoutePublicPath(c)) return next();
+    return patRouteGuardMiddleware(c, next);
+  });
+
   // Without anonymousAccess a missing token 401s instead of falling through as anonymous.
   const sessionOnlyGuard = authMiddleware(jwt, {
     ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
@@ -799,9 +844,10 @@ export function buildServer(options: ServerOptions): KumikoServer {
     return csrfGuard(c, next);
   });
 
-  // Same order as /api/* above: auth → PAT → origin → CSRF.
+  // Same order as /api/* above: auth → PAT route scope → PAT rate-limit → origin → CSRF.
   const sessionOnlyHttpRouteGuards: readonly MiddlewareHandler[] = [
     sessionOnlyGuard,
+    patRouteGuardMiddleware,
     ...(patRateLimitGuard ? [patRateLimitGuard] : []),
     ...(originGuard ? [originGuard] : []),
     csrfGuard,
@@ -822,7 +868,10 @@ export function buildServer(options: ServerOptions): KumikoServer {
           "need it to reject blocked principals).",
       );
     }
-    app.route("/api", createAuthRoutes(dispatcher, jwt, options.auth));
+    app.route(
+      "/api",
+      createAuthRoutes(dispatcher, jwt, { ...options.auth, resolver: clientIpResolver }),
+    );
   }
   app.route(
     "/api",
@@ -832,6 +881,47 @@ export function buildServer(options: ServerOptions): KumikoServer {
   );
   app.route("/api", createSseRoute(sseBroker));
 
+  // GET /api/schema — the only way a client obtains the AppSchema. Behind
+  // jwtGuard (NON_PUBLIC_API_PATHS), so anonymousAccess's synthesised user
+  // also gets rejected below — the schema never reaches an unauthenticated
+  // caller. The FULL schema is built lazily once — the registry is
+  // immutable for this server's lifetime, so it's the same on every
+  // request — then projected per caller-role-set (fw#3314: a role only
+  // sees the screens/navs/workspaces/content-collections it may reach,
+  // not the whole app's schema) and cached per role key. Tenant is
+  // deliberately NOT part of the key: the projection depends only on
+  // roles, and per-tenant caching would grow unboundedly across tenants
+  // that share the same role set.
+  let fullSchema: AppSchema | undefined;
+  const projectedSchemaCache = new Map<string, { readonly json: string; readonly etag: string }>();
+  app.get(`/api${Routes.schema}`, (c) => {
+    const user = getUser(c);
+    if (isMissingOrAnonymousUser(user)) {
+      return unauthenticatedResponse(c);
+    }
+    const roleKey = JSON.stringify([...new Set(user?.roles ?? [])].sort());
+    let cached = projectedSchemaCache.get(roleKey);
+    if (cached === undefined) {
+      if (fullSchema === undefined) {
+        fullSchema = buildAppSchema(options.registry, {
+          searchAdapterMissing: !options.context.searchAdapter,
+        });
+      }
+      const projected = projectAppSchemaForRoles(fullSchema, user?.roles ?? []);
+      const json = JSON.stringify(projected);
+      cached = { json, etag: computeStrongEtag(json) };
+      projectedSchemaCache.set(roleKey, cached);
+    }
+    const cacheHeaders = { "Cache-Control": "private, no-cache", ETag: cached.etag };
+    if (etagMatches(c.req.header("If-None-Match") ?? null, cached.etag)) {
+      return c.body(null, 304, cacheHeaders);
+    }
+    return c.body(cached.json, 200, {
+      "Content-Type": "application/json; charset=utf-8",
+      ...cacheHeaders,
+    });
+  });
+
   // Mount upload/download routes whenever a file provider is resolvable (a
   // file-provider plugin is mounted, or a resolver was injected). They resolve
   // the provider per-tenant through file-foundation — no `files` option; route
@@ -881,7 +971,8 @@ export function buildServer(options: ServerOptions): KumikoServer {
           // would leak it into the response. The forced tenant already
           // comes from bypassing the HTTP layer entirely; no elevated
           // role is needed or wanted on top of that.
-          systemQuery: makeSystemQuery(c, dispatcher),
+          systemQuery: makeSystemQuery(c, dispatcher, clientIpResolver),
+          clientIp: clientIpResolver.resolve(clientIpSourceFromHonoContext(c)),
         });
       mountHonoRoute(
         app,
@@ -941,6 +1032,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
         secrets: contextWithObservability.secrets,
         dispatchSystemWrite,
         dispatchSystemQuery,
+        clientIpResolver,
       });
       mountHonoRoute(app, route.method, route.path, honoHandler);
     }
@@ -1057,9 +1149,10 @@ function makeSystemQuery(
   // biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
   c: import("hono").Context<any, any>,
   dispatcher: Dispatcher,
+  clientIpResolver?: ClientIpResolver,
 ): (type: string, payload: unknown, tenantId: TenantId) => Promise<unknown> {
   return (type, payload, tenantId) =>
-    requestContext.run(requestContext.get() ?? buildRequestContextData(c), () =>
+    requestContext.run(requestContext.get() ?? buildRequestContextData(c, clientIpResolver), () =>
       dispatcher.query(type, payload, createAnonymousUser(tenantId)),
     );
 }
@@ -1103,6 +1196,27 @@ function makeAnonymousWrite(
   };
 }
 
+// Shared by entry:"user" extra routes and GET /api/schema — both require a
+// real, signed-in principal and reject the synthesised anonymousAccess user
+// (SessionUser.roles includes ANONYMOUS_ROLE) the same way.
+function isMissingOrAnonymousUser(user: SessionUser | undefined): boolean {
+  return !user || user.roles.includes(ANONYMOUS_ROLE);
+}
+
+function unauthenticatedResponse(c: import("hono").Context): Response {
+  return c.json(
+    {
+      error: {
+        code: "unauthenticated",
+        httpStatus: 401,
+        message: "this route requires a signed-in user",
+        i18nKey: "auth.errors.missingToken",
+      },
+    },
+    401,
+  );
+}
+
 function isKnownExtraRouteEntry(entry: unknown): entry is ExtraRouteEntry {
   return (
     entry === ExtraRouteEntries.anonymous ||
@@ -1146,6 +1260,7 @@ type ExtraRouteHonoHandlerDeps = {
   readonly secrets: import("../secrets").SecretsContext | undefined;
   readonly dispatchSystemWrite: (args: SystemDispatchArgs) => Promise<WriteResult>;
   readonly dispatchSystemQuery: (args: SystemDispatchArgs) => Promise<unknown>;
+  readonly clientIpResolver?: ClientIpResolver;
 };
 
 function buildExtraRouteHonoHandler(
@@ -1159,24 +1274,14 @@ function buildExtraRouteHonoHandler(
         route.handler(c, {
           app: shared.app,
           registry: shared.registry,
-          systemQuery: makeSystemQuery(c, shared.dispatcher),
+          systemQuery: makeSystemQuery(c, shared.dispatcher, shared.clientIpResolver),
           write: makeAnonymousWrite(c, shared.dispatcher),
         });
     case ExtraRouteEntries.user:
       return async (c) => {
         const user = getUser(c);
-        if (!user || user.roles.includes(ANONYMOUS_ROLE)) {
-          return c.json(
-            {
-              error: {
-                code: "unauthenticated",
-                httpStatus: 401,
-                message: "this route requires a signed-in user",
-                i18nKey: "auth.errors.missingToken",
-              },
-            },
-            401,
-          );
+        if (isMissingOrAnonymousUser(user)) {
+          return unauthenticatedResponse(c);
         }
         return route.handler(c, {
           app: shared.app,
@@ -1220,7 +1325,7 @@ function buildExtraRouteHonoHandler(
           app: shared.app,
           registry: shared.registry,
           secrets: shared.secrets,
-          systemQuery: makeSystemQuery(c, shared.dispatcher),
+          systemQuery: makeSystemQuery(c, shared.dispatcher, shared.clientIpResolver),
           dispatchSystemWrite: shared.dispatchSystemWrite,
           dispatchSystemQuery: shared.dispatchSystemQuery,
         });
@@ -1282,20 +1387,3 @@ function entitiesWithSearchableScreen(registry: Registry): readonly string[] {
   }
   return [...entities];
 }
-
-// Upload-route policy carried by createFilesFeature(opts?) — read from the
-// feature's exports so buildServer applies it without a parallel ServerOptions
-// surface. Absent feature / opts → defaults in createFileRoutes.
-function readFilesRouteOptions(
-  registry: Registry,
-): Pick<FileRoutesOptions, "accessGuard" | "privilegedRoles" | "maxUploadSize"> {
-  const exp = registry.features.get("files")?.exports;
-  if (exp && typeof exp === "object" && "routeOptions" in exp) {
-    const ro = (exp as { routeOptions?: unknown }).routeOptions;
-    if (ro && typeof ro === "object") {
-      // @cast-boundary feature-exports: engine-payload (unknown) → known shape
-      return ro as Pick<FileRoutesOptions, "accessGuard" | "privilegedRoles" | "maxUploadSize">;
-    }
-  }
-  return {};
-}