@podosoft/podokit 0.14.0 → 0.16.0

package/dist/templates/modules/admin-dashboard/files/tests/ui/users.ui.spec.ts

@@ -1,9 +1,9 @@
-import { expect, test } from "@playwright/test";
+import { expect, test } from "../helpers/disposable-users";
 import { ready } from "../helpers/hydration";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 
-test("admin can create a user with a custom role", async ({ page }) => {
+test("admin can create a user with a custom role", async ({ page, disposableUsers }) => {
   await ready(page, "/admin/users");
   await page.getByRole("button", { name: "Add user" }).click();
   const role = page.locator("#c-role");
@@ -16,7 +16,13 @@ test("admin can create a user with a custom role", async ({ page }) => {
   // pick the Moderator role from the select
   await role.click();
   await page.getByRole("option", { name: "Moderator" }).click();
+  const created = page.waitForResponse(
+    (response) =>
+      response.url().endsWith("/api/auth/admin/create-user") &&
+      response.request().method() === "POST",
+  );
   await page.getByRole("button", { name: "Create", exact: true }).click();
+  await disposableUsers.trackResponse(await created);
   await expect(page.getByText("User created")).toBeVisible();
   // it appears in the list, filterable by the Moderator role
   await page.locator("#toolbar-search").fill(email);
@@ -52,43 +58,27 @@ test("row menu exposes admin actions", async ({ page }) => {
   await expect(page.getByRole("menuitem", { name: "Impersonate" })).toBeVisible();
 });
 
-test("admin can approve a pending registration from the user list", async ({ page }) => {
+test("admin can approve a pending registration from the user list", async ({ page, disposableUsers }) => {
   const email = `pending-ui-${Date.now()}@example.com`;
-  const created = await page.request.post("/api/auth/admin/create-user", {
-    headers: { origin: base },
-    data: { email, password: "Podokit3e-Str0ng!pw", name: "Pending UI", role: "user" },
-  });
-  expect(created.ok()).toBeTruthy();
-  const userId = ((await created.json()).user?.id ?? "") as string;
+  const userId = await disposableUsers.create({ email, name: "Pending UI" });
+  expect(
+    (await page.request.post("/api/auth/admin/update-user", {
+      headers: { origin: base },
+      data: { userId, data: { signupApproved: false } },
+    })).ok(),
+  ).toBeTruthy();
 
-  try {
-    expect(userId).toBeTruthy();
-    expect(
-      (await page.request.post("/api/auth/admin/update-user", {
-        headers: { origin: base },
-        data: { userId, data: { signupApproved: false } },
-      })).ok(),
-    ).toBeTruthy();
-
-    await ready(page, "/admin/users");
-    await page.locator("#toolbar-search").fill(email);
-    await page.getByRole("button", { name: "Search", exact: true }).click();
-    const row = page.getByRole("row", { name: new RegExp(email) });
-    await expect(row.getByText("Pending approval")).toBeVisible();
-    await row.getByRole("button").click();
-    const response = page.waitForResponse(
-      (res) => res.url().endsWith("/api/auth/admin/update-user") && res.request().method() === "POST",
-    );
-    await page.getByRole("menuitem", { name: "Approve sign-up" }).click();
-    expect((await response).ok()).toBeTruthy();
-    await expect(page.getByText("Sign-up approved")).toBeVisible();
-    await expect(row.getByText("Active")).toBeVisible();
-  } finally {
-    if (userId) {
-      await page.request.post("/api/auth/admin/remove-user", {
-        headers: { origin: base },
-        data: { userId },
-      });
-    }
-  }
+  await ready(page, "/admin/users");
+  await page.locator("#toolbar-search").fill(email);
+  await page.getByRole("button", { name: "Search", exact: true }).click();
+  const row = page.getByRole("row", { name: new RegExp(email) });
+  await expect(row.getByText("Pending approval")).toBeVisible();
+  await row.getByRole("button").click();
+  const response = page.waitForResponse(
+    (res) => res.url().endsWith("/api/auth/admin/update-user") && res.request().method() === "POST",
+  );
+  await page.getByRole("menuitem", { name: "Approve sign-up" }).click();
+  expect((await response).ok()).toBeTruthy();
+  await expect(page.getByText("Sign-up approved")).toBeVisible();
+  await expect(row.getByText("Active")).toBeVisible();
 });

package/dist/templates/modules/admin-dashboard/module.manifest.json

@@ -119,7 +119,7 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### admin-dashboard\n- The `(admin)` route group and `admin-sidebar.svelte` are the admin-console shell for `/admin/*` only. Put signed-in product pages in `(app)` or in a separate route group with its own layout; do not place them under `(admin)`.\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `npm run admin:bootstrap -w <app>-api`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- Signed-in users can upload, replace, or remove their profile image from `/account` or `/admin/account`. Keep the shared policy visible in custom account UI: PNG, JPEG, or WebP; at most 2 MB and 2048 by 2048 pixels. Use the managed `/api/account/profile-image` endpoints instead of writing directly to storage or `user.image`.\n- Custom protected server layouts must call `requireBackendAvailable(locals)` from `$lib/server/guards` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\n- **Every list/table MUST use the shared `$lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `$lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand.\n"
+      "text": "### admin-dashboard\n- The `(admin)` route group and `admin-sidebar.svelte` are the admin-console shell for `/admin/*` only. Put signed-in product pages in `(app)` or in a separate route group with its own layout; do not place them under `(admin)`.\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `npm run admin:bootstrap -w <app>-api`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- Signed-in users can upload, replace, or remove their profile image from `/account` or `/admin/account`. Keep the shared policy visible in custom account UI: PNG, JPEG, or WebP; at most 2 MB and 2048 by 2048 pixels. Use the managed `/api/account/profile-image` endpoints instead of writing directly to storage or `user.image`.\n- `sidebar-user-menu.svelte` is specific to the admin sidebar. For a product shell outside `Sidebar.Provider`, use the managed `<AccountMenu {user} variant=\"identity\" side=\"top\" />` component.\n- Custom protected server layouts must call `requireBackendAvailable(locals)` from `$lib/server/guards` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\n- **Every list/table MUST use the shared `$lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `$lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand. For responsive columns, use `hideBelow` and apply the row context's `cellClass(columnKey)` to the matching cell.\n"
     },
     {
       "file": "apps/api/src/app.module.ts",

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key-verifier.spec.ts

@@ -0,0 +1,36 @@
+import { afterEach, describe, expect, it } from "@jest/globals";
+import { ApiKeyVerifier } from "./api-key-verifier";
+
+const originalApiKeys = process.env.API_KEYS;
+
+afterEach(() => {
+  if (originalApiKeys === undefined) {
+    delete process.env.API_KEYS;
+  } else {
+    process.env.API_KEYS = originalApiKeys;
+  }
+});
+
+describe("ApiKeyVerifier", () => {
+  it("accepts trimmed configured keys and rejects other values", () => {
+    process.env.API_KEYS = " first-service-key, second-service-key , ";
+    const verifier = new ApiKeyVerifier();
+
+    expect(verifier.isValid("first-service-key")).toBe(true);
+    expect(verifier.isValid("second-service-key")).toBe(true);
+    expect(verifier.isValid("different-service-key")).toBe(false);
+  });
+
+  it("rejects keys when the allowlist is empty", () => {
+    delete process.env.API_KEYS;
+
+    expect(new ApiKeyVerifier().isValid("any-service-key")).toBe(false);
+  });
+
+  it("compares fixed-length digests for differently sized input", () => {
+    process.env.API_KEYS = "short";
+    const verifier = new ApiKeyVerifier();
+
+    expect(verifier.isValid("a-much-longer-unconfigured-service-key")).toBe(false);
+  });
+});

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key-verifier.ts

@@ -0,0 +1,20 @@
+import { Injectable } from "@nestjs/common";
+import { createHash, timingSafeEqual } from "node:crypto";
+
+function digest(value: string): Buffer {
+  return createHash("sha256").update(value, "utf8").digest();
+}
+
+@Injectable()
+export class ApiKeyVerifier {
+  private readonly keyDigests = (process.env.API_KEYS ?? "")
+    .split(",")
+    .map((key) => key.trim())
+    .filter(Boolean)
+    .map(digest);
+
+  isValid(provided: string): boolean {
+    const supplied = digest(provided);
+    return this.keyDigests.some((expected) => timingSafeEqual(expected, supplied));
+  }
+}

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key.guard.spec.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it, jest } from "@jest/globals";
+import { type ExecutionContext, UnauthorizedException } from "@nestjs/common";
+import type { ApiKeyVerifier } from "./api-key-verifier";
+import { ApiKeyGuard } from "./api-key.guard";
+
+function requestContext(apiKey?: string): ExecutionContext {
+  return {
+    switchToHttp: () => ({
+      getRequest: () => ({
+        header: (name: string) => (name === "x-api-key" ? apiKey : undefined),
+      }),
+    }),
+  } as unknown as ExecutionContext;
+}
+
+describe("ApiKeyGuard", () => {
+  it("delegates a supplied key to the shared verifier", () => {
+    const verifier = {
+      isValid: jest.fn<(provided: string) => boolean>(() => true),
+    };
+    const guard = new ApiKeyGuard(verifier as unknown as ApiKeyVerifier);
+
+    expect(guard.canActivate(requestContext("service-key"))).toBe(true);
+    expect(verifier.isValid).toHaveBeenCalledWith("service-key");
+  });
+
+  it("rejects a missing key without invoking the verifier", () => {
+    const verifier = {
+      isValid: jest.fn<(provided: string) => boolean>(() => true),
+    };
+    const guard = new ApiKeyGuard(verifier as unknown as ApiKeyVerifier);
+
+    expect(() => guard.canActivate(requestContext())).toThrow(
+      new UnauthorizedException("Missing X-API-Key"),
+    );
+    expect(verifier.isValid).not.toHaveBeenCalled();
+  });
+
+  it("rejects a key that the verifier does not recognize", () => {
+    const verifier = {
+      isValid: jest.fn<(provided: string) => boolean>(() => false),
+    };
+    const guard = new ApiKeyGuard(verifier as unknown as ApiKeyVerifier);
+
+    expect(() => guard.canActivate(requestContext("invalid-key"))).toThrow(
+      new UnauthorizedException("Invalid API key"),
+    );
+  });
+});

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key.guard.ts

@@ -1,14 +1,11 @@
 import { type CanActivate, type ExecutionContext, Injectable, UnauthorizedException } from "@nestjs/common";
-import { timingSafeEqual } from "node:crypto";
 import type { Request } from "express";
+import { ApiKeyVerifier } from "./api-key-verifier";
 
 // Validates the X-API-Key header against the API_KEYS allowlist.
 @Injectable()
 export class ApiKeyGuard implements CanActivate {
-  private readonly keys = (process.env.API_KEYS ?? "")
-    .split(",")
-    .map((key) => key.trim())
-    .filter(Boolean);
+  constructor(private readonly verifier: ApiKeyVerifier) {}
 
   canActivate(context: ExecutionContext): boolean {
     const request = context.switchToHttp().getRequest<Request>();
@@ -16,12 +13,7 @@ export class ApiKeyGuard implements CanActivate {
     if (!provided) {
       throw new UnauthorizedException("Missing X-API-Key");
     }
-    const supplied = Buffer.from(provided);
-    const valid = this.keys.some((key) => {
-      const expected = Buffer.from(key);
-      return expected.length === supplied.length && timingSafeEqual(expected, supplied);
-    });
-    if (!valid) {
+    if (!this.verifier.isValid(provided)) {
       throw new UnauthorizedException("Invalid API key");
     }
     return true;

package/dist/templates/modules/api-key-auth/files/apps/api/src/api-key/api-key.module.ts

@@ -1,9 +1,11 @@
 import { Module } from "@nestjs/common";
 import { MachineController } from "../machine/machine.controller";
 import { ApiKeyGuard } from "./api-key.guard";
+import { ApiKeyVerifier } from "./api-key-verifier";
 
 @Module({
   controllers: [MachineController],
-  providers: [ApiKeyGuard],
+  providers: [ApiKeyGuard, ApiKeyVerifier],
+  exports: [ApiKeyVerifier],
 })
 export class ApiKeyModule {}

package/dist/templates/modules/api-key-auth/module.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "api-key-auth",
-  "description": "API-key auth for machine/service clients (X-API-Key), separate from user sessions. Provides an ApiKeyGuard and @ApiKeyProtected() to open a route to key holders. Requires auth.",
+  "description": "API-key auth for machine/service clients (X-API-Key), separate from user sessions. Provides an ApiKeyGuard and shared ApiKeyVerifier that compare SHA-256 key digests in constant time. Requires auth.",
   "requires": ["auth"],
   "targetApp": "api",
   "env": [

package/dist/templates/modules/auth/files/apps/api/src/auth/auth-environment.ts

@@ -0,0 +1,32 @@
+export function authSecret(): string {
+  const value = process.env.BETTER_AUTH_SECRET?.trim();
+  if (
+    process.env.NODE_ENV === "production" &&
+    (!value || value.startsWith("change-me-"))
+  ) {
+    throw new Error("BETTER_AUTH_SECRET must be set to a non-placeholder value in production");
+  }
+  const resolved = value || "development-only-auth-secret-min-32-characters";
+  if (resolved.length < 32) {
+    throw new Error("BETTER_AUTH_SECRET must contain at least 32 characters");
+  }
+  return resolved;
+}
+
+export function authBaseUrl(): string {
+  const value = process.env.BETTER_AUTH_URL?.trim();
+  if (process.env.NODE_ENV === "production" && !value) {
+    throw new Error("BETTER_AUTH_URL must be set in production");
+  }
+  const resolved = value || "http://localhost:5002";
+  let url: URL;
+  try {
+    url = new URL(resolved);
+  } catch {
+    throw new Error("BETTER_AUTH_URL must be a valid URL");
+  }
+  if (process.env.NODE_ENV === "production" && url.protocol !== "https:") {
+    throw new Error("BETTER_AUTH_URL must use HTTPS in production");
+  }
+  return resolved;
+}

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.runtime.spec.ts

@@ -0,0 +1,35 @@
+import { afterEach, describe, expect, it } from "@jest/globals";
+import { authBaseUrl, authSecret } from "./auth-environment";
+
+const originalEnvironment = {
+  NODE_ENV: process.env.NODE_ENV,
+  BETTER_AUTH_SECRET: process.env.BETTER_AUTH_SECRET,
+  BETTER_AUTH_URL: process.env.BETTER_AUTH_URL,
+};
+
+afterEach(() => {
+  for (const [key, value] of Object.entries(originalEnvironment)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+describe("authentication production environment", () => {
+  it("rejects missing and placeholder production secrets", () => {
+    process.env.NODE_ENV = "production";
+    delete process.env.BETTER_AUTH_SECRET;
+    expect(() => authSecret()).toThrow("must be set");
+    process.env.BETTER_AUTH_SECRET = "change-me-in-production-min-32-characters";
+    expect(() => authSecret()).toThrow("non-placeholder");
+  });
+
+  it("requires an HTTPS production origin", () => {
+    process.env.NODE_ENV = "production";
+    delete process.env.BETTER_AUTH_URL;
+    expect(() => authBaseUrl()).toThrow("must be set");
+    process.env.BETTER_AUTH_URL = "http://app.example.com";
+    expect(() => authBaseUrl()).toThrow("must use HTTPS");
+    process.env.BETTER_AUTH_URL = "https://app.example.com";
+    expect(authBaseUrl()).toBe("https://app.example.com");
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.ts

@@ -12,6 +12,7 @@ import { passkey } from "@better-auth/passkey";
 import { oauthProvider } from "@better-auth/oauth-provider";
 import { SIGNUP_APPROVAL_REQUIRED } from "@podosoft/podokit-contracts";
 import { runUserDeletedHandlers } from "./user-delete-handlers";
+import { authBaseUrl, authSecret } from "./auth-environment";
 // podokit:begin:auth-imports
 // podokit:end:auth-imports
 
@@ -214,8 +215,8 @@ export function buildAuth(config: AuthConfig) {
     ...(session ? { session } : {}),
     plugins,
     hooks,
-    secret: process.env.BETTER_AUTH_SECRET ?? "change-me-in-production-min-32-characters",
-    baseURL: process.env.BETTER_AUTH_URL ?? "http://localhost:5002",
+    secret: authSecret(),
+    baseURL: authBaseUrl(),
     advanced: {
       ipAddress: {
         // The API sits behind the SvelteKit server proxy, which forwards the

package/dist/templates/modules/auth/files/apps/api/src/health/health.controller.ts

@@ -2,12 +2,22 @@ import { Controller, Get, ServiceUnavailableException } from "@nestjs/common";
 import { InjectDataSource } from "@nestjs/typeorm";
 import { DataSource } from "typeorm";
 import { Public } from "@thallesp/nestjs-better-auth";
+import { ReadinessService, type ReadinessStatus } from "./readiness.service";
+
+interface ReadinessResponse {
+  status: "ready";
+  db: "up";
+  checks: Record<string, ReadinessStatus>;
+}
 
 // Health checks stay public under the global auth guard.
 @Public()
 @Controller("health")
 export class HealthController {
-  constructor(@InjectDataSource() private readonly dataSource: DataSource) {}
+  constructor(
+    @InjectDataSource() private readonly dataSource: DataSource,
+    private readonly readinessService: ReadinessService,
+  ) {}
 
   @Get()
   liveness(): { status: string; uptime: number; timestamp: string } {
@@ -15,12 +25,17 @@ export class HealthController {
   }
 
   @Get("ready")
-  async readiness(): Promise<{ status: string; db: string }> {
+  async readiness(): Promise<ReadinessResponse> {
+    let db: ReadinessStatus = "up";
     try {
       await this.dataSource.query("SELECT 1");
-      return { status: "ready", db: "up" };
     } catch {
-      throw new ServiceUnavailableException({ status: "degraded", db: "down" });
+      db = "down";
+    }
+    const checks = await this.readinessService.run();
+    if (db === "down" || Object.values(checks).includes("down")) {
+      throw new ServiceUnavailableException({ status: "degraded", db, checks });
     }
+    return { status: "ready", db: "up", checks };
   }
 }

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/queue.ts

@@ -1,8 +1,7 @@
+import { redisConnectionOptions, type RedisConnectionOptions } from "../config/redis.connection";
+
 export const DEMO_QUEUE = "demo";
 
-export function redisConnection(): { host: string; port: number } {
-  return {
-    host: process.env.REDIS_HOST ?? "localhost",
-    port: Number(process.env.REDIS_PORT ?? 6379),
-  };
+export function redisConnection(): RedisConnectionOptions {
+  return redisConnectionOptions(process.env, { maxRetriesPerRequest: null });
 }

package/dist/templates/modules/bullmq/module.manifest.json

@@ -2,6 +2,9 @@
   "name": "bullmq",
   "description": "Background jobs with BullMQ: a demo queue, a separate worker process, and enqueue/status endpoints (needs Redis).",
   "requires": [],
+  "requiredProjectFiles": [
+    "apps/api/src/config/redis.connection.ts"
+  ],
   "targetApp": "api",
   "dependencies": {
     "@nestjs/bullmq": "^11.0.4",
@@ -12,7 +15,7 @@
     "dev:worker": "nest start --watch --builder swc --entryFile main-worker"
   },
   "env": [
-    "# bullmq uses REDIS_HOST / REDIS_PORT (already defined above)"
+    "# bullmq uses REDIS_URL or the individual Redis settings defined above"
   ],
   "inject": [
     {

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",