roxxie-proxy-u-prod 0.1.0

package/source/packages/tracker-protocol/src/index.ts

@@ -0,0 +1,745 @@
+/**
+ * Roxxie tracker control protocol. This protocol carries discovery, signaling,
+ * health, and enrollment data only. Proxy payload bytes are never valid here.
+ */
+export const TRACKER_PROTOCOL_VERSION = "1.0";
+
+export const TRACKER_PATHS = {
+	browserWebSocket: "/v1/browser",
+	nodeControlWebSocket: "/v1/nodes/control",
+	browserCandidates: "/v1/browser/candidates",
+	browserSessions: "/v1/browser/sessions",
+	health: "/healthz",
+	nodeUpdateManifest: "/v1/updates/node/latest",
+	nodeUpdatePublicKey: "/v1/updates/node/key",
+} as const;
+
+export const TRACKER_WEBSOCKET_PROTOCOLS = {
+	browser: "roxxie-tracker-browser-v1",
+	node: "roxxie-tracker-node-v1",
+} as const;
+
+export const CONTROL_LIMITS = {
+	maxMessageBytes: 256 * 1024,
+	maxNodeNameBytes: 128,
+	maxVersionBytes: 64,
+	maxErrorBytes: 512,
+	maxCandidatesReturned: 3,
+	maxIceCandidates: 256,
+	maxNodeSessions: 512,
+} as const;
+
+export type NodeLifecycleState =
+	| "validating"
+	| "pending"
+	| "approved"
+	| "rejected"
+	| "revoked";
+
+export type NodeAvailability = "online" | "unhealthy" | "offline";
+export type NodeCredentialKind = "enrollment" | "pending" | "approved";
+
+export interface SessionDescriptionJSON {
+	type: "offer" | "answer" | "pranswer" | "rollback";
+	sdp?: string;
+}
+
+export interface IceCandidateJSON {
+	candidate: string;
+	sdpMid?: string | null;
+	sdpMLineIndex?: number | null;
+	usernameFragment?: string | null;
+}
+
+export interface RTCIceServerJSON {
+	urls: string | string[];
+	username?: string;
+	credential?: string;
+}
+
+export interface WebRTCOffer {
+	protocolVersion: string;
+	offer: SessionDescriptionJSON;
+	candidates: IceCandidateJSON[];
+}
+
+export interface WebRTCAnswer {
+	protocolVersion: string;
+	sessionId: string;
+	answer: SessionDescriptionJSON;
+	candidates: IceCandidateJSON[];
+}
+
+export interface NodeMetadata {
+	nodeId: string;
+	name: string;
+	packageVersion: string;
+	nodeVersion: string;
+	platform: string;
+	arch: string;
+	maxSessions: number;
+	protocolVersion: string;
+}
+
+export interface NodeMetrics {
+	activeSessions: number;
+	maxSessions: number;
+	uptimeSeconds: number;
+}
+
+export interface CandidateNode {
+	nodeId: string;
+	name: string;
+	activeSessions: number;
+	maxSessions: number;
+	utilization: number;
+	protocolVersion: string;
+	iceServers: RTCIceServerJSON[];
+}
+
+export interface BrowserCandidatesRequest {
+	type: "browser.candidates.request";
+	requestId: string;
+}
+
+export interface BrowserCandidatesResult {
+	type: "browser.candidates.result";
+	requestId: string;
+	candidates: CandidateNode[];
+}
+
+export interface BrowserSessionOffer {
+	type: "browser.session.offer";
+	requestId: string;
+	nodeId: string;
+	offer: WebRTCOffer;
+}
+
+export interface BrowserSessionAnswer {
+	type: "browser.session.answer";
+	requestId: string;
+	nodeId: string;
+	answer: WebRTCAnswer;
+}
+
+export interface BrowserError {
+	type: "browser.error";
+	requestId: string;
+	code:
+		| "BAD_REQUEST"
+		| "NODE_UNAVAILABLE"
+		| "NODE_CAPACITY"
+		| "SIGNAL_TIMEOUT"
+		| "INTERNAL";
+	message: string;
+}
+
+export type BrowserClientMessage =
+	| BrowserCandidatesRequest
+	| BrowserSessionOffer;
+export type BrowserServerMessage =
+	| BrowserCandidatesResult
+	| BrowserSessionAnswer
+	| BrowserError;
+
+export interface NodeHello {
+	type: "node.hello";
+	requestId: string;
+	trackerProtocolVersion: string;
+	credentialKind: NodeCredentialKind;
+	credential: string;
+	metadata: NodeMetadata;
+}
+
+export interface NodeWelcome {
+	type: "node.welcome";
+	requestId: string;
+	lifecycle: "validating" | "pending" | "approved";
+	credentialKind: "pending" | "approved";
+	credential?: string;
+	heartbeatIntervalMs: number;
+}
+
+export interface NodeHeartbeat {
+	type: "node.heartbeat";
+	requestId: string;
+	metrics: NodeMetrics;
+}
+
+export interface NodeHeartbeatAck {
+	type: "node.heartbeat.ack";
+	requestId: string;
+	nextHeartbeatMs: number;
+}
+
+/** Tracker -> node. The node creates an answer and hosts the proxy session. */
+export interface NodeWebRTCOffer {
+	type: "node.webrtc.offer";
+	requestId: string;
+	purpose: "validation" | "browser";
+	offer: WebRTCOffer;
+}
+
+/** Node -> tracker. Correlates exactly with NodeWebRTCOffer.requestId. */
+export interface NodeWebRTCAnswer {
+	type: "node.webrtc.answer";
+	requestId: string;
+	ok: boolean;
+	answer?: WebRTCAnswer;
+	error?: string;
+}
+
+export interface NodeCredentialRotated {
+	type: "node.credential.rotated";
+	requestId: string;
+	credential: string;
+}
+
+export interface NodeCredentialRotatedAck {
+	type: "node.credential.rotated.ack";
+	requestId: string;
+}
+
+export interface NodeStateChanged {
+	type: "node.state";
+	requestId: string;
+	lifecycle: "validating" | "pending" | "approved";
+	availability: NodeAvailability;
+}
+
+export interface NodeError {
+	type: "node.error";
+	requestId: string;
+	code:
+		| "BAD_REQUEST"
+		| "AUTH_FAILED"
+		| "NOT_APPROVED"
+		| "REJECTED"
+		| "REVOKED"
+		| "VERSION_MISMATCH"
+		| "INTERNAL";
+	message: string;
+}
+
+export type NodeClientMessage =
+	| NodeHello
+	| NodeHeartbeat
+	| NodeWebRTCAnswer
+	| NodeCredentialRotatedAck;
+export type NodeServerMessage =
+	| NodeWelcome
+	| NodeHeartbeatAck
+	| NodeWebRTCOffer
+	| NodeCredentialRotated
+	| NodeStateChanged
+	| NodeError;
+
+export interface SignedNodeUpdateManifest {
+	schemaVersion: 1;
+	packageName: "roxxie-transports-node";
+	version: string;
+	publishedAt: string;
+	expiresAt: string;
+	tarballUrl: string;
+	sha512: string;
+	minimumNodeVersion: string;
+	signatureAlgorithm: "Ed25519";
+	signature: string;
+}
+
+export type NodeUpdateManifestPayload = Omit<
+	SignedNodeUpdateManifest,
+	"signature"
+>;
+
+export class TrackerProtocolError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "TrackerProtocolError";
+	}
+}
+
+function objectValue(value: unknown, label: string): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		throw new TrackerProtocolError(`${label} must be an object`);
+	}
+	return value as Record<string, unknown>;
+}
+
+function stringValue(
+	value: unknown,
+	label: string,
+	maximumBytes: number = CONTROL_LIMITS.maxErrorBytes
+): string {
+	if (
+		typeof value !== "string" ||
+		value.length === 0 ||
+		new TextEncoder().encode(value).byteLength > maximumBytes
+	) {
+		throw new TrackerProtocolError(
+			`${label} must be a non-empty bounded string`
+		);
+	}
+	return value;
+}
+
+function requestId(value: unknown): string {
+	const result = stringValue(value, "requestId", 128);
+	if (!/^[A-Za-z0-9._:-]+$/u.test(result)) {
+		throw new TrackerProtocolError("requestId contains invalid characters");
+	}
+	return result;
+}
+
+function assertMessageBase(value: unknown): Record<string, unknown> {
+	const message = objectValue(value, "message");
+	stringValue(message.type, "type", 64);
+	requestId(message.requestId);
+	return message;
+}
+
+function assertNodeId(value: unknown, label = "nodeId"): string {
+	const id = stringValue(value, label, 64);
+	if (
+		!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(
+			id
+		)
+	) {
+		throw new TrackerProtocolError(`${label} must be an RFC 9562 UUID`);
+	}
+	return id;
+}
+
+function assertDescription(
+	value: unknown,
+	expectedType: "offer" | "answer",
+	label: string
+): void {
+	const description = objectValue(value, label);
+	if (description.type !== expectedType) {
+		throw new TrackerProtocolError(`${label} must have type ${expectedType}`);
+	}
+	stringValue(description.sdp, `${label}.sdp`, 1024 * 1024);
+}
+
+function assertIceCandidates(value: unknown, label: string): void {
+	if (!Array.isArray(value) || value.length > CONTROL_LIMITS.maxIceCandidates) {
+		throw new TrackerProtocolError(`${label} is invalid`);
+	}
+	for (const [index, entry] of value.entries()) {
+		const candidate = objectValue(entry, `${label}[${index}]`);
+		stringValue(candidate.candidate, `${label}[${index}].candidate`, 16 * 1024);
+		if (candidate.sdpMid !== undefined && candidate.sdpMid !== null) {
+			stringValue(candidate.sdpMid, `${label}[${index}].sdpMid`, 256);
+		}
+		if (
+			candidate.sdpMLineIndex !== undefined &&
+			candidate.sdpMLineIndex !== null &&
+			(!Number.isInteger(candidate.sdpMLineIndex) ||
+				(candidate.sdpMLineIndex as number) < 0 ||
+				(candidate.sdpMLineIndex as number) > 65_535)
+		) {
+			throw new TrackerProtocolError(
+				`${label}[${index}].sdpMLineIndex is invalid`
+			);
+		}
+		if (
+			candidate.usernameFragment !== undefined &&
+			candidate.usernameFragment !== null
+		) {
+			stringValue(
+				candidate.usernameFragment,
+				`${label}[${index}].usernameFragment`,
+				256
+			);
+		}
+	}
+}
+
+function assertIceServers(value: unknown, label: string): void {
+	if (!Array.isArray(value) || value.length > 8)
+		throw new TrackerProtocolError(`${label} is invalid`);
+	for (const [index, entry] of value.entries()) {
+		const server = objectValue(entry, `${label}[${index}]`);
+		const urls = typeof server.urls === "string" ? [server.urls] : server.urls;
+		if (!Array.isArray(urls) || urls.length === 0 || urls.length > 8)
+			throw new TrackerProtocolError(`${label}[${index}].urls is invalid`);
+		for (const url of urls) {
+			if (
+				typeof url !== "string" ||
+				url.length > 2048 ||
+				!/^stuns?:[^\s]+$/iu.test(url)
+			) {
+				throw new TrackerProtocolError(
+					`${label}[${index}] contains a non-STUN URL`
+				);
+			}
+		}
+		if (server.username !== undefined || server.credential !== undefined) {
+			throw new TrackerProtocolError(
+				`${label}[${index}] must not contain relay credentials`
+			);
+		}
+	}
+}
+
+function assertWebRTCOffer(value: unknown): asserts value is WebRTCOffer {
+	const offer = objectValue(value, "offer");
+	stringValue(offer.protocolVersion, "offer.protocolVersion", 32);
+	assertDescription(offer.offer, "offer", "offer.offer");
+	assertIceCandidates(offer.candidates, "offer.candidates");
+}
+
+export function assertWebRTCAnswer(
+	value: unknown
+): asserts value is WebRTCAnswer {
+	const answer = objectValue(value, "answer");
+	stringValue(answer.protocolVersion, "answer.protocolVersion", 32);
+	stringValue(answer.sessionId, "answer.sessionId", 128);
+	assertDescription(answer.answer, "answer", "answer.answer");
+	assertIceCandidates(answer.candidates, "answer.candidates");
+}
+
+export function assertBrowserClientMessage(
+	value: unknown
+): asserts value is BrowserClientMessage {
+	const message = assertMessageBase(value);
+	if (message.type === "browser.candidates.request") return;
+	if (message.type === "browser.session.offer") {
+		assertNodeId(message.nodeId);
+		assertWebRTCOffer(message.offer);
+		return;
+	}
+	throw new TrackerProtocolError("Unknown browser message type");
+}
+
+export function assertNodeClientMessage(
+	value: unknown
+): asserts value is NodeClientMessage {
+	const message = assertMessageBase(value);
+	switch (message.type) {
+		case "node.hello": {
+			if (message.trackerProtocolVersion !== TRACKER_PROTOCOL_VERSION) {
+				throw new TrackerProtocolError(
+					`Unsupported tracker protocol version; expected ${TRACKER_PROTOCOL_VERSION}`
+				);
+			}
+			if (
+				!(["enrollment", "pending", "approved"] as unknown[]).includes(
+					message.credentialKind
+				)
+			) {
+				throw new TrackerProtocolError("credentialKind is invalid");
+			}
+			stringValue(message.credential, "credential", 512);
+			const metadata = objectValue(message.metadata, "metadata");
+			assertNodeId(metadata.nodeId, "metadata.nodeId");
+			stringValue(
+				metadata.name,
+				"metadata.name",
+				CONTROL_LIMITS.maxNodeNameBytes
+			);
+			for (const field of [
+				"packageVersion",
+				"nodeVersion",
+				"platform",
+				"arch",
+				"protocolVersion",
+			] as const) {
+				stringValue(
+					metadata[field],
+					`metadata.${field}`,
+					CONTROL_LIMITS.maxVersionBytes
+				);
+			}
+			if (
+				!Number.isInteger(metadata.maxSessions) ||
+				(metadata.maxSessions as number) < 1 ||
+				(metadata.maxSessions as number) > CONTROL_LIMITS.maxNodeSessions
+			) {
+				throw new TrackerProtocolError("metadata.maxSessions is invalid");
+			}
+			return;
+		}
+		case "node.heartbeat": {
+			const metrics = objectValue(message.metrics, "metrics");
+			for (const field of [
+				"activeSessions",
+				"maxSessions",
+				"uptimeSeconds",
+			] as const) {
+				if (
+					!Number.isSafeInteger(metrics[field]) ||
+					(metrics[field] as number) < 0
+				) {
+					throw new TrackerProtocolError(`metrics.${field} is invalid`);
+				}
+			}
+			if ((metrics.maxSessions as number) > CONTROL_LIMITS.maxNodeSessions) {
+				throw new TrackerProtocolError(
+					"maxSessions exceeds the network safety ceiling"
+				);
+			}
+			if ((metrics.maxSessions as number) < 1) {
+				throw new TrackerProtocolError("maxSessions must be at least one");
+			}
+			if (
+				(metrics.activeSessions as number) > (metrics.maxSessions as number)
+			) {
+				throw new TrackerProtocolError("activeSessions exceeds maxSessions");
+			}
+			return;
+		}
+		case "node.webrtc.answer": {
+			if (typeof message.ok !== "boolean")
+				throw new TrackerProtocolError("ok must be boolean");
+			if (message.ok && message.answer === undefined)
+				throw new TrackerProtocolError("Successful answer is missing payload");
+			if (!message.ok && message.error === undefined)
+				throw new TrackerProtocolError("Failed answer is missing error");
+			if (message.ok) assertWebRTCAnswer(message.answer);
+			if (!message.ok) stringValue(message.error, "error");
+			return;
+		}
+		case "node.credential.rotated.ack":
+			return;
+		default:
+			throw new TrackerProtocolError("Unknown node message type");
+	}
+}
+
+export function assertNodeServerMessage(
+	value: unknown
+): asserts value is NodeServerMessage {
+	const message = assertMessageBase(value);
+	switch (message.type) {
+		case "node.welcome":
+			if (
+				!(["validating", "pending", "approved"] as unknown[]).includes(
+					message.lifecycle
+				)
+			) {
+				throw new TrackerProtocolError("lifecycle is invalid");
+			}
+			if (
+				!(["pending", "approved"] as unknown[]).includes(message.credentialKind)
+			) {
+				throw new TrackerProtocolError("credentialKind is invalid");
+			}
+			if (
+				(message.lifecycle === "approved") !==
+				(message.credentialKind === "approved")
+			) {
+				throw new TrackerProtocolError(
+					"credentialKind does not match lifecycle"
+				);
+			}
+			if (message.credential !== undefined)
+				stringValue(message.credential, "credential", 512);
+			if (
+				!Number.isInteger(message.heartbeatIntervalMs) ||
+				(message.heartbeatIntervalMs as number) < 1_000
+			) {
+				throw new TrackerProtocolError("heartbeatIntervalMs is invalid");
+			}
+			return;
+		case "node.heartbeat.ack":
+			if (
+				!Number.isInteger(message.nextHeartbeatMs) ||
+				(message.nextHeartbeatMs as number) < 1_000
+			) {
+				throw new TrackerProtocolError("nextHeartbeatMs is invalid");
+			}
+			return;
+		case "node.webrtc.offer":
+			if (message.purpose !== "validation" && message.purpose !== "browser") {
+				throw new TrackerProtocolError("purpose is invalid");
+			}
+			assertWebRTCOffer(message.offer);
+			return;
+		case "node.credential.rotated":
+			stringValue(message.credential, "credential", 512);
+			return;
+		case "node.state":
+			if (
+				!(["validating", "pending", "approved"] as unknown[]).includes(
+					message.lifecycle
+				)
+			) {
+				throw new TrackerProtocolError("lifecycle is invalid");
+			}
+			if (
+				!(["online", "unhealthy", "offline"] as unknown[]).includes(
+					message.availability
+				)
+			) {
+				throw new TrackerProtocolError("availability is invalid");
+			}
+			return;
+		case "node.error":
+			if (
+				!(
+					[
+						"BAD_REQUEST",
+						"AUTH_FAILED",
+						"NOT_APPROVED",
+						"REJECTED",
+						"REVOKED",
+						"VERSION_MISMATCH",
+						"INTERNAL",
+					] as unknown[]
+				).includes(message.code)
+			) {
+				throw new TrackerProtocolError("node error code is invalid");
+			}
+			stringValue(message.message, "message");
+			return;
+		default:
+			throw new TrackerProtocolError("Unknown tracker-to-node message type");
+	}
+}
+
+export function assertBrowserServerMessage(
+	value: unknown
+): asserts value is BrowserServerMessage {
+	const message = assertMessageBase(value);
+	switch (message.type) {
+		case "browser.candidates.result":
+			if (
+				!Array.isArray(message.candidates) ||
+				message.candidates.length > CONTROL_LIMITS.maxCandidatesReturned
+			) {
+				throw new TrackerProtocolError("candidates is invalid");
+			}
+			for (const [index, raw] of (message.candidates as unknown[]).entries()) {
+				const candidate = objectValue(raw, `candidates[${index}]`);
+				assertNodeId(candidate.nodeId, `candidates[${index}].nodeId`);
+				stringValue(
+					candidate.name,
+					`candidates[${index}].name`,
+					CONTROL_LIMITS.maxNodeNameBytes
+				);
+				stringValue(
+					candidate.protocolVersion,
+					`candidates[${index}].protocolVersion`,
+					32
+				);
+				for (const field of ["activeSessions", "maxSessions"] as const) {
+					if (
+						!Number.isSafeInteger(candidate[field]) ||
+						(candidate[field] as number) < (field === "maxSessions" ? 1 : 0)
+					) {
+						throw new TrackerProtocolError(
+							`candidates[${index}].${field} is invalid`
+						);
+					}
+				}
+				if (
+					typeof candidate.utilization !== "number" ||
+					!Number.isFinite(candidate.utilization) ||
+					candidate.utilization < 0 ||
+					candidate.utilization > 1
+				) {
+					throw new TrackerProtocolError(
+						`candidates[${index}].utilization is invalid`
+					);
+				}
+				assertIceServers(
+					candidate.iceServers,
+					`candidates[${index}].iceServers`
+				);
+			}
+			return;
+		case "browser.session.answer":
+			assertNodeId(message.nodeId);
+			assertWebRTCAnswer(message.answer);
+			return;
+		case "browser.error":
+			if (
+				!(
+					[
+						"BAD_REQUEST",
+						"NODE_UNAVAILABLE",
+						"NODE_CAPACITY",
+						"SIGNAL_TIMEOUT",
+						"INTERNAL",
+					] as unknown[]
+				).includes(message.code)
+			) {
+				throw new TrackerProtocolError("browser error code is invalid");
+			}
+			stringValue(message.message, "message");
+			return;
+		default:
+			throw new TrackerProtocolError("Unknown tracker-to-browser message type");
+	}
+}
+
+/**
+ * Canonical bytes signed with Ed25519. Field order is explicit and independent
+ * of object insertion order in the caller.
+ */
+export function manifestSigningPayload(
+	manifest: NodeUpdateManifestPayload
+): Uint8Array {
+	const canonical = {
+		schemaVersion: manifest.schemaVersion,
+		packageName: manifest.packageName,
+		version: manifest.version,
+		publishedAt: manifest.publishedAt,
+		expiresAt: manifest.expiresAt,
+		tarballUrl: manifest.tarballUrl,
+		sha512: manifest.sha512,
+		minimumNodeVersion: manifest.minimumNodeVersion,
+		signatureAlgorithm: manifest.signatureAlgorithm,
+	};
+	return new TextEncoder().encode(JSON.stringify(canonical));
+}
+
+function bytesOf(value: string | ArrayBuffer | ArrayBufferView): Uint8Array {
+	if (typeof value === "string") return new TextEncoder().encode(value);
+	if (ArrayBuffer.isView(value))
+		return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+	return new Uint8Array(value);
+}
+
+export function decodeControlJSON(
+	value: string | ArrayBuffer | ArrayBufferView
+): unknown {
+	const bytes = bytesOf(value);
+	if (bytes.byteLength > CONTROL_LIMITS.maxMessageBytes) {
+		throw new TrackerProtocolError("Control message is too large");
+	}
+	let text: string;
+	try {
+		text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		throw new TrackerProtocolError("Control message is not valid UTF-8");
+	}
+	try {
+		return JSON.parse(text) as unknown;
+	} catch {
+		throw new TrackerProtocolError("Control message is not valid JSON");
+	}
+}
+
+export function encodeControlJSON(value: unknown): string {
+	const result = JSON.stringify(value);
+	if (
+		new TextEncoder().encode(result).byteLength > CONTROL_LIMITS.maxMessageBytes
+	) {
+		throw new TrackerProtocolError("Control message is too large");
+	}
+	return result;
+}
+
+export function utilization(
+	activeSessions: number,
+	maxSessions: number
+): number {
+	if (!Number.isSafeInteger(activeSessions) || activeSessions < 0)
+		throw new TrackerProtocolError("activeSessions is invalid");
+	if (!Number.isSafeInteger(maxSessions) || maxSessions < 1)
+		throw new TrackerProtocolError("maxSessions is invalid");
+	return Math.min(1, activeSessions / maxSessions);
+}