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 org.jspecify.annotations.NonNull; 020import org.jspecify.annotations.Nullable; 021import com.google.errorprone.annotations.CheckReturnValue; 022import javax.annotation.concurrent.Immutable; 023import java.util.Optional; 024import static java.util.Objects.requireNonNull; 025import javax.annotation.concurrent.ThreadSafe; 026import java.time.Duration; 027 028/** 029 * Safe synchronous caller-thread issuer events. Hooks run outside held locks and transactions and must be fast 030 * and thread-safe. Failures are contained except VirtualMachineError; interruption is restored. No event includes 031 * a client, subject, grant, credential, key identifier, URL, request or claims. Exactly one terminal hook follows 032 * each will hook during ordinary completion; status is absent only for validation or trusted management work. 033 * Terminal events describe the processing checkpoint before that hook runs. A hook that delays return or 034 * changes admission/clock health can still cause a subsequent release check to withhold normal output; 035 * that withholding does not emit a second terminal event. A successful event is not a delivery receipt. 036 * @since 1.0.0 037 */ 038@ThreadSafe 039public interface OAuthServerObserver { 040 /** Returns the shared observer whose hooks do nothing. 041 * @return disabled observer 042 * @since 1.0.0 043 */ 044 @CheckReturnValue static @NonNull OAuthServerObserver disabledInstance() { return DisabledOAuthServerObserver.INSTANCE; } 045 /** Called once after successful construction when the port-less HTTP localhost any-port option is enabled. 046 * This event carries no configuration or request data. 047 * @since 1.0.0 048 */ 049 default void didEnableLocalhostAnyPortRedirects() {} 050 /** Called once per authorization operation that relies on port-less HTTP localhost any-port matching. 051 * It runs before store work, even if a later admission check rejects the request. Exact matches allowed by 052 * the separate exact-localhost option do not use this relaxation. This event carries no request data. 053 * @since 1.0.0 054 */ 055 default void didUseLocalhostAnyPortRedirects() {} 056 /** Called before handling an operation. 057 * @param endpoint fixed operation kind 058 * @since 1.0.0 059 */ 060 default void willHandleEndpoint(@NonNull Endpoint endpoint) {} 061 /** Called after ordinary successful completion. 062 * @param endpoint fixed operation kind 063 * @param statusCode HTTP status or null for non-HTTP work 064 * @param elapsed monotonic elapsed duration 065 * @since 1.0.0 066 */ 067 default void didHandleEndpoint(@NonNull Endpoint endpoint, @Nullable Integer statusCode, @NonNull Duration elapsed) {} 068 /** Called after an expected rejection, including explicit application denial. 069 * @param endpoint fixed operation kind 070 * @param reason fixed rejection reason 071 * @param statusCode HTTP status or null for non-HTTP work 072 * @param elapsed monotonic elapsed duration 073 * @since 1.0.0 074 */ 075 default void didRejectEndpoint(@NonNull Endpoint endpoint, OAuthServerException.@NonNull Reason reason, 076 @Nullable Integer statusCode, @NonNull Duration elapsed) {} 077 /** Called after infrastructure failure; the same fixed exception reaches the caller. 078 * @param endpoint fixed operation kind 079 * @param failure fixed exception without external causes 080 * @param elapsed monotonic elapsed duration 081 * @since 1.0.0 082 */ 083 default void didFailToHandleEndpoint(@NonNull Endpoint endpoint, @NonNull OAuthServerException failure, @NonNull Duration elapsed) {} 084 /** Fixed operation kinds, without request or application data. 085 * @since 1.0.0 086 */ 087 @Immutable enum Endpoint { 088 /** Browser interaction work. */ AUTHORIZATION, 089 /** Code or refresh exchange. */ TOKEN, 090 /** Explicit fresh deployment initialization. */ ISSUER_INITIALIZATION, 091 /** Explicit first subject registration. */ SUBJECT_REGISTRATION, 092 /** Credential revocation. */ REVOCATION, 093 /** Registered-resource introspection. */ INTROSPECTION, 094 /** Public issuer metadata. */ METADATA, 095 /** Public verification keys. */ JWKS, 096 /** Online issuer access-token validation. */ ACCESS_TOKEN_VALIDATION, 097 /** Trusted grant invalidation. */ GRANT_REVOCATION, 098 /** Trusted subject invalidation. */ SUBJECT_REVOCATION, 099 /** Trusted issuer-wide invalidation. */ ISSUER_REVOCATION, 100 /** Trusted store maintenance. */ STORE_RESEAL 101 } 102} 103final class DisabledOAuthServerObserver implements OAuthServerObserver { 104 static final @NonNull OAuthServerObserver INSTANCE=new DisabledOAuthServerObserver(); 105 private DisabledOAuthServerObserver() {} 106}