Files

T

weichenandCursor 7647215513 docs(ops): land Phase 2 Track E/S/P plans onto a legal feature branch

Move the reviewed durable-event, HTTP envelope, and PI typed-result
designs off the docs/ prefix so Track E can start from latest dev.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-09-15 08:11:29 +00:00

2.8 KiB

Raw Blame History

title, status, created, updated

title	status	created	updated
HTTP 与 SSE 公开错误信封整改	planned	2026-09-15	2026-09-15

HTTP 与 SSE 公开错误信封整改

背景

Phase 2 复核确认错误信封涉及全部 HTTP 路由、SSE transport 和前端解析，属于独立 wire-contract 改造，不应阻塞持久事件交付。审阅见模块解耦 Phase 2 方案审阅。

目标

所有公开 HTTP/SSE 错误使用版本化、可脱敏、可测试的信封；客户端按 typed code 分支，不解析任意后端文案。迁移保持 additive，breaking 状态码变化必须另写 ADR。

契约

基础字段：code、固定安全 message、request_id、可选 details。
每个 code 单独维护 details 公开字段 allowlist；默认空。
禁止输出 raw error、SQL、堆栈、绝对路径、凭证、prompt、正文和跨租户资源 ID。
授权失败保持资源存在性不泄露；404/403 选择由现有授权策略决定。
VERSION_CONFLICT、IDEMPOTENCY_CONFLICT、VALIDATION、AUTHZ 先建立领域错误到 wire code 的唯一映射。
SSE error frame 与 HTTP 使用同一 code registry 和脱敏器，保留 transport 所需 event metadata。

分波次计划

波次	内容	验收
H0	盘点路由、现有状态码、前端文本匹配和 SSE error frame	路由矩阵与兼容风险签字
H1	新增 envelope/code registry/request ID/details allowlist，旧字段 additive 保留	schema/golden/negative tests
H2	前端逐 code 迁移，未知 code 显示安全通用错误	浏览器覆盖冲突、鉴权、校验、未知 code
H3	删除文本匹配和旧字段；若改变状态码先 ADR	全路由 contract test；回滚窗口关闭

权限与安全验收

未授权用户无法从 code/message/details 区分资源存在性、owner 或项目成员。
任何 internal error 都只返回 request ID；完整诊断仅在受控服务端日志，且经过字段脱敏。
结构化 validation details 只包含公开字段名和稳定错误码，不回显原始输入。
日志按 request ID 关联，不把响应脱敏前对象序列化。

验收标准

HTTP 与 SSE schema/golden 入 CI，所有公开端点有矩阵。
前端不再按 message substring 分支。
XSS、路径/SQL/token/prompt/跨租户 ID 泄露负例通过。
additive、switch、contract、rollback 各有 test report。
未改变的状态码保持兼容；breaking 变更有 ADR 与同步发布计划。

2.8 KiB Raw Blame History

HTTP 与 SSE 公开错误信封整改

背景

目标

契约

分波次计划

权限与安全验收

验收标准

相关链接

2.8 KiB

Raw Blame History