@etus/bhono-app 0.1.1

package/templates/base/src/server/routes/health/routes.ts

@@ -0,0 +1,90 @@
+import { createRoute, z } from '@hono/zod-openapi'
+
+const HealthResponseSchema = z.object({
+  status: z.enum(['healthy', 'unhealthy']).openapi({
+    example: 'healthy',
+    description: 'Overall health status'
+  }),
+  timestamp: z.iso.datetime().openapi({
+    example: '2025-12-30T10:00:00Z',
+    description: 'UTC timestamp when check was performed'
+  }),
+  checks: z.object({
+    database: z.enum(['up', 'down']).openapi({
+      example: 'up',
+      description: 'Database connectivity status'
+    }),
+    storage: z.enum(['up', 'down']).openapi({
+      example: 'up',
+      description: 'R2 storage connectivity status'
+    })
+  }),
+  uptime: z.number().openapi({
+    example: 3600,
+    description: 'Seconds since server started'
+  })
+}).openapi('HealthResponse')
+
+const ReadyResponseSchema = z.object({
+  ready: z.boolean().openapi({
+    example: true,
+    description: 'Whether the system is ready to serve traffic'
+  })
+}).openapi('ReadyResponse')
+
+const LiveResponseSchema = z.object({
+  alive: z.boolean().openapi({
+    example: true,
+    description: 'Whether the system process is alive'
+  })
+}).openapi('LiveResponse')
+
+export const healthRoute = createRoute({
+  method: 'get',
+  path: '/',
+  tags: ['Health'],
+  summary: 'Overall health check with dependency status',
+  description: 'Checks database and storage connectivity',
+  responses: {
+    200: {
+      description: 'System is healthy',
+      content: { 'application/json': { schema: HealthResponseSchema } }
+    },
+    503: {
+      description: 'System is unhealthy',
+      content: { 'application/json': { schema: HealthResponseSchema } }
+    }
+  }
+})
+
+export const readyRoute = createRoute({
+  method: 'get',
+  path: '/ready',
+  tags: ['Health'],
+  summary: 'Readiness probe for orchestration',
+  description: 'Returns 200 if system is ready to accept traffic, 503 otherwise',
+  responses: {
+    200: {
+      description: 'System is ready',
+      content: { 'application/json': { schema: ReadyResponseSchema } }
+    },
+    503: {
+      description: 'System is not ready',
+      content: { 'application/json': { schema: ReadyResponseSchema } }
+    }
+  }
+})
+
+export const liveRoute = createRoute({
+  method: 'get',
+  path: '/live',
+  tags: ['Health'],
+  summary: 'Liveness probe for orchestration',
+  description: 'Returns 200 if process is alive',
+  responses: {
+    200: {
+      description: 'System is alive',
+      content: { 'application/json': { schema: LiveResponseSchema } }
+    }
+  }
+})

package/templates/base/src/server/routes/index.ts

@@ -0,0 +1,53 @@
+import { OpenAPIHono } from '@hono/zod-openapi'
+import { swaggerUI } from '@hono/swagger-ui'
+import type { HonoEnv } from '../types'
+import { sessionAuth, accountMiddleware } from '../middleware'
+import { users } from './users'
+import { accounts } from './accounts'
+import { invitationsRouter } from './invitations'
+import { audits } from './audits'
+import { storage } from './storage'
+import { openApiConfig } from './openapi'
+
+const api = new OpenAPIHono<HonoEnv>()
+
+// Apply auth middleware to all routes except documentation
+api.use('/*', async (c, next) => {
+  // Skip auth for documentation endpoints
+  if (c.req.path === '/api/doc' || c.req.path === '/api/swagger') {
+    return next()
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-argument -- Hono wildcard route typing
+  return sessionAuth(c, next)
+})
+api.use('/*', async (c, next) => {
+  // Skip account middleware for documentation endpoints
+  if (c.req.path === '/api/doc' || c.req.path === '/api/swagger') {
+    return next()
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-argument -- Hono wildcard route typing
+  return accountMiddleware(c, next)
+})
+
+// Mount routers
+api.route('/users', users)
+api.route('/accounts', accounts)
+api.route('/invitations', invitationsRouter)
+api.route('/audits', audits)
+api.route('/storage', storage)
+
+// Register security scheme component (session-based authentication via cookies)
+api.openAPIRegistry.registerComponent('securitySchemes', 'SessionCookie', {
+  type: 'apiKey',
+  in: 'cookie',
+  name: 'sid',
+  description: 'Session cookie authentication. Login via /auth/login to obtain session.',
+})
+
+// OpenAPI documentation
+api.doc('/doc', openApiConfig)
+
+// Swagger UI
+api.get('/swagger', swaggerUI({ url: '/api/doc' }))
+
+export { api }

package/templates/base/src/server/routes/invitations/__tests__/handlers.test.ts

@@ -0,0 +1,473 @@
+// src/server/routes/invitations/__tests__/handlers.test.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { Hono } from 'hono'
+import type { HonoEnv } from '../../../types'
+import { invitationsRouter } from '../index'
+import { createMockEnv } from '../../../__tests__/setup'
+import { createUserFixture, createAccountFixture } from '../../../__tests__/fixtures'
+import { NotFoundError, ConflictError, ForbiddenError } from '../../../lib/errors'
+
+// Test UUIDs
+const TEST_USER_ID = '550e8400-e29b-41d4-a716-446655440001'
+const TEST_ACCOUNT_ID = '550e8400-e29b-41d4-a716-446655440101'
+const TEST_INVITATION_ID = '550e8400-e29b-41d4-a716-446655440201'
+const NON_EXISTENT_ID = '550e8400-e29b-41d4-a716-446655440999'
+
+// Mock the invitations service
+vi.mock('../../../services/invitations', () => ({
+  invitationsService: {
+    create: vi.fn(),
+    list: vi.fn(),
+    revoke: vi.fn(),
+  },
+}))
+
+import { invitationsService } from '../../../services/invitations'
+
+describe('Invitations Routes', () => {
+  let mockEnv: ReturnType<typeof createMockEnv>
+  let mockDb: any
+  let testUser: ReturnType<typeof createUserFixture>
+  let testAccount: ReturnType<typeof createAccountFixture>
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockEnv = createMockEnv()
+
+    testUser = createUserFixture({ id: TEST_USER_ID, email: 'admin@example.com', name: 'Admin User' })
+    testAccount = createAccountFixture({ id: TEST_ACCOUNT_ID })
+
+    // Create mock database
+    mockDb = {
+      select: vi.fn().mockReturnThis(),
+      from: vi.fn().mockReturnThis(),
+      where: vi.fn().mockReturnThis(),
+      limit: vi.fn().mockResolvedValue([]),
+      insert: vi.fn().mockReturnThis(),
+      values: vi.fn().mockReturnThis(),
+      returning: vi.fn().mockResolvedValue([]),
+      update: vi.fn().mockReturnThis(),
+      set: vi.fn().mockReturnThis(),
+      delete: vi.fn().mockReturnThis(),
+      execute: vi.fn().mockResolvedValue({ rows: [] }),
+    }
+  })
+
+  // Helper to setup authenticated app with specific role
+  function setupAuthenticatedApp(userRole = 'ADMIN', isSuperAdmin = false) {
+    const authenticatedApp = new Hono<HonoEnv>()
+
+    authenticatedApp.use('*', async (c, next) => {
+      ;(c as any).env = mockEnv
+      c.set('db', mockDb)
+      c.set('transactionId', 'test-transaction-id')
+      c.set('ip', '127.0.0.1')
+      c.set('userAgent', 'TestAgent/1.0')
+      c.set('user', { ...testUser, isSuperAdmin })
+      c.set('accountId', testAccount.id)
+      c.set('userRole', userRole)
+      c.set('isSystemAdminAccess', isSuperAdmin)
+      await next()
+    })
+
+    authenticatedApp.route('/invitations', invitationsRouter)
+    return authenticatedApp
+  }
+
+  describe('POST /invitations (createInvitationHandler)', () => {
+    it('should create invitation for new user', async () => {
+      const invitationResult = {
+        linked: false,
+        invited: true,
+        invitation: {
+          id: TEST_INVITATION_ID,
+          email: 'newuser@example.com',
+          role: 'VIEWER',
+          expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+        },
+      }
+
+      vi.mocked(invitationsService.create).mockResolvedValue(invitationResult)
+
+      const authenticatedApp = setupAuthenticatedApp('ADMIN')
+
+      const res = await authenticatedApp.request('/invitations', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          email: 'newuser@example.com',
+          role: 'VIEWER',
+        }),
+      })
+
+      expect(res.status).toBe(200)
+      const body = await res.json()
+      expect(body.linked).toBe(false)
+      expect(body.invited).toBe(true)
+      expect(body.invitation).toBeDefined()
+      expect(body.invitation.email).toBe('newuser@example.com')
+      expect(body.invitation.role).toBe('VIEWER')
+    })
+
+    it('should return linked user when existing user is invited', async () => {
+      const linkedResult = {
+        linked: true,
+        invited: false,
+        user: {
+          id: 'existing-user-id',
+          email: 'existing@example.com',
+          name: 'Existing User',
+        },
+      }
+
+      vi.mocked(invitationsService.create).mockResolvedValue(linkedResult)
+
+      const authenticatedApp = setupAuthenticatedApp('ADMIN')
+
+      const res = await authenticatedApp.request('/invitations', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          email: 'existing@example.com',
+          role: 'VIEWER',
+        }),
+      })
+
+      expect(res.status).toBe(200)
+      const body = await res.json()
+      expect(body.linked).toBe(true)
+      expect(body.invited).toBe(false)
+      expect(body.user).toBeDefined()
+      expect(body.user.email).toBe('existing@example.com')
+      expect(body.user.name).toBe('Existing User')
+    })
+
+    it('should throw ForbiddenError when assigning higher role', async () => {
+      vi.mocked(invitationsService.create).mockRejectedValue(
+        new ForbiddenError('Cannot assign a role higher than your own')
+      )
+
+      const authenticatedApp = setupAuthenticatedApp('MANAGER')
+
+      const res = await authenticatedApp.request('/invitations', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          email: 'newuser@example.com',
+          role: 'ADMIN',
+        }),
+      })
+
+      expect(res.status).toBe(403)
+    })
+
+    it('should throw ConflictError when user already member', async () => {
+      vi.mocked(invitationsService.create).mockRejectedValue(
+        new ConflictError('User is already a member of this account')
+      )
+
+      const authenticatedApp = setupAuthenticatedApp('ADMIN')
+
+      const res = await authenticatedApp.request('/invitations', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          email: 'member@example.com',
+          role: 'VIEWER',
+        }),
+      })
+
+      expect(res.status).toBe(409)
+    })
+
+    it('calls service with correct parameters', async () => {
+      vi.mocked(invitationsService.create).mockResolvedValue({
+        linked: false,
+        invited: true,
+        invitation: {
+          id: TEST_INVITATION_ID,
+          email: 'test@example.com',
+          role: 'MANAGER',
+          expiresAt: new Date().toISOString(),
+        },
+      })
+
+      const authenticatedApp = setupAuthenticatedApp('ADMIN')
+
+      await authenticatedApp.request('/invitations', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          email: 'test@example.com',
+          role: 'MANAGER',
+        }),
+      })
+
+      expect(invitationsService.create).toHaveBeenCalledWith(
+        mockDb,
+        mockEnv,
+        expect.objectContaining({
+          accountId: testAccount.id,
+          user: expect.objectContaining({ id: testUser.id }),
+          userRole: 'ADMIN',
+        }),
+        expect.objectContaining({
+          email: 'test@example.com',
+          role: 'MANAGER',
+        })
+      )
+    })
+  })
+
+  describe('GET /invitations (listInvitationsHandler)', () => {
+    it('should return list of invitations', async () => {
+      const invitationsList = [
+        {
+          id: TEST_INVITATION_ID,
+          email: 'invited1@example.com',
+          role: 'VIEWER',
+          invitedBy: { id: TEST_USER_ID, name: 'Admin User' },
+          expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+          createdAt: new Date().toISOString(),
+        },
+        {
+          id: '550e8400-e29b-41d4-a716-446655440202',
+          email: 'invited2@example.com',
+          role: 'MANAGER',
+          invitedBy: { id: TEST_USER_ID, name: 'Admin User' },
+          expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+          createdAt: new Date().toISOString(),
+        },
+      ]
+
+      vi.mocked(invitationsService.list).mockResolvedValue(invitationsList)
+
+      const authenticatedApp = setupAuthenticatedApp('MANAGER')
+
+      const res = await authenticatedApp.request('/invitations', {
+        method: 'GET',
+      })
+
+      expect(res.status).toBe(200)
+      const body = await res.json()
+      expect(body.data).toHaveLength(2)
+      expect(body.data[0].email).toBe('invited1@example.com')
+      expect(body.data[1].email).toBe('invited2@example.com')
+    })
+
+    it('should return empty list when no invitations', async () => {
+      vi.mocked(invitationsService.list).mockResolvedValue([])
+
+      const authenticatedApp = setupAuthenticatedApp('MANAGER')
+
+      const res = await authenticatedApp.request('/invitations', {
+        method: 'GET',
+      })
+
+      expect(res.status).toBe(200)
+      const body = await res.json()
+      expect(body.data).toHaveLength(0)
+    })
+
+    it('calls service with correct context', async () => {
+      vi.mocked(invitationsService.list).mockResolvedValue([])
+
+      const authenticatedApp = setupAuthenticatedApp('ADMIN')
+
+      await authenticatedApp.request('/invitations', {
+        method: 'GET',
+      })
+
+      expect(invitationsService.list).toHaveBeenCalledWith(
+        mockDb,
+        expect.objectContaining({
+          accountId: testAccount.id,
+          user: expect.objectContaining({ id: testUser.id }),
+          userRole: 'ADMIN',
+        })
+      )
+    })
+  })
+
+  describe('DELETE /invitations/:id (revokeInvitationHandler)', () => {
+    it('should revoke invitation successfully', async () => {
+      vi.mocked(invitationsService.revoke).mockResolvedValue()
+
+      const authenticatedApp = setupAuthenticatedApp('ADMIN')
+
+      const res = await authenticatedApp.request(`/invitations/${TEST_INVITATION_ID}`, {
+        method: 'DELETE',
+      })
+
+      expect(res.status).toBe(204)
+      expect(invitationsService.revoke).toHaveBeenCalledWith(
+        mockDb,
+        expect.objectContaining({
+          accountId: testAccount.id,
+          user: expect.objectContaining({ id: testUser.id }),
+        }),
+        TEST_INVITATION_ID
+      )
+    })
+
+    it('should throw NotFoundError for non-existent invitation', async () => {
+      vi.mocked(invitationsService.revoke).mockRejectedValue(new NotFoundError('Invitation'))
+
+      const authenticatedApp = setupAuthenticatedApp('ADMIN')
+
+      const res = await authenticatedApp.request(`/invitations/${NON_EXISTENT_ID}`, {
+        method: 'DELETE',
+      })
+
+      expect(res.status).toBe(404)
+    })
+
+    it('allows MANAGER role to revoke invitations', async () => {
+      vi.mocked(invitationsService.revoke).mockResolvedValue()
+
+      const authenticatedApp = setupAuthenticatedApp('MANAGER')
+
+      const res = await authenticatedApp.request(`/invitations/${TEST_INVITATION_ID}`, {
+        method: 'DELETE',
+      })
+
+      expect(res.status).toBe(204)
+    })
+
+    it('should throw NotFoundError when revoking already accepted invitation', async () => {
+      vi.mocked(invitationsService.revoke).mockRejectedValue(new NotFoundError('Invitation'))
+
+      const authenticatedApp = setupAuthenticatedApp('ADMIN')
+
+      const res = await authenticatedApp.request(`/invitations/${TEST_INVITATION_ID}`, {
+        method: 'DELETE',
+      })
+
+      expect(res.status).toBe(404)
+    })
+  })
+
+  describe('Error handling - missing context', () => {
+    // Helper to setup app without db
+    function setupAppWithoutDb() {
+      const brokenApp = new Hono<HonoEnv>()
+      const testUser = createUserFixture({ id: TEST_USER_ID })
+      const testAccount = createAccountFixture({ id: TEST_ACCOUNT_ID })
+
+      brokenApp.use('*', async (c, next) => {
+        ;(c as any).env = createMockEnv()
+        c.set('db', null) // No database
+        c.set('transactionId', 'test-transaction-id')
+        c.set('ip', '127.0.0.1')
+        c.set('userAgent', 'TestAgent/1.0')
+        c.set('user', testUser)
+        c.set('accountId', testAccount.id)
+        c.set('userRole', 'ADMIN')
+        await next()
+      })
+
+      brokenApp.route('/invitations', invitationsRouter)
+      return brokenApp
+    }
+
+    // Helper to setup app without user context
+    function setupAppWithoutUser() {
+      const brokenApp = new Hono<HonoEnv>()
+      const testAccount = createAccountFixture({ id: TEST_ACCOUNT_ID })
+      const mockEnv = createMockEnv()
+
+      brokenApp.use('*', async (c, next) => {
+        ;(c as any).env = mockEnv
+        c.set('db', {
+          select: vi.fn().mockReturnThis(),
+          from: vi.fn().mockReturnThis(),
+          where: vi.fn().mockReturnThis(),
+          limit: vi.fn().mockResolvedValue([]),
+        })
+        c.set('transactionId', 'test-transaction-id')
+        c.set('ip', '127.0.0.1')
+        c.set('userAgent', 'TestAgent/1.0')
+        c.set('user', null) // No user
+        c.set('accountId', testAccount.id)
+        c.set('userRole', 'ADMIN')
+        await next()
+      })
+
+      brokenApp.route('/invitations', invitationsRouter)
+      return brokenApp
+    }
+
+    it('should throw 500 when db is not initialized for create', async () => {
+      const brokenApp = setupAppWithoutDb()
+
+      const res = await brokenApp.request('/invitations', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email: 'test@example.com', role: 'VIEWER' }),
+      })
+
+      expect(res.status).toBe(500)
+    })
+
+    it('should throw 500 when db is not initialized for list', async () => {
+      const brokenApp = setupAppWithoutDb()
+
+      const res = await brokenApp.request('/invitations', { method: 'GET' })
+
+      expect(res.status).toBe(500)
+    })
+
+    it('should throw 500 when db is not initialized for revoke', async () => {
+      const brokenApp = setupAppWithoutDb()
+
+      const res = await brokenApp.request(`/invitations/${TEST_INVITATION_ID}`, {
+        method: 'DELETE',
+      })
+
+      expect(res.status).toBe(500)
+    })
+
+    it('should throw 401 when user context is missing for create (auth guard)', async () => {
+      const brokenApp = setupAppWithoutUser()
+
+      const res = await brokenApp.request('/invitations', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email: 'test@example.com', role: 'VIEWER' }),
+      })
+
+      // Auth middleware returns 401 before handler runs
+      expect(res.status).toBe(401)
+    })
+
+    it('should throw 401 when user context is missing for list (auth guard)', async () => {
+      const brokenApp = setupAppWithoutUser()
+
+      const res = await brokenApp.request('/invitations', { method: 'GET' })
+
+      // Auth middleware returns 401 before handler runs
+      expect(res.status).toBe(401)
+    })
+
+    it('should throw 401 when user context is missing for revoke (auth guard)', async () => {
+      const brokenApp = setupAppWithoutUser()
+
+      const res = await brokenApp.request(`/invitations/${TEST_INVITATION_ID}`, {
+        method: 'DELETE',
+      })
+
+      // Auth middleware returns 401 before handler runs
+      expect(res.status).toBe(401)
+    })
+  })
+})

package/templates/base/src/server/routes/invitations/handlers.ts

@@ -0,0 +1,71 @@
+// src/routes/invitations/handlers.ts
+import type { RouteHandler } from '@hono/zod-openapi'
+import type { Context } from 'hono'
+import { HTTPException } from 'hono/http-exception'
+import { invitationsService } from '../../services/invitations'
+import type { ServiceContext, HonoEnv } from '../../types'
+import type {
+  createInvitationRoute,
+  listInvitationsRoute,
+  revokeInvitationRoute,
+} from './routes'
+
+function getServiceContext(c: Context<HonoEnv>): ServiceContext {
+  const accountId = c.get('accountId')
+  const user = c.get('user')
+
+  if (!accountId || !user) {
+    throw new HTTPException(500, { message: 'Missing required context' })
+  }
+
+  return {
+    accountId,
+    user,
+    userRole: c.get('userRole'),
+    transactionId: c.get('transactionId') ?? '',
+    ip: c.get('ip') ?? '',
+    userAgent: c.get('userAgent') ?? '',
+  }
+}
+
+export const createInvitationHandler: RouteHandler<typeof createInvitationRoute, HonoEnv> = async (c) => {
+  const body = c.req.valid('json')
+  const db = c.get('db')
+  const env = c.env
+  const ctx = getServiceContext(c)
+
+  if (!db) {
+    throw new HTTPException(500, { message: 'Database not initialized' })
+  }
+
+  const result = await invitationsService.create(db, env, ctx, body)
+
+  return c.json(result, 200)
+}
+
+export const listInvitationsHandler: RouteHandler<typeof listInvitationsRoute, HonoEnv> = async (c) => {
+  const db = c.get('db')
+  const ctx = getServiceContext(c)
+
+  if (!db) {
+    throw new HTTPException(500, { message: 'Database not initialized' })
+  }
+
+  const invitations = await invitationsService.list(db, ctx)
+
+  return c.json({ data: invitations }, 200)
+}
+
+export const revokeInvitationHandler: RouteHandler<typeof revokeInvitationRoute, HonoEnv> = async (c) => {
+  const { id } = c.req.valid('param')
+  const db = c.get('db')
+  const ctx = getServiceContext(c)
+
+  if (!db) {
+    throw new HTTPException(500, { message: 'Database not initialized' })
+  }
+
+  await invitationsService.revoke(db, ctx, id)
+
+  return c.body(null, 204)
+}