[RFC] Per-sender NyxID binding for channel bots —— 把 Lark bot 当作带鉴权的 CLI

[eanzhao]

相关：#375（Aevatar 线上零 secret material + capability broker 边界）、ChronoAIProject/NyxID#505（NyxID as Capability Broker scope）、本提案对应 NyxID 侧讨论：ChronoAIProject/NyxID#511

背景

目前 Lark bot 的消息链路是：

• Lark webhook → NyxID relay → Aevatar /api/webhooks/nyxid-relay
• NyxIdRelayAuthValidator 验 JWT → 解出 scope_id
• scope_id 来自 ChannelBotRegistrationEntry，也就是谁注册了这个 bot
• ConversationGAgent actor id = {canonicalKey}:scope:sha256(scope_id)
• ChannelConversationTurnRunner.BuildReplyMetadata 把 scope_id 和 user_access_token 塞进 AgentToolRequestContext 去打 LLM

结果：任何人跟 Lark bot 聊天都是在代表 bot owner 的 NyxID 账号说话。消息里的 sender.canonical_id（Lark user_open_id）只被记录，不影响 credential 选择。

对于个人生产力场景（每个人自己的 LLM 额度、自己的 NyxID 配置、自己的 tool 权限），这是错误的默认值。

提议

把"Lark bot"理解为一个带完整鉴权的 CLI 壳：每个 Lark user 第一次交互时走 /init 走一轮 NyxID 登录，之后这个 Lark user 发来的消息用他自己的 NyxID subject 跑 LLM、tool、capability。

本质上是"外部 subject 绑定 NyxID subject"的一个实例 —— 以后 Telegram、Discord、Slack 同理。

架构草案（延续 #375）

新概念

名字	语义
ExternalSubjectRef	(platform, tenant, external_user_id)
NyxSubjectRef	NyxID stable subject（opaque）
ExternalIdentityBindingGAgent	持久化 ExternalSubjectRef → NyxSubjectRef 的权威 actor
BindingChallenge	NyxID 签发的短期绑定票 + 打开用的 URL

grain state 只存 NyxSubjectRef 和 jti（都是 opaque 标识符，不是 secret material），满足 #375 的不变量。

/init 交互流程

1. Lark user 发 "/init"
2. turn runner 前置 slash-command 识别（不走 LLM，避免幻觉）
3. 调 broker.StartExternalBindingAsync(externalSubject)
   → 拿到 BindingChallenge { url, jti, expires_at }
4. 落 BindingChallengeIssuedEvent 到 ExternalIdentityBindingGAgent
5. 回 Lark user："打开 {url} 完成 NyxID 登录（5 分钟内有效）"
6. 用户浏览器打开 → NyxID 登录 → NyxID 侧记录 "当前 NyxID user 完成了 jti=xxx 的 binding"
7. NyxID 主动回调 Aevatar `/api/webhooks/nyxid-binding-callback`
   （复用 #366 的 callback JWT + JWKS，只换 aud = channel-binding/callback）
8. Aevatar 验签 → 落 ExternalIdentityBoundEvent
9. 下次消息进来，turn runner resolve binding → 用 nyx_subject 问 broker 拿
   short-lived capability handle → 塞进 AgentToolRequestContext

Handle 不跨 event sourcing 边界，跟 reply_token 一样只活在 actor runtime state，一次 turn 用完即弃。

需要改的地方

• 新增 Aevatar.GAgents.Channel.Identity（或类似命名）承载 ExternalIdentityBindingGAgent + projection + IExternalIdentityBindingQueryPort
• ChannelConversationTurnRunner.RunInboundAsync 开头增加 slash-command 前置路由
• BuildReplyMetadata 从"透传 bot owner user_access_token"改成"ResolveAsync 找 nyx_subject → broker.IssueShortLivedAsync → 写 nyxid.capability_handle"
• key 名建议从 nyxid.access_token 改成 nyxid.capability_handle，更诚实
• Arch test（承接 [RFC] Aevatar 线上零 secret material — 从 Day One 演化到 capability-broker 边界 #375 Layer 3）：CapabilityHandle / BindingChallenge 不得出现在任何 grain state / event / projection document 字段树

需要 NyxID 侧做什么

见对应的 NyxID discussion（见顶部链接）。总结：

1. POST /api/v1/bindings/challenges 签 challenge
2. 扩展现有 /cli-auth 页支持 binding_jti 参数
3. 登录完成后主动回调 Aevatar webhook（JWT + JWKS，复用 jwt_keys）
4. GET /api/v1/bindings?external_subject=... 查询
5. revoke 端点

这些都在 NyxID 现有产品范围内（身份 + credential broker），不是让它做 general vault。跟 #505 的 capability broker scope 放在一起就能装下。

待决问题

1. 群聊语义：群里有人绑定有人没绑定，未绑定的 sender 怎么处理？
   • A. 强制 /init，否则拒答（最纯粹）
   • B. 回落 bot owner（兼容但暴露配额）
   • C. 群级统一绑定到群主
   • 倾向 A，但需要产品决策
2. conversation actor 归属：现在 scope = bot owner hash。要不要改成 sender 的 nyx_subject？
   • 倾向不改。bot 是场所，user 是访客；场所保存对话，访客用自己的身份"打电话"。
3. /init 是 turn runner 前置 intent 还是 LLM tool？
   • 倾向两者都有：slash-command 直通保证可靠；注册 BindingTool 让 LLM 也能触发自然语言场景。
4. 未绑定的 UX：纯文本兜底 vs Lark interactive card。first cut 纯文本即可。

跟 #375 的关系

这个 RFC 是 #375 的具体应用场景 #1，不是并行提案：

• INyxIdCapabilityBroker 由本提案驱动落地，但 broker 的通用约束（arch test、zero secret material）完全承袭 [RFC] Aevatar 线上零 secret material — 从 Day One 演化到 capability-broker 边界 #375
• [RFC] Aevatar 线上零 secret material — 从 Day One 演化到 capability-broker 边界 #375 提过的 ListAsync / IssueShortLivedAsync 保留，本提案补充 StartExternalBindingAsync / ResolveBindingAsync / RevokeBindingAsync 三个 binding-specific 方法
• [RFC] Aevatar 线上零 secret material — 从 Day One 演化到 capability-broker 边界 #375 第 8 节的开放问题 1（broker 走哪条协议）在本提案里得到收窄：内部用自有契约，但边界兼容 OAuth Token Exchange 风格

落地顺序

1. 跟 NyxID 对齐 binding 协议 OpenAPI（不写码）
2. Aevatar 侧起 ExternalIdentityBindingGAgent + proto + projection
3. INyxIdCapabilityBroker 接口 + stub 实现
4. turn runner 集成 + slash command
5. NyxID 侧做完 → 开 binding webhook
6. CI 守卫补齐（承接 [RFC] Aevatar 线上零 secret material — 从 Day One 演化到 capability-broker 边界 #375 Layer 3）

评论区留给 scope / UX / 协议选型讨论。

[eanzhao]

[2026-04-28 update] 经过安全分析,本评论原推荐的"aevatar 本地加密持 refresh_token (Local stop-gap)"路径已被否决。最终方向走 NyxID broker 模型:aevatar 仅持不透明 binding_id,refresh_token 全程在 NyxID 加密存储。详见 ADR-0017 (aevatarAI/aevatar#477) 与 NyxID 侧依赖 ChronoAIProject/NyxID#549。

下文保留原分析(NyxID 已有 OAuth/OIDC surface 与 RFC 8693 Token Exchange)作为评估上下文,但结论部分(走 Local)请以 ADR-0017 为准。

---

NyxID 已经是完整 OAuth/OIDC server,#400 的 5 个 ask 大部分是已有能力的重复发明

回头扫了一遍 (~/Code/NyxID),发现现在 NyxID 已经实现:

• /.well-known/openid-configuration + /.well-known/oauth-authorization-server + /.well-known/jwks.json
• /oauth/authorize (Authorization Code + PKCE,支持任意 state 透传)
• /oauth/token (含 RFC 8693 Token Exchange grant_type:urn:ietf:params:oauth:grant-type:token-exchange)
• /oauth/userinfo / /oauth/introspect / /oauth/revoke (RFC 7009)
• /cli-auth 页面已透传任意 state 参数

#400 列的 5 个 NyxID 侧改动 → 已有 OAuth primitive 的对照:

RFC 要 NyxID 加的	NyxID 现状
POST /api/v1/bindings/challenges 签 challenge JWT	OAuth state 参数已承载 correlation id
扩展 /cli-auth 接受 binding_jti	cli-auth 已透传任意 state
NyxID 主动 webhook 回调 aevatar	OAuth 标准是浏览器跳 redirect_uri,不需要服务端主动推
GET /api/v1/bindings?external_subject=...	external→nyx 映射归 aevatar 自己持;拿 nyx subject 用 /oauth/userinfo
revoke 端点	/oauth/revoke 已有

但 RFC 8693 Token Exchange 不能完全替代 broker 语义 —— 它仍要求接入方先持有 user 的 access_token(subject_token),解决不了"aevatar 零持有"。这部分是真正缺失的能力,通过 NyxID#549 补齐。

最终方向:NyxID broker,aevatar 持不透明 binding_id

aevatar 注册成 NyxID OAuth client (aevatar-channel-binding,带 broker_binding scope),/init 走标准 Authorization Code + PKCE,但 /oauth/token 在 broker scope 下返回 binding_id 取代 refresh_token:

/init
  -> aevatar 生成 state(=correlation_id) + PKCE,落 BindingChallengeIssuedEvent
  -> 回 Lark: "{nyxid}/oauth/authorize?...&state={correlation_id}&code_challenge=...&scope=openid+broker_binding"
  -> 用户登录 -> NyxID 302 回 aevatar /api/oauth/nyxid-callback?code=...&state=...
  -> aevatar /oauth/token 换得 { access_token, binding_id }   <-- NyxID 不返 refresh_token
  -> /oauth/userinfo 拿 sub(NyxSubjectRef)
  -> 落 ExternalIdentityBoundEvent { external_subject, nyx_subject, binding_id }

turn
  -> ResolveAsync(externalSubject) -> binding_id
  -> POST {nyxid}/oauth/bindings/{binding_id}/token (client_credentials) -> 短期 access_token
  -> 塞 AgentToolRequestContext (key 名 `nyxid.capability_handle`)

aevatar grain state / projection / log 持有 zero long-lived secret material,对齐 #375 不变量。

为什么否决 Local stop-gap

aevatar 是跑任意 LLM tool 的 agent runtime(prompt injection / tool 越权属于固有风险)。这类 host 上 grain state 内的 secret material 即便加密,RCE 后攻击者几乎一定能拿到 IDataProtection key ring,加密形同虚设。

场景	Local(aevatar 加密持 refresh_token)	Remote(NyxID broker)
Event store 备份泄露	加密保护;需同时拿到 key ring 才能解	完全不可解(grain 只存 binding_id + opaque sub)
Aevatar RCE	全量 binding 长期 token 一锅端,可静默 impersonate 全部用户	攻击者持 binding_id + client_secret 仍受 NyxID 端 rate-limit、audit、用户 revoke 约束;短期 token TTL ≤ 5 min
Prompt injection / tool 越权	间接读 grain state → 加密 token 暴露	grain state 里没 secret material 可读
User 主动 revoke	必须双向同步,漏一步备份内 token 仍活	NyxID 单向操作,source of truth

第二个权衡是 unblock 速度 vs. 长期正确性:Local 立即 unblock,但 NyxID#549 落地后还要做数据 wipe + 加密字段下线,迁移成本不便宜;直接走 Remote 等待时间换的是终态架构上 zero secret material。aevatar 当前 bot owner-shared 模式可继续运行(不 regression),等待是可接受的代价。

落地路径

aevatar 侧实现 gated on ChronoAIProject/NyxID#549。在此之前可平行落地:

• INyxIdCapabilityBroker 接口 + proto
• ExternalIdentityBindingGAgent + projection + IExternalIdentityBindingQueryPort(state 仅存 opaque binding_id + nyx_subject)
• ChannelConversationTurnRunner.RunInboundAsync slash-command 前置路由(/init、/unbind)
• /api/oauth/nyxid-callback endpoint
• InMemoryCapabilityBroker 测试 fake

NyxID#549 ready 后:NyxIdRemoteCapabilityBroker 实现接好真实 endpoint → end-to-end 测试 → 灰度 → 切生产。

详见 ADR-0017 (#477)。