@freesignal/protocol 0.1.0 → 0.1.5

package/README.md

@@ -0,0 +1,34 @@
+# freesignal-protocol
+
+This library implements a secure messaging protocol inspired by Signal, with support for encryption, data management, and key exchange.
+
+## Main File Structure
+
+- **[src/crypto.ts](src/crypto.ts)**  
+    Contains cryptographic primitives, including box, ECDH, EdDSA, and UUID.  
+    See [`crypto.box`](src/crypto.ts), [`crypto.ECDH`](src/crypto.ts), [`crypto.EdDSA`](src/crypto.ts), [`crypto.UUID`](src/crypto.ts).
+
+- **[src/data.ts](src/data.ts)**  
+    Defines data structures for messages and datagrams, including attachments and serialization.  
+    See [`Datagram`](src/data.ts), [`Message`](src/data.ts).
+
+- **[src/double-ratchet.ts](src/double-ratchet.ts)**  
+    Implements the Double Ratchet algorithm for forward secrecy in conversations.
+
+- **[src/types.ts](src/types.ts)**  
+    Defines types and interfaces used throughout the project.
+
+- **[src/utils.ts](src/utils.ts)**  
+    Utility functions for manipulating arrays, strings, and binary data.
+
+- **[src/x3dh.ts](src/x3dh.ts)**  
+    Implements the X3DH protocol for secure key exchange between users.
+
+## How to Use
+
+Import the required modules from [src/index.ts](src/index.ts) to access the main protocol features.
+
+## License
+
+Distributed under the GPL v3 license.  
+See [LICENSE](LICENSE) for details.

package/crypto.d.ts

@@ -18,22 +18,31 @@
  */
 export type HashAlgorithms = 'sha224' | 'sha256' | 'sha384' | 'sha512';
 export type HmacAlgorithms = 'kmac128' | 'kmac256';
+interface UUIDv4 {
+    toString(): string;
+    toJSON(): string;
+    toBuffer(): Uint8Array;
+}
 export interface Crypto {
     hash(message: Uint8Array, algorithm?: HashAlgorithms): Uint8Array;
     hmac(key: Uint8Array, message: Uint8Array, length?: number, algorithm?: HmacAlgorithms): Uint8Array;
     hkdf(key: Uint8Array, salt: Uint8Array, info?: Uint8Array | string, length?: number): Uint8Array;
+    readonly KeyPair: typeof Crypto.KeyPair;
     readonly box: Crypto.box;
     readonly ECDH: Crypto.ECDH;
     readonly EdDSA: Crypto.EdDSA;
+    readonly UUID: Crypto.UUID;
     randomBytes(n: number): Uint8Array;
     scalarMult(n: Uint8Array, p: Uint8Array): Uint8Array;
-    generateId(): Crypto.UUID;
 }
 export declare namespace Crypto {
     type KeyPair = {
-        publicKey: Uint8Array;
-        secretKey: Uint8Array;
+        readonly publicKey: Uint8Array;
+        readonly secretKey: Uint8Array;
     };
+    namespace KeyPair {
+        function isKeyPair(obj: any): boolean;
+    }
     interface box {
         readonly keyLength: number;
         readonly nonceLength: number;
@@ -57,9 +66,9 @@ export declare namespace Crypto {
         verify(msg: Uint8Array, sig: Uint8Array, publicKey: Uint8Array): boolean;
     }
     interface UUID {
-        toString(): string;
-        toJSON(): string;
-        toBuffer(): Uint8Array;
+        generate(): UUIDv4;
+        stringify(arr: Uint8Array, offset?: number): string;
+        parse(uuid: string): Uint8Array;
     }
 }
 declare const crypto: Crypto;

package/crypto.js

@@ -21,15 +21,27 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Crypto = void 0;
 const js_sha3_1 = require("js-sha3");
 const tweetnacl_1 = __importDefault(require("tweetnacl"));
 const uuid_1 = require("uuid");
 const utils_1 = require("./utils");
+var Crypto;
+(function (Crypto) {
+})(Crypto || (exports.Crypto = Crypto = {}));
 class CryptoConstructor {
     constructor() {
+        this.KeyPair = {
+            isKeyPair(obj) {
+                if (typeof obj === 'object' && obj.publicKey && obj.secretKey)
+                    return true;
+                return false;
+            }
+        };
         this.box = new CryptoConstructor.box();
         this.ECDH = new CryptoConstructor.ECDH();
         this.EdDSA = new CryptoConstructor.EdDSA();
+        this.UUID = new CryptoConstructor.UUID();
         this.randomBytes = tweetnacl_1.default.randomBytes;
     }
     hash(message, algorithm = 'sha256') {
@@ -63,9 +75,6 @@ class CryptoConstructor {
     scalarMult(n, p) {
         return tweetnacl_1.default.scalarMult(n, p);
     }
-    generateId() {
-        return new CryptoConstructor.UUID();
-    }
 }
 (function (CryptoConstructor) {
     class box {
@@ -121,6 +130,18 @@ class CryptoConstructor {
     }
     CryptoConstructor.EdDSA = EdDSA;
     class UUID {
+        generate() {
+            return new UUIDv4();
+        }
+        stringify(arr, offset) {
+            return (0, uuid_1.stringify)(arr, offset);
+        }
+        parse(uuid) {
+            return (0, uuid_1.parse)(uuid);
+        }
+    }
+    CryptoConstructor.UUID = UUID;
+    class UUIDv4 {
         constructor() {
             this.value = (0, uuid_1.v4)();
         }
@@ -134,7 +155,6 @@ class CryptoConstructor {
             return (0, utils_1.decodeUTF8)(this.value);
         }
     }
-    CryptoConstructor.UUID = UUID;
 })(CryptoConstructor || (CryptoConstructor = {}));
 const crypto = new CryptoConstructor();
 exports.default = crypto;

package/data.d.ts

@@ -16,15 +16,7 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <https://www.gnu.org/licenses/>
  */
-export interface Encodable {
-    readonly length: number;
-    encode(): Uint8Array;
-    toString(): string;
-    toJSON(): string;
-}
-export declare namespace Encodable {
-    function isEncodable(obj: any): boolean;
-}
+import { Encodable } from "./types";
 export declare enum Protocols {
     NULL = "",
     MESSAGE = "/freesignal/message/1.0.0",
@@ -40,11 +32,13 @@ export declare namespace Protocols {
 export interface Datagram {
     readonly id: string;
     readonly version: number;
-    readonly sender: string;
-    readonly receiver: string;
+    readonly senderKey: string;
+    readonly senderRelay?: string;
+    readonly receiverKey: string;
+    readonly receiverRelay?: string;
     readonly protocol: Protocols;
-    payload?: Uint8Array;
     readonly createdAt: number;
+    payload?: Uint8Array;
 }
 export declare namespace Datagram {
     const version = 1;
@@ -53,54 +47,20 @@ export declare namespace Datagram {
     function from(data: Uint8Array): DatagramConstructor;
 }
 declare class DatagramConstructor implements Encodable, Datagram {
-    readonly createdAt: number;
     readonly id: string;
     readonly version: number;
-    readonly sender: string;
-    readonly receiver: string;
+    readonly senderKey: string;
+    readonly senderRelay?: string;
+    readonly receiverKey: string;
+    readonly receiverRelay?: string;
     readonly protocol: Protocols;
+    readonly createdAt: number;
     payload?: Uint8Array;
+    private static headerOffset;
     constructor(sender: Uint8Array | string, receiver: Uint8Array | string, protocol: Protocols, payload?: Uint8Array | Encodable);
     constructor(data: Uint8Array | Datagram);
-    get length(): number;
-    encode(): Uint8Array;
-    toString(): string;
-    toJSON(): string;
-}
-type Attachment = any;
-export interface Message {
-    readonly version: number;
-    text: string;
-    group?: string;
-    attachments?: Attachment[];
-}
-export declare namespace Message {
-    function isMessage(obj: any): boolean;
-    function create(opts?: {
-        text?: string;
-        group?: string;
-        attachments?: Attachment[];
-    }): MessageConstructor;
-    function from(data: Uint8Array | Message): MessageConstructor;
-}
-declare class MessageConstructor implements Encodable, Message {
-    static readonly version = 1;
-    readonly version: number;
-    text: string;
-    group?: string;
-    attachments?: Attachment[];
-    constructor(opts?: {
-        text?: string;
-        group?: string;
-        attachments?: Attachment[];
-    });
-    constructor(data: Uint8Array | Message);
-    get length(): number;
-    setText(str: string): this;
-    setGroup(str: string): this;
-    addAttachment(obj: Attachment): this;
-    delAttachment(obj: Attachment): this | undefined;
-    encode(): Uint8Array;
+    encode(compression?: boolean): Uint8Array;
+    encodeSigned(secretKey: Uint8Array, compression?: boolean): Uint8Array;
     toString(): string;
     toJSON(): string;
 }

package/data.js

@@ -21,17 +21,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Message = exports.Datagram = exports.Protocols = exports.Encodable = void 0;
+exports.Datagram = exports.Protocols = void 0;
 const utils_1 = require("./utils");
 const crypto_1 = __importDefault(require("./crypto"));
-var Encodable;
-(function (Encodable) {
-    const properties = ['length', 'encode', 'toString', 'toJSON'];
-    function isEncodable(obj) {
-        return !properties.some(prop => !obj[prop]);
-    }
-    Encodable.isEncodable = isEncodable;
-})(Encodable || (exports.Encodable = Encodable = {}));
+const fflate_1 = __importDefault(require("fflate"));
 var Protocols;
 (function (Protocols) {
     Protocols["NULL"] = "";
@@ -52,9 +45,10 @@ var Protocols;
     }
     Protocols.toCode = toCode;
     function encode(protocol, length) {
-        const raw = (0, utils_1.numberToUint8Array)(Protocols.toCode(protocol), length).reverse();
+        /*const raw = numberToUint8Array(Protocols.toCode(protocol), length).reverse();
         raw[0] |= (raw.length - 1) << 6;
-        return raw;
+        return raw;*/
+        return (0, utils_1.numberToUint8Array)(Protocols.toCode(protocol), length !== null && length !== void 0 ? length : 4, 'big');
     }
     Protocols.encode = encode;
     function decode(array) {
@@ -84,149 +78,99 @@ class DatagramConstructor {
     constructor(data, receiver, protocol, payload) {
         if (!receiver && !protocol && !payload) {
             if (data instanceof Uint8Array) {
-                const obj = (0, utils_1.encodeUTF8)(data).split(',');
-                this.id = obj[0];
-                this.version = parseInt(obj[1]);
-                this.sender = obj[2];
-                this.receiver = obj[3];
-                this.protocol = Protocols.fromCode(parseInt(obj[4]));
-                this.payload = obj[5] ? (0, utils_1.decodeUTF8)(obj[5]) : undefined;
-                this.createdAt = parseInt(obj[6]);
+                this.version = data[0] & 63;
+                this.protocol = Protocols.decode(data.subarray(1, 4));
+                this.id = crypto_1.default.UUID.stringify(data.subarray(4, 20));
+                this.createdAt = (0, utils_1.numberFromUint8Array)(data.subarray(20, 28));
+                this.senderKey = (0, utils_1.encodeBase64)(data.subarray(28, 28 + crypto_1.default.EdDSA.publicKeyLength));
+                this.receiverKey = (0, utils_1.encodeBase64)(data.subarray(28 + crypto_1.default.EdDSA.publicKeyLength, DatagramConstructor.headerOffset));
+                const senderRelayOffset = data.indexOf(255, DatagramConstructor.headerOffset);
+                const receiverRelayOffset = data.indexOf(255, senderRelayOffset + 1);
+                this.senderRelay = (0, utils_1.encodeUTF8)(data.subarray(DatagramConstructor.headerOffset, senderRelayOffset)) ? "" : undefined;
+                this.receiverRelay = (0, utils_1.encodeUTF8)(data.subarray(senderRelayOffset + 1, receiverRelayOffset)) ? "" : undefined;
+                if (data[0] & 128) {
+                    const signature = data.subarray(data.length - crypto_1.default.EdDSA.signatureLength);
+                    if (!crypto_1.default.EdDSA.verify(data.subarray(0, data.length - crypto_1.default.EdDSA.signatureLength), signature, data.subarray(28, 28 + crypto_1.default.EdDSA.publicKeyLength)))
+                        throw new Error('Invalid signature for Datagram');
+                }
+                if (data[0] & 64)
+                    this.payload = fflate_1.default.inflateSync(data.subarray(receiverRelayOffset + 1, data.length));
+                else
+                    this.payload = data.subarray(receiverRelayOffset + 1, data.length);
             }
-            else {
+            else if (Datagram.isDatagram(data)) {
                 const datagram = data;
                 this.id = datagram.id;
                 this.version = datagram.version;
-                this.sender = datagram.sender;
-                this.receiver = datagram.receiver;
+                this.senderKey = datagram.senderKey;
+                this.receiverKey = datagram.receiverKey;
                 this.protocol = datagram.protocol;
-                this.payload = datagram.payload;
                 this.createdAt = datagram.createdAt;
+                this.senderRelay = datagram.senderRelay;
+                this.receiverRelay = datagram.receiverRelay;
+                this.payload = datagram.payload;
             }
+            else
+                throw new Error('Invalid constructor arguments for Datagram');
         }
         else if (typeof data === 'string' || data instanceof Uint8Array) {
-            this.id = crypto_1.default.generateId().toString();
+            this.id = crypto_1.default.UUID.generate().toString();
             this.version = Datagram.version;
-            this.sender = typeof data === 'string' ? data : (0, utils_1.encodeBase64)(data);
-            this.receiver = typeof receiver === 'string' ? receiver : (0, utils_1.encodeBase64)(receiver);
+            if (typeof data === 'string') {
+                const address = data.split('@');
+                this.senderKey = address[0];
+                this.senderRelay = address[1];
+            }
+            else
+                this.senderKey = (0, utils_1.encodeBase64)(data);
+            if (typeof receiver === 'string') {
+                const address = receiver.split('@');
+                this.receiverKey = address[0];
+                this.receiverRelay = address[1];
+            }
+            else
+                this.receiverKey = (0, utils_1.encodeBase64)(receiver);
             this.protocol = protocol;
-            this.payload = payload instanceof Uint8Array ? payload : payload === null || payload === void 0 ? void 0 : payload.encode();
             this.createdAt = Date.now();
+            this.payload = payload instanceof Uint8Array ? payload : payload === null || payload === void 0 ? void 0 : payload.encode();
         }
         else
             throw new Error('Invalid constructor arguments for Datagram');
     }
-    get length() { return this.encode().length; }
-    encode() {
-        return (0, utils_1.decodeUTF8)([
-            this.id,
-            this.version,
-            this.sender,
-            this.receiver,
-            Protocols.toCode(this.protocol).toString(),
-            this.payload ? this.payload : undefined, this.createdAt
-        ].filter(x => x !== undefined).join(','));
+    encode(compression = true) {
+        var _a;
+        compression = compression && this.payload != undefined && this.payload.length > 1024;
+        return (0, utils_1.concatUint8Array)(new Uint8Array(1).fill(this.version | (compression ? 64 : 0)), //1
+        Protocols.encode(this.protocol, 3), //3
+        (_a = crypto_1.default.UUID.parse(this.id)) !== null && _a !== void 0 ? _a : [], //16
+        (0, utils_1.numberToUint8Array)(this.createdAt, 8), //8
+        (0, utils_1.decodeBase64)(this.senderKey), //32
+        (0, utils_1.decodeBase64)(this.receiverKey), //32
+        ...(this.senderRelay ? [(0, utils_1.decodeUTF8)(this.senderRelay)] : []), new Uint8Array(1).fill(255), ...(this.receiverRelay ? [(0, utils_1.decodeUTF8)(this.receiverRelay)] : []), new Uint8Array(1).fill(255), ...(this.payload ? [compression ? fflate_1.default.deflateSync(this.payload) : this.payload] : []));
+    }
+    encodeSigned(secretKey, compression) {
+        //if (!this.payload) throw new Error('Cannot sign a datagram without payload');
+        const header = this.encode(compression);
+        header[0] |= 128; // Set the sign bit
+        const signature = crypto_1.default.EdDSA.sign(header, secretKey);
+        return (0, utils_1.concatUint8Array)(header, signature);
     }
     toString() {
-        return this.toJSON();
+        return (0, utils_1.encodeBase64)(this.encode());
     }
     toJSON() {
-        return JSON.stringify({
+        /*return JSON.stringify({
             id: this.id,
             version: this.version,
-            sender: this.sender,
-            receiver: this.receiver,
+            senderKey: this.senderKey,
+            senderRelay: this.senderRelay,
+            receiverKey: this.receiverKey,
+            receiverRelay: this.receiverRelay,
             protocol: this.protocol,
-            payload: this.payload ? (0, utils_1.encodeUTF8)(this.payload) : undefined,
-            createdAt: this.createdAt
-        });
-    }
-}
-var Message;
-(function (Message) {
-    function isMessage(obj) {
-        return obj instanceof MessageConstructor || (obj && typeof obj === 'object' && 'version' in obj && 'text' in obj && 'group' in obj && 'attachments' in obj);
-    }
-    Message.isMessage = isMessage;
-    function create(opts) {
-        return new MessageConstructor(opts);
-    }
-    Message.create = create;
-    ;
-    function from(data) {
-        return new MessageConstructor(data);
-    }
-    Message.from = from;
-})(Message || (exports.Message = Message = {}));
-class MessageConstructor {
-    constructor(opts) {
-        var _a;
-        this.version = MessageConstructor.version;
-        this.text = "";
-        if (Message.isMessage(opts)) {
-            const json = opts;
-            this.version = json.version;
-            this.text = json.text;
-            this.group = json.group;
-            this.attachments = json.attachments;
-        }
-        else if (!opts) {
-            this.text = "";
-        }
-        else if (opts instanceof Uint8Array) {
-            const arr = (0, utils_1.encodeUTF8)(opts).split(',');
-            this.version = arr[0];
-            this.text = (_a = arr[1]) !== null && _a !== void 0 ? _a : "";
-            this.group = arr[2];
-            this.attachments = arr[3] ? JSON.parse(arr[3]) : undefined;
-        }
-        else if (typeof opts === 'object') {
-            const { text, group, attachments } = opts;
-            this.text = text || "";
-            this.group = group;
-            this.attachments = attachments || [];
-        }
-        else {
-            throw new Error('Invalid constructor arguments for Message');
-        }
-    }
-    get length() { return this.encode().length; }
-    setText(str) {
-        this.text = str;
-        return this;
-    }
-    setGroup(str) {
-        this.group = str;
-        return this;
-    }
-    addAttachment(obj) {
-        if (this.attachments)
-            this.attachments.push(obj);
-        else
-            this.attachments = [obj];
-        return this;
-    }
-    delAttachment(obj) {
-        var _a;
-        const index = (_a = this.attachments) === null || _a === void 0 ? void 0 : _a.indexOf(obj);
-        if (!index || !this.attachments)
-            return undefined;
-        this.attachments = this.attachments.filter((v, i) => index !== i);
-        return this;
-    }
-    encode() {
-        return (0, utils_1.decodeUTF8)([this.version, this.text, this.group, JSON.stringify(this.attachments || [])].join(','));
-    }
-    toString() {
-        return this.toJSON();
-    }
-    toJSON() {
-        return JSON.stringify({
-            version: MessageConstructor.version,
-            text: this.text,
-            group: this.group,
-            attachments: JSON.stringify(this.attachments)
-        });
+            createdAt: this.createdAt,
+            payload: this.payload ? encodeBase64(this.payload) : undefined
+        });*/
+        return this.toString();
     }
 }
-MessageConstructor.version = 1;
+DatagramConstructor.headerOffset = 28 + crypto_1.default.EdDSA.publicKeyLength * 2;

package/double-ratchet.d.ts

@@ -16,24 +16,23 @@
  * 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;
+import { Encodable } from "./types";
+type ExportedKeySession = {
+    secretKey: string;
+    remoteKey: string;
+    rootKey: string;
+    sendingChain: string;
+    receivingChain: string;
+    sendingCount: number;
+    receivingCount: number;
+    previousCount: number;
+    previousKeys: [number, Uint8Array][];
+};
 /**
  * Represents a secure Double Ratchet session.
  * Used for forward-secure encryption and decryption of messages.
  */
-export declare class Session {
+export declare class KeySession {
     private static readonly skipLimit;
     static readonly version = 1;
     static readonly rootKeyLength: number;
@@ -47,8 +46,9 @@ export declare class Session {
     private receivingCount;
     private previousKeys;
     constructor(opts?: {
+        secretKey?: Uint8Array;
         remoteKey?: Uint8Array;
-        preSharedKey?: Uint8Array;
+        rootKey?: Uint8Array;
     });
     /**
      * Whether both the sending and receiving chains are initialized.
@@ -62,11 +62,8 @@ export declare class Session {
      * The last known remote public key.
      */
     get remoteKey(): Uint8Array | undefined;
-    /**
-     * Set remote public key.
-     */
-    setRemoteKey(key: Uint8Array): this;
-    private dhRatchet;
+    private setRemoteKey;
+    private ratchetKeys;
     private getSendingKey;
     private getReceivingKey;
     /**
@@ -75,25 +72,25 @@ export declare class Session {
      * @param message - The message as a Uint8Array.
      * @returns An EncryptedPayload or undefined if encryption fails.
      */
-    encrypt(message: Uint8Array): EncryptedPayload | undefined;
+    encrypt(message: Uint8Array): EncryptedData;
     /**
      * 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;
+    decrypt(payload: Uint8Array | EncryptedData): Uint8Array | undefined;
     /**
      * Export the state of the session;
      */
-    export(): string;
+    export(): ExportedKeySession;
     /**
      * Import a state.
      *
      * @param json string returned by `export()` method.
      * @returns session with the state parsed.
      */
-    static import(json: string): Session;
+    static import(json: string): KeySession;
     /**
      * The fixed key length (in bytes) used throughout the Double Ratchet session.
      * Typically 32 bytes (256 bits) for symmetric keys.
@@ -105,7 +102,7 @@ export declare class Session {
  * Interface representing an encrypted payload.
  * Provides metadata and de/serialization methods.
  */
-export interface EncryptedPayload extends Encodable {
+export interface EncryptedData extends Encodable {
     /**
      * The length of the payload.
      */
@@ -134,26 +131,12 @@ export interface EncryptedPayload extends Encodable {
      * 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.
+     * Returns the payload as a Base64 string.
      */
     toString(): string;
     /**
@@ -161,12 +144,13 @@ export interface EncryptedPayload extends Encodable {
      */
     toJSON(): string;
 }
-export declare class EncryptedPayload {
+export declare class EncryptedData {
     /**
      * 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;
+    static from(array: Uint8Array | EncryptedData): EncryptedData;
 }
+export {};