create-tigra 3.0.0 → 3.0.3

package/template/server/src/modules/auth/auth.controller.ts

@@ -1,127 +1,128 @@
-import type { FastifyRequest, FastifyReply } from 'fastify';
-import { successResponse } from '@shared/responses/successResponse.js';
-import { UnauthorizedError, ForbiddenError } from '@shared/errors/errors.js';
-import { setAuthCookies, clearAuthCookies } from '@libs/cookies.js';
-import type {
-  RegisterInput,
-  LoginInput,
-  ForgotPasswordInput,
-  ResetPasswordInput,
-} from './auth.schemas.js';
-import * as authService from './auth.service.js';
-
-export async function register(
-  request: FastifyRequest<{ Body: RegisterInput }>,
-  reply: FastifyReply,
-): Promise<void> {
-  const deviceInfo = request.headers['user-agent'];
-  const ipAddress = request.ip;
-
-  const result = await authService.register(request.body, deviceInfo, ipAddress);
-
-  if (result.requiresVerification) {
-    reply.status(201).send(
-      successResponse('Registration successful. Please verify your account to continue.', { user: result.user }),
-    );
-    return;
-  }
-
-  setAuthCookies(reply, result.accessToken!, result.refreshToken!);
-  reply.status(201).send(successResponse('User registered successfully', { user: result.user }));
-}
-
-export async function login(
-  request: FastifyRequest<{ Body: LoginInput }>,
-  reply: FastifyReply,
-): Promise<void> {
-  const deviceInfo = request.headers['user-agent'];
-  const ipAddress = request.ip;
-
-  const result = await authService.login(request.body, deviceInfo, ipAddress);
-
-  setAuthCookies(reply, result.accessToken, result.refreshToken);
-  reply.send(successResponse('Logged in successfully', { user: result.user }));
-}
-
-export async function refresh(
-  request: FastifyRequest,
-  reply: FastifyReply,
-): Promise<void> {
-  const refreshToken = request.cookies.refresh_token;
-  if (!refreshToken) {
-    clearAuthCookies(reply);
-    throw new UnauthorizedError('Refresh token not provided', 'MISSING_REFRESH_TOKEN');
-  }
-
-  try {
-    const tokens = await authService.refresh(refreshToken);
-    setAuthCookies(reply, tokens.accessToken, tokens.refreshToken);
-    reply.send(successResponse('Token refreshed successfully', null));
-  } catch (error) {
-    // Session is definitively dead (refresh token revoked, user gone, inactive).
-    // Clear all auth cookies so the browser stops replaying them — otherwise the
-    // client keeps retrying refresh and middleware keeps redirecting, producing
-    // an infinite loop that trips the rate limiter.
-    if (error instanceof UnauthorizedError || error instanceof ForbiddenError) {
-      clearAuthCookies(reply);
-    }
-    throw error;
-  }
-}
-
-export async function logout(
-  request: FastifyRequest,
-  reply: FastifyReply,
-): Promise<void> {
-  const refreshToken = request.cookies.refresh_token;
-  if (refreshToken) {
-    await authService.logout(refreshToken);
-  }
-
-  clearAuthCookies(reply);
-  reply.send(successResponse('Logged out successfully', null));
-}
-
-export async function me(
-  request: FastifyRequest,
-  reply: FastifyReply,
-): Promise<void> {
-  const user = await authService.getCurrentUser(request.user.userId);
-  reply.send(successResponse('Current user retrieved', user));
-}
-
-export async function getSessions(
-  request: FastifyRequest,
-  reply: FastifyReply,
-): Promise<void> {
-  const sessions = await authService.getUserSessions(request.user.userId);
-  reply.send(successResponse('User sessions retrieved', sessions));
-}
-
-export async function logoutAllSessions(
-  request: FastifyRequest,
-  reply: FastifyReply,
-): Promise<void> {
-  const count = await authService.logoutAllSessions(request.user.userId);
-  clearAuthCookies(reply);
-  reply.send(
-    successResponse(`Successfully logged out from ${count} session(s)`, { count }),
-  );
-}
-
-export async function forgotPassword(
-  request: FastifyRequest<{ Body: ForgotPasswordInput }>,
-  reply: FastifyReply,
-): Promise<void> {
-  await authService.forgotPassword(request.body.email);
-  // Always return success to prevent email enumeration
-  reply.send(successResponse('If an account exists with that email, a reset link has been sent', null));
-}
-
-export async function resetPassword(
-  request: FastifyRequest<{ Body: ResetPasswordInput }>,
-  reply: FastifyReply,
-): Promise<void> {
-  await authService.resetPassword(request.body.token, request.body.newPassword);
-  reply.send(successResponse('Password reset successfully', null));
-}
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import { successResponse } from '@shared/responses/successResponse.js';
+import { UnauthorizedError, ForbiddenError } from '@shared/errors/errors.js';
+import { setAuthCookies, clearAuthCookies } from '@libs/cookies.js';
+import { getClientIp } from '@libs/client-ip.js';
+import type {
+  RegisterInput,
+  LoginInput,
+  ForgotPasswordInput,
+  ResetPasswordInput,
+} from './auth.schemas.js';
+import * as authService from './auth.service.js';
+
+export async function register(
+  request: FastifyRequest<{ Body: RegisterInput }>,
+  reply: FastifyReply,
+): Promise<void> {
+  const deviceInfo = request.headers['user-agent'];
+  const ipAddress = getClientIp(request);
+
+  const result = await authService.register(request.body, deviceInfo, ipAddress);
+
+  if (result.requiresVerification) {
+    reply.status(201).send(
+      successResponse('Registration successful. Please verify your account to continue.', { user: result.user }),
+    );
+    return;
+  }
+
+  setAuthCookies(reply, result.accessToken!, result.refreshToken!);
+  reply.status(201).send(successResponse('User registered successfully', { user: result.user }));
+}
+
+export async function login(
+  request: FastifyRequest<{ Body: LoginInput }>,
+  reply: FastifyReply,
+): Promise<void> {
+  const deviceInfo = request.headers['user-agent'];
+  const ipAddress = getClientIp(request);
+
+  const result = await authService.login(request.body, deviceInfo, ipAddress);
+
+  setAuthCookies(reply, result.accessToken, result.refreshToken);
+  reply.send(successResponse('Logged in successfully', { user: result.user }));
+}
+
+export async function refresh(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const refreshToken = request.cookies.refresh_token;
+  if (!refreshToken) {
+    clearAuthCookies(reply);
+    throw new UnauthorizedError('Refresh token not provided', 'MISSING_REFRESH_TOKEN');
+  }
+
+  try {
+    const tokens = await authService.refresh(refreshToken);
+    setAuthCookies(reply, tokens.accessToken, tokens.refreshToken);
+    reply.send(successResponse('Token refreshed successfully', null));
+  } catch (error) {
+    // Session is definitively dead (refresh token revoked, user gone, inactive).
+    // Clear all auth cookies so the browser stops replaying them — otherwise the
+    // client keeps retrying refresh and middleware keeps redirecting, producing
+    // an infinite loop that trips the rate limiter.
+    if (error instanceof UnauthorizedError || error instanceof ForbiddenError) {
+      clearAuthCookies(reply);
+    }
+    throw error;
+  }
+}
+
+export async function logout(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const refreshToken = request.cookies.refresh_token;
+  if (refreshToken) {
+    await authService.logout(refreshToken);
+  }
+
+  clearAuthCookies(reply);
+  reply.send(successResponse('Logged out successfully', null));
+}
+
+export async function me(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const user = await authService.getCurrentUser(request.user.userId);
+  reply.send(successResponse('Current user retrieved', user));
+}
+
+export async function getSessions(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const sessions = await authService.getUserSessions(request.user.userId);
+  reply.send(successResponse('User sessions retrieved', sessions));
+}
+
+export async function logoutAllSessions(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const count = await authService.logoutAllSessions(request.user.userId);
+  clearAuthCookies(reply);
+  reply.send(
+    successResponse(`Successfully logged out from ${count} session(s)`, { count }),
+  );
+}
+
+export async function forgotPassword(
+  request: FastifyRequest<{ Body: ForgotPasswordInput }>,
+  reply: FastifyReply,
+): Promise<void> {
+  await authService.forgotPassword(request.body.email);
+  // Always return success to prevent email enumeration
+  reply.send(successResponse('If an account exists with that email, a reset link has been sent', null));
+}
+
+export async function resetPassword(
+  request: FastifyRequest<{ Body: ResetPasswordInput }>,
+  reply: FastifyReply,
+): Promise<void> {
+  await authService.resetPassword(request.body.token, request.body.newPassword);
+  reply.send(successResponse('Password reset successfully', null));
+}

package/template/server/src/modules/files/__tests__/files.integration.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Files-route integration test — the load-bearing proof that the two-tier
+ * upload split (P0-2) closes the @fastify/static over-exposure.
+ *
+ * Drives the REAL Fastify app via `app.inject()` against the MySQL 8 + Redis
+ * booted by `src/test/integration.setup.ts`. The setup file points
+ * UPLOAD_PUBLIC_DIR / UPLOAD_PRIVATE_DIR at isolated temp dirs (exported via
+ * `containerInfo`) BEFORE env.ts is evaluated, so this test controls the files
+ * on disk and asserts exactly what is and isn't reachable.
+ *
+ * What this proves:
+ *   1. PUBLIC static still works WITHOUT auth (avatar URL shape unchanged).
+ *   2. EXPOSURE CLOSED — a file in the PRIVATE tier is NOT reachable via the
+ *      static /uploads/... path (404).
+ *   3. The auth-gated route: 401 without a cookie, 200 + bytes with one, 206 +
+ *      Content-Range for a Range request, 404 for a traversal attempt.
+ *
+ * Env-before-import: `@/app` is imported LAZILY inside `beforeAll`, after the
+ * setup file has populated process.env. See integration.setup.ts.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { FastifyInstance } from 'fastify';
+import { containerInfo } from '@/test/integration.setup.js';
+
+let app: FastifyInstance;
+
+/** Pull a named cookie value out of a set-cookie header array. */
+function extractCookie(setCookie: string[] | string | undefined, name: string): string | undefined {
+  const headers = Array.isArray(setCookie) ? setCookie : setCookie ? [setCookie] : [];
+  for (const header of headers) {
+    const first = header.split(';')[0];
+    const eq = first.indexOf('=');
+    if (eq === -1) continue;
+    if (first.slice(0, eq).trim() === name) {
+      return first.slice(eq + 1).trim();
+    }
+  }
+  return undefined;
+}
+
+const filesUser = {
+  email: 'files-route@example.com',
+  password: 'Password123!',
+  firstName: 'Files',
+  lastName: 'Route',
+};
+
+let accessCookie: string;
+let userId: string;
+
+const PRIVATE_BODY = 'the-quick-brown-fox-private-bytes';
+
+beforeAll(async () => {
+  const { buildApp } = await import('@/app.js');
+  app = await buildApp();
+  await app.ready();
+
+  // Register + login to mint an authed cookie and learn the user id.
+  const reg = await app.inject({ method: 'POST', url: '/api/v1/auth/register', payload: filesUser });
+  expect(reg.statusCode).toBe(201);
+  userId = reg.json().data.user.id as string;
+  expect(userId).toBeTruthy();
+
+  const login = await app.inject({
+    method: 'POST',
+    url: '/api/v1/auth/login',
+    payload: { email: filesUser.email, password: filesUser.password },
+  });
+  expect(login.statusCode).toBe(200);
+  const cookie = extractCookie(login.headers['set-cookie'], 'access_token');
+  expect(cookie, 'login must set an access_token cookie').toBeTruthy();
+  accessCookie = cookie!;
+
+  // --- Seed fixtures directly on disk, in the temp tiers the app reads. ---
+  // PUBLIC avatar (served statically, no auth).
+  const publicAvatarDir = path.join(containerInfo.uploadPublicDir, 'users', userId, 'avatar');
+  await fs.mkdir(publicAvatarDir, { recursive: true });
+  await fs.writeFile(path.join(publicAvatarDir, 'x.webp'), Buffer.from('PUBLIC-AVATAR-BYTES'));
+
+  // PRIVATE file (auth-gated route only).
+  const privateUserDir = path.join(containerInfo.uploadPrivateDir, 'users', userId);
+  await fs.mkdir(privateUserDir, { recursive: true });
+  await fs.writeFile(path.join(privateUserDir, 'doc.txt'), Buffer.from(PRIVATE_BODY));
+
+  // A SECRET file in the private tier, addressable only via traversal from the
+  // static root — used to prove the static mount cannot reach the private tier.
+  await fs.writeFile(path.join(containerInfo.uploadPrivateDir, 'secret.txt'), Buffer.from('TOP-SECRET'));
+});
+
+afterAll(async () => {
+  await app?.close();
+});
+
+describe('files two-tier uploads (real containers)', () => {
+  it('PUBLIC: GET /uploads/users/{id}/avatar/x.webp WITHOUT auth → 200 (static still served)', async () => {
+    const res = await app.inject({ method: 'GET', url: `/uploads/users/${userId}/avatar/x.webp` });
+    expect(res.statusCode).toBe(200);
+    expect(res.body).toContain('PUBLIC-AVATAR-BYTES');
+  });
+
+  it('EXPOSURE CLOSED: a PRIVATE-tier file is NOT reachable via /uploads/... (404)', async () => {
+    // Direct static path into the private tier does not exist under the public
+    // root, and traversal out of the public root is blocked by @fastify/static.
+    const direct = await app.inject({ method: 'GET', url: '/uploads/secret.txt' });
+    expect(direct.statusCode).toBe(404);
+
+    const traversal = await app.inject({
+      method: 'GET',
+      url: '/uploads/..%2f..%2fprivate%2fsecret.txt',
+    });
+    // @fastify/static rejects traversal (404/403); the one thing that must
+    // never happen is a 200 leaking the private bytes.
+    expect(traversal.statusCode).not.toBe(200);
+  });
+
+  it('PRIVATE route WITHOUT auth → 401', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/v1/files/doc.txt' });
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('PRIVATE route WITH auth → 200 and the file bytes', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/v1/files/doc.txt',
+      cookies: { access_token: accessCookie },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.body).toBe(PRIVATE_BODY);
+    expect(res.headers['accept-ranges']).toBe('bytes');
+    expect(res.headers['cache-control']).toBe('private');
+    expect(res.headers['content-type']).toContain('text/plain');
+  });
+
+  it('PRIVATE route with a Range header → 206 + correct Content-Range', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/v1/files/doc.txt',
+      cookies: { access_token: accessCookie },
+      headers: { range: 'bytes=0-3' },
+    });
+    expect(res.statusCode).toBe(206);
+    expect(res.headers['content-range']).toBe(`bytes 0-3/${PRIVATE_BODY.length}`);
+    expect(res.headers['content-length']).toBe('4');
+    expect(res.body).toBe(PRIVATE_BODY.slice(0, 4));
+  });
+
+  it('PRIVATE route traversal attempt → 404 (no existence leak, not 403)', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/v1/files/..%2f..%2fsecret',
+      cookies: { access_token: accessCookie },
+    });
+    expect(res.statusCode).toBe(404);
+  });
+});

package/template/server/src/modules/files/files.controller.ts

@@ -0,0 +1,180 @@
+/**
+ * Files Controller
+ *
+ * Auth-gated, owner-scoped streaming of PRIVATE-tier files.
+ *
+ * SECURITY model — three independent guards, any one of which forces a 404
+ * (never a 403: we do not leak whether a file exists):
+ *   1. Owner-scoped by construction. The on-disk path is built from the
+ *      AUTHENTICATED user's id (request.user.userId), never a client-supplied
+ *      owner. A user can therefore only ever read files under their OWN private
+ *      directory — there is no parameter that selects another user's files.
+ *   2. Filename validation. The :filename segment is rejected if it contains a
+ *      path separator, a `..` traversal, or a null byte.
+ *   3. Path containment. After path.resolve, the absolute target must still sit
+ *      inside the user's resolved private directory — a final belt-and-braces
+ *      check against any traversal the validation missed.
+ *
+ * NOTE for apps with a Prisma file/upload model: swap the path-based
+ * owner-scoping below for a DB lookup keyed on ownerId — load the row by id,
+ * 404 if it doesn't exist OR its ownerId !== request.user.userId, then stream
+ * from the stored path. The Range/streaming half of this handler stays the same.
+ */
+
+import { createReadStream } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { FastifyReply } from 'fastify';
+import { fileStorageService } from '@libs/storage/file-storage.service.js';
+import { NotFoundError } from '@shared/errors/errors.js';
+import type { AuthenticatedRequest } from '@shared/types/index.js';
+import { logger } from '@libs/logger.js';
+
+/** Map a file extension to a Content-Type. Falls back to octet-stream. */
+const CONTENT_TYPES: Record<string, string> = {
+  '.webp': 'image/webp',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.pdf': 'application/pdf',
+  '.txt': 'text/plain; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.csv': 'text/csv; charset=utf-8',
+  '.zip': 'application/zip',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg',
+};
+
+function contentTypeFor(filename: string): string {
+  return CONTENT_TYPES[path.extname(filename).toLowerCase()] ?? 'application/octet-stream';
+}
+
+/** Reject any filename that is not a single safe path segment. */
+function isUnsafeFilename(filename: string): boolean {
+  return (
+    !filename ||
+    filename.includes('\0') ||
+    filename.includes('/') ||
+    filename.includes('\\') ||
+    filename.includes('..')
+  );
+}
+
+/**
+ * Parse a single `bytes=start-end` Range header against a known total size.
+ * Returns null when there is no (usable) range and the full file should be
+ * sent, or an `unsatisfiable` marker when the range is out of bounds (→ 416).
+ */
+function parseRange(
+  rangeHeader: string | undefined,
+  size: number,
+): { start: number; end: number } | null | 'unsatisfiable' {
+  if (!rangeHeader) return null;
+  const match = /^bytes=(\d*)-(\d*)$/.exec(rangeHeader.trim());
+  if (!match) return null; // unparseable → ignore, serve full body (RFC 7233)
+
+  const [, startRaw, endRaw] = match;
+  if (startRaw === '' && endRaw === '') return null;
+
+  let start: number;
+  let end: number;
+  if (startRaw === '') {
+    // Suffix range: last N bytes.
+    const suffix = Number(endRaw);
+    if (suffix <= 0) return 'unsatisfiable';
+    start = Math.max(size - suffix, 0);
+    end = size - 1;
+  } else {
+    start = Number(startRaw);
+    end = endRaw === '' ? size - 1 : Number(endRaw);
+  }
+
+  if (Number.isNaN(start) || Number.isNaN(end) || start > end || start >= size) {
+    return 'unsatisfiable';
+  }
+  if (end >= size) end = size - 1;
+  return { start, end };
+}
+
+class FilesController {
+  /**
+   * GET /api/v1/files/:filename
+   *
+   * Streams a PRIVATE file owned by the authenticated user. Honors a Range
+   * header (206 partial content); otherwise sends the full file (200).
+   */
+  async getPrivateFile(
+    request: AuthenticatedRequest,
+    reply: FastifyReply,
+  ): Promise<void> {
+    const userId = request.user.userId;
+    const { filename } = request.params as { filename: string };
+
+    // Guard 2: filename validation. Any violation → 404 (no existence leak).
+    if (isUnsafeFilename(filename)) {
+      logger.warn({ msg: 'Rejected unsafe private file name', userId, filename });
+      throw new NotFoundError('File not found', 'FILE_NOT_FOUND');
+    }
+
+    // Guard 1: owner-scoped path, derived from the authenticated user id only.
+    const filePath = fileStorageService.getPrivateFilePath(userId, filename);
+
+    // Guard 3: path containment. The resolved absolute path must remain inside
+    // the user's resolved private directory.
+    const userPrivateRoot = path.resolve(
+      fileStorageService.getPrivateDir(),
+      'users',
+      userId,
+    );
+    const resolved = path.resolve(filePath);
+    if (resolved !== userPrivateRoot && !resolved.startsWith(userPrivateRoot + path.sep)) {
+      logger.warn({ msg: 'Private file path escaped owner root', userId, filename });
+      throw new NotFoundError('File not found', 'FILE_NOT_FOUND');
+    }
+
+    // Stat the file — missing/inaccessible/dir → 404 (no existence leak).
+    let stat;
+    try {
+      stat = await fs.stat(resolved);
+    } catch {
+      throw new NotFoundError('File not found', 'FILE_NOT_FOUND');
+    }
+    if (!stat.isFile()) {
+      throw new NotFoundError('File not found', 'FILE_NOT_FOUND');
+    }
+
+    const size = stat.size;
+    const contentType = contentTypeFor(filename);
+
+    reply.header('Accept-Ranges', 'bytes');
+    reply.header('Content-Type', contentType);
+    // Private files must never be cached by shared/proxy caches.
+    reply.header('Cache-Control', 'private');
+
+    const range = parseRange(request.headers.range, size);
+
+    if (range === 'unsatisfiable') {
+      reply.header('Content-Range', `bytes */${size}`);
+      reply.code(416);
+      return reply.send('Range Not Satisfiable');
+    }
+
+    if (range) {
+      const { start, end } = range;
+      reply.code(206);
+      reply.header('Content-Range', `bytes ${start}-${end}/${size}`);
+      reply.header('Content-Length', String(end - start + 1));
+      return reply.send(createReadStream(resolved, { start, end }));
+    }
+
+    // No range → full file.
+    reply.code(200);
+    reply.header('Content-Length', String(size));
+    return reply.send(createReadStream(resolved));
+  }
+}
+
+export const filesController = new FilesController();

package/template/server/src/modules/files/files.routes.ts

@@ -0,0 +1,46 @@
+/**
+ * Files Routes
+ *
+ * Auth-gated streaming of PRIVATE-tier files. This is the ONLY way to read a
+ * file stored under UPLOAD_PRIVATE_DIR — that directory is deliberately NOT
+ * served by @fastify/static (see app.ts), so a private file can never leak
+ * through /uploads/*.
+ */
+
+import type { FastifyInstance } from 'fastify';
+import { z } from 'zod';
+import { filesController } from './files.controller.js';
+import { authenticate } from '@libs/auth.js';
+import { RATE_LIMITS } from '@config/rate-limit.config.js';
+
+// Params are intentionally validated as a plain string here — the security
+// checks (separator / `..` / null-byte rejection + path containment) live in
+// the controller so a violation maps to 404 (no existence leak) rather than the
+// 400 a Zod-level regex rejection would produce.
+const GetPrivateFileParamsSchema = z.object({
+  filename: z.string().min(1),
+});
+
+export async function filesRoutes(fastify: FastifyInstance): Promise<void> {
+  /**
+   * Get a private file (owner-scoped, auth required)
+   *
+   * GET /api/v1/files/:filename
+   * Auth: Required (JWT) — 401 if unauthenticated.
+   * Serves UPLOAD_PRIVATE_DIR/users/{authenticatedUserId}/:filename.
+   * Honors a Range header (206 partial content); 404 on any miss/violation.
+   */
+  fastify.get<{ Params: { filename: string } }>(
+    '/files/:filename',
+    {
+      preValidation: [authenticate],
+      schema: {
+        params: GetPrivateFileParamsSchema,
+      },
+      config: {
+        rateLimit: RATE_LIMITS.FILES_GET,
+      },
+    },
+    filesController.getPrivateFile.bind(filesController),
+  );
+}

package/template/server/src/server.ts

@@ -1,3 +1,9 @@
+// Initialize Sentry as early as possible — before the app (and its routes) are
+// imported/built — so error capture is active before any request is handled.
+// Inert no-op when SENTRY_DSN is unset. See src/libs/observability/sentry.ts.
+import { initSentry } from '@libs/observability/sentry.js';
+initSentry();
+
 import { env } from '@config/env.js';
 import { logger } from '@libs/logger.js';
 import { testDatabaseConnection, disconnectPrisma } from '@libs/prisma.js';