Nanoprogrammed Penultimate Musicianship

    @rill/auth

    3.0.0 • Public • Published

    Rill
    @rill/auth
    API stability Standard NPM version Downloads Gitter Chat

    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!

    Install

    npm i @rill/auth

    DownloadsWeekly Downloads

    0

    Version

    3.0.0

    License

    MIT

    Last publish

    Collaborators

    • dylanpiercey