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}