shortcut-next 0.2.2 → 0.2.6

package/templates/base/lib/abilities/types.ts

@@ -0,0 +1,68 @@
+import type { MongoAbility } from '@casl/ability'
+
+/**
+ * Subject types for authorization
+ * These represent resource areas in the application
+ */
+export type Subjects =
+  | 'Home'
+  | 'Dashboard'
+  | 'Users'
+  | 'Settings'
+  | 'Reports'
+  | 'Tickets'
+  | 'all'
+
+/**
+ * Action types for CASL permissions
+ * - read: View resources
+ * - create: Create new resources
+ * - update: Modify existing resources
+ * - delete: Remove resources
+ * - manage: Full access (all actions)
+ */
+export type Actions = 'read' | 'create' | 'update' | 'delete' | 'manage'
+
+/**
+ * CASL Ability type for the application
+ */
+export type AppAbility = MongoAbility<[Actions, Subjects]>
+
+/**
+ * Supported user roles
+ * Hierarchy: admin > manager > agent > viewer
+ */
+export type UserRole = 'admin' | 'manager' | 'agent' | 'viewer'
+
+/**
+ * Minimal user type for authorization checks
+ */
+export interface AuthUser {
+  id: string
+  role: UserRole
+}
+
+/**
+ * Route permission mapping entry
+ * Maps a route pattern to required CASL permission
+ */
+export interface RoutePermission {
+  /** Route pattern (exact, [param], or wildcard /*) */
+  pattern: string
+  /** Required action to access the route */
+  action: Actions
+  /** Required subject for the route */
+  subject: Subjects
+  /** Optional description for documentation */
+  description?: string
+}
+
+/**
+ * Result of matching a route against patterns
+ */
+export interface MatchedRoute {
+  /** The matched permission entry */
+  permission: RoutePermission
+  /** Extracted dynamic parameters */
+  params: Record<string, string>
+}

package/templates/base/lib/mocks/browser.ts

@@ -0,0 +1,11 @@
+/**
+ * MSW Browser Worker
+ *
+ * Sets up MSW to intercept requests in the browser.
+ * This is used for development to mock API responses.
+ */
+
+import { setupWorker } from 'msw/browser'
+import { handlers } from './handlers'
+
+export const worker = setupWorker(...handlers)

package/templates/base/lib/mocks/db.ts

@@ -0,0 +1,124 @@
+/**
+ * Mock Database for MSW
+ *
+ * Uses in-memory storage since MSW service workers don't have localStorage access.
+ * This simulates a database for development/testing purposes.
+ */
+
+import type { UserRole } from '@/lib/abilities'
+
+export interface MockUser {
+  id: string
+  email: string
+  password: string // In real app, this would be hashed
+  name: string
+  role: UserRole
+  phone?: string
+  companyName?: string
+  type?: 'BUSINESS' | 'CUSTOMER'
+  createdAt: string
+}
+
+/**
+ * Default test users for each role
+ */
+const defaultUsers: MockUser[] = [
+  {
+    id: 'user_admin_001',
+    email: 'admin@test.com',
+    password: 'password123',
+    name: 'Admin User',
+    role: 'admin',
+    createdAt: new Date().toISOString()
+  },
+  {
+    id: 'user_manager_001',
+    email: 'manager@test.com',
+    password: 'password123',
+    name: 'Manager User',
+    role: 'manager',
+    createdAt: new Date().toISOString()
+  },
+  {
+    id: 'user_agent_001',
+    email: 'agent@test.com',
+    password: 'password123',
+    name: 'Agent User',
+    role: 'agent',
+    createdAt: new Date().toISOString()
+  },
+  {
+    id: 'user_viewer_001',
+    email: 'viewer@test.com',
+    password: 'password123',
+    name: 'Viewer User',
+    role: 'viewer',
+    createdAt: new Date().toISOString()
+  }
+]
+
+// In-memory database (works in service worker context)
+let usersDb: MockUser[] = [...defaultUsers]
+
+/**
+ * Get all users from mock database
+ */
+export function getUsers(): MockUser[] {
+  return usersDb
+}
+
+/**
+ * Find user by email
+ */
+export function findUserByEmail(email: string): MockUser | undefined {
+  return usersDb.find((u) => u.email.toLowerCase() === email.toLowerCase())
+}
+
+/**
+ * Find user by ID
+ */
+export function findUserById(id: string): MockUser | undefined {
+  return usersDb.find((u) => u.id === id)
+}
+
+/**
+ * Create a new user
+ */
+export function createUser(userData: Omit<MockUser, 'id' | 'createdAt'>): MockUser {
+  const newUser: MockUser = {
+    ...userData,
+    id: `user_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+    createdAt: new Date().toISOString()
+  }
+
+  usersDb.push(newUser)
+  return newUser
+}
+
+/**
+ * Update user
+ */
+export function updateUser(id: string, updates: Partial<MockUser>): MockUser | null {
+  const index = usersDb.findIndex((u) => u.id === id)
+
+  if (index === -1) return null
+
+  usersDb[index] = { ...usersDb[index], ...updates }
+  return usersDb[index]
+}
+
+/**
+ * Delete user
+ */
+export function deleteUser(id: string): boolean {
+  const initialLength = usersDb.length
+  usersDb = usersDb.filter((u) => u.id !== id)
+  return usersDb.length !== initialLength
+}
+
+/**
+ * Reset database to default users
+ */
+export function resetDatabase(): void {
+  usersDb = [...defaultUsers]
+}

package/templates/base/lib/mocks/handlers/auth.ts

@@ -0,0 +1,203 @@
+/**
+ * MSW Auth Handlers
+ *
+ * Mock API handlers for authentication endpoints.
+ * These simulate a real backend for development and testing.
+ */
+
+import { http, HttpResponse, delay } from 'msw'
+import { findUserByEmail, createUser } from '../db'
+import { createMockAccessToken, createMockRefreshToken, decodeMockToken } from '../jwt'
+import type { UserRole } from '@/lib/abilities'
+
+const API_BASE = '/api'
+
+/**
+ * Simulate network delay
+ */
+const SIMULATED_DELAY = 500
+
+export const authHandlers = [
+  /**
+   * POST /api/auth/login
+   */
+  http.post(`${API_BASE}/auth/login`, async ({ request }) => {
+    await delay(SIMULATED_DELAY)
+
+    const body = (await request.json()) as { email: string; password: string }
+
+    if (!body.email || !body.password) {
+      return HttpResponse.json({ message: 'Email and password are required' }, { status: 400 })
+    }
+
+    const user = findUserByEmail(body.email)
+
+    if (!user) {
+      return HttpResponse.json({ message: 'Invalid email or password' }, { status: 401 })
+    }
+
+    if (user.password !== body.password) {
+      return HttpResponse.json({ message: 'Invalid email or password' }, { status: 401 })
+    }
+
+    const accessToken = createMockAccessToken({
+      id: user.id,
+      email: user.email,
+      name: user.name,
+      role: user.role
+    })
+
+    const refreshToken = createMockRefreshToken(user.id)
+
+    // Return user without password
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { password, ...userWithoutPassword } = user
+
+    return HttpResponse.json({
+      user: userWithoutPassword,
+      accessToken,
+      refreshToken
+    })
+  }),
+
+  /**
+   * POST /api/auth/signup
+   */
+  http.post(`${API_BASE}/auth/signup`, async ({ request }) => {
+    await delay(SIMULATED_DELAY)
+
+    const body = (await request.json()) as {
+      email: string
+      password: string
+      name: string
+      phone?: string
+      companyName?: string
+      type?: 'BUSINESS' | 'CUSTOMER'
+      role?: UserRole
+    }
+
+    if (!body.email || !body.password || !body.name) {
+      return HttpResponse.json({ message: 'Email, password, and name are required' }, { status: 400 })
+    }
+
+    // Check if user already exists
+    const existingUser = findUserByEmail(body.email)
+    if (existingUser) {
+      return HttpResponse.json({ message: 'User with this email already exists' }, { status: 409 })
+    }
+
+    // Create new user (default role is 'viewer' for new signups)
+    const newUser = createUser({
+      email: body.email,
+      password: body.password,
+      name: body.name,
+      role: body.role || 'viewer', // Allow role override for testing
+      phone: body.phone,
+      companyName: body.companyName,
+      type: body.type
+    })
+
+    const accessToken = createMockAccessToken({
+      id: newUser.id,
+      email: newUser.email,
+      name: newUser.name,
+      role: newUser.role
+    })
+
+    const refreshToken = createMockRefreshToken(newUser.id)
+
+    // Return user without password
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { password, ...userWithoutPassword } = newUser
+
+    return HttpResponse.json({
+      user: userWithoutPassword,
+      accessToken,
+      refreshToken
+    })
+  }),
+
+  /**
+   * POST /api/auth/refresh
+   */
+  http.post(`${API_BASE}/auth/refresh`, async ({ request }) => {
+    await delay(SIMULATED_DELAY)
+
+    const body = (await request.json()) as { refreshToken: string }
+
+    if (!body.refreshToken) {
+      return HttpResponse.json({ message: 'Refresh token is required' }, { status: 400 })
+    }
+
+    const decoded = decodeMockToken(body.refreshToken)
+
+    if (!decoded || decoded.exp * 1000 < Date.now()) {
+      return HttpResponse.json({ message: 'Invalid or expired refresh token' }, { status: 401 })
+    }
+
+    // Find user by ID from token
+    const { findUserById } = await import('../db')
+    const user = findUserById(decoded.sub)
+
+    if (!user) {
+      return HttpResponse.json({ message: 'User not found' }, { status: 401 })
+    }
+
+    const accessToken = createMockAccessToken({
+      id: user.id,
+      email: user.email,
+      name: user.name,
+      role: user.role
+    })
+
+    const refreshToken = createMockRefreshToken(user.id)
+
+    return HttpResponse.json({
+      accessToken,
+      refreshToken
+    })
+  }),
+
+  /**
+   * POST /api/auth/logout
+   */
+  http.post(`${API_BASE}/auth/logout`, async () => {
+    await delay(SIMULATED_DELAY / 2)
+
+    // In a real app, you might invalidate the refresh token here
+    return HttpResponse.json({ message: 'Logged out successfully' })
+  }),
+
+  /**
+   * GET /api/auth/me
+   */
+  http.get(`${API_BASE}/auth/me`, async ({ request }) => {
+    await delay(SIMULATED_DELAY / 2)
+
+    const authHeader = request.headers.get('Authorization')
+
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return HttpResponse.json({ message: 'Unauthorized' }, { status: 401 })
+    }
+
+    const token = authHeader.substring(7)
+    const decoded = decodeMockToken(token)
+
+    if (!decoded || decoded.exp * 1000 < Date.now()) {
+      return HttpResponse.json({ message: 'Token expired' }, { status: 401 })
+    }
+
+    const { findUserById } = await import('../db')
+    const user = findUserById(decoded.sub)
+
+    if (!user) {
+      return HttpResponse.json({ message: 'User not found' }, { status: 404 })
+    }
+
+    // Return user without password
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { password, ...userWithoutPassword } = user
+
+    return HttpResponse.json({ user: userWithoutPassword })
+  })
+]

package/templates/base/lib/mocks/handlers/index.ts

@@ -0,0 +1,16 @@
+/**
+ * MSW Handlers Index
+ *
+ * Combines all mock API handlers.
+ * Add new handler modules here as your app grows.
+ */
+
+import { authHandlers } from './auth'
+
+export const handlers = [
+  ...authHandlers
+  // Add more handlers here as needed:
+  // ...userHandlers,
+  // ...ticketHandlers,
+  // etc.
+]

package/templates/base/lib/mocks/index.ts

@@ -0,0 +1,34 @@
+/**
+ * MSW Mock Service Worker Setup
+ *
+ * This module provides mock API functionality for development.
+ *
+ * Usage:
+ * 1. Call initMocks() early in your app (e.g., in a useEffect in your root layout)
+ * 2. The mock server will intercept API calls and return mock responses
+ *
+ * To disable mocks, set NEXT_PUBLIC_ENABLE_MOCKS=false in .env.local
+ */
+
+export async function initMocks() {
+  // Only run in browser and development
+  if (typeof window === 'undefined') return
+  if (process.env.NODE_ENV !== 'development') return
+  if (process.env.NEXT_PUBLIC_ENABLE_MOCKS === 'false') return
+
+  const { worker } = await import('./browser')
+
+  // Start the worker
+  await worker.start({
+    onUnhandledRequest: 'bypass', // Don't warn about unhandled requests
+    serviceWorker: {
+      url: '/mockServiceWorker.js'
+    }
+  })
+
+  console.log('[MSW] Mock Service Worker started')
+}
+
+// Re-export utilities
+export { resetDatabase, getUsers } from './db'
+export type { MockUser } from './db'

package/templates/base/lib/mocks/jwt.ts

@@ -0,0 +1,99 @@
+/**
+ * Mock JWT utilities for development
+ *
+ * Creates JWTs that can be decoded by the middleware.
+ * In production, JWTs should be created and signed by your backend.
+ */
+
+import type { UserRole } from '@/lib/abilities'
+
+interface TokenPayload {
+  sub: string
+  email: string
+  name: string
+  role: UserRole
+  iat: number
+  exp: number
+}
+
+/**
+ * Create a mock JWT token
+ *
+ * This creates a valid JWT structure that can be decoded.
+ * Note: This is NOT cryptographically signed - for development only.
+ */
+export function createMockAccessToken(user: {
+  id: string
+  email: string
+  name: string
+  role: UserRole
+}): string {
+  const header = { alg: 'HS256', typ: 'JWT' }
+
+  const payload: TokenPayload = {
+    sub: user.id,
+    email: user.email,
+    name: user.name,
+    role: user.role,
+    iat: Math.floor(Date.now() / 1000),
+    exp: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 7 // 7 days
+  }
+
+  const base64Header = base64UrlEncode(JSON.stringify(header))
+  const base64Payload = base64UrlEncode(JSON.stringify(payload))
+  const mockSignature = base64UrlEncode('mock_signature_for_development')
+
+  return `${base64Header}.${base64Payload}.${mockSignature}`
+}
+
+/**
+ * Create a mock refresh token
+ */
+export function createMockRefreshToken(userId: string): string {
+  const payload = {
+    sub: userId,
+    type: 'refresh',
+    iat: Math.floor(Date.now() / 1000),
+    exp: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 30 // 30 days
+  }
+
+  const header = { alg: 'HS256', typ: 'JWT' }
+  const base64Header = base64UrlEncode(JSON.stringify(header))
+  const base64Payload = base64UrlEncode(JSON.stringify(payload))
+  const mockSignature = base64UrlEncode('mock_refresh_signature')
+
+  return `${base64Header}.${base64Payload}.${mockSignature}`
+}
+
+/**
+ * Decode a JWT token (without verification)
+ */
+export function decodeMockToken(token: string): TokenPayload | null {
+  try {
+    const parts = token.split('.')
+    if (parts.length !== 3) return null
+
+    const payload = JSON.parse(base64UrlDecode(parts[1]))
+    return payload
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Base64 URL encode
+ */
+function base64UrlEncode(str: string): string {
+  return btoa(str).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')
+}
+
+/**
+ * Base64 URL decode
+ */
+function base64UrlDecode(str: string): string {
+  let base64 = str.replace(/-/g, '+').replace(/_/g, '/')
+  while (base64.length % 4) {
+    base64 += '='
+  }
+  return atob(base64)
+}

package/templates/base/middleware.ts

@@ -0,0 +1,147 @@
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+import { decodeJwt } from 'jose'
+import { checkAuthorization, isPublicRoute } from '@/lib/abilities'
+import type { UserRole } from '@/lib/abilities'
+import { authConfig } from './@core/configs/clientConfig'
+
+/**
+ * Cookie name for access token
+ * Must match the value in clientConfig.ts
+ */
+const ACCESS_TOKEN_COOKIE = 'accessToken'
+
+/**
+ * Routes that middleware should skip entirely
+ * These are static assets and API routes handled elsewhere
+ */
+const SKIP_ROUTES = ['/_next', '/api', '/favicon.ico', '/locales', '/images']
+
+/**
+ * Valid user roles for type checking
+ */
+const VALID_ROLES: UserRole[] = ['admin', 'manager', 'agent', 'viewer']
+
+/**
+ * JWT payload structure expected from the auth system
+ */
+interface JWTPayload {
+  sub: string
+  email?: string
+  role?: string
+  name?: string
+  exp?: number
+  iat?: number
+}
+
+/**
+ * Extract user role from JWT token
+ *
+ * Note: This only decodes the JWT, it does NOT verify the signature.
+ * Signature verification should happen in API routes.
+ * Middleware decoding is for early rejection of clearly unauthorized requests.
+ *
+ * @param token - JWT access token
+ * @returns UserRole if valid, null otherwise
+ */
+function getUserRoleFromToken(token: string): UserRole | null {
+  try {
+    const payload = decodeJwt(token) as JWTPayload
+
+    // Check if token is expired
+    if (payload.exp && payload.exp * 1000 < Date.now()) {
+      return null
+    }
+
+    // Validate and return role
+    const role = payload.role as UserRole
+    if (VALID_ROLES.includes(role)) {
+      return role
+    }
+
+    // Default to viewer if no valid role found
+    return 'viewer'
+  } catch {
+    // Invalid JWT format
+    return null
+  }
+}
+
+/**
+ * Next.js Middleware
+ *
+ * This is the primary enforcement point for authorization.
+ * It runs before any page renders, on the Edge Runtime.
+ *
+ * Flow:
+ * 1. Skip static assets and API routes
+ * 2. Allow public routes without auth
+ * 3. Extract session from cookie
+ * 4. Check authorization
+ * 5. Redirect if unauthorized
+ */
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl
+
+  // Skip middleware for static assets and API routes
+  if (SKIP_ROUTES.some(route => pathname.startsWith(route))) {
+    return NextResponse.next()
+  }
+
+  // Get token from cookie (needed for both public and protected route checks)
+  const token = request.cookies.get(ACCESS_TOKEN_COOKIE)?.value
+  const userRole = token ? getUserRoleFromToken(token) : null
+
+  // Redirect authenticated users away from login page
+  if (token && userRole && pathname === '/login') {
+    const homeUrl = new URL(authConfig.homePageURL, request.url)
+    return NextResponse.redirect(homeUrl)
+  }
+
+  // Allow public routes without further checks
+  if (isPublicRoute(pathname)) {
+    return NextResponse.next()
+  }
+
+  // Check authorization
+  const result = checkAuthorization(pathname, userRole)
+
+  if (result.authorized) {
+    return NextResponse.next()
+  }
+
+  // Handle unauthorized access
+  if (result.reason === 'unauthenticated') {
+    // Redirect to login with return URL
+    const loginUrl = new URL('/login', request.url)
+    loginUrl.searchParams.set('returnUrl', pathname)
+    return NextResponse.redirect(loginUrl)
+  }
+
+  if (result.reason === 'forbidden') {
+    // Redirect to unauthorized page with context
+    const unauthorizedUrl = new URL('/unauthorized', request.url)
+    unauthorizedUrl.searchParams.set('from', pathname)
+    if (result.requiredSubject) {
+      unauthorizedUrl.searchParams.set('resource', result.requiredSubject)
+    }
+    if (result.requiredAction) {
+      unauthorizedUrl.searchParams.set('action', result.requiredAction)
+    }
+    return NextResponse.redirect(unauthorizedUrl)
+  }
+
+  return NextResponse.next()
+}
+
+/**
+ * Middleware matcher configuration
+ *
+ * Excludes:
+ * - _next/static (static files)
+ * - _next/image (image optimization)
+ * - favicon.ico, sitemap.xml, robots.txt (metadata files)
+ */
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt|mockServiceWorker.js).*)']
+}