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 java.time.Duration;
020import org.jspecify.annotations.NonNull;
021import org.jspecify.annotations.Nullable;
022
023/**
024 * Application-owned recovery admission barrier. Before granting admission, compare externally
025 * durable recovery state and allowed sealing-key lifecycle with the exact requested context. The
026 * controller closes admission, drains outstanding operations, fences old transactions and writers,
027 * then restores into a fresh never-reused epoch. Encryption cannot detect database rollback.
028 * <p>Implementations are thread-safe; each permit belongs to the acquiring thread. Nested admission
029 * on that thread retains the barrier until its outermost permit closes. This allows an application
030 * to hold outer admission through its own login/session transaction. Alternatively, that transaction
031 * must atomically enforce a recovery epoch fence. A preceding epoch lookup leaves a completion race.
032 * Returned proofs cannot revoke themselves; sessions and approvals from earlier epochs must be
033 * invalidated by the application. Initialization admission is granted only while provisioning a new
034 * epoch, and stops before ordinary traffic opens.
035 * @since 1.0.0
036 */
037@javax.annotation.concurrent.ThreadSafe
038public interface TotpRecoveryGate {
039 /**
040  * Acquires admission within the positive remaining caller-thread budget. The budget establishes
041  * a deadline for the complete permit lifetime, including later currentness checks. Return null
042  * when admission is closed or cannot be confirmed. Core holds admission through storage and its
043  * final result decision. After a genuinely unknown mutation, loss of admission preserves Indeterminate; a known requested
044  * commitment without releasable output requires ReconciliationRequired. A retained charge whose
045  * settlement is incomplete remains ATTEMPT_INCOMPLETE. None releases proofs or plaintext. If acquisition returns null or throws, the
046  * implementation must first release every partially acquired lock, lease, reference count or
047  * other admission claim. Such an outcome must leave no admission held by the calling thread;
048  * core cannot release a permit it never received. This also applies when acquisition is
049  * interrupted or its budget expires. Preserve interruption and never extend a deadline.
050  * @param context the exact operation and sealing configuration
051  * @param remainingBudget remaining positive operation budget
052  * @return a caller-thread permit, or null when admission is unavailable
053  * @since 1.0.0
054  */
055 @Nullable Permit acquire(@NonNull TotpRecoveryContext context, @NonNull Duration remainingBudget);
056 /**
057  * One caller-thread admission permit, with an idempotent prompt release.
058  * @since 1.0.0
059  */
060 @javax.annotation.concurrent.NotThreadSafe
061 interface Permit extends AutoCloseable {
062  /**
063   * Confirms admission and the original deadline still hold. This check cannot substitute for
064   * the store's transactional epoch comparison against stale lease holders.
065   * @return true only while this permit remains current
066   * @since 1.0.0
067   */
068  @NonNull Boolean isCurrent();
069  /**
070   * Releases this nested permit promptly and idempotently. The final close releases admission.
071   * @since 1.0.0
072   */
073  @Override void close();
074 }
075}