# Siwe

Utility functions for working with
[EIP-4361: Sign-In with Ethereum](https://eips.ethereum.org/EIPS/eip-4361)

## Examples

Below are some examples demonstrating common usages of the `Siwe` module:

* [Creating a SIWE Message](#creating-a-siwe-message)

* [Generating SIWE Nonces](#generating-siwe-nonces)

* [Parsing a SIWE Message](#parsing-a-siwe-message)

* [Validating a SIWE Message](#validating-a-siwe-message)

### Creating a SIWE Message

SIWE messages can be created using [`Siwe.createMessage`](/api/Siwe/createMessage):

```ts twoslash
import { Siwe } from 'ox'

Siwe.createMessage({
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  chainId: 1n,
  domain: 'example.com',
  nonce: 'foobarbaz',
  uri: 'https://example.com/path',
  version: '1'
})
// @log: "example.com wants you to sign in with your Ethereum account:
// @log: 0xA0Cf798816D4b9b9866b5330EEa46a18382f251e
// @log:
// @log:
// @log: URI: https://example.com/path
// @log: Version: 1
// @log: Chain ID: 1
// @log: Nonce: foobarbaz
// @log: Issued At: 2023-02-01T00:00:00.000Z"
```

### Generating SIWE Nonces

SIWE nonces can be generated using [`Siwe.generateNonce`](/api/Siwe/generateNonce):

```ts twoslash
import { Siwe } from 'ox'

Siwe.generateNonce()
// @log: '65ed4681d4efe0270b923ff5f4b097b1c95974dc33aeebecd5724c42fd86dfd25dc70b27ef836b2aa22e68f19ebcccc1'
```

### Parsing a SIWE Message

SIWE messages can be parsed using [`Siwe.parseMessage`](/api/Siwe/parseMessage):

```ts twoslash
import { Siwe } from 'ox'

Siwe.parseMessage(`example.com wants you to sign in with your Ethereum account:
0xA0Cf798816D4b9b9866b5330EEa46a18382f251e

I accept the ExampleOrg Terms of Service: https://example.com/tos

URI: https://example.com/path
Version: 1
Chain ID: 1
Nonce: foobarbaz
Issued At: 2023-02-01T00:00:00.000Z`)
// @log: {
// @log:   address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
// @log:   chainId: 1,
// @log:   domain: 'example.com',
// @log:   issuedAt: '2023-02-01T00:00:00.000Z',
// @log:   nonce: 'foobarbaz',
// @log:   statement: 'I accept the ExampleOrg Terms of Service: https://example.com/tos',
// @log:   uri: 'https://example.com/path',
// @log:   version: '1',
// @log: }
```

### Validating a SIWE Message

SIWE messages can be validated using [`Siwe.validateMessage`](/api/Siwe/validateMessage):

```ts twoslash
import { Siwe } from 'ox'

Siwe.validateMessage({
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  domain: 'example.com',
  message: {
    address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
    chainId: 1n,
    domain: 'example.com',
    nonce: 'foobarbaz',
    uri: 'https://example.com/path',
    version: '1'
  },
  nonce: 'foobarbaz'
})
// @log: true
```

## Functions

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Siwe.createMessage`](/api/Siwe/createMessage) | Creates [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361) formatted message. |
| [`Siwe.generateNonce`](/api/Siwe/generateNonce) | Generates random [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361) nonce. |
| [`Siwe.isUri`](/api/Siwe/isUri) | Check if the given URI is a valid [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986) URI. |
| [`Siwe.parseMessage`](/api/Siwe/parseMessage) | [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361) formatted message into message fields object. |
| [`Siwe.validateMessage`](/api/Siwe/validateMessage) | Validates [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361) message. |

## Errors

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Siwe.InvalidMessageFieldError`](/api/Siwe/errors#siweinvalidmessagefielderror) | Thrown when a field in a SIWE Message is invalid. |

## Types

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Siwe.Message`](/api/Siwe/types#siwemessage) | [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361) message fields. |