![](\"https://img.shields.io/npm/v/csrf-sync\")
\n \n 
\n \n ![](\"https://discordapp.com/api/guilds/643569902866923550/widget.png?style=shield\")
\n \n \n ![](\"https://ko-fi.com/img/githubbutton_sm.svg\")
\n \n\n \n \n \n \n \n \n \n \n
\n Getting Started •\n Configuration •\n FAQ •\n Support\n
\n\n\n This module intends to provide the necessary pieces required to implement CSRF protection using the Synchroniser Token Pattern. This means you will require server side state, if you require stateless CSRF protection, please see csrf-csrf for the Double-Submit Cookie Pattern.\n
\n\n\n Since csurf has been deprecated I struggled to find alternative solutions that were accurately implemented and configurable, so I decided to write my own! A lot of CSRF protection based packages often try to provide a full solution, or they only provide the Double-Submit Cookie method, and in doing so, they become rather complicated to configure. So much so, that your configuration alone could render the protection completely useless.\n\n\n
\n This is why csrf-sync aims to provide a single and targeted implementation to simplify it's use.\n
\n This section will guide you through using the default setup, which does sufficiently implement the Synchronised Token Pattern. Be sure to check the FAQ as it can help you determine whether you need CSRF protection, and if you do, whether csrf-sync is an appropriate choice, as well as provide insight on how to use it appropriately. If you would like to customise the configuration, see the configuration section, whenever you change a configuration, you should ensure you understand the impact of the change.\n
\n You will need to be using express-session (or a session middleware which provides a request.session property). this utility will add a csrfToken property to request.session.\n
\n This will extract the default utilities, you can configure these and re-export them from your own module. For handling the CSRF token see \"How should the CSRF token be transmitted?\" from the FAQ.\n
\n\n You may need to create your own route(s) for generating and retrieving a token. For example, a JSON endpoint which you can call before making form submissions:\n
\n\n```js\nconst myRoute = (req, res) => res.json({ token: generateToken(req) });\nconst myProtectedRoute = (req, res) =>\n res.json({ unpopularOpinion: \"Game of Thrones was amazing\" });\n```\n\nYou can also put the token into the context of a templated HTML response. Note in this case, the route is aGET request, and these request types are not protected (ignored request method), as they do not need to be protected so long as the route is not exposing any sensitive or sideeffect actions.\n\n```js\n// Make sure your session middleware is registered before these\nexpress.use(session);\nexpress.get(\"/csrf-token\", myRoute);\nexpress.use(csrfSynchronisedProtection);\n// Anything registered after this will be considered \"protected\"\n```\n\n\n You can also protect your routes on a case-to-case basis:\n
\n\n```js\napp.get(\"/secret-stuff\", csrfSynchronisedProtection, myProtectedRoute);\n```\n\nOnce a route is protected, you will need to include the most recently generated token in the `x-csrf-token` request header, otherwise you'll receive a `403 - ForbiddenError: invalid csrf token`.\n\nBy default if a token already exists on the session object, generateToken will not overwrite it, it will simply return the existing token. If you wish to force a token generation, you can use the second parameter:
\n\n```js\ngenerateToken(req, true); // This will force a new token to be generated, even if one already exists\n```\n\n
Instead of importing and using generateToken, you can also use req.csrfToken any time after the csrfSynchronisedProtection middleware has executed on your incoming request.
generateToken with overwrite set to true, this will revoke the any existing token and only the new one will be valid.\n\n\n Optional
\n Default:\n
statusCode, the contained error message, and it's code, the error is constructed via createHttpError. The default values match that of csurf for convenience.\n\n\n\n Optional
\n Default:\n
This function should return the token sent by the frontend, either in the request body/payload, or from the x-csrf-token header. Do NOT return the value from a cookie in this function, this would be the same as having no CSRF protection at all, see the \"How thould the csrf token be transmitted?\" section of the FAQ.
\n\n\n
\n Optional
\n Default:\n
This function should return the token from the backend state for the uniquely identified Request.
\n\n\n\n Optional
\n Default: 128\n
The size in bytes of the generated CSRF tokens.
\n\n\nOptional - Use this option with extreme caution*
\n\nUsed to determine whether CSRF protection should be skipped for the given request. If this callback is provided and the request is not in the ignoredMethods, then the callback will be called to determine whether or not CSRF token validation should be checked. If it returns true the CSRF protection will be skipped, if it returns false then CSRF protection will be checked.
\n\n
* It is primarily provided to avoid the need of wrapping the csrfSynchronisedProtection middleware in your own middleware, allowing you to apply a global logic as to whether or not CSRF protection should be executed based on the incoming request. You should only skip CSRF protection for cases you are 100% certain it is safe to do so, for example, requests you have identified as coming from a native app. You should ensure you are not introducing any vulnerabilities that would allow your web based app to circumvent the protection via CSRF attacks. This option is NOT a solution for CSRF errors.
\n Optional
\n Default:\n
This function should store the token in the backend state for the uniquely identified Request.
\n\n\ncsrfSync, you have a few options available for configuration, all of them are optional and have sensible defaults (shown below).\n\n```js\nconst csrfSyncProtection = csrfSync({\n ignoredMethods = [\"GET\", \"HEAD\", \"OPTIONS\"],\n getTokenFromState = (req) => {\n return req.session.csrfToken;\n }, // Used to retrieve the token from state.\n getTokenFromRequest = (req) => {\n return req.headers['x-csrf-token'];\n }, // Used to retrieve the token submitted by the request from headers\n storeTokenInState = (req, token) => {\n req.session.csrfToken = token;\n }, // Used to store the token in state.\n size = 128, // The size of the generated tokens in bits\n});\n\n// NOTE THE VALUES ABOVE ARE THE DEFAULTS.\n// THE ABOVE IS THE SAME AS DOING:\n\nconst csrfSyncProtection = csrfSync();\n```\n\ncsrf-sync itself will not support promises or async, however there is a way around this. If your CSRF token is stored externally and needs to be retrieved asynchronously, you can register an asynchronous middleware first, which exposes the token.
And in this example, your `getTokenFromRequest` would look like this:
\n\n```js\n(req) => req.asyncCsrfToken;\n```\n\npsifi-support channel.\n ![\"Buy](\"https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png\")
","users":{}}