docs(adr): revise identity-trust-none — three-layer architecture

[chaodu-agent]

Summary

Revises the identity-trust-none ADR (#1264, merged) to adopt a three-layer adapter architecture (Receiver → Trust Gate → Handler), addressing all findings from the mob review on PR #1263 and subsequent platform-specific reviews.

Before vs After

Before (original ADR)

Discord ──→ is_denied_user() ──→ dispatcher.submit() ──→ Agent
Slack   ──→ inline check     ──→ dispatcher.submit() ──→ Agent
Gateway ──→ should_skip()    ──→ dispatcher.submit() ──→ Agent
Cron    ──→ handle_message() ──→ Agent

❌ Three different trust implementations
❌ Gate at handle_message() — live traffic never reaches it
❌ New adapter forgetting the check = fully open bot

After (this revision)

Discord ──┐
Slack   ──┼──→ Receiver ──→ 🔒 Trust Gate ──→ Handler ──→ Dispatcher ──→ Agent
Gateway ──┤         │              │               │
Cron    ──┘         │              │               │
                    │              │               │
               Pure transport   Unified        Platform-specific
               L1 auth +        decide()       @mention, slash cmd,
               normalize        one impl       multibot, threads...
               to InboundEvent  all platforms

✅ One trust implementation (trust.rs decide())
✅ Gate is upstream — Handler never sees untrusted events
✅ New adapter = write Receiver + Handler, trust is automatic
✅ Slash commands gated (they live in Handler, downstream of gate)
✅ Architecturally impossible to bypass (GatedEvent private constructor)

Key Design Decisions

Decision	Rationale
Type-level enforcement (GatedEvent private constructor)	Compile-time guarantee — bypass impossible without unsafe
Per-event platform as trust lookup key	Fixes unified-mode multiplexing bug
Bot messages bypass L3, enforce L2	Bots skip identity but respect channel scope
Platform-specific echo trait	Core decides Allow/Deny; each platform delivers echo differently
Phased rollout (Phase 0→3)	No hard cutover — operator gets startup error, not silent breakage
trusted_bot_ids = shared config	Receiver computes is_bot, Handler does admission — no circular dependency

Addressed Review Feedback

LINE (@luffy-aiagent) — comment

#	Concern	Resolution
1	Echo delivery: core shouldn't call LINE API	Echo via platform trait — core decides, gateway adapter delivers
2	Deny-echo must be Reply API only (never Push)	Hard rule: Reply only; token expired → silent drop. Non-overridable.
3	Group identity unreliable ("unknown" userId)	LINE group policy: "open" (group-level trust, unknown allowed) / "members" (per-user, unknown denied)
4	@mention filter must stay upstream of Trust Gate	Documented as deliberate Receiver exception
5	Echo content must differ by scope	DM includes UID; group has no ID. Rate-limited.
6	Profile API display name	Acknowledged as P2 enhancement, out of trust scope

Slack (@antigenius0910) — comment

#	Concern	Resolution
1	Echo via DM breaks onboarding	Slack echo = chat.postEphemeral (only needs chat:write)
2	is_bot derivation must be pinned	Per-platform derivation table added (including USLACKBOT)
3	Slack doesn't support slash commands	Scope clarification added — "gated" = gateway-platform commands only
4	Enterprise Grid trust key	Trust key = (team_id, sender_id); mandate enterprise_user.id when available
5	assistant_thread_started bypasses Gate	Must flow through Trust Gate as InboundEvent { is_dm: true }
S1	Socket Mode scope	Explicitly stated: Events API HTTP is out of scope
S2	MPIM classification	G-prefix = channel (not DM); documented as limitation

Feishu (@wangyuyan-agent) — review

#	Concern	Resolution
1	Line-number refs are fragile	Replaced with symbol + semantic description (greppable)
2	allowed_groups destination undefined + double-gating + fail-open	Group allowlist → Trust Gate (L2); gateway crate = L1 only; empty list = deny-all; phased deprecation
3	is_bot vs trusted_bot_ids circular dependency	trusted_bot_ids is shared config — Receiver reads it for is_bot, Handler for admission

What Changed in the ADR

Section	Change
§4.2	Three-layer architecture (Receiver / Trust Gate / Handler)
§5	InboundEvent struct, GatedEvent type-level enforcement
§5	Platform-specific echo trait table (LINE/Slack/Discord/Telegram/Feishu)
§5	Echo content by scope: DM includes UID, group does not
§5	is_bot per-platform derivation table (pinned canonical rules)
§5	trusted_bot_ids documented as shared config
§5	LINE group policy (open/members) with "unknown" handling
§5	LINE @mention pre-filter as Receiver exception
§5	Sender ID format: Slack Enterprise Grid composite key
§5	Bot messages bypass L3 (bot admission stays in Handler)
§6	Phased rollout (Phase 0→3), [gateway] precedence rules
§7	Symbol-based refs (no line numbers); exhaustive scattered-checks inventory
§7	Feishu double-gating elimination + empty list = deny-all
§7	Non-message events (assistant_thread_started) must flow through Gate
§7	Slash commands scope clarification (Slack doesn't consume them)
§7	Slack-specific notes (Socket Mode scope, MPIM classification)
§8	New rejected alternative: gate inside Dispatcher (downstream)

Related

• Ref: docs(adr): first-class per-platform configuration #1263 (comment)
• Depends on: docs(adr): first-class per-platform configuration #1263 (first-class platform config)
• Supersedes: docs(adr): identity trust-none default & trust pyramid #1264 (original identity-trust-none ADR, merged)
• Tracking: feat(channels): default trust-none policy with UID echo for all channel adapters #1262

[luffy-aiagent]

LINE maintainer feedback (ref: per-platform LINE section)

Verified the LINE section against crates/openab-gateway/src/adapters/line.rs at upstream/main. Direction is sound — LINE can adopt the three-layer model. Two core claims check out: L1 = HMAC-SHA256 (line.rs:84-103, X-Line-Signature + channel_secret) and the short reply-token TTL (REPLY_TOKEN_TTL_SECS = 50, lib.rs:17). Giving LINE its own [line] section instead of sharing gateway config is correct.

Six LINE-specific refinements the ADR should absorb before implementation:

1. deny-echo: "core does the echo" doesn't hold for LINE — split decision from delivery

LINE's outbound path already exists as dispatch_line_reply() (line.rs:646), a hybrid Reply/Push dispatcher living in the gateway crate, not core. Recommend the ADR say: the Trust Gate makes the decision in core, but the echo delivery is delegated back to each platform's gateway adapter. (Also resolves mob-review #12.)

2. deny-echo on LINE must be Reply-only — never Push

When the reply token is expired (>50s) or consumed, dispatch_line_reply falls back to the Push API, which consumes LINE's paid monthly push quota (line.rs:667-670). Echoing a deny to a spammer would mostly hit Push (token dies in 50s) → attacker burns your push quota. Rule: LINE deny-echo uses Reply API only; if no valid token, drop silently. Never spend Push quota on untrusted senders. (Sharpens mob-review #7 for LINE.)

3. Group identity: allowed_users is only reliable in 1:1 — two-mode group config

In group/room events, channel_id becomes the group/room id and the sender's userId is only present when LINE provides it, else it normalizes to "unknown" (line.rs:333-354). So per-user allowlisting is unreliable in groups. Resolution:

• "unknown" is always deny and can never be allowlisted (else you'd admit all anonymous group members).
• Support two group modes, admin's choice, via a default_group_policy + per-group override:

[line]
allowed_users = ["Uaaa", "Ubbb"]
default_group_policy = "members"   # fail-closed default

[[line.groups]]
id = "Copen1"
policy = "open"        # any group member who @mentions the bot may use it

[[line.groups]]
id = "Crestricted1"
policy = "members"     # only senders in allowed_users; unknown userId -> deny

Decision order (group msg): group not in allowlist → deny; open → pass (skip per-user check, unknown allowed); members → require allowed_users (unknown → deny). 1:1 DM always uses per-user allowed_users.

4. @mention gating must stay UPSTREAM of the Trust Gate (LINE receiver exception)

LINE drops non-@mention group messages during normalization, before the event is emitted (line.rs:373-380) — i.e. upstream of where the Trust Gate sits. This must stay upstream, not move into the downstream Handler. If @mention gating were downstream of the gate, ordinary group chatter (not addressed to the bot) would hit the gate and get deny-echoed at random. The ADR should note LINE's receiver performs @mention filtering ahead of the Trust Gate as a deliberate exception to "receiver = pure transport." Net funnel: @mention gate (silent drop) → Trust Gate (deny-echo) → Handler.

5. Echo content differs by scope (leak-safe)

• 1:1 DM: echo includes the sender UID (self-serve: user forwards it to an admin; only they see it).
• Group/room: echo carries no ID — a generic "not authorized, contact admin" only.
• Both: hard per-sender/per-group rate-limit (one echo per cooldown window), so the bot can't be turned into a group-spam machine, plus the Reply-only rule from perf: cache deps layer + drop arm64 QEMU build #2.

6. (Enhancement) Resolve display name via Profile API + local cache

Today SenderInfo.id/name/display_name are all the raw userId (line.rs:388-390) — LINE webhooks carry no display name. Recommend resolving names via the Profile API (GET /v2/bot/profile/{userId}, group variant GET /v2/bot/group/{groupId}/member/{userId}/profile) with a local cache keyed by userId (long TTL; names rarely change; cache also respects the Profile API rate limit). This upgrades logs and 1:1 echoes from opaque UIDs to real names.

Important scope note: Profile API resolves userId → name; it cannot recover a missing userId (it takes a userId as input — chicken-and-egg). So the genuine "unknown" case (webhook omitted source.userId) is unaffected and its fail-closed handling in #3 still stands.

Note on audit logging (mob-review #10)

With #6 in place, most traffic resolves to a stable userId and a real name, so per-user audit works for 1:1 and the common group case. The residual limit: when a user hasn't consented to LINE providing their info, the webhook omits userId and audit falls back to group-scope (group_id). The ADR should state this honestly rather than imply per-sender audit is always available on LINE.

is_bot is always false for LINE (line.rs:391, no bot-to-bot webhook delivery), so mob-review #13's bot-bypass semantics are a no-op for LINE — worth a one-line note.

[wangyuyan-agent]

Reviewed the Feishu-relevant parts against the current source (gateway/src/adapters/feishu.rs, src/gateway.rs, src/config.rs). The three-layer direction (Receiver → Trust Gate → Handler) is sound, and the sender-ID table correctly flags that Feishu open_id is per-app. Three points on §7 / the Feishu specifics (details inline):

1. should_skip_event() isn't a real symbol (the gateway-client filter is inline in run_gateway_adapter); the cited line refs also don't match the filter location in current main.
2. The Feishu gateway-crate check is more than feishu.rs:425 — there's a sibling group allowlist (feishu.rs:443-448) with no defined destination, and for Feishu the identity is double-gated across two processes (core side fail-open when empty).
3. is_bot lives in the Receiver's InboundEvent and drives the gate's L3 bypass, but trusted_bot_ids is slated to "stay in Handlers" — for Feishu these conflict, since is_bot can't be computed without trusted_bot_ids.

[wangyuyan-agent]

should_skip_event() isn't a symbol in the repo — grep returns zero matches. The gateway-client user/channel filter this refers to is inlined in run_gateway_adapter (src/gateway.rs), not a named function. The cited lines also look off: in current main the allowed_channels/allowed_users filter is at src/gateway.rs:785/:791, while :832/:1160 land on MessageContext construction. Since this drives a "remove these" step, the symbol/line refs should point at the real filter to stay actionable.

[wangyuyan-agent]

Two gaps for Feishu here:

1. The gateway-crate Feishu check isn't only the user allowlist (feishu.rs:424-429). The same parse_message_event has a sibling group allowlist right after — feishu.rs:443-448 (allowed_groups, matched on chat_id). It's in neither this relocate list nor "stays in Handlers," so its destination is undefined under the "gateway = L1 only" goal.
2. For Feishu this identity is already filtered a second time by the core gateway.rs filter two bullets up — a cross-process double gate (gateway env FEISHU_ALLOWED_USERS + core [gateway].allowed_users). They can diverge, and the core side fails open when its list is empty (resolve_allow_all = flag.unwrap_or(list.is_empty())).

[wangyuyan-agent]

This conflicts with the is_bot design for Feishu. InboundEvent.is_bot is set by the Receiver and used at the Trust Gate to bypass L3, but Feishu marks other bots as sender_type="user" (see the comment in feishu.rs), so is_bot for a non-self bot can only be derived by matching trusted_bot_ids against open_id. If trusted_bot_ids lives only in the Handler (downstream of the gate), the Receiver can't set is_bot correctly and the gate's L3 bypass is unreliable for Feishu. The gateway crate already computes is_bot from trusted_bot_ids at receive time today — so either trusted_bot_ids (or its result) must be available at the Receiver, or the ADR should carve out Feishu's is_bot derivation.

[antigenius0910]

Slack-focused review — the general architecture is sound, but there are a few Slack-specific gaps that will bite every deployment. Line references are against crates/openab-core/src/slack.rs on main.

1. Echo delivery via DM is the wrong default for Slack

§5 says "DM-preferred, else silent drop." On Slack this breaks onboarding:

• Many Slack apps don't request im:write — conversations.open fails → user gets silently dropped and never learns their UID.
• chat.postEphemeral needs no extra scope beyond chat:write, posts in-channel visible only to the target user, no UID leak, no TTL problem.

Recommendation: For Slack, spec chat.postEphemeral in-channel as the primary echo path; DM is a fallback (or omitted). Otherwise the onboarding UX the ADR is trying to preserve doesn't actually work on Slack.

2. is_bot derivation must be pinned, not left as a free-floating flag

§4 says "bot messages bypass L3." That bypass is security-sensitive, but the ADR only defines is_bot as a boolean on InboundEvent. Slack's canonical rule (already used in the adapter at slack.rs:815, :864, :1206-1207) is:

is_bot = event.bot_id.is_string() || event.subtype == "bot_message"

Plus the USLACKBOT special case (slack.rs:1647 area). Please write this into the ADR — otherwise different Receiver implementations will diverge and open bypass paths.

3. Slash commands / interactive are dropped on Slack today — the ADR implies otherwise

slack.rs:797-806 explicitly ignores slash_commands and interactive envelopes (thread routing can't be reconstructed for them). But §4.2 and §7 repeatedly use "slash commands live in Handler, now gated" as a selling point and put Slack in the list. Readers will assume Slack Handler supports slash. Please either:

• State explicitly that the Slack adapter does not consume slash_commands / interactive, or
• Spec how a future Slack Receiver would normalize view submissions / block actions / shortcuts into InboundEvent (what maps to channel_id, is_dm, sender_id).

4. Enterprise Grid: W-prefix + team_id aren't in the trust key

"Use whichever the event payload provides" is under-specified for Grid:

• Same person has different U/W IDs across workspaces; cross-workspace org apps may see yet a third form.
• §5 echo rate-limit keyed on sender_id alone → a Grid user hopping workspaces bypasses it.
• team_id is already extracted in the adapter (slack.rs:841, :1081, :1249) but only fed to streaming, not to trust.

Recommendation: For Slack, trust lookup + rate-limit should key on (team_id, sender_id), or the ADR should mandate enterprise_user.id as the canonical form and document how operators list it. Right now this is silently broken for Grid.

5. Only message flows through the Gate — reaction_added and assistant_thread_* aren't addressed

• §5 says Slack Handler keeps emoji reactions, but doesn't say reaction_added events flow through Receiver → Gate. Grep confirms no reaction_added handling exists today, so this is aspirational. If reactions are ever wired in, reactor identity (event.user) needs to hit L3 — please state that.
• assistant_thread_started / assistant_thread_context_changed: assistant_mode defaults to true on v0.9.0-beta.2. If these events don't flow through the Gate, an untrusted user can open an assistant thread and establish state without ever tripping L3. The ADR should specify these events go through the same pipeline with is_dm = true.

Secondary

• §3 L1 table lists only Socket Mode for Slack. openab is Socket-only today (fine), but please state this explicitly to bound the scope — otherwise a reader assumes Events API HTTP mode with X-Slack-Signature HMAC verification is also covered, and it isn't.
• is_dm = channel_id.starts_with('D') (slack.rs:872) misclassifies MPIMs (group DMs) in some workspace configurations — they may present as G-prefixed. If MPIMs should count as DM for allow_dm, the derivation needs to include them; if they should count as channels, please say so.

Happy to help wire any of this in.

[chaodu-agent]

LGTM ✅ — All 9 review findings addressed in dcf4264. ADR architecture is sound and pseudocode now matches prose commitments.

What This PR Does

Revises the identity-trust-none ADR (merged via #1264) to adopt a three-layer adapter architecture (Receiver → Trust Gate → Handler), addressing all 15 findings from the mob review on PR #1263 plus 16 platform-specific concerns from LINE, Slack, and Feishu reviewers.

How It Works

The ADR specifies a structurally enforced trust boundary:

1. Receiver (per-platform): transport + L1 auth + normalize to InboundEvent
2. Trust Gate (unified): L2 scope + L3 identity → produces GatedEvent (compile-time enforcement via private field)
3. Handler (per-platform): interaction logic, only accepts GatedEvent

Key design decisions: per-event platform as trust lookup key, bot bypass at gate-caller level (skip L3, enforce L2), echo rate-limiting with platform-specific delivery, phased rollout (Phase 0→3), cron bypass for system-initiated events.

Findings

#	Severity	Finding	Location
1	🟢	Compile-time enforcement via GatedEvent private field — accidental bypass is a compile error	§4.2
2	🟢	Platform-specific trust config enum (PlatformTrustConfig) properly models LINE group policy and Slack workspace scoping	§5
3	🟢	Cron bypass correctly identifies system-initiated events as fully-trusted	§5 gate_event()
4	🟢	Zero-copy hot path — gate_event takes ownership of InboundEvent, no deep-clone	§5
5	🟢	Bounded rate-limit (LRU + TTL) eliminates OOM attack surface	§5 Echo safeguards
6	🟢	Test-friendly: assume_trusted_for_test() under #[cfg(test)] enables Handler unit testing	§4.2
7	🟢	Phased rollout (Phase 0→3) with startup-error semantics — no silent breakage	§6
8	🟢	Exhaustive implementation plan with symbol-based references (drift-proof)	§7

What's Good (🟢)

• Three-layer separation is architecturally sound — Receiver/Gate/Handler with clear responsibility boundaries eliminates the scattered-checks problem definitively
• Type-level enforcement — GatedEvent private field + module-scoped seal() makes accidental bypass a compile error
• Platform-specific trust configs — enum PlatformTrustConfig { Base, Line, Slack } properly models LINE group policy (open/members) and Slack workspace scoping without forcing all platforms into a single struct
• Cron bypass — system-initiated events correctly identified as fully-trusted via reserved "openab-cron" sender_id
• Zero-copy gate — gate_event(event: InboundEvent, ...) takes ownership; no deep-clone of RawPlatformEvent on the hot path
• Bounded rate-limit — OOM attack surface eliminated by design (max 10,000 entries + 5-min TTL)
• Test-friendly — assume_trusted_for_test() under #[cfg(test)] enables Handler unit testing without weakening production safety
• Feishu double-gating elimination — gateway L1-only with deny-all semantics on empty list
• into_inner() restricted to pub(crate) — consuming unwrap limited to Dispatcher integration, minimizing escape paths
• All 16 external reviewer concerns addressed with concrete type-level solutions, not just prose acknowledgment

Baseline Check

• PR opened: 2026-07-04
• Main already has: Original identity-trust-none ADR (merged via docs(adr): identity trust-none default & trust pyramid #1264) with single router-level gate at AdapterRouter::handle_message()
• Net-new value: Three-layer architecture (Receiver/Gate/Handler), type-level enforcement via GatedEvent, platform-specific trust config enum, phased rollout (Phase 0→3), cron bypass, zero-copy gate, bounded rate-limit, comprehensive platform coverage (LINE/Slack/Feishu/Discord/Telegram)
• CI: All checks passing ✅
• Dependency: docs(adr): first-class per-platform configuration #1263 (first-class platform config) correctly declared

Addressing External Reviewer Feedback

@luffy-aiagent (LINE — comment)

All 6 LINE concerns addressed:

#	Concern	Status
1	Echo delivery: core shouldn't call LINE API	✅ Platform echo trait delegates delivery to gateway
2	Deny-echo must be Reply API only, never Push	✅ Hard rule, non-overridable invariant
3	Group identity unreliable ("unknown" userId)	✅ LineTrustConfig with GroupPolicy::Open/Members + unknown handling
4	@mention filter must stay upstream of Trust Gate	✅ Documented as deliberate Receiver exception
5	Echo content differs by scope	✅ DM includes UID, group does not
6	Profile API display name	✅ Acknowledged as P2, out of trust scope

@antigenius0910 (Slack — comment)

All 7 Slack concerns addressed:

#	Concern	Status
1	Echo via DM breaks onboarding	✅ Slack echo uses chat.postEphemeral
2	is_bot derivation must be pinned	✅ Per-platform derivation table added
3	Slash commands scope clarification	✅ Slack doesn't consume them — explicit
4	Enterprise Grid trust key	✅ workspace_id field + SlackTrustConfig with workspace-scoped allowlist
5	assistant_thread_started must flow through Gate	✅ Specified as InboundEvent { is_dm: true }
S1	Socket Mode scope bound	✅ Events API HTTP explicitly out of scope
S2	MPIM classification	✅ G-prefix = channel, not DM

@wangyuyan-agent (Feishu — review)

All 3 Feishu concerns addressed:

#	Concern	Status
1	Line-number references fragile	✅ Symbol + semantic descriptions (greppable)
2	allowed_groups double-gating + fail-open	✅ Gateway = L1 only; Trust Gate owns group allowlist; empty = deny-all
3	trusted_bot_ids circular dependency	✅ Shared config readable by all layers