sp-auth

Simple library for authentication and authorization for web APIs

Documentation

• sp-auth
  • Documentation
  • Overview
  • Features
  • Installation
  • Usage
    • Session Management
    • Free form authorization
    • Encryption & Decryption
    • Single use tokens

Overview

This library aims to provide a set of tools for authentication and authorization of express applications.

Features

• Stateful Sessions
• Stateless Sessions
• Encryption and Decryption using tweetnacl
• One-time tokens
• Free-form authorization(permission checks)

Installation

You can install sp-auth via a package manager:

yarn

$ yarn add @random-guys/sp-auth`

npm

$ npm install @random-guys/sp-auth`

Usage

Session Management

Make sure to add session typings first

declare namespace Express {
  export interface Request {
    session: any;
    sessionID: string;
  }
}

Setting up authentication for your app.

import express from "express";
import { SessionService } from "@random-guys/sp-auth";

const app = express();
const Auth = new SessionService({
  secret: "some-strong-secret",
  stateful: {
    duration: "10m", // 10 minutes
    store: new RedisStore(ioRedisClient)
  },
  stateless: {
    duration: "1m",
    scheme: "MyAppScheme"
  }
});

// automatically load sessions.
app.use(Auth.autoload());

app.post("/signin", async (req, res) => {
  const user = getUser();
  res.json({ token: await Auth.saveSession(user.id, user) });
});

// allow MyAppScheme and Bearer tokens
app.get("/products/:id", Auth.authCheck, async (req, res) => {
  res.json({
    msg: "This is a protected route",
    session: req.session,
    // this is only available with stateful(bearer) sessions
    sessionID: req.sessionID,
    // create a stateless(MyAppScheme) token
    headless: await Auth.headless(req.session)
  });
});

// only allow MyAppScheme
app.post("/products", Auth.headlessCheck(), (req, res) => {
  res.json({ msg: "This is an internal route" });
});

Free form authorization

This allow to check properties or the session using predicates and throw FailedPredicateError with a message if one of them fails.

const sterlingOnly = because(
  "Only users in 'my-workspace' can access this route",
  req => req.session.workspace == "my-workspace"
);
const permissionCheck = checkRequest(null, sterlingOnly);
app.get("/secure", Auth.authCheck, permissionCheck, handler);

Encryption & Decryption

Encryption is done using xsalsa20-poly1305 from the tweetnacl library.

// secrets must be no less than 32 characters long
const secret = await asyncRandomString(32);
const encrypted = await encrypt(payload, secret);
const decryptedPayload = await decrypt(encrypted, secret);

Single use tokens

Create tokens that are revoked once they've been used once.

// create token that expires in 10 minutes
const token = await sessions.commission(sample, "10m");

// view data without revoking
const peekedData = await sessions.peak(token);

// delay automatic expiry by 2 minutes
const sameData = await sessions.refresh(token, "2M");

// first decomission makes the token unusable.
const data = await sessions.decommission(token);