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}