suaveplan/docs/old-network-planning/LIBRARY_INTEGRATION.md

Network Library Integration Plan

Overview

Based on review of existing libraries in the project, this document outlines how to integrate several robust, existing libraries into the network implementation rather than rebuilding similar functionality. This approach will save development time, ensure consistency across the codebase, and leverage well-tested components.

Available Libraries for Integration

The following libraries are available and relevant for network implementation:

1. Events Library: Type-safe event emitter implementation
2. BitPacker Library: Binary serialization with schema validation and delta compression
3. Crypto Library: Comprehensive cryptography utilities
4. Keys Library: Hierarchical key management system
5. Utils Library: General purpose utilities

Events Library Integration

The existing @suaveplan/events library can be used directly as the standardized event system called for in ADAPT_1.md, eliminating the need to build a custom event system.

Integration Points

1. NetworkNode Event Handling:

   import { EventEmitter } from '@suaveplan/events';
   
   class NetworkNode {
     private events: EventEmitter;
   
     constructor() {
       this.events = new EventEmitter();
     }
   
     on(event: string, handler: Function, context?: any) {
       return this.events.on(event, handler, context);
     }
   
     once(event: string, handler: Function, context?: any) {
       return this.events.once(event, handler, context);
     }
   
     off(event: string, handler?: Function, context?: any) {
       return this.events.off(event, handler, context);
     }
   
     emit(event: string, ...args: any[]) {
       return this.events.emit(event, ...args);
     }
   }
   

2. Type-Safe Event Definitions:

   interface NetworkEvents {
     'connection:established': (peerId: string, metadata?: any) => void;
     'connection:closed': (peerId: string, reason?: string) => void;
     'message:received': (peerId: string, message: any) => void;
     'node:promoted': (newLevel: number, oldLevel: number) => void;
     'node:demoted': (newLevel: number, oldLevel: number) => void;
     'tier:reorganizing': (tierInfo: any) => void;
     'tier:reorganized': (tierInfo: any) => void;
   }
   
   class NetworkNode {
     private events: EventEmitter<NetworkEvents>;
     // ...implementation
   }
   

3. Testing Utilities: The Events library includes features such as getting event names and listener counts, which will be useful for testing.

BitPacker Library Integration

The @suaveplan/bitpacker library can be used for efficient binary serialization in several components, particularly in state synchronization.

Integration Points

1. State Synchronization:

   import { BitPacker } from '@suaveplan/bitpacker';
   
   class StateManager {
     private statePacker: BitPacker;
   
     constructor(stateSchema: any) {
       this.statePacker = new BitPacker(stateSchema);
     }
   
     serializeState(state: any): Uint8Array {
       return this.statePacker.pack(state);
     }
   
     deserializeState(data: Uint8Array): any {
       return this.statePacker.unpack(data);
     }
   }
   

2. Delta Compression for State Updates:

   import { GameBitPacker } from '@suaveplan/bitpacker';
   
   class DeltaStateManager {
     private gamePacker: GameBitPacker;
   
     constructor(stateSchema: any) {
       this.gamePacker = new GameBitPacker(stateSchema, {
         delta: true,
         enablePrediction: true
       });
     }
   
     updateState(state: any): void {
       this.gamePacker.update(state);
     }
   
     packFullState(): Uint8Array {
       return this.gamePacker.packState();
     }
   
     packDeltaState(): Uint8Array {
       return this.gamePacker.packDelta();
     }
   
     applyDelta(deltaData: Uint8Array): any {
       return this.gamePacker.applyDelta(deltaData);
     }
   }
   

3. Network Simulation for Testing:

   import { NetworkSimulation, NetworkCondition } from '@suaveplan/bitpacker';
   
   function createNetworkTestEnvironment() {
     return new NetworkSimulation({
       condition: NetworkCondition.MOBILE,
       packetLoss: 5,
       latencyMin: 50,
       latencyMax: 200
     });
   }
   

4. Schema Versioning and Migration: Leverage BitPacker's schema versioning capabilities for evolving state structures.

Crypto Library Integration

The @suaveplan/crypto library provides comprehensive cryptographic functionality that can be used for secure communications.

Integration Points

1. Message Signing and Verification:

   import { sign, verify } from '@suaveplan/crypto';
   
   class SecureMessageHandler {
     private secretKey: Uint8Array;
     private publicKeys: Map<string, Uint8Array>;
   
     async signMessage(message: any): Promise<any> {
       const serializedMessage = JSON.stringify(message);
       const signature = await sign(serializedMessage, this.secretKey);
       return {
         ...message,
         _signature: signature
       };
     }
   
     async verifyMessage(message: any, senderId: string): Promise<boolean> {
       const { _signature, ...messageContent } = message;
       const serializedContent = JSON.stringify(messageContent);
       const publicKey = this.publicKeys.get(senderId);
       if (!publicKey) return false;
   
       return await verify(_signature, serializedContent, publicKey);
     }
   }
   

2. Secure Transport Layer:

   import { encrypt, decrypt, box, boxOpen } from '@suaveplan/crypto';
   
   class SecureTransport {
     private secretKey: Uint8Array;
     private peerPublicKeys: Map<string, Uint8Array>;
   
     async sendEncrypted(data: any, peerId: string): Promise<Uint8Array> {
       const peerPublicKey = this.peerPublicKeys.get(peerId);
       if (!peerPublicKey) throw new Error('Unknown peer');
   
       const serialized = new TextEncoder().encode(JSON.stringify(data));
       return await box(serialized, peerPublicKey, this.secretKey);
     }
   
     async receiveEncrypted(data: Uint8Array): Promise<any> {
       const decrypted = await boxOpen(data, this.secretKey, 'utf8');
       return JSON.parse(decrypted);
     }
   }
   

3. Authentication Mechanisms: Leverage crypto's password hashing for optional password-protected sessions.

Keys Library Integration

The @suaveplan/keys library provides hierarchical key management that can be used for session ownership and authentication.

Integration Points

1. Session Ownership:

   import { createRootKeys, packPublicKeys } from '@suaveplan/keys';
   
   class SessionManager {
     async createSession(password: string): Promise<{ sessionId: string, ownerToken: string }> {
       // Create root keys for the session
       const [keys, vault, publicKeys] = await createRootKeys(password);
   
       // Session ID derived from the public key
       const sessionId = await generateSessionId(publicKeys);
   
       // Owner token is the vault
       const ownerToken = Buffer.from(vault).toString('base64');
   
       // Store public keys for verification
       await this.storeSessionPublicKeys(sessionId, publicKeys);
   
       return { sessionId, ownerToken };
     }
   
     async verifySessionOwner(sessionId: string, ownerToken: string, password: string): Promise<boolean> {
       try {
         const vault = Buffer.from(ownerToken, 'base64');
   
         // This will throw if password is incorrect or vault is tampered
         const keys = await unpackVault(vault, password);
   
         // Verify the keys match the session
         const storedPublicKeys = await this.getSessionPublicKeys(sessionId);
         const packedPublicKeys = await packPublicKeys(keys);
   
         // Compare public keys to confirm ownership
         return await this.comparePublicKeys(storedPublicKeys, packedPublicKeys);
       } catch (error) {
         return false;
       }
     }
   }
   

2. Session Participant Authentication: Use server keys derived from root keys to authenticate participants:

   import { createServerKeys, viewPublicKeys } from '@suaveplan/keys';
   
   class ParticipantManager {
     async createParticipantCredentials(rootKeys, participantId: string): Promise<string> {
       // Create unique server keys for this participant
       const password = await generateRandomPassword();
       const [keys, vault, publicKeys] = await createServerKeys(rootKeys, password);
   
       // Register this participant's public keys
       await this.registerParticipantPublicKeys(participantId, publicKeys);
   
       // Return credentials to the participant
       return JSON.stringify({
         vault: Buffer.from(vault).toString('base64'),
         password
       });
     }
   
     async authenticateParticipant(participantId: string, credentials: string): Promise<boolean> {
       const { vault, password } = JSON.parse(credentials);
   
       try {
         const vaultData = Buffer.from(vault, 'base64');
         const publicKeyData = await this.getParticipantPublicKeys(participantId);
         const publicKeys = await viewPublicKeys(publicKeyData);
   
         // This will throw if vault is invalid or password is incorrect
         const keys = await unpackVault(vaultData, password, publicKeys.sign);
   
         return true;
       } catch (error) {
         return false;
       }
     }
   }
   

3. Message Authorization Requirements:

   interface AuthorizationRequirement {
     // Action type requiring authorization
     action: string;
   
     // Whether owner signature is required
     requireOwner: boolean;
   
     // Required participant roles if any
     requiredRoles?: string[];
   }
   
   const authorizationRequirements: AuthorizationRequirement[] = [
     { action: 'tier:reorganize', requireOwner: true },
     { action: 'participant:remove', requireOwner: true },
     { action: 'message:broadcast', requireOwner: false }
   ];
   

Utils Library Integration

The @suaveplan/utils library provides various utility functions that can be used throughout the network implementation.

Integration Points

1. ID Generation:

   import { generateId } from '@suaveplan/utils';
   
   class NetworkNode {
     public readonly id: string;
   
     constructor() {
       this.id = generateId();
     }
   }
   

2. Debug Utilities:

   import { debug } from '@suaveplan/utils';
   
   class NetworkTracer {
     traceMessageFlow(message: any, path: string[]) {
       debug.time(`message-${message.id}`);
       debug.log(`Message ${message.id} following path: ${path.join(' -> ')}`);
       // ... processing
       debug.timeEnd(`message-${message.id}`);
     }
   }
   

3. Data Validation:

   import { isHex } from '@suaveplan/utils';
   
   function validateNodeId(id: string): boolean {
     // Node IDs must be valid hex strings of length 32
     return id.length === 32 && isHex(id);
   }
   

Implementation Strategy

Phase-by-Phase Integration

The following table outlines which existing libraries should be integrated in each phase:

Phase	Libraries to Integrate	Components
0	Events, Utils	Testing utilities, event system
1	Events, Utils	NetworkNode events, ID generation
2	Crypto, Utils	Transport security, debug utilities
3	Events, Utils	Message routing events, validation
4	Utils	Metrics and host selection
5	Events, Keys	Tier management events, session ownership
6	Events	Plugin system
7	BitPacker, Crypto	State serialization, compression
8	Utils	Monitoring and simulation
9	BitPacker	Serialization strategies
10	All	Integration testing, examples

Session Ownership Implementation

Based on the user's request to incorporate session ownership with public key verification, we recommend implementing this during Phase 5 (Tier Management) using the following approach:

1. Session Creation:

   • When a network session is created, generate root keys for the session owner
   • Store the vault securely with the owner
   • Distribute public keys to participants for verification

2. Host Authorization:

   • Require owner signature for critical operations like tier reorganization
   • Verify signatures using the public signing key

3. Participant Authentication:

   • Optionally issue participant-specific keys derived from root keys
   • Use server keys from the Keys library for different roles/tiers

// Example session creation in NetworkSystem
async createNetworkSession(ownerPassword: string): Promise<{ 
  sessionId: string,
  ownerCredentials: string,
  publicData: string
}> {
  // Create root keys for the session
  const [rootKeys, rootVault, rootPublicKeys] = await createRootKeys(ownerPassword);
  
  // Generate session ID from public key hash
  const sessionId = await generateSessionId(rootPublicKeys);
  
  // Owner credentials contain the encrypted vault
  const ownerCredentials = Buffer.from(rootVault).toString('base64');
  
  // Public data for participants to verify the session
  const publicData = Buffer.from(rootPublicKeys).toString('base64');
  
  // Initialize the network with these keys
  this.initializeWithKeys(sessionId, rootPublicKeys);
  
  return { sessionId, ownerCredentials, publicData };
}

Conclusion

Integrating these existing libraries will significantly reduce development time while ensuring consistency and security across the implementation. The most impactful integrations are:

1. Events Library for the standardized event system
2. BitPacker Library for efficient state serialization and delta compression
3. Keys and Crypto Libraries for security, session ownership, and authentication

By leveraging these libraries, we can focus development efforts on the unique aspects of the network architecture while relying on proven implementations for common functionality.