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

src/main/java/dev/coph/nextusweb/server/websocket/WebSocketSession.java

@@ -1,5 +1,6 @@
 package dev.coph.nextusweb.server.websocket;
 
+import dev.coph.nextusweb.server.auth.Principal;
 import dev.coph.nextusweb.server.json.JsonMapper;
 import io.netty.buffer.ByteBuf;
 import io.netty.buffer.Unpooled;
@@ -47,6 +48,8 @@ public final class WebSocketSession {
     private final String path;
     /** Path parameters captured during routing, keyed by name. */
     private final Map<String, String> pathParams;
+    /** Authenticated principal for this connection, or {@code null} if anonymous. */
+    private final Principal principal;
     /** Thread-safe bag of user-defined attributes attached to the session. */
     private final Map<String, Object> attributes = new ConcurrentHashMap<>();
 
@@ -57,12 +60,14 @@ public final class WebSocketSession {
      * @param channel    the underlying Netty channel
      * @param path       the connection path
      * @param pathParams the path parameters captured during routing
+     * @param principal  the authenticated principal, or {@code null} if the connection is anonymous
      */
-    WebSocketSession(Channel channel, String path, Map<String, String> pathParams) {
+    WebSocketSession(Channel channel, String path, Map<String, String> pathParams, Principal principal) {
         this.channel = channel;
         this.id = UUID.randomUUID().toString();
         this.path = path;
         this.pathParams = pathParams;
+        this.principal = principal;
     }
 
     /**
@@ -93,6 +98,16 @@ public final class WebSocketSession {
         return pathParams.get(name);
     }
 
+    /**
+     * Returns the authenticated principal associated with this connection, established by the auth
+     * layer during the upgrade handshake.
+     *
+     * @return the principal, or {@code null} if the connection is anonymous
+     */
+    public Principal principal() {
+        return principal;
+    }
+
     /**
      * Indicates whether the connection is still open.
      *