create-tigra 3.0.2 → 3.0.3

package/template/server/package.json

@@ -9,6 +9,7 @@
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
     "start": "node dist/server.js",
     "test": "vitest run",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest run --coverage",
@@ -20,6 +21,7 @@
     "prisma:studio": "prisma studio",
     "lint": "eslint src/",
     "typecheck": "tsc --noEmit",
+    "audit": "npm audit --audit-level=high",
     "redis:flush": "tsx scripts/flush-redis.ts",
     "docker:up": "docker compose up -d",
     "docker:tools": "docker compose --profile tools up -d",
@@ -39,6 +41,7 @@
     "@fastify/rate-limit": "^10.3.0",
     "@fastify/static": "^9.1.3",
     "@prisma/client": "^6.19.3",
+    "@sentry/node": "^10.62.0",
     "argon2": "^0.44.0",
     "axios": "^1.17.0",
     "dotenv": "^16.4.7",
@@ -61,12 +64,15 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@testcontainers/mysql": "^12.0.3",
+    "@testcontainers/redis": "^12.0.3",
     "@types/node": "^20.17.10",
     "@types/uuid": "^10.0.0",
     "@vitest/coverage-v8": "^4.0.18",
     "@vitest/ui": "^4.0.18",
     "eslint": "^10.0.1",
     "prisma": "^6.19.3",
+    "testcontainers": "^12.0.3",
     "tsc-alias": "^1.8.16",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",

package/template/server/src/app.ts

@@ -6,10 +6,10 @@ import cookie from '@fastify/cookie';
 import jwt from '@fastify/jwt';
 import multipart from '@fastify/multipart';
 import fastifyStatic from '@fastify/static';
-import path from 'path';
-import { fileURLToPath } from 'url';
+import { randomUUID } from 'node:crypto';
 import { env } from '@config/env.js';
 import { logger } from '@libs/logger.js';
+import { Sentry } from '@libs/observability/sentry.js';
 import { markRequestStart, logRequestLine } from '@libs/requestLogger.js';
 import { initAuth } from '@libs/auth.js';
 import { registerQueryCounter } from '@libs/query-counter.js';
@@ -18,6 +18,7 @@ import { successResponse, errorResponse } from '@shared/responses/successRespons
 import { authRoutes } from '@modules/auth/auth.routes.js';
 import { usersRoutes } from '@modules/users/users.routes.js';
 import { adminRoutes } from '@modules/admin/admin.routes.js';
+import { filesRoutes } from '@modules/files/files.routes.js';
 import { fileStorageService } from '@libs/storage/file-storage.service.js';
 import { registerJobs } from '@jobs/index.js';
 import { RATE_LIMIT_ENABLED, getRateLimitRedisStore } from '@config/rate-limit.config.js';
@@ -38,6 +39,10 @@ import type {} from '@shared/types/index.js';
 export async function buildApp(): Promise<FastifyInstance> {
   const app = Fastify({
     logger: false,
+    // Request-id correlation: honour an inbound X-Request-Id (set by a reverse
+    // proxy / upstream service) so logs and Sentry events share one id across
+    // hops; otherwise mint a UUID. Works even with logger:false.
+    genReqId: (req) => (req.headers['x-request-id'] as string | undefined) ?? randomUUID(),
     // Trust proxy headers (X-Forwarded-For) for accurate client IP behind Nginx/load balancer
     trustProxy: env.NODE_ENV === 'production',
     // Graceful shutdown configuration
@@ -134,19 +139,22 @@ export async function buildApp(): Promise<FastifyInstance> {
     },
   });
 
-  // Static file serving for uploads
-  // Get __dirname equivalent in ES modules
-  const __filename = fileURLToPath(import.meta.url);
-  const __dirname = path.dirname(__filename);
+  // Initialize file storage (create both upload tiers) BEFORE mounting static,
+  // so the public root exists when @fastify/static checks it.
+  await fileStorageService.initialize();
 
+  // Static file serving for uploads — PUBLIC tier ONLY.
+  // SECURITY: the root is scoped to UPLOAD_PUBLIC_DIR (uploads/public), NOT the
+  // whole uploads/ tree. The PRIVATE tier (uploads/private) lives OUTSIDE this
+  // root and is unreachable through /uploads/* — it is served only by the
+  // auth-gated, owner-scoped route GET /api/v1/files/:filename (filesRoutes).
+  // The public avatar URL shape is unchanged: serving UPLOAD_PUBLIC_DIR at
+  // prefix '/uploads/' keeps avatars at /uploads/users/{id}/avatar/x.webp.
   await app.register(fastifyStatic, {
-    root: path.join(__dirname, '..', 'uploads'),
+    root: fileStorageService.getPublicDir(),
     prefix: '/uploads/',
   });
 
-  // Initialize file storage (create directories)
-  await fileStorageService.initialize();
-
   // --- Sync permanent IP blocks from DB to Redis ---
   await syncBlockedIpsToRedis();
 
@@ -158,6 +166,14 @@ export async function buildApp(): Promise<FastifyInstance> {
   // These paths must match the route registrations below.
   const monitoringPaths = new Set(['/api/v1/health', '/api/v1/ready', '/api/v1/live']);
 
+  // --- Request-id echo: surface request.id on the response so a client/proxy
+  // can correlate a failed call with the server log + Sentry event. Runs first
+  // so the header is present even when a later hook short-circuits (IP block,
+  // origin check). request.id is the genReqId value (inbound X-Request-Id or UUID).
+  app.addHook('onRequest', async (request, reply) => {
+    reply.header('x-request-id', request.id);
+  });
+
   // --- IP Block Check (runs before everything else) ---
   app.addHook('onRequest', async (request: FastifyRequest) => {
     if (monitoringPaths.has(request.url.split('?')[0])) {
@@ -241,8 +257,10 @@ export async function buildApp(): Promise<FastifyInstance> {
       return reply.status(error.statusCode).send(errorResponse(errorInfo.code, errorInfo.message));
     }
 
-    // Unexpected error — log and return generic 500
+    // Unexpected error — capture in Sentry (safe no-op when SDK uninitialized),
+    // then log and return a generic 500. reqId ties the event to the log line.
     const requestId = request.id || 'unknown';
+    Sentry.captureException(error, { extra: { reqId: requestId } });
     logger.error(
       {
         err: error,
@@ -306,6 +324,7 @@ export async function buildApp(): Promise<FastifyInstance> {
   await app.register(authRoutes, { prefix: '/api/v1' });
   await app.register(usersRoutes, { prefix: '/api/v1' });
   await app.register(adminRoutes, { prefix: '/api/v1' });
+  await app.register(filesRoutes, { prefix: '/api/v1' });
 
   // --- Background Jobs ---
   registerJobs(app);

package/template/server/src/config/env.ts

@@ -67,6 +67,17 @@ const envSchema = z.object({
   // --- File Upload ---
   MAX_FILE_SIZE_MB: optionalEnv(z.coerce.number().min(1).max(100).default(10)),
 
+  // --- Two-tier upload storage (see src/libs/storage/file-storage.service.ts) ---
+  // PUBLIC tier: served as static files at /uploads/ — viewable by ANYONE,
+  //   including unauthenticated users (e.g. social-style avatars). @fastify/static
+  //   is scoped to ONLY this directory so it can never serve a private file.
+  // PRIVATE tier: lives OUTSIDE the static root and is served ONLY through the
+  //   auth-gated streaming route GET /api/v1/files/:filename (owner-scoped).
+  // Both optional with sensible <cwd>/uploads/{public,private} defaults so a
+  // clean env still boots; the storage service resolves the defaults at runtime.
+  UPLOAD_PUBLIC_DIR: optionalEnv(z.string().optional()),
+  UPLOAD_PRIVATE_DIR: optionalEnv(z.string().optional()),
+
   // --- JWT Authentication ---
   JWT_SECRET: z
     .string()
@@ -118,8 +129,14 @@ const envSchema = z.object({
   RESEND_FROM_EMAIL: optionalEnv(z.string().email().default('onboarding@resend.dev')),
   CLIENT_URL: optionalEnv(z.string().url().default('http://localhost:3000')),
 
-  // --- Error Tracking (Optional) ---
+  // --- Error Tracking (Optional, Sentry) ---
+  // All inert without SENTRY_DSN — Sentry init becomes a no-op (see
+  // src/libs/observability/sentry.ts). Never hardcode a DSN.
   SENTRY_DSN: optionalEnv(z.string().url().optional()),
+  // Fraction of transactions sampled for performance tracing (0..1).
+  SENTRY_TRACES_SAMPLE_RATE: optionalEnv(z.coerce.number().min(0).max(1).default(0.1)),
+  // Environment tag attached to Sentry events; defaults to NODE_ENV when unset.
+  SENTRY_ENVIRONMENT: optionalEnv(z.string().optional()),
 });
 
 const parsed = envSchema.safeParse(process.env);
@@ -145,6 +162,10 @@ if (parsed.data.REQUIRE_USER_VERIFICATION && !parsed.data.RESEND_API_KEY) {
   process.exit(1);
 }
 
-export const env = parsed.data;
+export const env = {
+  ...parsed.data,
+  // Default the Sentry environment tag to NODE_ENV when not explicitly set.
+  SENTRY_ENVIRONMENT: parsed.data.SENTRY_ENVIRONMENT ?? parsed.data.NODE_ENV,
+};
 
 export type Env = z.infer<typeof envSchema>;

package/template/server/src/config/rate-limit.config.ts

@@ -116,6 +116,12 @@ export const RATE_LIMITS = {
     timeWindow: '1 minute',
   },
 
+  // Files — auth-gated private file streaming
+  FILES_GET: {
+    max: applyMultiplier(100),
+    timeWindow: '1 minute',
+  },
+
   // Admin routes
   ADMIN_DEFAULT: {
     max: applyMultiplier(30),

package/template/server/src/libs/logger.ts

@@ -3,6 +3,21 @@ import { env } from '@config/env.js';
 
 export const logger = pino({
   level: env.LOG_LEVEL,
+  // Never let secrets reach the logs. Covers auth/cookie headers (raw and under
+  // the `req` serializer) plus any password/token/secret field at any depth.
+  // `remove: true` drops the key entirely rather than emitting "[Redacted]".
+  redact: {
+    paths: [
+      'req.headers.authorization',
+      'req.headers.cookie',
+      'headers.authorization',
+      'headers.cookie',
+      '*.password',
+      '*.token',
+      '*.secret',
+    ],
+    remove: true,
+  },
   ...(env.NODE_ENV !== 'production' && {
     transport: {
       target: 'pino-pretty',

package/template/server/src/libs/observability/sentry.ts

@@ -0,0 +1,42 @@
+/**
+ * Sentry (error tracking) — env-gated, INERT by default.
+ *
+ * With no `SENTRY_DSN` set, `initSentry()` short-circuits and the SDK is never
+ * initialized. `Sentry.captureException(...)` elsewhere is a safe no-op when the
+ * SDK is uninitialized, so the rest of the app needs no DSN-presence guards.
+ *
+ * Never hardcode a DSN here or anywhere — it comes only from the environment.
+ */
+import * as Sentry from '@sentry/node';
+import { env } from '@config/env.js';
+import { logger } from '@libs/logger.js';
+
+let initialized = false;
+
+/**
+ * Initialize Sentry only when a DSN is configured.
+ *
+ * Call this as early as possible in the process lifecycle (top of server.ts),
+ * BEFORE the app is built, so error capture is active before any request is
+ * handled. A missing DSN is a clean no-op (no throw).
+ */
+export function initSentry(): void {
+  if (initialized) return;
+
+  if (!env.SENTRY_DSN) {
+    // No DSN → stay inert. One quiet debug line; nothing in prod logs at info.
+    logger.debug('[OBSERVABILITY] Sentry disabled (no DSN)');
+    return;
+  }
+
+  Sentry.init({
+    dsn: env.SENTRY_DSN,
+    tracesSampleRate: env.SENTRY_TRACES_SAMPLE_RATE,
+    environment: env.SENTRY_ENVIRONMENT,
+  });
+
+  initialized = true;
+  logger.info(`[OBSERVABILITY] Sentry enabled [${env.SENTRY_ENVIRONMENT}]`);
+}
+
+export { Sentry };

package/template/server/src/libs/requestLogger.ts

@@ -1,5 +1,6 @@
 import type { FastifyRequest, FastifyReply } from 'fastify';
 import { logger } from '@libs/logger.js';
+import { getClientIp } from '@libs/client-ip.js';
 
 const colors = {
   // Methods: blue=read, green=create, yellow=update, red=destroy, gray=meta
@@ -44,17 +45,22 @@ export function markRequestStart(request: FastifyRequest): void {
 /**
  * Log a single-line request/response summary (called in onResponse)
  *
- * Format: GET /api/v1/auth/me 200 OK (12ms)
+ * Format: GET /api/v1/auth/me 200 OK (12ms) [ip=203.0.113.7 reqId=<uuid>]
+ *
+ * The IP is the Cloudflare-/proxy-aware resolved client IP (getClientIp), so
+ * behind Cloudflare we log the CF-Connecting-IP, not the shared edge IP. reqId
+ * is request.id (inbound X-Request-Id or the minted UUID) for log↔Sentry tie-up.
  */
 export function logRequestLine(request: FastifyRequest, reply: FastifyReply): void {
   const duration = request.startTime ? Date.now() - request.startTime : 0;
   const statusCode = reply.statusCode;
   const statusMessage = reply.raw.statusMessage || '';
+  const clientIp = getClientIp(request);
 
   const methodColor = colors[request.method as keyof typeof colors] || colors.reset;
   const statusColor = getStatusColor(statusCode);
 
-  const line = `${methodColor}${request.method.padEnd(7)}${colors.reset}${request.url} ${statusColor}${statusCode} ${statusMessage}${colors.reset} ${colors.dim}(${formatDuration(duration)})${colors.reset}`;
+  const line = `${methodColor}${request.method.padEnd(7)}${colors.reset}${request.url} ${statusColor}${statusCode} ${statusMessage}${colors.reset} ${colors.dim}(${formatDuration(duration)}) [ip=${clientIp} reqId=${request.id}]${colors.reset}`;
 
   if (statusCode >= 500) {
     logger.error(line);

package/template/server/src/libs/storage/file-storage.service.ts

@@ -2,11 +2,25 @@
  * File Storage Service
  *
  * Handles local file system operations for user-uploaded files.
- * Directory structure: uploads/users/{userId}/<media-type>/
+ *
+ * ── Two-tier storage (security: closes the @fastify/static over-exposure) ──────
+ * PUBLIC tier  (UPLOAD_PUBLIC_DIR, default <cwd>/uploads/public):
+ *   uploads/public/users/{userId}/<media-type>/ — avatars and other assets meant
+ *   to be world-readable. THIS is the only directory @fastify/static serves at
+ *   /uploads/, so a private file can never leak through the static mount.
+ * PRIVATE tier (UPLOAD_PRIVATE_DIR, default <cwd>/uploads/private):
+ *   uploads/private/users/{userId}/ — sensitive files. Lives OUTSIDE the static
+ *   root and is reachable ONLY through the auth-gated, owner-scoped streaming
+ *   route GET /api/v1/files/:filename (see src/modules/files/).
+ *
+ * The public avatar URL shape is UNCHANGED — `/uploads/users/{id}/avatar/x.webp`
+ * — because the static mount serves UPLOAD_PUBLIC_DIR at prefix `/uploads/`, so
+ * the file just moves one level down on disk (under public/) with no URL churn.
  */
 
 import fs from 'fs/promises';
 import path from 'path';
+import { env } from '@config/env.js';
 import { logger } from '@libs/logger.js';
 import { InternalError } from '@shared/errors/errors.js';
 import { generateAvatarFilename } from './filename-sanitizer.js';
@@ -15,28 +29,53 @@ import { generateAvatarFilename } from './filename-sanitizer.js';
  * File Storage Service
  *
  * Manages local file storage with per-user directories and SEO-friendly naming.
- * All user media lives under uploads/users/{userId}/ for easy per-user cleanup.
+ * All user media lives under {tier}/users/{userId}/ for easy per-user cleanup.
  */
 class FileStorageService {
-  private readonly uploadDir: string;
-  private readonly usersDir: string;
+  /** PUBLIC tier root — served as static files at /uploads/ (world-readable). */
+  private readonly publicDir: string;
+  /** PRIVATE tier root — NEVER served statically; auth-gated route only. */
+  private readonly privateDir: string;
+  /** {publicDir}/users — per-user public media. */
+  private readonly publicUsersDir: string;
+  /** {privateDir}/users — per-user private media. */
+  private readonly privateUsersDir: string;
 
   constructor() {
-    // Base upload directory: server/uploads
-    this.uploadDir = path.join(process.cwd(), 'uploads');
-    // Users media directory: server/uploads/users
-    this.usersDir = path.join(this.uploadDir, 'users');
+    // Env-driven base paths, optional with <cwd>/uploads/{public,private}
+    // defaults so a clean env still boots (see src/config/env.ts).
+    this.publicDir = env.UPLOAD_PUBLIC_DIR ?? path.join(process.cwd(), 'uploads', 'public');
+    this.privateDir = env.UPLOAD_PRIVATE_DIR ?? path.join(process.cwd(), 'uploads', 'private');
+    this.publicUsersDir = path.join(this.publicDir, 'users');
+    this.privateUsersDir = path.join(this.privateDir, 'users');
+  }
+
+  /** PUBLIC tier root — read by app.ts to scope the @fastify/static mount. */
+  getPublicDir(): string {
+    return this.publicDir;
+  }
+
+  /** PRIVATE tier root — read by the files route for path-containment checks. */
+  getPrivateDir(): string {
+    return this.privateDir;
   }
 
   /**
-   * Gets the base directory for a user's media
+   * Gets the base PUBLIC directory for a user's media
    */
   private getUserDir(userId: string): string {
-    return path.join(this.usersDir, userId);
+    return path.join(this.publicUsersDir, userId);
   }
 
   /**
-   * Gets the avatar directory for a user
+   * Gets the PRIVATE per-user directory
+   */
+  private getUserPrivateDir(userId: string): string {
+    return path.join(this.privateUsersDir, userId);
+  }
+
+  /**
+   * Gets the avatar directory for a user (PUBLIC tier)
    */
   private getUserAvatarDir(userId: string): string {
     return path.join(this.getUserDir(userId), 'avatar');
@@ -189,6 +228,88 @@ class FileStorageService {
     return `/uploads/users/${userId}/avatar/${filename}`;
   }
 
+  /**
+   * Sanitizes a single-segment filename for safe disk storage.
+   *
+   * Strips every path component (returns only the basename) and rejects any
+   * remaining traversal/separator/null-byte chars, so the result can never
+   * escape the user's private directory. This is a storage-side guard; the
+   * files route applies its OWN validation + path-containment check on read.
+   *
+   * @throws InternalError on an empty or unusable name
+   */
+  private sanitizePrivateFilename(filename: string): string {
+    // Reject obvious traversal/separator/null-byte input up front.
+    if (!filename || filename.includes('\0') || filename.includes('/') || filename.includes('\\')) {
+      throw new InternalError('Invalid private filename', 'INVALID_FILENAME');
+    }
+    // Collapse to the basename and drop any leading dots so `..`/`.` can't slip
+    // through; keep a conservative allowlist (letters, digits, . _ -).
+    const base = path.basename(filename).replace(/^\.+/, '');
+    const cleaned = base.replace(/[^a-zA-Z0-9._-]/g, '');
+    if (!cleaned) {
+      throw new InternalError('Invalid private filename', 'INVALID_FILENAME');
+    }
+    return cleaned;
+  }
+
+  /**
+   * Saves a PRIVATE file for a user (PRIVATE tier — never served statically).
+   *
+   * Writes to UPLOAD_PRIVATE_DIR/users/{userId}/<sanitized-filename>. The file
+   * is reachable ONLY through the auth-gated, owner-scoped route
+   * GET /api/v1/files/:filename — there is no static mount over this tier.
+   *
+   * @param userId - User's unique ID (the owner; scopes the directory)
+   * @param filename - Desired filename (sanitized to a safe single segment)
+   * @param buffer - File contents
+   * @returns The sanitized filename and the owner-scoped absolute path
+   */
+  async savePrivateFile(
+    userId: string,
+    filename: string,
+    buffer: Buffer
+  ): Promise<{ filename: string; path: string }> {
+    try {
+      const safeName = this.sanitizePrivateFilename(filename);
+      const userDir = this.getUserPrivateDir(userId);
+      await this.ensureDirectoryExists(userDir);
+
+      const filePath = path.join(userDir, safeName);
+      await fs.writeFile(filePath, buffer);
+
+      logger.info({
+        msg: 'Private file saved successfully',
+        userId,
+        filename: safeName,
+        fileSize: buffer.length,
+      });
+
+      return { filename: safeName, path: filePath };
+    } catch (error) {
+      if (error instanceof InternalError) throw error;
+      logger.error({ err: error, msg: 'Failed to save private file', userId });
+      throw new InternalError('Failed to save private file', 'FILE_SAVE_FAILED');
+    }
+  }
+
+  /**
+   * Resolves the absolute path of a PRIVATE file for a user.
+   *
+   * Owner-scoped by construction: the path is derived from the supplied userId
+   * (the AUTHENTICATED user at the call site) — never a client-supplied owner.
+   * Returns the path WITHOUT touching disk; the caller checks existence and
+   * re-asserts path containment before streaming.
+   *
+   * @param userId - User's unique ID (the owner)
+   * @param filename - File name within the user's private directory
+   * @returns Absolute file path under UPLOAD_PRIVATE_DIR/users/{userId}/
+   */
+  getPrivateFilePath(userId: string, filename: string): string {
+    const safeName = this.sanitizePrivateFilename(filename);
+    return path.join(this.getUserPrivateDir(userId), safeName);
+  }
+
   /**
    * Checks if a file exists
    *
@@ -239,14 +360,21 @@ class FileStorageService {
   /**
    * Initializes the upload directory structure
    *
-   * Creates base uploads directory and users subdirectory if they don't exist.
-   * Should be called at application startup.
+   * Creates BOTH tiers (public + private) and their per-user subdirectories if
+   * they don't exist. Should be called at application startup. Creating the
+   * public dir up front matters because @fastify/static is mounted on it.
    */
   async initialize(): Promise<void> {
     try {
-      await this.ensureDirectoryExists(this.uploadDir);
-      await this.ensureDirectoryExists(this.usersDir);
-      logger.info({ msg: 'File storage initialized', uploadDir: this.uploadDir });
+      await this.ensureDirectoryExists(this.publicDir);
+      await this.ensureDirectoryExists(this.publicUsersDir);
+      await this.ensureDirectoryExists(this.privateDir);
+      await this.ensureDirectoryExists(this.privateUsersDir);
+      logger.info({
+        msg: 'File storage initialized',
+        publicDir: this.publicDir,
+        privateDir: this.privateDir,
+      });
     } catch (error) {
       logger.error({ err: error, msg: 'Failed to initialize file storage' });
       throw new InternalError('Failed to initialize file storage', 'STORAGE_INIT_FAILED');

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

@@ -0,0 +1,128 @@
+/**
+ * Admin role-gate integration test against REAL containers.
+ *
+ * Exercises the admin-gated route (`GET /api/v1/admin/stats`, behind
+ * `authenticate` + `authorize('ADMIN')`) at all three gates:
+ *   - 401 unauthenticated
+ *   - 403 as a normal logged-in USER
+ *   - 200 as an ADMIN
+ *
+ * The register endpoint cannot mint admins, so we SEED an ADMIN User row
+ * directly via prisma against the container DB, hashing the password with the
+ * server's own `@libs/password` lib so the real login path verifies it.
+ *
+ * Env-before-import: `@/app`, `@/libs/prisma`, `@/libs/password` are all
+ * imported LAZILY inside `beforeAll`, after integration.setup.ts has populated
+ * process.env with the container URLs.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import type { FastifyInstance } from 'fastify';
+
+let app: FastifyInstance;
+let prisma: typeof import('@/libs/prisma.js')['prisma'];
+
+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;
+}
+
+async function loginAndGetAccessCookie(email: string, password: string): Promise<string> {
+  const res = await app.inject({
+    method: 'POST',
+    url: '/api/v1/auth/login',
+    payload: { email, password },
+  });
+  expect(res.statusCode, `login for ${email} should succeed`).toBe(200);
+  const cookie = extractCookie(res.headers['set-cookie'], 'access_token');
+  expect(cookie, `login for ${email} must set an access_token cookie`).toBeTruthy();
+  return cookie!;
+}
+
+const adminCreds = { email: 'admin-it@example.com', password: 'AdminPass123!' };
+const userCreds = {
+  email: 'normal-it@example.com',
+  password: 'UserPass123!',
+  firstName: 'Normal',
+  lastName: 'User',
+};
+
+let adminCookie: string;
+let userCookie: string;
+
+beforeAll(async () => {
+  const [{ buildApp }, prismaMod, { hashPassword }] = await Promise.all([
+    import('@/app.js'),
+    import('@/libs/prisma.js'),
+    import('@/libs/password.js'),
+  ]);
+  prisma = prismaMod.prisma;
+
+  app = await buildApp();
+  await app.ready();
+
+  // Seed an ADMIN directly — the register endpoint only mints USER role.
+  await prisma.user.create({
+    data: {
+      email: adminCreds.email,
+      password: await hashPassword(adminCreds.password),
+      firstName: 'Admin',
+      lastName: 'It',
+      role: 'ADMIN',
+      isActive: true,
+    },
+  });
+
+  // Create the normal user via the real register endpoint.
+  const reg = await app.inject({
+    method: 'POST',
+    url: '/api/v1/auth/register',
+    payload: userCreds,
+  });
+  expect(reg.statusCode).toBe(201);
+
+  adminCookie = await loginAndGetAccessCookie(adminCreds.email, adminCreds.password);
+  userCookie = await loginAndGetAccessCookie(userCreds.email, userCreds.password);
+});
+
+afterAll(async () => {
+  await app?.close();
+});
+
+describe('admin role gate (real containers)', () => {
+  const ADMIN_ROUTE = '/api/v1/admin/stats';
+
+  it('rejects an UNAUTHENTICATED request (401)', async () => {
+    const res = await app.inject({ method: 'GET', url: ADMIN_ROUTE });
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('rejects a normal logged-in USER (403)', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: ADMIN_ROUTE,
+      cookies: { access_token: userCookie },
+    });
+    expect(res.statusCode).toBe(403);
+  });
+
+  it('allows an ADMIN (200)', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: ADMIN_ROUTE,
+      cookies: { access_token: adminCookie },
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.success).toBe(true);
+    // Dashboard stats shape (see admin.controller.getDashboardStats).
+    expect(body.data).toHaveProperty('totalUsers');
+  });
+});