@podosoft/podokit 1.4.2 → 1.5.0

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

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

@@ -11,8 +11,6 @@ const config = {
   authTtlSeconds: 60,
   authLimit: 20,
   runtimeLimit: 1000,
-  trustedProxyHops: 0,
-  proxyHeader: "x-forwarded-for",
   storageTimeoutMs: 100,
   unavailableRetryAfterSeconds: 1,
 };
@@ -25,7 +23,7 @@ function context(path: string, method = "GET"): { value: RequestGuardContext; he
     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; },
     },
   };
@@ -50,11 +48,49 @@ describe("RateLimitRoutes", () => {
     expect(routes.resolve("GET", "/other")).toBeUndefined();
   });
 
+  test("matches a :name parameter against exactly one non-empty segment", () => {
+    const routes = new RateLimitRoutes(60);
+    const transfers = { name: "file-transfers", limit: 600 };
+    routes.register({ pathPrefix: "/hosts/:hostId/file-transfers", profile: transfers });
+
+    expect(routes.resolve("PUT", "/hosts/h1/file-transfers/t1/chunks/3")).toMatchObject(transfers);
+    expect(routes.resolve("GET", "/hosts/h1/file-transfers")).toMatchObject(transfers);
+    expect(routes.resolve("GET", "/hosts/h1/file-transfers/")).toMatchObject(transfers);
+    expect(routes.resolve("GET", "/hosts/h1/file-transfers-old")).toBeUndefined();
+    expect(routes.resolve("GET", "/hosts/file-transfers")).toBeUndefined();
+    expect(routes.resolve("GET", "/hosts//file-transfers")).toBeUndefined();
+    expect(routes.resolve("GET", "/hosts/h1/h2/file-transfers")).toBeUndefined();
+  });
+
+  test("prefers more segments, then a literal segment over a parameter from the left", () => {
+    const routes = new RateLimitRoutes(60);
+    routes.register({ pathPrefix: "/hosts/:hostId/:section/:id", profile: { name: "deep", limit: 1 } });
+    routes.register({ pathPrefix: "/hosts/:hostId/files", profile: { name: "files", limit: 2 } });
+    routes.register({ pathPrefix: "/hosts/local/:section", profile: { name: "local", limit: 3 } });
+    routes.register({ pathPrefix: "/hosts", profile: { name: "hosts", limit: 4 } });
+
+    expect(routes.resolve("GET", "/hosts/local/files/1")).toMatchObject({ name: "deep" });
+    expect(routes.resolve("GET", "/hosts/local/files")).toMatchObject({ name: "local" });
+    expect(routes.resolve("GET", "/hosts/h2/files")).toMatchObject({ name: "files" });
+    expect(routes.resolve("GET", "/hosts/h2/logs")).toMatchObject({ name: "hosts" });
+
+    // Equal specificity falls back to the method, then the latest registration.
+    routes.register({ method: "GET", pathPrefix: "/hosts/:a/logs", profile: "exempt" });
+    routes.register({ pathPrefix: "/hosts/:b/logs", profile: { name: "logs", limit: 5 } });
+    expect(routes.resolve("GET", "/hosts/h2/logs")).toBe("exempt");
+    expect(routes.resolve("POST", "/hosts/h2/logs")).toMatchObject({ name: "logs" });
+  });
+
   test("rejects invalid routes and conflicting budgets under one name", () => {
     const routes = new RateLimitRoutes(60);
     expect(() => routes.register({ pathPrefix: "uploads", profile: "exempt" })).toThrow("absolute path");
     expect(() => routes.register({ pathPrefix: "/a?b", profile: "exempt" })).toThrow("absolute path");
     expect(() => routes.register({ pathPrefix: "/a//b", profile: "exempt" })).toThrow("absolute path");
+    expect(() => routes.register({ pathPrefix: "/a/../b", profile: "exempt" })).toThrow('".." segments');
+    expect(() => routes.register({ pathPrefix: "/a/*", profile: "exempt" })).toThrow("not wildcards");
+    for (const parameter of [":", ":1st", ":host-id", ":a:b"]) {
+      expect(() => routes.register({ pathPrefix: `/hosts/${parameter}/x`, profile: "exempt" })).toThrow("parameter");
+    }
     expect(() => routes.register({ method: "GET /", pathPrefix: "/a", profile: "exempt" })).toThrow("method");
     expect(() => routes.register({ pathPrefix: "/a", profile: { name: "a:b", limit: 1 } })).toThrow("name");
     expect(() => routes.register({ pathPrefix: "/a", profile: { name: "a", limit: 0 } })).toThrow("limit");
@@ -83,6 +119,28 @@ describe("RateLimitRoutes", () => {
 });
 
 describe("RateLimiter route profiles", () => {
+  test("advertises the built-in budget of each default route", async () => {
+    const limiter = new RateLimiter(
+      config,
+      { resolve: async () => "session:test" } as unknown as RateLimitIdentity,
+      { increment: async () => ({ count: 1, retryAfterSeconds: 60 }) },
+    );
+    const ceiling = async (path: string, method = "GET"): Promise<string | undefined> => {
+      const request = context(path, method);
+      await limiter.enforce(request.value);
+      return request.headers["ratelimit-limit"];
+    };
+
+    expect(await ceiling("/api/auth/get-session")).toBe("1000");
+    expect(await ceiling("/site/settings")).toBe("1000");
+    expect(await ceiling("/api/auth/admin/list-users")).toBe("300");
+    expect(await ceiling("/api/auth/admin/ban-user", "POST")).toBe("20");
+    expect(await ceiling("/api/auth/sign-out", "POST")).toBe("20");
+    expect(await ceiling("/api/auth/sign-in/email", "POST")).toBe("20");
+    expect(await ceiling("/site/settings", "PUT")).toBe("300");
+    expect(await ceiling("/account/capabilities")).toBe("300");
+  });
+
   test("counts a registered route in its own bucket and skips exempt routes", async () => {
     const increment = mock(async (_key: string, _ttlSeconds: number) => ({ count: 1, retryAfterSeconds: 30 }));
     const limiter = new RateLimiter(

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

@@ -8,14 +8,18 @@ import type { RateLimitConfig } from "./rate-limit.config";
 /** A budget with its window resolved, or "exempt". */
 export type ResolvedRateLimitProfile = Required<RateLimitProfile> | "exempt";
 
+/** A literal path segment, or null for a `:name` parameter. */
+type Segment = string | null;
+
 interface RouteEntry {
   method?: string;
-  prefix: string;
+  segments: Segment[];
   profile: ResolvedRateLimitProfile;
 }
 
 const PROFILE_NAME = /^[A-Za-z0-9_-]{1,64}$/;
 const METHOD = /^[A-Z]+$/;
+const PARAMETER = /^:[A-Za-z_][A-Za-z0-9_]*$/;
 
 function positiveInteger(value: number | undefined, label: string): void {
   if (value !== undefined && (!Number.isSafeInteger(value) || value < 1)) {
@@ -23,15 +27,47 @@ function positiveInteger(value: number | undefined, label: string): void {
   }
 }
 
-function normalizePrefix(prefix: string): string {
+function parsePrefix(prefix: string): Segment[] {
   if (!prefix.startsWith("/") || /[?#\s]/.test(prefix) || prefix.includes("//")) {
     throw new Error(`Rate limit path prefix must be an absolute path: ${prefix}`);
   }
-  return prefix.length > 1 && prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+  if (prefix.includes("*")) {
+    throw new Error(`Rate limit path prefix takes ":name" parameters, not wildcards: ${prefix}`);
+  }
+  const base = prefix.length > 1 && prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+  return base === "/"
+    ? []
+    : base.slice(1).split("/").map((segment) => {
+        if (segment === "." || segment === "..") {
+          throw new Error(`Rate limit path prefix must not contain "." or ".." segments: ${prefix}`);
+        }
+        if (!segment.startsWith(":")) return segment;
+        if (!PARAMETER.test(segment)) {
+          throw new Error(`Rate limit path parameter must be ":" and a name such as ":hostId": ${prefix}`);
+        }
+        return null;
+      });
+}
+
+/** Whole-segment prefix match; a parameter matches one non-empty segment. */
+function covers(segments: Segment[], path: string[]): boolean {
+  return (
+    path.length >= segments.length &&
+    segments.every((segment, index) => (segment === null ? path[index] !== "" : segment === path[index]))
+  );
 }
 
-function covers(prefix: string, path: string): boolean {
-  return prefix === "/" || path === prefix || path.startsWith(`${prefix}/`);
+/**
+ * Below zero when `a` is more specific: more segments, then, from the left, a
+ * literal segment before a parameter.
+ */
+function compareSpecificity(a: Segment[], b: Segment[]): number {
+  if (a.length !== b.length) return b.length - a.length;
+  for (let index = 0; index < a.length; index += 1) {
+    const literalA = a[index] !== null;
+    if (literalA !== (b[index] !== null)) return literalA ? -1 : 1;
+  }
+  return 0;
 }
 
 /**
@@ -50,24 +86,21 @@ export class RateLimitRoutes implements RateLimitRouteRegistry {
     if (method !== undefined && !METHOD.test(method)) {
       throw new Error(`Rate limit route method is invalid: ${route.method}`);
     }
-    const prefix = normalizePrefix(route.pathPrefix);
+    const segments = parsePrefix(route.pathPrefix);
     const profile = route.profile === "exempt" ? "exempt" : this.budget(route.profile);
-    this.entries.push({ ...(method ? { method } : {}), prefix, profile });
+    this.entries.push({ ...(method ? { method } : {}), segments, profile });
   }
 
   /** The most specific registered profile for a request, if any route matches. */
   resolve(method: string, path: string): ResolvedRateLimitProfile | undefined {
+    const pathSegments = path.split("/").slice(1);
     let best: RouteEntry | undefined;
     for (const entry of this.entries) {
       if (entry.method !== undefined && entry.method !== method) continue;
-      if (!covers(entry.prefix, path)) continue;
-      // The longer prefix wins, then a route with a method, then the later one.
-      if (
-        !best ||
-        entry.prefix.length > best.prefix.length ||
-        (entry.prefix.length === best.prefix.length &&
-          (entry.method !== undefined || best.method === undefined))
-      ) {
+      if (!covers(entry.segments, pathSegments)) continue;
+      // The more specific prefix wins, then a route with a method, then the later one.
+      const order = best ? compareSpecificity(entry.segments, best.segments) : -1;
+      if (order < 0 || (order === 0 && (entry.method !== undefined || best?.method === undefined))) {
         best = entry;
       }
     }