{"id":13510296,"url":"https://github.com/ianstormtaylor/permit","last_synced_at":"2025-05-14T11:08:40.639Z","repository":{"id":45993088,"uuid":"130138377","full_name":"ianstormtaylor/permit","owner":"ianstormtaylor","description":"An unopinionated authentication library for building Node.js APIs.","archived":false,"fork":false,"pushed_at":"2022-12-06T19:46:38.000Z","size":719,"stargazers_count":1688,"open_issues_count":9,"forks_count":56,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-05-13T00:06:58.870Z","etag":null,"topics":["authentication","express","fastify","hapi","koa","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ianstormtaylor.png","metadata":{"files":{"readme":"Readme.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"License.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-19T00:43:11.000Z","updated_at":"2025-04-23T22:03:04.000Z","dependencies_parsed_at":"2023-01-23T12:25:15.842Z","dependency_job_id":null,"html_url":"https://github.com/ianstormtaylor/permit","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianstormtaylor%2Fpermit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianstormtaylor%2Fpermit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianstormtaylor%2Fpermit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianstormtaylor%2Fpermit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ianstormtaylor","download_url":"https://codeload.github.com/ianstormtaylor/permit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254129481,"owners_count":22019628,"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","express","fastify","hapi","koa","nodejs"],"created_at":"2024-08-01T02:01:32.464Z","updated_at":"2025-05-14T11:08:40.594Z","avatar_url":"https://github.com/ianstormtaylor.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Repository","nodejs"],"sub_categories":["Authentication"],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"#\"\u003e\u003cimg src=\"./docs/images/banner.png\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  An \u003cem\u003eunopinionated\u003c/em\u003e authentication library \u003cbr/\u003e\n  for building Node.js APIs.\n\u003c/p\u003e\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e •\n  \u003ca href=\"#why\"\u003eWhy?\u003c/a\u003e •\n  \u003ca href=\"#principles\"\u003ePrinciples\u003c/a\u003e •\n  \u003ca href=\"#examples\"\u003eExamples\u003c/a\u003e •\n  \u003ca href=\"#documentation\"\u003eDocumentation\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://travis-ci.org/ianstormtaylor/permit\"\u003e\n    \u003cimg src=\"https://travis-ci.org/ianstormtaylor/permit.svg?branch=master\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"./package.json\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/permit.svg?maxAge=300\u0026label=version\u0026colorB=007ec6\u0026maxAge=300\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"./License.md\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/l/slate.svg?maxAge=300\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cbr/\u003e\n\u003cbr/\u003e\n\nPermit makes it easy to add an authentication layer to any Node.js API. It can be used with any of the popular server frameworks (eg. Express, Koa, Hapi, Fastify) and it can be used for any type of API (eg. REST, GraphQL, etc.) due to its simple, unopinionated design.\n\n\u003cbr/\u003e\n\n### Usage\n\nPermit lets you authenticate via the two schemes most APIs need: a single secret bearer token, or a set of username and password credentials. For example, here's how to authenticate a bearer token:\n\n```js\nimport { Bearer } from 'permit'\n\n// A permit that checks for HTTP Bearer Auth, falling back to a query string.\nconst permit = new Bearer({\n  query: 'access_token',\n})\n\nasync function handler({ req, res }) {\n  // Try to find the bearer token in the request.\n  const token = permit.check(req)\n\n  // No token, that means they didn't pass credentials!\n  if (!token) {\n    permit.fail(res)\n    throw new Error(`Authentication required!`)\n  }\n\n  // Authenticate the token however you'd like...\n  const user = await db.users.findByToken(token)\n\n  // No user, that means their credentials were invalid!\n  if (!user) {\n    permit.fail(res)\n    throw new Error(`Authentication invalid!`)\n  }\n\n  // They were authenticated, so continue with your business logic...\n  ...\n}\n```\n\nSince Permit isn't tightly coupled to a framework or data model, it gives you complete control over how you write your authentication logic—the exact same way you'd write any other request handler.\n\n\u003cbr/\u003e\n\n### Why?\n\nBefore Permit, the only real choice for authentication libraries in Node.js was [Passport.js](http://www.passportjs.org/). But it has a bunch of issues that complicate your codebase...\n\n* **It is not focused on authenticating APIs.** Passport is focused on authenticating _web apps_ with services like Facebook, Twitter and GitHub. APIs don't need that, so all the extra bloat means _lots_ of complexity for no gain.\n\n* **It is tightly-coupled to Express.** If you use Koa, Hapi, Fastify, or some other framework you have to go to great lengths to get it to play nicely. Even if you just want to tweak the opinionated defaults you're often out of luck.\n\n* **Other middleware are tightly-coupled to it.** Passport stores state on the `req` object, so all your other middleware (even other third-party middleware) become tightly coupled to its implementation, making your codebase brittle.\n\n* **It results in lots of hard to debug indirection.** Because of Passport's black-box architecture, whenever you need to debug an issue it's causing you have to trace its logic across many layers of indirection and many repositories.\n\n* **It's not very actively maintained.** Passport's focus on OAuth providers means that it takes on a _huge_ amount of scope, across a lot of repositories, many of which are not actively maintained anymore.\n\nDon't get me wrong, Passport works great for working with OAuth providers. But if you've run into any of these problems before while adding authentication to a Node.js API, you might like Permit.\n\nWhich brings me to how Permit solves these issues...\n\n\u003cbr/\u003e\n\n### Principles\n\n1. **API first.** Permit was designed with authenticating APIs in mind, so it's able to be _much_ leaner than others, since it doesn't need to handle complex OAuth integrations with Facebook, Google, etc.\n\n2. **Stateless requests.** Since the vast majority of APIs are stateless in nature, Permit eschews the complexity that comes with handling session stores—without preventing you from using one if you need to.\n\n3. **Framework agnostic.** Permit doesn't lock you into using any specific server framework or data model, because it's composed of small but powerful utility functions that do the heavy-lifting for you.\n\n4. **Unopinionated interface.** Due to its simple interface, Permit makes it much easier to write and reason about your actual authentication logic, because it's exactly like writing any other route handler for your API.\n\n\u003cbr/\u003e\n\n### Examples\n\nPermit's API is very flexible, allowing it to be used for a variety of use cases depending on your server framework, your feelings about ORMs, your use of promises, etc. Here are a few examples of common patterns...\n\n* [Koa](./examples/koa.js)\n* [Express](./examples/express.js)\n* [Fastify](./examples/fastify.js)\n* [Hapi](./examples/hapi.js)\n* [Generic](./examples/generic.js)\n\n\u003cbr/\u003e\n\n### Documentation\n\nRead the getting started guide to familiarize yourself with how Permit works, or check out the full API reference for more detailed information...\n\n* [**Guide**](./docs/guide.md)\n  * [Installing Permit](./docs/guide.md#installing-permit)\n  * [Creating Permits](./docs/guide.md#creating-permits)\n  * [Writing Authentication Logic](./docs/guide.md#writing-authentication-logic)\n  * [Failing Authentication](./docs/guide.md#failing-authentication)\n* [**Reference**](./docs/reference.md)\n  * [Permit](./docs/reference.md#permit)\n    * [`permit.check`](./docs/reference.md#permit-check)\n    * [`permit.fail`](./docs/reference.md#permit-fail)\n  * [Types](./docs/reference.md#types)\n    * [`Basic`](./docs/reference.md#basic)\n    * [`Bearer`](./docs/reference.md#bearer)\n    * [`Permit`](./docs/reference.md#permit2)\n\n\u003cbr/\u003e\n\n### Thanks\n\nThank you to [@dresende](https://github.com/dresende) for graciously transferring the `permit` package!\n\n\u003cbr/\u003e\n\n### License\n\nThis package is [MIT-licensed](./License.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fianstormtaylor%2Fpermit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fianstormtaylor%2Fpermit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fianstormtaylor%2Fpermit/lists"}