Renaming, + Updated documentation

Author: artem-v

jwt/src/main/java/io/scalecube/security/jwt/JwksKeyLocator.java renamed to jwt/src/main/java/io/scalecube/security/jwt/JwksKeyProvider.java

@@ -27,7 +27,11 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.locks.ReentrantLock;
 
-public class JwksKeyLocator {
+/**
+ * Provides public keys from a remote JWKS endpoint and caches them temporarily. Keys are fetched on
+ * demand by their {@code kid} and automatically removed when expired.
+ */
+public class JwksKeyProvider {
 
   private static final ObjectMapper OBJECT_MAPPER = newObjectMapper();
 
@@ -40,7 +44,7 @@ public class JwksKeyLocator {
   private final Map<String, CachedKey> keyResolutions = new ConcurrentHashMap<>();
   private final ReentrantLock cleanupLock = new ReentrantLock();
 
-  private JwksKeyLocator(Builder builder) {
+  private JwksKeyProvider(Builder builder) {
     this.jwksUri = Objects.requireNonNull(builder.jwksUri, "jwksUri");
     this.connectTimeout = Objects.requireNonNull(builder.connectTimeout, "connectTimeout");
     this.requestTimeout = Objects.requireNonNull(builder.requestTimeout, "requestTimeout");
@@ -55,7 +59,15 @@ public static Builder builder() {
     return new Builder();
   }
 
-  public Key locate(String kid) {
+  /**
+   * Returns the public key for the given {@code kid}. If not cached, the key is fetched from the
+   * JWKS endpoint and cached for future use.
+   *
+   * @param kid key id of the public key to retrieve
+   * @return {@link Key} object associated with given {@code kid}
+   * @throws JwtUnavailableException if key cannot be found or JWKS cannot be retrieved
+   */
+  public Key getKey(String kid) {
     try {
       return keyResolutions
           .computeIfAbsent(
@@ -226,8 +238,8 @@ public Builder httpClient(HttpClient httpClient) {
       return this;
     }
 
-    public JwksKeyLocator build() {
-      return new JwksKeyLocator(this);
+    public JwksKeyProvider build() {
+      return new JwksKeyProvider(this);
     }
   }
 }

jwt/src/main/java/io/scalecube/security/jwt/JsonwebtokenResolver.java renamed to jwt/src/main/java/io/scalecube/security/jwt/JwksTokenResolver.java

@@ -7,14 +7,18 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-public class JsonwebtokenResolver implements JwtTokenResolver {
+/**
+ * Resolves and verifies JWT tokens using public keys provided by {@link JwksKeyProvider}. Tokens
+ * are validated asynchronously and parsed into {@link JwtToken} instances.
+ */
+public class JwksTokenResolver implements JwtTokenResolver {
 
-  private static final Logger LOGGER = LoggerFactory.getLogger(JsonwebtokenResolver.class);
+  private static final Logger LOGGER = LoggerFactory.getLogger(JwksTokenResolver.class);
 
-  private final JwksKeyLocator keyLocator;
+  private final JwksKeyProvider keyProvider;
 
-  public JsonwebtokenResolver(JwksKeyLocator keyLocator) {
-    this.keyLocator = keyLocator;
+  public JwksTokenResolver(JwksKeyProvider keyProvider) {
+    this.keyProvider = keyProvider;
   }
 
   @Override
@@ -23,7 +27,7 @@ public CompletableFuture<JwtToken> resolveToken(String token) {
             () -> {
               final var rawToken = JWT.decode(token);
               final var kid = rawToken.getKeyId();
-              final var publicKey = (RSAPublicKey) keyLocator.locate(kid);
+              final var publicKey = (RSAPublicKey) keyProvider.getKey(kid);
               final var verifier = JWT.require(Algorithm.RSA256(publicKey, null)).build();
               verifier.verify(token);
               return JwtToken.parseToken(token);

jwt/src/main/java/io/scalecube/security/jwt/JwtToken.java

@@ -6,13 +6,19 @@
 import java.util.Base64;
 import java.util.Map;
 
+/**
+ * Represents parsed JWT (JSON Web Token), including its header and payload claims.
+ *
+ * @param header JWT header as map of key-value pairs
+ * @param payload JWT payload (claims) as map of key-value pairs
+ */
 public record JwtToken(Map<String, Object> header, Map<String, Object> payload) {
 
   /**
    * Parses given JWT without verifying its signature.
    *
    * @param token jwt token
-   * @return parsed token
+   * @return {@link JwtToken} object, or {@link JwtTokenException} will be thrown
    */
   public static JwtToken parseToken(String token) {
     String[] parts = token.split("\\.");

jwt/src/main/java/io/scalecube/security/jwt/JwtTokenResolver.java

@@ -2,13 +2,18 @@
 
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * Resolves and verifies JWT tokens asynchronously. Implementations parse the token, validate its
+ * signature, and extract claims.
+ */
 public interface JwtTokenResolver {
 
   /**
    * Verifies given JWT and parses its header and claims.
    *
    * @param token jwt token
-   * @return async result with {@link JwtToken}, or error
+   * @return async result completing with {@link JwtToken}, or completing exceptionally with {@link
+   *     JwtTokenException} on failure
    */
   CompletableFuture<JwtToken> resolveToken(String token);
 }

tests/src/test/java/io/scalecube/security/jwt/JsonwebtokenResolverTests.java renamed to tests/src/test/java/io/scalecube/security/jwt/JwksTokenResolverTests.java

@@ -19,15 +19,15 @@
 import org.junit.jupiter.api.extension.ExtendWith;
 
 @ExtendWith(IntegrationEnvironmentFixture.class)
-public class JsonwebtokenResolverTests {
+public class JwksTokenResolverTests {
 
   @Test
   void testResolveTokenTokenSuccessfully(VaultEnvironment vaultEnvironment) throws Exception {
     final var token = vaultEnvironment.newServiceToken();
 
     final var jwtToken =
-        new JsonwebtokenResolver(
-                JwksKeyLocator.builder()
+        new JwksTokenResolver(
+                JwksKeyProvider.builder()
                     .jwksUri(vaultEnvironment.jwksUri())
                     .connectTimeout(Duration.ofSeconds(3))
                     .requestTimeout(Duration.ofSeconds(3))
@@ -53,14 +53,14 @@ void testParseTokenSuccessfully(VaultEnvironment vaultEnvironment) {
   }
 
   @Test
-  void testJwksKeyLocatorThrowsError(VaultEnvironment vaultEnvironment) {
+  void testJwksKeyProviderThrowsError(VaultEnvironment vaultEnvironment) {
     final var token = vaultEnvironment.newServiceToken();
 
-    final var keyLocator = mock(JwksKeyLocator.class);
-    when(keyLocator.locate(any())).thenThrow(new RuntimeException("Cannot get key"));
+    final var keyProvider = mock(JwksKeyProvider.class);
+    when(keyProvider.getKey(any())).thenThrow(new RuntimeException("Cannot get key"));
 
     try {
-      new JsonwebtokenResolver(keyLocator).resolveToken(token).get(3, TimeUnit.SECONDS);
+      new JwksTokenResolver(keyProvider).resolveToken(token).get(3, TimeUnit.SECONDS);
       fail("Expected exception");
     } catch (Exception e) {
       final var ex = getRootCause(e);
@@ -70,14 +70,14 @@ void testJwksKeyLocatorThrowsError(VaultEnvironment vaultEnvironment) {
   }
 
   @Test
-  void testJwksKeyLocatorThrowsRetryableError(VaultEnvironment vaultEnvironment) {
+  void testJwksKeyProviderThrowsRetryableError(VaultEnvironment vaultEnvironment) {
     final var token = vaultEnvironment.newServiceToken();
 
-    final var keyLocator = mock(JwksKeyLocator.class);
-    when(keyLocator.locate(any())).thenThrow(new JwtUnavailableException("JWKS timeout"));
+    final var keyProvider = mock(JwksKeyProvider.class);
+    when(keyProvider.getKey(any())).thenThrow(new JwtUnavailableException("JWKS timeout"));
 
     try {
-      new JsonwebtokenResolver(keyLocator).resolveToken(token).get(3, TimeUnit.SECONDS);
+      new JwksTokenResolver(keyProvider).resolveToken(token).get(3, TimeUnit.SECONDS);
       fail("Expected exception");
     } catch (Exception e) {
       final var ex = getRootCause(e);

tests/src/test/java/io/scalecube/security/vault/VaultServiceTokenTests.java

@@ -11,8 +11,8 @@
 
 import io.scalecube.security.environment.IntegrationEnvironmentFixture;
 import io.scalecube.security.environment.VaultEnvironment;
-import io.scalecube.security.jwt.JsonwebtokenResolver;
-import io.scalecube.security.jwt.JwksKeyLocator;
+import io.scalecube.security.jwt.JwksKeyProvider;
+import io.scalecube.security.jwt.JwksTokenResolver;
 import io.scalecube.security.vault.VaultServiceRolesInstaller.ServiceRoles;
 import io.scalecube.security.vault.VaultServiceRolesInstaller.ServiceRoles.Role;
 import java.util.Collections;
@@ -141,8 +141,7 @@ void testGetServiceTokenSuccessfully(VaultEnvironment vaultEnvironment) throws E
     // Verify serviceToken
 
     final var jwtToken =
-        new JsonwebtokenResolver(
-                JwksKeyLocator.builder().jwksUri(vaultEnvironment.jwksUri()).build())
+        new JwksTokenResolver(JwksKeyProvider.builder().jwksUri(vaultEnvironment.jwksUri()).build())
             .resolveToken(serviceToken)
             .get(3, TimeUnit.SECONDS);