Add HTMX-aware AuthenticationEntryPoint for session expiry handling

When HTMX-powered pages poll or fetch fragments and the user's session
expires, Spring Security's default 302 redirect causes HTMX to swap the
full login page HTML into each target element, breaking the UI.

This adds HtmxAwareAuthenticationEntryPoint which detects HTMX requests
(HX-Request header) and returns a 401 JSON response with HX-Redirect
header instead of the 302 redirect, allowing HTMX clients to handle
session expiry gracefully. Non-HTMX requests are delegated unchanged.

Consumers can override by defining their own AuthenticationEntryPoint bean.

Closes #294

Author: devondragon

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);