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}