@podosoft/podokit 0.14.0 → 0.16.0

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

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "@jest/globals";
+import {
+  clientAddressFromProxy,
+  rateLimitConfig,
+} from "./rate-limit.config";
+
+describe("rate limit configuration", () => {
+  it("validates route limits and proxy settings", () => {
+    expect(
+      rateLimitConfig({
+        RATE_LIMIT_TTL: "30",
+        RATE_LIMIT_MAX: "250",
+        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",
+      }),
+    ).toEqual({
+      ttlSeconds: 30,
+      limit: 250,
+      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");
+  });
+
+  it("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");
+  });
+
+  it("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");
+  });
+});

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

@@ -0,0 +1,110 @@
+import { isIP } from "node:net";
+
+export interface RateLimitConfig {
+  ttlSeconds: number;
+  limit: number;
+  authTtlSeconds: number;
+  authLimit: number;
+  runtimeLimit: number;
+  trustedProxyHops: number;
+  proxyHeader: string;
+  storageTimeoutMs: number;
+  unavailableRetryAfterSeconds: number;
+}
+
+function positiveInteger(name: string, value: string | undefined, fallback: number): number {
+  if (value === undefined || value === "") return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+  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 {
+    ttlSeconds: positiveInteger("RATE_LIMIT_TTL", env.RATE_LIMIT_TTL, 60),
+    limit: positiveInteger("RATE_LIMIT_MAX", env.RATE_LIMIT_MAX, 300),
+    authTtlSeconds: positiveInteger(
+      "RATE_LIMIT_AUTH_TTL",
+      env.RATE_LIMIT_AUTH_TTL,
+      60,
+    ),
+    authLimit: positiveInteger("RATE_LIMIT_AUTH_MAX", env.RATE_LIMIT_AUTH_MAX, 20),
+    runtimeLimit: positiveInteger(
+      "RATE_LIMIT_RUNTIME_MAX",
+      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,
+      1000,
+    ),
+    unavailableRetryAfterSeconds: positiveInteger(
+      "RATE_LIMIT_UNAVAILABLE_RETRY_AFTER",
+      env.RATE_LIMIT_UNAVAILABLE_RETRY_AFTER,
+      1,
+    ),
+  };
+}
+
+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 || 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

@@ -0,0 +1,132 @@
+import { describe, expect, it, jest } from "@jest/globals";
+import type { Request } from "express";
+import type { ModuleRef } from "@nestjs/core";
+import type { ApiKeyVerifier } from "../api-key/api-key-verifier";
+
+jest.mock("../auth/auth-provider", () => ({
+  authRuntime: { api: { getSession: jest.fn() } },
+}));
+jest.mock("better-auth/node", () => ({
+  fromNodeHeaders: (headers: unknown) => headers,
+}));
+
+import { authRuntime } from "../auth/auth-provider";
+import {
+  RateLimitIdentity,
+  RateLimitIdentityExtension,
+  type RateLimitRequest,
+} from "./rate-limit.identity";
+
+function testRequest(input?: {
+  session?: RateLimitRequest["session"];
+  apiKey?: string;
+  forwarded?: string;
+  remoteAddress?: string;
+}): RateLimitRequest {
+  const headers: Record<string, string> = {};
+  if (input?.apiKey) headers["x-api-key"] = input.apiKey;
+  if (input?.forwarded) headers["x-forwarded-for"] = input.forwarded;
+  return {
+    headers,
+    header: (name: string) => headers[name.toLowerCase()],
+    socket: { remoteAddress: input?.remoteAddress ?? "10.0.0.9" },
+    ip: input?.remoteAddress ?? "10.0.0.9",
+    ...(input && "session" in input ? { session: input.session } : {}),
+  } as unknown as Request & RateLimitRequest;
+}
+
+const proxyConfig = {
+  proxyHeader: "x-forwarded-for",
+  trustedProxyHops: 1,
+};
+
+class ApplicationIdentityExtension extends RateLimitIdentityExtension {
+  override async validatedApiKeyId(
+    _request: RateLimitRequest,
+    rawApiKey: string,
+  ): Promise<string | undefined> {
+    return rawApiKey === "external-valid" ? "external-stable-id" : undefined;
+  }
+}
+
+describe("RateLimitIdentity", () => {
+  it("uses an attached user before API key or IP without exposing the user id", async () => {
+    const verifier = { isValid: jest.fn(() => true) };
+    const identity = new RateLimitIdentity(verifier as unknown as ApiKeyVerifier);
+    const request = testRequest({
+      session: { user: { id: "user-secret-id" } },
+      apiKey: "api-secret",
+      forwarded: "203.0.113.7",
+    });
+
+    const first = await identity.resolve(request, proxyConfig);
+    const second = await identity.resolve(request, proxyConfig);
+
+    expect(first).toBe(second);
+    expect(first).toMatch(/^user:[a-f0-9]{64}$/);
+    expect(first).not.toContain("user-secret-id");
+    expect(verifier.isValid).not.toHaveBeenCalled();
+  });
+
+  it("resolves a session when a preceding auth guard has not attached one", async () => {
+    const session = {
+      user: { id: "resolved-user", email: "user@example.com", name: "User" },
+      session: { id: "session-id", userId: "resolved-user" },
+    };
+    const getSession = jest
+      .spyOn(authRuntime.api, "getSession")
+      .mockResolvedValue(
+        session as Awaited<ReturnType<typeof authRuntime.api.getSession>>,
+      );
+    const identity = new RateLimitIdentity(
+      { isValid: jest.fn(() => false) } as unknown as ApiKeyVerifier,
+    );
+    const request = testRequest();
+
+    try {
+      const value = await identity.resolve(request, proxyConfig);
+      expect(value).toMatch(/^user:[a-f0-9]{64}$/);
+      expect(request.session?.user?.id).toBe("resolved-user");
+      expect(getSession).toHaveBeenCalledTimes(1);
+    } finally {
+      getSession.mockRestore();
+    }
+  });
+
+  it("uses validated configured and extension API keys without storing raw keys", async () => {
+    const verifier = {
+      isValid: jest.fn((value: string) => value === "configured-valid"),
+    } as unknown as ApiKeyVerifier;
+    const extension = new ApplicationIdentityExtension();
+    const moduleRef = {
+      get: () => extension,
+    } as unknown as ModuleRef;
+    const identity = new RateLimitIdentity(verifier, moduleRef);
+
+    for (const raw of ["configured-valid", "external-valid"]) {
+      const value = await identity.resolve(
+        testRequest({ session: null, apiKey: raw }),
+        proxyConfig,
+      );
+      expect(value).toMatch(/^api-key:[a-f0-9]{64}$/);
+      expect(value).not.toContain(raw);
+    }
+  });
+
+  it("falls back to the trusted proxy client for an invalid API key", async () => {
+    const identity = new RateLimitIdentity(
+      { isValid: jest.fn(() => false) } as unknown as ApiKeyVerifier,
+    );
+    const request = testRequest({
+      session: null,
+      apiKey: "invalid-and-rotating",
+      forwarded: "203.0.113.7",
+    });
+
+    const value = await identity.resolve(request, proxyConfig);
+
+    expect(value).toMatch(/^ip:[a-f0-9]{64}$/);
+    expect(value).not.toContain("invalid-and-rotating");
+    expect(value).not.toContain("203.0.113.7");
+  });
+});

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

@@ -0,0 +1,100 @@
+import { Injectable, Optional } from "@nestjs/common";
+import { ModuleRef } from "@nestjs/core";
+import { createHash } from "node:crypto";
+import { fromNodeHeaders } from "better-auth/node";
+import type { Request } from "express";
+import { ApiKeyVerifier } from "../api-key/api-key-verifier";
+import { authRuntime } from "../auth/auth-provider";
+import {
+  clientAddressFromProxy,
+  type RateLimitConfig,
+} from "./rate-limit.config";
+
+type SessionLike = { user?: { id?: string | null } | null } | null;
+export type RateLimitRequest = Request & {
+  session?: SessionLike;
+  user?: unknown;
+};
+
+export abstract class RateLimitIdentityExtension {
+  abstract validatedApiKeyId(
+    request: RateLimitRequest,
+    rawApiKey: string,
+  ): Promise<string | undefined>;
+}
+
+function stableDigest(kind: "user" | "api-key" | "ip", value: string): string {
+  return createHash("sha256")
+    .update("podokit-rate-limit-v1", "utf8")
+    .update("\0")
+    .update(kind, "utf8")
+    .update("\0")
+    .update(value, "utf8")
+    .digest("hex");
+}
+
+function tracker(kind: "user" | "api-key" | "ip", value: string): string {
+  return `${kind}:${stableDigest(kind, value)}`;
+}
+
+@Injectable()
+export class RateLimitIdentity {
+  constructor(
+    private readonly configuredApiKeys: ApiKeyVerifier,
+    @Optional() private readonly moduleRef?: ModuleRef,
+  ) {}
+
+  async resolve(
+    request: RateLimitRequest,
+    config: Pick<RateLimitConfig, "proxyHeader" | "trustedProxyHops">,
+  ): Promise<string> {
+    const userId = await this.userId(request);
+    if (userId) return tracker("user", userId);
+
+    const rawApiKey = request.header("x-api-key");
+    if (rawApiKey) {
+      if (this.configuredApiKeys.isValid(rawApiKey)) {
+        return tracker("api-key", rawApiKey);
+      }
+      const additionalIdentity = await this.additionalApiKeyIdentity(request, rawApiKey);
+      if (additionalIdentity) return tracker("api-key", additionalIdentity);
+    }
+
+    const remoteAddress = request.socket?.remoteAddress ?? request.ip;
+    const clientAddress = clientAddressFromProxy(request.headers, remoteAddress, config);
+    return tracker("ip", clientAddress);
+  }
+
+  private async additionalApiKeyIdentity(
+    request: RateLimitRequest,
+    rawApiKey: string,
+  ): Promise<string | undefined> {
+    if (!this.moduleRef) return undefined;
+    let extension: RateLimitIdentityExtension;
+    try {
+      extension = this.moduleRef.get(RateLimitIdentityExtension, {
+        strict: false,
+      });
+    } catch {
+      return undefined;
+    }
+    return extension.validatedApiKeyId(request, rawApiKey);
+  }
+
+  private async userId(request: RateLimitRequest): Promise<string | undefined> {
+    if (request.session === undefined) {
+      try {
+        const session = await authRuntime.api.getSession({
+          headers: fromNodeHeaders(request.headers),
+        });
+        request.session = session;
+        request.user = session?.user ?? null;
+      } catch {
+        request.session = null;
+        request.user = null;
+      }
+    }
+    const id = request.session?.user?.id;
+    return typeof id === "string" && id.length > 0 ? id : undefined;
+  }
+}

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;
+    }
+  });
+});