# wallet-server-verify

Signs a user in to your server with Sign-In with Ethereum (EIP-4361). Your server creates the message, the user signs
it in the wallet, and your server checks that the signature came from the account. It runs on your server and works
with smart account signatures, including ones from accounts that haven't sent a transaction yet.
See [SIWE](https://moss.megaeth.com/developers/methods/signing/sign-message#siwe) and [Authentication](https://moss.megaeth.com/developers/concepts/authentication).

```bash title="pnpm"
pnpm add @megaeth-labs/wallet-server-verify viem
```

```bash title="npm"
npm install @megaeth-labs/wallet-server-verify viem
```

```bash title="yarn"
yarn add @megaeth-labs/wallet-server-verify viem
```

## Signing In

### `getMessageToSign`

Creates a SIWE message for an address, with a fresh nonce, for your client to ask the user to sign.
See [Sign Message](https://moss.megaeth.com/developers/methods/signing/sign-message).

```ts title="Types"
getMessageToSign: (config: MessageConfig, address: Hex) => MessageToSign;

interface MessageConfig {
    scheme: 'http' | 'https';
    domain: string; // Your site's host, such as example.com
    uri: string; // Your site's URL
    chainId: 6343 | 4326; // Testnet or mainnet
    statement: string; // The text the user is asked to agree to
}

interface MessageToSign {
    address: Hex;
    message: string;
    nonce: string;
    issuedAt: Date;
}
```

```ts title="Example"
import { getMessageToSign, type MessageConfig } from '@megaeth-labs/wallet-server-verify';

const config: MessageConfig = {
    scheme: 'https',
    domain: 'example.com',
    uri: 'https://example.com',
    chainId: 4326,
    statement: 'Sign in to Example',
};

// In your API: create the message and send it to the client to sign.
export function createMessage(address: `0x${string}`) {
    return getMessageToSign(config, address);
}
```

### `verifySignature`

Checks that a signed message is the one your server created and that the account signed it. Resolves when it is valid
and throws when it isn't.
See [Verifying Signatures](https://moss.megaeth.com/developers/methods/signing/sign-message#verifying-signatures).

```ts title="Types"
verifySignature: (config: MessageConfig, request: MessageToConfirm) => Promise<void>;

interface MessageToConfirm {
    address: Hex;
    message: string;
    nonce: string;
    issuedAt: Date;
    signature: Hex;
}

interface MessageConfig {
    scheme: 'http' | 'https';
    domain: string;
    uri: string;
    chainId: 6343 | 4326;
    statement: string;
}
```

```ts title="Example"
import { type MessageToConfirm, verifySignature } from '@megaeth-labs/wallet-server-verify';

// The client sends back what createMessage returned, plus the user's signature.
export async function login(signed: MessageToConfirm) {
    await verifySignature(config, signed);

    // Check signed.nonce hasn't been used before, then start a session for signed.address.
    return signed.address;
}
```

> [!NOTE]
> `verifySignature` doesn't remember nonces. Store each one you issue and reject any that come back twice.

## Errors

### `Errors`

The messages `verifySignature` throws, as the `message` of an `Error`.

```ts title="Types"
const Errors: {
    INVALID_SIGNATURE: string; // The signature isn't valid for the account
    DIFFERENT_MESSAGE: string; // The message isn't the one your server created
    ACCOUNT_NOT_FOUND: string; // Not thrown by version 0.1.10
    ACCESS_DENIED: string; // Not thrown by version 0.1.10
};
```

```ts title="Example"
import { Errors, verifySignature } from '@megaeth-labs/wallet-server-verify';

try {
    await verifySignature(config, signed);
} catch (error) {
    if (error instanceof Error && error.message === Errors.INVALID_SIGNATURE) {
        // Reject the sign-in.
    }
}
```
