拓冰网站定制 
人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载导读本文基于 IronClaw 开源仓库docs/internal/reborn/security-parity/03-headers-errors.md审计记录深入剖析 WebUIWebChat v2网关如何通过外层SetResponseHeaderLayer统一注入X-Content-Type-Options、X-Frame-Options、CSP 与Referrer-Policy并如何在认证、JSON 校验与 panic 边界三层实现错误信息净化。读完本文你将掌握 v1 与 v2 两代网关的安全头差异、同一监听器上双 CSP的共存机制、?tokenSSE 方案的 referrer 泄漏缓解原理以及全部 9 条安全规则的测试锁定方式与对应源码路径。背景一次关于响应头与错误信息的 WebUI 安全对齐审计IronClaw 的 WebUI 从 v1src/channels/web/platform/网关演进到 v2crates/product/ironclaw_webui/原生表面时需要回答一个核心问题v1 已有的安全规则是否在 v2 中原样保留还是被悄悄弱化。docs/internal/reborn/security-parity/03-headers-errors.md正是该审计编号 #3615的第三个切片专门负责静态安全响应头 净化后的认证/校验错误这一部分与 01-auth.md认证和 02-network-limits.md网络限制并列为三份审计文档。审计的核心结论可以一句话概括9 条规则中6 条原样保留Keep、3 条主动加严Change没有任何一条被削弱因此本切片不存在 Beta-break。下文将逐条展开这些规则在 v1/v2 中的具体实现、代码位置与验证方式。规则总览9 条安全规则的 v1 → v2 决策表#规则v1 实现v2 实现决策1X-Content-Type-Optionsnosniffv1platform/router.rs:593-597nosniff通过外层SetResponseHeaderLayerwebui_serve.rsKeep2X-Frame-OptionsDENYv1platform/router.rs:598-601DENY同上Keep3aCSP —— API/JSON 路由build_csp()为 SPA 放行 CDN/字体/图片/iframe 源v1static_files.rs:78-116default-src self; object-src none; frame-ancestors none; base-uri self由组合层以SetResponseHeaderLayer::if_not_present注入Change—— 未自行设置 CSP 的所有路由全部/api/webchat/v2/*JSON 路由都落到严格默认值不作用于已自行设置 CSP 的 HTML 文档见 3b3bCSP —— SPA 文档/索引build_csp()含 CDN/字体放行render_index_with_nonce为同源脚本、样式、字体、资源与连接设置 CSP内联脚本需要每次请求的 nonce同源外部 bundle 由self放行内联样式仍允许Keep已加严—— 相对 v1 收紧为同源资源、每次请求的内联脚本 nonce、object-src none且script-src无unsafe-eval与unsafe-inline3cCSP —— wallet-connect 弹窗无script-src self unsafe-inline https:; style-src self unsafe-inline; connect-src self https:; frame-src self https: data:Change定向放宽—— 隔离的钱包弹窗刻意放宽仅作用于/wallet/connect单条路由4Referrer-Policyv1 网关未设置每个响应都带no-referrer—— 作为 SSE?token方案的防御Change—— v2 新增 v1 没有的响应头5错误响应上的响应头各 layer 覆盖整个路由器SetResponseHeaderLayer位于最外层401/413/429 同样携带全部响应头Keep—— 由static_security_headers_present_on_error_response锁定6认证失败净化统一Invalid or missing auth token401细节只记日志不回显所有认证失败收敛为通用 401原因不外泄Keep7校验错误净化axum extractor 拒绝 → 4xxJsonTextractor 在 facade 之前对畸形 body 返回 400body 为 axum 标准JsonRejection文本不含文件系统路径、Rust 类型名、traceback 或密钥但并非完全 opaque 字符串Keep—— 由malformed_request_body_returns_sanitized_client_error锁定8OAuth 错误净化v1 OAuth 错误处理回调失败重定向到?login_erroropaque enumprovider/JWT/签名会话细节只记日志不回显Keep—— 由 OAuth 路由错误重定向测试锁定9panic 边界CatchPanicLayer截断 payloadv1platform/router.rs:566-592CatchPanicLayer::custom(panic_handler)记录截断细节tracing::error!不回显返回通用500 Internal Server Error位于响应头 layer 内侧500 仍携带静态安全响应头Keep—— 由panic_boundary_returns_sanitized_500锁定双 CSP 机制同一监听器上的两套策略为何能共存文档 Notes 部分强调WebUI v2 存在两套截然不同的 CSP而不是一套理解这一点是正确配置的前提。组合层严格默认值规则 3a管辖 JSON API 表面组合层gateway 组装代码以SetResponseHeaderLayer::if_not_present的方式注入严格默认值default-src self; object-src none; frame-ancestors none; base-uri self该值定义在 webui_serve.rs 的DEFAULT_WEBUI_CSP常量中if_not_present语义意味着只要某个响应没有自行设置 CSP就落在这个严格默认值上。由于 v2 表面是纯 API/api/webchat/v2/*全部返回 JSON从不输出不可信的 HTML这套策略对 JSON 路由是完全安全的。同时文档注明CLI 二进制若将来在同一监听器上托管 HTML SPA可按部署覆盖该默认值with_csp_header_str构建器方法即为此设计。HTML 壳层自设 CSP规则 3b文档策略优先SPA 文档由render_index_with_nonce()static_assets/router.rs渲染它在响应上先写入自己的 CSP由于组合层使用if_not_present文档 CSP 会赢得外层注入严格默认值永远不会到达 HTML 文档。这套文档 CSP 的完整形态为default-src self; script-src self nonce-nonce; script-src-elem self nonce-nonce; style-src self unsafe-inline; style-src-elem self unsafe-inline; font-src self; img-src self data:; media-src self data:; frame-src self blob:; connect-src self; object-src none; frame-ancestors none; base-uri self其安全设计要点完全无 CDNVite 将应用 bundle 输出到/assets/字体托管在/vendor/所有子资源同源font-src self即可覆盖nonce 机制每次请求生成 16 字节随机 nonce32 个 hex 字符超过 CSP-3 建议的 128 位替换进 HTML 模板的__IRONCLAW_CSP_NONCE__占位符并写入 CSP 的nonce-...源。文档 CSP 与 HTML 中的 nonce 必须精确一致浏览器才会放行内联脚本unsafe-inline仅限样式Tailwind 运行时注入style与壳层内联主题样式需要它内联脚本则只能依赖 noncescript-src中既没有unsafe-inline也没有unsafe-eval附带缓存策略壳层响应携带Cache-Control: no-store—— nonce 每次变化浏览器若缓存旧壳层下一次加载会因 nonce 失配被 CSP 拒绝。wallet-connect 弹窗规则 3c隔离页面上的定向放宽/wallet/connect路由是唯一的宽松例外。钱包连接器需要在沙箱 iframe 中加载远程执行器代码并访问多种钱包 relay 与 NEAR RPC 端点无法预先固定源列表unsafe-inline是因为连接器向srcdoc沙箱框架注入内联引导脚本这些框架以独立的 opaque origin 运行。因此该页面使用default-src self; script-src self unsafe-inline https:; script-src-elem self unsafe-inline https:; style-src self unsafe-inline; img-src self data: https:; connect-src self https:; frame-src self https: data:; object-src none; base-uri self放宽之所以可接受是因为该页面不持有任何会话 bearer 与应用状态它连接 NEAR 钱包、签署固定的登录消息然后通过随机的同源BroadcastChannel将签名投递给已认证的 SPA由 SPA 中继给后端 —— 秘密永远不落在这个宽松 CSP 页面上。在 static_assets/router.rs 中/wallet/connect路由被显式放在 SPA 通配符之前确保它永远不会渲染应用壳层。Referrer-Policy针对 SSE?token泄密的纵深防御Referrer-Policy: no-referrer规则 4是 v2真正的新增响应头。它的存在直接服务于 SSE 的?token兼容方案浏览器EventSource无法设置自定义请求头因此 v2 在GET /api/webchat/v2/threads/{id}/events单一路由上接受了查询参数?token...判定逻辑见 webui_serve.rs 的is_v2_sse_event_request仅限 GET 且 thread id 为单个路径段。代价是 token 出现在 URL 中会进入任何 HTTP 访问日志、中间代理日志或分析管线。no-referrer的缓解原理浏览器在决定是否把引用 URL 附加到后续导航、第三方资源加载或下游链接点击时遵循Referrer-Policy。设成no-referrer后携带?token...的网关 URL 不会泄漏到任何跨域目标的日志。但文档明确警告这不能防护服务端访问日志捕获—— 操作者仍必须在保留期前清理 URL 查询串。同时 token-as-URL 的接受范围被收窄到唯一一条 SSE 路由变异mutation与时间线读取始终只接受 bearer 头确保查询 token 泄漏不能认证任何状态变更。错误信息净化三层边界各自如何工作审计的第二个主题是错误信息绝不外泄内部细节共覆盖认证规则 6、校验规则 7、OAuth规则 8与 panic规则 9四个场景。认证边界通用 401 与WebuiAuthenticator契约WebuiServeConfig持有的WebuiAuthenticatortraitwebui_serve.rs是组合层与宿主二进制之间的认证契约实现返回Some(UserId)表示成功、None表示拒绝具体失败原因始终留在实现内部网关统一回 401Invalid or missing auth token。这与 v1 的platform/auth.rs行为一致细节记日志、不回显且符合how-to-port-channel-to-reborn.md的 Path A 原则认证证据由宿主持有绝不向客户端泄漏。v2 还要求验证过的 token 必须通过mark_bearer_token_verified_for_tenant铸造受保护的HostAuthenticationGrant该证据只能在认证成功后产生进一步收紧信任边界。校验边界畸形 JSON 在 facade 之前被 400 拦截当请求体不是合法 JSON 时JsonTextractor 在进入服务facade之前即返回 400。响应体是 axum 标准的JsonRejection文本形如Failed to parse the request body as JSON: …line N column M。它不含文件系统路径、Rust 类型名、traceback 或密钥 —— 但文档特别注明它并非完全 opaque 字符串其中包含 serde 的结构化解析位置行/列该信息不敏感可接受。Panic 边界CatchPanicLayer::custom与固定的 500panic_handlerwebui_serve.rs将 panic payload 截断到 200 字符使用floor_char_boundary保证 UTF-8 边界通过tracing::error!记录target 为ironclaw::reborn::webui_serve响应体固定为字符串Internal Server Error状态码 500Content-Type 为text/plain。由于该 layer 位于响应头 layer内侧500 仍然携带 nosniff、DENY、CSP 与no-referrer—— 错误页面不会被嗅探、被嵌入或被 referrer 泄密。OAuth 回调opaque 枚举重定向v2 的 OAuth 回调失败重定向到?login_erroropaque enumprovider/JWT/签名会话的细节只记日志。由google_oauth_routes.rs/github_oauth_routes.rs的错误重定向测试锁定。错误响应的线格式WebUiV2HttpError的单一收敛点除 axum 标准JsonRejection外v2 处理器的业务错误统一通过 webui_v2/error.rs 的WebUiV2HttpError类型出口。它只包装已被净化过的ProductSurfaceErrorIntoResponse是唯一构造路径调用方通过From/?转换从不手工拼装状态码从而保证映射一致性。线格式为{ error: ProductSurfaceErrorCode, kind: ProductSurfaceErrorKind, retryable: true, field: optional_field, validation_code: missing_field }其中error/kind/retryable必填field/validation_code仅在有值时出现validation_code为来自ironclaw_assistant的类型化枚举以 snake_case 序列化。该类型还内置一道保险若ProductSurfaceError携带了非 HTTP 状态码防御性兜底正常情况只可能来自 400/401/403/404/409/429/500/503 固定表会大声记录日志并强制收敛为 500所有 5xx 出口都会先写一条服务端日志保证操作者能看到告警轨迹。测试锁定每个安全规则都有对应契约测试审计的价值在于可验证。所有 Keep/Change 决策都由测试钉死防止未来重构悄悄回退本审计#3615新增的契约测试crates/product/ironclaw_webui/tests/headers_errors_contract.rs覆盖测试锁定的规则验证要点static_security_headers_present_on_error_response1、2、4、5未认证 401 仍携带nosniff、DENY、CSP 与Referrer-Policy: no-referrercsp_directives_are_locked3aAPI 路由 CSP内容被锁定含default-src self、object-src none、frame-ancestors none、base-uri self仅检查存在性是不够的panic_boundary_returns_sanitized_5009携带敏感消息如/Users/secret/db SELECT token...的 panic → 500body 精确等于Internal Server Error无路径/SQL/token/::泄漏且静态安全头仍在malformed_request_body_returns_sanitized_client_error7畸形 JSON → 400不触及服务断言服务调用列表为空body 不含路径/类型名/traceback/tokensse_streams_are_capped_per_caller02 文档第 7 行网络限制回填每调用方 SSE 并发上限默认 3端到端生效第 4 个并发流 → 429释放后插槽归还RAII 语义其中sse_streams_are_capped_per_caller落在本文档的原因是网络限制 PR 当时已打开02-network-limits.md目录行只引用了sse_capacity.rs单元测试需要补一条路由层测试补足端到端覆盖。既有测试交叉引用不重复crates/app/ironclaw_composition/tests/webui_v2_serve.rs::v2_response_carries_static_security_headers—— 200 响应的响应头存在性规则 1、2、3aironclaw_webui/src/static_assets/router.rs::testsstandalone_spa_shell_carries_matching_csp_nonce—— 文档 nonce 与 CSP 精确匹配规则 3bspa_document_csp_allowlist_is_locked—— 文档 CSP 钉死同源资源、保留 nonce、script-src无unsafe-eval/unsafe-inline规则 3bwallet_connect_popup_gets_relaxed_csp_and_spa_shell_stays_strict—— 弹窗放宽而壳层保持严格规则 3b、3c认证失败 401 净化webui_v2_serve.rs缺失/非法 bearer与auth_route_contract.rs规则 6OAuth opaque 错误重定向google_oauth_routes.rs/github_oauth_routes.rs规则 8。运维建议与注意事项SSE?token的日志清理是操作者责任no-referrer只防浏览器侧 referrer 泄漏服务端访问日志仍需在保留前 scrub?tokenvalue接受范围已被收窄到GET .../threads/{id}/events单一路由。不要向public_mounts钩子传入 v1 网关路由器v1 的/auth/*处理器与 v2 原生认证路由器共享路径名/auth/providers、/auth/login/{p}、/auth/callback/{p}、/auth/logout混入会导致路径冲突并把 v1 流量导向 v2 的宿主签名会话存储。CSP 覆盖有明确入口宿主二进制可通过WebuiServeConfig::with_csp_header_str覆盖默认严格 CSP非法值会以WebuiServeConfigError::InvalidCspHeaderfail-closedCORS 允许源为空列表意味着拒绝一切跨域请求preflight 绝不回显攻击者提供的 Origin。静态路由命名空间 fail-closedapi、auth、v1、webhooks等根命名空间保留给服务器未知的 API 请求返回 404 而非渲染 SPA 壳层避免把宿主请求变成成功的 HTML 响应。结语审计闭环与工程启示本切片完成后#3615 的认证/网络/响应头-错误三份审计全部收口v1 WebUI 的每一条安全规则在 v2 中要么原样保留Keep要么有意加严Change仅有的两个 Beta-break —— 邮箱域名限制迁移到宿主UserDirectory#3580与 cookie 会话改为一站式登录票据#4116—— 都在 01-auth.md 中记录并关联。审计未发现任何回归。从工程实践角度看这份文档值得借鉴的方法论是安全策略的决策表 测试锁定双轨制—— 每条规则明确 v1/v2 的实现位置与 Keep/Change 结论再由端到端契约测试把响应头内容而非响应头存在性钉死csp_directives_are_locked即为典型一个把object-src放宽的回归会因内容断言失败而无法合并。对于任何在演进中更换过 Web 网关层的项目这套逐条对齐 契约测试的做法都是防止安全能力悄悄漂移的可靠模板。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐httpbin错误处理机制友好响应与调试信息httpbin错误处理机制友好响应与调试信息 在API开发过程中错误处理机制往往决定了开发者的调试效率和用户体验。当服务端返回一个模糊的500错误时开发者开发工具测试API设计HalfStyle无障碍访问指南保持屏幕阅读器友好的字符样式HalfStyle无障碍访问指南保持屏幕阅读器友好的字符样式 HalfStyle是一个创新的CSS样式库专门用于为字符创建独特的视觉效果同时确保屏幕阅读器前端UI库/组件如何掌握DVWA PHP错误处理从调试到安全配置的完整指南如何掌握DVWA PHP错误处理从调试到安全配置的完整指南 Damn Vulnerable Web Application DVWA 是一款专为安全爱好者和开应用安全渗透测试教育上一篇如何正确使用ZeroTierOne的MPL-2.0许可进行商业开发下一篇Biu音乐播放器革新B站音乐体验的跨平台桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 IronClaw WebUI 安全对齐实录：静态安全响应头与错误信息净化机制解析
人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载导读本文基于 IronClaw 开源仓库docs/internal/reborn/security-parity/03-headers-errors.md审计记录深入剖析 WebUIWebChat v2网关如何通过外层SetResponseHeaderLayer统一注入X-Content-Type-Options、X-Frame-Options、CSP 与Referrer-Policy并如何在认证、JSON 校验与 panic 边界三层实现错误信息净化。读完本文你将掌握 v1 与 v2 两代网关的安全头差异、同一监听器上双 CSP的共存机制、?tokenSSE 方案的 referrer 泄漏缓解原理以及全部 9 条安全规则的测试锁定方式与对应源码路径。背景一次关于响应头与错误信息的 WebUI 安全对齐审计IronClaw 的 WebUI 从 v1src/channels/web/platform/网关演进到 v2crates/product/ironclaw_webui/原生表面时需要回答一个核心问题v1 已有的安全规则是否在 v2 中原样保留还是被悄悄弱化。docs/internal/reborn/security-parity/03-headers-errors.md正是该审计编号 #3615的第三个切片专门负责静态安全响应头 净化后的认证/校验错误这一部分与 01-auth.md认证和 02-network-limits.md网络限制并列为三份审计文档。审计的核心结论可以一句话概括9 条规则中6 条原样保留Keep、3 条主动加严Change没有任何一条被削弱因此本切片不存在 Beta-break。下文将逐条展开这些规则在 v1/v2 中的具体实现、代码位置与验证方式。规则总览9 条安全规则的 v1 → v2 决策表#规则v1 实现v2 实现决策1X-Content-Type-Optionsnosniffv1platform/router.rs:593-597nosniff通过外层SetResponseHeaderLayerwebui_serve.rsKeep2X-Frame-OptionsDENYv1platform/router.rs:598-601DENY同上Keep3aCSP —— API/JSON 路由build_csp()为 SPA 放行 CDN/字体/图片/iframe 源v1static_files.rs:78-116default-src self; object-src none; frame-ancestors none; base-uri self由组合层以SetResponseHeaderLayer::if_not_present注入Change—— 未自行设置 CSP 的所有路由全部/api/webchat/v2/*JSON 路由都落到严格默认值不作用于已自行设置 CSP 的 HTML 文档见 3b3bCSP —— SPA 文档/索引build_csp()含 CDN/字体放行render_index_with_nonce为同源脚本、样式、字体、资源与连接设置 CSP内联脚本需要每次请求的 nonce同源外部 bundle 由self放行内联样式仍允许Keep已加严—— 相对 v1 收紧为同源资源、每次请求的内联脚本 nonce、object-src none且script-src无unsafe-eval与unsafe-inline3cCSP —— wallet-connect 弹窗无script-src self unsafe-inline https:; style-src self unsafe-inline; connect-src self https:; frame-src self https: data:Change定向放宽—— 隔离的钱包弹窗刻意放宽仅作用于/wallet/connect单条路由4Referrer-Policyv1 网关未设置每个响应都带no-referrer—— 作为 SSE?token方案的防御Change—— v2 新增 v1 没有的响应头5错误响应上的响应头各 layer 覆盖整个路由器SetResponseHeaderLayer位于最外层401/413/429 同样携带全部响应头Keep—— 由static_security_headers_present_on_error_response锁定6认证失败净化统一Invalid or missing auth token401细节只记日志不回显所有认证失败收敛为通用 401原因不外泄Keep7校验错误净化axum extractor 拒绝 → 4xxJsonTextractor 在 facade 之前对畸形 body 返回 400body 为 axum 标准JsonRejection文本不含文件系统路径、Rust 类型名、traceback 或密钥但并非完全 opaque 字符串Keep—— 由malformed_request_body_returns_sanitized_client_error锁定8OAuth 错误净化v1 OAuth 错误处理回调失败重定向到?login_erroropaque enumprovider/JWT/签名会话细节只记日志不回显Keep—— 由 OAuth 路由错误重定向测试锁定9panic 边界CatchPanicLayer截断 payloadv1platform/router.rs:566-592CatchPanicLayer::custom(panic_handler)记录截断细节tracing::error!不回显返回通用500 Internal Server Error位于响应头 layer 内侧500 仍携带静态安全响应头Keep—— 由panic_boundary_returns_sanitized_500锁定双 CSP 机制同一监听器上的两套策略为何能共存文档 Notes 部分强调WebUI v2 存在两套截然不同的 CSP而不是一套理解这一点是正确配置的前提。组合层严格默认值规则 3a管辖 JSON API 表面组合层gateway 组装代码以SetResponseHeaderLayer::if_not_present的方式注入严格默认值default-src self; object-src none; frame-ancestors none; base-uri self该值定义在 webui_serve.rs 的DEFAULT_WEBUI_CSP常量中if_not_present语义意味着只要某个响应没有自行设置 CSP就落在这个严格默认值上。由于 v2 表面是纯 API/api/webchat/v2/*全部返回 JSON从不输出不可信的 HTML这套策略对 JSON 路由是完全安全的。同时文档注明CLI 二进制若将来在同一监听器上托管 HTML SPA可按部署覆盖该默认值with_csp_header_str构建器方法即为此设计。HTML 壳层自设 CSP规则 3b文档策略优先SPA 文档由render_index_with_nonce()static_assets/router.rs渲染它在响应上先写入自己的 CSP由于组合层使用if_not_present文档 CSP 会赢得外层注入严格默认值永远不会到达 HTML 文档。这套文档 CSP 的完整形态为default-src self; script-src self nonce-nonce; script-src-elem self nonce-nonce; style-src self unsafe-inline; style-src-elem self unsafe-inline; font-src self; img-src self data:; media-src self data:; frame-src self blob:; connect-src self; object-src none; frame-ancestors none; base-uri self其安全设计要点完全无 CDNVite 将应用 bundle 输出到/assets/字体托管在/vendor/所有子资源同源font-src self即可覆盖nonce 机制每次请求生成 16 字节随机 nonce32 个 hex 字符超过 CSP-3 建议的 128 位替换进 HTML 模板的__IRONCLAW_CSP_NONCE__占位符并写入 CSP 的nonce-...源。文档 CSP 与 HTML 中的 nonce 必须精确一致浏览器才会放行内联脚本unsafe-inline仅限样式Tailwind 运行时注入style与壳层内联主题样式需要它内联脚本则只能依赖 noncescript-src中既没有unsafe-inline也没有unsafe-eval附带缓存策略壳层响应携带Cache-Control: no-store—— nonce 每次变化浏览器若缓存旧壳层下一次加载会因 nonce 失配被 CSP 拒绝。wallet-connect 弹窗规则 3c隔离页面上的定向放宽/wallet/connect路由是唯一的宽松例外。钱包连接器需要在沙箱 iframe 中加载远程执行器代码并访问多种钱包 relay 与 NEAR RPC 端点无法预先固定源列表unsafe-inline是因为连接器向srcdoc沙箱框架注入内联引导脚本这些框架以独立的 opaque origin 运行。因此该页面使用default-src self; script-src self unsafe-inline https:; script-src-elem self unsafe-inline https:; style-src self unsafe-inline; img-src self data: https:; connect-src self https:; frame-src self https: data:; object-src none; base-uri self放宽之所以可接受是因为该页面不持有任何会话 bearer 与应用状态它连接 NEAR 钱包、签署固定的登录消息然后通过随机的同源BroadcastChannel将签名投递给已认证的 SPA由 SPA 中继给后端 —— 秘密永远不落在这个宽松 CSP 页面上。在 static_assets/router.rs 中/wallet/connect路由被显式放在 SPA 通配符之前确保它永远不会渲染应用壳层。Referrer-Policy针对 SSE?token泄密的纵深防御Referrer-Policy: no-referrer规则 4是 v2真正的新增响应头。它的存在直接服务于 SSE 的?token兼容方案浏览器EventSource无法设置自定义请求头因此 v2 在GET /api/webchat/v2/threads/{id}/events单一路由上接受了查询参数?token...判定逻辑见 webui_serve.rs 的is_v2_sse_event_request仅限 GET 且 thread id 为单个路径段。代价是 token 出现在 URL 中会进入任何 HTTP 访问日志、中间代理日志或分析管线。no-referrer的缓解原理浏览器在决定是否把引用 URL 附加到后续导航、第三方资源加载或下游链接点击时遵循Referrer-Policy。设成no-referrer后携带?token...的网关 URL 不会泄漏到任何跨域目标的日志。但文档明确警告这不能防护服务端访问日志捕获—— 操作者仍必须在保留期前清理 URL 查询串。同时 token-as-URL 的接受范围被收窄到唯一一条 SSE 路由变异mutation与时间线读取始终只接受 bearer 头确保查询 token 泄漏不能认证任何状态变更。错误信息净化三层边界各自如何工作审计的第二个主题是错误信息绝不外泄内部细节共覆盖认证规则 6、校验规则 7、OAuth规则 8与 panic规则 9四个场景。认证边界通用 401 与WebuiAuthenticator契约WebuiServeConfig持有的WebuiAuthenticatortraitwebui_serve.rs是组合层与宿主二进制之间的认证契约实现返回Some(UserId)表示成功、None表示拒绝具体失败原因始终留在实现内部网关统一回 401Invalid or missing auth token。这与 v1 的platform/auth.rs行为一致细节记日志、不回显且符合how-to-port-channel-to-reborn.md的 Path A 原则认证证据由宿主持有绝不向客户端泄漏。v2 还要求验证过的 token 必须通过mark_bearer_token_verified_for_tenant铸造受保护的HostAuthenticationGrant该证据只能在认证成功后产生进一步收紧信任边界。校验边界畸形 JSON 在 facade 之前被 400 拦截当请求体不是合法 JSON 时JsonTextractor 在进入服务facade之前即返回 400。响应体是 axum 标准的JsonRejection文本形如Failed to parse the request body as JSON: …line N column M。它不含文件系统路径、Rust 类型名、traceback 或密钥 —— 但文档特别注明它并非完全 opaque 字符串其中包含 serde 的结构化解析位置行/列该信息不敏感可接受。Panic 边界CatchPanicLayer::custom与固定的 500panic_handlerwebui_serve.rs将 panic payload 截断到 200 字符使用floor_char_boundary保证 UTF-8 边界通过tracing::error!记录target 为ironclaw::reborn::webui_serve响应体固定为字符串Internal Server Error状态码 500Content-Type 为text/plain。由于该 layer 位于响应头 layer内侧500 仍然携带 nosniff、DENY、CSP 与no-referrer—— 错误页面不会被嗅探、被嵌入或被 referrer 泄密。OAuth 回调opaque 枚举重定向v2 的 OAuth 回调失败重定向到?login_erroropaque enumprovider/JWT/签名会话的细节只记日志。由google_oauth_routes.rs/github_oauth_routes.rs的错误重定向测试锁定。错误响应的线格式WebUiV2HttpError的单一收敛点除 axum 标准JsonRejection外v2 处理器的业务错误统一通过 webui_v2/error.rs 的WebUiV2HttpError类型出口。它只包装已被净化过的ProductSurfaceErrorIntoResponse是唯一构造路径调用方通过From/?转换从不手工拼装状态码从而保证映射一致性。线格式为{ error: ProductSurfaceErrorCode, kind: ProductSurfaceErrorKind, retryable: true, field: optional_field, validation_code: missing_field }其中error/kind/retryable必填field/validation_code仅在有值时出现validation_code为来自ironclaw_assistant的类型化枚举以 snake_case 序列化。该类型还内置一道保险若ProductSurfaceError携带了非 HTTP 状态码防御性兜底正常情况只可能来自 400/401/403/404/409/429/500/503 固定表会大声记录日志并强制收敛为 500所有 5xx 出口都会先写一条服务端日志保证操作者能看到告警轨迹。测试锁定每个安全规则都有对应契约测试审计的价值在于可验证。所有 Keep/Change 决策都由测试钉死防止未来重构悄悄回退本审计#3615新增的契约测试crates/product/ironclaw_webui/tests/headers_errors_contract.rs覆盖测试锁定的规则验证要点static_security_headers_present_on_error_response1、2、4、5未认证 401 仍携带nosniff、DENY、CSP 与Referrer-Policy: no-referrercsp_directives_are_locked3aAPI 路由 CSP内容被锁定含default-src self、object-src none、frame-ancestors none、base-uri self仅检查存在性是不够的panic_boundary_returns_sanitized_5009携带敏感消息如/Users/secret/db SELECT token...的 panic → 500body 精确等于Internal Server Error无路径/SQL/token/::泄漏且静态安全头仍在malformed_request_body_returns_sanitized_client_error7畸形 JSON → 400不触及服务断言服务调用列表为空body 不含路径/类型名/traceback/tokensse_streams_are_capped_per_caller02 文档第 7 行网络限制回填每调用方 SSE 并发上限默认 3端到端生效第 4 个并发流 → 429释放后插槽归还RAII 语义其中sse_streams_are_capped_per_caller落在本文档的原因是网络限制 PR 当时已打开02-network-limits.md目录行只引用了sse_capacity.rs单元测试需要补一条路由层测试补足端到端覆盖。既有测试交叉引用不重复crates/app/ironclaw_composition/tests/webui_v2_serve.rs::v2_response_carries_static_security_headers—— 200 响应的响应头存在性规则 1、2、3aironclaw_webui/src/static_assets/router.rs::testsstandalone_spa_shell_carries_matching_csp_nonce—— 文档 nonce 与 CSP 精确匹配规则 3bspa_document_csp_allowlist_is_locked—— 文档 CSP 钉死同源资源、保留 nonce、script-src无unsafe-eval/unsafe-inline规则 3bwallet_connect_popup_gets_relaxed_csp_and_spa_shell_stays_strict—— 弹窗放宽而壳层保持严格规则 3b、3c认证失败 401 净化webui_v2_serve.rs缺失/非法 bearer与auth_route_contract.rs规则 6OAuth opaque 错误重定向google_oauth_routes.rs/github_oauth_routes.rs规则 8。运维建议与注意事项SSE?token的日志清理是操作者责任no-referrer只防浏览器侧 referrer 泄漏服务端访问日志仍需在保留前 scrub?tokenvalue接受范围已被收窄到GET .../threads/{id}/events单一路由。不要向public_mounts钩子传入 v1 网关路由器v1 的/auth/*处理器与 v2 原生认证路由器共享路径名/auth/providers、/auth/login/{p}、/auth/callback/{p}、/auth/logout混入会导致路径冲突并把 v1 流量导向 v2 的宿主签名会话存储。CSP 覆盖有明确入口宿主二进制可通过WebuiServeConfig::with_csp_header_str覆盖默认严格 CSP非法值会以WebuiServeConfigError::InvalidCspHeaderfail-closedCORS 允许源为空列表意味着拒绝一切跨域请求preflight 绝不回显攻击者提供的 Origin。静态路由命名空间 fail-closedapi、auth、v1、webhooks等根命名空间保留给服务器未知的 API 请求返回 404 而非渲染 SPA 壳层避免把宿主请求变成成功的 HTML 响应。结语审计闭环与工程启示本切片完成后#3615 的认证/网络/响应头-错误三份审计全部收口v1 WebUI 的每一条安全规则在 v2 中要么原样保留Keep要么有意加严Change仅有的两个 Beta-break —— 邮箱域名限制迁移到宿主UserDirectory#3580与 cookie 会话改为一站式登录票据#4116—— 都在 01-auth.md 中记录并关联。审计未发现任何回归。从工程实践角度看这份文档值得借鉴的方法论是安全策略的决策表 测试锁定双轨制—— 每条规则明确 v1/v2 的实现位置与 Keep/Change 结论再由端到端契约测试把响应头内容而非响应头存在性钉死csp_directives_are_locked即为典型一个把object-src放宽的回归会因内容断言失败而无法合并。对于任何在演进中更换过 Web 网关层的项目这套逐条对齐 契约测试的做法都是防止安全能力悄悄漂移的可靠模板。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐httpbin错误处理机制友好响应与调试信息httpbin错误处理机制友好响应与调试信息 在API开发过程中错误处理机制往往决定了开发者的调试效率和用户体验。当服务端返回一个模糊的500错误时开发者开发工具测试API设计HalfStyle无障碍访问指南保持屏幕阅读器友好的字符样式HalfStyle无障碍访问指南保持屏幕阅读器友好的字符样式 HalfStyle是一个创新的CSS样式库专门用于为字符创建独特的视觉效果同时确保屏幕阅读器前端UI库/组件如何掌握DVWA PHP错误处理从调试到安全配置的完整指南如何掌握DVWA PHP错误处理从调试到安全配置的完整指南 Damn Vulnerable Web Application DVWA 是一款专为安全爱好者和开应用安全渗透测试教育上一篇如何正确使用ZeroTierOne的MPL-2.0许可进行商业开发下一篇Biu音乐播放器革新B站音乐体验的跨平台桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考