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.jose;
018
019import com.revetsec.RevetsecException;
020import org.jspecify.annotations.NonNull;
021
022import javax.annotation.concurrent.ThreadSafe;
023import java.net.URI;
024import java.time.Duration;
025
026/**
027 * Receives events from {@link JwtValidator} and {@link RemoteJwksSource}, for metrics, logs and alerts.
028 * <p>
029 * Every hook is a {@code default} method that does nothing, so an implementation overrides only the hooks it needs.
030 * Hooks run synchronously on the calling thread, never while Revetsec holds a lock. Anything a hook throws is
031 * contained and does not affect the operation, except a {@link VirtualMachineError}. Keep hooks fast: a slow hook
032 * slows the call that fired it.
033 * <p>
034 * Hooks never receive a string taken from a token or a key set: no key ID, claim or header value. A key is named by
035 * its position in the set's {@code keys} array. URIs are cut to their scheme, host, port and path. Elapsed durations
036 * are measured with {@link System#nanoTime()}; {@code untilNextAttempt} follows the key source's
037 * {@link java.time.Clock}, and {@code timeToLive} comes from the response's cache headers within the source's limits.
038 * A failure hook receives the same exception instance the caller gets.
039 * <p>
040 * An observer may be called from many threads at once, so implementations must be thread-safe.
041 *
042 * @author <a href="https://www.revetkn.com">Mark Allen</a>
043 * @since 1.0.0
044 */
045@ThreadSafe
046public interface JoseObserver {
047        /**
048         * Returns an observer whose hooks do nothing: the default for every component that takes an observer.
049         *
050         * @return the shared observer that does nothing
051         * @since 1.0.0
052         */
053        @NonNull
054        static JoseObserver disabledInstance() {
055                return DisabledJoseObserver.INSTANCE;
056        }
057
058        /**
059         * Called just before a {@link RemoteJwksSource} sends a request for its key set, by the one caller that
060         * fetches it.
061         *
062         * @param jwksUri the key set's URI, cut to its scheme, host, port and path
063         * @since 1.0.0
064         */
065        default void willFetchJwks(@NonNull URI jwksUri) {
066                // Does nothing unless overridden.
067        }
068
069        /**
070         * Called when a key set fetch succeeded, by the one caller that fetched it. A key set in which every key was
071         * skipped still succeeds.
072         *
073         * @param jwksUri         the key set's URI, cut to its scheme, host, port and path
074         * @param usableKeyCount  how many keys are usable
075         * @param skippedKeyCount how many keys were skipped (each also reported to
076         *                        {@link #didSkipJwk(URI, Integer, JwkSkipReason)})
077         * @param timeToLive      how long the key set stays fresh, from the response's cache headers within the source's
078         *                        limits
079         * @param elapsed         how long the fetch took
080         * @since 1.0.0
081         */
082        default void didFetchJwks(@NonNull URI jwksUri,
083                                                                                                                                                 @NonNull Integer usableKeyCount,
084                                                                                                                                                 @NonNull Integer skippedKeyCount,
085                                                                                                                                                 @NonNull Duration timeToLive,
086                                                                                                                                                 @NonNull Duration elapsed) {
087                // Does nothing unless overridden.
088        }
089
090        /**
091         * Called when a key set fetch failed, by the one caller that fetched it.
092         *
093         * @param jwksUri          the key set's URI, cut to its scheme, host, port and path
094         * @param exception        the failure, the same instance that caller receives unless it is served stale keys
095         * @param servingStaleKeys whether the caller is served keys from the expired key set instead
096         * @param elapsed          how long the fetch took
097         * @since 1.0.0
098         */
099        default void didFailToFetchJwks(@NonNull URI jwksUri,
100                                                                                                                                                                         @NonNull JwksUnavailableException exception,
101                                                                                                                                                                         @NonNull Boolean servingStaleKeys,
102                                                                                                                                                                         @NonNull Duration elapsed) {
103                // Does nothing unless overridden.
104        }
105
106        /**
107         * Called on every call that needed a key set fetch but sent no request, because a recent failure, the unknown-key
108         * cooldown or the limit on attempts per cooldown held it back. Many of these in a short time can mean that
109         * someone is sending tokens with made-up key IDs.
110         *
111         * @param jwksUri          the key set's URI, cut to its scheme, host, port and path
112         * @param untilNextAttempt how long until a fetch may be sent again, on the source's clock
113         * @since 1.0.0
114         */
115        default void didSuppressJwksFetch(@NonNull URI jwksUri,
116                                                                                                                                                                                 @NonNull Duration untilNextAttempt) {
117                // Does nothing unless overridden.
118        }
119
120        /**
121         * Called for each key a fetched key set holds but Revetsec does not use, on every fetch. Some identity providers
122         * publish an encryption key beside their signing keys, so this hook can fire on every fetch in normal operation.
123         *
124         * @param jwksUri  the key set's URI, cut to its scheme, host, port and path
125         * @param keyIndex the key's zero-based position in the set's {@code keys} array
126         * @param reason   why the key is not used
127         * @since 1.0.0
128         */
129        default void didSkipJwk(@NonNull URI jwksUri,
130                                                                                                                                 @NonNull Integer keyIndex,
131                                                                                                                                 @NonNull JwkSkipReason reason) {
132                // Does nothing unless overridden.
133        }
134
135        /**
136         * Called when {@link JwtValidator#validateResult(String)} accepted a token.
137         *
138         * @param algorithm the token's algorithm
139         * @param elapsed   how long validation took, any key set fetch included
140         * @since 1.0.0
141         */
142        default void didValidateJwt(@NonNull JwsAlgorithm algorithm,
143                                                                                                                        @NonNull Duration elapsed) {
144                // Does nothing unless overridden.
145        }
146
147        /**
148         * Called when {@link JwtValidator#validateResult(String)} rejects a token or cannot get its keys, before returning the rejection or
149         * propagating the key-source failure.
150         *
151         * @param exception the fixed rejection diagnostic as a {@link JoseException}, or the
152         *                  {@link JwksUnavailableException} about to be thrown
153         * @param elapsed   how long validation took, any key set fetch included
154         * @since 1.0.0
155         */
156        default void didFailToValidateJwt(@NonNull RevetsecException exception,
157                                                                                                                                                @NonNull Duration elapsed) {
158                // Does nothing unless overridden.
159        }
160
161        /**
162         * Called when a validator configured to accept any audience is built, and on each of its validations, because
163         * accepting any audience lets a token issued for another application through.
164         *
165         * @param issuer the validator's expected issuer
166         * @since 1.0.0
167         */
168        default void didAcceptAnyAudience(@NonNull String issuer) {
169                // Does nothing unless overridden.
170        }
171
172        /**
173         * Called when a component that acknowledged running below Revetsec's minimum Java runtime version is built, and
174         * on each of its fetches.
175         *
176         * @param runtimeVersion the running Java version, such as {@code 17.0.2}
177         * @since 1.0.0
178         */
179        default void didUseUnpatchedRuntime(@NonNull String runtimeVersion) {
180                // Does nothing unless overridden.
181        }
182}