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}