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 com.google.errorprone.annotations.CheckReturnValue;
020import com.revetsec.StoreCommitTiming;
021import org.jspecify.annotations.NonNull;
022import org.jspecify.annotations.Nullable;
023
024import java.util.Objects;
025import java.util.Optional;
026
027/**
028 * Immutable factual acknowledgement of an atomic TOTP write or predicate barrier.
029 * A known commitment retains its required validation timing even when completion acquisition or
030 * later service admission fails. It is not a credential, current-readiness assertion or retry token.
031 *
032 * @since 1.0.0
033 */
034@javax.annotation.concurrent.Immutable
035@CheckReturnValue
036public final class TotpStoreCommitReceipt {
037        private final @NonNull TotpStoreCommitResult status;
038        private final @Nullable StoreCommitTiming timing;
039
040        private TotpStoreCommitReceipt(@NonNull TotpStoreCommitResult status, @Nullable StoreCommitTiming timing) {
041                this.status = Objects.requireNonNull(status);
042                this.timing = timing;
043        }
044
045        /**
046         * Records a known committed timed write, including a successful condition-only barrier.
047         * @param timing the fresh final-validation sample and optional post-acknowledgement sample
048         * @return the committed factual receipt
049         * @throws NullPointerException if timing is null
050         * @since 1.0.0
051         */
052        public static @NonNull TotpStoreCommitReceipt fromCommittedTiming(@NonNull StoreCommitTiming timing) {
053                return new TotpStoreCommitReceipt(TotpStoreCommitResult.COMMITTED, Objects.requireNonNull(timing));
054        }
055
056        /**
057         * Records a definitive no-effect refusal, without fabricating validation timing.
058         * @param status a refusal status other than COMMITTED or UNKNOWN
059         * @return the no-effect receipt
060         * @throws NullPointerException if status is null
061         * @throws IllegalArgumentException if status is COMMITTED or UNKNOWN
062         * @since 1.0.0
063         */
064        public static @NonNull TotpStoreCommitReceipt fromRefusal(@NonNull TotpStoreCommitResult status) {
065                Objects.requireNonNull(status);
066                if (status == TotpStoreCommitResult.COMMITTED || status == TotpStoreCommitResult.UNKNOWN)
067                        throw new IllegalArgumentException("Invalid TOTP refusal status");
068                return new TotpStoreCommitReceipt(status, null);
069        }
070
071        /**
072         * Records an uncertain possible commitment, without claimed timing.
073         * @return the unknown factual receipt
074         * @since 1.0.0
075         */
076        public static @NonNull TotpStoreCommitReceipt unknownInstance() {
077                return new TotpStoreCommitReceipt(TotpStoreCommitResult.UNKNOWN, null);
078        }
079
080        /**
081         * Returns factual commitment, a definite no-effect refusal or uncertainty.
082         * @return the status
083         * @since 1.0.0
084         */
085        public @NonNull TotpStoreCommitResult getStatus() { return this.status; }
086
087        /**
088         * Returns required timing only for COMMITTED.
089         * @return the optional validation/completion metadata
090         * @since 1.0.0
091         */
092        public @NonNull Optional<@NonNull StoreCommitTiming> getTiming() { return Optional.ofNullable(this.timing); }
093
094        /**
095         * Returns a fixed description without timing, identities or state.
096         * @return the redacted description
097         * @since 1.0.0
098         */
099        @Override public @NonNull String toString() { return "TotpStoreCommitReceipt{receipt=<redacted>}"; }
100}