Merge pull request w3c#1951 from pascoej/conditionalcreate

Initial text for conditional create

index.bs

@@ -36,6 +36,7 @@ Former Editor: Rolf Lindemann, w3cid 84447, Nok Nok Labs, rolf@noknok.com
 !Contributors: <a href="mailto:cbrand@google.com">Christiaan Brand</a> (Google)
 !Contributors: <a href="mailto:agl@google.com">Adam Langley</a> (Google)
 !Contributors: <a href="mailto:mandyam@qti.qualcomm.com">Giridhar Mandyam</a> (Qualcomm)
+!Contributors: <a href="mailto:pascoe@apple.com">Pascoe</a> (Apple)
 !Contributors: <a href="mailto:nsatragno@google.com">Nina Satragno</a> (Google)
 !Contributors: <a href="mailto:kieun.shin@sk.com">Ki-Eun Shin</a> (SK Telecom)
 !Contributors: <a href="mailto:nick.steele@agilebits.com">Nick Steele</a> (1Password)
@@ -1579,15 +1580,16 @@ that are returned to the caller when a new credential is created, or a new asser
 
     :   {{PublicKeyCredential/isConditionalMediationAvailable()}}
     ::  {{PublicKeyCredential}} overrides this method to indicate availability for {{CredentialMediationRequirement/conditional}}
-        mediation. [=[WRPS]=] SHOULD verify availability before attempting to set
-        <code>|options|.{{CredentialRequestOptions/mediation}}</code> to {{CredentialMediationRequirement/conditional}}.
+        mediation during {{CredentialsContainer/get()|navigator.credentials.get()}}. [=[WRPS]=] SHOULD verify availability before
+        attempting to set <code>|options|.{{CredentialRequestOptions/mediation}}</code> to {{CredentialMediationRequirement/conditional}}.
 
         Upon invocation, a promise is returned that resolves with a value of [TRUE] if {{CredentialMediationRequirement/conditional}}
         [=user mediation=] is available, or [FALSE] otherwise.
 
         This method has no arguments and returns a promise to a Boolean value.
 
-        Note: If this method is not present, {{CredentialMediationRequirement/conditional}} [=user mediation=] is not available.
+        Note: If this method is not present, {{CredentialMediationRequirement/conditional}} [=user mediation=] is not available for
+        {{CredentialsContainer/get()|navigator.credentials.get()}}.
 
     :   {{PublicKeyCredential/toJSON()}}
     ::  This operation returns {{RegistrationResponseJSON}} or {{AuthenticationResponseJSON}},
@@ -1733,8 +1735,16 @@ To support obtaining assertions via {{CredentialsContainer/get()|navigator.crede
 {{PublicKeyCredential}}'s [=interface object=]'s implementation of the <dfn for="PublicKeyCredential" method>\[[Create]](origin,
 options, sameOriginWithAncestors)</dfn> [=internal method=] [[!CREDENTIAL-MANAGEMENT-1]] allows
 [=[WRP]=] scripts to call {{CredentialsContainer/create()|navigator.credentials.create()}} to request the creation of a new
-[=public key credential source=], [=bound credential|bound=] to an [=authenticator=]. This
-{{CredentialsContainer/create()|navigator.credentials.create()}} operation can be aborted by leveraging the {{AbortController}};
+[=public key credential source=], [=bound credential|bound=] to an [=authenticator=].
+
+By setting <code>|options|.{{CredentialCreationOptions/mediation}}</code> to {{CredentialMediationRequirement/conditional}},
+[=[RPS]=] can indicate that they would like to register a credential without prominent modal UI if user has already consented to create a credential. The [=[RP]=] SHOULD first check that {{ClientCapability/conditionalCreate}} is present
+in the result of {{PublicKeyCredential/getClientCapabilities()}} in order to avoid the possibility of causing a user-visible error to be returned if the user agent does
+not support {{CredentialMediationRequirement/conditional}} [=user mediation=] for {{CredentialsContainer/create()|navigator.credentials.create()}}.
+The client MUST set BOTH |requireUserPresence| and |requireUserVerification| to |FALSE| when <code>|options|.{{CredentialCreationOptions/mediation}}</code> is set to {{CredentialMediationRequirement/conditional}}
+unless they may explicitly performed during the ceremony.
+
+Any {{CredentialsContainer/create()|navigator.credentials.create()}} operation can be aborted by leveraging the {{AbortController}};
 see [[dom#abortcontroller-api-integration]] for detailed instructions.
 
 
@@ -1773,6 +1783,11 @@ When this method is invoked, the user agent MUST execute the following algorithm
 
 1. If <var ignore>sameOriginWithAncestors</var> is [FALSE]:
 
+    1. If <code>|options|.{{CredentialCreationOptions/mediation}}</code> is present with the value
+        {{CredentialMediationRequirement/conditional}}:
+
+        1. Throw a "{{NotAllowedError}}" {{DOMException}}
+
     1. If the [=relevant global object=], as determined by the calling
         {{CredentialsContainer/create()}} implementation, does not have
         [=transient activation=]:
@@ -1909,6 +1924,16 @@ a numbered step. If outdented, it (today) is rendered as a bullet in the midst o
     [=authenticators=] can be <a href="https://en.wikipedia.org/w/index.php?title=Hot_plug">hot-plugged</a> into (e.g., via USB)
     or discovered (e.g., via NFC or Bluetooth) by the [=client=] by various mechanisms, or permanently built into the [=client=].
 
+1. If <code>|options|.{{CredentialCreationOptions/mediation}}</code> is present with the value
+     {{CredentialMediationRequirement/conditional}}:
+
+    1. If the user agent has not recently mediated an authentication, the origin of said authentication is not |callerOrigin|, or the user
+        does not consent to this type of credential creation, throw a "{{NotAllowedError}}" {{DOMException}}.
+
+        It is up to the user agent to decide when it believes an authentication ceremony has
+        been completed. That authentication ceremony MAY be performed via other means than the
+        [=Web Authentication API=].
+
 1. Consider the value of {{PublicKeyCredentialCreationOptions/hints}} and craft the user interface accordingly, as the user-agent sees fit.
 
 1. Start |lifetimeTimer|.
@@ -1997,7 +2022,10 @@ a numbered step. If outdented, it (today) is rendered as a bullet in the midst o
                         <dl class="switch">
 
                             :   is set to {{UserVerificationRequirement/required}}
-                            ::  Let |userVerification| be [TRUE].
+                            ::  1. If <code>|options|.{{CredentialCreationOptions/mediation}}</code> is set to {{CredentialMediationRequirement/conditional}}
+                                    and [=user verification=] cannot be collected during the ceremony,
+                                    throw a {{ConstraintError}} {{DOMException}}.
+                                1. Let |userVerification| be [TRUE].
 
                             :   is set to {{UserVerificationRequirement/preferred}}
                             ::  If the |authenticator|
@@ -2196,7 +2224,7 @@ a numbered step. If outdented, it (today) is rendered as a bullet in the midst o
     [[#sctn-make-credential-privacy]] for details.
 
 During the above process, the user agent SHOULD show some UI to the user to guide them in the process of selecting and
-authorizing an authenticator.
+authorizing an authenticator. When <code>|options|.{{CredentialCreationOptions/mediation}}</code> is set to {{CredentialMediationRequirement/conditional}}, prominent modal UI should <i>not</i> be shown <i>unless</i> credential creation was previously consented to via means determined by the user agent.
 </div>
 
 
@@ -4616,9 +4644,7 @@ It takes the following input parameters:
 : |requireResidentKey|
 :: The [=effective resident key requirement for credential creation=], a Boolean value determined by the [=client=].
 : |requireUserPresence|
-:: The constant Boolean value [TRUE].
-    It is included here as a pseudo-parameter to simplify applying this abstract authenticator model to implementations that may
-    wish to make a [=test of user presence=] optional although WebAuthn does not.
+:: The constant Boolean value [TRUE], or |FALSE| when <code>|options|.{{CredentialCreationOptions/mediation}}</code> is set to {{CredentialMediationRequirement/conditional}} and the user agent previously collected consent from the user.
 : |requireUserVerification|
 :: The [=effective user verification requirement for credential creation=], a Boolean value determined by the [=client=].
 : |credTypesAndPubKeyAlgs|
@@ -5373,7 +5399,7 @@ a numbered step. If outdented, it (today) is rendered as a bullet in the midst o
 
 1. Verify that the <code>[=rpIdHash=]</code> in |authData| is the SHA-256 hash of the [=RP ID=] expected by the [=[RP]=].
 
-1. Verify that the [=UP=] bit of the <code>[=flags=]</code> in |authData| is set.
+1. Verify that the [=UP=] bit of the <code>[=flags=]</code> in |authData| is set, unless <code>|options|.{{CredentialCreationOptions/mediation}}</code> is set to {{CredentialMediationRequirement/conditional}}.
 
 1. If the [=[RP]=] requires [=user verification=] for this registration,
     verify that the [=authData/flags/UV=] bit of the <code>[=flags=]</code> in |authData| is set.