create-tigra 2.8.0 → 3.0.2

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

@@ -1,99 +1,150 @@
-import { z } from 'zod';
-import dotenv from 'dotenv';
-
-// Suppress dotenv's informational logs
-process.env.DOTENV_CONFIG_QUIET = 'true';
-dotenv.config();
-
-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'),
-
-  // --- 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),
-
-  // --- 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
-
-  // --- 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(),
-
-  // --- File Upload ---
-  MAX_FILE_SIZE_MB: 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'),
-
-  // --- 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 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(),
-
-  // --- 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'),
-
-  // --- 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(),
-
-  // --- Logging ---
-  LOG_LEVEL: 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'),
-
-  // --- Error Tracking (Optional) ---
-  SENTRY_DSN: z.string().url().optional(),
-});
-
-const parsed = envSchema.safeParse(process.env);
-
-if (!parsed.success) {
-  const formatted = parsed.error.issues
-    .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);
-}
-
-export const env = parsed.data;
-
-export type Env = z.infer<typeof envSchema>;
+import { z } from 'zod';
+import dotenv from 'dotenv';
+
+// Suppress dotenv's informational logs
+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: 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: 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: 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: optionalEnv(z.string().default('true').transform((val) => val === 'true')),
+  RATE_LIMIT_MULTIPLIER: optionalEnv(z.coerce.number().min(0.1).max(100).default(1)),
+
+  // When true, derive the client IP for rate-limiting / IP-blocking from the
+  // Cloudflare `CF-Connecting-IP` header instead of the socket/X-Forwarded-For
+  // IP (which is a Cloudflare edge IP behind the proxy — see src/libs/client-ip.ts).
+  // Default false: the header is client-spoofable, so enable this ONLY when the
+  // origin accepts traffic exclusively via Cloudflare.
+  TRUST_CLOUDFLARE: optionalEnv(z.string().default('false').transform((val) => val === 'true')),
+  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: 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')
+    // 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: 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: 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: 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: optionalEnv(z.string().optional()),
+
+  // --- Logging ---
+  LOG_LEVEL: optionalEnv(z.enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace']).default('info')),
+
+  // --- Email (Resend) ---
+  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: optionalEnv(z.string().url().optional()),
+});
+
+const parsed = envSchema.safeParse(process.env);
+
+if (!parsed.success) {
+  const formatted = parsed.error.issues
+    .map((issue) => `  - ${issue.path.join('.')}: ${issue.message}`)
+    .join('\n');
+
+  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) {
+  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) {
+  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);
+}
+
+export const env = parsed.data;
+
+export type Env = z.infer<typeof envSchema>;

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__/auth-path.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { isAuthPath } from '../auth-path.js';
+
+describe('isAuthPath', () => {
+  it('returns true for an auth route', () => {
+    expect(isAuthPath({ url: '/api/v1/auth/login' })).toBe(true);
+  });
+
+  it('returns true when the auth route has a query string', () => {
+    expect(isAuthPath({ url: '/api/v1/auth/login?next=/dashboard' })).toBe(true);
+  });
+
+  it('returns false for a non-auth route (it still feeds the auto-ban)', () => {
+    expect(isAuthPath({ url: '/api/v1/widget/chat' })).toBe(false);
+  });
+
+  it('returns false for the bare /api/v1/auth prefix without a sub-path', () => {
+    expect(isAuthPath({ url: '/api/v1/auth' })).toBe(false);
+  });
+
+  it('returns false for a non-auth path that only starts with "auth"', () => {
+    expect(isAuthPath({ url: '/api/v1/auth-internal/health' })).toBe(false);
+  });
+});

package/template/server/src/libs/__tests__/client-ip.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { FastifyRequest } from 'fastify';
+
+// Mock the env module so each test can flip TRUST_CLOUDFLARE without relying on
+// process.env load order (src/config/env.ts validates + exits on import).
+const mockEnv = vi.hoisted(() => ({ TRUST_CLOUDFLARE: false }));
+vi.mock('@config/env.js', () => ({ env: mockEnv }));
+
+import { getClientIp } from '../client-ip.js';
+
+// Minimal FastifyRequest stub — getClientIp only reads `.ip` and `.headers`.
+function makeRequest(ip: string, headers: Record<string, unknown> = {}): FastifyRequest {
+  return { ip, headers } as unknown as FastifyRequest;
+}
+
+describe('getClientIp', () => {
+  beforeEach(() => {
+    mockEnv.TRUST_CLOUDFLARE = false;
+  });
+
+  describe('when TRUST_CLOUDFLARE is false (default)', () => {
+    it('returns request.ip and ignores the CF-Connecting-IP header', () => {
+      const request = makeRequest('10.0.0.1', { 'cf-connecting-ip': '203.0.113.7' });
+      expect(getClientIp(request)).toBe('10.0.0.1');
+    });
+
+    it('returns request.ip when no CF header is present', () => {
+      expect(getClientIp(makeRequest('10.0.0.1'))).toBe('10.0.0.1');
+    });
+  });
+
+  describe('when TRUST_CLOUDFLARE is true', () => {
+    beforeEach(() => {
+      mockEnv.TRUST_CLOUDFLARE = true;
+    });
+
+    it('returns the CF-Connecting-IP header value', () => {
+      const request = makeRequest('10.0.0.1', { 'cf-connecting-ip': '203.0.113.7' });
+      expect(getClientIp(request)).toBe('203.0.113.7');
+    });
+
+    it('falls back to request.ip when the CF header is absent', () => {
+      expect(getClientIp(makeRequest('10.0.0.1'))).toBe('10.0.0.1');
+    });
+
+    it('falls back to request.ip when the CF header is an empty string', () => {
+      const request = makeRequest('10.0.0.1', { 'cf-connecting-ip': '' });
+      expect(getClientIp(request)).toBe('10.0.0.1');
+    });
+
+    it('falls back to request.ip when the CF header is an array (duplicated header)', () => {
+      const request = makeRequest('10.0.0.1', { 'cf-connecting-ip': ['203.0.113.7', '198.51.100.2'] });
+      expect(getClientIp(request)).toBe('10.0.0.1');
+    });
+
+    it('falls through an array CF header to a valid X-Forwarded-For entry', () => {
+      // CF header is an array (untrusted shape) so it falls through; XFF is then used.
+      const request = makeRequest('10.0.0.1', {
+        'cf-connecting-ip': ['203.0.113.7', '198.51.100.2'],
+        'x-forwarded-for': '198.51.100.9',
+      });
+      expect(getClientIp(request)).toBe('198.51.100.9');
+    });
+
+    it('prefers a valid CF header over X-Forwarded-For', () => {
+      const request = makeRequest('10.0.0.1', {
+        'cf-connecting-ip': '203.0.113.7',
+        'x-forwarded-for': '198.51.100.9',
+      });
+      expect(getClientIp(request)).toBe('203.0.113.7');
+    });
+
+    it('falls through to X-Forwarded-For when the CF header is an invalid IP', () => {
+      const request = makeRequest('10.0.0.1', {
+        'cf-connecting-ip': 'not-an-ip',
+        'x-forwarded-for': '198.51.100.9',
+      });
+      expect(getClientIp(request)).toBe('198.51.100.9');
+    });
+  });
+
+  describe('X-Forwarded-For resolution (independent of the flag)', () => {
+    it('uses the left-most XFF entry when the CF flag is on but the CF header is absent', () => {
+      mockEnv.TRUST_CLOUDFLARE = true;
+      const request = makeRequest('10.0.0.1', { 'x-forwarded-for': '203.0.113.7' });
+      expect(getClientIp(request)).toBe('203.0.113.7');
+    });
+
+    it('uses the left-most XFF entry even when the CF flag is off (grey-cloud / DNS-only)', () => {
+      const request = makeRequest('10.0.0.1', { 'x-forwarded-for': '203.0.113.7' });
+      expect(getClientIp(request)).toBe('203.0.113.7');
+    });
+
+    it('returns the left-most entry of a multi-hop XFF chain', () => {
+      const request = makeRequest('10.0.0.1', {
+        'x-forwarded-for': '203.0.113.7, 70.41.3.18, 150.172.238.178',
+      });
+      expect(getClientIp(request)).toBe('203.0.113.7');
+    });
+
+    it('trims surrounding whitespace from the XFF entry', () => {
+      const request = makeRequest('10.0.0.1', { 'x-forwarded-for': '  203.0.113.7  , 70.41.3.18' });
+      expect(getClientIp(request)).toBe('203.0.113.7');
+    });
+
+    it('falls back to request.ip when the XFF entry is not a valid IP', () => {
+      const request = makeRequest('10.0.0.1', { 'x-forwarded-for': 'garbage, 70.41.3.18' });
+      expect(getClientIp(request)).toBe('10.0.0.1');
+    });
+
+    it('falls back to request.ip when the XFF header is an empty string', () => {
+      const request = makeRequest('10.0.0.1', { 'x-forwarded-for': '' });
+      expect(getClientIp(request)).toBe('10.0.0.1');
+    });
+
+    it('uses the first element when XFF is an array (duplicated header)', () => {
+      const request = makeRequest('10.0.0.1', { 'x-forwarded-for': ['203.0.113.7', '70.41.3.18'] });
+      expect(getClientIp(request)).toBe('203.0.113.7');
+    });
+  });
+});

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__/ip-block.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { getRedis } from '@libs/redis.js';
+import { recordRateLimitViolation } from '../ip-block.js';
+
+// Self-contained env so ip-block.ts can read its threshold constants at import
+// time without loading/validating the real environment.
+vi.mock('@config/env.js', () => ({
+  env: {
+    IP_AUTO_BLOCK_THRESHOLD: 20,
+    IP_AUTO_BLOCK_WINDOW_SECONDS: 300,
+    IP_AUTO_BLOCK_DURATION_SECONDS: 3600,
+  },
+}));
+
+vi.mock('@libs/prisma.js', () => ({
+  prisma: {
+    blockedIp: {
+      findMany: vi.fn(),
+      findUnique: vi.fn(),
+      create: vi.fn(),
+      deleteMany: vi.fn(),
+    },
+  },
+}));
+
+vi.mock('@libs/redis.js');
+vi.mock('@libs/logger.js', () => ({
+  logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn(), debug: vi.fn() },
+}));
+
+const redisMock = {
+  del: vi.fn(),
+  zadd: vi.fn(),
+  incr: vi.fn(),
+  expire: vi.fn(),
+};
+
+describe('recordRateLimitViolation — infra-IP guard', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(getRedis).mockReturnValue(redisMock as never);
+  });
+
+  it('never auto-blocks a private/reserved IP (skips Redis accounting entirely)', async () => {
+    // A shared Traefik/Docker internal IP must never be auto-banned — that would
+    // lock out every real user behind it.
+    await recordRateLimitViolation('10.0.0.5');
+    expect(redisMock.incr).not.toHaveBeenCalled();
+    expect(redisMock.zadd).not.toHaveBeenCalled();
+  });
+
+  it('skips loopback addresses', async () => {
+    await recordRateLimitViolation('127.0.0.1');
+    expect(redisMock.incr).not.toHaveBeenCalled();
+  });
+
+  it('records a violation for a public client IP', async () => {
+    redisMock.incr.mockResolvedValue(1);
+    await recordRateLimitViolation('93.184.216.34');
+    expect(redisMock.incr).toHaveBeenCalledTimes(1);
+  });
+});

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);
+  });
+});