@freesignal/protocol 0.1.8 → 0.2.0

package/types.d.ts

@@ -16,19 +16,30 @@
  * 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 {
+import { Encodable } from "@freesignal/interfaces";
+export type UserId = string;
+export interface IdentityKeys {
+    readonly publicKey: string;
+    readonly identityKey: string;
+}
+export declare namespace IdentityKeys {
+    const keyLength: number;
+    function isIdentityKeys(obj: any): boolean;
+    function from(identityKeys: IdentityKeys): IdentityKeysConstructor;
+}
+declare class IdentityKeysConstructor implements IdentityKeys, Encodable {
+    readonly publicKey: string;
+    readonly identityKey: string;
+    constructor(identityKeys: IdentityKeys | Uint8Array | string);
     encode(): Uint8Array;
     toString(): string;
     toJSON(): string;
 }
-export declare namespace Encodable {
-    function isEncodable(obj: any): boolean;
-}
 export declare enum Protocols {
     NULL = "",
     MESSAGE = "/freesignal/message/1.0.0",
-    RELAY = "/freesignal/relay/1.0.0"
+    RELAY = "/freesignal/relay/1.0.0",
+    HANDSHAKE = "/freesignal/handshake/1.0.0"
 }
 export declare namespace Protocols {
     function isProtocol(protocol: any): boolean;
@@ -37,92 +48,119 @@ export declare namespace Protocols {
     function encode(protocol: Protocols, length?: number): Uint8Array;
     function decode(array: Uint8Array): Protocols;
 }
-type LocalStorageIterator<T> = Iterable<T>;
-export interface LocalStorage<K, T> {
-    set(key: K, value: T): Promise<this>;
-    get(key: K): Promise<T | undefined>;
-    has(key: K): Promise<boolean>;
-    delete(key: K): Promise<boolean>;
-    entries(): Promise<LocalStorageIterator<[K, T]>>;
-}
-export interface KeyExchangeData {
+export interface Datagram {
+    readonly id: string;
     readonly version: number;
-    readonly publicKey: string;
-    readonly identityKey: string;
-    readonly signedPreKey: string;
-    readonly signature: string;
-    readonly onetimePreKey: string;
+    readonly sender: string;
+    readonly receiver: string;
+    readonly protocol: Protocols;
+    readonly createdAt: number;
+    payload?: Uint8Array;
 }
-export interface KeyExchangeSynMessage {
-    readonly version: number;
-    readonly publicKey: string;
-    readonly identityKey: string;
-    readonly ephemeralKey: string;
-    readonly signedPreKeyHash: string;
-    readonly onetimePreKeyHash: string;
-    readonly associatedData: string;
+export declare namespace Datagram {
+    const version = 1;
+    function create(sender: Uint8Array | string, receiver: Uint8Array | string, protocol: Protocols, payload?: Uint8Array | Encodable): DatagramConstructor;
+    function isDatagram(obj: any): boolean;
+    function from(data: Uint8Array | Datagram | string): DatagramConstructor;
 }
-export interface KeyExchangeDataBundle {
+declare class DatagramConstructor implements Encodable, Datagram {
+    readonly id: string;
     readonly version: number;
-    readonly publicKey: string;
-    readonly identityKey: string;
-    readonly signedPreKey: string;
-    readonly signature: string;
-    readonly onetimePreKey: string[];
+    readonly sender: string;
+    readonly receiver: 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);
+    encode(compression?: boolean): Uint8Array;
+    encodeSigned(secretKey: Uint8Array, compression?: boolean): Uint8Array;
+    toString(): string;
+    toJSON(): string;
 }
-interface UUIDv4 {
+/**
+ * Interface representing an encrypted payload.
+ * Provides metadata and de/serialization methods.
+ */
+export interface EncryptedData 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;
+    /**
+     * Serializes the payload into a Uint8Array for transport.
+     */
+    encode(): Uint8Array;
+    /**
+     * Returns the payload as a Base64 string.
+     */
     toString(): string;
+    /**
+     * Returns the decoded object as a JSON string.
+     */
     toJSON(): string;
-    toBuffer(): Uint8Array;
 }
-export interface Crypto {
-    hash(message: Uint8Array, algorithm?: Crypto.HashAlgorithms): Uint8Array;
-    hmac(key: Uint8Array, message: Uint8Array, length?: number, algorithm?: Crypto.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;
+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 | EncryptedData): EncryptedData;
 }
-export declare namespace Crypto {
-    type HashAlgorithms = 'sha224' | 'sha256' | 'sha384' | 'sha512';
-    type HmacAlgorithms = 'kmac128' | 'kmac256';
-    type KeyPair = {
-        readonly publicKey: Uint8Array;
-        readonly secretKey: Uint8Array;
+export declare class EncryptedDataConstructor implements EncryptedData {
+    static readonly secretKeyLength: number;
+    static readonly publicKeyLength: number;
+    static readonly keyLength: number;
+    static readonly nonceLength: number;
+    static readonly maxCount = 65536;
+    static readonly countLength = 2;
+    private raw;
+    constructor(count: number | Uint8Array, previous: number | Uint8Array, publicKey: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, version?: number | Uint8Array);
+    constructor(encrypted: Uint8Array | EncryptedData);
+    get length(): number;
+    get version(): number;
+    get count(): number;
+    get previous(): number;
+    get publicKey(): Uint8Array;
+    get nonce(): Uint8Array;
+    get ciphertext(): Uint8Array;
+    encode(): Uint8Array;
+    decode(): {
+        version: number;
+        count: number;
+        previous: number;
+        publicKey: string;
+        nonce: string;
+        ciphertext: string;
     };
-    namespace KeyPair {
-        function isKeyPair(obj: any): boolean;
-    }
-    interface box {
-        readonly keyLength: number;
-        readonly nonceLength: number;
-        encrypt(msg: Uint8Array, nonce: Uint8Array, key: Uint8Array): Uint8Array;
-        decrypt(msg: Uint8Array, nonce: Uint8Array, key: Uint8Array): Uint8Array | undefined;
-    }
-    interface ECDH {
-        readonly publicKeyLength: number;
-        readonly secretKeyLength: number;
-        keyPair(secretKey?: Uint8Array): KeyPair;
-        sharedKey(publicKey: Uint8Array, secretKey: Uint8Array): Uint8Array;
-        scalarMult(n: Uint8Array, p: Uint8Array): Uint8Array;
-    }
-    interface EdDSA {
-        readonly publicKeyLength: number;
-        readonly secretKeyLength: number;
-        readonly signatureLength: number;
-        readonly seedLength: number;
-        keyPair(secretKey?: Uint8Array): KeyPair;
-        keyPairFromSeed(seed: Uint8Array): KeyPair;
-        sign(msg: Uint8Array, secretKey: Uint8Array): Uint8Array;
-        verify(msg: Uint8Array, sig: Uint8Array, publicKey: Uint8Array): boolean;
-    }
-    interface UUID {
-        generate(): UUIDv4;
-        stringify(arr: Uint8Array, offset?: number): string;
-        parse(uuid: string): Uint8Array;
-    }
+    toString(): string;
+    toJSON(): string;
 }
 export {};

package/types.js

@@ -17,22 +17,56 @@
  * 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.Crypto = exports.Protocols = exports.Encodable = void 0;
-const utils_1 = require("./utils");
-var Encodable;
-(function (Encodable) {
-    const properties = ['encode', 'toString', 'toJSON'];
-    function isEncodable(obj) {
-        return !properties.some(prop => !obj[prop]);
-    }
-    Encodable.isEncodable = isEncodable;
-})(Encodable || (exports.Encodable = Encodable = {}));
+exports.EncryptedDataConstructor = exports.EncryptedData = exports.Datagram = exports.Protocols = exports.IdentityKeys = void 0;
+const utils_1 = require("@freesignal/utils");
+const crypto_1 = __importDefault(require("@freesignal/crypto"));
+const fflate_1 = __importDefault(require("fflate"));
+const double_ratchet_1 = require("./double-ratchet");
+var IdentityKeys;
+(function (IdentityKeys) {
+    IdentityKeys.keyLength = crypto_1.default.ECDH.publicKeyLength;
+    function isIdentityKeys(obj) {
+        return (typeof obj === 'object' && obj.publicKey && obj.identityKey);
+    }
+    IdentityKeys.isIdentityKeys = isIdentityKeys;
+    function from(identityKeys) {
+        return new IdentityKeysConstructor(identityKeys);
+    }
+    IdentityKeys.from = from;
+})(IdentityKeys || (exports.IdentityKeys = IdentityKeys = {}));
+class IdentityKeysConstructor {
+    constructor(identityKeys) {
+        if (typeof identityKeys === 'string')
+            identityKeys = (0, utils_1.decodeBase64)(identityKeys);
+        if (identityKeys instanceof Uint8Array) {
+            this.publicKey = (0, utils_1.encodeBase64)(identityKeys.subarray(0, IdentityKeys.keyLength));
+            this.identityKey = (0, utils_1.encodeBase64)(identityKeys.subarray(IdentityKeys.keyLength));
+        }
+        else {
+            this.publicKey = identityKeys.publicKey;
+            this.identityKey = identityKeys.identityKey;
+        }
+    }
+    encode() {
+        return (0, utils_1.concatUint8Array)((0, utils_1.decodeBase64)(this.publicKey), (0, utils_1.decodeBase64)(this.identityKey));
+    }
+    toString() {
+        throw (0, utils_1.encodeBase64)(this.encode());
+    }
+    toJSON() {
+        throw this.toString();
+    }
+}
 var Protocols;
 (function (Protocols) {
     Protocols["NULL"] = "";
     Protocols["MESSAGE"] = "/freesignal/message/1.0.0";
     Protocols["RELAY"] = "/freesignal/relay/1.0.0";
+    Protocols["HANDSHAKE"] = "/freesignal/handshake/1.0.0";
 })(Protocols || (exports.Protocols = Protocols = {}));
 (function (Protocols) {
     function isProtocol(protocol) {
@@ -61,6 +95,195 @@ var Protocols;
     }
     Protocols.decode = decode;
 })(Protocols || (exports.Protocols = Protocols = {}));
-var Crypto;
-(function (Crypto) {
-})(Crypto || (exports.Crypto = Crypto = {}));
+var Datagram;
+(function (Datagram) {
+    Datagram.version = 1;
+    function create(sender, receiver, protocol, payload) {
+        return new DatagramConstructor(sender, receiver, protocol, payload);
+    }
+    Datagram.create = create;
+    function isDatagram(obj) {
+        return obj instanceof DatagramConstructor || (obj && typeof obj === 'object' && 'id' in obj && 'version' in obj && 'sender' in obj && 'receiver' in obj && 'protocol' in obj && 'createdAt' in obj);
+    }
+    Datagram.isDatagram = isDatagram;
+    function from(data) {
+        if (typeof data === 'string') {
+            const decoded = (0, utils_1.decodeBase64)(data);
+            return new DatagramConstructor(decoded);
+        }
+        else
+            return new DatagramConstructor(data);
+    }
+    Datagram.from = from;
+})(Datagram || (exports.Datagram = Datagram = {}));
+class DatagramConstructor {
+    constructor(data, receiver, protocol, payload) {
+        if (!receiver && !protocol && !payload) {
+            if (data instanceof Uint8Array) {
+                this.version = data[0] & 63;
+                this.protocol = Protocols.decode(data.subarray(1, 2));
+                this.id = crypto_1.default.UUID.stringify(data.subarray(2, 18));
+                this.createdAt = (0, utils_1.numberFromUint8Array)(data.subarray(18, 26));
+                this.sender = (0, utils_1.encodeBase64)(data.subarray(26, 26 + crypto_1.default.EdDSA.publicKeyLength));
+                this.receiver = (0, utils_1.encodeBase64)(data.subarray(26 + crypto_1.default.EdDSA.publicKeyLength, DatagramConstructor.headerOffset));
+                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(26, 26 + crypto_1.default.EdDSA.publicKeyLength)))
+                        throw new Error('Invalid signature for Datagram');
+                }
+                if (data[0] & 64)
+                    this.payload = fflate_1.default.inflateSync(data.subarray(DatagramConstructor.headerOffset, data.length));
+                else
+                    this.payload = data.subarray(DatagramConstructor.headerOffset, data.length);
+            }
+            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.protocol = datagram.protocol;
+                this.createdAt = datagram.createdAt;
+                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.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);
+            this.protocol = protocol;
+            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');
+    }
+    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), //1
+        (_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.sender), //32
+        (0, utils_1.decodeBase64)(this.receiver), //32
+        ...(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 (0, utils_1.encodeBase64)(this.encode());
+    }
+    toJSON() {
+        /*return JSON.stringify({
+            id: this.id,
+            version: this.version,
+            senderKey: this.senderKey,
+            senderRelay: this.senderRelay,
+            receiverKey: this.receiverKey,
+            receiverRelay: this.receiverRelay,
+            protocol: this.protocol,
+            createdAt: this.createdAt,
+            payload: this.payload ? encodeBase64(this.payload) : undefined
+        });*/
+        return this.toString();
+    }
+}
+DatagramConstructor.headerOffset = 26 + crypto_1.default.EdDSA.publicKeyLength * 2;
+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) {
+        return new EncryptedDataConstructor(array);
+    }
+}
+exports.EncryptedData = EncryptedData;
+class EncryptedDataConstructor {
+    constructor(...arrays) {
+        arrays = arrays.filter(value => value !== undefined);
+        if (arrays[0] instanceof EncryptedDataConstructor) {
+            this.raw = arrays[0].raw;
+            return this;
+        }
+        if (typeof arrays[0] === 'number')
+            arrays[0] = (0, utils_1.numberToUint8Array)(arrays[0], EncryptedDataConstructor.countLength);
+        if (typeof arrays[1] === 'number')
+            arrays[1] = (0, utils_1.numberToUint8Array)(arrays[1], EncryptedDataConstructor.countLength);
+        if (arrays.length === 6) {
+            arrays.unshift(typeof arrays[5] === 'number' ? (0, utils_1.numberToUint8Array)(arrays[5]) : arrays[5]);
+            arrays.pop();
+        }
+        else if (arrays.length > 1) {
+            arrays.unshift((0, utils_1.numberToUint8Array)(double_ratchet_1.KeySession.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); }
+    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.encodeBase64)(this.ciphertext)
+        };
+    }
+    toString() {
+        return (0, utils_1.encodeBase64)(this.raw);
+    }
+    toJSON() {
+        return JSON.stringify(this.decode());
+    }
+}
+exports.EncryptedDataConstructor = EncryptedDataConstructor;
+EncryptedDataConstructor.secretKeyLength = crypto_1.default.ECDH.secretKeyLength;
+EncryptedDataConstructor.publicKeyLength = crypto_1.default.ECDH.publicKeyLength;
+EncryptedDataConstructor.keyLength = crypto_1.default.box.keyLength;
+EncryptedDataConstructor.nonceLength = crypto_1.default.box.nonceLength;
+EncryptedDataConstructor.maxCount = 65536; //32768;
+EncryptedDataConstructor.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, EncryptedDataConstructor.countLength);
+Offsets.previous = Offsets.set(Offsets.count.end, EncryptedDataConstructor.countLength);
+Offsets.publicKey = Offsets.set(Offsets.previous.end, EncryptedDataConstructor.publicKeyLength);
+Offsets.nonce = Offsets.set(Offsets.publicKey.end, EncryptedDataConstructor.nonceLength);
+Offsets.ciphertext = Offsets.set(Offsets.nonce.end, undefined);

package/x3dh.d.ts

@@ -16,7 +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/>
  */
-import { KeyExchangeData, KeyExchangeDataBundle, KeyExchangeSynMessage, LocalStorage, Crypto } from "./types";
+import { KeyExchangeData, KeyExchangeDataBundle, KeyExchangeSynMessage, LocalStorage, Crypto } from "@freesignal/interfaces";
 import { KeySession } from "./double-ratchet";
 export declare class KeyExchange {
     static readonly version = 1;

package/x3dh.js

@@ -31,9 +31,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KeyExchange = void 0;
-const crypto_1 = __importDefault(require("./crypto"));
+const crypto_1 = __importDefault(require("@freesignal/crypto"));
 const double_ratchet_1 = require("./double-ratchet");
-const utils_1 = require("./utils");
+const utils_1 = require("@freesignal/utils");
 class KeyExchange {
     constructor(signSecretKey, boxSecretKey, bundleStore) {
         this._signatureKey = crypto_1.default.EdDSA.keyPair(signSecretKey);

package/crypto.d.ts

@@ -1,24 +0,0 @@
-/**
- * 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 './types';
-declare const crypto: Crypto;
-declare namespace crypto {
-    type KeyPair = Crypto.KeyPair;
-}
-export default crypto;