IM.codes安全设计全解：从Passkey认证、CSRF防护到Pod-Sticky路由的8道防线-平芜编程栈

【免费下载链接】imcodes

The IM for agents. Shared Agent Context & Memory, supervised execution, and cross-agent audit across AI providers.

项目地址：https://gitcode.com/gh_mirrors/im/imcodes

IM.codes（The IM for agents）是一个面向 AI Agent 的即时通讯服务，提供共享 Agent 上下文与记忆、监督执行和跨 Agent 提供商审计能力。作为承载敏感会话与凭据的服务器，它的安全架构值得拆解：从 Passkey 无密码登录、CSRF 双重提交防护、登录锁定到多副本部署下的 Pod-Sticky 路由，IM.codes 一共布下了 8 道防线。本文带你用非专业视角看懂每一道防线在防什么、怎么防。

第一道防线：Passkey 无密码登录 🗝️

传统账号密码是撞库和钓鱼的重灾区。IM.codes 支持基于 WebAuthn 标准的 Passkey（通行密钥）登录，浏览器或手机用指纹、Face ID 完成挑战-响应认证，密码从头到尾不出现在网络上。

认证流程基于@simplewebauthn/server实现，注册和认证挑战存储在数据库（auth_nonces表中的 nonce 仅有 60 秒有效期），一次性、防重放；
rpId和期望 Origin 从请求实际访问的主机名动态推导，而不是写死配置，避免"在 A 域名注册、被 B 域名利用"的跨域攻击；
所有 Passkey 端点强制Cache-Control: no-store，杜绝中间缓存截获认证响应。

第二道防线：HttpOnly Cookie + 刷新令牌轮换 🍪

登录成功后，IM.codes 下发三枚职责分明的 Cookie，命名统一维护在 cookie-names.ts：

Cookie	特性	作用
`rcc_session`	HttpOnly + Secure	承载 4 小时有效期的 JWT 访问令牌，JS 读不到
`rcc_refresh`	HttpOnly + Secure	30 天刷新令牌，只用于换新访问令牌
`rcc_csrf`	可被 JS 读取	专供第三道防线使用的 CSRF 令牌

刷新令牌采用单次使用 + 轮换策略：每次调用POST /api/auth/refresh后旧令牌立即作废并签发新令牌对，被盗用的旧令牌无法二次使用（见 auth.ts）。同时刷新接口会校验账号状态——被管理员禁用的账号，其旧令牌也无法续命。

第三道防线：CSRF 双重提交防护 🛡️

浏览器带着 Cookie 访问第三方网站时，恶意页面可能诱导浏览器"夹带"你的会话发起请求，这就是 CSRF 攻击。IM.codes 的 csrf.ts 采用经典的双重提交（double-submit）模式，且做了不少加固细节：

Origin 精确匹配：不是简单的"前缀匹配"，而是将 Origin 归一化为协议+主机后与白名单逐字符比对，专门堵死https://app.example.com.evil.tld这类子域前缀绕过；
令牌一致性校验：请求头X-CSRF-Token必须与rcc_csrfCookie 完全一致，否则直接返回csrf_rejected；
合理豁免：GET/HEAD/OPTIONS 等安全方法、Passkey 端点（挑战-响应机制本身比 CSRF 更强）、登出和登录接口（不豁免会导致用户卡在无法退出的坏会话）走白名单跳过。

第四道防线：scrypt 哈希与 AES-256-GCM 加密 🔐

密钥与敏感数据怎么存？crypto.ts 给出答案：

密码哈希：使用 scrypt 算法 + 32 字节随机盐，输出 64 字节派生密钥，且用常量时间比较（timingSafeEqual）防时序侧信道攻击；
敏感配置加密：Bot 配置等敏感数据用 AES-256-GCM 认证加密，密文布局为iv(12) || ciphertext || authTag(16)，任何一位被篡改都会解密失败；
JWT 签名：HS256 HMAC-SHA256 签名，验签同样是常量时间比较，并严格校验exp过期时间。

第五道防线：登录锁定与速率限制 ⏱️

暴破攻击最怕"锁门"。lockout.ts 的规则很简单粗暴：同一 IP 或同一身份 15 分钟内失败 5 次，直接锁定 15 分钟。

关键设计：锁定状态存在 PostgreSQL 的auth_lockout表里而不是内存，多实例部署时所有副本共享同一个"黑名单"。刷新令牌接口同样套用 IP + 用户双重锁定检查（返回 429 和retryAfterMs）。另外 rate-limiter.ts 提供滑动窗口限流，并跟踪 WebSocket 票据（JTI）的"一次性"消费，防止票据被重放。

第六道防线：重放防护与幂等性 🔁

截获一个合法请求并原样重发，是内网攻击的经典手段。replay.ts 从三个层面设防：

时间戳窗口：内部 daemon ↔ server 调用必须携带X-Deck-Timestamp，与服务器时间偏差超过 5 分钟直接拒绝；
幂等键：状态变更操作可携带Idempotency-Key，相同键重复提交直接返回首次缓存的响应，记录保留 24 小时后由定时任务清理；
平台 Webhook 原生签名：Discord 用 Ed25519 + 时间戳签名，飞书用 SHA-256（含时间戳与 nonce），Telegram 用 secret token——只认官方签名，第三方伪造无效。

第七道防线：角色权限矩阵 + 审计日志 📋

谁能干什么？authorization.ts 定义了一张清晰的角色权限矩阵：

owner → 读 / 写 / 管理 / 所有者操作 admin → 读 / 写 / 管理 member → 读 / 写 unauthenticated → 无权限

更精细的地方在于：受控节点（controlled node）凭证默认拒绝一切普通 REST API 调用，只能到达其被允许的最小接口面——"默认拒绝"是安全设计里最重要的四个字母。同时，多标签页切换账号导致的身份漂移也会被X-Expected-User-Id校验拦截（返回 409），防止"A 账号的标签页偷偷操作 B 账号"。

所有状态变更请求（POST/PUT/DELETE）由 audit.ts 自动写入audit_log表，记录操作者、服务器 ID、动作、来源 IP 与客户端平台版本，保留 90 天——出了问题可以追溯"是谁、在什么客户端、对哪台机器做了什么"。

第八道防线：Pod-Sticky 路由 🏗️

最后一道防线关乎架构。IM.codes 服务器以多副本（多 Pod）方式运行，每个 daemon（用户本机的守护进程）通过 WebSocket 连接到其中一个 Pod。问题来了：下载令牌、WsBridge 实例、终端流等状态都只存在于单个 Pod 的内存里。

解决办法是 Pod-Sticky 路由约定：任何依赖 daemon 的请求必须携带serverId（查询参数?serverId=或路径参数/api/server/:serverId/...），入口网关据此把请求精确路由到持有该 daemon WebSocket 的那个 Pod（挂载逻辑见 index.ts，路由约定见 CLAUDE.md）。

从安全角度看，这道防线的价值在于状态隔离：A 用户的请求绝不可能"飘"到另一个 Pod 上，摸到别人内存里的会话状态、下载票据或终端流——路由本身就成了访问控制的一部分。

总结：8 道防线一张表 ✅

#	防线	抵御的威胁	核心源码
1	Passkey 认证	撞库、钓鱼、密码泄露	passkey-auth.ts
2	HttpOnly Cookie + 令牌轮换	XSS 窃取会话、令牌重放	auth.ts
3	CSRF 双重提交 + Origin 精确校验	跨站请求伪造	csrf.ts
4	scrypt 哈希 + AES-256-GCM	时序攻击、数据篡改	crypto.ts
5	登录锁定 + 滑动窗口限流	暴力破解、凭据喷洒	lockout.ts
6	时间戳窗口 + 幂等键 + Webhook 签名	请求重放、伪签名	replay.ts
7	RBAC 权限矩阵 + 审计日志	越权操作、内部滥用	authorization.ts / audit.ts
8	Pod-Sticky 路由	跨 Pod 内存状态越界	index.ts

从认证入口到路由层，IM.codes 的安全设计遵循一个朴素原则：每一层都假设上一层可能失守。无密码的 Passkey 减少了可泄露的凭据面，即使 Cookie 被带出，CSRF 校验、身份头校验、角色矩阵仍层层拦截；即使内部调用被截获，时间戳窗口和签名校验会让重放失效；而多副本架构下，路由把每个用户的状态牢牢锁在它自己的 Pod 里。对于关注 Agent 协作安全的新手开发者来说，这 8 道防线既是现成的参考样板，也是一份可直接对号入座的 Web 安全清单。