Kabukibot contains a simple mechanism to control access to certain functionality in channels, the Access Control List (ACL), which works like a whitelist.
The concept is simple: By default, nobody* is allowed to do anything. Only people that got explicit permissions can use the functionality tied to those permissions.
You can only grant permissions in one direction, which means you cannot say "I want to grant permission X to all moderators except my friend Tom, because he's a dick.". The only way to achieve this would be to grant the permission X to all moderators individually or to simply not make Tom a moderator (because, well, he's a dick).
Managing permissions is always only allowed by the channel owner and the bot operator. You cannot grant this to other people.
(*) Not quite. the channel owner and the bot operator are always allowed to do anything; this cannot be changed on a per-channel basis.
Let's take the Domain Ban plugin as an example. It defines
one single permission, called
configure_domain_bans. This permission controls all
commands provided by the plugin, e.g. !ban_domain and !unban_domain. To use
the command, a person has to be granted the permission. Otherwise, the command will
be silently ignored (to prevent spamming).
#tester_mantester_man: !ban_domain foo.com kabukibot: tester_man, links to foo.com will be *banned*.
#tester_mansome_guy: !ban_domain foo.com (command is ignored)
Let's say you want to allow
some_guy to configure domain bans, you'd use
#tester_mantester_man: !k_allow configure_domain_bans some_guy kabukibot: tester_man, granted permission "configure_domain_bans" to some_guy.
#tester_mansome_guy: !ban_domain bar.com kabukibot: some_guy, links to bar.com will be *banned*.
some_guy does not need to be in the channel at the moment when permissions are set for him.
Behind the scenes, Kabukibot will remember your permissions as a list of tuples. So after the
commands above, the list for the channel
#tester_man would look like this:
This is important when revoking permissions (see below).
Instead of working on a per-user basis, you can use predefined groups. Group names always begin
with a dollar sign (e.g.
$mods), to distinguish them from usernames (so
mods is the user named "mods", not the group).
There are 6 groups:
Working with groups works just the same as with usernames.
#tester_mantester_man: !k_allow configure_domain_bans $mods kabukibot: tester_man, granted permission "configure_domain_bans" to $mods.
#tester_mana_moderator: !ban_domain baz.com kabukibot: a_moderator, links to baz.com will be *banned*.
Note that you can create overlapping permissions, i.e. grant something to both moderators and single users (who can also be moderators). It does not matter if a user has been granted something because he is in a certain group or it has been granted to him individually.
In most cases, you should stick to using only groups to manage your permissions. Mixing users
and groups can be confusing (have fun explaining people in chat why
can use !ban_domain, but
You can check whom you granted a particular permission to by using the global !k_allowed command:
#tester_mantester_man: !k_allowed configure_domain_bans kabukibot: tester_man, "configure_domain_bans" is granted to: some_guy, $mods
You can revoke previously granted permissions at any time using the !k_deny command. Remember the list of grants for you channel?
Revoking means deleting elements from this list. That means you can revoke the permission
$mods, but you
cannot revoke it for
$subs. Otherwise, it would be possible to create ambiguous
#tester_mantester_man: !k_deny configure_domain_bans some_guy kabukibot: tester_man, revoked permission "configure_domain_bans" from some_guy.
#tester_mansome_guy: !ban_domain bar.com (command is ignored again)
If you try to revoke something that has not been granted, Kabukibot will tell you that no changes are needed to fulfill this (pointless) request:
#tester_mantester_man: !k_deny configure_domain_bans $subs kabukibot: tester_man, no changes needed.
This basically means "You did not grant $subs the permission configure_domain_bans earlier."
Why not per-plugin permissions?
It seems that this permission system is overly complex and one could simply grant people to use a plugin instead of an abstract permission thingy.
Think of a more complex plugin like the Custom Commands
plugin. Imagine it had only the possibility to be either completely allowed or completely
denied to a person/group in the channel.
The plugin provides a number of functions: adding new commands, altering existing ones, using the custom commands, removing them, ... – do you really want all the people who can use custom commands (e.g. do !busta) to also be able to delete them (do !cc_del busta)? Certainly not.
That's why each plugin has the freedom to declare as many permissions as it wants. The Custom Command plugin for example has one for adding commands, one for using them and one permission per custom command (so you can actually say "I want my mods to be able to use !busta, and everyone to be able to use !bigsmoke").