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 org.jspecify.annotations.NonNull; 020import com.google.errorprone.annotations.CheckReturnValue; 021import javax.annotation.concurrent.Immutable; 022import java.time.Duration; 023 024import static java.util.Objects.requireNonNull; 025 026/** Enrollment confirmation and atomic activation of a factor and recovery batch. 027 * @since 1.0.0 */ 028@Immutable 029public abstract sealed class TotpEnrollmentResult permits 030 TotpEnrollmentResult.Succeeded, TotpEnrollmentResult.Rejected, TotpEnrollmentResult.Throttled, TotpEnrollmentResult.Unavailable, TotpEnrollmentResult.Indeterminate, TotpEnrollmentResult.ReconciliationRequired { 031 private static final @NonNull Indeterminate INDETERMINATE = new Indeterminate(); 032 private static final @NonNull ReconciliationRequired RECONCILIATION_REQUIRED = new ReconciliationRequired(); 033 034 TotpEnrollmentResult() { } 035 static @NonNull TotpEnrollmentResult succeeded(@NonNull TotpFactor factor, @NonNull RecoveryCodes recoveryCodes) { 036 return new Succeeded(factor, recoveryCodes); 037 } 038 static @NonNull TotpEnrollmentResult rejected(@NonNull TotpRejectionReason reason) { 039 return new Rejected(reason); 040 } 041 static @NonNull TotpEnrollmentResult throttled(@NonNull Duration retryAfter) { 042 return new Throttled(retryAfter); 043 } 044 static @NonNull TotpEnrollmentResult unavailable(@NonNull TotpUnavailableReason reason) { 045 return new Unavailable(reason); 046 } 047 static @NonNull TotpEnrollmentResult indeterminate() { 048 return INDETERMINATE; 049 } 050 @CheckReturnValue 051 static @NonNull TotpEnrollmentResult reconciliationRequired() { 052 return RECONCILIATION_REQUIRED; 053 } 054 static @NonNull TotpEnrollmentResult unavailable() { 055 return unavailable(TotpUnavailableReason.DEPENDENCY_UNAVAILABLE); 056 } 057 058 /** Redacts all account, binding and secret data. 059 * @return a fixed description 060 * @since 1.0.0 */ 061 @Override public final @NonNull String toString() { return "TotpEnrollmentResult{<redacted>}"; } 062 063 /** The requested transition was definitely committed under current admission. 064 * @since 1.0.0 */ 065 @Immutable 066 public static final class Succeeded extends TotpEnrollmentResult { 067 private final @NonNull TotpFactor factor; 068 private final @NonNull RecoveryCodes recoveryCodes; 069 private Succeeded(@NonNull TotpFactor factor, @NonNull RecoveryCodes recoveryCodes) { 070 this.factor = requireNonNull(factor); 071 this.recoveryCodes = requireNonNull(recoveryCodes); 072 } 073 /** Returns the factor. 074 * @return factor 075 * @since 1.0.0 */ 076 public @NonNull TotpFactor getFactor() { return this.factor; } 077 /** Returns the recoveryCodes. 078 * @return recoveryCodes 079 * @since 1.0.0 */ 080 public @NonNull RecoveryCodes getRecoveryCodes() { return this.recoveryCodes; } 081 } 082 083 /** Fixed input, policy or generation rejection; no proof is released. 084 * @since 1.0.0 */ 085 @Immutable 086 public static final class Rejected extends TotpEnrollmentResult { 087 private final @NonNull TotpRejectionReason reason; 088 private Rejected(@NonNull TotpRejectionReason reason) { 089 this.reason = requireNonNull(reason); 090 } 091 /** Returns the reason. 092 * @return reason 093 * @since 1.0.0 */ 094 public @NonNull TotpRejectionReason getReason() { return this.reason; } 095 } 096 097 /** The durable shared account admission limit prevented this attempt. 098 * @since 1.0.0 */ 099 @Immutable 100 public static final class Throttled extends TotpEnrollmentResult { 101 private final @NonNull Duration retryAfter; 102 private Throttled(@NonNull Duration retryAfter) { 103 this.retryAfter = requireNonNull(retryAfter); 104 if (retryAfter.isNegative()) throw new IllegalArgumentException("Negative retry duration"); 105 } 106 /** Returns the retryAfter. 107 * @return retryAfter 108 * @since 1.0.0 */ 109 public @NonNull Duration getRetryAfter() { return this.retryAfter; } 110 } 111 112 /** Infrastructure or recovery admission was unavailable; no success is established. 113 * @since 1.0.0 */ 114 @Immutable 115 public static final class Unavailable extends TotpEnrollmentResult { 116 private final @NonNull TotpUnavailableReason reason; 117 private Unavailable(@NonNull TotpUnavailableReason reason) { 118 this.reason = requireNonNull(reason); 119 } 120 /** Returns the reason. 121 * @return reason 122 * @since 1.0.0 */ 123 public @NonNull TotpUnavailableReason getReason() { return this.reason; } 124 } 125 126 /** A write may have occurred; reconcile management state and never infer authentication success. 127 * @since 1.0.0 */ 128 @Immutable 129 public static final class Indeterminate extends TotpEnrollmentResult { 130 private Indeterminate() { } 131 } 132 133 /** The requested transition is known committed, but normal output could not be admitted. 134 * No proof, secret or operation detail is released. 135 * @since 1.0.0 */ 136 @Immutable 137 public static final class ReconciliationRequired extends TotpEnrollmentResult { 138 private ReconciliationRequired() { } 139 } 140}