@vex-chat/crypto

@vex-chat/crypto

Crypto primitives for the Vex encrypted chat platform. Sign, encrypt, hash, derive keys, and encode bytes — everything the client and server need to speak the protocol.

What's in the box

• Key generation — xBoxKeyPair() / xSignKeyPair() / xSignKeyPairFromSecret() / xBoxKeyPairFromSecret() for X25519 (box) and Ed25519 (sign) keypairs (tweetnacl).
• Signing — xSign() / xSignOpen() over arbitrary bytes (Ed25519, tweetnacl).
• Authenticated encryption — xSecretbox() / xSecretboxOpen() (XSalsa20-Poly1305 secretbox) and xDH() (X25519 scalar mult) via tweetnacl.
• Hashing & KDF — xHash() (SHA-512 hex via @noble/hashes), xKDF() (HKDF-SHA-512 via @noble/hashes), xHMAC() (HMAC-SHA-256 via @noble/hashes), and XUtils.encryptKeyData / decryptKeyData (PBKDF2-SHA-512 + tweetnacl secretbox).
• Curve key encoding — xEncode() prefixes a 32-byte X25519 public key for the wire format (not msgpack).
• Msgpack framing — XUtils.packMessage() / unpackMessage() wrap a 32-byte header + msgpack body (msgpackr); unpackMessage validates base fields with Zod.
• Text & byte encoding — XUtils hex/base64/UTF-8 helpers (@stablelib/base64, @stablelib/utf8).
• Mnemonics — xMnemonic() (BIP39 via bip39).
• Utilities — xConcat(), xMakeNonce(), xRandomBytes(), XUtils.bytesEqual (constant-time when lengths match), and XKeyConvert (Ed25519 ↔ X25519 via ed2curve).

HKDF, PBKDF2, HMAC, and SHA-512 / SHA-256 all run through @noble/hashes. tweetnacl supplies CSPRNG, box, sign, and secretbox.

Install

npm install @vex-chat/crypto

@vex-chat/types is a peer dependency — install it alongside if you don't already have it:

npm install @vex-chat/types @vex-chat/crypto

Usage

import {
    xBoxKeyPair,
    xSignKeyPair,
    xSign,
    xSignOpen,
    xSecretbox,
    xSecretboxOpen,
    xDH,
    xMakeNonce,
    XUtils,
} from "@vex-chat/crypto";

// Generate identity keys
const signKeys = xSignKeyPair();
const boxKeys = xBoxKeyPair();

// Sign a message (returns 64-byte signature prefix + message)
const message = XUtils.encodeUTF8("hello vex");
const signed = xSign(message, signKeys.secretKey);
const opened = xSignOpen(signed, signKeys.publicKey);

// Derive a shared secret and encrypt
const shared = xDH(boxKeys.secretKey, otherPartyPublicKey);
const nonce = xMakeNonce();
const ciphertext = xSecretbox(message, nonce, shared);

// Decrypt
const plaintext = xSecretboxOpen(ciphertext, nonce, shared);

// Msgpack wire body (32-byte header + msgpack); see XUtils.packMessage / unpackMessage
const wire = XUtils.packMessage({
    type: "success",
    transmissionID: "abc",
    data: null,
});
const [, body] = XUtils.unpackMessage(wire);

API documentation

HTML and JSON API reference is generated from TSDoc on src/index.ts:

npm run docs

Output is written to ./docs/ (gitignored). CI runs the same generator with --treatWarningsAsErrors.

License

AGPL-3.0-or-later