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;
022
023import static java.util.Objects.requireNonNull;
024
025/** Atomic recovery-code batch replacement for an approved current factor and batch.
026 * @since 1.0.0 */
027@Immutable
028public abstract sealed class RecoveryCodeRotationResult permits
029        RecoveryCodeRotationResult.Succeeded, RecoveryCodeRotationResult.Rejected, RecoveryCodeRotationResult.Unavailable, RecoveryCodeRotationResult.Indeterminate, RecoveryCodeRotationResult.ReconciliationRequired {
030    private static final @NonNull Indeterminate INDETERMINATE = new Indeterminate();
031    private static final @NonNull ReconciliationRequired RECONCILIATION_REQUIRED = new ReconciliationRequired();
032
033    RecoveryCodeRotationResult() { }
034    static @NonNull RecoveryCodeRotationResult succeeded(@NonNull RecoveryCodes recoveryCodes) {
035        return new Succeeded(recoveryCodes);
036    }
037    static @NonNull RecoveryCodeRotationResult rejected(@NonNull TotpRejectionReason reason) {
038        return new Rejected(reason);
039    }
040    static @NonNull RecoveryCodeRotationResult unavailable(@NonNull TotpUnavailableReason reason) {
041        return new Unavailable(reason);
042    }
043    static @NonNull RecoveryCodeRotationResult indeterminate() {
044        return INDETERMINATE;
045    }
046    @CheckReturnValue
047    static @NonNull RecoveryCodeRotationResult reconciliationRequired() {
048        return RECONCILIATION_REQUIRED;
049    }
050    static @NonNull RecoveryCodeRotationResult unavailable() {
051        return unavailable(TotpUnavailableReason.DEPENDENCY_UNAVAILABLE);
052    }
053
054    /** Redacts all account, binding and secret data.
055     * @return a fixed description
056     * @since 1.0.0 */
057    @Override public final @NonNull String toString() { return "RecoveryCodeRotationResult{<redacted>}"; }
058
059    /** The requested transition was definitely committed under current admission.
060     * @since 1.0.0 */
061    @Immutable
062    public static final class Succeeded extends RecoveryCodeRotationResult {
063        private final @NonNull RecoveryCodes recoveryCodes;
064        private Succeeded(@NonNull RecoveryCodes recoveryCodes) {
065            this.recoveryCodes = requireNonNull(recoveryCodes);
066        }
067        /** Returns the recoveryCodes.
068         * @return recoveryCodes
069         * @since 1.0.0 */
070        public @NonNull RecoveryCodes getRecoveryCodes() { return this.recoveryCodes; }
071    }
072
073    /** Fixed input, policy or generation rejection; no proof is released.
074     * @since 1.0.0 */
075    @Immutable
076    public static final class Rejected extends RecoveryCodeRotationResult {
077        private final @NonNull TotpRejectionReason reason;
078        private Rejected(@NonNull TotpRejectionReason reason) {
079            this.reason = requireNonNull(reason);
080        }
081        /** Returns the reason.
082         * @return reason
083         * @since 1.0.0 */
084        public @NonNull TotpRejectionReason getReason() { return this.reason; }
085    }
086
087    /** Infrastructure or recovery admission was unavailable; no success is established.
088     * @since 1.0.0 */
089    @Immutable
090    public static final class Unavailable extends RecoveryCodeRotationResult {
091        private final @NonNull TotpUnavailableReason reason;
092        private Unavailable(@NonNull TotpUnavailableReason reason) {
093            this.reason = requireNonNull(reason);
094        }
095        /** Returns the reason.
096         * @return reason
097         * @since 1.0.0 */
098        public @NonNull TotpUnavailableReason getReason() { return this.reason; }
099    }
100
101    /** A write may have occurred; reconcile management state and never infer authentication success.
102     * @since 1.0.0 */
103    @Immutable
104    public static final class Indeterminate extends RecoveryCodeRotationResult {
105        private Indeterminate() { }
106    }
107
108    /** The requested transition is known committed, but normal output could not be admitted.
109     * No proof, secret or operation detail is released.
110     * @since 1.0.0 */
111    @Immutable
112    public static final class ReconciliationRequired extends RecoveryCodeRotationResult {
113        private ReconciliationRequired() { }
114    }
115}