# 以用户身份调用

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

*rungent 位于人们使用的入口与产品 API 之间*

用户确认「Stop server gpu-train-01?」之后，rungent 向你的 API 发出这个请求：

```http
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`：

```json
"/api/me": { "get": { "x-rungent": { "name": "whoami", "role": "identity" } } }
```

```json
{ "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` 执行其余各项；[快速开始](quickstart.md#verify-the-assertion)把它们包成了一个 Hono 中间件：

```ts
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 与其他技术栈](python.md#verify-the-assertion)，那一页也讲了其他语言。有三点容易出错：

- **公开 URL。** 即使 rungent 通过内部地址访问你的 API，`htu` 写的也是你的公开源。如果前面的代理去掉了路径前缀，要把前缀补回去。
- **一份重放缓存。** 承接你 API 的每个 worker 都必须共享已见 `jti` 的记录，否则重放请求可能落到一个从没见过它的 worker 上。
- **在边界处止步。** 把请求转发给其他服务的网关，要先去掉 `Rungent-Assertion`；断言只属于完成校验的那个服务。

在审计日志里记录 `actor = rungent`、`rid` 和 `apr`，这样经由 rungent 做出的每次变更都能追溯到一次运行和一次确认。

## 密钥与轮换

```bash
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](http-api.md#host-assertions)。

## 接下来

[表单与确认](forms-and-approvals.md)讲 `apr` 从哪里来，以及在此之前用户看到什么。
