# 安全功能

本文档概述了 MCP 代理系统中实现的全面的安全功能。

## 标签即 OAuth 范围安全模型

### 核心概念

标签使用 `tag:{tag-name}` 格式（例如 `tag:web`、`tag:db`）映射到 OAuth 2.1 范围。这提供了细粒度的访问控制，客户端只能访问已明确授予其范围权限的服务器。

### 安全优势

- **细粒度的访问控制**：客户端只能访问授权的服务器
- **标准合规性**：正确使用 OAuth 2.1 范围
- **用户同意**：通过 Web 界面明确批准请求的权限
- **故障安全设计**：在任何验证失败时拒绝访问
- **范围过期**：范围随访问令牌一起过期

## 范围验证安全

### 输入验证 (`src/utils/scopeValidation.ts`)

- **严格的格式验证**：只允许 `tag:[a-zA-Z0-9_-]+` 模式
- **长度限制**：最大范围和标签长度强制执行
- **注入预防**：阻止路径遍历、命令注入和特殊字符
- **计数限制**：每个请求的最大范围数
- **重复检测**：防止请求中出现重复范围

### 白名单方法

- 范围仅根据可用的服务器标签进行验证
- 不允许通配符或模式匹配
- 具有全面错误日志记录的故障安全验证

## 身份验证和授权

### OAuth 2.1 实现 (`src/auth/sdkOAuthServerProvider.ts`)

- **PKCE 支持**：防止授权码拦截
- **客户端注册**：带有验证的动态客户端注册
- **令牌管理**：安全的令牌生成、验证和撤销
- **会话管理**：带有过期的安全会话存储
- **基于 Web 的同意**：用于范围批准的用户友好同意界面

### 基于范围的授权中间件 (`src/transport/http/middlewares/scopeAuthMiddleware.ts`)

- **令牌验证**：在每个请求上验证不记名令牌
- **范围强制执行**：确保请求的标签被授予的范围所覆盖
- **向后兼容性**：在禁用身份验证时无缝工作
- **故障安全设计**：在任何错误条件下拒绝访问

## 速率限制

### 多层速率限制

1. **通用 OAuth 端点**：OAuth 操作的标准速率限制
2. **敏感操作**：对同意和令牌操作进行更严格的速率限制
3. **自适应限制**：不同操作类型的不同限制

### 速率限制功能

- **基于 IP 的限制**：防止来自特定地址的滥用
- **时间窗口控制**：可配置的速率限制时间窗口
- **安全日志记录**：记录速率限制违规以进行监控
- **优雅降级**：超出限制时提供适当的错误响应

## 安全中间件 (`src/transport/http/middlewares/securityMiddleware.ts`)

### 安全标头

- **X-Frame-Options**：防止点击劫持攻击
- **X-Content-Type-Options**：防止 MIME 类型嗅探
- **X-XSS-Protection**：在浏览器中启用 XSS 保护
- **Content-Security-Policy**：限制 HTML 响应的资源加载
- **Referrer-Policy**：控制引荐来源信息泄漏

### 输入验证

- **注入保护**：检测并阻止常见的注入模式
- **标头验证**：验证所有 HTTP 标头是否存在可疑内容
- **查询参数验证**：验证查询参数是否存在恶意内容
- **正文验证**：验证 POST 操作的请求正文

### 会话安全

- **缓存控制**：防止缓存敏感响应
- **机器人排除**：防止索引 OAuth 端点
- **时序攻击预防**：身份验证端点的随机延迟

## 审计日志记录

### 全面的审计跟踪 (`src/utils/scopeValidation.ts`)

- **范围操作**：所有范围验证和授权事件
- **客户端识别**：跟踪执行操作的客户端
- **成功/失败跟踪**：记录成功和失败的操作
- **时间戳记录**：所有安全事件的精确时间

### 安全事件日志记录

- **身份验证事件**：登录尝试、令牌生成、失败
- **授权事件**：范围授予、拒绝、违规
- **速率限制事件**：超出限制时
- **安全违规**：注入尝试、可疑活动

## 网络安全

### 传输安全

- **HTTPS 强制执行**：所有生产流量都通过加密连接
- **CORS 配置**：正确的跨域请求处理
- **请求大小限制**：通过大请求防止 DoS

### 错误处理

- **安全的错误响应**：错误消息中没有敏感信息
- **一致的错误格式**：标准 OAuth 2.1 错误格式
- **错误日志记录**：仅在服务器端记录详细错误

## 输入清理 (`src/utils/sanitization.ts`)

### 上下文感知清理

- **HTML 转义**：防止 HTML 响应中的 XSS
- **URL 参数清理**：安全处理 URL 参数
- **服务器名称清理**：防止通过服务器名称注入
- **错误消息清理**：安全显示错误消息

## 向后兼容性

### 禁用身份验证模式

- **优雅降级**：禁用身份验证时功能齐全
- **标签筛选保留**：禁用身份验证时保留原始标签筛选
- **配置灵活性**：运行时启用/禁用身份验证

### 迁移支持

- **增量采用**：可以逐步启用身份验证
- **现有客户端支持**：禁用身份验证时可与非 OAuth 客户端一起使用

## 安全测试

### 全面的测试覆盖率

- **单元测试**：范围验证、中间件功能
- **集成测试**：完整的身份验证流程
- **安全测试**：注入尝试、边缘情况、时序攻击
- **性能测试**：速率限制和验证的负载测试

### 安全边缘情况

- **缓冲区溢出预防**：输入长度验证
- **空字节注入预防**：输入格式验证
- **Unicode 攻击预防**：字符集限制
- **原型污染预防**：安全的对象处理

## 安全最佳实践

### 开发指南

- **最小权限原则**：授予最小必需的范围
- **故障安全设计**：默认为拒绝访问
- **深度防御**：多个安全层
- **定期安全审计**：持续的安全监控

### 操作安全

- **安全的配置默认值**：开箱即用的安全配置
- **特定于环境的设置**：每个环境的不同安全级别
- **安全监控**：实时安全事件监控
- **事件响应**：明确的安全事件响应程序

## 合规性

### 标准遵守

- **OAuth 2.1**：完全符合 OAuth 2.1 规范
- **RFC 7636**：PKCE 实现
- **OWASP Top 10**：防范常见的 Web 漏洞
- **安全标头**：遵循安全标头最佳实践

### 隐私保护

- **数据最小化**：仅收集和存储必要的数据
- **安全存储**：加密的会话和令牌存储
- **访问日志记录**：审计跟踪，不暴露敏感数据
- **用户同意**：对所有数据访问的明确同意
