148 lines
4.9 KiB
Markdown
148 lines
4.9 KiB
Markdown
# TH Hotel SuperAgent MCP 安全策略
|
||
|
||
## 1. 文档信息
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 文档版本 | 0.1 |
|
||
| 日期 | 2026-07-09 |
|
||
| 状态 | 草案 |
|
||
| 适用范围 | `server/` 内嵌 SuperAgent MCP endpoint 安全、权限和日志边界 |
|
||
|
||
## 2. 安全目标
|
||
|
||
内嵌 MCP endpoint 的安全目标是：
|
||
|
||
- 让 SuperAgent 通过语义化工具调用业务能力。
|
||
- 不让 SuperAgent 直接接触后端 HMAC secret。
|
||
- 不绕过现有后端鉴权、幂等、审计和业务校验。
|
||
- 不返回附件 URL、原始未清洗 HTML、客户敏感信息或生产 Secret。
|
||
- 对写操作建立清晰边界。
|
||
|
||
## 3. 两层鉴权
|
||
|
||
### 3.1 SuperAgent 到 MCP Endpoint
|
||
|
||
建议使用 MCP 层访问凭证：
|
||
|
||
```text
|
||
Authorization: Bearer <MCP_AUTH_TOKEN>
|
||
```
|
||
|
||
中文说明：
|
||
|
||
- `MCP_AUTH_TOKEN` 用于限制谁可以调用后端内嵌 MCP endpoint。
|
||
- 该 token 与后端 HMAC secret 不是同一个值。
|
||
- 该 token 应是高熵随机字符串，不使用手机号、项目名、酒店名、固定短语或可猜测文本。
|
||
- dev、test、prod 必须使用不同 token，生产 token 建议至少 32 字节随机值。
|
||
- token 应通过部署平台 Secret 或安全通道交付，不写入仓库。
|
||
|
||
### 3.2 MCP Endpoint 到业务 Service
|
||
|
||
MCP endpoint 与后端业务 Service 同进程，不再通过 HMAC REST 调用本后端。
|
||
|
||
中文说明：
|
||
|
||
- REST HMAC 规则继续用于原有 REST API。
|
||
- MCP endpoint 只校验 MCP Bearer Token。
|
||
- MCP endpoint 必须通过现有 Service 进入业务逻辑，不能直接访问 Mapper 或数据库。
|
||
- SuperAgent 不需要知道 REST HMAC 签名串，也不能拿到 REST HMAC secret。
|
||
|
||
## 4. Tool 权限边界
|
||
|
||
| Tool | 权限级别 | 安全说明 |
|
||
| --- | --- | --- |
|
||
| `th_hotel_query_case_context` | 只读 | 不写订单、不写任务、不写 OPERA |
|
||
| `th_hotel_query_object_detail` | 只读 | 不写订单、不写任务、不写 OPERA |
|
||
| `th_hotel_list_message_conversation_tasks` | 只读 | 不创建任务、不修改任务 |
|
||
| `th_hotel_list_message_conversation_messages` | 受控读取 | 读取正文会写后端访问审计 |
|
||
| `th_hotel_submit_task_results` | 写入 | 只接受 M002 V4 payload；写 AI 过渡层、V4 订单任务、V4 任务卡或 V4 来源通知，不写旧 V2/V3 任务 |
|
||
|
||
写入工具要求：
|
||
|
||
- dev/test 可以用于联调。
|
||
- prod 必须经过上线审批后启用。
|
||
- 生产建议保留独立开关，例如 `MCP_ENABLE_SUBMIT_TASK_RESULTS=true`。
|
||
- 旧 V2/V3 submit payload 必须返回 `MCP_SUBMIT_V4_REQUIRED`，不能进入业务写入 Service。
|
||
- 日志必须能定位调用方、request id、trace id 和 source message，但不能输出正文和 Secret。
|
||
|
||
## 5. 邮件正文和附件边界
|
||
|
||
`th_hotel_list_message_conversation_messages` 只允许返回受控正文。
|
||
|
||
禁止返回：
|
||
|
||
- 原始未清洗 HTML。
|
||
- 附件 URL。
|
||
- 内嵌图片 URL。
|
||
- `attachments`、`inline_images`、`external_url`。
|
||
- HTML 中的 `href/src` 外链属性。
|
||
|
||
如果 SuperAgent 后续需要附件内容，应新增独立的受控附件接口和权限策略，不能复用当前正文工具绕过限制。
|
||
|
||
## 6. ID 边界
|
||
|
||
SuperAgent 可以使用：
|
||
|
||
- `hotel_id`
|
||
- 外部 `source_message_id`
|
||
- `external_conversation_id`
|
||
- 业务 key，例如 `group_code`、`confirmation_number`
|
||
|
||
SuperAgent 不应依赖：
|
||
|
||
- 内部 SourceMessage Inbox ID。
|
||
- 数据库主键表达业务含义。
|
||
- 前端内部路由或展示字段。
|
||
|
||
接口响应中如果出现内部 ID，只能用于本系统排查或后续本系统 API 的对象定位，不应当作外部系统稳定业务 ID。
|
||
|
||
## 7. 日志与脱敏
|
||
|
||
MCP endpoint 日志允许记录：
|
||
|
||
- tool 名称。
|
||
- request id。
|
||
- trace id。
|
||
- hotel id。
|
||
- 外部 source message id。
|
||
- HTTP 状态码。
|
||
- 错误码。
|
||
- 调用耗时。
|
||
|
||
禁止记录：
|
||
|
||
- REST HMAC secret。
|
||
- MCP auth token。
|
||
- 完整 HMAC signature。
|
||
- 原始邮件正文。
|
||
- 附件 URL。
|
||
- 客户证件、支付信息、Token、Cookie。
|
||
- 未清洗 HTML。
|
||
|
||
## 8. 重试策略
|
||
|
||
只读工具：
|
||
|
||
- MCP endpoint 与业务 Service 同进程，不做 HTTP 重试。
|
||
- 如果内部 Service 返回受控错误，应原样包装为 tool result。
|
||
|
||
写入工具：
|
||
|
||
- 默认不自动重试已发送的写请求。
|
||
- MCP submit payload adapter 校验失败时，不调用业务写入 Service，也不触发自动重试。
|
||
- 如果调用方需要重试，必须依赖后端幂等机制和任务结果中的幂等信息。
|
||
- 对于响应丢失但请求可能已到达后端的场景，应优先查询已有任务或人工排查，避免重复写入。
|
||
|
||
## 9. 生产上线前检查
|
||
|
||
上线前必须确认：
|
||
|
||
- 生产 `MCP_AUTH_TOKEN` 已通过 Secret 注入。
|
||
- `MCP_MAX_BODY_BYTES` 已确认，默认 10MB。
|
||
- dev/test 临时 token 没有进入生产。
|
||
- 日志脱敏规则已经生效。
|
||
- 写入工具生产开关已经明确。
|
||
- 所有接口只暴露在 HTTPS 和可信网络边界内。
|
||
- 监控覆盖 `/mcp` 可用性、tool 调用失败率和写入错误率。
|