@hive-p2p/server 1.0.19 → 1.0.21

package/core/gossip.mjs

@@ -0,0 +1,159 @@
+import { CLOCK, GOSSIP, DISCOVERY } from './config.mjs';
+import { xxHash32 } from '../libs/xxhash32.mjs';
+
+export class GossipMessage { // TYPE DEFINITION
+	topic = 'gossip';
+	timestamp;
+	neighborsList;
+	HOPS;
+	senderId;
+	pubkey;
+	data;
+	signature;
+	signatureStart; // position in the serialized message where the signature starts
+	expectedEnd; // expected length of the serialized message
+
+	/** @param {string} topic @param {number} timestamp @param {string[]} neighborsList @param {number} HOPS @param {string} senderId @param {string} pubkey @param {string | Uint8Array | Object} data @param {string | undefined} signature @param {number} signatureStart @param {number} expectedEnd */
+	constructor(topic, timestamp, neighborsList, HOPS, senderId, pubkey, data, signature, signatureStart, expectedEnd) {
+		this.topic = topic; this.timestamp = timestamp; this.neighborsList = neighborsList;
+		this.HOPS = HOPS; this.senderId = senderId; this.pubkey = pubkey; this.data = data;
+		this.signature = signature; this.signatureStart = signatureStart; this.expectedEnd = expectedEnd;
+	}
+}
+
+/** - 'BloomFilterCacheEntry' Definition
+ * @typedef {Object} BloomFilterCacheEntry
+ * @property {string} hash
+ * @property {string} senderId
+ * @property {string} topic
+ * @property {Uint8Array} serializedMessage
+ * @property {number} expiration
+ */
+class DegenerateBloomFilter {
+	cryptoCodex;
+	xxHash32UsageCount = 0;
+	/** @type {Record<string, number>} */
+	seenTimeouts = {}; // Map of message hashes to their expiration timestamps
+	
+	/** @type {BloomFilterCacheEntry[]} */ cache = [];
+	cleanupFrequency = 100;
+	cleanupIn = 100;
+	cleanupDurationWarning = 10;
+
+	/** @param {import('./crypto-codex.mjs').CryptoCodex} cryptoCodex */
+	constructor(cryptoCodex) { this.cryptoCodex = cryptoCodex; }
+
+	// PUBLIC API
+	/** @param {'asc' | 'desc'} order */
+	getGossipHistoryByTime(order = 'asc') {
+		const lightenHistory = this.cache.map(e => ({ senderId: e.senderId, topic: e.topic, data: e.serializedMessage }));
+		return order === 'asc' ? lightenHistory : lightenHistory.reverse();
+	}
+	/** @param {Uint8Array} serializedMessage */
+	addMessage(serializedMessage) {
+    	const n = CLOCK.time;
+		const { marker, neighLength, timestamp, dataLength, pubkey, associatedId } = this.cryptoCodex.readBufferHeader(serializedMessage);
+		if (n - timestamp > GOSSIP.EXPIRATION) return;
+
+		const hashableData = serializedMessage.subarray(0, 47 + neighLength + dataLength);
+		const h = xxHash32(hashableData);
+		this.xxHash32UsageCount++;
+		if (this.seenTimeouts[h]) return;
+
+		const topic = GOSSIP.MARKERS_BYTES[marker];
+		const senderId = associatedId;
+		const expiration = n + GOSSIP.CACHE_DURATION;
+		this.cache.push({ hash: h, senderId, topic, serializedMessage, timestamp, expiration });
+		this.seenTimeouts[h] = expiration;
+
+		if (--this.cleanupIn <= 0) this.#cleanupOldestEntries(n);
+		return { hash: h, isNew: !this.seenTimeouts[h] };
+	}
+	#cleanupOldestEntries(n = CLOCK.time) {
+		let firstValidIndex = -1;
+		for (let i = 0; i < this.cache.length; i++)
+			if (this.cache[i].expiration <= n) delete this.seenTimeouts[this.cache[i].hash];
+			else if (firstValidIndex === -1) firstValidIndex = i;
+		
+		if (firstValidIndex > 0) this.cache = this.cache.slice(firstValidIndex);
+		else if (firstValidIndex === -1) this.cache = [];
+		this.cleanupIn = this.cleanupFrequency;
+	}
+}
+
+export class Gossip {
+	/** @type {Record<string, Function[]>} */ callbacks = { message_handle: [] };
+	id; cryptoCodex; arbiter; peerStore; verbose; bloomFilter;
+
+	/** @param {string} selfId @param {import('./crypto-codex.mjs').CryptoCodex} cryptoCodex @param {import('./arbiter.mjs').Arbiter} arbiter @param {import('./peer-store.mjs').PeerStore} peerStore */
+	constructor(selfId, cryptoCodex, arbiter, peerStore, verbose = 0) {
+		this.id = selfId;
+		this.cryptoCodex = cryptoCodex;
+		this.arbiter = arbiter;
+		this.peerStore = peerStore;
+		this.verbose = verbose;
+		this.bloomFilter = new DegenerateBloomFilter(cryptoCodex);
+	}
+
+	/** @param {string} callbackType @param {Function} callback */
+	on(callbackType, callback) {
+		if (!this.callbacks[callbackType]) this.callbacks[callbackType] = [callback];
+		else this.callbacks[callbackType].push(callback);
+	}
+	/** Gossip a message to all connected peers > will be forwarded to all peers
+	 * @param {string | Uint8Array | Object} data @param {string} topic @param {number} [HOPS] */
+	broadcastToAll(data, topic = 'gossip', HOPS) {
+		const hops = HOPS || GOSSIP.HOPS[topic] || GOSSIP.HOPS.default;
+		const serializedMessage = this.cryptoCodex.createGossipMessage(topic, data, hops, this.peerStore.neighborsList);
+		if (!this.bloomFilter.addMessage(serializedMessage)) return; // avoid sending duplicate messages
+		if (this.verbose > 3) console.log(`(${this.id}) Gossip ${topic}, to ${JSON.stringify(this.peerStore.neighborsList)}: ${data}`);
+		for (const peerId of this.peerStore.neighborsList) this.#broadcastToPeer(peerId, serializedMessage);
+	}
+	/** @param {string} targetId @param {any} serializedMessage */
+	#broadcastToPeer(targetId, serializedMessage) {
+		if (targetId === this.id) throw new Error(`Refusing to send a gossip message to self (${this.id}).`);
+		const transportInstance = this.peerStore.connected[targetId]?.transportInstance;
+		if (!transportInstance) return { success: false, reason: `Transport instance is not available for peer ${targetId}.` };
+		try { transportInstance.send(serializedMessage); }
+		catch (error) { this.peerStore.connected[targetId]?.close(); }
+	}
+	sendGossipHistoryToPeer(peerId) {
+		const gossipHistory = this.bloomFilter.getGossipHistoryByTime('asc');
+		for (const entry of gossipHistory) this.#broadcastToPeer(peerId, entry.data);
+	}
+	/** @param {string} from @param {Uint8Array} serialized @returns {void} */
+	async handleGossipMessage(from, serialized) {
+		if (this.arbiter.isBanished(from)) return this.verbose >= 3 ? console.info(`%cReceived gossip message from banned peer ${from}, ignoring.`, 'color: red;') : null;
+		if (!this.arbiter.countMessageBytes(from, serialized.byteLength, 'gossip')) return; // ignore if flooding/banished
+		for (const cb of this.callbacks.message_handle || []) cb(serialized); // Simulator counter before filtering
+		if (!this.bloomFilter.addMessage(serialized)) return; // already processed this message
+
+		const message = this.cryptoCodex.readGossipMessage(serialized);
+		if (!message) return this.arbiter.countPeerAction(from, 'WRONG_SERIALIZATION');
+		await this.arbiter.digestMessage(from, message, serialized);
+		if (this.arbiter.isBanished(from)) return; // ignore messages from banished peers
+		if (this.arbiter.isBanished(message.senderId)) return; // ignore messages from banished peers
+
+		const { topic, timestamp, neighborsList, HOPS, senderId, data } = message;
+		if (senderId === this.id) throw new Error(`#${this.id}#${from}# Received our own message back from peer ${from}.`);
+		
+		if (this.verbose > 3) // LOGGING
+			if (senderId === from) console.log(`(${this.id}) Gossip ${topic} from ${senderId}: ${data}`);
+			else console.log(`(${this.id}) Gossip ${topic} from ${senderId} (by: ${from}): ${data}`);
+
+		this.peerStore.digestPeerNeighbors(senderId, neighborsList);
+		for (const cb of this.callbacks[topic] || []) cb(senderId, data, HOPS, message); // specific topic callback
+		if (HOPS < 1) return; // stop forwarding if HOPS is 0
+
+		const nCount = this.peerStore.neighborsList.length;
+		const trm = Math.max(1, nCount / GOSSIP.TRANSMISSION_RATE.NEIGHBOURS_PONDERATION);
+		const tRateBase = GOSSIP.TRANSMISSION_RATE[topic] || GOSSIP.TRANSMISSION_RATE.default;
+		const transmissionRate = Math.pow(tRateBase, trm);
+		const avoidTransmissionRate = nCount < GOSSIP.TRANSMISSION_RATE.MIN_NEIGHBOURS_TO_APPLY_PONDERATION;
+		const serializedToTransmit = this.cryptoCodex.decrementGossipHops(serialized);
+		for (const peerId of this.peerStore.neighborsList)
+			if (peerId === from) continue; // avoid sending back to sender
+			else if (!avoidTransmissionRate && Math.random() > transmissionRate) continue; // apply gossip transmission rate
+			else this.#broadcastToPeer(peerId, serializedToTransmit);
+	}
+}

package/core/ice-offer-manager.mjs

@@ -0,0 +1,181 @@
+import { CLOCK, NODE, TRANSPORTS, LOG_CSS } from './config.mjs';
+import { xxHash32 } from '../libs/xxhash32.mjs';
+async function getWrtc() {
+    if (typeof globalThis.RTCPeerConnection !== 'undefined') return undefined;
+    return (await import('wrtc')).default;
+}
+const wrtc = await getWrtc();
+
+/** - 'OfferObj' Definition
+ * @typedef {Object} OfferObj
+ * @property {number} timestamp
+ * @property {boolean} isUsed // => if true => should be deleted
+ * @property {number} sentCounter
+ * @property {Object} signal
+ * @property {import('simple-peer').Instance} offererInstance
+ * @property {boolean} isDigestingOneAnswer Flag to avoid multiple answers handling at the same time (DISCOVERY.LOOP_DELAY (2.5s) will be doubled (5s) between two answers handling)
+ * @property {Array<{peerId: string, signal: any, timestamp: number, used: boolean}>} answers
+ * @property {Record<string, boolean>} answerers key: peerId, value: true */
+
+export class OfferManager { // Manages the creation of SDP offers and handling of answers
+	id;
+	verbose;
+	stunUrls;
+
+	/** @param {string} id @param {Array<{urls: string}>} stunUrls */
+	constructor(id, stunUrls, verbose = 0) { this.id = id; this.verbose = verbose; this.stunUrls = stunUrls; }
+
+	onSignalAnswer = null; 		// function(remoteId, signalData, offerHash)
+	onConnect = null; 			// function(remoteId, transportInstance)
+	
+	/** @type {Record<number, import('simple-peer').Instance>} key: expiration timestamp */
+	offerInstanceByExpiration = {};
+	creatingOffer = false; 		// flag to avoid multiple simultaneous creations (shared between all offers)
+	offerCreationTimeout = null; // sequential creation timeout (shared between all offers)
+	offersToCreate = TRANSPORTS.MAX_SDP_OFFERS;
+	/** @type {Record<string, OfferObj>} key: offerHash **/ offers = {};
+
+	tick() { // called in peerStore to avoid multiple intervals
+		const now = CLOCK.time;
+		// CLEAR EXPIRED CREATOR OFFER INSTANCES
+		for (const expiration in this.offerInstanceByExpiration) {
+			const instance = this.offerInstanceByExpiration[expiration];
+			if (now < expiration) continue; // not expired yet
+			instance?.destroy();
+			delete this.offerInstanceByExpiration[expiration];
+			this.creatingOffer = false; // release flag
+		}
+			
+		// CLEAR USED AND EXPIRED OFFERS
+		for (const hash in this.offers) {
+			const offer = this.offers[hash];
+			if (offer.offererInstance.destroyed) { delete this.offers[hash]; continue; } // offerer destroyed
+			if (offer.isUsed) { delete this.offers[hash]; continue; } // used offer => remove it (handled by peerStore)
+			if (offer.timestamp + TRANSPORTS.SDP_OFFER_EXPIRATION > now) continue; // not expired yet
+			offer.offererInstance?.destroy();
+			delete this.offers[hash];
+		}
+
+		// TRY TO USE AVAILABLE ANSWERS
+		let offerCount = 0;
+		for (const hash in this.offers) {
+			offerCount++; // [live at the first line of the loop] used just below -> avoid Object.keys() call
+			const offer = this.offers[hash];
+			if (offer.isDigestingOneAnswer) { offer.isDigestingOneAnswer = false; continue; }
+			if (offer.offererInstance.destroyed) continue; // offerer destroyed
+			
+			const unusedAnswers = offer.answers.filter(a => !a.used);
+			if (!unusedAnswers.length) continue; // no answers available
+			
+			const newestAnswer = unusedAnswers.reduce((a, b) => a.timestamp > b.timestamp ? a : b);
+			if (!newestAnswer) continue; // all answers are used
+
+			newestAnswer.used = true;
+			const receivedSince = now - newestAnswer.timestamp;
+			if (receivedSince > NODE.CONNECTION_UPGRADE_TIMEOUT / 2) continue; // remote peer will break the connection soon, don't use this answer
+			offer.offererInstance.signal(newestAnswer.signal);
+			offer.isDigestingOneAnswer = true;
+			if (this.verbose > 2) console.log(`(${this.id}) Using answer from ${newestAnswer.peerId} for offer ${hash} (received since ${receivedSince} ms)`);
+		}
+
+		if (this.creatingOffer) return; // already creating one or unable to send
+		if (offerCount >= this.offersToCreate) return; // already have enough offers
+		
+		// CREATE NEW OFFER
+		this.creatingOffer = true;
+		const expiration = now + (TRANSPORTS.SIGNAL_CREATION_TIMEOUT || 8_000);
+		const instance = this.#createOffererInstance(expiration);
+		this.offerInstanceByExpiration[expiration] = instance;
+	};
+	#createOffererInstance(expiration) {
+		const iceCompleteTimeout = TRANSPORTS.ICE_COMPLETE_TIMEOUT || 1_000;
+		const instance = new TRANSPORTS.PEER({ initiator: true, trickle: false, iceCompleteTimeout, wrtc, config: { iceServers: this.stunUrls } });
+		instance.on('error', error => this.#onError(error));
+		instance.on('signal', data => { // trickle: false => only one signal event with the full offer
+			const { candidate, type } = data; // with trickle, we need to adapt the approach.
+			if (!data || candidate) throw new Error('Unexpected signal data from offerer instance: ' + JSON.stringify(data));
+			if (type !== 'offer') throw new Error('Unexpected signal type from offerer instance: ' + type);
+			
+			// OFFER READY
+			delete this.offerInstanceByExpiration[expiration];
+			const offerHash = xxHash32(JSON.stringify(data)); // UN PEU BLOQUE ICI (connect on voudrait identifer le peer)
+			instance.on('connect', () => { // cb > peerStore > Node > Node.#onConnect()
+				if (this.offers[offerHash]) this.offers[offerHash].isUsed = true;
+				this.onConnect(undefined, instance);
+			});
+			this.offers[offerHash] = { timestamp: CLOCK.time, sentCounter: 0, signal: data, offererInstance: instance, answers: [], answerers: {}, isUsed: false };
+			this.creatingOffer = false; // release flag
+		});
+
+		return instance;
+	}
+	/** @param {Error} error @param {string} incl @param {number} level @param {'includes' | 'startsWith'} searchMode (Prefer 'startsWith' for performance) */
+	#logAndOrIgnore(error, incl = '', level = 2, searchMode = 'includes') { // if false => log it fully, if true => ignore it (message logged or ignored based on level)
+		if (searchMode[0] === 'i' && !error.message.includes(incl)) return false;
+		else if (!error.message.startsWith(incl)) return false;
+		if (this.verbose >= level) console.info(`%cOfferManager => ${error.message}`, LOG_CSS.PEER_STORE);
+		return true;
+	}
+	#onError = (error) => {
+		if (this.verbose < 1) return; // avoid logging
+		// PRODUCTION (SimplePeer ERRORS) --|
+		if (this.#logAndOrIgnore(error, 'Ice connection failed', 2)) return;
+		if (this.#logAndOrIgnore(error, 'Connection failed', 2)) return;
+		// --PRODUCTION ----------------- --|
+
+		if (this.#logAndOrIgnore(error, 'Remote transport instance', 3, 'startsWith')) return;
+		if (this.#logAndOrIgnore(error, 'Simulated failure', 4, 'startsWith')) return;
+		if (this.#logAndOrIgnore(error, 'No peer found', 4, 'startsWith')) return;
+		if (this.#logAndOrIgnore(error, 'Missing transport instance', 2, 'startsWith')) return;
+		if (this.#logAndOrIgnore(error, 'Failed to create answer', 2, 'startsWith')) return;
+		if (this.#logAndOrIgnore(error, 'Transport instance', 3, 'startsWith')) return;
+		if (this.#logAndOrIgnore(error, 'cannot signal after peer is destroyed', 3, 'startsWith')) return;
+		if (this.#logAndOrIgnore(error, 'No pending', 3)) return;
+		if (this.#logAndOrIgnore(error, 'is already linked', 3)) return;
+		if (this.#logAndOrIgnore(error, 'There is already a pending', 3)) return;
+		if (this.#logAndOrIgnore(error, 'closed the connection', 3)) return;
+		if (this.#logAndOrIgnore(error, 'No transport instance found for id:', 3)) return;
+
+		if (this.verbose > 0) console.error(`transportInstance ERROR => `, error.stack);
+	};
+	/** @param {string} remoteId @param {{type: 'answer', sdp: Record<string, string>}} signal @param {string} offerHash @param {number} timestamp receptionTimestamp */
+	addSignalAnswer(remoteId, signal, offerHash, timestamp) {
+		if (!signal || signal.type !== 'answer' || !offerHash) return; // ignore non-answers or missing offerHash
+		if (!this.offers[offerHash] || this.offers[offerHash].answerers[remoteId]) return; // already have an answer from this peerId
+		this.offers[offerHash].answerers[remoteId] = true; // mark as having answered - one answer per peerId
+		this.offers[offerHash].answers.push({ peerId: remoteId, signal, timestamp });
+		if (this.verbose > 3) console.log(`(OfferManager) Added answer from ${remoteId} for offer ${offerHash}`);
+	}
+	/** @param {string} remoteId @param {{type: 'offer' | 'answer', sdp: Record<string, string>}} signal @param {string} [offerHash] offer only */
+	getTransportInstanceForSignal(remoteId, signal, offerHash) {
+		try {
+			if (!signal || !signal.type || !signal.sdp) throw new Error('Wrong remote SDP provided');
+			
+			const { type, sdp } = signal;
+			if (type !== 'offer' && type !== 'answer') throw new Error('Invalid remote SDP type');
+			if (type === 'offer' && !sdp) throw new Error('No SDP in the remote SDP offer');
+			if (type === 'answer' && !sdp) throw new Error('No SDP in the remote SDP answer');
+			
+			if (type === 'answer') { // NEED TO FIND THE PENDING OFFERER INSTANCE
+				const instance = offerHash ? this.offers[offerHash]?.offererInstance : null;
+				if (!instance) throw new Error('No pending offer found for the given offer hash to accept the answer');
+				return instance;
+			}
+			
+			// type === 'offer' => CREATE ANSWERER INSTANCE
+			const iceCompleteTimeout = TRANSPORTS.ICE_COMPLETE_TIMEOUT || 1_000;
+			const instance = new TRANSPORTS.PEER({ initiator: false, trickle: false, iceCompleteTimeout, wrtc, config: { iceServers: this.stunUrls } });
+			instance.on('error', (error) => this.#onError(error));
+			instance.on('signal', (data) => this.onSignalAnswer(remoteId, data, offerHash));
+			instance.on('connect', () => this.onConnect(remoteId, instance));
+			return instance;
+		} catch (error) {
+			if (error.message.startsWith('No pending offer found') && this.verbose < 2) return null; // avoid logging
+			if (this.verbose > 1 && error.message.startsWith('No pending offer found')) return console.info(`%c${error.message}`, LOG_CSS.PEER_STORE);
+			if (this.verbose > 0) console.error(error.stack);
+		}
+	}
+	destroy() {
+		for (const offerHash in this.offers) this.offers[offerHash].offererInstance?.destroy();
+	}
+}

package/core/node-services.mjs

@@ -0,0 +1,129 @@
+import { SIMULATION, NODE, SERVICE, TRANSPORTS, DISCOVERY, LOG_CSS } from './config.mjs';
+import { PeerConnection } from './peer-store.mjs';
+import { Converter } from '../services/converter.mjs';
+const dgram = !NODE.IS_BROWSER ? await import('dgram') : null;
+/*const dgram = !NODE.IS_BROWSER ? 
+  await import('dgram').catch(() => null) : 
+  null;*/
+
+export class NodeServices {
+	id;
+	verbose;
+	maxKick;
+	peerStore;
+	cryptoCodex;
+	/** @type {string | undefined} WebSocket URL (public node only) */ publicUrl;
+
+	/** @param {import('./crypto-codex.mjs').CryptoCodex} cryptoCodex @param {import('./peer-store.mjs').PeerStore} peerStore */
+	constructor(cryptoCodex, peerStore, maxKick = 3, verbose = 1) {
+		this.id = cryptoCodex.id;
+		this.verbose = verbose;
+		this.maxKick = maxKick;
+		this.peerStore = peerStore;
+		this.cryptoCodex = cryptoCodex;
+	}
+	
+	start(domain = 'localhost', port = SERVICE.PORT) {
+		this.publicUrl = `ws://${domain}:${port}`;
+		this.#startWebSocketServer(domain, port);
+		if (!SIMULATION.USE_TEST_TRANSPORTS) this.#startSTUNServer(domain, port + 1);
+	}
+	freePublicNodeByKickingPeers() {
+		const maxKick = Math.min(this.maxKick, this.peerStore.neighborsList.length - DISCOVERY.TARGET_NEIGHBORS_COUNT);
+		if (maxKick <= 0) return; // nothing to do
+		
+		let kicked = 0;
+		const delay = SERVICE.AUTO_KICK_DELAY;
+		for (const peerId  in this.peerStore.connected) {
+			const conn = this.peerStore.connected[peerId];
+			const nonPublicNeighborsCount = this.peerStore.getUpdatedPeerConnectionsCount(peerId, false);
+			if (nonPublicNeighborsCount > DISCOVERY.TARGET_NEIGHBORS_COUNT) { // OVER CONNECTED
+				this.peerStore.kickPeer(peerId, SERVICE.AUTO_KICK_DURATION, 'freePublicNode');
+				if (this.peerStore.neighborsList.length <= DISCOVERY.TARGET_NEIGHBORS_COUNT) break;
+				else continue; // Don't count in maxKick
+			}
+
+			if (conn.getConnectionDuration() < (nonPublicNeighborsCount > 2 ? delay : delay * 2)) continue;
+			this.peerStore.kickPeer(peerId, SERVICE.AUTO_KICK_DURATION, 'freePublicNode');
+			if (++kicked >= maxKick) break;
+		}
+	}
+	#startWebSocketServer(domain = 'localhost', port = SERVICE.PORT) {
+		this.wsServer = new TRANSPORTS.WS_SERVER({ port, host: domain });
+		this.wsServer.on('error', (error) => console.error(`WebSocket error on Node #${this.id}:`, error));
+		this.wsServer.on('connection', (ws) => {
+			ws.on('close', () => { if (remoteId) for (const cb of this.peerStore.callbacks.disconnect) cb(remoteId, 'in'); });
+			ws.on('error', (error) => console.error(`WebSocket error on Node #${this.id} with peer ${remoteId}:`, error.stack));
+
+			let remoteId;
+			ws.on('message', (data) => { // When peer proves his id, we can handle data normally
+				if (remoteId) for (const cb of this.peerStore.callbacks.data) cb(remoteId, data);
+				else { // FIRST MESSAGE SHOULD BE HANDSHAKE WITH ID
+					const d = new Uint8Array(data); if (d[0] > 127) return; // not unicast, ignore
+					const { route, type, neighborsList } = this.cryptoCodex.readUnicastMessage(d) || {};
+					if (type !== 'handshake' || route.length !== 2 || route[1] !== this.id) return;
+
+					remoteId = route[0];
+					this.peerStore.digestPeerNeighbors(remoteId, neighborsList); // Update known store
+					this.peerStore.connecting[remoteId]?.out?.close(); // close outgoing connection if any
+					if (!this.peerStore.connecting[remoteId]) this.peerStore.connecting[remoteId] = {};
+					this.peerStore.connecting[remoteId].in = new PeerConnection(remoteId, ws, 'in', true);
+					for (const cb of this.peerStore.callbacks.connect) cb(remoteId, 'in');
+				}
+			});
+		});
+	}
+	#startSTUNServer(host = 'localhost', port = SERVICE.PORT + 1) {
+		this.stunServer = dgram.createSocket('udp4');
+		this.stunServer.on('message', (msg, rinfo) => {
+			if (this.verbose > 2) console.log(`%cSTUN message from ${rinfo.address}:${rinfo.port} - ${msg.toString('hex')}`, LOG_CSS.SERVICE);
+			if (!this.#isValidSTUNRequest(msg)) return;
+			this.stunServer.send(this.#buildSTUNResponse(msg, rinfo), rinfo.port, rinfo.address);
+		});
+		this.stunServer.bind(port, host);
+	}
+	#isValidSTUNRequest(msg) {
+		if (msg.length < 20) return false;
+		const messageType = msg.readUInt16BE(0);
+		const magicCookie = msg.readUInt32BE(4);
+		return messageType === 0x0001 && magicCookie === 0x2112A442;
+	}
+	#buildSTUNResponse(request, rinfo) {
+		const transactionId = request.subarray(8, 20); // copy the 12 bytes
+
+		// Header : Success Response (0x0101) + length + magic + transaction
+		const response = Buffer.allocUnsafe(32); // 20 header + 12 attribute
+		response.writeUInt16BE(0x0101, 0);     // Binding Success Response
+		response.writeUInt16BE(12, 2);         // Message Length (12 bytes d'attributs)
+		response.writeUInt32BE(0x2112A442, 4); // Magic Cookie
+		transactionId.copy(response, 8);       // Transaction ID
+		
+		// Attribut MAPPED-ADDRESS (8 bytes)
+		response.writeUInt16BE(0x0001, 20);    // Type: MAPPED-ADDRESS
+		response.writeUInt16BE(8, 22);         // Length: 8 bytes
+		response.writeUInt16BE(0x0001, 24);    // Family: IPv4
+		response.writeUInt16BE(rinfo.port, 26); // Port
+		response.writeUInt32BE(Converter.ipToInt(rinfo.address), 28); // IP
+		
+		if (this.verbose > 2) console.log(`%cSTUN Response: client will discover IP ${rinfo.address}:${rinfo.port}`, 'color: green;');
+		return response;
+	}
+	/** @param {Array<{id: string, publicUrl: string}>} bootstraps */
+	static deriveSTUNServers(bootstraps, includesCentralized = false) {
+		/** @type {Array<{urls: string}>} */
+		const stunUrls = [];
+		for (const b of bootstraps) {
+			const domain = b.publicUrl.split(':')[1].replace('//', '');
+			const port = parseInt(b.publicUrl.split(':')[2]) + 1;
+			stunUrls.push({ urls: `stun:${domain}:${port}` });
+		}
+		if (!includesCentralized) return stunUrls;
+
+		// CENTRALIZED STUN SERVERS FALLBACK (GOOGLE) - OPTIONAL
+		this.stunUrls.push({ urls: 'stun:stun.l.google.com:5349' });
+		this.stunUrls.push({ urls: 'stun:stun.l.google.com:19302' });
+		this.stunUrls.push({ urls: 'stun:stun1.l.google.com:3478' });
+		this.stunUrls.push({ urls: 'stun:stun1.l.google.com:5349' });
+		return stunUrls;
+	}
+}

package/core/node.mjs

@@ -0,0 +1,177 @@
+import { CLOCK, SIMULATION, NODE, SERVICE, DISCOVERY } from './config.mjs';
+import { Arbiter } from './arbiter.mjs';
+import { OfferManager } from './ice-offer-manager.mjs';
+import { PeerStore } from './peer-store.mjs';
+import { UnicastMessager } from './unicast.mjs';
+import { Gossip } from './gossip.mjs';
+import { Topologist } from './topologist.mjs';
+import { CryptoCodex } from './crypto-codex.mjs';
+import { NodeServices } from './node-services.mjs';
+
+/** Create and start a new PublicNode instance.
+ * @param {Object} options
+ * @param {Array<{id: string, publicUrl: string}>} options.bootstraps List of bootstrap nodes used as P2P network entry
+ * @param {boolean} [options.autoStart] If true, the node will automatically start after creation (default: true)
+ * @param {CryptoCodex} [options.cryptoCodex] Identity of the node; if not provided, a new one will be generated
+ * @param {string} [options.domain] If provided, the node will operate as a public node and start necessary services (e.g., WebSocket server)
+ * @param {number} [options.port] If provided, the node will listen on this port (default: SERVICE.PORT)
+ * @param {number} [options.verbose] Verbosity level for logging (default: NODE.DEFAULT_VERBOSE) */
+export async function createPublicNode(options) {		
+	const verbose = options.verbose !== undefined ? options.verbose : NODE.DEFAULT_VERBOSE;
+	const domain = options.domain || undefined;
+	const codex = options.cryptoCodex || new CryptoCodex(undefined, verbose);
+	if (!codex.publicKey) await codex.generate(domain ? true : false);
+	
+	const node = new Node(codex, options.bootstraps || [], verbose);
+	if (domain) {
+		node.services = new NodeServices(codex, node.peerStore, undefined, verbose);
+		node.services.start(domain, options.port || SERVICE.PORT);
+		node.topologist.services = node.services;
+	}
+	if (options.autoStart !== false) await node.start();
+	return node;
+}
+
+/** Create and start a new Node instance.
+ * @param {Object} options
+ * @param {Array<{id: string, publicUrl: string}>} options.bootstraps List of bootstrap nodes used as P2P network entry
+ * @param {CryptoCodex} [options.cryptoCodex] Identity of the node; if not provided, a new one will be generated
+ * @param {boolean} [options.autoStart] If true, the node will automatically start after creation (default: true)
+ * @param {number} [options.verbose] Verbosity level for logging (default: NODE.DEFAULT_VERBOSE) */
+export async function createNode(options = {}) {
+	const verbose = options.verbose !== undefined ? options.verbose : NODE.DEFAULT_VERBOSE;
+	const codex = options.cryptoCodex || new CryptoCodex(undefined, verbose);
+	if (!codex.publicKey) await codex.generate(false);
+
+	const node = new Node(codex, options.bootstraps || [], verbose);
+	if (options.autoStart !== false) await node.start();
+	return node;
+}
+
+export class Node {
+	started = false;
+	id; cryptoCodex; verbose; arbiter;
+	/** class managing ICE offers */ offerManager;
+	/** class managing network connections */ peerStore;
+	/** class who manage direct messages */ messager;
+	/** class who manage gossip messages */ gossip;
+	/** class managing network connections */ topologist;
+	/** @type {NodeServices | undefined} */ services;
+
+	/** Initialize a new P2P node instance, use .start() to init topologist
+	 * @param {CryptoCodex} cryptoCodex - Identity of the node.
+	 * @param {Array<Record<string, string>>} bootstraps List of bootstrap nodes used as P2P network entry */
+	constructor(cryptoCodex, bootstraps = [], verbose = NODE.DEFAULT_VERBOSE) {
+		this.verbose = verbose;
+		if (this.topologist?.services) this.topologist.services.verbose = verbose;
+		this.cryptoCodex = cryptoCodex;
+		this.id = this.cryptoCodex.id;
+		const stunUrls = NodeServices.deriveSTUNServers(bootstraps || []);
+		this.offerManager = new OfferManager(this.id, stunUrls, verbose);
+		this.arbiter = new Arbiter(this.id, cryptoCodex, verbose);
+		this.peerStore = new PeerStore(this.id, this.cryptoCodex, this.offerManager, this.arbiter, verbose);
+		this.messager = new UnicastMessager(this.id, this.cryptoCodex, this.arbiter, this.peerStore, verbose);
+		this.gossip = new Gossip(this.id, this.cryptoCodex, this.arbiter, this.peerStore, verbose);
+		this.topologist = new Topologist(this.id, this.gossip, this.messager, this.peerStore, bootstraps || []);
+		const { arbiter, peerStore, messager, gossip, topologist } = this;
+
+		// SETUP TRANSPORTS LISTENERS
+		peerStore.on('signal', (peerId, data) => this.sendMessage(peerId, data, 'signal_answer')); // answer created => send it to offerer
+		peerStore.on('connect', (peerId, direction) => this.#onConnect(peerId, direction));
+		peerStore.on('disconnect', (peerId, direction) => this.#onDisconnect(peerId, direction));
+		peerStore.on('data', (peerId, data) => this.#onData(peerId, data));
+		
+		// UNICAST LISTENERS
+		messager.on('signal_answer', (senderId, data) => topologist.handleIncomingSignal(senderId, data));
+		messager.on('signal_offer', (senderId, data) => topologist.handleIncomingSignal(senderId, data));
+
+		// GOSSIP LISTENERS
+		gossip.on('signal_offer', (senderId, data, HOPS) => topologist.handleIncomingSignal(senderId, data, HOPS));
+
+		if (verbose > 2) console.log(`Node initialized: ${this.id}`);
+	}
+
+	// PRIVATE METHODS
+	/** @param {string} peerId @param {'in' | 'out'} direction */
+	#onConnect = (peerId, direction) => {
+		const remoteIsPublic = this.cryptoCodex.isPublicNode(peerId);
+		if (this.publicUrl) return; // public node do not need to do anything special on connect
+		if (this.verbose > ((this.publicUrl || remoteIsPublic) ? 3 : 2)) console.log(`(${this.id}) ${direction === 'in' ? 'Incoming' : 'Outgoing'} connection established with peer ${peerId}`);
+		const isHandshakeInitiator = remoteIsPublic || direction === 'in';
+		if (isHandshakeInitiator) this.sendMessage(peerId, this.id, 'handshake'); // send it in both case, no doubt...
+		
+		const isHoverNeighbored = this.peerStore.neighborsList.length >= DISCOVERY.TARGET_NEIGHBORS_COUNT + this.halfTarget;
+		const dispatchEvents = () => {
+			//this.sendMessage(peerId, this.id, 'handshake'); // send it in both case, no doubt...
+			if (DISCOVERY.ON_CONNECT_DISPATCH.OVER_NEIGHBORED && isHoverNeighbored)
+				this.broadcast([], 'over_neighbored'); // inform my neighbors that I am over neighbored
+			if (DISCOVERY.ON_CONNECT_DISPATCH.SHARE_HISTORY) 
+				if (this.peerStore.getUpdatedPeerConnectionsCount(peerId) <= 1) this.gossip.sendGossipHistoryToPeer(peerId);
+		};
+		if (!DISCOVERY.ON_CONNECT_DISPATCH.DELAY) dispatchEvents();
+		else setTimeout(dispatchEvents, DISCOVERY.ON_CONNECT_DISPATCH.DELAY);
+	}
+	/** @param {string} peerId @param {'in' | 'out'} direction */
+	#onDisconnect = (peerId, direction) => {
+		if (!this.peerStore.neighborsList.length) { // If we are totally alone => kick all connecting peers and invalidate all offers
+			for (const id in this.peerStore.connecting) this.peerStore.kickPeer(id, 0, 'no_neighbors_left');
+			for (const offerId in this.offerManager.offers) this.offerManager.offers[offerId].timestamp = 0; // reset offers to retry
+		}
+
+		const remoteIsPublic = this.cryptoCodex.isPublicNode(peerId);
+		if (this.peerStore.connected[peerId]) return; // still connected, ignore disconnection for now ?
+		if (this.verbose > ((this.publicUrl || remoteIsPublic) ? 3 : 2)) console.log(`(${this.id}) ${direction === 'in' ? 'Incoming' : 'Outgoing'} connection closed with peer ${peerId}`);
+		
+		return; // no event dispatching for now
+		const dispatchEvents = () => {
+		};
+		if (!DISCOVERY.ON_DISCONNECT_DISPATCH.DELAY) dispatchEvents();
+		else setTimeout(dispatchEvents, DISCOVERY.ON_DISCONNECT_DISPATCH.DELAY);
+	}
+	#onData = (peerId, data) => {
+		const d = new Uint8Array(data);
+		if (d[0] > 127) this.gossip.handleGossipMessage(peerId, d);
+		else this.messager.handleDirectMessage(peerId, d);
+	}
+
+	// PUBLIC API
+	get publicUrl() { return this.services?.publicUrl; }
+	get publicIdentity() { return { id: this.id, publicUrl: this.publicUrl }; }
+
+	onMessageData(callback) { this.messager.on('message', callback); }
+	onGossipData(callback) { this.gossip.on('gossip', callback); }
+	
+	async start() {
+		await CLOCK.sync(this.verbose);
+		this.started = true;
+		if (SIMULATION.AVOID_INTERVALS) return true; // SIMULATOR CASE
+		this.topologist.tryConnectNextBootstrap(); // first shot ASAP
+		this.arbiterInterval = setInterval(() => this.arbiter.tick(), 1000);
+		this.enhancerInterval = setInterval(() => this.topologist.tick(), DISCOVERY.LOOP_DELAY);
+		this.peerStoreInterval = setInterval(() => { this.peerStore.cleanupExpired(); this.peerStore.offerManager.tick(); }, 2500);
+		return true;
+	}
+	/** Broadcast a message to all connected peers or to a specified peer
+	 * @param {string | Uint8Array | Object} data @param {string} topic  @param {string} [targetId] default: broadcast to all
+	 * @param {number} [timestamp] default: CLOCK.time @param {number} [HOPS] default: GOSSIP.HOPS[topic] || GOSSIP.HOPS.default */
+	broadcast(data, topic, HOPS) { this.gossip.broadcastToAll(data, topic, HOPS); }
+	/** @param {string} remoteId @param {string | Uint8Array | Object} data @param {string} type */
+	sendMessage(remoteId, data, type, spread = 1) { this.messager.sendUnicast(remoteId, data, type, spread); }
+	async tryConnectToPeer(targetId = 'toto', retry = 5) { // TO REFACTO
+		console.info('FUNCTION DISABLED FOR NOW');
+		/*if (this.peerStore.connected[targetId]) return; // already connected
+		do {
+			if (this.peerStore.offerManager.readyOffer) break;
+			else await new Promise(r => setTimeout(r, 1000)); // build in progress...
+		} while (retry-- > 0);*/
+	}
+	destroy() {
+		if (this.enhancerInterval) clearInterval(this.enhancerInterval);
+		this.enhancerInterval = null;
+		if (this.peerStoreInterval) clearInterval(this.peerStoreInterval);
+		this.peerStoreInterval = null;
+		this.peerStore.destroy();
+		if (this.wsServer) this.wsServer.close();
+		if (this.stunServer) this.stunServer.close();
+	}
+}