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.webauthn; 018 019import org.jspecify.annotations.NonNull; 020import org.jspecify.annotations.Nullable; 021 022import javax.annotation.concurrent.NotThreadSafe; 023import javax.annotation.concurrent.ThreadSafe; 024import java.time.Duration; 025 026/** 027 * Application-owned admission barrier for authoritative WebAuthn operations. Before granting a 028 * permit, the application must compare its independent durable recovery marker and sealing-key 029 * state with the authoritative store. A database snapshot that is internally consistent can 030 * still be old, so checking only WebAuthn records is insufficient. Restore must stop new 031 * admission and drain every outstanding permit before reopening traffic. Implementations must 032 * honor the remaining positive caller-thread budget and preserve interrupt status. This gate 033 * never creates a verification proof. 034 * Reopening traffic means resuming deployment admission after recovery checks; it does not 035 * reenable an account whose permanent WebAuthn fence has been disabled. 036 * 037 * @since 1.0.0 038 */ 039@ThreadSafe 040public interface WebAuthnRecoveryGate { 041 /** 042 * Acquires an admission permit held through the entire operation, including the store write. 043 * Return {@code null} when traffic is closed or the external marker cannot be confirmed. 044 * A failure to acquire is an infrastructure outcome, not an invalid-credential verdict. 045 * 046 * @param remainingBudget the remaining positive operation budget 047 * @return an admitted permit, or {@code null} when admission is unavailable 048 * @since 1.0.0 049 */ 050 @Nullable Permit acquire(@NonNull Duration remainingBudget); 051 052 /** 053 * One caller-thread permit. A restore barrier must wait for its close before replacing 054 * authoritative state. {@link #isCurrent()} can revoke admission while an operation runs; 055 * after a possible write, that condition requires reconciliation rather than success. 056 * 057 * @since 1.0.0 058 */ 059 @NotThreadSafe 060 interface Permit extends AutoCloseable { 061 /** 062 * Checks that the external durable recovery marker and key state remain admitted. 063 * @return true only while this permit still admits traffic 064 * @since 1.0.0 065 */ 066 @NonNull Boolean isCurrent(); 067 068 /** Releases this operation's restore barrier. @since 1.0.0 */ 069 @Override void close(); 070 } 071}