Add HTMX-aware AuthenticationEntryPoint for session expiry handling

src/main/java/com/digitalsanctuary/spring/user/security/HtmxAwareAuthenticationEntryPoint.java

@@ -0,0 +1,75 @@
+package com.digitalsanctuary.spring.user.security;
+
+import java.io.IOException;
+import org.springframework.security.core.AuthenticationException;
+import org.springframework.security.web.AuthenticationEntryPoint;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * An {@link AuthenticationEntryPoint} that detects HTMX requests and returns a JSON 401 response instead of the
+ * default 302 redirect to the login page.
+ *
+ * <p>When an HTMX-powered page has polling or dynamic fragment requests and the user's session expires, Spring
+ * Security's default entry point sends a 302 redirect to the login page. HTMX transparently follows the redirect and
+ * swaps the full login page HTML into each target element, breaking the UI. This entry point intercepts HTMX requests
+ * (identified by the {@code HX-Request} header) and returns a 401 status with a JSON body and an {@code HX-Redirect}
+ * header, allowing the HTMX client to handle the session expiry gracefully.</p>
+ *
+ * <p>Non-HTMX requests are delegated to the wrapped {@link AuthenticationEntryPoint}, preserving the existing
+ * redirect behavior for standard browser requests.</p>
+ *
+ * @see <a href="https://htmx.org/attributes/hx-request/">HTMX HX-Request Header</a>
+ * @see <a href="https://htmx.org/headers/hx-redirect/">HTMX HX-Redirect Response Header</a>
+ */
+@Slf4j
+public class HtmxAwareAuthenticationEntryPoint implements AuthenticationEntryPoint {
+
+    static final String HX_REQUEST_HEADER = "HX-Request";
+    static final String HX_REDIRECT_HEADER = "HX-Redirect";
+
+    private final AuthenticationEntryPoint delegate;
+    private final String loginUrl;
+
+    /**
+     * Creates a new HTMX-aware authentication entry point.
+     *
+     * @param delegate the entry point to delegate to for non-HTMX requests
+     * @param loginUrl the login page URL used in the JSON response and HX-Redirect header
+     */
+    public HtmxAwareAuthenticationEntryPoint(AuthenticationEntryPoint delegate, String loginUrl) {
+        this.delegate = delegate;
+        this.loginUrl = loginUrl;
+    }
+
+    @Override
+    public void commence(HttpServletRequest request, HttpServletResponse response,
+            AuthenticationException authException) throws IOException, ServletException {
+        if (isHtmxRequest(request)) {
+            log.debug("HTMX request detected for URI {}; returning 401 with JSON body and HX-Redirect to {}",
+                    request.getRequestURI(), loginUrl);
+
+            if (response.isCommitted()) {
+                log.warn("Response already committed for HTMX request to {}; cannot write 401 response",
+                        request.getRequestURI());
+                return;
+            }
+
+            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
+            response.setContentType("application/json");
+            response.setHeader(HX_REDIRECT_HEADER, loginUrl);
+            String escapedLoginUrl = loginUrl.replace("\\", "\\\\").replace("\"", "\\\"");
+            response.getWriter().write("{\"error\":\"authentication_required\","
+                    + "\"message\":\"Session expired. Please log in.\","
+                    + "\"loginUrl\":\"" + escapedLoginUrl + "\"}");
+        } else {
+            delegate.commence(request, response, authException);
+        }
+    }
+
+    private boolean isHtmxRequest(HttpServletRequest request) {
+        return "true".equalsIgnoreCase(request.getHeader(HX_REQUEST_HEADER));
+    }
+}

src/main/java/com/digitalsanctuary/spring/user/security/HtmxAwareAuthenticationEntryPointConfiguration.java

@@ -0,0 +1,55 @@
+package com.digitalsanctuary.spring.user.security;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.web.AuthenticationEntryPoint;
+import org.springframework.security.web.authentication.LoginUrlAuthenticationEntryPoint;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Auto-configuration for the {@link AuthenticationEntryPoint}.
+ *
+ * <p>Registers an {@link HtmxAwareAuthenticationEntryPoint} that wraps the appropriate inner entry point
+ * (form-login or OAuth2) when no custom {@link AuthenticationEntryPoint} bean is defined by the consuming
+ * application.</p>
+ *
+ * <p>Consuming applications can override this by defining their own {@link AuthenticationEntryPoint} bean:</p>
+ * <pre>{@code
+ * @Bean
+ * public AuthenticationEntryPoint myCustomEntryPoint() {
+ *     return new MyCustomAuthenticationEntryPoint();
+ * }
+ * }</pre>
+ */
+@Slf4j
+@Configuration
+public class HtmxAwareAuthenticationEntryPointConfiguration {
+
+    @Value("${user.security.loginPageURI}")
+    private String loginPageURI;
+
+    @Value("${spring.security.oauth2.enabled:false}")
+    private boolean oauth2Enabled;
+
+    /**
+     * Creates the default {@link AuthenticationEntryPoint} bean. This bean is only registered when no custom
+     * {@link AuthenticationEntryPoint} bean is provided by the consuming application.
+     *
+     * @return an {@link HtmxAwareAuthenticationEntryPoint} wrapping the appropriate inner entry point
+     */
+    @Bean
+    @ConditionalOnMissingBean(AuthenticationEntryPoint.class)
+    public AuthenticationEntryPoint authenticationEntryPoint() {
+        AuthenticationEntryPoint inner;
+        if (oauth2Enabled) {
+            inner = new CustomOAuth2AuthenticationEntryPoint(null, loginPageURI);
+            log.info("Configuring HtmxAwareAuthenticationEntryPoint wrapping CustomOAuth2AuthenticationEntryPoint");
+        } else {
+            inner = new LoginUrlAuthenticationEntryPoint(loginPageURI);
+            log.info("Configuring HtmxAwareAuthenticationEntryPoint wrapping LoginUrlAuthenticationEntryPoint");
+        }
+        return new HtmxAwareAuthenticationEntryPoint(inner, loginPageURI);
+    }
+}

src/main/java/com/digitalsanctuary/spring/user/security/WebSecurityConfig.java

@@ -22,6 +22,7 @@
 import org.springframework.security.config.ObjectPostProcessor;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
 import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.web.AuthenticationEntryPoint;
 import org.springframework.security.core.session.SessionRegistry;
 import org.springframework.security.core.session.SessionRegistryImpl;
 import org.springframework.security.core.userdetails.UserDetailsService;
@@ -122,6 +123,7 @@ public class WebSecurityConfig {
 	@Value("${user.dev.auto-login-enabled:false}")
 	private boolean devAutoLoginEnabled;
 
+	private final AuthenticationEntryPoint authenticationEntryPoint;
 	private final UserDetailsService userDetailsService;
 	private final LoginSuccessService loginSuccessService;
 	private final LogoutSuccessService logoutSuccessService;
@@ -150,6 +152,9 @@ public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Excepti
 		http.formLogin(
 				formLogin -> formLogin.loginPage(loginPageURI).loginProcessingUrl(loginActionURI).successHandler(loginSuccessService).permitAll());
 
+		// Always configure exception handling with the injected entry point (HTMX-aware by default)
+		http.exceptionHandling(handling -> handling.authenticationEntryPoint(authenticationEntryPoint));
+
 		// Configure remember-me only if explicitly enabled and key is provided
 		if (rememberMeEnabled && rememberMeKey != null && !rememberMeKey.trim().isEmpty()) {
 			http.rememberMe(rememberMe -> rememberMe.key(rememberMeKey).userDetailsService(userDetailsService));
@@ -211,10 +216,8 @@ public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Excepti
 	 * @throws Exception the exception
 	 */
 	private void setupOAuth2(HttpSecurity http) throws Exception {
-		CustomOAuth2AuthenticationEntryPoint loginAuthenticationEntryPoint = new CustomOAuth2AuthenticationEntryPoint(null, loginPageURI);
-
-		http.exceptionHandling(handling -> handling.authenticationEntryPoint(loginAuthenticationEntryPoint))
-				.oauth2Login(o -> o.loginPage(loginPageURI).successHandler(loginSuccessService).failureHandler((request, response, exception) -> {
+		// Entry point is handled globally in securityFilterChain via the injected authenticationEntryPoint bean
+		http.oauth2Login(o -> o.loginPage(loginPageURI).successHandler(loginSuccessService).failureHandler((request, response, exception) -> {
 					log.error("WebSecurityConfig.configure: OAuth2 login failure: {}", exception.getMessage());
 					request.getSession().setAttribute("error.message", exception.getMessage());
 					response.sendRedirect(loginPageURI);