create-fullstack-scaffold 0.1.0

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

@@ -0,0 +1,258 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { Hono } from 'hono'
+import {
+  captchaMiddleware,
+  verifyCaptchaMiddleware,
+  markCaptchaVerifiedMiddleware,
+  clearCaptchaSessionMiddleware,
+} from '../captcha'
+
+describe('captchaMiddleware', () => {
+  beforeEach(() => {
+    vi.stubEnv('NODE_ENV', 'development')
+  })
+
+  afterEach(() => {
+    vi.unstubAllEnvs()
+  })
+
+  it('should skip in test environment', async () => {
+    vi.stubEnv('NODE_ENV', 'test')
+    const app = new Hono()
+    const handler = vi.fn().mockResolvedValue(new Response('ok'))
+    app.use('*', captchaMiddleware())
+    app.get('/api/test', handler)
+
+    const res = await app.request('/api/test')
+    expect(res.status).toBe(200)
+    expect(handler).toHaveBeenCalled()
+  })
+
+  it('should skip configured skip paths', async () => {
+    const app = new Hono()
+    const handler = vi.fn().mockResolvedValue(new Response('ok'))
+    app.use('*', captchaMiddleware())
+    app.get('/api/captcha', handler)
+    app.post('/api/verify-captcha', handler)
+    app.post('/api/admin/login', handler)
+    app.post('/api/admin/register', handler)
+
+    let res = await app.request('/api/captcha')
+    expect(res.status).toBe(200)
+
+    res = await app.request('/api/verify-captcha', { method: 'POST' })
+    expect(res.status).toBe(200)
+
+    res = await app.request('/api/admin/login', { method: 'POST' })
+    expect(res.status).toBe(200)
+
+    res = await app.request('/api/admin/register', { method: 'POST' })
+    expect(res.status).toBe(200)
+    expect(handler).toHaveBeenCalledTimes(4)
+  })
+
+  it('should skip custom skip paths', async () => {
+    const app = new Hono()
+    const handler = vi.fn().mockResolvedValue(new Response('ok'))
+    app.use('*', captchaMiddleware({ skipPaths: ['/api/custom'] }))
+    app.get('/api/custom', handler)
+
+    const res = await app.request('/api/custom')
+    expect(res.status).toBe(200)
+    expect(handler).toHaveBeenCalled()
+  })
+
+  it('should allow requests within rate limit', async () => {
+    const app = new Hono()
+    let callCount = 0
+    app.use('*', captchaMiddleware({ maxRequests: 10, windowMs: 60000 }))
+    app.get('/api/data', c => {
+      callCount++
+      return c.json({ ok: true })
+    })
+
+    for (let i = 0; i < 5; i++) {
+      const res = await app.request('/api/data', {
+        headers: { 'User-Agent': 'Mozilla/5.0 Test Browser Normal' },
+      })
+      expect(res.status).toBe(200)
+    }
+    expect(callCount).toBe(5)
+  })
+
+  it('should block requests exceeding rate limit', async () => {
+    const app = new Hono()
+    app.use('*', captchaMiddleware({ maxRequests: 3, windowMs: 60000 }))
+    app.get('/api/data', c => c.json({ ok: true }))
+
+    const ua = 'Mozilla/5.0 Test Browser For Rate Limit Testing'
+    let sessionId = ''
+    for (let i = 0; i < 3; i++) {
+      const r = await app.request('/api/data', {
+        headers: { 'User-Agent': ua, ...(sessionId ? { Cookie: `session_id=${sessionId}` } : {}) },
+      })
+      const setCookie = r.headers.get('set-cookie')
+      if (setCookie) {
+        const match = setCookie.match(/session_id=([^;]+)/)
+        if (match) sessionId = match[1]
+      }
+    }
+
+    const res = await app.request('/api/data', {
+      headers: { 'User-Agent': ua, Cookie: `session_id=${sessionId}` },
+    })
+    expect(res.status).toBe(429)
+    const body = (await res.json()) as { needCaptcha: boolean; success: boolean }
+    expect(body.needCaptcha).toBe(true)
+    expect(body.success).toBe(false)
+  })
+
+  it('should block suspicious requests with short User-Agent', async () => {
+    const app = new Hono()
+    app.use('*', captchaMiddleware())
+    app.get('/api/data', c => c.json({ ok: true }))
+
+    const res = await app.request('/api/data', {
+      headers: { 'User-Agent': 'short' },
+    })
+    expect(res.status).toBe(403)
+    const body = (await res.json()) as { needCaptcha: boolean }
+    expect(body.needCaptcha).toBe(true)
+  })
+
+  it('should block requests with bot in User-Agent', async () => {
+    const app = new Hono()
+    app.use('*', captchaMiddleware())
+    app.get('/api/data', c => c.json({ ok: true }))
+
+    const res = await app.request('/api/data', {
+      headers: { 'User-Agent': 'Some bot crawler tool for testing' },
+    })
+    expect(res.status).toBe(403)
+  })
+
+  it('should block requests with crawler in User-Agent', async () => {
+    const app = new Hono()
+    app.use('*', captchaMiddleware())
+    app.get('/api/data', c => c.json({ ok: true }))
+
+    const res = await app.request('/api/data', {
+      headers: { 'User-Agent': 'Google crawler bot for web scraping tests here' },
+    })
+    expect(res.status).toBe(403)
+  })
+
+  it('should block requests with empty User-Agent', async () => {
+    const app = new Hono()
+    app.use('*', captchaMiddleware())
+    app.get('/api/data', c => c.json({ ok: true }))
+
+    const res = await app.request('/api/data')
+    expect(res.status).toBe(403)
+  })
+
+  it('should reset rate limit after window expires', async () => {
+    vi.useFakeTimers()
+    const app = new Hono()
+    app.use('*', captchaMiddleware({ maxRequests: 2, windowMs: 1000 }))
+    app.get('/api/data', c => c.json({ ok: true }))
+
+    const ua = 'Mozilla/5.0 Window Reset Test Browser'
+    let sessionId = ''
+    for (let i = 0; i < 2; i++) {
+      const r = await app.request('/api/data', {
+        headers: { 'User-Agent': ua, ...(sessionId ? { Cookie: `session_id=${sessionId}` } : {}) },
+      })
+      const setCookie = r.headers.get('set-cookie')
+      if (setCookie) {
+        const match = setCookie.match(/session_id=([^;]+)/)
+        if (match) sessionId = match[1]
+      }
+    }
+
+    const blocked = await app.request('/api/data', {
+      headers: { 'User-Agent': ua, Cookie: `session_id=${sessionId}` },
+    })
+    expect(blocked.status).toBe(429)
+
+    vi.advanceTimersByTime(1001)
+
+    const allowed = await app.request('/api/data', {
+      headers: { 'User-Agent': ua, Cookie: `session_id=${sessionId}` },
+    })
+    expect(allowed.status).toBe(200)
+
+    vi.useRealTimers()
+  })
+
+  it('should allow verified session within verification window', async () => {
+    vi.useFakeTimers()
+    const sessionId = 'verified-session-test'
+    markCaptchaVerifiedMiddleware(sessionId)
+
+    const app = new Hono()
+    app.use('*', captchaMiddleware({ maxRequests: 1, windowMs: 60000 }))
+    app.get('/api/data', c => c.json({ ok: true }))
+
+    const res = await app.request('/api/data', {
+      headers: {
+        'User-Agent': 'Mozilla/5.0 Verified Session Test',
+        Cookie: `session_id=${sessionId}`,
+      },
+    })
+    expect(res.status).toBe(200)
+
+    vi.useRealTimers()
+  })
+})
+
+describe('verifyCaptchaMiddleware', () => {
+  it('should return 400 if no session cookie', async () => {
+    const app = new Hono()
+    app.use('*', verifyCaptchaMiddleware())
+    app.post('/api/verify', c => c.json({ ok: true }))
+
+    const res = await app.request('/api/verify', { method: 'POST' })
+    expect(res.status).toBe(400)
+    const body = (await res.json()) as { error: string }
+    expect(body.error).toBe('Session not found')
+  })
+
+  it('should mark session as verified when session exists', async () => {
+    const sessionId = 'verify-test-session'
+    markCaptchaVerifiedMiddleware(sessionId)
+
+    const app = new Hono()
+    app.use('*', verifyCaptchaMiddleware())
+    app.post('/api/verify', c => c.json({ ok: true }))
+
+    const res = await app.request('/api/verify', {
+      method: 'POST',
+      headers: { Cookie: `session_id=${sessionId}` },
+    })
+    expect(res.status).toBe(200)
+  })
+})
+
+describe('markCaptchaVerifiedMiddleware', () => {
+  it('should mark session as verified', () => {
+    const sessionId = 'test-session-123'
+    markCaptchaVerifiedMiddleware(sessionId)
+  })
+
+  it('should handle non-existent session gracefully', () => {
+    expect(() => markCaptchaVerifiedMiddleware('non-existent')).not.toThrow()
+  })
+})
+
+describe('clearCaptchaSessionMiddleware', () => {
+  it('should clear session', () => {
+    const sessionId = 'test-session-clear'
+    markCaptchaVerifiedMiddleware(sessionId)
+    clearCaptchaSessionMiddleware(sessionId)
+  })
+
+  it('should handle non-existent session gracefully', () => {
+    expect(() => clearCaptchaSessionMiddleware('non-existent')).not.toThrow()
+  })
+})

package/template/src/server/middleware/__tests__/error-handler.test.ts

@@ -0,0 +1,364 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { Hono } from 'hono'
+import { HTTPException } from 'hono/http-exception'
+import { ZodError, type ZodIssue } from 'zod'
+import { AppError, ErrorCode } from '@server/utils/app-error'
+
+vi.mock('@server/utils/logger', () => {
+  const noop = () => {}
+  const mockLogger = {
+    info: noop,
+    warn: noop,
+    error: noop,
+    debug: noop,
+    trace: noop,
+    fatal: noop,
+    child: () => mockLogger,
+  }
+  return {
+    createModuleLoggerSync: () => mockLogger,
+    logger: {
+      api: () => mockLogger,
+      app: () => mockLogger,
+      db: () => mockLogger,
+      ws: () => mockLogger,
+      bootstrap: () => mockLogger,
+      module: () => mockLogger,
+    },
+  }
+})
+
+import { errorHandlerMiddleware } from '../error-handler'
+
+function createTestApp(options?: { includeStackTrace?: boolean; logErrors?: boolean }) {
+  const app = new Hono()
+
+  app.use(
+    '*',
+    errorHandlerMiddleware({
+      includeStackTrace: options?.includeStackTrace,
+      logErrors: options?.logErrors,
+    })
+  )
+
+  app.onError((err, c) => {
+    if (AppError.isAppError(err)) {
+      return c.json(
+        {
+          success: false as const,
+          error: err.message,
+          status: err.statusCode,
+          details: err.details,
+        },
+        err.statusCode as 400
+      )
+    }
+
+    if (err instanceof ZodError) {
+      const details = err.issues.map(issue => ({
+        field: issue.path.join('.'),
+        message: issue.message,
+        code: issue.code,
+      }))
+      return c.json(
+        {
+          success: false as const,
+          error: 'Validation failed',
+          status: 400,
+          details,
+        },
+        400
+      )
+    }
+
+    if (err instanceof HTTPException) {
+      const status = err.status || 500
+      const message = err.message || 'Internal server error'
+      return c.json({ success: false as const, error: message, status }, status as 400)
+    }
+
+    const message = err instanceof Error ? err.message : 'Internal server error'
+    const response: { success: false; error: string; status: number; stack?: string } = {
+      success: false as const,
+      error: message,
+      status: 500,
+    }
+    if (options?.includeStackTrace && err instanceof Error && err.stack) {
+      response.stack = err.stack
+    }
+    return c.json(response, 500)
+  })
+
+  return app
+}
+
+describe('errorHandlerMiddleware', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('AppError handling', () => {
+    it('should handle AppError with correct status and message', async () => {
+      const app = createTestApp()
+      app.get('/test', () => {
+        throw new AppError({
+          code: ErrorCode.NOT_FOUND,
+          message: 'Resource not found',
+          statusCode: 404,
+        })
+      })
+
+      const res = await app.request('/test')
+      expect(res.status).toBe(404)
+      const body = (await res.json()) as { success: boolean; error: string; status: number }
+      expect(body.success).toBe(false)
+      expect(body.error).toBe('Resource not found')
+      expect(body.status).toBe(404)
+    })
+
+    it('should include details in AppError response', async () => {
+      const app = createTestApp()
+      app.get('/test', () => {
+        throw new AppError({
+          code: ErrorCode.VALIDATION_ERROR,
+          message: 'Validation failed',
+          statusCode: 400,
+          details: [{ field: 'email', message: 'Invalid email' }],
+        })
+      })
+
+      const res = await app.request('/test')
+      expect(res.status).toBe(400)
+      const body = (await res.json()) as { details: Array<{ field: string; message: string }> }
+      expect(body.details).toEqual([{ field: 'email', message: 'Invalid email' }])
+    })
+
+    it('should set Content-Type to application/json', async () => {
+      const app = createTestApp()
+      app.get('/test', () => {
+        throw new AppError({
+          code: ErrorCode.UNAUTHORIZED,
+          message: 'Unauthorized',
+          statusCode: 401,
+        })
+      })
+
+      const res = await app.request('/test')
+      expect(res.headers.get('Content-Type')).toContain('application/json')
+    })
+
+    it('should handle AppError without details', async () => {
+      const app = createTestApp()
+      app.get('/test', () => {
+        throw new AppError({ code: ErrorCode.FORBIDDEN, message: 'Forbidden', statusCode: 403 })
+      })
+
+      const res = await app.request('/test')
+      expect(res.status).toBe(403)
+      const body = (await res.json()) as { success: boolean; error: string }
+      expect(body.success).toBe(false)
+      expect(body.error).toBe('Forbidden')
+    })
+  })
+
+  describe('ZodError handling', () => {
+    it('should handle ZodError with formatted validation errors', async () => {
+      const app = createTestApp()
+      app.get('/test', () => {
+        throw new ZodError([
+          {
+            code: 'invalid_type',
+            expected: 'string',
+            received: 'number',
+            path: ['email'],
+            message: 'Expected string, received number',
+          } as unknown as ZodIssue,
+        ])
+      })
+
+      const res = await app.request('/test')
+      expect(res.status).toBe(400)
+      const body = (await res.json()) as {
+        success: boolean
+        error: string
+        details: Array<{ field: string; message: string; code: string }>
+      }
+      expect(body.success).toBe(false)
+      expect(body.error).toBe('Validation failed')
+      expect(body.details).toHaveLength(1)
+      expect(body.details[0]).toEqual({
+        field: 'email',
+        message: 'Expected string, received number',
+        code: 'invalid_type',
+      })
+    })
+
+    it('should handle ZodError with nested path', async () => {
+      const app = createTestApp()
+      app.get('/test', () => {
+        throw new ZodError([
+          {
+            code: 'invalid_type',
+            expected: 'string',
+            received: 'undefined',
+            path: ['user', 'address', 'city'],
+            message: 'City is required',
+          } as unknown as ZodIssue,
+        ])
+      })
+
+      const res = await app.request('/test')
+      const body = (await res.json()) as { details: Array<{ field: string }> }
+      expect(body.details[0].field).toBe('user.address.city')
+    })
+
+    it('should handle ZodError with multiple issues', async () => {
+      const app = createTestApp()
+      app.get('/test', () => {
+        throw new ZodError([
+          {
+            code: 'invalid_type',
+            expected: 'string',
+            received: 'number',
+            path: ['email'],
+            message: 'bad email',
+          } as unknown as ZodIssue,
+          {
+            code: 'too_small',
+            minimum: 1,
+            type: 'string',
+            inclusive: true,
+            path: ['name'],
+            message: 'required',
+          } as unknown as ZodIssue,
+        ])
+      })
+
+      const res = await app.request('/test')
+      const body = (await res.json()) as { details: unknown[] }
+      expect(body.details).toHaveLength(2)
+    })
+  })
+
+  describe('HTTPException handling', () => {
+    it('should handle HTTPException with status and message', async () => {
+      const app = createTestApp()
+      app.get('/test', () => {
+        throw new HTTPException(403, { message: 'Access denied' })
+      })
+
+      const res = await app.request('/test')
+      expect(res.status).toBe(403)
+      const body = (await res.json()) as { success: boolean; error: string; status: number }
+      expect(body.success).toBe(false)
+      expect(body.error).toBe('Access denied')
+      expect(body.status).toBe(403)
+    })
+
+    it('should handle HTTPException with empty message', async () => {
+      const app = createTestApp()
+      app.get('/test', () => {
+        throw new HTTPException(500, { message: '' })
+      })
+
+      const res = await app.request('/test')
+      expect(res.status).toBe(500)
+      const body = (await res.json()) as { error: string }
+      expect(body.error).toBe('Internal server error')
+    })
+  })
+
+  describe('unknown error handling', () => {
+    it('should handle generic Error', async () => {
+      const app = createTestApp()
+      app.get('/test', () => {
+        throw new Error('Something went wrong')
+      })
+
+      const res = await app.request('/test')
+      expect(res.status).toBe(500)
+      const body = (await res.json()) as { success: boolean; error: string }
+      expect(body.success).toBe(false)
+      expect(body.error).toBe('Something went wrong')
+    })
+
+    it('should handle non-Error thrown value', async () => {
+      const app = createTestApp()
+      app.get('/test', () => {
+        throw 'string error'
+      })
+
+      const res = await app.request('/test')
+      expect(res.status).toBe(500)
+      const body = (await res.json()) as { error: string }
+      expect(body.error).toBe('Internal server error')
+    })
+
+    it('should include stack trace when option is enabled', async () => {
+      const app = createTestApp({ includeStackTrace: true })
+      app.get('/test', () => {
+        throw new Error('With stack')
+      })
+
+      const res = await app.request('/test')
+      const body = (await res.json()) as { stack: string }
+      expect(body.stack).toBeDefined()
+      expect(typeof body.stack).toBe('string')
+    })
+
+    it('should not include stack trace when option is disabled', async () => {
+      const app = createTestApp({ includeStackTrace: false })
+      app.get('/test', () => {
+        throw new Error('No stack')
+      })
+
+      const res = await app.request('/test')
+      const body = (await res.json()) as { stack?: string }
+      expect(body.stack).toBeUndefined()
+    })
+
+    it('should not include stack trace for non-Error throws', async () => {
+      const app = createTestApp({ includeStackTrace: true })
+      app.get('/test', () => {
+        throw 42
+      })
+
+      const res = await app.request('/test')
+      const body = (await res.json()) as { stack?: string }
+      expect(body.stack).toBeUndefined()
+    })
+  })
+
+  describe('normal flow', () => {
+    it('should pass through when no error', async () => {
+      const app = createTestApp()
+      app.get('/test', c => c.json({ success: true, data: 'hello' }))
+
+      const res = await app.request('/test')
+      expect(res.status).toBe(200)
+      const body = (await res.json()) as { success: boolean; data: string }
+      expect(body.success).toBe(true)
+      expect(body.data).toBe('hello')
+    })
+  })
+
+  describe('middleware try/catch path (direct invocation)', () => {
+    it('should handle no-log-errors option', async () => {
+      const app = new Hono()
+      app.use('*', errorHandlerMiddleware({ logErrors: false }))
+      app.get('/test', c => c.json({ ok: true }))
+
+      const res = await app.request('/test')
+      expect(res.status).toBe(200)
+    })
+
+    it('should handle includeStackTrace with non-Error', async () => {
+      const app = new Hono()
+      app.use('*', errorHandlerMiddleware({ includeStackTrace: true, logErrors: false }))
+      app.get('/test', c => c.json({ ok: true }))
+
+      const res = await app.request('/test')
+      expect(res.status).toBe(200)
+    })
+  })
+})

package/template/src/server/middleware/__tests__/error-response-format.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest'
+import { createTestClient } from '@server/test-utils/test-client'
+
+function authedClient(token: string) {
+  return createTestClient(undefined, {
+    headers: { Authorization: `Bearer ${token}` },
+  })
+}
+
+describe('Error Response Format', () => {
+  describe('Authentication Errors', () => {
+    it('should return JSON format for missing authentication token', async () => {
+      const client = createTestClient()
+
+      const res = await client.api.admin.stats.$get()
+
+      expect(res.status).toBe(401)
+
+      const contentType = res.headers.get('content-type')
+      expect(contentType).toContain('application/json')
+
+      const data = await res.json()
+      expect(data).toMatchObject({
+        success: false,
+        error: expect.stringContaining('Authentication token is required'),
+        status: 401,
+      })
+    })
+
+    it('should return JSON format for invalid authentication token', async () => {
+      const client = authedClient('invalid-token')
+
+      const res = await client.api.admin.stats.$get()
+
+      expect(res.status).toBe(401)
+
+      const data = await res.json()
+      expect(data).toMatchObject({
+        success: false,
+        error: expect.stringContaining('Invalid token'),
+        status: 401,
+      })
+    })
+  })
+
+  describe('Permission Errors', () => {
+    it('should return JSON format for insufficient permissions', async () => {
+      const client = authedClient('user-token')
+
+      const res = await client.api.admin.stats.$get()
+
+      expect(res.status).toBe(403)
+
+      const contentType = res.headers.get('content-type')
+      expect(contentType).toContain('application/json')
+
+      const data = await res.json()
+      expect(data).toMatchObject({
+        success: false,
+        error: expect.stringContaining('Insufficient role'),
+        status: 403,
+      })
+    })
+  })
+
+  describe('All error responses should be JSON', () => {
+    it('should never return plain text error', async () => {
+      const client = createTestClient()
+
+      const res = await client.api.admin.stats.$get()
+
+      const text = await res.text()
+
+      expect(() => JSON.parse(text)).not.toThrow()
+
+      expect(text.trim().startsWith('{')).toBe(true)
+      expect(text.trim().endsWith('}')).toBe(true)
+    })
+  })
+})