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}