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.oidc;
018
019import com.revetsec.oauth.OAuthObserver;
020import org.jspecify.annotations.NonNull;
021import javax.annotation.concurrent.ThreadSafe;
022
023/**
024 * Receives caller-thread OIDC events and the inherited OAuth/JOSE endpoint events. Hooks carry no tokens or claims.
025 * Hook failures are contained except for VirtualMachineError; implementations must be thread-safe and fast.
026 *
027 * @author <a href="https://www.revetkn.com">Mark Allen</a>
028 * @since 1.0.0
029 */
030@ThreadSafe
031public interface OidcObserver extends OAuthObserver {
032        /**
033         * Returns a silent observer.
034         * @return the disabled observer
035         * @since 1.0.0
036         */
037        static @NonNull OidcObserver disabledInstance() { return DisabledOidcObserver.INSTANCE; }
038        /**
039         * Called after a client successfully builds with an explicit compatibility mode.
040         * @param mode enabled mode; no credential is passed
041         * @since 1.0.0
042         */
043        default void didEnableCompatibilityMode(@NonNull OidcCompatibilityMode mode) { }
044        /**
045         * Called when validation uses the mode, including when its signature or later checks fail.
046         * @param mode used mode; no credential or token is passed
047         * @since 1.0.0
048         */
049        default void didUseCompatibilityMode(@NonNull OidcCompatibilityMode mode) { }
050        /**
051         * Called when an ID token or OIDC token response fails validation, before token release.
052         * @param exception the same fixed-message exception the caller receives
053         * @since 1.0.0
054         */
055        default void didRejectIdToken(@NonNull OidcValidationException exception) { }
056        /**
057         * Called after successful OIDC validation. No identity or credential is passed.
058         * @since 1.0.0
059         */
060        default void didCompleteAuthentication() { }
061        /**
062         * Called when a UserInfo response fails profile validation. No claims or credentials are passed.
063         * @param exception fixed-message rejection
064         * @since 1.0.0
065         */
066        default void didRejectUserInfo(@NonNull OidcValidationException exception) { }
067        /**
068         * Called after the UserInfo subject matches the verified authentication.
069         * @param signed whether a signed response was validated
070         * @since 1.0.0
071         */
072        default void didFetchUserInfo(@NonNull Boolean signed) { }
073        /**
074         * Called when refresh profile/continuity checks reject. No endpoint credential or rejected claim is passed.
075         * @param exception fixed-message rejection
076         * @since 1.0.0
077         */
078        default void didRejectRefresh(@NonNull OidcValidationException exception) { }
079        /**
080         * Called after refresh tokens are released following all required ID-token checks.
081         * @param idTokenReturned whether a new verified ID token was returned
082         * @param refreshTokenReturned whether the endpoint supplied a replacement refresh token
083         * @since 1.0.0
084         */
085        default void didRefreshTokens(@NonNull Boolean idTokenReturned, @NonNull Boolean refreshTokenReturned) { }
086
087        /**
088         * Called once after successful build selects the fixed Entra issuer policy.
089         * @since 1.0.0
090         */
091        default void didEnableMicrosoftEntraMultiTenant() { }
092        /**
093         * Called when Entra ID-token validation or an authenticated UserInfo tenant check uses the selected policy,
094         * including rejected outcomes. No tenant or credential is supplied.
095         * @since 1.0.0
096         */
097        default void didUseMicrosoftEntraMultiTenant() { }
098
099}