@freesignal/protocol 0.1.0

package/double-ratchet.d.ts

@@ -0,0 +1,172 @@
+/**
+ * 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 { Encodable } from "./data";
+/**
+ * Creates a new Double Ratchet session.
+ *
+ * @param opts.remoteKey The public key of the remote party.
+ * @param opts.preSharedKey An optional pre-shared key to initialize the session.
+ *
+ * @returns A new Double Ratchet session.
+ */
+export declare function createSession(opts?: {
+    remoteKey?: Uint8Array;
+    preSharedKey?: Uint8Array;
+}): Session;
+/**
+ * Represents a secure Double Ratchet session.
+ * Used for forward-secure encryption and decryption of messages.
+ */
+export declare class Session {
+    private static readonly skipLimit;
+    static readonly version = 1;
+    static readonly rootKeyLength: number;
+    private keyPair;
+    private _remoteKey?;
+    private rootKey?;
+    private sendingChain?;
+    private sendingCount;
+    private previousCount;
+    private receivingChain?;
+    private receivingCount;
+    private previousKeys;
+    constructor(opts?: {
+        remoteKey?: Uint8Array;
+        preSharedKey?: Uint8Array;
+    });
+    /**
+     * Whether both the sending and receiving chains are initialized.
+     */
+    get handshaked(): boolean;
+    /**
+     * The public key of this session.
+     */
+    get publicKey(): Uint8Array;
+    /**
+     * The last known remote public key.
+     */
+    get remoteKey(): Uint8Array | undefined;
+    /**
+     * Set remote public key.
+     */
+    setRemoteKey(key: Uint8Array): this;
+    private dhRatchet;
+    private getSendingKey;
+    private getReceivingKey;
+    /**
+     * Encrypts a message payload using the current sending chain.
+     *
+     * @param message - The message as a Uint8Array.
+     * @returns An EncryptedPayload or undefined if encryption fails.
+     */
+    encrypt(message: Uint8Array): EncryptedPayload | undefined;
+    /**
+     * Decrypts an encrypted message.
+     *
+     * @param payload - The received encrypted message.
+     * @returns The decrypted message as a Uint8Array, or undefined if decryption fails.
+     */
+    decrypt(payload: Uint8Array | EncryptedPayload): Uint8Array | undefined;
+    /**
+     * Export the state of the session;
+     */
+    export(): string;
+    /**
+     * Import a state.
+     *
+     * @param json string returned by `export()` method.
+     * @returns session with the state parsed.
+     */
+    static import(json: string): Session;
+    /**
+     * The fixed key length (in bytes) used throughout the Double Ratchet session.
+     * Typically 32 bytes (256 bits) for symmetric keys.
+     */
+    static readonly keyLength = 32;
+    private static symmetricRatchet;
+}
+/**
+ * Interface representing an encrypted payload.
+ * Provides metadata and de/serialization methods.
+ */
+export interface EncryptedPayload extends Encodable {
+    /**
+     * The length of the payload.
+     */
+    readonly length: number;
+    /**
+     * Version of the payload.
+     */
+    readonly version: number;
+    /**
+     * The current message count of the sending chain.
+     */
+    readonly count: number;
+    /**
+     * The count of the previous sending chain.
+     */
+    readonly previous: number;
+    /**
+     * The sender's public key used for this message.
+     */
+    readonly publicKey: Uint8Array;
+    /**
+     * The nonce used during encryption.
+     */
+    readonly nonce: Uint8Array;
+    /**
+     * The encrypted message content.
+     */
+    readonly ciphertext: Uint8Array;
+    /**
+     * The payload signature.
+     */
+    /**
+     * Set the signature of the payload.
+     *
+     * @param signature signature
+     */
+    /**
+     * Return the payload without the signature.
+     */
+    /**
+     * Serializes the payload into a Uint8Array for transport.
+     */
+    encode(): Uint8Array;
+    /**
+     * Decodes the payload into a readable object format.
+     */
+    /**
+     * Returns the payload as a UTF-8 string.
+     */
+    toString(): string;
+    /**
+     * Returns the decoded object as a JSON string.
+     */
+    toJSON(): string;
+}
+export declare class EncryptedPayload {
+    /**
+     * Static factory method that constructs an `EncryptedPayload` from a raw Uint8Array.
+     *
+     * @param array - A previously serialized encrypted payload.
+     * @returns An instance of `EncryptedPayload`.
+     */
+    static from(array: Uint8Array | EncryptedPayload): EncryptedPayload;
+}

package/double-ratchet.js

@@ -0,0 +1,338 @@
+"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.EncryptedPayload = exports.Session = void 0;
+exports.createSession = createSession;
+const crypto_1 = __importDefault(require("./crypto"));
+const utils_1 = require("./utils");
+/**
+ * Creates a new Double Ratchet session.
+ *
+ * @param opts.remoteKey The public key of the remote party.
+ * @param opts.preSharedKey An optional pre-shared key to initialize the session.
+ *
+ * @returns A new Double Ratchet session.
+ */
+function createSession(opts) {
+    return new Session(opts);
+}
+/**
+ * Represents a secure Double Ratchet session.
+ * Used for forward-secure encryption and decryption of messages.
+ */
+class Session {
+    constructor(opts = {}) {
+        this.keyPair = crypto_1.default.ECDH.keyPair();
+        this.sendingCount = 0;
+        this.previousCount = 0;
+        this.receivingCount = 0;
+        this.previousKeys = new KeyMap();
+        if (opts.preSharedKey)
+            this.rootKey = opts.preSharedKey;
+        if (opts.remoteKey) {
+            this._remoteKey = opts.remoteKey;
+            this.sendingChain = this.dhRatchet();
+        }
+    }
+    /**
+     * Whether both the sending and receiving chains are initialized.
+     */
+    get handshaked() { return this.sendingChain && this.receivingChain ? true : false; }
+    /**
+     * The public key of this session.
+     */
+    get publicKey() { return this.keyPair.publicKey; }
+    /**
+     * The last known remote public key.
+     */
+    get remoteKey() { return this._remoteKey; }
+    /**
+     * Set remote public key.
+     */
+    setRemoteKey(key) {
+        this._remoteKey = key;
+        this.receivingChain = this.dhRatchet();
+        if (this.receivingCount > (EncryptedPayloadConstructor.maxCount - Session.skipLimit * 2))
+            this.receivingCount = 0;
+        this.previousCount = this.sendingCount;
+        this.keyPair = crypto_1.default.ECDH.keyPair();
+        this.sendingChain = this.dhRatchet();
+        if (this.sendingCount > (EncryptedPayloadConstructor.maxCount - Session.skipLimit * 2))
+            this.sendingCount = 0;
+        return this;
+    }
+    dhRatchet(info) {
+        if (!this._remoteKey)
+            throw new Error();
+        const sharedKey = crypto_1.default.scalarMult(this.keyPair.secretKey, this._remoteKey);
+        if (!this.rootKey)
+            this.rootKey = crypto_1.default.hash(sharedKey);
+        const hashkey = crypto_1.default.hkdf(sharedKey, this.rootKey, info, Session.keyLength * 2);
+        this.rootKey = hashkey.slice(0, Session.keyLength);
+        return hashkey.slice(Session.keyLength);
+    }
+    getSendingKey() {
+        if (!this.sendingChain)
+            throw new Error;
+        const out = Session.symmetricRatchet(this.sendingChain);
+        this.sendingChain = out[0];
+        this.sendingCount++;
+        return out[1];
+    }
+    getReceivingKey() {
+        if (!this.receivingChain)
+            throw new Error();
+        const out = Session.symmetricRatchet(this.receivingChain);
+        this.receivingChain = out[0];
+        this.receivingCount++;
+        return out[1];
+    }
+    /**
+     * Encrypts a message payload using the current sending chain.
+     *
+     * @param message - The message as a Uint8Array.
+     * @returns An EncryptedPayload or undefined if encryption fails.
+     */
+    encrypt(message) {
+        try {
+            const key = this.getSendingKey();
+            if (this.sendingCount >= EncryptedPayloadConstructor.maxCount || this.previousCount >= EncryptedPayloadConstructor.maxCount)
+                throw new Error();
+            const nonce = crypto_1.default.randomBytes(EncryptedPayloadConstructor.nonceLength);
+            const ciphertext = crypto_1.default.box.encrypt(message, nonce, key);
+            return new EncryptedPayloadConstructor(this.sendingCount, this.previousCount, this.keyPair.publicKey, nonce, ciphertext);
+        }
+        catch (error) {
+            return undefined;
+        }
+    }
+    /**
+     * Decrypts an encrypted message.
+     *
+     * @param payload - The received encrypted message.
+     * @returns The decrypted message as a Uint8Array, or undefined if decryption fails.
+     */
+    decrypt(payload) {
+        var _a;
+        try {
+            const encrypted = EncryptedPayload.from(payload);
+            const publicKey = encrypted.publicKey;
+            if (!(0, utils_1.verifyUint8Array)(publicKey, this._remoteKey)) {
+                while (this.receivingCount < encrypted.previous)
+                    this.previousKeys.set(this.receivingCount, this.getReceivingKey());
+                this.setRemoteKey(publicKey);
+            }
+            let key;
+            const count = encrypted.count;
+            if (this.receivingCount < count) {
+                let i = 0;
+                while (this.receivingCount < count - 1 && i < Session.skipLimit) {
+                    this.previousKeys.set(this.receivingCount, this.getReceivingKey());
+                }
+                key = this.getReceivingKey();
+            }
+            else {
+                key = this.previousKeys.get(count);
+            }
+            if (!key)
+                return undefined;
+            return (_a = crypto_1.default.box.decrypt(encrypted.ciphertext, encrypted.nonce, key)) !== null && _a !== void 0 ? _a : undefined;
+        }
+        catch (error) {
+            return undefined;
+        }
+    }
+    /**
+     * Export the state of the session;
+     */
+    export() {
+        return JSON.stringify({
+            remoteKey: (0, utils_1.encodeBase64)(this._remoteKey),
+            rootKey: (0, utils_1.encodeBase64)(this.rootKey),
+            sendingChain: (0, utils_1.encodeBase64)(this.sendingChain),
+            receivingChain: (0, utils_1.encodeBase64)(this.receivingChain),
+            sendingCount: this.sendingCount,
+            receivingCount: this.receivingCount,
+            //previousCount: this.previousCount
+        });
+    }
+    /**
+     * Import a state.
+     *
+     * @param json string returned by `export()` method.
+     * @returns session with the state parsed.
+     */
+    static import(json) {
+        const data = JSON.parse(json);
+        const session = new Session({ remoteKey: (0, utils_1.decodeBase64)(data.remoteKey), preSharedKey: (0, utils_1.decodeBase64)(data.rootKey) });
+        session.sendingChain = (0, utils_1.decodeBase64)(data.sendingChain);
+        session.receivingChain = (0, utils_1.decodeBase64)(data.receivingChain);
+        session.sendingCount = data.sendingCount;
+        session.receivingCount = data.receivingCount;
+        return session;
+    }
+    static symmetricRatchet(chain, salt, info) {
+        const hash = crypto_1.default.hkdf(chain, salt !== null && salt !== void 0 ? salt : new Uint8Array(), info, Session.keyLength * 2);
+        return [new Uint8Array(hash.buffer, 0, Session.keyLength), new Uint8Array(hash.buffer, Session.keyLength)];
+    }
+}
+exports.Session = Session;
+Session.skipLimit = 1000;
+Session.version = 1;
+Session.rootKeyLength = crypto_1.default.box.keyLength;
+/**
+ * The fixed key length (in bytes) used throughout the Double Ratchet session.
+ * Typically 32 bytes (256 bits) for symmetric keys.
+ */
+Session.keyLength = 32;
+class EncryptedPayload {
+    /**
+     * Static factory method that constructs an `EncryptedPayload` from a raw Uint8Array.
+     *
+     * @param array - A previously serialized encrypted payload.
+     * @returns An instance of `EncryptedPayload`.
+     */
+    static from(array) {
+        return new EncryptedPayloadConstructor(array);
+    }
+}
+exports.EncryptedPayload = EncryptedPayload;
+class EncryptedPayloadConstructor {
+    constructor(...arrays) {
+        var _a;
+        arrays = arrays.filter(value => value !== undefined);
+        if (arrays[0] instanceof EncryptedPayloadConstructor) {
+            this.raw = arrays[0].raw;
+            return this;
+        }
+        if (typeof arrays[0] === 'number')
+            arrays[0] = (0, utils_1.numberToUint8Array)(arrays[0], EncryptedPayloadConstructor.countLength);
+        if (typeof arrays[1] === 'number')
+            arrays[1] = (0, utils_1.numberToUint8Array)(arrays[1], EncryptedPayloadConstructor.countLength);
+        if (arrays.length > 1) {
+            arrays.unshift((_a = (typeof arrays[5] === 'number' ? (0, utils_1.numberToUint8Array)(arrays[5]) : arrays[5])) !== null && _a !== void 0 ? _a : (0, utils_1.numberToUint8Array)(Session.version));
+        }
+        this.raw = (0, utils_1.concatUint8Array)(...arrays);
+    }
+    get length() { return this.raw.length; }
+    get version() { return (0, utils_1.numberFromUint8Array)(new Uint8Array(this.raw.buffer, ...Offsets.version.get)); }
+    get count() { return (0, utils_1.numberFromUint8Array)(new Uint8Array(this.raw.buffer, ...Offsets.count.get)); }
+    get previous() { return (0, utils_1.numberFromUint8Array)(new Uint8Array(this.raw.buffer, ...Offsets.previous.get)); }
+    get publicKey() { return new Uint8Array(this.raw.buffer, ...Offsets.publicKey.get); }
+    get nonce() { return new Uint8Array(this.raw.buffer, ...Offsets.nonce.get); }
+    get ciphertext() { return new Uint8Array(this.raw.buffer, Offsets.ciphertext.start); }
+    /*public get signature() { return this.signed ? new Uint8Array(this.raw.buffer, this.raw.length - EncryptedPayloadConstructor.signatureLength) : undefined }
+
+    public setSignature(signature: Uint8Array): this {
+        this.raw = concatUint8Array(this.raw, signature);
+        this.signed = true;
+        return this;
+    }
+
+    public encodeUnsigned(): Uint8Array {
+        return !this.signed ? this.raw : new Uint8Array(this.raw.buffer, 0, this.raw.length - EncryptedPayloadConstructor.signatureLength);
+    }
+
+    public encode(fixedLength?: number): Uint8Array {
+        if (fixedLength) {
+            var padStart = Math.floor(Math.random() * fixedLength - 2 - this.raw.length);
+            var padEnd = Math.floor(padStart + 2 + this.raw.length);
+        } else {
+            padStart = Math.floor(Math.random() * (EncryptedPayloadConstructor.maxPadLength - EncryptedPayloadConstructor.minPadLength) + 1) + EncryptedPayloadConstructor.minPadLength;
+            padEnd = Math.floor(Math.random() * (EncryptedPayloadConstructor.maxPadLength - EncryptedPayloadConstructor.minPadLength) + 1) + EncryptedPayloadConstructor.minPadLength;
+        }
+        return concatUint8Array(
+            randomBytes(padStart - 1).map((value) => value !== 255 ? value : (value - 1)),
+            new Uint8Array(1).fill(255), this.raw, new Uint8Array(1).fill(255),
+            randomBytes(padEnd).map((value) => value !== 255 ? value : (value - 1)),
+        );
+    }*/
+    encode() {
+        return this.raw;
+    }
+    decode() {
+        return {
+            version: this.version,
+            count: this.count,
+            previous: this.previous,
+            publicKey: (0, utils_1.encodeBase64)(this.publicKey),
+            nonce: (0, utils_1.encodeBase64)(this.nonce),
+            ciphertext: (0, utils_1.encodeUTF8)(this.ciphertext),
+            //signature: encodeBase64(this.signature)
+        };
+    }
+    toString() {
+        return (0, utils_1.encodeUTF8)(this.raw);
+    }
+    toJSON() {
+        return JSON.stringify(this.decode());
+    }
+}
+//public static readonly signatureLength = crypto.EdDSA.signatureLength;
+EncryptedPayloadConstructor.secretKeyLength = crypto_1.default.ECDH.secretKeyLength;
+EncryptedPayloadConstructor.publicKeyLength = crypto_1.default.ECDH.publicKeyLength;
+EncryptedPayloadConstructor.keyLength = crypto_1.default.box.keyLength;
+EncryptedPayloadConstructor.nonceLength = crypto_1.default.box.nonceLength;
+//public static readonly minPadLength = 6;
+//public static readonly maxPadLength = 14;
+EncryptedPayloadConstructor.maxCount = 65536; //32768;
+EncryptedPayloadConstructor.countLength = 2;
+class Offsets {
+    static set(start, length) {
+        class Offset {
+            constructor(start, length) {
+                this.start = start;
+                this.length = length;
+                if (typeof length === 'number')
+                    this.end = start + length;
+            }
+            get get() {
+                return [this.start, this.length];
+            }
+        }
+        return new Offset(start, length);
+    }
+}
+Offsets.checksum = Offsets.set(0, 0);
+Offsets.version = Offsets.set(Offsets.checksum.end, 1);
+Offsets.count = Offsets.set(Offsets.version.end, EncryptedPayloadConstructor.countLength);
+Offsets.previous = Offsets.set(Offsets.count.end, EncryptedPayloadConstructor.countLength);
+Offsets.publicKey = Offsets.set(Offsets.previous.end, EncryptedPayloadConstructor.publicKeyLength);
+Offsets.nonce = Offsets.set(Offsets.publicKey.end, EncryptedPayloadConstructor.nonceLength);
+Offsets.ciphertext = Offsets.set(Offsets.nonce.end, undefined);
+class KeyMap {
+    constructor(iterable) {
+        return new KeyMapConstructor(iterable);
+    }
+}
+class KeyMapConstructor extends Map {
+    constructor(iterable) {
+        super(iterable);
+    }
+    get(key) {
+        const out = super.get(key);
+        if (out && !super.delete(key))
+            throw new Error();
+        return out;
+    }
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@freesignal/protocol",
+  "version": "0.1.0",
+  "description": "Signal Protocol implementation in javascript",
+  "license": "GPL-3.0-or-later",
+  "author": "Christian Braghette",
+  "type": "commonjs",
+  "main": "index.js",
+  "scripts": {
+    "test": "tsc && node ./build/test.js",
+    "build": "tsc && node ./build/build.js"
+  },
+  "dependencies": {
+    "base64-js": "^1.5.1",
+    "js-sha3": "^0.9.3",
+    "tweetnacl": "^1.0.3",
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.1"
+  }
+}

package/test.js

@@ -0,0 +1,17 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const x3dh_1 = require("./x3dh");
+const crypto_1 = __importDefault(require("./crypto"));
+const utils_1 = require("./utils");
+const bob = new x3dh_1.X3DH(crypto_1.default.EdDSA.keyPair());
+const alice = new x3dh_1.X3DH(crypto_1.default.EdDSA.keyPair());
+const bobmessage = bob.generateSyn();
+const { rootKey, ackMessage: aliceack } = alice.digestSyn(bobmessage);
+if ((0, utils_1.verifyUint8Array)(rootKey, bob.digestAck(aliceack))) {
+    console.log("Session established successfully between Alice and Bob.");
+}
+else
+    console.log("Error");

package/utils.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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/>
+ */
+/**
+ * Decodes a Uint8Array into a UTF-8 string.
+ *
+ * @param array - The input byte array.
+ * @returns The UTF-8 encoded string.
+ */
+export declare function encodeUTF8(array?: Uint8Array): string;
+/**
+ * Encodes a UTF-8 string into a Uint8Array.
+ *
+ * @param string - The input string.
+ * @returns The resulting Uint8Array.
+ */
+export declare function decodeUTF8(string?: string): Uint8Array;
+/**
+ * Encodes a Uint8Array into a Base64 string.
+ *
+ * @param array - The input byte array.
+ * @returns The Base64 encoded string.
+ */
+export declare function encodeBase64(array?: Uint8Array): string;
+/**
+ * Decodes a Base64 string into a Uint8Array.
+ *
+ * @param string - The Base64 string.
+ * @returns The decoded Uint8Array.
+ */
+export declare function decodeBase64(string?: string): Uint8Array;
+export declare function encodeHex(array?: Uint8Array): string;
+export declare function decodeHex(string?: string): Uint8Array;
+/**
+ * Converts a Uint8Array into a number.
+ *
+ * @param array - The input byte array.
+ * @returns The resulting number.
+ */
+export declare function numberFromUint8Array(array?: Uint8Array, endian?: 'big' | 'little'): number;
+/**
+ * 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.
+ */
+export declare function numberToUint8Array(number?: number, length?: number, endian?: 'big' | 'little'): Uint8Array;
+/**
+ * Compare Uint8Arrays.
+ *
+ * @param a - First Uint8Array to compare to.
+ * @param b - Arrays to compare to the first one.
+ * @returns A boolean value.
+ */
+export declare function verifyUint8Array(a?: Uint8Array, ...b: (Uint8Array | undefined)[]): boolean;
+/**
+ * Concat Uint8Arrays.
+ *
+ * @param arrays - Uint8Array to concat.
+ * @returns A Uint8Array
+ */
+export declare function concatUint8Array(...arrays: Uint8Array[]): Uint8Array;