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/** TOTP verification; only Succeeded carries a committed one-time acceptance.
027 * @since 1.0.0 */
028@Immutable
029public abstract sealed class TotpVerificationResult permits
030        TotpVerificationResult.Succeeded, TotpVerificationResult.Rejected, TotpVerificationResult.Throttled, TotpVerificationResult.Unavailable, TotpVerificationResult.Indeterminate, TotpVerificationResult.ReconciliationRequired {
031    private static final @NonNull Indeterminate INDETERMINATE = new Indeterminate();
032    private static final @NonNull ReconciliationRequired RECONCILIATION_REQUIRED = new ReconciliationRequired();
033
034    TotpVerificationResult() { }
035    static @NonNull TotpVerificationResult succeeded(@NonNull TotpVerification verification) {
036        return new Succeeded(verification);
037    }
038    static @NonNull TotpVerificationResult rejected(@NonNull TotpRejectionReason reason) {
039        return new Rejected(reason);
040    }
041    static @NonNull TotpVerificationResult throttled(@NonNull Duration retryAfter) {
042        return new Throttled(retryAfter);
043    }
044    static @NonNull TotpVerificationResult unavailable(@NonNull TotpUnavailableReason reason) {
045        return new Unavailable(reason);
046    }
047    static @NonNull TotpVerificationResult indeterminate() {
048        return INDETERMINATE;
049    }
050    @CheckReturnValue
051    static @NonNull TotpVerificationResult reconciliationRequired() {
052        return RECONCILIATION_REQUIRED;
053    }
054    static @NonNull TotpVerificationResult 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 "TotpVerificationResult{<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 TotpVerificationResult {
067        private final @NonNull TotpVerification verification;
068        private Succeeded(@NonNull TotpVerification verification) {
069            this.verification = requireNonNull(verification);
070        }
071        /** Returns the verification.
072         * @return verification
073         * @since 1.0.0 */
074        public @NonNull TotpVerification getVerification() { return this.verification; }
075    }
076
077    /** Fixed input, policy or generation rejection; no proof is released.
078     * @since 1.0.0 */
079    @Immutable
080    public static final class Rejected extends TotpVerificationResult {
081        private final @NonNull TotpRejectionReason reason;
082        private Rejected(@NonNull TotpRejectionReason reason) {
083            this.reason = requireNonNull(reason);
084        }
085        /** Returns the reason.
086         * @return reason
087         * @since 1.0.0 */
088        public @NonNull TotpRejectionReason getReason() { return this.reason; }
089    }
090
091    /** The durable shared account admission limit prevented this attempt.
092     * @since 1.0.0 */
093    @Immutable
094    public static final class Throttled extends TotpVerificationResult {
095        private final @NonNull Duration retryAfter;
096        private Throttled(@NonNull Duration retryAfter) {
097            this.retryAfter = requireNonNull(retryAfter);
098            if (retryAfter.isNegative()) throw new IllegalArgumentException("Negative retry duration");
099        }
100        /** Returns the retryAfter.
101         * @return retryAfter
102         * @since 1.0.0 */
103        public @NonNull Duration getRetryAfter() { return this.retryAfter; }
104    }
105
106    /** Infrastructure or recovery admission was unavailable; no success is established.
107     * @since 1.0.0 */
108    @Immutable
109    public static final class Unavailable extends TotpVerificationResult {
110        private final @NonNull TotpUnavailableReason reason;
111        private Unavailable(@NonNull TotpUnavailableReason reason) {
112            this.reason = requireNonNull(reason);
113        }
114        /** Returns the reason.
115         * @return reason
116         * @since 1.0.0 */
117        public @NonNull TotpUnavailableReason getReason() { return this.reason; }
118    }
119
120    /** A write may have occurred; reconcile management state and never infer authentication success.
121     * @since 1.0.0 */
122    @Immutable
123    public static final class Indeterminate extends TotpVerificationResult {
124        private Indeterminate() { }
125    }
126
127    /** The requested transition is known committed, but normal output could not be admitted.
128     * No proof, secret or operation detail is released.
129     * @since 1.0.0 */
130    @Immutable
131    public static final class ReconciliationRequired extends TotpVerificationResult {
132        private ReconciliationRequired() { }
133    }
134}