wire-mesh-core 0.0.0 → 1.0.2

package/dist/domain/mesh-session.d.mts

@@ -0,0 +1,101 @@
+import { F as ManageOk, M as ManageCommand, P as ManageError, U as PeerAdvert, Z as ProtocolVersion, ct as RevocationEntry, i as CapabilityToken, r as CapabilityScope, v as DeviceId, w as Frame } from "../protocol-B26-5VX7.mjs";
+import { t as IdentityPort } from "../identity-qNkmGytv.mjs";
+import { t as Clock } from "../clock-DiSx-WKM.mjs";
+import { Connection, Transport } from "../ports/transport.mjs";
+//#region src/domain/mesh-session.d.ts
+/** How long to wait for the node's handshake before calling it unanswered. A relay-only node never sends one; that is a state to display, not an error. */
+export declare const HANDSHAKE_TIMEOUT_MS = 3000;
+export type ConnectionState = {
+  status: "idle";
+} | {
+  status: "connecting";
+  address: string;
+} | {
+  status: "connected";
+  address: string;
+  handshake: HandshakeStatus;
+} | {
+  status: "reconnecting";
+  address: string;
+  attempt: number;
+  reason: string;
+} | {
+  status: "closed";
+  address: string;
+  reason: string;
+};
+/** Opt-in retry behaviour for a session's own reconnect attempts. Left at its default `null` in createMeshSession, a disconnect always falls straight to `"closed"` -- today's exact behaviour, unchanged unless a caller opts in. */
+export interface ReconnectPolicy {
+  maxAttempts: number;
+  /** Backoff before attempt N (1-indexed), in milliseconds. */
+  delayMs: (attempt: number) => number;
+}
+/** The union `manage-response-frame.outcome` actually carries -- no dedicated generated type name exists for it. */
+export type ManageOutcome = ManageOk | ManageError;
+/** One `manage-request` this session received from its peer, surfaced for the caller to act on and answer. */
+export interface IncomingManageRequest {
+  requestId: number;
+  command: ManageCommand;
+  scope: CapabilityScope;
+  token?: CapabilityToken;
+  /** The device-id of the peer this request was relayed on behalf of, present only when the request arrived wrapped in a relay-data frame rather than directly over this session's own connection. A caller that needs to address a further request back to the same peer (one not sent via respond(), which already routes back correctly on its own) passes this as sendManageRequest's targetDevice. */
+  fromDevice?: DeviceId;
+  respond: (outcome: ManageOutcome) => Promise<void>;
+}
+export type HandshakeStatus = {
+  status: "pending";
+} | {
+  status: "negotiated";
+  version: ProtocolVersion;
+  sharedDomains: string[];
+} | {
+  status: "unanswered";
+} | {
+  status: "rejected";
+  reason: string;
+};
+export interface SessionEvent {
+  state: ConnectionState;
+  /** The peer directory as of this event: latest peer-advert per device-id, in first-heard order. */
+  directory: readonly DirectoryEntry[];
+  /** Every frame that crossed the connection, sent or received, in order. */
+  frameLog: readonly FrameLogEntry[];
+}
+export interface DirectoryEntry {
+  device: DeviceId;
+  advert: PeerAdvert;
+}
+export interface FrameLogEntry {
+  direction: "sent" | "received";
+  frame: Frame;
+}
+export interface MeshSession {
+  readonly events: AsyncIterable<SessionEvent>;
+  /** Every `manage-request` received from the peer, in arrival order. */
+  readonly incomingManageRequests: AsyncIterable<IncomingManageRequest>;
+  /** Every `revocation-entry` received from the peer, in arrival order -- a `revocation-announce` frame's own `entries` array is flattened to one item per entry, since each entry is independently verifiable and independently meaningful regardless of which frame carried it. A consumer typically feeds each one into a RevocationView's own `record`. */
+  readonly revocationAnnouncements: AsyncIterable<RevocationEntry>;
+  connect: (address: string, localDomains: readonly string[]) => Promise<void>;
+  sendPing: () => Promise<void>;
+  /** Attaches this token to every `manage-request` sent from now on. */
+  setToken: (token: CapabilityToken) => void;
+  /** Announces one or more already-minted revocation-entries to the peer. Sent directly over the connection, never relay-wrapped -- revocation-announce is a gossiped broadcast, not a request addressed to a specific peer, so it has no targetDevice/token parameters the way sendManageRequest does. */
+  sendRevocationAnnounce: (entries: readonly RevocationEntry[]) => Promise<void>;
+  /** Sends a manage-request and resolves with the matching manage-response's outcome, correlated by request-id. When targetDevice is given, the request is routed to that specific peer via an established relay-connect pairing (wrapped as relay-data) rather than sent directly over this session's own Connection -- relay-hub deliberately drops manage-request/manage-response frames sent to it directly, since routing between two connected peers is not the relay role's business, so a specific peer reachable only through a relay hub can only be addressed this way. Absent, this sends directly over the Connection exactly as before. When token is given, it is attached to this one request instead of whatever setToken last set -- a single session routinely needs a different token per request when its peer shares more than one scope with this side (e.g. several core/room memberships over one connection), and a session-global token can only ever be correct for one of them. Absent, this request carries setToken's own session-global token exactly as before. */
+  sendManageRequest: (command: ManageCommand, scope: Readonly<CapabilityScope>, targetDevice?: DeviceId, token?: CapabilityToken) => Promise<ManageOutcome>;
+  close: () => Promise<void>;
+}
+export declare function createMeshSession(transport: Readonly<Transport>, identity: Readonly<IdentityPort>, clock?: Readonly<Clock>, reconnect?: ReconnectPolicy | null): MeshSession;
+/** A MeshSession built over a connection that already exists (a Transport's own listen() handed it to onConnection), extended with the one thing a dial-side session can't offer: the device-id of the specific peer at the other end. Unlike createMeshSession, which may end up talking to a relay gossiping about many devices at once, an accepted connection is the agent-comms case -- exactly two peers, directly connected -- so "the peer" is well-defined here in a way it structurally isn't for the dial side. */
+export interface AcceptedMeshSession extends MeshSession {
+  /** Resolves with the device-id carried by the first peer-advert this connection's remote sends -- the same self-advertisement mechanism createMeshSession's own directory already relies on for every peer, just narrowed to "the one peer this specific connection is with" rather than accumulated into a directory of possibly many. There is no transport-level authentication behind this yet (see wire-mesh#45's own createTlsTransport item): it is only as trustworthy as the remote's own gossip, exactly the same trust level the dial-side directory already has for every entry in it. */
+  peerDeviceId: Promise<DeviceId>;
+}
+export interface AcceptedMeshSessionOptions {
+  /** A caller-chosen label for this connection, used only for ConnectionState's own address field -- the Connection/Transport ports expose no remote-address concept an accepted connection could report on its own (see wire-mesh#45). Defaults to a fixed placeholder since most callers have nothing more specific to offer; a transport adapter that does know the remote's address should pass it here. */
+  label?: string;
+  clock?: Readonly<Clock>;
+}
+/** Wires an already-accepted Connection up as a full MeshSession, mirroring exactly what createMeshSession's own dial path does once a connection exists (send handshake, send self-advert, negotiate, consume frames) -- the wire-mesh#45 prerequisite agent-comms needs, since its peers both listen and dial rather than only ever dialing the way web-console's own console UI does. Reconnect does not apply here: if this connection drops, only the remote redialing and being accepted again produces a new connection, and therefore a new session -- there is nothing on this side to retry. */
+export declare function acceptMeshSession(connection: Readonly<Connection>, identity: Readonly<IdentityPort>, localDomains: readonly string[], options?: Readonly<AcceptedMeshSessionOptions>): Promise<AcceptedMeshSession>;
+//#endregion

package/dist/domain/mesh-session.mjs

@@ -0,0 +1,436 @@
+import { deviceIdToHex } from "./device-id.mjs";
+import { negotiate } from "./handshake.mjs";
+import { messageFromFrame, tryDecodeFrame } from "../adapters/frame-codec.mjs";
+//#region src/domain/mesh-session.ts
+const MS_PER_SECOND = 1e3;
+/** How long to wait for the node's handshake before calling it unanswered. A relay-only node never sends one; that is a state to display, not an error. */
+const HANDSHAKE_TIMEOUT_MS = 3e3;
+function localHandshake(domains) {
+	return {
+		type: "handshake",
+		version: 1,
+		domains: [...domains]
+	};
+}
+/**
+* Builds the connection-agnostic session state machine and its public MeshSession surface. dial is null for a session that can never (re)connect on its own -- acceptMeshSession's case, where the one connection it will ever have already exists by construction and reconnect therefore cannot apply (only the remote redialing, and being accepted again, produces a fresh connection). createMeshSession supplies dial as transport.connect so its own connect()/reconnect behaviour is unchanged from before this was factored out.
+*/
+function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert) {
+	let connection = null;
+	let state = { status: "idle" };
+	let handshake = { status: "pending" };
+	const directory = /* @__PURE__ */ new Map();
+	const frameLog = [];
+	let feedCancelled = false;
+	const eventWaiters = [];
+	const eventBacklog = [];
+	let handshakeTimer = null;
+	let reconnectTimer = null;
+	let attempt = 0;
+	let currentToken = null;
+	let nextRequestId = 0;
+	let relayPeerDevice = null;
+	const pendingManageRequests = /* @__PURE__ */ new Map();
+	const incomingWaiters = [];
+	const incomingBacklog = [];
+	const revocationWaiters = [];
+	const revocationBacklog = [];
+	function snapshot() {
+		return {
+			state,
+			directory: [...directory.values()],
+			frameLog: [...frameLog]
+		};
+	}
+	function emit() {
+		const event = snapshot();
+		const waiter = eventWaiters.shift();
+		if (waiter) waiter(event);
+		else eventBacklog.push(event);
+	}
+	function emitIncomingManageRequest(request) {
+		const waiter = incomingWaiters.shift();
+		if (waiter) waiter(request);
+		else incomingBacklog.push(request);
+	}
+	function emitRevocationEntry(entry) {
+		const waiter = revocationWaiters.shift();
+		if (waiter) waiter(entry);
+		else revocationBacklog.push(entry);
+	}
+	function rejectPendingManageRequests(reason) {
+		for (const pending of pendingManageRequests.values()) pending.reject(new Error(reason));
+		pendingManageRequests.clear();
+	}
+	function buildManageRequest(command, scope, tokenOverride) {
+		const requestId = nextRequestId;
+		nextRequestId += 1;
+		const token = tokenOverride ?? currentToken;
+		return {
+			type: "manage-request",
+			"request-id": requestId,
+			command,
+			scope,
+			...token !== null ? { token } : {}
+		};
+	}
+	/** Sends a frame, wrapping it as relay-data first when viaRelay is set -- the single choke point every outbound manage-request/manage-response passes through, so a consumer of sendManageRequest/respond never needs its own relay-wrapping logic. */
+	async function transmit(frame, viaRelay) {
+		if (connection === null) throw new Error("not connected");
+		if (viaRelay) {
+			const relayFrame = {
+				type: "relay-data",
+				payload: messageFromFrame(frame)
+			};
+			await connection.send(relayFrame);
+			return;
+		}
+		await connection.send(frame);
+	}
+	function applyManageResponse(frame) {
+		const requestId = frame["request-id"];
+		const pending = pendingManageRequests.get(requestId);
+		if (pending !== void 0) {
+			pendingManageRequests.delete(requestId);
+			pending.resolve(frame.outcome);
+		}
+	}
+	function applyManageRequest(frame, viaRelay) {
+		const requestId = frame["request-id"];
+		const fromDevice = viaRelay && relayPeerDevice !== null ? relayPeerDevice : void 0;
+		emitIncomingManageRequest({
+			requestId,
+			command: frame.command,
+			scope: frame.scope,
+			...frame.token !== void 0 ? { token: frame.token } : {},
+			...fromDevice !== void 0 ? { fromDevice } : {},
+			respond: async (outcome) => {
+				const response = {
+					type: "manage-response",
+					"request-id": requestId,
+					outcome
+				};
+				frameLog.push({
+					direction: "sent",
+					frame: response
+				});
+				await transmit(response, viaRelay);
+				emit();
+			}
+		});
+	}
+	function applyFrame(frame) {
+		if (frame.type === "relay-data") {
+			const inner = tryDecodeFrame(frame.payload);
+			if (inner !== null && (inner.type === "manage-request" || inner.type === "manage-response")) {
+				frameLog.push({
+					direction: "received",
+					frame: inner
+				});
+				if (inner.type === "manage-response") applyManageResponse(inner);
+				else applyManageRequest(inner, true);
+				return;
+			}
+			frameLog.push({
+				direction: "received",
+				frame
+			});
+			return;
+		}
+		frameLog.push({
+			direction: "received",
+			frame
+		});
+		if (frame.type === "handshake") applyRemoteHandshake(frame);
+		else if (frame.type === "gossip") for (const advert of frame.peers) {
+			directory.set(deviceIdToHex(advert.device), {
+				device: advert.device,
+				advert
+			});
+			onPeerAdvert?.(advert);
+		}
+		else if (frame.type === "relay-inbound") relayPeerDevice = frame["source-device"];
+		else if (frame.type === "manage-response") applyManageResponse(frame);
+		else if (frame.type === "manage-request") applyManageRequest(frame, false);
+		else if (frame.type === "revocation-announce") for (const entry of frame.entries) emitRevocationEntry(entry);
+	}
+	/** Establishes a relay-connect pairing to targetDevice if this session isn't already paired with it -- a no-op when it already is, whether that pairing was established by this session's own prior relay-connect (initiator role) or learned from an incoming relay-inbound (target role, replying back to whoever dialed it). relay-connect has no ack frame: the initiator proceeds to relay-data right after sending it. */
+	async function ensureRelayPairing(targetDevice) {
+		if (connection === null) throw new Error("not connected");
+		if (relayPeerDevice !== null && deviceIdToHex(relayPeerDevice) === deviceIdToHex(targetDevice)) return;
+		const relayConnect = {
+			type: "relay-connect",
+			"target-device": targetDevice
+		};
+		frameLog.push({
+			direction: "sent",
+			frame: relayConnect
+		});
+		await connection.send(relayConnect);
+		relayPeerDevice = targetDevice;
+		emit();
+	}
+	let localHandshakeSent = localHandshake([]);
+	function applyRemoteHandshake(remote) {
+		if (handshake.status !== "pending") return;
+		if (handshakeTimer !== null) {
+			clearTimeout(handshakeTimer);
+			handshakeTimer = null;
+		}
+		const result = negotiate(localHandshakeSent, remote);
+		handshake = result.ok ? {
+			status: "negotiated",
+			version: result.version,
+			sharedDomains: result.sharedDomains
+		} : {
+			status: "rejected",
+			reason: "no shared domains or version"
+		};
+		if (state.status === "connected") state = {
+			...state,
+			handshake
+		};
+	}
+	function handleDisconnect(reason, address, localDomains) {
+		if (feedCancelled) return;
+		rejectPendingManageRequests("disconnected before a response arrived");
+		if (reconnect !== null && attempt < reconnect.maxAttempts) {
+			attempt += 1;
+			const currentAttempt = attempt;
+			state = {
+				status: "reconnecting",
+				address,
+				attempt: currentAttempt,
+				reason
+			};
+			emit();
+			reconnectTimer = setTimeout(() => {
+				reconnectTimer = null;
+				doConnect(address, localDomains).catch((error) => {
+					handleDisconnect(error instanceof Error ? error.message : String(error), address, localDomains);
+				});
+			}, reconnect.delayMs(currentAttempt));
+			return;
+		}
+		state = {
+			status: "closed",
+			address,
+			reason
+		};
+		emit();
+	}
+	async function consume(link, address, localDomains) {
+		for await (const frame of link.receive()) {
+			if (feedCancelled) return;
+			applyFrame(frame);
+			emit();
+		}
+		if (state.status === "connected") handleDisconnect("node closed the connection", address, localDomains);
+	}
+	/** Everything a connection needs once it exists, regardless of whether it was dialled (createMeshSession's own doConnect, below) or handed over already established (acceptMeshSession): send this side's handshake and self-advert, arm the handshake timeout, and start consuming frames. The two entry points differ only in how link itself came to exist and what address means for it -- a real dial target for one, a caller-chosen label for the other, since the Connection/Transport ports expose no remote-address concept of their own for an accepted connection. */
+	async function wireUpConnection(link, address, localDomains) {
+		connection = link;
+		localHandshakeSent = localHandshake(localDomains);
+		handshake = { status: "pending" };
+		state = {
+			status: "connected",
+			address,
+			handshake
+		};
+		frameLog.push({
+			direction: "sent",
+			frame: localHandshakeSent
+		});
+		await connection.send(localHandshakeSent);
+		emit();
+		const selfAdvert = {
+			type: "gossip",
+			peers: [{
+				device: identity.deviceId,
+				addresses: [],
+				"snapshot-seconds": Math.floor(clock.now() / MS_PER_SECOND)
+			}]
+		};
+		frameLog.push({
+			direction: "sent",
+			frame: selfAdvert
+		});
+		await connection.send(selfAdvert);
+		emit();
+		handshakeTimer = setTimeout(() => {
+			handshakeTimer = null;
+			if (handshake.status === "pending") {
+				handshake = { status: "unanswered" };
+				if (state.status === "connected") state = {
+					...state,
+					handshake
+				};
+				emit();
+			}
+		}, HANDSHAKE_TIMEOUT_MS);
+		consume(connection, address, localDomains).catch((error) => {
+			if (state.status === "connected") handleDisconnect(error instanceof Error ? error.message : String(error), address, localDomains);
+		});
+	}
+	async function doConnect(address, localDomains) {
+		if (dial === null) throw new Error("this session is already connected; there is nothing to dial");
+		if (handshakeTimer !== null) {
+			clearTimeout(handshakeTimer);
+			handshakeTimer = null;
+		}
+		state = {
+			status: "connecting",
+			address
+		};
+		emit();
+		const link = await dial(address);
+		if (feedCancelled) {
+			await link.close();
+			return;
+		}
+		await wireUpConnection(link, address, localDomains);
+	}
+	return {
+		wireUpConnection,
+		session: {
+			events: { [Symbol.asyncIterator]() {
+				return { next: async () => new Promise((resolve) => {
+					const backlogEvent = eventBacklog.shift();
+					if (backlogEvent) resolve({
+						value: backlogEvent,
+						done: false
+					});
+					else eventWaiters.push((event) => {
+						resolve({
+							value: event,
+							done: false
+						});
+					});
+				}) };
+			} },
+			incomingManageRequests: { [Symbol.asyncIterator]() {
+				return { next: async () => new Promise((resolve) => {
+					const backlogRequest = incomingBacklog.shift();
+					if (backlogRequest) resolve({
+						value: backlogRequest,
+						done: false
+					});
+					else incomingWaiters.push((request) => {
+						resolve({
+							value: request,
+							done: false
+						});
+					});
+				}) };
+			} },
+			revocationAnnouncements: { [Symbol.asyncIterator]() {
+				return { next: async () => new Promise((resolve) => {
+					const backlogEntry = revocationBacklog.shift();
+					if (backlogEntry) resolve({
+						value: backlogEntry,
+						done: false
+					});
+					else revocationWaiters.push((entry) => {
+						resolve({
+							value: entry,
+							done: false
+						});
+					});
+				}) };
+			} },
+			async connect(address, localDomains) {
+				if (connection !== null) throw new Error("a session connects once; create a new one to reconnect");
+				attempt = 0;
+				await doConnect(address, localDomains);
+			},
+			async sendPing() {
+				if (connection === null || state.status !== "connected") throw new Error("not connected");
+				const ping = { type: "ping" };
+				frameLog.push({
+					direction: "sent",
+					frame: ping
+				});
+				await connection.send(ping);
+				emit();
+			},
+			setToken(token) {
+				currentToken = token;
+			},
+			async sendManageRequest(command, scope, targetDevice, token) {
+				if (connection === null || state.status !== "connected") throw new Error("not connected");
+				if (targetDevice !== void 0) await ensureRelayPairing(targetDevice);
+				const frame = buildManageRequest(command, scope, token);
+				const outcome = new Promise((resolve, reject) => {
+					pendingManageRequests.set(frame["request-id"], {
+						resolve,
+						reject
+					});
+				});
+				frameLog.push({
+					direction: "sent",
+					frame
+				});
+				await transmit(frame, targetDevice !== void 0);
+				emit();
+				return outcome;
+			},
+			async sendRevocationAnnounce(entries) {
+				if (connection === null || state.status !== "connected") throw new Error("not connected");
+				const frame = {
+					type: "revocation-announce",
+					entries: [...entries]
+				};
+				frameLog.push({
+					direction: "sent",
+					frame
+				});
+				await transmit(frame, false);
+				emit();
+			},
+			async close() {
+				feedCancelled = true;
+				if (handshakeTimer !== null) {
+					clearTimeout(handshakeTimer);
+					handshakeTimer = null;
+				}
+				if (reconnectTimer !== null) {
+					clearTimeout(reconnectTimer);
+					reconnectTimer = null;
+				}
+				rejectPendingManageRequests("connection closed before a response arrived");
+				if (connection !== null) await connection.close();
+				if (state.status === "connected" || state.status === "connecting" || state.status === "reconnecting") state = {
+					status: "closed",
+					address: state.address,
+					reason: "closed by you"
+				};
+				emit();
+			}
+		}
+	};
+}
+function createMeshSession(transport, identity, clock = { now: () => Date.now() }, reconnect = null) {
+	const { session } = createSessionCore(identity, clock, reconnect, async (address) => transport.connect(address));
+	return session;
+}
+/** Wires an already-accepted Connection up as a full MeshSession, mirroring exactly what createMeshSession's own dial path does once a connection exists (send handshake, send self-advert, negotiate, consume frames) -- the wire-mesh#45 prerequisite agent-comms needs, since its peers both listen and dial rather than only ever dialing the way web-console's own console UI does. Reconnect does not apply here: if this connection drops, only the remote redialing and being accepted again produces a new connection, and therefore a new session -- there is nothing on this side to retry. */
+async function acceptMeshSession(connection, identity, localDomains, options = {}) {
+	const clock = options.clock ?? { now: () => Date.now() };
+	let resolvePeerDeviceId = null;
+	const peerDeviceId = new Promise((resolve) => {
+		resolvePeerDeviceId = resolve;
+	});
+	let peerDeviceIdResolved = false;
+	const { session, wireUpConnection } = createSessionCore(identity, clock, null, null, (advert) => {
+		if (peerDeviceIdResolved) return;
+		peerDeviceIdResolved = true;
+		resolvePeerDeviceId?.(advert.device);
+	});
+	await wireUpConnection(connection, options.label ?? "accepted", localDomains);
+	return {
+		...session,
+		peerDeviceId
+	};
+}
+//#endregion
+export { HANDSHAKE_TIMEOUT_MS, acceptMeshSession, createMeshSession };

package/dist/domain/relay-hub.cjs

@@ -0,0 +1,99 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/domain/relay-hub.ts
+const HEX_RADIX = 16;
+const HEX_DIGITS_PER_BYTE = 2;
+function deviceKey(device) {
+	let key = "";
+	for (const byte of device) key += byte.toString(HEX_RADIX).padStart(HEX_DIGITS_PER_BYTE, "0");
+	return key;
+}
+function createRelayHub() {
+	const devices = /* @__PURE__ */ new Map();
+	const connectionDevice = /* @__PURE__ */ new Map();
+	const pairings = /* @__PURE__ */ new Map();
+	const mostRecentPairing = /* @__PURE__ */ new Map();
+	function pairingsOf(connection) {
+		const existing = pairings.get(connection);
+		if (existing) return existing;
+		const created = /* @__PURE__ */ new Map();
+		pairings.set(connection, created);
+		return created;
+	}
+	function addPairing(a, aDevice, b, bDevice) {
+		pairingsOf(a).set(deviceKey(bDevice), b);
+		pairingsOf(b).set(deviceKey(aDevice), a);
+		mostRecentPairing.set(a, b);
+		mostRecentPairing.set(b, a);
+	}
+	function forgetConnection(connection) {
+		for (const [key, registration] of devices) if (registration.connection === connection) devices.delete(key);
+		const ownDevice = connectionDevice.get(connection);
+		connectionDevice.delete(connection);
+		mostRecentPairing.delete(connection);
+		const own = pairings.get(connection);
+		if (own) {
+			for (const peer of own.values()) {
+				const peerOwn = pairings.get(peer);
+				if (peerOwn && ownDevice !== void 0) peerOwn.delete(deviceKey(ownDevice));
+				if (mostRecentPairing.get(peer) === connection) mostRecentPairing.delete(peer);
+			}
+			pairings.delete(connection);
+		}
+	}
+	async function handleFrame(connection, frame) {
+		if (frame.type === "gossip") {
+			for (const advert of frame.peers) devices.set(deviceKey(advert.device), {
+				connection,
+				device: advert.device
+			});
+			for (const registration of devices.values()) if (registration.connection === connection) {
+				connectionDevice.set(connection, registration.device);
+				break;
+			}
+			return;
+		}
+		if (frame.type === "relay-connect") {
+			const registration = devices.get(deviceKey(frame["target-device"]));
+			if (!registration || registration.connection === connection) return;
+			const initiatorDevice = connectionDevice.get(connection);
+			if (initiatorDevice === void 0) return;
+			addPairing(connection, initiatorDevice, registration.connection, registration.device);
+			await registration.connection.send({
+				type: "relay-inbound",
+				"source-device": initiatorDevice
+			});
+			return;
+		}
+		if (frame.type === "relay-data") {
+			const own = pairings.get(connection);
+			const toDevice = frame["to-device"];
+			const peer = toDevice !== void 0 ? own?.get(deviceKey(toDevice)) : mostRecentPairing.get(connection);
+			if (!peer) return;
+			const senderDevice = connectionDevice.get(connection);
+			if (senderDevice === void 0) return;
+			await peer.send({
+				type: "relay-data",
+				payload: frame.payload,
+				"from-device": senderDevice
+			});
+			return;
+		}
+	}
+	return {
+		async handleConnection(connection) {
+			try {
+				for await (const frame of connection.receive()) await handleFrame(connection, frame);
+			} catch {} finally {
+				forgetConnection(connection);
+			}
+		},
+		stop() {
+			devices.clear();
+			connectionDevice.clear();
+			pairings.clear();
+			mostRecentPairing.clear();
+		}
+	};
+}
+//#endregion
+exports.createRelayHub = createRelayHub;

package/dist/domain/relay-hub.d.cts

@@ -0,0 +1,10 @@
+import { Connection } from "../ports/transport.cjs";
+//#region src/domain/relay-hub.d.ts
+export interface RelayHub {
+  /** Drives one accepted connection until it closes: registers gossip-advertised devices, answers relay-connect by pairing and notifying the target, and forwards relay-data within established pairings. Resolves when the connection's frame stream ends. */
+  handleConnection: (connection: Readonly<Connection>) => Promise<void>;
+  /** Drops all registry and pairing state -- used by tests and by transport teardown. */
+  stop: () => void;
+}
+export declare function createRelayHub(): RelayHub;
+//#endregion

package/dist/domain/relay-hub.d.mts

@@ -0,0 +1,10 @@
+import { Connection } from "../ports/transport.mjs";
+//#region src/domain/relay-hub.d.ts
+export interface RelayHub {
+  /** Drives one accepted connection until it closes: registers gossip-advertised devices, answers relay-connect by pairing and notifying the target, and forwards relay-data within established pairings. Resolves when the connection's frame stream ends. */
+  handleConnection: (connection: Readonly<Connection>) => Promise<void>;
+  /** Drops all registry and pairing state -- used by tests and by transport teardown. */
+  stop: () => void;
+}
+export declare function createRelayHub(): RelayHub;
+//#endregion