Introduce authentication framework with AuthConfig, AuthGate, and Authenticator classes, alongside comprehensive tests for rules, modes, and schemes.

src/main/java/dev/coph/nextusweb/server/ratelimit/RateLimiter.java

@@ -8,6 +8,10 @@ package dev.coph.nextusweb.server.ratelimit;
  * {@link LeakyBucketLimiter}, {@link FixedWindowLimiter} and {@link SlidingWindowLimiter}.
  * Implementations are expected to be thread-safe, since the same limiter is shared across all
  * request-handling threads.</p>
+ *
+ * <p>The interface remains effectively functional ({@link #tryAcquire} is its single abstract
+ * method), so simple stateless limiters can still be written as a lambda; stateful limiters that
+ * keep one entry per key should additionally override {@link #cleanup(long)}.</p>
  */
 public interface RateLimiter {
 
@@ -21,6 +25,24 @@ public interface RateLimiter {
      */
     Result tryAcquire(String key, long nowNanos);
 
+    /**
+     * Evicts per-key state that has not been accessed within the given age, bounding the memory
+     * a limiter consumes when it has seen many distinct keys.
+     *
+     * <p>Implementations keep one entry per key seen ({@code clientIp}, API key, ...). Without
+     * periodic eviction those maps grow without bound, which is both a memory leak and a denial
+     * of service vector (an attacker that varies the key on every request can exhaust the heap).
+     * {@link RateLimitGate} calls this periodically for every configured limiter.</p>
+     *
+     * <p>The default implementation does nothing, which is correct for stateless limiters; any
+     * limiter that retains per-key state <strong>must</strong> override it to evict stale
+     * entries.</p>
+     *
+     * @param olderThanNanos maximum idle age in nanoseconds before an entry is removed
+     */
+    default void cleanup(long olderThanNanos) {
+    }
+
     /**
      * Immutable outcome of a {@link #tryAcquire(String, long)} call.
      *