Permissions

Modbot has a permissions system that determines who can run which commands. Permissions are managed by the Permissions module and can be reloaded by running the command !reload permissions. Permissions are configurable through the file at settings/permissions.yml.

Config example

Groups:
  'Group 1':        #This is the name of this group. This may be any string, and does not affect how the group is processed.
    admin: false    #Optional, defaults to false. Decides whether or not this group grants admin permissions.
    owner: false    #Optional, defaults to false. Decides whether or not this group grants owner permissions.
    members:        #The Discord IDs of the members that belong in this group. Users may be in multiple groups.
    - 110875794905014272   #User1
    - 167087172371873793   #User2
    - 133520886455074816   #User3
    permissions:    #Permissions to grant or remove from this group.
    - +!reload      #Grants permission to use the !reload command, an Admin command.
    - -Reminder     #Revokes permission to use any commands provided by the Reminder module (currently !remind and !reminders).

  'Admin group':
    admin: true
    members:
    - 110875794905014272   #User1

  'Owner group':
    owner: true
    members:
    - 167087172371873793   #User2
    permissions:
    - +Reminder     #Grants permission to use any commands provided by the Reminder module (currently !remind and !reminders).
    - -!reminders   #Revokes permission to use the !reminders command, a Generic command.

Interpretation

Determining admins and owners

Each group may contain optional fields to grant its members the title of "admin" or "owner". Members' titles are evaluated before any further permissions are added or removed.

If the admin/owner field in a group's configuration is false, not present, or not a Boolean value, the group does not grant the respective title. If the field is true, the group grants the title. Admin/owner titles cannot be revoked by other groups.

Applying permission modifiers

Once admins and owners are determined, permissions can be further manipulated.

By default:

• All users may run Generic commands.
• Admins may additionally run Admin commands.
• Owners may additionally run Owner commands. Owners will also be notified of unhandled exceptions encountered by ExtendedListeners and when the bot starts up or shuts down, if enabled. Owners that are not also Admins are not granted permission to run Admin commands.

From here, each group is evaluated in the order they appear in the file. If a member is in multiple groups, groups that appear later in the file may override changes made by previous groups. Similarly, within each group, permissions are added to/removed from its members in the order they appear. Permission modifiers later in the list may override changes made by previous ones.

Each permission modifier consists of a + or - character followed by the name of a command or CommandListener module. If the name is that of a module, all commands provided by the module are affected.

Following the example

1. Determining admins and owners
   • User1 is in the group titled "Admin group" which grants them the Admin title.
   • User2 is in the group titled "Owner group" which grants them the Owner title.
   • User3 is not part of any group that can grant them a title.
2. Applying permission modifiers
   • "Group 1" grants User2 and User3 !reload permissions. User1 is unaffected as they already have !reload permissions granted by their Admin title.
   • "Group 1" also revokes permissions for all Reminder commands from all 3 users.
   • "Admin group" does not contain any permission modifiers, so no changes are made.
   • "Owner group" regrants permissions for all Reminder commands to User2. However, it later revokes permissions for the !reminders command, which is one of Reminder's commands.

Therefore the final permissions are:

• User1 is an Admin, and may run all Generic and Admin commands, except for any commands provided by the Reminder module. They may not run any Owner commands.
• User2 is an Owner, and may run all Generic and Owner commands except for the !reminders command. They may also run one Admin command, !reload, but not any other Admin commands.
• User3 is neither an Admin nor an Owner, and may run all Generic commands, except for any commands provided by the Reminder module. They may also run one Admin command, !reload, but not any other Admin commands, nor any Owner commands.
• All other users may run all Generic commands, but not any Admin or Owner commands.