add 'spec roadmap' section (#375)

merging per agreement on 12-Sep-2018 call.

* add 'spec roadmap' section as discussed with vijaybh'

* fix minor mispelling

* re-write and incorp vijaybh's feedback

* fix BS's bs objections to my source formatting...

* fix typo, thx apowers313 :)

* revise Note, thx emlun!

* polish

* fix an oops

* fix oopsies and try to polish

* update per emlun's comment, thx!

index.bs

@@ -29,7 +29,7 @@ Shortname: webauthn
 Level: 1
 Editor: Dirk Balfanz, w3cid 47648, Google, balfanz@google.com
 Editor: Alexei Czeskis, w3cid 87258, Google, aczeskis@google.com
-Editor: Jeff Hodges, w3cid 43843, Invited Expert, Jeff.Hodges@KIngsMountain.com
+Editor: Jeff Hodges, w3cid 43843, Invited Expert, Jeff.Hodges@KingsMountain.com
 Editor: J.C. Jones, w3cid 87240, Mozilla, jc@mozilla.com
 Editor: Michael B. Jones, w3cid 38745, Microsoft, mbj@microsoft.com
 Editor: Akshay Kumar, w3cid 99318, Microsoft, akshayku@microsoft.com
@@ -58,7 +58,7 @@ Text Macro: WRP WebAuthn Relying Party
 Text Macro: WRPS WebAuthn Relying Parties
 Ignored Vars: op, alg, type, algorithm
 Abstract: This specification defines an API enabling the creation and use of strong, attested, [=scoped=], public key-based
- credentials by web applications, for the purpose of strongly authenticating users. Conceptually, one or more [=public key
+ credentials by [=web applications=], for the purpose of strongly authenticating users. Conceptually, one or more [=public key
  credentials=], each [=scoped=] to a given [=WebAuthn Relying Party=], are created by and [=bound credential|bound=] to
  [=authenticators=] as requested by the web application. The user agent mediates access to [=authenticators=] and their [=public
  key credentials=] in order to preserve user
@@ -226,6 +226,13 @@ spec:webidl; type:interface; text:Promise
         "title": "Feature Policy",
         "publisher": "WICG: Web Incubator Community Group",
         "status": "Draft Community Group Report"
+    },
+
+    "WebAuthnAPIGuide": {
+        "href": "https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API",
+        "title": "Web Authentication API Guide",
+        "publisher": "MDN: Mozilla Developer Network",
+        "status": "Experimental"
     }
 }
 </pre>
@@ -236,7 +243,7 @@ spec:webidl; type:interface; text:Promise
 [INFORMATIVE]
 
 This specification defines an API enabling the creation and use of strong, attested, [=scoped=], public key-based
-credentials by web applications, for the purpose of strongly authenticating users. A [=public key credential=] is
+credentials by [=web applications=], for the purpose of strongly authenticating users. A [=public key credential=] is
 created and stored by an <em>[=authenticator=]</em> at the behest of a <em>[=[WRP]=]</em>, subject to <em>[=user
 consent=]</em>. Subsequently, the [=public key credential=] can only be accessed by [=origins=] belonging to that [=[RP]=].
 This scoping is enforced jointly by <em>[=conforming User Agents=]</em> and <em>[=authenticators=]</em>.
@@ -261,6 +268,55 @@ for [=user verification=], along with appropriate driver software to mediate acc
 authenticators MAY operate autonomously from the [=client device=] running the user agent, and be accessed over a transport such
 as Universal Serial Bus (USB), Bluetooth Low Energy (BLE) or Near Field Communications (NFC).
 
+## Specification Roadmap ## {#spec-roadmap}
+
+While many W3C specifications are directed primarily to user agent developers and also to web application developers
+(i.e., "Web authors"), the nature of Web Authentication requires that this specification be correctly used by multiple audiences,
+as described below.
+All audiences ought to begin with [[#use-cases]], [[#sample-scenarios]], and [[#terminology]], and should also
+refer to [[WebAuthnAPIGuide]] for an overall tutorial.
+<br><br>
+- [=[RP]=] web application developers, expecially those responsible for [=[RP]=] [=web application=] login flows, account recovery flows,
+    user account database content, etc.
+- Web framework developers
+
+    - The above two audiences should in particular refer to [[#rp-operations]].
+        The introduction to [[#api]] may be helpful, though readers should realize that the [[#api]] section is targeted specifically
+        at user agent developers, not web application defelopers.
+        Additionally, if they intend to verify [=authenticator=] [=attestations=], then
+        [[#sctn-attestation]] and [[#defined-attestation-formats]] will also be relevant.
+        [[#extensions]], and [[#sctn-defined-extensions]] will be of interest if they wish to make use of extensions.
+        <br><br>
+
+- User agent developers
+- OS platform developers, responsible for OS platform API design and implementation in regards to platform-specific
+    [=authenticator=] APIs, platform [=WebAuthn Client=] instantiation, etc.
+
+    - The above two audiences should read [[#api]] very carefully, along with [[#extensions]] if they intend to support extensions.
+        <br><br>
+
+- [=Authenticator=] developers. These readers will want to pay particular attention to [[#sctn-authenticator-model]],
+    [[#defined-attestation-formats]], [[#extensions]], and [[#sctn-defined-extensions]].
+    <br><br>
+
+<div class="note">
+    Note: Along with the [[#api|Web Authentication API]] itself, this specification defines a 
+    request-response <em>cryptographic protocol</em>
+    between a [=[WRP]=] server and an [=authenticator=], where the [=[RP]=]'s request consists of a
+    [[#cryptographic-challenges|challenge]] and other
+    input data supplied by the [=[RP]=] and sent to the [=authenticator=].
+    The request is conveyed via the
+    combination of HTTPS, the [=[RP]=] [=web application=], the [[#api|WebAuthn API]], and the platform-specific communications channel
+    between the user agent and the [=authenticator=].
+    The [=authenticator=] replies with a digitally signed [=authenticator data=] message and other output data, which is conveyed back to the
+    [=[RP]=] server via the same path in reverse. Protocol details vary according to whether an [=authentication=] or
+    [=registration=] operation is invoked by the [=[RP]=].
+    See also [Figure 1](#fig-registration) and [Figure 2](#fig-authentication).
+
+    <strong>It is important for Web Authentication deployments' end-to-end security</strong> that the role of each
+    component&mdash;the [=[RP]=] server, the [=client=], and the [=authenticator=]&mdash;
+    as well as [[#security-considerations]] and [[#sctn-privacy-considerations]], are understood <em>by all audiences</em>.
+</div>
 
 ## Use Cases ## {#use-cases}
 
@@ -717,12 +773,13 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
     up a [=client platform=].
 
 : <dfn>[WRP]</dfn>
-:: The entity whose web application utilizes the [=Web Authentication API=] to register and authenticate users. See
-    [=Registration=] and [=Authentication=], respectively.
+:: The entity whose <dfn>web application</dfn> utilizes the [[#api|Web Authentication API]] to [=registration|register=] and
+    [=authentication|authenticate=] users.
 
-        Note: While the term [=[RP]=] is used in other contexts (e.g., X.509 and OAuth), an entity acting as a [=[RP]=] in one
+        Note: While the term [=[RP]=] is also often used in other contexts (e.g., X.509 and OAuth), an entity acting as a [=[RP]=] in one
         context is not necessarily a [=[RP]=] in other contexts. In this specification, the term [=[WRP]=] is often shortened 
-        to be just [=[RP]=].
+        to be just [=[RP]=], and explicitly refers to a [=[RP]=] in the WebAuthn context. Note that in any concrete instantiation
+        a WebAuthn context may be embedded in a broader overall context, e.g., one based on OAuth.
 
 
 # <dfn>Web Authentication API</dfn> # {#api}
@@ -5143,11 +5200,11 @@ handled on the server side and do not need support from the API specified here.
 
 # Security Considerations # {#security-considerations}
 
-This specification defines a Web API and a cryptographic peer-entity authentication protocol.
+This specification defines a [[#api|Web API]] and a cryptographic peer-entity authentication protocol.
 The [=Web Authentication API=] allows Web developers (i.e., "authors") to utilize the Web Authentication protocol in their
 [=registration=] and [=authentication=] [=ceremonies=].
 The entities comprising the Web Authentication protocol endpoints are user-controlled [=authenticators=] and a [=[WRP]=]'s
-computing environment hosting the [=[RP]=]'s web application.
+computing environment hosting the [=[RP]=]'s [=web application=].
 In this model, the user agent, together with the [=[WAC]=], comprise an intermediary between [=authenticators=] and [=[RPS]=].
 Additionally, [=authenticators=] can [=attestation|attest=] to [=[RPS]=] as to their provenance.