安全与故障排查

安全要求

• 使用 PKCE S256，每次授权生成新的 verifier 和 state。
• redirectUri 必须与登记的应用入口同源。
• 不在 URL、日志、错误上报、埋点或截图中记录 token。
• token 按 workspaceId + runtimeAppId + installId 隔离，并检查过期时间。
• 页面存在 XSS 风险时，浏览器存储中的 token 同样会泄漏；必须执行内容安全策略和依赖安全检查。
• 应用停用、卸载、权限变化或用户退出时，清理本地会话。
• 后端服务只信任平台网关注入并验证过的上下文，不信任前端自行传入的 userId 或 workspaceId。

授权页提示缺少参数

检查参数是否写在 Hash Router 路由后：

正确：/manager/#/platform-app-authorize?installId=...
错误：/manager/?installId=...#/platform-app-authorize

redirectUri 不合法

检查协议、域名和端口是否与平台应用入口同源。外部应用必须使用绝对的 http(s) 地址，不能用协议相对地址。

缺少 PKCE verifier

通常是授权前没有保存 verifier、回跳进入了不同浏览器会话，或者应用刷新逻辑提前清理了 sessionStorage。重新开始授权并保证同一浏览器会话完成回跳。

state 校验失败

停止兑换 token。检查是否同时发起了多个授权请求、多个安装共用了同一个 storage key，或者回跳参数被路由层覆盖。

token 兑换失败

依次确认：

1. code 尚未使用且没有过期。
2. installId 与发起授权时一致。
3. codeVerifier 与原始 challenge 匹配。
4. 请求体字段使用 code 和 codeVerifier。

接口返回无权限

不要立即重新登录。先区分：

• token 无效或过期：重新授权。
• 模块方法未声明：发布包含正确最小权限的平台应用新版本。
• 工作区未安装依赖能力：修复安装或接口绑定。
• 用户没有目标业务权限：由业务权限管理员处理。
• 后端服务异常：查看目标服务日志和追踪信息。

排障时保留 installId、runtimeAppId、平台应用版本号、模块 service、方法名和平台 返回的公开错误信息；不要保存完整 token。