create-tigra 3.0.0 → 3.0.2

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

@@ -0,0 +1,77 @@
+/**
+ * Client IP resolution — Cloudflare- and reverse-proxy-aware.
+ *
+ * Behind a Cloudflare proxy (or any reverse proxy such as Traefik/Coolify),
+ * Fastify's `request.ip` (derived from the socket / X-Forwarded-For) resolves
+ * to an *edge* IP, not the real visitor. Every request through one edge node
+ * then shares a single IP, which collapses the per-IP rate limiter and the IP
+ * auto-block onto that shared edge address: one abusive client can rate-limit
+ * or self-ban every legitimate user behind the same edge, and conversely abuse
+ * from many clients hides behind one IP.
+ *
+ * Resolution is ordered, and every header value is VALIDATED as a real IPv4/IPv6
+ * literal (via `node:net.isIP`) before it is trusted — a junk or spoofed header
+ * falls through to the next tier instead of becoming the rate-limit key:
+ *
+ *   1. `CF-Connecting-IP` — the genuine client IP Cloudflare injects. Consulted
+ *      ONLY when `TRUST_CLOUDFLARE` is enabled (orange-cloud / proxied origin).
+ *   2. Left-most VALID `X-Forwarded-For` entry — the original client, appended by
+ *      the reverse proxy. XFF is a comma-separated list (client, proxy1, proxy2,
+ *      ...), so the original client is the left-most entry. This tier is consulted
+ *      regardless of the flag: it covers the grey-cloud / DNS-only case where the
+ *      Cloudflare header is absent but traffic still arrives through Traefik —
+ *      without it, every grey-clouded visitor collapses onto the single shared
+ *      Traefik upstream IP and trips the auto-block site-wide.
+ *   3. `request.ip` — Fastify's socket / trustProxy-resolved peer IP (always
+ *      non-empty), the safe fallback for any origin reachable directly.
+ *
+ * SECURITY PRECONDITION: both `CF-Connecting-IP` and `X-Forwarded-For` are
+ * client-supplied and therefore SPOOFABLE if a caller can reach the origin
+ * directly. They are only trustworthy when the origin accepts traffic
+ * EXCLUSIVELY via the proxy (Cloudflare / Traefik) — a documented deploy
+ * precondition. Validation here narrows the spoof surface to well-formed IP
+ * literals but does not, on its own, prove provenance.
+ *
+ * Use this for rate-limiting and IP-blocking decisions. Logging / session
+ * metadata can keep using `request.ip` — there a spoofed value is harmless.
+ */
+
+import { isIP } from 'node:net';
+import type { FastifyRequest } from 'fastify';
+import { env } from '@config/env.js';
+
+/** Return the trimmed value if it is a valid IPv4/IPv6 literal, else undefined. */
+function asValidIp(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  return isIP(trimmed) !== 0 ? trimmed : undefined;
+}
+
+/**
+ * Resolve the real client IP for rate-limiting / blocking decisions.
+ *
+ * Synchronous and always returns a non-empty string (the `request.ip` fallback
+ * guarantees this), so it is safe to use directly as a rate-limit `keyGenerator`.
+ *
+ * @param request - The incoming Fastify request
+ * @returns The client IP to use as the rate-limit / block key
+ */
+export function getClientIp(request: FastifyRequest): string {
+  // 1. CF-Connecting-IP — only when TRUST_CLOUDFLARE is set (origin locked to CF).
+  if (env.TRUST_CLOUDFLARE) {
+    const cfHeader = request.headers['cf-connecting-ip'];
+    const cf = asValidIp(typeof cfHeader === 'string' ? cfHeader : undefined);
+    if (cf) return cf;
+  }
+  // 2. Left-most VALID X-Forwarded-For entry — the original client, appended by the
+  //    reverse proxy (Traefik/Coolify). Covers grey-cloud / DNS-only where the CF
+  //    header is absent. Validated so a junk/spoofed header falls through.
+  const xffRaw = request.headers['x-forwarded-for'];
+  const xff = typeof xffRaw === 'string' ? xffRaw : Array.isArray(xffRaw) ? xffRaw[0] : undefined;
+  if (xff) {
+    const leftMost = asValidIp(xff.split(',')[0]);
+    if (leftMost) return leftMost;
+  }
+  // 3. Fastify's socket/trustProxy-resolved peer IP (always non-empty).
+  return request.ip;
+}

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

@@ -1,212 +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 { 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';
-
-// 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> {
-  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/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;
+  });
+}