create-fullstack-scaffold 0.1.0

package/template/src/server/middleware/__tests__/permission.test.ts

@@ -0,0 +1,312 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { Hono } from 'hono'
+import { permissionMiddleware } from '../permission'
+
+vi.mock('@server/utils/auth', () => ({
+  getAuthUser: vi.fn(),
+}))
+
+vi.mock('@server/module-permission/services/permission-service-impl', () => ({
+  permissionService: {
+    hasPermission: vi.fn(),
+  },
+}))
+
+vi.mock('@server/module-permission/services/role-service', () => ({
+  roleService: {
+    getUserRoles: vi.fn(),
+  },
+}))
+
+vi.mock('@server/utils/logger', () => ({
+  logger: {
+    api: () => ({
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    }),
+  },
+}))
+
+import { getAuthUser } from '@server/utils/auth'
+import { permissionService } from '@server/module-permission/services/permission-service-impl'
+import { roleService } from '@server/module-permission/services/role-service'
+
+const mockGetAuthUser = vi.mocked(getAuthUser)
+const mockHasPermission = vi.mocked(permissionService.hasPermission)
+const mockGetUserRoles = vi.mocked(roleService.getUserRoles)
+
+describe('permissionMiddleware', () => {
+  let app: Hono
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    app = new Hono()
+    app.use('*', permissionMiddleware())
+    app.get('/api/admin/users', c => c.json({ success: true }))
+    app.post('/api/admin/users', c => c.json({ success: true }))
+    app.put('/api/admin/users/:id', c => c.json({ success: true }))
+    app.delete('/api/admin/users/:id', c => c.json({ success: true }))
+    app.get('/api/content', c => c.json({ success: true }))
+    app.post('/api/content', c => c.json({ success: true }))
+    app.put('/api/content/:id', c => c.json({ success: true }))
+    app.delete('/api/content/:id', c => c.json({ success: true }))
+    app.get('/api/admin/settings', c => c.json({ success: true }))
+    app.put('/api/admin/settings', c => c.json({ success: true }))
+    app.get('/api/admin/logs', c => c.json({ success: true }))
+    app.post('/api/admin/login', c => c.json({ success: true }))
+    app.post('/api/admin/register', c => c.json({ success: true }))
+    app.get('/api/permissions', c => c.json({ success: true }))
+    app.get('/api/permissions/roles', c => c.json({ success: true }))
+    app.get('/api/permissions/categories', c => c.json({ success: true }))
+    app.get('/api/permissions/role-labels', c => c.json({ success: true }))
+    app.get('/api/permissions/permission-labels', c => c.json({ success: true }))
+    app.get('/api/permissions/menu-config', c => c.json({ success: true }))
+    app.get('/api/permissions/page-permissions', c => c.json({ success: true }))
+  })
+
+  describe('public routes', () => {
+    it('should allow POST /api/admin/login without auth', async () => {
+      mockGetAuthUser.mockReturnValue(undefined as never)
+      const res = await app.request('/api/admin/login', { method: 'POST' })
+      expect(res.status).toBe(200)
+    })
+
+    it('should allow POST /api/admin/register without auth', async () => {
+      mockGetAuthUser.mockReturnValue(undefined as never)
+      const res = await app.request('/api/admin/register', { method: 'POST' })
+      expect(res.status).toBe(200)
+    })
+
+    it('should allow GET /api/permissions without auth', async () => {
+      mockGetAuthUser.mockReturnValue(undefined as never)
+      const res = await app.request('/api/permissions')
+      expect(res.status).toBe(200)
+    })
+
+    it('should allow GET /api/permissions/roles without auth', async () => {
+      mockGetAuthUser.mockReturnValue(undefined as never)
+      const res = await app.request('/api/permissions/roles')
+      expect(res.status).toBe(200)
+    })
+
+    it('should allow GET /api/permissions/categories without auth', async () => {
+      mockGetAuthUser.mockReturnValue(undefined as never)
+      const res = await app.request('/api/permissions/categories')
+      expect(res.status).toBe(200)
+    })
+
+    it('should allow GET /api/permissions/role-labels without auth', async () => {
+      mockGetAuthUser.mockReturnValue(undefined as never)
+      const res = await app.request('/api/permissions/role-labels')
+      expect(res.status).toBe(200)
+    })
+
+    it('should allow GET /api/permissions/permission-labels without auth', async () => {
+      mockGetAuthUser.mockReturnValue(undefined as never)
+      const res = await app.request('/api/permissions/permission-labels')
+      expect(res.status).toBe(200)
+    })
+
+    it('should allow GET /api/permissions/menu-config without auth', async () => {
+      mockGetAuthUser.mockReturnValue(undefined as never)
+      const res = await app.request('/api/permissions/menu-config')
+      expect(res.status).toBe(200)
+    })
+
+    it('should allow GET /api/permissions/page-permissions without auth', async () => {
+      mockGetAuthUser.mockReturnValue(undefined as never)
+      const res = await app.request('/api/permissions/page-permissions')
+      expect(res.status).toBe(200)
+    })
+  })
+
+  describe('unmatched routes', () => {
+    it('should allow unmatched routes through', async () => {
+      app.get('/api/todos', c => c.json({ success: true }))
+      mockGetAuthUser.mockReturnValue(undefined as never)
+      const res = await app.request('/api/todos')
+      expect(res.status).toBe(200)
+    })
+  })
+
+  describe('unauthenticated requests to protected routes', () => {
+    it('should pass through when no user (let auth middleware handle)', async () => {
+      mockGetAuthUser.mockReturnValue(undefined as never)
+      const res = await app.request('/api/admin/users')
+      expect(res.status).toBe(200)
+    })
+  })
+
+  describe('super admin bypass', () => {
+    it('should allow super admin access to any protected route', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '1' } as never)
+      mockGetUserRoles.mockResolvedValue([{ code: 'super_admin' }] as never)
+      mockHasPermission.mockResolvedValue(false)
+
+      const res = await app.request('/api/admin/users')
+      expect(res.status).toBe(200)
+    })
+  })
+
+  describe('permission-based access', () => {
+    it('should allow user with correct permission (user:view)', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '2' } as never)
+      mockGetUserRoles.mockResolvedValue([{ code: 'user' }] as never)
+      mockHasPermission.mockResolvedValue(true)
+
+      const res = await app.request('/api/admin/users')
+      expect(res.status).toBe(200)
+      expect(mockHasPermission).toHaveBeenCalledWith('2', 'user:view')
+    })
+
+    it('should allow user with correct permission (content:view)', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '2' } as never)
+      mockGetUserRoles.mockResolvedValue([{ code: 'user' }] as never)
+      mockHasPermission.mockResolvedValue(true)
+
+      const res = await app.request('/api/content')
+      expect(res.status).toBe(200)
+      expect(mockHasPermission).toHaveBeenCalledWith('2', 'content:view')
+    })
+
+    it('should allow user with correct permission (system:settings)', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '2' } as never)
+      mockGetUserRoles.mockResolvedValue([{ code: 'user' }] as never)
+      mockHasPermission.mockResolvedValue(true)
+
+      const res = await app.request('/api/admin/settings')
+      expect(res.status).toBe(200)
+      expect(mockHasPermission).toHaveBeenCalledWith('2', 'system:settings')
+    })
+
+    it('should allow user with correct permission (system:logs)', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '2' } as never)
+      mockGetUserRoles.mockResolvedValue([{ code: 'user' }] as never)
+      mockHasPermission.mockResolvedValue(true)
+
+      const res = await app.request('/api/admin/logs')
+      expect(res.status).toBe(200)
+      expect(mockHasPermission).toHaveBeenCalledWith('2', 'system:logs')
+    })
+
+    it('should block user without required permission', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '3' } as never)
+      mockGetUserRoles.mockResolvedValue([{ code: 'user' }] as never)
+      mockHasPermission.mockResolvedValue(false)
+
+      const res = await app.request('/api/admin/users')
+      expect(res.status).toBe(403)
+      const body = (await res.json()) as { success: boolean; error: string }
+      expect(body.success).toBe(false)
+      expect(body.error).toContain('Forbidden')
+    })
+  })
+
+  describe('parameterized routes', () => {
+    it('should match PUT /api/admin/users/:id with user:edit permission', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '2' } as never)
+      mockGetUserRoles.mockResolvedValue([{ code: 'user' }] as never)
+      mockHasPermission.mockResolvedValue(true)
+
+      const res = await app.request('/api/admin/users/123', { method: 'PUT' })
+      expect(res.status).toBe(200)
+      expect(mockHasPermission).toHaveBeenCalledWith('2', 'user:edit')
+    })
+
+    it('should match DELETE /api/admin/users/:id with user:delete permission', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '2' } as never)
+      mockGetUserRoles.mockResolvedValue([{ code: 'user' }] as never)
+      mockHasPermission.mockResolvedValue(true)
+
+      const res = await app.request('/api/admin/users/456', { method: 'DELETE' })
+      expect(res.status).toBe(200)
+      expect(mockHasPermission).toHaveBeenCalledWith('2', 'user:delete')
+    })
+
+    it('should match PUT /api/content/:id with content:edit permission', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '2' } as never)
+      mockGetUserRoles.mockResolvedValue([{ code: 'user' }] as never)
+      mockHasPermission.mockResolvedValue(true)
+
+      const res = await app.request('/api/content/789', { method: 'PUT' })
+      expect(res.status).toBe(200)
+      expect(mockHasPermission).toHaveBeenCalledWith('2', 'content:edit')
+    })
+
+    it('should match DELETE /api/content/:id with content:delete permission', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '2' } as never)
+      mockGetUserRoles.mockResolvedValue([{ code: 'user' }] as never)
+      mockHasPermission.mockResolvedValue(true)
+
+      const res = await app.request('/api/content/999', { method: 'DELETE' })
+      expect(res.status).toBe(200)
+      expect(mockHasPermission).toHaveBeenCalledWith('2', 'content:delete')
+    })
+
+    it('should not match wrong method for parameterized route', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '2' } as never)
+      mockGetUserRoles.mockResolvedValue([{ code: 'user' }] as never)
+
+      app.patch('/api/admin/users/:id', c => c.json({ success: true }))
+      const res = await app.request('/api/admin/users/123', { method: 'PATCH' })
+      expect(res.status).toBe(200)
+      expect(mockHasPermission).not.toHaveBeenCalled()
+    })
+
+    it('should not match wrong path segment length', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '2' } as never)
+      mockGetUserRoles.mockResolvedValue([{ code: 'user' }] as never)
+
+      app.get('/api/admin/users/extra/segment', c => c.json({ success: true }))
+      const res = await app.request('/api/admin/users/extra/segment')
+      expect(res.status).toBe(200)
+      expect(mockHasPermission).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('POST routes with permissions', () => {
+    it('should match POST /api/admin/users with user:create permission', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '2' } as never)
+      mockGetUserRoles.mockResolvedValue([{ code: 'user' }] as never)
+      mockHasPermission.mockResolvedValue(true)
+
+      const res = await app.request('/api/admin/users', { method: 'POST' })
+      expect(res.status).toBe(200)
+      expect(mockHasPermission).toHaveBeenCalledWith('2', 'user:create')
+    })
+
+    it('should match POST /api/content with content:create permission', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '2' } as never)
+      mockGetUserRoles.mockResolvedValue([{ code: 'user' }] as never)
+      mockHasPermission.mockResolvedValue(true)
+
+      const res = await app.request('/api/content', { method: 'POST' })
+      expect(res.status).toBe(200)
+      expect(mockHasPermission).toHaveBeenCalledWith('2', 'content:create')
+    })
+
+    it('should match PUT /api/admin/settings with system:settings permission', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '2' } as never)
+      mockGetUserRoles.mockResolvedValue([{ code: 'user' }] as never)
+      mockHasPermission.mockResolvedValue(true)
+
+      const res = await app.request('/api/admin/settings', { method: 'PUT' })
+      expect(res.status).toBe(200)
+      expect(mockHasPermission).toHaveBeenCalledWith('2', 'system:settings')
+    })
+  })
+
+  describe('route with no required permissions', () => {
+    it('should allow access when route has empty permissions array', async () => {
+      mockGetAuthUser.mockReturnValue({ id: '2' } as never)
+
+      const testApp = new Hono()
+      testApp.use('*', permissionMiddleware())
+      testApp.get('/api/custom', c => c.json({ success: true }))
+
+      const res = await testApp.request('/api/custom')
+      expect(res.status).toBe(200)
+    })
+  })
+})

package/template/src/server/middleware/audit-log.ts

@@ -0,0 +1,101 @@
+import type { MiddlewareHandler } from 'hono'
+import { getAuthUser } from '../utils/auth'
+import { auditLogService } from '../module-permission/services/audit-log-service'
+import { logger } from '../utils/logger'
+import {
+  PATH_TO_RESOURCE_TYPE,
+  ACTION_TYPES,
+  type ResourceType,
+  type ActionType,
+} from '@shared/constants'
+
+const log = logger.api()
+
+export function auditLogMiddleware(): MiddlewareHandler {
+  return async (c, next) => {
+    const startTime = Date.now()
+    const path = c.req.path
+    const method = c.req.method
+
+    await next()
+
+    const duration = Date.now() - startTime
+    const status = c.res.status
+
+    log.info(
+      {
+        path,
+        method,
+        status,
+        duration,
+      },
+      'Audit log middleware checking'
+    )
+
+    if (!path.startsWith('/api/') || path.startsWith('/api/permissions/')) {
+      log.info({ path }, 'Skipping: not API or public API')
+      return
+    }
+
+    if (!['POST', 'PUT', 'DELETE', 'PATCH'].includes(method)) {
+      log.info({ method }, 'Skipping: not write operation')
+      return
+    }
+
+    if (status < 200 || status >= 300) {
+      log.info({ status }, 'Skipping: not successful operation')
+      return
+    }
+
+    const user = getAuthUser(c)
+    if (!user) {
+      log.info({ path }, 'Skipping: no user')
+      return
+    }
+
+    let action: ActionType = ACTION_TYPES.CREATE
+    if (method === 'POST') {
+      action = ACTION_TYPES.CREATE
+    } else if (method === 'PUT' || method === 'PATCH') {
+      action = ACTION_TYPES.UPDATE
+    } else if (method === 'DELETE') {
+      action = ACTION_TYPES.DELETE
+    }
+
+    const pathParts = path.split('/').filter(Boolean)
+    let resourceType: ResourceType = 'user' as ResourceType
+    if (pathParts.length >= 2) {
+      const pathSegment = pathParts[1]
+      resourceType = PATH_TO_RESOURCE_TYPE[pathSegment] || ('unknown' as ResourceType)
+    }
+
+    try {
+      await auditLogService.create({
+        id: `audit_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+        userId: user.id,
+        action,
+        resourceType,
+        resourceId: pathParts.length >= 3 ? pathParts[2] : null,
+        oldValue: null,
+        newValue: null,
+        ipAddress: c.req.header('x-forwarded-for') || c.req.header('x-real-ip') || null,
+        userAgent: c.req.header('user-agent') || null,
+      })
+
+      log.info(
+        {
+          userId: user.id,
+          action,
+          resourceType,
+          path,
+          method,
+          status,
+          duration,
+        },
+        'Audit log created'
+      )
+    } catch (error) {
+      log.error({ error, path, method }, 'Failed to create audit log')
+    }
+  }
+}

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

@@ -0,0 +1,235 @@
+import type { MiddlewareHandler } from 'hono'
+import jwt from 'jsonwebtoken'
+import { createModuleLoggerSync } from '../utils/logger'
+import { Role, Permission, getPermissionsByRole } from '@shared/modules/permission'
+import { AuthenticationError, AuthorizationError } from '../utils/app-error'
+
+export type UserRole = Role
+
+export interface AuthUser {
+  id: string
+  username: string
+  email: string
+  role: UserRole
+  avatar?: string
+  permissions: Permission[]
+}
+
+export interface AuthMiddlewareOptions {
+  secretKey?: string
+  requiredRole?: UserRole
+  requiredPermissions?: Permission[]
+}
+
+declare module 'hono' {
+  interface ContextVariableMap {
+    authUser: AuthUser
+  }
+}
+
+const defaultSecretKey = 'dev-secret-key-change-in-production'
+
+const secretKey = process.env.AUTH_SECRET_KEY || defaultSecretKey
+
+if (secretKey === defaultSecretKey && process.env.NODE_ENV === 'production') {
+  console.error(
+    '⚠️  SECURITY WARNING: AUTH_SECRET_KEY is using the default value in production!\n' +
+      '   Please set a strong AUTH_SECRET_KEY environment variable.\n' +
+      '   Dev tokens should NEVER be used in production.'
+  )
+}
+
+const isDevTokensEnabled = (): boolean => {
+  return process.env.ENABLE_DEV_TOKENS === 'true' && process.env.NODE_ENV !== 'production'
+}
+
+if (isDevTokensEnabled()) {
+  console.warn('⚠️  WARNING: Dev tokens are ENABLED. Do not use in production!')
+}
+
+function extractToken(authHeader: string | undefined): string | null {
+  if (!authHeader) return null
+  if (!authHeader.startsWith('Bearer ')) return null
+  return authHeader.slice(7)
+}
+
+function verifyDevToken(token: string): AuthUser | null {
+  if (token === 'admin-token' || token === 'super-admin-token') {
+    return {
+      id: 'super-admin-1',
+      username: 'superadmin',
+      email: 'superadmin@example.com',
+      role: Role.SUPER_ADMIN,
+      permissions: getPermissionsByRole(Role.SUPER_ADMIN),
+    }
+  }
+  if (token === 'customer-service-token') {
+    return {
+      id: 'customer-service-1',
+      username: 'customerservice',
+      email: 'cs@example.com',
+      role: Role.CUSTOMER_SERVICE,
+      permissions: getPermissionsByRole(Role.CUSTOMER_SERVICE),
+    }
+  }
+  if (token === 'user-token') {
+    return {
+      id: 'user-1',
+      username: 'user',
+      email: 'user@example.com',
+      role: Role.USER,
+      permissions: getPermissionsByRole(Role.USER),
+    }
+  }
+  if (token.startsWith('test-super-admin-')) {
+    return {
+      id: token,
+      username: `superadmin-${token}`,
+      email: `superadmin-${token}@example.com`,
+      role: Role.SUPER_ADMIN,
+      permissions: getPermissionsByRole(Role.SUPER_ADMIN),
+    }
+  }
+  if (token.startsWith('test-customer-service-')) {
+    return {
+      id: token,
+      username: `cs-${token}`,
+      email: `cs-${token}@example.com`,
+      role: Role.CUSTOMER_SERVICE,
+      permissions: getPermissionsByRole(Role.CUSTOMER_SERVICE),
+    }
+  }
+  if (token.startsWith('test-user-')) {
+    return {
+      id: token,
+      username: `user-${token}`,
+      email: `user-${token}@example.com`,
+      role: Role.USER,
+      permissions: getPermissionsByRole(Role.USER),
+    }
+  }
+  return null
+}
+
+function verifyToken(token: string, key: string): AuthUser | null {
+  if (key === defaultSecretKey && isDevTokensEnabled()) {
+    const devUser = verifyDevToken(token)
+    if (devUser) {
+      const log = createModuleLoggerSync('auth')
+      log.warn(
+        { userId: devUser.id, role: devUser.role },
+        'DEV TOKEN USED - This should not appear in production!'
+      )
+      return devUser
+    }
+  }
+
+  if (key !== defaultSecretKey) {
+    try {
+      const decoded = jwt.verify(token, key) as {
+        userId: string
+        role: string
+        username: string
+        email: string
+      }
+      return {
+        id: decoded.userId,
+        username: decoded.username,
+        email: decoded.email,
+        role: decoded.role as UserRole,
+        permissions: getPermissionsByRole(decoded.role as UserRole),
+      }
+    } catch {
+      return null
+    }
+  }
+
+  return null
+}
+
+export function authMiddleware(options: AuthMiddlewareOptions = {}): MiddlewareHandler {
+  const key = options.secretKey ?? secretKey
+  const log = createModuleLoggerSync('auth')
+
+  return async (c, next) => {
+    const authHeader = c.req.header('Authorization')
+    const token = extractToken(authHeader)
+
+    if (!token) {
+      log.warn({ path: c.req.path, method: c.req.method }, 'Missing auth token')
+      throw AuthenticationError.tokenMissing()
+    }
+
+    const user = verifyToken(token, key)
+
+    if (!user) {
+      log.warn({ path: c.req.path, method: c.req.method }, 'Invalid auth token')
+      throw AuthenticationError.tokenInvalid()
+    }
+
+    log.info({ userId: user.id, role: user.role, path: c.req.path }, 'User authenticated')
+
+    if (options.requiredRole) {
+      const roleHierarchy = {
+        [Role.SUPER_ADMIN]: 3,
+        [Role.CUSTOMER_SERVICE]: 2,
+        [Role.USER]: 1,
+      }
+      const userLevel = roleHierarchy[user.role]
+      const requiredLevel = roleHierarchy[options.requiredRole]
+
+      if (userLevel < requiredLevel) {
+        log.warn(
+          {
+            path: c.req.path,
+            method: c.req.method,
+            userRole: user.role,
+            requiredRole: options.requiredRole,
+          },
+          'Insufficient role'
+        )
+        throw AuthorizationError.insufficientRole(user.role, options.requiredRole)
+      }
+    }
+
+    if (options.requiredPermissions && options.requiredPermissions.length > 0) {
+      const { permissionService } =
+        await import('../module-permission/services/permission-service-impl')
+
+      for (const requiredPermission of options.requiredPermissions) {
+        const hasPermission = await permissionService.hasPermission(
+          user.id,
+          requiredPermission,
+          user.role
+        )
+        if (!hasPermission) {
+          log.warn(
+            {
+              path: c.req.path,
+              method: c.req.method,
+              userId: user.id,
+              requiredPermission,
+            },
+            'Insufficient permission'
+          )
+          throw AuthorizationError.permissionDenied(requiredPermission)
+        }
+      }
+    }
+
+    c.set('authUser', user)
+    await next()
+  }
+}
+
+export function requireSuperAdminMiddleware(): MiddlewareHandler {
+  return authMiddleware({ requiredRole: Role.SUPER_ADMIN })
+}
+
+export function requireCustomerServiceMiddleware(): MiddlewareHandler {
+  return authMiddleware({ requiredRole: Role.CUSTOMER_SERVICE })
+}
+
+export function requirePermissionsMiddleware(...permissions: Permission[]): MiddlewareHandler {
+  return authMiddleware({ requiredPermissions: permissions })
+}