moparisthebest
/
xeps
mirror of https://github.com/moparisthebest/xeps
1
0
Fork 0
Code Issues Releases Wiki Activity
xeps/inbox/muc-admin.xml

591 lines
24 KiB
XML
Raw Permalink Blame History

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Multi-User Chat Administration</title>
<abstract>This specification defines how to administer Multi-User Chat rooms and services using Ad-Hoc Commands.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0045</spec>
<spec>XEP-0050</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
&stpeter;
<revision>
<version>0.0.1</version>
<date>2012-09-25</date>
<initials>psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>&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).</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>This document addresses the following requirements:</p>
<ul>
<li>Enable users with appropriate privileges to perform common administrative tasks with respect to Multi-User Chat rooms and services.</li>
<li>Re-use Ad-Hoc Commands for maximum flexibility.</li>
</ul>
</section1>
<section1 topic='Discovery' anchor='disco'>
<p>A MUC service MUST advertise any administrative commands it supports via &xep0030; (as described in <cite>XEP-0050: Ad-Hoc Commands</cite>); such commands exist as well-defined discovery nodes associated with the service in question.</p>
<p>All supported Ad-Hoc Command nodes MUST be included in the &xep0115; hash generated by a MUC service.</p>
</section1>
<section1 topic='Extensibility' anchor='extensions'>
<p>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").</p>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<p>This document defines a profile of <cite>XEP-0050: Ad-Hoc Commands</cite> 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.)</p>
<ol>
<li>Modify Room Subject</li>
<li>Set Occupant Role</li>
<li>Set User Affiliation</li>
<li>Assign Occupant Nickname</li>
<li>Clear Room History</li>
<li>Report a Spammer</li>
</ol>
<p>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.</p>
<section2 topic='Modify Room Subject' anchor='modify-room-subject'>
<p>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.</p>
<example caption='Admin Requests to Modify a Room Subject'><![CDATA[
<iq from='wiccarocks@shakespeare.lit/laptop'
id='ur72vx41'
to='coven@chat.shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='urn:xmpp:muc-admin:modify-room-subject'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> 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).</p>
<example caption='Service Returns Modify Room Subject Form to Admin'><![CDATA[
<iq from='coven@chat.shakespeare.lit'
id='ur72vx41'
to='wiccarocks@shakespeare.lit/laptop'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:modify-room-subject'/>
sessionid='5981DC80-AF4E-445E-9FF6-0F4067FDCD05'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Modifying a Room Subject</title>
<instructions>Fill out this form to modify the room subject.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>urn:xmpp:muc-admin</value>
</field>
<field label='Room subject'
type='text'
var='room-subject'>
<required/>
</field>
<field type='hidden' var='roomjid'>
<value>coven</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Modify Room Subject Form to Service'><![CDATA[
<iq from='wiccarocks@shakespeare.lit/laptop'
id='9i2fsvc7'
to='coven@chat.shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:modify-room-subject'
sessionid='5981DC80-AF4E-445E-9FF6-0F4067FDCD05'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>urn:xmpp:muc-admin</value>
</field>
<field var='room-subject'>
<value>Fire Burn and Cauldron Bubble!</value>
</field>
<field var='roomjid'>
<value>coven@chat.shakespeare.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='coven@chat.shakespeare.lit'
id='9i2fsvc7'
to='wiccarocks@shakespeare.lit/laptop'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:modify-room-subject'
sessionid='5981DC80-AF4E-445E-9FF6-0F4067FDCD05'
status='completed'/>
</iq>
]]></example>
<p>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.</p>
</section2>
<section2 topic='Modify Occupant Role' anchor='modify-occupant-role'>
<p>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.</p>
<example caption='Admin Requests to Modify an Occupant Role'><![CDATA[
<iq from='fluellen@shakespeare.lit/pda'
id='so3g2bl5'
to='harfleur@chat.shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='urn:xmpp:muc-admin:modify-occupant-role'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form.</p>
<example caption='Service Returns Modify Occupant Role Form to Admin'><![CDATA[
<iq from='harfleur@chat.shakespeare.lit'
id='so3g2bl5'
to='fluellen@shakespeare.lit/pda'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:modify-occupant-role'/>
sessionid='F4CC8121-DA42-4FDD-8668-17900310D8BE'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Modifying an Occupant Role</title>
<instructions>Fill out this form to modify the role for a room occupant.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>urn:xmpp:muc-admin</value>
</field>
<field label='Occupant Nickname'
type='text-single'
var='nick'>
<required/>
</field>
<field label='Role'
type='list-single'
var='role'>
<option label='None (note: user will be kicked)'><value>none</value></option>
<option label='Visitor'><value>visitor</value></option>
<option label='Participant'><value>participant</value></option>
<option label='Moderator'><value>moderator</value></option>
<required/>
</field>
<field label='Reason'
type='text-single'
var='reason'/>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Modify Occupant Role Form to Service'><![CDATA[
<iq from='fluellen@shakespeare.lit/pda'
id='kes62fa3'
to='harfleur@chat.shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:modify-occupant-role'
sessionid='F4CC8121-DA42-4FDD-8668-17900310D8BE'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>urn:xmpp:muc-admin</value>
</field>
<field var='nick'>
<value>pistol</value>
</field>
<field var='role'>
<value>none</value>
</field>
<field var='reason'>
<value>Avaunt, you cullion!</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='harfleur@chat.shakespeare.lit'
id='kes62fa3'
to='fluellen@shakespeare.lit/pda'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:modify-occupant-role'
sessionid='F4CC8121-DA42-4FDD-8668-17900310D8BE'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Set User Affiliation' anchor='set-user-affiliation'>
<p>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.</p>
<example caption='Admin Requests to Modify a User Affiliation'><![CDATA[
<iq from='crone1@shakespeare.lit/desktop'
id='rk391bf6'
to='coven@chat.shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='urn:xmpp:muc-admin:modify-user-affiliation'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form.</p>
<example caption='Service Returns Modify Occupant Role Form to Admin'><![CDATA[
<iq from='coven@chat.shakespeare.lit'
id='rk391bf6'
to='crone1@shakespeare.lit/desktop'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:modify-user-affiliation'/>
sessionid='3C5229C9-CD08-46F0-80BF-3BAB604363A2'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Modifying a User Affiliation</title>
<instructions>Fill out this form to modify the affiliation for a user.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>urn:xmpp:muc-admin</value>
</field>
<field label='User JID'
type='jid-single'
var='userjid'>
<required/>
</field>
<field label='Affiliation'
type='list-single'
var='affiliation'>
<option label='Outcast (note: user will be banned)'><value>outcast</value></option>
<option label='None'><value>none</value></option>
<option label='Member'><value>member</value></option>
<option label='Administrator'><value>administrator</value></option>
<option label='Owner'><value>owner</value></option>
<required/>
</field>
<field label='Reason'
type='text-single'
var='reason'/>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Modify User Affiliation Form to Service'><![CDATA[
<iq from='crone1@shakespeare.lit/desktop'
id='i72bs93v'
to='coven@chat.shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:modify-user-affiliation'
sessionid='3C5229C9-CD08-46F0-80BF-3BAB604363A2'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>urn:xmpp:muc-admin</value>
</field>
<field var='userjid'>
<value>hecate@shakespeare.lit</value>
</field>
<field var='affiliation'>
<value>owner</value>
</field>
<field var='reason'>
<value>A worthy witch indeed!</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='coven@chat.shakespeare.lit'
id='i72bs93v'
to='crone1@shakespeare.lit/desktop'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:modify-user-affiliation'
sessionid='3C5229C9-CD08-46F0-80BF-3BAB604363A2'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Assign Occupant Nickname' anchor='assign-occupant-nickname'>
<p>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").</p>
<example caption='Admin Requests to Assign an Occupant Nickname'><![CDATA[
<iq from='crone1@shakespeare.lit/desktop'
id='9eb251ck'
to='heath@chat.shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='urn:xmpp:muc-admin:assign-occupant-nickname'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form.</p>
<example caption='Service Returns Assign Occupant Nickname Form to Admin'><![CDATA[
<iq from='heath@chat.shakespeare.lit'
id='9eb251ck'
to='crone1@shakespeare.lit/desktop'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:assign-occupant-nickname'/>
sessionid='53E9C396-64DD-4652-97CF-42E21E857A2D'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Assigning an Occupant Nickname</title>
<instructions>Fill out this form to assign a nickname to a participant.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>urn:xmpp:muc-admin</value>
</field>
<field label='Current Nickname'
type='text-single'
var='current-nick'>
<required/>
</field>
<field label='New Nickname'
type='text-single'
var='nick'>
<required/>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Assign Occupant Nickname Form to Service'><![CDATA[
<iq from='crone1@shakespeare.lit/desktop'
id='h4bs91hy'
to='coven@chat.shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:assign-occupant-nickname'
sessionid='53E9C396-64DD-4652-97CF-42E21E857A2D'
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>urn:xmpp:muc-admin</value>
</field>
<field var='nick'>
<value>thirdwitch</value>
</field>
<field var='newnick'>
<value>hag66</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='heath@chat.shakespeare.lit'
id='h4bs91hy'
to='crone1@shakespeare.lit/desktop'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:assign-occupant-nickname'
sessionid='53E9C396-64DD-4652-97CF-42E21E857A2D'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Clear Room History' anchor='clear-room-history'>
<p>This use case enables a moderator or administrator to clear the history that new occupants receive when they join the room.</p>
<example caption='Admin Requests to Clear History'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='xn274h59'
to='heath@chat.shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='urn:xmpp:muc-admin:clear-room-history'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD simply clear the history.</p>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='heath@chat.shakespeare.lit'
id='xn274h59'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:clear-room-history'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Report a Spammer' anchor='report-spammer'>
<p>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;.</p>
<example caption='Admin Requests to Report a Spammer'><![CDATA[
<iq from='fluellen@shakespeare.lit/pda'
id='lz62g4b8'
to='harfleur@chat.shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='urn:xmpp:muc-admin:spamreport'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form.</p>
<example caption='Service Returns Spam Report Form to Admin'><![CDATA[
<iq from='harfleur@chat.shakespeare.lit'
id='lz62g4b8'
to='fluellen@shakespeare.lit/pda'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:spamreport'/>
sessionid='E244DA21-E081-430C-B030-6886FDBCF0CD'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Spam Report</title>
<instructions>Fill out this form to report a room occupant as a spammer.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>urn:xmpp:muc-admin</value>
</field>
<field label='Occupant Nickname'
type='text-single'
var='nick'>
<required/>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Spam Report Form to Service'><![CDATA[
<iq from='fluellen@shakespeare.lit/pda'
id='gr92g1v5'
to='harfleur@chat.shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:spamreport'
sessionid='E244DA21-E081-430C-B030-6886FDBCF0CD'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>urn:xmpp:muc-admin</value>
</field>
<field var='nick'>
<value>pistol</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='harfleur@chat.shakespeare.lit'
id='gr92g1v5'
to='fluellen@shakespeare.lit/pda'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='urn:xmpp:muc-admin:modify-occupant-role'
sessionid='E244DA21-E081-430C-B030-6886FDBCF0CD'
status='completed'/>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Error Handling' anchor='errors'>
<p>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.</p>
<table caption='Error Conditions'>
<tr>
<th>Condition</th>
<th>Cause</th>
</tr>
<tr>
<td>&conflict;</td>
<td>The command cannot be completed because of a data or system conflict (e.g., a user already exists with that username).</td>
</tr>
<tr>
<td>&feature;</td>
<td>The specific command is not supported (even though the ad-hoc commands protocol is).</td>
</tr>
<tr>
<td>&forbidden;</td>
<td>The requesting entity does not have sufficient privileges to perform the command.</td>
</tr>
<tr>
<td>&notallowed;</td>
<td>No entity is allowed to perform the command (e.g., retrieve the CEO's roster).</td>
</tr>
<tr>
<td>&unavailable;</td>
<td>The ad-hoc commands protocol is not supported.</td>
</tr>
</table>
<p>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).</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>The ability to complete the administrative tasks specified herein MUST NOT be granted to users who lack service-level administrative privileges.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-protocol'>
<p>The XMPP Registrar shall add "urn:xmpp:muc-admin" to its registry of protocol namespaces.</p>
</section2>
<section2 topic='Field Standardization' anchor='registrar-formtype'>
<p>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.</p>
<code caption='Registry Submission'><![CDATA[
<form_type>
<name>urn:xmpp:muc-admin</name>
<doc>XEP-xxxx</doc>
<desc>Forms used for administration of MUC rooms and services.</desc>
<field var='newnick'
type='text-single'
label='The new nickname to be assigned to a room occupant'/>
<field var='nick'
type='text-single'
label='The current nickname of a room occupant'/>
<field var='roomjid'
type='jid-single'
label='The Jabber ID of MUC room'/>
<field var='roomjids'
type='jid-multi'
label='The Jabber IDs of one or more rooms to which an operation applies'/>
<field var='subject'
type='text-single'
label='The text of a room subject'/>
</form_type>
]]></code>
</section2>
</section1>
<section1 topic='XML Schema'>
<p>Because the protocol defined here is a profile of <cite>XEP-0050: Ad-Hoc Commands</cite>, no schema definition is needed.</p>
</section1>
</xep>
Reference in New Issue View Git Blame Copy Permalink