[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 / 协议选型讨论。