Sign-In with Ethereum (SIWE)

The verify(params, opts) method checks the integrity of a SiweMessage by matching its signature. It supports standard EIP-191 signature recovery and EIP-1271 (contract wallet) verification.

Parameters

params: VerifyParams

• signature: (Required) The signature provided by the user.
• scheme: (Optional) The URI scheme for domain binding. Must match this.scheme if provided.
• domain: (Optional) The domain. Must match this.domain if provided.
• nonce: (Optional) The nonce. Must match this.nonce if provided.
• time: (Optional) The time to use for expiration/not-before checks. Defaults to current time.

opts: VerifyOpts

• suppressExceptions: If true, the method returns a SiweResponse with success: false instead of throwing an error. Defaults to false.
• provider: Used for EIP-1271 contract wallet signature verification.
• verificationFallback: An optional function to provide custom verification logic. It receives (params, opts, siweMessage, eip1271Promise).

Return Value

Returns a Promise<SiweResponse>. A successful verification returns { success: true, data: SiweMessage }. A failed verification returns { success: false, data: SiweMessage, error: Error } (if suppressExceptions is true).

const siweResponse = await message.verify(
  {
    signature: '0x...',
    domain: 'example.com',
  },
  {
    suppressExceptions: true,
    provider: myEthersProvider,
  }
);

The SiweMessage class is the primary interface for creating, formatting, and verifying Sign-In with Ethereum (EIP-4361) messages. You can instantiate it using either a raw SIWE message string or a partial configuration object.

Key Capabilities

• Instantiation: Create a message object from a string (parsed via ABNF) or an object.
• Message Preparation: Generate the exact string required for EIP-191 signing using prepareMessage() or toMessage().
• Verification: Validate a signature against the message using the verify() method.

Fields

• domain: The RFC 4501 DNS authority requesting the signature.
• address: The Ethereum address performing the signing (EIP-55 checksummed).
• chainId: The EIP-155 Chain ID.
• nonce: A random token (at least 8 alphanumeric characters) to prevent replay attacks.
• uri: The resource subject to the signing.
• version: The current version of the message (e.g., '1').
• statement: An optional human-readable ASCII assertion.
• expirationTime / notBefore: ISO 8601 datetime strings for validity windows.
• resources: An array of RFC 3986 URIs for the user to resolve.

import { SiweMessage } from 'siwe';

// 1. Create a message from an object
const message = new SiweMessage({
  domain: 'example.com',
  address: '0x...',
  statement: 'Sign in with your Ethereum account',
  uri: 'https://example.com',
  version: '1',
  chainId: 1,
  nonce: 'random-nonce-string',
});

// 2. Get the string to be signed by the user
const textToSign = message.prepareMessage();

// 3. Verify the signature after the user signs it
const siweResponse = await message.verify({
  signature: '0x...',
  // optional: scheme, domain, nonce, time
});

if (siweResponse.success) {
  console.log('Verified!', siweResponse.data);
} else {
  console.error('Verification failed:', siweResponse.error);
}

The ParsedMessage class is used to parse a raw Sign-In with Ethereum (SIWE) message string into a structured object. When instantiated with a message string, it performs ABNF grammar parsing. If the message is invalid according to the SIWE specification, the constructor will throw an Error containing the parsing errors.

Upon successful parsing, the resulting object contains the following fields:

• scheme: The URI scheme (e.g., siwe).
• domain: The domain of the SIWE message.
• address: The Ethereum address.
• statement: The human-readable message statement.
• uri: The full URI.
• version: The SIWE version.
• chainId: The network chain ID as a number.
• nonce: The unique nonce.
• issuedAt: The issuance timestamp.
• expirationTime: The expiration timestamp (optional).
• notBefore: The 'not before' timestamp (optional).
• requestId: The request ID (optional).
• resources: An array of resource URIs (optional).
• uriElements: An object containing decomposed URI components:
  • scheme
  • userinfo (optional)
  • host (optional)
  • port (optional)
  • path
  • query (optional)
  • fragment (optional)

import { ParsedMessage } from '@spruceid/siwe-parser';

try {
  const msg = "siwe://example.com/\nDomain: example.com\nAddress: 0x...\n...";
  const parsed = new ParsedMessage(msg);
  console.log(parsed.address);
  console.log(parsed.chainId);
} catch (e) {
  console.error("Failed to parse SIWE message:", e.message);
}

The VerifyOpts interface allows you to customize the verification process, such as enabling EIP-1271 support or providing custom fallback logic.

Fields:

• provider (optional): An ethers provider used for EIP-1271 smart contract wallet validation.
• suppressExceptions (optional): If set to true, the library will not throw exceptions on errors (instead, errors are returned in the SiweResponse). Defaults to false.
• verificationFallback (optional): A custom async function that runs alongside the EIP-1271 check. It receives the params, opts, the original message, and a EIP1271Promise which can be awaited to get the result of the standard EIP-1271 check.

const opts: VerifyOpts = {
  provider: myEthersProvider,
  suppressExceptions: true,
  verificationFallback: async (params, opts, message, EIP1271Promise) => {
    const eip1271Result = await EIP1271Promise;
    if (eip1271Result.success) return eip1271Result;
    // Implement custom logic here
    return { success: false, error: new SiweError('Custom error'), data: message };
  }
};

Errors in SIWE verification are encapsulated in the SiweError class. When verification fails, the SiweError provides a machine-readable type and optional context about what was expected versus what was received.

Error Types (SiweErrorType)

• EXPIRED_MESSAGE: expirationTime is in the past.
• INVALID_DOMAIN: domain is empty or invalid.
• SCHEME_MISMATCH: scheme does not match the provided verification scheme.
• DOMAIN_MISMATCH: domain does not match the provided domain.
• NONCE_MISMATCH: nonce does not match the provided nonce.
• INVALID_ADDRESS: address is not a valid address or does not conform to EIP-55.
• INVALID_URI: uri does not conform to RFC 3986.
• INVALID_NONCE: nonce is not alphanumeric or is shorter than 8 characters.
• NOT_YET_VALID_MESSAGE: notBefore is in the future.
• INVALID_SIGNATURE: Signature does not match the message address.
• INVALID_TIME_FORMAT: expirationTime, notBefore, or issuedAt are not ISO-8601 compliant.
• INVALID_MESSAGE_VERSION: version is not 1.
• UNABLE_TO_PARSE: Required fields are missing or the message is malformed.