create-fullstack-scaffold 0.1.0

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

@@ -0,0 +1,166 @@
+import type { Context, Next } from 'hono'
+import { getCookie, setCookie } from 'hono/cookie'
+import { randomUUID } from 'crypto'
+
+export interface CaptchaConfig {
+  skipPaths?: string[]
+  maxRequests?: number
+  windowMs?: number
+}
+
+interface CaptchaSession {
+  verified: boolean
+  verifiedAt?: number
+  requestCount: number
+  windowStart: number
+  createdAt: number
+}
+
+const MAX_SESSIONS = 1000
+const SESSION_TTL = 5 * 60 * 1000
+
+const captchaSessions = new Map<string, CaptchaSession>()
+
+function cleanupExpiredSessions() {
+  const now = Date.now()
+  for (const [key, session] of captchaSessions) {
+    if (now - session.createdAt > SESSION_TTL) {
+      captchaSessions.delete(key)
+    }
+  }
+  if (captchaSessions.size > MAX_SESSIONS) {
+    const entries = [...captchaSessions.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt)
+    const toDelete = entries.slice(0, captchaSessions.size - MAX_SESSIONS)
+    for (const [key] of toDelete) captchaSessions.delete(key)
+  }
+}
+
+export function captchaMiddleware(config: CaptchaConfig = {}) {
+  const {
+    skipPaths = ['/api/captcha', '/api/verify-captcha', '/api/admin/login', '/api/admin/register'],
+    maxRequests = 10,
+    windowMs = 60000,
+  } = config
+
+  return async (c: Context, next: Next) => {
+    if (process.env.NODE_ENV === 'test') {
+      return next()
+    }
+
+    cleanupExpiredSessions()
+
+    const path = c.req.path
+
+    if (skipPaths.some(skipPath => path.startsWith(skipPath))) {
+      return next()
+    }
+
+    const sessionId = getCookie(c, 'session_id') || generateSessionId()
+
+    if (!getCookie(c, 'session_id')) {
+      setCookie(c, 'session_id', sessionId, {
+        httpOnly: true,
+        secure: process.env.NODE_ENV === 'production',
+        sameSite: 'Strict',
+        maxAge: 86400,
+      })
+    }
+
+    const now = Date.now()
+    const session = captchaSessions.get(sessionId) || {
+      verified: false,
+      requestCount: 0,
+      windowStart: now,
+      createdAt: now,
+    }
+
+    if (now - session.windowStart > windowMs) {
+      session.requestCount = 0
+      session.windowStart = now
+    }
+
+    session.requestCount++
+    captchaSessions.set(sessionId, session)
+
+    if (session.verified && session.verifiedAt && now - session.verifiedAt < 300000) {
+      return next()
+    }
+
+    if (session.requestCount > maxRequests) {
+      return c.json(
+        {
+          success: false as const,
+          error: '请求过于频繁，请完成验证码验证',
+          needCaptcha: true,
+        },
+        429
+      )
+    }
+
+    if (isSuspiciousRequest(c)) {
+      return c.json(
+        {
+          success: false as const,
+          error: '检测到可疑行为，请完成验证码验证',
+          needCaptcha: true,
+        },
+        403
+      )
+    }
+
+    return next()
+  }
+}
+
+export function verifyCaptchaMiddleware() {
+  return async (c: Context, next: Next) => {
+    const sessionId = getCookie(c, 'session_id')
+
+    if (!sessionId) {
+      return c.json({ success: false as const, error: 'Session not found' }, 400)
+    }
+
+    const session = captchaSessions.get(sessionId)
+
+    if (session) {
+      session.verified = true
+      session.verifiedAt = Date.now()
+      captchaSessions.set(sessionId, session)
+    }
+
+    return next()
+  }
+}
+
+function generateSessionId(): string {
+  return randomUUID()
+}
+
+function isSuspiciousRequest(c: Context): boolean {
+  const userAgent = c.req.header('User-Agent') || ''
+
+  if (!userAgent || userAgent.length < 10) {
+    return true
+  }
+
+  if (userAgent.includes('bot') || userAgent.includes('crawler')) {
+    return true
+  }
+
+  return false
+}
+
+export function markCaptchaVerifiedMiddleware(sessionId: string) {
+  const session = captchaSessions.get(sessionId)
+  if (session) {
+    session.verified = true
+    session.verifiedAt = Date.now()
+    session.requestCount = 0
+    session.windowStart = Date.now()
+    captchaSessions.set(sessionId, session)
+  }
+}
+
+export function clearCaptchaSessionMiddleware(sessionId: string) {
+  captchaSessions.delete(sessionId)
+}

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

@@ -0,0 +1,30 @@
+import type { MiddlewareHandler } from 'hono'
+import { cors } from 'hono/cors'
+
+export type CorsOptions = {
+  origin?: string | string[]
+  credentials?: boolean
+  allowMethods?: string[]
+  allowHeaders?: string[]
+  exposeHeaders?: string[]
+  maxAge?: number
+}
+
+const defaultCorsOptions: Required<Omit<CorsOptions, 'exposeHeaders' | 'maxAge'>> & CorsOptions = {
+  origin: process.env.NODE_ENV === 'production'
+    ? (process.env.CORS_ORIGIN?.split(',') || [])
+    : ['http://localhost:5173', 'http://localhost:3010'],
+  credentials: true,
+  allowMethods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+  allowHeaders: ['Content-Type', 'Authorization'],
+}
+
+export function corsMiddleware(options: CorsOptions = {}): MiddlewareHandler {
+  const mergedOptions = { ...defaultCorsOptions, ...options }
+
+  return cors(mergedOptions as never)
+}
+
+export function createCorsMiddleware(options: CorsOptions = {}) {
+  return corsMiddleware(options)
+}

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

@@ -0,0 +1,135 @@
+import type { MiddlewareHandler } from 'hono'
+import { HTTPException } from 'hono/http-exception'
+import { ZodError } from 'zod'
+import { createModuleLoggerSync } from '../utils/logger'
+import type { LogFnFields } from '../utils/logger'
+import { AppError } from '../utils/app-error'
+
+export type ErrorHandlerOptions = {
+  includeStackTrace?: boolean
+  logErrors?: boolean
+}
+
+const defaultErrorHandlerOptions: ErrorHandlerOptions = {
+  includeStackTrace: false,
+  logErrors: true,
+}
+
+type ZodIssueFormatted = {
+  field: string
+  message: string
+  code?: string
+}
+
+function formatZodError(error: ZodError): ZodIssueFormatted[] {
+  return error.issues.map(issue => ({
+    field: issue.path.join('.'),
+    message: issue.message,
+    code: issue.code,
+  }))
+}
+
+function createErrorResponse(status: number, message: string, details?: unknown) {
+  const response: { success: false; error: string; status: number; details?: unknown } = {
+    success: false as const,
+    error: message,
+    status,
+  }
+  if (details) {
+    response.details = details
+  }
+  return response
+}
+
+export function errorHandlerMiddleware(options: ErrorHandlerOptions = {}): MiddlewareHandler {
+  const mergedOptions = { ...defaultErrorHandlerOptions, ...options }
+  const log = createModuleLoggerSync('api')
+
+  return async (c, next) => {
+    try {
+      await next()
+    } catch (error) {
+      // Always return JSON response
+      c.res.headers.set('Content-Type', 'application/json')
+
+      if (AppError.isAppError(error)) {
+        if (mergedOptions.logErrors) {
+          const fields: LogFnFields = {
+            errorType: error.name,
+            code: error.code,
+            message: error.message,
+            status: error.statusCode,
+            path: c.req.path,
+            method: c.req.method,
+          }
+          log.warn(fields, error.message)
+        }
+
+        return c.json(createErrorResponse(error.statusCode, error.message, error.details), error.statusCode as import('hono/utils/http-status').ContentfulStatusCode)
+      }
+
+      if (error instanceof ZodError) {
+        const formattedErrors = formatZodError(error)
+
+        if (mergedOptions.logErrors) {
+          const fields: LogFnFields = {
+            errorType: 'ZodError',
+            errors: formattedErrors,
+            path: c.req.path,
+            method: c.req.method,
+          }
+          log.warn(fields, 'Validation error')
+        }
+
+        return c.json(createErrorResponse(400, 'Validation failed', formattedErrors), 400)
+      }
+
+      if (error instanceof HTTPException) {
+        if (mergedOptions.logErrors) {
+          const fields: LogFnFields = {
+            errorType: 'HTTPException',
+            error: error.message,
+            status: error.status,
+            path: c.req.path,
+            method: c.req.method,
+            cause: error.cause,
+          }
+          log.warn(fields, 'HTTP exception')
+        }
+
+        // Ensure we always return JSON even if HTTPException has a text response
+        const status = error.status || 500
+        const message = error.message || 'Internal server error'
+        return c.json(createErrorResponse(status, message), status)
+      }
+
+      if (mergedOptions.logErrors) {
+        const fields: LogFnFields = {
+          errorType: 'UnknownError',
+          error: error instanceof Error ? error.message : 'Unknown error',
+          stack: error instanceof Error ? error.stack : undefined,
+          path: c.req.path,
+          method: c.req.method,
+        }
+        log.error(fields, 'Unhandled error')
+      }
+
+      const message = error instanceof Error ? error.message : 'Internal server error'
+      const response: { success: false; error: string; status: number; stack?: string } = {
+        success: false as const,
+        error: message,
+        status: 500,
+      }
+
+      if (mergedOptions.includeStackTrace && error instanceof Error && error.stack) {
+        response.stack = error.stack
+      }
+
+      return c.json(response, 500)
+    }
+  }
+}
+
+export function createErrorHandlerMiddleware(options: ErrorHandlerOptions = {}) {
+  return errorHandlerMiddleware(options)
+}

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

@@ -0,0 +1,24 @@
+export { corsMiddleware, createCorsMiddleware, type CorsOptions } from './cors'
+export { loggerMiddleware, createLoggerMiddleware, type LoggerOptions } from './logger'
+export {
+  errorHandlerMiddleware,
+  createErrorHandlerMiddleware,
+  type ErrorHandlerOptions,
+} from './error-handler'
+export {
+  authMiddleware,
+  requireSuperAdminMiddleware,
+  requireCustomerServiceMiddleware,
+  requirePermissionsMiddleware,
+  type AuthUser,
+  type AuthMiddlewareOptions,
+} from './auth'
+export {
+  captchaMiddleware,
+  markCaptchaVerifiedMiddleware,
+  clearCaptchaSessionMiddleware,
+  type CaptchaConfig,
+} from './captcha'
+export { permissionMiddleware } from './permission'
+export { rateLimitMiddleware, type RateLimitOptions } from './rate-limit'
+export { getAuthUser } from '../utils/auth'

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

@@ -0,0 +1,73 @@
+import type { MiddlewareHandler } from 'hono'
+import { createModuleLoggerSync } from '../utils/logger'
+import type { LogFnFields } from '../utils/logger'
+
+export type LoggerOptions = {
+  logRequests?: boolean
+  logResponses?: boolean
+  logErrors?: boolean
+  excludePaths?: string[]
+}
+
+const defaultLoggerOptions: LoggerOptions = {
+  logRequests: true,
+  logResponses: true,
+  logErrors: true,
+  excludePaths: ['/health'],
+}
+
+export function loggerMiddleware(options: LoggerOptions = {}): MiddlewareHandler {
+  const mergedOptions = { ...defaultLoggerOptions, ...options }
+  const log = createModuleLoggerSync('api')
+
+  return async (c, next) => {
+    const { req } = c
+    const path = new URL(req.url).pathname
+
+    if (mergedOptions.excludePaths?.some(p => path.startsWith(p))) {
+      return next()
+    }
+
+    const startTime = Date.now()
+
+    if (mergedOptions.logRequests) {
+      const fields: LogFnFields = {
+        method: req.method,
+        path,
+        userAgent: req.header('user-agent'),
+      }
+      log.info(fields, 'Request started')
+    }
+
+    try {
+      await next()
+
+      if (mergedOptions.logResponses) {
+        const duration = Date.now() - startTime
+        const fields: LogFnFields = {
+          method: req.method,
+          path,
+          status: c.res?.status,
+          duration: `${duration}ms`,
+        }
+        log.info(fields, 'Request completed')
+      }
+    } catch (error) {
+      if (mergedOptions.logErrors) {
+        const duration = Date.now() - startTime
+        const fields: LogFnFields = {
+          method: req.method,
+          path,
+          error: error instanceof Error ? error.message : 'Unknown error',
+          duration: `${duration}ms`,
+        }
+        log.error(fields, 'Request failed')
+      }
+      throw error
+    }
+  }
+}
+
+export function createLoggerMiddleware(options: LoggerOptions = {}) {
+  return loggerMiddleware(options)
+}

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

@@ -0,0 +1,127 @@
+import { MiddlewareHandler } from 'hono'
+import { getAuthUser } from '../utils/auth'
+import { permissionService } from '../module-permission/services/permission-service-impl'
+import { roleService } from '../module-permission/services/role-service'
+import { logger } from '../utils/logger'
+
+const log = logger.api()
+
+interface RouteConfig {
+  path: string
+  method: string
+  isPublic: boolean
+  permissions: string[]
+}
+
+const publicRoutes: RouteConfig[] = [
+  { path: '/api/admin/login', method: 'POST', isPublic: true, permissions: [] },
+  { path: '/api/admin/register', method: 'POST', isPublic: true, permissions: [] },
+  { path: '/api/permissions', method: 'GET', isPublic: true, permissions: [] },
+  { path: '/api/permissions/roles', method: 'GET', isPublic: true, permissions: [] },
+  { path: '/api/permissions/categories', method: 'GET', isPublic: true, permissions: [] },
+  { path: '/api/permissions/role-labels', method: 'GET', isPublic: true, permissions: [] },
+  { path: '/api/permissions/permission-labels', method: 'GET', isPublic: true, permissions: [] },
+  { path: '/api/permissions/menu-config', method: 'GET', isPublic: true, permissions: [] },
+  { path: '/api/permissions/page-permissions', method: 'GET', isPublic: true, permissions: [] },
+  { path: '/api/public/contents', method: 'GET', isPublic: true, permissions: [] },
+  { path: '/api/public/contents/:id', method: 'GET', isPublic: true, permissions: [] },
+]
+
+const permissionRoutes: RouteConfig[] = [
+  { path: '/api/admin/users', method: 'GET', isPublic: false, permissions: ['user:view'] },
+  { path: '/api/admin/users', method: 'POST', isPublic: false, permissions: ['user:create'] },
+  { path: '/api/admin/users/:id', method: 'PUT', isPublic: false, permissions: ['user:edit'] },
+  { path: '/api/admin/users/:id', method: 'DELETE', isPublic: false, permissions: ['user:delete'] },
+  { path: '/api/content', method: 'GET', isPublic: false, permissions: ['content:view'] },
+  { path: '/api/content', method: 'POST', isPublic: false, permissions: ['content:create'] },
+  { path: '/api/content/:id', method: 'PUT', isPublic: false, permissions: ['content:edit'] },
+  { path: '/api/content/:id', method: 'DELETE', isPublic: false, permissions: ['content:delete'] },
+  { path: '/api/admin/settings', method: 'GET', isPublic: false, permissions: ['system:settings'] },
+  { path: '/api/admin/settings', method: 'PUT', isPublic: false, permissions: ['system:settings'] },
+  { path: '/api/admin/logs', method: 'GET', isPublic: false, permissions: ['system:logs'] },
+]
+
+function matchRoute(requestPath: string, requestMethod: string): RouteConfig | undefined {
+  const publicRoute = publicRoutes.find(r => r.path === requestPath && r.method === requestMethod)
+  if (publicRoute) return publicRoute
+
+  for (const route of permissionRoutes) {
+    const routeParts = route.path.split('/')
+    const requestParts = requestPath.split('/')
+
+    if (routeParts.length !== requestParts.length || route.method !== requestMethod) {
+      continue
+    }
+
+    let match = true
+    for (let i = 0; i < routeParts.length; i++) {
+      if (routeParts[i].startsWith(':')) {
+        continue
+      }
+      if (routeParts[i] !== requestParts[i]) {
+        match = false
+        break
+      }
+    }
+
+    if (match) return route
+  }
+
+  return undefined
+}
+
+export function permissionMiddleware(): MiddlewareHandler {
+  return async (c, next) => {
+    const path = c.req.path
+    const method = c.req.method
+
+    const routeConfig = matchRoute(path, method)
+
+    if (!routeConfig || routeConfig.isPublic) {
+      return next()
+    }
+
+    const user = getAuthUser(c)
+    if (!user) {
+      // 没有用户信息，跳过权限检查，让路由的认证中间件处理
+      return next()
+    }
+
+    if (routeConfig.permissions.length === 0) {
+      return next()
+    }
+
+    log.info(
+      { path, method, userId: user.id, requiredPermissions: routeConfig.permissions },
+      'Checking permissions'
+    )
+
+    const userRoles = await roleService.getUserRoles(user.id)
+    const isSuperAdmin = userRoles.some(r => r.code === 'super_admin')
+
+    if (isSuperAdmin) {
+      log.info({ userId: user.id }, 'User is super admin, allowing access')
+      return next()
+    }
+
+    for (const permissionCode of routeConfig.permissions) {
+      const hasPermission = await permissionService.hasPermission(user.id, permissionCode)
+      log.info({ userId: user.id, permissionCode, hasPermission }, 'Permission check result')
+      if (hasPermission) {
+        return next()
+      }
+    }
+
+    log.warn(
+      { path, method, userId: user.id, requiredPermissions: routeConfig.permissions },
+      'Forbidden: no permission'
+    )
+    return c.json(
+      {
+        success: false as const,
+        error: 'Forbidden: You do not have permission to access this resource',
+      },
+      403
+    )
+  }
+}

package/template/src/server/middleware/rate-limit.ts

@@ -0,0 +1,69 @@
+import type { Context, Next } from 'hono'
+
+type RateLimitEntry = { count: number; resetAt: number }
+
+const rateLimitStore = new Map<string, RateLimitEntry>()
+
+setInterval(() => {
+  const now = Date.now()
+  for (const [key, entry] of rateLimitStore) {
+    if (entry.resetAt <= now) {
+      rateLimitStore.delete(key)
+    }
+  }
+}, 60_000)
+
+export type RateLimitOptions = {
+  windowMs?: number
+  max?: number
+  message?: string
+}
+
+export function rateLimitMiddleware(options: RateLimitOptions = {}) {
+  const windowMs = options.windowMs ?? 60_000
+  const max = options.max ?? 100
+  const message = options.message ?? 'Too many requests'
+
+  return async (c: Context, next: Next) => {
+    if (process.env.NODE_ENV === 'test') {
+      return next()
+    }
+
+    const ip =
+      c.req.header('x-forwarded-for')?.split(',')[0]?.trim() ||
+      c.req.header('x-real-ip') ||
+      'unknown'
+    const now = Date.now()
+    const entry = rateLimitStore.get(ip)
+
+    if (entry && entry.resetAt > now && entry.count >= max) {
+      c.header('Retry-After', String(Math.ceil((entry.resetAt - now) / 1000)))
+      return c.json({ success: false as const, error: message }, 429)
+    }
+
+    if (!entry || entry.resetAt <= now) {
+      rateLimitStore.set(ip, { count: 1, resetAt: now + windowMs })
+    } else {
+      entry.count++
+    }
+
+    await next()
+  }
+}
+
+export const strictRateLimitMiddleware = rateLimitMiddleware({
+  windowMs: 15 * 60_000,
+  max: 5,
+  message: 'Too many attempts, please try again later',
+})
+
+export const mediumRateLimitMiddleware = rateLimitMiddleware({
+  windowMs: 60_000,
+  max: 20,
+  message: 'Too many upload requests, please slow down',
+})
+
+export const standardRateLimitMiddleware = rateLimitMiddleware({
+  windowMs: 60_000,
+  max: 100,
+})

package/template/src/server/middleware/realtime-env.ts

@@ -0,0 +1,12 @@
+import type { MiddlewareHandler } from 'hono'
+import { setRealtimeEnv } from '../core/index'
+
+export function realtimeEnvMiddleware(): MiddlewareHandler {
+  return async (c, next) => {
+    const env = c.env as { REALTIME_DO?: DurableObjectNamespace } | undefined
+    if (env) {
+      setRealtimeEnv(env)
+    }
+    await next()
+  }
+}