Invitations - YunoHost-Apps/galene_ynh GitHub Wiki

Basic usage

In order to generate a token, you must either be group operator or have specified

"allow-tokens": true

in the group description. In order to invite a single person, you type

/invite username

This will generate a link that you may send to said user and that will allow logging-in without the need to specify either a username or password. By default, tokens are valid for one week, but you may specify a different duration:

/invite username 15d

In order to make a wildcard invitation (one that you may send to multiple users), simply type:

/invite

This will generate a link that will lead to a simplified login dialog, where the password field has been removed. Again, you may specify a different duration:

/invite '' 15d

There's a menu entry on the context menu of your own username that allows generating a wildcard token valid a day. This should be expanded to pop up a friendly dialog, but I'm not likely to do that myself.

Token management

Unlike the stateless tokens previously implemented, the tokens used by the /invite command are stateful: we keep track of all the tokens that we have generated in a file on the server. If you have the "op" privilege, you may view the list of all (stateful) tokens generated for the group:

/listtokens

You may revoke a token:

/revoke https://galene.org:8443/group/public/?token=xxx

and you may extend its lifetime (even if it's been revoked):

/reinvite https://galene.org:8443/group/public/?token=xxx 2d

Token storage

Tokens are stored in the file data/var/tokens.jsonl. They are deleted one week after their expiration date. The expiration date is stored in absolute time, so your server better have accurate time if you want accurate expiration of tokens.

It should be safe to modify the file while Galene is running (the server will notice your modifications straight away), although of course you might suffer from the lost update problem if two entities modify the file at the same time.

There are some features that I've implemented that can currently only be accessed by editing the token file directly, such as tokens with unusual permissions (permission to record, permission to create new tokens) or tokens that are only valid after a certain date. I'll extend the protocol support if there's demand.