#4410 - Comments on classes

Joaquín Reñé

2025-10-07 146a0fb8b0e90f9196e569152f649baf60d6cc8f

 securis/src/main/java/net/curisit/securis/AuthFilter.java
..
..
@@ -1,3 +1,6 @@
1
+/*
2
+ * Copyright @ 2013 CurisTEC, S.A.S. All Rights Reserved.
3
+ */
1
4
 package net.curisit.securis;
2
5
 
3
6
 import java.io.IOException;
..
..
@@ -17,16 +20,63 @@
17
20
 import org.apache.logging.log4j.LogManager;
18
21
 import org.apache.logging.log4j.Logger;
19
22
 
23
+/**
24
+* AuthFilter
25
+* <p>
26
+* Simple authentication/role wrapper for development and lightweight scenarios.
27
+* If a request parameter <code>user</code> or a session attribute <code>user</code>
28
+* is present, this filter wraps the current request with a custom {@link Principal}
29
+* and an ad-hoc role. The role assignment is temporary and follows the rule:
30
+* <ul>
31
+* <li>user == "advance" → role "advance"</li>
32
+* <li>otherwise → role "normal"</li>
33
+* </ul>
34
+* If no user is present, the request continues unmodified.
35
+*
36
+* <p><b>Security note:</b> This filter trusts a user name coming from a request parameter,
37
+* which must not be used in production. Replace with a proper authentication mechanism
38
+* (e.g., JWT, container security, SSO) and derive roles from authoritative claims.
39
+*
40
+* @author JRA
41
+* Last reviewed by JRA on Oct 6, 2025.
42
+*/
20
43
 @ApplicationScoped
21
44
 @WebFilter(urlPatterns = "/*")
22
45
 public class AuthFilter implements Filter {
23
46
 
24
47
     private static final Logger LOG = LogManager.getLogger(AuthFilter.class);
25
48
 
49
+    // ---------------------------------------------------------------------
50
+    // Lifecycle
51
+    // ---------------------------------------------------------------------
52
+    
53
+    /** 
54
+     * init<p>
55
+     * Filter initialization hook (unused). 
56
+     */
26
57
     @Override
27
58
     public void init(FilterConfig fc) throws ServletException {
28
59
     }
29
60
 
61
+    // ---------------------------------------------------------------------
62
+    // Filtering
63
+    // ---------------------------------------------------------------------
64
+
65
+
66
+    /**
67
+     * doFilter
68
+     * <p>
69
+     * If a user is detected (request param or session attribute), wrap the request to:
70
+     * <ul>
71
+     * <li>Expose a {@link Principal} with the provided username.</li>
72
+     * <li>Report a single role through {@link HttpServletRequest#isUserInRole(String)}.</li>
73
+     * </ul>
74
+     * Otherwise, pass-through.
75
+     *
76
+     * @param sr incoming request
77
+     * @param sr1 outgoing response
78
+     * @param fc filter chain
79
+     */
30
80
     @Override
31
81
     public void doFilter(ServletRequest sr, ServletResponse sr1, FilterChain fc) throws IOException, ServletException {
32
82
         HttpServletRequest req = (HttpServletRequest) sr;
..
..
@@ -46,21 +96,46 @@
46
96
 
47
97
     }
48
98
 
99
+    /** 
100
+     * destroy<p>
101
+     * Filter destruction hook (unused). 
102
+     */
49
103
     @Override
50
104
     public void destroy() {
51
105
     }
52
106
 
107
+     // ---------------------------------------------------------------------
108
+     // Wrapper
109
+     // ---------------------------------------------------------------------
110
+
111
+     /**
112
+      * UserRoleRequestWrapper
113
+      * <p>
114
+      * Wrapper that overrides role checks and the user principal when a synthetic user is present.
115
+      */
53
116
     private class UserRoleRequestWrapper extends HttpServletRequestWrapper {
54
117
 
55
118
         private String role;
56
119
         private String user;
57
120
 
121
+        /**
122
+        * Constructor
123
+        * <p>
124
+        * @param role single role to expose via {@link #isUserInRole(String)}
125
+        * @param user user name to expose via {@link #getUserPrincipal()}
126
+        * @param request original request to wrap
127
+        */
58
128
         public UserRoleRequestWrapper(String role, String user, HttpServletRequest request) {
59
129
             super(request);
60
130
             this.role = role;
61
131
             this.user = user;
62
132
         }
63
133
 
134
+        /**
135
+        * isUserInRole
136
+        * <p>
137
+        * Returns {@code true} if the requested role equals the configured synthetic role.
138
+        */
64
139
         @Override
65
140
         public boolean isUserInRole(String role) {
66
141
             LOG.info("isUserRole METHOD: {}, {}", role, this.role);
..
..
@@ -70,6 +145,11 @@
70
145
             return this.role.equals(role);
71
146
         }
72
147
 
148
+        /**
149
+        * getUserPrincipal
150
+        * <p>
151
+        * Returns a minimal {@link Principal} with the configured user name; delegates otherwise.
152
+        */
73
153
         @Override
74
154
         public Principal getUserPrincipal() {
75
155
             if (this.user == null) {