@freesignal/protocol 0.11.0

package/README.md

@@ -0,0 +1,103 @@
+# FreeSignal Protocol
+
+TypeScript primitives and a small reference implementation of the FreeSignal secure-messaging primitives.
+
+This repository provides low-level building blocks: a lightweight key-exchange manager (X3DH-like), an in-memory keystore for testing, a double-ratchet style session manager, and small constructor helpers intended for building secure messaging clients or protocol tooling.
+
+**Highlights**
+- User factories and a test harness for peer handshakes and message exchange.
+- Pure TypeScript implementation with a pluggable Crypto provider (see `@freesignal/crypto`).
+- In-memory keystore reference implementation for testing: [src/keystore.ts](src/keystore.ts).
+
+## Package
+
+This package is published as `@freesignal/protocol` (see `package.json`). The library exports the primary constructors and helpers from `src/index.ts`:
+
+- `UserFactory` — factory for creating `User` instances
+- `UserConstructor` — low-level user constructor
+- `InMemoryKeystoreFactory`, `InMemoryKeystore` — test keystore helpers
+- `useConstructors` — convenience constructor helpers
+
+## Installation
+
+Install from npm:
+
+```bash
+npm install @freesignal/protocol
+```
+
+This library expects a compatible Crypto provider implementing the FreeSignal crypto interfaces — the test harness uses `@freesignal/crypto`.
+
+## Quick start
+
+The repository includes a small test/example in [src/test.ts](src/test.ts) which demonstrates creating two users, performing a handshake and exchanging messages.
+
+Example (based on `src/test.ts`):
+
+```ts
+import crypto from "@freesignal/crypto";
+import { UserFactory, InMemoryKeystoreFactory } from "@freesignal/protocol";
+
+const userFactory = new UserFactory(new InMemoryKeystoreFactory(), crypto);
+const alice = await userFactory.create();
+const bob = await userFactory.create();
+
+
+// Exchange pre-key bundle and complete handshake
+const bundle = await alice.generatePreKeyBundle();
+const message = await bob.handleIncomingPreKeyBundle(bundle);
+await alice.handleIncomingPreKeyMessage(message);
+
+// Encrypt / decrypt
+const ciphertext = await alice.encrypt(bob.id, "Hello from Alice");
+const plaintext = await bob.decrypt(alice.id, ciphertext);
+console.log(plaintext);
+```
+
+This demonstrates how `UserFactory` composes the keystore, key-exchange manager and session manager to create a usable `User` object with `encrypt`, `decrypt`.
+
+## API Overview
+
+This package primarily exposes two constructors: `UserFactoryConstructor` and `UserConstructor` (re-exported from `src/index.ts`). Documentation below follows the runtime signatures implemented in `src/user.ts`.
+
+- `UserFactoryConstructor` (constructor: `new UserFactoryConstructor(keyStoreFactory: KeyStoreFactory, crypto: Crypto)`)
+  - `create(seed?: Bytes): Promise<User>` — create a `User` with a fresh identity or a deterministic seed. Uses `useConstructors` and the provided `Crypto` implementation to derive an identity and an in-memory `KeyStore` from the provided `KeyStoreFactory`.
+  - `destroy(user: User): boolean` — optional cleanup; returns `true` if the factory removed internal references to the supplied `User` instance.
+
+- `UserConstructor` (new UserConstructor(publicIdentity: PublicIdentity, keyStore: KeyStore, crypto: Crypto))
+  - `publicIdentity: PublicIdentity` — the public identity supplied to the constructor.
+  - `id: UserId` — getter for `publicIdentity.userId`.
+  - `encrypt<T>(to: UserId | string, plaintext: T): Promise<Ciphertext>` — encrypt a payload for a recipient.
+  - `decrypt<T>(ciphertext: Ciphertext | Bytes): Promise<DecryptResult<T>>` — decrypt an incoming ciphertext.
+  - `generatePreKeyBundle(): Promise<PreKeyBundle>` — create a pre-key bundle for publication or delivery to a peer.
+  - `handleIncomingPreKeyBundle(bundle: PreKeyBundle, associatedData?: Bytes): Promise<PreKeyMessage>` — process an incoming bundle and create the resulting session.
+  - `handleIncomingPreKeyMessage(message: PreKeyMessage): Promise<Bytes | undefined>` — process an incoming pre-key message and create the resulting session.
+
+## Build & test
+
+The project compiles to `dist/` using TypeScript. The `package.json` scripts are:
+
+```bash
+# compile (run by `prepare` and `pretest`)
+npm run prepare
+
+# run tests (compiles first via pretest)
+npm test
+```
+
+The test harness is `src/test.ts`; compiled output is `dist/test.js`.
+
+## Contributing
+
+- Keep changes focused and add tests for protocol behavior and edge cases.
+- If you add features, include small examples or update `src/test.ts`.
+
+## License
+
+This project is licensed under `GPL-3.0-or-later`. See the `LICENSE` file in the repository root.
+
+## Notes
+
+- The in-memory keystore is a test/reference implementation only — for production use implement a durable `KeyStore`.
+- The library is agnostic to the Crypto provider as long as it implements the expected `Crypto` FreeSignal interface from `@freesignal/interfaces`, you can use `@freesignal/crypto` as a reference implementation.
+

package/dist/constructors.d.ts

@@ -0,0 +1,148 @@
+/**
+ * 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 type { Bytes, Ciphertext, Identity, PublicIdentity, UserId, Crypto } from "./interfaces.ts";
+type Constructors = ReturnType<typeof defConstructors>;
+declare function defConstructors(crypto: Crypto): {
+    UserIdConstructor: {
+        new (bytes: Bytes): {
+            readonly bytes: Bytes;
+            toString(): string;
+            toUrl(): string;
+            toJSON(): string;
+        };
+        readonly keyLength: 32;
+        fromKey(identityKey: string | Uint8Array | PublicIdentity): UserId;
+        from(userId: string | Uint8Array | UserId): UserId;
+    };
+    PublicIdentityConstructor: {
+        new (publicKey: Bytes): {
+            readonly publicKey: Bytes;
+            readonly userId: UserId;
+            toPublicECDHKey(): Bytes;
+            readonly bytes: Uint8Array;
+            toString(): string;
+            toJSON(): string;
+        };
+        readonly keyLength: number;
+        from(publicIdentity: PublicIdentity | Bytes | string): PublicIdentity;
+    };
+    IdentityConstructor: {
+        new (secretKey: Bytes): {
+            readonly secretKey: Bytes;
+            toSecretECDHKey(): Bytes;
+            readonly publicKey: Bytes;
+            readonly userId: UserId;
+            toPublicECDHKey(): Bytes;
+            readonly bytes: Uint8Array;
+            toString(): string;
+            toJSON(): string;
+        };
+        readonly keyLength: number;
+        from(identity: Identity | Uint8Array | string): Identity;
+    };
+    CiphertextHeaderConstructor: {
+        new (count: number, previous: number, publicKey: Uint8Array, nonce: Uint8Array): {
+            readonly count: number;
+            readonly previous: number;
+            readonly publicKey: Uint8Array;
+            readonly nonce: Uint8Array;
+            readonly bytes: Uint8Array;
+            toJSON(): {
+                count: number;
+                previous: number;
+                publicKey: string;
+            };
+        };
+        readonly keyLength: number;
+        readonly nonceLength: number;
+        readonly countLength: 2;
+        from(data: Uint8Array | {
+            readonly count: number;
+            readonly previous: number;
+            readonly publicKey: Uint8Array;
+            readonly nonce: Uint8Array;
+            readonly bytes: Uint8Array;
+            toJSON(): {
+                count: number;
+                previous: number;
+                publicKey: string;
+            };
+        }): {
+            readonly count: number;
+            readonly previous: number;
+            readonly publicKey: Uint8Array;
+            readonly nonce: Uint8Array;
+            readonly bytes: Uint8Array;
+            toJSON(): {
+                count: number;
+                previous: number;
+                publicKey: string;
+            };
+        };
+    };
+    CiphertextConstructor: {
+        new (opts: {
+            header: Uint8Array;
+            payload: Uint8Array;
+            version?: number;
+        }): {
+            readonly version: number;
+            readonly hashkey: Uint8Array;
+            readonly header: Uint8Array;
+            readonly nonce: Uint8Array;
+            readonly payload: Uint8Array;
+            readonly length: number;
+            readonly bytes: Uint8Array;
+            toJSON(): {
+                version: number;
+                header: string;
+                hashkey: string;
+                nonce: string;
+                payload: string;
+            };
+        };
+        new (opts: {
+            header: Uint8Array;
+            hashkey: Uint8Array;
+            nonce: Uint8Array;
+            payload: Uint8Array;
+            version?: number;
+        }): {
+            readonly version: number;
+            readonly hashkey: Uint8Array;
+            readonly header: Uint8Array;
+            readonly nonce: Uint8Array;
+            readonly payload: Uint8Array;
+            readonly length: number;
+            readonly bytes: Uint8Array;
+            toJSON(): {
+                version: number;
+                header: string;
+                hashkey: string;
+                nonce: string;
+                payload: string;
+            };
+        };
+        readonly version: 1;
+        readonly nonceLength: number;
+        from(data: Bytes | Ciphertext): Ciphertext;
+    };
+};
+export declare function useConstructors(crypto: Crypto): Constructors;
+export {};

package/dist/constructors.js

@@ -0,0 +1,185 @@
+/**
+ * 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/>
+ */
+const cache = new WeakMap();
+function defConstructors(crypto) {
+    class UserIdConstructor {
+        constructor(bytes) {
+            this.bytes = bytes;
+        }
+        ;
+        toString() {
+            return crypto.Utils.decodeBase64(this.bytes);
+        }
+        toUrl() {
+            return crypto.Utils.decodeBase64URL(this.bytes);
+        }
+        toJSON() {
+            return this.toString();
+        }
+        static fromKey(identityKey) {
+            if (typeof identityKey === 'string')
+                identityKey = crypto.Utils.encodeBase64(identityKey);
+            else if (!(identityKey instanceof Uint8Array))
+                identityKey = identityKey.bytes;
+            return new UserIdConstructor(crypto.hkdf(identityKey, new Uint8Array(32).fill(0), "/freesignal/userid", UserIdConstructor.keyLength));
+        }
+        static from(userId) {
+            if (typeof userId === 'string')
+                userId = crypto.Utils.encodeBase64(userId);
+            return new UserIdConstructor(userId instanceof Uint8Array ? userId : userId.bytes);
+        }
+    }
+    UserIdConstructor.keyLength = 32;
+    class PublicIdentityConstructor {
+        constructor(publicKey) {
+            this.publicKey = publicKey;
+        }
+        get userId() {
+            return UserIdConstructor.fromKey(this.publicKey);
+        }
+        toPublicECDHKey() {
+            return crypto.EdDSA.toPublicECDHKey(this.publicKey);
+        }
+        get bytes() {
+            return this.publicKey;
+        }
+        toString() {
+            return crypto.Utils.decodeBase64(this.bytes);
+        }
+        toJSON() {
+            return this.toString();
+        }
+        static from(publicIdentity) {
+            if (publicIdentity instanceof Uint8Array || typeof publicIdentity === 'string') {
+                if (typeof publicIdentity === 'string')
+                    publicIdentity = crypto.Utils.encodeBase64(publicIdentity);
+                if (publicIdentity.length !== PublicIdentityConstructor.keyLength)
+                    throw new Error("Invalid key length");
+            }
+            else {
+                publicIdentity = publicIdentity.publicKey;
+            }
+            return new PublicIdentityConstructor(publicIdentity);
+        }
+    }
+    PublicIdentityConstructor.keyLength = crypto.EdDSA.publicKeyLength;
+    class IdentityConstructor extends PublicIdentityConstructor {
+        constructor(secretKey) {
+            const keyPair = crypto.EdDSA.keyPair(secretKey);
+            super(keyPair.publicKey);
+            this.secretKey = secretKey;
+            this.secretKey = keyPair.secretKey;
+        }
+        toSecretECDHKey() {
+            return crypto.EdDSA.toSecretECDHKey(this.secretKey);
+        }
+        static from(identity) {
+            if (identity instanceof Uint8Array || typeof identity === 'string') {
+                if (typeof identity === 'string')
+                    identity = crypto.Utils.encodeBase64(identity);
+                if (identity.length !== IdentityConstructor.keyLength)
+                    throw new Error("Invalid key length");
+            }
+            else {
+                identity = identity.secretKey;
+            }
+            return new IdentityConstructor(identity);
+        }
+    }
+    IdentityConstructor.keyLength = crypto.EdDSA.secretKeyLength;
+    class CiphertextHeaderConstructor {
+        constructor(count, previous, publicKey, nonce) {
+            this.count = count;
+            this.previous = previous;
+            this.publicKey = publicKey;
+            this.nonce = nonce;
+        }
+        get bytes() {
+            return crypto.Utils.concatBytes(crypto.Utils.numberToBytes(this.count, CiphertextHeaderConstructor.countLength), crypto.Utils.numberToBytes(this.previous, CiphertextHeaderConstructor.countLength), this.publicKey, this.nonce);
+        }
+        toJSON() {
+            return {
+                count: this.count,
+                previous: this.previous,
+                publicKey: crypto.Utils.decodeBase64(this.publicKey)
+            };
+        }
+        static from(data) {
+            if (data instanceof CiphertextHeaderConstructor)
+                data = data.bytes;
+            let offset = 0;
+            return new CiphertextHeaderConstructor(crypto.Utils.bytesToNumber(data.subarray(offset, offset += CiphertextHeaderConstructor.countLength)), crypto.Utils.bytesToNumber(data.subarray(offset, offset += CiphertextHeaderConstructor.countLength)), data.subarray(offset, offset += CiphertextHeaderConstructor.keyLength), data.subarray(offset, offset += CiphertextConstructor.nonceLength));
+        }
+    }
+    CiphertextHeaderConstructor.keyLength = crypto.Box.keyLength;
+    CiphertextHeaderConstructor.nonceLength = crypto.Box.nonceLength;
+    CiphertextHeaderConstructor.countLength = 2;
+    class CiphertextConstructor {
+        constructor({ hashkey, header, nonce, payload, version }) {
+            this.version = version !== null && version !== void 0 ? version : CiphertextConstructor.version;
+            this.header = header;
+            this.hashkey = hashkey;
+            this.nonce = nonce;
+            this.payload = payload;
+        }
+        get length() {
+            return this.bytes.length;
+        }
+        get bytes() {
+            var _a, _b;
+            return crypto.Utils.concatBytes(crypto.Utils.numberToBytes(this.version | (this.hashkey && this.nonce ? 128 : 0), 1), crypto.Utils.numberToBytes(this.header.length, 3), this.header, (_a = this.hashkey) !== null && _a !== void 0 ? _a : new Uint8Array(), (_b = this.nonce) !== null && _b !== void 0 ? _b : new Uint8Array, this.payload);
+        }
+        toJSON() {
+            return {
+                version: this.version,
+                header: crypto.Utils.decodeBase64(this.header),
+                hashkey: crypto.Utils.decodeBase64(this.hashkey),
+                nonce: crypto.Utils.decodeBase64(this.nonce),
+                payload: crypto.Utils.decodeBase64(this.payload)
+            };
+        }
+        static from(data) {
+            if (!(data instanceof Uint8Array))
+                data = data.bytes;
+            const versionByte = crypto.Utils.bytesToNumber(data.subarray(0, 1));
+            const headerLength = crypto.Utils.bytesToNumber(data.subarray(1, 4));
+            let offset = 4;
+            const header = data.subarray(offset, offset += headerLength);
+            let hashkey, nonce;
+            if ((versionByte & 128) > 0) {
+                hashkey = data.subarray(offset, offset += 32);
+                nonce = data.subarray(offset, offset += this.nonceLength);
+            }
+            const payload = data.subarray(offset);
+            const version = versionByte & 127;
+            if (!hashkey || !nonce)
+                var obj = new CiphertextConstructor({ header, payload, version });
+            else
+                var obj = new CiphertextConstructor({ header, hashkey, nonce, payload, version });
+            return obj;
+        }
+    }
+    CiphertextConstructor.version = 1;
+    CiphertextConstructor.nonceLength = crypto.Box.nonceLength;
+    return { UserIdConstructor, PublicIdentityConstructor, IdentityConstructor, CiphertextHeaderConstructor, CiphertextConstructor };
+}
+export function useConstructors(crypto) {
+    var _a;
+    return (_a = cache.get(crypto)) !== null && _a !== void 0 ? _a : defConstructors(crypto);
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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/>
+ */
+export { UserFactoryConstructor as UserFactory, UserConstructor } from "./user.js";
+export { InMemoryKeystoreFactory, InMemoryKeystore } from "./keystore.js";
+export { useConstructors } from "./constructors.js";

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * 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/>
+ */
+export { UserFactoryConstructor as UserFactory, UserConstructor } from "./user.js";
+export { InMemoryKeystoreFactory, InMemoryKeystore } from "./keystore.js";
+export { useConstructors } from "./constructors.js";