Merge pull request #188 from lcnicolau/htmx-csrf-token

Add support for automatic CSRF token injection

Author: wimdeblauwe

README.md

@@ -383,6 +383,14 @@ You can use multiple values like this:
 <div hx:vals="${ {id: user.id, groupId: group.id } }"></div>
 ```
 
+#### Automatic CSRF token injection
+
+A Cross-Site Request Forgery (CSRF) attack tricks an authenticated user into performing unintended state-changing actions in a web application.
+
+By default, Spring Security provides built-in protection against CSRF attacks on unsafe HTTP methods, while Thymeleaf automatically includes the required CSRF token as a hidden field in forms using `th:action`.
+
+The library extends this support to htmx by automatically injecting the CSRF token into the request headers through the `hx-headers` attribute of elements using `hx:post`, `hx:put`, `hx:patch`, or `hx:delete`, even if the element is not part of a form.
+
 ## Articles
 
 Links to articles and blog posts about this library:

htmx-spring-boot-thymeleaf/pom.xml

@@ -28,6 +28,11 @@
             <artifactId>spring-boot-starter-webmvc</artifactId>
             <optional>true</optional>
         </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-security</artifactId>
+            <optional>true</optional>
+        </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-thymeleaf</artifactId>
@@ -43,6 +48,11 @@
             <artifactId>spring-boot-starter-webmvc-test</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-security-test</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
 </project>

htmx-spring-boot-thymeleaf/src/main/java/io/github/wimdeblauwe/htmx/spring/boot/thymeleaf/HtmxAttributeProcessor.java

@@ -17,14 +17,14 @@
 import tools.jackson.core.JacksonException;
 import tools.jackson.databind.ObjectMapper;
 
-import java.util.LinkedHashMap;
+import java.util.Map;
 
 public class HtmxAttributeProcessor extends AbstractStandardExpressionAttributeTagProcessor
         implements IAttributeDefinitionsAware {
 
     public static final int ATTR_PRECEDENCE = 1000;
     private final String attrName;
-    private final ObjectMapper mapper;
+    protected final ObjectMapper mapper;
 
     private static final TemplateMode TEMPLATE_MODE = TemplateMode.HTML;
 
@@ -33,7 +33,14 @@ public class HtmxAttributeProcessor extends AbstractStandardExpressionAttributeT
     public HtmxAttributeProcessor(String dialectPrefix,
                                   String attrName,
                                   ObjectMapper mapper) {
-        super(TEMPLATE_MODE, dialectPrefix, attrName, ATTR_PRECEDENCE, false, true);
+        this(dialectPrefix, attrName, ATTR_PRECEDENCE, mapper);
+    }
+
+    public HtmxAttributeProcessor(String dialectPrefix,
+                                  String attrName,
+                                  int precedence,
+                                  ObjectMapper mapper) {
+        super(TEMPLATE_MODE, dialectPrefix, attrName, precedence, false, true);
         this.attrName = attrName;
         this.mapper = mapper;
     }
@@ -46,7 +53,7 @@ public void setAttributeDefinitions(final AttributeDefinitions attributeDefiniti
     }
 
     @Override
-    protected final void doProcess(
+    protected void doProcess(
             final ITemplateContext context,
             final IProcessableElementTag tag,
             final AttributeName attributeName,
@@ -57,7 +64,7 @@ protected final void doProcess(
             structureHandler.removeAttribute(attributeName);
         } else {
             String expressionResultString;
-            if (expressionResult instanceof LinkedHashMap) {
+            if (expressionResult instanceof Map) {
                 try {
                     expressionResultString = this.mapper.writeValueAsString(expressionResult);
                 } catch (JacksonException e) {

htmx-spring-boot-thymeleaf/src/main/java/io/github/wimdeblauwe/htmx/spring/boot/thymeleaf/HtmxCsrfAttributeProcessor.java

@@ -0,0 +1,93 @@
+package io.github.wimdeblauwe.htmx.spring.boot.thymeleaf;
+
+import org.springframework.security.web.csrf.CsrfToken;
+import org.thymeleaf.context.ITemplateContext;
+import org.thymeleaf.engine.AttributeName;
+import org.thymeleaf.exceptions.TemplateProcessingException;
+import org.thymeleaf.model.IProcessableElementTag;
+import org.thymeleaf.processor.element.IElementTagStructureHandler;
+import org.unbescape.html.HtmlEscape;
+import tools.jackson.core.JacksonException;
+import tools.jackson.core.type.TypeReference;
+import tools.jackson.databind.ObjectMapper;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Thymeleaf processor for seamless integration of htmx with Spring Boot applications using CSRF protection.
+ * <p>
+ * Automatically injects the current Spring Security {@link CsrfToken} into htmx request headers.
+ * It obtains the CSRF token from the Thymeleaf context (via the {@code _csrf} variable)
+ * and merges it into the {@code hx-headers} attribute, while preserving any existing values.
+ * <p>
+ * If no CSRF token is available, the processor performs no action.
+ * <p>
+ * This enables htmx-triggered requests to include the CSRF token automatically,
+ * eliminating the need for manual token handling in templates.
+ * <p>
+ * Example:
+ * <pre>{@code
+ * <a hx:post="@{/logout}">Log out</a>
+ * }</pre>
+ * <p>
+ * After processing, will render as:
+ * <pre>{@code
+ * <a hx-post="/logout"
+ *    hx-headers="{&quot;X-CSRF-TOKEN&quot;:&quot;abc123&quot;}">Log out</a>
+ * }</pre>
+ * ("abc123" represents the real CSRF token that Spring Security provides at runtime)
+ *
+ * @author LC Nicolau
+ * @see <a href="https://htmx.org/docs/#csrf-prevention">CSRF Prevention</a>
+ * @see <a href="https://htmx.org/attributes/hx-headers/">hx-headers Attribute Reference</a>
+ * @since 5.1.0
+ */
+public class HtmxCsrfAttributeProcessor extends HtmxAttributeProcessor {
+
+    public HtmxCsrfAttributeProcessor(String dialectPrefix,
+                                      String attrName,
+                                      ObjectMapper mapper) {
+        super(dialectPrefix, attrName, ATTR_PRECEDENCE + 1, mapper);
+    }
+
+    @Override
+    protected void doProcess(
+            final ITemplateContext context,
+            final IProcessableElementTag tag,
+            final AttributeName attributeName,
+            final String attributeValue,
+            final Object expressionResult,
+            final IElementTagStructureHandler structureHandler) {
+        super.doProcess(context, tag, attributeName, attributeValue, expressionResult, structureHandler);
+
+        var token = (CsrfToken) context.getVariable("_csrf");
+        if (token == null || expressionResult == null) {
+            return;
+        }
+        var headers = this.getHeaders(tag);
+        headers.put(token.getHeaderName(), token.getToken());
+        try {
+            var json = mapper.writeValueAsString(headers);
+            var escaped = HtmlEscape.escapeHtml4Xml(json);
+            structureHandler.setAttribute("hx-headers", escaped);
+        } catch (JacksonException e) {
+            throw new TemplateProcessingException("Exception writing map", tag.getTemplateName(), tag.getLine(), tag.getLine(), e);
+        }
+    }
+
+    protected Map<String, Object> getHeaders(IProcessableElementTag tag) {
+        var current = tag.getAttributeValue("hx-headers");
+        if (current == null || current.isBlank()) {
+            return new HashMap<>();
+        }
+        try {
+            var json = HtmlEscape.unescapeHtml(current);
+            return this.mapper.readValue(json, new TypeReference<>() {
+            });
+        } catch (JacksonException e) {
+            throw new TemplateProcessingException("Exception reading map", tag.getTemplateName(), tag.getLine(), tag.getLine(), e);
+        }
+    }
+
+}

htmx-spring-boot-thymeleaf/src/main/java/io/github/wimdeblauwe/htmx/spring/boot/thymeleaf/HtmxDialect.java

@@ -26,7 +26,7 @@ public Set<IProcessor> getProcessors(String dialectPrefix) {
 
         htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "boost", mapper));
         htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "confirm", mapper));
-        htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "delete", mapper));
+        htmxProcessors.add(new HtmxCsrfAttributeProcessor(dialectPrefix, "delete", mapper));
         htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "disable", mapper));
         htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "disinherit", mapper));
         htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "encoding", mapper));
@@ -37,11 +37,11 @@ public Set<IProcessor> getProcessors(String dialectPrefix) {
         htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "include", mapper));
         htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "indicator", mapper));
         htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "params", mapper));
-        htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "patch", mapper));
-        htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "post", mapper));
+        htmxProcessors.add(new HtmxCsrfAttributeProcessor(dialectPrefix, "patch", mapper));
+        htmxProcessors.add(new HtmxCsrfAttributeProcessor(dialectPrefix, "post", mapper));
         htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "preserve", mapper));
         htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "prompt", mapper));
-        htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "put", mapper));
+        htmxProcessors.add(new HtmxCsrfAttributeProcessor(dialectPrefix, "put", mapper));
         htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "push-url", mapper));
         htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "request", mapper));
         htmxProcessors.add(new HtmxAttributeProcessor(dialectPrefix, "select", mapper));

htmx-spring-boot-thymeleaf/src/test/java/io/github/wimdeblauwe/htmx/spring/boot/thymeleaf/HtmxCsrfTest.java

@@ -0,0 +1,164 @@
+package io.github.wimdeblauwe.htmx.spring.boot.thymeleaf;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.Customizer;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.security.web.csrf.CsrfToken;
+import org.springframework.stereotype.Controller;
+import org.springframework.test.context.ContextConfiguration;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.MvcResult;
+import org.springframework.web.bind.annotation.GetMapping;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/**
+ * Verifies automatic CSRF token injection into elements using unsafe HTTP methods
+ * ({@code hx:post}, {@code hx:put}, {@code hx:patch}, {@code hx:delete}).
+ * <p>
+ * Tests cover the following scenarios:
+ * <ul>
+ *     <li>The CSRF token is automatically injected into the {@code hx-headers} attribute.</li>
+ *     <li>Correct merging when {@code hx-headers} already contains additional entries.</li>
+ *     <li>Proper behavior when CSRF protection is disabled or no token is present.</li>
+ * </ul>
+ *
+ * @author LC Nicolau
+ * @since 5.1.0
+ */
+@WebMvcTest(controllers = HtmxCsrfTest.TestController.class)
+@ContextConfiguration(classes = {HtmxCsrfTest.TestController.class, HtmxCsrfTest.SecurityConfig.class})
+@WithMockUser
+class HtmxCsrfTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @Test
+    void testHxPostCsrf() throws Exception {
+        MvcResult result = mockMvc.perform(get("/htmx-csrf"))
+                                  .andExpect(status().isOk())
+                                  .andReturn();
+
+        String html = result.getResponse().getContentAsString();
+        assertThat(html)
+                .containsPattern("hx-post-div.*hx-post=\"/foo\"")
+                .containsPattern("hx-post-headers.*hx-post=\"/foo\"");
+
+        CsrfToken csrf = ((CsrfToken) result.getRequest().getAttribute("_csrf"));
+        if (csrf == null) {
+            assertThat(html)
+                    .doesNotContainPattern("hx-post-div.*hx-headers=")
+                    .doesNotContainPattern("hx-post-headers.*hx-headers=.*X-CSRF-TOKEN");
+        } else {
+            String token = csrf.getToken();
+            assertThat(html)
+                    .containsPattern("hx-post-div.*hx-headers=\"\\{&quot;X-CSRF-TOKEN&quot;:&quot;" + token + "&quot;}\"")
+                    .containsPattern("hx-post-headers.*hx-headers=\"\\{&quot;someHeader&quot;:true,&quot;X-CSRF-TOKEN&quot;:&quot;" + token + "&quot;}\"");
+        }
+    }
+
+    @Test
+    void testHxPutCsrf() throws Exception {
+        MvcResult result = mockMvc.perform(get("/htmx-csrf"))
+                                  .andExpect(status().isOk())
+                                  .andReturn();
+
+        String html = result.getResponse().getContentAsString();
+        assertThat(html)
+                .containsPattern("hx-put-div.*hx-put=\"/foo\"")
+                .containsPattern("hx-put-headers.*hx-put=\"/foo\"");
+
+        CsrfToken csrf = ((CsrfToken) result.getRequest().getAttribute("_csrf"));
+        if (csrf == null) {
+            assertThat(html)
+                    .doesNotContainPattern("hx-put-div.*hx-headers=")
+                    .doesNotContainPattern("hx-put-headers.*hx-headers=.*X-CSRF-TOKEN");
+        } else {
+            String token = csrf.getToken();
+            assertThat(html)
+                    .containsPattern("hx-put-div.*hx-headers=\"\\{&quot;X-CSRF-TOKEN&quot;:&quot;" + token + "&quot;}\"")
+                    .containsPattern("hx-put-headers.*hx-headers=\"\\{&quot;someHeader&quot;:true,&quot;X-CSRF-TOKEN&quot;:&quot;" + token + "&quot;}\"");
+        }
+    }
+
+    @Test
+    void testHxPatchCsrf() throws Exception {
+        MvcResult result = mockMvc.perform(get("/htmx-csrf"))
+                                  .andExpect(status().isOk())
+                                  .andReturn();
+
+        String html = result.getResponse().getContentAsString();
+        assertThat(html)
+                .containsPattern("hx-patch-div.*hx-patch=\"/foo\"")
+                .containsPattern("hx-patch-headers.*hx-patch=\"/foo\"");
+
+        CsrfToken csrf = ((CsrfToken) result.getRequest().getAttribute("_csrf"));
+        if (csrf == null) {
+            assertThat(html)
+                    .doesNotContainPattern("hx-patch-div.*hx-headers=")
+                    .doesNotContainPattern("hx-patch-headers.*hx-headers=.*X-CSRF-TOKEN");
+        } else {
+            String token = csrf.getToken();
+            assertThat(html)
+                    .containsPattern("hx-patch-div.*hx-headers=\"\\{&quot;X-CSRF-TOKEN&quot;:&quot;" + token + "&quot;}\"")
+                    .containsPattern("hx-patch-headers.*hx-headers=\"\\{&quot;someHeader&quot;:true,&quot;X-CSRF-TOKEN&quot;:&quot;" + token + "&quot;}\"");
+        }
+    }
+
+    @Test
+    void testHxDeleteCsrf() throws Exception {
+        MvcResult result = mockMvc.perform(get("/htmx-csrf"))
+                                  .andExpect(status().isOk())
+                                  .andReturn();
+
+        String html = result.getResponse().getContentAsString();
+        assertThat(html)
+                .containsPattern("hx-delete-div.*hx-delete=\"/foo\"")
+                .containsPattern("hx-delete-headers.*hx-delete=\"/foo\"");
+
+        CsrfToken csrf = ((CsrfToken) result.getRequest().getAttribute("_csrf"));
+        if (csrf == null) {
+            assertThat(html)
+                    .doesNotContainPattern("hx-delete-div.*hx-headers=")
+                    .doesNotContainPattern("hx-delete-headers.*hx-headers=.*X-CSRF-TOKEN");
+        } else {
+            String token = csrf.getToken();
+            assertThat(html)
+                    .containsPattern("hx-delete-div.*hx-headers=\"\\{&quot;X-CSRF-TOKEN&quot;:&quot;" + token + "&quot;}\"")
+                    .containsPattern("hx-delete-headers.*hx-headers=\"\\{&quot;someHeader&quot;:true,&quot;X-CSRF-TOKEN&quot;:&quot;" + token + "&quot;}\"");
+        }
+    }
+
+    @Controller
+    static class TestController {
+
+        @GetMapping("/htmx-csrf")
+        public String csrf() {
+            return "htmx-csrf";
+        }
+
+    }
+
+    @Configuration
+    static class SecurityConfig {
+
+        @Bean
+        SecurityFilterChain securityFilterChain(HttpSecurity http) {
+            return http.authorizeHttpRequests(config -> config
+                               .requestMatchers("/htmx-csrf").authenticated())
+                       .csrf(Customizer.withDefaults())
+                       .build();
+        }
+
+    }
+
+}

htmx-spring-boot-thymeleaf/src/test/java/io/github/wimdeblauwe/htmx/spring/boot/thymeleaf/HtmxDialectTest.java

@@ -1,9 +1,9 @@
 package io.github.wimdeblauwe.htmx.spring.boot.thymeleaf;
 
-
 import org.junit.jupiter.api.Test;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
+import org.springframework.security.test.context.support.WithMockUser;
 import org.springframework.test.context.ContextConfiguration;
 import org.springframework.test.web.servlet.MockMvc;
 
@@ -14,6 +14,7 @@
 
 @WebMvcTest(HtmxDialectTestController.class)
 @ContextConfiguration(classes = HtmxDialectTestController.class)
+@WithMockUser
 class HtmxDialectTest {
 
     @Autowired