@podosoft/podokit 0.17.4 → 1.0.2

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

@@ -1,132 +1,72 @@
-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 { describe, expect, mock, test } from "bun:test";
+import { ApiKeyVerifier } from "../api-key/api-key-verifier";
 import {
+  REQUEST_IDENTITY,
+  ServiceRegistry,
+} from "../core/services";
+import {
+  RATE_LIMIT_IDENTITY_EXTENSION,
   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 };
 
-const proxyConfig = {
-  proxyHeader: "x-forwarded-for",
-  trustedProxyHops: 1,
-};
+function request(headers: Record<string, string> = {}): Request {
+  return new Request("http://localhost/ordinary", { headers });
+}
 
-class ApplicationIdentityExtension extends RateLimitIdentityExtension {
-  override async validatedApiKeyId(
-    _request: RateLimitRequest,
-    rawApiKey: string,
-  ): Promise<string | undefined> {
-    return rawApiKey === "external-valid" ? "external-stable-id" : undefined;
-  }
+function services(userId?: string): ServiceRegistry {
+  const registry = new ServiceRegistry();
+  registry.register(REQUEST_IDENTITY, { userId: async () => userId });
+  return registry;
 }
 
 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");
+  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"));
+    const value = await identity.resolve(
+      request({ "x-api-key": "api-secret" }),
+      "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();
   });
 
-  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();
+  test("uses configured and extension API keys without storing raw keys", async () => {
+    const registry = services();
+    class Extension extends RateLimitIdentityExtension {
+      async validatedApiKeyId(_request: Request, rawApiKey: string): Promise<string | undefined> {
+        return rawApiKey === "external-valid" ? "external-stable-id" : undefined;
+      }
     }
-  });
-
-  it("uses validated configured and extension API keys without storing raw keys", async () => {
+    registry.register(RATE_LIMIT_IDENTITY_EXTENSION, new Extension());
     const verifier = {
-      isValid: jest.fn((value: string) => value === "configured-valid"),
+      isValid: mock((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);
+    const identity = new RateLimitIdentity(verifier, registry);
 
     for (const raw of ["configured-valid", "external-valid"]) {
-      const value = await identity.resolve(
-        testRequest({ session: null, apiKey: raw }),
-        proxyConfig,
-      );
+      const value = await identity.resolve(request({ "x-api-key": raw }), "10.0.0.9", 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 () => {
+  test("falls back to the trusted client address", async () => {
     const identity = new RateLimitIdentity(
-      { isValid: jest.fn(() => false) } as unknown as ApiKeyVerifier,
+      { isValid: mock(() => false) } as unknown as ApiKeyVerifier,
+      services(),
+    );
+    const value = await identity.resolve(
+      request({ "x-forwarded-for": "203.0.113.7" }),
+      "10.0.0.9",
+      proxyConfig,
     );
-    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

@@ -1,28 +1,26 @@
-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 type { ApiKeyVerifier } from "../api-key/api-key-verifier";
+import {
+  REQUEST_IDENTITY,
+  type ServiceKey,
+  type ServiceRegistry,
+} from "../core/services";
 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,
+    request: Request,
     rawApiKey: string,
   ): Promise<string | undefined>;
 }
 
+export const RATE_LIMIT_IDENTITY_EXTENSION = Symbol(
+  "rate-limit-identity-extension",
+) as ServiceKey<RateLimitIdentityExtension>;
+
 function stableDigest(kind: "user" | "api-key" | "ip", value: string): string {
   return createHash("sha256")
     .update("podokit-rate-limit-v1", "utf8")
@@ -37,64 +35,29 @@ 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,
+    private readonly services: ServiceRegistry,
   ) {}
 
   async resolve(
-    request: RateLimitRequest,
+    request: Request,
+    remoteAddress: string | undefined,
     config: Pick<RateLimitConfig, "proxyHeader" | "trustedProxyHops">,
   ): Promise<string> {
-    const userId = await this.userId(request);
+    const userId = await this.services.resolve(REQUEST_IDENTITY).userId(request);
     if (userId) return tracker("user", userId);
 
-    const rawApiKey = request.header("x-api-key");
+    const rawApiKey = request.headers.get("x-api-key");
     if (rawApiKey) {
-      if (this.configuredApiKeys.isValid(rawApiKey)) {
-        return tracker("api-key", rawApiKey);
-      }
-      const additionalIdentity = await this.additionalApiKeyIdentity(request, rawApiKey);
+      if (this.configuredApiKeys.isValid(rawApiKey)) return tracker("api-key", rawApiKey);
+      const extension = this.services.tryResolve(RATE_LIMIT_IDENTITY_EXTENSION);
+      const additionalIdentity = await extension?.validatedApiKeyId(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.spec.ts

@@ -1,228 +1,140 @@
-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;
+import { describe, expect, mock, test } from "bun:test";
+import type { RequestGuardContext } from "../core/services";
+import type { RateLimitIdentity } from "./rate-limit.identity";
+import { RateLimiter, type RateLimitStorage } from "./rate-limit.module";
+
+const config = {
+  keyPrefix: "podokit:test:rate-limit",
+  ttlSeconds: 60,
+  limit: 300,
+  authTtlSeconds: 60,
+  authLimit: 20,
+  runtimeLimit: 1000,
+  trustedProxyHops: 0,
+  proxyHeader: "x-forwarded-for",
+  storageTimeoutMs: 100,
+  unavailableRetryAfterSeconds: 1,
 };
 
-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" },
+function context(path: string, method = "GET"): {
+  value: RequestGuardContext;
+  headers: Record<string, string>;
+} {
+  const headers: Record<string, string> = {};
+  return {
+    headers,
+    value: {
+      request: new Request(`http://localhost${path}`, { method }),
+      remoteAddress: "127.0.0.1",
+      setHeader: (name, value) => { headers[name.toLowerCase()] = value; },
     },
-    { 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 },
+describe("RateLimiter", () => {
+  test("applies general, authentication, and runtime profiles", async () => {
+    const increment = mock(async (_key: string, _ttlSeconds: number) => ({
+      count: 1,
+      retryAfterSeconds: 60,
+    }));
+    const limiter = new RateLimiter(
+      config,
+      { resolve: async () => "user: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("/site/settings").value);
+
+    expect(increment.mock.calls.map((call) => call.slice(1))).toEqual([
+      [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",
     ]);
   });
 
-  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);
+  test("bypasses health probes and API documentation", async () => {
+    const increment = mock(async (_key: string, _ttlSeconds: number) => ({
+      count: 1,
+      retryAfterSeconds: 60,
+    }));
+    const limiter = new RateLimiter(
+      config,
+      { resolve: async () => "ip:test" } as unknown as RateLimitIdentity,
+      { increment },
+    );
+    await limiter.enforce(context("/health").value);
+    await limiter.enforce(context("/health/ready").value);
+    await limiter.enforce(context("/api-docs").value);
+    await limiter.enforce(context("/api-docs-json").value);
+    await limiter.enforce(context("/api-docs-elysia-json").value);
+    expect(increment).not.toHaveBeenCalled();
   });
 
-  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 },
+  test("returns stable blocked and storage errors with retry headers", async () => {
+    const identity = { resolve: async () => "ip:test" } as unknown as RateLimitIdentity;
+    const blockedContext = context("/ordinary");
+    const blocked = new RateLimiter(config, identity, {
+      increment: async () => ({ count: 301, retryAfterSeconds: 7 }),
     });
+    await expect(blocked.enforce(blockedContext.value)).rejects.toMatchObject({
+      code: "RATE_LIMIT_EXCEEDED",
+      statusCode: 429,
+    });
+    expect(blockedContext.headers["retry-after"]).toBe("7");
 
-    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 },
+    const failedContext = context("/ordinary");
+    const failed = new RateLimiter(config, identity, {
+      increment: async () => { throw new Error("Redis unavailable"); },
+    });
+    await expect(failed.enforce(failedContext.value)).rejects.toMatchObject({
+      code: "RATE_LIMIT_UNAVAILABLE",
+      statusCode: 503,
+    });
+    expect(failedContext.headers["retry-after"]).toBe("1");
+
+    const identityContext = context("/ordinary");
+    const failedIdentity = new RateLimiter(
+      config,
+      { resolve: async () => { throw new Error("Identity unavailable"); } } as unknown as RateLimitIdentity,
+      { increment: async () => ({ count: 1, retryAfterSeconds: 60 }) },
+    );
+    await expect(failedIdentity.enforce(identityContext.value)).rejects.toMatchObject({
+      code: "RATE_LIMIT_UNAVAILABLE",
+      statusCode: 503,
     });
+    expect(identityContext.headers["retry-after"]).toBe("1");
   });
 
-  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();
-    }
+  test("enforces module-specific profiles with the shared atomic storage", async () => {
+    const increment = mock(async (_key: string, _ttlSeconds: number) => ({
+      count: 2,
+      retryAfterSeconds: 3600,
+    }));
+    const limiter = new RateLimiter(
+      config,
+      { resolve: async () => "user:test" } as unknown as RateLimitIdentity,
+      { increment },
+    );
+    const headers: Record<string, string> = {};
+
+    await limiter.enforceCustom(
+      "blog-create",
+      "author-hash",
+      3600,
+      3,
+      (name, value) => { headers[name.toLowerCase()] = value; },
+    );
+
+    expect(increment).toHaveBeenCalledWith(
+      "podokit:test:rate-limit:blog-create:author-hash",
+      3600,
+    );
+    expect(headers["ratelimit-remaining"]).toBe("1");
   });
 });