委托
aidy 自己不持有任何权限。它对你 API 的每次调用都代表发起请求的用户,你的 API 像对待自己 UI 的请求一样鉴权。
POST /api/vm/vm-42/stop HTTP/1.1Host: console.example.comAuthorization: Bearer <the user's own credential, as aidy received it>Aidy-Assertion: <compact JWS>Content-Type: application/json
{"forced":false}Authorization(以及用户用 cookie 登录时的Cookie)是用户的凭据,原样透传。你的 API 照常鉴权。Aidy-Assertion证明这个确切的请求来自 aidy、代表这个用户、发生在某次运行中;对于需要审批的操作,还证明用户批准了这些确切的参数。
不带 Aidy-Assertion 的请求就是普通的用户请求。aidy 拉取 OpenAPI 文档和调用身份操作时,发出的也是普通请求。
断言是用 EdDSA(Ed25519)签名的 compact JWS。它的 protected header 为:
{ "alg": "EdDSA", "kid": "aidy-2026-11", "typ": "aidy-call+jwt" }claims 如下:
| Claim | 含义 |
|---|---|
iss |
aidy 实例的 URL。 |
aud |
宿主的 origin,https://console.example.com。 |
sub |
用户身份中的 subject。 |
ten |
用户的 tenant(如果有)。 |
sid、rid、cid |
会话、运行和工具调用的 id,用于审计。通过 MCP 调用时,cid 是 MCP 请求 id。 |
op |
目录操作名,stop_vm。 |
htm |
HTTP 方法。 |
htu |
宿主的公开源加上请求路径和查询串。 |
bsh |
请求体原始字节 SHA-256 的 base64url;没有请求体时为空内容的哈希。 |
apr |
审批 id,用户批准了此次调用时出现。 |
iat、exp |
签发时间和过期时间,单位为秒。exp - iat 不超过 60。 |
jti |
唯一 id,用于防重放。 |
请求带有断言时,除非以下各项全部成立,宿主都必须返回 401 和 aidy_assertion_invalid:
- 签名能用按
kid选出的、预先固定的 aidy 公钥验证。公钥来自你的配置,绝不来自请求。 aud是你的 origin,exp未过期(时钟偏差最多 60 秒),且jti在其exp之前没有出现过。htm、htu和bsh与实际收到的请求一致。sub和ten等于宿主根据Authorization解析出的身份。op正是提供这个方法和路径的目录操作。- 当
op为approval: always时,apr存在。
各语言的 host kit 都用一次调用完成这些检查:
| 宿主 | Kit |
|---|---|
| Python(FastAPI) | aidy.fastapi.AidyHost 中间件,或 verify_assertion 加 check_call |
| TypeScript | @aidy-dev/spec/delegation 中的 verifyAssertion 和 checkCall |
| Go | 在代码库内实现,并通过 conformance/delegation/vectors.json 中的共享测试向量验证 |
from aidy import check_call, verify_assertion
claims = verify_assertion( token, keys=keys, audience="https://console.example.com", method="POST", url=full_url_as_sent, body=raw_body, remember=lambda jti, until: cache.add(jti, until), # 见过时返回 False)check_call(claims, subject=user.id, tenant=user.tenant_id, op="stop_vm", approval="always")在审计日志中记录 actor = aidy、rid 和 apr,让每个 agent 动作都能追溯到一次运行和一次审批。
调用需要审批时,aidy 冻结已校验的参数,按 RFC 8785 的 JCS 计算 argsHash = base64url(SHA-256(JCS(arguments))),并连同哈希持久化审批。恢复时,aidy 只执行冻结的参数,且仅在存储的哈希仍然匹配时执行。每个审批最多执行一次,即使两个 worker 竞争也是如此。该调用的断言以 apr 携带审批 id。见审批。
凭据生命周期
Section titled “凭据生命周期”aidy 在一次运行期间把用户凭据保存在内存中,从不持久化。凭据在运行中途过期时,调用以 credential_expired 失败,运行暂停,直到用户的下一个请求带来新的凭据。延迟任务由宿主完成,不需要用户凭据。
aidy keys generate --kid aidy-2026-11 -o aidy-2026-11.private.jwkaidy keys generate 生成一对 Ed25519 密钥。私钥 JWK 是 aidy 的签名密钥,属于配置机密,会写入一个权限为 0600 的新文件,从不打印。公钥 JWK 会被打印出来,用于宿主配置:
{ "kty": "OKP", "crv": "Ed25519", "x": "…", "kid": "aidy-2026-11" }aidy 还在 /.well-known/aidy-keys.json 提供公钥,供查看。宿主在配置中固定公钥,校验时不去拉取。两个 JWK 都是可移植的:{kty, crv, x, kid} 和 {kty, crv, x, d, kid},不含 alg、key_ops 或 ext,Node、Bun、Deno 和 workerd 都能导入。在代码中加载私钥用 @aidy-dev/spec/delegation 的 importSigningKey,它也接受 Node 导出的带 alg 的 JWK。
轮换。 用新的 kid 生成密钥,先把公钥发布到所有宿主,再切换 aidy 的签名密钥。等旧密钥签发的断言都不可能再被接受时(断言最长 60 秒,另加 60 秒时钟偏差),再从宿主中移除旧公钥。
宿主自己的断言
Section titled “宿主自己的断言”有两类调用方向相反,由宿主发给 aidy:完成延迟任务(POST /aidy/v0/tasks/{taskId})和宿主任务(POST /aidy/v0/generate)。宿主为每个请求签发 Aidy-Host-Assertion:用固定在 aidy hostKeys(aidy-server 中为 AIDY_HOST_KEYS)里的宿主密钥签名的 EdDSA JWS,claims 与上面相同:
aud是 aidy 的 URL,iss是宿主的 URL;htu是 aidy 公开 URL 的源加上宿主请求的路径和查询串,即使代理把请求转发到内部地址也不变,因此在代理后面也能工作;bsh是请求体原始字节的哈希;exp - iat不超过 60 秒;每个jti只接受一次;op是延迟的操作名,或generate;sub(和ten)表示调用为谁执行。
校验失败返回 401 aidy_assertion_invalid。见 HTTP API。
宿主任务是后端在对话之外请求的一次模型补全:定时报告的摘要、导入条目的标题等。POST /aidy/v0/generate 使用与运行相同的模型链执行它,没有工具,也没有会话。
import { importSigningKey, sha256, signAssertion } from '@aidy-dev/spec/delegation';
const key = await importSigningKey(JSON.parse(process.env.HOST_PRIVATE_JWK!)); // 公钥配置在 aidy 的 hostKeys 中const url = 'https://console.example.com/aidy/v0/generate'; // aidy 的公开 URLconst body = JSON.stringify({ instructions: "Write the weekly report's summary.", input: 'Closed: 14 items. Opened: 9. Slowest: I-1647 (6 days).', schema: { type: 'object', properties: { headline: { type: 'string' } }, required: ['headline'] },});const now = Math.floor(Date.now() / 1000);const assertion = await signAssertion( { iss: 'https://console.example.com', aud: 'https://console.example.com', sub: 'u_1', // 任务为谁执行 sid: 'weekly-report', rid: 'weekly-report-2026-47', cid: 'weekly-report-2026-47', op: 'generate', htm: 'POST', htu: url, bsh: await sha256(body), iat: now, exp: now + 60, jti: crypto.randomUUID(), }, key,);const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Aidy-Host-Assertion': assertion }, body,});const { object } = await response.json(); // { headline: "…" }- 请求体为
{instructions?, input, schema?, maxOutputTokens?},input必填。 - 不带
schema时返回{text}。带schema时,aidy 要求模型输出 JSON(服务商支持 JSON 模式时也会启用),返回{object},一个符合该 schema 的值。不符合的回答会连同问题说明发回同一端点重试一次;第二次仍不符合则返回422 invalid_output。 - 请求中的
maxOutputTokens优先于端点的设置。任务受运行超时限制(504 timeout);503 model_unavailable表示没有端点能回答。
Python kit 没有签名辅助函数。Python 宿主可以用任意 Ed25519 JWS 库签发同样的 claims,也可以直接用 kit 依赖的 cryptography:
import base64, hashlib, json, time, uuidfrom cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
def b64url(data: bytes) -> str: return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
def host_assertion(key: Ed25519PrivateKey, kid: str, url: str, body: bytes, sub: str) -> str: now = int(time.time()) header = {"alg": "EdDSA", "kid": kid, "typ": "aidy-call+jwt"} claims = { "iss": "https://console.example.com", "aud": "https://console.example.com", "sub": sub, "sid": "job", "rid": "job", "cid": "job", "op": "generate", "htm": "POST", "htu": url, "bsh": b64url(hashlib.sha256(body).digest()), "iat": now, "exp": now + 60, "jti": str(uuid.uuid4()), } signing_input = f"{b64url(json.dumps(header).encode())}.{b64url(json.dumps(claims).encode())}" return f"{signing_input}.{b64url(key.sign(signing_input.encode()))}"