XEP-xxxx: Managing message moderators in MUC rooms

This XEP defines a way for the moderator to communicate with the room for moderating MUC messages.


WARNING: This document has not yet been accepted for consideration or approved in any official manner by the XMPP Standards Foundation, and this document must not be referred to as an XMPP Extension Protocol (XEP). If this document is accepted as a XEP by the XMPP Council, it will be published at <http://www.xmpp.org/extensions/> and announced on the <standards@xmpp.org> mailing list.


Document Information

Series: XEP
Number: xxxx
Publisher: XMPP Standards Foundation
Status: ProtoXEP
Type: Standards Track
Version: 0.0.1
Last Updated: 2007-05-22
Approving Body: XMPP Council
Dependencies: XMPP Core, XMPP IM, XEP-0045
Supersedes: None
Superseded By: None
Short Name: Not yet assigned

Author Information

Mridul Muralidharan

Email: mridul@sun.com
JabberID: mm132998@sun.com

Rahul Shah

Email: rahul.shah@sun.com
JabberID: rs129080@sun.com

Legal Notice

This XMPP Extension Protocol is copyright 1999 - 2007 by the XMPP Standards Foundation (XSF) and is in full conformance with the XSF's Intellectual Property Rights Policy (<http://www.xmpp.org/extensions/ipr-policy.shtml>). This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).

Discussion Venue

The preferred venue for discussion of this document is the Standards discussion list: <http://mail.jabber.org/mailman/listinfo/standards>.

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

The following keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".


Table of Contents


1. Introduction
2. Requirements
3. Use Cases
    3.1. Discovering support for message moderation
    3.2. Managing moderators
       3.2.1. Becoming a moderator
       3.2.2. Leaving as a message moderator
       3.2.3. Pausing message moderation
       3.2.4. Listing message moderators
    3.3. Room sending the message for moderation
    3.4. Moderator managing messages
    3.5. Room cancelling the message
4. Security Considerations
5. IANA Considerations
6. Jabber Registrar Considerations
    6.1. Protocol Namespaces
    6.2. Service Discovery Features
    6.3. Field Standardization
    6.4. Field Standardization
7. XML Schema
    7.1. http://jabber.org/protocol/muc#msg_room_moderator
8. Acknowledgements
Notes
Revision History


1. Introduction

This document defines a means to manage moderated rooms. XEP ??? defines a way for the users without a voice to submit the messages for moderation. This proposal provides a mechanism for the moderator and the room to communicate to do the moderation.

2. Requirements

All the requirements mentioned in XEP-0045 and XEP ??? are applicable. In addition the ability to become a message moderator SHALL be controlled by affiliation level - only participants with admin or owner affiliation level (referred to as room moderator) can become a message moderator. Room moderator's who have enabled message moderation are referred to as moderator in this proposal.

3. Use Cases

3.1 Discovering support for message moderation

A participant wanting to become a moderator as defined in this spec sends a disco#info query trying to find out if message moderation is supported or not.

Example 1. User queries for availability of message moderation

<iq from='crone1@shakespeare.lit/desktop'
    id='disco1'
    to='darkcave@macbeth.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

If the room supports managing moderators, it MUST return the feature 'http://jabber.org/protocol/muc#msg_room_moderator'.

Example 2. MUC response to user query for availability of managing moderators

<iq from='darkcave@macbeth.shakespeare.lit'
    id='disco1'
    to='crone1@shakespeare.lit/desktop'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='conference'
        name='A Dark Cave'
        type='text'/>
    ...
    <feature var='muc_moderated'/>
    <feature var='http://jabber.org/protocol/muc#msg_moderate'/>
    ...
    <feature var='http://jabber.org/protocol/muc#msg_room_moderator'/>
    ...
  </query></iq>

Example 3. MUC response to user query when there is one or more active moderator(s) in the room

<iq from='darkcave@macbeth.shakespeare.lit'
    id='disco1'
    to='crone1@shakespeare.lit/desktop'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='conference'
        name='A Dark Cave'
        type='text'/>
    ...
    <feature var='muc_moderated'/>
    <feature var='http://jabber.org/protocol/muc#msg_moderate'/>
    ...
    <feature var='http://jabber.org/protocol/muc#msg_room_moderator'/>
    ...
    <x xmlns='jabber:x:data' type='result'>
      <field var='FORM_TYPE' type='hidden'>
        <value>http://jabber.org/protocol/muc#roominfo</value>
      </field>
      ...
      <field var='muc#msg_room_moderator' type='boolean'>
        <value>true</value>
      </field>
      ...
    </x>
  </query></iq>

To fetch the list of currently active room moderators, participant can send a disco#items query to the room with a 'http://jabber.org/protocol/muc#msg_room_moderator' extension. The jid's of moderators MUST be in-room jids and if exposed, MUST be the complete list of moderators. It is an implementation detail whether to expose these values or not, but they MUST be exposed for the list moderator usecase described below. If the jid's are exposed, the response MUST contain an 'http://jabber.org/protocol/muc#msg_room_moderator' extension element.

Example 4. MUC response to User query when there is one or more active moderator(s) in the room

<iq from='crone1@shakespeare.lit/desktop'
    id='disco_list'
    to='darkcave@macbeth.shakespeare.lit'
    type='get'>
    <query xmlns='http://jabber.org/protocol/disco#items' />
    <x xmlns='http://jabber.org/protocol/muc#msg_room_moderator' />
</iq>


<iq from='darkcave@macbeth.shakespeare.lit'
    id='disco_list'
    to='crone1@shakespeare.lit/desktop'
    type='result'>
    <query xmlns='http://jabber.org/protocol/disco#items'>
      <item jid='darkcave@macbeth.shakespeare.lit/secondwitch'/>
      <item jid='darkcave@macbeth.shakespeare.lit/uberwitch'/>
    </query>
    <x xmlns='http://jabber.org/protocol/muc#msg_room_moderator' />
</iq>

3.2 Managing moderators

3.2.1 Becoming a moderator

If the room supports message moderation, a participant wanting to become a moderator sends a iq packet to the room with the start notification.

Example 5. User tries to become a message moderator

<iq
     from='wiccarocks@shakespeare.lit/laptop'
     to='darkcave@macbeth.shakespeare.lit' 
     id='mod_id1'
     type='set'>
     <query xmlns='http://jabber.org/protocol/muc#msg_room_moderator'>
   	<action type='start' />
     </query>
</iq>  
An error is to be returned if :

Note that for any moderator related usecase in message moderation (not just 'start'), an appropriate iq error MUST be sent as response to requestor if the conditions mentioned above are not satisfied.

Example 6. Message moderation is not supported

<iq
     from='darkcave@macbeth.shakespeare.lit'
     to='wiccarocks@shakespeare.lit/laptop' 
     id='mod_id1'
     type='error'>
   <query xmlns='http://jabber.org/protocol/muc#msg_room_moderator'>
     <action type='start' />
   </query>
   <error code='403' type='auth'>
     <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
   </error>
</iq>  

Becoming a message moderator could also fail for policy reasons, due to evaluation of custom extensions (like access control, etc - these are not defined in the scope of this document) or other implementation specific reasons. Appropriate iq error MUST be returned for indicating these (enforcement of these is not limited to 'start').

If the user has a Admin or higher affiliation and all other constraints imposed on the room are satisfied as per muc spec, then the service will inform the user about the start of message moderation.

Example 7. Notifying the user that it has become the moderator

<iq
    from='darkcave@macbeth.shakespeare.lit'
    to='wiccarocks@shakespeare.lit/laptop' 
    id='mod_id1'
    type='result'>
  <query xmlns='http://jabber.org/protocol/muc#msg_room_moderator' />
</iq>

The component MUST broadcast start and stop of moderation as defined in XEP ???. If there are multiple moderators, room MUST NOT send stop's/start's for intermediate moderator additions/removals. That is, the broadcast MUST be sent only when room moderation becomes initially enabled for the room moderator and room moderation is stopped for the room when all moderators stop moderation - not for any other moderator initiated start/stop.

3.2.2 Leaving as a message moderator

If a moderator intends to leave as a message moderator of the room then it should send a iq packet with the stop moderation notification.

Example 8. Moderator signalling end of its moderation

<iq
     from='wiccarocks@shakespeare.lit/laptop'
     to='darkcave@macbeth.shakespeare.lit'
     id='mod_id2'
     type='set'>
   <query xmlns='http://jabber.org/protocol/muc#msg_room_moderator' >
     <action type='stop' />
   </query>
</iq>

If this is the only moderator in the room, it MUST be broadcasted to the room participants as per XEP ??? and the room config disco#info MUST reflect moderation state (no 'muc#msg_room_moderator' element or value set to false) from then on - to signal stop of message moderation for the room.

Example 9. Notifying the user that it is no longer the moderator

<iq
    from='darkcave@macbeth.shakespeare.lit'
    to='wiccarocks@shakespeare.lit/laptop'
    id='mod_id2'
    type='result'>
  <query xmlns='http://jabber.org/protocol/muc#msg_room_moderator' />  
</iq>

This usecase is implicitly invoked when an active moderator leaves the room without sending a stop moderation request.That is, the message moderator becomes unavailable or leaves the room without a formal 'stop' being sent to the room.

Messages which were pending for this moderator's approval could be handled in two ways -

  1. If there are multiple moderators in a room, the room SHOULD reroute it to another available moderator (subject to constraints of pause, cancel and route as described below for each message).
  2. If no other moderator is available, room sends an 'error' action to the submitter.

3.2.3 Pausing message moderation

If the moderator wants to pause accepting any further messages for moderation, while still act on the pending messages - it has to set the state to 'pause'. In this state, the moderator is still responsible for the pending messages it has to act on but no new messages are sent to it for moderation.

That is, room moderation continues to be active (even if this is the only moderator), but no further messages are sent to the specific moderator again : all new message moderation requests are routed to other moderators. If there are no other moderators present, the room MUST reject the messages with an appropriate diagnostic reason.

Example 10. Moderator pauses message moderation

<iq
     from='wiccarocks@shakespeare.lit/laptop'
     to='darkcave@macbeth.shakespeare.lit'
     id='mod_id3'
     type='set'>
     <query xmlns='http://jabber.org/protocol/muc#msg_room_moderator'>
   	<action type='pause' />
     </query>
</iq>  

Moderator resumes moderation by sending 'start' again.

3.2.4 Listing message moderators

Any active moderator can request for the list of currently active moderators and the room MUST send it the complete list.

Example 11. Moderator listing active moderators in the room

<iq from='crone1@shakespeare.lit/desktop'
    id='disco_list'
    to='darkcave@macbeth.shakespeare.lit'
    type='get'>
    <query xmlns='http://jabber.org/protocol/disco#items' />
    <x xmlns='http://jabber.org/protocol/muc#msg_room_moderator' />
</iq>


<iq from='darkcave@macbeth.shakespeare.lit'
    id='disco_list'
    to='crone1@shakespeare.lit/desktop'
    type='result'>
    <query xmlns='http://jabber.org/protocol/disco#items'>
      <item jid='darkcave@macbeth.shakespeare.lit/secondwitch'/>
      <item jid='darkcave@macbeth.shakespeare.lit/uberwitch'/>
    </query>
    <x xmlns='http://jabber.org/protocol/muc#msg_room_moderator' />
</iq>

3.3 Room sending the message for moderation

The room will submit the new message to the moderator with http://jabber.org/protocol/muc#msg_room_moderator extension. This extension differentiates the moderation request from a normal groupchat message.

Example 12. Moderator recieving the message for moderation

<message
    from='darkcave@macbeth.shakespeare.lit/thirdwitch'
    to='wiccarocks@shakespeare.lit/laptop'
    type='groupchat'>
  <body>Harrpier cries: 'tis time, 'tis time.</body>
  <x xmlns='http://jabber.org/protocol/muc#msg_room_moderator'>
     <action type='submit' id='moderation_message_id'/>
  </x>
</message>

3.4 Moderator managing messages

The moderator processes the message and notifies the room of the result by assigning appropriate value(accepted|rejected) to the type attribute of the action element. The moderator MUST send 'id' in the action, and its value MUST be identical to what is specified in the request. The room is expected to correlate moderation responses with pending messages using this id.

Example 13. Moderator approves message

<message
     from='wiccarocks@shakespeare.lit/laptop'
     to='darkcave@macbeth.shakespeare.lit'
     type='groupchat'>
   <x xmlns='http://jabber.org/protocol/muc#msg_room_moderator'>
       <action type='accepted' id='moderation_message_id'>
           <reason>what a good idea!</reason>
       </action>
   </x>
</message>

Example 14. Moderator rejects message

<message
     from='wiccarocks@shakespeare.lit/laptop'
     to='darkcave@macbeth.shakespeare.lit'
     type='groupchat'>
   <x xmlns='http://jabber.org/protocol/muc#msg_room_moderator'>
       <action type='rejected' id='moderation_message_id'>
           <reason>you said that already</reason>
       </action>
   </x>
</message>

It might be possible that after having accepted message(s) for moderation, moderator does not want to decide on some specific message(s). In this case, moderator sends a cancel with the specific moderation_message_id back to the room. The room MUST then find another moderator to service this message (who has not previously cancelled that message to avoid looping). If none are found, room MUST send 'error' action to submitter.

Example 15. Moderator cancels message which it previously accepted for moderation

<message
    from='wiccarocks@shakespeare.lit/laptop'
    to='darkcave@macbeth.shakespeare.lit'
    type='groupchat'>
  <x xmlns='http://jabber.org/protocol/muc#msg_room_moderator' >
     <action type='cancel' id='moderation_message_id'/>
  </x>
</message>

It is possible that moderator instead of canceling a message, wants to delegate the message to a specific moderator for moderation. In this case, moderator sends a 'route' to the room with the in room jid of the moderator to forward to.

Example 16. Moderator forwards the message to another moderator

<message
    from='wiccarocks@shakespeare.lit/laptop'
    to='darkcave@macbeth.shakespeare.lit'
    type='groupchat'>
  <x xmlns='http://jabber.org/protocol/muc#msg_room_moderator'>
     <action type='route' to='darkcave@macbeth.shakespeare.lit/uberwitch' id='moderation_message_id'>
       <reason>I dont understand shakespeare as well as you, please handle it.</reason>
     </action>
  </x>
</message>
If the destination of the route is invalid, not online or not an active message moderator, then room MUST send an 'error' action back to submitter.

Once accepted, rejected, cancel or route is sent, the moderator is not responsible for moderation_message_id anymore. The only association the room keeps between the moderator and the message is to ensure that multiple cancel's/route's for a specific message does not get sent to a moderator which has previously processed the same message.

3.5 Room cancelling the message

The room might also want to cancel the submission of the message. On receving the cancel request the moderator must drop the message.

Example 17. Room sends a message cancellation request

<message
    from='hag66@shakespeare.lit/pda'
    to='darkcave@macbeth.shakespeare.lit'
    type='groupchat'>
  <x xmlns='http://jabber.org/protocol/muc#msg_room_moderator' >
     <action type='cancel' id='moderation_message_id'/>
  </x>
</message>

4. Security Considerations

Security considerations applicable to multi user chat are applicable here.

5. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [1].

6. Jabber Registrar Considerations

The XMPP Registrar [2] includes the following information in its registries.

6.1 Protocol Namespaces

The XMPP Registrar includes the following message moderation related namespaces in its registry of protocol namespaces:

6.2 Service Discovery Features

The following features related to a MUC room can be discovered by means of Service Discovery.

Registry Submission

<var>
  <name>http://jabber.org/protocol/muc#msg_room_moderator</name>
  <desc>Indicates that room supports managing message moderators</desc>
  <doc>Managing Message moderators XEP proposal</doc>
</var>
  

6.3 Field Standardization

The following field needs to be added to the muc#roominfo FORM_TYPE indicating who is the current message moderator for a room.

Registry Submission

<form_type>
  <name>http://jabber.org/protocol/muc#msg_room_moderator</name>
  <doc>XEP-xxxx</doc>
  <desc>
    Form specifying if message moderation is enabled in the Multi-User Chat (MUC) room.
  </desc>
  <field
      var='muc#msg_room_moderator'
      type='boolean'
      label='Is message moderation currently active in the room'/>
</form_type>
      

6.4 Field Standardization

The following field needs to be added to the muc#roomconfig FORM_TYPE indicating whether a room has been configured to support mesage moderation or not.

Registry Submission

<form_type>
  <name>http://jabber.org/protocol/muc#msg_room_moderator</name>
  <doc>XEP-xxxx</doc>
  <desc>
    Forms enabling configuration of a message moderated Multi-User Chat (MUC) room as defined by this XEP.
    If it is enabled, then the feature "http://jabber.org/protocol/muc#msg_moderate" and "muc_moderated" MUST be exposed.
  </desc>
  <field
      var='muc#roomconfig_msg_room_moderator'
      type='boolean'
      label='Whether to allow message moderation or not'/>
</form_type>
      

7. XML Schema

7.1 http://jabber.org/protocol/muc#msg_room_moderator

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/muc#msg_room_moderator'
    xmlns='http://jabber.org/protocol/muc#msg_room_moderator'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in submitter XEP (TODO - add link ?).
    </xs:documentation>
  </xs:annotation>
  
  <xs:element name='x'>
    <xs:complexType>
      <xs:element ref='action'/>
    </xs:complexType>
  </xs:element> 

  <xs:element name='action'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='reason' minOccurs='0'/>
      </xs:sequence>
      <xs:attribute name='type' use='required'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='start' />
            <xs:enumeration value='stop' />
            <xs:enumeration value='pause' />
            <xs:enumeration value='submit' />
            <xs:enumeration value='accepted' />
            <xs:enumeration value='rejected' />
            <xs:enumeration value='cancel' />
            <xs:enumeration value='route' />
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name='to' type='xs:string' use='optional' />
      <xs:attribute name='id' type='xs:string' use='optional' />
    </xs:complexType>
  </xs:element>
  <xs:element name='reason' type='xs:string'/>
</xs:schema>
  

8. Acknowledgements

The authors would like to thank the following individuals for their many helpful comments on various drafts of this proposal: Jacques Belissent.


Notes

1. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

2. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://www.xmpp.org/registrar/>.


Revision History

Version 0.0.1 (2007-05-22)

Initial submission.

(mm,rs)

END