@valora/express-siwe
TypeScript icon, indicating that this package has built-in type declarations

1.0.0 • Public • Published

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.

Package Sidebar

Install

npm i @valora/express-siwe

Weekly Downloads

251

Version

1.0.0

License

Apache-2.0

Unpacked Size

29.5 kB

Total Files

12

Last publish

Collaborators

  • satishr
  • valora-bot
  • jeanregisser
  • jh2oman
  • dievazqu
  • jophish
  • caj-valora
  • sbw