fix: secure authentication request identity

Replace Better Auth's default trust of a caller-controlled X-Forwarded-For
with a platform-owned client-address resolution boundary: direct mode (the
safe default) trusts only the real socket peer, and an explicit trusted-proxy
mode requires a header name, a concrete trusted-proxy list, and only honors a
forwarded chain from an actual trusted peer. This closes a rate-limit bypass
where rotating a spoofed header let a caller choose a fresh bucket on every
request. Public sign-up is also disabled by default and requires an explicit
typed opt-in, using Better Auth's own disableSignUp gate so no email-existence
leak or second signup path is introduced.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

apps/api/src/app.ts

@@ -119,7 +119,18 @@ export function createApiApp(options: CreateApiAppOptions): Hono {
 
   app.on(["POST", "GET"], "/api/auth/*", async (c) => {
     try {
-      return await runtime.handleAuthRequest(c.req.raw);
+      const response = await runtime.handleAuthRequest(c.req.raw);
+      // Every Better Auth response — including a session cookie — must never be cached by an
+      // intermediary; constructing a fresh Response (rather than relying on `c.header()`, which
+      // only affects `c.res`) guarantees this regardless of how the handler produced its result,
+      // and never reads or buffers the body.
+      const headers = new Headers(response.headers);
+      headers.set("Cache-Control", "no-store");
+      return new Response(response.body, {
+        headers,
+        status: response.status,
+        statusText: response.statusText,
+      });
     } catch (error) {
       return sanitizedErrorResponse(c, error, 500);
     }

apps/api/src/client-address.ts

@@ -0,0 +1,66 @@
+import { type ClientAddressResolver, TRUSTED_CLIENT_ADDRESS_HEADER } from "@ekklesia/core/identity";
+import type { Http2Bindings, HttpBindings } from "@hono/node-server";
+
+type NodeServerBindings = HttpBindings | Http2Bindings;
+
+export {
+  type ClientAddressConfig,
+  ClientAddressConfigError,
+  type ClientAddressConfigErrorCode,
+  type ClientAddressConfigInput,
+  type ClientAddressFailureReason,
+  type ClientAddressMode,
+  type ClientAddressResolution,
+  type ClientAddressResolver,
+  createClientAddressConfig,
+  createClientAddressResolver,
+  type DirectClientAddressConfig,
+  findInvalidTrustedProxies,
+  normalizeClientAddress,
+  type TrustedProxyClientAddressConfig,
+} from "@ekklesia/core/identity";
+
+/** A fixed, generic diagnostic — never the peer address, forwarded header content, request path, or
+ * any other request detail — logged only when client-address resolution fails closed. */
+export const CLIENT_ADDRESS_UNRESOLVED_LOG_MESSAGE =
+  "[client-address] A request's caller address could not be resolved safely; rejecting with 503.";
+
+function sanitizedClientAddressUnresolvedResponse(): Response {
+  return new Response(JSON.stringify({ code: "CLIENT_ADDRESS_UNRESOLVED" }), {
+    headers: { "cache-control": "no-store", "content-type": "application/json" },
+    status: 503,
+  });
+}
+
+/**
+ * Wraps a `@hono/node-server` fetch callback at the exact Node/API transport boundary — the one
+ * place in this repository below `apps/api` that reads the raw Node `IncomingMessage` — with
+ * Core's framework-agnostic client-address resolution policy (`@ekklesia/core/identity`). Resolves
+ * the caller's trusted address from the real socket peer (`env.incoming.socket.remoteAddress`)
+ * before the wrapped callback — and therefore Better Auth's own rate limiter — ever sees the
+ * request, then overwrites (never merely appends) any externally supplied copy of
+ * `TRUSTED_CLIENT_ADDRESS_HEADER` with that resolved value. A caller can therefore never choose its
+ * own resolved address, whether by spoofing a forwarded header or by sending the internal header
+ * directly. Resolution failure never reaches the wrapped callback at all — no Better Auth logic, no
+ * Core mutation, and no module handler ever runs for a request whose caller address could not be
+ * resolved safely.
+ */
+export function wrapFetchWithClientAddress(
+  fetchCallback: (request: Request, env: NodeServerBindings) => Response | Promise<Response>,
+  resolver: ClientAddressResolver,
+): (request: Request, env: NodeServerBindings) => Promise<Response> {
+  return async (request: Request, env: NodeServerBindings): Promise<Response> => {
+    const resolution = resolver.resolve({
+      headers: request.headers,
+      peerAddress: env.incoming.socket.remoteAddress,
+    });
+    if (!resolution.ok) {
+      console.error(CLIENT_ADDRESS_UNRESOLVED_LOG_MESSAGE);
+      return sanitizedClientAddressUnresolvedResponse();
+    }
+    const headers = new Headers(request.headers);
+    headers.set(TRUSTED_CLIENT_ADDRESS_HEADER, resolution.address);
+    const sanitizedRequest = new Request(request, { headers });
+    return fetchCallback(sanitizedRequest, env);
+  };
+}

apps/api/src/config.ts

@@ -4,6 +4,11 @@ import {
   type IdentityConfig,
   type IdentityConfigInput,
 } from "@ekklesia/core/identity";
+import {
+  type ClientAddressConfig,
+  type ClientAddressConfigInput,
+  createClientAddressConfig,
+} from "./client-address.js";
 
 export type ApiConfigErrorCode =
   | "DATABASE_URL_INVALID"
@@ -37,6 +42,7 @@ const defaultHost = "127.0.0.1";
 const defaultPort = 3000;
 
 export interface ApiRuntimeConfig {
+  readonly clientAddress: ClientAddressConfig;
   readonly databaseUrl: string;
   readonly host: string;
   readonly identity: IdentityConfig;
@@ -44,6 +50,9 @@ export interface ApiRuntimeConfig {
 }
 
 export interface ApiRuntimeConfigInput {
+  /** Optional. Defaults to direct mode (trusts only the actual immediate socket peer) — no proxy
+   * trust unless explicitly configured. See `./client-address.js`. */
+  readonly clientAddress?: ClientAddressConfigInput;
   readonly databaseUrl?: unknown;
   readonly host?: unknown;
   readonly identity: IdentityConfigInput;
@@ -112,6 +121,7 @@ export function createApiRuntimeConfig(
     input.identity,
     options.environment === undefined ? {} : { environment: options.environment },
   );
+  const clientAddress = createClientAddressConfig(input.clientAddress);
 
-  return Object.freeze({ databaseUrl, host, identity, port });
+  return Object.freeze({ clientAddress, databaseUrl, host, identity, port });
 }

apps/api/src/server.ts

@@ -14,6 +14,12 @@ import {
 import { serve, type ServerType } from "@hono/node-server";
 import type { Hono } from "hono";
 import { createApiApp } from "./app.js";
+import {
+  type ClientAddressConfigInput,
+  type ClientAddressResolver,
+  createClientAddressResolver,
+  wrapFetchWithClientAddress,
+} from "./client-address.js";
 import { type ApiRuntimeConfig, createApiRuntimeConfig } from "./config.js";
 import { type ApiDatabaseHandle, createApiDatabase } from "./database.js";
 import { prepareStartupModuleInventory } from "./platform-permissions.js";
@@ -61,15 +67,29 @@ async function safeStopModuleRuntime(moduleRuntime: StartedModuleRuntime): Promi
   }
 }
 
-function bindServer(app: Hono, host: string, port: number): Promise<ServerType> {
+/**
+ * Binds the Node HTTP server. `wrapFetchWithClientAddress` resolves and sanitizes the caller's
+ * address from the real socket peer before any route (including Better Auth's own rate limiter)
+ * ever sees the request — see `./client-address.js` for the platform-owned client-address
+ * resolution policy this depends on.
+ */
+function bindServer(
+  app: Hono,
+  host: string,
+  port: number,
+  clientAddressResolver: ClientAddressResolver,
+): Promise<ServerType> {
   return new Promise((resolve, reject) => {
     let settled = false;
-    const server = serve({ fetch: app.fetch, hostname: host, port }, () => {
-      if (!settled) {
-        settled = true;
-        resolve(server);
-      }
-    });
+    const server = serve(
+      { fetch: wrapFetchWithClientAddress(app.fetch, clientAddressResolver), hostname: host, port },
+      () => {
+        if (!settled) {
+          settled = true;
+          resolve(server);
+        }
+      },
+    );
     server.once("error", () => {
       if (!settled) {
         settled = true;
@@ -178,9 +198,11 @@ export async function startApi(
     throw error;
   }
 
+  const clientAddressResolver = createClientAddressResolver(config.clientAddress);
+
   let server: ServerType;
   try {
-    server = await bindServer(app, config.host, config.port);
+    server = await bindServer(app, config.host, config.port, clientAddressResolver);
   } catch (error) {
     await safeStopModuleRuntime(moduleRuntime);
     await safeCloseDatabase(databaseHandle);
@@ -250,6 +272,25 @@ export function installShutdownSignalHandlers(
   process.on("SIGTERM", handleSignal);
 }
 
+function readClientAddressInputFromEnvironment(): ClientAddressConfigInput | undefined {
+  const mode = process.env.EKKLESIA_CLIENT_ADDRESS_MODE;
+  if (mode === undefined) {
+    // Omitted entirely: `createClientAddressConfig` defaults to direct mode. Reading `header`/
+    // `trustedProxies` only when `mode` is actually set keeps an operator from accidentally
+    // half-configuring proxy mode by setting only one of the three variables.
+    return undefined;
+  }
+  const trustedProxiesValue = process.env.EKKLESIA_CLIENT_ADDRESS_TRUSTED_PROXIES;
+  return {
+    header: process.env.EKKLESIA_CLIENT_ADDRESS_HEADER,
+    mode,
+    trustedProxies: trustedProxiesValue
+      ?.split(",")
+      .map((entry) => entry.trim())
+      .filter((entry) => entry.length > 0),
+  };
+}
+
 function readConfigFromEnvironment(): {
   readonly input: Parameters<typeof createApiRuntimeConfig>[0];
   readonly environment: "development" | "production";
@@ -259,14 +300,17 @@ function readConfigFromEnvironment(): {
     ?.split(",")
     .map((origin) => origin.trim())
     .filter((origin) => origin.length > 0);
+  const clientAddress = readClientAddressInputFromEnvironment();
 
   return {
     environment: process.env.NODE_ENV === "development" ? "development" : "production",
     input: {
+      ...(clientAddress === undefined ? {} : { clientAddress }),
       databaseUrl: process.env.DATABASE_URL,
       host: process.env.EKKLESIA_API_HOST,
       identity: {
         baseUrl: process.env.EKKLESIA_IDENTITY_BASE_URL,
+        publicSignupEnabled: process.env.EKKLESIA_PUBLIC_SIGNUP_ENABLED,
         secret: process.env.EKKLESIA_IDENTITY_SECRET,
         trustedOrigins,
       },