feat: implement pluggable ECDH-X25519 encryption and refactor SDK

Author: ABHIRAM-CREATOR06

service/README.md

@@ -90,13 +90,59 @@ Custom encryption protocol allows you to implement your own symmetric encryption
 
 ```javascript
 import { createChatInstance, AesGcmEncryption } from '@chat-e2ee/service';
-
 const chat = createChatInstance({
     baseUrl: 'https://your-api.example.com',
     settings: { disableLog: true },
     encryptionProtocol: new AesGcmEncryption(), // optional custom implementation
 });
 ```
+
+---
+
+## Pluggable Encryption
+
+The SDK supports pluggable symmetric encryption strategies via the `EncryptionFactory`. This allows you to swap the underlying encryption logic used for WebRTC media streams.
+
+### Available Strategies
+
+- **`AES-GCM`** (Default): Standard AES-256-GCM encryption where the key is generated locally and shared via the signaling channel.
+- **`ECDH-X25519`**: Uses Ephemeral X25519 ECDH to derive a shared AES-256-GCM key. The secret key material never leaves the device.
+
+### Switching Strategies
+
+You can specify the encryption strategy when creating a chat instance:
+
+```javascript
+import { createChatInstance, EncryptionFactory } from '@chat-e2ee/service';
+
+// Use the high-security ECDH-X25519 strategy
+const strategy = EncryptionFactory.create({ symmetric: 'ECDH-X25519' });
+
+const chat = createChatInstance({
+    encryptionProtocol: strategy.symmetric
+});
+```
+
+### Registering Custom Strategies
+
+You can register your own implementation by implementing the `ISymmetricEncryption` interface:
+
+```javascript
+import { EncryptionFactory } from '@chat-e2ee/service';
+
+class MySymmetricCipher {
+    async init() { ... }
+    async exportKey() { ... }
+    async importRemoteKey(key) { ... }
+    async encryptData(data) { ... }
+    async decryptData(data, iv) { ... }
+}
+
+EncryptionFactory.registerSymmetric('MY-CIPHER', () => new MySymmetricCipher());
+
+const chat = createChatInstance({
+    encryptionProtocol: EncryptionFactory.create({ symmetric: 'MY-CIPHER' }).symmetric
+});
 ```
 
 ---
@@ -109,8 +155,6 @@ Initializes the instance:
 - Generates ECDH key pairs for WebRTC encryption.
 - Establishes the socket connection.
 - Sets up WebRTC listeners.
-
-#### `await getLink(): Promise<LinkObjType>`
 Requests a new channel link from the server.
 Returns an object containing `hash`, `link`, `absoluteLink`, `pin`, etc.
 

service/src/crypto.test.ts

@@ -76,9 +76,9 @@ describe('AesGcmEncryption (AES-GCM) – real Web Crypto', () => {
     it('init() generates ECDH key pair and is idempotent on subsequent calls', async () => {
         const aes = new AesGcmEncryption();
         await aes.init();
-        const key1Export = await aes.getRawAesKeyToExport();
+        const key1Export = await aes.exportKey();
         await aes.init();
-        const key2Export = await aes.getRawAesKeyToExport();
+        const key2Export = await aes.exportKey();
 
         expect(key1Export).toBeDefined();
         // Second call should return the same cached instance
@@ -92,8 +92,8 @@ describe('AesGcmEncryption (AES-GCM) – real Web Crypto', () => {
         await aes.init();
 
         // Export the local ECDH public key and set it as the "remote" key to derive shared key for loopback test
-        const exportedKey = await aes.getRawAesKeyToExport();
-        await aes.setRemoteAesKey(exportedKey);
+        const exportedKey = await aes.exportKey();
+        await aes.importRemoteKey(exportedKey);
 
         const originalText = 'AES test payload 🔒';
         const originalData = new TextEncoder().encode(originalText).buffer;
@@ -110,18 +110,19 @@ describe('AesGcmEncryption (AES-GCM) – real Web Crypto', () => {
         expect(decryptedText).toBe(originalText);
     });
 
-    it('encryptData() and decryptData() throw when remote key has not been set', async () => {
+    it('encryptData() and decryptData() throw before initialisation/key import', async () => {
         const aes = new AesGcmEncryption();
-        await aes.init();
 
-        // No setRemoteAesKey() call → should throw for encrypt
+        // No init() call → should throw for encrypt
         await expect(aes.encryptData(
             new TextEncoder().encode('data').buffer
-        )).rejects.toThrow('Shared AES key not derived.');
+        )).rejects.toThrow('Local AES key not generated.');
+
+        await aes.init();
 
-        // No setRemoteAesKey() call → should throw for decrypt
+        // No importRemoteKey() call → should throw for decrypt
         await expect(aes.decryptData(new ArrayBuffer(10), new Uint8Array(12))).rejects.toThrow(
-            'Shared AES key not derived.'
+            'Remote AES key not set.'
         );
     });
 });
@@ -134,16 +135,16 @@ describe('ECDH symmetric key exchange', () => {
         // Simulate Bob (receiver)
         const bobAes = new AesGcmEncryption();
         await bobAes.init();
-        const bobEcdhKeyJwk = await bobAes.getRawAesKeyToExport();
+        const bobEcdhKeyJwk = await bobAes.exportKey();
 
         // Simulate Alice (sender)
         const aliceAes = new AesGcmEncryption();
         await aliceAes.init();
-        const aliceEcdhKeyJwk = await aliceAes.getRawAesKeyToExport();
+        const aliceEcdhKeyJwk = await aliceAes.exportKey();
 
         // Exchange keys (in plaintext over the wire)
-        await aliceAes.setRemoteAesKey(bobEcdhKeyJwk);
-        await bobAes.setRemoteAesKey(aliceEcdhKeyJwk);
+        await aliceAes.importRemoteKey(bobEcdhKeyJwk);
+        await bobAes.importRemoteKey(aliceEcdhKeyJwk);
 
         // Alice encrypts some data with her derived AES key
         const originalText = 'Secret message over ECDH derived AES-GCM 🔐';

service/src/cryptoAES.ts

@@ -1,3 +1,7 @@
+/**
+ * Interface for pluggable symmetric encryption strategies.
+ * Implement this to swap in any symmetric cipher (e.g. AES-GCM, ChaCha20-Poly1305).
+ */
 export interface ISymmetricEncryption {
     /** Generate / initialise the local encryption key. Idempotent. */
     init(): Promise<void>;
@@ -12,99 +16,63 @@ export interface ISymmetricEncryption {
 }
 
 /**
- * AES-GCM encryption using ECDH X25519 for key exchange.
- * Both peers derive the same AES-256-GCM key independently — the raw key is never transmitted.
+ * AES-256-GCM implementation of ISymmetricEncryption.
+ * Used for encrypting Audio/Video WebRTC streams.
  */
 export class AesGcmEncryption implements ISymmetricEncryption {
-    private ecdhPrivateKey?: CryptoKey;
-    private ecdhPublicKey?: CryptoKey;
-    private sharedAesKey?: CryptoKey;
+    private aesKeyLocal?: CryptoKey;
+    private aesKeyRemote?: CryptoKey;
 
     public async init(): Promise<void> {
-        if (this.ecdhPrivateKey) {
+        if (this.aesKeyLocal) {
             return;
         }
-        // Generate ECDH key pair
-        const keyPair = await globalThis.crypto.subtle.generateKey(
-            { name: "X25519" },
-            true, // extractable
-            ["deriveKey", "deriveBits"]
-        ) as CryptoKeyPair;
-
-        this.ecdhPrivateKey = keyPair.privateKey;
-        this.ecdhPublicKey = keyPair.publicKey;
-    }
-
-    public getRemoteAesKey(): CryptoKey {
-        if (!this.sharedAesKey) {
-            throw new Error('Shared AES key not derived');
-        }
-        return this.sharedAesKey;
+        this.aesKeyLocal = await window.crypto.subtle.generateKey(
+            { name: "AES-GCM", length: 256 },
+            true,
+            ["encrypt", "decrypt"]
+        );
     }
 
-    public async getRawAesKeyToExport(): Promise<string> {
-        if (!this.ecdhPublicKey) {
-            throw new Error('ECDH keys not generated');
+    public async exportKey(): Promise<string> {
+        if (!this.aesKeyLocal) {
+            throw new Error('AES key not generated');
         }
-        const jsonWebKey = await globalThis.crypto.subtle.exportKey("jwk", this.ecdhPublicKey);
+        const jsonWebKey = await crypto.subtle.exportKey("jwk", this.aesKeyLocal);
         return JSON.stringify(jsonWebKey);
     }
 
-    /** Satisfies ISymmetricEncryption interface — delegates to getRawAesKeyToExport */
-    public exportKey(): Promise<string> {
-        return this.getRawAesKeyToExport();
-    }
-
-    public async setRemoteAesKey(key: string): Promise<void> {
-        if (!this.ecdhPrivateKey) {
-            throw new Error('Local ECDH private key not generated');
-        }
+    public async importRemoteKey(key: string): Promise<void> {
         const jsonWebKey = JSON.parse(key);
-        const remotePublicKey = await globalThis.crypto.subtle.importKey(
+        this.aesKeyRemote = await crypto.subtle.importKey(
             "jwk",
             jsonWebKey,
-            { name: "X25519" },
+            { name: "AES-GCM" },
             true,
-            [] // public keys don't require key usages for derivation
+            ["decrypt"]
         );
-
-        // Derive shared AES-GCM key — never leaves the device
-        this.sharedAesKey = await globalThis.crypto.subtle.deriveKey(
-            { name: "X25519", public: remotePublicKey },
-            this.ecdhPrivateKey,
-            { name: "AES-GCM", length: 256 },
-            false, // AES key is never extractable/transmitted
-            ["encrypt", "decrypt"]
-        );
-    }
-
-    /** Satisfies ISymmetricEncryption interface — delegates to setRemoteAesKey */
-    public importRemoteKey(key: string): Promise<void> {
-        return this.setRemoteAesKey(key);
     }
 
     public async encryptData(data: ArrayBuffer): Promise<{ encryptedData: Uint8Array<ArrayBuffer>; iv: Uint8Array<ArrayBuffer> }> {
-        if (!this.sharedAesKey) {
-            throw new Error('Shared AES key not derived.');
+        if (!this.aesKeyLocal) {
+            throw new Error('Local AES key not generated.');
         }
-        // Generate an Initialization Vector (IV) for AES-GCM (12 bytes)
-        const iv = globalThis.crypto.getRandomValues(new Uint8Array(12));
-        // Encrypt the frame data using AES-GCM
-        const encryptedData = await globalThis.crypto.subtle.encrypt(
+        const iv = crypto.getRandomValues(new Uint8Array(12));
+        const encryptedData = await crypto.subtle.encrypt(
             { name: "AES-GCM", iv },
-            this.sharedAesKey,
+            this.aesKeyLocal,
             data
         );
         return { encryptedData: new Uint8Array(encryptedData), iv };
     }
 
     public async decryptData(data: BufferSource, iv: BufferSource): Promise<ArrayBuffer> {
-        if (!this.sharedAesKey) {
-            throw new Error('Shared AES key not derived.');
+        if (!this.aesKeyRemote) {
+            throw new Error('Remote AES key not set.');
         }
-        return globalThis.crypto.subtle.decrypt(
+        return crypto.subtle.decrypt(
             { name: "AES-GCM", iv },
-            this.sharedAesKey,
+            this.aesKeyRemote,
             data
         );
     }