001/*
002 * Copyright 2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.revetsec.webauthn;
018
019import com.google.errorprone.annotations.CheckReturnValue;
020import com.revetsec.json.JsonString;
021import org.jspecify.annotations.NonNull;
022import org.jspecify.annotations.Nullable;
023
024import javax.annotation.concurrent.Immutable;
025import javax.annotation.concurrent.NotThreadSafe;
026import java.util.Arrays;
027
028import static java.util.Objects.requireNonNull;
029
030/** Application-approved account information used only to prepare credential enrollment.
031 * @since 1.0.0 */
032@Immutable
033public final class WebAuthnRegistrationOptions {
034    private final byte @NonNull [] userHandle;
035    private final @NonNull String userName;
036    private final @NonNull String userDisplayName;
037
038    private WebAuthnRegistrationOptions(byte @NonNull [] userHandle, @NonNull String userName,
039            @NonNull String userDisplayName) {
040        this.userHandle = userHandle.clone();
041        this.userName = userName;
042        this.userDisplayName = userDisplayName;
043    }
044
045    /** Starts account-approved enrollment options.
046     * @param userHandle stable opaque account handle
047     * @return a builder
048     * @since 1.0.0 */
049    public static @NonNull Builder withUserHandle(byte @NonNull [] userHandle) {
050        return new Builder(userHandle);
051    }
052
053    /** Returns a defensive handle copy.
054     * @return the account handle
055     * @since 1.0.0 */
056    public byte @NonNull [] getUserHandle() { return this.userHandle.clone(); }
057    /** Returns the browser display name.
058     * @return the account name
059     * @since 1.0.0 */
060    public @NonNull String getUserName() { return this.userName; }
061    /** Returns the browser display label.
062     * @return the display label
063     * @since 1.0.0 */
064    public @NonNull String getUserDisplayName() { return this.userDisplayName; }
065    /** Redacts the account fields.
066     * @return a fixed description
067     * @since 1.0.0 */
068    @Override public @NonNull String toString() { return "WebAuthnRegistrationOptions{account=<redacted>}"; }
069
070    /** One caller-thread builder.
071     * @since 1.0.0 */
072    @NotThreadSafe @CheckReturnValue
073    public static final class Builder {
074        private final byte @NonNull [] userHandle;
075        private @Nullable String userName;
076        private @Nullable String userDisplayName;
077        private Builder(byte @NonNull [] userHandle) {
078            requireNonNull(userHandle);
079            if (userHandle.length < 1 || userHandle.length > 64)
080                throw new IllegalArgumentException("Invalid WebAuthn user handle");
081            this.userHandle = Arrays.copyOf(userHandle, userHandle.length);
082        }
083        /** Sets a browser display name, which does not establish identity.
084         * @param name bounded account name, or null to clear the required name
085         * @return this builder
086         * @since 1.0.0 */
087        public @NonNull Builder userName(@Nullable String name) {
088            this.userName = name == null ? null : boundedName(name); return this;
089        }
090        /** Sets a browser display label.
091         * @param name bounded display label, or null to clear the required label
092         * @return this builder
093         * @since 1.0.0 */
094        public @NonNull Builder userDisplayName(@Nullable String name) {
095            this.userDisplayName = name == null ? null : boundedName(name); return this;
096        }
097        /** Builds immutable enrollment options.
098         * @return the options
099         * @since 1.0.0 */
100        public @NonNull WebAuthnRegistrationOptions build() {
101            return new WebAuthnRegistrationOptions(this.userHandle,
102                    requireNonNull(this.userName, "userName"),
103                    requireNonNull(this.userDisplayName, "userDisplayName"));
104        }
105        /** Redacts the builder fields.
106         * @return a fixed description
107         * @since 1.0.0 */
108        @Override public @NonNull String toString() { return "WebAuthnRegistrationOptions.Builder{<redacted>}"; }
109    }
110
111    private static @NonNull String boundedName(@NonNull String name) {
112        requireNonNull(name);
113        JsonString.fromValue(name);
114        if (name.isEmpty() || name.codePointCount(0, name.length()) > 64)
115            throw new IllegalArgumentException("Invalid WebAuthn display name");
116        for (int offset = 0; offset < name.length();) {
117            int point = name.codePointAt(offset);
118            if (Character.isISOControl(point)) throw new IllegalArgumentException("Invalid WebAuthn display name");
119            offset += Character.charCount(point);
120        }
121        return name;
122    }
123}