AgentRQ安全模型全景图：OAuth2、AES-GCM加密与多层权限防护-平芜编程栈

【免费下载链接】agentrq

AgentRQ: Human-in-loop realtime conversational task manager for AI Agents. Self-hosted! Control your own agents from wherever you want Mobile, Web, Desktop. Designed to work well with your own Claude subscriptions and any harness with ACP support.

项目地址：https://gitcode.com/gh_mirrors/ag/agentrq

点击查看免费下载

AgentRQ 是一款自托管的 Human-in-loop（人在回路）AI Agent 实时任务管理工具，它的核心安全模型由三大支柱构成：标准OAuth2授权流程、AES-GCM 加密存储的 Workspace 令牌，以及覆盖工具调用的多层权限防护机制。无论你是想在团队内部署一套安全的 Agent 调度平台，还是单纯好奇"让 AI 替我干活时，如何保证它不越权"，这篇指南都能帮你快速看懂 AgentRQ 是如何把密钥、令牌和审批流层层锁死的。

一、安全边界全景图：谁访问谁，用什么凭证

AgentRQ 把系统划分为几类清晰的边界，每一类都有独立的认证机制。完整定义可以在架构文档 ARCHITECTURE.md 的 "Security Boundaries" 一节找到，核心内容如下：

安全边界	认证机制
Supervisor Agent ↔ Core MCP 服务	OAuth2 + JWT 访问令牌（audience 为`coremcp`，用户级作用域）
Worker Agent ↔ 单 Workspace MCP	Workspace 令牌（AES-GCM 静态加密，传输中为 Bearer 令牌，仅限一个 workspace）
人类用户 ↔ REST API	JWT（会话 Cookie 或 Authorization 头）
权限门控	Auto-allow 规则 + SSE 推送 + MCP 通知的人工审批流
Workspace 隔离	每个 workspace 的 MCP 服务只作用于本 workspace，禁止跨 workspace 工具调用
限流 / DDoS 防护	按用户请求计数 + 按 IP 计数并可配置封禁时长

这个设计的精髓在于**"一个凭证只干一件事"**：人的令牌、Agent 的令牌、终端票据、OAuth 同意票据全部互相隔离，任何一张偷来的票据都换不来第二种权限。

二、OAuth2 授权：人类必须亲手按下 "Allow"

AgentRQ 同时对外暴露两类 MCP 服务：面向 Supervisor Agent 的 Core MCP（/mcp）和面向 Worker Agent 的单 Workspace MCP（/mcp/{workspaceId}）。两者的认证细节都写在 auth.md 中。

对新手来说，最关键的一条设计原则是：任何凭证都以某个人的名义签发，且必须由本人在浏览器中批准。Agent 自己无法注册账号、无法自行换取令牌，因此授权服务器元数据里根本没有agent_auth通道。

授权码流程：人类始终在回路里

Agent 把用户的浏览器带到/oauth2/authorize，附带response_type=code、client_id、redirect_uri与state；
用户未登录则先登录 AgentRQ；
用户看到同意页面——上面写清楚"哪个应用在申请、它能做什么、回调地址在哪里"，然后亲手按Allow或Deny；
允许后应用拿到code，用它去/oauth2/token换取访问令牌。

同意页面由后端独立渲染（见 consent.go），而不是由前端 Vue 应用渲染。源码注释写得很直白：这样"任何 Agent 能驱动的东西——WebMCP 工具或 REST API——都无法替某人按下 Allow"。

防 CSRF、防重放：同意令牌绑定"人 + 请求"

同意页面提交时携带的 OAuth Consent Token 会同时校验三件事（见 jwt.go）：

Subject：必须是渲染此页面的那个人；
Audience：必须是oauth_consent，其他类型的令牌一概不认；
完整载荷：应用 ID、资源、redirect_uri、state必须与授权请求逐字段一致。

这意味着你为 A 应用批准的授权，绝不能被挪到 B 应用或另一个回调地址上使用。整个同意令牌只有10 分钟有效期，超时就得重新走一遍流程。

客户端注册也自带"反 SSRF 装甲"

AgentRQ 支持 RFC 7591 动态客户端注册，还支持较新的CIMD（Client ID Metadata Document）方案——让client_id直接是一个 HTTPS 元数据文档 URL。由于这个 URL 由调用方提供，服务端在 cimd.go 中做了非常激进的加固：

自行解析 DNS，任何解析结果落在回环、内网、链路本地地址的请求直接拒绝；
额外封锁 NAT64（64:ff9b::/96）、6to4 等能"把 IPv4 藏进 IPv6"的地址段，堵住重绑定攻击；
绝不跟随 HTTP 重定向，响应体限制 5KB，只接受 200 状态码；
明确拒绝client_secret字段——CIMD 客户端永远不能是"共享密钥型"机密客户端。

三、AES-GCM 加密：Workspace 令牌如何"入库即密文"

Worker Agent 连接 Workspace MCP 时用的凭证，是一个 16 字符的 Workspace 令牌。这个令牌在数据库里从不以明文存储——它使用 AES-256-GCM 加密，密钥来自服务端 32 字节的配置项。

加密实现位于 security.go，几个值得新手注意的工程细节：

GCM 模式自带完整性校验：解密时若密文被篡改或 nonce 被重放，gcm.Open会直接报错，而不是解出一串乱码让你误以为是合法数据；
每次加密随机生成新 nonce（crypto/rand产生），避免同一明文+同一密文的模式泄露；
密钥长度强制校验：不是 32 字节直接拒绝，错误信息明确提示 "key must be 32 bytes for AES-256"；
同文件还提供两个"防君子"工具函数：
- GenerateSecret：用crypto/rand.Int生成无模偏差的随机密钥串（用于各种 secret 的初始生成）；
- SecureCompare：基于crypto/subtle.ConstantTimeCompare的常数时间比较，防止通过响应耗时差异发动时序攻击。

一句话总结：令牌在磁盘上是密文，在网络上是 Bearer 头，在验证时是常数时间比较——三个环节各管一段。

四、JWT 受众隔离：一张令牌只配一个"工牌"

AgentRQ 的所有令牌都是 HS256 签名的 JWT，但真正的安全感来自audience（受众）隔离。jwt.go 中定义了多组互不通用的受众：

凭证类型	Audience	有效期	用途
人类访问令牌	`actor:human`	24 小时	浏览器/桌面应用的会话令牌
刷新令牌	`refresh:human`	2 天	换发新会话（刻意缩短，因为无法吊销）
终端票据	`terminal_ticket`+ 会话 ID	1 分钟	打开某个终端 WebSocket
浏览器票据	`browser_ticket`	1 分钟	Chrome 扩展的浏览器 socket
OAuth 同意令牌	`oauth_consent`	10 分钟	同意页面提交
授权码	workspace ID +`authorization_code`	2 分钟	OAuth 授权码交换

几个设计非常值得借鉴：

短命票据走 URL 传输。终端/浏览器票据会出现在 URL 查询串里（可能被代理日志、shell 历史记录看到），所以只给 1 分钟寿命，每次重连重新签发，绝不复用；
刷新令牌刻意不带 email/name 字段，每次刷新都从数据库现查现签发，避免"一个月前的旧名字"复活；
所有校验函数都强制检查签名算法必须是 HMAC，防算法混淆攻击（即伪造alg=none或换成非对称算法的常见 JWT 攻击）。

五、多层权限防护：Agent 调用工具前，先过三关

光有身份认证还不够，AgentRQ 对Agent 的每一次工具调用都做了门控。

第一关：Workspace 隔离

每个 workspace 有独立的 MCP 服务实例，Worker Agent 认证成功后只能看到自己这个 workspace——它的任务、消息、记忆、技能，看不到隔壁 workspace 的任何东西。跨 workspace 的操作必须走 Supervisor 通道的 OAuth2 用户级令牌。

第二关：Auto-allow 规则

Workspace 可以配置"免审批工具清单"（见 autoallow.go）。规则有三种粒度：

MCP 工具：mcp_servername_toolname精确匹配；
Shell 工具：Bash:git *这类基础命令通配（git status放行，rm -rf不放行）；
普通工具：按工具名精确匹配，如Read、Write。

第三关：人工审批流

未命中 auto-allow 规则的危险操作，Agent 的调用会挂起等待人类批准：请求经 SSE 推送到你的 Web/移动端界面，你在手机上点一下 Allow 或 Deny，结果再通过 MCP 通知回 Agent。这正是 AgentRQ "Human-in-loop" 名的由来——AI 跑得再快，油门也在人手里。

此外还有按用户的请求限流（workspace/task/message/telemetry/import 各自独立计数，见 ratelimit.go）和可配置的按 IP DDoS 防护（默认 20 请求/秒、超限封禁 5 分钟，见 .env.example 中的AGENTRQ_DDOS_*配置）。

六、守护进程侧：机器凭证也有一层保险

当你用agentrqd守护进程把本机注册到 AgentRQ 时，机器令牌（machine token）的保管同样讲究：

注册必须人在机器前：一次性注册码由人亲手敲进目标机器的终端，没有远程注册通道（见 enrol.go）；
令牌落盘即最小权限：每个 profile 一个独立文件，权限0600；父目录0700——即使文件被读出，目录权限也挡住了"到底有哪些 profile"这种元信息泄露（见 store.go）；
文件路径构造处会二次校验 profile ID 字符集，专门防御目录穿越攻击。

七、总结：AgentRQ 安全模型的三层纵深

层级	机制	防的是什么
身份层	OAuth2 授权码 + 人工同意页 + JWT 受众隔离	冒用身份、CSRF、令牌跨场景重放
数据层	AES-GCM 加密静态令牌 + 常数时间比较 + 强随机密钥生成	数据库拖库、时序攻击、弱密钥
行为层	Workspace 隔离 + auto-allow 规则 + 人工审批 + 限流/DDoS 防护	Agent 越权操作、跨空间窥探、接口滥用

对自托管用户来说，这套模型意味着三件实在的事：你持有自己的 Claude 订阅和机器，凭证永远签发在你的服务器名下；Agent 的能力边界由你划定，从精确到单条命令；每一类风险都有对应的最小化凭证，令牌泄露的爆炸半径被压缩到"一个用途、一分钟到两天"。

如果想深入源码，推荐按这条路径阅读：security.go → jwt.go → cimd.go → auth.md → consent.go，基本就能把 AgentRQ 的整个安全模型走通一遍。