Chat Access
Understand the admission model for Chat users entering an Agent
Chat Access
Chat Access is an admission capability of the Chat Plugin. It answers one question: may a direct or group message from an external Chat user enter a specific Agent?
It is not an Agent Core permission system or a general Role/Permission model. After admission, the Chat Plugin passes the message to the Agent without propagating roles or permissions into Sessions or other Plugins.
Core rules
- Default deny: without an explicit
allowgrant, the message does not enter the Agent. - Per-Agent isolation: approval for Agent A does not grant access to Agent B.
- Per-account isolation: identity uses
channel + issuer + subject_id, so the same user contacting two bots has two principals. - Explicit scopes: persisted grants are only
directandgroup;allin management commands expands to two grants. denydiffers fromrevoke: denial prevents new requests, while revocation lets the user request access again.
Approval flow
When an unapproved user sends a direct message, the Chat Plugin creates or reuses a pending request and returns a command like:
city plugin action chat access-approve assistant --input '{"request_id":"req_xxx"}' --token <token>Administrators can inspect requests first:
city plugin action chat access-snapshot assistant --input '{}' --token <token>Unapproved group messages are silent by default, but their pending requests appear in the same management list.
Storage
Each Agent stores its own data at:
<agent_project>/.downcity/chat/access.dbThe Chat Access database contains principals, requests, allow/deny grants, and audit events. It does not contain bot tokens, app secrets, or message bodies. Complete Chat Resource Items are encrypted separately in the City-global ~/.downcity/downcity.db; the Chat Plugin Binding stores only resource_ids.
Difference from City Auth
An Agent Token protects the HTTP control plane. Each token belongs to one Agent and has full access to that Agent API; it contains no User, Role, or Permission. Chat Access decides whether an external Telegram, Feishu, or QQ user may send messages to a specific Agent. Their data, identities, and decision paths are separate.