@vex-chat/crypto 1.1.0-rc.1 → 2.0.0

package/README.md

@@ -1,18 +1,81 @@
-# @vex-chat/crypto-js
+# @vex-chat/crypto
 
-![typescript_ci](https://github.com/vex-chat/crypto-js/workflows/typescript_ci/badge.svg)
+[![npm](https://img.shields.io/npm/v/@vex-chat/crypto?style=flat-square&color=cb3837&logo=npm)](https://www.npmjs.com/package/@vex-chat/crypto)
+[![CI](https://img.shields.io/github/actions/workflow/status/vex-protocol/crypto-js/build.yml?branch=master&style=flat-square&logo=github&label=CI)](https://github.com/vex-protocol/crypto-js/actions/workflows/build.yml)
+[![Released](https://img.shields.io/github/release-date/vex-protocol/crypto-js?style=flat-square&label=released)](https://github.com/vex-protocol/crypto-js/releases)
+[![License](https://img.shields.io/npm/l/@vex-chat/crypto?style=flat-square&color=blue)](./LICENSE)
+[![Types](https://img.shields.io/npm/types/@vex-chat/crypto?style=flat-square&logo=typescript&color=3178c6)](./dist/index.d.ts)
+[![Type Coverage](https://img.shields.io/badge/dynamic/json?style=flat-square&label=type-coverage&prefix=%E2%89%A5&suffix=%25&query=$.typeCoverage.atLeast&url=https://raw.githubusercontent.com/vex-protocol/crypto-js/master/package.json&color=3178c6&logo=typescript)](https://github.com/plantain-00/type-coverage)
+[![Node](https://img.shields.io/node/v/@vex-chat/crypto?style=flat-square&color=339933&logo=nodedotjs)](./package.json)
+[![Bundle](https://deno.bundlejs.com/badge?q=@vex-chat/crypto&treeshake=[*])](https://bundlejs.com/?q=@vex-chat/crypto&treeshake=[*])
+[![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/vex-protocol/crypto-js?style=flat-square&label=Scorecard)](https://securityscorecards.dev/viewer/?uri=github.com/vex-protocol/crypto-js)
+[![Socket](https://socket.dev/api/badge/npm/package/@vex-chat/crypto)](https://socket.dev/npm/package/@vex-chat/crypto)
 
-All of the crypto functions for the key exchange are contained in here.
+Crypto primitives for the [Vex](https://vex.wtf) encrypted chat platform. Sign, encrypt, hash, derive keys, and encode bytes — everything the client and server need to speak the protocol.
 
-[Documentation](https://vex-chat.github.io/crypto-js/)
+## What's in the box
 
-## external crypto dependencies
+- **Key generation** — `xBoxKeyPair()` / `xSignKeyPair()` / `xSignKeyPairFromSecret()` / `xBoxKeyPairFromSecret()` for X25519 (encryption) and Ed25519 (signing) keypairs.
+- **Signing** — `xSign()` / `xSignVerify()` over arbitrary bytes using Ed25519.
+- **Authenticated encryption** — `xSecretbox()` / `xSecretboxOpen()` (NaCl secretbox) plus `xDH()` for Diffie-Hellman shared secrets.
+- **Hashing & KDF** — `xHash()` (SHA-512), `xKDF()` (HKDF-SHA256 via `@noble/hashes`), `xHMAC()`, and PBKDF2.
+- **Encoding** — `xEncode()` / `xDecode()` for msgpack wire serialization; `XUtils.encodeBase64` / `encodeUTF8` for constant-time transport encoding.
+- **Mnemonic keys** — `xMnemonic()` (BIP39) for deriving keys from human-readable phrases.
+- **Utilities** — `xConcat()`, `xMakeNonce()`, `xRandomBytes()`, and `XKeyConvert` (Ed25519 ↔ X25519 conversion via `ed2curve`).
 
-This library utilizes native Node.js crypto where possible for performance and security.
+All primitives use constant-time operations where relevant. Native Node crypto is used for HKDF/PBKDF2/HMAC/SHA; `tweetnacl` and `@noble/hashes` cover the rest.
 
--   **tweetnacl**: Primitives for signing and encryption (X25519 / Ed25519).
--   **ed2curve**: Ed25519 signing key to X25519 encryption key conversion.
--   **msgpackr**: High-performance MessagePack serialization (replacing `msgpack-lite`).
--   **bip39**: Mnemonic generation for keys.
--   **Node Crypto**: Native implementations for HKDF, PBKDF2, HMAC, and SHA hashing (replacing `futoin-hkdf`, `create-hmac`, and `sha.js`).
--   **@stablelib**: Constant-time encoding for Base64 and UTF8.
+## Install
+
+```sh
+npm install @vex-chat/crypto
+```
+
+`@vex-chat/types` is a peer dependency — install it alongside if you don't already have it:
+
+```sh
+npm install @vex-chat/types @vex-chat/crypto
+```
+
+## Usage
+
+```ts
+import {
+    xBoxKeyPair,
+    xSignKeyPair,
+    xSign,
+    xSecretbox,
+    xSecretboxOpen,
+    xDH,
+    xMakeNonce,
+    xEncode,
+    xDecode,
+    XUtils,
+} from "@vex-chat/crypto";
+
+// Generate identity keys
+const signKeys = xSignKeyPair();
+const boxKeys = xBoxKeyPair();
+
+// Sign a message
+const message = XUtils.encodeUTF8("hello vex");
+const signature = xSign(message, signKeys.secretKey);
+
+// 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 encoding
+const frame = xEncode({ type: "success", transmissionID: "abc", data: null });
+const decoded = xDecode(frame);
+```
+
+See the generated API docs at [vex-chat.github.io/crypto-js](https://vex-chat.github.io/crypto-js/) for the full surface.
+
+## License
+
+[AGPL-3.0-or-later](./LICENSE)

package/dist/index.d.ts

@@ -1,6 +1,6 @@
+import type { BaseMsg } from "@vex-chat/types";
 import { decode as decodeBase64, encode as encodeBase64 } from "@stablelib/base64";
-import { decode as encodeUTF8, encode as decodeUTF8 } from "@stablelib/utf8";
-import type { IBaseMsg } from "@vex-chat/types";
+import { encode as decodeUTF8, decode as encodeUTF8 } from "@stablelib/utf8";
 import ed2curve from "ed2curve";
 /**
  * Provides an interface that can map an ed25519 keypair to its equivalent
@@ -12,10 +12,10 @@ export declare const XKeyConvert: typeof ed2curve;
  * vex messages.
  */
 export declare class XUtils {
-    static encodeUTF8: typeof encodeUTF8;
+    static decodeBase64: typeof decodeBase64;
     static decodeUTF8: typeof decodeUTF8;
     static encodeBase64: typeof encodeBase64;
-    static decodeBase64: typeof decodeBase64;
+    static encodeUTF8: typeof encodeUTF8;
     /**
      * Checks if two buffer-like objects are equal.
      *
@@ -24,110 +24,133 @@ export declare class XUtils {
      *
      * @returns True if equal, else false.
      */
-    static bytesEqual(buf1: Uint8Array | ArrayBuffer, buf2: Uint8Array | ArrayBuffer): boolean;
+    static bytesEqual(buf1: ArrayBuffer | Uint8Array, buf2: ArrayBuffer | Uint8Array): boolean;
     /**
-     * Returns a six bit Uint8Array representation of an integer.
-     * The integer must be positive, and it must be able to be stored
-     * in six bytes.
+     * Decodes a hex string into a Uint8Array.
      *
-     * @param n The number to convert.
-     * @returns The Uint8Array representation of n.
+     * @returns The Uint8Array.
      */
-    static numberToUint8Arr(n: number): Uint8Array;
+    static decodeHex(hexString: string): Uint8Array;
     /**
-     * Converts a Uint8Array representation of an integer back into a number.
+     * Decrypts a secret key from the binary format produced by encryptKeyData().
+     * No I/O — the caller handles reading the data.
      *
-     * @param arr The array to convert.
-     * @returns the number representation of arr.
+     * @param keyData The encrypted key data as a Uint8Array.
+     * @param password The password used to encrypt.
+     * @returns The hex-encoded secret key.
      */
-    static uint8ArrToNumber(arr: Uint8Array): number;
+    static decryptKeyData: (keyData: Uint8Array, password: string) => string;
     /**
-     * Takes a vex message and unpacks it into its header and a javascript object
-     * respresentation of its body.
+     * Returns the empty header (32 0's)
      *
-     * @param arr The array to convert.
-     * @returns [32 byte header, message body]
+     * @returns The empty header.
      */
-    static unpackMessage(msg: Uint8Array | Buffer): [Uint8Array, IBaseMsg];
+    static emptyHeader(): Uint8Array<ArrayBuffer>;
     /**
-     * Packs a javascript object and a 32 byte header into a vex message.
+     * Encodes a Uint8Array to a hex string.
      *
-     * @param arr The array to convert.
-     * @returns the packed message.
+     * @returns The hex string.
      */
-    static packMessage(msg: any, header?: Uint8Array): Uint8Array<ArrayBufferLike>;
+    static encodeHex(bytes: Uint8Array): string;
     /**
-     * Returns the empty header (32 0's)
-     *
-     * @returns The empty header.
-     */
-    static emptyHeader(): Uint8Array<ArrayBuffer>;
+   * Encrypts a secret key with a password and saves it as a file.
+   *
+   * @param path The path to save the keyfile.
+  /**
+   * Encrypts a secret key into a portable binary format.
+   * The result can be written to disk, sent over the network, etc.
+   * No I/O — the caller handles persistence.
+   *
+   * Format: [iterations(6)|salt(24)|nonce(24)|ciphertext(N)]
+   *
+   * @param password The password to derive the encryption key from.
+   * @param keyToSave The hex-encoded secret key to encrypt.
+   * @param iterationOverride Optional PBKDF2 iteration count (random if omitted).
+   * @returns The encrypted key data as a Uint8Array.
+   */
+    static encryptKeyData: (password: string, keyToSave: string, iterationOverride?: number) => Uint8Array;
     /**
-     * Encrypts a secret key with a password and saves it as a file.
+     * Returns a six bit Uint8Array representation of an integer.
+     * The integer must be positive, and it must be able to be stored
+     * in six bytes.
      *
-     * @param path The path to save the keyfile.
-     * @param password The password to encrypt the keyfile with.
-     * @param keyToSave The key to encrypt.
-     * @param iterationOverride An optional override if you'd prefer to manually
-     * select your iterations rather than having a random amount selected.
+     * @param n The number to convert.
+     * @returns The Uint8Array representation of n.
      */
-    static saveKeyFile: (path: string, password: string, keyToSave: string, iterationOverride?: number) => void;
+    static numberToUint8Arr(n: number): Uint8Array;
     /**
-     * Decrypts and returns a secret key stored in a file with saveKeyFile().
+     * Packs a javascript object and a 32 byte header into a vex message.
      *
-     * @param path The path of the file.
-     * @param password The password the file was encrypted with.
+     * @param arr The array to convert.
+     * @returns the packed message.
      */
-    static loadKeyFile: (path: string, password: string) => string;
+    static packMessage(msg: unknown, header?: Uint8Array): Uint8Array<ArrayBufferLike>;
     /**
-     * Decodes a hex string into a Uint8Array.
+     * Converts a Uint8Array representation of an integer back into a number.
      *
-     * @returns The Uint8Array.
+     * @param arr The array to convert.
+     * @returns the number representation of arr.
      */
-    static decodeHex(hexString: string): Uint8Array;
+    static uint8ArrToNumber(arr: Uint8Array): number;
     /**
-     * Encodes a Uint8Array to a hex string.
+     * Takes a vex message and unpacks it into its header and a javascript object
+     * respresentation of its body.
      *
-     * @returns The hex string.
+     * @param arr The array to convert.
+     * @returns [32 byte header, message body]
      */
-    static encodeHex(bytes: Uint8Array): string;
+    static unpackMessage(msg: Buffer | Uint8Array): [Uint8Array, BaseMsg];
 }
-/**
- * Gets a word list representation of a byte sequence.
- *
- * @param entropy The bytes to derive the wordlist from.
- * @param wordList Optional, override the wordlist. See bip39 docs for details.
- */
-export declare function xMnemonic(entropy: Uint8Array, wordList?: string[] | undefined): string;
 /**
  * Returns a 32 byte HMAC of a javscript object.
  *
  * @param msg the message to create the HMAC of
  * @param SK the secret key to create the HMAC with
  */
-export declare function xHMAC(msg: any, SK: Uint8Array): Uint8Array<ArrayBuffer>;
+export declare function xHMAC(msg: unknown, SK: Uint8Array): Uint8Array<ArrayBufferLike>;
 /**
- * Constants for vex.
+ * Gets a word list representation of a byte sequence.
+ *
+ * @param entropy The bytes to derive the wordlist from.
+ * @param wordList Optional, override the wordlist. See bip39 docs for details.
  */
-export declare const xConstants: XConstants;
+export declare function xMnemonic(entropy: Uint8Array, wordList?: string[]): string;
 /**
- * Returns a 24 byte random nonce of cryptographic quality.
+ * Constants for vex.
  */
-export declare function xMakeNonce(): Uint8Array;
+export declare const xConstants: XConstants;
+/** Ed25519 or X25519 key pair. Structurally identical to nacl.SignKeyPair / nacl.BoxKeyPair. */
+export interface KeyPair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
 /**
  * Derives a 32 byte secret key from some initial key material.
  *
  * @param IKM the initial key material.
  * @returns The generated key.
  */
-export declare function xKDF(IKM: Uint8Array): Uint8Array;
 /**
- * Hashes some data.
+ * @ignore
+ */
+interface XConstants {
+    CURVE: "X25519";
+    HASH: "SHA-512";
+    HEADER_SIZE: 32;
+    INFO: string;
+    KEY_LENGTH: 32 | 57;
+    MIN_OTK_SUPPLY: number;
+}
+/** Generate a fresh X25519 box key pair. */
+export declare function xBoxKeyPair(): KeyPair;
+/** Restore an X25519 box key pair from a 32-byte secret key. */
+export declare function xBoxKeyPairFromSecret(secretKey: Uint8Array): KeyPair;
+/**
+ * Concatanates multiple Uint8Arrays.
  *
- * @param data the data to hash.
- * @returns The hash of the data.
+ * @param arrays As many Uint8Arrays as you would like to concatanate.
  */
-export declare function xHash(data: Uint8Array): string;
+export declare function xConcat(...arrays: Uint8Array[]): Uint8Array;
 /**
  * Derives a shared Secret Key from a known private key and
  * a peer's known public key.
@@ -137,28 +160,38 @@ export declare function xHash(data: Uint8Array): string;
  * @returns The derived shared secret, SK.
  */
 export declare function xDH(myPrivateKey: Uint8Array, theirPublicKey: Uint8Array): Uint8Array;
-/**
- * Concatanates multiple Uint8Arrays.
- *
- * @param arrays As many Uint8Arrays as you would like to concatanate.
- */
-export declare function xConcat(...arrays: Uint8Array[]): Uint8Array;
 /**
  * Encode an X25519 or X448 public key PK into a byte sequence.
  * The encoding consists of 0 or 1 to represent the type of curve, followed by l
  * ittle-endian encoding of the u-coordinate. See [rfc 7748](https://www.ietf.org/rfc/rfc7748.txt) for more
  * details.
  */
-export declare function xEncode(curveType: "X25519" | "X448", publicKey: Uint8Array): Uint8Array;
+export declare function xEncode(curveType: "X448" | "X25519", publicKey: Uint8Array): Uint8Array;
 /**
- * @ignore
+ * Hashes some data.
+ *
+ * @param data the data to hash.
+ * @returns The hash of the data.
  */
-interface XConstants {
-    CURVE: "X25519";
-    HASH: "SHA-512";
-    INFO: string;
-    KEY_LENGTH: 32 | 57;
-    MIN_OTK_SUPPLY: number;
-    HEADER_SIZE: 32;
-}
+export declare function xHash(data: Uint8Array): string;
+export declare function xKDF(IKM: Uint8Array): Uint8Array;
+/**
+ * Returns a 24 byte random nonce of cryptographic quality.
+ */
+export declare function xMakeNonce(): Uint8Array;
+/** Cryptographically secure random bytes. */
+export declare function xRandomBytes(length: number): Uint8Array;
+/** Encrypt with a shared secret key. */
+export declare function xSecretbox(plaintext: Uint8Array, nonce: Uint8Array, key: Uint8Array): Uint8Array;
+/** Decrypt with a shared secret key. Returns null if authentication fails. */
+export declare function xSecretboxOpen(ciphertext: Uint8Array, nonce: Uint8Array, key: Uint8Array): null | Uint8Array;
+/** Sign a message with an Ed25519 secret key. Returns signed message (64-byte signature prefix + message). */
+export declare function xSign(message: Uint8Array, secretKey: Uint8Array): Uint8Array;
+/** Generate a fresh Ed25519 signing key pair. */
+export declare function xSignKeyPair(): KeyPair;
+/** Restore an Ed25519 signing key pair from a 64-byte secret key. */
+export declare function xSignKeyPairFromSecret(secretKey: Uint8Array): KeyPair;
+/** Verify and open a signed message. Returns the original message, or null if verification fails. */
+export declare function xSignOpen(signedMessage: Uint8Array, publicKey: Uint8Array): null | Uint8Array;
 export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}