shortcut-next 0.2.2 → 0.2.6

package/templates/base/components/ui/FormFieldWrapper.tsx

@@ -0,0 +1,27 @@
+'use client'
+
+import { Box, Typography } from '@mui/material'
+import type { ReactNode } from 'react'
+
+interface FormFieldWrapperProps {
+  title: string
+  children: ReactNode
+  required?: boolean
+}
+
+export default function FormFieldWrapper({ title, children, required }: FormFieldWrapperProps) {
+  return (
+    <Box>
+      <Typography
+        variant="body2"
+        fontWeight={500}
+        color="text.secondary"
+        sx={{ mb: 0.5 }}
+      >
+        {title}
+        {required && <span style={{ color: 'red' }}> *</span>}
+      </Typography>
+      {children}
+    </Box>
+  )
+}

package/templates/base/docs/AuthorizationDocumentation.md

@@ -0,0 +1,348 @@
+# Adding Protected Pages
+
+This guide explains how to add new pages with authentication and authorization.
+
+## Quick Start
+
+### Step 1: Create Your Page
+
+Create a new page file **anywhere** in the `app/` folder:
+
+```tsx
+// app/invoices/page.tsx (or anywhere you want!)
+'use client'
+
+import { Container, Typography } from '@mui/material'
+
+export default function InvoicesPage() {
+  return (
+    <Container maxWidth="lg" sx={{ py: 4 }}>
+      <Typography variant="h4">Invoices</Typography>
+      {/* Your page content */}
+    </Container>
+  )
+}
+```
+
+> **Important:** Always add `'use client'` at the top when using MUI components.
+
+**Note:** The file location doesn't matter for protection. You can place pages at:
+
+- `app/invoices/page.tsx` → `/invoices`
+- `app/(dashboard)/invoices/page.tsx` → `/invoices` (same URL, just organized)
+- `app/admin/invoices/page.tsx` → `/admin/invoices`
+
+Protection is determined by `routeMap.ts`, not folder structure.
+
+### Step 2: Add Permission to Route Map
+
+Open `lib/abilities/routeMap.ts` and add your route:
+
+```ts
+export const routePermissions: RoutePermission[] = [
+  // ... existing routes ...
+
+  // Add your new route
+  {
+    pattern: '/dashboard/invoices',
+    action: 'read',
+    subject: 'Invoices',  // New subject
+    description: 'View invoices list',
+  },
+]
+```
+
+### Step 3: Add Subject to Types (if new)
+
+If you created a new subject (like `'Invoices'`), add it to `lib/abilities/types.ts`:
+
+```ts
+export type Subjects =
+  | 'Dashboard'
+  | 'Users'
+  | 'Settings'
+  | 'Reports'
+  | 'Tickets'
+  | 'Invoices'  // Add your new subject
+  | 'all'
+```
+
+### Step 4: Define Role Permissions
+
+Open `lib/abilities/roles.ts` and add permissions for each role:
+
+```ts
+case 'manager':
+  can('read', 'all')
+  can('manage', 'Users')
+  can('manage', 'Tickets')
+  can('manage', 'Reports')
+  can('manage', 'Invoices')  // Add permission
+  cannot('manage', 'Settings')
+  break
+
+case 'agent':
+  can('read', 'Dashboard')
+  can('read', 'Tickets')
+  can('read', 'Reports')
+  can('read', 'Invoices')  // Add permission
+  // ...
+  break
+```
+
+**Done!** Your page is now protected.
+
+---
+
+## Route Pattern Examples
+
+| Pattern | Matches | Use Case |
+|---------|---------|----------|
+| `/dashboard/invoices` | Exact path only | List page |
+| `/dashboard/invoices/[id]` | `/dashboard/invoices/123` | Detail page |
+| `/dashboard/invoices/*` | Any nested path | Section with sub-pages |
+
+### Dynamic Route Example
+
+```ts
+// For /dashboard/invoices/[id]
+{
+  pattern: '/dashboard/invoices/[id]',
+  action: 'read',
+  subject: 'Invoices',
+},
+
+// For edit page /dashboard/invoices/[id]/edit
+{
+  pattern: '/dashboard/invoices/[id]/edit',
+  action: 'update',
+  subject: 'Invoices',
+},
+
+// For all nested pages under /invoices, including the page itself
+{
+  pattern: '/dashboard/invoices/*',
+  action: 'update',
+  subject: 'Invoices',
+},
+```
+
+---
+
+## Actions Reference
+
+| Action | Meaning | Typical Use |
+|--------|---------|-------------|
+| `read` | View/list resources | List pages, detail pages |
+| `create` | Create new resources | "New" or "Add" pages |
+| `update` | Modify resources | Edit pages |
+| `delete` | Remove resources | Delete functionality |
+| `manage` | All of the above | Full access |
+
+---
+
+## Hiding UI Based on Permissions
+
+To show/hide navigation or buttons based on user's role:
+
+```tsx
+'use client'
+
+import { useAbility } from '@/@core/hooks/useAbility'
+
+function Navigation() {
+  const ability = useAbility()
+
+  return (
+    <nav>
+      {ability.can('read', 'Invoices') && (
+        <Link href="/dashboard/invoices">Invoices</Link>
+      )}
+
+      {ability.can('create', 'Invoices') && (
+        <Button>New Invoice</Button>
+      )}
+    </nav>
+  )
+}
+```
+
+Or use the simpler `useCan` hook:
+
+```tsx
+import { useCan } from '@/@core/hooks/useAbility'
+
+function InvoiceActions() {
+  const canCreate = useCan('create', 'Invoices')
+  const canDelete = useCan('delete', 'Invoices')
+
+  return (
+    <>
+      {canCreate && <Button>New Invoice</Button>}
+      {canDelete && <Button color="error">Delete</Button>}
+    </>
+  )
+}
+```
+
+---
+
+## Complete Example: Adding an "Orders" Section
+
+### 1. Create the pages
+
+```
+app/(dashboard)/dashboard/orders/
+├── page.tsx           # /dashboard/orders (list)
+├── [id]/
+│   └── page.tsx       # /dashboard/orders/123 (detail)
+└── new/
+    └── page.tsx       # /dashboard/orders/new (create)
+```
+
+### 2. Update types.ts
+
+```ts
+export type Subjects =
+  | 'Dashboard'
+  | 'Users'
+  | 'Settings'
+  | 'Reports'
+  | 'Tickets'
+  | 'Orders'  // Added
+  | 'all'
+```
+
+### 3. Update routeMap.ts
+
+```ts
+// Orders - manager and admin
+{ pattern: '/dashboard/orders', action: 'read', subject: 'Orders' },
+{ pattern: '/dashboard/orders/[id]', action: 'read', subject: 'Orders' },
+{ pattern: '/dashboard/orders/new', action: 'create', subject: 'Orders' },
+{ pattern: '/dashboard/orders/[id]/edit', action: 'update', subject: 'Orders' },
+```
+
+### 4. Update roles.ts
+
+```ts
+case 'admin':
+  can('manage', 'all')  // Already has access
+  break
+
+case 'manager':
+  can('read', 'all')
+  can('manage', 'Orders')  // Full access to orders
+  break
+
+case 'agent':
+  can('read', 'Orders')    // Can only view
+  break
+
+case 'viewer':
+  // No access to orders
+  break
+```
+
+---
+
+## Understanding Roles
+
+### Default Roles
+
+The authorization system includes four roles with hierarchical permissions. Find them in `lib/abilities/roles.ts`:
+
+| Role | Description | Access Level |
+|------|-------------|--------------|
+| `admin` | Full system access | `can('manage', 'all')` - everything |
+| `manager` | Team management | Read all, manage Users/Tickets/Reports |
+| `agent` | Operational user | Read Dashboard/Tickets/Reports, manage Tickets |
+| `viewer` | Read-only access | Read Dashboard/Reports only |
+
+### Where Roles are Defined
+
+**Role types:** `lib/abilities/types.ts`
+```ts
+export type UserRole = 'admin' | 'manager' | 'agent' | 'viewer'
+```
+
+**Role permissions:** `lib/abilities/roles.ts`
+```ts
+export function defineAbilitiesFor(role: UserRole): AppAbility {
+  const { can, cannot, build } = new AbilityBuilder<AppAbility>(createMongoAbility)
+
+  switch (role) {
+    case 'admin':
+      can('manage', 'all')
+      break
+    case 'manager':
+      can('read', 'all')
+      can('manage', 'Users')
+      can('manage', 'Tickets')
+      can('manage', 'Reports')
+      cannot('manage', 'Settings')
+      break
+    // ... other roles
+  }
+
+  return build()
+}
+```
+
+### Adding a New Role
+
+1. **Add the role type** in `lib/abilities/types.ts`:
+```ts
+export type UserRole = 'admin' | 'manager' | 'agent' | 'viewer' | 'support'
+```
+
+2. **Define permissions** in `lib/abilities/roles.ts`:
+```ts
+case 'support':
+  can('read', 'Dashboard')
+  can('read', 'Tickets')
+  can('create', 'Tickets')
+  break
+```
+
+3. **Update your JWT** - ensure the backend includes the new role in the token payload.
+
+### Modifying Existing Role Permissions
+
+Open `lib/abilities/roles.ts` and modify the `switch` cases:
+
+```ts
+// Example: Give agents access to create invoices
+case 'agent':
+  can('read', 'Dashboard')
+  can('read', 'Tickets')
+  can('manage', 'Tickets')
+  can('read', 'Reports')
+  can('create', 'Invoices')  // Added new permission
+  break
+```
+
+### Role Permission Matrix
+
+Current default permissions:
+
+| Subject | admin | manager | agent | viewer |
+|---------|-------|---------|-------|--------|
+| Dashboard | manage | read | read | read |
+| Users | manage | manage | - | - |
+| Tickets | manage | manage | manage | - |
+| Reports | manage | manage | read | read |
+| Settings | manage | - | - | - |
+
+> **Tip:** Use `can('manage', 'Subject')` to grant all actions (read, create, update, delete) at once.
+
+---
+
+## Summary
+
+1. **Create page** in `app/(dashboard)/dashboard/`
+2. **Add route** to `lib/abilities/routeMap.ts`
+3. **Add subject** to `lib/abilities/types.ts` (if new)
+4. **Define permissions** in `lib/abilities/roles.ts`
+
+The middleware automatically enforces these rules - no changes needed to individual pages!

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

@@ -0,0 +1,74 @@
+import type { UserRole, Actions, Subjects } from './types'
+import { matchRoute, isPublicRoute, isAuthenticatedOnlyRoute } from './routeMatcher'
+import { canAccess } from './roles'
+
+/**
+ * Result of an authorization check
+ */
+export interface AuthorizationResult {
+  /** Whether access is authorized */
+  authorized: boolean
+  /** Reason for the result */
+  reason?: 'unauthenticated' | 'forbidden' | 'public' | 'authenticated'
+  /** The action that was required (for forbidden results) */
+  requiredAction?: Actions
+  /** The subject that was required (for forbidden results) */
+  requiredSubject?: Subjects
+}
+
+/**
+ * Check if a user can access a given pathname
+ *
+ * This is the main authorization orchestration function.
+ * It checks:
+ * 1. If the route is public (always allowed)
+ * 2. If the user is authenticated
+ * 3. If the route has specific permissions and user satisfies them
+ *
+ * @param pathname - The URL pathname to check
+ * @param userRole - The user's role, or null if not authenticated
+ * @returns AuthorizationResult with authorized status and reason
+ */
+export function checkAuthorization(
+  pathname: string,
+  userRole: UserRole | null
+): AuthorizationResult {
+  // 1. Public routes - always allowed
+  if (isPublicRoute(pathname)) {
+    return { authorized: true, reason: 'public' }
+  }
+
+  // 2. No user = unauthenticated
+  if (!userRole) {
+    return { authorized: false, reason: 'unauthenticated' }
+  }
+
+  // 3. Routes that only need authentication (no specific permission)
+  if (isAuthenticatedOnlyRoute(pathname)) {
+    return { authorized: true, reason: 'authenticated' }
+  }
+
+  // 4. Check route-specific permissions
+  const matched = matchRoute(pathname)
+
+  // No matching route permission = allow by default
+  // This means the route exists but has no specific permission requirement
+  if (!matched) {
+    return { authorized: true, reason: 'authenticated' }
+  }
+
+  const { permission } = matched
+  const hasPermission = canAccess(userRole, permission.action, permission.subject)
+
+  if (hasPermission) {
+    return { authorized: true }
+  }
+
+  // User doesn't have required permission
+  return {
+    authorized: false,
+    reason: 'forbidden',
+    requiredAction: permission.action,
+    requiredSubject: permission.subject,
+  }
+}

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

@@ -0,0 +1,27 @@
+// Types
+export type {
+  Subjects,
+  Actions,
+  AppAbility,
+  AuthUser,
+  UserRole,
+  RoutePermission,
+  MatchedRoute,
+} from './types'
+
+// Role definitions
+export { defineAbilitiesFor, canAccess } from './roles'
+
+// Route configuration
+export { routePermissions, publicRoutes, authenticatedOnlyRoutes } from './routeMap'
+
+// Route matching
+export {
+  matchRoute,
+  isPublicRoute,
+  isAuthenticatedOnlyRoute,
+  isProtectedRoute,
+} from './routeMatcher'
+
+// Authorization check
+export { checkAuthorization, type AuthorizationResult } from './checkAuthorization'

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

@@ -0,0 +1,75 @@
+import { AbilityBuilder, createMongoAbility } from '@casl/ability'
+import type { AppAbility, UserRole, Actions, Subjects } from './types'
+
+/**
+ * Define CASL abilities for each role
+ *
+ * Role hierarchy: admin > manager > agent > viewer
+ *
+ * @param role - The user's role
+ * @returns CASL Ability instance with permissions for that role
+ */
+export function defineAbilitiesFor(role: UserRole): AppAbility {
+  const { can, cannot, build } = new AbilityBuilder<AppAbility>(createMongoAbility)
+
+  switch (role) {
+    case 'admin':
+      // Admin has full access to everything
+      can('manage', 'all')
+      break
+
+    case 'manager':
+      // Manager can read everything
+      can('read', 'all')
+      // Manager can manage Users, Tickets, and Reports
+      can('manage', 'Users')
+      can('manage', 'Tickets')
+      can('manage', 'Reports')
+      // Manager cannot access Settings
+      cannot('manage', 'Settings')
+      break
+
+    case 'agent':
+      // Agent can read Home, Dashboard, Tickets, and Reports
+      can('read', 'Home')
+      can('read', 'Dashboard')
+      can('read', 'Tickets')
+      can('read', 'Reports')
+      // Agent can manage (CRUD) Tickets
+      can('manage', 'Tickets')
+      // Agent cannot access Users or Settings
+      cannot('read', 'Users')
+      cannot('read', 'Settings')
+      break
+
+    case 'viewer':
+      // Viewer can read Home, Dashboard and Reports
+      can('read', 'Home')
+      can('read', 'Dashboard')
+      can('read', 'Reports')
+      // Viewer cannot access anything else
+      cannot('read', 'Users')
+      cannot('read', 'Tickets')
+      cannot('read', 'Settings')
+      break
+
+    default:
+      // Unknown roles get no permissions
+      break
+  }
+
+  return build()
+}
+
+/**
+ * Quick check if a role can access a subject with given action
+ *
+ * @param role - User's role
+ * @param action - The action to check
+ * @param subject - The subject to check against
+ * @returns true if the role has permission
+ */
+export function canAccess(role: UserRole, action: Actions, subject: Subjects): boolean {
+  const ability = defineAbilitiesFor(role)
+  return ability.can(action, subject)
+}

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

@@ -0,0 +1,35 @@
+import type { RoutePermission } from './types'
+
+/**
+ * Centralized route to permission mapping
+ *
+ * Pattern types supported:
+ * - Exact: '/dashboard' matches only '/dashboard'
+ * - Dynamic: '/users/[id]' matches '/users/123', '/users/abc'
+ * - Wildcard: '/settings/*' matches '/settings/profile', '/settings/a/b/c'
+ *
+ * To add a new protected route:
+ * 1. Add an entry here with the pattern, action, and subject
+ * 2. That's it - middleware handles the rest
+ */
+export const routePermissions: RoutePermission[] = [
+  // Home - accessible to all authenticated users
+  {
+    pattern: '/home',
+    action: 'read',
+    subject: 'Home',
+    description: 'Home page for authenticated users'
+  }
+]
+
+/**
+ * Public routes that don't require authentication
+ * These bypass all auth checks
+ */
+export const publicRoutes: string[] = ['/', '/login', '/signup', '/forgot-password', '/reset-password', '/unauthorized']
+
+/**
+ * Routes that only require authentication (any role can access)
+ * No specific permission check needed
+ */
+export const authenticatedOnlyRoutes: string[] = ['/home']

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

@@ -0,0 +1,117 @@
+import type { MatchedRoute } from './types'
+import { routePermissions, publicRoutes, authenticatedOnlyRoutes } from './routeMap'
+
+/**
+ * Convert route pattern to regex for matching
+ *
+ * Handles:
+ * - [param] → named capture group (?<param>[^/]+)
+ * - /* → wildcard match (?:/.*)?
+ * - Escapes other regex special characters
+ */
+function patternToRegex(pattern: string): RegExp {
+  const regexStr = pattern
+    // Escape special regex characters (except [ ] and *)
+    .replace(/[.+?^${}()|\\]/g, '\\$&')
+    // Convert [param] to named capture group
+    .replace(/\[(\w+)\]/g, '(?<$1>[^/]+)')
+    // Convert /* wildcard to match anything after
+    .replace(/\/\*$/, '(?:/.*)?')
+
+  return new RegExp(`^${regexStr}$`)
+}
+
+/**
+ * Calculate match priority score
+ * Higher score = more specific match
+ *
+ * - Exact matches get highest priority
+ * - Dynamic segments get medium priority
+ * - Wildcards get lowest priority
+ */
+function getMatchScore(pattern: string): number {
+  let score = 100
+
+  // Count dynamic segments (lower score)
+  const dynamicCount = (pattern.match(/\[\w+\]/g) || []).length
+  score -= dynamicCount * 10
+
+  // Wildcard patterns get lowest score
+  if (pattern.endsWith('/*')) {
+    score -= 50
+  }
+
+  return score
+}
+
+/**
+ * Match a pathname against all route patterns
+ *
+ * @param pathname - The URL pathname to match
+ * @returns MatchedRoute with permission and params, or null if no match
+ */
+export function matchRoute(pathname: string): MatchedRoute | null {
+  const matches: Array<{ route: MatchedRoute; score: number }> = []
+
+  for (const permission of routePermissions) {
+    const regex = patternToRegex(permission.pattern)
+    const match = pathname.match(regex)
+
+    if (match) {
+      matches.push({
+        route: {
+          permission,
+          params: match.groups || {},
+        },
+        score: getMatchScore(permission.pattern),
+      })
+    }
+  }
+
+  // Return highest scoring match (most specific)
+  if (matches.length > 0) {
+    matches.sort((a, b) => b.score - a.score)
+    return matches[0].route
+  }
+
+  return null
+}
+
+/**
+ * Check if a route is public (no auth required)
+ *
+ * @param pathname - The URL pathname to check
+ * @returns true if the route is public
+ */
+export function isPublicRoute(pathname: string): boolean {
+  return publicRoutes.some((route) => {
+    // Exact match
+    if (pathname === route) return true
+
+    // Check if pathname starts with public route (for sub-paths)
+    // e.g., /about matches /about/team
+    if (pathname.startsWith(route + '/')) return true
+
+    return false
+  })
+}
+
+/**
+ * Check if route only requires authentication (no specific permission)
+ *
+ * @param pathname - The URL pathname to check
+ * @returns true if route just needs auth, no specific permission
+ */
+export function isAuthenticatedOnlyRoute(pathname: string): boolean {
+  return authenticatedOnlyRoutes.includes(pathname)
+}
+
+/**
+ * Check if route is protected (has specific permission requirements)
+ *
+ * @param pathname - The URL pathname to check
+ * @returns true if route has permission requirements
+ */
+export function isProtectedRoute(pathname: string): boolean {
+  return matchRoute(pathname) !== null
+}