@talismn/siws NPM

SIWS Example

Sign-In with Substrate

@talismn/siws is a package that lets you easily allow users to authenticate themselves with your off chain services by signing in with their Substrate accounts.

Problem & Motivation

When building Signet, an enterprise tool for companies to manage their on-chain organisations in the Substrate ecosystem, we needed a way for users to prove that they own an address before they can request for resources relevant to that address. There was no solution yet that offered good user experience, where users could easily understand what they are signing with their wallet. Inspired by Sign-in with Ethereum, we decided to build the right tool for the Substrate ecosystem.

Features

Construct human readable sign in message
Construct message in stringified JSON format
Decode and parse string message of both format into JS object
Basic validations (e.g. expiration)
Utility Address to help with dealing with address string
Utility verifySIWS to help verify that a signature is valid
Full Typescript support

Installation

$ npm install @talismn/siws

Usage

Frontend

// 1. import necessary modules
import { web3FromSource } from "@polkadot/extension-dapp"
import { SiwsMessage } from "@talismn/siws"

// 2. handle sign in after `account` is selected
const handleSignIn = async () => {
  const siws = new SiwsMessage({
    domain: "localhost",
    uri: "http://localhost:3000/sign-in",
    address: account.address,
    nonce, // a challenge generated from backend
    statement: "Welcome to my dapp!",
  })

  // get the injector so we can sign the message
  const injectedExtension = await web3FromSource(account.meta.source)
  const signed = await siws.sign(injectedExtension)

  // api to sign in with backend
  await signIn(signed)
}

Backend

// 1. import siws
import { verifySIWS } from "@talismn/siws"

// 2. backend handler to handle sign in request
const handleSignInRequest = ({ signature, message, address }) => {
  // verify that signature is valid
  const siwsMessage = await verifySIWS(message, signature, address)

  // ... user has proven ownership of address and hence authenticated!
}