create-tigra 2.8.0 → 3.0.2

package/template/server/src/libs/ip-block.ts

@@ -1,206 +1,220 @@
-/**
- * IP Blocking Service
- *
- * Two-tier IP blocking:
- * - Permanent blocks: DB (source of truth) + Redis SET (hot cache). Admin-managed via API.
- * - Auto-blocks: Redis ZSET with expiry timestamps (triggered by excessive rate-limit violations)
- *
- * Design decisions:
- * - DB is the source of truth for permanent blocks — survives Redis restarts
- * - Redis is the hot cache — all runtime checks hit Redis only (O(1))
- * - On server boot, syncBlockedIpsToRedis() loads all permanent blocks from DB into Redis
- * - Fails open: if Redis is down, requests are NOT blocked (availability > security for rate limiting)
- * - Lazy cleanup: expired auto-blocks are removed on check, no separate cleanup job needed
- */
-
-import { prisma } from '@libs/prisma.js';
-import { getRedis } from '@libs/redis.js';
-import { logger } from '@libs/logger.js';
-import { ConflictError } from '@shared/errors/errors.js';
-
-// Redis keys
-const BLOCKED_IPS_KEY = 'blocked_ips';
-const AUTO_BLOCKED_KEY = 'auto_blocked_ips';
-const VIOLATION_PREFIX = 'rl_violations:';
-
-// Auto-block thresholds
-const AUTO_BLOCK_THRESHOLD = 10;         // violations before auto-block
-const AUTO_BLOCK_WINDOW_SECONDS = 300;   // 5-minute sliding window
-const AUTO_BLOCK_DURATION_SECONDS = 3600; // block for 1 hour
-
-/**
- * Sync all permanent blocked IPs from DB to Redis.
- * Called once during server startup.
- */
-export async function syncBlockedIpsToRedis(): Promise<void> {
-  try {
-    const blockedIps = await prisma.blockedIp.findMany({ select: { ip: true } });
-
-    const redis = getRedis();
-
-    // Clear stale Redis state and repopulate from DB
-    await redis.del(BLOCKED_IPS_KEY);
-
-    if (blockedIps.length > 0) {
-      await redis.sadd(BLOCKED_IPS_KEY, ...blockedIps.map((b) => b.ip));
-    }
-
-    logger.info(`[IP-BLOCK] Synced ${blockedIps.length} blocked IPs from DB to Redis`);
-  } catch (error) {
-    logger.warn('[IP-BLOCK] Failed to sync blocked IPs from DB to Redis — permanent blocks may not be enforced until next restart');
-    logger.debug(error);
-  }
-}
-
-/**
- * Check if an IP is blocked (permanent or auto-blocked).
- *
- * @param ip - IP address to check
- * @returns true if blocked, false otherwise (including Redis failures)
- */
-export async function isIpBlocked(ip: string): Promise<boolean> {
-  try {
-    const redis = getRedis();
-
-    // Check permanent block list
-    const permanent = await redis.sismember(BLOCKED_IPS_KEY, ip);
-    if (permanent === 1) return true;
-
-    // Check auto-block list (score = expiry Unix timestamp)
-    const score = await redis.zscore(AUTO_BLOCKED_KEY, ip);
-    if (score) {
-      const expiresAt = Number(score);
-      if (expiresAt > Date.now() / 1000) return true;
-
-      // Expired — clean up lazily
-      await redis.zrem(AUTO_BLOCKED_KEY, ip);
-    }
-
-    return false;
-  } catch {
-    // Fail open: if Redis is down, don't block
-    logger.warn('[IP-BLOCK] Redis unavailable, skipping IP block check');
-    return false;
-  }
-}
-
-/**
- * Block an IP permanently. Writes to DB (source of truth) + Redis (hot cache).
- *
- * @param ip - IP address to block
- * @param blockedBy - Admin user ID who initiated the block
- * @param reason - Optional reason for the block
- */
-export async function blockIp(
-  ip: string,
-  blockedBy: string,
-  reason?: string,
-): Promise<{ id: string; ip: string; reason: string | null; blockedBy: string; createdAt: Date }> {
-  // Write to DB (source of truth)
-  const existing = await prisma.blockedIp.findUnique({ where: { ip } });
-  if (existing) {
-    throw new ConflictError('IP is already blocked', 'IP_ALREADY_BLOCKED');
-  }
-
-  const blocked = await prisma.blockedIp.create({
-    data: { ip, blockedBy, reason: reason ?? null },
-  });
-
-  // Sync to Redis cache
-  try {
-    const redis = getRedis();
-    await redis.sadd(BLOCKED_IPS_KEY, ip);
-  } catch {
-    logger.warn({ ip }, '[IP-BLOCK] Failed to sync block to Redis — will be synced on next restart');
-  }
-
-  logger.info({ ip, blockedBy, reason }, '[IP-BLOCK] IP permanently blocked');
-  return blocked;
-}
-
-/**
- * Unblock an IP. Removes from DB + Redis + auto-block list.
- *
- * @param ip - IP address to unblock
- */
-export async function unblockIp(ip: string): Promise<void> {
-  // Remove from DB
-  await prisma.blockedIp.deleteMany({ where: { ip } });
-
-  // Remove from Redis (both permanent and auto-block)
-  try {
-    const redis = getRedis();
-    await redis.srem(BLOCKED_IPS_KEY, ip);
-    await redis.zrem(AUTO_BLOCKED_KEY, ip);
-  } catch {
-    logger.warn({ ip }, '[IP-BLOCK] Failed to sync unblock to Redis — will be synced on next restart');
-  }
-
-  logger.info({ ip }, '[IP-BLOCK] IP unblocked');
-}
-
-/**
- * List all currently blocked IPs (permanent from DB + active auto-blocks from Redis).
- */
-export async function getBlockedIps(): Promise<{
-  permanent: { id: string; ip: string; reason: string | null; blockedBy: string; createdAt: Date }[];
-  autoBlocked: string[];
-}> {
-  // Permanent blocks from DB (source of truth)
-  const permanent = await prisma.blockedIp.findMany({
-    select: { id: true, ip: true, reason: true, blockedBy: true, createdAt: true },
-    orderBy: { createdAt: 'desc' },
-  });
-
-  // Auto-blocks from Redis
-  let autoBlocked: string[] = [];
-  try {
-    const redis = getRedis();
-    const nowSeconds = Date.now() / 1000;
-    autoBlocked = await redis.zrangebyscore(AUTO_BLOCKED_KEY, nowSeconds, '+inf');
-  } catch {
-    logger.warn('[IP-BLOCK] Redis unavailable, cannot retrieve auto-blocked IPs');
-  }
-
-  return { permanent, autoBlocked };
-}
-
-/**
- * Record a rate-limit violation for an IP.
- *
- * If the IP exceeds AUTO_BLOCK_THRESHOLD violations within
- * AUTO_BLOCK_WINDOW_SECONDS, it gets auto-blocked for
- * AUTO_BLOCK_DURATION_SECONDS.
- *
- * Called from the rate-limit `onExceeded` callback.
- *
- * @param ip - IP address that violated rate limit
- */
-export async function recordRateLimitViolation(ip: string): Promise<void> {
-  try {
-    const redis = getRedis();
-    const key = `${VIOLATION_PREFIX}${ip}`;
-
-    const count = await redis.incr(key);
-
-    // Set TTL on first violation (sliding window)
-    if (count === 1) {
-      await redis.expire(key, AUTO_BLOCK_WINDOW_SECONDS);
-    }
-
-    if (count >= AUTO_BLOCK_THRESHOLD) {
-      // Auto-block: add to ZSET with expiry timestamp as score
-      const expiresAt = Math.floor(Date.now() / 1000) + AUTO_BLOCK_DURATION_SECONDS;
-      await redis.zadd(AUTO_BLOCKED_KEY, expiresAt, ip);
-      await redis.del(key); // Reset violation counter
-
-      logger.warn(
-        { ip, violations: count, blockedForSeconds: AUTO_BLOCK_DURATION_SECONDS },
-        '[IP-BLOCK] Auto-blocked IP due to excessive rate-limit violations',
-      );
-    }
-  } catch {
-    // Non-critical: don't break the request if violation tracking fails
-    logger.warn('[IP-BLOCK] Failed to record rate-limit violation');
-  }
-}
+/**
+ * IP Blocking Service
+ *
+ * Two-tier IP blocking:
+ * - Permanent blocks: DB (source of truth) + Redis SET (hot cache). Admin-managed via API.
+ * - Auto-blocks: Redis ZSET with expiry timestamps (triggered by excessive rate-limit violations)
+ *
+ * Design decisions:
+ * - DB is the source of truth for permanent blocks — survives Redis restarts
+ * - Redis is the hot cache — all runtime checks hit Redis only (O(1))
+ * - On server boot, syncBlockedIpsToRedis() loads all permanent blocks from DB into Redis
+ * - Fails open: if Redis is down, requests are NOT blocked (availability > security for rate limiting)
+ * - Lazy cleanup: expired auto-blocks are removed on check, no separate cleanup job needed
+ */
+
+import { env } from '@config/env.js';
+import { prisma } from '@libs/prisma.js';
+import { getRedis } from '@libs/redis.js';
+import { logger } from '@libs/logger.js';
+import { ConflictError } from '@shared/errors/errors.js';
+import { isPrivateOrReservedIp } from '@libs/url-safety.js';
+
+// Redis keys
+const BLOCKED_IPS_KEY = 'blocked_ips';
+const AUTO_BLOCKED_KEY = 'auto_blocked_ips';
+const VIOLATION_PREFIX = 'rl_violations:';
+
+// Auto-block thresholds — env-configurable (see .env.example).
+// The threshold default is deliberately high (20): auto-block must catch
+// SUSTAINED abuse, not a single burst. Rate-limit counting happens before
+// validation, so a retry-looping but legitimate client (or a NAT'd office
+// sharing one egress IP) can rack up violations quickly — see the self-ban
+// interaction note in src/config/rate-limit.config.ts before lowering it.
+const AUTO_BLOCK_THRESHOLD = env.IP_AUTO_BLOCK_THRESHOLD;                 // violations before auto-block (default 20)
+const AUTO_BLOCK_WINDOW_SECONDS = env.IP_AUTO_BLOCK_WINDOW_SECONDS;       // sliding window (default 300 = 5 min)
+const AUTO_BLOCK_DURATION_SECONDS = env.IP_AUTO_BLOCK_DURATION_SECONDS;   // block duration (default 3600 = 1 hour)
+
+/**
+ * Sync all permanent blocked IPs from DB to Redis.
+ * Called once during server startup.
+ */
+export async function syncBlockedIpsToRedis(): Promise<void> {
+  try {
+    const blockedIps = await prisma.blockedIp.findMany({ select: { ip: true } });
+
+    const redis = getRedis();
+
+    // Clear stale Redis state and repopulate from DB
+    await redis.del(BLOCKED_IPS_KEY);
+
+    if (blockedIps.length > 0) {
+      await redis.sadd(BLOCKED_IPS_KEY, ...blockedIps.map((b) => b.ip));
+    }
+
+    logger.info(`[IP-BLOCK] Synced ${blockedIps.length} blocked IPs from DB to Redis`);
+  } catch (error) {
+    logger.warn('[IP-BLOCK] Failed to sync blocked IPs from DB to Redis — permanent blocks may not be enforced until next restart');
+    logger.debug(error);
+  }
+}
+
+/**
+ * Check if an IP is blocked (permanent or auto-blocked).
+ *
+ * @param ip - IP address to check
+ * @returns true if blocked, false otherwise (including Redis failures)
+ */
+export async function isIpBlocked(ip: string): Promise<boolean> {
+  try {
+    const redis = getRedis();
+
+    // Check permanent block list
+    const permanent = await redis.sismember(BLOCKED_IPS_KEY, ip);
+    if (permanent === 1) return true;
+
+    // Check auto-block list (score = expiry Unix timestamp)
+    const score = await redis.zscore(AUTO_BLOCKED_KEY, ip);
+    if (score) {
+      const expiresAt = Number(score);
+      if (expiresAt > Date.now() / 1000) return true;
+
+      // Expired — clean up lazily
+      await redis.zrem(AUTO_BLOCKED_KEY, ip);
+    }
+
+    return false;
+  } catch {
+    // Fail open: if Redis is down, don't block
+    logger.warn('[IP-BLOCK] Redis unavailable, skipping IP block check');
+    return false;
+  }
+}
+
+/**
+ * Block an IP permanently. Writes to DB (source of truth) + Redis (hot cache).
+ *
+ * @param ip - IP address to block
+ * @param blockedBy - Admin user ID who initiated the block
+ * @param reason - Optional reason for the block
+ */
+export async function blockIp(
+  ip: string,
+  blockedBy: string,
+  reason?: string,
+): Promise<{ id: string; ip: string; reason: string | null; blockedBy: string; createdAt: Date }> {
+  // Write to DB (source of truth)
+  const existing = await prisma.blockedIp.findUnique({ where: { ip } });
+  if (existing) {
+    throw new ConflictError('IP is already blocked', 'IP_ALREADY_BLOCKED');
+  }
+
+  const blocked = await prisma.blockedIp.create({
+    data: { ip, blockedBy, reason: reason ?? null },
+  });
+
+  // Sync to Redis cache
+  try {
+    const redis = getRedis();
+    await redis.sadd(BLOCKED_IPS_KEY, ip);
+  } catch {
+    logger.warn({ ip }, '[IP-BLOCK] Failed to sync block to Redis — will be synced on next restart');
+  }
+
+  logger.info({ ip, blockedBy, reason }, '[IP-BLOCK] IP permanently blocked');
+  return blocked;
+}
+
+/**
+ * Unblock an IP. Removes from DB + Redis + auto-block list.
+ *
+ * @param ip - IP address to unblock
+ */
+export async function unblockIp(ip: string): Promise<void> {
+  // Remove from DB
+  await prisma.blockedIp.deleteMany({ where: { ip } });
+
+  // Remove from Redis (both permanent and auto-block)
+  try {
+    const redis = getRedis();
+    await redis.srem(BLOCKED_IPS_KEY, ip);
+    await redis.zrem(AUTO_BLOCKED_KEY, ip);
+  } catch {
+    logger.warn({ ip }, '[IP-BLOCK] Failed to sync unblock to Redis — will be synced on next restart');
+  }
+
+  logger.info({ ip }, '[IP-BLOCK] IP unblocked');
+}
+
+/**
+ * List all currently blocked IPs (permanent from DB + active auto-blocks from Redis).
+ */
+export async function getBlockedIps(): Promise<{
+  permanent: { id: string; ip: string; reason: string | null; blockedBy: string; createdAt: Date }[];
+  autoBlocked: string[];
+}> {
+  // Permanent blocks from DB (source of truth)
+  const permanent = await prisma.blockedIp.findMany({
+    select: { id: true, ip: true, reason: true, blockedBy: true, createdAt: true },
+    orderBy: { createdAt: 'desc' },
+  });
+
+  // Auto-blocks from Redis
+  let autoBlocked: string[] = [];
+  try {
+    const redis = getRedis();
+    const nowSeconds = Date.now() / 1000;
+    autoBlocked = await redis.zrangebyscore(AUTO_BLOCKED_KEY, nowSeconds, '+inf');
+  } catch {
+    logger.warn('[IP-BLOCK] Redis unavailable, cannot retrieve auto-blocked IPs');
+  }
+
+  return { permanent, autoBlocked };
+}
+
+/**
+ * Record a rate-limit violation for an IP.
+ *
+ * If the IP exceeds AUTO_BLOCK_THRESHOLD violations within
+ * AUTO_BLOCK_WINDOW_SECONDS, it gets auto-blocked for
+ * AUTO_BLOCK_DURATION_SECONDS.
+ *
+ * Called from the rate-limit `onExceeded` callback.
+ *
+ * @param ip - IP address that violated rate limit
+ */
+export async function recordRateLimitViolation(ip: string): Promise<void> {
+  // Never auto-block infrastructure addresses (loopback / private / link-local /
+  // Traefik-Docker internal). A shared proxy IP getting auto-blocked would lock
+  // out every real user behind it. Public client IPs proceed as normal.
+  if (isPrivateOrReservedIp(ip)) {
+    return;
+  }
+
+  try {
+    const redis = getRedis();
+    const key = `${VIOLATION_PREFIX}${ip}`;
+
+    const count = await redis.incr(key);
+
+    // Set TTL on first violation (sliding window)
+    if (count === 1) {
+      await redis.expire(key, AUTO_BLOCK_WINDOW_SECONDS);
+    }
+
+    if (count >= AUTO_BLOCK_THRESHOLD) {
+      // Auto-block: add to ZSET with expiry timestamp as score
+      const expiresAt = Math.floor(Date.now() / 1000) + AUTO_BLOCK_DURATION_SECONDS;
+      await redis.zadd(AUTO_BLOCKED_KEY, expiresAt, ip);
+      await redis.del(key); // Reset violation counter
+
+      logger.warn(
+        { ip, violations: count, blockedForSeconds: AUTO_BLOCK_DURATION_SECONDS },
+        '[IP-BLOCK] Auto-blocked IP due to excessive rate-limit violations',
+      );
+    }
+  } catch {
+    // Non-critical: don't break the request if violation tracking fails
+    logger.warn('[IP-BLOCK] Failed to record rate-limit violation');
+  }
+}

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

@@ -0,0 +1,38 @@
+/**
+ * CSRF defense-in-depth — Origin verification for state-changing requests.
+ *
+ * With cross-origin cookie deployments (sameSite=none), browsers attach auth
+ * cookies to cross-site requests. CORS only protects *reading* responses — it
+ * does not stop the side effects of a forged POST/PUT/PATCH/DELETE. This check
+ * rejects browser-originated state-changing requests whose Origin header is
+ * neither the API itself (same-origin) nor a configured CORS origin.
+ *
+ * Deliberately conservative:
+ * - No Origin header → ALLOWED. Non-browser clients (curl, Postman,
+ *   server-to-server) omit it, and they carry no ambient cookies, so they are
+ *   not CSRF vectors. Browsers always send Origin on cross-site state-changing
+ *   requests, which is the only case this defends against.
+ * - allowAllOrigins (development CORS) → ALLOWED.
+ */
+export function isOriginAllowed(
+  origin: string | undefined,
+  requestHost: string | undefined,
+  allowedOrigins: ReadonlySet<string>,
+  allowAllOrigins: boolean,
+): boolean {
+  if (!origin) return true; // non-browser client — not a CSRF vector
+  if (allowAllOrigins) return true; // development: CORS allows all origins
+  if (allowedOrigins.has(origin)) return true; // configured cross-origin client
+
+  // Same-origin request: the Origin's host matches the request's Host header.
+  // Compared scheme-insensitively — TLS usually terminates at the reverse
+  // proxy, so the API may see the request as http while Origin says https.
+  // The Host header is lowercased before comparing: `new URL()` normalizes the
+  // Origin's host to lowercase, but the raw Host header arrives as-sent and
+  // host names are case-insensitive (RFC 9110).
+  try {
+    return requestHost !== undefined && new URL(origin).host === requestHost.toLowerCase();
+  } catch {
+    return false; // malformed Origin header — reject
+  }
+}

package/template/server/src/libs/query-counter.ts

@@ -0,0 +1,59 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { FastifyInstance } from 'fastify';
+import { prisma } from './prisma.js';
+import { env } from '@config/env.js';
+
+/**
+ * Dev-only per-request Prisma query counter → the `X-Query-Count` response header.
+ *
+ * Rides the query events prisma.ts already emits (`{ emit: 'event', level: 'query' }`): an
+ * AsyncLocalStorage store is entered per request, every emitted query increments it, and the
+ * total ships back as `X-Query-Count`. This lets a black-box perf/load tester (the fleet's
+ * perf-tester) see N+1 at the source over plain HTTP — no DB access, no profiler needed.
+ *
+ * Note on Prisma N+1: the engine's DataLoader auto-batches relation `include`s and same-tick
+ * calls, so the queries this counts are the ones that actually matter — sequential awaited
+ * queries in a loop (`for (...) await prisma.x.find()`), the real application-level N+1.
+ *
+ * NEVER active in production: no listener, no header, zero overhead — purely a dev aid.
+ */
+interface QueryCountStore {
+  count: number;
+}
+
+const als = new AsyncLocalStorage<QueryCountStore>();
+
+let listenerAttached = false;
+function attachQueryListener(): void {
+  if (listenerAttached) return;
+  listenerAttached = true;
+  // Queries outside a counted request (startup, jobs) simply find no store and are ignored.
+  prisma.$on('query' as never, () => {
+    const store = als.getStore();
+    if (store) store.count += 1;
+  });
+}
+
+/**
+ * Wire the dev-only `X-Query-Count` header onto every route. Call once with the root app
+ * instance (top-level, so the hooks are global). No-op in production.
+ */
+export function registerQueryCounter(app: FastifyInstance): void {
+  if (env.NODE_ENV === 'production') return;
+  attachQueryListener();
+
+  // Wrap the whole request lifecycle in a fresh store via the callback-style hook: passing
+  // Fastify's `done` continuation into als.run() means every subsequent hook, the handler, and
+  // the Prisma calls they make run inside this request's store (the @fastify/request-context
+  // pattern — more robust than enterWith, which can be lost across the hook boundary).
+  app.addHook('onRequest', (_request, _reply, done) => {
+    als.run({ count: 0 }, done);
+  });
+
+  // onSend can still mutate headers (runs before the body is flushed).
+  app.addHook('onSend', async (_request, reply, payload) => {
+    const store = als.getStore();
+    if (store) reply.header('X-Query-Count', String(store.count));
+    return payload;
+  });
+}

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

@@ -10,7 +10,7 @@ export function getRedis(): Redis {
       maxRetriesPerRequest: env.REDIS_MAX_RETRIES,
       connectTimeout: env.REDIS_CONNECT_TIMEOUT,
       lazyConnect: true,
-      retryStrategy: (times: number) => {
+      retryStrategy: (times: number): number | null => {
         // Exponential backoff with max delay of 3 seconds
         if (times > env.REDIS_MAX_RETRIES) {
           // Stop retrying after max retries