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 java.time.Duration; 022import javax.annotation.concurrent.ThreadSafe; 023import static java.util.Objects.requireNonNull; 024 025/** 026 * Trusted application-owned durable key lifecycle and distribution callback. Implementations must be thread-safe, 027 * return promptly on the calling thread, cooperate with interruption and the remaining original operation budget, 028 * and preserve published-key retention through all issued token expiries and configured margins across nodes and 029 * restarts. Returning a snapshot declares that its generation was actually published at its publication instant. 030 * Construction does not call the provider. Ordinary key rotation does not invalidate grants; compromise or store 031 * restoration requires an explicit issuer revocation fence before reopening traffic. 032 * The callback receives no candidate expiry or durable issuance acknowledgement. Persist conservative 033 * retention promises before enabling dependent issuance; process-local observations cannot recover missing 034 * publication history. A well-formed initial snapshot cannot prove that an omitted prior key is safe to remove. 035 * @author <a href="https://www.revetkn.com">Mark Allen</a> 036 * @since 1.0.0 037 */ 038@ThreadSafe 039public interface OAuthIssuerKeyProvider { 040 /** 041 * Returns the current immutable declaration, preserving in-flight signing and public verification overlap. 042 * @param remainingBudget positive time left in the original operation 043 * @return one immutable snapshot 044 * @since 1.0.0 045 */ 046 @NonNull OAuthIssuerKeySnapshot getSnapshot(@NonNull Duration remainingBudget); 047 /** 048 * Supplies one fixed immutable declaration without I/O. 049 * This convenience provider adds no durable publication history or cross-node rotation coordination. 050 * @param snapshot required snapshot 051 * @return a thread-safe fixed provider 052 * @throws NullPointerException if snapshot is null 053 * @since 1.0.0 054 */ 055 @CheckReturnValue 056 static @NonNull OAuthIssuerKeyProvider fromSnapshot(@NonNull OAuthIssuerKeySnapshot snapshot) { 057 requireNonNull(snapshot);return budget -> { requireNonNull(budget);return snapshot; }; 058 } 059}