@podosoft/podokit 0.15.0 → 0.16.0

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.bridge.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it, jest } from "@jest/globals";
+import type { EventsService } from "../events/events.service";
+import type { RedisService } from "../redis/redis.service";
+import { ProgressBridge } from "./progress.bridge";
+import { PROGRESS_CHANNEL } from "./progress.processor";
+
+describe("ProgressBridge", () => {
+  it("delivers worker fan-out locally without republishing it", async () => {
+    let handler: ((message: string) => void) | undefined;
+    const unsubscribe = jest.fn<() => Promise<void>>(() => Promise.resolve());
+    const subscribe = jest.fn(
+      (channel: string, listener: (message: string) => void): Promise<() => Promise<void>> => {
+        expect(channel).toBe(PROGRESS_CHANNEL);
+        handler = listener;
+        return Promise.resolve(unsubscribe);
+      },
+    );
+    const publishLocal = jest.fn<(data: unknown) => void>();
+    const redis = { subscribe } as unknown as RedisService;
+    const events = { publishLocal } as unknown as EventsService;
+    const bridge = new ProgressBridge(redis, events);
+
+    await bridge.onModuleInit();
+    handler?.('{"jobId":"1","progress":50}');
+    handler?.("invalid");
+
+    expect(publishLocal).toHaveBeenCalledTimes(1);
+    expect(publishLocal).toHaveBeenCalledWith({
+      type: "job-progress",
+      jobId: "1",
+      progress: 50,
+    });
+    await bridge.onModuleDestroy();
+    expect(unsubscribe).toHaveBeenCalledTimes(1);
+  });
+});

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.bridge.ts

@@ -1,19 +1,40 @@
-import { Injectable, type OnModuleInit } from "@nestjs/common";
+import {
+  Injectable,
+  Logger,
+  type OnModuleDestroy,
+  type OnModuleInit,
+} from "@nestjs/common";
 import { RedisService } from "../redis/redis.service";
 import { EventsService } from "../events/events.service";
 import { PROGRESS_CHANNEL } from "./progress.processor";
 
 // Runs in the API process: relays worker progress (Redis pub/sub) to SSE.
 @Injectable()
-export class ProgressBridge implements OnModuleInit {
+export class ProgressBridge implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(ProgressBridge.name);
+  private unsubscribe?: () => Promise<void>;
+
   constructor(
     private readonly redis: RedisService,
     private readonly events: EventsService,
   ) {}
 
-  onModuleInit(): void {
-    this.redis.subscribe(PROGRESS_CHANNEL, (message) => {
-      this.events.publish({ type: "job-progress", ...JSON.parse(message) });
+  async onModuleInit(): Promise<void> {
+    this.unsubscribe = await this.redis.subscribe(PROGRESS_CHANNEL, (message) => {
+      try {
+        const parsed: unknown = JSON.parse(message);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+          this.logger.warn("Discarded invalid job progress event");
+          return;
+        }
+        this.events.publishLocal({ type: "job-progress", ...parsed });
+      } catch {
+        this.logger.warn("Discarded malformed job progress event");
+      }
     });
   }
+
+  async onModuleDestroy(): Promise<void> {
+    await this.unsubscribe?.();
+  }
 }

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage.service.spec.ts

@@ -0,0 +1,35 @@
+import { HeadBucketCommand } from "@aws-sdk/client-s3";
+import { describe, expect, it, jest } from "@jest/globals";
+import type { ReadinessService } from "../health/readiness.service";
+import { StorageService } from "./storage.service";
+
+describe("StorageService readiness", () => {
+  it("registers a bucket probe and releases resources on shutdown", async () => {
+    const unregister = jest.fn();
+    const register = jest.fn<
+      (name: string, check: () => Promise<void>) => () => void
+    >(() => unregister);
+    const service = new StorageService({ register } as unknown as ReadinessService);
+    const send = jest
+      .fn<(...arguments_: unknown[]) => Promise<unknown>>()
+      .mockResolvedValue({});
+    const destroy = jest.fn();
+    Object.defineProperty(service, "client", {
+      value: { send, destroy },
+    });
+
+    service.onModuleInit();
+    expect(register).toHaveBeenCalledWith("object-storage", expect.any(Function));
+    const probe = register.mock.calls[0]?.[1];
+    expect(probe).toBeDefined();
+    await probe?.();
+    expect(send).toHaveBeenCalledWith(
+      expect.any(HeadBucketCommand),
+      expect.objectContaining({ abortSignal: expect.any(AbortSignal) }),
+    );
+
+    service.onModuleDestroy();
+    expect(unregister).toHaveBeenCalledTimes(1);
+    expect(destroy).toHaveBeenCalledTimes(1);
+  });
+});

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage.service.ts

@@ -1,17 +1,31 @@
-import { Injectable } from "@nestjs/common";
+import { Injectable, type OnModuleDestroy, type OnModuleInit } from "@nestjs/common";
 import {
   DeleteObjectCommand,
   GetObjectCommand,
+  HeadBucketCommand,
   PutObjectCommand,
   S3Client,
 } from "@aws-sdk/client-s3";
 import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { ReadinessService } from "../health/readiness.service";
 import { storageClientConfig, storageSettings } from "./storage.config";
 
 @Injectable()
-export class StorageService {
+export class StorageService implements OnModuleInit, OnModuleDestroy {
   private readonly client = new S3Client(storageClientConfig());
   private readonly bucket = storageSettings().bucket;
+  private unregisterReadiness?: () => void;
+
+  constructor(private readonly readiness: ReadinessService) {}
+
+  onModuleInit(): void {
+    this.unregisterReadiness = this.readiness.register("object-storage", async () => {
+      await this.client.send(
+        new HeadBucketCommand({ Bucket: this.bucket }),
+        { abortSignal: AbortSignal.timeout(3_000) },
+      );
+    });
+  }
 
   async put(key: string, body: Buffer | string, contentType?: string): Promise<void> {
     await this.client.send(
@@ -34,4 +48,9 @@ export class StorageService {
   async delete(key: string): Promise<void> {
     await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: key }));
   }
+
+  onModuleDestroy(): void {
+    this.unregisterReadiness?.();
+    this.client.destroy();
+  }
 }

package/dist/templates/modules/object-storage-s3/module.manifest.json

@@ -2,6 +2,9 @@
   "name": "object-storage-s3",
   "description": "S3-compatible object storage (AWS S3 or MinIO, chosen by STORAGE_PROVIDER) with a StorageService and presigned URLs.",
   "requires": [],
+  "requiredProjectFiles": [
+    "apps/api/src/health/readiness.service.ts"
+  ],
   "targetApp": "api",
   "dependencies": {
     "@aws-sdk/client-s3": "^3.700.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;
+  }
+}