From 146a0fb8b0e90f9196e569152f649baf60d6cc8f Mon Sep 17 00:00:00 2001
From: Joaquín Reñé <jrene@curisit.net>
Date: Tue, 07 Oct 2025 14:52:57 +0000
Subject: [PATCH] #4410 - Comments on classes

---
 securis/src/main/java/net/curisit/securis/AuthFilter.java |   80 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 80 insertions(+), 0 deletions(-)

diff --git a/securis/src/main/java/net/curisit/securis/AuthFilter.java b/securis/src/main/java/net/curisit/securis/AuthFilter.java
index 48acee4..28a2c7f 100644
--- a/securis/src/main/java/net/curisit/securis/AuthFilter.java
+++ b/securis/src/main/java/net/curisit/securis/AuthFilter.java
@@ -1,3 +1,6 @@
+/*
+ * Copyright @ 2013 CurisTEC, S.A.S. All Rights Reserved.
+ */
 package net.curisit.securis;
 
 import java.io.IOException;
@@ -17,16 +20,63 @@
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 
+/**
+* AuthFilter
+* <p>
+* Simple authentication/role wrapper for development and lightweight scenarios.
+* If a request parameter <code>user</code> or a session attribute <code>user</code>
+* is present, this filter wraps the current request with a custom {@link Principal}
+* and an ad-hoc role. The role assignment is temporary and follows the rule:
+* <ul>
+* <li>user == "advance" → role "advance"</li>
+* <li>otherwise → role "normal"</li>
+* </ul>
+* If no user is present, the request continues unmodified.
+*
+* <p><b>Security note:</b> This filter trusts a user name coming from a request parameter,
+* which must not be used in production. Replace with a proper authentication mechanism
+* (e.g., JWT, container security, SSO) and derive roles from authoritative claims.
+*
+* @author JRA
+* Last reviewed by JRA on Oct 6, 2025.
+*/
 @ApplicationScoped
 @WebFilter(urlPatterns = "/*")
 public class AuthFilter implements Filter {
 
     private static final Logger LOG = LogManager.getLogger(AuthFilter.class);
 
+    // ---------------------------------------------------------------------
+    // Lifecycle
+    // ---------------------------------------------------------------------
+    
+    /** 
+     * init<p>
+     * Filter initialization hook (unused). 
+     */
     @Override
     public void init(FilterConfig fc) throws ServletException {
     }
 
+    // ---------------------------------------------------------------------
+    // Filtering
+    // ---------------------------------------------------------------------
+
+
+    /**
+     * doFilter
+     * <p>
+     * If a user is detected (request param or session attribute), wrap the request to:
+     * <ul>
+     * <li>Expose a {@link Principal} with the provided username.</li>
+     * <li>Report a single role through {@link HttpServletRequest#isUserInRole(String)}.</li>
+     * </ul>
+     * Otherwise, pass-through.
+     *
+     * @param sr incoming request
+     * @param sr1 outgoing response
+     * @param fc filter chain
+     */
     @Override
     public void doFilter(ServletRequest sr, ServletResponse sr1, FilterChain fc) throws IOException, ServletException {
         HttpServletRequest req = (HttpServletRequest) sr;
@@ -46,21 +96,46 @@
 
     }
 
+    /** 
+     * destroy<p>
+     * Filter destruction hook (unused). 
+     */
     @Override
     public void destroy() {
     }
 
+     // ---------------------------------------------------------------------
+     // Wrapper
+     // ---------------------------------------------------------------------
+
+     /**
+      * UserRoleRequestWrapper
+      * <p>
+      * Wrapper that overrides role checks and the user principal when a synthetic user is present.
+      */
     private class UserRoleRequestWrapper extends HttpServletRequestWrapper {
 
         private String role;
         private String user;
 
+        /**
+        * Constructor
+        * <p>
+        * @param role single role to expose via {@link #isUserInRole(String)}
+        * @param user user name to expose via {@link #getUserPrincipal()}
+        * @param request original request to wrap
+        */
         public UserRoleRequestWrapper(String role, String user, HttpServletRequest request) {
             super(request);
             this.role = role;
             this.user = user;
         }
 
+        /**
+        * isUserInRole
+        * <p>
+        * Returns {@code true} if the requested role equals the configured synthetic role.
+        */
         @Override
         public boolean isUserInRole(String role) {
             LOG.info("isUserRole METHOD: {}, {}", role, this.role);
@@ -70,6 +145,11 @@
             return this.role.equals(role);
         }
 
+        /**
+        * getUserPrincipal
+        * <p>
+        * Returns a minimal {@link Principal} with the configured user name; delegates otherwise.
+        */
         @Override
         public Principal getUserPrincipal() {
             if (this.user == null) {

--
Gitblit v1.3.2