@etus/bhono-app 0.1.1

package/templates/base/src/server/auth/__tests__/guards.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect } from 'vitest'
+import { Hono } from 'hono'
+import { requireRole, requirePermission } from '../guards'
+import type { HonoEnv } from '../../types'
+
+describe('guards', () => {
+  describe('requireRole', () => {
+    it('should throw 401 when user is not authenticated', async () => {
+      const app = new Hono<HonoEnv>()
+      app.use('*', requireRole('ADMIN'))
+      app.get('/', (c) => c.json({ ok: true }))
+
+      const res = await app.request('/')
+      expect(res.status).toBe(401)
+    })
+
+    it('should allow access when user is system admin', async () => {
+      const app = new Hono<HonoEnv>()
+      app.use('*', (c, next) => {
+        c.set('user', { id: 'test-id', email: 'test@test.com', name: 'Test' } as any)
+        c.set('isSystemAdminAccess', true)
+        return next()
+      })
+      app.use('*', requireRole('ADMIN'))
+      app.get('/', (c) => c.json({ ok: true }))
+
+      const res = await app.request('/')
+      expect(res.status).toBe(200)
+    })
+
+    it('should throw 403 when user has no role assigned', async () => {
+      const app = new Hono<HonoEnv>()
+      app.use('*', (c, next) => {
+        c.set('user', { id: 'test-id', email: 'test@test.com', name: 'Test' } as any)
+        c.set('isSystemAdminAccess', false)
+        c.set('userRole', undefined)
+        return next()
+      })
+      app.use('*', requireRole('ADMIN'))
+      app.get('/', (c) => c.json({ ok: true }))
+
+      const res = await app.request('/')
+      expect(res.status).toBe(403)
+    })
+
+    it('should throw 403 when user has insufficient role', async () => {
+      const app = new Hono<HonoEnv>()
+      app.use('*', (c, next) => {
+        c.set('user', { id: 'test-id', email: 'test@test.com', name: 'Test' } as any)
+        c.set('isSystemAdminAccess', false)
+        c.set('userRole', 'VIEWER')
+        return next()
+      })
+      app.use('*', requireRole('ADMIN'))
+      app.get('/', (c) => c.json({ ok: true }))
+
+      const res = await app.request('/')
+      expect(res.status).toBe(403)
+    })
+
+    it('should allow access when user has sufficient role', async () => {
+      const app = new Hono<HonoEnv>()
+      app.use('*', (c, next) => {
+        c.set('user', { id: 'test-id', email: 'test@test.com', name: 'Test' } as any)
+        c.set('isSystemAdminAccess', false)
+        c.set('userRole', 'ADMIN')
+        return next()
+      })
+      app.use('*', requireRole('ADMIN'))
+      app.get('/', (c) => c.json({ ok: true }))
+
+      const res = await app.request('/')
+      expect(res.status).toBe(200)
+    })
+
+    it('should allow access with additional roles', async () => {
+      const app = new Hono<HonoEnv>()
+      app.use('*', (c, next) => {
+        c.set('user', { id: 'test-id', email: 'test@test.com', name: 'Test' } as any)
+        c.set('isSystemAdminAccess', false)
+        c.set('userRole', 'BILLING')
+        return next()
+      })
+      app.use('*', requireRole('EDITOR', ['BILLING']))
+      app.get('/', (c) => c.json({ ok: true }))
+
+      const res = await app.request('/')
+      expect(res.status).toBe(200)
+    })
+  })
+
+  describe('requirePermission', () => {
+    it('should throw 401 when user is not authenticated', async () => {
+      const app = new Hono<HonoEnv>()
+      app.use('*', requirePermission('accounts:manage'))
+      app.get('/', (c) => c.json({ ok: true }))
+
+      const res = await app.request('/')
+      expect(res.status).toBe(401)
+    })
+
+    it('should allow access when user is system admin', async () => {
+      const app = new Hono<HonoEnv>()
+      app.use('*', (c, next) => {
+        c.set('user', { id: 'test-id', email: 'test@test.com', name: 'Test' } as any)
+        c.set('isSystemAdminAccess', true)
+        return next()
+      })
+      app.use('*', requirePermission('accounts:manage'))
+      app.get('/', (c) => c.json({ ok: true }))
+
+      const res = await app.request('/')
+      expect(res.status).toBe(200)
+    })
+
+    it('should throw 403 when user has no role assigned', async () => {
+      const app = new Hono<HonoEnv>()
+      app.use('*', (c, next) => {
+        c.set('user', { id: 'test-id', email: 'test@test.com', name: 'Test' } as any)
+        c.set('isSystemAdminAccess', false)
+        c.set('userRole', undefined)
+        return next()
+      })
+      app.use('*', requirePermission('accounts:manage'))
+      app.get('/', (c) => c.json({ ok: true }))
+
+      const res = await app.request('/')
+      expect(res.status).toBe(403)
+    })
+
+    it('should throw 403 when user lacks permission', async () => {
+      const app = new Hono<HonoEnv>()
+      app.use('*', (c, next) => {
+        c.set('user', { id: 'test-id', email: 'test@test.com', name: 'Test' } as any)
+        c.set('isSystemAdminAccess', false)
+        c.set('userRole', 'VIEWER')
+        return next()
+      })
+      app.use('*', requirePermission('accounts:manage'))
+      app.get('/', (c) => c.json({ ok: true }))
+
+      const res = await app.request('/')
+      expect(res.status).toBe(403)
+    })
+
+    it('should allow access when user has permission via role', async () => {
+      const app = new Hono<HonoEnv>()
+      app.use('*', (c, next) => {
+        c.set('user', { id: 'test-id', email: 'test@test.com', name: 'Test' } as any)
+        c.set('isSystemAdminAccess', false)
+        c.set('userRole', 'ADMIN')
+        return next()
+      })
+      // ADMIN has VIEW_ALL_USERS permission
+      app.use('*', requirePermission('VIEW_ALL_USERS'))
+      app.get('/', (c) => c.json({ ok: true }))
+
+      const res = await app.request('/')
+      expect(res.status).toBe(200)
+    })
+  })
+})

package/templates/base/src/server/auth/guards.ts

@@ -0,0 +1,92 @@
+// src/auth/guards.ts
+import { createMiddleware } from 'hono/factory'
+import { HTTPException } from 'hono/http-exception'
+import type { HonoEnv } from '../types'
+import type { Role } from './roles'
+import type { Permission } from './permissions'
+import { hasMinimumRole } from './roles'
+import { hasPermission } from './permissions'
+
+/**
+ * Middleware factory that requires a minimum role level.
+ * Users with the minimum role or higher in the hierarchy can access the route.
+ * Super-admins bypass all role checks.
+ *
+ * @param minRole - The minimum role required to access the route
+ * @param additionalRoles - Optional array of non-hierarchical roles that also grant access
+ */
+export const requireRole = (minRole: Role, additionalRoles: Role[] = []) => {
+  return createMiddleware<HonoEnv>(async (c, next) => {
+    const user = c.get('user')
+
+    if (!user) {
+      throw new HTTPException(401, {
+        message: 'Unauthorized: User not authenticated',
+      })
+    }
+
+    // Super-admin bypass
+    if (c.get('isSystemAdminAccess')) {
+      await next()
+      return
+    }
+
+    const userRole = c.get('userRole')
+
+    if (!userRole) {
+      throw new HTTPException(403, {
+        message: 'Forbidden: No role assigned for this account',
+      })
+    }
+
+    // Check if user has minimum role (userRole is guaranteed to be Role here)
+    if (!hasMinimumRole(userRole, minRole, additionalRoles)) {
+      throw new HTTPException(403, {
+        message: `Forbidden: Requires ${minRole} role or higher`,
+      })
+    }
+
+    await next()
+  })
+}
+
+/**
+ * Middleware factory that requires a specific permission.
+ * Super-admins bypass all permission checks.
+ *
+ * @param permission - The permission required to access the route
+ */
+export const requirePermission = (permission: Permission) => {
+  return createMiddleware<HonoEnv>(async (c, next) => {
+    const user = c.get('user')
+
+    if (!user) {
+      throw new HTTPException(401, {
+        message: 'Unauthorized: User not authenticated',
+      })
+    }
+
+    // Super-admin bypass
+    if (c.get('isSystemAdminAccess')) {
+      await next()
+      return
+    }
+
+    const userRole = c.get('userRole')
+
+    if (!userRole) {
+      throw new HTTPException(403, {
+        message: 'Forbidden: No role assigned for this account',
+      })
+    }
+
+    // Check if user's role has the required permission (userRole is guaranteed to be Role here)
+    if (!hasPermission(userRole, permission)) {
+      throw new HTTPException(403, {
+        message: `Forbidden: Requires ${permission} permission`,
+      })
+    }
+
+    await next()
+  })
+}

package/templates/base/src/server/auth/permissions.test.ts

@@ -0,0 +1,45 @@
+// src/auth/permissions.test.ts
+import { describe, it, expect } from 'vitest'
+import { Permission, hasPermission, hasAnyPermission, hasAllPermissions } from './permissions'
+
+describe('permissions', () => {
+  describe('hasPermission', () => {
+    it('ADMIN should have MANAGE_TENANT_SETTINGS', () => {
+      // Note: MANAGE_SYSTEM_SETTINGS requires isSuperAdmin flag, not ADMIN role
+      expect(hasPermission('ADMIN', 'MANAGE_TENANT_SETTINGS')).toBe(true)
+    })
+
+    it('ADMIN should NOT have MANAGE_SYSTEM_SETTINGS (requires isSuperAdmin)', () => {
+      expect(hasPermission('ADMIN', 'MANAGE_SYSTEM_SETTINGS')).toBe(false)
+    })
+
+    it('VIEWER should have VIEW_PUBLISHED_CONTENT', () => {
+      // Note: VIEWER only has VIEW_PUBLISHED_CONTENT, not full VIEW_CONTENT
+      expect(hasPermission('VIEWER', 'VIEW_PUBLISHED_CONTENT')).toBe(true)
+    })
+
+    it('BILLING should have MANAGE_BILLING', () => {
+      expect(hasPermission('BILLING', 'MANAGE_BILLING')).toBe(true)
+    })
+  })
+
+  describe('hasAnyPermission', () => {
+    it('should return true if user has any of the permissions', () => {
+      expect(hasAnyPermission('EDITOR', ['MANAGE_BILLING', 'CREATE_CONTENT'])).toBe(true)
+    })
+
+    it('should return false if user has none of the permissions', () => {
+      expect(hasAnyPermission('VIEWER', ['MANAGE_BILLING', 'CREATE_CONTENT'])).toBe(false)
+    })
+  })
+
+  describe('hasAllPermissions', () => {
+    it('should return true if user has all permissions', () => {
+      expect(hasAllPermissions('ADMIN', ['CREATE_CONTENT', 'EDIT_ALL_CONTENT'])).toBe(true)
+    })
+
+    it('should return false if user is missing any permission', () => {
+      expect(hasAllPermissions('VIEWER', ['CREATE_CONTENT', 'VIEW_PUBLISHED_CONTENT'])).toBe(false)
+    })
+  })
+})

package/templates/base/src/server/auth/permissions.ts

@@ -0,0 +1,139 @@
+// src/auth/permissions.ts
+import type { Role } from './roles'
+
+export const Permission = {
+  // System Management
+  MANAGE_SYSTEM_SETTINGS: 'MANAGE_SYSTEM_SETTINGS',
+
+  // Tenant/Organization Management
+  MANAGE_TENANT_SETTINGS: 'MANAGE_TENANT_SETTINGS',
+
+  // User & Role Management
+  MANAGE_ALL_USERS: 'MANAGE_ALL_USERS',
+  MANAGE_TEAM_USERS: 'MANAGE_TEAM_USERS',
+  VIEW_ALL_USERS: 'VIEW_ALL_USERS',
+
+  // Billing & Subscription Management
+  MANAGE_BILLING: 'MANAGE_BILLING',
+  VIEW_BILLING: 'VIEW_BILLING',
+
+  // Content Creation & Management
+  CREATE_CONTENT: 'CREATE_CONTENT',
+  EDIT_OWN_CONTENT: 'EDIT_OWN_CONTENT',
+  EDIT_ALL_CONTENT: 'EDIT_ALL_CONTENT',
+  PUBLISH_CONTENT: 'PUBLISH_CONTENT',
+  UNPUBLISH_CONTENT: 'UNPUBLISH_CONTENT',
+  DELETE_CONTENT: 'DELETE_CONTENT',
+
+  // Media/Assets Management
+  MANAGE_ASSETS: 'MANAGE_ASSETS',
+
+  // Categories/Tags Management
+  MANAGE_CATEGORIES_TAGS: 'MANAGE_CATEGORIES_TAGS',
+
+  // Comments/Community Management
+  MANAGE_COMMENTS: 'MANAGE_COMMENTS',
+
+  // Content Viewing
+  VIEW_CONTENT: 'VIEW_CONTENT',
+  VIEW_OWN_CONTENT: 'VIEW_OWN_CONTENT',
+  VIEW_PUBLISHED_CONTENT: 'VIEW_PUBLISHED_CONTENT',
+
+  // Analytics & Reports
+  VIEW_ANALYTICS: 'VIEW_ANALYTICS',
+  EXPORT_REPORTS: 'EXPORT_REPORTS',
+} as const
+
+export type Permission = (typeof Permission)[keyof typeof Permission]
+
+const ROLE_PERMISSIONS: Record<Role, Permission[]> = {
+  ADMIN: [
+    // Highest account-level role (no system settings - those require isSuperAdmin flag)
+    Permission.MANAGE_TENANT_SETTINGS,
+    Permission.MANAGE_ALL_USERS,
+    Permission.MANAGE_TEAM_USERS,
+    Permission.VIEW_ALL_USERS,
+    Permission.CREATE_CONTENT,
+    Permission.EDIT_OWN_CONTENT,
+    Permission.EDIT_ALL_CONTENT,
+    Permission.PUBLISH_CONTENT,
+    Permission.UNPUBLISH_CONTENT,
+    Permission.DELETE_CONTENT,
+    Permission.MANAGE_ASSETS,
+    Permission.MANAGE_CATEGORIES_TAGS,
+    Permission.MANAGE_COMMENTS,
+    Permission.VIEW_CONTENT,
+    Permission.VIEW_OWN_CONTENT,
+    Permission.VIEW_PUBLISHED_CONTENT,
+    Permission.VIEW_ANALYTICS,
+    Permission.EXPORT_REPORTS,
+  ],
+  MANAGER: [
+    // Team & workflow management
+    Permission.MANAGE_TEAM_USERS,
+    Permission.VIEW_ALL_USERS,
+    Permission.CREATE_CONTENT,
+    Permission.EDIT_OWN_CONTENT,
+    Permission.EDIT_ALL_CONTENT,
+    Permission.PUBLISH_CONTENT,
+    Permission.UNPUBLISH_CONTENT,
+    Permission.DELETE_CONTENT,
+    Permission.MANAGE_ASSETS,
+    Permission.MANAGE_CATEGORIES_TAGS,
+    Permission.MANAGE_COMMENTS,
+    Permission.VIEW_CONTENT,
+    Permission.VIEW_OWN_CONTENT,
+    Permission.VIEW_PUBLISHED_CONTENT,
+    Permission.VIEW_ANALYTICS,
+    Permission.EXPORT_REPORTS,
+  ],
+  EDITOR: [
+    // Edit and publish any content
+    Permission.CREATE_CONTENT,
+    Permission.EDIT_OWN_CONTENT,
+    Permission.EDIT_ALL_CONTENT,
+    Permission.PUBLISH_CONTENT,
+    Permission.UNPUBLISH_CONTENT,
+    Permission.DELETE_CONTENT,
+    Permission.MANAGE_ASSETS,
+    Permission.MANAGE_CATEGORIES_TAGS,
+    Permission.MANAGE_COMMENTS,
+    Permission.VIEW_CONTENT,
+    Permission.VIEW_OWN_CONTENT,
+    Permission.VIEW_PUBLISHED_CONTENT,
+  ],
+  AUTHOR: [
+    // Create and edit own content only
+    Permission.CREATE_CONTENT,
+    Permission.EDIT_OWN_CONTENT,
+    Permission.MANAGE_ASSETS,
+    Permission.VIEW_OWN_CONTENT,
+    Permission.VIEW_PUBLISHED_CONTENT,
+  ],
+  VIEWER: [
+    // Read-only access to published content
+    Permission.VIEW_PUBLISHED_CONTENT,
+  ],
+  BILLING: [
+    // Billing and subscription management only
+    Permission.MANAGE_BILLING,
+    Permission.VIEW_BILLING,
+  ],
+  ANALYTICS: [
+    // Analytics and reports access only
+    Permission.VIEW_ANALYTICS,
+    Permission.EXPORT_REPORTS,
+  ],
+}
+
+export function hasPermission(role: Role, permission: Permission): boolean {
+  return ROLE_PERMISSIONS[role].includes(permission)
+}
+
+export function hasAnyPermission(role: Role, permissions: Permission[]): boolean {
+  return permissions.some((p) => hasPermission(role, p))
+}
+
+export function hasAllPermissions(role: Role, permissions: Permission[]): boolean {
+  return permissions.every((p) => hasPermission(role, p))
+}

package/templates/base/src/server/auth/roles.test.ts

@@ -0,0 +1,169 @@
+// src/auth/roles.test.ts
+import { describe, it, expect } from 'vitest'
+import {
+  Role,
+  hasMinimumRole,
+  getRolesWithMinimumAccess,
+  isHierarchicalRole,
+  getRoleLevel,
+  getAllRoles,
+  compareRoles,
+  isRoleHigherThan,
+} from './roles'
+
+describe('roles', () => {
+  describe('hasMinimumRole', () => {
+    it('ADMIN should have access to ADMIN-required endpoints', () => {
+      expect(hasMinimumRole('ADMIN', 'ADMIN')).toBe(true)
+    })
+
+    it('ADMIN should have access to VIEWER-required endpoints', () => {
+      expect(hasMinimumRole('ADMIN', 'VIEWER')).toBe(true)
+    })
+
+    it('VIEWER should NOT have access to ADMIN-required endpoints', () => {
+      expect(hasMinimumRole('VIEWER', 'ADMIN')).toBe(false)
+    })
+
+    it('MANAGER should have access to EDITOR-required endpoints', () => {
+      expect(hasMinimumRole('MANAGER', 'EDITOR')).toBe(true)
+    })
+
+    it('BILLING (non-hierarchical) should only match BILLING', () => {
+      expect(hasMinimumRole('BILLING', 'BILLING')).toBe(true)
+      expect(hasMinimumRole('BILLING', 'VIEWER')).toBe(false)
+      expect(hasMinimumRole('ADMIN', 'BILLING')).toBe(false)
+    })
+
+    it('ANALYTICS (non-hierarchical) should only match ANALYTICS', () => {
+      expect(hasMinimumRole('ANALYTICS', 'ANALYTICS')).toBe(true)
+      expect(hasMinimumRole('ANALYTICS', 'VIEWER')).toBe(false)
+    })
+
+    it('should allow access via additionalRoles', () => {
+      expect(hasMinimumRole('BILLING', 'ADMIN', ['BILLING'])).toBe(true)
+    })
+  })
+
+  describe('getRolesWithMinimumAccess', () => {
+    it('should return ADMIN, MANAGER, EDITOR for EDITOR minimum', () => {
+      const result = getRolesWithMinimumAccess('EDITOR')
+      expect(result).toContain('ADMIN')
+      expect(result).toContain('MANAGER')
+      expect(result).toContain('EDITOR')
+      expect(result).not.toContain('AUTHOR')
+      expect(result).not.toContain('VIEWER')
+    })
+
+    it('should return only ADMIN for ADMIN minimum', () => {
+      const result = getRolesWithMinimumAccess('ADMIN')
+      expect(result).toEqual(['ADMIN'])
+    })
+
+    it('should return all hierarchical roles for VIEWER minimum', () => {
+      const result = getRolesWithMinimumAccess('VIEWER')
+      expect(result).toContain('ADMIN')
+      expect(result).toContain('MANAGER')
+      expect(result).toContain('EDITOR')
+      expect(result).toContain('AUTHOR')
+      expect(result).toContain('VIEWER')
+    })
+
+    it('should include additional roles', () => {
+      const result = getRolesWithMinimumAccess('ADMIN', ['BILLING'])
+      expect(result).toContain('ADMIN')
+      expect(result).toContain('BILLING')
+    })
+
+    it('should return empty for non-hierarchical role without additionalRoles', () => {
+      const result = getRolesWithMinimumAccess('BILLING')
+      expect(result).toEqual([])
+    })
+  })
+
+  describe('isHierarchicalRole', () => {
+    it('should return true for ADMIN', () => {
+      expect(isHierarchicalRole('ADMIN')).toBe(true)
+    })
+
+    it('should return true for VIEWER', () => {
+      expect(isHierarchicalRole('VIEWER')).toBe(true)
+    })
+
+    it('should return false for BILLING', () => {
+      expect(isHierarchicalRole('BILLING')).toBe(false)
+    })
+
+    it('should return false for ANALYTICS', () => {
+      expect(isHierarchicalRole('ANALYTICS')).toBe(false)
+    })
+  })
+
+  describe('getRoleLevel', () => {
+    it('should return 0 for ADMIN', () => {
+      expect(getRoleLevel('ADMIN')).toBe(0)
+    })
+
+    it('should return 1 for MANAGER', () => {
+      expect(getRoleLevel('MANAGER')).toBe(1)
+    })
+
+    it('should return 4 for VIEWER', () => {
+      expect(getRoleLevel('VIEWER')).toBe(4)
+    })
+
+    it('should return -1 for BILLING', () => {
+      expect(getRoleLevel('BILLING')).toBe(-1)
+    })
+  })
+
+  describe('getAllRoles', () => {
+    it('should return all 7 roles', () => {
+      const roles = getAllRoles()
+      expect(roles).toHaveLength(7)
+      expect(roles).toContain('ADMIN')
+      expect(roles).toContain('BILLING')
+      expect(roles).toContain('ANALYTICS')
+    })
+  })
+
+  describe('compareRoles', () => {
+    it('should return -1 when roleA is higher than roleB', () => {
+      expect(compareRoles('ADMIN', 'VIEWER')).toBe(-1)
+    })
+
+    it('should return 1 when roleA is lower than roleB', () => {
+      expect(compareRoles('VIEWER', 'ADMIN')).toBe(1)
+    })
+
+    it('should return 0 when roles are equal', () => {
+      expect(compareRoles('MANAGER', 'MANAGER')).toBe(0)
+    })
+
+    it('should handle non-hierarchical roles', () => {
+      expect(compareRoles('BILLING', 'ANALYTICS')).toBe(0)
+    })
+  })
+
+  describe('isRoleHigherThan', () => {
+    it('should return true when ADMIN compared to VIEWER', () => {
+      expect(isRoleHigherThan('ADMIN', 'VIEWER')).toBe(true)
+    })
+
+    it('should return true when MANAGER compared to EDITOR', () => {
+      expect(isRoleHigherThan('MANAGER', 'EDITOR')).toBe(true)
+    })
+
+    it('should return false when VIEWER compared to ADMIN', () => {
+      expect(isRoleHigherThan('VIEWER', 'ADMIN')).toBe(false)
+    })
+
+    it('should return false when roles are equal', () => {
+      expect(isRoleHigherThan('MANAGER', 'MANAGER')).toBe(false)
+    })
+
+    it('should return false for non-hierarchical roles', () => {
+      expect(isRoleHigherThan('BILLING', 'VIEWER')).toBe(false)
+    })
+  })
+})