@learncard/sss-key-manager 0.1.14 → 0.1.16

package/src/qr-crypto.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Tests for QR Login Crypto Helpers (X25519 ECDH + AES-256-GCM)
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import {
+    generateEphemeralKeypair,
+    encryptShareForTransfer,
+    decryptShareFromTransfer,
+} from './qr-crypto';
+
+// Node 20+ supports X25519 in crypto.subtle.
+// jsdom doesn't provide its own Web Crypto — it falls through to Node's.
+// If this environment doesn't support X25519, skip gracefully.
+const supportsX25519 = async (): Promise<boolean> => {
+    try {
+        await crypto.subtle.generateKey({ name: 'X25519' }, false, ['deriveBits']);
+        return true;
+    } catch {
+        return false;
+    }
+};
+
+describe('QR Crypto (X25519 ECDH + AES-GCM)', async () => {
+    const supported = await supportsX25519();
+
+    it.skipIf(!supported)('generateEphemeralKeypair returns a public key string and private CryptoKey', async () => {
+        const keypair = await generateEphemeralKeypair();
+
+        expect(keypair.publicKey).toBeTruthy();
+        expect(typeof keypair.publicKey).toBe('string');
+
+        // X25519 public keys are 32 bytes → 44 chars in base64
+        expect(keypair.publicKey.length).toBeGreaterThanOrEqual(40);
+
+        expect(keypair.privateKey).toBeTruthy();
+        expect(keypair.privateKey.type).toBe('private');
+    });
+
+    it.skipIf(!supported)('generates unique keypairs on each call', async () => {
+        const kp1 = await generateEphemeralKeypair();
+        const kp2 = await generateEphemeralKeypair();
+
+        expect(kp1.publicKey).not.toBe(kp2.publicKey);
+    });
+
+    it.skipIf(!supported)('encrypt + decrypt round-trip produces the original share', async () => {
+        const deviceShare = 'abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab';
+
+        // Device B generates keypair
+        const deviceB = await generateEphemeralKeypair();
+
+        // Device A encrypts the share for Device B
+        const encrypted = await encryptShareForTransfer(deviceShare, deviceB.publicKey);
+
+        expect(encrypted.ciphertext).toBeTruthy();
+        expect(encrypted.iv).toBeTruthy();
+        expect(encrypted.senderPublicKey).toBeTruthy();
+
+        // Device B decrypts
+        const decrypted = await decryptShareFromTransfer(encrypted, deviceB.privateKey);
+
+        expect(decrypted).toBe(deviceShare);
+    });
+
+    it.skipIf(!supported)('decryption with wrong private key fails', async () => {
+        const deviceShare = 'secret-share-data-12345';
+
+        const deviceB = await generateEphemeralKeypair();
+        const wrongKey = await generateEphemeralKeypair();
+
+        const encrypted = await encryptShareForTransfer(deviceShare, deviceB.publicKey);
+
+        // Try to decrypt with a different private key — should fail
+        await expect(
+            decryptShareFromTransfer(encrypted, wrongKey.privateKey)
+        ).rejects.toThrow();
+    });
+
+    it.skipIf(!supported)('encrypted payload is different each time (unique IV + sender key)', async () => {
+        const deviceShare = 'some-share';
+
+        const deviceB = await generateEphemeralKeypair();
+
+        const enc1 = await encryptShareForTransfer(deviceShare, deviceB.publicKey);
+        const enc2 = await encryptShareForTransfer(deviceShare, deviceB.publicKey);
+
+        // Different IVs
+        expect(enc1.iv).not.toBe(enc2.iv);
+
+        // Different sender keys (each call generates a new ephemeral pair)
+        expect(enc1.senderPublicKey).not.toBe(enc2.senderPublicKey);
+
+        // Different ciphertexts
+        expect(enc1.ciphertext).not.toBe(enc2.ciphertext);
+
+        // But both decrypt to the same share
+        const dec1 = await decryptShareFromTransfer(enc1, deviceB.privateKey);
+        const dec2 = await decryptShareFromTransfer(enc2, deviceB.privateKey);
+
+        expect(dec1).toBe(deviceShare);
+        expect(dec2).toBe(deviceShare);
+    });
+
+    it.skipIf(!supported)('handles various share lengths correctly', async () => {
+        const shares = [
+            'short',
+            'a'.repeat(66),   // typical SSS hex share
+            'a'.repeat(1000), // unusually long
+            '🔐🔑',          // unicode
+        ];
+
+        for (const share of shares) {
+            const deviceB = await generateEphemeralKeypair();
+            const encrypted = await encryptShareForTransfer(share, deviceB.publicKey);
+            const decrypted = await decryptShareFromTransfer(encrypted, deviceB.privateKey);
+
+            expect(decrypted).toBe(share);
+        }
+    });
+});

package/src/qr-crypto.ts

@@ -0,0 +1,206 @@
+/**
+ * QR Login Crypto Helpers
+ *
+ * X25519 ECDH key exchange + AES-256-GCM encryption for cross-device
+ * share transfer. Uses the Web Crypto API exclusively — no external deps.
+ *
+ * Flow:
+ *   Device B generates an ephemeral X25519 keypair, shares the public key.
+ *   Device A derives a shared secret via ECDH, encrypts the device share
+ *   with AES-256-GCM, and sends the ciphertext.
+ *   Device B decrypts with the same derived shared secret.
+ */
+
+import { bufferToBase64, base64ToBuffer } from './crypto';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface EphemeralKeypair {
+    /** Base64-encoded X25519 public key (sent to server / encoded in QR) */
+    publicKey: string;
+
+    /** Raw CryptoKey — kept in memory on Device B, never leaves the device */
+    privateKey: CryptoKey;
+}
+
+export interface EncryptedSharePayload {
+    /** Base64-encoded AES-256-GCM ciphertext */
+    ciphertext: string;
+
+    /** Base64-encoded 12-byte IV */
+    iv: string;
+
+    /** Base64-encoded ephemeral public key of the *sender* (Device A) */
+    senderPublicKey: string;
+}
+
+// ---------------------------------------------------------------------------
+// Key Generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate an ephemeral X25519 keypair for the new device (Device B).
+ * The public key is shared via QR / short code; the private key stays in memory.
+ */
+export const generateEphemeralKeypair = async (): Promise<EphemeralKeypair> => {
+    if (typeof crypto === 'undefined' || !crypto.subtle) {
+        throw new Error(
+            'Web Crypto API is not available. This feature requires a secure context (HTTPS). ' +
+            'If you are running a Capacitor dev server over HTTP, use a production build or configure HTTPS.'
+        );
+    }
+
+    const keyPair = await crypto.subtle.generateKey(
+        { name: 'X25519' },
+        false,
+        ['deriveBits']
+    ) as CryptoKeyPair;
+
+    const rawPublicKey = await crypto.subtle.exportKey('raw', keyPair.publicKey);
+
+    return {
+        publicKey: bufferToBase64(rawPublicKey),
+        privateKey: keyPair.privateKey,
+    };
+};
+
+// ---------------------------------------------------------------------------
+// Shared Secret Derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Import a raw X25519 public key from base64.
+ */
+const importPublicKey = async (base64Key: string): Promise<CryptoKey> => {
+    const keyBytes = base64ToBuffer(base64Key);
+
+    return crypto.subtle.importKey(
+        'raw',
+        keyBytes,
+        { name: 'X25519' },
+        false,
+        []
+    );
+};
+
+/**
+ * Derive a 256-bit AES-GCM key from our private key + their public key
+ * using X25519 ECDH → HKDF-SHA256.
+ *
+ * The raw ECDH output is fed through HKDF with a context-specific info
+ * string to produce the final encryption key (NIST SP 800-56C compliant).
+ */
+const deriveSharedAesKey = async (
+    ourPrivateKey: CryptoKey,
+    theirPublicKeyBase64: string
+): Promise<CryptoKey> => {
+    const theirPublicKey = await importPublicKey(theirPublicKeyBase64);
+
+    const sharedBits = await crypto.subtle.deriveBits(
+        { name: 'X25519', public: theirPublicKey },
+        ourPrivateKey,
+        256
+    );
+
+    // Import raw ECDH output as HKDF key material
+    const hkdfKey = await crypto.subtle.importKey(
+        'raw',
+        sharedBits,
+        'HKDF',
+        false,
+        ['deriveKey']
+    );
+
+    // Derive the final AES-256-GCM key via HKDF-SHA256
+    const encoder = new TextEncoder();
+
+    return crypto.subtle.deriveKey(
+        {
+            name: 'HKDF',
+            hash: 'SHA-256',
+            salt: new Uint8Array(32), // fixed empty salt (ephemeral keys provide freshness)
+            info: encoder.encode('learncard-qr-login-v1'),
+        },
+        hkdfKey,
+        { name: 'AES-GCM', length: 256 },
+        false,
+        ['encrypt', 'decrypt']
+    );
+};
+
+// ---------------------------------------------------------------------------
+// Encrypt / Decrypt
+// ---------------------------------------------------------------------------
+
+/**
+ * Encrypt a device share for transfer to Device B.
+ *
+ * Called by Device A (the logged-in device):
+ *   1. Generates its own ephemeral X25519 keypair
+ *   2. Derives a shared secret from its private key + Device B's public key
+ *   3. Encrypts the share with AES-256-GCM
+ *   4. Returns the ciphertext + IV + Device A's ephemeral public key
+ *
+ * @param deviceShare - Plaintext device share to encrypt
+ * @param recipientPublicKey - Base64-encoded X25519 public key from Device B
+ */
+export const encryptShareForTransfer = async (
+    deviceShare: string,
+    recipientPublicKey: string
+): Promise<EncryptedSharePayload> => {
+    // Generate sender's ephemeral keypair
+    const senderKeypair = await generateEphemeralKeypair();
+
+    // Derive shared AES key
+    const aesKey = await deriveSharedAesKey(senderKeypair.privateKey, recipientPublicKey);
+
+    // Encrypt
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const encoder = new TextEncoder();
+
+    const ciphertextBuffer = await crypto.subtle.encrypt(
+        { name: 'AES-GCM', iv },
+        aesKey,
+        encoder.encode(deviceShare)
+    );
+
+    return {
+        ciphertext: bufferToBase64(ciphertextBuffer),
+        iv: bufferToBase64(iv.buffer),
+        senderPublicKey: senderKeypair.publicKey,
+    };
+};
+
+/**
+ * Decrypt a device share received from Device A.
+ *
+ * Called by Device B (the new device):
+ *   1. Derives the shared secret from its private key + Device A's public key
+ *   2. Decrypts the ciphertext with AES-256-GCM
+ *
+ * @param payload - The encrypted payload from Device A
+ * @param recipientPrivateKey - Device B's ephemeral private CryptoKey
+ */
+export const decryptShareFromTransfer = async (
+    payload: EncryptedSharePayload,
+    recipientPrivateKey: CryptoKey
+): Promise<string> => {
+    // Derive shared AES key
+    const aesKey = await deriveSharedAesKey(recipientPrivateKey, payload.senderPublicKey);
+
+    // Decrypt
+    const ivBytes = base64ToBuffer(payload.iv);
+    const ciphertextBytes = base64ToBuffer(payload.ciphertext);
+
+    const plaintextBuffer = await crypto.subtle.decrypt(
+        { name: 'AES-GCM', iv: ivBytes },
+        aesKey,
+        ciphertextBytes
+    );
+
+    const decoder = new TextDecoder();
+
+    return decoder.decode(plaintextBuffer);
+};

package/src/qr-login-notify.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Tests for QR Login Push Notification helper
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+import { notifyDevicesForQrSession } from './qr-login';
+
+const SERVER_URL = 'https://api.example.com';
+
+let mockFetch: ReturnType<typeof vi.fn>;
+
+describe('notifyDevicesForQrSession', () => {
+    beforeEach(() => {
+        mockFetch = vi.fn();
+        vi.stubGlobal('fetch', mockFetch);
+    });
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+
+    it('sends a POST to /qr-login/notify with correct body', async () => {
+        mockFetch.mockResolvedValueOnce(
+            new Response(JSON.stringify({ sent: true, deviceCount: 2 }), { status: 200 })
+        );
+
+        const result = await notifyDevicesForQrSession(
+            { serverUrl: SERVER_URL },
+            'session-123',
+            '12345678',
+            'firebase-token-abc',
+            'firebase'
+        );
+
+        expect(result).toEqual({ sent: true, deviceCount: 2 });
+
+        expect(mockFetch).toHaveBeenCalledOnce();
+
+        const [url, init] = mockFetch.mock.calls[0] as [string, RequestInit];
+
+        expect(url).toBe(`${SERVER_URL}/qr-login/notify`);
+        expect(init.method).toBe('POST');
+
+        const body = JSON.parse(init.body as string);
+
+        expect(body.authToken).toBe('firebase-token-abc');
+        expect(body.providerType).toBe('firebase');
+        expect(body.sessionId).toBe('session-123');
+        expect(body.shortCode).toBe('12345678');
+    });
+
+    it('defaults providerType to firebase', async () => {
+        mockFetch.mockResolvedValueOnce(
+            new Response(JSON.stringify({ sent: true, deviceCount: 1 }), { status: 200 })
+        );
+
+        await notifyDevicesForQrSession(
+            { serverUrl: SERVER_URL },
+            'session-456',
+            '87654321',
+            'token-xyz'
+        );
+
+        const body = JSON.parse((mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string);
+
+        expect(body.providerType).toBe('firebase');
+    });
+
+    it('returns { sent: false, deviceCount: 0 } on HTTP error', async () => {
+        mockFetch.mockResolvedValueOnce(new Response('Server Error', { status: 500 }));
+
+        const result = await notifyDevicesForQrSession(
+            { serverUrl: SERVER_URL },
+            'session-err',
+            '00000000',
+            'token'
+        );
+
+        expect(result).toEqual({ sent: false, deviceCount: 0 });
+    });
+
+    it('returns { sent: false, deviceCount: 0 } on network failure', async () => {
+        mockFetch.mockRejectedValueOnce(new TypeError('Network error'));
+
+        const result = await notifyDevicesForQrSession(
+            { serverUrl: SERVER_URL },
+            'session-net',
+            '11111111',
+            'token'
+        );
+
+        expect(result).toEqual({ sent: false, deviceCount: 0 });
+    });
+});