@ethermail/ethermail-wallet-provider v0.1.8

EtherMail

EtherMail SSO + Wallet Provider

EtherMail SSO enables apps to seamlessly support web2 and web3 login via EtherMail.

Features

• Enable web2 and web3 login
• Allow users to choose permissions to enable/disable wallet interactions

Installation

Get the login widget from the Marketing Hub and follow the steps to embed it into your site.

Install the dependencies. If you don't need to support wallet actions, you can skip this step.

npm i @ethermail/ethermail-wallet-provider

Usage

After embedding the login widget, add event listeners for custom events. You will receive the EtherMailSignInOnSuccess custom event on a successful login, and you can use that event to connect to our provider with web3.js/ethers.js, etc.

Embedded script:

<script defer>
  (function ({ ...args }) {
      var p = document.createElement('script');
      p.src = 'https://cdn-email.ethermail.io/sdk/v2/ethermail.js';
      document.body.appendChild(p);
      p.setAttribute('a', args.afid);
      p.setAttribute('b', args.communityAlias);
      p.setAttribute('c', args.features);
    })({
      afid: <AFID>,
      communityAlias: <COMMUNITY_NAME>,
      features: ['login']
    });
</script>

<ethermail-login
  widget="<ID>"
  type="wallet"
  permissions="write"
></ethermail-login>

You will get back a JWT token:

{
  exp: number;
  iat: number;
  iss: string;
  sub: string;
  permissions: "none" | "read" | "write";
  type: "sso" | "wallet";
  origin: string;
  address: string;
  wallet: `0x${string}`;
  ethermail_verified: boolean;
}

Example with ethers.js version 6:

import { EtherMailProvider } from "@ethermail/ethermail-wallet-provider";
import { BrowserProvider } from "ethers";

let provider;

window.addEventListener("EtherMailSignInOnSuccess", async (event) => {
  console.log("token", event.detail.token);
  // If you want to support wallet actions, connect to our provider
  provider = new BrowserProvider(new EtherMailProvider());
});

function signMessage() {
  const signer = await provider.getSigner();
  const signature = await signer.signMessage("Hello world");
  console.log(signature);
}

Example with web3.js:

import { EtherMailProvider } from "@ethermail/ethermail-wallet-provider";
import Web3 from "web3";

let web3;

window.addEventListener("EtherMailSignInOnSuccess", async (event) => {
  console.log("token", event.detail.token);
  // If you want to support wallet actions, connect to our provider
  web3 = new Web3(new EtherMailProvider());
});

function signMessage() {
  const account = await web3.eth.getAccounts();
  const signature = await web3.eth.personal.sign(
    web3.utils.utf8ToHex("Hello from web3"),
    account[0],
    "123456"
  );
  console.log(signature);
}

Another custom event is EtherMailTokenError, which will be used in case of token expiration or permissions error:

window.addEventListener("EtherMailTokenError", (event) => {
  if (event.detail.type === "expired") {
    // Show login modal or redirect to login page
  }

  if (event.detail.type === "permissions") {
    // Show permissions error message, or redirect to login page
  }
});

Token Validation

To validate a token, send a request to our API as demonstrated below. We recommend that you make this request on the server.

const validateToken = async (token) => {
  try {
    const response = await fetch(
      "https://api.ethermail.io/sso/validate-token",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          token: token,
        }),
      }
    );

    const result = await response.json();

    if (result.success) {
      console.log("Token is valid");
    } else {
      console.log("Token is invalid");
    }
  } catch (error) {
    console.error("Error validating token:", error);
  }
};