From 6e2b46d6667b29fae5dbbc2cc31675d40f01e080 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Fri, 3 Apr 2026 18:51:40 +0900 Subject: [PATCH] docs: clarify DM pairing vs group auth --- docs/channels/groups.md | 3 +++ docs/channels/pairing.md | 3 +++ docs/channels/telegram.md | 6 ++++++ 3 files changed, 12 insertions(+) diff --git a/docs/channels/groups.md b/docs/channels/groups.md index 12d1de831fb..fd0731f9399 100644 --- a/docs/channels/groups.md +++ b/docs/channels/groups.md @@ -320,6 +320,9 @@ Notes: When `channels.whatsapp.groups`, `channels.telegram.groups`, or `channels.imessage.groups` is configured, the keys act as a group allowlist. Use `"*"` to allow all groups while still setting default mention behavior. +Common confusion: DM pairing approval is not the same as group authorization. +For channels that support DM pairing, the pairing store unlocks DMs only. Group commands still require explicit group sender authorization from config allowlists such as `groupAllowFrom` or the documented config fallback for that channel. + Common intents (copy/paste): 1. Disable all group replies diff --git a/docs/channels/pairing.md b/docs/channels/pairing.md index aff1c3cb517..a40a6b96986 100644 --- a/docs/channels/pairing.md +++ b/docs/channels/pairing.md @@ -54,6 +54,9 @@ Account scoping behavior: Treat these as sensitive (they gate access to your assistant). +Important: this store is for DM access. Group authorization is separate. +Approving a DM pairing code does not automatically allow that sender to run group commands or control the bot in groups. For group access, configure the channel's explicit group allowlists (for example `groupAllowFrom`, `groups`, or per-group/per-topic overrides depending on the channel). + ## 2) Node device pairing (iOS/Android/macOS/headless nodes) Nodes connect to the Gateway as **devices** with `role: node`. The Gateway diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md index ef72860d038..04943a0fe46 100644 --- a/docs/channels/telegram.md +++ b/docs/channels/telegram.md @@ -121,6 +121,10 @@ Token resolution order is account-aware. In practice, config values win over env For one-owner bots, prefer `dmPolicy: "allowlist"` with explicit numeric `allowFrom` IDs to keep access policy durable in config (instead of depending on previous pairing approvals). + Common confusion: DM pairing approval does not mean "this sender is authorized everywhere". + Pairing grants DM access only. Group sender authorization still comes from explicit config allowlists. + If you want "I am authorized once and both DMs and group commands work", put your numeric Telegram user ID in `channels.telegram.allowFrom`. + ### Finding your Telegram user ID Safer (no third-party bot): @@ -159,6 +163,8 @@ curl "https://api.telegram.org/bot/getUpdates" Non-numeric entries are ignored for sender authorization. Security boundary (`2026.2.25+`): group sender auth does **not** inherit DM pairing-store approvals. Pairing stays DM-only. For groups, set `groupAllowFrom` or per-group/per-topic `allowFrom`. + If `groupAllowFrom` is unset, Telegram falls back to config `allowFrom`, not the pairing store. + Practical pattern for one-owner bots: set your user ID in `channels.telegram.allowFrom`, leave `groupAllowFrom` unset, and allow the target groups under `channels.telegram.groups`. Runtime note: if `channels.telegram` is completely missing, runtime defaults to fail-closed `groupPolicy="allowlist"` unless `channels.defaults.groupPolicy` is explicitly set. Example: allow any member in one specific group: