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}