@ruvector/edge-net 0.3.0 → 0.4.0

package/firebase-signaling.js

@@ -0,0 +1,788 @@
+/**
+ * @ruvector/edge-net Firebase Signaling
+ *
+ * Uses Google Firebase as bootstrap infrastructure for WebRTC signaling
+ * with migration path to full P2P DHT network.
+ *
+ * Architecture:
+ * 1. Firebase Firestore for signaling (offer/answer/ICE)
+ * 2. Firebase Realtime DB for presence (who's online)
+ * 3. Gradual migration to DHT as network grows
+ *
+ * @module @ruvector/edge-net/firebase-signaling
+ */
+
+import { EventEmitter } from 'events';
+
+// ============================================
+// FIREBASE CONFIGURATION
+// ============================================
+
+/**
+ * Get Firebase config from environment variables or saved config
+ *
+ * Configuration sources (in order of priority):
+ * 1. Environment variables: FIREBASE_API_KEY, FIREBASE_PROJECT_ID
+ * 2. Saved config from: ~/.edge-net/firebase.json (via firebase-setup.js)
+ * 3. Application Default Credentials (for server-side via gcloud)
+ *
+ * SECURITY:
+ * - Never hardcode API keys
+ * - Use `gcloud auth application-default login` for server-side
+ * - Restrict API keys by domain in Google Cloud Console for browser-side
+ *
+ * Setup:
+ *   npx edge-net-firebase-setup --project YOUR_PROJECT_ID
+ */
+export function getFirebaseConfig() {
+    // Try environment variables first (highest priority)
+    const apiKey = process.env.FIREBASE_API_KEY;
+    const projectId = process.env.FIREBASE_PROJECT_ID;
+
+    if (apiKey && projectId) {
+        return {
+            apiKey,
+            projectId,
+            authDomain: process.env.FIREBASE_AUTH_DOMAIN || `${projectId}.firebaseapp.com`,
+            databaseURL: process.env.FIREBASE_DATABASE_URL || `https://${projectId}-default-rtdb.firebaseio.com`,
+            storageBucket: process.env.FIREBASE_STORAGE_BUCKET || `${projectId}.appspot.com`,
+        };
+    }
+
+    // Sync version only uses env vars - use getFirebaseConfigAsync for file config
+    return null;
+}
+
+/**
+ * Async version that can load from config file
+ */
+export async function getFirebaseConfigAsync() {
+    // Try environment variables first
+    const apiKey = process.env.FIREBASE_API_KEY;
+    const projectId = process.env.FIREBASE_PROJECT_ID;
+
+    if (apiKey && projectId) {
+        return {
+            apiKey,
+            projectId,
+            authDomain: process.env.FIREBASE_AUTH_DOMAIN || `${projectId}.firebaseapp.com`,
+            databaseURL: process.env.FIREBASE_DATABASE_URL || `https://${projectId}-default-rtdb.firebaseio.com`,
+            storageBucket: process.env.FIREBASE_STORAGE_BUCKET || `${projectId}.appspot.com`,
+        };
+    }
+
+    // Try loading saved config
+    try {
+        const { loadConfig } = await import('./firebase-setup.js');
+        const savedConfig = loadConfig();
+        if (savedConfig && apiKey) {
+            return { apiKey, ...savedConfig };
+        }
+        // Can work with just project config for server-side with ADC
+        if (savedConfig) {
+            return savedConfig; // No API key, but has project info (use ADC)
+        }
+    } catch {
+        // firebase-setup.js not available
+    }
+
+    return null;
+}
+
+/**
+ * Default returns null - must be configured via environment or setup
+ */
+export const DEFAULT_FIREBASE_CONFIG = null;
+
+/**
+ * Signaling paths in Firestore
+ */
+export const SIGNALING_PATHS = {
+    peers: 'edge-net/peers',
+    signals: 'edge-net/signals',
+    rooms: 'edge-net/rooms',
+    ledger: 'edge-net/ledger',
+};
+
+// ============================================
+// FIREBASE SIGNALING CLIENT
+// ============================================
+
+/**
+ * Firebase-based WebRTC Signaling
+ *
+ * Provides:
+ * - Peer discovery via Firestore
+ * - WebRTC signaling (offer/answer/ICE)
+ * - Presence tracking
+ * - Graceful fallback to local/DHT
+ */
+export class FirebaseSignaling extends EventEmitter {
+    constructor(options = {}) {
+        super();
+
+        // SECURITY: Config must come from options or environment variables
+        // Will be loaded async if not provided
+        this._configPromise = null;
+        this._providedConfig = options.firebaseConfig;
+        this.peerId = options.peerId;
+        this.room = options.room || 'default';
+
+        // Initial sync config check (env vars only)
+        this.config = options.firebaseConfig || getFirebaseConfig();
+
+        // Firebase instances (lazy loaded)
+        this.app = null;
+        this.db = null;
+        this.rtdb = null;
+
+        // State
+        this.isConnected = false;
+        this.peers = new Map();
+        this.pendingSignals = new Map();
+
+        // Listeners for cleanup
+        this.unsubscribers = [];
+
+        // Migration tracking
+        this.stats = {
+            firebaseSignals: 0,
+            dhtSignals: 0,
+            p2pSignals: 0,
+        };
+    }
+
+    /**
+     * Initialize Firebase connection
+     */
+    async connect() {
+        // SECURITY: Require valid config
+        if (!this.config || !this.config.apiKey || !this.config.projectId) {
+            console.log('   ⚠️  Firebase not configured (no credentials)');
+            console.log('   💡 Set environment variables: FIREBASE_API_KEY, FIREBASE_PROJECT_ID');
+            this.emit('not-configured');
+            return false;
+        }
+
+        try {
+            // Dynamic import Firebase (tree-shakeable)
+            const { initializeApp, getApps } = await import('firebase/app');
+            const { getFirestore, collection, doc, setDoc, onSnapshot, deleteDoc, query, where, orderBy, limit } = await import('firebase/firestore');
+            const { getDatabase, ref, set, onValue, onDisconnect, serverTimestamp } = await import('firebase/database');
+
+            // Store Firebase methods for later use
+            this.firebase = {
+                collection, doc, setDoc, onSnapshot, deleteDoc, query, where, orderBy, limit,
+                ref, set, onValue, onDisconnect, serverTimestamp
+            };
+
+            // Initialize or reuse existing app
+            const apps = getApps();
+            this.app = apps.length ? apps[0] : initializeApp(this.config);
+
+            // Initialize Firestore (for signaling)
+            this.db = getFirestore(this.app);
+
+            // Initialize Realtime Database (for presence)
+            this.rtdb = getDatabase(this.app);
+
+            // Register presence
+            await this.registerPresence();
+
+            // Listen for peers
+            this.subscribeToPeers();
+
+            // Listen for signals
+            this.subscribeToSignals();
+
+            this.isConnected = true;
+            console.log('   ✅ Firebase signaling connected');
+
+            this.emit('connected');
+            return true;
+
+        } catch (error) {
+            console.log('   ⚠️  Firebase unavailable:', error.message);
+            this.emit('error', error);
+            return false;
+        }
+    }
+
+    /**
+     * Register this peer's presence in Firebase
+     */
+    async registerPresence() {
+        const { ref, set, onDisconnect, serverTimestamp } = this.firebase;
+
+        const presenceRef = ref(this.rtdb, `presence/${this.room}/${this.peerId}`);
+
+        // Set online status
+        await set(presenceRef, {
+            peerId: this.peerId,
+            room: this.room,
+            online: true,
+            lastSeen: serverTimestamp(),
+            capabilities: ['compute', 'storage', 'verify'],
+        });
+
+        // Remove on disconnect
+        onDisconnect(presenceRef).remove();
+
+        console.log(`   📡 Registered presence: ${this.peerId.slice(0, 8)}...`);
+    }
+
+    /**
+     * Subscribe to peer presence updates
+     */
+    subscribeToPeers() {
+        const { ref, onValue } = this.firebase;
+
+        const roomRef = ref(this.rtdb, `presence/${this.room}`);
+
+        const unsubscribe = onValue(roomRef, (snapshot) => {
+            const peers = snapshot.val() || {};
+
+            // Track new peers
+            for (const [peerId, data] of Object.entries(peers)) {
+                if (peerId !== this.peerId && !this.peers.has(peerId)) {
+                    this.peers.set(peerId, data);
+                    this.emit('peer-discovered', { peerId, ...data });
+                }
+            }
+
+            // Track disconnected peers
+            for (const peerId of this.peers.keys()) {
+                if (!peers[peerId]) {
+                    this.peers.delete(peerId);
+                    this.emit('peer-left', { peerId });
+                }
+            }
+        });
+
+        this.unsubscribers.push(unsubscribe);
+    }
+
+    /**
+     * Subscribe to WebRTC signaling messages
+     */
+    subscribeToSignals() {
+        const { collection, query, where, onSnapshot } = this.firebase;
+
+        // Listen for signals addressed to this peer
+        const signalsRef = collection(this.db, SIGNALING_PATHS.signals);
+        const q = query(signalsRef, where('to', '==', this.peerId));
+
+        const unsubscribe = onSnapshot(q, (snapshot) => {
+            snapshot.docChanges().forEach(async (change) => {
+                if (change.type === 'added') {
+                    const signal = change.doc.data();
+                    this.handleSignal(signal, change.doc.id);
+                }
+            });
+        });
+
+        this.unsubscribers.push(unsubscribe);
+    }
+
+    /**
+     * Handle incoming signal
+     */
+    async handleSignal(signal, docId) {
+        this.stats.firebaseSignals++;
+
+        // Delete processed signal
+        const { doc, deleteDoc } = this.firebase;
+        await deleteDoc(doc(this.db, SIGNALING_PATHS.signals, docId));
+
+        // Emit appropriate event
+        switch (signal.type) {
+            case 'offer':
+                this.emit('offer', { from: signal.from, offer: signal.data });
+                break;
+            case 'answer':
+                this.emit('answer', { from: signal.from, answer: signal.data });
+                break;
+            case 'ice-candidate':
+                this.emit('ice-candidate', { from: signal.from, candidate: signal.data });
+                break;
+            default:
+                this.emit('signal', signal);
+        }
+    }
+
+    /**
+     * Send WebRTC offer to peer
+     */
+    async sendOffer(toPeerId, offer) {
+        return this.sendSignal(toPeerId, 'offer', offer);
+    }
+
+    /**
+     * Send WebRTC answer to peer
+     */
+    async sendAnswer(toPeerId, answer) {
+        return this.sendSignal(toPeerId, 'answer', answer);
+    }
+
+    /**
+     * Send ICE candidate to peer
+     */
+    async sendIceCandidate(toPeerId, candidate) {
+        return this.sendSignal(toPeerId, 'ice-candidate', candidate);
+    }
+
+    /**
+     * Send signal via Firebase
+     */
+    async sendSignal(toPeerId, type, data) {
+        if (!this.isConnected) {
+            throw new Error('Firebase not connected');
+        }
+
+        const { collection, doc, setDoc } = this.firebase;
+
+        const signalId = `${this.peerId}-${toPeerId}-${Date.now()}`;
+        const signalRef = doc(this.db, SIGNALING_PATHS.signals, signalId);
+
+        await setDoc(signalRef, {
+            from: this.peerId,
+            to: toPeerId,
+            type,
+            data,
+            timestamp: Date.now(),
+            room: this.room,
+        });
+
+        return true;
+    }
+
+    /**
+     * Get list of online peers
+     */
+    getOnlinePeers() {
+        return Array.from(this.peers.entries()).map(([id, data]) => ({
+            id,
+            ...data,
+        }));
+    }
+
+    /**
+     * Disconnect and cleanup
+     */
+    async disconnect() {
+        // Unsubscribe from all listeners
+        for (const unsub of this.unsubscribers) {
+            if (typeof unsub === 'function') unsub();
+        }
+        this.unsubscribers = [];
+
+        // Remove presence
+        if (this.rtdb && this.firebase) {
+            const { ref, set } = this.firebase;
+            const presenceRef = ref(this.rtdb, `presence/${this.room}/${this.peerId}`);
+            await set(presenceRef, null);
+        }
+
+        this.isConnected = false;
+        this.peers.clear();
+
+        this.emit('disconnected');
+    }
+}
+
+// ============================================
+// FIREBASE LEDGER SYNC
+// ============================================
+
+/**
+ * Firebase-based Ledger Synchronization
+ *
+ * Syncs CRDT ledger state across peers using Firestore
+ * with automatic CRDT merge on conflicts.
+ */
+export class FirebaseLedgerSync extends EventEmitter {
+    constructor(ledger, options = {}) {
+        super();
+
+        this.ledger = ledger;
+        this.peerId = options.peerId;
+        // SECURITY: Config must come from options or environment variables
+        this.config = options.firebaseConfig || getFirebaseConfig();
+
+        // Firebase instances
+        this.app = null;
+        this.db = null;
+
+        // Sync state
+        this.lastSyncedVersion = 0;
+        this.syncInterval = options.syncInterval || 30000;
+        this.syncTimer = null;
+
+        this.unsubscribers = [];
+    }
+
+    /**
+     * Start ledger sync
+     */
+    async start() {
+        // SECURITY: Require valid config
+        if (!this.config || !this.config.apiKey || !this.config.projectId) {
+            console.log('   ⚠️  Firebase ledger sync disabled (no credentials)');
+            return false;
+        }
+
+        try {
+            const { initializeApp, getApps } = await import('firebase/app');
+            const { getFirestore, doc, setDoc, onSnapshot, getDoc } = await import('firebase/firestore');
+
+            this.firebase = { doc, setDoc, onSnapshot, getDoc };
+
+            const apps = getApps();
+            this.app = apps.length ? apps[0] : initializeApp(this.config);
+            this.db = getFirestore(this.app);
+
+            // Initial sync from Firebase
+            await this.pullLedger();
+
+            // Subscribe to ledger updates
+            this.subscribeLedger();
+
+            // Periodic push
+            this.syncTimer = setInterval(() => this.pushLedger(), this.syncInterval);
+
+            console.log('   ✅ Firebase ledger sync started');
+            return true;
+
+        } catch (error) {
+            console.log('   ⚠️  Firebase ledger sync unavailable:', error.message);
+            return false;
+        }
+    }
+
+    /**
+     * Pull ledger state from Firebase
+     */
+    async pullLedger() {
+        const { doc, getDoc } = this.firebase;
+
+        const ledgerRef = doc(this.db, SIGNALING_PATHS.ledger, this.peerId);
+        const snapshot = await getDoc(ledgerRef);
+
+        if (snapshot.exists()) {
+            const remoteState = snapshot.data();
+            this.mergeLedger(remoteState);
+        }
+    }
+
+    /**
+     * Push ledger state to Firebase
+     */
+    async pushLedger() {
+        if (!this.ledger) return;
+
+        const { doc, setDoc } = this.firebase;
+
+        const state = this.ledger.export();
+        const ledgerRef = doc(this.db, SIGNALING_PATHS.ledger, this.peerId);
+
+        await setDoc(ledgerRef, {
+            ...state,
+            peerId: this.peerId,
+            updatedAt: Date.now(),
+        }, { merge: true });
+    }
+
+    /**
+     * Subscribe to ledger updates from other peers
+     */
+    subscribeLedger() {
+        const { doc, onSnapshot } = this.firebase;
+
+        // For now, just sync own ledger
+        // Full multi-peer sync would subscribe to all peers
+        const ledgerRef = doc(this.db, SIGNALING_PATHS.ledger, this.peerId);
+
+        const unsubscribe = onSnapshot(ledgerRef, (snapshot) => {
+            if (snapshot.exists()) {
+                const remoteState = snapshot.data();
+                if (remoteState.updatedAt > this.lastSyncedVersion) {
+                    this.mergeLedger(remoteState);
+                    this.lastSyncedVersion = remoteState.updatedAt;
+                }
+            }
+        });
+
+        this.unsubscribers.push(unsubscribe);
+    }
+
+    /**
+     * Merge remote ledger state using CRDT rules
+     */
+    mergeLedger(remoteState) {
+        if (!this.ledger || !remoteState) return;
+
+        // CRDT merge: take max of counters
+        if (remoteState.credits !== undefined) {
+            const localCredits = this.ledger.getBalance?.() || 0;
+            if (remoteState.credits > localCredits) {
+                // Remote has more - need to import
+                this.ledger.import?.(remoteState);
+                this.emit('synced', { source: 'firebase', credits: remoteState.credits });
+            }
+        }
+    }
+
+    /**
+     * Stop sync
+     */
+    stop() {
+        if (this.syncTimer) {
+            clearInterval(this.syncTimer);
+            this.syncTimer = null;
+        }
+
+        for (const unsub of this.unsubscribers) {
+            if (typeof unsub === 'function') unsub();
+        }
+        this.unsubscribers = [];
+    }
+}
+
+// ============================================
+// HYBRID BOOTSTRAP MANAGER
+// ============================================
+
+/**
+ * Hybrid Bootstrap Manager
+ *
+ * Manages the migration from Firebase bootstrap to full P2P:
+ * 1. Start with Firebase for discovery and signaling
+ * 2. Establish WebRTC connections to peers
+ * 3. Build DHT routing table from connected peers
+ * 4. Gradually reduce Firebase dependency
+ * 5. Eventually operate fully P2P
+ */
+export class HybridBootstrap extends EventEmitter {
+    constructor(options = {}) {
+        super();
+
+        this.peerId = options.peerId;
+        this.config = options.firebaseConfig || DEFAULT_FIREBASE_CONFIG;
+
+        // Components
+        this.firebase = null;
+        this.dht = null;
+        this.webrtc = null;
+
+        // Migration state
+        this.mode = 'firebase'; // firebase -> hybrid -> p2p
+        this.dhtPeerThreshold = options.dhtPeerThreshold || 5;
+        this.p2pPeerThreshold = options.p2pPeerThreshold || 10;
+
+        // Stats for migration decisions
+        this.stats = {
+            firebaseDiscoveries: 0,
+            dhtDiscoveries: 0,
+            directConnections: 0,
+            firebaseSignals: 0,
+            p2pSignals: 0,
+        };
+    }
+
+    /**
+     * Start hybrid bootstrap
+     */
+    async start(webrtc, dht) {
+        this.webrtc = webrtc;
+        this.dht = dht;
+
+        // Start with Firebase
+        this.firebase = new FirebaseSignaling({
+            peerId: this.peerId,
+            firebaseConfig: this.config,
+        });
+
+        // Wire up events
+        this.setupFirebaseEvents();
+
+        // Connect to Firebase
+        const connected = await this.firebase.connect();
+
+        if (connected) {
+            console.log('   🔄 Hybrid bootstrap: Firebase mode');
+            this.mode = 'firebase';
+        } else {
+            console.log('   🔄 Hybrid bootstrap: DHT-only mode');
+            this.mode = 'p2p';
+        }
+
+        // Start migration checker
+        this.startMigrationChecker();
+
+        return connected;
+    }
+
+    /**
+     * Setup Firebase event handlers
+     */
+    setupFirebaseEvents() {
+        this.firebase.on('peer-discovered', async ({ peerId }) => {
+            this.stats.firebaseDiscoveries++;
+
+            // Try to connect via WebRTC
+            if (this.webrtc) {
+                await this.connectToPeer(peerId);
+            }
+
+            this.emit('peer-discovered', { peerId, source: 'firebase' });
+        });
+
+        this.firebase.on('offer', async ({ from, offer }) => {
+            this.stats.firebaseSignals++;
+            if (this.webrtc) {
+                await this.webrtc.handleOffer({ from, offer });
+            }
+        });
+
+        this.firebase.on('answer', async ({ from, answer }) => {
+            this.stats.firebaseSignals++;
+            if (this.webrtc) {
+                await this.webrtc.handleAnswer({ from, answer });
+            }
+        });
+
+        this.firebase.on('ice-candidate', async ({ from, candidate }) => {
+            if (this.webrtc) {
+                await this.webrtc.handleIceCandidate({ from, candidate });
+            }
+        });
+    }
+
+    /**
+     * Connect to peer with signaling fallback
+     */
+    async connectToPeer(peerId) {
+        if (!this.webrtc) return;
+
+        try {
+            // Create offer
+            const offer = await this.webrtc.createOffer(peerId);
+
+            // Try P2P signaling first (if peer is directly connected)
+            if (this.mode === 'p2p' && this.webrtc.isConnected(peerId)) {
+                this.webrtc.sendToPeer(peerId, { type: 'offer', offer });
+                this.stats.p2pSignals++;
+            } else {
+                // Fall back to Firebase
+                await this.firebase.sendOffer(peerId, offer);
+                this.stats.firebaseSignals++;
+            }
+
+        } catch (error) {
+            console.warn(`[HybridBootstrap] Connect to ${peerId.slice(0, 8)} failed:`, error.message);
+        }
+    }
+
+    /**
+     * Send signaling message with automatic routing
+     */
+    async signal(toPeerId, type, data) {
+        // Prefer P2P if available
+        if (this.webrtc?.isConnected(toPeerId)) {
+            this.webrtc.sendToPeer(toPeerId, { type, data });
+            this.stats.p2pSignals++;
+            return;
+        }
+
+        // Fall back to Firebase
+        if (this.firebase?.isConnected) {
+            await this.firebase.sendSignal(toPeerId, type, data);
+            this.stats.firebaseSignals++;
+            return;
+        }
+
+        throw new Error('No signaling path available');
+    }
+
+    /**
+     * Start migration checker
+     * Monitors network health and decides when to reduce Firebase dependency
+     */
+    startMigrationChecker() {
+        setInterval(() => {
+            this.checkMigration();
+        }, 30000);
+    }
+
+    /**
+     * Check if we should migrate modes
+     */
+    checkMigration() {
+        const connectedPeers = this.webrtc?.peers?.size || 0;
+        const dhtPeers = this.dht?.getPeers?.()?.length || 0;
+
+        const previousMode = this.mode;
+
+        // Migration logic
+        if (this.mode === 'firebase') {
+            // Migrate to hybrid when we have enough DHT peers
+            if (dhtPeers >= this.dhtPeerThreshold) {
+                this.mode = 'hybrid';
+                console.log(`   🔄 Migration: firebase → hybrid (${dhtPeers} DHT peers)`);
+            }
+        } else if (this.mode === 'hybrid') {
+            // Migrate to full P2P when we have strong peer connectivity
+            if (connectedPeers >= this.p2pPeerThreshold) {
+                this.mode = 'p2p';
+                console.log(`   🔄 Migration: hybrid → p2p (${connectedPeers} direct peers)`);
+
+                // Could disconnect Firebase here to save resources
+                // this.firebase.disconnect();
+            }
+            // Fall back to Firebase if DHT shrinks
+            else if (dhtPeers < this.dhtPeerThreshold / 2) {
+                this.mode = 'firebase';
+                console.log(`   🔄 Migration: hybrid → firebase (DHT peers dropped)`);
+            }
+        } else if (this.mode === 'p2p') {
+            // Fall back to hybrid if peers drop
+            if (connectedPeers < this.p2pPeerThreshold / 2) {
+                this.mode = 'hybrid';
+                console.log(`   🔄 Migration: p2p → hybrid (peers dropped)`);
+            }
+        }
+
+        if (this.mode !== previousMode) {
+            this.emit('mode-changed', { from: previousMode, to: this.mode });
+        }
+    }
+
+    /**
+     * Get current bootstrap stats
+     */
+    getStats() {
+        return {
+            mode: this.mode,
+            ...this.stats,
+            firebaseConnected: this.firebase?.isConnected || false,
+            firebasePeers: this.firebase?.peers?.size || 0,
+            dhtPeers: this.dht?.getPeers?.()?.length || 0,
+            directPeers: this.webrtc?.peers?.size || 0,
+        };
+    }
+
+    /**
+     * Stop bootstrap
+     */
+    async stop() {
+        if (this.firebase) {
+            await this.firebase.disconnect();
+        }
+    }
+}
+
+// ============================================
+// EXPORTS
+// ============================================
+
+export default FirebaseSignaling;