express-siwe

SIWE middlewares for express applications

Usage

import express from 'express'
import Session from 'express-session'
import { loginHandler, authMiddleware, SiweError } from '@valora/express-siwe'

// initialize express app and include session and json body parser middlewares
const app = express()
app.use(
  Session({
    secret: 'secret',
  }),
)
app.use(express.json())

// add login route
app.use(
  '/auth/login',
  loginHandler({
    sessionDurationMs: 3600000,
    validateNonce: async (nonce: string) => {
      /* validate nonce, ensure it isn't already used and return true / false */
    },
    markNonceAsUsed: async (nonce: string, expirationTime: Date) => {
      /* save nonce to some store */
    },
    chainId: 1,
    domain: 'foo.com',
  }),
)

// include auth middleware for secure routes
app.get('/some/secure/route', authMiddleware, (req, res) => {
  /* handle request */
})

// error handler
app.use((err, req, res, next) => {
  if (err instanceof SiweError) {
    /* handle siwe error and return appropriate error codes */
  }
  /* handle other errors */
})

API

loginHandler(options: LoginOptions): express.Router

Creates an express router with a single post route / that handles a SIWE login request. The route expects a JSON body with shape:

{
  "message": "<the serialized SIWE message>",
  "signature": "<the SIWE signature>"
}

On a successful SIWE login, the route returns a 200 response with a session cookie. On any error, the route invokes the express next function with a SiweRequestError with appropriate SiweRequestErrorType.

Login Options:

• validateNonce: (nonce: string) => Promise<boolean>, required
  • A function to validate whether the nonce is valid and not already used
• markNonceAsUsed: (nonce: string, expirationTime: Date) => Promise<void>, required
  • A function to mark nonce as used. Could use some persistent store to save used nonces
• sessionDurationMs: number, required
  • The duration to issue session's for. The expirationTime on the SIWE message must not be greater than the session duration.
• chainId: number, optional
  • If set, compares the chainId on the SIWE message with this field and throws an error on mismatch
• domain: string, optional
  • If set, compares the domain on the SIWE message with this field and throws an error on mismatch

authMiddleware(req: express.Request, res: express.Response, next: express.NextFunction): void

An express middleware that validates whether a SIWE session exists. Invokes next with no args if a valid session exists. Otherwise, invokes next with a SiweRequestError of type SiweRequestErrorType.UNAUTHORIZED.

Release

This project uses semantic-release to automatically publish new versions to NPM. You must use PR titles adhering to the conventional commits standard (also enforced in CI) for this to work properly.