Add isPlatformAuthenticatorReady function to the API surface

index.bs

@@ -72,9 +72,11 @@ spec: WebCryptoAPI; urlPrefix: https://www.w3.org/TR/WebCryptoAPI/
         text: AlgorithmIdentifier; url: dfn-AlgorithmIdentifier
 
 <!-- Remove these once Shepherd picks up the changes -->
-spec: CREDENTIAL-MANAGEMENT-1; urlPrefix: https://w3c.github.io/webappsec-credential-management/
+spec: credential-management-1; urlPrefix: https://w3c.github.io/webappsec-credential-management/
     type: dictionary
         text: CredentialCreationOptions; url: dictdef-credentialcreationoptions
+    type: dictionary
+        text: CredentialRequestOptions; url: dictdef-credentialrequestoptions
     for: Credential
         type: method
             text: [[Create]](options)
@@ -88,7 +90,7 @@ spec:html; type:dfn; for:environment settings object; text:global object
 spec:infra; type:dfn; text:list
 spec:url; type:dfn; text:domain
 spec:url; type:dfn; text:valid domain;
-spec:webappsec-credential-management-1; type:dictionary; for:/; text:CredentialRequestOptions
+<!-- spec:webappsec-credential-management-1; type:dictionary; for:/; text:CredentialRequestOptions -->
 spec:webidl; type:interface; text:Promise
 </pre>
 
@@ -920,9 +922,9 @@ When this method is invoked, the user agent MUST execute the following algorithm
                 entries created by running each extension's [=client extension processing=] algorithm to create the [=client
                 extension outputs=], for each [=client extension=] in {{AuthenticatorResponse/clientDataJSON}}.clientExtensions.
 
-        3. [=set/For each=] remaining |authenticator| in |issuedRequests| invoke the [=authenticatorCancel=] operation on
+        3.  [=set/For each=] remaining |authenticator| in |issuedRequests| invoke the [=authenticatorCancel=] operation on
             |authenticator| and [=set/remove=] it from |issuedRequests|.
-        4. Return |value| and terminate this algorithm.
+        4.  Return |value| and terminate this algorithm.
     </dd>
     </dl>
 
@@ -933,6 +935,35 @@ authorizing an authenticator with which to complete the operation.
 </div>
 
 
+### Platform Authenticator Availability - PublicKeyCredential's `isPlatformAuthenticatorAvailable()` method ### {#isPlatformAuthenticatorAvailable}
+
+<div link-for-hint="WebAuthentication/isPlatformAuthenticatorAvailable">
+
+[=[RPS]=] use this method to determine whether they can create a new credential using a [=platform authenticator=].
+Upon invocation, the [=client=] employs a platform-specific procedure to discover available [=platform authenticators=].
+If successful, the [=client=] then assesses whether the user is willing to create a credential using one of the available [=platform authenticators=].
+This assessment may include various factors, such as:
+    - Whether the user is running in private or incognito mode.
+    - Whether the user has configured the [=client=] to not create such credentials.
+    - Whether the user has previously expressed an unwillingness to create a new credential for this [=[RP]=],
+        either through configuration or by declining a user interface prompt.
+    - The user's explicitly stated intentions, determined through user interaction.
+If this assessment is affirmative, the promise is resolved with the value of <i>True</i>.
+Otherwise, the promise is resolved with the value of <i>False</i>.
+Based on the result, the [=[RP]=] can take further actions to guide the user to create a credential.
+
+This method has no arguments and returns a boolean value.
+
+<pre class="idl">
+    [SecureContext]
+    partial interface PublicKeyCredential {
+        [Unscopable] Promise < boolean > isPlatformAuthenticatorAvailable();
+    };
+</pre>
+
+</div>
+
+
 ## Authenticator Responses (interface <dfn interface>AuthenticatorResponse</dfn>) ## {#iface-authenticatorresponse}
 
 [=Authenticators=] respond to [=[RP]=] requests by returning an object derived from the
@@ -1822,7 +1853,7 @@ WebAuthn supports multiple attestation types:
     [[#sec-attestation-privacy]] for futher information.
 
 : <dfn>Self Attestation</dfn>
-:: In the case of [=self attestation=], also known as surrogate basic attestation [[UAFProtocol]], the Authenticator doesn't have
+:: In the case of [=self attestation=], also known as surrogate basic attestation [[UAFProtocol]], the Authenticator does not have
     any specific attestation key. Instead it uses the authentication key itself to create the attestation signature.
     Authenticators without meaningful protection measures for an attestation private key typically use this attestation type.
 
@@ -1905,7 +1936,7 @@ in several ways, including:
 
 - A WebAuthn Authenticator can implement [=Elliptic Curve based direct anonymous attestation=] (see [[FIDOEcdaaAlgorithm]]).
     Using this scheme, the authenticator generates a blinded attestation signature. This allows the [=[RP]=] to verify the
-    signature using the [=ECDAA-Issuer public key=], but the attestation signature doesn't serve as a global correlation handle.
+    signature using the [=ECDAA-Issuer public key=], but the attestation signature does not serve as a global correlation handle.
 
 
 #### Attestation Certificate and Attestation Certificate CA Compromise #### {#ca-compromise}
@@ -3219,9 +3250,11 @@ platform to enumerate all the authenticator's credentials so that the client can
 ## Registration ## {#sample-registration}
 
 This is the first-time flow, in which a new credential is created and registered with the server.
+In this flow, the [=[RP]=] does not have a preference for [=platform authenticator=] or [=roaming authenticators=].
 
-1. The user visits example.com, which serves up a script. At this point, the user must already be logged in using a legacy
+1. The user visits example.com, which serves up a script. At this point, the user may already be logged in using a legacy
     username and password, or additional authenticator, or other means acceptable to the [=[RP]=].
+    Or the user may be in the process of creating a new account.
 
 2. The [=[RP]=] script runs the code snippet below.
 
@@ -3292,6 +3325,43 @@ The sample code for generating and registering a new key follows:
       });
 </pre>
 
+## Registration Specifically with Platform Authenticator ## {#sample-registration-with-platform-authenticator}
+
+This is flow for when the [=[RP]=] is specifically interested in creating a public key credential with
+a [=platform authenticator=].
+
+1. The user visits example.com. At this point, the user is likely already logged in.
+
+1. The [=[RP]=] script runs the code snippet below.
+
+1. The user agent asks the user whether they are willing to register with the [=[RP]=] using an available [=platform authenticator=].
+
+1. If the user is not willing, terminate this flow.
+
+1. The user is shown appropriate UI and guided in creating a credential using one of the available platform authenticators.
+    Upon successful credential creation, the RP script conveys the new credential to the server.
+
+<pre class="example" highlight="js">
+    if (!PublicKeyCredential) { /* Platform not capable of the API. Handle error. */ }
+
+    navigator.credentials.isPlatformAuthenticatorAvailable()
+        .then(function (userIntent) {
+
+            // If the user has affirmed willingness to register with RP using an available platform authenticator
+            if (userIntent) {
+                var publicKeyOptions = { /* Public key credential creation options. */};
+
+                // Create and register credentials.
+                return navigator.credentials.create({ "publicKey": publicKeyOptions });
+            }
+
+            // If user is not interested, don't ask the user to register.
+        }).then(function (newCredentialInfo) {
+            // Send new credential info to server for verification and registration.
+        }).catch( function(err) {
+            // Something went wrong. Handle appropriately.
+        });
+</pre>
 
 ## Authentication ## {#sample-authentication}