@anders94/siwe

A lightweight TypeScript implementation of Sign-In with Ethereum (EIP-4361).

Why this library?

Most SIWE implementations depend on heavy Ethereum libraries like ethers.js or viem. This library uses only @noble/secp256k1 and @noble/hashes for cryptographic operations, resulting in a much smaller bundle size for applications that don't need a full Ethereum library.

Installation

npm install @anders94/siwe

Usage

Creating a SIWE message

import { SiweMessage } from '@anders94/siwe';

const message = new SiweMessage({
  domain: 'myapp.com',
  address: '0x1234567890123456789012345678901234567890',
  statement: 'Sign in to My App',
  uri: 'https://myapp.com',
  version: '1',
  chainId: 1,
  nonce: 'randomNonce123',
  issuedAt: new Date().toISOString(),
  expirationTime: new Date(Date.now() + 3600000).toISOString(), // optional
  notBefore: new Date().toISOString(), // optional
  requestId: 'request-123', // optional
  resources: ['https://myapp.com/api'] // optional
});

// Get the message string to be signed
const messageString = message.prepareMessage();

Parsing a SIWE message

import { SiweMessage } from '@anders94/siwe';

const messageString = `myapp.com wants you to sign in with your Ethereum account:
0x1234567890123456789012345678901234567890

Sign in to My App

URI: https://myapp.com
Version: 1
Chain ID: 1
Nonce: randomNonce123
Issued At: 2024-01-01T00:00:00.000Z`;

const message = SiweMessage.fromString(messageString);

Validating a signature

import { SiweMessage } from '@anders94/siwe';

const message = new SiweMessage({
  domain: 'myapp.com',
  address: userAddress,
  uri: 'https://myapp.com',
  version: '1',
  chainId: 1,
  nonce: 'randomNonce123',
  issuedAt: new Date().toISOString()
});

try {
  // Validates signature and checks expiration/notBefore times
  await message.validate(signature);
  console.log('Signature valid!');
} catch (error) {
  console.error('Validation failed:', error.message);
}

Low-level signature verification

import { checkSignature } from '@anders94/siwe';

const isValid = await checkSignature(message, signature, expectedAddress);

API

SiweMessage

Constructor Options

Property	Type	Required	Description
domain	string	Yes	The domain requesting the sign-in
address	string	Yes	Ethereum address (0x-prefixed)
uri	string	Yes	URI of the resource
version	string	Yes	SIWE version (typically "1")
chainId	number	Yes	EIP-155 chain ID
nonce	string	Yes	Randomized token for replay protection
issuedAt	string	Yes	ISO 8601 timestamp
statement	string	No	Human-readable message
expirationTime	string	No	ISO 8601 expiration time
notBefore	string	No	ISO 8601 time before which message is invalid
requestId	string	No	Request identifier
resources	string[]	No	List of resource URIs

Methods

• prepareMessage(): string - Returns the EIP-4361 formatted message string
• toMessage(): string - Alias for prepareMessage()
• validate(signature: string): Promise<SiweMessage> - Validates signature and time constraints
• static fromString(str: string): SiweMessage - Parses an EIP-4361 message string

checkSignature

function checkSignature(
  message: string,
  signature: string,
  expectedAddress: string
): Promise<boolean>

Low-level function to verify an Ethereum signature matches an expected address.

License

MIT