[stimulus-bundle] Export CSRF protection helpers #1375

hlecorche · 2025-01-08T19:44:51Z

Q	A
License	MIT
Doc issue/PR	-

Here is my first proposal addressing #1370:

Fixes the issue where the CSRF token is updated after the form is submitted (e.g., when using fetch requests) ;
Avoids code duplication when reusing this logic in multiple places ;
Replaces var by const or let for better modern JavaScript practices.

This code can be used without Turbo. Here's an example:

import { generateCsrfHeaders, removeCsrfToken } from './csrf_protection.js';

// ...

document.addEventListener('before-event-with-jquery-or-custom-fetch-event', function (event) {
	Object.entries(generateCsrfHeaders(event.detail.form)).forEach(([name, value]) => {
	    // add header
	});
});

document.addEventListener('after-event-with-jquery-or-custom-fetch-event', function (event) {
	removeCsrfToken(event.detail.form);
});

It can also be used without relying on the form's submit event :

import { generateCsrfToken, generateCsrfHeaders, removeCsrfToken } from './csrf_protection.js';

// ...

link.addEventListener('click', function (event) {
	const form = document.getElementById('my-form');
	generateCsrfToken(form);
	// Send form with fetch (or jquery) with generateCsrfHeaders and removeCsrfToken functions
});

I have made these changes in version 2.20 (the existing version). However, since the behavior of the files is modified, I assume it is necessary to create a new version.

github-actions · 2025-01-08T19:45:15Z

Thanks for the PR 😍

How to test these changes in your application

Define the SYMFONY_ENDPOINT environment variable:

# On Unix-like (BSD, Linux and macOS)
export SYMFONY_ENDPOINT=https://raw.githubusercontent.com/symfony/recipes/flex/pull-1375/index.json
# On Windows
SET SYMFONY_ENDPOINT=https://raw.githubusercontent.com/symfony/recipes/flex/pull-1375/index.json

Install the package(s) related to this recipe:

composer req symfony/flex
composer req 'symfony/stimulus-bundle:^2.20'

Don't forget to unset the SYMFONY_ENDPOINT environment variable when done:

# On Unix-like (BSD, Linux and macOS)
unset SYMFONY_ENDPOINT
# On Windows
SET SYMFONY_ENDPOINT=

Diff between recipe versions

In order to help with the review stage, I'm in charge of computing the diff between the various versions of patched recipes.
I'm going keep this comment up to date with any updates of the attached patch.

symfony/stimulus-bundle

2.8 vs 2.9

diff --git a/symfony/stimulus-bundle/2.9/assets/bootstrap.js b/symfony/stimulus-bundle/2.9/assets/bootstrap.js
new file mode 100644
index 0000000..2689398
--- /dev/null
+++ b/symfony/stimulus-bundle/2.9/assets/bootstrap.js
@@ -0,0 +1,2 @@
+// register any custom, 3rd party controllers here
+// app.register('some_controller_name', SomeImportedController);
diff --git a/symfony/stimulus-bundle/2.9/assets/controllers/hello_controller.js b/symfony/stimulus-bundle/2.9/assets/controllers/hello_controller.js
new file mode 100644
index 0000000..e847027
--- /dev/null
+++ b/symfony/stimulus-bundle/2.9/assets/controllers/hello_controller.js
@@ -0,0 +1,16 @@
+import { Controller } from '@hotwired/stimulus';
+
+/*
+ * This is an example Stimulus controller!
+ *
+ * Any element with a data-controller="hello" attribute will cause
+ * this controller to be executed. The name "hello" comes from the filename:
+ * hello_controller.js -> "hello"
+ *
+ * Delete this file or adapt it for your use!
+ */
+export default class extends Controller {
+    connect() {
+        this.element.textContent = 'Hello Stimulus! Edit me in assets/controllers/hello_controller.js';
+    }
+}
diff --git a/symfony/stimulus-bundle/2.9/assets/controllers.json b/symfony/stimulus-bundle/2.9/assets/controllers.json
new file mode 100644
index 0000000..a1c6e90
--- /dev/null
+++ b/symfony/stimulus-bundle/2.9/assets/controllers.json
@@ -0,0 +1,4 @@
+{
+    "controllers": [],
+    "entrypoints": []
+}
diff --git a/symfony/stimulus-bundle/2.8/manifest.json b/symfony/stimulus-bundle/2.9/manifest.json
index ff66e87..60e0ddb 100644
--- a/symfony/stimulus-bundle/2.8/manifest.json
+++ b/symfony/stimulus-bundle/2.9/manifest.json
@@ -2,5 +2,46 @@
     "bundles": {
         "Symfony\\UX\\StimulusBundle\\StimulusBundle": ["all"]
     },
-    "aliases": ["stimulus", "stimulus-bundle"]
+    "copy-from-recipe": {
+        "assets/": "assets/"
+    },
+    "aliases": ["stimulus", "stimulus-bundle"],
+    "conflict": {
+        "symfony/webpack-encore-bundle": "<2.0",
+        "symfony/flex": "<1.20.0 || >=2.0.0,<2.3.0"
+    },
+    "add-lines": [
+        {
+            "file": "webpack.config.js",
+            "content": "\n    // enables the Symfony UX Stimulus bridge (used in assets/bootstrap.js)\n    .enableStimulusBridge('./assets/controllers.json')",
+            "position": "after_target",
+            "target": ".splitEntryChunks()"
+        },
+        {
+            "file": "assets/app.js",
+            "content": "import './bootstrap.js';",
+            "position": "top",
+            "warn_if_missing": true
+        },
+        {
+            "file": "assets/bootstrap.js",
+            "content": "import { startStimulusApp } from '@symfony/stimulus-bridge';\n\n// Registers Stimulus controllers from controllers.json and in the controllers/ directory\nexport const app = startStimulusApp(require.context(\n    '@symfony/stimulus-bridge/lazy-controller-loader!./controllers',\n    true,\n    /\\.[jt]sx?$/\n));",
+            "position": "top",
+            "requires": "symfony/webpack-encore-bundle"
+        },
+        {
+            "file": "assets/bootstrap.js",
+            "content": "import { startStimulusApp } from '@symfony/stimulus-bundle';\n\nconst app = startStimulusApp();",
+            "position": "top",
+            "requires": "symfony/asset-mapper"
+        },
+        {
+            "file": "templates/base.html.twig",
+            "content": "            {{ ux_controller_link_tags() }}",
+            "position": "after_target",
+            "target": "{% block stylesheets %}",
+            "warn_if_missing": true,
+            "requires": "symfony/asset-mapper"
+        }
+    ]
 }

2.9 vs 2.13

diff --git a/symfony/stimulus-bundle/2.9/manifest.json b/symfony/stimulus-bundle/2.13/manifest.json
index 60e0ddb..4701215 100644
--- a/symfony/stimulus-bundle/2.9/manifest.json
+++ b/symfony/stimulus-bundle/2.13/manifest.json
@@ -34,14 +34,6 @@
             "content": "import { startStimulusApp } from '@symfony/stimulus-bundle';\n\nconst app = startStimulusApp();",
             "position": "top",
             "requires": "symfony/asset-mapper"
-        },
-        {
-            "file": "templates/base.html.twig",
-            "content": "            {{ ux_controller_link_tags() }}",
-            "position": "after_target",
-            "target": "{% block stylesheets %}",
-            "warn_if_missing": true,
-            "requires": "symfony/asset-mapper"
         }
     ]
 }

2.13 vs 2.20

diff --git a/symfony/stimulus-bundle/2.20/assets/controllers/csrf_protection_controller.js b/symfony/stimulus-bundle/2.20/assets/controllers/csrf_protection_controller.js
new file mode 100644
index 0000000..05e46b7
--- /dev/null
+++ b/symfony/stimulus-bundle/2.20/assets/controllers/csrf_protection_controller.js
@@ -0,0 +1,79 @@
+const nameCheck = /^[-_a-zA-Z0-9]{4,22}$/;
+const tokenCheck = /^[-_\/+a-zA-Z0-9]{24,}$/;
+
+// Generate and double-submit a CSRF token in a form field and a cookie, as defined by Symfony's SameOriginCsrfTokenManager
+document.addEventListener('submit', function (event) {
+    generateCsrfToken(event.target);
+}, true);
+
+// When @hotwired/turbo handles form submissions, send the CSRF token in a header in addition to a cookie
+// The `framework.csrf_protection.check_header` config option needs to be enabled for the header to be checked
+document.addEventListener('turbo:submit-start', function (event) {
+    const h = generateCsrfHeaders(event.detail.formSubmission);
+    Object.keys(h).map(function (k) {
+        event.detail.formSubmission.fetchRequest.headers[k] = h[k];
+    });
+});
+
+// When @hotwired/turbo handles form submissions, remove the CSRF cookie once a form has been submitted
+document.addEventListener('turbo:submit-end', function (event) {
+    removeCsrfToken(event.detail.formSubmission.formElement);
+});
+
+export function generateCsrfToken (formElement) {
+    const csrfField = formElement.querySelector('input[data-controller="csrf-protection"], input[name="_csrf_token"]');
+
+    if (!csrfField) {
+        return;
+    }
+
+    let csrfCookie = csrfField.getAttribute('data-csrf-protection-cookie-value');
+    let csrfToken = csrfField.value;
+
+    if (!csrfCookie && nameCheck.test(csrfToken)) {
+        csrfField.setAttribute('data-csrf-protection-cookie-value', csrfCookie = csrfToken);
+        csrfField.defaultValue = csrfToken = btoa(String.fromCharCode.apply(null, (window.crypto || window.msCrypto).getRandomValues(new Uint8Array(18))));
+        csrfField.dispatchEvent(new Event('change', { bubbles: true }));
+    }
+
+    if (csrfCookie && tokenCheck.test(csrfToken)) {
+        const cookie = csrfCookie + '_' + csrfToken + '=' + csrfCookie + '; path=/; samesite=strict';
+        document.cookie = window.location.protocol === 'https:' ? '__Host-' + cookie + '; secure' : cookie;
+    }
+}
+
+export function generateCsrfHeaders (formElement) {
+    const headers = {};
+    const csrfField = formElement.querySelector('input[data-controller="csrf-protection"], input[name="_csrf_token"]');
+
+    if (!csrfField) {
+        return headers;
+    }
+
+    const csrfCookie = csrfField.getAttribute('data-csrf-protection-cookie-value');
+
+    if (tokenCheck.test(csrfField.value) && nameCheck.test(csrfCookie)) {
+        headers[csrfCookie] = csrfField.value;
+    }
+
+    return headers;
+}
+
+export function removeCsrfToken (formElement) {
+    const csrfField = formElement.querySelector('input[data-controller="csrf-protection"], input[name="_csrf_token"]');
+
+    if (!csrfField) {
+        return;
+    }
+
+    const csrfCookie = csrfField.getAttribute('data-csrf-protection-cookie-value');
+
+    if (tokenCheck.test(csrfField.value) && nameCheck.test(csrfCookie)) {
+        const cookie = csrfCookie + '_' + csrfField.value + '=0; path=/; samesite=strict; max-age=0';
+
+        document.cookie = window.location.protocol === 'https:' ? '__Host-' + cookie + '; secure' : cookie;
+    }
+}
+
+/* stimulusFetch: 'lazy' */
+export default 'csrf-protection-controller';
diff --git a/symfony/stimulus-bundle/2.13/manifest.json b/symfony/stimulus-bundle/2.20/manifest.json
index 4701215..4289495 100644
--- a/symfony/stimulus-bundle/2.13/manifest.json
+++ b/symfony/stimulus-bundle/2.20/manifest.json
@@ -7,6 +7,8 @@
     },
     "aliases": ["stimulus", "stimulus-bundle"],
     "conflict": {
+        "symfony/framework-bundle": "<7.2",
+        "symfony/security-csrf": "<7.2",
         "symfony/webpack-encore-bundle": "<2.0",
         "symfony/flex": "<1.20.0 || >=2.0.0,<2.3.0"
     },

ajgarlag · 2025-01-15T12:56:48Z

I've tested it in a POST form in a turbo-frame that was failing with the current csrf_protection_controller.js and it worked flawlessly.

Thanks @hlecorche.

smnandre · 2025-01-19T17:50:51Z

Do we really need two distinct files for this ? :|

nicolas-grekas · 2025-01-20T07:45:26Z

Definitely one file please here.

hlecorche · 2025-01-21T16:05:07Z

@nicolas-grekas I have merged everything into a single file.

Here are the modified examples :

This code can be used without Turbo. Here's an example:

import { generateCsrfHeaders, removeCsrfToken } from '../controllers/csrf_protection_controller';

// ...

document.addEventListener('before-event-with-jquery-or-custom-fetch-event', function (event) {
	Object.entries(generateCsrfHeaders(event.detail.form)).forEach(([name, value]) => {
	    // add header
	});
});

document.addEventListener('after-event-with-jquery-or-custom-fetch-event', function (event) {
	removeCsrfToken(event.detail.form);
});

It can also be used without relying on the form's submit event :

import { generateCsrfToken, generateCsrfHeaders, removeCsrfToken } from '../controllers/csrf_protection_controller';

// ...

link.addEventListener('click', function (event) {
	const form = document.getElementById('my-form');
	generateCsrfToken(form);
	// Send form with fetch (or jquery) with generateCsrfHeaders and removeCsrfToken functions
});

nicolas-grekas · 2025-01-21T16:27:56Z

symfony/stimulus-bundle/2.20/assets/controllers/csrf_protection_controller.js

+// When @hotwired/turbo handles form submissions, send the CSRF token in a header in addition to a cookie
+// The `framework.csrf_protection.check_header` config option needs to be enabled for the header to be checked
+document.addEventListener('turbo:submit-start', function (event) {
+    Object.entries(generateCsrfHeaders(event.detail.formSubmission.formElement)).forEach(([name, value]) => {


Object.entries isn't available with IE11, while I think the previous script was working with it.
export is also a feature not compatible with IE11 so that maybe the script didn't work with it already, but maybe the eshim made it work in the end?

What I mean is: if the snippet worked with IE11, let's not break IE11 support. Any idea of the status of this?

Turbo and Stimulus do not support IE 11, so I believe it is fine to use more modern API's

No IE support for Stimulus, Turbo, import map, nor the importmap polyfill (see here)

No consequence / difference with today ☺️

this comment is old, the polyfill does support IE11 (at least the .dist version, I've tried already)

The dist file of es-module-shims uses async/await among other things. So it definitely does not support IE11 without transpiling. And it also uses some modern methods that won't work without polyfiling them.

Projects needing to support IE11 probably have an infrastructure to transpile code to ES5 and load polyfills, which would work for this file as well.

nicolas-grekas · 2025-01-23T08:45:49Z

Thank you @hlecorche

hlecorche · 2025-01-23T11:15:38Z

Thanks @nicolas-grekas

nicolas-grekas · 2025-01-23T17:16:50Z

symfony/stimulus-bundle/2.20/assets/controllers/csrf_protection_controller.js


 // Generate and double-submit a CSRF token in a form field and a cookie, as defined by Symfony's SameOriginCsrfTokenManager
 document.addEventListener('submit', function (event) {
-    var csrfField = event.target.querySelector('input[data-controller="csrf-protection"], input[name="_csrf_token"]');
+    generateCsrfToken(event.target);
+}, true);


sorry I missed this during the review: why adding true as third argument here @hlecorche ?

Doing that in the capture phase means that this listener (attached on the root of the document) runs before the listeners attached directly on the form. This ensures that listeners attached on a form to perform custom submission logic (using Ajax for instance) will have the value for the generated CSRF token (instead of generating it too late): https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling#event_capture

and this fixes symfony/symfony#59571

Here’s an example that illustrates the problem :

document.addEventListener('submit', function (event) { if (event.target.matches('form[data-toggle="ajax-form"]')) { event.preventDefault() // Send request with fetch } })

Depending on the order of event listener registration, the event that triggers the fetch request can be executed before the csrf_protection_controller.js event listener. This is exactly what happens in my case, as my event listener is registered during the DOMContentLoaded event, which causes it to run before the CSRF protection logic is applied.

To fix this issue, I used the capture phase (true as the third argument in addEventListener) to ensure that the CSRF protection logic is executed before the fetch request is sent.

stof · 2025-01-21T16:28:04Z

symfony/stimulus-bundle/2.20/assets/controllers/csrf_protection_controller.js

+    removeCsrfToken(event.detail.formSubmission.formElement);
+});
+
+export function generateCsrfToken (formElement) {


why exporting them ? If the goal is to make them reusable elsewhere, this seems a bad idea to me to mix side effects with reusable utilities: code wanting to use those utilities would trigger the side effects of the file (and if you use a bundler able to perform tree-shaking, side effects are bad as they prevent tree shaking).

It's for this reason that the first version of my pull request included two files (Stimulus and utilities)

But yes @stof , the goal is to make them reusable elsewhere :

import { generateCsrfHeaders, removeCsrfToken } from '../controllers/csrf_protection_controller'; // ... document.addEventListener('before-event-with-jquery-or-custom-fetch-event', function (event) { Object.entries(generateCsrfHeaders(event.detail.form)).forEach(([name, value]) => { // add header }); }); document.addEventListener('after-event-with-jquery-or-custom-fetch-event', function (event) { removeCsrfToken(event.detail.form); });

It can also be used without relying on the form's submit event :

import { generateCsrfToken, generateCsrfHeaders, removeCsrfToken } from '../controllers/csrf_protection_controller'; // ... link.addEventListener('click', function (event) { const form = document.getElementById('my-form'); generateCsrfToken(form); // Send form with fetch (or jquery) with generateCsrfHeaders and removeCsrfToken functions });

maybe we can do something about by leveraging the export default entry to register the listeners when stimulus loads the controller?
having one file is desirable to me

stof · 2025-01-21T16:28:34Z

symfony/stimulus-bundle/2.20/assets/controllers/csrf_protection_controller.js

-// The `framework.csrf_protection.check_header` config option needs to be enabled for the header to be checked
-document.addEventListener('turbo:submit-start', function (event) {
-    var csrfField = event.detail.formSubmission.formElement.querySelector('input[data-controller="csrf-protection"]');
+export function generateCsrfHeaders (formElement) {


if we export functions, we should write some JSDoc on them to provide better DX when using them.

More an more I'm thinking such method / exports should not be there.

We provide "plug n play" CSRF here, but we should probably not encourage using this recipe file as vendor/ lib code.

We can remove it / change it at any time in future versions

stof · 2025-01-23T17:42:17Z

symfony/stimulus-bundle/2.20/assets/controllers/csrf_protection_controller.js


 // Generate and double-submit a CSRF token in a form field and a cookie, as defined by Symfony's SameOriginCsrfTokenManager
 document.addEventListener('submit', function (event) {
-    var csrfField = event.target.querySelector('input[data-controller="csrf-protection"], input[name="_csrf_token"]');
+    generateCsrfToken(event.target);
+}, true);


Doing that in the capture phase means that this listener (attached on the root of the document) runs before the listeners attached directly on the form. This ensures that listeners attached on a form to perform custom submission logic (using Ajax for instance) will have the value for the generated CSRF token (instead of generating it too late): https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling#event_capture

symfony-recipes-bot enabled auto-merge (squash) January 8, 2025 19:45

auto-merge was automatically disabled January 21, 2025 15:58
Head branch was pushed to by a user without write access

hlecorche closed this Jan 21, 2025

auto-merge was automatically disabled January 21, 2025 15:58
Pull request was closed

hlecorche reopened this Jan 21, 2025

nicolas-grekas reviewed Jan 21, 2025

View reviewed changes

nicolas-grekas changed the title ~~[stimulus-bundle] Improve CSRF protection~~ [stimulus-bundle] Export CSRF protection helpers Jan 23, 2025

nicolas-grekas force-pushed the issue-1370 branch from 2a4fbea to 5c9bc98 Compare January 23, 2025 08:34

symfony-recipes-bot enabled auto-merge (squash) January 23, 2025 08:34

[stimulus-bundle] Export CSRF protection helpers

2c0d32f

nicolas-grekas force-pushed the issue-1370 branch from 5c9bc98 to 2c0d32f Compare January 23, 2025 08:44

nicolas-grekas disabled auto-merge January 23, 2025 08:44

symfony-recipes-bot enabled auto-merge (squash) January 23, 2025 08:44

nicolas-grekas disabled auto-merge January 23, 2025 08:45

nicolas-grekas merged commit 452e626 into symfony:main Jan 23, 2025
1 of 2 checks passed

aleho mentioned this pull request Jan 23, 2025

[stimulus-bundle] Fix broken CSRF header generation with Turbo forms #1377

Merged

nicolas-grekas reviewed Jan 23, 2025

View reviewed changes

stof reviewed Jan 23, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[stimulus-bundle] Export CSRF protection helpers #1375

[stimulus-bundle] Export CSRF protection helpers #1375

hlecorche commented Jan 8, 2025

github-actions bot commented Jan 8, 2025 •

edited

Loading

ajgarlag commented Jan 15, 2025 •

edited

Loading

smnandre commented Jan 19, 2025

nicolas-grekas commented Jan 20, 2025

hlecorche commented Jan 21, 2025

nicolas-grekas Jan 21, 2025 •

edited

Loading

Kocal Jan 21, 2025

smnandre Jan 21, 2025

nicolas-grekas Jan 23, 2025

stof Jan 23, 2025

nicolas-grekas commented Jan 23, 2025

hlecorche commented Jan 23, 2025

nicolas-grekas Jan 23, 2025 •

edited

Loading

stof Jan 23, 2025

nicolas-grekas Jan 23, 2025

hlecorche Jan 23, 2025

stof Jan 21, 2025

hlecorche Jan 23, 2025

hlecorche Jan 23, 2025

nicolas-grekas Jan 23, 2025

stof Jan 21, 2025

smnandre Jan 23, 2025

stof Jan 23, 2025

[stimulus-bundle] Export CSRF protection helpers #1375

[stimulus-bundle] Export CSRF protection helpers #1375

Conversation

hlecorche commented Jan 8, 2025

github-actions bot commented Jan 8, 2025 • edited Loading

How to test these changes in your application

Diff between recipe versions

symfony/stimulus-bundle

ajgarlag commented Jan 15, 2025 • edited Loading

smnandre commented Jan 19, 2025

nicolas-grekas commented Jan 20, 2025

hlecorche commented Jan 21, 2025

nicolas-grekas Jan 21, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nicolas-grekas commented Jan 23, 2025

hlecorche commented Jan 23, 2025

nicolas-grekas Jan 23, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Jan 8, 2025 •

edited

Loading

ajgarlag commented Jan 15, 2025 •

edited

Loading

nicolas-grekas Jan 21, 2025 •

edited

Loading

nicolas-grekas Jan 23, 2025 •

edited

Loading