Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/simplito/privmx-webendpoint-sdk
A set of TypeScript/JavaScript tools that simplify working with PrivMX Bridge in Web environments.
https://github.com/simplito/privmx-webendpoint-sdk
communication cryptography end-to-end-encryption privacy privmx security zero-knowledge
Last synced: about 2 months ago
JSON representation
A set of TypeScript/JavaScript tools that simplify working with PrivMX Bridge in Web environments.
- Host: GitHub
- URL: https://github.com/simplito/privmx-webendpoint-sdk
- Owner: simplito
- License: other
- Created: 2024-11-05T08:46:43.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2024-11-05T13:14:12.000Z (2 months ago)
- Last Synced: 2024-11-05T13:44:35.908Z (2 months ago)
- Topics: communication, cryptography, end-to-end-encryption, privacy, privmx, security, zero-knowledge
- Language: TypeScript
- Homepage:
- Size: 117 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://github.com/simplito/privmx-bridge-docker) 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](https://docs.privmx.dev/js/getting-started).
## 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 ``
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](https://docs.privmx.dev).
## Example Apps
If you prefer a more hands-on approach to learning, start by cloning one of our example apps:
- [Endpoint Examples Minimal](https://github.com/simplito/privmx-webendpoint-sdk-example) -
a set of small Tool-specific code examples executed inside browser console. The best for a quick-start with PrivMX
Endpoint.
- [Chatee](https://github.com/simplito/privmx-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](https://github.com/simplito/privmx-bridge-docker)**:
```shell
git clone https://github.com/simplito/privmx-bridge-docker
```
2. **Run setup scripts (it may require admin permissions)**:
```bash
./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:
```shell
./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:
```shell
./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**:
```shell
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:
```shell
npm i @simplito/privmx-webendpoint-sdk@latest
```
After the installation, run setup script provided by the SDK:
```shell
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`):
```ts
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.
```ts
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.
```ts
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).
```ts
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.**
```ts
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](./LICENSE)