docs: Document Telegram gateway security pipeline & fix YAML allowlist fields#492
Conversation
…t fields (fixes #486) This commit addresses the documentation gaps identified after PR #1791, which fixed the security vulnerability where Telegram gateway polling bypassed access controls. Changes: - Add Channel Security subsection to bot-gateway.mdx with YAML reference table, security pipeline diagram, and configuration examples - Add Channel Security section to channels-gateway.mdx showing standalone/gateway parity - Add Gateway Mode note to bot-unknown-user-pairing.mdx with gateway YAML example - Fix critical bug: replace 'allowlist:' with 'allowed_users:' throughout bot-security.mdx - Add cross-link from messaging-bots.mdx to gateway security documentation - Include Mermaid diagrams following AGENTS.md color standards - Add warnings about empty allowed_users and field name requirements 🤖 Generated with [Claude Code](https://claude.ai/code) Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>
Qodo reviews are paused for this user.Troubleshooting steps vary by plan Learn more → On a Teams plan? Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center? |
|
Warning Review limit reached
More reviews will be available in 55 minutes and 15 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (5)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation to align with security pipeline changes introduced in PR #1791, detailing the transition from allowlist to allowed_users and explaining how gateway-mode bots now enforce the same security controls as standalone bots. However, the reviewer identified several critical mismatches between these documentation updates and the underlying codebase. Specifically, the Pydantic schema (ChannelConfigSchema) still expects allowlist as a list and lacks definitions for allowed_channels and allowed_users as a list, which will cause validation errors. Additionally, the gateway server implementation fails to extract or pass unknown_user_policy and owner_user_id from the configuration, silently breaking the pairing workflow. Minor documentation issues were also noted, including missing keys in the Channel Security reference table and inconsistent link prefixes.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| <Warning> | ||
| **Field name is `allowed_users`, not `allowlist`.** The gateway YAML parser only recognizes `allowed_users:` and `allowed_channels:`. Examples using `allowlist:` will silently produce a bot with **no enforcement**. (Fixed in [PR #1791](https://github.com/MervinPraison/PraisonAI/pull/1791).) | ||
| </Warning> |
There was a problem hiding this comment.
There is a critical mismatch between this documentation change and the Pydantic configuration schema in praisonai/bots/_config_schema.py.
In _config_schema.py, ChannelConfigSchema defines:
allowlist: List[str] = Field(default_factory=list)allowed_users: Optional[str] = None
If a user configures bot.yaml (for standalone bot mode) using allowed_users as a list (as shown in the updated examples on lines 151, 172, 194, 214, etc.), praisonai bot start --config bot.yaml will fail Pydantic validation with a ValidationError (since a list cannot be coerced into Optional[str]).
To resolve this, the codebase's ChannelConfigSchema in praisonai/bots/_config_schema.py should be updated to support allowed_users as a list or string, or the documentation should clarify that allowlist is still required for standalone bot.yaml while allowed_users is used for gateway.yaml.
| <Info> | ||
| **Gateway mode (`praisonai gateway start`)**: As of PR #1791, the gateway polling path runs the same pairing pipeline as the standalone bot. If `pairing.enabled: true` is set in your gateway config, unknown users get the same Approve/Deny inline-button flow. No code changes needed — configure `unknown_user_policy: "pair"` and `owner_user_id` in your `channels:` YAML entry. | ||
| </Info> |
There was a problem hiding this comment.
There is a critical implementation gap between this documentation and the gateway server codebase (praisonai/gateway/server.py).
Currently, praisonai/gateway/server.py does not extract or pass unknown_user_policy or owner_user_id from the channel's YAML configuration (ch_cfg) when instantiating BotConfig on line 1651:
config_kwargs = dict(
token=token,
allowed_users=list(_raw_allowed),
allowed_channels=list(_raw_channels),
mention_required=mention_required,
auto_approve_tools=auto_approve_tools,
)Because of this, any unknown_user_policy or owner_user_id configured in gateway.yaml will be completely ignored, defaulting to "deny" and None respectively, which silently breaks the pairing workflow in gateway mode.
Additionally, there is no pairing or pairing.enabled field defined in GatewayConfig or ChannelConfigSchema.
To fix this, the gateway server's start_channels method in praisonai/gateway/server.py needs to be updated to extract and pass these fields to BotConfig:
config_kwargs = dict(
token=token,
allowed_users=list(_raw_allowed),
allowed_channels=list(_raw_channels),
mention_required=mention_required,
auto_approve_tools=auto_approve_tools,
unknown_user_policy=ch_cfg.get("unknown_user_policy", "deny"),
owner_user_id=ch_cfg.get("owner_user_id"),
)| | YAML Key | Type | Default | Purpose | | ||
| |----------|------|---------|---------| | ||
| | `token` | `str` | required* | Bot auth token. *Optional for `whatsapp` web mode and `email`/`agentmail`. | | ||
| | `platform` | `str` | channel name | Override channel platform (e.g. `telegram`). | | ||
| | `routing` / `routes` | `dict` | `{"default": "default"}` | Route map: `dm`, `group`, `default` → agent id. | | ||
| | `allowed_users` | `list[str]` \| `str` | `[]` | User-ID allowlist. Comma-separated string also accepted (env-expansion friendly). | | ||
| | `allowed_channels` | `list[str]` \| `str` | `[]` | Channel/group-ID allowlist. Same string handling. | | ||
| | `group_policy` | `str` | `"mention_only"` | One of `"mention_only"`, `"command_only"`, `"respond_all"`. Sets `mention_required` automatically. | | ||
| | `auto_approve_tools` | `bool` \| `str` | `True` | Auto-approve safe tools. Strings `"1"/"true"/"yes"/"on"` are truthy. | | ||
| | `default_tools` | `list[str]` | (BotConfig default) | Per-channel override for default safe tools. | |
There was a problem hiding this comment.
The YAML reference table for Channel Security is missing unknown_user_policy and owner_user_id keys, which are documented as configurable in channels: entries in bot-unknown-user-pairing.mdx. Adding them to this reference table will improve completeness and consistency.
| | Feature | Standalone Bot | Gateway Mode | | ||
| |---------|----------------|--------------| | ||
| | User allowlist (`allowed_users`) | ✅ | ✅ | | ||
| | Channel allowlist (`allowed_channels`) | ✅ | ✅ | | ||
| | Unknown user pairing | ✅ | ✅ | | ||
| | Group policy enforcement | ✅ | ✅ | |
There was a problem hiding this comment.
The table states that allowed_channels is supported for Standalone Bots. However, ChannelConfigSchema in praisonai/bots/_config_schema.py (which validates bot.yaml for standalone bots) does not define allowed_channels. Consequently, configuring allowed_channels in bot.yaml will cause a validation error on startup.
Please update praisonai/bots/_config_schema.py to include allowed_channels to ensure parity between standalone bot.yaml and gateway configurations.
| When running via the gateway, set `group_policy` per channel in `gateway.yaml`. See [Bot Gateway → Channel Security](/docs/features/bot-gateway#channel-security). | ||
| </Note> |
There was a problem hiding this comment.
The link /docs/features/bot-gateway#channel-security uses the /docs prefix, whereas other links in this file (e.g., /features/cross-platform-mirror on line 11, /features/bot-commands on line 935) do not use the /docs prefix. Please ensure consistency across documentation links to prevent broken links depending on the documentation site's routing configuration.
1 participant
Fixes #486
This PR addresses the documentation gaps identified after PraisonAI PR #1791, which fixed a security vulnerability where the Telegram gateway polling path bypassed all access-control enforcement.
Changes Made
📚 New Documentation Sections
🐛 Critical Bug Fixes
🔗 Cross-References
🎨 Visual Improvements
Impact
Generated with Claude Code