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 java.time.Duration;
021import java.util.Set;
022import org.jspecify.annotations.NonNull;
023
024/**
025 * Application-owned, authoritative TOTP storage. Implementations coordinate every node, read a
026 * complete immutable snapshot and atomically compare every version, absence and active recovery
027 * epoch before applying all mutations or none. A separately performed epoch or time lookup is insufficient.
028 * A confirmed commit is durable across restart. {@link InMemoryTotpStore} is an explicitly selected
029 * volatile demonstration backend, never an automatic fallback.
030 * <p>Both record kinds are permanent. No backend TTL, eviction or automatic deletion is allowed,
031 * including after factor removal. Capacity refusal changes nothing. Unknown acknowledgement after
032 * a possible mutation is UNKNOWN, never CONFLICT or UNAVAILABLE. Only definite CONFLICT permits
033 * bounded recalculation. Honor positive remaining caller-thread budgets and preserve interruption.
034 * <p>Namespace activation metadata is application-owned. INITIALIZE_NAMESPACE atomically inserts
035 * its root and changes NEW to ACTIVATED once. Updates require ACTIVATED and a present root; a
036 * missing root in an activated epoch is unavailability, never permission to initialize again.
037 * Recovery provisioning fences all old writers before a fresh, never-reused epoch is initialized.
038 * @since 1.0.0
039 */
040@javax.annotation.concurrent.ThreadSafe
041@CheckReturnValue
042public interface TotpStore {
043 /**
044  * Reads exactly the requested nonempty bounded scope at one authoritative snapshot point,
045  * checking the active epoch and operational admission in the same transaction. The entries and
046  * fresh admitted time or time-only unavailability form one coherent observation. Explicitly
047  * represent every absence; no cleanup, quota update or floor write belongs to a read.
048  * @param keys one namespace and recovery epoch, at most 16 addresses
049  * @param remainingBudget remaining positive operation budget
050  * @return a complete snapshot, fenced epoch or unavailable read
051  * @since 1.0.0
052  */
053 @NonNull TotpStoreReadResult read(@NonNull Set<@NonNull TotpStoreKey> keys,
054   @NonNull Duration remainingBudget);
055 /**
056  * Atomically compares current admission, epoch and all snapshot predicates, then validates fresh
057  * store-authoritative time after every wait, including for condition-only writes.
058  * @param write the exact predicates and complete change set
059  * @param remainingBudget remaining positive operation budget
060  * @return the factual contextual receipt, with required validation timing for COMMITTED
061  * @since 1.0.0
062  */
063 @NonNull TotpStoreCommitReceipt compareAndCommit(@NonNull TotpStoreWrite write,
064   @NonNull Duration remainingBudget);
065}