@vex-chat/libvex

@vex-chat/libvex

Reference TypeScript client for the Vex encrypted chat platform. Builds against the wire protocol defined in @vex-chat/types and the cryptographic primitives in @vex-chat/crypto. Use it to build a chat client, a bot, or any application that needs to talk to a spire server.

Documentation

What's in the box

The client implements an X3DH-style handshake (X25519 DH + KDF), XSalsa20-Poly1305 (xSecretbox) for payloads, and HMAC over mail objects for integrity on the wire. Message payloads are intended to be end-to-end encrypted; the server still sees ciphertext, routing metadata, timing, and who talks to whom, and controls key-bundle distribution—so a malicious or compromised Spire can mount impersonation unless users verify sessions out-of-band.

• End-to-end encrypted messaging with X3DH key agreement — sessions, prekeys, and one-time keys handled internally.
• Tree-shakable subpath exports for platform-specific code: ./preset/node, ./preset/test, ./storage/node, ./storage/sqlite, ./storage/schema, ./keystore/node, ./keystore/memory. Browser bundles never pull in better-sqlite3 or other native modules.
• Pluggable storage backend via Kysely so node consumers can use SQLite and browser/tauri/expo consumers can wire their own.
• Pluggable key store so secrets can live in memory (tests), the OS keychain (./keystore/node), or wherever the embedding app keeps them.
• WebSocket transport for live message delivery with automatic reconnection and HTTP fallback for the REST API.

Install

npm install @vex-chat/libvex

@vex-chat/types, @vex-chat/crypto, axios, kysely, winston, and zod are required runtime dependencies and install automatically.

better-sqlite3 is an optional peer dependency — install it explicitly only if you plan to use the SQLite storage backend on Node:

npm install @vex-chat/libvex better-sqlite3

Browser, Tauri, and Expo consumers should leave better-sqlite3 out and supply their own storage adapter via ./storage/schema.

Quickstart

import { Client } from "@vex-chat/libvex";

// Generate or load a long-lived secret key — store it in the OS keychain.
const secretKey = Client.generateSecretKey();

const client = await Client.create(secretKey);

// First-time devices must register before logging in.
await client.register(Client.randomUsername());
await client.login();

client.on("authed", async () => {
    const me = await client.users.me();
    await client.messages.send(me.userID, "Hello world!");
});

client.on("message", (message) => {
    console.log("message:", message);
});

Platform presets

libvex ships per-platform "presets" that wire together the appropriate storage and keystore:

// Node — sqlite storage + OS keychain
import {
    Client,
    makeStorage,
    BootstrapConfig,
} from "@vex-chat/libvex/preset/node";

// Tests / ephemeral — in-memory storage + memory keystore
import {
    Client,
    makeStorage,
    BootstrapConfig,
} from "@vex-chat/libvex/preset/test";

For a custom platform (browser, tauri, expo), import Client from @vex-chat/libvex directly and supply your own Storage (implementing the schema in @vex-chat/libvex/storage/schema) and KeyStore to Client.create.

Development

npm run build           # tsc -p tsconfig.build.json
npm run lint            # eslint
npm run lint:fix        # eslint --fix
npm run format          # prettier --write
npm run format:check
npm test                # vitest unit suite (browser-safe, no spire required)
npm run test:e2e        # vitest node + browser e2e — needs a running spire
npm run lint:pkg        # publint --strict
npm run lint:types      # @arethetypeswrong/cli
npm run lint:api        # api-extractor — regenerates api/libvex.api.md
npx type-coverage       # type-coverage (≥95%)
npm run license:check   # license allowlist gate
npm run docs            # typedoc — writes ./docs

The unit suite (npm test) runs browser-safe and offline. The e2e suite (npm run test:e2e) spins up a real spire server in a separate process — point VEX_API_URL at a running spire if you want to test against a different host.

See AGENTS.md for the release flow (changesets → publish) and the rules for writing changesets.

License

AGPL-3.0-or-later