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; 022import java.time.Duration; 023 024import static java.util.Objects.requireNonNull; 025 026/** Pending enrollment preparation; provisioning material appears only after a confirmed commit. 027 * @since 1.0.0 */ 028@Immutable 029public abstract sealed class TotpEnrollmentRequestResult permits 030 TotpEnrollmentRequestResult.Prepared, TotpEnrollmentRequestResult.Rejected, TotpEnrollmentRequestResult.Throttled, TotpEnrollmentRequestResult.Unavailable, TotpEnrollmentRequestResult.Indeterminate, TotpEnrollmentRequestResult.ReconciliationRequired { 031 private static final @NonNull Indeterminate INDETERMINATE = new Indeterminate(); 032 private static final @NonNull ReconciliationRequired RECONCILIATION_REQUIRED = new ReconciliationRequired(); 033 034 TotpEnrollmentRequestResult() { } 035 static @NonNull TotpEnrollmentRequestResult prepared(@NonNull TotpEnrollment enrollment) { 036 return new Prepared(enrollment); 037 } 038 static @NonNull TotpEnrollmentRequestResult rejected(@NonNull TotpRejectionReason reason) { 039 return new Rejected(reason); 040 } 041 static @NonNull TotpEnrollmentRequestResult throttled(@NonNull Duration retryAfter) { 042 return new Throttled(retryAfter); 043 } 044 static @NonNull TotpEnrollmentRequestResult unavailable(@NonNull TotpUnavailableReason reason) { 045 return new Unavailable(reason); 046 } 047 static @NonNull TotpEnrollmentRequestResult indeterminate() { 048 return INDETERMINATE; 049 } 050 @CheckReturnValue 051 static @NonNull TotpEnrollmentRequestResult reconciliationRequired() { 052 return RECONCILIATION_REQUIRED; 053 } 054 static @NonNull TotpEnrollmentRequestResult unavailable() { 055 return unavailable(TotpUnavailableReason.DEPENDENCY_UNAVAILABLE); 056 } 057 058 /** Redacts all account, binding and secret data. 059 * @return a fixed description 060 * @since 1.0.0 */ 061 @Override public final @NonNull String toString() { return "TotpEnrollmentRequestResult{<redacted>}"; } 062 063 /** Provisioning material whose pending record was definitely committed. 064 * @since 1.0.0 */ 065 @Immutable 066 public static final class Prepared extends TotpEnrollmentRequestResult { 067 private final @NonNull TotpEnrollment enrollment; 068 private Prepared(@NonNull TotpEnrollment enrollment) { 069 this.enrollment = requireNonNull(enrollment); 070 } 071 /** Returns the enrollment. 072 * @return enrollment 073 * @since 1.0.0 */ 074 public @NonNull TotpEnrollment getEnrollment() { return this.enrollment; } 075 } 076 077 /** Fixed input, policy or generation rejection; no proof is released. 078 * @since 1.0.0 */ 079 @Immutable 080 public static final class Rejected extends TotpEnrollmentRequestResult { 081 private final @NonNull TotpRejectionReason reason; 082 private Rejected(@NonNull TotpRejectionReason reason) { 083 this.reason = requireNonNull(reason); 084 } 085 /** Returns the reason. 086 * @return reason 087 * @since 1.0.0 */ 088 public @NonNull TotpRejectionReason getReason() { return this.reason; } 089 } 090 091 /** The durable shared account admission limit prevented this attempt. 092 * @since 1.0.0 */ 093 @Immutable 094 public static final class Throttled extends TotpEnrollmentRequestResult { 095 private final @NonNull Duration retryAfter; 096 private Throttled(@NonNull Duration retryAfter) { 097 this.retryAfter = requireNonNull(retryAfter); 098 if (retryAfter.isNegative()) throw new IllegalArgumentException("Negative retry duration"); 099 } 100 /** Returns the retryAfter. 101 * @return retryAfter 102 * @since 1.0.0 */ 103 public @NonNull Duration getRetryAfter() { return this.retryAfter; } 104 } 105 106 /** Infrastructure or recovery admission was unavailable; no success is established. 107 * @since 1.0.0 */ 108 @Immutable 109 public static final class Unavailable extends TotpEnrollmentRequestResult { 110 private final @NonNull TotpUnavailableReason reason; 111 private Unavailable(@NonNull TotpUnavailableReason reason) { 112 this.reason = requireNonNull(reason); 113 } 114 /** Returns the reason. 115 * @return reason 116 * @since 1.0.0 */ 117 public @NonNull TotpUnavailableReason getReason() { return this.reason; } 118 } 119 120 /** A write may have occurred; reconcile management state and never infer authentication success. 121 * @since 1.0.0 */ 122 @Immutable 123 public static final class Indeterminate extends TotpEnrollmentRequestResult { 124 private Indeterminate() { } 125 } 126 127 /** The requested transition is known committed, but normal output could not be admitted. 128 * No proof, secret or operation detail is released. 129 * @since 1.0.0 */ 130 @Immutable 131 public static final class ReconciliationRequired extends TotpEnrollmentRequestResult { 132 private ReconciliationRequired() { } 133 } 134}