create-tigra 2.8.0 → 3.0.2

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

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

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

package/template/server/src/libs/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/cookies.ts

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

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

@@ -0,0 +1,30 @@
+/**
+ * Duration parsing — LEAF MODULE.
+ *
+ * This file must have ZERO imports. It exists to break the circular import
+ * between cookies.ts and auth.ts: cookies.ts calls parseDurationMs at module
+ * top-level, so if it imported the function from auth.ts (which imports
+ * clearAuthCookies from cookies.ts), the cycle left auth.ts partially
+ * initialized and crashed module evaluation with
+ * "parseDurationMs is not a function" (TDZ). Keep this module dependency-free.
+ */
+
+/**
+ * Parse a duration string like "15m", "7d", "30s", "12h" into milliseconds.
+ * Returns `fallbackMs` when the string doesn't match the expected format.
+ */
+export function parseDurationMs(duration: string, fallbackMs: number): number {
+  const match = duration.match(/^(\d+)([smhd])$/);
+  if (!match) return fallbackMs;
+
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  const multipliers: Record<string, number> = {
+    s: 1000,
+    m: 60 * 1000,
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+  };
+
+  return value * multipliers[unit];
+}