@podosoft/podokit 1.4.2 → 1.5.0

package/dist/deploy-compose-profile.js

@@ -357,6 +357,8 @@ function buildDefaultComposeProfile(projectName, options) {
             CORS_ORIGIN: `https://${host}`,
             ADDRESS_HEADER: "x-forwarded-for",
             XFF_DEPTH: "1",
+            TRUSTED_PROXY_HOPS: "1",
+            TRUSTED_PROXY_HEADER: "x-forwarded-for",
         },
         verification: {
             baseUrl: `https://${host}`,
@@ -418,8 +420,6 @@ function initializeComposeProfile(projectRoot, name, options) {
                 RATE_LIMIT_AUTH_TTL: "60",
                 RATE_LIMIT_AUTH_MAX: "20",
                 RATE_LIMIT_RUNTIME_MAX: "1000",
-                RATE_LIMIT_TRUSTED_PROXY_HOPS: "1",
-                RATE_LIMIT_PROXY_HEADER: "x-forwarded-for",
                 RATE_LIMIT_STORAGE_TIMEOUT_MS: "1000",
                 RATE_LIMIT_UNAVAILABLE_RETRY_AFTER: "1",
             }

package/dist/deploy-compose-render.js

@@ -37,6 +37,7 @@ function derivedRuntimeConfig(profile) {
     const result = {
         PORT: String(CONTAINER_PORT),
         BACKEND_INTERNAL_URL: `http://${serviceName(profile, "api")}:${CONTAINER_PORT}`,
+        ...(0, deploy_schema_1.idleTimeoutConfig)(profile.runtimeConfig),
         ...profile.runtimeConfig,
     };
     if (profile.dependencies.postgres.mode === "managed") {

package/dist/deploy-profile.js

@@ -397,6 +397,8 @@ function initializeDeploymentProfile(projectRoot, name, options) {
             CORS_ORIGIN: `https://${host}`,
             ADDRESS_HEADER: "x-forwarded-for",
             XFF_DEPTH: "1",
+            TRUSTED_PROXY_HOPS: "1",
+            TRUSTED_PROXY_HEADER: "x-forwarded-for",
             ...(usesAuth ? { BETTER_AUTH_URL: `https://${host}` } : {}),
             ...(modules.has("rate-limit")
                 ? {
@@ -406,8 +408,6 @@ function initializeDeploymentProfile(projectRoot, name, options) {
                     RATE_LIMIT_AUTH_TTL: "60",
                     RATE_LIMIT_AUTH_MAX: "20",
                     RATE_LIMIT_RUNTIME_MAX: "1000",
-                    RATE_LIMIT_TRUSTED_PROXY_HOPS: "1",
-                    RATE_LIMIT_PROXY_HEADER: "x-forwarded-for",
                     RATE_LIMIT_STORAGE_TIMEOUT_MS: "1000",
                     RATE_LIMIT_UNAVAILABLE_RETRY_AFTER: "1",
                 }

package/dist/deploy-render.js

@@ -6,6 +6,7 @@ const node_crypto_1 = require("node:crypto");
 const node_path_1 = require("node:path");
 const deploy_profile_1 = require("./deploy-profile");
 const api_paths_1 = require("./api-paths");
+const deploy_schema_1 = require("./deploy-schema");
 const lockfile_1 = require("./lockfile");
 const toolchain_1 = require("./toolchain");
 function quote(value) {
@@ -356,6 +357,7 @@ function derivedRuntimeConfig(profile) {
         BACKEND_INTERNAL_URL: `http://${profile.target.release}-api:3000`,
         PROTOCOL_HEADER: "x-forwarded-proto",
         HOST_HEADER: "x-forwarded-host",
+        ...(0, deploy_schema_1.idleTimeoutConfig)(profile.runtimeConfig),
         ...profile.runtimeConfig,
     };
     if (profile.dependencies.postgres.mode === "inCluster") {

package/dist/deploy-schema.d.ts

@@ -50,6 +50,13 @@ export declare function validateImage(value: string, field: string): void;
 export declare function validateImageRepository(value: string, field: string): void;
 export declare function parseReleaseProfile(release: Record<string, unknown>): ReleaseProfile;
 export declare function parseRuntimeConfig(runtimeConfig: Record<string, unknown>): Record<string, string>;
+/**
+ * The idle timeouts of the web server (CONNECTION_IDLE_TIMEOUT) and the API
+ * (API_IDLE_TIMEOUT), both run by Bun. Each is the profile's own value, or else
+ * the fewest seconds that keep a silent connection open past the /api proxy's
+ * BACKEND_PROXY_TIMEOUT_MS deadline: 35 for the default 30000 ms.
+ */
+export declare function idleTimeoutConfig(runtimeConfig: Record<string, string>): Record<string, string>;
 export declare function validateHttpsOrigin(value: string): void;
 export declare function parseVerification(verification: Record<string, unknown>): VerificationProfile;
 export declare function profileDirectory(projectRoot: string): string;

package/dist/deploy-schema.js

@@ -17,6 +17,7 @@ exports.validateImage = validateImage;
 exports.validateImageRepository = validateImageRepository;
 exports.parseReleaseProfile = parseReleaseProfile;
 exports.parseRuntimeConfig = parseRuntimeConfig;
+exports.idleTimeoutConfig = idleTimeoutConfig;
 exports.validateHttpsOrigin = validateHttpsOrigin;
 exports.parseVerification = parseVerification;
 exports.profileDirectory = profileDirectory;
@@ -35,6 +36,11 @@ exports.MANAGED_RUNTIME_CONFIG_KEYS = [
     "PROTOCOL_HEADER",
     "HOST_HEADER",
 ];
+/** Keys the generated API no longer reads; it refuses to start while they are set. */
+const RENAMED_RUNTIME_CONFIG_KEYS = {
+    RATE_LIMIT_TRUSTED_PROXY_HOPS: "TRUSTED_PROXY_HOPS",
+    RATE_LIMIT_PROXY_HEADER: "TRUSTED_PROXY_HEADER",
+};
 function containsUrlCredentials(value) {
     if (!value.includes("://"))
         return false;
@@ -183,6 +189,10 @@ function parseRuntimeConfig(runtimeConfig) {
         if (exports.MANAGED_RUNTIME_CONFIG_KEYS.includes(key)) {
             throw new Error(`Deployment runtimeConfig key "${key}" is managed by PodoKit.`);
         }
+        const renamed = RENAMED_RUNTIME_CONFIG_KEYS[key];
+        if (renamed) {
+            throw new Error(`Deployment runtimeConfig key "${key}" was renamed to "${renamed}".`);
+        }
         if (typeof entry !== "string") {
             throw new Error(`Deployment runtimeConfig value "${key}" must be a string.`);
         }
@@ -193,6 +203,36 @@ function parseRuntimeConfig(runtimeConfig) {
     }
     return parsed;
 }
+/** Bun closes silent connections on a 4-second tick, up to 4 seconds before their idle timeout. */
+const IDLE_TICK_SECONDS = 4;
+const MAX_IDLE_TIMEOUT_SECONDS = 255;
+const DEFAULT_BACKEND_PROXY_TIMEOUT_MS = 30_000;
+/**
+ * The idle timeouts of the web server (CONNECTION_IDLE_TIMEOUT) and the API
+ * (API_IDLE_TIMEOUT), both run by Bun. Each is the profile's own value, or else
+ * the fewest seconds that keep a silent connection open past the /api proxy's
+ * BACKEND_PROXY_TIMEOUT_MS deadline: 35 for the default 30000 ms.
+ */
+function idleTimeoutConfig(runtimeConfig) {
+    const proxyTimeout = runtimeConfig.BACKEND_PROXY_TIMEOUT_MS?.trim();
+    const proxyMs = proxyTimeout && /^\d+$/.test(proxyTimeout) ? Number(proxyTimeout) : DEFAULT_BACKEND_PROXY_TIMEOUT_MS;
+    const derived = Math.floor(proxyMs / 1000) + IDLE_TICK_SECONDS + 1;
+    const config = {};
+    for (const name of ["CONNECTION_IDLE_TIMEOUT", "API_IDLE_TIMEOUT"]) {
+        const configured = runtimeConfig[name];
+        if (configured !== undefined) {
+            config[name] = configured;
+        }
+        else if (derived > MAX_IDLE_TIMEOUT_SECONDS) {
+            throw new Error(`Deployment runtimeConfig BACKEND_PROXY_TIMEOUT_MS ${proxyMs} outlasts the longest idle timeout ` +
+                `(${MAX_IDLE_TIMEOUT_SECONDS} seconds); set ${name} to "0" to turn it off.`);
+        }
+        else {
+            config[name] = String(derived);
+        }
+    }
+    return config;
+}
 function validateHttpsOrigin(value) {
     let parsed;
     try {

package/dist/lockfile.js

@@ -55,9 +55,11 @@ exports.DEFAULT_OWNED_GLOBS = [
     "apps/web/src/lib/i18n/catalogs/app/**",
     // Owned Elysia extension slot — register application services and plugins here.
     "apps/api/src/app.extensions.ts",
-    // Owned additions to the managed /api proxy's header lists and body limits.
+    // Owned additions to the managed /api proxy's header lists, body limits, and
+    // response deadlines.
     "apps/web/src/lib/server/proxy-headers.ts",
     "apps/web/src/lib/server/body-limits.ts",
+    "apps/web/src/lib/server/proxy-timeouts.ts",
     // Owned fallback page SvelteKit serves when the root layout or a hook fails.
     "apps/web/src/error.html",
     // AI agent guidance — yours to customize; update never touches it.

package/dist/provider.d.ts

@@ -18,6 +18,7 @@ export interface ApplyProviderChangeOptions {
     modulesDir?: string;
     podokitVersion?: string;
 }
+/** The managed provider source; it must render byte for byte like the template's copy. */
 export declare function providerSource(providers: ProviderSelections): string;
 export declare function listProviders(projectRoot: string): ProviderListItem[];
 export declare function planProviderChange(projectRoot: string, capabilityInput: string, provider: string, modulesDir?: string): ProviderChangePlan;

package/dist/provider.js

@@ -27,15 +27,18 @@ function assertProvider(capability, provider) {
     }
     return capability;
 }
+/** The managed provider source; it must render byte for byte like the template's copy. */
 function providerSource(providers) {
     return `import type { ProviderSelections } from "@podosoft/podokit-runtime";\n\n` +
-        `export const PROVIDERS = {\n` +
+        `// Typed with every provider name, not the selected ones: the module of a\n` +
+        `// provider that stays installed after a switch compares against its own name.\n` +
+        `export const PROVIDERS: Readonly<ProviderSelections> = {\n` +
         `  database: "${providers.database}",\n` +
         `  cache: "${providers.cache}",\n` +
         `  "object-storage": "${providers["object-storage"]}",\n` +
         `  events: "${providers.events}",\n` +
         `  jobs: "${providers.jobs}",\n` +
-        `} as const satisfies ProviderSelections;\n`;
+        `};\n`;
 }
 function listProviders(projectRoot) {
     const manifest = requireManifest(projectRoot);

package/dist/templates/fullstack/AGENTS.md

@@ -49,15 +49,28 @@ Merge added module settings from `.env.example` into an existing `.env`.
   managed lists. Cap a route's request body in the app-owned
   `apps/web/src/lib/server/body-limits.ts` (`APP_BODY_LIMITS`, 413
   `PAYLOAD_TOO_LARGE`). `BODY_SIZE_LIMIT` is the ceiling for every web route, so
-  uploads larger than it must use a direct API path (`apiPaths`) instead.
+  uploads larger than it must use a direct API path (`apiPaths`) instead. Give a
+  route a longer, shorter, or no response deadline in the app-owned
+  `apps/web/src/lib/server/proxy-timeouts.ts` (`APP_PROXY_TIMEOUTS`, `null` for
+  none); never edit the managed deadline. Both lists take path prefixes with
+  `:name` parameters, such as `/api/hosts/:hostId/file-transfers`, and the most
+  specific prefix wins.
 - Server-side API calls (`serverApiClient`) give up after `BACKEND_TIMEOUT_MS`
   (2000), and the proxy answers 504 `BACKEND_TIMEOUT` when the API sends no
   response headers within `BACKEND_PROXY_TIMEOUT_MS` (30000). Once the API's
   `GET /health` stops answering too, calls throw `BackendUnavailableError` and the
   proxy answers 503 `BACKEND_UNAVAILABLE` at once until it answers again. Handle
-  any non-`ApiError` failure in a load function as a temporary outage. Raising
-  the API's `apiServerOptions.idleTimeout` needs a matching
-  `BACKEND_PROXY_TIMEOUT_MS`.
+  any non-`ApiError` failure in a load function as a temporary outage. The API
+  (`API_IDLE_TIMEOUT`) and the built web server (`CONNECTION_IDLE_TIMEOUT`) close
+  a connection that sends nothing for that many seconds (35 each): raise both
+  with any longer `BACKEND_PROXY_TIMEOUT_MS` or `APP_PROXY_TIMEOUTS` entry, more
+  than 4 above it, or set `0` when a route has no deadline. The proxy refuses to
+  load when `CONNECTION_IDLE_TIMEOUT` cannot cover a deadline.
+- Read a caller's address in the API with `clientAddressOf(request.headers)` from
+  `apps/api/src/core/client-address.ts`, never from `X-Forwarded-For` directly. The
+  API resolves it once per request from `TRUSTED_PROXY_HOPS` (1: the web proxy) and
+  `TRUSTED_PROXY_HEADER`; Better Auth sessions, audit entries, and rate limits use
+  the same address.
 - `GET /healthz` (`apps/web/src/routes/healthz/+server.ts`) is the web server's own
   health route for the Kubernetes probes, the Compose healthcheck, and the image
   `HEALTHCHECK`. Keep it free of API calls, so an API outage does not take the web
@@ -108,7 +121,7 @@ changes need an e2e/unit test.
 This project is managed by the `podo` CLI. Files have an ownership tier recorded
 in `.podokit/files.lock` — respect it:
 
-- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. Add application-owned services or module descriptors through `app.extensions.ts` instead of changing toolkit registrations. Set Bun server options (`maxRequestBodySize`, `idleTimeout`) with its `apiServerOptions` export rather than editing `main.ts`; `API_MAX_REQUEST_BODY_SIZE` sets the body limit when the export leaves it out.
+- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. Add application-owned services or module descriptors through `app.extensions.ts` instead of changing toolkit registrations. Set Bun server options (`maxRequestBodySize`, `idleTimeout`) with its `apiServerOptions` export rather than editing `main.ts`; `API_MAX_REQUEST_BODY_SIZE` and `API_IDLE_TIMEOUT` apply when the export leaves them out.
 - **assembled** (e.g. `apps/api/src/app.ts`, `auth.ts`) — contain `// podokit:begin:… / …:end` fenced regions that the toolkit recomputes. Edit outside the fences only; **never hand-edit inside the fences**.
 - **managed** (bootstrap/config like `main.ts`) — the toolkit may update these; avoid gratuitous edits.
 

package/dist/templates/fullstack/apps/api/package.json

@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@podosoft/podokit-contracts": "^0.5.0",
-    "@podosoft/podokit-runtime": "^0.4.0",
+    "@podosoft/podokit-runtime": "^0.4.1",
     "@elysia/cors": "^1.4.2",
     "@elysia/openapi": "^1.4.15",
     "dotenv": "^16.4.5",

package/dist/templates/fullstack/apps/api/src/app.extensions.ts

@@ -12,8 +12,11 @@ export const extensionModules: PodokitModule[] = [];
 
 // Bun server options such as a larger request body limit for uploads, for
 // example { maxRequestBodySize: 1024 ** 3, idleTimeout: 120 }. Values set here
-// win over API_MAX_REQUEST_BODY_SIZE; a function receives the validated
-// environment instead: (env) => ({ maxRequestBodySize: ... }). A longer
-// idleTimeout also needs BACKEND_PROXY_TIMEOUT_MS on the web server, which stops
-// waiting for response headers after 30 seconds by default.
+// win over API_MAX_REQUEST_BODY_SIZE and API_IDLE_TIMEOUT; a function receives
+// the validated environment instead: (env) => ({ maxRequestBodySize: ... }). A
+// longer idleTimeout also needs a longer proxy deadline on the web server, which
+// stops waiting for response headers after 30 seconds by default:
+// BACKEND_PROXY_TIMEOUT_MS, or one route's entry in APP_PROXY_TIMEOUTS
+// (apps/web/src/lib/server/proxy-timeouts.ts), and the web server's
+// CONNECTION_IDLE_TIMEOUT (35 seconds).
 export const apiServerOptions: ApiServerOptionsSource = {};

package/dist/templates/fullstack/apps/api/src/app.ts

@@ -4,6 +4,7 @@ import { AppException, type ErrorEnvelope } from "@podosoft/podokit-contracts";
 import { Elysia } from "elysia";
 import { configureServices, extensionModules } from "./app.extensions";
 import { validateEnv, type AppEnv } from "./config/env.validation";
+import { stampClientAddress } from "./core/client-address";
 import {
   appContext,
   createCoreServices,
@@ -137,6 +138,7 @@ const buildApp = (options: CreateAppOptions = {}) => {
   services.freeze();
   const context = appContext(env, services);
   const corsOrigin = env.CORS_ORIGIN?.split(",").map((origin) => origin.trim());
+  const clientAddressConfig = { trustedProxyHops: env.TRUSTED_PROXY_HOPS, header: env.TRUSTED_PROXY_HEADER };
 
   const app = new Elysia({ name: "podokit" })
     .use(cors({ origin: corsOrigin ?? true, credentials: true }))
@@ -157,11 +159,12 @@ const buildApp = (options: CreateAppOptions = {}) => {
     .onRequest(async ({ request, server, set }) => {
       const requestId = request.headers.get("x-request-id") ?? crypto.randomUUID();
       set.headers["x-request-id"] = requestId;
+      const remoteAddress = server?.requestIP(request)?.address;
+      const clientAddress = stampClientAddress(request, remoteAddress, clientAddressConfig);
       await context.requestGuards.run({
         request,
-        ...(server?.requestIP(request)?.address
-          ? { remoteAddress: server.requestIP(request)?.address }
-          : {}),
+        ...(remoteAddress ? { remoteAddress } : {}),
+        ...(clientAddress ? { clientAddress } : {}),
         setHeader: (name, value) => { set.headers[name] = value; },
       });
     })

package/dist/templates/fullstack/apps/api/src/config/env.validation.ts

@@ -6,6 +6,22 @@ const schema = z.object({
   PORT: z.coerce.number().default(5002),
   // Bytes one request body may hold; 128 MiB is Bun's default.
   API_MAX_REQUEST_BODY_SIZE: z.coerce.number().int().positive().default(128 * 1024 * 1024),
+  // Seconds a connection may stay silent, 0 (never closed) to 255. Bun closes idle
+  // connections on a 4-second sweep, so 35 outlasts the web proxy's 30-second
+  // deadline. An empty value means unset rather than 0.
+  API_IDLE_TIMEOUT: z.preprocess(
+    (value) => (value === "" ? undefined : value),
+    z.coerce.number().int().min(0).max(255).default(35),
+  ),
+  // Reverse proxies in front of the API whose forwarded header names the client;
+  // the generated web proxy is one. 0 uses the socket peer.
+  TRUSTED_PROXY_HOPS: z.coerce.number().int().nonnegative().default(0),
+  TRUSTED_PROXY_HEADER: z
+    .string()
+    .trim()
+    .toLowerCase()
+    .regex(/^[a-z0-9!#$%&'*+.^_`|~-]+$/, "must be an HTTP header name")
+    .default("x-forwarded-for"),
   CORS_ORIGIN: z.string().optional(),
   DATABASE_URL: z.string().optional(),
   POSTGRES_HOST: z.string().default("localhost"),
@@ -24,7 +40,19 @@ const schema = z.object({
 
 export type AppEnv = z.infer<typeof schema>;
 
+// Renamed settings fail loudly: falling back to the default would count and
+// record every browser request under the web server's address.
+const RENAMED: Record<string, string> = {
+  RATE_LIMIT_TRUSTED_PROXY_HOPS: "TRUSTED_PROXY_HOPS",
+  RATE_LIMIT_PROXY_HEADER: "TRUSTED_PROXY_HEADER",
+};
+
 export function validateEnv(config: Record<string, unknown>): AppEnv {
+  for (const [previous, current] of Object.entries(RENAMED)) {
+    if (config[previous] !== undefined) {
+      throw new Error(`Invalid environment: ${previous} was renamed to ${current}.`);
+    }
+  }
   const parsed = schema.safeParse(config);
   if (!parsed.success) {
     throw new Error(`Invalid environment:\n${parsed.error.toString()}`);

package/dist/templates/fullstack/apps/api/src/config/providers.ts

@@ -1,9 +1,11 @@
 import type { ProviderSelections } from "@podosoft/podokit-runtime";
 
-export const PROVIDERS = {
+// Typed with every provider name, not the selected ones: the module of a
+// provider that stays installed after a switch compares against its own name.
+export const PROVIDERS: Readonly<ProviderSelections> = {
   database: "{{databaseProvider}}",
   cache: "{{cacheProvider}}",
   "object-storage": "{{objectStorageProvider}}",
   events: "{{eventsProvider}}",
   jobs: "{{jobsProvider}}",
-} as const satisfies ProviderSelections;
+};

package/dist/templates/fullstack/apps/api/src/config/server-options.spec.ts

@@ -4,26 +4,37 @@ import { validateEnv } from "./env.validation";
 import { apiServerOptions, DEFAULT_MAX_REQUEST_BODY_SIZE } from "./server-options";
 
 describe("apiServerOptions", () => {
-  it("defaults to Bun's request body limit and leaves the idle timeout to Elysia", () => {
+  it("defaults to Bun's request body limit and an idle timeout that outlasts the web proxy", () => {
     const env = validateEnv({});
     expect(env.API_MAX_REQUEST_BODY_SIZE).toBe(DEFAULT_MAX_REQUEST_BODY_SIZE);
-    expect(apiServerOptions(env, {})).toEqual({ maxRequestBodySize: DEFAULT_MAX_REQUEST_BODY_SIZE });
+    expect(apiServerOptions(env, {})).toEqual({ maxRequestBodySize: DEFAULT_MAX_REQUEST_BODY_SIZE, idleTimeout: 35 });
+  });
+
+  it("reads API_IDLE_TIMEOUT from 0 to 255 seconds and treats an empty value as unset", () => {
+    expect(validateEnv({ API_IDLE_TIMEOUT: "125" }).API_IDLE_TIMEOUT).toBe(125);
+    expect(validateEnv({ API_IDLE_TIMEOUT: "0" }).API_IDLE_TIMEOUT).toBe(0);
+    expect(validateEnv({ API_IDLE_TIMEOUT: "255" }).API_IDLE_TIMEOUT).toBe(255);
+    expect(validateEnv({ API_IDLE_TIMEOUT: "" }).API_IDLE_TIMEOUT).toBe(35);
+    for (const value of ["256", "-1", "1.5", "soon"]) {
+      expect(() => validateEnv({ API_IDLE_TIMEOUT: value })).toThrow("API_IDLE_TIMEOUT");
+    }
+    expect(apiServerOptions(validateEnv({ API_IDLE_TIMEOUT: "0" }), {}).idleTimeout).toBe(0);
   });
 
   it("reads API_MAX_REQUEST_BODY_SIZE and rejects values that are not byte counts", () => {
-    expect(apiServerOptions(validateEnv({ API_MAX_REQUEST_BODY_SIZE: "1073741824" }), {}))
-      .toEqual({ maxRequestBodySize: 1_073_741_824 });
+    expect(apiServerOptions(validateEnv({ API_MAX_REQUEST_BODY_SIZE: "1073741824" }), {}).maxRequestBodySize)
+      .toBe(1_073_741_824);
     for (const value of ["0", "-1", "1.5", "lots"]) {
       expect(() => validateEnv({ API_MAX_REQUEST_BODY_SIZE: value })).toThrow("API_MAX_REQUEST_BODY_SIZE");
     }
   });
 
   it("lets the application's options win over the environment", () => {
-    const env = validateEnv({ API_MAX_REQUEST_BODY_SIZE: "1024" });
+    const env = validateEnv({ API_MAX_REQUEST_BODY_SIZE: "1024", API_IDLE_TIMEOUT: "60" });
     expect(apiServerOptions(env, { maxRequestBodySize: 4096, idleTimeout: 120 }))
       .toEqual({ maxRequestBodySize: 4096, idleTimeout: 120 });
     expect(apiServerOptions(env, (current) => ({ maxRequestBodySize: current.API_MAX_REQUEST_BODY_SIZE * 2 })))
-      .toEqual({ maxRequestBodySize: 2048 });
+      .toEqual({ maxRequestBodySize: 2048, idleTimeout: 60 });
     expect(() => apiServerOptions(env, { maxRequestBodySize: 0 })).toThrow("maxRequestBodySize");
     expect(() => apiServerOptions(env, { idleTimeout: 256 })).toThrow("idleTimeout");
     expect(() => apiServerOptions(env, { idleTimeout: -1 })).toThrow("idleTimeout");

package/dist/templates/fullstack/apps/api/src/config/server-options.ts

@@ -11,7 +11,7 @@ export interface ApiServerOptions {
   maxRequestBodySize?: number;
   /**
    * Seconds a connection may stay idle before it is closed, from 0 (never) to
-   * 255. Defaults to Elysia's 30 seconds.
+   * 255. Defaults to `API_IDLE_TIMEOUT`.
    */
   idleTimeout?: number;
 }
@@ -31,18 +31,15 @@ const owned: { readonly [name: string]: unknown; readonly apiServerOptions?: Api
 export function apiServerOptions(
   env: AppEnv,
   source: ApiServerOptionsSource | undefined = owned.apiServerOptions,
-): ApiServerOptions & { maxRequestBodySize: number } {
+): Required<ApiServerOptions> {
   const options = typeof source === "function" ? source(env) : source ?? {};
   const maxRequestBodySize = options.maxRequestBodySize ?? env.API_MAX_REQUEST_BODY_SIZE;
   if (!Number.isSafeInteger(maxRequestBodySize) || maxRequestBodySize < 1) {
     throw new Error("apiServerOptions.maxRequestBodySize must be a positive integer of bytes");
   }
-  const { idleTimeout } = options;
-  if (
-    idleTimeout !== undefined &&
-    (!Number.isInteger(idleTimeout) || idleTimeout < 0 || idleTimeout > MAX_IDLE_TIMEOUT_SECONDS)
-  ) {
+  const idleTimeout = options.idleTimeout ?? env.API_IDLE_TIMEOUT;
+  if (!Number.isInteger(idleTimeout) || idleTimeout < 0 || idleTimeout > MAX_IDLE_TIMEOUT_SECONDS) {
     throw new Error(`apiServerOptions.idleTimeout must be an integer from 0 to ${MAX_IDLE_TIMEOUT_SECONDS} seconds`);
   }
-  return { maxRequestBodySize, ...(idleTimeout === undefined ? {} : { idleTimeout }) };
+  return { maxRequestBodySize, idleTimeout };
 }

package/dist/templates/fullstack/apps/api/src/core/client-address.spec.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "bun:test";
+import { validateEnv } from "../config/env.validation";
+import {
+  CLIENT_ADDRESS_HEADER,
+  clientAddressOf,
+  resolveClientAddress,
+  stampClientAddress,
+} from "./client-address";
+
+const forwarded = (value: string): Headers => new Headers({ "x-forwarded-for": value });
+const config = (trustedProxyHops: number) => ({ trustedProxyHops, header: "x-forwarded-for" });
+
+describe("resolveClientAddress", () => {
+  it("uses the socket peer and ignores a caller's header without trusted proxies", () => {
+    expect(resolveClientAddress(forwarded("198.51.100.66"), "10.0.0.9", config(0))).toBe("10.0.0.9");
+    expect(resolveClientAddress(forwarded("198.51.100.66"), "::ffff:10.0.0.9", config(0))).toBe("10.0.0.9");
+    expect(resolveClientAddress(new Headers(), undefined, config(0))).toBeUndefined();
+  });
+
+  it("takes the entry the trusted proxies appended, never one further left", () => {
+    // A caller sent "198.51.100.66"; the one trusted proxy appended the real client.
+    const chain = forwarded("198.51.100.66, 203.0.113.7");
+    expect(resolveClientAddress(chain, "10.0.0.9", config(1))).toBe("203.0.113.7");
+    expect(resolveClientAddress(chain, "10.0.0.9", config(2))).toBe("198.51.100.66");
+    expect(resolveClientAddress(forwarded("203.0.113.7"), "10.0.0.9", config(1))).toBe("203.0.113.7");
+    expect(
+      resolveClientAddress(new Headers({ "x-real-ip": "203.0.113.8" }), "10.0.0.9", {
+        trustedProxyHops: 1,
+        header: "x-real-ip",
+      }),
+    ).toBe("203.0.113.8");
+  });
+
+  it("falls back to the peer for a short or malformed chain", () => {
+    expect(resolveClientAddress(new Headers(), "10.0.0.9", config(1))).toBe("10.0.0.9");
+    expect(resolveClientAddress(forwarded("203.0.113.7"), "10.0.0.9", config(2))).toBe("10.0.0.9");
+    expect(resolveClientAddress(forwarded("attacker-controlled"), "10.0.0.9", config(1))).toBe("10.0.0.9");
+    expect(resolveClientAddress(forwarded("203.0.113.7, not-an-ip"), "10.0.0.9", config(1))).toBe("10.0.0.9");
+  });
+
+  it("reads the address the API set", () => {
+    expect(clientAddressOf(new Headers({ [CLIENT_ADDRESS_HEADER]: "203.0.113.7" }))).toBe("203.0.113.7");
+    expect(clientAddressOf(new Headers())).toBeUndefined();
+    expect(clientAddressOf(undefined)).toBeUndefined();
+  });
+});
+
+describe("client address settings", () => {
+  it("validates the trusted proxy settings and refuses the rate limiter's former names", () => {
+    expect(validateEnv({})).toMatchObject({ TRUSTED_PROXY_HOPS: 0, TRUSTED_PROXY_HEADER: "x-forwarded-for" });
+    expect(validateEnv({ TRUSTED_PROXY_HOPS: "1", TRUSTED_PROXY_HEADER: "X-Real-IP" }))
+      .toMatchObject({ TRUSTED_PROXY_HOPS: 1, TRUSTED_PROXY_HEADER: "x-real-ip" });
+    expect(() => validateEnv({ TRUSTED_PROXY_HOPS: "-1" })).toThrow("TRUSTED_PROXY_HOPS");
+    expect(() => validateEnv({ TRUSTED_PROXY_HEADER: "bad header" })).toThrow("TRUSTED_PROXY_HEADER");
+    expect(() => validateEnv({ RATE_LIMIT_TRUSTED_PROXY_HOPS: "1" }))
+      .toThrow("RATE_LIMIT_TRUSTED_PROXY_HOPS was renamed to TRUSTED_PROXY_HOPS");
+    expect(() => validateEnv({ RATE_LIMIT_PROXY_HEADER: "x-forwarded-for" }))
+      .toThrow("RATE_LIMIT_PROXY_HEADER was renamed to TRUSTED_PROXY_HEADER");
+  });
+});
+
+describe("stampClientAddress", () => {
+  const request = (headers: Record<string, string>): Request => new Request("http://localhost/x", { headers });
+
+  it("replaces a caller's own address header and ignores its forwarded header without trusted proxies", () => {
+    const spoofed = request({ "x-forwarded-for": "198.51.100.66", [CLIENT_ADDRESS_HEADER]: "198.51.100.67" });
+    expect(stampClientAddress(spoofed, "::ffff:127.0.0.1", config(0))).toBe("127.0.0.1");
+    expect(clientAddressOf(spoofed.headers)).toBe("127.0.0.1");
+  });
+
+  it("records the rightmost forwarded entry behind one trusted proxy", () => {
+    const proxied = request({ "x-forwarded-for": "198.51.100.66, 203.0.113.7" });
+    expect(stampClientAddress(proxied, "10.0.0.9", config(1))).toBe("203.0.113.7");
+    expect(clientAddressOf(proxied.headers)).toBe("203.0.113.7");
+  });
+
+  it("removes a caller's value when no address can be resolved", () => {
+    const unknown = request({ [CLIENT_ADDRESS_HEADER]: "198.51.100.67" });
+    expect(stampClientAddress(unknown, undefined, config(0))).toBeUndefined();
+    expect(clientAddressOf(unknown.headers)).toBeUndefined();
+  });
+});

package/dist/templates/fullstack/apps/api/src/core/client-address.ts

@@ -0,0 +1,68 @@
+import { isIP } from "node:net";
+
+/**
+ * The request header that carries the client address the API resolved. The API
+ * sets it on every request before any handler runs, replacing whatever a caller
+ * sent, so Better Auth, audit entries, and application code read one address
+ * that a caller cannot choose.
+ */
+export const CLIENT_ADDRESS_HEADER = "x-podokit-client-address";
+
+export interface ClientAddressConfig {
+  /** Reverse proxies in front of the API whose forwarded header is trusted; 0 trusts none. */
+  trustedProxyHops: number;
+  /** The lowercase header those proxies append the client address to. */
+  header: string;
+}
+
+/** An IP address without its IPv4-mapped IPv6 prefix, or undefined when the value is not one. */
+export function normalizeIp(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  const normalized = trimmed.startsWith("::ffff:") ? trimmed.slice("::ffff:".length) : trimmed;
+  return isIP(normalized) === 0 ? undefined : normalized;
+}
+
+/**
+ * The caller's address. With no trusted proxy it is the socket peer. Otherwise
+ * each trusted proxy appended one entry to the header, so the client is the
+ * entry that many places left of the peer; entries further left were written
+ * by the caller and are ignored. A chain shorter than the trusted hops, or a
+ * malformed entry, falls back to the peer instead of trusting caller input.
+ */
+export function resolveClientAddress(
+  headers: Headers,
+  remoteAddress: string | undefined,
+  config: ClientAddressConfig,
+): string | undefined {
+  const direct = normalizeIp(remoteAddress);
+  if (config.trustedProxyHops === 0) return direct;
+  const forwarded = headers.get(config.header)
+    ?.split(",")
+    .map((value) => value.trim())
+    .filter(Boolean) ?? [];
+  const chain = [...forwarded, direct ?? ""];
+  if (chain.length <= config.trustedProxyHops) return direct;
+  return normalizeIp(chain[chain.length - config.trustedProxyHops - 1]) ?? direct;
+}
+
+/**
+ * Resolves a request's client address and records it in CLIENT_ADDRESS_HEADER,
+ * replacing any value the caller sent. The API does this for every request
+ * before a guard, Better Auth, or a handler reads the request.
+ */
+export function stampClientAddress(
+  request: Request,
+  remoteAddress: string | undefined,
+  config: ClientAddressConfig,
+): string | undefined {
+  const address = resolveClientAddress(request.headers, remoteAddress, config);
+  if (address) request.headers.set(CLIENT_ADDRESS_HEADER, address);
+  else request.headers.delete(CLIENT_ADDRESS_HEADER);
+  return address;
+}
+
+/** The address the API resolved for a request, as set in CLIENT_ADDRESS_HEADER. */
+export function clientAddressOf(headers: Headers | undefined): string | undefined {
+  return headers?.get(CLIENT_ADDRESS_HEADER) ?? undefined;
+}

package/dist/templates/fullstack/apps/api/src/core/services.ts

@@ -280,7 +280,10 @@ export class AccessPolicy {
 
 export interface RequestGuardContext {
   request: Request;
+  /** The socket peer. */
   remoteAddress?: string;
+  /** The caller's address behind the trusted proxies; see core/client-address.ts. */
+  clientAddress?: string;
   setHeader: (name: string, value: string) => void;
 }
 
@@ -305,6 +308,31 @@ export interface RequestIdentity {
   activeOrganizationId(request: Request): Promise<string | undefined>;
 }
 
+/** A session the API resolved while handling a request. */
+export interface ResolvedSession {
+  /** The session token without its cookie signature. */
+  token: string;
+  userId: string;
+  expiresAt: Date;
+}
+
+/**
+ * Passes each session the API resolves for a request to the modules that listen,
+ * so they can use it without a session lookup of their own. The auth module
+ * reports; the rate limiter listens to count a signed-in caller per user.
+ */
+export class ResolvedSessions {
+  private readonly listeners: Array<(session: ResolvedSession) => void> = [];
+
+  listen(listener: (session: ResolvedSession) => void): void {
+    this.listeners.push(listener);
+  }
+
+  report(session: ResolvedSession): void {
+    for (const listener of this.listeners) listener(session);
+  }
+}
+
 export interface OpenApiContribution {
   document: Record<string, unknown>;
   pathPrefix?: string;
@@ -331,6 +359,7 @@ export const LOGGER = Symbol("logger") as ServiceKey<Logger>;
 export const ACCESS_POLICY = Symbol("access-policy") as ServiceKey<AccessPolicy>;
 export const REQUEST_GUARDS = Symbol("request-guards") as ServiceKey<RequestGuardRegistry>;
 export const REQUEST_IDENTITY = Symbol("request-identity") as ServiceKey<RequestIdentity>;
+export const RESOLVED_SESSIONS = Symbol("resolved-sessions") as ServiceKey<ResolvedSessions>;
 export const OPENAPI = Symbol("openapi") as ServiceKey<OpenApiRegistry>;
 
 export interface AppContext {
@@ -390,6 +419,7 @@ export function createCoreServices(env: AppEnv): ServiceRegistry {
     roles: async () => [],
     activeOrganizationId: async () => undefined,
   });
+  services.register(RESOLVED_SESSIONS, new ResolvedSessions());
   services.register(OPENAPI, openapiRegistry);
   return services;
 }