pairnet 0.1.0

package/.eslintrc

@@ -0,0 +1,3 @@
+{
+	"extends": "@joepie91/eslint-config"
+}

package/README.md

@@ -0,0 +1,51 @@
+# pairnet - easy high-security paired connections
+
+__Maintenance status:__ [Experimental](https://codeberg.org/joepie91/policy#maintenance-and-support). This project is AI-free and [bans all AI contributions](https://codeberg.org/joepie91/policy#ai-policy).
+
+## ⚠️ WARNING
+
+This is an early release of Pairnet. It is __not__ yet carefully reviewed, and documentation may be incomplete or even incorrect. You should not use Pairnet for your projects yet, unless you intend to actively work with me on any issues you encounter. You have been warned!
+
+## Documentation continues below.
+
+Pairnet is a (mostly) unopinionated networking library for establishing high-security connections between processes on different systems, in Node.js. It uses an explicit pairing process to mutually authenticate between those processes.
+
+__What it's for:__
+
+- Distributed clusters, eg. for storage or computation.
+- Software that spans multiple systems, eg. a 'main server' and one or more 'worker nodes' for resource-intensive or specialized tasks.
+- Really, anything else where you need authenticated long-term links between processes on different servers.
+
+__What it gives you:__
+
+- An encrypted message stream to a Node.js process on another system, that lets you send values across without needing to serialize them first.
+- Authentication that ensures you really are talking to that process, not a man-in-the-middle.
+- Stable and unique "peer IDs" that are directly tied to the authentication, and so are not falsifiable.
+- The ability to re-establish that connection in the future, with the same guarantees.
+- A bidirectional protocol negotiation mechanism, to ensure that two processes using pairnet actually use it for the same (compatible) purpose.
+- A simple mechanism for specifying your own 'trust store' that keeps track of the trusted peers you have paired with, in whichever existing storage mechanism you already use.
+- A simple pairing process for the initial setup process, that's simply exposed as a few functions, so you can integrate it in whichever way you need.
+- Pairing tokens that can be directly given to and handled by users, eg. for interactive pairing processes in your own software designed for others to use.
+
+__What it doesn't give you:__
+
+- A discovery layer; it won't find services for you. But you can use pairnet with any discovery layer you prefer; all it requires is the ability to send a pairing token (string) in any one direction.
+- A VPN; this establishes process-to-process communication only, it doesn't create a virtual network interface.
+- NAT traversal; this library assumes direct TCP connectivity to be available. If you need NAT traversal, you will need to handle this on another layer.
+- Key rotation (yet); this may be added at a later time.
+- A raw byte stream; Pairnet uses a small CBOR-based protocol internally to negotiate the connection, and so the library exposes a message-oriented API rather than a bytestream-oriented one. CBOR supports binary data, so you can still just send binary blobs as your messages, of course.
+
+## How it works
+
+Pairnet establishes a mutually-authenticated TLS connection between two processes. This means that it uses TLS certificates as both server and client certificates, depending on the direction of the connection. The public fingerprint of the certificate serves as the node's "peer ID", making it non-falsifiable, as it is cryptographically derived from the specific certificate that a peer uses to authenticate itself.
+
+The pairing process is relatively simple; one peer creates a random 128-bit token, and encodes this pairing token plus its own public fingerprint and additional metadata (eg. IP and port) into a single string called a "wrapped pairing token". The other peer is given this token, internally unpacks it back into a separate fingerprint and a pairing token, and connects to the first peer in pairing mode. It verifies that the fingerprint matches what it expects, then sends the token over. The first peer verifies it against its list of previously-generated tokens, and if found, removes it from the list and tells the second peer that the pairing was successful. The second peer now registers the fingerprint from the wrapped pairing token as the correct fingerprint for the first peer; and the first peer registers whichever fingerprint the second peer connected with as *its *correct fingerprint.
+
+## Security considerations
+
+__Keep your Node.js installation up-to-date.__ On most systems, Node.js uses a bundled version of OpenSSL for all of its TLS and other cryptography features, and publishes security releases tracking those of OpenSSL. For this same reason, you _must_ only use Node.js version [that are still supported](https://endoflife.date/nodejs). This warning applies to all uses of built-in cryptography in Node.js, not just to pairnet.
+
+The following security-relevant features are currently missing, and will most likely be added to pairnet later:
+
+- Key rotation
+- Pairing token expiry

package/index.js

@@ -0,0 +1,330 @@
+"use strict";
+
+const crypto = require("crypto");
+const tls = require("tls");
+const debug = require("debug")("pairnet");
+const matchValue = require("match-value");
+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 generateKeys = require("./lib/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 handleProtocol = require("./lib/protocol");
+const serverListen = require("./promisified/server-listen");
+const serverClose = require("./promisified/server-close");
+
+const { validateOptions } = require("@validatem/core");
+const required = require("@validatem/required");
+const isFunction = require("@validatem/is-function");
+const ValidationError = require("@validatem/error");
+const isInteger = require("@validatem/is-integer");
+const isNonEmptyString = require("@validatem/is-non-empty-string");
+
+/* TODO:
+- Verify that errors don't get eaten anywhere
+- Redesign query error responses so that it doesn't interfere with force disconnection
+- 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,
+		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
+		checkServerIdentity: () => {},
+		cert: protocolConfiguration.identity.certificate,
+		key: protocolConfiguration.identity.privateKey,
+		... options ?? {}
+	});
+
+	let api = await handleProtocol(socket, {
+		protocolConfiguration: protocolConfiguration,
+		onQuery: onQuery
+	});
+	
+	return {
+		peerFingerprint: getFingerprint(socket),
+		eventStream: api.eventStream,
+		send: api.sender.sendEvent,
+		query: api.sender.sendQuery,
+		disconnect: api.disconnect
+	};
+}
+
+function isStorageProvider(value) {
+	if (value._pairnetStorage !== true) {
+		throw new ValidationError(`Must be a pairnet storage`);
+	}
+}
+
+module.exports = {
+	createQueryError: createQueryError,
+	createMemoryStorage: createMemoryStorage,
+	createFileStorage: createFileStorage,
+	createPeer: async function createPeer(_options) {
+		let { storage, generateClientHello, onClientHello, onServerHello } = validateOptions(arguments, {
+			storage: [ required, isStorageProvider ],
+			generateClientHello: [ required, isFunction ],
+			onClientHello: [ required, isFunction ],
+			onServerHello: [ required, isFunction ]
+		});
+
+		// FIXME: Why do we still have this fragile 'background task' mechanism?
+		let backgroundTasks = createBackgroundTaskManager();
+		let store = createStore(storage);
+
+		let identity = await store.getIdentity();
+		
+		if (identity === NotSet) {
+			debug(`[createPeer] Generating identity...`);
+			identity = await generateKeys("peer");
+			await store.setIdentity(identity);
+		}
+
+		debug(`[createPeer] Peer initialized with fingerprint ${identity.fingerprint}`);
+
+		let protocolConfiguration = {
+			generateClientHello: generateClientHello,
+			onClientHello: onClientHello,
+			onServerHello: onServerHello,
+			isClient: (generateClientHello != null && onServerHello != null),
+			isServer: (onClientHello != null),
+			storage: storage,
+			identity: identity
+		};
+
+		function makeProtocolPeer(socket, backgroundTasks) {
+			return {
+				fingerprint: socket.peerFingerprint,
+				eventStream: socket.eventStream,
+				query: function (message) {
+					return socket.query({ type: "MSG", m: message });
+				},
+				send: function (message) {
+					return socket.send(message);
+				},
+				disconnect: function () {
+					return Promise.all([
+						socket.disconnect(),
+						(backgroundTasks != null) ? backgroundTasks.awaitCompletion() : null
+					]);
+				}
+			};
+		}
+	
+		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}...`);
+
+					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: () => {}
+					});
+
+					debug(`[pair] Expected fingerprint: ${fingerprint}`);
+					debug(`[pair] Actual fingerprint:   ${socket.peerFingerprint}`);
+
+					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");
+						})
+					]);
+
+					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();
+							}
+						})()
+					]);
+				} else {
+					throw new Error(`This peer is not configured as a client`);
+				}
+			},
+			connect: async function (_options) {
+				let { hostname, port, onQuery } = validateOptions(arguments, {
+					hostname: [ required, isNonEmptyString ],
+					port: [ required, isInteger ],
+					onQuery: [ required, isFunction ],
+				});
+
+				if (protocolConfiguration.isClient) {
+					debug(`[connect] Initiating client connection to ${hostname}:${port}...`);
+
+					// connect with client certificate made from own identity, and validate server pubkey
+					let socket = await makeClientSocket({
+						hostname, 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 {
+						return makeProtocolPeer(socket, backgroundTasks);
+					}
+				} else {
+					throw new Error(`This peer is not configured as a client`);
+				}
+			},
+			createServer: async function (_option) {
+				let { hostname, port, onConnect, onDisconnect, onQuery } = validateOptions(arguments, {
+					hostname: [ required, isNonEmptyString ],
+					port: [ required, isInteger ],
+					onConnect: [ required, isFunction ],
+					onDisconnect: [ isFunction ],
+					onQuery: [ required, isFunction ]
+				});
+
+				if (protocolConfiguration.isServer) {
+					// FIXME: Reject connections without certificate
+					let server = tls.createServer({
+						cert: identity.certificate,
+						key: identity.privateKey,
+						requestCert: true,
+						rejectUnauthorized: false
+					});
+
+					async function handleClient(socket) {
+						let clientFingerprint = getFingerprint(socket);
+						
+						if (clientFingerprint == null) {
+							socket.destroy();
+							return;
+						}
+						
+						let isPaired = await store.isPeerTrusted(clientFingerprint);
+
+						debug(`[server] Peer fingerprint: ${clientFingerprint}`);
+						debug(`[server] Is trusted: ${isPaired}`);
+		
+						let api = await handleProtocol(socket, {
+							protocolConfiguration,
+							onQuery: async (query) => {
+								return matchValue(query.type, {
+									PAIR: async () => {
+										if (isPaired) {
+											throw new Error(`Already paired`);
+										} else {
+											let { token } = query;
+			
+											if (await store.isValidPairingToken(token) === true) {
+												await store.trustPeer(clientFingerprint);
+												await store.removeValidPairingToken(token);
+												return true;
+											} else {
+												// TODO: Force disconnect?
+												throw createQueryError("Invalid pairing token");
+											}
+										}
+									},
+									MSG: async () => {
+										if (isPaired) {
+											return onQuery(clientFingerprint, query.m);
+										} else {
+											// FIXME: Force disconnect?
+											throw new Error(`Client unauthorized`);
+										}
+									},
+									_: async () => {
+										// Invalid message type
+										return protocolPeer.disconnect();
+									}
+								});
+							}
+						});
+
+						let protocolPeer = makeProtocolPeer({
+							peerFingerprint: getFingerprint(socket),
+							eventStream: api.eventStream,
+							send: api.sender.sendEvent,
+							query: api.sender.sendQuery,
+							disconnect: api.disconnect
+						});
+		
+						// This is where the read stream should be attached to
+						await onConnect(protocolPeer);
+		
+						socket.on("close", () => {
+							maybeCall(onDisconnect, protocolPeer);
+						});
+					}
+		
+					server.on("secureConnection", async (socket) => { 
+						backgroundTasks.register(handleClient(socket));
+					});
+		
+					await serverListen(server, port, hostname);
+
+					return {
+						stop: async () => {
+							return Promise.all([
+								serverClose(server),
+								backgroundTasks.awaitCompletion()
+							]);
+						}
+					};
+				} else {
+					throw new Error(`This peer is not configured as a server`);
+				}
+			}
+		};
+	}
+};
+
+
+
+

package/lib/background-tasks.js

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = function createBackgroundTaskManager() {
+	let promises = [];
+
+	return {
+		_promises: promises,
+		register: function (promise) {
+			let num = Math.trunc(Math.random() * 800);
+			// console.log(`started stream ${num} ${(new Error("trace")).stack}`);
+			promises.push(promise.catch((error) => {
+				console.error(`Error in background task: ${error.stack}`);
+			}).then(() => { /* console.log(`finished stream ${num}`) */ }));
+		},
+		awaitCompletion: function () {
+			return Promise.all(promises);
+		}
+	};
+};

package/lib/generate-keys.js

@@ -0,0 +1,82 @@
+"use strict";
+
+const util = require("util");
+const childProcess = require("child_process");
+const assert = require("assert");
+const fs = require("fs/promises");
+const path = require("path");
+const nanoid = require("nanoid");
+
+async function withTemporaryFile(callback) {
+	// TODO: Improve cleanup; eg. on process exit?
+	let id = nanoid.nanoid();
+	let temporaryPath = path.join("/tmp/pairnet", id);
+	let pendingError, result;
+
+	await fs.mkdir("/tmp/pairnet", { recursive: true });
+	
+	try {
+		result = await callback(temporaryPath);
+	} catch (error) {
+		pendingError = error;
+	}
+	
+	try {
+		await fs.unlink(temporaryPath);
+	} catch (error) {
+		if (error.code === "ENOENT") {
+			// file was never created, this is fine
+		} else {
+			throw error;
+		}
+	}
+
+	if (pendingError != null) {
+		throw pendingError;
+	} else {
+		return result;
+	}
+}
+
+module.exports = async function generateKeys(subjectName) {
+	// TODO: Make broader, only forbidding (unencoded?) special characters
+	assert(/^[a-zA-Z0-9._ -]+$/.test(subjectName));
+
+	return await withTemporaryFile(async (keyPath) => {
+		return withTemporaryFile(async (csrPath) => {
+			await util.promisify(childProcess.execFile)("openssl", [
+				"req", "-newkey", "rsa:4096",
+				"-keyout", keyPath,
+				"-out", csrPath,
+				"-nodes",
+				"-subj", `/CN=${subjectName}`
+			]);
+
+			return withTemporaryFile(async (certificatePath) => {
+				await util.promisify(childProcess.execFile)("openssl", [
+					"x509", "-req",
+					"-in", csrPath,
+					"-signkey", keyPath, // self-signed
+					"-out", certificatePath,
+					"-days", "7000"
+				]);
+
+				// Node.js does not seem to expose any methods for getting a fingerprint from a certificate...
+				let fingerprintOutput = await util.promisify(childProcess.execFile)("openssl", [
+					"x509", "-fingerprint", "-sha256",
+					"-in", certificatePath,
+					"-noout"
+				]);
+
+				let match = /^\s*sha256 Fingerprint=(.+)\s*$/.exec(fingerprintOutput.stdout);
+				assert(match != null && match[1].length > 0);
+
+				return {
+					privateKey: (await fs.readFile(keyPath)).toString(),
+					certificate: (await fs.readFile(certificatePath)).toString(),
+					fingerprint: match[1]
+				};
+			});
+		});
+	});
+};

package/lib/get-fingerprint.js

@@ -0,0 +1,5 @@
+"use strict";
+
+module.exports = function getFingerprint(socket) {
+	return socket.getPeerCertificate().fingerprint256;
+};

package/lib/maybe-call.js

@@ -0,0 +1,7 @@
+"use strict";
+
+module.exports = function maybeCall(func, ... args) {
+	if (func != null) {
+		return func(...args);
+	}
+};

package/lib/protocol.js

@@ -0,0 +1,191 @@
+"use strict";
+
+const encodeCBOR = require("@promistream/encode-cbor");
+const decodeCBOR = require("@promistream/decode-cbor");
+const pipe = require("@promistream/pipe");
+const fromNodeStream = require("@promistream/from-node-stream");
+const map = require("@promistream/map");
+const infiniteQueue = require("../streams/infinite-queue");
+const simpleSink = require("@promistream/simple-sink");
+const createDebugStream = require("@promistream/debug");
+const objid = require("@joepie91/objid");
+
+const debug = require("debug")("pairnet:protocol");
+
+const createSender = require("./sender");
+const createReplyTracker = require("./reply-tracker");
+const disconnectSocket = require("../promisified/disconnect-socket");
+const filter = require("@promistream/filter");
+
+let NORMAL_QUERY_TYPE = "q";
+let NEGOTIATION_QUERY_TYPE = "nq";
+let EVENT_TYPE = "e";
+// negotiation query, negotiation reply, negotiation reply error
+let NEGOTIATION_TYPES = new Set([ "nq", "n", "N" ]);
+// reply, reply error, negotiation reply, negotiation reply error
+let REPLY_TYPES = new Set([ "r", "R", "n", "N" ]);
+let SUCCESS_REPLIES = new Set([ "r", "n" ]);
+let ERROR_REPLIES = new Set([ "R", "N" ]);
+
+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;
+		}
+	}
+}
+
+module.exports = async function handleProtocol(socket, { onQuery, protocolConfiguration } = {}) {
+	debug("Attaching semantic protocol handler");
+
+	let writeQueue = infiniteQueue([]);
+	let replyTracker = createReplyTracker();
+	let negotiationCompleted = false;
+
+	let sender = createSender(replyTracker, (message) => {
+		writeQueue.push(message);
+	});
+
+	// Send pipeline
+	pipe([
+		writeQueue.stream,
+		map((message) => {
+			debug("Sending message:", message);
+
+			let isNegotiationMessage = NEGOTIATION_TYPES.has(message.t);
+			
+			if (negotiationCompleted !== true && !isNegotiationMessage) {
+				debug(`[handleProtocol] Prevented message send; not allowed type '${message.t}' during negotiation`);
+				throw new Error(`Cannot send messages in negotiation phase`);
+			} else {
+				return message;
+			}
+		}),
+		// createDebugStream(`pairnet:protocol:send-pipeline ${objid(socket)}`),
+		encodeCBOR(),
+		fromNodeStream.fromWritable(socket)
+	]).read().catch((error) => {
+		// These errors are also mirrored on the read side, so we don't need to handle them here
+		debug(`Error occurred on writable side of socket`, error);
+	});
+
+	let incomingMessageStream = pipe([
+		fromNodeStream.fromReadable(socket),
+		decodeCBOR(),
+		// createDebugStream(`pairnet:protocol:receive-pipeline ${objid(socket)}`),
+	]);
+
+	let clientHelloQuery = (protocolConfiguration.isClient)
+		? sender.sendNegotiationQuery(await protocolConfiguration.generateClientHello())._queryID.toString("hex") // FIXME: Hacky
+		: null;
+
+	// We read messages for as long as negotiation has not been completed yet
+	await pipe([
+		incomingMessageStream,
+		simpleSink(async (message) => {
+			debug("Received message:", message);
+
+			let isNegotiationMessage = NEGOTIATION_TYPES.has(message.t);
+			let isReplyMessage = REPLY_TYPES.has(message.t);
+
+			if (!isNegotiationMessage) {
+				debug(`[readLoop] Ignored received message; not allowed type '${message.t}' during negotiation`);
+			} else if (isReplyMessage) {
+				if (message.i.toString("hex") === clientHelloQuery) {
+					let helloResponse = message.m;
+					let helloDecision = await protocolConfiguration.onServerHello(helloResponse);
+
+					if (helloDecision === false) {
+						// Connection rejected
+						return disconnectSocket(socket);
+					} else {
+						debug(`[readLoop] Negotiation completed on client side; detaching sink...`);
+						return null;
+					}
+				} else {
+					throw new Error(`Unrecognized negotiation query reply, id: ${message.i}`);
+				}
+			} else if (message.t === NEGOTIATION_QUERY_TYPE) {
+				let result = await evaluateQuery(message.m, protocolConfiguration.onClientHello);
+
+				if (result.success) { 
+					await sender.sendNegotiationReply(message.i, result.message); 
+					
+					debug(`[readLoop] Negotiation completed on server side; detaching sink...`);
+					return null;
+				} else {
+					await sender.sendNegotiationReplyError(message.i, result.message);
+				}
+
+				debug(`[readLoop] Processed negotiation query ID '${message.i.toString("hex")}'`);
+			} else {
+				debug(`[readLoop] Received message with unknown type '${message.t}'`);
+			}
+		})
+	]).read();
+
+	// Unlock the sender
+	negotiationCompleted = true;
+
+	let eventStream = pipe([
+		incomingMessageStream,
+		filter(async (message) => {
+			let isReplyMessage = REPLY_TYPES.has(message.t);
+
+			if (message.t === NORMAL_QUERY_TYPE) {
+				let result = await evaluateQuery(message.m, onQuery);
+		
+				if (result.success) {
+					await sender.sendReply(message.i, result.message);
+				} else {
+					await sender.sendReplyError(message.i, result.message);
+				}
+		
+				debug(`[readLoop] Processed normal query ID '${message.i.toString("hex")}'`);
+				return false;
+			} else if (message.t === EVENT_TYPE) {
+				// This is the only type of message that we will pass through as-is
+				debug(`[readLoop] Passed through event message as-is`);
+				return true;
+			} else if (isReplyMessage) {
+				try {
+					if (SUCCESS_REPLIES.has(message.t)) {
+						replyTracker.registerReply(message.i).resolve(message.m);
+					} else if (ERROR_REPLIES.has(message.t)) {
+						let error = new Error(`Received error response from peer`);
+						error.code = "PEER_ERROR";
+						error.message = message.m;
+		
+						replyTracker.registerReply(message.i).reject(error);
+					}
+				} catch (error) {
+					if (error.code === "UNKNOWN_QUERY_ID") {
+						debug(`[readLoop] Received reply to unknown query ID '${message.i.toString("hex")}'`);
+					}
+				}
+			} else {
+				debug(`[readLoop] Received message with unknown type '${message.t}'`);
+				return false;
+			}
+		}),
+		map(async (message) => {
+			return message.m; // Unpack actual message content from event message
+		})
+	]);
+
+	return {
+		eventStream: eventStream,
+		sender: sender,
+		disconnect: () => disconnectSocket(socket)
+	};
+};

package/lib/reply-tracker.js

@@ -0,0 +1,42 @@
+"use strict";
+
+const pDefer = require("p-defer");
+const crypto = require("crypto");
+const debug = require("debug")("pairnet:reply-tracker");
+
+module.exports = function createReplyTracker() {
+	let map = new Map();
+
+	return {
+		_map: map,
+		registerQuery: function () {
+			let defer = pDefer();
+			let id = crypto.randomBytes(6);
+			let hexID = id.toString("hex");
+			
+			// Store under string key due to Map not behaving like we want for value-identical Buffers
+			debug(`Storing query ID '${hexID}'`);
+			map.set(hexID, defer);
+			
+			return {
+				id: id,
+				promise: defer.promise
+			};
+		},
+		registerReply: function (id) {
+			let hexID = id.toString("hex");
+			let defer = map.get(hexID);
+
+			if (defer != null) {
+				debug(`Registering reply for query ID '${hexID}'`);
+				map.delete(hexID);
+				return defer;
+			} else {
+				debug(`Unknown query ID '${hexID}'`);
+				let error = Error(`Unknown ID '${hexID}'`);
+				error.code = "UNKNOWN_QUERY_ID";
+				throw error;
+			}
+		}
+	};
+};

package/lib/sender.js

@@ -0,0 +1,52 @@
+"use strict";
+
+module.exports = function createSender(replyTracker, send) {
+	let sender = {
+		sendRaw: function (message) {
+			send(message);
+		},
+		sendEvent: function sendEvent(message) {
+			send({
+				t: "e",
+				m: message
+			});
+		},
+		sendQuery: function sendQuery(message, type = "q") {
+			let { promise, id } = replyTracker.registerQuery();
+
+			send({
+				t: type,
+				m: message,
+				i: id
+			});
+	
+			promise._queryID = id;
+			return promise;
+		},
+		sendNegotiationQuery: function sendNegotiationQuery(message) {
+			return sender.sendQuery(message, "nq");
+		},
+		sendReply: function sendReply(id, message, type = "r") {
+			send({
+				t: type,
+				m: message,
+				i: id
+			});
+		},
+		sendNegotiationReply: function sendNegotiationReply(id, message) {
+			return sender.sendReply(id, message, "n");
+		},
+		sendReplyError: function sendReplyError(id, message, type = "R") {
+			send({
+				t: type,
+				m: message,
+				i: id
+			});
+		},
+		sendNegotiationReplyError: function sendNegotiationReplyError(id, message) {
+			return sender.sendReplyError(id, message, "N");
+		}
+	};
+
+	return sender;
+};

package/lib/store.js

@@ -0,0 +1,30 @@
+"use strict";
+
+module.exports = function (storage) {
+	return {
+		getIdentity: async function () {
+			return storage.get("pairnet_identity");
+		},
+		setIdentity: async function (identity) {
+			return storage.set("pairnet_identity", identity);
+		},
+		isValidPairingToken: async function (token) {
+			return (await storage.get(`pairnet_token_${token}`) === true);
+		},
+		setValidPairingToken: async function (token) {
+			return storage.set(`pairnet_token_${token}`, true);
+		},
+		removeValidPairingToken: async function (token) {
+			return storage.delete(`pairnet_token_${token}`);
+		},
+		trustPeer: async function (fingerprint) {
+			return storage.set(`pairnet_peer_${fingerprint}`, true);
+		},
+		untrustPeer: async function (fingerprint) {
+			return storage.delete(`pairnet_peer_${fingerprint}`);
+		},
+		isPeerTrusted: async function (fingerprint) {
+			return (await storage.get(`pairnet_peer_${fingerprint}`) === true);
+		}
+	};
+};

package/notes.txt

@@ -0,0 +1,6 @@
+# Connection procedure
+- Client connects to server
+- Client checks server pubkey
+- Client sends clientHello (custom) including protocol negotiation information
+- Server either breaks connection (optionally with an error) or responds with serverHello (custom) including protocol negotiation information
+- At this point, client must either already be recognized by the server, or it will get locked into pairing-only mode

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "pairnet",
+  "version": "0.1.0",
+  "description": "",
+  "main": "index.js",
+  "keywords": [],
+  "author": "Sven Slootweg <admin@cryto.net>",
+  "license": "WTFPL",
+  "dependencies": {
+    "@joepie91/consumable": "^1.0.1",
+    "@joepie91/objid": "^1.0.1",
+    "@promistream/aborted": "^0.1.2",
+    "@promistream/decode-cbor": "^0.1.0",
+    "@promistream/encode-cbor": "^0.1.0",
+    "@promistream/filter": "^0.1.1",
+    "@promistream/from-node-stream": "^0.1.3",
+    "@promistream/map": "^0.1.1",
+    "@promistream/pipe": "^0.1.6",
+    "@promistream/simple-sink": "^0.3.0",
+    "@promistream/simple-source": "^0.1.4",
+    "@validatem/core": "^0.5.0",
+    "@validatem/error": "^1.1.0",
+    "@validatem/is-function": "^0.1.0",
+    "@validatem/is-integer": "^0.1.0",
+    "@validatem/is-non-empty-string": "^0.1.0",
+    "@validatem/is-positive": "^1.0.0",
+    "@validatem/required": "^0.1.1",
+    "cbor": "^9.0.2",
+    "colorette": "^2.0.20",
+    "debug": "^4.3.4",
+    "match-value": "^1.1.0",
+    "nanoid": "^3.3.7",
+    "p-defer": "^3",
+    "p-event": "^4",
+    "range": "^0.0.3",
+    "sanitize-filename": "^1.6.3"
+  },
+  "devDependencies": {
+    "@joepie91/eslint-config": "^1.1.1",
+    "@promistream/debug": "^0.1.0",
+    "@promistream/from-iterable": "^0.1.0",
+    "@promistream/spy": "^0.1.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/promisified/disconnect-socket.js

@@ -0,0 +1,11 @@
+"use strict";
+
+const debug = require("debug")("pairnet");
+const pEvent = require("p-event");
+
+module.exports = async function disconnect(socket) {
+	debug(`[disconnectSocket] Disconnecting...`);
+	socket.destroySoon();
+	await pEvent(socket, "close");
+	debug(`[disconnectSocket] Disconnected!`);
+};

package/promisified/server-close.js

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

package/promisified/server-listen.js

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

package/storages/file.js

@@ -0,0 +1,45 @@
+"use strict";
+
+const fs = require("fs/promises");
+const path = require("path");
+const cbor = require("cbor");
+const sanitizeFilename = require("sanitize-filename");
+const { NotSet, AlreadySet } = require("./symbols");
+
+function safeName(name) {
+	return sanitizeFilename(name, { replacement: "_" });
+}
+
+module.exports = async function createFileStorage(folder) {
+	// NOTE: Unsafe filenames may result in duplicates for keys that are technically not duplicated!
+	await fs.mkdir(folder, { recursive: true });
+
+	return {
+		_pairnetStorage: true,
+		set: async function (key, value) {
+			try {
+				await fs.writeFile(path.join(folder, safeName(key)), cbor.encode(value), { flag: "wx" });
+			} catch (error) {
+				if (error.code === "EEXIST") {
+					return AlreadySet;
+				} else {
+					throw error;
+				}
+			}
+		},
+		get: async function (key) {
+			try {
+				return fs.readFile(path.join(folder, safeName(key)));
+			} catch (error) {
+				if (error.code === "ENOENT") {
+					return NotSet;
+				} else {
+					throw error;
+				}
+			}
+		},
+		delete: async function (key) {
+			return fs.unlink(path.join(folder, safeName(key)));
+		},
+	};
+};

package/storages/memory.js

@@ -0,0 +1,28 @@
+"use strict";
+
+const { NotSet, AlreadySet } = require("./symbols");
+
+module.exports = async function createMemoryStorage() {
+	let storage = new Map();
+
+	return {
+		_pairnetStorage: true,
+		set: async function (key, value) {
+			if (storage.has(key)) {
+				return AlreadySet;
+			} else {
+				storage.set(key, value);
+			}
+		},
+		get: async function (key) {
+			if (storage.has(key)) {
+				return storage.get(key);
+			} else {
+				return NotSet;
+			}
+		},
+		delete: async function (key) {
+			return storage.delete(key);
+		}
+	};
+};

package/storages/symbols.js

@@ -0,0 +1,6 @@
+"use strict";
+
+module.exports = {
+	NotSet: Symbol("NotSet"),
+	AlreadySet: Symbol("AlreadySet")
+};

package/streams/infinite-queue.js

@@ -0,0 +1,37 @@
+"use strict";
+
+const simpleSource = require("@promistream/simple-source");
+const Aborted = require("@promistream/aborted");
+const pDefer = require("p-defer");
+
+module.exports = function createInfiniteQueue(initialItems = []) {
+	let queue = initialItems.slice();
+	let defers = [];
+
+	return {
+		push: function (value) {
+			if (defers.length > 0) {
+				defers.shift().resolve(value);
+			} else {
+				queue.push(value);
+			}
+		},
+		stream: simpleSource({
+			onRequest: () => {
+				if (queue.length > 0) {
+					return queue.shift();
+				} else {
+					let defer = pDefer();
+					defers.push(defer);
+					return defer.promise;
+				}
+			},
+			onAbort: (reason) => {
+				for (let defer of defers) {
+					// TODO: Test properly
+					defer.reject(new Aborted("Stream was aborted"));
+				}
+			}
+		})
+	};
+};

package/test/index.js

@@ -0,0 +1,99 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("assert");
+const pairnet = require("../");
+const pipe = require("@promistream/pipe");
+const simpleSink = require("@promistream/simple-sink");
+
+function noop(value) {
+	// Do nothing
+	console.log(`noop:`, value);
+}
+
+async function yeetStream(stream) {
+	return await pipe([ stream, simpleSink(noop) ]).read();
+}
+
+async function withYeetedStream(stream, callback) {
+	return Promise.all([
+		yeetStream(stream),
+		callback()
+	]);
+}
+
+async function expectFailure(errorPattern, callback) {
+	try {
+		await assert.rejects(callback, errorPattern);
+		return true;
+	} catch (error) {
+		throw error;
+	}
+}
+
+async function makePeer(overrides) {
+	return pairnet.createPeer({
+		storage: await pairnet.createMemoryStorage(),
+		generateClientHello: function () {
+			return {
+				PROTO: "testproto"
+			};
+		},
+		onClientHello: function (clientHello) {
+			if (clientHello.PROTO === "testproto") {
+				return { PROTO_RESP: "testproto" };
+			} else {
+				throw pairnet.createQueryError("protocol mismatch");
+			}
+		},
+		onServerHello: function (serverHello) {
+			if (serverHello.PROTO_RESP === "testproto") {
+				return true;
+			} else {
+				return false;
+			}
+		},
+		... overrides
+	});
+}
+
+test("full procedure", async (t) => {
+	let peer1 = await makePeer();
+	let peer2 = await makePeer();
+
+	let server = await peer1.createServer({
+		hostname: "localhost", port: 4005,
+		onQuery: (fingerprint, query) => ({ number: query.number * 2, hasFingerprint: (fingerprint != null) }),
+		onConnect: async (peer) => {
+			yeetStream(peer.eventStream);
+		}
+	});
+
+	let token = await peer1.generatePairingToken();
+
+	await t.test("fails on wrong fingerprint", async (t) => {
+		return expectFailure({ message: "Fingerprint of server certificate does not match expected fingerprint" }, async () => {
+			await peer2.pair({ hostname: "localhost", port: 4005, fingerprint: "wrong", pairingToken: token });
+		});
+	});
+
+	await t.test("fails on wrong token", async (t) => {
+		return expectFailure({ message: "Invalid pairing token" }, async () => {
+			await peer2.pair({ hostname: "localhost", port: 4005, fingerprint: peer1.fingerprint, pairingToken: "wrong" });
+		});
+	});
+
+	await t.test("happy path", async (t) => {
+		await peer2.pair({ hostname: "localhost", port: 4005, fingerprint: peer1.fingerprint, pairingToken: token });
+		let peer = await peer2.connect({ hostname: "localhost", port: 4005, onQuery: noop });
+
+		await withYeetedStream(peer.eventStream, async () => {
+			let response = await peer.query({ number: 21 });
+			assert.deepStrictEqual(response, { number: 42, hasFingerprint: true });
+			await peer.disconnect();
+			// FIXME: Test query error reply
+		});
+	});
+
+	await server.stop();
+});