Terminal3 Messaging Utilities

Overview

This repository provides utility functions for encrypting and decrypting messages using Ethereum's MetaMask provider. It leverages elliptic curve cryptography (ECIES) with the ed25519 curve (due to MetaMask constraints) and symmetric encryption with xsalsa20-poly1305.

The code implements functions to:

• Encrypt messages to be sent to a server, including user profile data.
• Sign messages using the user's Ethereum account via MetaMask.
• Retrieve and include the user's public key in messages when necessary.
• Format messages for user-friendly display and signing using EIP-712.

Features

• Integrated Encryption Scheme (ECIES): Implements ECIES using MetaMask's eth-sig-util library.
• Encryption Functions: Provides functions to encrypt messages, with options to include or exclude the user's public key.
• Signing and Verification: Includes functionality to sign messages with the user's Ethereum account.
• Support for User Profiles: Functions to build and encrypt user profile data.
• EIP-712 Support: Automatically uses EIP-712 for message signing when supported by the wallet provider.

Getting Started

Prerequisites

• Node.js: Ensure you have Node.js installed.
• MetaMask: Users should have MetaMask installed in their browser with an active Ethereum account.

Installation

Install the Package:

npm install @terminal3/messaging_client

Usage

Import the necessary functions into your TypeScript or JavaScript project:

import {
  makeEncryptedMsg,
  makeEncryptedUserMsg,
  makeEncryptedSignedMsgWithPubKey,
  makeEncryptedUserSignedMsg,
  makeEncryptedSignedMsgWithoutPubKey,
  makeEncryptedUserSignedMsgWithoutPubKey,
  makeEncryptedSignedFetchRequest,
  makeEncryptedSignedPubKeyMsg,
} from '@terminal3/messaging_client';

Encrypting a Message

Encrypt a simple message without user authentication:

const encryptedData = makeEncryptedMsg('Your message here');

Encrypting User Profile Data

Encrypt a user profile:

import { UserProfileRequest } from '@terminal3/messaging_core';

// Build your user profile request object
const userProfileRequest: UserProfileRequest = {
  // Fill with your user profile data
};

// Encrypt the user profile
const encryptedUserProfile = await makeEncryptedUserMsg(userProfileRequest);

Encrypting and Signing a Message with User's Private Key

This function works with Metamask only. Encrypt and sign a message, including the user's public key that can be used to send encrypted messages back to the user:

const encryptedSignedMsg = await makeEncryptedSignedMsgWithPubKey(
  'Your message here',
  provider,
);

This function works with any RainbowKit wallet, and generally any Web3/AA wallet. As it requires only signMessage functionality. It encrypt and sign a message:

const encryptedSignedMsg = await makeEncryptedSignedMsgWithoutPubKey(
  'Your message here',
  provider,
);

Encrypting and Signing User Profile Data with User's Private Key

Encrypt and sign user profile data, including the user's public key:

const encryptedUserSignedMsg = await makeEncryptedUserSignedMsgWithPubKey(
  userProfileRequest,
  provider,
);

Alternatively, to exclude the user's public key:

const encryptedUserSignedMsgWithoutPubKey =
  await makeEncryptedUserSignedMsgWithoutPubKey(userProfileRequest, provider);

This function now automatically uses EIP-712 for message signing when supported by the wallet provider. This means users will see a well-structured, human-readable representation of the data they're signing, making it much easier to understand and verify the content before signing.

Fetching Encrypted Data

Send a signed fetch request to the server. The server should respond with user data:

const fetchRequest = await makeEncryptedSignedFetchRequest(provider);

Decrypting Messages

Decryption is handled on the server-side using the server's private key corresponding to the public key used in encryption.

Cryptographic Details

• Encryption Scheme: The encryption follows the Integrated Encryption Scheme (ECIES) using the ed25519 elliptic curve.
• Symmetric Encryption: Uses xsalsa20-poly1305 for encrypting the actual message payload.
• Ephemeral Keys: Generates an ephemeral public key for each encryption, enhancing security.
• Message Structure: Messages include the encrypted data, optional public key, and a timestamp.
• EIP-712: Implements the Ethereum EIP-712 standard for typed data signing to enhance user experience and security.

Dependencies

• eth-sig-util: Utilities for signing and encryption with Ethereum accounts via MetaMask.
• @terminal3/messaging_core: Core messaging utilities for building user profiles and message structures.
• ethers: A complete Ethereum library and wallet implementation.