create-tigra 2.8.0 → 3.0.0

package/template/server/package.json

@@ -1,75 +1,76 @@
-{
-  "name": "{{PROJECT_NAME}}-server",
-  "version": "1.0.0",
-  "type": "module",
-  "description": "",
-  "main": "dist/server.js",
-  "scripts": {
-    "dev": "tsx watch src/server.ts",
-    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
-    "start": "node dist/server.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:ui": "vitest --ui",
-    "test:coverage": "vitest run --coverage",
-    "prisma:generate": "prisma generate",
-    "prisma:migrate:dev": "prisma migrate dev",
-    "prisma:migrate:deploy": "prisma migrate deploy",
-    "prisma:reset": "prisma migrate reset",
-    "prisma:seed": "prisma db seed",
-    "prisma:studio": "prisma studio",
-    "lint": "eslint src/",
-    "typecheck": "tsc --noEmit",
-    "redis:flush": "tsx scripts/flush-redis.ts",
-    "docker:up": "docker compose up -d",
-    "docker:down": "docker compose down",
-    "docker:logs": "docker compose logs -f",
-    "generate:env": "node -e \"import('fs').then(f=>{if(f.existsSync('.env'))console.log('.env already exists, skipping');else{f.copyFileSync('.env.example','.env');console.log('.env created from .env.example')}})\""
-  },
-  "prisma": {
-    "seed": "tsx prisma/seed.ts"
-  },
-  "dependencies": {
-    "@fastify/cookie": "^11.0.2",
-    "@fastify/cors": "^11.2.0",
-    "@fastify/helmet": "^13.0.2",
-    "@fastify/jwt": "^10.0.0",
-    "@fastify/multipart": "^9.0.2",
-    "@fastify/rate-limit": "^10.3.0",
-    "@fastify/static": "^9.0.0",
-    "@prisma/client": "^6.19.2",
-    "argon2": "^0.44.0",
-    "axios": "^1.7.9",
-    "dotenv": "^16.4.7",
-    "fastify": "^5.7.4",
-    "fastify-type-provider-zod": "^6.1.0",
-    "ioredis": "^5.9.2",
-    "pino": "^10.3.1",
-    "pino-pretty": "^13.1.3",
-    "resend": "^6.9.4",
-    "sharp": "^0.33.5",
-    "uuid": "^10.0.0",
-    "zod": "^4.3.6"
-  },
-  "overrides": {
-    "bn.js": ">=5.2.3",
-    "flatted": ">=3.4.2",
-    "@typescript-eslint/typescript-estree": {
-      "minimatch": ">=10.2.1"
-    }
-  },
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@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.2",
-    "tsc-alias": "^1.8.16",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.55.0",
-    "vitest": "^4.0.18"
-  }
-}
+{
+  "name": "{{PROJECT_NAME}}-server",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "",
+  "main": "dist/server.js",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "start": "node dist/server.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "prisma:generate": "prisma generate",
+    "prisma:migrate:dev": "prisma migrate dev",
+    "prisma:migrate:deploy": "prisma migrate deploy",
+    "prisma:reset": "prisma migrate reset",
+    "prisma:seed": "prisma db seed",
+    "prisma:studio": "prisma studio",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "redis:flush": "tsx scripts/flush-redis.ts",
+    "docker:up": "docker compose up -d",
+    "docker:tools": "docker compose --profile tools up -d",
+    "docker:down": "docker compose --profile tools down",
+    "docker:logs": "docker compose logs -f",
+    "generate:env": "node -e \"import('fs').then(f=>{if(f.existsSync('.env'))console.log('.env already exists, skipping');else{f.copyFileSync('.env.example','.env');console.log('.env created from .env.example')}})\""
+  },
+  "prisma": {
+    "seed": "tsx prisma/seed.ts"
+  },
+  "dependencies": {
+    "@fastify/cookie": "^11.0.2",
+    "@fastify/cors": "^11.2.0",
+    "@fastify/helmet": "^13.0.2",
+    "@fastify/jwt": "^10.1.0",
+    "@fastify/multipart": "^9.0.2",
+    "@fastify/rate-limit": "^10.3.0",
+    "@fastify/static": "^9.1.3",
+    "@prisma/client": "^6.19.3",
+    "argon2": "^0.44.0",
+    "axios": "^1.17.0",
+    "dotenv": "^16.4.7",
+    "fastify": "^5.8.5",
+    "fastify-type-provider-zod": "^6.1.0",
+    "ioredis": "^5.9.2",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "resend": "^6.9.4",
+    "sharp": "^0.33.5",
+    "uuid": "^10.0.0",
+    "zod": "^4.3.6"
+  },
+  "overrides": {
+    "bn.js": ">=5.2.3",
+    "flatted": ">=3.4.2",
+    "@typescript-eslint/typescript-estree": {
+      "minimatch": ">=10.2.1"
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@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",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.55.0",
+    "vitest": "^4.0.18"
+  }
+}

package/template/server/prisma/seed.ts

@@ -3,9 +3,27 @@ import argon2 from 'argon2';
 
 const prisma = new PrismaClient();
 
+// Well-known dev-only fallbacks. NEVER used in production — the guard in
+// main() refuses to seed when NODE_ENV=production, and even outside production
+// you can override via SEED_ADMIN_PASSWORD / SEED_USER_PASSWORD.
+const DEV_ADMIN_PASSWORD = 'Admin123!';
+const DEV_USER_PASSWORD = 'User123!';
+
 async function main(): Promise<void> {
-  const adminPassword = await argon2.hash('Admin123!');
-  const userPassword = await argon2.hash('User123!');
+  // Refuse to seed production: this script creates a well-known admin account
+  // (admin@example.com). On a production database that is a backdoor, not a
+  // convenience. Seed data belongs to dev/test environments only.
+  if (process.env.NODE_ENV === 'production') {
+    console.error(
+      'Refusing to seed: NODE_ENV is "production".\n' +
+      'The seed script creates well-known demo accounts (admin@example.com) and must never run against a production database.\n' +
+      'If you really need initial data in production, create it manually or write a dedicated, audited provisioning script.',
+    );
+    process.exit(1);
+  }
+
+  const adminPassword = await argon2.hash(process.env.SEED_ADMIN_PASSWORD || DEV_ADMIN_PASSWORD);
+  const userPassword = await argon2.hash(process.env.SEED_USER_PASSWORD || DEV_USER_PASSWORD);
 
   const admin = await prisma.user.upsert({
     where: { email: 'admin@example.com' },
@@ -31,13 +49,11 @@ async function main(): Promise<void> {
     },
   });
 
-  // eslint-disable-next-line no-console
   console.log('Seeded users:', { admin: admin.email, user: user.email });
 }
 
 main()
   .catch((error) => {
-    // eslint-disable-next-line no-console
     console.error('Seed failed:', error);
     process.exit(1);
   })

package/template/server/src/app.ts

@@ -1,4 +1,4 @@
-import Fastify, { type FastifyError, type FastifyRequest } from 'fastify';
+import Fastify, { type FastifyError, type FastifyInstance, type FastifyRequest } from 'fastify';
 import cors from '@fastify/cors';
 import helmet from '@fastify/helmet';
 import rateLimit from '@fastify/rate-limit';
@@ -21,6 +21,7 @@ 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';
 import { isIpBlocked, recordRateLimitViolation, syncBlockedIpsToRedis } from '@libs/ip-block.js';
+import { isOriginAllowed } from '@libs/origin-check.js';
 import { ForbiddenError } from '@shared/errors/errors.js';
 import {
   serializerCompiler,
@@ -31,15 +32,18 @@ import {
 // Import types to register Fastify augmentations
 import type {} from '@shared/types/index.js';
 
-export async function buildApp() {
+export async function buildApp(): Promise<FastifyInstance> {
   const app = Fastify({
     logger: false,
     // Trust proxy headers (X-Forwarded-For) for accurate client IP behind Nginx/load balancer
     trustProxy: env.NODE_ENV === 'production',
     // Graceful shutdown configuration
     forceCloseConnections: true, // Force close idle connections on shutdown
-    requestTimeout: 30000, // 30s request timeout
-    connectionTimeout: 60000, // 60s connection timeout
+    // Env-configurable timeouts (defaults: 30s request, 60s connection).
+    // Long-running routes (LLM calls, exports) may need 180s+ — raise the
+    // reverse proxy timeout to match. See REQUEST_TIMEOUT_MS in .env.example.
+    requestTimeout: env.REQUEST_TIMEOUT_MS,
+    connectionTimeout: env.CONNECTION_TIMEOUT_MS,
     keepAliveTimeout: 5000, // 5s keep-alive timeout
     // Request body size limits (prevent DoS attacks)
     bodyLimit: 1048576, // 1MB default limit (1024 * 1024)
@@ -133,26 +137,54 @@ export async function buildApp() {
   // --- Sync permanent IP blocks from DB to Redis ---
   await syncBlockedIpsToRedis();
 
+  // Monitoring endpoints exempt from IP blocking and request logging.
+  // Health probes (Coolify/Docker/K8s/load balancers) come from infrastructure
+  // IPs that must NEVER be blocked — a blocked probe IP would mark a healthy
+  // container as dead and restart-loop it. Exact match on the path (query
+  // string stripped) so the exemption cannot be widened by crafted URLs.
+  // These paths must match the route registrations below.
+  const monitoringPaths = new Set(['/api/v1/health', '/api/v1/ready', '/api/v1/live']);
+
   // --- IP Block Check (runs before everything else) ---
   app.addHook('onRequest', async (request: FastifyRequest) => {
+    if (monitoringPaths.has(request.url.split('?')[0])) {
+      return; // never block health probes
+    }
     if (await isIpBlocked(request.ip)) {
       throw new ForbiddenError('Access denied', 'IP_BLOCKED');
     }
   });
 
-  // --- Request/Response Logging ---
-  const skipLogPaths = new Set(['/api/v1/health', '/api/v1/ready', '/api/v1/live']);
+  // --- CSRF defense-in-depth: Origin check on state-changing methods ---
+  // With sameSite=none cookies (cross-origin deployments), the browser attaches
+  // auth cookies to cross-site requests. If a browser sends an Origin header on
+  // a state-changing request, it must be same-origin or a configured CORS
+  // origin. Requests WITHOUT an Origin header (curl, Postman, server-to-server,
+  // health probes) are allowed — they carry no ambient cookies and are not
+  // CSRF vectors. See src/libs/origin-check.ts for the full rationale.
+  const stateChangingMethods = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+  const allowAllOrigins = corsOrigin === true;
+  const allowedOrigins = new Set<string>(
+    Array.isArray(corsOrigin) ? corsOrigin : typeof corsOrigin === 'string' ? [corsOrigin] : [],
+  );
 
+  app.addHook('onRequest', async (request: FastifyRequest) => {
+    if (!stateChangingMethods.has(request.method)) return;
+    if (isOriginAllowed(request.headers.origin, request.headers.host, allowedOrigins, allowAllOrigins)) return;
+    throw new ForbiddenError('Origin not allowed', 'ORIGIN_NOT_ALLOWED');
+  });
+
+  // --- Request/Response Logging ---
   app.addHook('preHandler', async (request) => {
     const pathname = request.url.split('?')[0];
-    if (!skipLogPaths.has(pathname)) {
+    if (!monitoringPaths.has(pathname)) {
       markRequestStart(request);
     }
   });
 
   app.addHook('onResponse', async (request, reply) => {
     const pathname = request.url.split('?')[0];
-    if (!skipLogPaths.has(pathname)) {
+    if (!monitoringPaths.has(pathname)) {
       logRequestLine(request, reply);
     }
   });

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

@@ -5,67 +5,114 @@ import dotenv from 'dotenv';
 process.env.DOTENV_CONFIG_QUIET = 'true';
 dotenv.config();
 
+/**
+ * Treat present-but-empty env vars as unset.
+ *
+ * The .env ↔ .env.example sync convention produces `VAR=""` placeholders, and
+ * Zod's `.optional()` rejects a present-but-empty string (e.g. `.url()` or
+ * `.min(32)` fails on "") — which killed boot in incident aeaaf94a. Mapping
+ * "" → undefined makes empty placeholders behave like missing vars: optionals
+ * stay undefined, defaults kick in. Production presence guards (`!env.VAR`)
+ * keep working since "" parses to undefined.
+ */
+const optionalEnv = <T extends z.ZodTypeAny>(schema: T): z.ZodPreprocess<T> =>
+  z.preprocess((v) => (v === '' ? undefined : v), schema);
+
 const envSchema = z.object({
   // --- Application ---
-  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
-  PORT: z.coerce.number().int().min(1).max(65535).default(8000),
-  HOST: z.string().default('0.0.0.0'),
+  NODE_ENV: optionalEnv(z.enum(['development', 'production', 'test']).default('development')),
+  PORT: optionalEnv(z.coerce.number().int().min(1).max(65535).default(8000)),
+  HOST: optionalEnv(z.string().default('0.0.0.0')),
+
+  // --- Server timeouts ---
+  // Fastify request/connection timeouts. Defaults match the previous hardcoded
+  // values. Long-running routes (LLM calls, large exports) may need 180s+ —
+  // remember the reverse proxy (Nginx/Coolify) timeout must be raised to match,
+  // or the proxy will cut the connection before the server does.
+  REQUEST_TIMEOUT_MS: optionalEnv(z.coerce.number().int().min(1).default(30000)),
+  CONNECTION_TIMEOUT_MS: optionalEnv(z.coerce.number().int().min(1).default(60000)),
 
   // --- Database (MySQL 8.0+) ---
   DATABASE_URL: z.string().min(1, 'DATABASE_URL is required'),
-  DATABASE_POOL_MIN: z.coerce.number().int().min(1).default(2),
-  DATABASE_POOL_MAX: z.coerce.number().int().min(1).max(1000).default(10),
+  DATABASE_POOL_MIN: optionalEnv(z.coerce.number().int().min(1).default(2)),
+  DATABASE_POOL_MAX: optionalEnv(z.coerce.number().int().min(1).max(1000).default(10)),
 
   // --- Redis ---
-  REDIS_URL: z.string().default('redis://localhost:6379'),
-  REDIS_MAX_RETRIES: z.coerce.number().int().min(0).default(3),
-  REDIS_CONNECT_TIMEOUT: z.coerce.number().int().min(1000).default(10000), // ms
+  REDIS_URL: optionalEnv(z.string().default('redis://localhost:6379')),
+  REDIS_MAX_RETRIES: optionalEnv(z.coerce.number().int().min(0).default(3)),
+  REDIS_CONNECT_TIMEOUT: optionalEnv(z.coerce.number().int().min(1000).default(10000)), // ms
 
   // --- Rate Limiting ---
-  RATE_LIMIT_ENABLED: z.string().default('true').transform((val) => val === 'true'),
-  RATE_LIMIT_MULTIPLIER: z.coerce.number().min(0.1).max(100).default(1),
-  RATE_LIMIT_AUTH_LOGIN_MAX: z.coerce.number().int().min(1).optional(),
-  RATE_LIMIT_AUTH_REGISTER_MAX: z.coerce.number().int().min(1).optional(),
+  RATE_LIMIT_ENABLED: optionalEnv(z.string().default('true').transform((val) => val === 'true')),
+  RATE_LIMIT_MULTIPLIER: optionalEnv(z.coerce.number().min(0.1).max(100).default(1)),
+  RATE_LIMIT_AUTH_LOGIN_MAX: optionalEnv(z.coerce.number().int().min(1).optional()),
+  RATE_LIMIT_AUTH_REGISTER_MAX: optionalEnv(z.coerce.number().int().min(1).optional()),
+
+  // --- IP Auto-Block (see src/libs/ip-block.ts) ---
+  // An IP that exceeds rate limits IP_AUTO_BLOCK_THRESHOLD times within
+  // IP_AUTO_BLOCK_WINDOW_SECONDS is blocked for IP_AUTO_BLOCK_DURATION_SECONDS.
+  // The threshold targets sustained abuse, not a single burst — a retry-looping
+  // but legitimate client (or a NAT'd office sharing one IP) must not self-ban.
+  IP_AUTO_BLOCK_THRESHOLD: optionalEnv(z.coerce.number().int().min(1).default(20)),
+  IP_AUTO_BLOCK_WINDOW_SECONDS: optionalEnv(z.coerce.number().int().min(1).default(300)),
+  IP_AUTO_BLOCK_DURATION_SECONDS: optionalEnv(z.coerce.number().int().min(1).default(3600)),
 
   // --- File Upload ---
-  MAX_FILE_SIZE_MB: z.coerce.number().min(1).max(100).default(10),
+  MAX_FILE_SIZE_MB: optionalEnv(z.coerce.number().min(1).max(100).default(10)),
 
   // --- JWT Authentication ---
-  JWT_SECRET: z.string().min(32, 'JWT_SECRET must be at least 32 characters'),
-  JWT_ACCESS_EXPIRY: z.string().default('15m'),
-  JWT_REFRESH_EXPIRY: z.string().default('7d'),
+  JWT_SECRET: z
+    .string()
+    .min(32, 'JWT_SECRET must be at least 32 characters')
+    // The committed .env.example placeholder is 43 chars and would pass min(32) —
+    // every scaffolded app would boot with the same publicly-known signing key.
+    .refine(
+      (s) => !s.startsWith('CHANGE_ME'),
+      'JWT_SECRET is still the placeholder — generate one: openssl rand -hex 48',
+    ),
+  JWT_ACCESS_EXPIRY: optionalEnv(z.string().default('15m')),
+  JWT_REFRESH_EXPIRY: optionalEnv(z.string().default('7d')),
 
   // --- Cookie ---
   // Separate secret for cookie signing (defaults to JWT_SECRET if not set)
-  COOKIE_SECRET: z.string().min(32, 'COOKIE_SECRET must be at least 32 characters').optional(),
+  COOKIE_SECRET: optionalEnv(
+    z
+      .string()
+      .min(32, 'COOKIE_SECRET must be at least 32 characters')
+      .refine(
+        (s) => !s.startsWith('CHANGE_ME'),
+        'COOKIE_SECRET is still the placeholder — generate one: openssl rand -hex 48',
+      )
+      .optional(),
+  ),
 
   // Cookie domain for cross-origin deployments (client ≠ server hostname)
   // Required when client and API are on different subdomains (e.g., app.example.com + api.example.com)
   // Set to the shared parent domain with a leading dot: ".example.com"
   // Leave empty for same-origin deployments or local development
-  COOKIE_DOMAIN: z.string().optional(),
+  COOKIE_DOMAIN: optionalEnv(z.string().optional()),
 
   // --- Account Activation ---
   // When true (default), new users are created as inactive and must verify
   // their account before they can log in. When false, users are active immediately.
-  REQUIRE_USER_VERIFICATION: z.string().default('true').transform((val) => val === 'true'),
+  REQUIRE_USER_VERIFICATION: optionalEnv(z.string().default('true').transform((val) => val === 'true')),
 
   // --- CORS ---
   // In development: CORS_ORIGIN is optional (allows all origins)
   // In production: REQUIRED for security
   // Supports comma-separated multiple origins: "https://a.com,https://b.com"
-  CORS_ORIGIN: z.string().optional(),
+  CORS_ORIGIN: optionalEnv(z.string().optional()),
 
   // --- Logging ---
-  LOG_LEVEL: z.enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace']).default('info'),
+  LOG_LEVEL: optionalEnv(z.enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace']).default('info')),
 
   // --- Email (Resend) ---
-  RESEND_API_KEY: z.string().min(1).optional(),
-  RESEND_FROM_EMAIL: z.string().email().default('onboarding@resend.dev'),
-  CLIENT_URL: z.string().url().default('http://localhost:3000'),
+  RESEND_API_KEY: optionalEnv(z.string().min(1).optional()),
+  RESEND_FROM_EMAIL: optionalEnv(z.string().email().default('onboarding@resend.dev')),
+  CLIENT_URL: optionalEnv(z.string().url().default('http://localhost:3000')),
 
   // --- Error Tracking (Optional) ---
-  SENTRY_DSN: z.string().url().optional(),
+  SENTRY_DSN: optionalEnv(z.string().url().optional()),
 });
 
 const parsed = envSchema.safeParse(process.env);
@@ -75,21 +122,18 @@ if (!parsed.success) {
     .map((issue) => `  - ${issue.path.join('.')}: ${issue.message}`)
     .join('\n');
 
-  // eslint-disable-next-line no-console
   console.error(`\nEnvironment validation failed:\n${formatted}\n`);
   process.exit(1);
 }
 
 // Validate CORS_ORIGIN in production
 if (parsed.data.NODE_ENV === 'production' && !parsed.data.CORS_ORIGIN) {
-  // eslint-disable-next-line no-console
   console.error('\nCORS_ORIGIN is required in production for security\n');
   process.exit(1);
 }
 
 // Validate RESEND_API_KEY when email verification is enabled
 if (parsed.data.REQUIRE_USER_VERIFICATION && !parsed.data.RESEND_API_KEY) {
-  // eslint-disable-next-line no-console
   console.error('\nRESEND_API_KEY is required when REQUIRE_USER_VERIFICATION is enabled.\nGet your API key from: https://resend.com/api-keys\n');
   process.exit(1);
 }

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

@@ -9,6 +9,22 @@
  * - RATE_LIMIT_MULTIPLIER: multiply all max values (default: 1, set 10 for dev)
  * - RATE_LIMIT_AUTH_LOGIN_MAX: override login max
  * - RATE_LIMIT_AUTH_REGISTER_MAX: override register max
+ *
+ * ── Self-ban interaction with IP auto-block (read before tightening limits) ──
+ * Every rate-limit exceedance records ONE violation against the client IP
+ * (app.ts `onExceeded` → recordRateLimitViolation). An IP that accumulates
+ * IP_AUTO_BLOCK_THRESHOLD violations (default 20) within
+ * IP_AUTO_BLOCK_WINDOW_SECONDS (default 300s) is auto-blocked for
+ * IP_AUTO_BLOCK_DURATION_SECONDS (default 1h) — for EVERY route.
+ *
+ * Rate limits are counted BEFORE validation, so a legitimate client stuck in a
+ * retry loop on a 400/422 response still burns quota; and NAT'd offices share
+ * one counter per IP. When tuning a route, keep
+ *   (realistic retries per window) × (windows per 5 min) well below the
+ * auto-block threshold, or a legit retry pattern self-bans for an hour.
+ * Example: AUTH_LOGIN at 10/15min can produce at most a handful of violations
+ * per 5-minute window — safely below 20. A hypothetical 5/10s limit could
+ * produce 30 violations in 5 minutes and trip the auto-block on its own.
  */
 
 import { env } from '@config/env.js';

package/template/server/src/libs/__tests__/http.test.ts

@@ -22,16 +22,26 @@ vi.mock('axios', () => ({
     create: vi.fn(() => ({
       interceptors: {
         request: {
-          use: vi.fn((onFulfilled: any, onRejected: any) => {
-            captured.requestFulfilled = onFulfilled;
-            captured.requestRejected = onRejected;
-          }),
+          use: vi.fn(
+            (
+              onFulfilled: (c: InternalAxiosRequestConfig) => InternalAxiosRequestConfig,
+              onRejected: (e: unknown) => never,
+            ) => {
+              captured.requestFulfilled = onFulfilled;
+              captured.requestRejected = onRejected;
+            },
+          ),
         },
         response: {
-          use: vi.fn((onFulfilled: any, onRejected: any) => {
-            captured.responseFulfilled = onFulfilled;
-            captured.responseRejected = onRejected;
-          }),
+          use: vi.fn(
+            (
+              onFulfilled: (r: AxiosResponse) => AxiosResponse,
+              onRejected: (e: unknown) => never,
+            ) => {
+              captured.responseFulfilled = onFulfilled;
+              captured.responseRejected = onRejected;
+            },
+          ),
         },
       },
     })),
@@ -404,7 +414,11 @@ describe('httpClient', () => {
 
     it('should not log request headers (may contain Authorization)', () => {
       captured.requestFulfilled!(
-        makeConfig({ method: 'get', url: '/me', headers: { Authorization: 'Bearer token123' } as any }),
+        makeConfig({
+          method: 'get',
+          url: '/me',
+          headers: { Authorization: 'Bearer token123' } as unknown as InternalAxiosRequestConfig['headers'],
+        }),
       );
       const logCall = vi.mocked(logger.debug).mock.calls[0][0] as Record<string, unknown>;
       expect(logCall).not.toHaveProperty('headers');

package/template/server/src/libs/__tests__/origin-check.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { isOriginAllowed } from '../origin-check.js';
+
+describe('isOriginAllowed', () => {
+  const allowed = new Set(['https://app.example.com', 'https://admin.example.com']);
+
+  it('should allow requests without an Origin header (curl, Postman, server-to-server)', () => {
+    expect(isOriginAllowed(undefined, 'api.example.com', allowed, false)).toBe(true);
+  });
+
+  it('should allow any origin when CORS allows all origins (development)', () => {
+    expect(isOriginAllowed('https://evil.example.org', 'api.example.com', allowed, true)).toBe(true);
+  });
+
+  it('should allow a configured CORS origin', () => {
+    expect(isOriginAllowed('https://app.example.com', 'api.example.com', allowed, false)).toBe(true);
+    expect(isOriginAllowed('https://admin.example.com', 'api.example.com', allowed, false)).toBe(true);
+  });
+
+  it('should allow same-origin requests (Origin host matches request Host)', () => {
+    expect(isOriginAllowed('https://api.example.com', 'api.example.com', allowed, false)).toBe(true);
+  });
+
+  it('should allow same-origin requests with a port in the host', () => {
+    expect(isOriginAllowed('http://localhost:8000', 'localhost:8000', new Set(), false)).toBe(true);
+  });
+
+  it('should allow same-origin requests with a mixed-case Host header', () => {
+    expect(isOriginAllowed('https://api.example.com', 'API.Example.COM', allowed, false)).toBe(true);
+  });
+
+  it('should reject a cross-site origin that is not configured', () => {
+    expect(isOriginAllowed('https://evil.example.org', 'api.example.com', allowed, false)).toBe(false);
+  });
+
+  it('should reject a subdomain lookalike of an allowed origin', () => {
+    expect(
+      isOriginAllowed('https://app.example.com.evil.org', 'api.example.com', allowed, false),
+    ).toBe(false);
+  });
+
+  it('should reject a malformed Origin header', () => {
+    expect(isOriginAllowed('not a url', 'api.example.com', allowed, false)).toBe(false);
+  });
+
+  it('should reject "null" origin (sandboxed iframe, data: URL)', () => {
+    expect(isOriginAllowed('null', 'api.example.com', allowed, false)).toBe(false);
+  });
+
+  it('should reject an unknown origin when the request host is unavailable', () => {
+    expect(isOriginAllowed('https://evil.example.org', undefined, allowed, false)).toBe(false);
+  });
+});

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

@@ -4,8 +4,14 @@ import { env } from '@config/env.js';
 import { prisma } from '@libs/prisma.js';
 import { UnauthorizedError, ForbiddenError, BadRequestError } from '@shared/errors/errors.js';
 import { clearAuthCookies } from '@libs/cookies.js';
+import { parseDurationMs } from '@libs/duration.js';
 import type { JwtPayload, UserRole } from '@shared/types/index.js';
 
+// Re-export so existing consumers of `parseDurationMs` from '@libs/auth.js'
+// keep working. The implementation lives in the import-free leaf module
+// duration.ts to avoid the cookies.ts ↔ auth.ts circular import (TDZ crash).
+export { parseDurationMs } from '@libs/duration.js';
+
 let app: FastifyInstance | null = null;
 
 export function initAuth(fastify: FastifyInstance): void {
@@ -30,22 +36,6 @@ export function generateRefreshToken(): string {
   return uuidv4();
 }
 
-export function parseDurationMs(duration: string, fallbackMs: number): number {
-  const match = duration.match(/^(\d+)([smhd])$/);
-  if (!match) return fallbackMs;
-
-  const value = parseInt(match[1], 10);
-  const unit = match[2];
-  const multipliers: Record<string, number> = {
-    s: 1000,
-    m: 60 * 1000,
-    h: 60 * 60 * 1000,
-    d: 24 * 60 * 60 * 1000,
-  };
-
-  return value * multipliers[unit];
-}
-
 export function getRefreshTokenExpiresAt(): Date {
   const ms = parseDurationMs(env.JWT_REFRESH_EXPIRY, 7 * 24 * 60 * 60 * 1000);
   return new Date(Date.now() + ms);

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

@@ -1,6 +1,6 @@
 import type { FastifyReply } from 'fastify';
 import { env } from '@config/env.js';
-import { parseDurationMs } from '@libs/auth.js';
+import { parseDurationMs } from '@libs/duration.js';
 
 const isProduction = env.NODE_ENV === 'production';