Home

Awesome

<p align="center"> <a href="#"><img src="./docs/images/banner.png" /></a> </p> <p align="center"> An <em>unopinionated</em> authentication library <br/> for building Node.js APIs. </p> <br/> <br/> <p align="center"> <a href="#usage">Usage</a> • <a href="#why">Why?</a> • <a href="#principles">Principles</a> • <a href="#examples">Examples</a> • <a href="#documentation">Documentation</a> </p> <p align="center"> <a href="https://travis-ci.org/ianstormtaylor/permit"> <img src="https://travis-ci.org/ianstormtaylor/permit.svg?branch=master"> </a> <a href="./package.json"> <img src="https://img.shields.io/npm/v/permit.svg?maxAge=300&label=version&colorB=007ec6&maxAge=300"> </a> <a href="./License.md"> <img src="https://img.shields.io/npm/l/slate.svg?maxAge=300"> </a> </p> <br/> <br/>

Permit 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.

<br/>

Usage

Permit 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:

import { Bearer } from 'permit'

// A permit that checks for HTTP Bearer Auth, falling back to a query string.
const permit = new Bearer({
  query: 'access_token',
})

async function handler({ req, res }) {
  // Try to find the bearer token in the request.
  const token = permit.check(req)

  // No token, that means they didn't pass credentials!
  if (!token) {
    permit.fail(res)
    throw new Error(`Authentication required!`)
  }

  // Authenticate the token however you'd like...
  const user = await db.users.findByToken(token)

  // No user, that means their credentials were invalid!
  if (!user) {
    permit.fail(res)
    throw new Error(`Authentication invalid!`)
  }

  // They were authenticated, so continue with your business logic...
  ...
}

Since 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.

<br/>

Why?

Before Permit, the only real choice for authentication libraries in Node.js was Passport.js. But it has a bunch of issues that complicate your codebase...

Don'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.

Which brings me to how Permit solves these issues...

<br/>

Principles

  1. 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.

  2. 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.

  3. 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.

  4. 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.

<br/>

Examples

Permit'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...

<br/>

Documentation

Read the getting started guide to familiarize yourself with how Permit works, or check out the full API reference for more detailed information...

<br/>

Thanks

Thank you to @dresende for graciously transferring the permit package!

<br/>

License

This package is MIT-licensed.