Permissions

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.

Example

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 !k_allow:

#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:

• (configure_domain_bans, some_guy)
• (configure_domain_bans, $mods)

This is important when revoking permissions (see below).

Groups

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:

• $mods (moderators)
• $subs (subscribers)
• $turbos (Turbo users)
• $admins (Twitch admins)
• $staff (Twitch staff)
• $all (anyone)

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 some_guy can use !ban_domain, but random_dude cannot).

Check permissions

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

Revoking permissions

You can revoke previously granted permissions at any time using the !k_deny command. Remember the list of grants for you channel?

• (configure_domain_bans, some_guy)
• (configure_domain_bans, $mods)

Revoking means deleting elements from this list. That means you can revoke the permission configure_domain_bans from some_guy and/or $mods, but you cannot revoke it for $subs. Otherwise, it would be possible to create ambiguous rules.

#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").