{"id":13484189,"url":"https://github.com/fastify/csrf-protection","last_synced_at":"2026-01-15T22:20:27.082Z","repository":{"id":36976898,"uuid":"164392385","full_name":"fastify/csrf-protection","owner":"fastify","description":"A fastify csrf plugin","archived":false,"fork":false,"pushed_at":"2026-01-01T04:04:21.000Z","size":239,"stargazers_count":165,"open_issues_count":2,"forks_count":21,"subscribers_count":13,"default_branch":"main","last_synced_at":"2026-01-13T04:07:37.091Z","etag":null,"topics":["csrf","csrf-protection","fastify","fastify-plugin"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/@fastify/csrf-protection","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fastify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"fastify","open_collective":"fastify"}},"created_at":"2019-01-07T07:09:39.000Z","updated_at":"2026-01-01T04:04:18.000Z","dependencies_parsed_at":"2026-01-13T04:07:41.731Z","dependency_job_id":null,"html_url":"https://github.com/fastify/csrf-protection","commit_stats":{"total_commits":205,"total_committers":30,"mean_commits":6.833333333333333,"dds":0.6682926829268292,"last_synced_commit":"680c1fce1d67e987acdbd22413fe2970562ce8dc"},"previous_names":["fastify/fastify-csrf","tarang11/fastify-csrf"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/fastify/csrf-protection","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fcsrf-protection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fcsrf-protection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fcsrf-protection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fcsrf-protection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastify","download_url":"https://codeload.github.com/fastify/csrf-protection/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fcsrf-protection/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28472626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T22:13:38.078Z","status":"ssl_error","status_checked_at":"2026-01-15T22:12:11.737Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csrf","csrf-protection","fastify","fastify-plugin"],"created_at":"2024-07-31T17:01:20.398Z","updated_at":"2026-01-15T22:20:27.070Z","avatar_url":"https://github.com/fastify.png","language":"JavaScript","readme":"# @fastify/csrf-protection\n\n[![CI](https://github.com/fastify/csrf-protection/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fastify/csrf-protection/actions/workflows/ci.yml)\n[![NPM version](https://img.shields.io/npm/v/@fastify/csrf-protection.svg?style=flat)](https://www.npmjs.com/package/@fastify/csrf-protection)\n[![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard)\n\nThis plugin helps developers protect their Fastify server against [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) attacks.\nIn order to fully protect against CSRF, developers should study [Cross-Site Request Forgery Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html)\nin depth. See also [pillarjs/understanding-csrf](https://github.com/pillarjs/understanding-csrf) as a good guide.\n\n## Security Disclaimer\n\nSecuring applications against CSRF is a _developer's responsibility_ and it should not be fully trusted to any third-party modules.\nWe do not claim that this module is able to protect an application without a clear study of CSRF, its impact, and the needed mitigations.\n@fastify/csrf-protection provides a series of utilities that developers can use to secure their application.\nWe recommend using [@fastify/helmet](https://github.com/fastify/fastify-helmet) to implement some of those mitigations.\n\nSecurity is always a tradeoff between risk mitigation, functionality, performance, and developer experience.\nAs a result, we will not consider a report of a plugin default configuration option as a security\nvulnerability that might be unsafe in certain scenarios as long as this module provides a\nway to provide full mitigation through configuration.\n\n## Install\n```js\nnpm i @fastify/csrf-protection\n```\n\n### Compatibility\n| Plugin version | Fastify version |\n| ---------------|-----------------|\n| `\u003e=7.x`        | `^5.x`          |\n| `\u003e=4.x \u003c7.x`   | `^4.x`          |\n| `^3.x`         | `^3.x`          |\n\n\nPlease note that if a Fastify version is out of support, then so are the corresponding versions of this plugin\nin the table above.\nSee [Fastify's LTS policy](https://github.com/fastify/fastify/blob/main/docs/Reference/LTS.md) for more details.\n\n## Usage\n\n\n### Use with [`@fastify/cookie`](https://github.com/fastify/fastify-cookie)\n\nIf you use `@fastify/csrf-protection` with `@fastify/cookie`, the CSRF secret will be added to the response cookies.\nBy default, the cookie used will be named `_csrf`, but you can rename it via the `cookieKey` option.\nWhen `cookieOpts` are provided, they **override** the default cookie options. Make sure you restore any of the default options which provide sensible and secure defaults.\n\n```js\nfastify.register(require('@fastify/cookie'))\nfastify.register(require('@fastify/csrf-protection'))\n\n// if you want to sign cookies:\nfastify.register(require('@fastify/cookie'), { secret }) // See following section to ensure security\nfastify.register(require('@fastify/csrf-protection'), { cookieOpts: { signed: true } })\n\n// generate a token\nfastify.route({\n  method: 'GET',\n  path: '/',\n  handler: async (req, reply) =\u003e {\n    const token = reply.generateCsrf()\n    return { token }\n  }\n})\n\n// protect a route\nfastify.route({\n  method: 'POST',\n  path: '/',\n  onRequest: fastify.csrfProtection,\n  handler: async (req, reply) =\u003e {\n    return req.body\n  }\n})\n```\n\n### Use with [`@fastify/session`](https://github.com/fastify/session)\n\nIf you use `@fastify/csrf-protection` with `@fastify/session`, the CSRF secret will be added to the session.\nBy default, the key used will be named `_csrf`, but you can rename it via the `sessionKey` option.\n\n```js\nfastify.register(require('@fastify-session'), { secret: \"a string which is longer than 32 characters\" })\nfastify.register(require('@fastify/csrf-protection'), { sessionPlugin: '@fastify/session' })\n\n// generate a token\nfastify.route({\n  method: 'GET',\n  path: '/',\n  handler: async (req, reply) =\u003e {\n    const token = reply.generateCsrf()\n    return { token }\n  }\n})\n\n// protect a route\nfastify.route({\n  method: 'POST',\n  path: '/',\n  onRequest: fastify.csrfProtection,\n  handler: async (req, reply) =\u003e {\n    return req.body\n  }\n})\n```\n\n### Use with [`@fastify/secure-session`](https://github.com/fastify/fastify-secure-session)\n\nIf you use `@fastify/csrf-protection` with `@fastify/secure-session`, the CSRF secret will be added to the session.\nBy default, the key used will be named `_csrf`, but you can rename it via the `sessionKey` option.\n\n```js\nfastify.register(require('@fastify/secure-session'), { secret: \"a string which is longer than 32 characters\" })\nfastify.register(require('@fastify/csrf-protection'), { sessionPlugin: '@fastify/secure-session' })\n\n// generate a token\nfastify.route({\n  method: 'GET',\n  path: '/',\n  handler: async (req, reply) =\u003e {\n    const token = reply.generateCsrf()\n    return { token }\n  }\n})\n\n// protect a route\nfastify.route({\n  method: 'POST',\n  path: '/',\n  onRequest: fastify.csrfProtection,\n  handler: async (req, reply) =\u003e {\n    return req.body\n  }\n})\n```\n\n### Securing the secret\n\nThe `secret` shown in the code above is strictly just an example. In all cases, you would need to make sure that the `secret` is:\n- **Never** hard-coded in the code or `.env` files or anywhere in the repository\n- Stored in some external services like KMS, Vault, or something similar\n- Read at run-time and supplied to this option\n- Of significant character length to provide adequate entropy\n- A truly random sequence of characters (You could use [crypto-random-string](https://npm.im/crypto-random-string))\n\nApart from these safeguards, it is extremely important to [use HTTPS for your website/app](https://letsencrypt.org/) to avoid a bunch of other potential security issues like [MITM attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) etc.\n\n## API\n\n### Module Options\n\n| Options      | Description |\n| ----------- | ----------- |\n| `cookieKey` |  The name of the cookie where the CSRF secret will be stored, default `_csrf`.     |\n| `cookieOpts` |  The cookie serialization options. See [@fastify/cookie](https://github.com/fastify/fastify-cookie).    |\n| `sessionKey` |  The key where to store the CSRF secret in the session.     |\n| `getToken` |  A sync function to get the CSRF secret from the request.     |\n| `getUserInfo` |  A sync function to get a string of user-specific information to prevent cookie tossing.     |\n| `sessionPlugin` |  The session plugin that you are using (if applicable).     |\n| `csrfOpts` |  The csrf options. See [@fastify/csrf](https://github.com/fastify/csrf).     |\n| `logLevel` | The log level for `fastify.csrfProtection` errors.     |\n\n### `reply.generateCsrf([opts])`\n\nGenerates a secret (if it is not already present) and returns a promise that resolves to the associated secret.\n\n```js\nconst token = reply.generateCsrf()\n```\n\nYou can also pass the [cookie serialization](https://github.com/fastify/fastify-cookie) options to the function.\n\nThe option `userInfo` is required if `getUserInfo` has been specified in the module option.\nThe provided `userInfo` is hashed inside the csrf token and it is not directly exposed.\nThis option is needed to protect against cookie tossing.\nThe option `csrfOpts.hmacKey` is required if `getUserInfo` has been specified in the module option in combination with using [@fastify/cookie](https://github.com/fastify/fastify-cookie) as sessionPlugin.\n\n### `fastify.csrfProtection(request, reply, next)`\n\nA hook that you can use for protecting routes or entire plugins from CSRF attacks.\nGenerally, we recommend using an `onRequest` hook, but if you are sending the token\nvia the request body, then you must use a `preValidation` or `preHandler` hook.\n\n```js\n// protect the fastify instance\nfastify.addHook('onRequest', fastify.csrfProtection)\n\n// protect a single route\nfastify.route({\n  method: 'POST',\n  path: '/',\n  onRequest: fastify.csrfProtection,\n  handler: async (req, reply) =\u003e {\n    return req.body\n  }\n})\n```\n\nYou can configure the function to read the CSRF token via the `getToken` option, by default the following is used:\n\n```js\nfunction getToken (req) {\n  return (req.body \u0026\u0026 req.body._csrf) ||\n    req.headers['csrf-token'] ||\n    req.headers['xsrf-token'] ||\n    req.headers['x-csrf-token'] ||\n    req.headers['x-xsrf-token']\n}\n```\n\nIt is recommended to provide a custom `getToken` function for performance and [security](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#use-of-custom-request-headers) reasons.\n\n```js\nfastify.register(require('@fastify/csrf-protection'),\n  { getToken: function (req) { return req.headers['csrf-token'] } }\n)\n```\nor\n\n```js\nfastify.register(require('@fastify/csrf-protection'),\n  { getToken: (req) =\u003e req.headers['csrf-token'] }\n)\n```\n\n## License\n\nLicensed under [MIT](./LICENSE).\n","funding_links":["https://github.com/sponsors/fastify","https://opencollective.com/fastify"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Fcsrf-protection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastify%2Fcsrf-protection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Fcsrf-protection/lists"}