create-tigra 2.2.0 → 2.4.0

package/template/client/src/middleware.ts

@@ -2,8 +2,7 @@ import { NextResponse } from 'next/server';
 
 import type { NextRequest } from 'next/server';
 
-const protectedPaths = ['/', '/dashboard', '/profile', '/admin'];
-const authPaths = ['/login', '/register'];
+const protectedPaths = ['/dashboard', '/profile', '/admin'];
 
 function isTokenExpired(token: string): boolean {
   try {
@@ -17,38 +16,33 @@ function isTokenExpired(token: string): boolean {
 
 export function middleware(request: NextRequest): NextResponse {
   const { pathname } = request.nextUrl;
-  const token = request.cookies.get('access_token')?.value;
+  const accessToken = request.cookies.get('access_token')?.value;
+  const authSession = request.cookies.get('auth_session')?.value;
 
-  const isProtectedPath = protectedPaths.some((path) =>
-    path === '/' ? pathname === '/' : pathname.startsWith(path)
-  );
+  const isProtectedPath = protectedPaths.some((path) => pathname.startsWith(path));
 
-  // No token at all — user is not logged in, redirect to login
-  if (isProtectedPath && !token) {
-    const loginUrl = new URL('/login', request.url);
-    loginUrl.searchParams.set('from', pathname);
-    return NextResponse.redirect(loginUrl);
-  }
-
-  // Expired token on protected path — allow through so client-side can attempt refresh.
-  // Delete the stale access_token so AuthInitializer starts fresh: getMe() → 401 → refresh.
-  if (isProtectedPath && token && isTokenExpired(token)) {
-    const response = NextResponse.next();
-    response.cookies.delete('access_token');
-    return response;
-  }
+  if (isProtectedPath) {
+    // No access_token AND no auth_session — truly unauthenticated
+    if (!accessToken && !authSession) {
+      const loginUrl = new URL('/login', request.url);
+      loginUrl.searchParams.set('from', pathname);
+      return NextResponse.redirect(loginUrl);
+    }
 
-  const isAuthPath = authPaths.some((path) => pathname.startsWith(path));
+    // No access_token BUT auth_session exists — session is alive,
+    // let through so client-side can do getMe() → 401 → refresh → retry
+    if (!accessToken && authSession) {
+      return NextResponse.next();
+    }
 
-  if (isAuthPath && token) {
-    if (isTokenExpired(token)) {
-      // Only delete the expired access token — keep the refresh token
-      // so the client-side interceptor can still recover the session
+    // Expired access_token — delete stale cookie, let through for client-side refresh
+    if (accessToken && isTokenExpired(accessToken)) {
       const response = NextResponse.next();
       response.cookies.delete('access_token');
       return response;
     }
-    return NextResponse.redirect(new URL('/', request.url));
+
+    return NextResponse.next();
   }
 
   return NextResponse.next();
@@ -56,11 +50,8 @@ export function middleware(request: NextRequest): NextResponse {
 
 export const config = {
   matcher: [
-    '/',
     '/dashboard/:path*',
     '/profile/:path*',
     '/admin/:path*',
-    '/login',
-    '/register',
   ],
 };

package/template/server/.env.example

@@ -94,6 +94,15 @@ JWT_REFRESH_EXPIRY="7d"
 # For production: generate a separate secret: openssl rand -base64 48
 # COOKIE_SECRET="change-this-to-a-different-secret-at-least-32-chars"
 
+# Cookie domain for cross-origin deployments
+# REQUIRED when client and API are on different subdomains:
+#   Client: https://app.example.com  |  API: https://api.example.com
+#   → Set COOKIE_DOMAIN=".example.com" (note the leading dot)
+# NOT needed when client and API share the same hostname (local dev, same-origin prod)
+# Without this, cookies are scoped to the API hostname only and the browser
+# will silently reject them on cross-origin requests (login appears to do nothing).
+# COOKIE_DOMAIN=".example.com"
+
 # ===================================================================
 # CORS (Cross-Origin Resource Sharing)
 # ===================================================================

package/template/server/.env.example.production

@@ -80,6 +80,14 @@ JWT_REFRESH_EXPIRY="7d"
 # Multiple origins separated by commas
 CORS_ORIGIN="https://yourdomain.com,https://app.yourdomain.com"
 
+# Cookie domain for cross-origin deployments
+# REQUIRED when client and API are on different subdomains:
+#   Client: https://app.example.com  |  API: https://api.example.com
+#   → Set COOKIE_DOMAIN=".example.com" (leading dot = all subdomains)
+# This enables cookies to be shared between client and API subdomains.
+# Without it, login will silently fail (server returns 200 but browser drops cookies).
+COOKIE_DOMAIN=".yourdomain.com"
+
 # ===================================================================
 # LOGGING
 # ===================================================================
@@ -102,6 +110,7 @@ SENTRY_DSN="https://YOUR_PUBLIC_KEY@o0.ingest.sentry.io/YOUR_PROJECT_ID"
 # [ ] DATABASE_URL uses secure credentials and SSL
 # [ ] JWT_SECRET is a strong random string (48+ chars)
 # [ ] CORS_ORIGIN is set to your exact frontend URL(s)
+# [ ] COOKIE_DOMAIN is set if client and API are on different subdomains
 # [ ] REDIS_URL uses authentication if Redis is exposed
 # [ ] LOG_LEVEL is set to info or warn
 # [ ] SENTRY_DSN is configured for error tracking

package/template/server/package.json

@@ -22,7 +22,8 @@
     "redis:flush": "tsx scripts/flush-redis.ts",
     "docker:up": "docker compose up -d",
     "docker:down": "docker compose down",
-    "docker:logs": "docker compose logs -f"
+    "docker:logs": "docker compose logs -f",
+    "generate:env": "node -e \"import('fs').then(f=>{if(f.existsSync('.env'))console.log('.env already exists, skipping');else{f.copyFileSync('.env.example','.env');console.log('.env created from .env.example')}})\""
   },
   "prisma": {
     "seed": "tsx prisma/seed.ts"

package/template/server/postman/collection.json

@@ -1,8 +1,8 @@
 {
   "info": {
-    "name": "Tigra Server API",
-    "_postman_id": "tigra-server-collection",
-    "description": "API collection for the Tigra server template.\n\nAll authenticated requests inherit Bearer Token auth from the collection root.\nLogin/Register requests auto-set tokens via test scripts.",
+    "name": "{{PROJECT_DISPLAY_NAME}} API",
+    "_postman_id": "{{PROJECT_NAME}}-server-collection",
+    "description": "API collection for {{PROJECT_DISPLAY_NAME}}.\n\nAll authenticated requests inherit Bearer Token auth from the collection root.\nLogin/Register requests auto-set tokens via test scripts.",
     "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
   },
   "auth": {
@@ -31,6 +31,10 @@
     {
       "key": "userId",
       "value": ""
+    },
+    {
+      "key": "targetUserId",
+      "value": ""
     }
   ],
   "item": [
@@ -358,6 +362,111 @@
       "name": "Admin",
       "description": "Admin-only endpoints. Requires ADMIN role. Auth inherited from collection root.",
       "item": [
+        {
+          "name": "User Management",
+          "description": "Manage users by ID. Requires ADMIN role. Set {{targetUserId}} before calling.",
+          "item": [
+            {
+              "name": "Update Profile (by ID)",
+              "request": {
+                "method": "PATCH",
+                "header": [
+                  {
+                    "key": "Content-Type",
+                    "value": "application/json"
+                  }
+                ],
+                "body": {
+                  "mode": "raw",
+                  "raw": "{\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Smith\"\n}"
+                },
+                "url": {
+                  "raw": "{{baseUrl}}/users/{{targetUserId}}",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["users", "{{targetUserId}}"]
+                },
+                "description": "Update a user's profile by ID. Requires owner or admin access."
+              },
+              "response": []
+            },
+            {
+              "name": "Change Password (by ID)",
+              "request": {
+                "method": "PATCH",
+                "header": [
+                  {
+                    "key": "Content-Type",
+                    "value": "application/json"
+                  }
+                ],
+                "body": {
+                  "mode": "raw",
+                  "raw": "{\n  \"newPassword\": \"NewPassword456\"\n}"
+                },
+                "url": {
+                  "raw": "{{baseUrl}}/users/{{targetUserId}}/password",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["users", "{{targetUserId}}", "password"]
+                },
+                "description": "Change a user's password by ID. Admin: only newPassword required. Invalidates all target user sessions."
+              },
+              "response": []
+            },
+            {
+              "name": "Delete Account (by ID)",
+              "request": {
+                "method": "DELETE",
+                "header": [],
+                "url": {
+                  "raw": "{{baseUrl}}/users/{{targetUserId}}",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["users", "{{targetUserId}}"]
+                },
+                "description": "Soft-delete a user's account by ID. No password required for admin. Invalidates all target user sessions."
+              },
+              "response": []
+            },
+            {
+              "name": "Upload Avatar (by ID)",
+              "request": {
+                "method": "POST",
+                "header": [],
+                "body": {
+                  "mode": "formdata",
+                  "formdata": [
+                    {
+                      "key": "file",
+                      "type": "file",
+                      "src": "",
+                      "description": "Image file (JPEG, PNG, or WebP, max 10MB)"
+                    }
+                  ]
+                },
+                "url": {
+                  "raw": "{{baseUrl}}/users/{{targetUserId}}/avatar",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["users", "{{targetUserId}}", "avatar"]
+                },
+                "description": "Upload or replace a user's avatar by ID. Requires admin access. Accepts JPEG, PNG, or WebP."
+              },
+              "response": []
+            },
+            {
+              "name": "Delete Avatar (by ID)",
+              "request": {
+                "method": "DELETE",
+                "header": [],
+                "url": {
+                  "raw": "{{baseUrl}}/users/{{targetUserId}}/avatar",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["users", "{{targetUserId}}", "avatar"]
+                },
+                "description": "Delete a user's avatar by ID. Requires admin access."
+              },
+              "response": []
+            }
+          ]
+        },
         {
           "name": "List Blocked IPs",
           "request": {
@@ -384,14 +493,14 @@
             ],
             "body": {
               "mode": "raw",
-              "raw": "{\n  \"ip\": \"1.2.3.4\"\n}"
+              "raw": "{\n  \"ip\": \"1.2.3.4\",\n  \"reason\": \"Spam bot\"\n}"
             },
             "url": {
               "raw": "{{baseUrl}}/admin/blocked-ips",
               "host": ["{{baseUrl}}"],
               "path": ["admin", "blocked-ips"]
             },
-            "description": "Permanently block an IP address. Blocked IPs receive 403 IP_BLOCKED on all requests."
+            "description": "Permanently block an IP address. Persisted to database and cached in Redis. Blocked IPs receive 403 IP_BLOCKED on all requests. Optional reason field for audit trail."
           },
           "response": []
         },

package/template/server/postman/environment.json

@@ -1,6 +1,6 @@
 {
-  "id": "tigra-server-env",
-  "name": "Tigra Server - Local",
+  "id": "{{PROJECT_NAME}}-server-env",
+  "name": "{{PROJECT_DISPLAY_NAME}} Server - Local",
   "values": [
     {
       "key": "baseUrl",

package/template/server/prisma/schema.prisma

@@ -18,7 +18,7 @@ model User {
   password      String
   firstName     String
   lastName      String
-  avatarUrl     String?   // SEO-friendly path: /uploads/avatars/{userId}/{firstName-lastName}-avatar.webp
+  avatarUrl     String?   // SEO-friendly path: /uploads/users/{userId}/avatar/{firstName-lastName}-avatar.webp
   role          UserRole  @default(USER)
   isActive      Boolean   @default(true)
   deletedAt     DateTime?
@@ -32,6 +32,7 @@ model User {
 
   refreshTokens RefreshToken[]
   sessions      Session[]
+  blockedIps    BlockedIp[]
 
   // Performance indexes for high-traffic scenarios (10K-100K users/day)
   @@index([role])           // For role-based authorization queries
@@ -75,3 +76,18 @@ model Session {
   @@index([expiresAt])         // For expired session cleanup
   @@map("sessions")
 }
+
+model BlockedIp {
+  id        String   @id @default(uuid())
+  ip        String   @unique @db.VarChar(45)
+  reason    String?  @db.VarChar(500)
+  blockedBy String
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  user User @relation(fields: [blockedBy], references: [id])
+
+  @@index([ip])
+  @@map("blocked_ips")
+}

package/template/server/src/app.ts

@@ -21,7 +21,7 @@ import { adminRoutes } from '@modules/admin/admin.routes.js';
 import { fileStorageService } from '@libs/storage/file-storage.service.js';
 import { registerJobs } from '@jobs/index.js';
 import { RATE_LIMIT_ENABLED, getRateLimitRedisStore } from '@config/rate-limit.config.js';
-import { isIpBlocked, recordRateLimitViolation } from '@libs/ip-block.js';
+import { isIpBlocked, recordRateLimitViolation, syncBlockedIpsToRedis } from '@libs/ip-block.js';
 import { ForbiddenError } from '@shared/errors/errors.js';
 import {
   serializerCompiler,
@@ -135,6 +135,9 @@ export async function buildApp() {
   // Initialize file storage (create directories)
   await fileStorageService.initialize();
 
+  // --- Sync permanent IP blocks from DB to Redis ---
+  await syncBlockedIpsToRedis();
+
   // --- IP Block Check (runs before everything else) ---
   app.addHook('onRequest', async (request: FastifyRequest) => {
     if (await isIpBlocked(request.ip)) {

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

@@ -39,6 +39,12 @@ const envSchema = z.object({
   // 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(),
+
   // --- CORS ---
   // In development: CORS_ORIGIN is optional (allows all origins)
   // In production: REQUIRED for security

package/template/server/src/jobs/cleanup-deleted-accounts.job.ts

@@ -2,7 +2,7 @@
  * Cleanup Deleted Accounts Job
  *
  * Permanently purges soft-deleted user accounts after a 30-day retention period.
- * Deletes avatar files from disk and hard-deletes the user record (cascades to
+ * Deletes all user media from disk and hard-deletes the user record (cascades to
  * refresh tokens and sessions via onDelete: Cascade).
  *
  * Runs once daily.
@@ -32,7 +32,6 @@ export function startCleanupDeletedAccountsJob(app: FastifyInstance): void {
         },
         select: {
           id: true,
-          avatarUrl: true,
         },
       });
 
@@ -49,10 +48,8 @@ export function startCleanupDeletedAccountsJob(app: FastifyInstance): void {
 
       for (const user of usersToDelete) {
         try {
-          // Delete avatar files from disk if they exist
-          if (user.avatarUrl) {
-            await fileStorageService.deleteAvatar(user.id);
-          }
+          // Delete all user media from disk (no-op if dir doesn't exist)
+          await fileStorageService.deleteUserMedia(user.id);
 
           // Hard delete user record (cascades to RefreshToken + Session)
           await prisma.user.delete({

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

@@ -2,7 +2,7 @@ import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
 import { v4 as uuidv4 } from 'uuid';
 import { env } from '@config/env.js';
 import { prisma } from '@libs/prisma.js';
-import { UnauthorizedError, ForbiddenError } from '@shared/errors/errors.js';
+import { UnauthorizedError, ForbiddenError, BadRequestError } from '@shared/errors/errors.js';
 import type { JwtPayload, UserRole } from '@shared/types/index.js';
 
 let app: FastifyInstance | null = null;
@@ -97,3 +97,47 @@ export function authorize(...roles: UserRole[]) {
   };
 }
 
+/**
+ * Middleware: resolves targetUserId from the authenticated user's JWT.
+ * Used for /users/me routes.
+ * Must run AFTER authenticate.
+ */
+export async function resolveMe(
+  request: FastifyRequest,
+  _reply: FastifyReply,
+): Promise<void> {
+  request.targetUserId = request.user.userId;
+  request.isAdminAction = false;
+}
+
+/**
+ * Middleware: resolves targetUserId from :userId param.
+ * Allows access if the authenticated user is the owner OR has ADMIN role.
+ * Must run AFTER authenticate.
+ *
+ * Sets:
+ * - request.targetUserId: the resolved user ID from params
+ * - request.isAdminAction: true if admin is acting on a different user
+ */
+export async function resolveTargetUser(
+  request: FastifyRequest,
+  _reply: FastifyReply,
+): Promise<void> {
+  const params = request.params as { userId?: string };
+  const targetUserId = params.userId;
+
+  if (!targetUserId) {
+    throw new BadRequestError('Missing userId parameter', 'MISSING_USER_ID');
+  }
+
+  const isOwner = request.user.userId === targetUserId;
+  const isAdmin = request.user.role === 'ADMIN';
+
+  if (!isOwner && !isAdmin) {
+    throw new ForbiddenError('You do not have permission to perform this action');
+  }
+
+  request.targetUserId = targetUserId;
+  request.isAdminAction = !isOwner && isAdmin;
+}
+

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

@@ -4,6 +4,14 @@ import { parseDurationMs } from '@libs/auth.js';
 
 const isProduction = env.NODE_ENV === 'production';
 
+// Cross-origin deployment: client and API on different subdomains require sameSite 'none'.
+// Same-origin deployment (or local dev): 'strict' is the safest default.
+const isCrossOrigin = Boolean(env.COOKIE_DOMAIN);
+const sameSitePolicy = isProduction && isCrossOrigin ? 'none' as const : 'strict' as const;
+
+// When set, cookies are shared across subdomains (e.g., ".example.com" covers app.example.com + api.example.com)
+const cookieDomain = env.COOKIE_DOMAIN || undefined;
+
 const ACCESS_TOKEN_MAX_AGE_MS = parseDurationMs(env.JWT_ACCESS_EXPIRY, 15 * 60 * 1000);
 const REFRESH_TOKEN_MAX_AGE_MS = parseDurationMs(env.JWT_REFRESH_EXPIRY, 7 * 24 * 60 * 60 * 1000);
 
@@ -15,7 +23,8 @@ export function setAuthCookies(
   reply.setCookie('access_token', accessToken, {
     httpOnly: true,
     secure: isProduction,
-    sameSite: 'strict',
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
     path: '/',
     maxAge: Math.floor(ACCESS_TOKEN_MAX_AGE_MS / 1000), // setCookie expects seconds
   });
@@ -23,24 +32,46 @@ export function setAuthCookies(
   reply.setCookie('refresh_token', refreshToken, {
     httpOnly: true,
     secure: isProduction,
-    sameSite: 'strict',
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
     path: '/api/v1/auth',
     maxAge: Math.floor(REFRESH_TOKEN_MAX_AGE_MS / 1000),
   });
+
+  // Non-sensitive session indicator visible to Next.js middleware and client JS.
+  // Lets middleware distinguish "never logged in" from "access token expired but session alive."
+  reply.setCookie('auth_session', '1', {
+    httpOnly: false,
+    secure: isProduction,
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
+    path: '/',
+    maxAge: Math.floor(REFRESH_TOKEN_MAX_AGE_MS / 1000),
+  });
 }
 
 export function clearAuthCookies(reply: FastifyReply): void {
   reply.clearCookie('access_token', {
     httpOnly: true,
     secure: isProduction,
-    sameSite: 'strict',
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
     path: '/',
   });
 
   reply.clearCookie('refresh_token', {
     httpOnly: true,
     secure: isProduction,
-    sameSite: 'strict',
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
     path: '/api/v1/auth',
   });
+
+  reply.clearCookie('auth_session', {
+    httpOnly: false,
+    secure: isProduction,
+    sameSite: sameSitePolicy,
+    domain: cookieDomain,
+    path: '/',
+  });
 }