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

package/package.json

@@ -1,80 +1,111 @@
 {
-  "name": "@vex-chat/crypto",
-  "version": "1.1.0-rc.1",
-  "description": "Crypto primitives for Vex",
-  "type": "module",
-  "sideEffects": false,
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+    "name": "@vex-chat/crypto",
+    "version": "2.0.0",
+    "description": "Crypto primitives for the Vex encrypted chat platform",
+    "type": "module",
+    "sideEffects": false,
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "LICENSE"
+    ],
+    "author": "Extra <extrahash@protonmail.com>",
+    "license": "AGPL-3.0-or-later",
+    "engines": {
+        "node": ">=24.0.0",
+        "npm": ">=10.0.0"
+    },
+    "packageManager": "npm@10.9.2",
+    "scripts": {
+        "prepare": "husky",
+        "preinstall": "npx only-allow npm",
+        "build": "tsc -p tsconfig.build.json",
+        "build:clean": "rimraf dist && tsc -p tsconfig.build.json",
+        "prepack": "npm run build",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "lint": "eslint src/",
+        "lint:fix": "eslint src/ --fix",
+        "license:check": "npx @onebeyond/license-checker scan --allowOnly MIT ISC BSD-2-Clause BSD-3-Clause Apache-2.0 0BSD MPL-2.0 CC0-1.0 CC-BY-4.0 Unlicense BlueOak-1.0.0 Python-2.0 Zlib PSF-2.0 Artistic-2.0 AGPL-3.0-or-later --ignoreRootPackageLicense --disableReport",
+        "lint:pkg": "publint --strict",
+        "lint:types": "attw --pack . --ignore-rules cjs-resolves-to-esm",
+        "lint:api": "api-extractor run --local --verbose",
+        "test": "vitest run",
+        "test:types": "tsc --noEmit",
+        "prepublish": "npm run build"
+    },
+    "peerDependencies": {
+        "@vex-chat/types": "^2.0.0",
+        "typescript": ">=5.9.0 || >=6.0.0"
+    },
+    "peerDependenciesMeta": {
+        "typescript": {
+            "optional": true
+        }
+    },
+    "dependencies": {
+        "@noble/hashes": "2.0.1",
+        "@stablelib/base64": "2.0.1",
+        "@stablelib/utf8": "2.1.0",
+        "bip39": "3.1.0",
+        "ed2curve": "0.3.0",
+        "msgpackr": "1.11.9",
+        "tweetnacl": "1.0.3"
+    },
+    "devDependencies": {
+        "@arethetypeswrong/cli": "0.18.2",
+        "@changesets/cli": "2.30.0",
+        "@microsoft/api-extractor": "7.58.2",
+        "@types/create-hmac": "1.1.3",
+        "@types/ed2curve": "0.2.4",
+        "@types/node": "25.6.0",
+        "@vex-chat/types": "2.0.0",
+        "@vitest/eslint-plugin": "1.6.15",
+        "eslint": "10.2.0",
+        "eslint-config-prettier": "10.1.8",
+        "eslint-plugin-perfectionist": "5.8.0",
+        "husky": "9.1.7",
+        "lint-staged": "16.4.0",
+        "prettier": "3.8.2",
+        "publint": "0.3.18",
+        "rimraf": "6.1.3",
+        "type-coverage": "2.29.7",
+        "typescript": "6.0.2",
+        "typescript-eslint": "8.58.1",
+        "vitest": "4.1.4"
+    },
+    "typeCoverage": {
+        "atLeast": 100,
+        "strict": true,
+        "ignoreCatch": true
+    },
+    "lint-staged": {
+        "src/**/*.ts": [
+            "eslint --fix",
+            "prettier --write"
+        ],
+        "*.{json,md,yaml,yml}": [
+            "prettier --write"
+        ]
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/vex-protocol/crypto-js.git"
+    },
+    "bugs": {
+        "url": "https://github.com/vex-protocol/crypto-js/issues"
+    },
+    "homepage": "https://github.com/vex-protocol/crypto-js#readme",
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
     }
-  },
-  "files": [
-    "dist"
-  ],
-  "author": "Extra <extrahash@protonmail.com>",
-  "license": "AGPL-3.0-or-later",
-  "scripts": {
-    "build": "rimraf dist && tsc",
-    "prepack": "npm run build",
-    "prettier": "prettier '**/*.{ts,tsx,json,md}' --ignore-path .gitignore --write",
-    "lint": "eslint src/**/*.ts",
-    "lint-fix": "eslint src/**/*.ts --fix",
-    "prepublish": "npm run build",
-    "test": "vitest run"
-  },
-  "peerDependencies": {
-    "@vex-chat/types": "^1.0.0-rc.1",
-    "typescript": ">=5.9.0 || >=6.0.0"
-  },
-  "peerDependenciesMeta": {
-    "typescript": {
-      "optional": true
-    }
-  },
-  "dependencies": {
-    "msgpackr": "1.11.8",
-    "@stablelib/base64": "^2.0.1",
-    "@stablelib/utf8": "^2.1.0",
-    "bip39": "^3.1.0",
-    "ed2curve": "^0.3.0",
-    "tweetnacl": "^1.0.3"
-  },
-  "devDependencies": {
-    "@changesets/cli": "^2.29.8",
-    "@types/create-hmac": "^1.1.3",
-    "@types/ed2curve": "^0.2.4",
-    "@types/node": "^24.12.2",
-    "@typescript-eslint/eslint-plugin": "^8.57.1",
-    "@typescript-eslint/parser": "^8.57.1",
-    "@vex-chat/types": "^1.0.0-rc.1",
-    "eslint": "^10.1.0",
-    "eslint-config-prettier": "^9.0.0",
-    "husky": "^9.0.0",
-    "lint-staged": "^15.2.0",
-    "prettier": "^3.2.0",
-    "rimraf": "^6.1.3",
-    "typescript": "^6.0.2",
-    "vitest": "^3.0.0"
-  },
-  "lint-staged": {
-    "src/**/*.{ts}": [
-      "eslint --fix"
-    ]
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/vex-chat/libvex-js.git"
-  },
-  "bugs": {
-    "url": "https://github.com/vex-chat/libvex-js/issues"
-  },
-  "homepage": "https://github.com/vex-chat/libvex-js#readme",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  }
 }

package/src/__tests__/XKeyConvert.ts

@@ -0,0 +1,68 @@
+import type nacl from "tweetnacl";
+
+import { XKeyConvert, XUtils } from "../index.js";
+
+const ed25519Keys = {
+    private:
+        "f69c92fbb224e1d75c5dffb5e40946e6106baa89ad73dbb6ef0bec2d8562d8a28d0538a45bce3d6fd43cd80a247da063c67cd01da2e263758567a51db5b1f7c6",
+    public: "8d0538a45bce3d6fd43cd80a247da063c67cd01da2e263758567a51db5b1f7c6",
+};
+
+const convertedX25519Keys = {
+    private: "10ed501acc2125730c294aa4b78eac989588d031015d1c77a75ea98aa7744b7a",
+    public: "55c4ca5a1d8e2859e186f36564cc41c9c9882ed9dbc01be8ec9a36b106eeee5b",
+};
+
+test("convertKeyPair", () => {
+    const keys = keyPairFromString(ed25519Keys);
+    const converted = XKeyConvert.convertKeyPair(keys);
+    // ed2curve returns null if conversion fails, though for valid keys it shouldn't.
+    // We cast to any to allow lodash comparison or check for existence
+    expect(converted).toBeDefined();
+    if (converted) {
+        expect(keyPairToString(converted)).toEqual(convertedX25519Keys);
+    }
+});
+
+test("convertPublicKey", () => {
+    const keys = keyPairFromString(ed25519Keys);
+    const convertedPublicKey = XKeyConvert.convertPublicKey(keys.publicKey);
+    if (!convertedPublicKey) {
+        throw new Error("Conversion failed.");
+    }
+
+    const correctConvertedKey = XUtils.decodeHex(convertedX25519Keys.public);
+    expect(XUtils.bytesEqual(convertedPublicKey, correctConvertedKey)).toBe(
+        true,
+    );
+});
+
+test("convertPrivateKey", () => {
+    const keys = keyPairFromString(ed25519Keys);
+    const convertedPrivateKey = XKeyConvert.convertSecretKey(keys.secretKey);
+    if (!convertedPrivateKey) {
+        throw new Error("Conversion failed.");
+    }
+
+    const correctConvertedKey = XUtils.decodeHex(convertedX25519Keys.private);
+    expect(XUtils.bytesEqual(convertedPrivateKey, correctConvertedKey)).toBe(
+        true,
+    );
+});
+
+function keyPairFromString(strKeyPair: { private: string; public: string }) {
+    return {
+        publicKey: XUtils.decodeHex(strKeyPair.public),
+        secretKey: XUtils.decodeHex(strKeyPair.private),
+    };
+}
+
+function keyPairToString(keyPair: nacl.BoxKeyPair | nacl.SignKeyPair): {
+    private: string;
+    public: string;
+} {
+    return {
+        private: XUtils.encodeHex(keyPair.secretKey),
+        public: XUtils.encodeHex(keyPair.publicKey),
+    };
+}

package/src/__tests__/XUtils/bytesEqual.ts

@@ -0,0 +1,16 @@
+import { XUtils } from "../../index.js";
+const { bytesEqual } = XUtils;
+
+test("bytesEqual", () => {
+    const bytes = [25, 23, 122, 142, 73, 92, 58];
+
+    const buf1 = Buffer.from(bytes);
+    const buf2 = Buffer.from(bytes);
+
+    expect(bytesEqual(buf1, buf2)).toBe(true);
+
+    bytes[0] = 0;
+    const buf3 = Buffer.from(bytes);
+
+    expect(bytesEqual(buf1, buf3)).toBe(false);
+});

package/src/__tests__/XUtils/emptyHeader.ts

@@ -0,0 +1,12 @@
+import { XUtils } from "../../index.js";
+const { emptyHeader } = XUtils;
+
+test("emptyHeader", () => {
+    const headerData =
+        "0000000000000000000000000000000000000000000000000000000000000000";
+
+    const eHeader = emptyHeader();
+    const testEmptyHeader = XUtils.decodeHex(headerData);
+
+    expect(XUtils.bytesEqual(eHeader, testEmptyHeader)).toBe(true);
+});

package/src/__tests__/XUtils/numberToUint8Arr.ts

@@ -0,0 +1,22 @@
+import { XUtils } from "../../index.js";
+
+const { bytesEqual, numberToUint8Arr } = XUtils;
+
+test("numberToUint8Arr", () => {
+    const cases: [number, number[]][] = [
+        [255, [0, 0, 0, 0, 0, 255]],
+        [65535, [0, 0, 0, 0, 255, 255]],
+        [16777215, [0, 0, 0, 255, 255, 255]],
+        [4294967295, [0, 0, 255, 255, 255, 255]],
+        [1099511627775, [0, 255, 255, 255, 255, 255]],
+        [281474976710655, [255, 255, 255, 255, 255, 255]],
+    ];
+
+    for (const [number, buffer] of cases) {
+        const arr = numberToUint8Arr(number);
+        expect(bytesEqual(arr, Buffer.from(buffer))).toBe(true);
+    }
+
+    expect(() => numberToUint8Arr(281474976710656)).toThrow();
+    expect(() => numberToUint8Arr(-1)).toThrow();
+});

package/src/__tests__/XUtils/packMessage.ts

@@ -0,0 +1,23 @@
+import type { ResourceMsg } from "@vex-chat/types";
+
+import { XUtils } from "../../index.js";
+const { emptyHeader, packMessage, unpackMessage } = XUtils;
+
+test("packMessage Round Trip", () => {
+    const testMessage: ResourceMsg = {
+        action: "create",
+        data: "A Server Name",
+        resourceType: "server",
+        transmissionID: "8154ac29-54fb-407c-8353-0f67742bb7c4",
+        type: "resource",
+    };
+
+    // Pack the message using the new implementation
+    const packedBytes = packMessage(testMessage, emptyHeader());
+
+    // Unpack it immediately to verify consistency (Round Trip)
+    const [header, body] = unpackMessage(packedBytes);
+
+    expect(XUtils.bytesEqual(header, emptyHeader())).toBe(true);
+    expect(body).toEqual(testMessage);
+});

package/src/__tests__/XUtils/stringEncoding.ts

@@ -0,0 +1,68 @@
+import { XUtils } from "../../index.js";
+const {
+    decodeBase64,
+    decodeHex,
+    decodeUTF8,
+    encodeBase64,
+    encodeHex,
+    encodeUTF8,
+} = XUtils;
+
+test("Encodes and decodes hex", () => {
+    const data = [
+        "a2dc693b93b3e2a31eb2b54f26f43b8ce971c6b9b4197544",
+        "9d9158ea82750c0b164834789f216d5a17a223d87e082199",
+        "e32079ba7c8ed5e62123ab55386689c2ec9f480ebb82f05c",
+        "e037b3f87bea23b8afea27c7ad173f5a43d0050559fbe091",
+        "df3cefb0f980f96eb5d6cc996702d6d166413fb2785772b1",
+        "6a328c1b103d1b331c9759ddde6c5df5753010a3c9881514",
+        "c5ad6470766845c420205700aaaed806456cae49b905aeed",
+        "5dc12b62156b1f68698b36b42e3e2f4716dffee09b768030",
+        "2985705f1f590b11e027ea6a05cbe4e0d351ab81748cbea0",
+        "6455945ea7110197a17a809cb973c2007eff629d5549273a",
+    ];
+
+    for (const value of data) {
+        expect(encodeHex(decodeHex(value)) === value).toBe(true);
+    }
+});
+
+test("Encodes and decodes utf8", () => {
+    const data = [
+        "L-dr`?%z5%?R8rT:Lwvk",
+        "H]gy!'X\")(:V/3.'LpE/",
+        "5G%h:@%PvCOk R,[]=z>",
+        '#d868evg)LM"{04$gFt',
+        '?\\/sz?&mh"$!K1_`qc15',
+        "V{Yw[ R{5L}1T3OHSj.",
+        "%-Kek[HIfW=_z`r'R|Av",
+        "E.E'\"\\ jzyxpfc'.N*z`",
+        "p:&^?<[n<ScUXB#O=|z",
+        'D;`5`"@H7X8Iw0%KbJr8',
+        '#,y][nQ9]",.62Bwxj#d',
+        '[eN"USyz$Dg@%a=a)r2h',
+    ];
+
+    for (const value of data) {
+        expect(encodeUTF8(decodeUTF8(value))).toBe(value);
+    }
+});
+
+test("Encodes and decodes base64", () => {
+    const data = [
+        "+UMP/v5VnVF/qSrSDfcLAXZ9jEauYFrbAcgtE3z46bI=",
+        "Cb+zq/R1zMRSEMGA1p47XWzwD48NZ/JqLO1p1hUnpEY=",
+        "mODgEB/U3MnvMHuG5fQ0xv8NRqo24diRlzyzJ4/Et7g=",
+        "vvYVuOpi3/pMdP49C7TgTqEdk02/LlcIY9a0CPyOJsc=",
+        "S6vBIf8WXmPi/BPV3ei9CMgdanxBNiTl8oHQ/HSnvsU=",
+        "0i2WNMF8I5ewIAefTbBBjhS3sZwZ9tILLpksPE00bt8=",
+        "W3SHYUb/F3sWFytIYNG4TCBgrDT80L0A9bB335nU8/8=",
+        "vbov+TNLyWc+VdpH7egFOifdKup26ertUlutTv8kFyY=",
+        "re9JVfQRSsXaaUG9uLoMd/bW05xDcCnk0qaPh6CUn90=",
+        "X9AyjBOM9tAsXrINjeDr5wgMiZNlkK5HlOOtDBwMeFw=",
+    ];
+
+    for (const value of data) {
+        expect(encodeBase64(decodeBase64(value)) === value).toBe(true);
+    }
+});

package/src/__tests__/XUtils/uint8ArrToNumber.ts

@@ -0,0 +1,19 @@
+import { XUtils } from "../../index.js";
+
+const { uint8ArrToNumber } = XUtils;
+
+test("uint8ArrToNumber", () => {
+    const cases: [number, number[]][] = [
+        [255, [0, 0, 0, 0, 0, 255]],
+        [65535, [0, 0, 0, 0, 255, 255]],
+        [16777215, [0, 0, 0, 255, 255, 255]],
+        [4294967295, [0, 0, 255, 255, 255, 255]],
+        [1099511627775, [0, 255, 255, 255, 255, 255]],
+        [281474976710655, [255, 255, 255, 255, 255, 255]],
+    ];
+
+    for (const [expected, buffer] of cases) {
+        const actual = uint8ArrToNumber(Buffer.from(buffer));
+        expect(actual === expected).toBe(true);
+    }
+});

package/src/__tests__/XUtils/unpackMessage.ts

@@ -0,0 +1,25 @@
+import type { ResourceMsg } from "@vex-chat/types";
+
+import { XUtils } from "../../index.js";
+const { bytesEqual, emptyHeader, unpackMessage } = XUtils;
+
+test("unpackMessage (Legacy Compatibility)", () => {
+    const testHeader = emptyHeader();
+    const testMessage: ResourceMsg = {
+        action: "create",
+        data: "A Server Name",
+        resourceType: "server",
+        transmissionID: "8154ac29-54fb-407c-8353-0f67742bb7c4",
+        type: "resource",
+    };
+
+    // This hex string was generated by the old version (msgpack-lite).
+    // We keep this test to ensure the new version (msgpackr) can read old data.
+    const packedTestMessage =
+        "000000000000000000000000000000000000000000000000000000000000000085a474797065a87265736f75726365ac7265736f7572636554797065a6736572766572a6616374696f6ea6637265617465ae7472616e736d697373696f6e4944d92438313534616332392d353466622d343037632d383335332d306636373734326262376334a464617461ad4120536572766572204e616d65";
+    const messageData = XUtils.decodeHex(packedTestMessage);
+
+    const [unpackedHeader, unpackedMessage] = unpackMessage(messageData);
+    expect(bytesEqual(unpackedHeader, testHeader)).toBe(true);
+    expect(unpackedMessage).toEqual(testMessage);
+});

package/src/__tests__/xConcat.ts

@@ -0,0 +1,18 @@
+import { xConcat, XUtils } from "../index.js";
+
+test("xConcat", () => {
+    const data1 = "dead";
+    const data2 = "beef";
+    const data3 = "bead";
+    const correctConcatData = data1 + data2 + data3;
+
+    const concatData = XUtils.encodeHex(
+        xConcat(
+            XUtils.decodeHex(data1),
+            XUtils.decodeHex(data2),
+            XUtils.decodeHex(data3),
+        ),
+    );
+
+    expect(concatData === correctConcatData).toBe(true);
+});

package/src/__tests__/xDH.ts

@@ -0,0 +1,16 @@
+import { xDH, XUtils } from "../index.js";
+
+test("xDH", () => {
+    const myPrivateKey =
+        "918ed243e2c6c507168b20e8b167cff33a10c30e99e8defe28dc2147f5cce703";
+    const theirPublicKey =
+        "6f4cc1ffc4009bd4f94628ba5922e40afa3491f0daa43ec9da0f7dc39bb1c026";
+
+    const correctDerivedKey =
+        "19a8594bdcf875ec9d4b8b9615ea8b73a0b327bb64b8f727dd2dee3a603a2230";
+    const derivedKey = XUtils.encodeHex(
+        xDH(XUtils.decodeHex(myPrivateKey), XUtils.decodeHex(theirPublicKey)),
+    );
+
+    expect(correctDerivedKey === derivedKey).toBe(true);
+});

package/src/__tests__/xEncode.ts

@@ -0,0 +1,11 @@
+import { xEncode, XUtils } from "../index.js";
+
+test("xEncode", () => {
+    const PK =
+        "3a488fc006156e77e58793846c204f17e0df88e914fc7638a084524a9124bf87";
+    const correctEncoded =
+        "00013a488fc006156e77e58793846c204f17e0df88e914fc7638a084524a9124bf87";
+
+    const encoded = XUtils.encodeHex(xEncode("X25519", XUtils.decodeHex(PK)));
+    expect(encoded === correctEncoded).toBe(true);
+});

package/src/__tests__/xHMAC.ts

@@ -0,0 +1,26 @@
+import { createHmac } from "crypto";
+
+import { Packr } from "msgpackr";
+
+import { xHMAC, XUtils } from "../index.js";
+
+test("xHMAC", () => {
+    const message = {
+        hello: "world",
+    };
+    const SK =
+        "b45203ef77c0a7fe7f771297f3e5c8248fe5b9f18ecf77faf8a8cef1058e630a";
+
+    // Must match the Packr config in src/index.ts
+    const packer = new Packr({ moreTypes: false, useRecords: false });
+    const packedMsg = packer.pack(message);
+    const hmacGen = createHmac("sha256", Buffer.from(XUtils.decodeHex(SK)));
+    hmacGen.update(packedMsg);
+    const expectedHMAC = XUtils.encodeHex(Uint8Array.from(hmacGen.digest()));
+
+    // Run the actual function
+    const hmac = XUtils.encodeHex(xHMAC(message, XUtils.decodeHex(SK)));
+
+    // Compare
+    expect(hmac).toBe(expectedHMAC);
+});

package/src/__tests__/xMnemonic.ts

@@ -0,0 +1,12 @@
+import { xMnemonic, XUtils } from "../index.js";
+
+test("xMnemonic", () => {
+    const IKM =
+        "dfb3c08de7335cc352e2c063c8e6891a06e17bf0dfcb4eec8139fc5eaf482b0e";
+    const correctMnemonic =
+        "text own casino solar cupboard giant entire fix glow elbow pelican cross host sadness sell west exclude goat example weather turtle piano promote scene";
+
+    const mnemonic = xMnemonic(XUtils.decodeHex(IKM));
+
+    expect(mnemonic === correctMnemonic).toBe(true);
+});