treg会话Cookie安全设计treg_session如何防止泄露到上游【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/tregtreg 是一个面向 Agent 工具的 API 网关OpenRouter for agent tools它的核心工作是把用户的请求中继relay到上游数据服务商。这种替浏览器转发请求的模式天然带有一个安全隐患用户在仪表盘上登录 treg 时浏览器持有treg_session会话 Cookie如果它被原样转发给第三方上游等于把钥匙交给了陌生人。这篇文章讲清楚 treg 是如何用签名会话 双向 Cookie 清洗 受众隔离三层设计把treg_session牢牢锁在网关内部的。一、为什么中继网关特别怕会话 Cookie 泄露treg 的中继层承诺忠实验证式转发方法、路径、查询参数、请求头、Cookie、请求体字节流几乎原样透传。这对 API 调试和凭证注入是必需的但也意味着——浏览器里发出的每一个 Cookie如果不加区分都会被复制进发往上游的请求头中。而 treg 的仪表盘前端在 Try it 试调用场景下使用了credentials: include让浏览器自动带上同源 Cookie会话 Cookie 就必然出现在请求里。上游服务商是第三方一旦拿到treg_session理论上可以反向调用 treg 的会话接口冒充该用户操作其团队、密钥和账单。所以整个安全设计围绕一个目标让treg_session永远只属于 treg 这一个域绝不跨出网关。二、签发环节一个上不了台面的签名 Cookietreg_session的定义和签发逻辑位于 session.py它不是服务端数据库里存的一串随机值而是一枚无状态 HMAC-SHA256 签名令牌内嵌三类声明claims声明含义安全作用uid用户 ID标识会话归属exp过期时间戳固定 7 天有效期TTL_SECONDSaud受众 session⭐ 与 API 密钥identity硬性隔离设置 Cookie 时见 auth.py同时叠加了浏览器侧的标准防御HttpOnlyJavaScript 读不到XSS 拿不走SameSiteLax跨站请求默认不带抗 CSRFSecureHTTPS 环境下仅加密传输max_age 7 天自动过期。还有一个细节值得注意如果没有配置签名密钥treg不会退化成代码里写死的默认密钥那会让任何读源码的人伪造任意用户的 Cookie包括超级管理员而是用每进程随机的临时密钥——代价是重启后登录失效但这是宁可响亮地失败也不能静默地裸奔的选择见 session.py 的注释。三、核心防线中继层的双向 Cookie 清洗真正的主角在中继函数relay()里实现在 relay.py。它做了一次双向清洗1️⃣ 出方向treg_session到不了上游def _scrub_treg_cookies(headers): # 从 Cookie 头中摘掉 treg 自己的 Cookie其余调用方 Cookie 保留 # 摘空了就整个删掉 Cookie 头转发前relay()会解析Cookie头精确剔除treg_session和treg_oauth_state见 _TREG_COOKIES而用户自己的其他 Cookie 原样保留——不会误伤。浏览器发出: Cookie: treg_sessionabc123; ordinarykeep-me 转发上游: Cookie: ordinarykeep-me ✅ treg_session 被扣下2️⃣ 入方向上游也不能反向种你的会话 Cookie更隐蔽的攻击是会话固定上游返回一个Set-Cookie: treg_sessionevil由于响应经过 treg 同域代理浏览器会把这个伪造值种到 treg 域名下覆盖真实会话。relay()在回传响应头时凡是针对 treg 自家 Cookie 名的Set-Cookie一律丢弃见 _is_treg_setcookie同时给每个中继响应追加X-Content-Type-Options: nosniff和Content-Security-Policy: sandbox防止上游 HTML 在 treg 源下执行脚本反射型 XSS 的最后一道闸。四、受众隔离会话令牌变不成 API 密钥单靠清洗只挡住了传输路径。treg 还在令牌本身做了身份互斥浏览器会话签发的令牌aud sessionAPI 密钥 / Bearer 令牌aud identityread_session_claims() 拒绝一切非session受众的令牌read_identity_claims() 则无条件拒绝session受众令牌。即使某条路径的清洗出现漏洞treg_session被复制走了也没用——它无法通过X-Treg-Token通道重放反之 API 密钥也不能冒充浏览器登录。两套身份互不串门。五、回归测试F3 用例双向验证这套设计被固化在调用矩阵测试 F3 中test_matrix.py说明见 CASES.md请求携带treg_sessioncaller-secret; ordinarykeep-me→ 断言上游收不到treg_session自定义头与ordinary保留上游模拟返回Set-Cookie: treg_sessionevil→ 断言该头不出现在回传响应中。双向各一条断言防止任何一侧的清洗回归。六、参考文件清单模块路径说明会话令牌签发/校验src/treg/domain/identity/session.pyHMAC 令牌、受众分离中继 Cookie 清洗src/treg/infra/upstream/relay.py双向 scrub 逻辑Cookie 属性设置src/treg/routers/auth.pyHttpOnly / Lax / Secure代理模型文档docs/context/architecture/proxy-model.md转发忠实性契约认证与密钥架构docs/context/architecture/auth-secrets.md会话生命周期双向清洗测试tests/callmatrix/test_matrix.pyF3 用例七、一句话总结 treg 的安全思路不是把 Cookie 藏起来而是假设它一定会出现在请求里然后在三个层面同时设防令牌自身签名 7 天过期 aud受众隔离泄露也变不成别的身份出方向_scrub_treg_cookies在中继前精确摘除只扣自家的、不误伤用户的入方向拒绝上游反向种植同名 Cookie杜绝会话固定。对任何做代理/网关类产品的人来说这套清洗 隔离 固定化测试的组合拳都是一份可以直接抄作业的防泄露清单。【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考