Ts3audiobot: Rights system rework

[Splamy]

Progress
Working Matcher:

• [x] ClientUid
• [x] ServerGroup
• [x] ChannelGroup
• [x] Visibility
• [x] Bot/Instance
• [x] Teamspeak 3 permissions
• [x] Api (Bool)
• [x] Api (Token)

Problems:

• The current rights system with Public/Private/Any/Admin is very limited and provides no configurability for the user.
• Many modules are bound to use certain userids and cant operate without. This limits the expandability of the code [open]
• The current system is limited to only one server

Solutions/Ideas:
The new system should fix those problems. The following constructs should help with this.

• We don't want to reinvent the wheel with a second rights system parallel to the one of teamspeak 3. Therefore rights are again bound to _ts3 user groups_ but can now also be sub-specified
• The rights config file will use toml as a standartized and widespread language which can be modified by other tools and already has stable libraries

Rights language syntax prototype v0.2 Example:

# Rules on level 0 layer affect all bot instances across all server.
# Keep in mind that those rights can still be overridden in any rule.

# the "+" is a list of all rights to be added
"+" = [ "cmd.help" ]
# the "-" is a list of all rights to be denied
"-" = "cmd.quit"

# You can declare groups with $name to structurize certain rights together
["$admin"]
    "+" = [ "cmd.play" ]
    "-" = [ "cmd.help", "cmd.pm" ]

# This is the first rule
# The keys have no fixed order, but we suggest you to keep it at least consistent
# Each rule can contain so called "includes", "matches" and "delcarations"
[[rule]]
    # This is a include, which means that this group will have all
    # "+" and "-" delcarations of the included groups
    include = "$admin"

    # These are the so called matches
    # This rule will be applied to a user if *any* of them matches, so for ex.
    # The bot/user talks on the server with the hostname "splamy.de"
    host = "splamy.de"
    # The user has the uid "gMVR34YE7I/r37+mgmYORV="
    useruid = [ "gMVR34YE7I/r37+mgmYORV=" ]
    # The user is within the group with id "30"
    groupid = 30
    # The user has the specified ts3 right or meets the expression requirement
    perm = [ "b_client_server_textmessage_send",
             "i_filebrowser_upload>=50" ]

    # These are the declarations (as seen at the start already)
    "+" = [ "cmd.play" ]
    "-" = [ "cmd.help", "cmd.pm" ]

[[rule]]
    host = [ "flakebi.de", "192.168.0.1" ]
    groupid = 30
    perm = [ "b_client_server_textmessage_send",
             "i_filebrowser_upload>=50" ]

    include = "$admin"
    "+" = [ "cmd.play" ]
    "-" = [ "cmd.help", "cmd.pm" ]

    # A nested group is only visible to rules on the same level and lower
    [rule."$all"]
        include = "$admin"
        "+" = "cmd.play"
        "-" = [ "cmd.help", "cmd.*" ]

    [[rule.rule]]
        groupid = [ 30, 31 ]
        include = [ "$admin", "$all" ]
        "+" = [ "cmd.play" ]
        "-" = [ "cmd.help", "cmd.pm" ]

    [[rule.rule]]
        groupid = 35
        include = "$admin"
        "+" = [ "cmd.play" ]
        "-" = [ "cmd.help", "cmd.pm" ]

# Whenever a right is specified more detailed (for ex. from [rule] =lvl1 to [rule.rule] =lvl3)
# the more detailed specification (lvl3) will override the previous one.

# Each rule consists of 2 levels:
# (n-1 = all rules build up from higher levels)
#  n   = all rules included with the 'include' directive
#  n+1 = all rules declared with '+' and '-'
# This conveniently allows to expand rules with groups while still giving the option
# to make the final changes in the rule itself

# When two rules with the same level are applied to a used they will be merged
# but "-" declarations will override "+" delcarations of the same level or lower

# A group name must be always uniqely idetifiable.
# This means when for ex. we have a group ["$a"], and [rule] declares a group [rule."$a"],
# those "$a"s are indistinguishable, therefore this is disallowed.
# On the other hand when one [rule] declares [rule."$a"], and another [rule] does the same,
# both "$a"s are only visible in that certain [rule] respectively, so this is valid.

# For convenience all keys can have either single values or array of values

[TheCrealm]

Wow, fine graded rights are real! But one question. In your example are only commands as rights. Is this right system especially for commands? In case of flexibility there should be something like permissions which grant rights for the commands. In case of later plugin support, there should be possibilities to easily use the right system in any context they want. Maybe you already considered this^ At all its a super configurable and a flexible system.. good approach 👍

[Splamy]

permissions which grant rights for the commands.

Could you elaborate on that?
Do you mean something like the ts3 permission grant option, for users to give other users permissions.
Or do you just want the rights system to also cover plugin-commands?

[TheCrealm]

There is no association with ts3 grant options or something like that..

Lets imagine we have one command, !foo
To execute this command we need the permission(right) to execute this command.
In case of our command we need the "commands.foo" permission.

This right can be evaluated by the command handler automagically.. But we also can do it manually and evaluate other things..

At all you can say that the "permission" is one more "right abstraction layer" which gives us the possibility to not only evaluate commands with this! (In your example we have commands, they should be this thingy permissions)

Lets explain what i mean.. Image we have a plugin which should move all non team member users into another channel. In this case we could simply check if the user has the permissions "users.team".. if not, move them!

The permission itself is just a plain string.. Could be "help" or "foo.bar" or "iLikeTrains".. I just wanna check if the user got the permission.

With this simple change you could support authentication checking which supports more than just commands! In case of commands you could just go just finer.. But primary it could be the more flexible way to handle cases which may get possible later.. Maybe you know about Sinusbot.. Started as a music bot they now have a scripting engine for everything related to the teamspeak.. There is no good approach to handle rights there.. Just for example :P

[JABirchall]

grant rights are very linear, wouldn't suit for dynamic permissions.

[Splamy]

Hmm, your example could also be solved by something like a 'tag'. You can tag and untag users and other tools can retrieve that tag.

The nice thing about our rights solution here is, that we dont have to remember anything. If the bot restarts, nothing is lost, ts3 gorups are still bound to the client.
A tag on the other hand must be saved seperately.

Something that could be easily implemented is that plugins can check if a user is has a certain group (for example +$all here)

Another point in planning is whether or not to allow editing rights at runtime with a special command or just offer a cmd to reload the file. Because offering exhaustive functions to edit the rights could get very complicated to keep it userfriendly.

[TheCrealm]

i do something wrong with explaining ..
Just forgot what i already wrote. Maybe i come on your teamspeak this weekend^

Have a nice day (sun is shining 👍)

[Splamy]

sure thing ^^
Edit: I think I just got what you were trying to explain. I'll give it a thought since this really seems interesting
Edit2: I adapted the syntax and the examples to match your idea

[JABirchall]

We could add a wrapper around the teamspeak permissions.
for example.

permission(b_client_server_textmessage_send) { 
// should allow all groups with client_textmessage_server = true to use announcement command
     +announcement
}

permission(i_filebrowser_upload, 50) {
// if permission i_filebrowser_upload >= 50 allow the user to tell the bot to download a music file
    +download
}

you following?

[Splamy]

Phew, I get the Idea, seems interesting. I will think about it 👍 .

(Btw, we will probably ditch the current rights syntax and move to toml with a similar syntax, sacrificing the prefect syntax for a more compatible and widespread language which can be modified by other tools and already has stable libraries)

[JABirchall]

Ya, or YAML

[Splamy]

I've seem yaml, and I'm not a fan of it, the syntax feels a bit more clumsy and the language feels bloated with unnecessay features (Also not a fan of syntax by indentation). From my few layout templates toml looks a lot nicer

[Splamy]

Ok a fresh prototype v0.2 is out, which imho looks way more clean and better structured.
The new permission specification request has also been added to see how well it fits.

[JABirchall]

Looks good, I want to improve the rights system on my bot. Im just using simple group IDs or UIDs.

https://github.com/JABirchall/NimdaTS3/blob/master/config/plugins/GlobalBan.json#L10-L13

edit:
Since toml supports tables, I think permissions would be better handled like so

[[rule]]
    host = [ "flakebi.de", "192.168.0.1" ]
    groupid = 30
        perm = {i_channel_textmessage_power = 50}

    include = "$admin"
    "+" = [ "cmd.play" ]
    "-" = [ "cmd.help", "cmd.pm" ]

    # A nested group is only visible to rules on the same level and lower
    [rule."$all"]
        include = "$admin"
        "+" = "cmd.play"
        "-" = [ "cmd.help", "cmd.*" ]

    [[rule.rule]]
        groupid = [ 30, 31 ]
        include = [ "$admin", "$all" ]
        "+" = [ "cmd.play" ]
        "-" = [ "cmd.help", "cmd.pm" ]                

    [[rule.rule]]
        groupid = 35
        include = "$admin"
        "+" = [ "cmd.play" ]
        "-" = [ "cmd.help", "cmd.pm" ]
    [[rule.rule]]
        perm = { b_client_server_textmessage_send = true }

        "+" = ["announce.global"]
        "-" = ["announce.staff"]
    [[rule.rule]]
        perm = {b_client_server_textmessage_send = true, i_client_talk_power = 90 }
        "+" = ["announce.*"]

It is less visually fatiguing to have perms in a inline table than having to parse the array value.
Could also improve on it by using array tables to support new lines '[{}]'
I'll look more into the spec when I get home from work and design a good model.

[Splamy]

While this looks nice here:
perm = {b_client_server_textmessage_send = true, i_client_talk_power = 90 }
You have less configurability saying
i_client_talk_power >= 90 or i_client_talk_power <= 90
and it also might get less readable when you have 4+ rights in one line (inline groups dont support linebreaks)
also it is less consistent with all key-value-pairs allowing single/array values...

[Splamy]

Ok a working rights version is live on the develop branch
You can see in my first post which matcher already work, the other matcher will be added as patches later
(ts3 permission matching is not trivial)

[TheCrealm]

yeah.. you implemented right that what i wanted to have ^.^
Sadly i am bad in explaining.. but like i thought you implemented it anyway.. thanks

[JABirchall]

Ahh, yeah that explains it a bit better, could be useful for revoking access to some commands if a specific perm is too low.

[LEpEX]

Die Channel Gruppen mit in das Permissions System übernehmen

[Splamy]

@LEpEX Filtering by ChannelGroupIds is now available on the latest dev branch, use
channelgroupid = [ 1, 2, 3 ] to filter with that. Documentaion will follow soon.

[Splamy]

First documentation is up on the wiki: https://github.com/Splamy/TS3AudioBot/wiki/Rights it will probably need a few reformats, but thats for later...

[Splamy]

Finally added permission matcher and host matcher.