explaining CSRF in Plone

Author: jensens

docs/classic-ui/csrf.md

@@ -11,3 +11,39 @@ myst:
 
 # Cross-Site Request Forgery (CSRF)
 
+Cross-Site Request Forgery (CSRF or XSRF) is a type of web attack that allows an attacker to send malicious requests to a web application on behalf of a legitimate user.
+The attack works by tricking the user's web browser into sending a request to the web application that the user did not intentionally make. This can allow an attacker to perform actions on the web application without the user's knowledge or consent.
+
+For example, consider a web application that allows users to transfer money between accounts.
+An attacker could craft a malicious link or form that, when clicked or submitted by a victim, would transfer money from the victim's account to the attacker's account.
+If the victim is logged into the web application and clicks the link or form, the web application would receive a request to transfer the money, and it would comply with the request because it appears to come from a legitimate user.
+
+To protect against CSRF attacks, Plone uses CSRF tokens to verify the authenticity of requests.
+CSRF tokens are unique, secret values that are generated by the web application and included in forms and links.
+When a form or link with a valid CSRF token is submitted, the web application can verify the authenticity of the request by checking the token.
+If the token is missing or invalid, the request is rejected.
+
+## Auto protection
+
+In Plone, CSRF protection is done almost transparently by [plone.protect](https://pypi.org/project/plone.protect/).
+One important aspect of `plone.protect` is that it performs the CSRF protection check on the database transaction commit, rather than at the beginning of the request.
+This means that the view can execute and make changes to the database, but the changes will not be persisted unless a valid CSRF token is present in the request.
+
+When a logged-in user requests a page, Plone automatically includes the auth token in all forms through the application of a transform for the `plone.transformchain` that adds a hidden field with the token.
+This includes, but is not limited to the following:
+
+- add and edit forms
+- control-panels
+- custom z3c-forms
+
+## Manual protection
+
+TODO
+
+## Allowing writes in absence of a protecting token
+
+TODO
+
+```{seealso}
+The [README file of `plone.protect`](https://github.com/plone/plone.protect/blob/master/README.rst) explains the usage and also validation in detail.
+```