feat(crypto): implement Web Crypto API encryption for sensitive node config (#63)

Author: Oluwasuyi-Oluwatimilehin-Daniel

src/hooks/useConfigEncryption.ts

@@ -0,0 +1,57 @@
+import { useEffect, useState, useRef } from 'react';
+import { deriveSessionKey } from '../lib/crypto/cryptoEngine';
+
+export function useConfigEncryption(sessionToken: string | null) {
+  // We use a ref to prevent exposing the CryptoKey directly in state/DevTools snapshots
+  const keyRef = useRef<WeakRef<CryptoKey> | null>(null);
+  const saltRef = useRef<Uint8Array | null>(null);
+  const [isReady, setIsReady] = useState(false);
+
+  useEffect(() => {
+    let isMounted = true;
+
+    if (!sessionToken) {
+      keyRef.current = null;
+      saltRef.current = null;
+      setIsReady(false);
+      return;
+    }
+
+    async function initializeKey() {
+      try {
+        const { key, salt } = await deriveSessionKey(sessionToken!);
+        if (isMounted) {
+          keyRef.current = new WeakRef(key);
+          saltRef.current = salt;
+          setIsReady(true);
+        }
+      } catch (error) {
+        console.error('Failed to initialize configuration encryption keys:', error);
+        if (isMounted) setIsReady(false);
+      }
+    }
+
+    initializeKey();
+
+    return () => {
+      isMounted = false;
+      // Break references explicitly to allow GC execution
+      keyRef.current = null;
+      saltRef.current = null;
+    };
+  }, [sessionToken]);
+
+  const getSessionKey = (): CryptoKey => {
+    const key = keyRef.current?.deref();
+    if (!key) {
+      throw new Error('Encryption session key is unavailable or has been garbage collected.');
+    }
+    return key;
+  };
+
+  return {
+    isReady,
+    getSessionKey,
+    getSalt: () => saltRef.current,
+  };
+}

src/hooks/useNodeConfig.ts

@@ -0,0 +1,72 @@
+import { useNodeConfigStore } from '../store/nodeConfigStore';
+import { encryptField, decryptField } from '../lib/crypto/cryptoEngine';
+import { saveToIndexedDB, loadFromIndexedDB } from '../lib/storage/idb';
+
+// Define layout schema metadata
+const CONFIG_SCHEMA: Record<string, { sensitive: boolean }> = {
+  rpcEndpoint: { sensitive: true },
+  apiKey: { sensitive: true },
+  sshCredentials: { sensitive: true },
+  nodeName: { sensitive: false },
+};
+
+export function useNodeConfig(getSessionKey: () => CryptoKey, getSalt: () => Uint8Array | null) {
+  const store = useNodeConfigStore();
+
+  const loadConfig = async (nodeId: string) => {
+    const rawPayload = await loadFromIndexedDB(nodeId);
+    if (!rawPayload) return null;
+
+    const sessionKey = getSessionKey();
+    const decryptedConfig: Record<string, any> = {};
+
+    for (const [key, value] of Object.entries(rawPayload)) {
+      if (CONFIG_SCHEMA[key]?.sensitive && value && typeof value === 'object') {
+        decryptedConfig[key] = await decryptField(value, sessionKey);
+      } else {
+        decryptedConfig[key] = value;
+      }
+    }
+
+    store.startEditing(decryptedConfig);
+  };
+
+  const saveConfig = async (nodeId: string) => {
+    if (!store.editingConfig) return;
+
+    const sessionKey = getSessionKey();
+    const salt = getSalt();
+    if (!salt) throw new Error('Salt configuration missing');
+
+    // Create shallow target object copy to execute transformations
+    const payloadToPersist = { ...store.editingConfig };
+
+    for (const [key, value] of Object.entries(payloadToPersist)) {
+      if (CONFIG_SCHEMA[key]?.sensitive && typeof value === 'string') {
+        // 1. Encrypt field mutation
+        payloadToPersist[key] = await encryptField(value, sessionKey, salt);
+        
+        // 2. Strict Memory Hygiene: Purge plaintexts from the working copy immediately
+        if (store.editingConfig[key]) {
+          store.editingConfig[key] = null; 
+          delete store.editingConfig[key];
+        }
+      }
+    }
+
+    // Persist finalized structural envelope safely to DB
+    await saveToIndexedDB(nodeId, payloadToPersist);
+    
+    // Wipe out state trace fully
+    store.clearEditor();
+  };
+
+  return {
+    isEditorOpen: store.isEditorOpen,
+    editingConfig: store.editingConfig,
+    updateField: store.updateField,
+    loadConfig,
+    saveConfig,
+    cancelEditing: store.clearEditor,
+  };
+}

src/lib/__tests__/cryptoEngine.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest'; // or jest
+import { deriveSessionKey, encryptField, decryptField } from '../lib/crypto/cryptoEngine';
+
+describe('Web Crypto Client-Side Configuration Encryption', () => {
+  const mockToken = 'wallet-auth-session-token-xyz-12345';
+  const plainTextSecret = 'https://eth-mainnet.g.alchemy.com/v2/secret-api-key';
+
+  it('should successfully execute an encrypt -> decrypt round-trip loop', async () => {
+    const { key, salt } = await deriveSessionKey(mockToken);
+    
+    const envelope = await encryptField(plainTextSecret, key, salt);
+    
+    expect(envelope).toHaveProperty('iv');
+    expect(envelope).toHaveProperty('salt');
+    expect(envelope).toHaveProperty('ciphertext');
+    expect(envelope.version).toBe(1);
+
+    const decryptedText = await decryptField(envelope, key);
+    expect(decryptedText).toBe(plainTextSecret);
+  });
+
+  it('should fail decryption if a different session key is supplied', async () => {
+    const { key: trueKey, salt } = await deriveSessionKey(mockToken);
+    const { key: wrongKey } = await deriveSessionKey('completely-different-token');
+
+    const envelope = await encryptField(plainTextSecret, trueKey, salt);
+
+    await expect(decryptField(envelope, wrongKey)).rejects.toThrow();
+  });
+
+  it('should guarantee unique IV strings across independent invocations', async () => {
+    const { key, salt } = await deriveSessionKey(mockToken);
+
+    const envelope1 = await encryptField(plainTextSecret, key, salt);
+    const envelope2 = await encryptField(plainTextSecret, key, salt);
+
+    expect(envelope1.iv).not.toBe(envelope2.iv);
+    expect(envelope1.ciphertext).not.toBe(envelope2.ciphertext);
+  });
+});

src/lib/crypto/cryptoEngine.ts

@@ -0,0 +1,101 @@
+export interface EncryptedEnvelope {
+  iv: string; // Base64
+  salt: string; // Base64
+  ciphertext: string; // Base64
+  version: number;
+}
+
+// Helper utilities for ArrayBuffer <-> Base64/String conversions
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+function bufferToBase64(buffer: ArrayBuffer): string {
+  return btoa(String.fromCharCode(...new Uint8Array(buffer)));
+}
+
+function base64ToBuffer(base64: string): ArrayBuffer {
+  const binaryString = atob(base64);
+  const bytes = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+
+/**
+ * Derives a 256-bit AES-GCM CryptoKey from a session token using PBKDF2.
+ */
+export async function deriveSessionKey(sessionToken: string, customSalt?: ArrayBuffer): Promise<{ key: CryptoKey; salt: Uint8Array }> {
+  const tokenBytes = textEncoder.encode(sessionToken);
+  const salt = customSalt ? new Uint8Array(customSalt) : window.crypto.getRandomValues(new Uint8Array(16));
+
+  const baseKey = await window.crypto.subtle.importKey(
+    'raw',
+    tokenBytes,
+    'PBKDF2',
+    false,
+    ['deriveKey']
+  );
+
+  const key = await window.crypto.subtle.deriveKey(
+    {
+      name: 'PBKDF2',
+      salt: salt,
+      iterations: 600000,
+      hash: 'SHA-256',
+    },
+    baseKey,
+    { name: 'AES-GCM', length: 256 },
+    false, // Key is non-extractable for security
+    ['encrypt', 'decrypt']
+  );
+
+  return { key, salt };
+}
+
+/**
+ * Encrypts a plaintext string using AES-GCM 256-bit with a session key.
+ */
+export async function encryptField(plaintext: string, sessionKey: CryptoKey, salt: Uint8Array): Promise<EncryptedEnvelope> {
+  const iv = window.crypto.getRandomValues(new Uint8Array(12));
+  const encodedPlaintext = textEncoder.encode(plaintext);
+
+  const ciphertextBuffer = await window.crypto.subtle.encrypt(
+    {
+      name: 'AES-GCM',
+      iv: iv,
+    },
+    sessionKey,
+    encodedPlaintext
+  );
+
+  return {
+    iv: bufferToBase64(iv.buffer),
+    salt: bufferToBase64(salt.buffer),
+    ciphertext: bufferToBase64(ciphertextBuffer),
+    version: 1,
+  };
+}
+
+/**
+ * Decrypts an EncryptedEnvelope back into a plaintext string.
+ */
+export async function decryptField(envelope: EncryptedEnvelope, sessionKey: CryptoKey): Promise<string> {
+  if (envelope.version !== 1) {
+    throw new Error(`Unsupported encryption version: ${envelope.version}`);
+  }
+
+  const iv = new Uint8Array(base64ToBuffer(envelope.iv));
+  const ciphertext = base64ToBuffer(envelope.ciphertext);
+
+  const decryptedBuffer = await window.crypto.subtle.decrypt(
+    {
+      name: 'AES-GCM',
+      iv: iv,
+    },
+    sessionKey,
+    ciphertext
+  );
+
+  return textDecoder.decode(decryptedBuffer);
+}

src/store/nodeConfigStore.ts

@@ -0,0 +1,34 @@
+import { create } from 'zustand';
+
+interface NodeConfigState {
+  editingConfig: Record<string, any> | null;
+  isEditorOpen: boolean;
+  startEditing: (initialConfig: Record<string, any>) => void;
+  updateField: (key: string, value: any) => void;
+  clearEditor: () => void;
+}
+
+export const useNodeConfigStore = create<NodeConfigState>((set) => ({
+  editingConfig: null,
+  isEditorOpen: false,
+
+  startEditing: (initialConfig) => set({
+    editingConfig: { ...initialConfig },
+    isEditorOpen: true
+  }),
+
+  updateField: (key, value) => set((state) => ({
+    editingConfig: state.editingConfig ? { ...state.editingConfig, [key]: value } : null
+  })),
+
+  clearEditor: () => set((state) => {
+    // Explicitly overwrite plaintext values in memory before dropping reference
+    if (state.editingConfig) {
+      Object.keys(state.editingConfig).forEach((key) => {
+        state.editingConfig![key] = null;
+        delete state.editingConfig![key];
+      });
+    }
+    return { editingConfig: null, isEditorOpen: false };
+  }),
+}));