@podosoft/podokit 1.4.2 → 1.6.0

package/dist/templates/modules/object-storage-s3/files/infra/docker/minio.compose.yml

@@ -24,12 +24,13 @@ services:
     profiles: ["dev"]
     depends_on:
       - minio
+    # -e stops at the first failing command, so a bucket that cannot be
+    # created fails this service instead of leaving uploads to fail later.
     entrypoint: >
-      /bin/sh -c "
+      /bin/sh -ec "
       until mc alias set local http://minio:9000 ${S3_ACCESS_KEY_ID:-podokit} ${S3_SECRET_ACCESS_KEY:-podokitsecret}; do echo 'waiting for minio'; sleep 1; done;
-      mc mb -p local/${S3_BUCKET:-podokit};
-      echo 'bucket ready';
-      exit 0"
+      mc mb --ignore-existing local/${S3_BUCKET:-podokit};
+      echo 'bucket ready'"
 
 volumes:
   minio-data:

package/dist/templates/modules/object-storage-s3/files/tests/api/storage.api.spec.ts

@@ -5,7 +5,7 @@ const origin = { origin: base };
 // The administrator seeded by the admin-dashboard Playwright setup. Inlined so this
 // spec also compiles in apps that do not install that module.
 const admin = {
-  email: "admin@example.com",
+  email: process.env.E2E_ADMIN_EMAIL || "admin@example.com",
   password: process.env.E2E_ADMIN_PASSWORD || "Podokit3e-Str0ng!pw",
 };
 

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.config.spec.ts

@@ -1,12 +1,8 @@
 import { describe, expect, test } from "bun:test";
-import {
-  clientAddressFromProxy,
-  rateLimitConfig,
-  sessionSigningSecret,
-} from "./rate-limit.config";
+import { rateLimitConfig, sessionSigningSecret } from "./rate-limit.config";
 
 describe("rate limit configuration", () => {
-  test("validates route limits and proxy settings", () => {
+  test("validates route limits", () => {
     expect(
       rateLimitConfig({
         RATE_LIMIT_KEY_PREFIX: "podokit:tenant-a:rate-limit",
@@ -15,8 +11,6 @@ describe("rate limit configuration", () => {
         RATE_LIMIT_AUTH_TTL: "45",
         RATE_LIMIT_AUTH_MAX: "15",
         RATE_LIMIT_RUNTIME_MAX: "900",
-        RATE_LIMIT_TRUSTED_PROXY_HOPS: "2",
-        RATE_LIMIT_PROXY_HEADER: "X-Real-IP",
         RATE_LIMIT_STORAGE_TIMEOUT_MS: "750",
         RATE_LIMIT_UNAVAILABLE_RETRY_AFTER: "3",
       }),
@@ -27,69 +21,18 @@ describe("rate limit configuration", () => {
       authTtlSeconds: 45,
       authLimit: 15,
       runtimeLimit: 900,
-      trustedProxyHops: 2,
-      proxyHeader: "x-real-ip",
       storageTimeoutMs: 750,
       unavailableRetryAfterSeconds: 3,
     });
     expect(() => rateLimitConfig({ RATE_LIMIT_MAX: "0" })).toThrow(
       "RATE_LIMIT_MAX must be a positive integer",
     );
-    expect(() =>
-      rateLimitConfig({ RATE_LIMIT_TRUSTED_PROXY_HOPS: "-1" }),
-    ).toThrow("must be a non-negative integer");
-    expect(() =>
-      rateLimitConfig({ RATE_LIMIT_PROXY_HEADER: "invalid header" }),
-    ).toThrow("must be a valid HTTP header name");
     expect(() => rateLimitConfig({ RATE_LIMIT_KEY_PREFIX: "invalid prefix!" })).toThrow(
       "RATE_LIMIT_KEY_PREFIX must be 1-128 characters",
     );
     expect(rateLimitConfig({}).keyPrefix).toBe("podokit:rate-limit");
   });
 
-  test("selects only the address outside the configured trusted proxy depth", () => {
-    const headers = {
-      "x-forwarded-for": "203.0.113.7, 198.51.100.8",
-    };
-    expect(
-      clientAddressFromProxy(headers, "10.0.0.9", {
-        proxyHeader: "x-forwarded-for",
-        trustedProxyHops: 2,
-      }),
-    ).toBe("203.0.113.7");
-    expect(
-      clientAddressFromProxy(headers, "10.0.0.9", {
-        proxyHeader: "x-forwarded-for",
-        trustedProxyHops: 1,
-      }),
-    ).toBe("198.51.100.8");
-    expect(
-      clientAddressFromProxy(headers, "10.0.0.9", {
-        proxyHeader: "x-forwarded-for",
-        trustedProxyHops: 0,
-      }),
-    ).toBe("10.0.0.9");
-  });
-
-  test("ignores malformed or incomplete forwarded chains", () => {
-    expect(
-      clientAddressFromProxy(
-        { "x-forwarded-for": "attacker-controlled" },
-        "::ffff:10.0.0.9",
-        {
-          proxyHeader: "x-forwarded-for",
-          trustedProxyHops: 1,
-        },
-      ),
-    ).toBe("10.0.0.9");
-    expect(
-      clientAddressFromProxy({}, "10.0.0.9", {
-        proxyHeader: "x-forwarded-for",
-        trustedProxyHops: 1,
-      }),
-    ).toBe("10.0.0.9");
-  });
-
   test("reads the session signing secret the way the auth module does", () => {
     expect(
       sessionSigningSecret({ BETTER_AUTH_SECRET: "  session-secret-with-at-least-32-chars  " }),

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.config.ts

@@ -1,5 +1,3 @@
-import { isIP } from "node:net";
-
 export interface RateLimitConfig {
   keyPrefix: string;
   ttlSeconds: number;
@@ -7,8 +5,6 @@ export interface RateLimitConfig {
   authTtlSeconds: number;
   authLimit: number;
   runtimeLimit: number;
-  trustedProxyHops: number;
-  proxyHeader: string;
   storageTimeoutMs: number;
   unavailableRetryAfterSeconds: number;
 }
@@ -32,23 +28,6 @@ function positiveInteger(name: string, value: string | undefined, fallback: numb
   return parsed;
 }
 
-function nonNegativeInteger(name: string, value: string | undefined, fallback: number): number {
-  if (value === undefined || value === "") return fallback;
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed < 0) {
-    throw new Error(`${name} must be a non-negative integer`);
-  }
-  return parsed;
-}
-
-function headerName(value: string | undefined): string {
-  const normalized = (value || "x-forwarded-for").trim().toLowerCase();
-  if (!/^[a-z0-9!#$%&'*+.^_`|~-]+$/.test(normalized)) {
-    throw new Error("RATE_LIMIT_PROXY_HEADER must be a valid HTTP header name");
-  }
-  return normalized;
-}
-
 export function rateLimitConfig(env: NodeJS.ProcessEnv = process.env): RateLimitConfig {
   return {
     keyPrefix: keyPrefix(env.RATE_LIMIT_KEY_PREFIX),
@@ -65,12 +44,6 @@ export function rateLimitConfig(env: NodeJS.ProcessEnv = process.env): RateLimit
       env.RATE_LIMIT_RUNTIME_MAX,
       1000,
     ),
-    trustedProxyHops: nonNegativeInteger(
-      "RATE_LIMIT_TRUSTED_PROXY_HOPS",
-      env.RATE_LIMIT_TRUSTED_PROXY_HOPS,
-      0,
-    ),
-    proxyHeader: headerName(env.RATE_LIMIT_PROXY_HEADER),
     storageTimeoutMs: positiveInteger(
       "RATE_LIMIT_STORAGE_TIMEOUT_MS",
       env.RATE_LIMIT_STORAGE_TIMEOUT_MS,
@@ -90,41 +63,3 @@ export function rateLimitConfig(env: NodeJS.ProcessEnv = process.env): RateLimit
 export function sessionSigningSecret(env: NodeJS.ProcessEnv = process.env): string | undefined {
   return env.BETTER_AUTH_SECRET?.trim() || undefined;
 }
-
-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;
-}
-
-function headerValue(headers: unknown, name: string): string | undefined {
-  if (headers instanceof Headers) return headers.get(name) ?? undefined;
-  if (!headers || typeof headers !== "object") return undefined;
-  const value = (headers as Record<string, unknown>)[name];
-  if (typeof value === "string") return value;
-  if (!Array.isArray(value)) return undefined;
-  const strings = value.filter((item): item is string => typeof item === "string");
-  return strings.length > 0 ? strings.join(",") : undefined;
-}
-
-export function clientAddressFromProxy(
-  headers: unknown,
-  remoteAddress: string | undefined,
-  config: Pick<RateLimitConfig, "proxyHeader" | "trustedProxyHops">,
-): string {
-  const direct = normalizeIp(remoteAddress) ?? "unknown";
-  if (config.trustedProxyHops === 0) return direct;
-
-  const forwarded = headerValue(headers, config.proxyHeader)
-    ?.split(",")
-    .map((value) => value.trim())
-    .filter(Boolean) ?? [];
-  const chain = [...forwarded, direct];
-  if (chain.length <= config.trustedProxyHops) return direct;
-
-  const selected = chain[chain.length - config.trustedProxyHops - 1];
-  return normalizeIp(selected) ?? direct;
-}

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.identity.spec.ts

@@ -9,10 +9,12 @@ import {
   RATE_LIMIT_IDENTITY_EXTENSION,
   RateLimitIdentity,
   RateLimitIdentityExtension,
+  SessionUsers,
   verifiedSessionToken,
 } from "./rate-limit.identity";
 
-const proxyConfig = { proxyHeader: "x-forwarded-for", trustedProxyHops: 1 };
+// The address the API resolved for the request (see core/client-address.ts).
+const clientAddress = "203.0.113.7";
 const secret = "rate-limit-test-secret-with-at-least-32-characters";
 const sessionToken = "Sx0d8mFqY3KcT7wJpLr2NvBhZa9EgUi4";
 
@@ -63,8 +65,7 @@ describe("RateLimitIdentity", () => {
 
     const value = await identity.resolve(
       request({ cookie: sessionCookie(signed(sessionToken)) }),
-      "10.0.0.9",
-      proxyConfig,
+      clientAddress,
     );
 
     expect(value).toMatch(/^session:[a-f0-9]{64}$/);
@@ -76,25 +77,22 @@ describe("RateLimitIdentity", () => {
     const identity = new RateLimitIdentity(rejectingVerifier(), new ServiceRegistry(), secret);
     const value = signed(sessionToken);
     const resolved = await Promise.all([
-      identity.resolve(request({ cookie: sessionCookie(value) }), "10.0.0.9", proxyConfig),
+      identity.resolve(request({ cookie: sessionCookie(value) }), clientAddress),
       identity.resolve(
         request({ cookie: sessionCookie(value, "__Secure-better-auth.session_token") }),
-        "10.0.0.9",
-        proxyConfig,
+        clientAddress,
       ),
-      identity.resolve(request({ authorization: `Bearer ${value}` }), "10.0.0.9", proxyConfig),
+      identity.resolve(request({ authorization: `Bearer ${value}` }), clientAddress),
       identity.resolve(
         request({ authorization: `bearer ${encodeURIComponent(value)}` }),
-        "10.0.0.9",
-        proxyConfig,
+        clientAddress,
       ),
     ]);
     expect(new Set(resolved).size).toBe(1);
 
     const other = await identity.resolve(
       request({ cookie: sessionCookie(signed("AnotherSessionToken0123456789abcd")) }),
-      "10.0.0.9",
-      proxyConfig,
+      clientAddress,
     );
     expect(other).toMatch(/^session:/);
     expect(other).not.toBe(resolved[0]);
@@ -103,7 +101,7 @@ describe("RateLimitIdentity", () => {
   test("counts forged, tampered, and unsigned session values by client address", async () => {
     const identity = new RateLimitIdentity(rejectingVerifier(), new ServiceRegistry(), secret);
     const address = { "x-forwarded-for": "203.0.113.7" };
-    const anonymous = await identity.resolve(request(address), "10.0.0.9", proxyConfig);
+    const anonymous = await identity.resolve(request(address), clientAddress);
     expect(anonymous).toMatch(/^ip:[a-f0-9]{64}$/);
 
     const genuine = signed(sessionToken);
@@ -123,8 +121,7 @@ describe("RateLimitIdentity", () => {
       for (const headers of variants) {
         const value = await identity.resolve(
           request({ ...address, ...headers }),
-          "10.0.0.9",
-          proxyConfig,
+          clientAddress,
         );
         expect(value).toBe(anonymous);
       }
@@ -148,8 +145,7 @@ describe("RateLimitIdentity", () => {
     for (const raw of ["configured-valid", "external-valid"]) {
       const value = await identity.resolve(
         request({ "x-api-key": raw, cookie }),
-        "10.0.0.9",
-        proxyConfig,
+        clientAddress,
       );
       expect(value).toMatch(/^api-key:[a-f0-9]{64}$/);
       expect(value).not.toContain(raw);
@@ -157,8 +153,7 @@ describe("RateLimitIdentity", () => {
 
     const invalidKey = await identity.resolve(
       request({ "x-api-key": "invalid", cookie }),
-      "10.0.0.9",
-      proxyConfig,
+      clientAddress,
     );
     expect(invalidKey).toMatch(/^session:/);
   });
@@ -169,17 +164,83 @@ describe("RateLimitIdentity", () => {
     const identity = new RateLimitIdentity(rejectingVerifier(), new ServiceRegistry(), undefined);
     const value = await identity.resolve(
       request({ "x-forwarded-for": "203.0.113.7", cookie }),
-      "10.0.0.9",
-      proxyConfig,
+      clientAddress,
     );
     expect(value).toMatch(/^ip:[a-f0-9]{64}$/);
     expect(value).not.toContain("203.0.113.7");
     expect(
-      await identity.resolve(request({ "x-forwarded-for": "203.0.113.7" }), "10.0.0.9", proxyConfig),
+      await identity.resolve(request({ "x-forwarded-for": "203.0.113.7" }), clientAddress),
     ).toBe(value);
   });
 });
 
+describe("RateLimitIdentity per user", () => {
+  const otherToken = "AnotherSessionToken0123456789abcd";
+  const thirdToken = "ThirdSessionToken0123456789abcdef";
+  const resolveWith = (identity: RateLimitIdentity, headers: Record<string, string>): Promise<string> =>
+    identity.resolve(request({ "x-forwarded-for": "203.0.113.7", ...headers }), clientAddress);
+
+  test("counts every session of a user under one counter once the API resolved them", async () => {
+    let now = 1_000;
+    const users = new SessionUsers(100, () => now);
+    const identity = new RateLimitIdentity(rejectingVerifier(), new ServiceRegistry(), secret, users);
+    const first = { cookie: sessionCookie(signed(sessionToken)) };
+    const second = { authorization: `Bearer ${signed(otherToken)}` };
+
+    // Before the API resolves a session, it keeps a counter of its own.
+    const unresolved = await resolveWith(identity, first);
+    expect(unresolved).toMatch(/^session:[a-f0-9]{64}$/);
+
+    users.remember(sessionToken, "user-1", new Date(now + 60_000));
+    users.remember(otherToken, "user-1", new Date(now + 60_000));
+    users.remember(thirdToken, "user-2", new Date(now + 60_000));
+    const userCounter = await resolveWith(identity, first);
+    expect(userCounter).toMatch(/^user:[a-f0-9]{64}$/);
+    expect(userCounter).not.toContain("user-1");
+    expect(await resolveWith(identity, second)).toBe(userCounter);
+    expect(await resolveWith(identity, { cookie: sessionCookie(signed(thirdToken)) })).not.toBe(userCounter);
+
+    // The entry lasts until the session expires.
+    now += 60_000;
+    expect(await resolveWith(identity, first)).toBe(unresolved);
+  });
+
+  test("keeps API keys first and forged sessions on the client address", async () => {
+    const users = new SessionUsers();
+    users.remember(sessionToken, "user-1", new Date(Date.now() + 60_000));
+    const verifier = { isValid: mock((value: string) => value === "configured-valid") } as unknown as ApiKeyVerifier;
+    const identity = new RateLimitIdentity(verifier, new ServiceRegistry(), secret, users);
+    const cookie = sessionCookie(signed(sessionToken));
+
+    expect(await resolveWith(identity, { "x-api-key": "configured-valid", cookie })).toMatch(/^api-key:/);
+    expect(await resolveWith(identity, { cookie: sessionCookie(tamperedSignature(signed(sessionToken))) }))
+      .toBe(await resolveWith(identity, {}));
+    expect(await resolveWith(identity, {})).toMatch(/^ip:/);
+  });
+});
+
+describe("SessionUsers", () => {
+  test("ignores an expired session and forgets the oldest past its bound", () => {
+    let now = 1_000;
+    const users = new SessionUsers(2, () => now);
+    users.remember("expired", "user-0", new Date(now));
+    expect(users.userOf("expired")).toBeUndefined();
+
+    users.remember("a", "user-a", new Date(now + 10_000));
+    users.remember("b", "user-b", new Date(now + 10_000));
+    users.remember("a", "user-a", new Date(now + 20_000));
+    users.remember("c", "user-c", new Date(now + 10_000));
+    // "a" was refreshed, so "b" was the oldest.
+    expect(users.userOf("a")).toBe("user-a");
+    expect(users.userOf("b")).toBeUndefined();
+    expect(users.userOf("c")).toBe("user-c");
+
+    now += 10_000;
+    expect(users.userOf("c")).toBeUndefined();
+    expect(users.userOf("a")).toBe("user-a");
+  });
+});
+
 describe("verifiedSessionToken", () => {
   test("returns the token only for a matching signature", () => {
     expect(verifiedSessionToken(signed(sessionToken), secret)).toBe(sessionToken);

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.identity.ts

@@ -1,10 +1,6 @@
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import type { ApiKeyVerifier } from "../api-key/api-key-verifier";
 import type { ServiceKey, ServiceRegistry } from "../core/services";
-import {
-  clientAddressFromProxy,
-  type RateLimitConfig,
-} from "./rate-limit.config";
 
 export abstract class RateLimitIdentityExtension {
   abstract validatedApiKeyId(
@@ -28,7 +24,7 @@ const SESSION_COOKIE_NAMES = [
 // accepts only the padded 44-character standard base64 signature.
 const SIGNATURE = /^[A-Za-z0-9+/]{43}=$/;
 
-type TrackerKind = "session" | "api-key" | "ip";
+type TrackerKind = "user" | "session" | "api-key" | "ip";
 
 function stableDigest(kind: TrackerKind, value: string): string {
   return createHash("sha256")
@@ -85,18 +81,57 @@ export function verifiedSessionToken(
     : undefined;
 }
 
+/** The most sessions one API process remembers; the oldest is forgotten first. */
+const MAX_SESSION_USERS = 10_000;
+
+/**
+ * The users of the sessions this API process has resolved, so the limiter can
+ * count a signed-in caller per user without a session lookup of its own. Each
+ * entry lasts until its session expires, and is refreshed whenever the session
+ * is resolved again. A signed-out or revoked session keeps its entry: it only
+ * decides which counter its requests use, never whether they are allowed.
+ */
+export class SessionUsers {
+  private readonly users = new Map<string, { userId: string; expiresAt: number }>();
+
+  constructor(
+    private readonly maxEntries = MAX_SESSION_USERS,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  remember(sessionToken: string, userId: string, expiresAt: Date): void {
+    const key = stableDigest("session", sessionToken);
+    this.users.delete(key);
+    if (!(expiresAt.getTime() > this.now())) return;
+    this.users.set(key, { userId, expiresAt: expiresAt.getTime() });
+    if (this.users.size > this.maxEntries) {
+      const oldest = this.users.keys().next().value;
+      if (oldest !== undefined) this.users.delete(oldest);
+    }
+  }
+
+  userOf(sessionToken: string): string | undefined {
+    const key = stableDigest("session", sessionToken);
+    const entry = this.users.get(key);
+    if (!entry) return undefined;
+    if (entry.expiresAt <= this.now()) {
+      this.users.delete(key);
+      return undefined;
+    }
+    return entry.userId;
+  }
+}
+
 export class RateLimitIdentity {
   constructor(
     private readonly configuredApiKeys: ApiKeyVerifier,
     private readonly services: ServiceRegistry,
     private readonly sessionSecret: string | undefined,
+    private readonly sessionUsers: SessionUsers = new SessionUsers(),
   ) {}
 
-  async resolve(
-    request: Request,
-    remoteAddress: string | undefined,
-    config: Pick<RateLimitConfig, "proxyHeader" | "trustedProxyHops">,
-  ): Promise<string> {
+  /** clientAddress is the address the API resolved behind its trusted proxies. */
+  async resolve(request: Request, clientAddress: string | undefined): Promise<string> {
     const rawApiKey = request.headers.get("x-api-key");
     if (rawApiKey) {
       if (this.configuredApiKeys.isValid(rawApiKey)) return tracker("api-key", rawApiKey);
@@ -106,15 +141,19 @@ export class RateLimitIdentity {
     }
 
     const sessionToken = this.sessionToken(request.headers);
-    if (sessionToken) return tracker("session", sessionToken);
+    if (sessionToken) {
+      const userId = this.sessionUsers.userOf(sessionToken);
+      return userId === undefined ? tracker("session", sessionToken) : tracker("user", userId);
+    }
 
-    const clientAddress = clientAddressFromProxy(request.headers, remoteAddress, config);
-    return tracker("ip", clientAddress);
+    return tracker("ip", clientAddress ?? "unknown");
   }
 
   // Only the signature is checked: resolving the session would cost a database
-  // read on every request. A revoked or expired token still maps to its single
-  // counter, and a value without a valid signature falls back to the client address.
+  // read on every request. Once the API has resolved the session for a request,
+  // SessionUsers maps it to its user's counter; until then, and for a revoked or
+  // expired token, it keeps a counter of its own. A value without a valid
+  // signature falls back to the client address.
   private sessionToken(headers: Headers): string | undefined {
     if (!this.sessionSecret) return undefined;
     const cookies = headers.get("cookie");

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.module.spec.ts

@@ -1,6 +1,8 @@
 import { describe, expect, mock, test } from "bun:test";
-import type { RequestGuardContext } from "../core/services";
-import type { RateLimitIdentity } from "./rate-limit.identity";
+import { createHmac } from "node:crypto";
+import type { ApiKeyVerifier } from "../api-key/api-key-verifier";
+import { RESOLVED_SESSIONS, ResolvedSessions, ServiceRegistry, type RequestGuardContext } from "../core/services";
+import { RateLimitIdentity, SessionUsers } from "./rate-limit.identity";
 import { CacheRateLimitStorage, RateLimiter, type RateLimitStorage } from "./rate-limit.module";
 import { MemoryCacheStore } from "@podosoft/podokit-runtime";
 
@@ -11,8 +13,6 @@ const config = {
   authTtlSeconds: 60,
   authLimit: 20,
   runtimeLimit: 1000,
-  trustedProxyHops: 0,
-  proxyHeader: "x-forwarded-for",
   storageTimeoutMs: 100,
   unavailableRetryAfterSeconds: 1,
 };
@@ -26,12 +26,50 @@ function context(path: string, method = "GET"): {
     headers,
     value: {
       request: new Request(`http://localhost${path}`, { method }),
-      remoteAddress: "127.0.0.1",
+      clientAddress: "127.0.0.1",
       setHeader: (name, value) => { headers[name.toLowerCase()] = value; },
     },
   };
 }
 
+describe("RateLimiter per-user budgets", () => {
+  const secret = "rate-limit-test-secret-with-at-least-32-characters";
+  const signed = (token: string): string =>
+    `${token}.${createHmac("sha256", secret).update(token).digest("base64")}`;
+
+  test("draws a user's sessions from one budget and another user's from its own", async () => {
+    const services = new ServiceRegistry();
+    services.register(RESOLVED_SESSIONS, new ResolvedSessions());
+    const users = new SessionUsers();
+    services.resolve(RESOLVED_SESSIONS).listen(({ token, userId, expiresAt }) => users.remember(token, userId, expiresAt));
+    const limiter = new RateLimiter(
+      config,
+      new RateLimitIdentity({ isValid: () => false } as unknown as ApiKeyVerifier, services, secret, users),
+      new CacheRateLimitStorage(new MemoryCacheStore()),
+    );
+    const expiresAt = new Date(Date.now() + 60_000);
+    for (const [token, userId] of [["laptop", "user-1"], ["phone", "user-1"], ["other", "user-2"]] as const) {
+      services.resolve(RESOLVED_SESSIONS).report({ token, userId, expiresAt });
+    }
+    const remaining = async (token: string): Promise<string | undefined> => {
+      const headers: Record<string, string> = {};
+      await limiter.enforce({
+        request: new Request("http://localhost/ordinary", { headers: { authorization: `Bearer ${signed(token)}` } }),
+        clientAddress: "127.0.0.1",
+        setHeader: (name, value) => { headers[name.toLowerCase()] = value; },
+      });
+      return headers["ratelimit-remaining"];
+    };
+
+    expect(await remaining("laptop")).toBe("299");
+    expect(await remaining("phone")).toBe("298");
+    expect(await remaining("laptop")).toBe("297");
+    expect(await remaining("other")).toBe("299");
+    // A session the API has not resolved yet keeps a counter of its own.
+    expect(await remaining("tablet")).toBe("299");
+  });
+});
+
 describe("RateLimiter", () => {
   test("uses the selected cache fixed-window primitive", async () => {
     let now = 1_000;

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.module.ts

@@ -3,6 +3,7 @@ import { AppException } from "../common/app-exception";
 import { API_KEY_VERIFIER } from "../api-key/api-key.module";
 import {
   REQUEST_GUARDS,
+  RESOLVED_SESSIONS,
   type PodokitModule,
   type RequestGuardContext,
   type ServiceKey,
@@ -12,7 +13,7 @@ import {
   sessionSigningSecret,
   type RateLimitConfig,
 } from "./rate-limit.config";
-import { RateLimitIdentity } from "./rate-limit.identity";
+import { RateLimitIdentity, SessionUsers } from "./rate-limit.identity";
 import { defaultRateLimitRoutes, generalProfile, type RateLimitRoutes } from "./rate-limit.routes";
 
 export { RATE_LIMIT_ROUTES } from "@podosoft/podokit-runtime";
@@ -61,7 +62,7 @@ export class RateLimiter {
     const profile = this.routes.resolve(request.method, path) ?? generalProfile(this.config);
     if (profile === "exempt") return;
     try {
-      const tracker = await this.identity.resolve(request, context.remoteAddress, this.config);
+      const tracker = await this.identity.resolve(request, context.clientAddress);
       await this.enforceCustom(profile.name, tracker, profile.ttlSeconds, profile.limit, context.setHeader);
     } catch (error) {
       if (error instanceof AppException) throw error;
@@ -125,12 +126,19 @@ export const RATE_LIMITER = Symbol("rate-limiter") as ServiceKey<RateLimiter>;
 export const rateLimitModule: PodokitModule = {
   name: "rate-limit",
   configure: (_env, services): void => {
+    // Sessions the auth module resolves for any request teach the limiter their
+    // users, so a user's sessions share one counter without another lookup.
+    const sessionUsers = new SessionUsers();
+    services.resolve(RESOLVED_SESSIONS).listen(({ token, userId, expiresAt }) =>
+      sessionUsers.remember(token, userId, expiresAt),
+    );
     const limiter = new RateLimiter(
       rateLimitConfig(),
       new RateLimitIdentity(
         services.resolve(API_KEY_VERIFIER),
         services,
         sessionSigningSecret(),
+        sessionUsers,
       ),
       new CacheRateLimitStorage(services.resolve(CACHE)),
     );