Permissions

The user-facing permission system in the current version is chat user authorization.

Project downcity.json no longer exposes a separate permissions block.

Runtime execution boundaries follow the built-in behavior of the current release, while chat authorization controls who can talk to the agent and what they can do.

Chat user authorization

This layer decides who is allowed to talk to the agent and what they are allowed to do.

The current model is a pure permission-group model:

each user belongs to one permission group
each permission group owns a set of permissions
every incoming message is judged only by the speaking user

There is no special master or owner identity in this model. Everything is handled through permission groups.

Core rules

New users fall into the default permission group.
Whether a direct message is allowed depends on that user's DM permission.
Group or channel messages are also judged only by the speaking user's permissions.
A group itself is not a permission subject.
The user platform is distinguished, so Telegram, Feishu, and QQ users are tracked separately.

Where it is stored

Chat user authorization is not written back to project downcity.json.

It is stored in the city-global ~/.downcity/downcity.db, which keeps permission management centralized and avoids exposing user authorization in plaintext project config. A role assigned to the same telegram:12345678, feishu:ou_xxx, or qq:123456 principal applies across agents connected to that platform.

The backing storage is structured tables, not a key-value JSON blob:

chat_auth_roles: roles
chat_auth_role_permissions: permissions owned by each role
chat_auth_channel_defaults: default role per platform
chat_auth_user_roles: platform user to role bindings

Where to manage it

Use the interactive city chat menu and choose "configure channel → configure authorization", or use the CLI directly:

city chat auth set telegram:12345678

The CLI then lets you choose the target permission group interactively. Common management tasks include:

view permission groups
edit which permissions belong to each group
choose the default group
assign users to groups

When a chat user is denied, the denial message includes a command like city chat auth set telegram:12345678 that they can forward to an admin.

A common group layout

default: lowest privilege, for new users
member: normal DM and group usage
admin: member permissions plus management permissions

Most setups do not need approval flows or pairing. In practice, placing users into the right group is enough.

How a message is judged

When a chat message enters the system, the flow is:

Identify which platform it came from and who sent it.
Look up the user's assigned permission group.
If no explicit assignment exists, use the default group for that platform.
Determine which permission is required for this message type, such as DM or group usage.
Only then is the message allowed to continue into the agent.

So even when a message comes from a group chat, the final decision is still based on the speaking user.

Permissions

Table of Contents