pairnet 0.1.1 → 0.2.0

package/lib/protocol/index.js

@@ -0,0 +1,161 @@
+"use strict";
+
+const pipe = require("@promistream/pipe");
+const forkSequential = require("@promistream/fork-sequential");
+const simpleQueue = require("@promistream/simple-queue");
+const { fromDuplex } = require("@promistream/from-node-stream");
+const encodeCBOR = require("@promistream/encode-cbor");
+const decodeCBOR = require("@promistream/decode-cbor");
+const map = require("@promistream/map");
+const simpleSink = require("@promistream/simple-sink");
+const NoValue = require("@promistream/no-value");
+const createDebugStream = require("@promistream/debug");
+
+const objid = require("@joepie91/objid");
+
+const createSender = require("../sender");
+const createReplyTracker = require("../reply-tracker");
+const evaluateQuery = require("./evaluate-query");
+const { isNegotiationMessage, isReplyMessage, isNegotiationQuery, isQuery, isEvent, isSuccessReply, isErrorReply } = require("./message-types");
+
+module.exports = async function handleProtocol(socket, { debug, onQuery, protocolConfiguration, role } = {}) {
+	debug(`Attaching semantic protocol handler (role = ${role})`);
+
+	async function startNegotiation() {
+		let helloResponse = await sender.sendNegotiationQuery(await protocolConfiguration.generateClientHello());
+		let helloDecision = await protocolConfiguration.onServerHello(helloResponse);
+
+		if (helloDecision === false) {
+			// Connection rejected
+			negotiationStream.abort();
+		} else {
+			debug(`[readLoop] Negotiation completed on client side`);
+			negotiationStream.done();
+		}
+	}
+
+	let writeQueue = simpleQueue([], { autoEnd: false });
+	let replyTracker = createReplyTracker();
+	let sender = createSender(replyTracker, (message) => writeQueue.push(message));
+	let negotiationCompleted = false;
+
+	/* TODO: Allow passing streams into the `writeQueue` for sending streams of messages; this currently requires normalizing every non-stream value to a single-value stream and then using combine-sequential, but that seems like it could be prohibitively expensive performance-wise due to creating and ending a whole stream for every individual value in normal use. Perhaps we need a dedicated stream package for normalizing streams and non-stream values into a stream of streams, where subsequent non-stream values are buffered up into a single stream to avoid this performance penalty? Name it something like `mix-stream-values`? */
+	let [ negotiationStream, appReadStream ] = pipe([
+		writeQueue.stream,
+		map((message) => {
+			debug("Sending message:", message);
+			
+			if (negotiationCompleted !== true && !isNegotiationMessage(message)) {
+				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(),
+		fromDuplex(socket),
+		// createDebugStream(`pairnet:protocol:receive-pipeline (pre-cbor) ${objid(socket)}`),
+		decodeCBOR(),
+		// createDebugStream(`pairnet:protocol:receive-pipeline ${objid(socket)}`),
+		map(async (message) => {
+			if (isReplyMessage(message)) {
+				try {
+					if (isSuccessReply(message)) {
+						replyTracker.registerReply(message.t, message.i).resolve(message.m);
+					} else if (isErrorReply(message)) {
+						let error = new Error(`Received error response from peer`);
+						error.code = "PEER_ERROR";
+						error.message = message.m;
+		
+						replyTracker.registerReply(message.t, 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 {
+						throw error;
+					}
+				}
+
+				return NoValue;
+			} else {
+				return message;
+			}
+		}),
+		forkSequential(2),
+	]).read();
+
+	// We read messages for as long as negotiation has not been completed yet
+	// TODO[security]: verify that we don't allow server/client confusion anywhere
+	let negotiationPipeline = pipe([
+		negotiationStream,
+		map(async (message) => {
+			debug("Received message (negotiation phase):", message);
+
+			if (!isNegotiationMessage(message)) {
+				debug(`[readLoop] Ignored received message; not allowed type '${message.t}' during negotiation`);
+			} else if (isNegotiationQuery(message)) {
+				if (role === "server") {
+					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`);
+						negotiationStream.done();
+					} else {
+						await sender.sendNegotiationReplyError(message.i, result.message);
+					}
+	
+					debug(`[readLoop] Processed negotiation query ID '${message.i.toString("hex")}'`);
+				} else {
+					await sender.sendNegotiationReplyError(message.i, `Only the client may send a negotiation query`);
+				}
+			} else {
+				debug(`[readLoop] Received message with unknown type '${message.t}'`);
+			}
+		}),
+		simpleSink(() => { /* discard */ })
+	]);
+
+	await Promise.all([
+		negotiationPipeline.read(),
+		(role === "client") ? startNegotiation() : null
+	]);
+
+	// Unlock the sender
+	negotiationCompleted = true;
+	debug("Negotiation completed; switching to regular messaging stream...");
+
+	let eventStream = pipe([
+		appReadStream,
+		map(async (message) => {
+			debug("Received message (operating phase):", message);
+
+			if (isEvent(message)) {
+				debug(`[readLoop] Passed through event message as-is`);
+				return message.m; // Unpack actual message content from event message
+			} else {
+				if (isQuery(message)) {
+					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")}'`);
+				} else {
+					debug(`[readLoop] Received message with unknown type '${message.t}'`);
+				}
+
+				return NoValue; /* We only want to emit event messages, not anything we've handled internally already */
+			}
+		}),
+	]);
+
+	return {
+		eventStream: eventStream,
+		sender: sender,
+		disconnect: () => writeQueue.end()
+	};
+};

package/lib/protocol/message-types.js

@@ -0,0 +1,37 @@
+"use strict";
+
+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" ]);
+
+module.exports = {
+	NORMAL_QUERY_TYPE, NEGOTIATION_QUERY_TYPE, EVENT_TYPE,
+	NEGOTIATION_TYPES, REPLY_TYPES, SUCCESS_REPLIES, ERROR_REPLIES,
+	isNegotiationMessage(message) {
+		return NEGOTIATION_TYPES.has(message.t);
+	},
+	isNegotiationQuery(message) {
+		return message.t === NEGOTIATION_QUERY_TYPE;
+	},
+	isReplyMessage(message) {
+		return REPLY_TYPES.has(message.t);
+	},
+	isSuccessReply(message) {
+		return SUCCESS_REPLIES.has(message.t);
+	},
+	isErrorReply(message) {
+		return ERROR_REPLIES.has(message.t);
+	},
+	isQuery(message) {
+		return message.t === NORMAL_QUERY_TYPE;
+	},
+	isEvent(message) {
+		return message.t === EVENT_TYPE;
+	}
+};

package/lib/reply-tracker.js

@@ -4,38 +4,53 @@ const pDefer = require("p-defer");
 const crypto = require("crypto");
 const debug = require("debug")("pairnet:reply-tracker");
 
+function validateReplyType(queryType, replyType) {
+	/* We check that either both the query and reply are the normal kind, *or* both are the negotiation type. This is an extra defense against unforeseen (potentially exploitable) protocol confusion bugs. */
+	if (queryType === "nq") {
+		return replyType === "n" || replyType === "N";
+	} else if (queryType === "q") {
+		return replyType === "r" || replyType === "R";
+	} else {
+		return false;
+	}
+}
+
 module.exports = function createReplyTracker() {
 	let map = new Map();
 
 	return {
 		_map: map,
-		registerQuery: function () {
+		registerQuery: function (type) {
 			let defer = pDefer();
-			let id = crypto.randomBytes(6);
+			let id = crypto.randomBytes(6); // TODO: Should we use an incrementing ID instead?
 			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);
+			map.set(hexID, { ... defer, type });
 			
 			return {
 				id: id,
 				promise: defer.promise
 			};
 		},
-		registerReply: function (id) {
+		registerReply: function (type, 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 {
+			if (defer == null) {
 				debug(`Unknown query ID '${hexID}'`);
-				let error = Error(`Unknown ID '${hexID}'`);
+				let error = new Error(`Unknown ID '${hexID}'`);
 				error.code = "UNKNOWN_QUERY_ID";
 				throw error;
+			} else if (!validateReplyType(defer.type, type)) {
+				let error = new Error(`Incorrect reply type '${type}' for query of type '${defer.type}'`);
+				error.code = "INVALID_REPLY_TYPE";
+				throw error;
+			} else {
+				debug(`Registering reply for query ID '${hexID}'`);
+				map.delete(hexID);
+				return defer;
 			}
 		}
 	};

package/lib/sender.js

@@ -12,7 +12,7 @@ module.exports = function createSender(replyTracker, send) {
 			});
 		},
 		sendQuery: function sendQuery(message, type = "q") {
-			let { promise, id } = replyTracker.registerQuery();
+			let { promise, id } = replyTracker.registerQuery(type);
 
 			send({
 				t: type,

package/{storages → lib/storages}/memory.js

@@ -1,13 +1,18 @@
 "use strict";
 
+const util = require("node:util");
+const makeDebug = require("debug-instanced")("pairnet:storage:memory");
+
 const { NotSet, AlreadySet } = require("./symbols");
 
 module.exports = async function createMemoryStorage() {
+	let debug = makeDebug();
 	let storage = new Map();
 
 	return {
 		_pairnetStorage: true,
 		set: async function (key, value) {
+			debug(`setting: ${key} = ${util.inspect(value, { compact: true })}`);
 			if (storage.has(key)) {
 				return AlreadySet;
 			} else {
@@ -15,6 +20,7 @@ module.exports = async function createMemoryStorage() {
 			}
 		},
 		get: async function (key) {
+			debug(`getting: ${key}`);
 			if (storage.has(key)) {
 				return storage.get(key);
 			} else {
@@ -22,6 +28,7 @@ module.exports = async function createMemoryStorage() {
 			}
 		},
 		delete: async function (key) {
+			debug(`deleting: ${key}`);
 			return storage.delete(key);
 		}
 	};

package/lib/store.js

@@ -1,6 +1,9 @@
 "use strict";
 
+const { NotSet } = require("./storages/symbols");
+
 module.exports = function (storage) {
+	// TODO: Have Buffer assertions for tokens to catch potential implementation bugs?
 	return {
 		getIdentity: async function () {
 			return storage.get("pairnet_identity");
@@ -9,22 +12,25 @@ module.exports = function (storage) {
 			return storage.set("pairnet_identity", identity);
 		},
 		isValidPairingToken: async function (token) {
-			return (await storage.get(`pairnet_token_${token}`) === true);
+			return (await storage.get(`pairnet_token_${token.toString("hex")}`) === true);
 		},
 		setValidPairingToken: async function (token) {
-			return storage.set(`pairnet_token_${token}`, true);
+			return storage.set(`pairnet_token_${token.toString("hex")}`, true);
 		},
 		removeValidPairingToken: async function (token) {
-			return storage.delete(`pairnet_token_${token}`);
+			return storage.delete(`pairnet_token_${token.toString("hex")}`);
 		},
-		trustPeer: async function (fingerprint) {
-			return storage.set(`pairnet_peer_${fingerprint}`, true);
+		trustPeer: async function (fingerprint, data) {
+			return storage.set(`pairnet_peer_${fingerprint}`, data ?? {});
 		},
 		untrustPeer: async function (fingerprint) {
 			return storage.delete(`pairnet_peer_${fingerprint}`);
 		},
 		isPeerTrusted: async function (fingerprint) {
-			return (await storage.get(`pairnet_peer_${fingerprint}`) === true);
+			return (await storage.get(`pairnet_peer_${fingerprint}`) !== NotSet);
+		},
+		getPeerData: async function (fingerprint) {
+			return storage.get(`pairnet_peer_${fingerprint}`);
 		}
 	};
 };

package/notes.txt

@@ -4,3 +4,6 @@
 - 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
+
+TODO:
+- Implement re-pairing with wrapped tokens for eg. when a system's IP has changed

package/package.json

@@ -1,33 +1,40 @@
 {
   "name": "pairnet",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "",
   "main": "index.js",
-  "scripts": {
-    "test": "node --test"
-  },
   "keywords": [],
   "author": "Sven Slootweg <admin@cryto.net>",
   "license": "WTFPL",
   "dependencies": {
     "@joepie91/objid": "^1.0.1",
-    "@promistream/decode-cbor": "^0.1.0",
-    "@promistream/encode-cbor": "^0.1.0",
-    "@promistream/filter": "^0.1.3",
-    "@promistream/from-node-stream": "^0.1.6",
+    "@promistream/decode-cbor": "^0.1.1",
+    "@promistream/encode-cbor": "^0.1.1",
+    "@promistream/fork-sequential": "^0.1.1",
+    "@promistream/from-node-stream": "^0.1.12",
     "@promistream/map": "^0.1.10",
+    "@promistream/no-value": "^1.0.0",
     "@promistream/pipe": "^0.1.8",
     "@promistream/simple-queue": "^0.1.7",
     "@promistream/simple-sink": "^0.3.5",
+    "@validatem/allow-extra-properties": "^0.1.0",
+    "@validatem/array-of": "^0.1.3",
     "@validatem/core": "^0.6.3",
+    "@validatem/default-to": "^1.0.0",
+    "@validatem/either": "^0.1.10",
     "@validatem/error": "^1.1.0",
+    "@validatem/is-boolean": "^0.1.2",
+    "@validatem/is-buffer": "^0.1.1",
     "@validatem/is-function": "^0.1.0",
-    "@validatem/is-integer": "^0.1.0",
-    "@validatem/is-non-empty-string": "^0.1.0",
+    "@validatem/is-non-empty-string": "^0.1.1",
+    "@validatem/is-port-number": "^1.0.0",
+    "@validatem/require-either": "^0.1.0",
     "@validatem/required": "^0.1.1",
     "cbor": "^10.0.12",
     "debug": "^4.4.3",
     "debug-instanced": "^1.0.0",
+    "get-ips": "^1.0.1",
+    "is-local-ip": "^1.1.0",
     "match-value": "^1.1.0",
     "nanoid": "^3.3.18",
     "p-defer": "^3.0.0",
@@ -36,6 +43,10 @@
   "devDependencies": {
     "@joepie91/eslint-config": "^2.0.3",
     "@promistream/debug": "^0.1.2",
-    "eslint": "^10.8.1"
+    "@promistream/from-iterable": "^0.1.1",
+    "eslint": "^10.9.1"
+  },
+  "scripts": {
+    "test": "node --test"
   }
-}
+}

package/test/index.js

@@ -22,15 +22,6 @@ async function withYeetedStream(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(),
@@ -69,23 +60,24 @@ test("full procedure", async (t) => {
 		}
 	});
 
-	let token = await peer1.generatePairingToken();
+	// let token = await peer1.generatePairingToken(4005);
+	let rawToken = await peer1.generateRawPairingToken();
 
-	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 fingerprint", { timeout: 500 }, async () => {
+		await assert.rejects(async () => {
+			await peer2.pairRaw({ hostname: "localhost", port: 4005, fingerprint: "wrong", pairingToken: rawToken });
+		}, { message: "Fingerprint of server certificate does not match expected fingerprint" });
 	});
 
-	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("fails on wrong token", { timeout: 500 }, async () => {
+		await assert.rejects(async () => {
+			await peer2.pairRaw({ hostname: "localhost", port: 4005, fingerprint: peer1.fingerprint, pairingToken: Buffer.from("wrong") });
+		}, { message: "Invalid pairing token" });
 	});
 
-	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 t.test("happy path", { timeout: 500 }, async () => {
+		await peer2.pairRaw({ hostname: "localhost", port: 4005, fingerprint: peer1.fingerprint, pairingToken: rawToken });
+		let peer = await peer2.connectRaw({ hostname: "localhost", port: 4005, onQuery: noop });
 
 		await withYeetedStream(peer.eventStream, async () => {
 			let response = await peer.query({ number: 21 });
@@ -97,3 +89,44 @@ test("full procedure", async (t) => {
 
 	await server.stop();
 });
+
+test("full procedure with wrapped token", 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 fingerprint;
+
+	await t.test("pair", { timeout: 500 }, async () => {
+		let token = await peer1.generatePairingToken(4005);
+		fingerprint = await peer2.pair(token);
+	});
+
+	await t.test("connect", { timeout: 500 }, async () => {
+		let peer = await peer2.connect({ fingerprint: fingerprint, onQuery: noop });
+	
+		await withYeetedStream(peer.eventStream, async () => {
+			let response = await peer.query({ number: 21 });
+			assert.deepStrictEqual(response, { number: 42, hasFingerprint: true });
+			await peer.disconnect();
+		});
+	});
+
+	await server.stop();
+});
+
+test("compact token", async () => {
+	let fakePeer = await makePeer();
+	let normalToken = await fakePeer.generatePairingToken(4005);
+	let compactToken = await fakePeer.generatePairingToken(4005, { compact: true });
+	
+	console.log(`compact token ${compactToken.length} characters, vs. normal token ${normalToken.length}`);
+	assert(compactToken.length < normalToken.length);
+});

package/test/wrapped-token.js

@@ -0,0 +1,30 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert");
+
+const getIPs = require("get-ips");
+const wrappedToken = require("../lib/pairing-token/wrapped");
+const makeRawPairingToken = require("../lib/pairing-token/generate");
+
+test("roundtrip", async () => {
+	let inputData = {
+		addresses: (await getIPs()).all,
+		port: 5892,
+		rawToken: await makeRawPairingToken(),
+		fingerprint: "9D:FD:F7:FB:97:21:AD:36:35:4E:52:6B:3E:C9:BA:11:E5:BA:D6:B4:14:D6:85:D5:D3:23:5C:93:41:A6:9A:73",
+	};
+
+	let encoded = wrappedToken.encode(inputData);
+	let decoded = wrappedToken.decode(encoded);
+
+	/* We lose the address type in the encoding, but this is acceptable */
+	let inputToCompare = {
+		... inputData,
+		addresses: inputData.addresses.map(({ family, address }) => ({ family, address }))
+	};
+
+	console.log(`naive JSON size: ${JSON.stringify(inputToCompare).length}, actual token size: ${encoded.length}`);
+
+	assert.deepStrictEqual(inputToCompare, decoded);
+});

package/lib/maybe-call.js

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