Added 'discoverable' attribute (see #34)

README.md

@@ -360,8 +360,8 @@ Unlike the [WebAuthn protocol](https://w3c.github.io/webauthn/), some defaults a
 - The `username` is used for both the protocol level user "name" and "displayName"
 
 
-Options
--------
+Common options
+--------------
 
 The following options are available for both `register` and `authenticate`.
 
@@ -372,10 +372,21 @@ The following options are available for both `register` and `authenticate`.
     - `'local'`: use the local device (using TouchID, FaceID, Windows Hello or PIN)
     - `'roaming'`: use a roaming device (security key or connected phone)
     - `'both'`: prompt the user to choose between local or roaming device. The UI and user interaction in this case is platform specific.
-- `attestation`: (Only for registration) If enabled, the device attestation and clientData will be provided as base64 encoded binary data. Note that this is not available on some platforms. *(Default: false)*
 - `debug`: If enabled, parses the "data" objects and provide it in a "debug" properties.
-- `userHandle`: (Only for registration) The `userHandle` can be used to re-register credentials for an existing user, thus overriding the current the key pair and username for that `userHandle`. *The default here is based on a hash of the `username`, and thus has some security implications as described in [issue](https://github.com/passwordless-id/webauthn/issues/29). For optimal security and privacy, it is recommended to set the `userHandle` to a random 64 bytes value.*
-- `mediation`: (Only for authentication) See https://developer.mozilla.org/en-US/docs/Web/API/CredentialsContainer/get#mediation
+
+
+Registration options
+--------------------
+
+- `discoverable`: (`'discouraged'`, `'preferred'` or `'required'`) If the credential is "discoverable", it can be selected using `authenticate` without providing credential IDs. In that case, a native pop-up will appear for user selection. This may have an impact on the "passkeys" user experience and syncing behavior of the key. *(Default: 'preferred')*
+- `attestation`: If enabled, the device attestation and clientData will be provided as base64 encoded binary data. Note that this is not available on some platforms. *(Default: false)*
+- `userHandle`: The `userHandle` can be used to re-register credentials for an existing user, thus overriding the current the key pair and username for that `userHandle`. *The default here is based on a hash of the `username`, and thus has some security implications as described in [issue](https://github.com/passwordless-id/webauthn/issues/29). For optimal security and privacy, it is recommended to set the `userHandle` to a random 64 bytes value.*
+
+
+Authentication options
+----------------------
+
+- `mediation`: See https://developer.mozilla.org/en-US/docs/Web/API/CredentialsContainer/get#mediation
 
 
 Parsing data

demos/js/playground.js

@@ -10,6 +10,7 @@ import {client, server, parsers, utils} from '../../dist/webauthn.min.js'
             options: {
                 authenticatorType: 'auto',
                 userVerification: 'required',
+                discoverable: 'preferred',
                 timeout: 60000,
                 attestation: false,
             },

demos/playground.html

@@ -53,11 +53,6 @@ <h2 class="title">Registration</h2>
             <div class="hint">Which device to use as authenticator.</div>
         </b-field>
 
-        <b-field label="Timeout" horizontal>
-            <b-input v-model="registration.options.timeout" placeholder="60000" expanded></b-input>
-            <div class="hint">Number of milliseconds the user has to respond to the biometric/PIN check.</div>
-        </b-field>
-
         <b-field label="userVerification" horizontal>
             <b-select v-model="registration.options.userVerification" expanded>
                 <option>required</option>
@@ -66,6 +61,20 @@ <h2 class="title">Registration</h2>
             </b-select>
             <div class="hint">Whether a biometric/PIN check is required or not. This filters out security keys not having this capability.</div>
         </b-field>
+
+        <b-field label="discoverable" horizontal>
+            <b-select v-model="registration.options.discoverable" expanded>
+                <option>required</option>
+                <option>preferred</option>
+                <option>discouraged</option>
+            </b-select>
+            <div class="hint">A "discoverable" credential can be selected using `authenticate` without providing credential IDs. Instead, a native pop-up will appear for user selection. This may have an impact on the "passkeys" user experience and syncing behavior of the key.</div>
+        </b-field>
+
+        <b-field label="Timeout" horizontal>
+            <b-input v-model="registration.options.timeout" placeholder="60000" expanded></b-input>
+            <div class="hint">Number of milliseconds the user has to respond to the biometric/PIN check.</div>
+        </b-field>
 
         <b-field label="debug" horizontal>
             <b-checkbox v-model="registration.options.debug" expanded></b-checkbox>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passwordless-id/webauthn",
-  "version": "1.2.6",
+  "version": "1.3.0",
   "description": "A small wrapper around the webauthn protocol to make one's life easier.",
   "type": "module",
   "main": "dist/esm/index.js",

src/client.ts

@@ -65,8 +65,10 @@ function getAlgoName(num :NumAlgo) :NamedAlgo {
  *          'local': use the local device (using TouchID, FaceID, Windows Hello or PIN)
  *          'roaming': use a roaming device (security key or connected phone)
  *          'both': prompt the user to choose between local or roaming device. The UI and user interaction in this case is platform specific.
- * @param {boolean} [attestation=false] If enabled, the device attestation and clientData will be provided as Base64url encoded binary data.
+ * @param {boolean} [options.attestation=false] If enabled, the device attestation and clientData will be provided as Base64url encoded binary data.
  *                                Note that this is not available on some platforms.
+ * @param {'discouraged'|'preferred'|'required'} [options.discoverable] If the credential is "discoverable", it can be selected using `authenticate` without providing credential IDs.
+ *                                A native pop-up will appear for user selection. This may have an impact on "passkeys" user experience and syncing behavior.
  */
 export async function register(username :string, challenge :string, options? :RegisterOptions) :Promise<RegistrationEncoded> {
     options = options ?? {}
@@ -93,8 +95,10 @@ export async function register(username :string, challenge :string, options? :Re
         authenticatorSelection: {
             userVerification: options.userVerification ?? "required", // Webauthn default is "preferred"
             authenticatorAttachment: await getAuthAttachment(options.authenticatorType ?? "auto"),
+            residentKey: options.discoverable ?? 'preferred', // official default is 'discouraged'
+            requireResidentKey: (options.discoverable === 'required') // mainly for backwards compatibility, see https://www.w3.org/TR/webauthn/#dictionary-authenticatorSelection
         },
-        attestation: "direct" // options.attestation ? "direct" : "none"
+        attestation: options.attestation ? "direct" : "none"
     }
 
     if(options.debug)

src/types.ts

@@ -40,6 +40,7 @@ export interface AuthenticationParsed {
 export interface RegisterOptions extends CommonOptions {
   userHandle?: string
   attestation?: boolean
+  discoverable?: ResidentKeyRequirement
 }