@podosoft/podokit 1.1.6 → 1.3.0

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

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import {
   clientAddressFromProxy,
   rateLimitConfig,
+  sessionSigningSecret,
 } from "./rate-limit.config";
 
 describe("rate limit configuration", () => {
@@ -88,4 +89,12 @@ describe("rate limit configuration", () => {
       }),
     ).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  " }),
+    ).toBe("session-secret-with-at-least-32-chars");
+    expect(sessionSigningSecret({ BETTER_AUTH_SECRET: "   " })).toBeUndefined();
+    expect(sessionSigningSecret({})).toBeUndefined();
+  });
 });

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

@@ -84,6 +84,13 @@ export function rateLimitConfig(env: NodeJS.ProcessEnv = process.env): RateLimit
   };
 }
 
+// The secret Better Auth signs session cookies with (the auth module trims it the
+// same way). Without it, sessions are not recognized and requests are counted by
+// client address.
+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();

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

@@ -1,4 +1,5 @@
-import { describe, expect, mock, test } from "bun:test";
+import { createHmac } from "node:crypto";
+import { describe, expect, mock, test, type Mock } from "bun:test";
 import { ApiKeyVerifier } from "../api-key/api-key-verifier";
 import {
   REQUEST_IDENTITY,
@@ -8,36 +9,130 @@ import {
   RATE_LIMIT_IDENTITY_EXTENSION,
   RateLimitIdentity,
   RateLimitIdentityExtension,
+  verifiedSessionToken,
 } from "./rate-limit.identity";
 
 const proxyConfig = { proxyHeader: "x-forwarded-for", trustedProxyHops: 1 };
+const secret = "rate-limit-test-secret-with-at-least-32-characters";
+const sessionToken = "Sx0d8mFqY3KcT7wJpLr2NvBhZa9EgUi4";
 
 function request(headers: Record<string, string> = {}): Request {
   return new Request("http://localhost/ordinary", { headers });
 }
 
-function services(userId?: string): ServiceRegistry {
+// The same format Better Auth issues: `${token}.${base64(HMAC-SHA256)}`.
+function signed(token: string, key = secret): string {
+  return `${token}.${createHmac("sha256", key).update(token).digest("base64")}`;
+}
+
+function tamperedSignature(value: string): string {
+  const index = value.lastIndexOf(".") + 1;
+  const replacement = value[index] === "A" ? "B" : "A";
+  return `${value.slice(0, index)}${replacement}${value.slice(index + 1)}`;
+}
+
+function sessionCookie(value: string, name = "better-auth.session_token"): string {
+  return `theme=dark; ${name}=${encodeURIComponent(value)}`;
+}
+
+function rejectingVerifier(): ApiKeyVerifier {
+  return { isValid: mock(() => false) } as unknown as ApiKeyVerifier;
+}
+
+// Registers a request identity that would hit the session store, so tests can
+// prove the limiter never asks for it.
+function servicesWithSessionStore(): {
+  registry: ServiceRegistry;
+  userId: Mock<(request: Request) => Promise<string | undefined>>;
+} {
   const registry = new ServiceRegistry();
-  registry.register(REQUEST_IDENTITY, { userId: async () => userId });
-  return registry;
+  const userId = mock(async (_request: Request): Promise<string | undefined> => "user-secret-id");
+  registry.register(REQUEST_IDENTITY, {
+    userId,
+    isAdmin: async () => false,
+    roles: async () => [],
+    activeOrganizationId: async () => undefined,
+  });
+  return { registry, userId };
 }
 
 describe("RateLimitIdentity", () => {
-  test("uses an authenticated user without exposing the user id", async () => {
-    const verifier = { isValid: mock(() => true) } as unknown as ApiKeyVerifier;
-    const identity = new RateLimitIdentity(verifier, services("user-secret-id"));
+  test("uses a verified session cookie without resolving the session", async () => {
+    const { registry, userId } = servicesWithSessionStore();
+    const identity = new RateLimitIdentity(rejectingVerifier(), registry, secret);
+
     const value = await identity.resolve(
-      request({ "x-api-key": "api-secret" }),
+      request({ cookie: sessionCookie(signed(sessionToken)) }),
+      "10.0.0.9",
+      proxyConfig,
+    );
+
+    expect(value).toMatch(/^session:[a-f0-9]{64}$/);
+    expect(value).not.toContain(sessionToken);
+    expect(userId).not.toHaveBeenCalled();
+  });
+
+  test("gives one session the same counter across cookie names and bearer forms", async () => {
+    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, "__Secure-better-auth.session_token") }),
+        "10.0.0.9",
+        proxyConfig,
+      ),
+      identity.resolve(request({ authorization: `Bearer ${value}` }), "10.0.0.9", proxyConfig),
+      identity.resolve(
+        request({ authorization: `bearer ${encodeURIComponent(value)}` }),
+        "10.0.0.9",
+        proxyConfig,
+      ),
+    ]);
+    expect(new Set(resolved).size).toBe(1);
+
+    const other = await identity.resolve(
+      request({ cookie: sessionCookie(signed("AnotherSessionToken0123456789abcd")) }),
       "10.0.0.9",
       proxyConfig,
     );
-    expect(value).toMatch(/^user:[a-f0-9]{64}$/);
-    expect(value).not.toContain("user-secret-id");
-    expect(verifier.isValid).not.toHaveBeenCalled();
+    expect(other).toMatch(/^session:/);
+    expect(other).not.toBe(resolved[0]);
+  });
+
+  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);
+    expect(anonymous).toMatch(/^ip:[a-f0-9]{64}$/);
+
+    const genuine = signed(sessionToken);
+    const forgedValues = [
+      signed(sessionToken, "an-attacker-chosen-secret-of-32-characters"),
+      `${sessionToken}x${genuine.slice(sessionToken.length)}`,
+      tamperedSignature(genuine),
+      genuine.replace("=", ""),
+      sessionToken,
+      "",
+    ];
+    for (const forged of forgedValues) {
+      const variants: Array<Record<string, string>> = [
+        { cookie: sessionCookie(forged) },
+        { authorization: `Bearer ${forged}` },
+      ];
+      for (const headers of variants) {
+        const value = await identity.resolve(
+          request({ ...address, ...headers }),
+          "10.0.0.9",
+          proxyConfig,
+        );
+        expect(value).toBe(anonymous);
+      }
+    }
   });
 
-  test("uses configured and extension API keys without storing raw keys", async () => {
-    const registry = services();
+  test("checks API keys before sessions without storing raw keys", async () => {
+    const registry = new ServiceRegistry();
     class Extension extends RateLimitIdentityExtension {
       async validatedApiKeyId(_request: Request, rawApiKey: string): Promise<string | undefined> {
         return rawApiKey === "external-valid" ? "external-stable-id" : undefined;
@@ -47,26 +142,49 @@ describe("RateLimitIdentity", () => {
     const verifier = {
       isValid: mock((value: string) => value === "configured-valid"),
     } as unknown as ApiKeyVerifier;
-    const identity = new RateLimitIdentity(verifier, registry);
+    const identity = new RateLimitIdentity(verifier, registry, secret);
+    const cookie = sessionCookie(signed(sessionToken));
 
     for (const raw of ["configured-valid", "external-valid"]) {
-      const value = await identity.resolve(request({ "x-api-key": raw }), "10.0.0.9", proxyConfig);
+      const value = await identity.resolve(
+        request({ "x-api-key": raw, cookie }),
+        "10.0.0.9",
+        proxyConfig,
+      );
       expect(value).toMatch(/^api-key:[a-f0-9]{64}$/);
       expect(value).not.toContain(raw);
     }
-  });
 
-  test("falls back to the trusted client address", async () => {
-    const identity = new RateLimitIdentity(
-      { isValid: mock(() => false) } as unknown as ApiKeyVerifier,
-      services(),
+    const invalidKey = await identity.resolve(
+      request({ "x-api-key": "invalid", cookie }),
+      "10.0.0.9",
+      proxyConfig,
     );
+    expect(invalidKey).toMatch(/^session:/);
+  });
+
+  test("falls back to the trusted client address without authentication", async () => {
+    const cookie = sessionCookie(signed(sessionToken));
+    // No session secret: the auth module is not installed or not configured.
+    const identity = new RateLimitIdentity(rejectingVerifier(), new ServiceRegistry(), undefined);
     const value = await identity.resolve(
-      request({ "x-forwarded-for": "203.0.113.7" }),
+      request({ "x-forwarded-for": "203.0.113.7", cookie }),
       "10.0.0.9",
       proxyConfig,
     );
     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),
+    ).toBe(value);
+  });
+});
+
+describe("verifiedSessionToken", () => {
+  test("returns the token only for a matching signature", () => {
+    expect(verifiedSessionToken(signed(sessionToken), secret)).toBe(sessionToken);
+    expect(verifiedSessionToken(signed(sessionToken), `${secret}-rotated`)).toBeUndefined();
+    expect(verifiedSessionToken(".", secret)).toBeUndefined();
+    expect(verifiedSessionToken(`${sessionToken}.`, secret)).toBeUndefined();
   });
 });

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

@@ -1,10 +1,6 @@
-import { createHash } from "node:crypto";
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import type { ApiKeyVerifier } from "../api-key/api-key-verifier";
-import {
-  REQUEST_IDENTITY,
-  type ServiceKey,
-  type ServiceRegistry,
-} from "../core/services";
+import type { ServiceKey, ServiceRegistry } from "../core/services";
 import {
   clientAddressFromProxy,
   type RateLimitConfig,
@@ -21,7 +17,20 @@ export const RATE_LIMIT_IDENTITY_EXTENSION = Symbol(
   "rate-limit-identity-extension",
 ) as ServiceKey<RateLimitIdentityExtension>;
 
-function stableDigest(kind: "user" | "api-key" | "ip", value: string): string {
+// Better Auth's session cookie. It adds the __Secure- prefix when BETTER_AUTH_URL
+// uses HTTPS; either name only counts when its signature verifies.
+const SESSION_COOKIE_NAMES = [
+  "__Secure-better-auth.session_token",
+  "better-auth.session_token",
+] as const;
+
+// better-call signs cookies as `${token}.${base64(HMAC-SHA256(secret, token))}` and
+// accepts only the padded 44-character standard base64 signature.
+const SIGNATURE = /^[A-Za-z0-9+/]{43}=$/;
+
+type TrackerKind = "session" | "api-key" | "ip";
+
+function stableDigest(kind: TrackerKind, value: string): string {
   return createHash("sha256")
     .update("podokit-rate-limit-v1", "utf8")
     .update("\0")
@@ -31,14 +40,56 @@ function stableDigest(kind: "user" | "api-key" | "ip", value: string): string {
     .digest("hex");
 }
 
-function tracker(kind: "user" | "api-key" | "ip", value: string): string {
+function tracker(kind: TrackerKind, value: string): string {
   return `${kind}:${stableDigest(kind, value)}`;
 }
 
+function decodeComponent(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function cookieValue(header: string | null, name: string): string | undefined {
+  if (!header) return undefined;
+  for (const pair of header.split(";")) {
+    const separator = pair.indexOf("=");
+    if (separator === -1 || pair.slice(0, separator).trim() !== name) continue;
+    const value = pair.slice(separator + 1).trim();
+    return decodeComponent(value.startsWith('"') ? value.slice(1, -1) : value);
+  }
+  return undefined;
+}
+
+function bearerValue(header: string | null): string | undefined {
+  if (!header || header.slice(0, 7).toLowerCase() !== "bearer ") return undefined;
+  const value = header.slice(7).trim();
+  return value.includes("%") ? decodeComponent(value) : value;
+}
+
+export function verifiedSessionToken(
+  signedValue: string,
+  secret: string,
+): string | undefined {
+  const separator = signedValue.lastIndexOf(".");
+  if (separator < 1) return undefined;
+  const token = signedValue.slice(0, separator);
+  const signature = signedValue.slice(separator + 1);
+  if (!SIGNATURE.test(signature)) return undefined;
+  const expected = createHmac("sha256", secret).update(token, "utf8").digest();
+  const provided = Buffer.from(signature, "base64");
+  return provided.length === expected.length && timingSafeEqual(provided, expected)
+    ? token
+    : undefined;
+}
+
 export class RateLimitIdentity {
   constructor(
     private readonly configuredApiKeys: ApiKeyVerifier,
     private readonly services: ServiceRegistry,
+    private readonly sessionSecret: string | undefined,
   ) {}
 
   async resolve(
@@ -46,9 +97,6 @@ export class RateLimitIdentity {
     remoteAddress: string | undefined,
     config: Pick<RateLimitConfig, "proxyHeader" | "trustedProxyHops">,
   ): Promise<string> {
-    const userId = await this.services.resolve(REQUEST_IDENTITY).userId(request);
-    if (userId) return tracker("user", userId);
-
     const rawApiKey = request.headers.get("x-api-key");
     if (rawApiKey) {
       if (this.configuredApiKeys.isValid(rawApiKey)) return tracker("api-key", rawApiKey);
@@ -57,7 +105,28 @@ export class RateLimitIdentity {
       if (additionalIdentity) return tracker("api-key", additionalIdentity);
     }
 
+    const sessionToken = this.sessionToken(request.headers);
+    if (sessionToken) return tracker("session", sessionToken);
+
     const clientAddress = clientAddressFromProxy(request.headers, remoteAddress, config);
     return tracker("ip", clientAddress);
   }
+
+  // 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.
+  private sessionToken(headers: Headers): string | undefined {
+    if (!this.sessionSecret) return undefined;
+    const cookies = headers.get("cookie");
+    const candidates = [
+      bearerValue(headers.get("authorization")),
+      ...SESSION_COOKIE_NAMES.map((name) => cookieValue(cookies, name)),
+    ];
+    for (const candidate of candidates) {
+      if (!candidate) continue;
+      const token = verifiedSessionToken(candidate, this.sessionSecret);
+      if (token) return token;
+    }
+    return undefined;
+  }
 }

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

@@ -49,25 +49,31 @@ describe("RateLimiter", () => {
     }));
     const limiter = new RateLimiter(
       config,
-      { resolve: async () => "user:test" } as unknown as RateLimitIdentity,
+      { resolve: async () => "session:test" } as unknown as RateLimitIdentity,
       { increment } as RateLimitStorage,
     );
     await limiter.enforce(context("/ordinary").value);
     await limiter.enforce(context("/api/auth/sign-in", "POST").value);
     await limiter.enforce(context("/api/auth/get-session").value);
     await limiter.enforce(context("/site/settings").value);
+    await limiter.enforce(context("/api/auth/admin/list-users").value);
+    await limiter.enforce(context("/api/auth/admin/ban-user", "POST").value);
 
     expect(increment.mock.calls.map((call) => call.slice(1))).toEqual([
       [60],
       [60],
       [60],
       [60],
+      [60],
+      [60],
     ]);
     expect(increment.mock.calls.map((call) => call[0])).toEqual([
-      "podokit:test:rate-limit:general:user:test",
-      "podokit:test:rate-limit:auth:user:test",
-      "podokit:test:rate-limit:runtime:user:test",
-      "podokit:test:rate-limit:runtime:user:test",
+      "podokit:test:rate-limit:general:session:test",
+      "podokit:test:rate-limit:auth:session:test",
+      "podokit:test:rate-limit:runtime:session:test",
+      "podokit:test:rate-limit:runtime:session:test",
+      "podokit:test:rate-limit:general:session:test",
+      "podokit:test:rate-limit:auth:session:test",
     ]);
   });
 
@@ -131,7 +137,7 @@ describe("RateLimiter", () => {
     }));
     const limiter = new RateLimiter(
       config,
-      { resolve: async () => "user:test" } as unknown as RateLimitIdentity,
+      { resolve: async () => "session:test" } as unknown as RateLimitIdentity,
       { increment },
     );
     const headers: Record<string, string> = {};

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

@@ -7,7 +7,11 @@ import {
   type RequestGuardContext,
   type ServiceKey,
 } from "../core/services";
-import { rateLimitConfig, type RateLimitConfig } from "./rate-limit.config";
+import {
+  rateLimitConfig,
+  sessionSigningSecret,
+  type RateLimitConfig,
+} from "./rate-limit.config";
 import { RateLimitIdentity } from "./rate-limit.identity";
 
 export interface RateLimitIncrement {
@@ -101,6 +105,11 @@ export class RateLimiter {
     ) {
       return { name: "runtime", ttlSeconds: this.config.ttlSeconds, limit: this.config.runtimeLimit };
     }
+    // Admin reads need an admin session and are not credential attempts. The
+    // dashboard and organizations pages read users through Better Auth.
+    if (method === "GET" && path.startsWith("/api/auth/admin/")) {
+      return { name: "general", ttlSeconds: this.config.ttlSeconds, limit: this.config.limit };
+    }
     if (path === "/api/auth" || path.startsWith("/api/auth/")) {
       return { name: "auth", ttlSeconds: this.config.authTtlSeconds, limit: this.config.authLimit };
     }
@@ -132,7 +141,11 @@ export const rateLimitModule: PodokitModule = {
   configure: (_env, services): void => {
     const limiter = new RateLimiter(
       rateLimitConfig(),
-      new RateLimitIdentity(services.resolve(API_KEY_VERIFIER), services),
+      new RateLimitIdentity(
+        services.resolve(API_KEY_VERIFIER),
+        services,
+        sessionSigningSecret(),
+      ),
       new CacheRateLimitStorage(services.resolve(CACHE)),
     );
     services.register(RATE_LIMITER, limiter);

package/dist/templates/modules/rate-limit/files/tests/api/rate-limit.api.spec.ts

@@ -65,6 +65,52 @@ test("rate limit: health probes stay available while ordinary routes return 429
   await ctx.dispose();
 });
 
+test("rate limit: each signed session has its own counter and forged sessions do not", async ({
+  playwright,
+}) => {
+  const email = `rate-limit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
+  const password = "Podokit3e-Str0ng!pw";
+  const first = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  expect((await first.post("/api/auth/sign-up/email", { data: { email, password, name: "Rate Limit" } })).ok()).toBeTruthy();
+  const probe = await first.get("/api/cache/rate-limit-probe");
+  test.skip(probe.status() >= 500, "throttler storage (redis) not reachable");
+  const remaining = (response: APIResponse): number => Number(response.headers()["ratelimit-remaining"]);
+  const ceiling = Number(probe.headers()["ratelimit-limit"]);
+  expect(remaining(probe)).toBe(ceiling - 1);
+
+  // The signed bearer form of the same session shares its counter.
+  const cookie = (await first.storageState()).cookies.find((c) => c.name.endsWith("session_token"));
+  expect(cookie, "sign-up set a session cookie").toBeTruthy();
+  const bearer = await playwright.request.newContext({
+    baseURL: base,
+    extraHTTPHeaders: { ...origin, authorization: `Bearer ${cookie?.value ?? ""}` },
+  });
+  expect(remaining(await bearer.get("/api/cache/rate-limit-probe"))).toBe(ceiling - 2);
+
+  // Counters follow the session, not the user: signing in again starts a new one.
+  const second = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  expect((await second.post("/api/auth/sign-in/email", { data: { email, password } })).ok()).toBeTruthy();
+  expect(remaining(await second.get("/api/cache/rate-limit-probe"))).toBe(ceiling - 1);
+
+  // A session cookie without a valid signature is counted with anonymous traffic
+  // from the same client address instead of receiving a fresh counter. The cache
+  // probe requires a session, so compare on a public route with the general limit.
+  const token = decodeURIComponent(cookie?.value ?? "").split(".")[0] ?? "";
+  const forged = await playwright.request.newContext({
+    baseURL: base,
+    extraHTTPHeaders: { ...origin, cookie: `${cookie?.name ?? ""}=${token}.${"A".repeat(43)}%3D` },
+  });
+  const anonymous = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  await expect(async () => {
+    const before = await anonymous.get("/api/account/capabilities");
+    const after = await forged.get("/api/account/capabilities");
+    expect(before.status()).toBe(200);
+    expect(remaining(after)).toBeLessThan(remaining(before));
+  }).toPass({ timeout: 10_000 });
+
+  for (const context of [first, bearer, second, forged, anonymous]) await context.dispose();
+});
+
 test("rate limit: session reads do not consume the strict authentication budget", async ({
   playwright,
 }) => {

package/dist/templates/modules/rate-limit/module.manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "rate-limit",
   "manifestVersion": 3,
-  "description": "Provider-neutral Elysia request limiting by authenticated user, validated API key, or trusted-proxy client address.",
+  "description": "Provider-neutral Elysia request limiting by validated API key, signed-in session, or trusted-proxy client address.",
   "requires": ["api-key-auth"],
   "requiresCapabilities": ["cache"],
   "targetApp": "api",
@@ -14,7 +14,7 @@
     "RATE_LIMIT_KEY_PREFIX=podokit:rate-limit",
     "RATE_LIMIT_TTL=60",
     "RATE_LIMIT_MAX=300",
-    "# stricter authentication endpoint ceiling",
+    "# stricter ceiling for authentication writes (admin reads use RATE_LIMIT_MAX)",
     "RATE_LIMIT_AUTH_TTL=60",
     "RATE_LIMIT_AUTH_MAX=20",
     "# higher ceiling for SSR runtime settings and session reads",
@@ -42,7 +42,8 @@
     "Tune the general, authentication, and runtime limits in .env.",
     "Give each deployment that shares Redis a distinct RATE_LIMIT_KEY_PREFIX.",
     "Set RATE_LIMIT_TRUSTED_PROXY_HOPS to the exact number of trusted reverse proxies; keep 0 for direct API access.",
-    "Authenticated users and validated X-API-Key clients receive independent opaque counters; other traffic uses the trusted client address.",
+    "Validated X-API-Key clients and signed-in sessions receive independent opaque counters; other traffic uses the trusted client address.",
+    "Sessions are recognized by verifying the Better Auth cookie or bearer signature with BETTER_AUTH_SECRET, without a database read, so limits apply per session rather than per user.",
     "Exceeded limits return RATE_LIMIT_EXCEEDED with HTTP 429 and Retry-After. Cache failures return RATE_LIMIT_UNAVAILABLE with HTTP 503.",
     "Register a RateLimitIdentityExtension under RATE_LIMIT_IDENTITY_EXTENSION in app.extensions.ts for another validated machine-key source.",
     "GET /health and GET /health/ready bypass request quotas so orchestrator probes remain reliable.",

package/dist/templates/modules/redis/files/apps/api/src/redis/redis-cache.store.spec.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it, mock } from "bun:test";
+import {
+  FIXED_WINDOW_SCRIPT,
+  FIXED_WINDOW_SCRIPT_SHA,
+  RedisCacheStore,
+} from "./redis-cache.store";
+import { RedisService } from "./redis.service";
+
+const redisUrl = process.env.REDIS_TEST_URL;
+const integrationTest = redisUrl ? it : it.skip;
+
+type Send = (command: string, args: string[]) => Promise<unknown>;
+type SetValue = (key: string, value: string, ...options: Array<string | number>) => Promise<"OK">;
+
+function storeWith(client: { send?: Send; set?: SetValue }): RedisCacheStore {
+  return new RedisCacheStore({ client } as unknown as RedisService);
+}
+
+function redisError(message: string): Error {
+  return Object.assign(new Error(message), { name: "RedisError", code: "ERR_REDIS_SERVER_ERROR" });
+}
+
+describe("RedisCacheStore fixed window", () => {
+  it("runs the cached script by SHA", async () => {
+    const send = mock<Send>(async () => [1, 60_000]);
+    const store = storeWith({ send });
+
+    await expect(
+      store.incrementFixedWindow("counter", { windowMs: 60_000, limit: 5 }),
+    ).resolves.toMatchObject({ allowed: true, count: 1, remaining: 4 });
+    expect(send.mock.calls).toEqual([
+      ["EVALSHA", [FIXED_WINDOW_SCRIPT_SHA, "1", "counter", "60000"]],
+    ]);
+  });
+
+  it("falls back to EVAL when Redis has not cached the script", async () => {
+    const send = mock<Send>(async (command) => {
+      if (command === "EVALSHA") throw redisError("NOSCRIPT No matching script. Please use EVAL.");
+      return [2, 500];
+    });
+    const store = storeWith({ send });
+
+    await expect(
+      store.incrementFixedWindow("counter", { windowMs: 1_000, limit: 1 }),
+    ).resolves.toMatchObject({ allowed: false, count: 2, remaining: 0 });
+    expect(send.mock.calls).toEqual([
+      ["EVALSHA", [FIXED_WINDOW_SCRIPT_SHA, "1", "counter", "1000"]],
+      ["EVAL", [FIXED_WINDOW_SCRIPT, "1", "counter", "1000"]],
+    ]);
+  });
+
+  it("propagates other Redis errors unchanged", async () => {
+    const failure = redisError("LOADING Redis is loading the dataset in memory");
+    const send = mock<Send>(async () => { throw failure; });
+    const store = storeWith({ send });
+
+    await expect(
+      store.incrementFixedWindow("counter", { windowMs: 1_000, limit: 1 }),
+    ).rejects.toBe(failure);
+    expect(send).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("RedisCacheStore set", () => {
+  it("writes the value and its TTL in one command", async () => {
+    const set = mock<SetValue>(async () => "OK");
+    const store = storeWith({ set });
+
+    await store.set("plain", "value");
+    await store.set("expiring", "value", { ttlMs: 1_500 });
+
+    expect(set.mock.calls).toEqual([
+      ["plain", "value"],
+      ["expiring", "value", "PX", 1_500],
+    ]);
+  });
+
+  it("rejects an invalid TTL before writing", async () => {
+    const set = mock<SetValue>(async () => "OK");
+    const store = storeWith({ set });
+
+    await expect(store.set("key", "value", { ttlMs: 0 })).rejects.toThrow("ttlMs");
+    expect(set).not.toHaveBeenCalled();
+  });
+});
+
+describe("RedisCacheStore integration", () => {
+  integrationTest("matches the Redis script SHA and counts atomically", async () => {
+    const previousUrl = process.env.REDIS_URL;
+    process.env.REDIS_URL = redisUrl;
+    const service = new RedisService();
+    const store = new RedisCacheStore(service);
+    const prefix = `podokit:test:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+
+    try {
+      await service.connect();
+      await expect(
+        service.client.send("SCRIPT", ["LOAD", FIXED_WINDOW_SCRIPT]),
+      ).resolves.toBe(FIXED_WINDOW_SCRIPT_SHA);
+
+      const counter = `${prefix}:counter`;
+      const options = { windowMs: 60_000, limit: 1 };
+      await expect(store.incrementFixedWindow(counter, options)).resolves.toMatchObject({
+        allowed: true,
+        count: 1,
+      });
+      await expect(store.incrementFixedWindow(counter, options)).resolves.toMatchObject({
+        allowed: false,
+        count: 2,
+      });
+
+      const expiring = `${prefix}:expiring`;
+      await store.set(expiring, "value", { ttlMs: 60_000 });
+      await expect(store.get(expiring)).resolves.toBe("value");
+      expect(await service.client.pttl(expiring)).toBeGreaterThan(0);
+
+      await service.del(counter);
+      await service.del(expiring);
+    } finally {
+      service.close();
+      if (previousUrl === undefined) delete process.env.REDIS_URL;
+      else process.env.REDIS_URL = previousUrl;
+    }
+  });
+});