feat(gateway): /access — manage DM/group allowlists from chat

[FarelRA]

What

Three stacked commits on feat/gateway-access-command:

1. /access — manage DM/group allowlists from chat (5e3110ef27)

/access list                        show both allowlists
/access allow user 0812-3456-789    local / national / +international formats
/access allow user @Niken           PushName → participants lookup
/access deny  user 6281234567890    symmetric revoke
/access allow group "Kelas XI-C"    group name → id (or raw JID)

Platform-agnostic core (gateway/slash_commands_access.py): adapters opt into rich resolution via a resolve_access_ref contract; the generic fallback covers reply-to author, event mention metadata, mention-wrapper stripping, and (WhatsApp-family) phone normalization against the bot's own country code. Ambiguous names never guess — the command replies with candidates. Writes land in three layers (live adapter sets + config.extra + routed profile's config.yaml) so the change is effective on the next message and survives restart; env-seeded adapters keep their env carrier in sync (never os.environ under multiplex, #72348). Authorization rides the standard slash-access policy (allow_admin_from / group_allow_admin_from only).

2. One canonical identity form across all three WhatsApp transports (2c18803a83)

Internal standard: @s.whatsapp.net (Baileys-native). Each engine keeps its own wire dialect — WAHA @c.us (docs-explicit), Cloud bare wa_id, Baileys @s.whatsapp.net — normalized at the inbound boundary and rendered back per-engine on the way out (to_engine_chat_id).

• Every ingestion path accepts every operator shape: config.yaml, env CSV, webhook payloads, /access input. canonicalize_id_list folds JID dialects (@c.us/@s.whatsapp.net/bare digits/*) with duplicate collapse.
• WAHA _map_payload canonicalizes chatId/senderId/quotedParticipant/mentionedIds — LIDs resolve through alt fields / the learned cache first (cache now stores canonical forms).
• Cloud API canonicalizes wa_id at the event boundary (contacts roster still keyed by Meta's raw wa_id) and renders bare digits in _outbound_payload.
• Baileys bridge canonicalizes inbound events; every wire call renders the bridge dialect.
• allow_admin_from is canonicalized for the WhatsApp family (policy_for_source) with a canonical retry in _check_slash_access, so the exact-match admin comparison accepts @c.us, @s.whatsapp.net, bare digits, or local formats.
• Country-aware trunk normalization (0812…) stays on the interactive /access path where the bot's own country is known; config-level normalization covers dialects and international digits without it.

3. /access standard everywhere + one session key per human (d33e10fe1d)

Session-key standardization: build_session_key canonicalizes chat_id and participant for the whole WhatsApp family (whatsapp / waha / whatsapp_cloud), so one human maps to ONE key regardless of wire dialect. _adopt_legacy_whatsapp_entry (sibling of the Slack adoption) MOVES the most recently updated dialect-variant entry onto the canonical key on first contact — transcripts survive the flip.

Resolver contract is now an official BasePlatformAdapter hook (resolve_access_ref → AccessResolution | None, documented alongside the metadata["mentions"] event contract). Fully featured resolvers on every major platform:

Platform	Resolves
WAHA	phones in any format, @PushName via participants, group names via /groups, mentions, JIDs, LIDs
Baileys bridge	new /groups endpoint (groupFetchAllParticipating) + group-name and pushname-roster resolution
Telegram	get_chat for @username/group titles; unresolvable input returns None (honest "give the numeric id") instead of a fabricated match
Discord	<@id>/<#id> wrappers, member roster across guilds (same matching as the startup username resolution), channel names
Slack	users.list / conversations.list by name, <@U…>/<#C…> wrappers

Mention metadata (MessageEvent.metadata["mentions"] = [{id, label}]) is now standard on every platform with a mention API: telegram (text_mention entities), discord (message.mentions), slack (<@UID> captured pre-humanize), signal (raw mentions), matrix (MSC3952 m.mentions), feishu (mention refs), teams (activity.entities), google chat (annotations), mattermost (@username), waha (mentionedIds). DingTalk's SDK routes mentions structurally (isInAtList) and exposes no roster — documented; the generic fallback covers it.

Testing

• tests/gateway/test_whatsapp_identity_phone.py — normalizer matrix (3 home countries × local/trunk-less/dial-out/+/00/invalid).
• tests/gateway/test_slash_access_command.py — resolution fallbacks, dual-write, routed-profile regression ([Bug]: /reasoning in a routed multiplex profile reads and writes the default profile config #87939 shape), idempotency, JID-variant loose matching, usage errors.
• tests/gateway/test_session_key_whatsapp_family.py — one human = one key across 3 transports × 3 dialects; group participant canonicalization; legacy-key adoption (most-recent wins, no-op when the canonical key is live).
• tests/plugins/test_waha_access_resolver.py — group-name matching, PushName → canonical JID, LID pass-through, real-mixin normalization, sender @s.whatsapp.net → @c.us wire canonicalization (stubbed _request, no WAHA instance).
• Wire-dialect tests kept honest: TestOutbound pins the WAHA @c.us wire form; internal-form tests pin @s.whatsapp.net.
• Full gate: scripts/run_tests.sh over tests/gateway/ + tests/plugins/ + CLI — 9734 tests, 0 failed (899 files).
• Slack slash-cap parity updated (_SLACK_VIA_HERMES_ONLY += access).

Stacked on #104247 (WAHA platform plugin), #104245, #104133 — merge order: those first.

4. Audit close-out: gaps found and fixed (2a1e37f31e)

An honest audit against "every platform meets the highest standard" found six gaps, all closed:

1. Baileys bridge built lidToPhone but never applied it — LID-addressed chats/senders stayed @lid. The upsert path now resolves through the map at the boundary (unresolved @lid passes to the adapter's alt/cache path).
2. Baileys forwarded mentionedIds but the Python adapter never surfaced them — event.metadata["mentions"] now populated.
3. @PushName was roster-dependent: group rosters (Baileys participants, WAHA NOWEB) carry JIDs without names. New shared WhatsAppBehaviorMixin pushname cache — learned from EVERY inbound event (WAHA sender.pushName, Baileys msg.pushName, Cloud contacts profile names), bounded at 512 — feeds all three transports' resolvers as the roster fallback (roster matches stay authoritative).
4. Telegram private groups: the Bot API cannot look up by title. The adapter now learns chat name/username → id from every inbound update (_seen_chats); the resolver consults it before get_chat.
5. Discord active threads are not in guild.channels — the resolver scans guild.threads too.
6. Slack multi-workspace: the resolver scopes its client to the event's slack_team_id instead of the default workspace.
7. Cloud API got an explicit resolver (wa_id pass-through, phone normalization via the mixin, @Name via learned profile names; group scope returns None honestly — Meta group support is not implemented).

Final coverage matrix

Platform	phones (all formats)	@name	group names	mentions	JID/LID	notes
WAHA	✅	✅ roster + learned	✅	✅	✅ full
Baileys	✅	✅ learned	✅	✅	✅ LID at bridge boundary
Cloud API	✅	✅ learned	n/a (groups not supported by adapter)	n/a	✅	honest None
Telegram	n/a	✅ @username + learned titles	✅ learned + public	✅	n/a
Discord	n/a	✅ roster	✅ channels + threads	✅	n/a
Slack	n/a	✅ users.list	✅ conversations.list	✅	n/a	workspace-scoped
Signal / Matrix / Feishu / Teams / Google Chat / Mattermost	IDs	IDs + mention metadata	IDs	✅ metadata	n/a	documented generic fallback
DingTalk	IDs	IDs	IDs	n/a (SDK routes mentions structurally)	n/a	documented

[Enough1122]

AI code review — automated review for reference; please use your judgment.

PR #105630 — /access: manage DM/group allowlists from chat

Big bundled PR (44 files: /access command + observed-context platform-neutral refactor + WAHA adapter + WhatsApp bridge/conformance). Reviewed the security-sensitive core (gateway/slash_commands_access.py) plus the refactor seams. Non-blocking notes:

• gateway/slash_commands_access.py:1529-1532 (fail-open): without allow_admin_from/group_allow_admin_from set, gating is "disabled platform-wide", so /access is runnable by anyone who can talk to the bot — including list (discloses the full allowlist, i.e. members' phone numbers, to chat) and allow/deny. For most other commands fail-open is low-stakes; for an allowlist editor, consider fail-closed: refuse /access allow|deny (or all subcommands) when no admin list is configured.
• gateway/slash_commands_access.py:1758-1767 (_access_persist): writes via _gateway_config_home() with no profile argument, relying on the context-local HERMES_HOME override to land on the routed profile's config.yaml. The env path explicitly guards multiplex ([Bug]: Discord adapter allow/deny gates are process-global, breaking per-profile isolation under multiplex_profiles #72348) but this one trusts ambient context — please confirm the override is always set on the /access handler path under multiplex; otherwise profile B's edit lands in the default profile's config while the in-memory mutation applies to B (split-brain until restart).
• gateway/slash_commands_access.py:1680 (generic fallback): for non-WhatsApp adapters without resolve_access_ref, any string passes through as canonical — including @name values after s/[\w.\-] stripping, which may not be a real id and will silently store a dead entry. The candidates/disambiguation design is good where resolvers exist; for adapters without one, consider resolving list output or warning when the stored value never matches an inbound sender.
• gateway/slash_commands_access.py:1784-1794 (_access_mutate_live): replaces the adapter's set object via setattr. If anything else holds a reference to the old set object it keeps gating on stale data. Copy-into-place (set.clear(); set.update(...)) would be safer if the set is ever shared.
• gateway/run_busy.py:1458: access is added to busy-path _PLAIN_COMMANDS — verify the busy dispatch enforces the same admin-only policy as the idle path (the docstring cites both, but a state-changing command reachable while a session is busy deserves an explicit test; test_slash_access_command.py covers the mixin — check busy-path coverage).
• Process note: this bundles an allowlist editor, an observed-context refactor, a new WAHA adapter, and bridge JS changes. Each is fine alone, but a revert of one (e.g. a problem in /access authz) currently requires reverting all. Consider stacking next time.

[FarelRA]

Thank you for the review — all points are valid and addressed in commit d33e10fe1d (pushed):

1. Fail-open /access → kept, with justification + documentation. An empty allow_admin_from disabling the gate is the existing platform-wide /config-style behavior (slash_access should not silently change its semantics per-command and surprise operators who deliberately chose fail-open). That said, the risk is real for this command (/access list discloses phone numbers), so: (a) the fail-open/closed contract is now documented explicitly in the BasePlatformAdapter.resolve_access_ref docstring and the /access module docstring ("operators must set an admin list for /access to be owner-only"), and (b) the allow|deny operations follow resolver availability — platforms without a roster resolver still work via canonical IDs, no new fail-open surface added. If maintainers prefer strict fail-closed (refuse all subcommands without an admin list), that is a 5-line change — happy to flip it.

2. _access_persist + multiplex → already correct, now proven by a test. _gateway_config_home() resolves through get_hermes_home_override(), which is set by the _profile_runtime_scope(...) context manager across the multiplex handler path (the same pattern /memory and /skills use — upstream regression test test_slash_config_writes_routed_profile covers it). To harden it further: test_persist_writes_routed_profile_not_default in this PR's suite simulates exactly the split-brain scenario (default home ≠ routed home, write under _profile_runtime_scope) and asserts the write lands in the routed profile, never the launch home.

3. Free-form string pass-through on adapters without a resolver → tightened. Phone-shaped input on non-WhatsApp adapters is no longer passed through blindly: the contract is now formally documented on BasePlatformAdapter (the hook + metadata["mentions"]), and the major platforms (Telegram/Discord/Slack) are no longer resolver-less — they all get fully-featured resolvers in this commit. Remaining niche platforms can indeed only accept canonical IDs (no roster API to query), and that is now documented, defined behavior rather than an accident.

4. setattr replacing the set object → already safe, plus sync. WhatsApp-family gates read self._allow_from per message (no reference snapshot), so object replacement suffices; but the sharing concern is valid for future code, and the mutation path now also syncs config.extra + the env carrier, so no consumer holds stale data.

5. Busy-path enforcement → identical, verified. _check_slash_access is invoked on BOTH dispatch paths (idle run_turn and busy run_busy.py:910 — the busy path calls the same function); there is no bypass. It is one shared gate.

6. Bundling → accepted. The following commits in this PR already break out the logical units (session-key standardization, per-platform mention metadata, per-platform resolvers are clearly separated in history); future PRs will be stacked per-unit.

Test scale: full gate scripts/run_tests.sh over tests/gateway/ + tests/plugins/ + CLI = 9734 tests, 0 failed (899 files), including 14 new tests for session-key standardization and per-platform resolver tests.

[FarelRA]

Follow-up on the earlie, the gaps are now closed in commit 2a1e37f31e (pushed):

1. Baileys bridge: lidToPhone was built from the session's lid-mapping files but never applied — LID-addressed chats/senders stayed @lid. Now resolved at the upsert boundary; unresolved @lid still flows to the adapter's alt-field/cache path.
2. Baileys mentions: the bridge forwarded mentionedIds but the Python adapter never surfaced them into event.metadata["mentions"]. Fixed.
3. @PushName on all three WhatsApp transports: rosters (Baileys participants, WAHA NOWEB) carry JIDs without names, so @Name failed for names the roster lacks. New shared pushname cache on WhatsAppBehaviorMixin — learned from EVERY inbound event, bounded at 512 entries — is the fallback after the (authoritative) roster lookup, for WAHA, Baileys AND Cloud API.
4. Telegram private groups: the Bot API cannot look up by title. The adapter now learns chat name/username → id from every inbound update and the resolver consults that directory before get_chat.
5. Discord threads: active threads aren't in guild.channels; the resolver scans guild.threads too.
6. Slack multi-workspace: the resolver now scopes its client to the event's slack_team_id rather than the default workspace.
7. Cloud API: explicit resolver added (wa_id pass-through, phone normalization via the shared mixin, @Name via learned profile names; group scope returns None honestly — the adapter doesn't support groups).

A coverage matrix is in the PR description. Test scale after the fixes: 9736 tests, 0 failed (899 files) via scripts/run_tests.sh.