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}