forge_admin/code-copilot/changes/framework-security-gap-hardening/spec.md

Framework Security Gap Hardening Spec

1. 状态

• 变更名：framework-security-gap-hardening
• 当前阶段：review-ready
• 发起日期：2026-08-02
• 用户授权：用户明确要求按优先级自动修复已核验问题，并要求不得影响正在并行修改的统一能力开放平台代码。

2. 背景

源码审计确认框架存在内部调用标记可伪造、WebSocket 未鉴权、租户上下文缺失时 SQL 隔离失败开放、本地文件路径未约束、防重放 nonce 非原子、登录密码加密失败降级明文等问题。另有数据权限错误放行、固定 Job Token pepper、消息部分成功状态不准确及若干低优先级技术债。

本变更按风险优先级分阶段加固，先关闭可直接跨越安全边界的入口，再处理兼容性和可观测性问题。

3. 目标

1. X-Inner-Call 只有来自显式可信源地址的请求才可跳过应用层加解密与防重放。
2. WebSocket STOMP CONNECT 必须校验 Sa-Token，服务端会话绑定真实用户，客户端不得向 broker topic/queue 直接发送消息。
3. 对需要租户隔离的表，缺失租户上下文默认失败关闭；显式忽略表和 @IgnoreTenant 场景保持可用。
4. 本地文件上传、下载、删除、分片和 bucket 操作都限制在规范化基础目录内，并拒绝路径穿越和符号链接逃逸。
5. nonce 通过原子 set-if-absent 登记，TTL 至少为时间窗口两倍。
6. 启用登录密码加密时，加密或解密失败必须拒绝登录，不再降级明文。
7. 已配置 DataScope 的查询在上下文获取或 SQL 改写失败时失败关闭；未配置 Mapper 至少提供去重告警和可选严格拒绝策略。
8. Job 开放 API 默认关闭且不再提供仓库固定 pepper；显式启用时缺少合规 pepper 必须启动失败。
9. 完成不改变协议的低风险修复：算法自适配自动密钥长度、稳定 JSON 幂等键、消息部分成功状态。
10. 对无法在缺少产品规则时安全补齐的 WorkerId 回收和流程/AI 未实现能力，采用可验证的安全收口，不伪造完成结果。

4. 非目标与并行开发隔离

本变更不修改：

• forge-server/forge-framework/forge-plugin-parent/forge-plugin-capability-*
• forge-admin-ui/src/views/ai/capability/client.vue
• 当前工作树中由并行 Agent 修改的 TenantInterceptor.java
• 当前工作树中由并行 Agent 修改的 LogProperties.java、OperationLogAspect.java
• 统一能力开放平台的协议、Token、授权、目录解析和 UI 行为

本变更不使用 git switch、不自动提交，避免改变并行 Agent 所在工作区的 HEAD。最终通过 git diff --name-only 证明未触碰上述边界。

5. 设计

5.1 内部调用边界

在 Crypto Starter 新增独立配置 forge.crypto.internal-call.trusted-addresses，默认只信任 IPv4/IPv6 loopback。校验仅使用 Servlet 容器提供的 remoteAddr，不信任可由客户端伪造的转发头。支持显式 IP 和 CIDR；生产容器或网关地址必须通过部署配置加入白名单。

三处加解密/防重放跳过逻辑统一调用同一个验证器。只有 Header 值为 true 且来源匹配白名单时才视为内部调用；伪造 Header 按普通外部请求处理并记录安全告警。

5.2 WebSocket 鉴权与消息隔离

WebSocket Starter 定义认证 SPI 和 STOMP 入站拦截器；Auth Starter 提供 Sa-Token 实现，避免 websocket/auth Maven 循环依赖。CONNECT 从 STOMP Header 读取 Bearer Token，认证成功后把 loginId 写入 Principal。

SUBSCRIBE/SEND 必须有已认证 Principal；客户端 SEND 只允许 /app/**，禁止直发 /topic/**、/queue/**、/user/**。认证类通知改为服务端 convertAndSendToUser，前端订阅 /user/queue/messages，不再广播后由浏览器按 userId 过滤。

允许 Origin 默认限制为 localhost 开发地址；生产通过 forge.websocket.allowed-origin-patterns 显式配置。

5.3 租户失败关闭

复用已有 forge.tenant.strict-mode，默认改为 true。处理顺序为：显式上下文忽略、已知非租户表、自动检测非租户表、租户上下文校验。只有确实需要租户列的表在 tenantId 缺失时抛异常；后台全局任务必须使用现有 TenantContextHolder.executeIgnore 或 @IgnoreTenant。

5.4 文件路径约束

初始化时将基础目录转为绝对规范路径。所有相对路径通过统一 resolver 解析，拒绝绝对路径、.. 逃逸、非法 businessType/bucketName 和路径中的符号链接。元数据中的历史路径同样重新校验，避免数据库污染后扩大为任意文件读删。

5.5 防重放

ReplayTokenCache 提供原子 markIfAbsent，底层使用 Redisson bucket setIfAbsent；Filter 只在登记成功后放行。TTL 使用 replayTimeWindow * 2 并检查溢出和非法窗口。

5.6 兼容性加固

• 密码：前端加密失败抛错；后端存在 RSA 密钥时解密失败抛业务异常。
• DataScope：配置存在时任何上下文/改写异常都拒绝；未配置策略支持 WARN 和 DENY，默认 WARN 保留兼容，生产可切换 DENY。
• Job Open API：Java 与 YAML 默认关闭，pepper 无默认值；启用时配置 Bean 阶段校验。
• 自动密钥：SM4 生成 16 字节，AES/AES_GCM 生成 32 字节，校验与算法一致。
• 幂等键：无 SpEL 时使用稳定 JSON 序列化参数后摘要。
• 消息：部分接收人失败时主消息和发送记录使用状态 3=部分成功，字典迁移同步增加状态。
• H5 构建：补齐构建配置直接依赖的 glob/sass，并将旧 Glob 默认导入迁移到仓库已使用的 Glob 11 API，保证登录安全改动可在干净环境构建。

6. 风险与回滚

1. 内部服务若非 loopback 调用，需要先配置真实来源 IP/CIDR，否则明文内部调用会被当作外部加密请求拒绝。回滚可临时加入精确可信网段，不允许恢复全网信任。
2. 租户严格模式可能暴露未正确建立上下文的后台任务。修复方式是补充明确的 tenantId 或 executeIgnore，不允许恢复默认 fail-open。
3. WebSocket 旧客户端若未在 CONNECT Header 携带 Token 将连接失败。Admin UI 与本变更同步升级。
4. Job Open API 未配置环境变量时将保持关闭；启用前必须注入 pepper。
5. DataScope 未配置默认保持告警，避免一次性阻断全量 Mapper；生产启用 DENY 前需先完成配置盘点。

7. 验收标准

1. 外部地址携带 X-Inner-Call: true 不再触发任何跳过路径，loopback/显式可信 CIDR 可通过。
2. 无 Token、无效 Token、客户端直发 broker 的 STOMP 帧被拒绝；有效 Token 绑定 Principal 并只能收到自己的用户队列消息。
3. tenantId 缺失访问租户表抛异常，忽略表与显式 ignore 正常。
4. ../、绝对路径、符号链接和恶意 bucket/businessType 均无法越出基础目录。
5. 并发相同 nonce 只有一次成功，TTL 为窗口两倍。
6. 密码加密失败不会发出登录请求，服务端不接受加密模式下的明文降级。
7. 目标模块单测通过，Admin UI 构建通过，Admin 聚合 package 通过。
8. capability 相关文件的工作树 diff 与本变更开始时相比没有由本变更产生的修改。

8. HARD-GATE

本变更涉及认证、权限和租户隔离。用户于 2026-08-02 明确要求“按照优先级自动修复这些问题”，并要求不影响正在并行修改的统一能力开放平台代码，视为本 Spec 的实施授权。真实生产网段、Origin、pepper 和部署回归仍是上线门禁。

9. 实施结论与剩余项

已完成内部调用来源校验、WebSocket 鉴权、租户上下文失败关闭、文件路径约束、nonce 原子登记、密码失败关闭、DataScope 可选严格策略、Job Open API fail-closed、密钥生成、幂等键、消息部分成功状态、WorkerId 容量门禁和未实现能力安全收口。

以下事项未做破坏性自动改造：

1. TenantInterceptor 属并行 Agent 冻结文件；其中无 auth 的 Header 回退在当前必选 Core 依赖图下不可达，超管跨租户语义仍需“目标租户 + 审计”产品规则后单独实施。
2. DataScope 未配置 Mapper 默认采用去重 WARN 保持兼容，生产完成配置盘点后应设置 forge.datascope.unconfigured-policy=DENY。
3. 自定义 XML 的租户条件仍由 MyBatis-Plus TenantLine 拦截器处理；del_flag 全库 AST/CI 审计需单独变更，不能无差别改写历史 SQL。
4. WorkerId 已做 80% 告警和越界拒绝；无租约模型前不实现可能产生重复 ID 的回收复用。
5. ExternalProxyServiceImpl.trustedInternal 仍依赖受控配置；入站服务已增加直接对端白名单，但网关仍必须剥离外部 X-Inner-Call Header。