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 java.util.Objects;
020import org.jspecify.annotations.NonNull;
021
022/**
023 * Authoritative read outcome. No outcome grants a credential proof.
024 * @since 1.0.0
025 */
026@javax.annotation.concurrent.Immutable
027public sealed interface TotpStoreReadResult permits TotpStoreReadResult.Available,
028  TotpStoreReadResult.Fenced, TotpStoreReadResult.Unavailable {
029 /**
030  * Complete observations at one authoritative snapshot point.
031  * @since 1.0.0
032  */
033 @javax.annotation.concurrent.Immutable
034 final class Available implements TotpStoreReadResult {
035  private final @NonNull TotpStoreSnapshot snapshot;
036  private Available(@NonNull TotpStoreSnapshot snapshot) { this.snapshot = Objects.requireNonNull(snapshot); }
037  /**
038   * Wraps a complete snapshot.
039   * @param snapshot the authoritative observations
040   * @return the available outcome
041   * @since 1.0.0
042   */
043  public static TotpStoreReadResult.@NonNull Available fromSnapshot(@NonNull TotpStoreSnapshot snapshot) {
044   return new Available(snapshot);
045  }
046  /**
047   * Returns the immutable snapshot.
048   * @return the observations
049   * @since 1.0.0
050   */
051  public @NonNull TotpStoreSnapshot getSnapshot() { return this.snapshot; }
052  /**
053   * Redacts all observations.
054   * @since 1.0.0
055   */
056  @Override public @NonNull String toString() { return "Available{snapshot=<redacted>}"; }
057 }
058 /**
059  * The requested recovery epoch is no longer authoritative.
060  * @since 1.0.0
061  */
062 @javax.annotation.concurrent.Immutable
063 final class Fenced implements TotpStoreReadResult {
064  private static final TotpStoreReadResult.@NonNull Fenced INSTANCE = new Fenced();
065  private Fenced() { }
066  /**
067   * Returns the fenced outcome.
068   * @return the fenced outcome
069   * @since 1.0.0
070   */
071  public static TotpStoreReadResult.@NonNull Fenced get() { return INSTANCE; }
072  /**
073   * Returns a fixed description.
074   * @since 1.0.0
075   */
076  @Override public @NonNull String toString() { return "Fenced{}"; }
077 }
078 /**
079  * An authoritative read could not be confirmed.
080  * @since 1.0.0
081  */
082 @javax.annotation.concurrent.Immutable
083 final class Unavailable implements TotpStoreReadResult {
084  private static final TotpStoreReadResult.@NonNull Unavailable INSTANCE = new Unavailable();
085  private Unavailable() { }
086  /**
087   * Returns the unavailable outcome.
088   * @return the unavailable outcome
089   * @since 1.0.0
090   */
091  public static TotpStoreReadResult.@NonNull Unavailable get() { return INSTANCE; }
092  /**
093   * Returns a fixed description.
094   * @since 1.0.0
095   */
096  @Override public @NonNull String toString() { return "Unavailable{}"; }
097 }
098}