@freesignal/protocol 0.1.0

package/utils.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * FreeSignal Protocol
+ *
+ * Copyright (C) 2025  Christian Braghette
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeUTF8 = encodeUTF8;
+exports.decodeUTF8 = decodeUTF8;
+exports.encodeBase64 = encodeBase64;
+exports.decodeBase64 = decodeBase64;
+exports.encodeHex = encodeHex;
+exports.decodeHex = decodeHex;
+exports.numberFromUint8Array = numberFromUint8Array;
+exports.numberToUint8Array = numberToUint8Array;
+exports.verifyUint8Array = verifyUint8Array;
+exports.concatUint8Array = concatUint8Array;
+const base64_js_1 = require("base64-js");
+const tweetnacl_1 = require("tweetnacl");
+/**
+ * Decodes a Uint8Array into a UTF-8 string.
+ *
+ * @param array - The input byte array.
+ * @returns The UTF-8 encoded string.
+ */
+function encodeUTF8(array) {
+    return new TextDecoder().decode(array);
+}
+/**
+ * Encodes a UTF-8 string into a Uint8Array.
+ *
+ * @param string - The input string.
+ * @returns The resulting Uint8Array.
+ */
+function decodeUTF8(string) {
+    return new TextEncoder().encode(string);
+}
+/**
+ * Encodes a Uint8Array into a Base64 string.
+ *
+ * @param array - The input byte array.
+ * @returns The Base64 encoded string.
+ */
+function encodeBase64(array) {
+    return (0, base64_js_1.fromByteArray)(array !== null && array !== void 0 ? array : new Uint8Array());
+}
+/**
+ * Decodes a Base64 string into a Uint8Array.
+ *
+ * @param string - The Base64 string.
+ * @returns The decoded Uint8Array.
+ */
+function decodeBase64(string) {
+    return (0, base64_js_1.toByteArray)(string !== null && string !== void 0 ? string : "");
+}
+function encodeHex(array) {
+    var _a;
+    return Array.from((_a = array === null || array === void 0 ? void 0 : array.values()) !== null && _a !== void 0 ? _a : []).map(value => value.toString(16).padStart(2, '0')).join('');
+}
+function decodeHex(string) {
+    return new Uint8Array(!string ? [] :
+        Array.from(string).reduce((prev, curr, index) => {
+            if (index % 2 === 0)
+                prev.push(curr);
+            else
+                prev[prev.length - 1] += curr;
+            return prev;
+        }, []).map(value => Number.parseInt(value, 16)));
+}
+/**
+ * Converts a Uint8Array into a number.
+ *
+ * @param array - The input byte array.
+ * @returns The resulting number.
+ */
+function numberFromUint8Array(array, endian = 'little') {
+    let total = 0;
+    if (array) {
+        if (endian === 'big')
+            array = array.reverse();
+        for (let c = 0; c < array.length; c++)
+            total += array[c] << (c * 8);
+    }
+    return total;
+}
+/**
+ * Converts a number into a Uint8Array of specified length.
+ *
+ * @param number - The number to convert.
+ * @param length - The desired output length.
+ * @returns A Uint8Array representing the number.
+ */
+function numberToUint8Array(number, length, endian = 'little') {
+    if (!number)
+        return new Uint8Array(length !== null && length !== void 0 ? length : 0).fill(0);
+    const arr = [];
+    while (number > 0) {
+        arr.push(number & 255);
+        number = number >>> 8;
+    }
+    const out = new Uint8Array(length !== null && length !== void 0 ? length : arr.length);
+    out.set(arr);
+    return endian === 'little' ? out : out.reverse();
+}
+/**
+ * Compare Uint8Arrays.
+ *
+ * @param a - First Uint8Array to compare to.
+ * @param b - Arrays to compare to the first one.
+ * @returns A boolean value.
+ */
+function verifyUint8Array(a, ...b) {
+    b = b.filter(value => value !== undefined);
+    if (!a || b.length === 0)
+        return false;
+    return b.every(b => (0, tweetnacl_1.verify)(a, b));
+}
+/**
+ * Concat Uint8Arrays.
+ *
+ * @param arrays - Uint8Array to concat.
+ * @returns A Uint8Array
+ */
+function concatUint8Array(...arrays) {
+    const out = new Uint8Array(arrays.map(value => value.length).reduce((prev, curr) => prev + curr));
+    let offset = 0;
+    arrays.forEach(array => {
+        out.set(array, offset);
+        offset += array.length;
+    });
+    return out;
+}

package/x3dh.d.ts

@@ -0,0 +1,74 @@
+/**
+ * FreeSignal Protocol
+ *
+ * Copyright (C) 2025  Christian Braghette
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>
+ */
+import crypto from "./crypto";
+type BoxKeyPair = crypto.KeyPair;
+type SignKeyPair = crypto.KeyPair;
+type ExportedX3DH = [
+    SignKeyPair,
+    [
+        Array<[string, BoxKeyPair]>,
+        Array<[string, BoxKeyPair]>
+    ]
+];
+interface SynMessage {
+    readonly version: number;
+    readonly PK: string;
+    readonly IK: string;
+    readonly SPK: string;
+    readonly SPKsign: string;
+    readonly OPK: string;
+}
+interface AckMessage {
+    readonly version: number;
+    readonly PK: string;
+    readonly IK: string;
+    readonly EK: string;
+    readonly SPKhash: string;
+    readonly OPKhash: string;
+    readonly AD: string;
+}
+export interface Bundle {
+    readonly version: number;
+    readonly PK: string;
+    readonly IK: string;
+    readonly SPK: string;
+    readonly SPKsign: string;
+    readonly OPK: string[];
+}
+export declare class X3DH {
+    static readonly version = 1;
+    private static readonly hkdfInfo;
+    private static readonly maxOPK;
+    private readonly PK;
+    private readonly IK;
+    private readonly bundleStore;
+    constructor(signKeyPair: SignKeyPair, instance?: [Iterable<[string, BoxKeyPair]>, Iterable<[string, BoxKeyPair]>]);
+    private generateSPK;
+    private generateOPK;
+    generateBundle(length?: number): Bundle;
+    generateSyn(): SynMessage;
+    digestSyn(message: SynMessage, encrypter?: (msg: Uint8Array, key: Uint8Array) => Uint8Array): {
+        rootKey: Uint8Array;
+        ackMessage: AckMessage;
+    };
+    digestAck(message: AckMessage, verifier?: (ciphertext: Uint8Array, key: Uint8Array) => boolean): Uint8Array | undefined;
+    export(): ExportedX3DH;
+    static import(input: ExportedX3DH): X3DH;
+}
+export {};

package/x3dh.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * FreeSignal Protocol
+ *
+ * Copyright (C) 2025  Christian Braghette
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X3DH = void 0;
+const crypto_1 = __importDefault(require("./crypto"));
+const double_ratchet_1 = require("./double-ratchet");
+const utils_1 = require("./utils");
+class X3DH {
+    constructor(signKeyPair, instance) {
+        this.PK = signKeyPair;
+        this.IK = crypto_1.default.ECDH.keyPair(crypto_1.default.hash(signKeyPair.secretKey));
+        this.bundleStore = {
+            SPK: new Map(instance ? instance[0] : []),
+            OPK: new Map(instance ? instance[1] : [])
+        };
+    }
+    generateSPK() {
+        const SPK = crypto_1.default.ECDH.keyPair();
+        const SPKhash = crypto_1.default.hash(SPK.publicKey);
+        this.bundleStore.SPK.set((0, utils_1.encodeBase64)(SPKhash), SPK);
+        return { SPK, SPKhash };
+    }
+    generateOPK(spkHash) {
+        const OPK = crypto_1.default.ECDH.keyPair();
+        const OPKhash = crypto_1.default.hash(OPK.publicKey);
+        this.bundleStore.OPK.set((0, utils_1.encodeBase64)(spkHash).concat((0, utils_1.encodeBase64)(OPKhash)), OPK);
+        return { OPK, OPKhash };
+    }
+    generateBundle(length) {
+        const { SPK, SPKhash } = this.generateSPK();
+        const OPK = new Array(length !== null && length !== void 0 ? length : X3DH.maxOPK).fill(0).map(() => this.generateOPK(SPKhash).OPK);
+        return {
+            version: X3DH.version,
+            PK: (0, utils_1.encodeBase64)(this.PK.publicKey),
+            IK: (0, utils_1.encodeBase64)(this.IK.publicKey),
+            SPK: (0, utils_1.encodeBase64)(SPK.publicKey),
+            SPKsign: (0, utils_1.encodeBase64)(crypto_1.default.EdDSA.sign((0, utils_1.concatUint8Array)(crypto_1.default.hash(this.IK.publicKey), SPKhash), this.PK.secretKey)),
+            OPK: OPK.map(opk => (0, utils_1.encodeBase64)(opk.publicKey))
+        };
+    }
+    generateSyn() {
+        const { SPK, SPKhash } = this.generateSPK();
+        const { OPK } = this.generateOPK(SPKhash);
+        return {
+            version: X3DH.version,
+            PK: (0, utils_1.encodeBase64)(this.PK.publicKey),
+            IK: (0, utils_1.encodeBase64)(this.IK.publicKey),
+            SPK: (0, utils_1.encodeBase64)(SPK.publicKey),
+            SPKsign: (0, utils_1.encodeBase64)(crypto_1.default.EdDSA.sign((0, utils_1.concatUint8Array)(crypto_1.default.hash(this.IK.publicKey), SPKhash), this.PK.secretKey)),
+            OPK: (0, utils_1.encodeBase64)(OPK.publicKey)
+        };
+    }
+    digestSyn(message, encrypter) {
+        const EK = crypto_1.default.ECDH.keyPair();
+        const SPK = (0, utils_1.decodeBase64)(message.SPK);
+        const IK = (0, utils_1.decodeBase64)(message.IK);
+        const OPK = message.OPK ? (0, utils_1.decodeBase64)(message.OPK) : undefined;
+        const spkHash = crypto_1.default.hash(SPK);
+        const opkHash = OPK ? crypto_1.default.hash(OPK) : new Uint8Array();
+        const rootKey = crypto_1.default.hkdf(new Uint8Array([
+            ...crypto_1.default.scalarMult(this.IK.secretKey, SPK),
+            ...crypto_1.default.scalarMult(EK.secretKey, IK),
+            ...crypto_1.default.scalarMult(EK.secretKey, SPK),
+            ...OPK ? crypto_1.default.scalarMult(EK.secretKey, OPK) : new Uint8Array()
+        ]), new Uint8Array(double_ratchet_1.Session.rootKeyLength).fill(0), X3DH.hkdfInfo, double_ratchet_1.Session.rootKeyLength);
+        if (!encrypter)
+            encrypter = (msg, key) => crypto_1.default.box.encrypt(msg, new Uint8Array(crypto_1.default.box.nonceLength).fill(0), key);
+        return {
+            rootKey,
+            ackMessage: {
+                version: X3DH.version,
+                PK: (0, utils_1.encodeBase64)(this.PK.publicKey),
+                IK: (0, utils_1.encodeBase64)(this.IK.publicKey),
+                EK: (0, utils_1.encodeBase64)(EK.publicKey),
+                SPKhash: (0, utils_1.encodeBase64)(spkHash),
+                OPKhash: (0, utils_1.encodeBase64)(opkHash),
+                AD: (0, utils_1.encodeBase64)(encrypter((0, utils_1.concatUint8Array)(crypto_1.default.hash(this.IK.publicKey), crypto_1.default.hash(IK)), rootKey))
+            }
+        };
+    }
+    digestAck(message, verifier) {
+        const SPK = this.bundleStore.SPK.get(message.SPKhash);
+        const OPK = this.bundleStore.OPK.get(message.SPKhash.concat(message.OPKhash));
+        if (!SPK || !OPK || !message.IK || !message.EK)
+            return;
+        const IK = (0, utils_1.decodeBase64)(message.IK);
+        const EK = (0, utils_1.decodeBase64)(message.EK);
+        const rootKey = crypto_1.default.hkdf(new Uint8Array([
+            ...crypto_1.default.scalarMult(SPK.secretKey, IK),
+            ...crypto_1.default.scalarMult(this.IK.secretKey, EK),
+            ...crypto_1.default.scalarMult(SPK.secretKey, EK),
+            ...OPK ? crypto_1.default.scalarMult(OPK.secretKey, EK) : new Uint8Array()
+        ]), new Uint8Array(double_ratchet_1.Session.rootKeyLength).fill(0), X3DH.hkdfInfo, double_ratchet_1.Session.rootKeyLength);
+        if (!verifier)
+            verifier = (ciphertext, key) => (0, utils_1.verifyUint8Array)(crypto_1.default.box.decrypt(ciphertext, new Uint8Array(crypto_1.default.box.nonceLength).fill(0), key), (0, utils_1.concatUint8Array)(crypto_1.default.hash(IK), crypto_1.default.hash(this.IK.publicKey)));
+        if (!verifier((0, utils_1.decodeBase64)(message.AD), rootKey))
+            return;
+        return rootKey;
+    }
+    export() {
+        return [
+            this.IK,
+            [
+                Array.from(this.bundleStore.SPK.entries()),
+                Array.from(this.bundleStore.OPK.entries())
+            ]
+        ];
+    }
+    static import(input) {
+        return new X3DH(...input);
+    }
+}
+exports.X3DH = X3DH;
+X3DH.version = 1;
+X3DH.hkdfInfo = (0, utils_1.decodeUTF8)("freesignal/x3dh/" + X3DH.version);
+X3DH.maxOPK = 10;