@podosoft/podokit 0.15.0 → 0.16.0

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

@@ -0,0 +1,91 @@
+import { Controller, Get, Global, Module } from "@nestjs/common";
+import { Test } from "@nestjs/testing";
+import { describe, it, jest } from "@jest/globals";
+import request from "supertest";
+import { AllExceptionsFilter } from "../common/all-exceptions.filter";
+import { ReadinessService } from "../health/readiness.service";
+
+jest.mock("../auth/auth-provider", () => ({
+  authRuntime: { api: { getSession: jest.fn() } },
+}));
+jest.mock("better-auth/node", () => ({
+  fromNodeHeaders: (headers: unknown) => headers,
+}));
+
+import { RateLimitModule } from "./rate-limit.module";
+
+@Global()
+@Module({
+  providers: [ReadinessService],
+  exports: [ReadinessService],
+})
+class TestReadinessModule {}
+
+@Controller()
+class TestController {
+  @Get("ordinary")
+  ordinary(): { ok: true } {
+    return { ok: true };
+  }
+
+  @Get("health")
+  health(): { ok: true } {
+    return { ok: true };
+  }
+}
+
+@Module({
+  imports: [TestReadinessModule, RateLimitModule],
+  controllers: [TestController],
+})
+class TestApplicationModule {}
+
+const redisUrl = process.env.REDIS_TEST_URL;
+const integrationTest = redisUrl ? it : it.skip;
+
+describe("RateLimitModule integration", () => {
+  integrationTest("shares counters across replicas and bypasses health probes", async () => {
+    const previousRedisUrl = process.env.REDIS_URL;
+    process.env.REDIS_URL = redisUrl;
+    const firstModule = await Test.createTestingModule({
+      imports: [TestApplicationModule],
+    }).compile();
+    const secondModule = await Test.createTestingModule({
+      imports: [TestApplicationModule],
+    }).compile();
+    const first = firstModule.createNestApplication();
+    const second = secondModule.createNestApplication();
+
+    try {
+      first.useGlobalFilters(new AllExceptionsFilter());
+      second.useGlobalFilters(new AllExceptionsFilter());
+      await Promise.all([first.init(), second.init()]);
+      const clientAddress = `198.51.100.${Math.floor(Math.random() * 200) + 1}`;
+      await request(first.getHttpServer())
+        .get("/ordinary")
+        .set("x-forwarded-for", clientAddress)
+        .expect(200);
+      const limited = await request(second.getHttpServer())
+        .get("/ordinary")
+        .set("x-forwarded-for", clientAddress)
+        .expect(429);
+      if (
+        limited.body?.error?.code !== "RATE_LIMIT_EXCEEDED" ||
+        !limited.headers["retry-after"]
+      ) {
+        throw new Error("Shared rate-limit response contract is invalid");
+      }
+
+      for (let index = 0; index < 3; index += 1) {
+        await request(index % 2 === 0 ? first.getHttpServer() : second.getHttpServer())
+          .get("/health")
+          .set("x-forwarded-for", clientAddress)
+          .expect(200);
+      }
+    } finally {
+      await Promise.all([first.close(), second.close()]);
+      if (previousRedisUrl === undefined) delete process.env.REDIS_URL;
+      else process.env.REDIS_URL = previousRedisUrl;
+    }
+  });
+});

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

@@ -0,0 +1,228 @@
+import {
+  Controller,
+  Get,
+  type INestApplication,
+  Injectable,
+  Module,
+  Post,
+} from "@nestjs/common";
+import { APP_GUARD } from "@nestjs/core";
+import { Test } from "@nestjs/testing";
+import {
+  ThrottlerModule,
+  type ThrottlerStorage,
+} from "@nestjs/throttler";
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  jest,
+} from "@jest/globals";
+import Redis from "ioredis";
+import request from "supertest";
+import { AllExceptionsFilter } from "../common/all-exceptions.filter";
+import { RedisService } from "../redis/redis.service";
+
+jest.mock("../auth/auth-provider", () => ({
+  authRuntime: { api: { getSession: jest.fn() } },
+}));
+jest.mock("better-auth/node", () => ({
+  fromNodeHeaders: (headers: unknown) => headers,
+}));
+
+import {
+  ProxyAwareThrottlerGuard,
+  RateLimitModule,
+} from "./rate-limit.module";
+import {
+  RateLimitIdentity,
+  RateLimitIdentityExtension,
+  type RateLimitRequest,
+} from "./rate-limit.identity";
+
+type StorageMode = "allow" | "blocked" | "error";
+type IncrementCall = {
+  ttl: number;
+  limit: number;
+  blockDuration: number;
+};
+
+class ContractStorage implements ThrottlerStorage {
+  mode: StorageMode = "allow";
+  readonly calls: IncrementCall[] = [];
+
+  async increment(
+    _key: string,
+    ttl: number,
+    limit: number,
+    blockDuration: number,
+    _throttlerName: string,
+  ): Promise<{
+    totalHits: number;
+    timeToExpire: number;
+    isBlocked: boolean;
+    timeToBlockExpire: number;
+  }> {
+    this.calls.push({ ttl, limit, blockDuration });
+    if (this.mode === "error") throw new Error("Redis unavailable");
+    return {
+      totalHits: this.mode === "blocked" ? limit + 1 : 1,
+      timeToExpire: 7,
+      isBlocked: this.mode === "blocked",
+      timeToBlockExpire: 7,
+    };
+  }
+}
+
+const storage = new ContractStorage();
+
+@Controller()
+class ContractController {
+  @Get("ordinary")
+  ordinary(): { ok: true } {
+    return { ok: true };
+  }
+
+  @Post("api/auth/sign-in")
+  signIn(): { ok: true } {
+    return { ok: true };
+  }
+
+  @Get("site/settings")
+  runtime(): { ok: true } {
+    return { ok: true };
+  }
+
+  @Get("health")
+  health(): { ok: true } {
+    return { ok: true };
+  }
+
+  @Get("health/ready")
+  ready(): { ok: true } {
+    return { ok: true };
+  }
+}
+
+@Module({
+  imports: [
+    ThrottlerModule.forRoot({
+      throttlers: [{ ttl: 60_000, limit: 300 }],
+      storage,
+    }),
+  ],
+  controllers: [ContractController],
+  providers: [
+    {
+      provide: RateLimitIdentity,
+      useValue: { resolve: async () => "user:test-tracker" },
+    },
+    { provide: APP_GUARD, useClass: ProxyAwareThrottlerGuard },
+  ],
+})
+class ContractModule {}
+
+describe("ProxyAwareThrottlerGuard contract", () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const module = await Test.createTestingModule({
+      imports: [ContractModule],
+    }).compile();
+    app = module.createNestApplication();
+    app.useGlobalFilters(new AllExceptionsFilter());
+    await app.init();
+  });
+
+  beforeEach(() => {
+    storage.mode = "allow";
+    storage.calls.length = 0;
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it("applies separate general, authentication, and runtime limits", async () => {
+    await request(app.getHttpServer()).get("/ordinary").expect(200);
+    await request(app.getHttpServer()).post("/api/auth/sign-in").expect(201);
+    await request(app.getHttpServer()).get("/site/settings").expect(200);
+
+    expect(storage.calls).toEqual([
+      { ttl: 60_000, limit: 300, blockDuration: 60_000 },
+      { ttl: 60_000, limit: 20, blockDuration: 60_000 },
+      { ttl: 60_000, limit: 1000, blockDuration: 60_000 },
+    ]);
+  });
+
+  it("keeps liveness and readiness outside request limiting", async () => {
+    await request(app.getHttpServer()).get("/health").expect(200);
+    await request(app.getHttpServer()).get("/health/ready").expect(200);
+    expect(storage.calls).toHaveLength(0);
+  });
+
+  it("returns stable error envelopes for blocked and unavailable storage", async () => {
+    storage.mode = "blocked";
+    const blocked = await request(app.getHttpServer()).get("/ordinary").expect(429);
+    expect(blocked.headers["retry-after"]).toBe("7");
+    expect(blocked.body).toMatchObject({
+      success: false,
+      error: { code: "RATE_LIMIT_EXCEEDED", statusCode: 429 },
+    });
+
+    storage.mode = "error";
+    const unavailable = await request(app.getHttpServer()).get("/ordinary").expect(503);
+    expect(unavailable.headers["retry-after"]).toBe("1");
+    expect(unavailable.body).toMatchObject({
+      success: false,
+      error: { code: "RATE_LIMIT_UNAVAILABLE", statusCode: 503 },
+    });
+  });
+
+  it("uses an application identity extension without a second rate-limit module", async () => {
+    @Injectable()
+    class ApplicationIdentityExtension extends RateLimitIdentityExtension {
+      override async validatedApiKeyId(
+        _request: RateLimitRequest,
+        rawApiKey: string,
+      ): Promise<string | undefined> {
+        return rawApiKey === "application-valid" ? "application-id" : undefined;
+      }
+    }
+    const redis = Object.create(Redis.prototype) as Redis;
+    const module = await Test.createTestingModule({
+      imports: [RateLimitModule],
+      providers: [
+        {
+          provide: RateLimitIdentityExtension,
+          useClass: ApplicationIdentityExtension,
+        },
+      ],
+    })
+      .overrideProvider(RedisService)
+      .useValue({ client: redis })
+      .compile();
+    try {
+      const identity = module.get(RateLimitIdentity);
+      const headers = { "x-api-key": "application-valid" };
+      const tracker = await identity.resolve(
+        {
+          headers,
+          header: (name: string) =>
+            headers[name.toLowerCase() as keyof typeof headers],
+          socket: { remoteAddress: "10.0.0.9" },
+          ip: "10.0.0.9",
+          session: null,
+        } as unknown as RateLimitRequest,
+        { proxyHeader: "x-forwarded-for", trustedProxyHops: 0 },
+      );
+      expect(tracker).toMatch(/^api-key:[a-f0-9]{64}$/);
+      expect(tracker).not.toContain("application-id");
+    } finally {
+      await module.close();
+    }
+  });
+});

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

@@ -1,65 +1,124 @@
 import { Injectable, Module } from "@nestjs/common";
-import { APP_GUARD } from "@nestjs/core";
+import { APP_GUARD, Reflector } from "@nestjs/core";
 import {
+  InjectThrottlerOptions,
+  InjectThrottlerStorage,
   ThrottlerGuard,
   ThrottlerModule,
+  type ThrottlerLimitDetail,
+  type ThrottlerModuleOptions,
   type ThrottlerRequest,
+  type ThrottlerStorage,
 } from "@nestjs/throttler";
 import { ThrottlerStorageRedisService } from "@nest-lab/throttler-storage-redis";
-import Redis from "ioredis";
+import type { Request } from "express";
+import { ApiKeyVerifier } from "../api-key/api-key-verifier";
+import { AppException } from "../common/app-exception";
+import { RedisModule } from "../redis/redis.module";
+import { RedisService } from "../redis/redis.service";
+import { rateLimitConfig } from "./rate-limit.config";
+import { RateLimitIdentity } from "./rate-limit.identity";
 
-const ttlSeconds = Number(process.env.RATE_LIMIT_TTL ?? 60);
-const limit = Number(process.env.RATE_LIMIT_MAX ?? 100);
-const runtimeLimit = Number(process.env.RATE_LIMIT_RUNTIME_MAX ?? 1000);
+const config = rateLimitConfig();
 const unthrottledHealthPaths = new Set(["/health", "/health/ready"]);
 
-function forwardedClient(headers: unknown): string | undefined {
-  if (!headers || typeof headers !== "object") return undefined;
-  const value = (headers as Record<string, unknown>)["x-forwarded-for"];
-  const first = Array.isArray(value) ? value[0] : value;
-  if (typeof first !== "string") return undefined;
-  return first.split(",")[0]?.trim() || undefined;
-}
-
-// PodoKit exposes the API through its web proxy, which replaces x-forwarded-for
-// with SvelteKit's resolved client address. Track that address instead of the
-// web container so unrelated visitors do not share one global counter.
 @Injectable()
-class ProxyAwareThrottlerGuard extends ThrottlerGuard {
-  protected override handleRequest(requestProps: ThrottlerRequest): Promise<boolean> {
-    const { req } = this.getRequestResponse(requestProps.context);
+export class ProxyAwareThrottlerGuard extends ThrottlerGuard {
+  constructor(
+    @InjectThrottlerOptions() options: ThrottlerModuleOptions,
+    @InjectThrottlerStorage() storage: ThrottlerStorage,
+    reflector: Reflector,
+    private readonly identity: RateLimitIdentity,
+  ) {
+    super(options, storage, reflector);
+  }
+
+  protected override async handleRequest(
+    requestProps: ThrottlerRequest,
+  ): Promise<boolean> {
+    const { req, res } = this.getRequestResponse(requestProps.context);
     const method = typeof req.method === "string" ? req.method : "";
     const path = typeof req.path === "string" ? req.path : "";
-    if (method === "GET" && unthrottledHealthPaths.has(path)) {
-      return Promise.resolve(true);
+    if (method === "GET" && unthrottledHealthPaths.has(path)) return true;
+
+    let effective = requestProps;
+    if (path === "/api/auth" || path.startsWith("/api/auth/")) {
+      effective = {
+        ...requestProps,
+        limit: config.authLimit,
+        ttl: config.authTtlSeconds * 1000,
+        blockDuration: config.authTtlSeconds * 1000,
+      };
+    } else if (method === "GET" && path === "/site/settings") {
+      effective = { ...requestProps, limit: config.runtimeLimit };
     }
-    if (method === "GET" && path === "/site/settings") {
-      return super.handleRequest({ ...requestProps, limit: runtimeLimit });
+
+    try {
+      return await this.withStorageTimeout(super.handleRequest(effective));
+    } catch (error) {
+      if (error instanceof AppException) throw error;
+      if (typeof res.header === "function") {
+        res.header("Retry-After", config.unavailableRetryAfterSeconds);
+      }
+      throw new AppException(
+        "RATE_LIMIT_UNAVAILABLE",
+        "Request limiting is temporarily unavailable.",
+        503,
+      );
     }
-    return super.handleRequest(requestProps);
   }
 
   protected override getTracker(request: Record<string, unknown>): Promise<string> {
-    const forwarded = forwardedClient(request.headers);
-    const direct = typeof request.ip === "string" ? request.ip : "unknown";
-    return Promise.resolve(forwarded ?? direct);
+    return this.identity.resolve(request as unknown as Request, config);
+  }
+
+  protected override async throwThrottlingException(
+    _context: Parameters<ThrottlerGuard["canActivate"]>[0],
+    _detail: ThrottlerLimitDetail,
+  ): Promise<void> {
+    throw new AppException(
+      "RATE_LIMIT_EXCEEDED",
+      "Too many requests.",
+      429,
+    );
+  }
+
+  private async withStorageTimeout(operation: Promise<boolean>): Promise<boolean> {
+    let timeout: NodeJS.Timeout | undefined;
+    try {
+      return await Promise.race([
+        operation,
+        new Promise<never>((_resolve, reject) => {
+          timeout = setTimeout(
+            () => reject(new Error("Rate limit storage timeout")),
+            config.storageTimeoutMs,
+          );
+        }),
+      ]);
+    } finally {
+      if (timeout) clearTimeout(timeout);
+    }
   }
 }
 
-// Distributed rate limiting: the counter lives in Redis, so the limit holds
-// across API replicas. Registers a global guard (429 when exceeded).
 @Module({
   imports: [
-    ThrottlerModule.forRoot({
-      throttlers: [{ ttl: ttlSeconds * 1000, limit }],
-      storage: new ThrottlerStorageRedisService(
-        new Redis({
-          host: process.env.REDIS_HOST ?? "localhost",
-          port: Number(process.env.REDIS_PORT ?? 6379),
-        }),
-      ),
+    RedisModule,
+    ThrottlerModule.forRootAsync({
+      imports: [RedisModule],
+      inject: [RedisService],
+      useFactory: (redis: RedisService) => ({
+        throttlers: [{ ttl: config.ttlSeconds * 1000, limit: config.limit }],
+        storage: new ThrottlerStorageRedisService(redis.client),
+      }),
     }),
   ],
-  providers: [{ provide: APP_GUARD, useClass: ProxyAwareThrottlerGuard }],
+  providers: [
+    ApiKeyVerifier,
+    RateLimitIdentity,
+    ProxyAwareThrottlerGuard,
+    { provide: APP_GUARD, useExisting: ProxyAwareThrottlerGuard },
+  ],
+  exports: [RateLimitIdentity],
 })
 export class RateLimitModule {}

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

@@ -1,4 +1,4 @@
-import { expect, test } from "@playwright/test";
+import { expect, test, type APIResponse } from "@playwright/test";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
@@ -11,7 +11,7 @@ const origin = { origin: base };
 // Honor RATE_LIMIT_MAX when the test runner has it (a dedicated app sets a small
 // value so the window is crossed in a handful of requests); otherwise fall back
 // to the module default and allow a little headroom.
-const limit = Number(process.env.RATE_LIMIT_MAX ?? 100);
+const limit = Number(process.env.RATE_LIMIT_MAX ?? 300);
 
 test("rate limit: health probes stay available while ordinary routes return 429 @smoke", async ({
   playwright,
@@ -30,15 +30,20 @@ test("rate limit: health probes stay available while ordinary routes return 429
   test.skip(probe.status() >= 500, "throttler storage (redis) not reachable");
 
   let seen200 = probe.status() === 200;
-  let got429 = false;
-  for (let i = 0; i < limit + 5 && !got429; i++) {
+  let limitedResponse: APIResponse | undefined;
+  for (let i = 0; i < limit + 5 && !limitedResponse; i++) {
     const response = await ctx.get("/api/cache/rate-limit-probe");
     if (response.status() === 200) seen200 = true;
-    if (response.status() === 429) got429 = true;
+    if (response.status() === 429) limitedResponse = response;
   }
   // A fresh window serves the first requests (200) and rejects once the limit is
   // crossed (429).
   expect(seen200).toBe(true);
-  expect(got429).toBe(true);
+  expect(limitedResponse?.status()).toBe(429);
+  expect(limitedResponse?.headers()["retry-after"]).toBeTruthy();
+  expect(await limitedResponse?.json()).toMatchObject({
+    success: false,
+    error: { code: "RATE_LIMIT_EXCEEDED", statusCode: 429 },
+  });
   await ctx.dispose();
 });

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

@@ -1,18 +1,30 @@
 {
   "name": "rate-limit",
-  "description": "Rate limiting with @nestjs/throttler backed by Redis (correct across API replicas). Installs a global throttler guard; configurable via env.",
-  "requires": ["redis"],
+  "description": "Distributed request limiting by authenticated user, validated API key, or trusted-proxy client address. Uses Redis across API replicas and returns stable 429/503 errors.",
+  "requires": ["redis", "api-key-auth"],
   "targetApp": "api",
+  "managedGlobs": [
+    "apps/api/src/rate-limit/**",
+    "tests/api/rate-limit.api.spec.ts"
+  ],
   "dependencies": {
     "@nestjs/throttler": "^6.5.0",
     "@nest-lab/throttler-storage-redis": "^1.2.0"
   },
   "env": [
-    "# rate limit (window in seconds, max requests per window per client)",
+    "# rate limit (window in seconds, max requests per identity)",
     "RATE_LIMIT_TTL=60",
-    "RATE_LIMIT_MAX=100",
+    "RATE_LIMIT_MAX=300",
+    "# stricter authentication endpoint ceiling",
+    "RATE_LIMIT_AUTH_TTL=60",
+    "RATE_LIMIT_AUTH_MAX=20",
     "# higher ceiling for SSR runtime settings reads (maintenance, sign-up, branding)",
-    "RATE_LIMIT_RUNTIME_MAX=1000"
+    "RATE_LIMIT_RUNTIME_MAX=1000",
+    "# trust no proxy hop by default; set the exact production proxy depth",
+    "RATE_LIMIT_TRUSTED_PROXY_HOPS=0",
+    "RATE_LIMIT_PROXY_HEADER=x-forwarded-for",
+    "RATE_LIMIT_STORAGE_TIMEOUT_MS=1000",
+    "RATE_LIMIT_UNAVAILABLE_RETRY_AFTER=1"
   ],
   "inject": [
     { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { RateLimitModule } from \"./rate-limit/rate-limit.module\";" },
@@ -20,10 +32,12 @@
   ],
   "instructions": [
     "Ensure Redis is running:  docker compose -f infra/docker/docker-compose.yml up -d",
-    "Tune RATE_LIMIT_TTL / RATE_LIMIT_MAX / RATE_LIMIT_RUNTIME_MAX in .env.",
-    "Exceeding the limit returns HTTP 429. Skip a route with @SkipThrottle() or tune it with @Throttle().",
+    "Tune the general, authentication, and runtime limits in .env.",
+    "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.",
+    "Exceeded limits return RATE_LIMIT_EXCEEDED with HTTP 429 and Retry-After. Redis failures return RATE_LIMIT_UNAVAILABLE with HTTP 503.",
+    "Provide RateLimitIdentityExtension from app.extensions.ts when an application has another validated machine-key source; keep the single managed RateLimitModule import.",
     "GET /health and GET /health/ready bypass request quotas so orchestrator probes remain reliable.",
-    "The limit is shared across API replicas because it is stored in Redis.",
-    "PodoKit's web proxy forwards the resolved client address, so visitors receive independent counters."
+    "The limit is shared across API replicas because it is stored in Redis."
   ]
 }

package/dist/templates/modules/redis/files/apps/api/src/redis/redis.service.spec.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "@jest/globals";
+import { ReadinessService } from "../health/readiness.service";
+import { RedisService } from "./redis.service";
+
+const redisUrl = process.env.REDIS_TEST_URL;
+const integrationTest = redisUrl ? it : it.skip;
+
+describe("RedisService integration", () => {
+  integrationTest("uses authenticated settings and registers readiness", async () => {
+    const previousUrl = process.env.REDIS_URL;
+    process.env.REDIS_URL = redisUrl;
+    const readiness = new ReadinessService();
+    const service = new RedisService(readiness);
+    const key = `podokit:test:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+
+    try {
+      await service.onModuleInit();
+      await service.set(key, "value", 10);
+      await expect(service.get(key)).resolves.toBe("value");
+      await expect(readiness.run()).resolves.toEqual({ redis: "up" });
+      await service.del(key);
+    } finally {
+      await service.onModuleDestroy();
+      if (previousUrl === undefined) delete process.env.REDIS_URL;
+      else process.env.REDIS_URL = previousUrl;
+    }
+  });
+});