create-tigra 3.0.2 → 3.0.3

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

@@ -0,0 +1,138 @@
+/**
+ * Money-path integration test — auth flow against REAL containers.
+ *
+ * No payments module exists in the scaffold, so the auth flow (register → login →
+ * authenticated read) is the money-adjacent critical path. This drives the REAL
+ * Fastify app via `app.inject()` against a real MySQL 8 + Redis booted by
+ * `src/test/integration.setup.ts`.
+ *
+ * Env-before-import: `@/app` (which pulls `env.ts` + prisma) is imported LAZILY
+ * inside `beforeAll`, AFTER the setup file has populated process.env with the
+ * container URLs. See integration.setup.ts for the full rationale.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import type { FastifyInstance } from 'fastify';
+
+let app: FastifyInstance;
+
+/**
+ * Pull the `access_token` cookie value out of a set-cookie header array.
+ * The login/register controllers set `access_token`, `refresh_token`, and a
+ * non-httpOnly `auth_session` indicator (see src/libs/cookies.ts).
+ */
+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 validUser = {
+  email: 'moneypath@example.com',
+  password: 'Password123!',
+  firstName: 'Money',
+  lastName: 'Path',
+};
+
+beforeAll(async () => {
+  // LAZY import — env is now populated by integration.setup.ts.
+  const { buildApp } = await import('@/app.js');
+  app = await buildApp();
+  await app.ready();
+});
+
+afterAll(async () => {
+  await app?.close();
+});
+
+describe('auth money-path (real containers)', () => {
+  let accessCookie: string | undefined;
+
+  it('POST /api/v1/auth/register with a valid body succeeds (201) and returns the user', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/auth/register',
+      payload: validUser,
+    });
+
+    expect(res.statusCode).toBe(201);
+    const body = res.json();
+    expect(body.success).toBe(true);
+    expect(body.data.user.email).toBe(validUser.email);
+    expect(body.data.user.role).toBe('USER');
+    // Password must never be echoed back.
+    expect(body.data.user.password).toBeUndefined();
+  });
+
+  it('POST /api/v1/auth/register with an INVALID body is rejected (400, Zod validation)', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/auth/register',
+      payload: { email: 'not-an-email', password: 'short', firstName: 'A', lastName: '' },
+    });
+
+    // fastify-type-provider-zod surfaces body validation as a Fastify
+    // validation error → the app's error handler maps it to 400 BAD_REQUEST.
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('POST /api/v1/auth/login with valid credentials succeeds and sets an access_token cookie', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/auth/login',
+      payload: { email: validUser.email, password: validUser.password },
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.success).toBe(true);
+    expect(body.data.user.email).toBe(validUser.email);
+
+    const setCookie = res.headers['set-cookie'];
+    accessCookie = extractCookie(setCookie, 'access_token');
+    expect(accessCookie, 'login must set an access_token cookie').toBeTruthy();
+    // The refresh cookie is also set (path-scoped to /api/v1/auth).
+    expect(extractCookie(setCookie, 'refresh_token')).toBeTruthy();
+  });
+
+  it('POST /api/v1/auth/login with a wrong password fails (401)', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/auth/login',
+      payload: { email: validUser.email, password: 'WrongPassword123!' },
+    });
+
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('GET /api/v1/auth/me WITHOUT the cookie is rejected (401)', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/v1/auth/me',
+    });
+
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('GET /api/v1/auth/me WITH the access_token cookie returns 200 and the right user', async () => {
+    expect(accessCookie, 'login test must have captured the cookie first').toBeTruthy();
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/v1/auth/me',
+      cookies: { access_token: accessCookie! },
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.success).toBe(true);
+    expect(body.data.email).toBe(validUser.email);
+    expect(body.data.role).toBe('USER');
+  });
+});

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';