pairnet 0.1.0 → 0.2.0

package/eslint.config.js

@@ -0,0 +1,3 @@
+"use strict";
+
+module.exports = require("@joepie91/eslint-config");

package/index.js

@@ -2,30 +2,42 @@
 
 const crypto = require("crypto");
 const tls = require("tls");
-const debug = require("debug")("pairnet");
+const makeDebug = require("debug-instanced")("pairnet");
 const matchValue = require("match-value");
+const getIPs = require("get-ips");
 const pipe = require("@promistream/pipe");
 const simpleSink = require("@promistream/simple-sink");
 
-const createMemoryStorage = require("./storages/memory");
-const createFileStorage = require("./storages/file");
-const { NotSet } = require("./storages/symbols");
+const createMemoryStorage = require("./lib/storages/memory");
+const createFileStorage = require("./lib/storages/file");
+const { NotSet, AlreadySet } = require("./lib/storages/symbols");
 
-const generateKeys = require("./lib/generate-keys");
+const generateKeys = require("./lib/tls/generate-keys");
 const createBackgroundTaskManager = require("./lib/background-tasks");
 const createStore = require("./lib/store");
-const getFingerprint = require("./lib/get-fingerprint");
-const maybeCall = require("./lib/maybe-call");
+const getFingerprint = require("./lib/tls/get-fingerprint");
 const handleProtocol = require("./lib/protocol");
-const serverListen = require("./promisified/server-listen");
-const serverClose = require("./promisified/server-close");
-
-const { validateOptions } = require("@validatem/core");
+const serverListen = require("./lib/promisified/server-listen");
+const serverClose = require("./lib/promisified/server-close");
+const wrappedToken = require("./lib/pairing-token/wrapped");
+const generatePairingToken = require("./lib/pairing-token/generate");
+const connectMultiple = require("./lib/network/connect-multiple");
+const reduceAddresses = require("./lib/pairing-token/reduce-addresses");
+const createQueryError = require("./lib/create-query-error");
+
+const { validateOptions, validateArguments } = require("@validatem/core");
+const ValidationError = require("@validatem/error");
 const required = require("@validatem/required");
+const defaultTo = require("@validatem/default-to");
+const requireEither = require("@validatem/require-either");
+const either = require("@validatem/either");
+const arrayOf = require("@validatem/array-of");
+const allowExtraProperties = require("@validatem/allow-extra-properties");
 const isFunction = require("@validatem/is-function");
-const ValidationError = require("@validatem/error");
-const isInteger = require("@validatem/is-integer");
+const isBuffer = require("@validatem/is-buffer");
+const isBoolean = require("@validatem/is-boolean");
 const isNonEmptyString = require("@validatem/is-non-empty-string");
+const isPortNumber = require("@validatem/is-port-number");
 
 /* TODO:
 - Verify that errors don't get eaten anywhere
@@ -33,16 +45,10 @@ const isNonEmptyString = require("@validatem/is-non-empty-string");
 - Auto-reconnection
 */
 
-function createQueryError(message) {
-	let error = new Error("Query resulted in an error");
-	error.code = "QUERY_ERROR_RESPONSE";
-	error.messageData = message;
-	return error;
-}
-
-async function makeClientSocket({ hostname, port, options, onQuery, protocolConfiguration }) {
-	let socket = tls.connect({
-		host: hostname,
+async function makeClientSocket({ addresses, port, options, onQuery, protocolConfiguration, debug }) {
+	// FIXME: tolerate protocol mismatches in negotiation, and fall over to the next address in that case as well
+	// TODO: Skip IPv6 addresses if we can determine that the system doesn't have IPv6 connectivity anyway, and likewise for IPv4; and figure out how to test that that works correctly
+	let socket = await connectMultiple(addresses, {
 		port: port,
 		rejectUnauthorized: false,
 		// We manually pin the certificate, so we don't have to care about the subject name at all; that's why checkServerIdentity always passes
@@ -53,12 +59,15 @@ async function makeClientSocket({ hostname, port, options, onQuery, protocolConf
 	});
 
 	let api = await handleProtocol(socket, {
+		debug,
 		protocolConfiguration: protocolConfiguration,
+		role: "client",
 		onQuery: onQuery
 	});
 	
 	return {
 		peerFingerprint: getFingerprint(socket),
+		peerAddress: socket.remoteAddress,
 		eventStream: api.eventStream,
 		send: api.sender.sendEvent,
 		query: api.sender.sendQuery,
@@ -73,16 +82,23 @@ function isStorageProvider(value) {
 }
 
 module.exports = {
+	NotSet: NotSet,
+	AlreadySet: AlreadySet,
 	createQueryError: createQueryError,
 	createMemoryStorage: createMemoryStorage,
 	createFileStorage: createFileStorage,
 	createPeer: async function createPeer(_options) {
-		let { storage, generateClientHello, onClientHello, onServerHello } = validateOptions(arguments, {
+		let debug = makeDebug("peer");
+
+		let { storage, generateClientHello, onClientHello, onServerHello } = validateOptions(arguments, [{
 			storage: [ required, isStorageProvider ],
-			generateClientHello: [ required, isFunction ],
-			onClientHello: [ required, isFunction ],
-			onServerHello: [ required, isFunction ]
-		});
+			generateClientHello: [ isFunction ],
+			onClientHello: [ isFunction ],
+			onServerHello: [ isFunction ]
+		}, either([
+			allowExtraProperties({ generateClientHello: required, onServerHello: required }),
+			allowExtraProperties({ onClientHello: required })
+		])]);
 
 		// FIXME: Why do we still have this fragile 'background task' mechanism?
 		let backgroundTasks = createBackgroundTaskManager();
@@ -126,104 +142,181 @@ module.exports = {
 				}
 			};
 		}
-	
-		return {
-			fingerprint: identity.fingerprint,
-			generatePairingToken: async function () {
-				let token = crypto.randomBytes(16).toString("hex");
-				// TODO: Expiry
-				await store.setValidPairingToken(token);
-				debug(`[generatePairingToken] Generated pairing token ${token}`);
-				return token;
-			},
-			pair: async function (_options) {
-				let { hostname, port, fingerprint, pairingToken } = validateOptions(arguments, {
-					hostname: [ required, isNonEmptyString ],
-					port: [ required, isInteger ],
-					fingerprint: [ required, isNonEmptyString ],
-					pairingToken: [ required, isNonEmptyString ]
-				});
 
-				if (protocolConfiguration.isClient) {
-					debug(`[pair] Initiating pairing connection to ${hostname}:${port}...`);
+		async function makeRawPairingToken() {
+			let token = generatePairingToken();
+			// TODO: Expiry
+			// TODO: Allow data to be associated with the token?
+			await store.setValidPairingToken(token);
+			debug(`[generatePairingToken] Generated pairing token ${token}`);
+			return token;
+		}
 
-					let socket = await makeClientSocket({
-						hostname, port, protocolConfiguration,
-						// We don't care about anything other than pairing messages in this mode, which are in the form of a query reply
-						onQuery: () => {}
-					});
+		async function pairRaw(_options) {
+			let { hostname, addresses, port, fingerprint, pairingToken } = validateOptions(arguments, [{
+				hostname: [ isNonEmptyString ],
+				addresses: [ arrayOf([ required, isNonEmptyString ]) ],
+				port: [ required, isPortNumber ],
+				fingerprint: [ required, isNonEmptyString ],
+				pairingToken: [ required, isBuffer ]
+			}, requireEither([ "hostname", "addresses" ])]);
+
+			if (protocolConfiguration.isClient) {
+				debug(`[pair] Initiating pairing connection to ${hostname}:${port}...`);
+
+				let socket = await makeClientSocket({
+					addresses: addresses ?? [ hostname ],
+					debug, port, protocolConfiguration,
+					// We don't care about anything other than pairing messages in this mode, which are in the form of a query reply
+					onQuery: () => {}
+				});
 
-					debug(`[pair] Expected fingerprint: ${fingerprint}`);
-					debug(`[pair] Actual fingerprint:   ${socket.peerFingerprint}`);
+				/* NOTE: We put the address that actually worked at the front of the list, so that that's the first thing we try upon connecting. But we leave the rest of the list in our store as well, in case we need to fall back (eg. due to temporary connectivity issues over IPv4 or IPv6 specifically). */
+				// TODO: Detect when the successful address does not exist in the original address list? To detect potential wrong assumptions in our implementation.
+				let orderedAddresses = (addresses != null)
+					? [ socket.peerAddress, ... addresses.filter((addr) => addr !== socket.peerAddress) ]
+					: [ hostname ];
 
-					if (socket.peerFingerprint !== fingerprint) {
-						await Promise.all([
-							socket.disconnect(),
-							backgroundTasks.awaitCompletion()
-						]);
-						throw new Error(`Fingerprint of server certificate does not match expected fingerprint`);
-					}
-
-					// We need to drive the read loop, even though we don't care about the events
-					let reader = pipe([
-						socket.eventStream,
-						simpleSink(() => {
-							debug("[pair] Ignored event message in pairing mode");
-						})
-					]);
+				debug(`[pair] Expected fingerprint: ${fingerprint}`);
+				debug(`[pair] Actual fingerprint:   ${socket.peerFingerprint}`);
 
+				if (socket.peerFingerprint !== fingerprint) {
 					await Promise.all([
-						// FIXME: Await completion of background tasks?
-						reader.read(),
-						(async () => {
-							try {
-								// Let any pairing errors throw
-								await socket.query({ type: "PAIR", token: pairingToken });
-								await store.trustPeer(fingerprint);
-							} finally {
-								await socket.disconnect();
-							}
-						})()
+						socket.disconnect(),
+						backgroundTasks.awaitCompletion()
 					]);
+					throw new Error(`Fingerprint of server certificate does not match expected fingerprint`);
+				}
+
+				// We need to drive the read loop, even though we don't care about the events
+				let reader = pipe([
+					socket.eventStream,
+					simpleSink(() => {
+						debug("[pair] Ignored event message in pairing mode");
+					})
+				]);
+
+				await Promise.all([
+					// FIXME: Await completion of background tasks?
+					reader.read(),
+					(async () => {
+						try {
+							// Let any pairing errors throw
+							await socket.query({ type: "PAIR", token: pairingToken });
+							await store.trustPeer(fingerprint, { addresses: orderedAddresses, port });
+						} finally {
+							await socket.disconnect();
+						}
+					})()
+				]);
+
+				return fingerprint;
+			} else {
+				throw new Error(`This peer is not configured as a client`);
+			}
+		}
+
+		async function connectRaw({ addresses, port, onQuery }) {
+			/* FIXME[security]: Verify that there are no exploitable issues if eg. one trusted peer presents the certificate of another trusted peer on an unexpected address (especially when connecting by fingerprint!) */
+			if (protocolConfiguration.isClient) {
+				debug(`[connect] Initiating client connection to (${addresses.join(", ")}):${port}...`);
+
+				// connect with client certificate made from own identity, and validate server pubkey
+				let socket = await makeClientSocket({
+					addresses: addresses,
+					debug, port, protocolConfiguration,
+					onQuery: onQuery
+				});
+	
+				let isPaired = await store.isPeerTrusted(socket.peerFingerprint);
+
+				debug(`[connect] Peer fingerprint: ${socket.peerFingerprint}`);
+				debug(`[connect] Is trusted: ${isPaired}`);
+	
+				if (isPaired !== true) {
+					await socket.disconnect();
+					throw new Error(`Not paired to specified peer`);
 				} else {
-					throw new Error(`This peer is not configured as a client`);
+					return makeProtocolPeer(socket, backgroundTasks);
 				}
+			} else {
+				throw new Error(`This peer is not configured as a client`);
+			}
+		}
+	
+		return {
+			fingerprint: identity.fingerprint,
+			generatePairingToken: async function (_port, _options) {
+				let [ port, { compact }] = validateArguments(arguments, {
+					port: [ required, isPortNumber ],
+					options: [ defaultTo({}), {
+						compact: [ defaultTo(false), isBoolean ]
+					}]
+				});
+
+				let ips = await getIPs();
+
+				return wrappedToken.encode({
+					addresses: (compact === true)
+						? reduceAddresses(ips.all)
+						: ips.all,
+					port: port,
+					rawToken: await makeRawPairingToken(),
+					fingerprint: identity.fingerprint,
+				});
 			},
-			connect: async function (_options) {
-				let { hostname, port, onQuery } = validateOptions(arguments, {
-					hostname: [ required, isNonEmptyString ],
-					port: [ required, isInteger ],
-					onQuery: [ required, isFunction ],
+			generateRawPairingToken: makeRawPairingToken,
+			pair: function (_token) {
+				let [ token ] = validateArguments(arguments, {
+					token: [ required, isNonEmptyString ]
 				});
 
-				if (protocolConfiguration.isClient) {
-					debug(`[connect] Initiating client connection to ${hostname}:${port}...`);
+				let tokenData = wrappedToken.decode(token);
 
-					// connect with client certificate made from own identity, and validate server pubkey
-					let socket = await makeClientSocket({
-						hostname, port, protocolConfiguration,
+				return pairRaw({
+					addresses: tokenData.addresses.map((item) => item.address),
+					port: tokenData.port,
+					fingerprint: tokenData.fingerprint,
+					pairingToken: tokenData.rawToken
+				});
+			},
+			pairRaw: pairRaw,
+			async connect(_options) {
+				let { fingerprint, onQuery } = validateOptions(arguments, {
+					fingerprint: [ required, isNonEmptyString ], // FIXME: Validate stricter
+					onQuery: [ required, isFunction ],
+				});
+				
+				let storedData = await store.getPeerData(fingerprint);
+				
+				if (storedData === NotSet) {
+					throw new Error(`Specified fingerprint is not known, cannot connect`);
+				} else if (storedData.addresses == null) {
+					throw new Error(`No stored addresses known for peer; try connectRaw instead`);
+				} else {
+					return connectRaw({
+						addresses: storedData.addresses,
+						port: storedData.port,
 						onQuery: onQuery
 					});
-		
-					let isPaired = await store.isPeerTrusted(socket.peerFingerprint);
-
-					debug(`[connect] Peer fingerprint: ${socket.peerFingerprint}`);
-					debug(`[connect] Is trusted: ${isPaired}`);
-		
-					if (isPaired !== true) {
-						await socket.disconnect();
-						throw new Error(`Not paired to specified peer`);
-					} else {
-						return makeProtocolPeer(socket, backgroundTasks);
-					}
-				} else {
-					throw new Error(`This peer is not configured as a client`);
 				}
 			},
+			connectRaw: async function (_options) {
+				let { hostname, port, onQuery } = validateOptions(arguments, {
+					hostname: [ required, isNonEmptyString ],
+					port: [ required, isPortNumber ],
+					onQuery: [ required, isFunction ],
+				});
+
+				return connectRaw({
+					addresses: [ hostname ],
+					port, onQuery,
+				});
+			},
 			createServer: async function (_option) {
 				let { hostname, port, onConnect, onDisconnect, onQuery } = validateOptions(arguments, {
-					hostname: [ required, isNonEmptyString ],
-					port: [ required, isInteger ],
+					hostname: [ isNonEmptyString ], /* undefined == listen on all public interfaces */
+					port: [ required, isPortNumber ],
 					onConnect: [ required, isFunction ],
 					onDisconnect: [ isFunction ],
 					onQuery: [ required, isFunction ]
@@ -252,17 +345,20 @@ module.exports = {
 						debug(`[server] Is trusted: ${isPaired}`);
 		
 						let api = await handleProtocol(socket, {
+							debug,
 							protocolConfiguration,
+							role: "server",
 							onQuery: async (query) => {
 								return matchValue(query.type, {
 									PAIR: async () => {
 										if (isPaired) {
+											// FIXME: Query error instead?
 											throw new Error(`Already paired`);
 										} else {
 											let { token } = query;
 			
 											if (await store.isValidPairingToken(token) === true) {
-												await store.trustPeer(clientFingerprint);
+												await store.trustPeer(clientFingerprint, { /* FIXME */ });
 												await store.removeValidPairingToken(token);
 												return true;
 											} else {
@@ -276,6 +372,7 @@ module.exports = {
 											return onQuery(clientFingerprint, query.m);
 										} else {
 											// FIXME: Force disconnect?
+											// FIXME: Query error instead?
 											throw new Error(`Client unauthorized`);
 										}
 									},
@@ -299,7 +396,7 @@ module.exports = {
 						await onConnect(protocolPeer);
 		
 						socket.on("close", () => {
-							maybeCall(onDisconnect, protocolPeer);
+							onDisconnect?.(protocolPeer);
 						});
 					}
 		

package/lib/create-query-error.js

@@ -0,0 +1,8 @@
+"use strict";
+
+module.exports = function createQueryError(message) {
+	let error = new Error("Query resulted in an error");
+	error.code = "QUERY_ERROR_RESPONSE";
+	error.messageData = message;
+	return error;
+};

package/lib/network/connect-multiple.js

@@ -0,0 +1,74 @@
+"use strict";
+
+const assert = require("node:assert");
+const tls = require("node:tls");
+const timers = require("node:timers/promises");
+
+function noop() {}
+
+module.exports = async function connectMultiple(addresses, options) {
+	return new Promise(async (resolveWinner, rejectAll) => {
+		/* attempt a connection to a series of addresses, until one succeeds. start a new connection every time a previous connection fails *or* every X milliseconds, whichever comes first, and then consider the 'winning' connection to be whichever one successfully completes connecting first. this mechanism ensures that when some addresses are very slow to respond (eg. due to network weather), this doesn't hold up any faster options that may appear after it in the list, keeping the delay from having to fail over to a different address minimal. */
+		/* NOTE: This function assumes that only IP addresses are passed in the `addresses` array; in particular, it assumes that if any connection attempt failed for a given address, that entire address has failed. This is not compatible with the family auto-selection that may occur for DNS names, where only the second IP address attempted may succeed. */
+		let pendingConnections = new Set();
+		let allConnectionPromises = [];
+		let connectionErrors = [];
+		let winner;
+	
+		for (let address of addresses) {
+			assert(address != null); /* undefined == implicit localhost */
+			let connection = tls.connect({ ... options, host: address });
+			pendingConnections.add(connection);
+	
+			// eslint-disable-next-line no-loop-func
+			let connectionPromise = new Promise((resolve, reject) => {
+				let timeout = setTimeout(() => connection.destroy(), 5000);
+
+				connection.on("error", noop);
+
+				connection.on("connect", () => {
+					clearTimeout(timeout);
+
+					/* Abort any other connection attempts (whether or not they have already connected, although the latter is very unlikely to happen) */
+					for (let otherCandidate of pendingConnections) {
+						if (otherCandidate !== connection) {
+							otherCandidate.destroy();
+						}
+					}
+					
+					winner = connection;
+					resolve();
+					resolveWinner(connection);
+				});
+	
+				connection.on("connectionAttemptFailed", (ip, port, family, error) => {
+					pendingConnections.delete(connection);
+					reject(error);
+				});
+			});
+
+			allConnectionPromises.push(connectionPromise.catch(() => {/*ignore*/}));
+	 
+			await Promise.race([
+				timers.setTimeout(100),
+				connectionPromise.catch((error) => { connectionErrors.push(error); })
+			]);
+
+			if (winner != null) {
+				break;
+			}
+		}
+
+		/* Wait for every connection attempt to complete, one of them may just be slow (and we want all of the connection errors in any case) */
+		await Promise.all(allConnectionPromises);
+		
+		if (winner == null) {
+			let aggregateError = new Error("Could not connect to any of the specified addresses");
+			aggregateError.errors = connectionErrors;
+			rejectAll(aggregateError);
+		} else {
+			/* By this point the socket is no longer under our control, and we want to make sure that we don't swallow any errors after this point */
+			winner.removeListener("error", noop);
+		}
+	});
+};

package/lib/pairing-token/generate.js

@@ -0,0 +1,7 @@
+"use strict";
+
+const crypto = require("node:crypto");
+
+module.exports = function generatePairingToken() {
+	return crypto.randomBytes(16);
+};

package/lib/pairing-token/reduce-addresses.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const isLocalIP = require("is-local-ip");
+
+module.exports = function reduceAddresses(addresses) {
+	let seen4 = false;
+	let seen6 = false;
+	let reducedList = [];
+
+	for (let address of addresses) {
+		if (address.family === 4 && !seen4 && !isLocalIP(address.address)) {
+			seen4 = true;
+			reducedList.push(address);
+		} else if (address.family === 6 && !seen6 && !isLocalIP(address.address)) {
+			seen6 = true;
+			reducedList.push(address);
+		}
+	}
+	
+	return reducedList;
+};

package/lib/pairing-token/wrapped.js

@@ -0,0 +1,77 @@
+"use strict";
+
+const assert = require("node:assert");
+const cbor = require("cbor");
+
+function uncompactAddress(compactedAddress) {
+	if (Buffer.isBuffer(compactedAddress)) {
+		/* IPv4 address */
+		return {
+			family: 4,
+			address: Array.from(compactedAddress)
+				.map((byte) => byte.toString(10))
+				.join(".")
+		};
+	} else {
+		/* IPv6 address */
+		return {
+			family: 6,
+			address: compactedAddress
+				.map((value) => value == null ? "" : value.toString(16))
+				.join(":")
+		};
+	}
+}
+
+function uncompactFingerprint(compactedFingerprint) {
+	return Array.from(compactedFingerprint)
+		.map((byte) => byte.toString(16).padStart(2, "0"))
+		.join(":")
+		.toUpperCase();
+}
+
+function compactAddress(address, family) {
+	/* This significantly reduces encoded token size */
+	// FIXME: Stricter validation/assertions to catch bugs loudly
+	if (family === 4) {
+		return Buffer.from(address.split(".").map((segment) => parseInt(segment, 10)));
+	} else if (family === 6) {
+		return address.split(":").map((segment) => segment === "" ? null : parseInt(segment, 16));
+	}
+}
+
+function compactFingerprint(fingerprint) {
+	// FIXME: Stricter validation/assertions to catch bugs loudly
+	return Buffer.from(fingerprint.split(":").map((byte) => parseInt(byte, 16)));
+}
+
+module.exports = {
+	encode({ addresses, port, rawToken, fingerprint }) {
+		/* We use an array to shave a couple bytes off the token size */
+		let tokenContents = [
+			0, /* token version */
+			addresses.map((ip) => compactAddress(ip.address, ip.family)),
+			port,
+			compactFingerprint(fingerprint),
+			rawToken,
+		];
+
+		return cbor.encode(tokenContents)
+			.toString("base64")
+			.replace(/\//g, "_")
+			.replace(/\+/g, "-")
+			.replace(/=+$/, "");
+	},
+	decode(wrappedToken) {
+		// FIXME: Validate decoded token strictly!
+		let data = cbor.decode(Buffer.from(wrappedToken, "base64"));
+		assert(Array.isArray(data) && data.length === 5);
+
+		let [ tokenVersion, compactedAddresses, port, compactedFingerprint, rawToken ] = data;
+		assert(tokenVersion === 0);
+		let addresses = compactedAddresses.map((address) => uncompactAddress(address));
+		let fingerprint = uncompactFingerprint(compactedFingerprint);
+
+		return { addresses, port, rawToken, fingerprint };
+	}
+};

package/{promisified → lib/promisified}/server-close.js

@@ -1,8 +1,8 @@
 "use strict";
 
-const pEvent = require("p-event");
+const { once } = require("node:events");
 
 module.exports = async function serverClose(server) {
 	server.close();
-	await pEvent(server, "close");
+	await once(server, "close");
 };

package/{promisified → lib/promisified}/server-listen.js

@@ -1,10 +1,10 @@
 "use strict";
 
-const pEvent = require("p-event");
+const { once } = require("node:events");
 const debug = require("debug")("pairnet:server-listen");
 
 module.exports = async function serverListen(server, port, hostname) {
 	server.listen(port, hostname);
-	await pEvent(server, "listening");
+	await once(server, "listening");
 	debug(`[createServer] Listening on ${hostname}:${port}...`);
 };

package/lib/protocol/evaluate-query.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = async function evaluateQuery(query, handler) {
+	try {
+		return {
+			success: true,
+			message: await handler(query)
+		};
+	} catch (error) {
+		if (error.code === "QUERY_ERROR_RESPONSE") {
+			return {
+				success: false,
+				message: error.messageData
+			};
+		} else {
+			throw error;
+		}
+	}
+};