[RFC] External Subject Binding —— 让 NyxID 能 broker 第三方 channel bot 里的身份

[eanzhao]

相关：#505（NyxID as Capability Broker scope）、aevatarAI/aevatar#375（Aevatar 线上零 secret material + broker 边界），本提案对应 Aevatar 侧 discussion：aevatarAI/aevatar#400

背景

Aevatar 侧的 Lark bot 现在是个"共用账号"：任何人跟 bot 聊天都走 bot owner 的 NyxID 配置。产品方向要把 Lark bot 升级成带鉴权的 CLI 壳——每个 Lark user 用 /init 绑定自己的 NyxID 账号，之后他发的消息用自己的 LLM 额度、tool 权限、capability 跑。

更一般地：这是"第三方平台的外部 subject（Lark user / Telegram user / Discord user）绑定到 NyxID subject"的问题。Aevatar 是第一个消费方，但这个能力一旦建好，Aexon、Chronograph、未来任何走 NyxID 的 agent host 都能复用。

对 NyxID 的判断

这个需求不要求 NyxID 做 general vault。它要求的是 NyxID 把现有能力连起来：

已有能力	用法
jwt_keys + JWKS	签 binding callback JWT（跟 aevatarAI/aevatar#366 的 relay callback 同构）
/api/v1/keys	未来可以作为 binding 后用户选 key 的 UI 目标
LLM proxy	Aevatar 拿到 binding 后通过 broker 走这里
AI Services discovery	broker.ListAsync 的数据源
user services 概念	external binding 是它的"外部寻址入口"
现有 /cli-auth 登录页	扩展一个 binding_jti 参数即可

新增的只是"binding 的 lifecycle 管理 + 回调"，不是从零做凭证中心。

建议的新 API（草案）

1. 签发 binding challenge

POST /api/v1/bindings/challenges
Authorization: <Aevatar 服务身份，走 #505 规划中的 service-to-service auth>

{
  "external_subject": {
    "platform": "lark",
    "tenant": "ou_tenant_xxx",
    "external_user_id": "ou_user_yyy"
  },
  "requested_by": {                      // 给用户展示"谁在请求"的上下文
    "agent_name": "MyBot",
    "scope_id": "aevatar_scope_xxx"
  },
  "ttl_seconds": 300,
  "callback_url": "https://aevatar.example/api/webhooks/nyxid-binding-callback"
}

=> 200 OK
{
  "jti": "uuid",
  "interaction_url": "https://nyxid.example/cli-auth?binding_jti=...",
  "expires_at": "2026-04-25T12:15:00Z"
}

2. 交互页扩展

/cli-auth?binding_jti=<jti> —— 复用现有 CLI login 页的大部分逻辑，登录完成后多一步：把 challenge 消费掉 + 记录 (nyx_subject, external_subject) 绑定 + 触发回调。

UI 上需要对用户展示"你正在授权把 Lark 账号 ou_user_yyy 绑定到你的 NyxID 身份，绑定后这个 Lark 账号发送给 MyBot 的消息将使用你的 LLM 额度和配置"。

3. 回调 Aevatar

POST <callback_url>
X-NyxID-Binding-Token: <JWT signed with jwt_keys>

JWT header:
{
  "alg": "RS256",
  "kid": "<key id>"
}
JWT payload:
{
  "aud": "channel-binding/callback",
  "iss": "https://nyxid.example",
  "jti": "<same as challenge>",
  "sub": "<nyx_subject_id>",
  "external_subject": {...},
  "bound_at": 1234567890,
  "exp": ...,
  "iat": ...
}

重要：这是 JWT-only 认证，没有 shared secret，跟 aevatarAI/aevatar#366 的 relay callback 协议同构。Aevatar 侧用现有 NyxIdRelayAuthValidator 换个 aud 就能复用。

4. 查询 binding

GET /api/v1/bindings?platform=lark&tenant=...&external_user_id=...
Authorization: <Aevatar service 身份>

=> 200 OK
{
  "binding": {
    "nyx_subject_id": "...",
    "bound_at": "..."
  }
}
// 或 404 not bound

Aevatar 侧的 broker.ResolveBindingAsync 走这个。生产调用频次高，建议打 Aevatar cache + 合理的失效策略（NyxID 侧可以后续加 webhook 通知 revoke）。

5. Revoke

DELETE /api/v1/bindings
{
  "external_subject": {...}
}

用户侧也应该能在 NyxID 个人中心看到"我绑了哪些 external subject"并主动解绑。

跟 #505 capability broker 的关系

本提案是 #505 的身份侧前置条件：broker 要 issue capability handle，得先知道"正在请求的 external subject 对应哪个 NyxID user"。没有 binding 这层，capability broker 在 multi-sender 场景下拿不到 subject，就只能 fallback 到"调用方身份"（= bot owner），等于退回到今天 Aevatar 的问题根源。

建议把本提案纳入 #505 的 scope，拆成两条并行工作项：

• Track A：本提案，external subject binding lifecycle
• Track B：[Proposal] 扩展 user services 为通用 Capability Broker — 让 Aevatar 线上零 secret storage #505 已经在讨论的 capability issuance protocol（token exchange / MCP / A2A / GNAP 选型）

Track A 的 OpenAPI 可以先冻结，Track B 慢慢选型，两者不互相 block。

待决问题

1. Binding 粒度：(nyx_subject, external_subject) 是 1:1 还是 1:many？
   • 同一个 NyxID user 能不能把多个 Lark 账号绑过来？（推荐：允许，反向查询是 1:1）
2. Cross-tenant 语义：同一 Lark open_id 在不同 Lark tenant 下视为同一个还是不同？
   • 倾向不同（tenant 是 primary key 的一部分），避免企业组织间串身份
3. Service-to-service auth：Aevatar 怎么向 NyxID 证明"我是 Aevatar"？
   • 选项 A：共享 service account access token（简单但有 secret 管理问题）
   • 选项 B：mTLS
   • 选项 C：Aevatar 也走 JWT + JWKS，对称于 callback 方向
   • 这条跟 [Proposal] 扩展 user services 为通用 Capability Broker — 让 Aevatar 线上零 secret storage #505 的 service auth 讨论合并
4. Consent revocation propagation：用户在 NyxID 侧 revoke 后怎么通知 Aevatar？
   • 首版可以轮询（Aevatar 定期 ResolveAsync），长期用 webhook
5. Binding 审计日志：给用户看"这个绑定最近被用于什么 agent 调用了什么 tool"
   • 这是 capability broker 的自然副产品，放到 Track B

为什么值得做

• Aevatar、Aexon 之后任何 "third-party channel bot with per-sender identity" 都会复用这套
• 把"身份绑定"留在 NyxID，Aevatar 只管 agent runtime，边界干净（呼应 [RFC] Aevatar 线上零 secret material — 从 Day One 演化到 capability-broker 边界 aevatarAI/aevatar#375 的职责划分）
• 是 [Proposal] 扩展 user services 为通用 Capability Broker — 让 Aevatar 线上零 secret storage #505 里最具体、最可先落地的一个切片，可以作为 capability broker 的"第一个正式产品化场景"

评论区留给协议细节、UX、scope 讨论。