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.oauth.server; 018 019import com.google.errorprone.annotations.CheckReturnValue; 020import org.jspecify.annotations.NonNull; 021import org.jspecify.annotations.Nullable; 022import javax.annotation.concurrent.Immutable; 023import java.time.Instant; 024import java.time.Duration; 025import java.util.List; 026import java.util.Optional; 027import static java.util.Objects.requireNonNull; 028 029/** 030 * Application-owned authoritative issuer persistence. Implementations must be safe across callers and nodes. 031 * Reads are linearizable; commits atomically check every condition before applying all mutations and return 032 * a contextual COMMITTED receipt only after durability under the application's deployment contract. CONFLICT has zero effects; 033 * a lost connection with uncertain outcome returns UNKNOWN, never a guessed conflict or success. 034 * Condition-only commits are required atomic read-set barriers. TIMED commits validate fresh authority time 035 * after all waits and exact predicates, lower/upper bounds before capacity or mutation. FENCE_ONLY is 036 * restricted to the transaction type's two existing permanent-fence epoch transitions. Reads and failed 037 * writes perform no cleanup. Missing established roots cannot be recreated as a fresh namespace. 038 * All time and admission facts are backend-owned; no worker clock fallback is permitted. No callback executes inside a transaction. 039 * Providers honor the remaining budget and preserve permanent fences and retained replay tombstones: 040 * capacity pressure rejects work rather than evicting active records. Revetsec cannot forcibly preempt 041 * blocked application code. This interface supplies no database, durability or rollback detection by itself. 042 * @author <a href="https://www.revetkn.com">Mark Allen</a> 043 * 044 * @since 1.0.0 045 */ 046@javax.annotation.concurrent.ThreadSafe 047@CheckReturnValue 048public interface OAuthAuthorizationServerStore { 049 /** 050 * Reads an authoritative entry or confirmed absence with coherent admitted time, preserving every transport field exactly. 051 * Infrastructure failure is unavailable, never translated into absence. Do not include record data in diagnostics. 052 * @param key the exact address 053 * @param remainingBudget the remaining positive operation budget 054 * @return the coherent available, fenced or unavailable observation 055 * @since 1.0.0 056 */ 057 @NonNull OAuthStoreReadResult read(@NonNull OAuthStoreKey key, 058 @NonNull Duration remainingBudget); 059 /** 060 * Atomically checks the complete predicate set and applies the complete mutation set. 061 * Zero mutations still checks all predicates at one linearization point. Never partially apply writes. 062 * @param transaction the immutable engine-created transaction 063 * @param remainingBudget the remaining positive operation budget 064 * @return the actual durable, conflict or uncertain outcome 065 * @since 1.0.0 066 */ 067 @NonNull OAuthStoreCommitReceipt commit(@NonNull OAuthStoreTransaction transaction, 068 @NonNull Duration remainingBudget); 069}