XEP-0389: add OOB challenge type.

Also add a revision block and fix a few minor typos.

xep-0389.xml

@@ -31,6 +31,21 @@
   <supersededby/>
   <shortname>ibr2</shortname>
   &sam;
+  <revision>
+    <version>0.4.0</version>
+    <date>2020-04-22</date>
+    <initials>ssw</initials>
+    <remark>
+      <ul>
+        <li>Add OOB challenge type.</li>
+        <li>Add IQ query for flows.</li>
+        <li>Add a glossary.</li>
+        <li>Make challenge listings more consistent.</li>
+        <li>Cleanup and expand the registrar considerations section.</li>
+        <li>Clarifications and typo fixes throughout the text.</li>
+      </ul>
+    </remark>
+  </revision>
   <revision>
     <version>0.3.0</version>
     <date>2020-04-19</date>
@@ -216,14 +231,14 @@
     registration or recovery flow.
     Each &lt;challenge/&gt; element contains a "type" attribute that uniquely
     identifies the challenge for the purpose of determining if it is supported.
-    If a flow would offer the same challenge twice (eg. two dataforms asking for
-    different data), the challenge SHOULD only be listed once in the flow
+    If a flow would offer the same challenge twice (eg. two data forms asking
+    for different data), the challenge SHOULD only be listed once in the flow
     element.
   </p>
   <p>
     For example, a server may advertise a "Verify with SMS" flow and a "Verify
-    by Phone Call" flow that both show a dataform asking for a phone number
-    and then a second dataform asking for a token provided to the user in a
+    by Phone Call" flow that both show a data form asking for a phone number
+    and then a second data form asking for a token provided to the user in a
     text message or phone call depending on which flow the user selects.
   </p>
   <example caption='Host Advertises Stream Features'><![CDATA[
@@ -332,7 +347,7 @@
     If the client is initiating registration or recovery after a stream has
     already been initiated it uses the same registration element wrapped in an
     IQ of type "set".
-  </p>
+    </p>
   <example caption='Client selects a recovery flow after stream negotiation'><![CDATA[
 <iq type='set' id='foo'>
   <recovery xmlns='urn:xmpp:register:0'>
@@ -347,14 +362,28 @@
     'urn:xmpp:register:0' namespace with a 'type' attribute that uniquely
     identifies the type of payload a client might expect the element to contain.
   </p>
+    <example caption='Server issues a challenge'><![CDATA[
+<challenge xmlns='urn:xmpp:register:0'
+           type='urn:example:challenge'>
+  <example xmlns='urn:example:challenge'>Payload</example>
+</challenge>]]></example>
   <p>
-    This document defines a type of 'jabber:x:data' which MUST always contain a
-    data form (an 'x' element with type 'form') as defined by &xep0004;.
-    Other types may be defined in the future.
-    For example, a challenge containing a data form might look like the
-    following:
+    After a challenge is received, the client replies to the challenge by
+    sending a &lt;response/&gt; element qualified by the 'urn:xmpp:register:0'
+    namespace or a cancellation as defined later in this document.
+    If the client sends a response, it MUST also include the payload
+    corresponding to the challenges 'type' element (which may be empty).
   </p>
-  <example caption='Host Returns Registration Form to Entity'><![CDATA[
+    <example caption='Client responds to a challenge'><![CDATA[
+<response xmlns='urn:xmpp:register:0'>
+  <result xmlns='urn:example:challenge'>Example Response</result>
+</response>]]></example>
+  <section2 topic='Data Form' anchor='dataform'>
+    <p>
+      This document defines a type of 'jabber:x:data' which MUST always contain a
+      data form (an 'x' element with type 'form') as defined by &xep0004;.
+    </p>
+    <example caption='Server issues a data form challenge'><![CDATA[
 <challenge xmlns='urn:xmpp:register:0'
            type='jabber:x:data'>
   <x xmlns='jabber:x:data' type='form'>
@@ -375,20 +404,14 @@
       <required/>
     </field>
   </x>
-</challenge>
-]]></example>
+</challenge>]]></example>
   <p>
-    After a challenge is received, the client replies to the challenge by
-    sending a &lt;response/&gt; element qualified by the 'urn:xmpp:register:0'
-    namespace or a cancellation as defined later in this document.
-    If the client sends a response, it MUST also include a payload defined by
-    the challenges 'type' element.
-    In the case of a "jabber:x:data" challenge, the payload should be a form
-    submission as defined by &xep0004; (an 'x' element of type 'submit').
+    The response to a "jabber:x:data" challenge MUST be a form submission (an
+    'x' element of type 'submit').
     For instance, to reply to the data form challenge from the previous example
     a client might send:
   </p>
-  <example caption='User Submits Registration Form'><![CDATA[
+  <example caption='Client submits a data form in response to the challenge'><![CDATA[
 <response xmlns='urn:xmpp:register:0'>
   <x xmlns='jabber:x:data' type='submit'>
     <field type='hidden' var='FORM_TYPE'>
@@ -407,8 +430,26 @@
       <value>juliet@capulet.com</value>
     </field>
   </x>
-</response>
-]]></example>
+</response>]]></example>
+  </section2>
+  <section2 topic='Out of Band Data' anchor='oob'>
+    <p>
+      Challenges of the type "jabber:x:oob" MUST contain an &lt;x/&gt; element
+      qualified by the "jabber:x:oob" namespace as defined in &xep0066;.
+    </p>
+    <example caption='Server issues an OOB challenge'><![CDATA[
+<challenge xmlns='urn:xmpp:register:0'
+           type='jabber:x:oob'>
+  <x xmlns='jabber:x:oob'>
+    <url>http://example.net/login?token=foo</url>
+  </x>
+</challenge>]]></example>
+    <p>
+      If the client sends a response to the OOB challenge it MUST be empty.
+    </p>
+    <example caption='Client acknowledges the OOB challenge'><![CDATA[
+<response xmlns='urn:xmpp:register:0'/>]]></example>
+  </section2>
 </section1>
 <section1 topic='Completing Registration or Recovery' anchor='completion'>
   <p>
@@ -528,7 +569,7 @@
   <type>A name that uniquely identifies the challenge.</type>
   <desc>A natural-language summary of the challenge.</desc>
   <doc>
-    The doucment (or documents) in which the IBR challenge and its paylaod are
+    The document (or documents) in which the IBR challenge and its payload are
     defined.
   </doc>
 </challenge>]]></code>
@@ -540,17 +581,24 @@
     <p>This specification defines the following IBR challenge:</p>
     <ul>
       <li>jabber:x:data</li>
+      <li>jabber:x:oob</li>
     </ul>
     <p>
       Upon advancement of this specification from a status of Experimental to a
-      status of Draft, the &REGISTRAR; shall add the following definition to the
-      IBR challenges registry, as described in this document:
+      status of Draft, the &REGISTRAR; shall add the following definitions to
+      the IBR challenges registry, as described in this document:
     </p>
     <code caption='IBR Challenges Registry Submission for Data Forms'><![CDATA[
 <challenge>
   <type>jabber:x:data</type>
   <desc>Requests that the client fill out an XEP-0004 data form.</desc>
   <doc>&xep0389;, &xep0004;</doc>
+</challenge>]]></code>
+    <code caption='IBR Challenges Registry Submission for OOB Data'><![CDATA[
+<challenge>
+  <type>jabber:x:oob</type>
+  <desc>Requests that the client execute a URI.</desc>
+  <doc>&xep0066;</doc>
 </challenge>]]></code>
   </section2>
   <section2 topic='Namespace Versioning' anchor='registrar-versioning'>