@rill/auth v3.0.0

Simple session authentication with login and logout for Rill with support for timeouts, refreshes and more.

Installation

npm install @rill/session @rill/auth

Example

const rill = require('rill')
const app = rill()
const session = require('@rill/session')
const auth = require('@rill/auth')

// Setup middleware
app.use(session()) // A session is required
app.use(auth())

// Work with authentication.
app.use((ctx, next)=> {
  var user = ...

  // A user can be anything.
  ctx.login(user, {
    ttl: '30 minutes', // optionally override ttl option
    refresh: false // optionally override refresh option
  })

  // User is attached to and a cookie created.
  ctx.locals.user === user //-> true

  // Test if a user is logged in.
  ctx.isLoggedIn() //-> true
  ctx.isLoggedOut() //-> false

  // Removes the user cookie.
  ctx.logout()
});

// Route that only allows logged in users.
app.get('/a', auth.isLoggedIn(), ...)

// Route that only allows logged out in users.
app.get('/b', auth.isLoggedOut(), ...)

Options

// To enable a login that automatically refreshes and expires after 1 hour of inactivity you can use:
{
  "key": "different-cookie-key", // change cookie name
  "ttl": "1 hour", // change when the auth expires.
  "refresh": true // automatically reset auth expiry on page load.
}

Utilities

auth.isLoggedIn({ fail, redirect, fallback })

Creates a middleware that will only continue if a user is logged in.

If the fail option is supplied it will throw a 401 error with the provided message when the user is not logged in.

app.use(auth.isLoggedIn({ fail: 'You must be logged in to access the api.' }))

If the redirect option is supplied it will redirect when the user is not logged in.

app.use(auth.isLoggedIn({ redirect: '/login' }))

If the fallback option is supplied it will call the fallback function when the user is not logged in.

app.use(auth.isLoggedIn({ fallback: handleUserNotLoggedIn }))
function handleUserNotLoggedIn (ctx, next) {...}

Otherwise nothing will happen but the next middleware will not be called.

auth.isLoggedOut({ fail, redirect, fallback })

If the fail option is supplied it will throw a 401 error with the provided message when the user is logged in.

app.use(auth.isLoggedOut({ fail: 'This page is only accessable when not logged in' }))

If the redirect option is supplied it will redirect when the user is logged in.

app.use(auth.isLoggedOut({ redirect: '/dashboard' }))

If the fallback option is supplied it will call the fallback function when the user is logged in.

app.use(auth.isLoggedOut({ fallback: handleUserLoggedIn }))
function handleUserLoggedIn (ctx, next) {...}

Otherwise nothing will happen but the next middleware will not be called.

Contributions

• Use npm test to run tests.

Please feel free to create a PR!