rungent v0.5.1
EN中文

rungent核心概念

以用户身份调用

rungent 在你的产品里没有账号。它带着当前登录用户自己的凭据,以及一份写明操作的短时签名断言调用你的 API;你的 API 校验两者,像处理界面上的一次点击一样授权这次调用。

人和 Agent 在这里工作产品内助手页面旁的助手面板⌘K 搜索资源与文档MCP 客户端Claude Code、Cursor 等CLI你的品牌命令skill.md · llms.txt给任何 Agentrungent一份目录你的 OpenAPI,按用户可见路由 → 表单 → 确认每次变更同一条路径Agent 循环模型链、重试、上限会话与流式AG-UI 事件,可续传搜索与知识联邦检索,带引用你的产品HTTP APIOpenAPI 3.1 + x-rungent身份当前登录的是谁权限由你的规则决定页面表单与业务页面同一张表单文档回答引用它们用户自己的会话用户凭据+ 签名断言结果,你的报错每次调用都以当前登录用户的身份执行,rungent 没有自己的权限。人和 Agent 在这里工作产品内助手页面旁的助手面板⌘K 搜索资源与文档MCP 客户端Claude Code、Cursor 等CLI你的品牌命令skill.md · llms.txt给任何 Agent用户自己的会话rungent一份目录你的 OpenAPI,按用户可见路由 → 表单 → 确认每次变更同一条路径Agent 循环模型链、重试、上限会话与流式AG-UI 事件,可续传搜索与知识联邦检索,带引用用户凭据+ 签名断言你的产品HTTP APIOpenAPI 3.1 + x-rungent身份当前登录的是谁权限由你的规则决定页面表单与业务页面同一张表单文档回答引用它们

每次调用都以当前登录用户的身份执行,rungent 没有自己的权限。

用户确认「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 应答:

  1. 签名能用你配置中固定的某个 rungent 公钥验证,按 kid 选取。永远不要从请求中获取密钥。
  2. aud 是你的源,exp 未过(时钟偏差最多 60 秒),jti 之前没见过。
  3. htm 和 bsh 与收到的请求一致,htu 是你的公开源加上请求的路径和查询。
  4. sub 和 ten 等于你根据请求自身凭据解析出的身份。
  5. op 是承接这个方法和路径的目录操作。
  6. 如果该操作是 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 提供公钥,便于查看。轮换步骤:

  1. 用新的 kid 生成一个密钥。
  2. 把它的公钥 JWK 加到你的 API 里,与旧公钥并存,然后部署。
  3. 把 rungent 的签名密钥换成新的私钥,然后部署。
  4. 两分钟后(断言有效期 60 秒,加上 60 秒时钟偏差),从你的 API 中删除旧公钥。

从你的 API 调用 rungent#

有两种调用方向相反:完成延后任务,以及宿主任务(为你的后端做一次模型补全,比如周报的摘要)。你的 API 为每次调用签一个 Rungent-Host-Assertion:声明相同,用你自己的密钥签名,rungent 把这个密钥固定在 hostKeys 里,aud 设为 rungent 的 URL。见 HTTP API。

接下来#

表单与确认讲 apr 从哪里来,以及在此之前用户看到什么。

供 Agent 读取: acting-as-the-user.md编辑此页