Updated the branch

Author: tanya732

auth0-api-java/src/main/java/com/auth0/AuthCache.java

@@ -5,12 +5,11 @@
  * OIDC discovery metadata and JWKS providers.
  * <p>
  * The SDK ships with a default in-memory LRU implementation
- * ({@link InMemoryAuthCache}). Developers can implement this interface
+ * ({@link InMemoryAuthCache}). Users can implement this interface
  * to plug in distributed cache backends (e.g., Redis, Memcached) without
  * breaking changes to the SDK's public API.
  * </p>
  *
- * <h3>Unified cache with key prefixes</h3>
  * <p>
  * A single {@code AuthCache<Object>} instance can serve as a unified cache
  * for both discovery metadata and JWKS providers by using key prefixes:

auth0-api-java/src/main/java/com/auth0/ClaimValidator.java

@@ -6,10 +6,7 @@
 import java.util.*;
 
 /**
- * Utility class for JWT claim validation
- *
- * Provides functionality to validate JWT claims including scopes and custom
- * claim checks.
+ * Utility class for JWT claim validation. Provides functionality to validate JWT claims including scopes and custom claim checks.
  * This is the Java equivalent of the TypeScript claim validation utilities.
  */
 class ClaimValidator {
@@ -27,13 +24,11 @@ static Set<String> getClaimValues(DecodedJWT jwt, String claimName) throws BaseA
             throw new VerifyAccessTokenException("Required claim is missing");
         }
 
-        // Case 1: space-separated string
         String strValue = jwt.getClaim(claimName).asString();
         if (strValue != null) {
             return new HashSet<>(Arrays.asList(strValue.trim().split("\\s+")));
         }
 
-        // Case 2: list of strings
         List<String> listValue = jwt.getClaim(claimName).asList(String.class);
         if (listValue != null) {
             return new HashSet<>(listValue);

auth0-api-java/src/main/java/com/auth0/InMemoryAuthCache.java

@@ -61,7 +61,7 @@ public InMemoryAuthCache(int maxEntries, long ttlSeconds) {
             throw new IllegalArgumentException("ttlSeconds must not be negative");
         }
         this.ttlMillis = ttlSeconds * 1000;
-        // accessOrder=true makes LinkedHashMap maintain LRU order
+
         this.store = new LinkedHashMap<String, CacheEntry<V>>(maxEntries, 0.75f, true) {
             @Override
             protected boolean removeEldestEntry(Map.Entry<String, CacheEntry<V>> eldest) {
@@ -130,7 +130,7 @@ public int size() {
 
     private boolean isExpired(CacheEntry<V> entry) {
         if (ttlMillis == 0) {
-            return false; // TTL of 0 means no expiration
+            return false;
         }
         return (System.currentTimeMillis() - entry.createdAt) > ttlMillis;
     }

auth0-api-java/src/main/java/com/auth0/JWTValidator.java

@@ -133,11 +133,9 @@ public DecodedJWT validateToken(String token, HttpRequestInfo httpRequestInfo) t
 
             List<String> allowedDomains = resolveAllowedDomains(tokenIss, httpRequestInfo);
 
-            // Normalize the token issuer and allowed domains for consistent comparison
             String normalizedIss = normalizeToUrl(tokenIss);
             if (!allowedDomains.contains(normalizedIss)) {
-                throw new VerifyAccessTokenException(
-                        String.format("Token issuer '%s' is not in the allowed list: %s"));
+                throw new VerifyAccessTokenException("Token issuer is not in the allowed list");
             }
 
             OidcMetadata discovery = performOidcDiscovery(tokenIss);

auth0-api-java/src/main/java/com/auth0/examples/Auth0ApiExample.java

@@ -229,8 +229,7 @@ public Builder cacheTtlSeconds(long ttlSeconds) {
         }
 
         /**
-         * Sets a custom cache implementation for both OIDC discovery metadata
-         * and JWKS providers.
+         * Sets a custom cache implementation for both OIDC discovery metadata and JWKS providers.
          * <p>
          * The cache uses a unified key-prefix scheme:
          * <ul>
@@ -251,13 +250,11 @@ public Builder cache(AuthCache<Object> cache) {
         }
 
         public AuthOptions build() {
-            // Mutual exclusivity: domains and domainsResolver cannot both be set
             if (domains != null && !domains.isEmpty() && domainsResolver != null) {
                 throw new IllegalArgumentException(
                         "Cannot configure both 'domains' and 'domainsResolver'. Use one or the other.");
             }
 
-            // At least one domain source must be provided
             boolean hasDomain = domain != null && !domain.isEmpty();
             boolean hasDomains = domains != null && !domains.isEmpty();
             boolean hasResolver = domainsResolver != null;

auth0-api-java/src/main/java/com/auth0/models/AuthOptions.java

@@ -1,16 +1,7 @@
 package com.auth0.models;
 
 /**
- * Represents the relevant fields from an OIDC Discovery document
- * ({@code .well-known/openid-configuration}).
- * <p>
- * Only the fields required for JWT validation are extracted:
- * <ul>
- * <li>{@code issuer} — the canonical issuer identifier (used for
- * double-validation)</li>
- * <li>{@code jwks_uri} — the URL of the JSON Web Key Set (used to fetch signing
- * keys)</li>
- * </ul>
+ * Represents the relevant fields from the OIDC discovery document.
  */
 public class OidcMetadata {
 

auth0-api-java/src/main/java/com/auth0/models/OidcMetadata.java

@@ -4,21 +4,7 @@
 import java.util.Map;
 
 /**
- * Provides request context to the {@link com.auth0.DomainResolver} for dynamic
- * issuer resolution.
- * <p>
- * This is the "silver platter" passed to the developer's resolver function,
- * containing all the
- * data needed to make a routing decision in multi-custom-domain scenarios.
- * </p>
- *
- * <ul>
- * <li>{@code url} — The URL the API request was made to</li>
- * <li>{@code headers} — Relevant request headers (e.g., Host,
- * X-Forwarded-Host)</li>
- * <li>{@code tokenIssuer} — The <b>unverified</b> {@code iss} claim extracted
- * from the incoming JWT</li>
- * </ul>
+ * Contextual information about the incoming API request, provided to the domain resolver.
  */
 public class RequestContext {
 
@@ -54,12 +40,6 @@ public Map<String, String> getHeaders() {
 
     /**
      * Returns the unverified {@code iss} claim from the incoming JWT.
-     * <p>
-     * <b>Warning:</b> This value has NOT been verified yet. It is provided so the
-     * resolver
-     * can use it as a hint for routing decisions, but it must not be trusted on its
-     * own.
-     * </p>
      *
      * @return the unverified token issuer, or {@code null} if not available
      */

auth0-api-java/src/main/java/com/auth0/models/RequestContext.java

@@ -1,7 +1,7 @@
 package com.auth0.playground;
 
-import org.springframework.http.ResponseEntity;
 import com.auth0.spring.boot.Auth0AuthenticationToken;
+import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -16,7 +16,7 @@ public class ProfileController {
 
     @GetMapping("/protected")
     public ResponseEntity<Map<String, Object>> protectedEndpoint(Authentication authentication) {
-        String userId = authentication.getName(); // Returns the 'sub' claim
+        String userId = authentication.getName();
 
         return ResponseEntity.ok(Map.of(
                 "message", "Access granted!",

auth0-springboot-api-playground/src/main/java/com/auth0/playground/ProfileController.java

@@ -10,32 +10,7 @@
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.context.annotation.Bean;
 
-/**
- * Autoconfiguration for Auth0 authentication and JWT validation.
- *
- * <p>Supports three domain configuration modes (mutually exclusive):
- *
- * <ol>
- *   <li><b>Single domain</b> — set {@code auth0.domain} in YAML
- *   <li><b>Static MCD list</b> — set {@code auth0.domains} in YAML
- *   <li><b>Dynamic resolver</b> — define a {@link DomainResolver} bean
- * </ol>
- *
- * Dynamic Domain Resolver
- *
- * <p>To dynamically resolve allowed issuer domains at request time, define a bean implementing
- * {@link DomainResolver}:
- *
- * <pre>{@code
- * @Bean
- * public DomainResolver domainResolver() {
- *     return context -> {
- *         String tenantId = context.getHeaders().get("x-tenant-id");
- *         return lookupDomainsForTenant(tenantId);
- *     };
- * }
- * }</pre>
- */
+/** Autoconfiguration for Auth0 authentication and JWT validation. */
 @AutoConfiguration
 @EnableConfigurationProperties(Auth0Properties.class)
 public class Auth0AutoConfiguration {