[Channel RFC] Adopt Lark -> NyxID -> Aevatar relay webhook; make Nyx the sole credential authority

[eanzhao]

Parent RFC: #254
Relates to: #261 (closed by #288), #288, #289, #294, #295
Supersedes for Lark: #294 Deliverable A

Decision

This issue is scoped to Lark only and adopts exactly one target topology:

Lark Service -> NyxID -> Aevatar

The older direct path

Lark Service -> Aevatar

is a retired implementation, not a fallback contract.

This is the only webhook architecture compatible with the hard requirement for this issue:

• NyxID is the sole authority for Lark channel-bot credentials and platform API calls
• Aevatar persists zero Lark credentials
• Aevatar does not perform Lark signature verification, decryption, or direct platform API calls
• Aevatar does not keep a rollback-window direct Lark ingress contract

Long connection is out of scope for this issue and deferred to future voice / gateway work.
Telegram migration is also out of scope here and should be handled in a separate follow-up.

Why This Path

Direct Lark -> Aevatar makes Aevatar own verification_token, encrypt_key, callback signature verification, AES-CBC decryption, and platform-specific webhook parsing.
That conflicts with the target of "Aevatar stores no Lark credentials".

NyxID already owns the channel webhook receiver, route resolution, callback forwarding, and async reply surface.
Therefore the production path for this issue is:

1. Lark webhook URL points to NyxID
2. NyxID verifies/decrypts/parses/stores inbound
3. NyxID pushes CallbackPayload to Aevatar
4. Aevatar processes the turn and replies through POST /api/v1/channel-relay/reply

The outbound delta in this issue is contract migration:

• from Nyx proxy + persisted Nyx session/refresh token assumptions
• to channel-relay/reply + callback-scoped Nyx relay JWT

Hard Constraints

• Aevatar must not persist app_id, app_secret, verification_token, encrypt_key, platform access tokens, Nyx user session tokens, Nyx refresh tokens, Nyx API keys, or Nyx API-key-hash-equivalent signing material in actor state, readmodels, or local secret stores for this path.
• Aevatar must not keep a second Lark webhook ingress or rollback-window direct callback contract for Lark.
• Aevatar may keep only non-secret identifiers returned during provisioning or required for routing/query, such as nyx_channel_bot_id, nyx_agent_api_key_id, route_id, status flags, and timestamps.
• Callback-scoped Nyx relay JWTs supplied by Nyx may be used in-memory during the current request / turn only. They must not be persisted to actor state, readmodels, or local secret stores.
• Current Nyx limitation: Lark callback forwarding only covers im.message.receive_v1; card.action.trigger is not forwarded today.
• Current Nyx limitation: Lark webhook registration is still manual in the Lark Developer Console; Nyx register_webhook() is a no-op.

Target Contract

Inbound

• Lark callback URL is Nyx webhook URL: POST /api/v1/webhooks/channel/lark/{bot_id}
• Aevatar receives only Nyx relay callbacks at POST /api/webhooks/nyxid-relay
• Nyx pushes CallbackPayload plus Nyx auth headers
• Aevatar acknowledges with HTTP 202 only after durable ingress commit; synchronous reply bodies are not part of the target contract

Callback Auth

• Nyx callback auth is centered on X-NyxID-User-Token, which in current Nyx is a relay-scoped JWT minted per callback and scoped to the assigned agent key.
• Aevatar must validate that JWT using Nyx OIDC discovery + JWKS, including issuer/audience checks, signature validation, TTL handling, JWKS cache/refresh, kid rotation, and bounded clock-skew handling.
• Current Nyx relay JWTs carry relay_api_key_id; current Nyx auth middleware maps that into AuthUser.api_key_id, so the same callback-scoped relay JWT is the intended auth surface for POST /api/v1/channel-relay/reply when the conversation's agent_api_key_id matches.
• Aevatar binds the callback to its stored non-secret registration identifiers and payload message/conversation identity.
• X-NyxID-Signature remains defense-in-depth only under the current zero-secret constraint.

Outbound

• Turn replies go through POST /api/v1/channel-relay/reply
• The reply key is Nyx message_id, not platform message_id
• Auth uses the callback-scoped Nyx relay JWT from the current Nyx callback, in-memory only
• No direct Lark send path remains in Aevatar for this issue

Proactive Outbound

This issue does not establish a new proactive channel-send credential model.
It covers inbound-triggered turns and their async replies.
Any future proactive send contract must be handled in a separate NyxID/Aevatar issue.

Scope

In

• adopt Lark -> NyxID -> Aevatar as the only supported production ingress path for Lark
• remove Aevatar-side Lark credential ownership and platform crypto from the Lark production runtime path
• move turn-reply path to Nyx channel-relay/reply
• prune all credential-bearing fields from Lark channel registration state/readmodel
• redesign card-action-dependent flows to text / open_url / deep-link interactions where needed
• explicitly migrate shipped social_media template and approval-style card flows away from card.action.trigger

Out

• direct Lark -> Aevatar as a supported runtime or rollback contract
• Aevatar-side vault semantics for Lark credentials
• proactive outbound credential model
• NyxID-side feature work such as card.action.trigger forwarding or programmatic webhook registration
• voice / long-connection design
• Telegram migration

Deliverables

A. Lock the architecture to Nyx relay webhook

• Record in an ADR under docs/decisions/ that production ingress for Lark is Lark -> NyxID -> Aevatar
• Record that the Lark callback URL points to Nyx, not Aevatar
• Record that Aevatar receives only Nyx relay callbacks at /api/webhooks/nyxid-relay
• Record that no rollback-window direct Lark callback contract remains
• Record explicitly that for Lark, this issue supersedes [Channel RFC] Lark outbound + streaming wire-through on LarkChannelAdapter (post-#261) #294 Deliverable A and sets the outbound target contract to channel-relay/reply

B. Provisioning / ownership model

• Registration in Aevatar stores only non-secret Nyx handles:
  • nyx_channel_bot_id
  • nyx_agent_api_key_id
  • route_id if Aevatar creates and stores it during provisioning
  • status flags / timestamps
• If Aevatar accepts app_id / app_secret during provisioning, it forwards them to Nyx and does not persist them locally
• Document the current manual Lark console step: the webhook URL must point to Nyx until Nyx supports programmatic registration

C. Inbound runtime refactor

• Retire production use of POST /api/channels/lark/callback/{registrationId}
• Remove Lark URL verification, signature verification, AES-CBC decryption, and direct platform event parsing from the supported Lark runtime path
• Make /api/webhooks/nyxid-relay the inbound edge
• Change the Nyx relay endpoint contract to:
  • verify Nyx-issued relay JWT
  • map CallbackPayload to typed ChatActivity / channel ingress message
  • commit durable ingress
  • return 202
  • never rely on sync reply bodies

D. Outbound runtime refactor

• Introduce INyxChannelRelayClient or equivalent outbound port implementation
• Use Nyx message_id from the callback payload for reply correlation
• Use the callback-scoped relay JWT in-memory only for channel-relay/reply
• Replace the current Lark reply contract assumption (proxy + persisted Nyx session/refresh token) with channel-relay/reply + callback relay JWT

E. Schema / state / readmodel cleanup

From channel_runtime_messages.proto, actor state, projector, and readmodel:

• remove encrypt_key
• remove verification_token
• remove credential_ref for Lark channel registrations
• remove nyx_user_token
• remove nyx_refresh_token
• remove nyx_provider_slug from the Lark runtime path if it only exists to support the older Nyx proxy contract
• add nyx_channel_bot_id
• add nyx_agent_api_key_id
• add any other non-secret route/status identifiers actually required by runtime behavior

F. Relay auth hardening

• Implement real Nyx JWT validation for /api/webhooks/nyxid-relay using OIDC discovery + JWKS
• Cover issuer/audience validation, signature validation, TTL/expiry checks, JWKS refresh/caching, kid rotation, and bounded clock skew
• Reject missing / invalid / mismatched callback auth
• Do not persist the raw relay JWT outside the current request / turn

G. Card behavior under current Nyx constraints

Because Nyx Lark ingress currently forwards im.message.receive_v1 only:

• display cards are allowed if they fit the current Nyx reply contract
• open_url / deep-link cards are the supported interactive pattern in this issue
• the shipped social_media template and approval-style flows that currently depend on card.action.trigger must be redesigned before cutover
• this issue must not keep a second direct Aevatar Lark webhook path just to preserve card callbacks

H. Cutover

• create / verify the Nyx callback route to Aevatar
• build /api/webhooks/nyxid-relay JWT validation and channel-relay/reply reply path first
• flip the Lark Developer Console callback URL to Nyx
• remove the direct Aevatar Lark callback path from the supported runtime contract
• return 410 or delete POST /api/channels/lark/callback/{registrationId}

Acceptance

• ADR under docs/decisions/ records Lark -> NyxID -> Aevatar as the only supported production webhook topology for this issue
• Production Lark callback URL points to Nyx, not Aevatar
• Aevatar persists zero Lark credentials in actor state and readmodels
• Aevatar persists zero long-lived Nyx session/refresh/API-key credentials for this relay path
• /api/webhooks/nyxid-relay validates Nyx relay JWT via JWKS and returns 202 after durable ingress commit
• Replies use Nyx channel-relay/reply with Nyx message_id
• Callback-scoped relay JWT is used in-memory only and is not persisted
• encrypt_key, verification_token, credential_ref, nyx_user_token, and nyx_refresh_token are removed from the Lark registration proto/state/readmodel path
• ChannelBotRegistrationDocument contains only non-secret identifiers / status fields for Lark
• social_media / approval flows no longer depend on card.action.trigger; they work through text or open_url / deep-link interactions over the Nyx relay path
• POST /api/channels/lark/callback/{registrationId} is deleted or returns 410 Gone
• No rollback-window direct Lark callback contract remains

Relationship to #295

For the target relay design defined here:

• reply auth comes from the callback-scoped Nyx relay JWT
• that JWT is used in-memory only
• no per-registration or Aevatar-wide persisted Nyx session/refresh token is part of the target end state

So #295 is not a dependency for the target end state of this issue.

References

• Parent RFC: [RFC] Aevatar Chat — Multi-Channel Adapter Architecture #254
• Aevatar direct callback path:
  • agents/Aevatar.GAgents.ChannelRuntime/ChannelCallbackEndpoints.cs
  • agents/Aevatar.GAgents.ChannelRuntime/Adapters/LarkPlatformAdapter.cs
• Aevatar current Nyx relay endpoint:
  • agents/Aevatar.GAgents.NyxidChat/NyxIdChatEndpoints.cs
• Nyx webhook + relay path:
  • ~/Code/NyxID/backend/src/routes.rs
  • ~/Code/NyxID/backend/src/handlers/channel_webhooks.rs
  • ~/Code/NyxID/backend/src/services/channel_routing_service.rs
  • ~/Code/NyxID/backend/src/handlers/channel_relay.rs
  • ~/Code/NyxID/backend/src/services/channel_relay_service.rs
  • ~/Code/NyxID/backend/src/crypto/jwt.rs
  • ~/Code/NyxID/backend/src/mw/auth.rs
  • ~/Code/NyxID/backend/src/handlers/oidc_discovery.rs
  • ~/Code/NyxID/backend/src/services/channel_adapters/lark.rs

[eanzhao]

Review

Architecture call: 方向对

把生产入口锁死为 Lark → NyxID → Aevatar、让 Nyx 作为唯一凭据权威——这是对的。Aevatar 侧的 crypto/decrypt 是真复杂度（ChannelCallbackEndpoints.cs 693 行 + LarkPlatformAdapter.cs:633-652 的 AES-CBC），Nyx 已经实现了一整套（channel_webhooks.rs:119-458）。Lark 凭据 + crypto 只在一处比两处好。

已核对的声明（✓）

• 直连 /api/channels/lark/callback/{registrationId} 确实存在，签名 + AES-256-CBC（ChannelCallbackEndpoints.cs:24、LarkPlatformAdapter.cs:147-172, 633-652）。
• /api/webhooks/nyxid-relay 已在 agents/Aevatar.GAgents.NyxidChat/NyxIdChatEndpoints.cs:34。
• Nyx 端点确实存在：/api/v1/webhooks/channel/lark/{bot_id}、/api/v1/channel-relay/reply、.well-known/openid-configuration、.well-known/jwks.json（只有 RS256）。
• Nyx Lark adapter 丢弃 im.message.receive_v1 以外全部事件（lark.rs:341-343）；register_webhook() 是字面 no-op（lark.rs:427-436）。
• 五个凭据字段（encrypt_key、verification_token、credential_ref、nyx_user_token、nyx_provider_slug）同时存在于 ChannelBotRegistrationEntry 和 ChannelBotRegistrationDocument。

需要在 RFC 里先消化的问题（⚠️）

1. Reply 鉴权契约和 Nyx 现状冲突——关键

RFC §Outbound："Auth uses the callback-scoped relay token from the current Nyx callback, in-memory only." 但 channel_relay.rs:209-217 要求 api_key_id 鉴权，缺则 403。Nyx 铸造的 relay token 是单向的（webhook → Aevatar）。Aevatar 要调 channel-relay/reply，必须出示自己的 Nyx API key——这本身是 secret-equivalent material，还是得存在某处。两种选项：

• Nyx 的 async_reply handler 改成接受 callback-scoped relay token 作为替代鉴权方式；或
• RFC 承认一个平台级 Nyx API key 存在于 channel registration 之外（不是 per-bot），然后把 "zero persisted credentials" 收窄为 "zero per-bot Lark credentials"。

这得在 issue 里敲定，不是实施时再发现。

2. scope_id / route_id Nyx 今天不下发

RFC §B 把它们列为 Aevatar 要保留的非敏感标识。channel_routing_service.rs 的 AgentRoute 只暴露 conversation.id、conversation.agent_api_key_id、callback_url、api_key_id。要么把这两个字段从 proto 清单里删掉，要么把"Nyx 开始下发"列为 Nyx 侧的前置需求。

3. X-NyxID-Signature 的作用被低估

Nyx 每次回调都带 HMAC-SHA256（channel_relay_service.rs:310-321）。RFC 说它 "audit/debug"。如果 Aevatar 跳过 HMAC 校验，又没把 JWKS 校验接完整（TTL、kid rotation、clock skew 等），relay edge 就没有任何密码学鉴权了。建议：HMAC 作为纵深防御保留，JWT via JWKS 是首要 bearer 检查——RFC 里写清楚。

4. JWKS 校验是新代码，不是 rename

当前 NyxIdChatEndpoints.cs:658-685 解 JWT 不验签，只读 sub。上 OIDC discovery + JWKS + cache + kid rotation 是个真工作量，带 config / HttpClient / rotation 策略。Deliverable F 里要明确写出来，不然会被当成"把校验接上"这种小活。

5. 与在飞 PR 的顺序是隐式的

Aevatar.GAgents.Channel.Lark 在 dev 上并不存在——PR #288 还开着，#294 是 outbound 接线。#294 Deliverable A 强制在 (A1) Nyx 代理 vs (A2) 直连 Lark OAuth + tenant_access_token cache 之间选。如果 #294 先落 A2，#296 只能把它删掉。RFC 里需要显式写：#296 supersedes #294 Deliverable A；outbound 走 channel-relay/reply，不讨价还价。 否则一定返工。

6. social_media template 是具体的迁移阻塞点

AgentBuilderTemplates.cs:79-157（social_media）+ ChannelCardActionRouting.cs:5-147 用 Lark card.action.trigger 通过 WorkflowResumeCommand 恢复 workflow。Nyx 不转发 card action（已确认：直接丢弃）。"Redesign to text / open_url" 原则上没问题，但这是已经 ship 的 template。RFC 应该在 Deliverable G 里点名它，并指定替代 UX（open_url 到 Aevatar 的审批页），不能停在抽象描述。

7. "Zero calls to open.feishu.cn" 其实已经是现状

grep 显示生产代码零引用（只有 tools/Aevatar.Tools.MockNyxId/MockStore.cs）。今天的 outbound 已经是 Nyx 代理（/api/v1/proxy/s/{slug} via LarkPlatformAdapter.cs:276-317）。真正的变更是Nyx 契约切换（proxy + 持久化 session token → channel-relay/reply + callback-scoped token），不是砍掉直连 Lark。把它写成"停止调 Lark"会让这个变更看起来比实际大得多、可怕得多。

8. Telegram 没提

PR #289 在同步迁移 Telegram。如果 Telegram 不也走 Nyx relay，"Nyx is sole credential authority" 对 Telegram 就是假的。要么把 RFC 收窄到"仅 Lark，Telegram 后续跟"，要么把 deliverables 扩展覆盖。

9. Deliverable H 的切换顺序有风险

Step 2（"把 Lark 开发者后台 URL 指向 Nyx"）是一次性大爆炸手动变更、没快速回滚——Nyx 变成唯一入口的 SPOF。建议开一个短的双入口窗口：legacy endpoint 在切换后再保留 N 天，只有在 Nyx 入口稳定后才返 410。现在的 "delete or 410" 把这个权衡藏起来了。

10. #295 不能干净关闭

RFC 说 #295（Nyx token refresh）不再是依赖。对 post-cutover 的 inbound-triggered 回复来说对。但：(a) 切换前 #294 当前计划仍在持久化 session token，#295 在切换完成前都还活着；(b) 未来任何 proactive-send issue 都会把 session-token 问题重开。建议写明："#295 可以关闭，当且仅当 #294 重新 scope 到 channel-relay/reply、且 proactive-send 保持 out of scope"。

结论

架构决策是对的，hard constraints 也是对的。现在这个 issue 可以打磨——但还不能开工。先把 reply-auth 矛盾（#1）和 #288/#294 的顺序（#5）定掉，并在 deliverables 里点名 social_media template（#6），再往下拆 sub-issues。

[eanzhao]

Rechecked against the latest Nyx code before changing the RFC body.

One point I do not think is blocked by current Nyx is reply auth.

• backend/src/crypto/jwt.rs now puts relay_api_key_id into the relay JWT generated for callbacks.
• backend/src/mw/auth.rs maps that relay claim back into AuthUser.api_key_id for relay-authenticated requests.
• backend/src/handlers/channel_relay.rs only checks that AuthUser.api_key_id matches conversation.agent_api_key_id.

So the callback-scoped Nyx relay JWT is already the intended auth surface for POST /api/v1/channel-relay/reply; I do not see a need to persist a second Aevatar-side Nyx API key just for inbound-triggered replies.

The one item that would still be a hard blocker without Nyx changes is the combination of:

• Aevatar persists zero secret-equivalent material
• Aevatar must verify X-NyxID-Signature HMAC

Current Nyx signs callbacks with API-key-hash-equivalent material, so Aevatar cannot verify that HMAC without storing secret-equivalent material locally. I updated the RFC to make JWT/JWKS validation the mandatory auth path, and kept X-NyxID-Signature as defense-in-depth / future-follow-up rather than a blocking requirement for this issue.

I also updated the issue body to absorb the other valid points:

• explicitly scope this RFC to Lark only; Telegram is follow-up
• explicitly state that [Channel RFC] Adopt Lark -> NyxID -> Aevatar relay webhook; make Nyx the sole credential authority #296 supersedes [Channel RFC] Lark outbound + streaming wire-through on LarkChannelAdapter (post-#261) #294 Deliverable A for Lark
• spell out JWKS/OIDC validation as real implementation work
• clarify that route_id is provisioning-time state if Aevatar stores it, not a callback-downlinked field
• explicitly name the shipped social_media / approval card-action flows as migration work, with open_url / deep-link replacement
• clarify that the real outbound delta is proxy + persisted session assumptions -> channel-relay/reply + callback relay JWT
• add a short rollback window before returning 410 on the legacy direct callback path
• tighten the wording around when [Channel RFC] Add Nyx access-token auto refresh for Lark outbound replies #295 becomes obsolete

With those changes, I do not see another "must change Nyx first" blocker for #296 itself. The remaining Nyx limitations are now explicit scope boundaries/manual steps in the RFC:

• Lark webhook URL still must be set manually in the Lark console
• Nyx still does not forward card.action.trigger

If you still want X-NyxID-Signature to be a mandatory verified check under the zero-secret constraint, that specific point needs a Nyx-side contract change first.

[eanzhao]

Verified against latest Nyx code — the pushback on #1 is correct and I was wrong.

backend/src/mw/auth.rs:395-416 maps claims.relay_api_key_id to AuthUser.api_key_id when claims.relay == true; backend/src/handlers/channel_relay.rs:213 only checks auth_user.api_key_id == conversation.agent_api_key_id. So the callback-scoped relay JWT is already a valid auth surface for POST /api/v1/channel-relay/reply, no separate Aevatar-side Nyx API key needed. The updated Callback Auth section describes this accurately.

Re-checked the other 9 points against the updated body — all absorbed:

#	Status
2 scope_id / route_id not downlinked	✅ scope_id dropped from hard constraints; route_id reframed as provisioning-time state only (Deliverable B)
3 HMAC role	✅ accepted in reverse: HMAC → defense-in-depth / non-blocking, JWT/JWKS becomes sole mandatory auth. Reasonable given current Nyx HMAC keying
4 JWKS is new code	✅ Deliverable F now enumerates issuer/audience, signature, TTL, JWKS cache/refresh, kid rotation, clock skew
5 vs #288/#294 ordering	✅ Header "Supersedes for Lark: #294 Deliverable A"; Deliverable A + Acceptance both call it out
6 social_media template	✅ named in Scope §In, Deliverable G, and Acceptance
7 "zero calls to open.feishu.cn" framing	✅ Why This Path now says "real delta is contract migration, not introduce Nyx for outbound from scratch"
8 Telegram silence	✅ title/Decision/Scope §Out all explicit "Lark only"
9 Cutover rollback	✅ Deliverable H reordered: build relay first, keep legacy during rollback window, 410 only after observation
10 #295 closure	✅ "obsolete only once #294 is re-scoped away from persisted-session-token outbound contract and proactive send stays out of scope"

All 10 resolved. One small follow-up worth noting: because HMAC is now downgraded to diagnostics, JWT-via-JWKS is the only cryptographic check on the callback edge. That raises the stakes on Deliverable F — kid rotation, JWKS cache TTL, and clock skew handling can't have bugs, because there's no second line of defense. Not a blocker; just a reminder that Deliverable F gets harder to implement "mostly right".

No other blockers from my side. This version looks ready to break down into sub-issues.

[eanzhao]

Implementation checklist split from #296, ordered by dependency / critical path:

Phase 0

• [Channel RFC] Add ADR for Lark -> NyxID -> Aevatar relay webhook and supersede #294 Deliverable A #298 Add ADR for Lark -> NyxID -> Aevatar and explicitly supersede [Channel RFC] Lark outbound + streaming wire-through on LarkChannelAdapter (post-#261) #294 Deliverable A for Lark

Phase 1: Foundation

• [Channel RFC] Add Nyx-backed Lark provisioning flow with zero local credential persistence #299 Add Nyx-backed Lark provisioning flow with zero local credential persistence
• [Channel RFC] Harden /api/webhooks/nyxid-relay with Nyx OIDC/JWKS validation and durable 202 ingress #300 Harden /api/webhooks/nyxid-relay with Nyx OIDC/JWKS validation and durable 202 ingress
• [Channel RFC] Switch Lark turn replies to Nyx channel-relay/reply using callback relay JWT #301 Switch Lark turn replies to Nyx channel-relay/reply using the callback relay JWT
• [Channel RFC] Remove credential-bearing fields from Lark channel registration proto, state, and readmodels #302 Remove credential-bearing fields from Lark channel registration proto, state, and readmodels

Phase 2: Behavior migration

• [Channel RFC] Migrate social_media and approval card-action flows off card.action.trigger #303 Migrate social_media and approval card-action flows off card.action.trigger

Phase 3: Cutover

• [Channel RFC] Cut over Lark webhook ingress to Nyx and retire direct callback path #304 Cut over Lark webhook ingress to Nyx and retire the legacy direct callback path after the rollback window

A few ordering notes:

• #300 is the highest-risk item now that JWT-via-JWKS is the only mandatory cryptographic check on the callback edge.
• #301 should land only against the relay JWT contract from #300, not against the older persisted-session-token assumptions from #294.
• #302 should be finished before final cutover so we do not drag dead credential fields into the Nyx-backed steady state.
• #303 must be done before #304, otherwise we would cut over to Nyx while still depending on card.action.trigger, which Nyx does not forward.

If we want, the next step can be to assign owners and mark which of #299/#300/#301/#302 can run in parallel after #298 lands.

[eanzhao]

Progress update based on the current head of #288 (7da26cb5).

If #288 merged now, #296 would not be "done" yet. It would put us in a pre-cutover state:

• #298 / Phase 0: effectively done
  • the ADR is already landed in docs/decisions/0011-lark-nyx-relay-webhook.md
• Phase 1 foundation: mostly done
  • #299 Nyx-backed Lark provisioning exists (NyxLarkProvisioningService)
  • #300 /api/webhooks/nyxid-relay + Nyx JWT/JWKS validation + durable 202 ingress exist
  • #301 Lark turn replies are already wired to Nyx channel-relay/reply
• #302 is not at steady-state acceptance yet
  • the current branch intentionally keeps legacy credential-bearing proto/state/readmodel fields in compatibility mode so existing persisted state does not misdeserialize
  • that means we are not yet at the final RFC end state of "credential-bearing fields removed from proto/state/readmodel"
• Phase 2 / #303: largely in place for the Nyx relay path, but not fully retired everywhere
  • relay-path workflow / approval interactions are now text-driven (/approve, /reject, /submit)
  • the relay prompt/guidance now explicitly avoids card.action.trigger
  • legacy direct-path card-action handling still exists during the rollback window
• Phase 3 / #304: not done
  • the cutover runbook and rollback-window scaffolding are in place
  • but the actual production cutover still requires switching the Lark Developer Console callback URL to Nyx and only later retiring the legacy direct callback path / returning 410

So the short version is:

merge now gets #296 to "foundation landed and relay path usable, with most relay-path behavior migration in place, but still pre-cutover."

If we want a phase label, I would call the current state:

between Phase 1 and Phase 2, or more bluntly: Phase 2 pre-cutover.

I would not close #296 on that merge. The remaining items to finish the RFC are mainly:

• #302 final steady-state schema/state/readmodel cleanup
• #304 the real production cutover and legacy direct-path retirement