中间件与权限控制实践指南和技术原理

// middleware/auth.global.ts
export default defineNuxtRouteMiddleware((to) => {
  console.log('全局中间件执行时机：', {
    执行阶段: '路由导航前',
    执行环境: process.client ? '客户端' : '服务端',
    目标路由: to.path,
    执行时间: Date.now()
  })
  
  // 获取用户认证状态
  const { $auth } = useNuxtApp()
  const user = useAuthUser()
  
  // 白名单路由检查
  const publicRoutes = ['/login', '/register', '/forgot-password', '/']
  const isPublicRoute = publicRoutes.some(route => 
    to.path.startsWith(route)
  )
  
  // 权限验证逻辑
  if (!isPublicRoute && !user.value) {
    console.warn('未授权访问尝试：', {
      targetRoute: to.path,
      userAgent: process.client ? navigator.userAgent : 'SSR',
      timestamp: new Date().toISOString()
    })
    
    // 保存目标路由用于登录后重定向
    if (process.client) {
      localStorage.setItem('redirectAfterAuth', to.fullPath)
    }
    
    return navigateTo('/login')
  }
})

// middleware/security.global.ts
export default defineNuxtRouteMiddleware((to, from) => {
  // 安全策略检查
  const securityChecks = {
    // 1. 检查恶意路由模式
    validateRouteSecurity: () => {
      const suspiciousPatterns = [
        /\.\.\//, // 路径遍历攻击
        /<script/, // XSS 攻击模式
        /union.*select/i, // SQL 注入模式
      ]
      
      return !suspiciousPatterns.some(pattern => 
        pattern.test(to.path)
      )
    },
    
    // 2. 检查访问频率限制
    validateRateLimit: () => {
      if (process.client) {
        const requestLog = JSON.parse(
          localStorage.getItem('requestLog') || '[]'
        )
        const now = Date.now()
        const recentRequests = requestLog.filter(
          (timestamp: number) => now - timestamp < 60000 // 1分钟内
        )
        
        if (recentRequests.length > 100) {
          console.warn('检测到异常访问频率')
          return false
        }
        
        requestLog.push(now)
        localStorage.setItem('requestLog', JSON.stringify(
          requestLog.slice(-50) // 保留最近50条记录
        ))
      }
      return true
    },
    
    // 3. 检查设备指纹
    validateDeviceFingerprint: () => {
      if (process.client && from) {
        const deviceInfo = {
          userAgent: navigator.userAgent,
          screen: `${screen.width}x${screen.height}`,
          timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
          language: navigator.language
        }
        
        const fingerprint = btoa(JSON.stringify(deviceInfo))
        const storedFingerprint = localStorage.getItem('deviceFingerprint')
        
        if (storedFingerprint && storedFingerprint !== fingerprint) {
          console.warn('设备指纹变化检测')
          // 可以触发额外验证或登出
        } else {
          localStorage.setItem('deviceFingerprint', fingerprint)
        }
      }
      return true
    }
  }
  
  // 执行安全检查
  const securityPassed = Object.values(securityChecks).every(check => check())
  
  if (!securityPassed) {
    throw createError({
      statusCode: 403,
      statusMessage: '安全检查失败',
      data: { timestamp: new Date().toISOString() }
    })
  }
})

// middleware/admin.ts
export default defineNuxtRouteMiddleware((to) => {
  const user = useAuthUser()
  
  // 角色权限检查
  if (!user.value || !user.value.roles?.includes('admin')) {
    throw createError({
      statusCode: 403,
      statusMessage: '需要管理员权限才能访问此页面'
    })
  }
})

// middleware/subscription.ts
export default defineNuxtRouteMiddleware((to) => {
  const user = useAuthUser()
  
  // 订阅状态检查
  if (!user.value?.subscription?.active) {
    return navigateTo('/upgrade', {
      query: { return: to.fullPath }
    })
  }
})

// middleware/rbac.ts
interface Permission {
  resource: string
  action: string
  conditions?: Record<string, any>
}

interface Role {
  name: string
  permissions: Permission[]
  inheritance?: string[]
}

export default defineNuxtRouteMiddleware((to) => {
  const user = useAuthUser()
  const { checkPermission } = useRBAC()
  
  // 从路由元信息获取所需权限
  const requiredPermissions = to.meta.permissions as Permission[]
  
  if (!requiredPermissions || requiredPermissions.length === 0) {
    return // 无权限要求的路由
  }
  
  // RBAC 权限检查
  const hasPermission = requiredPermissions.every(permission => 
    checkPermission(user.value, permission, {
      context: {
        route: to.path,
        params: to.params,
        query: to.query
      }
    })
  )
  
  if (!hasPermission) {
    console.warn('RBAC 权限检查失败：', {
      user: user.value?.id,
      route: to.path,
      requiredPermissions,
      userRoles: user.value?.roles,
      timestamp: new Date().toISOString()
    })
    
    throw createError({
      statusCode: 403,
      statusMessage: '权限不足，无法访问此资源',
      data: {
        requiredPermissions,
        userPermissions: user.value?.permissions || []
      }
    })
  }
})

<!-- pages/admin/users.vue -->
<template>
  <div>
    <h1>用户管理</h1>
    <!-- 用户管理界面 -->
  </div>
</template>

<script setup lang="ts">
// 定义页面权限要求
definePageMeta({
  middleware: ['auth', 'rbac'],
  permissions: [
    { resource: 'users', action: 'read' },
    { resource: 'users', action: 'list' }
  ],
  layout: 'admin'
})
</script>

// server/middleware/auth.ts
export default defineEventHandler(async (event) => {
  // 只处理 API 路由
  if (!event.node.req.url?.startsWith('/api/')) {
    return
  }
  
  // 跳过公开 API
  const publicEndpoints = [
    '/api/auth/login',
    '/api/auth/register',
    '/api/auth/refresh',
    '/api/health'
  ]
  
  if (publicEndpoints.some(endpoint => 
    event.node.req.url?.startsWith(endpoint)
  )) {
    return
  }
  
  try {
    // 获取授权令牌
    const authorization = getHeader(event, 'authorization')
    if (!authorization?.startsWith('Bearer ')) {
      throw createError({
        statusCode: 401,
        statusMessage: '缺少有效的授权令牌'
      })
    }
    
    const token = authorization.slice(7)
    
    // JWT 令牌验证
    const { verifyJWT } = useJWT()
    const payload = await verifyJWT(token)
    
    // 令牌黑名单检查
    const { isTokenBlacklisted } = useTokenBlacklist()
    if (await isTokenBlacklisted(token)) {
      throw createError({
        statusCode: 401,
        statusMessage: '令牌已被吊销'
      })
    }
    
    // 用户状态检查
    const user = await getUserById(payload.userId)
    if (!user || !user.active) {
      throw createError({
        statusCode: 401,
        statusMessage: '用户账户已被禁用'
      })
    }
    
    // 将用户信息添加到请求上下文
    event.context.user = user
    event.context.tokenPayload = payload
    
  } catch (error) {
    console.error('API 认证失败：', {
      url: event.node.req.url,
      method: event.node.req.method,
      ip: getClientIP(event),
      userAgent: getHeader(event, 'user-agent'),
      error: error.message,
      timestamp: new Date().toISOString()
    })
    
    throw createError({
      statusCode: 401,
      statusMessage: '认证失败'
    })
  }
})

// composables/useJWT.ts
import * as jose from 'jose'

export const useJWT = () => {
  const runtimeConfig = useRuntimeConfig()
  
  // JWT 密钥管理
  const getSecret = () => {
    const secret = runtimeConfig.jwtSecret
    if (!secret) {
      throw new Error('JWT_SECRET 环境变量未配置')
    }
    return new TextEncoder().encode(secret)
  }
  
  // 生成 JWT 令牌
  const generateJWT = async (payload: any, options: {
    expiresIn?: string
    audience?: string
    issuer?: string
  } = {}) => {
    const secret = getSecret()
    
    const jwt = await new jose.SignJWT(payload)
      .setProtectedHeader({ alg: 'HS256' })
      .setIssuedAt()
      .setIssuer(options.issuer || 'nuxt-app')
      .setAudience(options.audience || 'nuxt-app-users')
      .setExpirationTime(options.expiresIn || '1h')
      .sign(secret)
    
    return jwt
  }
  
  // 验证 JWT 令牌
  const verifyJWT = async (token: string) => {
    try {
      const secret = getSecret()
      const { payload } = await jose.jwtVerify(token, secret, {
        issuer: 'nuxt-app',
        audience: 'nuxt-app-users'
      })
      
      return payload
    } catch (error) {
      console.error('JWT 验证失败：', error.message)
      throw new Error('无效的令牌')
    }
  }
  
  // 刷新令牌
  const refreshToken = async (token: string) => {
    try {
      const payload = await verifyJWT(token)
      
      // 检查令牌是否接近过期（剩余时间少于 15 分钟）
      const exp = payload.exp as number
      const now = Math.floor(Date.now() / 1000)
      
      if (exp - now > 15 * 60) {
        return token // 令牌仍然有效
      }
      
      // 生成新令牌
      const newPayload = {
        userId: payload.userId,
        email: payload.email,
        roles: payload.roles
      }
      
      return await generateJWT(newPayload)
    } catch (error) {
      throw new Error('令牌刷新失败')
    }
  }
  
  // 解码令牌（不验证签名）
  const decodeJWT = (token: string) => {
    try {
      return jose.decodeJwt(token)
    } catch {
      return null
    }
  }
  
  return {
    generateJWT,
    verifyJWT,
    refreshToken,
    decodeJWT
  }
}

// server/api/auth/login.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  const { email, password, rememberMe } = body
  
  // 输入验证
  if (!email || !password) {
    throw createError({
      statusCode: 400,
      statusMessage: '邮箱和密码不能为空'
    })
  }
  
  try {
    // 用户认证
    const user = await authenticateUser(email, password)
    
    if (!user) {
      // 记录登录失败日志
      await logAuthEvent({
        type: 'login_failed',
        email,
        ip: getClientIP(event),
        userAgent: getHeader(event, 'user-agent'),
        reason: 'invalid_credentials'
      })
      
      throw createError({
        statusCode: 401,
        statusMessage: '邮箱或密码错误'
      })
    }
    
    // 检查账户状态
    if (!user.active) {
      throw createError({
        statusCode: 403,
        statusMessage: '账户已被禁用'
      })
    }
    
    // 生成令牌
    const { generateJWT } = useJWT()
    const tokenPayload = {
      userId: user.id,
      email: user.email,
      roles: user.roles,
      permissions: user.permissions
    }
    
    const accessToken = await generateJWT(tokenPayload, {
      expiresIn: rememberMe ? '30d' : '1h'
    })
    
    const refreshToken = await generateJWT(
      { userId: user.id, type: 'refresh' },
      { expiresIn: '30d' }
    )
    
    // 更新用户登录信息
    await updateUserLastLogin(user.id, {
      lastLoginAt: new Date(),
      lastLoginIp: getClientIP(event),
      lastLoginUserAgent: getHeader(event, 'user-agent')
    })
    
    // 记录登录成功日志
    await logAuthEvent({
      type: 'login_success',
      userId: user.id,
      email: user.email,
      ip: getClientIP(event),
      userAgent: getHeader(event, 'user-agent')
    })
    
    // 设置安全 Cookie
    setCookie(event, 'auth-token', accessToken, {
      httpOnly: true,
      secure: true,
      sameSite: 'strict',
      maxAge: rememberMe ? 30 * 24 * 60 * 60 : 60 * 60, // 30天或1小时
      path: '/'
    })
    
    setCookie(event, 'refresh-token', refreshToken, {
      httpOnly: true,
      secure: true,
      sameSite: 'strict',
      maxAge: 30 * 24 * 60 * 60, // 30天
      path: '/api/auth'
    })
    
    return {
      user: {
        id: user.id,
        email: user.email,
        name: user.name,
        roles: user.roles,
        avatar: user.avatar
      },
      accessToken,
      expiresIn: rememberMe ? 30 * 24 * 60 * 60 : 60 * 60
    }
    
  } catch (error) {
    console.error('登录过程出错：', error)
    
    if (error.statusCode) {
      throw error
    }
    
    throw createError({
      statusCode: 500,
      statusMessage: '登录服务暂时不可用'
    })
  }
})

// server/api/auth/oauth/[provider].get.ts
export default defineEventHandler(async (event) => {
  const provider = getRouterParam(event, 'provider')
  const query = getQuery(event)
  
  const oauthConfig = {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
      redirectUri: `${process.env.BASE_URL}/api/auth/oauth/google/callback`,
      scope: 'openid email profile',
      authUrl: 'https://accounts.google.com/o/oauth2/v2/auth'
    },
    github: {
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET,
      redirectUri: `${process.env.BASE_URL}/api/auth/oauth/github/callback`,
      scope: 'user:email',
      authUrl: 'https://github.com/login/oauth/authorize'
    }
  }
  
  const config = oauthConfig[provider as keyof typeof oauthConfig]
  if (!config) {
    throw createError({
      statusCode: 400,
      statusMessage: '不支持的 OAuth 提供商'
    })
  }
  
  // 生成 state 参数防止 CSRF
  const state = generateRandomString(32)
  
  // 存储 state 到会话中
  await setSessionData(event, 'oauth_state', state)
  
  // 构建授权 URL
  const authUrl = new URL(config.authUrl)
  authUrl.searchParams.set('client_id', config.clientId)
  authUrl.searchParams.set('redirect_uri', config.redirectUri)
  authUrl.searchParams.set('scope', config.scope)
  authUrl.searchParams.set('response_type', 'code')
  authUrl.searchParams.set('state', state)
  
  if (provider === 'google') {
    authUrl.searchParams.set('access_type', 'offline')
  }
  
  return sendRedirect(event, authUrl.toString())
})

// server/utils/csrf.ts
import { randomBytes, createHmac } from 'crypto'

export class CSRFProtection {
  private secret: string
  
  constructor() {
    this.secret = process.env.CSRF_SECRET || 'default-csrf-secret'
  }
  
  // 生成 CSRF Token
  generateToken(sessionId: string): string {
    const timestamp = Date.now().toString()
    const randomValue = randomBytes(16).toString('hex')
    const payload = `${sessionId}:${timestamp}:${randomValue}`
    
    const signature = createHmac('sha256', this.secret)
      .update(payload)
      .digest('hex')
    
    return Buffer.from(`${payload}:${signature}`).toString('base64')
  }
  
  // 验证 CSRF Token
  verifyToken(token: string, sessionId: string): boolean {
    try {
      const decoded = Buffer.from(token, 'base64').toString('utf8')
      const [session, timestamp, random, signature] = decoded.split(':')
      
      // 检查会话 ID
      if (session !== sessionId) {
        return false
      }
      
      // 检查时间戳（token 有效期 1 小时）
      const tokenTime = parseInt(timestamp)
      const now = Date.now()
      if (now - tokenTime > 60 * 60 * 1000) {
        return false
      }
      
      // 验证签名
      const payload = `${session}:${timestamp}:${random}`
      const expectedSignature = createHmac('sha256', this.secret)
        .update(payload)
        .digest('hex')
      
      return signature === expectedSignature
    } catch {
      return false
    }
  }
}

const csrfProtection = new CSRFProtection()
export { csrfProtection }

// server/utils/xss-protection.ts
import DOMPurify from 'isomorphic-dompurify'
import validator from 'validator'

export class XSSProtection {
  // HTML 内容清理
  static sanitizeHTML(input: string, options: {
    allowedTags?: string[]
    allowedAttributes?: Record<string, string[]>
    strict?: boolean
  } = {}): string {
    if (!input || typeof input !== 'string') {
      return ''
    }
    
    const defaultConfig = {
      ALLOWED_TAGS: options.allowedTags || [
        'p', 'br', 'strong', 'em', 'u', 'ul', 'ol', 'li', 'h1', 'h2', 'h3'
      ],
      ALLOWED_ATTR: options.allowedAttributes || {
        'a': ['href', 'title'],
        'img': ['src', 'alt', 'title'],
        '*': ['class']
      },
      FORBID_SCRIPT: true,
      FORBID_TAGS: ['script', 'object', 'embed', 'form', 'input'],
      FORBID_ATTR: ['onclick', 'onload', 'onerror', 'onfocus']
    }
    
    if (options.strict) {
      defaultConfig.ALLOWED_TAGS = ['p', 'br', 'strong', 'em']
      defaultConfig.ALLOWED_ATTR = {}
    }
    
    return DOMPurify.sanitize(input, defaultConfig)
  }
  
  // 文本内容转义
  static escapeHTML(input: string): string {
    if (!input || typeof input !== 'string') {
      return ''
    }
    
    return validator.escape(input)
  }
  
  // 检测潜在的 XSS 攻击
  static detectXSSAttempt(input: string): boolean {
    if (!input || typeof input !== 'string') {
      return false
    }
    
    const xssPatterns = [
      /<script[\s\S]*?>/i,
      /javascript:/i,
      /on\w+\s*=/i,
      /<iframe[\s\S]*?>/i,
      /<object[\s\S]*?>/i,
      /<embed[\s\S]*?>/i,
      /expression\s*\(/i,
      /vbscript:/i,
      /@import/i,
      /binding\s*:/i
    ]
    
    return xssPatterns.some(pattern => pattern.test(input))
  }
  
  // 批量处理对象属性
  static sanitizeObject<T extends Record<string, any>>(
    obj: T,
    rules: Record<keyof T, 'html' | 'text' | 'url' | 'skip'>
  ): T {
    const sanitized = { ...obj }
    
    for (const [key, rule] of Object.entries(rules)) {
      const value = sanitized[key]
      
      if (value && typeof value === 'string') {
        switch (rule) {
          case 'html':
            sanitized[key] = this.sanitizeHTML(value)
            break
          case 'text':
            sanitized[key] = this.escapeHTML(value)
            break
          case 'url':
            sanitized[key] = this.sanitizeURL(value)
            break
          case 'skip':
            // 跳过处理
            break
        }
      }
    }
    
    return sanitized
  }
}

// server/utils/rate-limiter.ts
import { LRUCache } from 'lru-cache'

interface RateLimitRule {
  windowMs: number    // 时间窗口（毫秒）
  maxRequests: number // 最大请求数
  message?: string    // 超限消息
  skipSuccessfulRequests?: boolean // 是否跳过成功请求
  keyGenerator?: (event: any) => string // 自定义键生成器
}

export class AdvancedRateLimiter {
  private cache: LRUCache<string, number[]>
  private rules: Map<string, RateLimitRule>
  
  constructor() {
    this.cache = new LRUCache({
      max: 10000,
      ttl: 1000 * 60 * 60 // 1小时
    })
    this.rules = new Map()
  }
  
  // 添加限制规则
  addRule(pattern: string, rule: RateLimitRule) {
    this.rules.set(pattern, rule)
  }
  
  // 检查请求是否被限制
  async checkLimit(event: any): Promise<{
    allowed: boolean
    remaining: number
    resetTime: number
    totalRequests: number
  }> {
    const url = getRequestURL(event)
    const rule = this.findMatchingRule(url.pathname)
    
    if (!rule) {
      return {
        allowed: true,
        remaining: -1,
        resetTime: -1,
        totalRequests: 0
      }
    }
    
    const key = rule.keyGenerator ? 
      rule.keyGenerator(event) : 
      this.generateDefaultKey(event)
    
    const now = Date.now()
    const windowStart = now - rule.windowMs
    
    // 获取时间窗口内的请求记录
    let requests = this.cache.get(key) || []
    
    // 清理过期记录
    requests = requests.filter(timestamp => timestamp > windowStart)
    
    const currentRequests = requests.length
    
    if (currentRequests >= rule.maxRequests) {
      // 计算重置时间
      const oldestRequest = Math.min(...requests)
      const resetTime = oldestRequest + rule.windowMs
      
      return {
        allowed: false,
        remaining: 0,
        resetTime,
        totalRequests: currentRequests
      }
    }
    
    // 记录当前请求
    requests.push(now)
    this.cache.set(key, requests)
    
    return {
      allowed: true,
      remaining: rule.maxRequests - requests.length,
      resetTime: now + rule.windowMs,
      totalRequests: requests.length
    }
  }
  
  private findMatchingRule(pathname: string): RateLimitRule | null {
    for (const [pattern, rule] of this.rules) {
      if (this.matchPattern(pattern, pathname)) {
        return rule
      }
    }
    return null
  }
  
  private matchPattern(pattern: string, pathname: string): boolean {
    // 支持通配符匹配
    const regex = new RegExp(
      pattern.replace(/\*/g, '.*').replace(/\?/g, '.')
    )
    return regex.test(pathname)
  }
  
  private generateDefaultKey(event: any): string {
    const ip = getClientIP(event)
    const url = getRequestURL(event)
    const method = getMethod(event)
    
    return `${ip}:${method}:${url.pathname}`
  }
}

// 全局限制器实例
const rateLimiter = new AdvancedRateLimiter()

// 配置限制规则
rateLimiter.addRule('/api/auth/login', {
  windowMs: 15 * 60 * 1000, // 15分钟
  maxRequests: 5, // 最多5次登录尝试
  message: '登录尝试过于频繁，请稍后再试'
})

rateLimiter.addRule('/api/*', {
  windowMs: 60 * 1000, // 1分钟
  maxRequests: 100, // 通用 API 限制
  keyGenerator: (event) => {
    // 认证用户使用用户ID，未认证使用IP
    const user = event.context.user
    const ip = getClientIP(event)
    return user ? `user:${user.id}` : `ip:${ip}`
  }
})

export { rateLimiter }

// composables/useSecurityMonitoring.ts
export const useSecurityMonitoring = () => {
  // 安全事件监控
  const monitorSecurityEvent = async (event: {
    type: string
    severity: 'low' | 'medium' | 'high' | 'critical'
    details: any
    user?: any
  }) => {
    // 实时告警
    if (event.severity === 'critical') {
      await sendImmediateAlert(event)
    }
    
    // 记录到安全日志
    await logSecurityEvent(event)
    
    // 更新安全仪表板
    await updateSecurityDashboard(event)
  }
  
  // 审计日志记录
  const auditLog = async (action: {
    user: string
    action: string
    resource: string
    result: 'success' | 'failure'
    details?: any
  }) => {
    await $fetch('/api/audit/log', {
      method: 'POST',
      body: {
        ...action,
        timestamp: new Date().toISOString(),
        ip: await getClientIP(),
        userAgent: navigator.userAgent
      }
    })
  }
  
  return {
    monitorSecurityEvent,
    auditLog
  }
}