Multi-User Chat Administration

%ents; ]>

Multi-User Chat Administration This specification defines how to administer Multi-User Chat rooms and services using Ad-Hoc Commands. &LEGALNOTICE; xxxx ProtoXEP Standards Track Standards Council XMPP Core XEP-0045 XEP-0050 NOT_YET_ASSIGNED &stpeter; 0.0.1 2012-09-25 psa

First draft.

&xep0045; defines a widely-implemented XMPP extension for chatrooms. The MUC specification covers a number of common administrative use cases, such as kicking and banning users, granting voice, and changing user affiliations (moderator, admin, etc.). However, the protocols for these use cases are "hardcoded" and not as flexible or extensible as we might like. A more flexible approach would be to use &xep0050; (which did not exist when MUC was originally being developed) so that any implementation or deployment of a MUC service could define its own commands, as was done for core XMPP servers in &xep0133;. This specification defines such a framework for MUC services, including in-room administration as well as administration of the MUC service as a whole (e.g., banning users across all rooms).

This document addresses the following requirements:

Enable users with appropriate privileges to perform common administrative tasks with respect to Multi-User Chat rooms and services.
Re-use Ad-Hoc Commands for maximum flexibility.

A MUC service MUST advertise any administrative commands it supports via &xep0030; (as described in XEP-0050: Ad-Hoc Commands); such commands exist as well-defined discovery nodes associated with the service in question.

All supported Ad-Hoc Command nodes MUST be included in the &xep0115; hash generated by a MUC service.

The &xep0004; FORM_TYPE for MUC administration is "urn:xmpp:muc-admin". Fields defined in this specification are of the form "urn:xmpp:muc-admin:*". Particular implementations and deployments MAY define their own commands as fields to be included in data forms scoped by the "urn:xmpp:muc-admin" FORM_TYPE; in accordance with &xep0068;, the names of such fields SHOULD use &clark; (e.g., "{http://www.example.com/muc-admin}foo").

This document defines a profile of XEP-0050: Ad-Hoc Commands that enables a MUC administrator to complete the use cases listed below. (Any overlap with existing administrative use cases currently defined in XEP-0045 is noted below.)

Modify Room Subject
Set Occupant Role
Set User Affiliation
Assign Occupant Nickname
Clear Room History
Report a Spammer

Some of these scenarios can apply to a single room or to multiple rooms. If the request is sent to a room JID (e.g., coven@chat.shakespeare.lit), then the interaction applies to that room only and the data form generated by the service might include a hidden field specifying the room. If the request is sent to the service's JID (e.g., chat.shakespeare.lit), the data form generated by the service might include a boolean flag specifying whether the interaction applies to all rooms on the service. The examples below illustrate these settings.

This use case provides the same functionality as the protocol described in Section 8.1 of XEP-0045. The following command sequence mirrors the examples in Section 8.1 of XEP-0045.

]]>

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form. Notice that, since the request was sent to a particular room, the interaction applies to that room only (in this case, the data form includes an optional hidden field specifying the room).

sessionid='5981DC80-AF4E-445E-9FF6-0F4067FDCD05' status='executing'> Modifying a Room Subject Fill out this form to modify the room subject. urn:xmpp:muc-admin coven ]]> urn:xmpp:muc-admin Fire Burn and Cauldron Bubble! coven@chat.shakespeare.lit ]]> ]]>

Notification of completion MAY include the processed data in a data form of type "result", although strictly speaking this is unnecessary since the subject change will be sent in the room.

This use case provides the same functionality as the protocol described in Sections 8.2, 8.3, and 8.4 of XEP-0045. However, the 'role' field is more easily extensible so that implementations can include their own values (e.g., a new role of "scribe"). The following command sequence mirrors the examples in Section 8.2 of XEP-0045.

]]>

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

sessionid='F4CC8121-DA42-4FDD-8668-17900310D8BE' status='executing'> Modifying an Occupant Role Fill out this form to modify the role for a room occupant. urn:xmpp:muc-admin ]]> urn:xmpp:muc-admin pistol none Avaunt, you cullion! ]]> ]]>

This use case provides the same functionality as the protocol described in Sections 9.1, 9.3, 9.4, 9.6, 9.7, 10.3, 10.4, 10.6, and 10.7 of XEP-0045. However, the 'affiliation' field is more easily extensible so that implementations can include their own values (e.g., a new affiliation of "creator"). The following command sequence mirrors the examples in Section 10.3 of XEP-0045.

]]>

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

sessionid='3C5229C9-CD08-46F0-80BF-3BAB604363A2' status='executing'> Modifying a User Affiliation Fill out this form to modify the affiliation for a user. urn:xmpp:muc-admin ]]> urn:xmpp:muc-admin hecate@shakespeare.lit owner A worthy witch indeed! ]]> ]]>

This use case enables a moderator or administrator to assign a new nickname to an occupant. This functionality can be helpful in situations where an occupant specifies or receives a temporary or inscrutable nickname on joining the room (e.g., "Call-In-User-7"), but the administrator wants to assign a more user-friendly nickname (e.g., "Peter Saint-Andre").

]]>

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

sessionid='53E9C396-64DD-4652-97CF-42E21E857A2D' status='executing'> Assigning an Occupant Nickname Fill out this form to assign a nickname to a participant. urn:xmpp:muc-admin ]]> urn:xmpp:muc-admin thirdwitch hag66 ]]> ]]>

This use case enables a moderator or administrator to clear the history that new occupants receive when they join the room.

]]>

Unless an error occurs (see the Error Handling section below), the service SHOULD simply clear the history.

]]>

This use case enables a moderator or administrator to report a particular user as a spammer. Typically such a report will trigger further events such as those described in &xep0268;.

]]>

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

sessionid='E244DA21-E081-430C-B030-6886FDBCF0CD' status='executing'> Spam Report Fill out this form to report a room occupant as a spammer. urn:xmpp:muc-admin ]]> urn:xmpp:muc-admin pistol ]]> ]]>

Several error conditions are possible when an entity sends a command request to the service, as defined in the following table. If one of these error conditions occurs, the service MUST return an error stanza to the requesting entity.

Condition	Cause
&conflict;	The command cannot be completed because of a data or system conflict (e.g., a user already exists with that username).
&feature;	The specific command is not supported (even though the ad-hoc commands protocol is).
&forbidden;	The requesting entity does not have sufficient privileges to perform the command.
¬allowed;	No entity is allowed to perform the command (e.g., retrieve the CEO's roster).
&unavailable;	The ad-hoc commands protocol is not supported.

For the syntax of these errors, see &xep0086;. Naturally, other errors may be returned as well (e.g., &internalserver; if the service cannot be shut down).

The ability to complete the administrative tasks specified herein MUST NOT be granted to users who lack service-level administrative privileges.

This document requires no interaction with &IANA;.

The XMPP Registrar shall add "urn:xmpp:muc-admin" to its registry of protocol namespaces.

XEP-0068 defines a process for standardizing the fields used within Data Forms scoped by a particular namespace. The reserved fields for the 'urn:xmpp:muc-admin' namespace are specified below.


  urn:xmpp:muc-admin
  XEP-xxxx
  Forms used for administration of MUC rooms and services.
  
  
  
  
  

    ]]>

Because the protocol defined here is a profile of XEP-0050: Ad-Hoc Commands, no schema definition is needed.