refactor(service): make encryption layer pluggable via strategy pattern

- Add ISymmetricEncryption and IAsymmetricEncryption interfaces
- Rename AesGcmEncryption methods to algorithm-agnostic names
  (int→init, getRawAesKeyToExport→exportKey, setRemoteAesKey→importRemoteKey)
- Add EncryptionStrategyFactory with a named registry; pre-registered
  with AES-GCM and RSA-OAEP as built-in defaults
- Inject strategies into ChatE2EE via createChatInstance second arg;
  sdk.ts uses EncryptionFactory.create() for its own defaults
- webrtc.ts accepts ISymmetricEncryption instead of concrete class
- Export EncryptionFactory, EncryptionStrategyConfig, and both
  interfaces from the public API surface
- Add integration tests: custom strategy call tracking, full
  SDK handshake protocol end-to-end via factory-created strategies
- Update README with factory API, interface contracts, and examples

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: muke1908

service/README.md

@@ -83,14 +83,123 @@ setConfig({
 });
 ```
 
-### `createChatInstance(config?: Partial<ConfigType>): IChatE2EE`
-Factory function to create a new chat session instance. Accepts an optional config to set `baseUrl` and `settings` inline, as an alternative to calling `setConfig()` separately.
+### `createChatInstance(config?, encryptionStrategy?): IChatE2EE`
+Factory function to create a new chat session instance.
 
-```javascript
-const chat = createChatInstance({
-    baseUrl: 'https://your-api.example.com',
-    settings: { disableLog: true },
-});
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `config` | `Partial<ConfigType>` | Optional. Sets `baseUrl` and `settings` inline. |
+| `encryptionStrategy` | `EncryptionStrategy` | Optional. Plug in custom symmetric / asymmetric ciphers. Use `EncryptionFactory.create()` to produce this value (see [Pluggable Encryption](#pluggable-encryption)). |
+
+```typescript
+import { createChatInstance, EncryptionFactory } from '@chat-e2ee/service';
+
+// Default — AES-256-GCM + RSA-OAEP
+const chat = createChatInstance({ baseUrl: 'https://your-api.example.com' });
+
+// Explicit strategy via factory
+const chat = createChatInstance(config, EncryptionFactory.create({ symmetric: 'AES-GCM' }));
+```
+
+---
+
+## Pluggable Encryption
+
+The SDK ships with two built-in ciphers:
+
+| Layer | Default | Purpose |
+| :--- | :--- | :--- |
+| Asymmetric | `RSA-OAEP` (2048-bit, SHA-256) | Key-pair generation, message encryption, symmetric key wrapping |
+| Symmetric | `AES-GCM` (256-bit) | Frame-by-frame WebRTC audio/video encryption |
+
+Both are swappable at construction time via `EncryptionFactory`.
+
+### EncryptionFactory
+
+`EncryptionFactory` is a registry-based singleton. Register a cipher once under a name, then reference it by that name anywhere.
+
+#### Built-in strategies
+
+| Name | Type |
+| :--- | :--- |
+| `'AES-GCM'` | symmetric |
+| `'RSA-OAEP'` | asymmetric |
+
+#### `EncryptionFactory.create(config?)`
+
+Returns an `EncryptionStrategy` ready to pass to `createChatInstance`. Omit either field to keep its built-in default.
+
+```typescript
+// Both defaults
+EncryptionFactory.create()
+
+// Override one layer, keep the other default
+EncryptionFactory.create({ symmetric: 'ChaCha20' })
+EncryptionFactory.create({ asymmetric: 'X25519' })
+
+// Override both
+EncryptionFactory.create({ symmetric: 'ChaCha20', asymmetric: 'X25519' })
+```
+
+Requesting an unregistered name throws immediately:
+> `Unknown symmetric strategy: "ChaCha20". Register it first with EncryptionFactory.registerSymmetric().`
+
+#### `EncryptionFactory.registerSymmetric(name, factory)`
+#### `EncryptionFactory.registerAsymmetric(name, factory)`
+
+Register a custom implementation under a name. Both methods return `this` for chaining.
+
+```typescript
+EncryptionFactory
+    .registerSymmetric('ChaCha20', () => new ChaCha20Encryption())
+    .registerAsymmetric('X25519',  () => new X25519Exchange());
+```
+
+### Implementing a custom strategy
+
+#### `ISymmetricEncryption`
+
+```typescript
+import type { ISymmetricEncryption } from '@chat-e2ee/service';
+
+class ChaCha20Encryption implements ISymmetricEncryption {
+    async init(): Promise<void> { /* generate local key */ }
+    async encryptData(data: ArrayBuffer): Promise<{ encryptedData: Uint8Array<ArrayBuffer>; iv: Uint8Array<ArrayBuffer> }> { /* … */ }
+    async decryptData(data: BufferSource, iv: BufferSource): Promise<ArrayBuffer> { /* … */ }
+    async exportKey(): Promise<string> { /* serialise local key for transmission */ }
+    async importRemoteKey(key: string): Promise<void> { /* import peer's key */ }
+}
+```
+
+#### `IAsymmetricEncryption`
+
+```typescript
+import type { IAsymmetricEncryption } from '@chat-e2ee/service';
+
+class X25519Exchange implements IAsymmetricEncryption {
+    async generateKeypairs(): Promise<{ privateKey: string; publicKey: string }> { /* … */ }
+    async encryptMessage(plaintext: string, publicKey: string): Promise<string> { /* … */ }
+    async decryptMessage(ciphertext: string, privateKey: string): Promise<string> { /* … */ }
+}
+```
+
+#### Full example
+
+```typescript
+import { createChatInstance, EncryptionFactory } from '@chat-e2ee/service';
+
+// 1. Register at app startup
+EncryptionFactory
+    .registerSymmetric('ChaCha20', () => new ChaCha20Encryption())
+    .registerAsymmetric('X25519',  () => new X25519Exchange());
+
+// 2. Use by name
+const chat = createChatInstance(config, EncryptionFactory.create({
+    symmetric:  'ChaCha20',
+    asymmetric: 'X25519',
+}));
+
+await chat.init();
 ```
 
 ---

service/src/crypto.test.ts

@@ -73,27 +73,28 @@ describe('cryptoUtils (RSA-OAEP) – real Web Crypto', () => {
 // AES-GCM round-trip tests
 // ---------------------------------------------------------------------------
 describe('AesGcmEncryption (AES-GCM) – real Web Crypto', () => {
-    it('int() generates a CryptoKey and returns it on subsequent calls', async () => {
+    it('init() generates the key and is idempotent on subsequent calls', async () => {
         const aes = new AesGcmEncryption();
-        const key1 = await aes.int();
-        const key2 = await aes.int();
+        await aes.init();
+        await aes.init(); // Should not throw or regenerate
 
-        expect(key1).toBeDefined();
-        // Second call should return the same cached instance
-        expect(key1).toBe(key2);
+        // Verify the key exists and is exportable
+        const exported = await aes.exportKey();
+        expect(typeof exported).toBe('string');
+        expect(exported.length).toBeGreaterThan(0);
     });
 
     it('encryptData() + decryptData() recover the original data', async () => {
         const aes = new AesGcmEncryption();
 
         // Initialise the local key (used for encryption)
-        await aes.int();
+        await aes.init();
 
         // Export the local key and re-import it as the "remote" key so that
         // decryptData() (which uses aesKeyRemote) can decrypt what encryptData()
         // produced.
-        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;
@@ -112,13 +113,13 @@ describe('AesGcmEncryption (AES-GCM) – real Web Crypto', () => {
 
     it('decryptData() throws when remote key has not been set', async () => {
         const aes = new AesGcmEncryption();
-        await aes.int();
+        await aes.init();
 
         const { encryptedData, iv } = await aes.encryptData(
             new TextEncoder().encode('data').buffer
         );
 
-        // No setRemoteAesKey() call → should throw
+        // No importRemoteKey() call → should throw
         await expect(aes.decryptData(encryptedData, iv)).rejects.toThrow(
             'Remote AES key not set.'
         );
@@ -135,10 +136,10 @@ describe('AES key exchange via RSA-encrypted channel', () => {
 
         // Simulate Alice (sender): generate an AES key
         const aliceAes = new AesGcmEncryption();
-        await aliceAes.int();
+        await aliceAes.init();
 
-        // Alice exports her AES key as a JWK string (this is what getRawAesKeyToExport returns)
-        const aesKeyJwk = await aliceAes.getRawAesKeyToExport();
+        // Alice exports her AES key as a JWK string
+        const aesKeyJwk = await aliceAes.exportKey();
 
         // Alice encrypts the AES key with Bob's RSA public key before sending it to the server
         const encryptedAesKey = await cryptoUtils.encryptMessage(aesKeyJwk, bobPublicKey);
@@ -151,7 +152,7 @@ describe('AES key exchange via RSA-encrypted channel', () => {
 
         // Bob sets the decrypted AES key as his remote key
         const bobAes = new AesGcmEncryption();
-        await bobAes.setRemoteAesKey(decryptedAesKeyJwk);
+        await bobAes.importRemoteKey(decryptedAesKeyJwk);
 
         // Alice encrypts some data with her local AES key
         const originalText = 'Secret message over AES-GCM 🔐';
@@ -171,8 +172,8 @@ describe('AES key exchange via RSA-encrypted channel', () => {
         const { privateKey: evePrivateKey } = await cryptoUtils.generateKeypairs(); // attacker's key
 
         const aliceAes = new AesGcmEncryption();
-        await aliceAes.int();
-        const aesKeyJwk = await aliceAes.getRawAesKeyToExport();
+        await aliceAes.init();
+        const aesKeyJwk = await aliceAes.exportKey();
 
         // Alice encrypts AES key with Bob's public key
         const encryptedAesKey = await cryptoUtils.encryptMessage(aesKeyJwk, bobPublicKey);
@@ -183,3 +184,157 @@ describe('AES key exchange via RSA-encrypted channel', () => {
         ).rejects.toThrow();
     });
 });
+
+// ---------------------------------------------------------------------------
+// EncryptionFactory
+// ---------------------------------------------------------------------------
+describe('EncryptionFactory', () => {
+    // Import inside the describe so the window polyfill above is already set up
+    const { EncryptionFactory } = require('./encryptionFactory');
+    const { AesGcmEncryption } = require('./cryptoAES');
+
+    it('create() with no args returns an object with symmetric and asymmetric strategies', () => {
+        const strategy = EncryptionFactory.create();
+        expect(strategy.symmetric).toBeDefined();
+        expect(strategy.asymmetric).toBeDefined();
+    });
+
+    it('create() returns a fresh symmetric instance on each call (stateful key material)', () => {
+        const a = EncryptionFactory.create();
+        const b = EncryptionFactory.create();
+        // Symmetric strategy holds key state — must be a distinct instance each time
+        expect(a.symmetric).not.toBe(b.symmetric);
+    });
+
+    it('create({ symmetric: "AES-GCM" }) returns an AesGcmEncryption instance', () => {
+        const { symmetric } = EncryptionFactory.create({ symmetric: 'AES-GCM' });
+        expect(symmetric).toBeInstanceOf(AesGcmEncryption);
+    });
+
+    it('create() with an unknown symmetric name throws a descriptive error', () => {
+        expect(() => EncryptionFactory.create({ symmetric: 'UNKNOWN' })).toThrow(
+            'Unknown symmetric strategy: "UNKNOWN"'
+        );
+    });
+
+    it('create() with an unknown asymmetric name throws a descriptive error', () => {
+        expect(() => EncryptionFactory.create({ asymmetric: 'UNKNOWN' })).toThrow(
+            'Unknown asymmetric strategy: "UNKNOWN"'
+        );
+    });
+
+    it('registerSymmetric() makes a custom strategy available by name', async () => {
+        const mockSymmetric = new AesGcmEncryption();
+        EncryptionFactory.registerSymmetric('MOCK-SYM', () => mockSymmetric);
+
+        const { symmetric } = EncryptionFactory.create({ symmetric: 'MOCK-SYM' });
+        expect(symmetric).toBe(mockSymmetric);
+    });
+
+    it('registerAsymmetric() makes a custom strategy available by name', () => {
+        const mockAsymmetric = { generateKeypairs: jest.fn(), encryptMessage: jest.fn(), decryptMessage: jest.fn() };
+        EncryptionFactory.registerAsymmetric('MOCK-ASM', () => mockAsymmetric);
+
+        const { asymmetric } = EncryptionFactory.create({ asymmetric: 'MOCK-ASM' });
+        expect(asymmetric).toBe(mockAsymmetric);
+    });
+
+    it('registerSymmetric() supports chaining', () => {
+        const result = EncryptionFactory.registerSymmetric('CHAIN-TEST', () => new AesGcmEncryption());
+        expect(result).toBe(EncryptionFactory);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Pluggable encryption – integration
+// ---------------------------------------------------------------------------
+describe('Pluggable encryption (integration)', () => {
+    const { EncryptionFactory } = require('./encryptionFactory');
+    const { AesGcmEncryption } = require('./cryptoAES');
+    const { cryptoUtils } = require('./cryptoRSA');
+
+    /**
+     * Thin tracking wrapper: delegates every call to a real AesGcmEncryption
+     * while recording which methods were invoked.
+     */
+    class TrackingSymmetric {
+        readonly calls: string[] = [];
+        private inner = new AesGcmEncryption();
+
+        async init()                                      { this.calls.push('init');            return this.inner.init(); }
+        async encryptData(data: ArrayBuffer)              { this.calls.push('encryptData');      return this.inner.encryptData(data); }
+        async decryptData(data: BufferSource, iv: BufferSource) { this.calls.push('decryptData'); return this.inner.decryptData(data, iv); }
+        async exportKey()                                 { this.calls.push('exportKey');        return this.inner.exportKey(); }
+        async importRemoteKey(key: string)                { this.calls.push('importRemoteKey');  return this.inner.importRemoteKey(key); }
+    }
+
+    it('custom symmetric strategy is called through the factory', async () => {
+        const impl = new TrackingSymmetric();
+        EncryptionFactory.registerSymmetric('TRACKING-SYM', () => impl);
+
+        const { symmetric } = EncryptionFactory.create({ symmetric: 'TRACKING-SYM' });
+
+        await symmetric.init();
+        const key = await symmetric.exportKey();
+        await symmetric.importRemoteKey(key);
+        const { encryptedData, iv } = await symmetric.encryptData(new TextEncoder().encode('test').buffer);
+        await symmetric.decryptData(encryptedData, iv);
+
+        expect(impl.calls).toEqual(['init', 'exportKey', 'importRemoteKey', 'encryptData', 'decryptData']);
+    });
+
+    it('custom asymmetric strategy is called through the factory', async () => {
+        const calls: string[] = [];
+        const impl = {
+            generateKeypairs: async () => { calls.push('generateKeypairs'); return cryptoUtils.generateKeypairs(); },
+            encryptMessage:   async (p: string, k: string) => { calls.push('encryptMessage');   return cryptoUtils.encryptMessage(p, k); },
+            decryptMessage:   async (c: string, k: string) => { calls.push('decryptMessage');   return cryptoUtils.decryptMessage(c, k); },
+        };
+        EncryptionFactory.registerAsymmetric('TRACKING-ASM', () => impl);
+
+        const { asymmetric } = EncryptionFactory.create({ asymmetric: 'TRACKING-ASM' });
+
+        const { publicKey, privateKey } = await asymmetric.generateKeypairs();
+        const ciphertext = await asymmetric.encryptMessage('hello', publicKey);
+        const recovered  = await asymmetric.decryptMessage(ciphertext, privateKey);
+
+        expect(recovered).toBe('hello');
+        expect(calls).toEqual(['generateKeypairs', 'encryptMessage', 'decryptMessage']);
+    });
+
+    it('full SDK handshake protocol works end-to-end with factory-created strategies', async () => {
+        // Mirrors exactly what sdk.ts does internally during setChannel()
+        const aliceStrategy = EncryptionFactory.create();
+        const bobStrategy   = EncryptionFactory.create();
+
+        // Both peers initialise their symmetric keys
+        await aliceStrategy.symmetric.init();
+        await bobStrategy.symmetric.init();
+
+        // Both peers generate asymmetric key pairs
+        const { publicKey: alicePub, privateKey: alicePriv } = await aliceStrategy.asymmetric.generateKeypairs();
+        const { publicKey: bobPub,   privateKey: bobPriv   } = await bobStrategy.asymmetric.generateKeypairs();
+
+        // Alice wraps her symmetric key with Bob's public key and "sends" it
+        const aliceExportedKey = await aliceStrategy.symmetric.exportKey();
+        const wrappedKey       = await aliceStrategy.asymmetric.encryptMessage(aliceExportedKey, bobPub);
+
+        // Bob unwraps it with his private key and imports it as the remote key
+        const unwrappedKey = await bobStrategy.asymmetric.decryptMessage(wrappedKey, bobPriv);
+        await bobStrategy.symmetric.importRemoteKey(unwrappedKey);
+
+        // Alice encrypts a message; Bob decrypts it
+        const plaintext = 'end-to-end via pluggable factory';
+        const { encryptedData, iv } = await aliceStrategy.symmetric.encryptData(
+            new TextEncoder().encode(plaintext).buffer
+        );
+        const decrypted = await bobStrategy.symmetric.decryptData(encryptedData, iv);
+
+        expect(new TextDecoder().decode(decrypted)).toBe(plaintext);
+
+        // Confirm the asymmetric keys are independent (no cross-contamination)
+        await expect(
+            aliceStrategy.asymmetric.decryptMessage(wrappedKey, alicePriv)
+        ).rejects.toThrow();
+    });
+});