444 lines
14 KiB
Markdown
444 lines
14 KiB
Markdown
# 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](#events-library-integration)**: Type-safe event emitter implementation
|
|
2. **[BitPacker Library](#bitpacker-library-integration)**: Binary serialization with schema validation and delta compression
|
|
3. **[Crypto Library](#crypto-library-integration)**: Comprehensive cryptography utilities
|
|
4. **[Keys Library](#keys-library-integration)**: Hierarchical key management system
|
|
5. **[Utils Library](#utils-library-integration)**: 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**:
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```typescript
|
|
import { generateId } from '@suaveplan/utils';
|
|
|
|
class NetworkNode {
|
|
public readonly id: string;
|
|
|
|
constructor() {
|
|
this.id = generateId();
|
|
}
|
|
}
|
|
```
|
|
|
|
2. **Debug Utilities**:
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
// 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.
|