create-tigra 3.0.0 → 3.0.2

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

@@ -1,143 +1,150 @@
-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)),
-  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>;
+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/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__/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__/url-safety.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+import { redactUrl, isPrivateOrReservedIp } from '../url-safety.js';
+
+describe('redactUrl', () => {
+  it('redacts a Telegram bot token in the API path', () => {
+    expect(redactUrl('https://api.telegram.org/bot123456:AAHsecret/getFile')).toBe(
+      'https://api.telegram.org/bot<redacted>/getFile',
+    );
+  });
+
+  it('redacts a Telegram bot token in the file-download path', () => {
+    expect(redactUrl('https://api.telegram.org/file/bot123456:AAHsecret/photos/file_1.jpg')).toBe(
+      'https://api.telegram.org/file/bot<redacted>/photos/file_1.jpg',
+    );
+  });
+
+  it('strips the query string (may carry signed media tokens)', () => {
+    expect(redactUrl('https://lookaside.fbsbx.com/media?asset_id=1&token=SECRET')).toBe(
+      'https://lookaside.fbsbx.com/media',
+    );
+  });
+
+  it('strips a fragment as well', () => {
+    expect(redactUrl('https://cdn.example.com/x.jpg#frag')).toBe('https://cdn.example.com/x.jpg');
+  });
+
+  it('leaves a normal URL unchanged', () => {
+    expect(redactUrl('https://scontent.xx.fbcdn.net/v/photo.jpg')).toBe(
+      'https://scontent.xx.fbcdn.net/v/photo.jpg',
+    );
+  });
+
+  it('returns empty / non-string input as-is without throwing', () => {
+    expect(redactUrl('')).toBe('');
+  });
+});
+
+describe('isPrivateOrReservedIp', () => {
+  it.each([
+    '0.0.0.0',
+    '127.0.0.1',
+    '10.0.0.5',
+    '172.16.0.1',
+    '172.31.255.254',
+    '192.168.1.1',
+    '169.254.169.254',
+    '100.64.0.1',
+    '100.127.255.255',
+    '::1',
+    '::',
+    'fc00::1',
+    'fd12:3456:789a::1',
+    'fe80::abcd',
+    '::ffff:10.0.0.5',
+    '::ffff:127.0.0.1',
+  ])('blocks internal/reserved address %s', (addr) => {
+    expect(isPrivateOrReservedIp(addr)).toBe(true);
+  });
+
+  it.each([
+    '93.184.216.34',
+    '8.8.8.8',
+    '1.1.1.1',
+    '172.32.0.1', // just outside 172.16/12
+    '172.15.0.1', // just below 172.16/12
+    '192.169.0.1', // not 192.168
+    '100.63.255.255', // just below CGNAT
+    '100.128.0.0', // just above CGNAT
+    '2606:4700:4700::1111', // Cloudflare public IPv6
+    '::ffff:93.184.216.34', // IPv4-mapped public
+  ])('allows public address %s', (addr) => {
+    expect(isPrivateOrReservedIp(addr)).toBe(false);
+  });
+
+  it('fails closed (blocks) on malformed input', () => {
+    expect(isPrivateOrReservedIp('not-an-ip')).toBe(true);
+    expect(isPrivateOrReservedIp('999.999.999.999')).toBe(true);
+    expect(isPrivateOrReservedIp('')).toBe(true);
+  });
+});

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

@@ -0,0 +1,14 @@
+import type { FastifyRequest } from 'fastify';
+
+/**
+ * Auth routes (login / register / refresh / ...) have their own per-route rate
+ * limit and an account-lockout ladder. Their 429s must NOT feed the
+ * cross-endpoint 1-hour IP auto-ban, or a user mistyping a password would lock
+ * themselves out of the entire API (widget included).
+ *
+ * Exported for unit testing (auth-path.test.ts).
+ */
+export function isAuthPath(request: Pick<FastifyRequest, 'url'>): boolean {
+  const pathname = request.url.split('?')[0];
+  return pathname.startsWith('/api/v1/auth/');
+}