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. Chat channel credentials belong to the selected plaintext profile in ~/.downcity/plugins/chat/config.toml; CLI and Desktop redact fields marked writeOnly when displaying configuration.
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.