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 */
016package com.revetsec.oauth;
017
018import com.revetsec.jose.*;
019import com.revetsec.json.*;
020import java.time.*;
021import java.util.*;
022import javax.annotation.concurrent.ThreadSafe;
023import org.jspecify.annotations.NonNull;
024
025/**
026 * Caller-thread resource events and inherited OAuth/JOSE events, without credentials or claims.
027 * Hooks must be fast and thread-safe; callers contain failures except VirtualMachineError.
028 * @author <a href="https://www.revetkn.com">Mark Allen</a>
029 * @since 1.0.0
030 */
031@ThreadSafe
032public interface AccessTokenObserver extends OAuthObserver {
033
034        /**
035         * Returns a silent observer.
036         * @return observer
037         * @since 1.0.0
038         */
039        @NonNull
040        static AccessTokenObserver disabledInstance() {
041                return DisabledAccessTokenObserver.INSTANCE;
042        }
043
044        /**
045         * Reports successful build with the explicit mode.
046         * @param mode enabled mode
047         * @since 1.0.0
048         */
049        default void didEnableCompatibilityMode(@NonNull AccessTokenCompatibilityMode mode) {
050        }
051
052        /**
053         * Reports actual mode use, including a later rejection.
054         * @param mode used mode
055         * @since 1.0.0
056         */
057        default void didUseCompatibilityMode(@NonNull AccessTokenCompatibilityMode mode) {
058        }
059
060        /**
061         * Reports successful profile validation; releases no result or identity.
062         * @since 1.0.0
063         */
064        default void didValidateAccessToken() {
065        }
066
067        /**
068         * Reports a fixed local rejection, never infrastructure failure.
069         * @param exception same fixed-message rejection the caller receives
070         * @since 1.0.0
071         */
072        default void didRejectAccessToken(@NonNull AccessTokenValidationException exception) {
073        }
074}