From 06261ee55bd36ef9c0dec88671370e05528f2ac7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maxime=20=E2=80=9Cpep=E2=80=9D=20Buquet?= Date: Wed, 3 May 2023 21:52:33 +0200 Subject: [PATCH] ProtoXEP: MUC Token Invite MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Maxime “pep” Buquet --- inbox/muc-token-invite.xml | 206 +++++++++++++++++++++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 inbox/muc-token-invite.xml diff --git a/inbox/muc-token-invite.xml b/inbox/muc-token-invite.xml new file mode 100644 index 00000000..12479cc1 --- /dev/null +++ b/inbox/muc-token-invite.xml @@ -0,0 +1,206 @@ + + + +%ents; +]> + + +
+ MUC Token Invite + This specification provides a way to generate tokens to invite users to a MUC room. + &LEGALNOTICE; + xxxx + ProtoXEP + Standards Track + Standards + Council + + XEP-0045 + XEP-0421 + + + + NOT_YET_ASSIGNED + + muc + token + invite + + &pep.; + + 0.0.1 + 2023-08-15 + pep +

First draft.

 + +
+ +

This specification provides a way to request invite tokens to a MUC room in order to invite users whose address is unknown to a member-only &xep0045; room.

+ + +
    +
  • Allow tokens to be generated, optionally with constraints.
    • +
  • Allow tokens to be revoked.
    • +
  • Don't prevent affiliated users of a room to join if they don't possess a token.
    • +
  • Don't require clients receiving tokens to have any specific implementation.
    • +
+ + + +

Supporting entities MUST advertise the &MTINS; &xep0030; feature.

+ + +

An entity may request a token from a &xep0045; service by sending an iq of type set containing a <request> element in the &MTINS; namespace.

+ + +]]> +

The MUC room MUST reply to the request with a <token> element in the &MTINS; namespace, containing the token as text node. The token MUST be an opaque string but does not need to be unique within a room.

+ + lyQZ1RzacYTlf3svGODYq1xVabNnMc2x +]]> +

Implementations MUST reply an error ot type auth/forbidden if the requesting entity isn't allowed to generate a token.

+ + + + +]]> + + +

It is possible to create tokens that may be used only a specific number of times to grant users affiliations, and/or may have an expiry time.

+

To constrain the token to a number of times after which it expires, the counter attribute (xs:unsignedInt) can be used in the <request> element.

+

To constrain the token to a time limit, the delay attribute (xs:unsignedInt) can be used in the <request> element.

+

if both attributes are combined, whichever constraint is reached first expires the token.

+ + +]]> +

The reply from the service MUST contain at least the requested delay and counter attributes. Requested values for these attributes MAY be altered by the server. This may be useful to implement a default server policy (maximum time, and/or counter). Values returned indicate current values that apply to the issued token.

+

Services may want to automatically limit issued tokens even with the request doesn't have any. In the following example, the MUC service enforces a maximum time limit of a week as a policy.

+ + lyQZ1RzacYTlf3svGODYq1xVabNnMc2x +]]> + + +

Integration with Mediated Invites or &xep0249; is not described in this document as invite tokens generated this way may not be used when the invitee's address is known.

+

Clients may include generated tokens in the password parameter of a URI as such:

+ xmpp:news@commons.example?join;password=TOKEN + + +

Receiving entities will follow the usual flow of joining password protected-rooms.

+

When a token is used by a participant who doesn't have any affiliation, a server MUST give them an affiliation level of member.

+

If an expired token is used by someone who isn't affiliated yet, the room MAY additionally include in the presence error an <expired-token/> element in the &MTINS; namespace, as a sibling of the <not-authorized/> element.

+ + +

It is possible for room participants to list tokens by sending an iq of type get containing a <tokens/> element in the &MTINS; namespace.

+

The room MUST reply with all tokens that the participant is allowed to revoke, each listed in <token> elements within a <tokens> wrapper element. Individual token elements MUST contain updated attibute values, that is, if a token has been issued with counter set to 5 and has been used twice (2), listing tokens at this point will show this specific token with a counter attribute value of 3.

+ + + + + + + lyQZ1RzacYTlf3svGODYq1xVabNnMc2x + HIFac1EUx3gDA1TEXlblwQ2izGIqAUab + +]]> + + +

It is possible to revoke a token early by sending an iq containing a <revoke> element in the &MTINS; namespace, with the token as the text node. The room MUST then reply successfully with an empty iq.

+

If the user is unauthorized to issue tokens, the room should reply with an iq error type auth/forbidden. If the user is unauthorized to revoke the specified token, or if the token doesn't exist, the room should reply with an iq error of type cancel/item-not-found.

+

+ + lyQZ1RzacYTlf3svGODYq1xVabNnMc2x +]]> + ]]> + + + + +]]> + + + +

Tokens may be added to bookmark storage by receiving entities and as such implementing MUC rooms SHOULD ignore tokens provided during join when a user is already affiliated with the room. In this case, if a counter was attached it SHOULD NOT be decremented.

+

Tokens with no constraint are not equivalent to passwords. A token is only required to be supplied once as opposed to passwords, which need to be specified at every join independently of user affiliation.

+

The Using a token section describes a way for clients to know they may have used an invalid token by adding an error specific to this document. It is likely that tokens aren't stored indefinitely but rather removed from storage not long after they expire, which makes it hard for MUC services to distinguish between a password for the room before configuration change, and an expired token. This specification assumes that it was an expired token as the room isn't password protected.

+

Possible extensions to this spec could include broadcasting information about the inviter in a new participant's join presence, as well as issuing tokens with specific affiliations and/or &xep0317;.

+ + +

None?

+ + +

None?

+ + +

Leaking tokens may lead to inviting unwelcomed people to a room. Token limits and revocations provide users a way to reduce harm in such a case. A service SHOULD also enforce a reasonable maximum value as a time or usage constraint (24h, a week, a year, etc.).

+

Issuing tokens may be locked down by service operators, or by room administrators via the muc#roomconfig_allowinvites &xep0045; configuration option.

+

It is RECOMMENDED that room moderators be able to list and revoke tokens generated by every other participant.

+ + +

None.

+ + +

None.

+ + + + + + + + The protocol documented by this schema is defined + in XEP-xxxx: https://xmpp.org/extensions/xep-xxxx.html. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]> + +