PrivMX Web Endpoint SDK

Overview

PrivMX Web Endpoint SDK is a set of TypeScript/JavaScript tools that simplify working with PrivMX Bridge in Web environments. It consists of:

• high-level wrappers for native WASM assets, to accelerate the development of end-to-end encrypted apps even more;
• types for powerful autocompletion in your IDE;
• CLI for straightforward project initialization.

Initial Requirements

To start developing end-to-end encrypted applications using PrivMX Endpoint you need:

• A PrivMX Bridge Instance. Go to Bridge CLI repo to find scripts to create and initialize one on your local machine.

• A server for managing users. It can be new or existing, depending on the specific requirements. For more information about how PrivMX Endpoint integrates into your stack check our getting started guide.

Installation

First, install this package using your package manager of choice.

• npm:

npm install @simplito/privmx-webendpoint-sdk@latest 

• pnpm:

pnpm add @simplito/privmx-webendpoint-sdk@latest 

• yarn:

yarn add @simplito/privmx-webendpoint-sdk@latest 

The wrappers need access to the core lib in order to work properly. To do this, follow these steps:

1. Host core WASM assets from your static assets folder (e.g. /public). Then import them using <script> tags inside your app's main file. Depending on the stack it can be for example index.html or app.js.
2. Configure your server to properly integrate our library. You need to set up specific HTTP headers:

• Cross-Origin-Embedder-Policy: require-corp
• Cross-Origin-Opener-Policy: same-origin

This will ensure the library functions correctly and maintain security.

The steps above can be handled automatically, using our setup npx script:

npx @simplito/webendpoint-manager

Documentation

Full documentation about this package's functions, types and example usage can be found in our docs.

Example Apps

If you prefer a more hands-on approach to learning, start by cloning one of our example apps:

• Endpoint Examples Minimal - a set of small Tool-specific code examples executed inside browser console. The best for a quick-start with PrivMX Endpoint.

• Chatee - a full-fledged end-to-end encrypted chat app built using Next.js. It demonstrates how to:

  • create a secure real-time chat using Threads;
  • send attachments using Stores;
  • manage users inside PrivMX Bridge from your own server using REST API.

Creating First App

A step-by-step tutorial that will guide you through creating your first app using JavaScript Endpoint SDK with PrivMX Bridge.

Setup PrivMX Bridge Instance

To create a PrivMX Bridge Instance, you need Docker with Docker Compose installed on your machine.

1. First, clone our Bridge CLI repo:

   git clone https://github.com/simplito/privmx-bridge-docker

2. Run setup scripts (it may require admin permissions):

   ./setup.sh

   This will fetch the necessary Docker images, create Access Keys and your first Context. After a successful setup, CLI will display all the API keys necessary for connection.

3. Register the first user:

   In your terminal, generate private-public key pair for your user. The keys must be in WIF format:

   ./genKeyPair.sh

   With the keys ready, register userId - public key pair in your Context. Don't forget to replace placeholder values with the ones created earlier:

   ./cli.sh context/addUserToContext '{"contextId": "CONTEXT_ID", "userId":"USER_ID", "userPubKey":"USER_PUBLIC_KEY" }'

Create Client App

To create client app, you need Node and npm installed on your machine.

1. Create app using Vite CLI:

npm create vite

Follow all the steps displayed by Vite CLI. You can choose any framework you prefer - PrivMX Endpoint Web SDK is framework-agnostic.

2. Install dependencies

Inside the created project folder, install this Endpoint Web SDK:

npm i @simplito/privmx-webendpoint-sdk@latest

After the installation, run setup script provided by the SDK:

npx @simplito/webendpoint-manager

Follow the steps displayed in your terminal.

3. Connect to your Bridge Instance

Paste the following snippet to your main JavaScript file (e.g. ./src/App.ts or ./src/index.js):

 async function connectToBridge() {
     const connection = await Endpoint.connect({
         bridgeUrl:"BRIDGE_URL",
         solutionId:"SOLUTION_ID",
         privKey:"USER_PRIVATE_KEY",
     })

     const firstUser = {
         userId:"USER_ID",
         pubKey:"USER_PUBLIC_KEY",
     }

     const threadId = await connection.threads.new({
         users:[firstUser],
         managers:[firstUser]
     })

     await connection.thread(threadId).sendMessage({
         data:new TextEncoder().encode("Hello Bridge!")
     })
     const messageList = await connection.thread(threadId).getMessages(0)

     const decodedMessageList = messageList.readItems.map(message => {
         return {
             data:new TextDecoder().decode(message.data),
             info:message.info,
             authorPubKey:message.authorPubKey,
         }
     })
     console.log(decodedMessageList)
}

First, you have to connect to your Bridge Instance using Endpoint.connect method. It requires the API keys generated while initializing your local instance earlier.

const connection = await Endpoint.connect({
         bridgeUrl:"BRIDGE_URL",
         solutionId:"SOLUTION_ID",
         privKey:"USER_PRIVATE_KEY",
})

When connected, you have access to all SDK methods. This example shows how to create a Thread, send and download a message. To create a Thread inside Context, use Threads handle methods new. Note that you have to pass user ID - public key pair to make a list of users and managers.

 const firstUser = {
         userId:"USER_ID",
         pubKey:"USER_PUBLIC_KEY",
     }

     const threadId = await connection.threads.new({
         users:[firstUser],
         managers:[firstUser]
     })

With the Thread created, you can now send the first message.

Endpoint sends data in Uint8Array format. It requires encoding your data from string or object format to binary (e.g. the usage of TextEncoder for string encoding).

await connection.thread(threadId).sendMessage({
    data:new TextEncoder().encode("Hello Bridge!")
})

To get a list of messages inside a Thread, use getMessages method. Because data inside messages is in Uint8Array you have to deserialize it to human-readable string. Endpoint takes care of encrypting your data before sending it to PrivMX Bridge.

   const messageList = await connection.thread(threadId).getMessages(0)

     const decodedMessageList = messageList.readItems.map(message => {
         return {
             data:new TextDecoder().decode(message.data),
             info:message.info,
             authorPubKey:message.authorPubKey,
         }
     })
     console.log(decodedMessageList)

4. Run your app

In your terminal, run npm run dev to start local app server.

License

MIT