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 javax.annotation.concurrent.Immutable;
021
022import static java.util.Objects.requireNonNull;
023
024/** Authoritative non-secret status; absence never authorizes an application to downgrade MFA.
025 * @since 1.0.0 */
026@Immutable
027public abstract sealed class TotpStatusResult permits
028        TotpStatusResult.Present, TotpStatusResult.Absent, TotpStatusResult.Unavailable {
029    private static final @NonNull Absent ABSENT = new Absent();
030
031    TotpStatusResult() { }
032    static @NonNull TotpStatusResult present(@NonNull TotpStatus status) {
033        return new Present(status);
034    }
035    static @NonNull TotpStatusResult absent() {
036        return ABSENT;
037    }
038    static @NonNull TotpStatusResult unavailable(@NonNull TotpUnavailableReason reason) {
039        return new Unavailable(reason);
040    }
041    static @NonNull TotpStatusResult unavailable() {
042        return unavailable(TotpUnavailableReason.DEPENDENCY_UNAVAILABLE);
043    }
044
045    /** Redacts all account, binding and secret data.
046     * @return a fixed description
047     * @since 1.0.0 */
048    @Override public final @NonNull String toString() { return "TotpStatusResult{<redacted>}"; }
049
050    /** An authoritative status read; this is not identity proof.
051     * @since 1.0.0 */
052    @Immutable
053    public static final class Present extends TotpStatusResult {
054        private final @NonNull TotpStatus status;
055        private Present(@NonNull TotpStatus status) {
056            this.status = requireNonNull(status);
057        }
058        /** Returns the status.
059         * @return status
060         * @since 1.0.0 */
061        public @NonNull TotpStatus getStatus() { return this.status; }
062    }
063
064    /** The account has no record in this epoch; application MFA requirements still apply.
065     * @since 1.0.0 */
066    @Immutable
067    public static final class Absent extends TotpStatusResult {
068        private Absent() { }
069    }
070
071    /** Infrastructure or recovery admission was unavailable; no success is established.
072     * @since 1.0.0 */
073    @Immutable
074    public static final class Unavailable extends TotpStatusResult {
075        private final @NonNull TotpUnavailableReason reason;
076        private Unavailable(@NonNull TotpUnavailableReason reason) {
077            this.reason = requireNonNull(reason);
078        }
079        /** Returns the reason.
080         * @return reason
081         * @since 1.0.0 */
082        public @NonNull TotpUnavailableReason getReason() { return this.reason; }
083    }
084}