authrite-express

Express middleware for Authrite

The code is available on GitHub and the package is published on NPM.

Overview

Authrite is a system for mutual authentication over a communications channel where both parties come to know the identity of the counterparty. authrite-express provides a way to easily add mutual authentication to the routes of an express server.

During setup, the client asks for some basic information from the server and provides their identity key. The server sends back a reply, proving custody over the identity key they send back. Then, every message sent between the two parties is signed and verified, enabling everyone to have confidence in message integrity. Messages are not encrypted by Authrite, but encryption is provided by HTTPS.

Installation

npm i authrite-express

Example Middleware Usage

This example demonstrates creating a simple express server that makes use of the authrite-express middleware.

const authrite = require('authrite-express')
const express = require('express')
const bodyparser = require('body-parser')
const app = express()
const port = 5000

const TEST_SERVER_PRIVATE_KEY = 
'6dcc124be5f382be631d49ba12f61adbce33a5ac14f6ddee12de25272f943f8b'
const TEST_SERVER_BASEURL = `http://localhost:${port}`

app.use(bodyparser.json())
app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', '*')
  res.header('Access-Control-Allow-Headers', '*')
  res.header('Access-Control-Allow-Methods', '*')
  res.header('Access-Control-Expose-Headers', '*')
  res.header('Access-Control-Allow-Private-Network', 'true')
  if (req.method === 'OPTIONS') {
    res.sendStatus(200)
  } else {
    next()
  }
})
// Configure the express server to use the authrite middleware
app.use(authrite.middleware({
    serverPrivateKey: TEST_SERVER_PRIVATE_KEY,
    baseUrl: TEST_SERVER_BASEURL
}))

// Example Routes
app.get('/getData', (req, res) => {
    res.json({ user: 'bob' })
}) 
app.post('/sendSomeData', (req, res) => {
    res.json({
        message: 'Hello, this is the server.',
        clientData: req.body
    })
})

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})

Example WebSocket Usage

This example demonstrates setting up a websocket connection on an express server with a simple on chatMessage event.

Note: This does not show starting the express server which can be seen in the example above.

const express = require('express')
const app = express()
const http = require('http').Server(app)
const authrite = require('authrite-express')

const TEST_SERVER_PRIVATE_KEY = 'a0b6131b2ed7c9f6099f35a1e61a18c0e6bca3352a624d9e4b4851403cf52949'

// Configure AuthSock just as you would for socket.io
// Just add an additional param to pass in the server private key to use
const io = authrite.socket(http, {
  cors: {
    origin: '*'
  },
  serverPrivateKey: SERVER_PRIVATE_KEY
})

io.on('connection', (socket) => {
  // Custom events
   socket.on('chatMessage', (msg) => {
    io.emit('chatMessage', {
      id: socket.id,
      text: msg.text,
      identityKey: msg.identityKey
    })
  })
})

API

Table of Contents

• AuthSock
  • Parameters
  • id
  • rooms
  • handshake
  • use
    • Parameters
  • join
    • Parameters
  • leave
    • Parameters
  • to
    • Parameters
  • disconnect
  • close
  • emit
    • Parameters
  • on
    • Parameters
• middleware
  • Parameters

AuthSock

Provides server-side access to Authrite protected sockets

Parameters

• http http.Server The HTTP server instance
• options Object Optional configurations for Socket.IO (optional, default {})

id

Retrieves the unique identifier for the socket connection

Returns string The socket ID

rooms

Retrieves the list of rooms that the socket is currently in

Returns Set<string> A set containing the names of the rooms

handshake

Retrieves information about the initial handshake when the socket connection was established

Returns Object Handshake information including headers, address, secure, etc.

use

Registers a middleware function to intercept events on the socket

Parameters

• socket Socket The socket object to apply the middleware to
• next function The callback function to call after the middleware completes

join

Joins the socket to a specified room

Parameters

• room string The name of the room to join

leave

Leaves a specified room

Parameters

• room string The name of the room to leave

to

Sends a message to all clients in a specified room

Parameters

• room string The name of the room to send the message to

Returns Socket A reference to the socket

disconnect

Disconnects the socket from the server

close

Closes the socket connection

emit

Emits a message to the client

Parameters

• event string The type of event to emit
• data (object | string | Buffer) The data to send with the event

on

Custom configured websocket on method

Parameters

• event string The type of event to handle
• callback function The callback function to be executed when the event occurs

middleware

Authrite express middleware for providing mutual authentication with a client

Parameters

• config object Configures the middleware with initial parameters (optional, default {})

  • config.serverPrivateKey String The server's private key used for derivations
  • config.requestedCertificates Object The RequestedCertificateSet that the server will send to client. An object with certifiers and types, as per the Authrite specification.
  • config.baseUrl String The base url of the express server
  • config.initialRequestPath String The initial route path used to request the server's information and identity key

Returns function Which can be used as authentication middleware in an express server

License

The license for the code in this repository is the Open BSV License.