rungent核心概念
以用户身份调用
rungent 在你的产品里没有账号。它带着当前登录用户自己的凭据,以及一份写明操作的短时签名断言调用你的 API;你的 API 校验两者,像处理界面上的一次点击一样授权这次调用。
用户确认「Stop server gpu-train-01?」之后,rungent 向你的 API 发出这个请求:
POST /api/vms/vm-42/stop HTTP/1.1
Host: console.example.com
Authorization: Bearer <the user's own credential, as rungent received it>
Rungent-Assertion: eyJhbGciOiJFZERTQSIsImtpZCI6InJ1bmdlbnQtMjAyNi0xMSIsInR5cCI6InJ1bmdlbnQtY2FsbCtqd3QifQ…
Content-Type: application/json
{"forced":false}
你的 API 照常认证这个凭据,所以这次调用能做什么由用户自己的权限决定。其余的由断言证明:这个确切的请求是 rungent 发出的,代表这个用户,针对这个操作,并且是在用户确认了这组参数之后。
用户是谁#
rungent 不保存用户数据库。它通过目录中唯一一个 role: identity 的操作问你的 API,这是一个不带参数的 GET:
"/api/me": { "get": { "x-rungent": { "name": "whoami", "role": "identity" } } }
{ "subject": "u_123", "tenant": "t_9", "name": "Ada Lovelace", "locale": "zh-CN", "scopes": ["rungent:admin"] }
| 字段 | 含义 |
|---|---|
subject |
必填。用户在你的产品里的稳定 ID。 |
tenant |
凭据所在的组织或工作区,如果你的产品有这个概念。 |
name |
显示名。 |
locale |
语言标签,如 en 或 zh-CN;助手用这种语言作答,除非用户用别的语言书写。 |
scopes |
rungent:admin 允许用户修改 rungent 的模型设置并查看反馈。 |
rungent 用每个请求的凭据调用它,作为一次不带断言的普通请求,并按凭据把答复记住 60 秒。它返回 4xx 时,rungent 返回 401。对话属于某个 (subject, tenant):同一个人在两个租户里有两份历史,其他人都读不到。
用户的凭据#
rungent 原样转发请求里的 Authorization 和 Cookie 头,用户的其他请求头一概不转发。在你的 Web 应用里,这就是用户已有的登录会话,因为 rungent 就在你自己的域名下提供服务。MCP 客户端和 CLI 发送的是你的 API 认可的 Bearer 令牌。
rungent 只在一次运行期间把凭据留在内存里,从不存储。凭据在运行中途过期时,调用以 credential_expired 失败,用户的下一条消息会带来新的凭据。
断言绑定了什么#
Rungent-Assertion 是用 Ed25519 签名的紧凑 JWS(alg: EdDSA、typ: rungent-call+jwt,以及签名密钥的 kid)。它的声明把它绑定到一个请求:
| 声明 | 含义 |
|---|---|
iss |
rungent 实例的 URL |
aud |
你的源,https://console.example.com |
sub、ten |
用户的 subject 和 tenant |
op |
目录中的操作,stop_vm |
htm、htu |
方法,以及你的公开源加上路径和查询 |
bsh |
请求体原始字节的 SHA-256,base64url 编码(没有请求体时取空请求体的哈希) |
apr |
确认的 ID,在用户确认了这次调用时出现 |
sid、rid、cid |
对话、运行和工具调用,供你的审计日志使用 |
iat、exp |
签发和过期时间,相隔最多 60 秒 |
jti |
唯一 ID,保证断言只用一次 |
被偷走的断言几乎没有价值:它只对应一个方法、一个 URL 和一个请求体,有效期一分钟,而且只被接受一次。
校验断言#
不带 Rungent-Assertion 的请求就是普通的用户请求。带了断言的,除非以下各项全部成立,否则你的 API 以 401 和 rungent_assertion_invalid 应答:
- 签名能用你配置中固定的某个 rungent 公钥验证,按
kid选取。永远不要从请求中获取密钥。 aud是你的源,exp未过(时钟偏差最多 60 秒),jti之前没见过。htm和bsh与收到的请求一致,htu是你的公开源加上请求的路径和查询。sub和ten等于你根据请求自身凭据解析出的身份。op是承接这个方法和路径的目录操作。- 如果该操作是
approval: always,apr必须存在。
辅助函数会替你完成这些。在 TypeScript 里,verifyAssertion 执行第 1 到 3 项,checkCall 执行其余各项;快速开始把它们包成了一个 Hono 中间件:
import { checkCall, importPublicKeys, verifyAssertion } from 'rungent/delegation';
const keys = await importPublicKeys([RUNGENT_PUBLIC_JWK]);
const claims = await verifyAssertion(assertion, {
keys,
audience: 'https://console.example.com',
request: { method: 'POST', url: 'https://console.example.com/api/vms/vm-42/stop', body: rawBody },
remember: (jti, until) => replays.add(jti, until), // 之前见过时返回 false
});
checkCall(claims, { subject: user.id, tenant: user.tenantId, op: 'stop_vm', approval: 'always' });
在 FastAPI 里,RungentHost 是一个中间件,它根据你的路由匹配操作,并执行全部六项检查;见 Python 与其他技术栈,那一页也讲了其他语言。有三点容易出错:
- 公开 URL。 即使 rungent 通过内部地址访问你的 API,
htu写的也是你的公开源。如果前面的代理去掉了路径前缀,要把前缀补回去。 - 一份重放缓存。 承接你 API 的每个 worker 都必须共享已见
jti的记录,否则重放请求可能落到一个从没见过它的 worker 上。 - 在边界处止步。 把请求转发给其他服务的网关,要先去掉
Rungent-Assertion;断言只属于完成校验的那个服务。
在审计日志里记录 actor = rungent、rid 和 apr,这样经由 rungent 做出的每次变更都能追溯到一次运行和一次确认。
密钥与轮换#
npx rungent keys generate --kid rungent-2026-11 -o rungent-2026-11.private.jwk
它把私钥,也就是 rungent 的签名密钥,写进一个只有你能读的新文件,并打印出公钥 JWK,供你的 API 配置使用。rungent 还在 /.well-known/rungent-keys.json 提供公钥,便于查看。轮换步骤:
- 用新的
kid生成一个密钥。 - 把它的公钥 JWK 加到你的 API 里,与旧公钥并存,然后部署。
- 把 rungent 的签名密钥换成新的私钥,然后部署。
- 两分钟后(断言有效期 60 秒,加上 60 秒时钟偏差),从你的 API 中删除旧公钥。
从你的 API 调用 rungent#
有两种调用方向相反:完成延后任务,以及宿主任务(为你的后端做一次模型补全,比如周报的摘要)。你的 API 为每次调用签一个 Rungent-Host-Assertion:声明相同,用你自己的密钥签名,rungent 把这个密钥固定在 hostKeys 里,aud 设为 rungent 的 URL。见 HTTP API。
接下来#
表单与确认讲 apr 从哪里来,以及在此之前用户看到什么。
供 Agent 读取: acting-as-the-user.md编辑此页