{"id":13484185,"url":"https://github.com/fastify/fastify-auth","last_synced_at":"2025-05-14T14:08:44.792Z","repository":{"id":38375700,"uuid":"96610023","full_name":"fastify/fastify-auth","owner":"fastify","description":"Run multiple auth functions in Fastify","archived":false,"fork":false,"pushed_at":"2025-05-01T08:35:50.000Z","size":261,"stargazers_count":364,"open_issues_count":1,"forks_count":57,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-05-01T09:34:19.372Z","etag":null,"topics":["authentication","fastify","fastify-plugin","strategy-pattern"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/@fastify/auth","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},"funding":{"github":"fastify","open_collective":"fastify"}},"created_at":"2017-07-08T09:47:16.000Z","updated_at":"2025-05-01T08:35:46.000Z","dependencies_parsed_at":"2023-02-12T21:15:51.446Z","dependency_job_id":"346de92f-f9d7-4fb8-8288-9cf2d6a3eeea","html_url":"https://github.com/fastify/fastify-auth","commit_stats":{"total_commits":209,"total_committers":42,"mean_commits":4.976190476190476,"dds":0.7129186602870814,"last_synced_commit":"b440d9ffba5faab18fc57909a22c246a016b036d"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastify","download_url":"https://codeload.github.com/fastify/fastify-auth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254159935,"owners_count":22024566,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["authentication","fastify","fastify-plugin","strategy-pattern"],"created_at":"2024-07-31T17:01:20.358Z","updated_at":"2025-05-14T14:08:44.785Z","avatar_url":"https://github.com/fastify.png","language":"JavaScript","readme":"# @fastify/auth\n\n[![CI](https://github.com/fastify/fastify-auth/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fastify/fastify-auth/actions/workflows/ci.yml)\n[![NPM version](https://img.shields.io/npm/v/@fastify/auth.svg?style=flat)](https://www.npmjs.com/package/@fastify/auth)\n[![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard)\n\nThis module does not provide an authentication strategy but offers a fast utility to handle authentication and multiple strategies in routes without adding overhead.\nSee a complete example [here](test/example.js).\n\n## Install\n```\nnpm i @fastify/auth\n```\n\n### Compatibility\n| Plugin version | Fastify version |\n| ---------------|-----------------|\n| `\u003e=5.x`        | `^5.x`          |\n| `\u003e=3.x \u003c5.x`   | `^4.x`          |\n| `\u003e=1.x \u003c3.x`   | `^3.x`          |\n| `^0.x`         | `^2.x`          |\n| `^0.x`         | `^1.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`@fastify/auth` does not provide an authentication strategy; authentication strategies must be provided using a decorator or another plugin.\n\nThe following example provides a straightforward implementation to demonstrate the usage of this module:\n```js\nfastify\n  .decorate('verifyJWTandLevel', function (request, reply, done) {\n    // your validation logic\n    done() // pass an error if the authentication fails\n  })\n  .decorate('verifyUserAndPassword', function (request, reply, done) {\n    // your validation logic\n    done() // pass an error if the authentication fails\n  })\n  .register(require('@fastify/auth'))\n  .after(() =\u003e {\n    fastify.route({\n      method: 'POST',\n      url: '/auth-multiple',\n      preHandler: fastify.auth([\n        fastify.verifyJWTandLevel,\n        fastify.verifyUserAndPassword\n      ]),\n      handler: (req, reply) =\u003e {\n        req.log.info('Auth route')\n        reply.send({ hello: 'world' })\n      }\n    })\n  })\n```\n\nThe default relationship of these customized authentication strategies is `or`, but `and` can also be used:\n```js\nfastify\n  .decorate('verifyAdmin', function (request, reply, done) {\n    // your validation logic\n    done() // pass an error if the authentication fails\n  })\n  .decorate('verifyReputation', function (request, reply, done) {\n    // your validation logic\n    done() // pass an error if the authentication fails\n  })\n  .register(require('@fastify/auth'))\n  .after(() =\u003e {\n    fastify.route({\n      method: 'POST',\n      url: '/auth-multiple',\n      preHandler: fastify.auth([\n        fastify.verifyAdmin,\n        fastify.verifyReputation\n      ], {\n        relation: 'and'\n      }),\n      handler: (req, reply) =\u003e {\n        req.log.info('Auth route')\n        reply.send({ hello: 'world' })\n      }\n    })\n  })\n```\n\nFor composite authentication, such as verifying user passwords and levels or meeting VIP criteria, use nested arrays.\nFor example, the logic [(verifyUserPassword `and` verifyLevel) `or` (verifyVIP)] can be achieved with the following code:\n```js\nfastify\n  .decorate('verifyUserPassword', function (request, reply, done) {\n    // your validation logic\n    done() // pass an error if the authentication fails\n  })\n  .decorate('verifyLevel', function (request, reply, done) {\n    // your validation logic\n    done() // pass an error if the authentication fails\n  })\n  .decorate('verifyVIP', function (request, reply, done) {\n    // your validation logic\n    done() // pass an error if the authentication fails\n  })\n  .register(require('@fastify/auth'))\n  .after(() =\u003e {\n    fastify.route({\n      method: 'POST',\n      url: '/auth-multiple',\n      preHandler: fastify.auth([\n        [fastify.verifyUserPassword, fastify.verifyLevel], // The arrays within an array have the opposite relation to the main (default) relation.\n        fastify.verifyVIP\n      ], {\n        relation: 'or' // default relation\n      }),\n      handler: (req, reply) =\u003e {\n        req.log.info('Auth route')\n        reply.send({ hello: 'world' })\n      }\n    })\n  })\n```\n\nIf the `relation` (`defaultRelation`) parameter is `and`, then the relation inside sub-arrays will be `or`.\nIf the `relation` (`defaultRelation`) parameter is `or`, then the relation inside sub-arrays will be `and`.\n\n| auth code        | resulting logical expression           |\n| ------------- |:-------------:|\n| `fastify.auth([f1, f2, [f3, f4]], { relation: 'or' })`  | `f1 OR f2 OR (f3 AND f4)` |\n| `fastify.auth([f1, f2, [f3, f4]], { relation: 'and' })` | `f1 AND f2 AND (f3 OR f4)` |\n\n\nThe `defaultRelation` option can be used while registering the plugin to change the default `relation`:\n```js\nfastify.register(require('@fastify/auth'), { defaultRelation: 'and'} )\n```\n\n_For more examples, please check [`example-composited.js`](test/example-composited.js)_\n\nThis plugin supports `callback`s and `Promise`s returned by functions. Note that an `async` function **does not have** to call the `done` parameter, otherwise, the route handler linked to the auth methods [might be called multiple times](https://fastify.dev/docs/latest/Reference/Hooks/#respond-to-a-request-from-a-hook):\n```js\nfastify\n  .decorate('asyncVerifyJWTandLevel', async function (request, reply) {\n    // your async validation logic\n    await validation()\n    // throws an error if the authentication fails\n  })\n  .decorate('asyncVerifyUserAndPassword', function (request, reply) {\n    // return a promise that throws an error if the authentication fails\n    return myPromiseValidation()\n  })\n  .register(require('@fastify/auth'))\n  .after(() =\u003e {\n    fastify.route({\n      method: 'POST',\n      url: '/auth-multiple',\n      preHandler: fastify.auth([\n        fastify.asyncVerifyJWTandLevel,\n        fastify.asyncVerifyUserAndPassword\n      ]),\n      handler: (req, reply) =\u003e {\n        req.log.info('Auth route')\n        reply.send({ hello: 'world' })\n      }\n    })\n  })\n```\n\n\nRoute definition should be done as [a plugin](https://github.com/fastify/fastify/blob/main/docs/Reference/Plugins.md) or within an `.after()` callback. For a complete example, see [example.js](test/example.js).\n\n`@fastify/auth` runs all authentication methods, allowing the request to continue if at least one succeeds; otherwise, it returns an error to the client.\nAny successful authentication stops `@fastify/auth` from trying the rest unless the `run: 'all'` parameter is provided:\n```js\nfastify.route({\n  method: 'GET',\n  url: '/run-all',\n  preHandler: fastify.auth([\n    (request, reply, done) =\u003e { console.log('executed 1'); done() },\n    (request, reply, done) =\u003e { console.log('executed 2'); done() },\n    (request, reply, done) =\u003e { console.log('executed 3'); done(new Error('you are not authenticated')) },\n    (request, reply, done) =\u003e { console.log('executed 4'); done() },\n    (request, reply, done) =\u003e { console.log('executed 5'); done(new Error('you shall not pass')) }\n  ], { run: 'all' }),\n  handler: (req, reply) =\u003e { reply.send({ hello: 'world' }) }\n})\n```\nThis example shows all console logs and always replies with `401: you are not authenticated`.\nThe `run` parameter is useful for adding business data read from auth tokens to the request.\n\n\nThis plugin can be used at the route level as in the above example or at the hook level using the `preHandler` hook:\n```js\nfastify.addHook('preHandler', fastify.auth([\n  fastify.verifyJWTandLevel,\n  fastify.verifyUserAndPassword\n]))\n\nfastify.route({\n  method: 'POST',\n  url: '/auth-multiple',\n  handler: (req, reply) =\u003e {\n    req.log.info('Auth route')\n    reply.send({ hello: 'world' })\n  }\n})\n```\n\nThe difference between the two approaches is that using the route-level `preHandler` function runs authentication for the selected route only, while using the `preHandler` hook runs authentication for all routes in the current plugin and its descendants.\n\n## Security Considerations\n\n### Hook selection\n\nIn the [Fastify Lifecycle](https://fastify.dev/docs/latest/Reference/Lifecycle/), the `onRequest` and `preParsing` stages do not parse the payload, unlike the `preHandler` stage. Parsing the body can be a potential security risk, as it can be used for denial of service (DoS) attacks. Therefore, it is recommended to avoid parsing the body for unauthorized access.\n\nUsing the `@fastify/auth` plugin in the `preHandler` hook can result in unnecessary memory allocation if a malicious user sends a large payload in the request body and the request is unauthorized. Fastify will parse the body, even though the request is not authorized, leading to unnecessary memory allocation. To avoid this, use an `onRequest` or `preParsing` hook for authentication if the method does not require the request body, such as `@fastify/jwt`, which expects authentication in the request header.\n\nFor authentication methods that require the request body, such as sending a token in the body, use the `preHandler` hook.\n\nIn mixed cases, you must use the `preHandler` hook.\n\n## API\n\n### Options\n\n*@fastify/auth* accepts the options object:\n\n```js\n{\n  defaultRelation: 'and'\n}\n```\n\n+ `defaultRelation` (Default: `or`): The default relation between the functions. It can be either `or` or `and`.\n\n## Acknowledgments\n\nThis project is kindly sponsored by:\n- [LetzDoIt](https://www.letzdoitapp.com/)\n\n## License\n\nLicensed under [MIT](./LICENSE).\n","funding_links":["https://github.com/sponsors/fastify","https://opencollective.com/fastify"],"categories":["JavaScript","\u003ch2 align=\"center\"\u003eAwesome Fastify\u003c/h2\u003e"],"sub_categories":["\u003ch2 align=\"center\"\u003eEcosystem\u003c/h2\u003e"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Ffastify-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastify%2Ffastify-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Ffastify-auth/lists"}