Add support for PublicKeyCredentialHint

webauthn-server-core/src/main/java/com/yubico/webauthn/RelyingParty.java

@@ -493,7 +493,8 @@ public PublicKeyCredentialCreationOptions startRegistration(
                             .appidExclude(appId)
                             .credProps()
                             .build()))
-            .timeout(startRegistrationOptions.getTimeout());
+            .timeout(startRegistrationOptions.getTimeout())
+            .hints(startRegistrationOptions.getHints());
     attestationConveyancePreference.ifPresent(builder::attestation);
     return builder.build();
   }
@@ -537,7 +538,8 @@ public AssertionRequest startAssertion(StartAssertionOptions startAssertionOptio
                 startAssertionOptions
                     .getExtensions()
                     .merge(startAssertionOptions.getExtensions().toBuilder().appid(appId).build()))
-            .timeout(startAssertionOptions.getTimeout());
+            .timeout(startAssertionOptions.getTimeout())
+            .hints(startAssertionOptions.getHints());
 
     startAssertionOptions.getUserVerification().ifPresent(pkcro::userVerification);
 

webauthn-server-core/src/main/java/com/yubico/webauthn/RelyingPartyV2.java

@@ -452,7 +452,8 @@ public PublicKeyCredentialCreationOptions startRegistration(
                             .appidExclude(appId)
                             .credProps()
                             .build()))
-            .timeout(startRegistrationOptions.getTimeout());
+            .timeout(startRegistrationOptions.getTimeout())
+            .hints(startRegistrationOptions.getHints());
     attestationConveyancePreference.ifPresent(builder::attestation);
     return builder.build();
   }
@@ -509,7 +510,8 @@ public AssertionRequest startAssertion(StartAssertionOptions startAssertionOptio
                 startAssertionOptions
                     .getExtensions()
                     .merge(startAssertionOptions.getExtensions().toBuilder().appid(appId).build()))
-            .timeout(startAssertionOptions.getTimeout());
+            .timeout(startAssertionOptions.getTimeout())
+            .hints(startAssertionOptions.getHints());
 
     startAssertionOptions.getUserVerification().ifPresent(pkcro::userVerification);
 

webauthn-server-core/src/main/java/com/yubico/webauthn/StartAssertionOptions.java

@@ -26,8 +26,13 @@
 
 import com.yubico.webauthn.data.AssertionExtensionInputs;
 import com.yubico.webauthn.data.ByteArray;
+import com.yubico.webauthn.data.PublicKeyCredentialDescriptor;
+import com.yubico.webauthn.data.PublicKeyCredentialHint;
 import com.yubico.webauthn.data.PublicKeyCredentialRequestOptions;
 import com.yubico.webauthn.data.UserVerificationRequirement;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
 import java.util.Optional;
 import lombok.Builder;
 import lombok.NonNull;
@@ -79,6 +84,55 @@ public class StartAssertionOptions {
    */
   private final Long timeout;
 
+  /**
+   * Zero or more hints, in descending order of preference, to guide the user agent in interacting
+   * with the user during this authentication operation.
+   *
+   * <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
+   * client to emphasize the option of authenticating with an external security key, or the {@link
+   * PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the
+   * option of authenticating a built-in passkey provider.
+   *
+   * <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
+   * providing the best experience by using contextual information about the request.
+   *
+   * <p>Hints MAY contradict information contained in {@link
+   * PublicKeyCredentialDescriptor#getTransports()}. When this occurs, the hints take precedence.
+   *
+   * <p>This library does not take these hints into account in any way, other than passing them
+   * through to the {@link PublicKeyCredentialRequestOptions} so they can be used in the argument to
+   * <code>navigator.credentials.get()</code> on the client side.
+   *
+   * <p>The default is empty.
+   *
+   * @see PublicKeyCredentialHint
+   * @see PublicKeyCredentialRequestOptions#getHints()
+   * @see StartAssertionOptionsBuilder#hints(List)
+   * @see StartAssertionOptionsBuilder#hints(String...)
+   * @see StartAssertionOptionsBuilder#hints(PublicKeyCredentialHint...)
+   * @see <a
+   *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialrequestoptions-hints">PublicKeyCredentialRequestOptions.hints</a>
+   * @see <a
+   *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
+   *     User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
+   */
+  private final List<String> hints;
+
+  private StartAssertionOptions(
+      String username,
+      ByteArray userHandle,
+      @NonNull AssertionExtensionInputs extensions,
+      UserVerificationRequirement userVerification,
+      Long timeout,
+      List<String> hints) {
+    this.username = username;
+    this.userHandle = userHandle;
+    this.extensions = extensions;
+    this.userVerification = userVerification;
+    this.timeout = timeout;
+    this.hints = hints == null ? Collections.emptyList() : Collections.unmodifiableList(hints);
+  }
+
   /**
    * The username of the user to authenticate, if the user has already been identified.
    *
@@ -370,5 +424,122 @@ public StartAssertionOptionsBuilder timeout(long timeout) {
     private StartAssertionOptionsBuilder timeout(Long timeout) {
       return this.timeout(Optional.ofNullable(timeout));
     }
+
+    /**
+     * Zero or more hints, in descending order of preference, to guide the user agent in interacting
+     * with the user during this authentication operation.
+     *
+     * <p>Setting this property multiple times overwrites any value set previously.
+     *
+     * <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
+     * client to emphasize the option of authenticating with an external security key, or the {@link
+     * PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the
+     * option of authenticating a built-in passkey provider.
+     *
+     * <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
+     * providing the best experience by using contextual information about the request.
+     *
+     * <p>Hints MAY contradict information contained in {@link
+     * PublicKeyCredentialDescriptor#getTransports()}. When this occurs, the hints take precedence.
+     *
+     * <p>This library does not take these hints into account in any way, other than passing them
+     * through to the {@link PublicKeyCredentialRequestOptions} so they can be used in the argument
+     * to <code>navigator.credentials.get()</code> on the client side.
+     *
+     * <p>The default is empty.
+     *
+     * @see PublicKeyCredentialHint
+     * @see PublicKeyCredentialRequestOptions#getHints()
+     * @see StartAssertionOptions#getHints()
+     * @see StartAssertionOptionsBuilder#hints(List)
+     * @see StartAssertionOptionsBuilder#hints(PublicKeyCredentialHint...)
+     * @see <a
+     *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialrequestoptions-hints">PublicKeyCredentialRequestOptions.hints</a>
+     * @see <a
+     *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
+     *     User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
+     */
+    public StartAssertionOptionsBuilder hints(@NonNull String... hints) {
+      this.hints = Arrays.asList(hints);
+      return this;
+    }
+
+    /**
+     * Zero or more hints, in descending order of preference, to guide the user agent in interacting
+     * with the user during this authentication operation.
+     *
+     * <p>Setting this property multiple times overwrites any value set previously.
+     *
+     * <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
+     * client to emphasize the option of authenticating with an external security key, or the {@link
+     * PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the
+     * option of authenticating a built-in passkey provider.
+     *
+     * <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
+     * providing the best experience by using contextual information about the request.
+     *
+     * <p>Hints MAY contradict information contained in {@link
+     * PublicKeyCredentialDescriptor#getTransports()}. When this occurs, the hints take precedence.
+     *
+     * <p>This library does not take these hints into account in any way, other than passing them
+     * through to the {@link PublicKeyCredentialRequestOptions} so they can be used in the argument
+     * to <code>navigator.credentials.get()</code> on the client side.
+     *
+     * <p>The default is empty.
+     *
+     * @see PublicKeyCredentialHint
+     * @see PublicKeyCredentialRequestOptions#getHints()
+     * @see StartAssertionOptions#getHints()
+     * @see StartAssertionOptionsBuilder#hints(List)
+     * @see StartAssertionOptionsBuilder#hints(String...)
+     * @see <a
+     *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialrequestoptions-hints">PublicKeyCredentialRequestOptions.hints</a>
+     * @see <a
+     *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
+     *     User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
+     */
+    public StartAssertionOptionsBuilder hints(@NonNull PublicKeyCredentialHint... hints) {
+      return this.hints(
+          Arrays.stream(hints).map(PublicKeyCredentialHint::getValue).toArray(String[]::new));
+    }
+
+    /**
+     * Zero or more hints, in descending order of preference, to guide the user agent in interacting
+     * with the user during this authentication operation.
+     *
+     * <p>Setting this property multiple times overwrites any value set previously.
+     *
+     * <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
+     * client to emphasize the option of authenticating with an external security key, or the {@link
+     * PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the
+     * option of authenticating a built-in passkey provider.
+     *
+     * <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
+     * providing the best experience by using contextual information about the request.
+     *
+     * <p>Hints MAY contradict information contained in {@link
+     * PublicKeyCredentialDescriptor#getTransports()}. When this occurs, the hints take precedence.
+     *
+     * <p>This library does not take these hints into account in any way, other than passing them
+     * through to the {@link PublicKeyCredentialRequestOptions} so they can be used in the argument
+     * to <code>navigator.credentials.get()</code> on the client side.
+     *
+     * <p>The default is empty.
+     *
+     * @see PublicKeyCredentialHint
+     * @see PublicKeyCredentialRequestOptions#getHints()
+     * @see StartAssertionOptions#getHints()
+     * @see StartAssertionOptionsBuilder#hints(String...)
+     * @see StartAssertionOptionsBuilder#hints(PublicKeyCredentialHint...)
+     * @see <a
+     *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialrequestoptions-hints">PublicKeyCredentialRequestOptions.hints</a>
+     * @see <a
+     *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
+     *     User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
+     */
+    public StartAssertionOptionsBuilder hints(@NonNull List<String> hints) {
+      this.hints = hints;
+      return this;
+    }
   }
 }