@skillkit/mesh


Peer mesh network for SkillKit - Multi-machine agent distribution with secure peer-to-peer communication.

Installation

``bash
npm install @skillkit/mesh
`

Key Features

- Peer Discovery: UDP multicast LAN discovery with signed announcements
- Multi-Transport: HTTP, WebSocket, and UDP transport layers
- Ed25519 Cryptography: Peer identity, message signing, and verification
- XChaCha20-Poly1305: End-to-end message encryption
- TLS Support: Self-signed certificates for secure transport
- JWT Authentication: Challenge-response handshake with EdDSA tokens
- Health Monitoring: Automatic peer health checks with latency tracking
- Trust Management: Peer trust/revoke with fingerprint-based verification

Usage

$3

`typescript
import { MeshHost, PeerIdentity, MeshSecurityConfig } from '@skillkit/mesh';

// Generate or load identity
const identity = await PeerIdentity.generate();
console.log('Fingerprint:', identity.fingerprint);

// Configure security
const security: MeshSecurityConfig = {
discovery: { mode: 'signed' },
transport: { encryption: 'required', tls: 'self-signed', requireAuth: true },
trust: { autoTrustFirst: true },
};

// Create mesh host
const host = new MeshHost({
hostId: 'my-workstation',
identity,
security,
});

await host.start();
`

$3

`typescript
import { LocalDiscovery } from '@skillkit/mesh';

// Start discovery
const discovery = new LocalDiscovery({
identity,
port: 41234,
});

discovery.on('peer', (peer) => {
console.log('Found peer:', peer.hostId, peer.fingerprint);
});

await discovery.start();
await discovery.announce();
`

$3

`typescript
// Send to a specific peer
await host.send('peer-fingerprint', {
type: 'skill-sync',
payload: { skills: ['react-patterns', 'api-design'] },
});

// Broadcast to all peers
await host.broadcast({
type: 'announcement',
payload: { message: 'New skill available' },
});
`

$3

`typescript
import { SecureWebSocketTransport, TLSManager } from '@skillkit/mesh';

// Generate TLS certificate
const certInfo = await TLSManager.generateCertificate(identity, 'my-host');

// Create secure WebSocket transport
const transport = new SecureWebSocketTransport({
port: 8443,
tls: {
cert: certInfo.cert,
key: certInfo.key,
},
requireAuth: true,
});

await transport.listen();
`

$3

`typescript
import { SecureKeystore } from '@skillkit/mesh';

// Initialize keystore
const keystore = new SecureKeystore({
path: '~/.skillkit/mesh/identity',
});

// Trust a peer
await keystore.addTrustedPeer(peerFingerprint, peerPublicKey);

// Revoke trust
await keystore.revokePeer(peerFingerprint);

// List trusted peers
const trusted = await keystore.getTrustedPeers();
`

Security Levels

| Level | Discovery | Transport | Auth | Use Case |
|-------|-----------|-----------|------|----------|
| development | open | none | none | Local dev |
| signed | signed | optional | optional | Trusted LAN |
| secure (default) | signed | required | required | Production |
| strict | trusted-only | required | mTLS | High security |

API Reference

$3

`typescript
interface MeshHost {
start(): Promise;
stop(): Promise;
send(peerId: string, message: TransportMessage): Promise;
broadcast(message: TransportMessage): Promise;
getPeers(): PeerInfo[];
on(event: 'message' | 'peer' | 'disconnect', handler: Function): void;
}
`

$3

`typescript
interface PeerIdentity {
static generate(): Promise;
static fromPrivateKey(key: Uint8Array): Promise;
static load(path: string, passphrase?: string): Promise;
save(path: string, passphrase?: string): Promise;
sign(message: Uint8Array): Promise;
static verify(sig: Uint8Array, msg: Uint8Array, pubKey: Uint8Array): Promise;
deriveSharedSecret(peerPublicKey: Uint8Array): Uint8Array;
get publicKey(): Uint8Array;
get fingerprint(): string;
}
`

$3

`typescript
interface PeerInfo {
hostId: string;
fingerprint: string;
address: string;
port: number;
status: 'online' | 'offline';
latency?: number;
}

interface TransportMessage {
type: string;
payload: unknown;
signature?: string;
senderFingerprint?: string;
}

interface MeshSecurityConfig {
discovery: { mode: 'open' | 'signed' | 'trusted-only' };
transport: { encryption: 'none' | 'optional' | 'required'; tls: 'none' | 'self-signed' | 'ca-signed'; requireAuth: boolean };
trust: { autoTrustFirst: boolean; requireManualApproval?: boolean; trustedFingerprints?: string[] };
}
`

CLI Commands

`bash
skillkit mesh init # Initialize mesh network
skillkit mesh add