Various suggested edits

proposal.md

@@ -3,13 +3,13 @@ layout: post
 title: WebID
 ---
 
-**TL;DR**; This is a **strawman proposal** for a new Web API that allows websites to use single sign-on federation with tighter privacy properties, namely making [third party tracking](README.md#rp-tracking-and-joinability) and [identity provider tracking](README.md#idp-tracking-and-opaque-data-exchange) substantially harder.
+**TL;DR**; This is a **strawman proposal** for a new Web API that allows websites to use federated identity services with tighter privacy properties, namely making [third party tracking](README.md#rp-tracking-and-joinability) and [identity provider tracking](README.md#idp-tracking-and-opaque-data-exchange) substantially harder.
 
-It is composed of (a) a [baseline proposal](#the-baseline-proposal) that starts with a **high level API** that permits browser intermediation of existing federated sign-in flows on the web in a [backwards compatible](#considerations) manner where it matters most and (b) a series of privacy enhancements are suggested as [next steps](#next-steps), some requiring longer deployment windows (i.e. to be discussed separately).
+It is composed of (a) a [baseline proposal](#the-baseline-proposal) that starts with a **high-level API** that permits browser intermediation of existing federated sign-in flows on the web in a [backwards compatible](#considerations) manner where it matters most and (b) a series of privacy enhancements are suggested as [next steps](#next-steps), some requiring longer deployment windows (i.e. to be discussed separately).
 
 # Why?
 
-Over the last decade, identity federation has unquestionably played a central role in raising the bar for authentication on the web, in terms of ease-of-use (e.g. passwordless single sign on), security (e.g. improved resistance to phishing and credential stuffing attacks) and trustworthiness compared to its preceding common pattern: per-site usernames and passwords.
+Over the last decade, identity federation has unquestionably played a central role in raising the bar for authentication on the web, in terms of ease-of-use (e.g. passwordless single sign-on), security (e.g. improved resistance to phishing and credential stuffing attacks) and trustworthiness compared to its preceding common pattern: per-site usernames and passwords.
 
 The standards that define how identity federation works today were built independently of the web platform, and their designers had to work **around** its limitations rather than extending them. Because of that, existing user authentication flows rely on general web capabilities such as top-level navigation, link decoration, window popups and cookies.
 
@@ -55,20 +55,20 @@ The postmortem analysis [here](https://wiki.mozilla.org/Identity/Persona_AAR) is
 
 This strawman proposal is broken down into two parts: a baseline proposal and a series of privacy enhancing extensions.
 
-The baseline proposal addresses the **classification problem**: turn some of the otherwise opaque data exchange that uses low level primitives (i.e. identity agnostic, e.g. redirects) into an exchange that is transparent to browsers with high level primitives (e.g. identity specific). The extensions build from that baseline tightening up the privacy properties of the data exchange.
+The baseline proposal addresses the **classification problem**: turn some of the otherwise opaque data exchange that uses low-level primitives (i.e. identity agnostic, e.g. redirects) into an exchange that is transparent to browsers with high-level primitives (e.g. identity specific). The extensions build from that baseline tightening up the privacy properties of the data exchange.
 
 ## The Baseline Proposal
 
-The goal of the baseline proposal is to provide a **high level**, identity specific API that allows browsers to **classify** the otherwise **opaque** transactions that are enabled by low level, general purpose APIs (e.g. redirects).
+The goal of the baseline proposal is to provide a **high-level**, identity-specific API that allows browsers to **classify** the otherwise **opaque** transactions that are enabled by low-level, general-purpose APIs (e.g. redirects).
 
-By classifying as an identity data exchange, browsers can (a) provide high level guidance to users regarding the consequences of the specific identity transaction and/or (b) demote / disencourage / prevent the opaque data exchange (e.g. opaque link decoration). 
-Currently, RP sign-in flows usually begin with a login screen that provides the user options to use federated identity, as illustrated in the mock below. Today, clicking the button for an IDP usually initiates a top level navigation to a designated IDP sign-in page. 
+By classifying as an identity data exchange, browsers can (a) provide high-level guidance to users regarding the consequences of the specific identity transaction and/or (b) demote / discourage / prevent the opaque data exchange (e.g. opaque link decoration). 
+Currently, RP sign-in flows usually begin with a login screen that provides the user options to use federated identity, as illustrated in the mock below. Today, clicking the button for an IDP usually initiates a top-level navigation to a designated IDP sign-in page. 
 
 ![](mock1.svg)
 
 ### WebSite Sign-In Flow
 
-In this formulation, the redirect flow gets replaced by the invocation of a new **high level** identity specific API that enables RPs to request IdTokens. While largely to be determined, a good source of inspiration and analogy can be drawn from the PaymentsRequest API (it has similar UX flows, number of players and privacy requirements):
+In this formulation, the redirect flow gets replaced by the invocation of a new **high-level** identity-specific API that enables RPs to request IdTokens. While largely to be determined, a good source of inspiration and analogy can be drawn from the PaymentsRequest API (it has similar UX flows, number of players and privacy requirements):
 
 ```javascript
 // This is just a possible starting point, largely TBD.
@@ -84,11 +84,11 @@ Here is a declarative formulation that could potentially work too:
 <input type=”idtoken” provider=”https://accounts.example.com”>
 ```
 
-In current flows this is done on the IDP’s page following a top-level navigation, but we suggest that it could be better placed in a popup window or a tab-modal dialog resembling what is used for PaymentHandler [windows](https://www.w3.org/TR/payment-handler/#windows) or the proposed [modal-window](https://github.com/adrianhopebailie/modal-window/blob/master/explainer.md), for example combining the account selection / authentication step with the consent step, with a bottom sheet that combines IDP-supplied and browser-supplied UI to accomplish both tasks.
+In current flows this is done on the IDP’s page following a top-level navigation, but we suggest that it could be better placed in a popup window or a tab-modal dialog resembling what is used for PaymentHandler [windows](https://www.w3.org/TR/payment-handler/#windows) or the proposed [modal-window](https://github.com/adrianhopebailie/modal-window/blob/master/explainer.md), for performing the Identity Provisioning Flow step that follows. The mock below shows an example of a bottom sheet that combines IDP-supplied and browser-supplied UI.
 
 ![](mock2.svg)
 
-In this step, the browser intercepts the invocation and knows which IDP to load. The details of this step are left to the discretion of the user agent, which must decide the amount of information to provide that would sufficiently make them aware of the exchange, and also may take into account available contextual information. For example, if the user has previously signed in to the current RP with the same account, then it might be reasonable to streamline this step and presume that consent previously given still applies.
+The details of this step are left to the discretion of the user agent, which must decide the amount of information to provide to the user that would make them sufficiently aware of the exchange, and also may take into account available contextual information. For example, if the user has previously signed in to the current RP with the same account, then it might be reasonable to streamline this step and presume that consent previously given still applies.
 
 ### Identity Provisioning Flow
 
@@ -102,7 +102,7 @@ new IdentityResponse().resolve(idToken};
 
 The IdToken is largely opaque to the browser in this baseline proposal, so the browser needs to gather the user consent assuming that global identifiers are being exchanged. Inspecting the data exchange and enforcing the absence of global identifiers are left as next step from this baseline. 
 
-Finally, In possession of the IdToken and with the confidence of consent having been obtained to the user agent’s satisfaction, a data exchange can occur in accordance with OpenID Connect or SAML standards. The user agent conveys the RP’s identity request to the IDP, and an ID token is returned that is provided to the RP in order to fulfill the Promise initiated at the beginning.
+Finally, in possession of the IdToken and with confidence of the user having consented to share it, the user agent can return the ID token to the RP in order to complete the identity transaction.
 
 # Next Steps
 
@@ -125,11 +125,11 @@ Much of this is still largely to be determined and we believe it can only be loo
 
 ### IDP Tracking
 
-The [baseline proposal](#the-baseline-proposal) isn’t changing the amount of information (nor its timing) exchanged between RPs and IDPs, especially non consensually. What it does though, is to position the user agent in a place where it intermediates interaction between RPs and IDPs, enabling it to tighten up the privacy properties of the data exchange. For example:
+The [baseline proposal](#the-baseline-proposal) isn’t changing the amount of information (nor its timing) exchanged between RPs and IDPs, especially non-consensually. What it does though, is to position the user agent in a place where it intermediates interaction between RPs and IDPs, enabling it to tighten up the privacy properties of the data exchange. For example:
 
 - the user agent could choose to prompt the user for permission early on
 - the user agent could choose to delay revealing the origin of the RP to the IDP upon user consent. In this formulation, the user agent could load the IDP without telling it which RP is requesting it and only let that information be passed upon further stages of the transaction when the user understands better what’s involved.
-- the user agent could step up and mint IdTokens itself on behalf of the user, using the (cryptographically signed) identity from the IDP. In this formulation, the RP could still use information from the IDP, but without the IDP ever knowing who the RP is, along the lines of the infrastructure built by BrowseID.
+- the user agent could step up and mint IdTokens itself on behalf of the user, using the (cryptographically signed) identity from the IDP. In this formulation, the RP could still use information from the IDP, but without the IDP ever knowing who the RP is, along the lines of the infrastructure built by BrowserID.
 
 ## Friction Extensions