create-tigra 3.0.2 → 3.0.5

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

package/template/server/src/test/integration.setup.ts

@@ -0,0 +1,170 @@
+/**
+ * Integration test setup — REAL Testcontainers, NOT mocks.
+ *
+ * This file is the load-bearing piece of the money-path integration harness.
+ * It is wired via `vitest.integration.config.ts` → `setupFiles`, and is SEPARATE
+ * from the Docker-free unit `src/test/setup.ts` (which mocks env/DB/Redis).
+ *
+ * ── The central gotcha: env-before-import ──────────────────────────────────
+ * `src/config/env.ts` validates `process.env` at IMPORT time and calls
+ * `process.exit(1)` if DATABASE_URL / JWT_SECRET / … are missing. So the
+ * container connection strings MUST be in `process.env` BEFORE anything that
+ * transitively imports `env.ts` (which is `@/app`, `@/libs/prisma`, etc.).
+ *
+ * How we guarantee that ordering:
+ *   1. Vitest evaluates `setupFiles` — INCLUDING their top-level `await` — to
+ *      completion BEFORE it evaluates any test module. We start the containers
+ *      and run the schema sync here with TOP-LEVEL await, then populate
+ *      process.env.
+ *   2. The test files themselves import `@/app` / `@/libs/prisma` LAZILY
+ *      (`await import(...)` inside `beforeAll`), so a test module's own static
+ *      import graph never evaluates `env.ts` before this setup has finished.
+ *
+ * ── Why a process-global singleton ─────────────────────────────────────────
+ * Vitest runs `setupFiles` ONCE PER TEST FILE, not once for the whole run. With
+ * `singleFork: true` (vitest.integration.config.ts) every test file shares ONE
+ * worker process, so we boot the MySQL + Redis containers exactly once and cache
+ * them on `globalThis`. The second (and later) test files reuse the running
+ * containers instead of each spinning up their own pair and racing two
+ * concurrent `prisma db push` invocations against a saturated Docker daemon
+ * (which produced intermittent `P1001: can't reach database server`).
+ *
+ * ── Teardown ───────────────────────────────────────────────────────────────
+ * Because the containers are shared across files, we CANNOT tear them down from
+ * a per-file `afterAll` (the first file to finish would stop the DB out from
+ * under the others). Instead we stop them once on the worker process's
+ * `beforeExit`, and rely on Testcontainers' Ryuk reaper as the backstop — it
+ * removes any container we started the moment this process dies, even on crash.
+ *
+ * The committed template ships NO `prisma/migrations/` directory (apps run
+ * `prisma migrate dev` locally to author their first migration). `prisma migrate
+ * deploy` therefore has nothing to apply against a fresh container. We use
+ * `prisma db push` instead — it syncs the Prisma schema straight to the empty
+ * container database, which is exactly what an ephemeral test DB wants.
+ */
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import os from 'node:os';
+import { MySqlContainer, type StartedMySqlContainer } from '@testcontainers/mysql';
+import { RedisContainer, type StartedRedisContainer } from '@testcontainers/redis';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const serverRoot = path.resolve(__dirname, '..', '..');
+
+interface IntegrationContainers {
+  mysql: StartedMySqlContainer;
+  redis: StartedRedisContainer;
+  databaseUrl: string;
+  redisUrl: string;
+  uploadPublicDir: string;
+  uploadPrivateDir: string;
+}
+
+// Singleton cache on globalThis — survives across the per-file setup invocations
+// that share one worker process (singleFork). Keyed under a unique symbol so it
+// can't collide with anything else on the global object.
+const CONTAINERS_KEY = Symbol.for('create-tigra.integration.containers');
+const TEARDOWN_KEY = Symbol.for('create-tigra.integration.teardownRegistered');
+
+type GlobalWithContainers = typeof globalThis & {
+  [CONTAINERS_KEY]?: Promise<IntegrationContainers>;
+  [TEARDOWN_KEY]?: boolean;
+};
+
+const g = globalThis as GlobalWithContainers;
+
+async function bootContainers(): Promise<IntegrationContainers> {
+  const mysql = await new MySqlContainer('mysql:8.0')
+    .withDatabase('test_db')
+    .withUsername('test')
+    .withUserPassword('test')
+    .withRootPassword('rootpass')
+    .start();
+
+  const redis = await new RedisContainer('redis:7-alpine').start();
+
+  // MySqlContainer.getConnectionUri() returns `mysql://user:pass@host:port/db`
+  // — exactly Prisma's DATABASE_URL shape.
+  const databaseUrl = mysql.getConnectionUri();
+  const redisUrl = redis.getConnectionUrl();
+
+  // Populate env BEFORE any consumer of env.ts is imported.
+  process.env.NODE_ENV = 'test';
+  process.env.DATABASE_URL = databaseUrl;
+  process.env.REDIS_URL = redisUrl;
+  process.env.JWT_SECRET = 'integration-test-jwt-secret-at-least-32-chars-long';
+  process.env.JWT_ACCESS_EXPIRY = '15m';
+  process.env.JWT_REFRESH_EXPIRY = '7d';
+  // Tests don't send email and don't activate via the verify flow — register
+  // must mint tokens and login must work immediately, so disable verification.
+  process.env.REQUIRE_USER_VERIFICATION = 'false';
+  // This is a money-PATH harness, not a rate-limit test. Disabling the limiter
+  // keeps the suite deterministic (no per-IP counters, no auto-block self-ban
+  // across repeated register/login calls).
+  process.env.RATE_LIMIT_ENABLED = 'false';
+  // In NODE_ENV=test the app's CORS config (see app.ts) is NOT the dev "allow
+  // all" branch — it reads CORS_ORIGIN, and an undefined value makes
+  // @fastify/cors throw "Invalid CORS origin option" → 500 on EVERY request.
+  // Pin a concrete origin so the real app boots a valid CORS policy.
+  process.env.CORS_ORIGIN = 'http://localhost:3000';
+
+  // Two-tier upload dirs under an isolated temp root, set BEFORE env.ts is ever
+  // evaluated (the storage-service singleton reads env.UPLOAD_*_DIR at
+  // construction, which happens when a test lazily imports @/app). The
+  // files-route integration test writes fixtures directly into these dirs.
+  const uploadsRoot = path.join(os.tmpdir(), `create-tigra-uploads-${process.pid}`);
+  const uploadPublicDir = path.join(uploadsRoot, 'public');
+  const uploadPrivateDir = path.join(uploadsRoot, 'private');
+  process.env.UPLOAD_PUBLIC_DIR = uploadPublicDir;
+  process.env.UPLOAD_PRIVATE_DIR = uploadPrivateDir;
+
+  // Sync the Prisma schema into the fresh container DB. `db push` (not
+  // `migrate deploy`) because the template ships no migrations. The container's
+  // wait strategy already guarantees MySQL is accepting connections by here.
+  execSync('npx prisma db push --skip-generate --accept-data-loss', {
+    cwd: serverRoot,
+    env: process.env,
+    stdio: 'inherit',
+  });
+
+  return { mysql, redis, databaseUrl, redisUrl, uploadPublicDir, uploadPrivateDir };
+}
+
+// Boot once (or await the in-flight boot) — TOP-LEVEL await, completes before
+// any test module is evaluated.
+if (!g[CONTAINERS_KEY]) {
+  g[CONTAINERS_KEY] = bootContainers();
+}
+const containers = await g[CONTAINERS_KEY];
+
+// Subsequent per-file setup runs need env populated too (the boot only set it on
+// the first run). Re-assert from the cached values — cheap and idempotent.
+process.env.DATABASE_URL = containers.databaseUrl;
+process.env.REDIS_URL = containers.redisUrl;
+process.env.NODE_ENV = 'test';
+process.env.JWT_SECRET ??= 'integration-test-jwt-secret-at-least-32-chars-long';
+process.env.REQUIRE_USER_VERIFICATION = 'false';
+process.env.RATE_LIMIT_ENABLED = 'false';
+process.env.CORS_ORIGIN = 'http://localhost:3000';
+process.env.UPLOAD_PUBLIC_DIR = containers.uploadPublicDir;
+process.env.UPLOAD_PRIVATE_DIR = containers.uploadPrivateDir;
+
+// Register the teardown exactly once for the whole run. Tied to the worker
+// process lifecycle (NOT a per-file afterAll, which would stop the shared
+// containers while later files still need them). Ryuk is the crash-safe backstop.
+if (!g[TEARDOWN_KEY]) {
+  g[TEARDOWN_KEY] = true;
+  process.once('beforeExit', () => {
+    void containers.redis.stop();
+    void containers.mysql.stop();
+  });
+}
+
+export const containerInfo = {
+  databaseUrl: containers.databaseUrl,
+  redisUrl: containers.redisUrl,
+  uploadPublicDir: containers.uploadPublicDir,
+  uploadPrivateDir: containers.uploadPrivateDir,
+};

package/template/server/vitest.config.ts

@@ -23,11 +23,20 @@ export default defineConfig({
         functions: 80,
         branches: 80,
         statements: 80,
+        // Money-path forward-contract: any future payments module is held to a
+        // stricter bar than the 80% global gate. The scaffold ships no payments
+        // module, so this glob matches nothing today and is vacuously satisfied;
+        // the moment an app adds `src/modules/payments/**`, these thresholds
+        // start enforcing. Verified to not red an empty match on vitest v4.
+        'src/modules/payments/**': { lines: 95, branches: 90 },
       },
     },
     setupFiles: ['./src/test/setup.ts'],
     include: ['**/__tests__/**/*.test.ts', '**/*.test.ts'],
-    exclude: ['node_modules', 'dist'],
+    // Keep the unit gate Docker-free: integration tests boot Testcontainers and
+    // live behind `npm run test:integration` (vitest.integration.config.ts).
+    // The `**/*.test.ts` include would otherwise sweep in `*.integration.test.ts`.
+    exclude: ['node_modules', 'dist', '**/*.integration.test.ts'],
     testTimeout: 10000,
     hookTimeout: 10000,
   },

package/template/server/vitest.integration.config.ts

@@ -0,0 +1,50 @@
+import { defineConfig } from 'vitest/config';
+import { resolve } from 'path';
+
+/**
+ * Integration test config — REAL Testcontainers (MySQL 8 + Redis), app.inject().
+ *
+ * Deliberately SEPARATE from the Docker-free unit `vitest.config.ts`:
+ *   - includes ONLY `*.integration.test.ts`
+ *   - uses `src/test/integration.setup.ts` (boots containers) — NOT the mocking
+ *     unit setup `src/test/setup.ts`
+ *   - runs serially in a single fork: the containers are shared process-wide and
+ *     started once via the setup file's top-level await, so parallel workers
+ *     must not fight over them or each re-boot Docker.
+ *   - generous timeouts: container boot + `prisma db push` is slow on a cold
+ *     Docker daemon / first image pull.
+ *
+ * Run with: npm run test:integration
+ */
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    setupFiles: ['./src/test/integration.setup.ts'],
+    include: ['**/*.integration.test.ts'],
+    exclude: ['node_modules', 'dist'],
+    // Containers are shared — never parallelize across files or forks.
+    // Vitest 4 flattened `poolOptions.forks.singleFork` to the top-level
+    // `singleFork` option (the nested form is deprecated/removed).
+    pool: 'forks',
+    singleFork: true,
+    fileParallelism: false,
+    // Container boot + image pull + schema push can take well over a minute on
+    // a cold daemon; the setup file does all of that under hookTimeout.
+    testTimeout: 120_000,
+    hookTimeout: 120_000,
+    teardownTimeout: 60_000,
+    // No coverage gate on the integration suite — coverage thresholds live in
+    // the unit config. This suite is about real end-to-end behavior.
+  },
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, './src'),
+      '@modules': resolve(__dirname, './src/modules'),
+      '@libs': resolve(__dirname, './src/libs'),
+      '@config': resolve(__dirname, './src/config'),
+      '@shared': resolve(__dirname, './src/shared'),
+      '@jobs': resolve(__dirname, './src/jobs'),
+    },
+  },
+});