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; 018 019import com.revetsec.jose.JoseObserver; 020import org.jspecify.annotations.NonNull; 021 022import javax.annotation.concurrent.ThreadSafe; 023import java.net.URI; 024import java.time.Duration; 025 026/** 027 * Receives synchronous, caller-thread OAuth events. Endpoint URIs contain only scheme, host, port and path; 028 * callbacks and request bodies are never passed. Implementations must be thread-safe and fast. A hook failure is 029 * contained by the caller except for {@link VirtualMachineError}. 030 * 031 * @author <a href="https://www.revetkn.com">Mark Allen</a> 032 * @since 1.0.0 033 */ 034@ThreadSafe 035public interface OAuthObserver extends JoseObserver { 036 /** 037 * Returns an observer whose hooks do nothing. 038 * 039 * @return the disabled observer 040 * @since 1.0.0 041 */ 042 @NonNull 043 static OAuthObserver disabledInstance() { return DisabledOAuthObserver.INSTANCE; } 044 045 /** 046 * Called after a browser authorization URL is prepared. 047 * 048 * @param endpoint its reduced endpoint URI 049 * @since 1.0.0 050 */ 051 default void didBeginAuthorization(@NonNull URI endpoint) { } 052 053 /** 054 * Called before an OAuth endpoint request. 055 * 056 * @param endpoint endpoint kind 057 * @param uri its reduced URI 058 * @since 1.0.0 059 */ 060 default void willRequestEndpoint(@NonNull OAuthEndpoint endpoint, @NonNull URI uri) { } 061 062 /** 063 * Called after a completed endpoint request. 064 * 065 * @param endpoint endpoint kind 066 * @param uri its reduced URI 067 * @param status HTTP status 068 * @param elapsed elapsed duration 069 * @since 1.0.0 070 */ 071 default void didRequestEndpoint(@NonNull OAuthEndpoint endpoint, @NonNull URI uri, 072 @NonNull Integer status, @NonNull Duration elapsed) { } 073 074 /** 075 * Called when an endpoint request fails. The exception is the same instance the caller receives. 076 * 077 * @param endpoint endpoint kind 078 * @param uri its reduced URI 079 * @param exception fixed-message exception 080 * @param elapsed elapsed duration 081 * @since 1.0.0 082 */ 083 default void didFailEndpoint(@NonNull OAuthEndpoint endpoint, @NonNull URI uri, 084 @NonNull OAuthException exception, @NonNull Duration elapsed) { } 085 086 /** 087 * Called when a callback fails a local validation check. 088 * 089 * @param exception fixed-message exception 090 * @since 1.0.0 091 */ 092 default void didRejectCallback(@NonNull OAuthValidationException exception) { } 093 094 /** 095 * Called when the explicit unencoded Basic interoperability mode is configured and on every request using it. 096 * No credential value is passed. 097 * 098 * @since 1.0.0 099 */ 100 default void didUseUnencodedBasic() { } 101 /** 102 * Called once after a client successfully enables endpoint-audience assertion compatibility. 103 * @param audience TOKEN_ENDPOINT compatibility selection 104 * @since 1.0.0 105 */ 106 default void didEnableClientAssertionAudience(@NonNull ClientAssertionAudience audience) { } 107 /** 108 * Called when endpoint-audience compatibility is selected for an actual assertion operation, including failure. 109 * @param audience TOKEN_ENDPOINT compatibility selection 110 * @since 1.0.0 111 */ 112 default void didUseClientAssertionAudience(@NonNull ClientAssertionAudience audience) { } 113 /** 114 * Called once for assertion preparation failure before any endpoint will event. The same fixed-message 115 * exception is received by the caller; no assertion or key is passed. 116 * @param endpoint selected POST role 117 * @param exception preparation failure 118 * @since 1.0.0 119 */ 120 default void didFailClientAssertionPreparation(@NonNull OAuthEndpoint endpoint, @NonNull OAuthException exception) { } 121 122}