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/** Explicit namespace initialization under provisioning admission.
026 * @since 1.0.0 */
027@Immutable
028public abstract sealed class TotpNamespaceInitializationResult permits
029        TotpNamespaceInitializationResult.Initialized, TotpNamespaceInitializationResult.AlreadyInitialized, TotpNamespaceInitializationResult.Unavailable, TotpNamespaceInitializationResult.Indeterminate, TotpNamespaceInitializationResult.ReconciliationRequired {
030    private static final @NonNull Initialized INITIALIZED = new Initialized();
031    private static final @NonNull AlreadyInitialized ALREADY_INITIALIZED = new AlreadyInitialized();
032    private static final @NonNull Indeterminate INDETERMINATE = new Indeterminate();
033    private static final @NonNull ReconciliationRequired RECONCILIATION_REQUIRED = new ReconciliationRequired();
034
035    TotpNamespaceInitializationResult() { }
036    static @NonNull TotpNamespaceInitializationResult initialized() {
037        return INITIALIZED;
038    }
039    static @NonNull TotpNamespaceInitializationResult alreadyInitialized() {
040        return ALREADY_INITIALIZED;
041    }
042    static @NonNull TotpNamespaceInitializationResult unavailable(@NonNull TotpUnavailableReason reason) {
043        return new Unavailable(reason);
044    }
045    static @NonNull TotpNamespaceInitializationResult indeterminate() {
046        return INDETERMINATE;
047    }
048    @CheckReturnValue
049    static @NonNull TotpNamespaceInitializationResult reconciliationRequired() {
050        return RECONCILIATION_REQUIRED;
051    }
052    static @NonNull TotpNamespaceInitializationResult unavailable() {
053        return unavailable(TotpUnavailableReason.DEPENDENCY_UNAVAILABLE);
054    }
055
056    /** Redacts all account, binding and secret data.
057     * @return a fixed description
058     * @since 1.0.0 */
059    @Override public final @NonNull String toString() { return "TotpNamespaceInitializationResult{<redacted>}"; }
060
061    /** The new namespace record and activation state were atomically initialized.
062     * @since 1.0.0 */
063    @Immutable
064    public static final class Initialized extends TotpNamespaceInitializationResult {
065        private Initialized() { }
066    }
067
068    /** The current namespace was already validly initialized.
069     * @since 1.0.0 */
070    @Immutable
071    public static final class AlreadyInitialized extends TotpNamespaceInitializationResult {
072        private AlreadyInitialized() { }
073    }
074
075    /** Infrastructure or recovery admission was unavailable; no success is established.
076     * @since 1.0.0 */
077    @Immutable
078    public static final class Unavailable extends TotpNamespaceInitializationResult {
079        private final @NonNull TotpUnavailableReason reason;
080        private Unavailable(@NonNull TotpUnavailableReason reason) {
081            this.reason = requireNonNull(reason);
082        }
083        /** Returns the reason.
084         * @return reason
085         * @since 1.0.0 */
086        public @NonNull TotpUnavailableReason getReason() { return this.reason; }
087    }
088
089    /** A write may have occurred; reconcile management state and never infer authentication success.
090     * @since 1.0.0 */
091    @Immutable
092    public static final class Indeterminate extends TotpNamespaceInitializationResult {
093        private Indeterminate() { }
094    }
095
096    /** The requested transition is known committed, but normal output could not be admitted.
097     * No proof, secret or operation detail is released.
098     * @since 1.0.0 */
099    @Immutable
100    public static final class ReconciliationRequired extends TotpNamespaceInitializationResult {
101        private ReconciliationRequired() { }
102    }
103}