✅ Command permission system

PBModular includes a flexible permission system to control which users can execute specific commands or trigger certain handlers. This involves both developer-defined defaults and user (bot owner) overrides.

Roles and User Identifiers

Permissions can be granted based on:

1. Roles: Predefined categories of users.
   • owner: The bot owner, defined by config.owner (can be username or user ID). The owner implicitly has access to all commands, regardless of restrictions.
   • chat_owner: The creator/owner of the chat where the command is used (only applies in groups/channels).
   • chat_admins: Administrators of the chat where the command is used (only applies in groups/channels).
   • all: Any user (effectively means no restriction based on role). Useful mainly for bot owner overrides, as a default.
   • Custom Roles: The bot owner can potentially define and assign custom roles to users via a core module or database management, which could then be used in permission settings. (Check core module features for details).
2. Specific Users:
   • @username: Allows a specific user identified by their username.
   • User ID: Potentially allow by specific user ID (check implementation details in __check_role).

Setting Default Permissions (@allowed_for)

As a module developer, you can set default permissions required to use a handler using the @allowed_for decorator from base.module. This decorator should be placed before the handler decorator (@command, @callback_query, @message).

• It accepts a single role/user identifier as a string, or a list of allowed roles/identifiers.
• If a user meets any of the conditions (matches a role in the list, is the bot owner, etc.), they are allowed access.
• If @allowed_for is not used on a handler, it defaults to being accessible by all users (unless overridden by the bot owner for specific commands).

Examples:

# Inside your BaseModule or ModuleExtension class
from base.module import command, callback_query, allowed_for
from pyrogram import filters

# Command only for chat administrators and the bot owner
@allowed_for("chat_admins")
@command("kick", filters=filters.group)
async def kick_cmd(self, client: Client, message: Message):
    """Kicks a user from the group."""
    # ... implementation ...

# Command accessible by chat admins OR a specific user @someHelperBot
@allowed_for(["chat_admins", "@someHelperBot"])
@command("warn", filters.group)
async def warn_cmd(self, client: Client, message: Message):
    """Warns a user."""
    # ... implementation ...

# Callback query only for the bot owner(s)
@allowed_for("owner")
@callback_query(filters.regex("^admin_action:"))
async def admin_callback(self, client: Client, cb: CallbackQuery):
    """Handles sensitive admin actions via callbacks."""
    # ... implementation ...

# Command with no specific restriction (accessible by 'all' by default)
@command("ping")
async def ping_cmd(self, _, message: Message):
    """Simple ping command."""
    # ... implementation ...

Bot Owner Overrides

The bot owner typically has commands (provided by a core module) to manage permissions:

• /allow_cmd <command> <role_or_user>: Grants permission for a specific command to a role or user.
• /disallow_cmd <command> <role_or_user>: Revokes permission.
• These overrides are usually stored in the bot's main database (db.CommandPermission table) and take precedence over the defaults set by @allowed_for for commands.

TIP

• Currently, bot owner overrides via /allow_cmd typically only apply to handlers registered with @command. Permissions set via @allowed_for on @callback_query or @message handlers generally cannot be overridden through bot commands and remain fixed by the developer's setting.

• The bot owner always bypasses permission checks

Use @allowed_for judiciously to secure sensitive commands while keeping common features accessible. Rely on the docstrings and help pages to inform users about command availability.