@rill/auth

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

Installation

``console
npm install @rill/session @rill/auth
`

Example

`js
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

`js
// 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 })

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

`js
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.

`js
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.

`js
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.

`js
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.

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

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

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

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

$3

* Use npm test` to run tests.

Please feel free to create a PR!