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.totp;
018
019import com.revetsec.json.JsonString;
020import com.google.errorprone.annotations.CheckReturnValue;
021import org.jspecify.annotations.NonNull;
022import org.jspecify.annotations.Nullable;
023
024import javax.annotation.concurrent.Immutable;
025import javax.annotation.concurrent.NotThreadSafe;
026import java.nio.charset.StandardCharsets;
027import java.util.Optional;
028
029import static java.util.Objects.requireNonNull;
030
031/** Application-approved account and display information for initial or replacement enrollment.
032 * @since 1.0.0 */
033@Immutable
034public final class TotpEnrollmentOptions {
035    private final @NonNull String accountId;
036    private final @NonNull String accountName;
037    private final @Nullable String replacingFactorId;
038
039    private TotpEnrollmentOptions(@NonNull String accountId, @NonNull String accountName,
040            @Nullable String replacingFactorId) {
041        this.accountId = accountId;
042        this.accountName = accountName;
043        this.replacingFactorId = replacingFactorId;
044    }
045
046    /** Starts enrollment options for an application-approved account.
047     * @param accountId stable nonempty, well-formed account identifier, at most 1024 UTF-8 bytes
048     * @return a builder
049     * @since 1.0.0 */
050    public static @NonNull Builder withAccountId(@NonNull String accountId) {
051        return new Builder(accountId);
052    }
053
054    /** Returns the application-approved account identifier.
055     * @return account identifier
056     * @since 1.0.0 */
057    public @NonNull String getAccountId() { return this.accountId; }
058
059    /** Returns the authenticator display name, which does not establish identity.
060     * @return account display name
061     * @since 1.0.0 */
062    public @NonNull String getAccountName() { return this.accountName; }
063
064    /** Returns the explicitly approved factor generation to replace.
065     * @return current factor generation, or empty for initial enrollment
066     * @since 1.0.0 */
067    public @NonNull Optional<@NonNull String> getReplacingFactorId() {
068        return Optional.ofNullable(this.replacingFactorId);
069    }
070
071    /** Redacts account and generation information.
072     * @return a fixed description
073     * @since 1.0.0 */
074    @Override public @NonNull String toString() { return "TotpEnrollmentOptions{<redacted>}"; }
075
076    /** One caller-thread enrollment builder.
077     * @since 1.0.0 */
078    @NotThreadSafe
079    @CheckReturnValue
080    public static final class Builder {
081        private final @NonNull String accountId;
082        private @Nullable String accountName;
083        private @Nullable String replacingFactorId;
084        private Builder(@NonNull String accountId) {
085            requireNonNull(accountId);
086            if (accountId.isEmpty() || accountId.length() > 1024)
087                throw new IllegalArgumentException("Invalid TOTP account identifier");
088            JsonString.fromValue(accountId);
089            if (accountId.getBytes(StandardCharsets.UTF_8).length > 1024)
090                throw new IllegalArgumentException("Invalid TOTP account identifier");
091            this.accountId = accountId;
092        }
093
094        /** Sets the display name shown by the authenticator application.
095         * @param accountName display name of at most 256 code points, without colons, ISO controls,
096         * Unicode format/line/paragraph controls or leading/trailing whitespace; null clears this required setting.
097         * Enrollment also requires the full percent-encoded URI to fit 512 ASCII bytes
098         * @return this builder
099         * @since 1.0.0 */
100        public @NonNull Builder accountName(@Nullable String accountName) {
101            if (accountName == null) { this.accountName = null; return this; }
102            bounded(accountName, 256);
103            TotpProvisioning.validateLabel(accountName);
104            this.accountName = accountName;
105            return this;
106        }
107
108        /** Approves replacement of an exact current factor generation.
109         * Starting replacement preserves the active factor until confirmation commits.
110         * @param factorId current factor generation, or null for initial enrollment
111         * @return this builder
112         * @since 1.0.0 */
113        public @NonNull Builder replacingFactorId(@Nullable String factorId) {
114            this.replacingFactorId = factorId == null ? null : bounded(factorId, 1024);
115            return this;
116        }
117
118        /** Builds immutable options; an account display name is required.
119         * @return enrollment options
120         * @since 1.0.0 */
121        public @NonNull TotpEnrollmentOptions build() {
122            return new TotpEnrollmentOptions(this.accountId,
123                    requireNonNull(this.accountName, "accountName"), this.replacingFactorId);
124        }
125
126        /** Redacts builder contents.
127         * @return a fixed description
128         * @since 1.0.0 */
129        @Override public @NonNull String toString() { return "TotpEnrollmentOptions.Builder{<redacted>}"; }
130    }
131
132    private static @NonNull String bounded(@NonNull String value, int maximumPoints) {
133        requireNonNull(value);
134        if (value.isEmpty() || value.length() > maximumPoints * 2)
135            throw new IllegalArgumentException("Invalid TOTP enrollment option");
136        JsonString.fromValue(value);
137        if (value.codePointCount(0, value.length()) > maximumPoints)
138            throw new IllegalArgumentException("Invalid TOTP enrollment option");
139        for (int offset = 0; offset < value.length();) {
140            int point = value.codePointAt(offset);
141            if (Character.isISOControl(point))
142                throw new IllegalArgumentException("Invalid TOTP enrollment option");
143            offset += Character.charCount(point);
144        }
145        return value;
146    }
147}