Feat: Added MCD Support

Author: tanya732

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

@@ -0,0 +1,44 @@
+package com.auth0;
+
+import com.auth0.models.RequestContext;
+
+import java.util.List;
+
+/**
+ * Functional interface for dynamically resolving allowed issuer domains
+ * based on the incoming request context.
+ * <p>
+ * Used in multi-custom-domain (MCD) scenarios where the set of valid issuers
+ * cannot be determined statically at configuration time. The resolver receives
+ * a {@link RequestContext} containing the request URL, headers, and the
+ * unverified token issuer, and returns the list of allowed issuer domains.
+ * </p>
+ *
+ * <pre>{@code
+ * AuthOptions options = new AuthOptions.Builder()
+ *         .domainsResolver(context -> {
+ *             String host = context.getHeaders().get("host");
+ *             return lookupIssuersForHost(host);
+ *         })
+ *         .audience("https://api.example.com")
+ *         .build();
+ * }</pre>
+ *
+ * @see RequestContext
+ * @see com.auth0.models.AuthOptions.Builder#domainsResolver(DomainResolver)
+ */
+@FunctionalInterface
+public interface DomainResolver {
+
+    /**
+     * Resolves the list of allowed issuer domains for the given request context.
+     *
+     * @param context the request context containing URL, headers, and unverified
+     *                token issuer
+     * @return a list of allowed issuer domain strings (e.g.,
+     *         {@code ["https://tenant1.auth0.com/"]});
+     *         may return {@code null} or an empty list if no domains can be
+     *         resolved
+     */
+    List<String> resolveDomains(RequestContext context);
+}

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

@@ -0,0 +1,66 @@
+package com.auth0.cache;
+
+/**
+ * Cache abstraction for storing authentication-related data such as
+ * OIDC discovery metadata and JWKS providers.
+ * <p>
+ * The SDK ships with a default in-memory LRU implementation
+ * ({@link InMemoryAuthCache}). Developers 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:
+ * </p>
+ * <ul>
+ * <li>{@code discovery:{issuerUrl}} — OIDC discovery metadata</li>
+ * <li>{@code jwks:{jwksUri}} — JwkProvider instances</li>
+ * </ul>
+ *
+ * <h3>Thread Safety</h3>
+ * <p>
+ * All implementations <b>must</b> be thread-safe.
+ * </p>
+ *
+ * @param <V> the type of cached values
+ */
+public interface AuthCache<V> {
+
+    /**
+     * Retrieves a value from the cache.
+     *
+     * @param key the cache key
+     * @return the cached value, or {@code null} if not present or expired
+     */
+    V get(String key);
+
+    /**
+     * Stores a value in the cache with the cache's default TTL.
+     *
+     * @param key   the cache key
+     * @param value the value to cache
+     */
+    void put(String key, V value);
+
+    /**
+     * Removes a specific entry from the cache.
+     *
+     * @param key the cache key to remove
+     */
+    void remove(String key);
+
+    /**
+     * Removes all entries from the cache.
+     */
+    void clear();
+
+    /**
+     * Returns the number of entries currently in the cache.
+     *
+     * @return the cache size
+     */
+    int size();
+}

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

@@ -0,0 +1,150 @@
+package com.auth0.cache;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.concurrent.locks.ReentrantReadWriteLock;
+
+/**
+ * Thread-safe, in-memory LRU cache with TTL expiration.
+ * <p>
+ * This is the default {@link AuthCache} implementation shipped with the SDK.
+ * It uses a {@link LinkedHashMap} in access-order mode for LRU eviction and
+ * per-entry timestamps for TTL enforcement.
+ * </p>
+ *
+ * <h3>Configuration</h3>
+ * <ul>
+ * <li><b>maxEntries</b> — maximum number of entries; LRU eviction when exceeded
+ * (default: 100)</li>
+ * <li><b>ttlSeconds</b> — time-to-live per entry in seconds (default: 600 = 10
+ * minutes)</li>
+ * </ul>
+ *
+ * <h3>Thread Safety</h3>
+ * <p>
+ * Uses a {@link ReentrantReadWriteLock} so concurrent reads do not block each
+ * other,
+ * while writes acquire exclusive access.
+ * </p>
+ *
+ * @param <V> the type of cached values
+ */
+public class InMemoryAuthCache<V> implements AuthCache<V> {
+
+    /** Default maximum number of entries. */
+    public static final int DEFAULT_MAX_ENTRIES = 100;
+
+    public static final long DEFAULT_TTL_SECONDS = 600;
+
+    private final long ttlMillis;
+    private final LinkedHashMap<String, CacheEntry<V>> store;
+    private final ReentrantReadWriteLock lock = new ReentrantReadWriteLock();
+
+    /**
+     * Creates a cache with default settings (100 entries, 10-minute TTL).
+     */
+    public InMemoryAuthCache() {
+        this(DEFAULT_MAX_ENTRIES, DEFAULT_TTL_SECONDS);
+    }
+
+    /**
+     * Creates a cache with the specified limits.
+     *
+     * @param maxEntries maximum number of entries before LRU eviction
+     * @param ttlSeconds time-to-live per entry in seconds
+     */
+    public InMemoryAuthCache(int maxEntries, long ttlSeconds) {
+        if (maxEntries <= 0) {
+            throw new IllegalArgumentException("maxEntries must be positive");
+        }
+        if (ttlSeconds < 0) {
+            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) {
+                return size() > maxEntries;
+            }
+        };
+    }
+
+    @Override
+    public V get(String key) {
+        lock.writeLock().lock();
+        try {
+            CacheEntry<V> entry = store.get(key);
+            if (entry == null) {
+                return null;
+            }
+            if (isExpired(entry)) {
+                store.remove(key);
+                return null;
+            }
+            return entry.value;
+        } finally {
+            lock.writeLock().unlock();
+        }
+    }
+
+    @Override
+    public void put(String key, V value) {
+        lock.writeLock().lock();
+        try {
+            store.put(key, new CacheEntry<>(value, System.currentTimeMillis()));
+        } finally {
+            lock.writeLock().unlock();
+        }
+    }
+
+    @Override
+    public void remove(String key) {
+        lock.writeLock().lock();
+        try {
+            store.remove(key);
+        } finally {
+            lock.writeLock().unlock();
+        }
+    }
+
+    @Override
+    public void clear() {
+        lock.writeLock().lock();
+        try {
+            store.clear();
+        } finally {
+            lock.writeLock().unlock();
+        }
+    }
+
+    @Override
+    public int size() {
+        lock.readLock().lock();
+        try {
+            return store.size();
+        } finally {
+            lock.readLock().unlock();
+        }
+    }
+
+    private boolean isExpired(CacheEntry<V> entry) {
+        if (ttlMillis == 0) {
+            return false; // TTL of 0 means no expiration
+        }
+        return (System.currentTimeMillis() - entry.createdAt) > ttlMillis;
+    }
+
+    /**
+     * Internal wrapper that pairs a value with its insertion timestamp.
+     */
+    private static final class CacheEntry<V> {
+        final V value;
+        final long createdAt;
+
+        CacheEntry(V value, long createdAt) {
+            this.value = value;
+            this.createdAt = createdAt;
+        }
+    }
+}

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

@@ -1,19 +1,24 @@
 package com.auth0.examples;
 
 import com.auth0.AuthClient;
+import com.auth0.DomainResolver;
 import com.auth0.enums.DPoPMode;
 import com.auth0.exception.BaseAuthException;
 import com.auth0.models.AuthOptions;
 import com.auth0.models.AuthenticationContext;
 import com.auth0.models.HttpRequestInfo;
+import com.auth0.models.RequestContext;
 import com.sun.net.httpserver.HttpExchange;
 import com.sun.net.httpserver.HttpHandler;
 import com.sun.net.httpserver.HttpServer;
 
 import java.io.IOException;
 import java.io.OutputStream;
 import java.net.InetSocketAddress;
+import java.util.Arrays;
+import java.util.Collections;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 
 public class Auth0ApiExample {
@@ -88,30 +93,26 @@ public void handle(HttpExchange exchange) throws IOException {
 
             headers.put("authorization", auth);
 
-
             String dpopHeader = exchange.getRequestHeaders().getFirst("DPoP");
 
-            if(dpopHeader != null) {
+            if (dpopHeader != null) {
                 headers.put("DPoP", dpopHeader);
             }
 
-
             // Build HttpRequestInfo (needed for DPoP htm + htu validation)
             HttpRequestInfo requestInfo = null;
             try {
                 requestInfo = new HttpRequestInfo(
                         exchange.getRequestMethod(),
-                        "http://localhost:8000" + exchange.getRequestURI().toString(), headers
-                );
+                        "http://localhost:8000" + exchange.getRequestURI().toString(), headers);
             } catch (BaseAuthException e) {
                 throw new RuntimeException(e);
             }
 
             System.out.println("Incoming request to " + requestInfo.toString());
 
             try {
-                AuthenticationContext claims =
-                        authClient.verifyRequest(requestInfo);
+                AuthenticationContext claims = authClient.verifyRequest(requestInfo);
 
                 String user = (String) claims.getClaims().get("sub");