@cosmicdrift/kumiko-framework 0.318.0 → 0.320.0

package/src/engine/types/handlers.ts

@@ -1,3 +1,3 @@
 // Legacy path — re-exported for callers still importing this module directly.
 export type * from "@cosmicdrift/kumiko-types/handlers";
-export { isOpenToAllGranted } from "@cosmicdrift/kumiko-types/handlers";
+export { isOpenToAllGranted, isUiAccessGranted } from "@cosmicdrift/kumiko-types/handlers";

package/src/engine/types/index.ts

@@ -218,7 +218,11 @@ export type {
   WriteHandlerFn,
   WriteResult,
 } from "@cosmicdrift/kumiko-types/handlers";
-export { isOpenToAllGranted, isRateLimitDisabled } from "@cosmicdrift/kumiko-types/handlers";
+export {
+  isOpenToAllGranted,
+  isRateLimitDisabled,
+  isUiAccessGranted,
+} from "@cosmicdrift/kumiko-types/handlers";
 export type {
   DeleteContext,
   EntityHookMap,

package/src/entrypoint/index.ts

@@ -17,7 +17,18 @@
 //   const entry = createApiEntrypoint(opts);
 //   attachSignalHandlers(entry.lifecycle);
 //   await entry.start();
-//   serve({ fetch: entry.app.fetch, port: 3000 });
+//   serve({
+//     fetch: (req, server) => entry.app.fetch(req, server.requestIP(req)?.address),
+//     port: 3000,
+//   });
+//
+// `entry.app.fetch` alone (without the 2nd arg) loses the caller's real
+// socket address — the client-ip resolver then sees no env, falls back to
+// "unknown", and every caller shares one IP-keyed rate-limit bucket (see
+// api/client-ip.ts). @cosmicdrift/kumiko-server-runtime's
+// `buildBunServeOptions(port, entry.app.fetch)` wires this same pattern
+// plus the SSE-safe idleTimeout default, for consumers that already
+// depend on that package.
 //
 // The `lifecycle` handle drives graceful-shutdown LIFO; the framework
 // registers its own shutdown hooks (eventDispatcher.stop, jobRunner.stop)
@@ -107,6 +118,7 @@ export type ApiEntrypointOptions = BaseEntrypointOptions & {
   readonly eventDispatcher?: ServerOptions["eventDispatcher"] & {
     readonly runLocal?: boolean;
   };
+  readonly trustedProxyHops?: ServerOptions["trustedProxyHops"];
 };
 
 export type WorkerEntrypointOptions = BaseEntrypointOptions &
@@ -231,6 +243,7 @@ function buildApiServer(
     processLane,
     jwtIssuer: opts.jwtIssuer,
     auth: opts.auth,
+    trustedProxyHops: opts.trustedProxyHops,
     anonymousAccess: opts.anonymousAccess,
     sseBroker: opts.sseBroker,
     rateLimit: opts.rateLimit,

package/src/files/__tests__/files.integration.test.ts

@@ -33,7 +33,7 @@ import {
 import { createFilesFeature } from "../feature";
 import { fileRefsTable } from "../file-ref-table";
 import type { FileRoutesOptions } from "../file-routes";
-import { createInMemoryFileProvider } from "../in-memory-provider";
+import { createInMemoryFileProvider, type InMemoryFileProvider } from "../in-memory-provider";
 import { createLocalProvider } from "../local-provider";
 import type { FileStorageProvider, SignedUrlOptions } from "../types";
 import {
@@ -1643,3 +1643,107 @@ describe("byte-serving routes with field-encrypted fileName", () => {
     }
   });
 });
+
+describe("upload body-size limit", () => {
+  // Small on purpose: the pre-parseBody body limit is maxUploadSize + a
+  // fixed multipart margin regardless of scale, so a tiny maxUploadSize
+  // keeps the over-limit payloads (and this suite) fast.
+  const SMALL_MAX_UPLOAD_SIZE = "1kb";
+  const OVER_LIMIT_FILE_BYTES = 200 * 1024;
+
+  async function withSizeLimitedServer(
+    body: (args: { app: Hono; jwt: JwtHelper; provider: InMemoryFileProvider }) => Promise<void>,
+  ): Promise<void> {
+    const isolatedDb = await createTestDb();
+    await unsafePushTables(isolatedDb.db, { fileRefsTable });
+    const provider = createInMemoryFileProvider();
+    const isolatedRegistry = createRegistry([
+      createFilesFeature({ maxUploadSize: SMALL_MAX_UPLOAD_SIZE }),
+    ]);
+    const isolatedServer = buildServer({
+      registry: isolatedRegistry,
+      context: { db: isolatedDb.db, _fileProviderResolver: () => Promise.resolve(provider) },
+      jwtSecret: JWT_SECRET,
+    });
+    try {
+      await body({ app: isolatedServer.app, jwt: isolatedServer.jwt, provider });
+    } finally {
+      await isolatedDb.cleanup();
+    }
+  }
+
+  async function buildUnattachedMultipartBody(
+    fileSizeBytes: number,
+  ): Promise<{ body: Uint8Array; contentType: string }> {
+    const fd = new FormData();
+    const content = new Uint8Array(fileSizeBytes);
+    content.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]); // PNG magic bytes
+    fd.append("file", new File([Buffer.from(content)], "big.png", { type: "image/png" }));
+    const { body, contentType } = await buildMultipartBody(fd);
+    return { body: body as Uint8Array, contentType };
+  }
+
+  test("Content-Length above the limit is rejected without writing to storage", async () => {
+    await withSizeLimitedServer(async ({ app, jwt, provider }) => {
+      const token = await jwt.sign(adminUser);
+      const { body, contentType } = await buildUnattachedMultipartBody(OVER_LIMIT_FILE_BYTES);
+      const res = await app.request("/api/files", {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": contentType },
+        body: body as unknown as BodyInit,
+      });
+      expect(res.status).toBe(413);
+      const json = (await res.json()) as { error: string };
+      expectErrorIncludes(json.error, "request_too_large");
+      expect(provider.keys()).toEqual([]);
+    });
+  });
+
+  test("a chunked body without Content-Length above the limit is rejected while streaming", async () => {
+    await withSizeLimitedServer(async ({ app, jwt, provider }) => {
+      const token = await jwt.sign(adminUser);
+      const { body, contentType } = await buildUnattachedMultipartBody(OVER_LIMIT_FILE_BYTES);
+      // Feeding the buffer through a ReadableStream (instead of handing it to
+      // fetch directly) means no Content-Length can be inferred — this drives
+      // bodyLimit's streaming/counting branch instead of its Content-Length
+      // shortcut.
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          const chunkSize = 8 * 1024;
+          for (let offset = 0; offset < body.length; offset += chunkSize) {
+            controller.enqueue(body.subarray(offset, offset + chunkSize));
+          }
+          controller.close();
+        },
+      });
+      const req = new Request("http://localhost/api/files", {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": contentType },
+        body: stream,
+        duplex: "half",
+      } as RequestInit);
+      // A stream body has no known length — confirms this exercises
+      // bodyLimit's streaming/counting branch, not its Content-Length shortcut.
+      expect(req.headers.get("content-length")).toBeNull();
+      const res = await app.request(req);
+      expect(res.status).toBe(413);
+      const json = (await res.json()) as { error: string };
+      expectErrorIncludes(json.error, "request_too_large");
+      expect(provider.keys()).toEqual([]);
+    });
+  });
+
+  test("an upload within the limit still succeeds", async () => {
+    await withSizeLimitedServer(async ({ app, jwt, provider }) => {
+      const token = await jwt.sign(adminUser);
+      const { body, contentType } = await buildUnattachedMultipartBody(128);
+      const res = await app.request("/api/files", {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": contentType },
+        body: body as unknown as BodyInit,
+      });
+      expect(res.status).toBe(201);
+      expect(provider.keys().length).toBe(1);
+    });
+  });
+});

package/src/files/file-routes.ts

@@ -1,5 +1,6 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
 import { getUser } from "../api/auth-middleware";
 import { requestContext } from "../api/request-context";
 import {
@@ -29,6 +30,7 @@ import { fileRefsTable } from "./file-ref-table";
 import type { FileProviderResolver } from "./provider-resolver";
 import {
   buildStorageKey,
+  parseMaxSize,
   resolveServedContentType,
   resolveUploadMimeType,
   validateFile,
@@ -130,6 +132,45 @@ function resolveAttachedField(
   return { kind: "resolved", fieldDef };
 }
 
+const DEFAULT_MAX_UPLOAD_SIZE = "10mb";
+
+// Multipart framing plus the small entityType/entityId/fieldName parts
+// riding alongside the file.
+const MULTIPART_OVERHEAD_MARGIN_BYTES = 64 * 1024;
+
+// entityType/fieldName (and therefore the field's own maxSize) are only
+// known after the body is parsed, so this covers the largest configured
+// field, not just the global default.
+export function resolveMaxUploadBodyBytes(
+  options: Pick<FileRoutesOptions, "registry" | "maxUploadSize">,
+): number {
+  let maxBytes = parseMaxSize(options.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE);
+  for (const entity of options.registry?.getAllEntities().values() ?? []) {
+    for (const field of Object.values(entity.fields)) {
+      if (isFileField(field) && field.maxSize) {
+        maxBytes = Math.max(maxBytes, parseMaxSize(field.maxSize));
+      }
+    }
+  }
+  return maxBytes + MULTIPART_OVERHEAD_MARGIN_BYTES;
+}
+
+// Upload-route policy carried by createFilesFeature(opts?) — read from the
+// feature's exports so callers apply it without a parallel options surface.
+export 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 {};
+}
+
 export function createFileRoutes(options: FileRoutesOptions): Hono {
   const { db } = options;
   const privilegedRoles = options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES;
@@ -168,8 +209,19 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     return typeof decrypted["fileName"] === "string" ? decrypted["fileName"] : "download";
   }
 
+  // Runs before parseBody buffers the request below: checks Content-Length
+  // upfront, counts chunked bodies while streaming.
+  const uploadBodyLimit = bodyLimit({
+    maxSize: resolveMaxUploadBodyBytes(options),
+    onError: (c) =>
+      c.json(
+        { error: "request_too_large: request body exceeds the maximum allowed upload size" },
+        413,
+      ),
+  });
+
   // POST /files — multipart upload.
-  api.post("/files", async (c) => {
+  api.post("/files", uploadBodyLimit, async (c) => {
     const user = getUser(c);
     const body = await c.req.parseBody();
     const file = body["file"];
@@ -198,7 +250,7 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     }
 
     // Validate against entity field definition if available.
-    let maxSize = options.maxUploadSize ?? "10mb";
+    let maxSize = options.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE;
     let accept: readonly string[] | undefined;
 
     const attachedField = resolveAttachedField(options.registry, entityType, fieldName);

package/src/files/index.ts

@@ -11,7 +11,7 @@ export type {
   FileRef,
   FileRoutesOptions,
 } from "./file-routes";
-export { createFileRoutes } from "./file-routes";
+export { createFileRoutes, readFilesRouteOptions, resolveMaxUploadBodyBytes } from "./file-routes";
 export type { InMemoryFileProvider } from "./in-memory-provider";
 export { createInMemoryFileProvider } from "./in-memory-provider";
 export { createLocalProvider } from "./local-provider";

package/src/http/index.ts

@@ -1,2 +1,10 @@
-export type { EgressPolicy } from "@cosmicdrift/kumiko-http";
-export { egress, isPublicHost } from "@cosmicdrift/kumiko-http";
+export type { EgressPolicy, ResolvedHost } from "@cosmicdrift/kumiko-http";
+export {
+  BlockedHostError,
+  buildPinnedRequest,
+  egress,
+  HostResolutionError,
+  isPublicHost,
+  resolvePublicHost,
+  resolvePublicHostname,
+} from "@cosmicdrift/kumiko-http";

package/src/jobs/__tests__/jobs.integration.test.ts

@@ -1,5 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { Queue } from "bullmq";
+import { Redis } from "ioredis";
 import * as z from "zod";
 import { requestContext } from "../../api/request-context";
 import { tenantDbRunner } from "../../db/tenant-db-runner";
@@ -13,6 +14,7 @@ import type {
   TenantId,
 } from "../../engine/types";
 import { createInMemoryFileProvider } from "../../files/in-memory-provider";
+import { RedisKeys } from "../../pipeline/redis-keys";
 import { createTestRedis, type TestRedis, TestUsers } from "../../stack";
 import { sleep, waitFor } from "../../testing";
 import {
@@ -498,10 +500,110 @@ describe("concurrency: sequential", () => {
       expect(delta12).toBeGreaterThanOrEqual(250);
       expect(delta23).toBeGreaterThanOrEqual(250);
 
-      // FIFO inside the same lock-name: the dispatch order is preserved
-      // even though re-enqueues happen.
-      expect(entries[0]?.payload).toEqual({ n: 1 });
+      // NOT dispatch order: "sequential" is mutual exclusion, not a FIFO
+      // queue. A re-enqueued lock loser goes to the back of its
+      // queue, so it can still win the next race. What's guaranteed, and
+      // already asserted above via delta12/delta23, is that runs never
+      // overlap. Assert the complete set instead of a specific order.
+      expect(entries.map((e) => e.payload)).toEqual(
+        expect.arrayContaining([{ n: 1 }, { n: 2 }, { n: 3 }]),
+      );
+    });
+  });
+
+  test("runners with distinct queueNamePrefix do not share the sequential lock", async () => {
+    clearLog();
+    // Regression guard: the lock key used to omit queueNamePrefix, so two
+    // isolated runners sharing a Redis collided on the same lock.
+    const prefixA = `kumiko-test-lockscope-a-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const prefixB = `kumiko-test-lockscope-b-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const runnerA = createJobRunner({
+      registry: createRegistry([testFeature]),
+      context: {},
+      redisUrl,
+      consumerLane: "worker",
+      queueNamePrefix: prefixA,
+    });
+    const runnerB = createJobRunner({
+      registry: createRegistry([testFeature]),
+      context: {},
+      redisUrl,
+      consumerLane: "worker",
+      queueNamePrefix: prefixB,
+    });
+    // Own client, no keyPrefix — testRedis.redis auto-prefixes SET/DEL and
+    // would write a different key than the runner's own lock connection.
+    const lockKeyA = `${RedisKeys.lock}seq:${prefixA}:worker:test:job:sequential-job`;
+    const rawRedis = new Redis(redisUrl);
+    rawRedis.on("error", () => {});
+    const queueA = new Queue(`${prefixA}-worker`, {
+      connection: { host: testRedis.redis.options.host, port: testRedis.redis.options.port },
     });
+    // A post-close 'error' here is otherwise unhandled and bun:test
+    // attributes it to whichever test runs next (fw#1805).
+    queueA.on("error", () => {});
+
+    try {
+      await rawRedis.set(lockKeyA, "held-by-test", "EX", 30, "NX");
+
+      await runnerA.start();
+      await runnerB.start();
+
+      await runnerA.dispatch("test:job:sequential-job", { n: 100 });
+
+      // A's handler returns successfully on a lock loss (re-enqueue, not a
+      // throw) — BullMQ records the dropped attempt as completed even
+      // though the job body never ran. Filtered by name+payload so unrelated
+      // boot/cron jobs on the same worker queue don't false-positive this.
+      await waitFor(
+        async () => {
+          const completed = await queueA.getCompleted();
+          const lostAttempts = completed.filter(
+            (job) => job.name === "test:job:sequential-job" && job.data.n === 100,
+          );
+          expect(lostAttempts.length).toBeGreaterThanOrEqual(1);
+        },
+        { delays: [400, 800, 1500, 3000] },
+      );
+      expect(
+        jobLog.some((e) => e.name === "test:job:sequential-job" && e.payload["n"] === 100),
+      ).toBe(false);
+
+      // B shares no lock scope with the externally held A-key, so it must
+      // run despite A being blocked.
+      await runnerB.dispatch("test:job:sequential-job", { n: 200 });
+      await waitFor(
+        () => {
+          const entries = jobLog.filter(
+            (e) => e.name === "test:job:sequential-job" && e.payload["n"] === 200,
+          );
+          expect(entries.length).toBeGreaterThanOrEqual(1);
+        },
+        { delays: [400, 800, 1500, 3000] },
+      );
+
+      // Releasing the externally held key unblocks A's own dispatch.
+      await rawRedis.del(lockKeyA);
+      await waitFor(
+        () => {
+          const entries = jobLog.filter(
+            (e) => e.name === "test:job:sequential-job" && e.payload["n"] === 100,
+          );
+          expect(entries.length).toBeGreaterThanOrEqual(1);
+        },
+        { delays: [400, 800, 1500, 3000] },
+      );
+    } finally {
+      await runnerA.stop();
+      await runnerB.stop();
+      await queueA.close();
+      await rawRedis.del(lockKeyA);
+      rawRedis.disconnect();
+      const keysA = await testRedis.redis.keys(`bull:${prefixA}-worker:*`);
+      if (keysA.length > 0) await testRedis.redis.del(...keysA);
+      const keysB = await testRedis.redis.keys(`bull:${prefixB}-worker:*`);
+      if (keysB.length > 0) await testRedis.redis.del(...keysB);
+    }
   });
 
   test("lock is released even when the handler throws", async () => {

package/src/jobs/job-runner.ts

@@ -550,7 +550,12 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       log("lock redis connection error", { error: err.message });
     });
     const lockScope = consumerLane ?? "enqueue";
-    sequentialLock = createDistributedLock(lockRedis, `${RedisKeys.lock}seq:${lockScope}:`);
+    // Scoped by queueNamePrefix like the queues themselves, so runners
+    // isolated by prefix on a shared Redis don't contend for the same lock.
+    sequentialLock = createDistributedLock(
+      lockRedis,
+      `${RedisKeys.lock}seq:${queueNamePrefix}:${lockScope}:`,
+    );
   }
   // Default lock-TTL for sequential jobs that didn't declare a timeout.
   // 5 minutes matches BullMQ's default stalledInterval — long enough for

package/src/rate-limit/__tests__/middleware.integration.test.ts

@@ -28,7 +28,16 @@ describe("globalIpRateLimit (L1)", () => {
     const app = new Hono();
     app.use(
       "/api/*",
-      globalIpRateLimit({ resolver, limit: 3, windowSeconds: 60, onFailClosed: () => {} }),
+      // trustedProxyHops: 1 — the default hops=0 ignores x-forwarded-for
+      // outright, which would collapse the bucket
+      // assertion below onto "l1:unknown" instead of the literal IP.
+      globalIpRateLimit({
+        resolver,
+        limit: 3,
+        windowSeconds: 60,
+        trustedProxyHops: 1,
+        onFailClosed: () => {},
+      }),
     );
     app.get("/api/probe", (c) => c.text("ok"));
 
@@ -56,7 +65,13 @@ describe("globalIpRateLimit (L1)", () => {
     const app = new Hono();
     app.use(
       "/api/*",
-      globalIpRateLimit({ resolver, limit: 2, windowSeconds: 60, onFailClosed: () => {} }),
+      globalIpRateLimit({
+        resolver,
+        limit: 2,
+        windowSeconds: 60,
+        trustedProxyHops: 1,
+        onFailClosed: () => {},
+      }),
     );
     app.get("/api/probe", (c) => c.text("ok"));
 
@@ -73,7 +88,11 @@ describe("globalIpRateLimit (L1)", () => {
     expect(otherIp.status).toBe(200);
   });
 
-  test("no x-forwarded-for: pass-through (no bucket)", async () => {
+  // The built-in resolver never returns undefined — no x-forwarded-for (or
+  // an untrusted one at hops=0) falls back to a fixed "unknown" bucket
+  // instead of skipping the middleware: skipping would fail open, letting
+  // an attacker omit/rotate the header to dodge L1 entirely.
+  test("no x-forwarded-for: still enforced via the shared 'unknown' bucket, never skipped", async () => {
     const app = new Hono();
     app.use(
       "/api/*",
@@ -81,12 +100,10 @@ describe("globalIpRateLimit (L1)", () => {
     );
     app.get("/api/probe", (c) => c.text("ok"));
 
-    // No xff header — extractIp returns undefined → middleware skips.
-    // Both calls succeed even though limit=1.
     const a = await app.request("/api/probe");
-    const b = await app.request("/api/probe");
     expect(a.status).toBe(200);
-    expect(b.status).toBe(200);
+    const b = await app.request("/api/probe");
+    expect(b.status).toBe(429);
   });
 
   test("fail-closed when resolver throws non-RateLimit error (Redis down)", async () => {

package/src/rate-limit/middleware.ts

@@ -1,5 +1,10 @@
 import type { Context, MiddlewareHandler } from "hono";
 import { isAuthRateLimitExempt } from "../api/api-constants";
+import {
+  type ClientIpResolver,
+  clientIpSourceFromHonoContext,
+  createClientIpResolver,
+} from "../api/client-ip";
 import { requestContext } from "../api/request-context";
 import { RateLimitError, serializeError } from "../errors";
 import type { RateLimitDecision, RateLimitResolver } from "./resolver";
@@ -22,8 +27,17 @@ export type GlobalIpRateLimitOptions = {
   readonly resolver: RateLimitResolver;
   readonly limit?: number;
   readonly windowSeconds?: number;
+  // Number of trusted reverse-proxy hops for the default client-IP
+  // resolver — see createClientIpResolver. Ignored when `extractIp` is set.
+  // Default 0 (no proxy trusted).
+  readonly trustedProxyHops?: number;
+  // Shared resolver instance from buildServer — takes precedence over
+  // `trustedProxyHops` so the whole server has exactly one resolver (and
+  // one warn-once flag) rather than one per middleware.
+  // Only standalone callers (no buildServer) should rely on `trustedProxyHops`.
+  readonly clientIpResolver?: ClientIpResolver;
   // Override IP extraction — useful when behind a non-standard proxy.
-  // Default: x-forwarded-for first hop.
+  // Default: the shared resolveClientIp, honoring `trustedProxyHops`.
   readonly extractIp?: (c: Context) => string | undefined;
   // Hook for ops logging when fail-closed fires (Redis down). Default:
   // emits to console.error so the misbehaviour is loud at minimum.
@@ -33,7 +47,11 @@ export type GlobalIpRateLimitOptions = {
 export function globalIpRateLimit(opts: GlobalIpRateLimitOptions): MiddlewareHandler {
   const limit = opts.limit ?? 1000;
   const windowSeconds = opts.windowSeconds ?? 60;
-  const extractIp = opts.extractIp ?? defaultExtractIp;
+  const clientIpResolver =
+    opts.clientIpResolver ??
+    createClientIpResolver(opts.trustedProxyHops ?? 0, "globalIpRateLimit");
+  const extractIp =
+    opts.extractIp ?? ((c) => clientIpResolver.resolve(clientIpSourceFromHonoContext(c)));
   const onFailClosed = opts.onFailClosed ?? defaultOnFailClosed("l1-global-ip");
 
   return async (c, next) => {
@@ -73,6 +91,13 @@ export type AuthEndpointRateLimitOptions = {
   // top of IP. Default: bucket on `l2:${ip}:${path}` (IP + route),
   // which catches naive IP-flood without consuming the request body.
   readonly extractTarget?: (c: Context) => string | undefined | Promise<string | undefined>;
+  // Number of trusted reverse-proxy hops for the default client-IP
+  // resolver — see createClientIpResolver. Ignored when `extractIp` is set.
+  // Default 0 (no proxy trusted).
+  readonly trustedProxyHops?: number;
+  // See GlobalIpRateLimitOptions.clientIpResolver — same single-resolver
+  // rationale.
+  readonly clientIpResolver?: ClientIpResolver;
   readonly extractIp?: (c: Context) => string | undefined;
   readonly onFailClosed?: (err: unknown) => void;
 };
@@ -80,7 +105,11 @@ export type AuthEndpointRateLimitOptions = {
 export function authEndpointRateLimit(opts: AuthEndpointRateLimitOptions): MiddlewareHandler {
   const limit = opts.limit ?? 5;
   const windowSeconds = opts.windowSeconds ?? 60;
-  const extractIp = opts.extractIp ?? defaultExtractIp;
+  const clientIpResolver =
+    opts.clientIpResolver ??
+    createClientIpResolver(opts.trustedProxyHops ?? 0, "authEndpointRateLimit");
+  const extractIp =
+    opts.extractIp ?? ((c) => clientIpResolver.resolve(clientIpSourceFromHonoContext(c)));
   const extractTarget = opts.extractTarget;
   const onFailClosed = opts.onFailClosed ?? defaultOnFailClosed("l2-auth-endpoints");
 
@@ -110,11 +139,6 @@ export function authEndpointRateLimit(opts: AuthEndpointRateLimitOptions): Middl
   };
 }
 
-function defaultExtractIp(c: Context): string | undefined {
-  const xff = c.req.header("x-forwarded-for");
-  return xff?.split(",")[0]?.trim() || undefined;
-}
-
 function defaultOnFailClosed(label: string): (err: unknown) => void {
   return (err) => {
     // Loud by default — fail-closed for an unknown reason is an ops