wire-mesh-core 1.58.7 → 2.0.0

package/dist/domain/peer-advert.d.cts

@@ -0,0 +1,45 @@
+import { B as IdentityKey, D as DeviceId, et as PeerAdvert } from "../protocol-Bi2fzBCc.cjs";
+import { t as IdentityPort } from "../identity-DImeXZcq.cjs";
+//#region src/domain/peer-advert.d.ts
+/** peer-advert's own signature field, the one entry the signature does not cover, named once here so the signing input and the reserved-extension-key guard cannot drift apart. */
+export declare const PEER_ADVERT_SIGNATURE_KEY = "signature";
+/** peer-advert's own self-certifying key field. Covered by the signature like every other entry, so an advert cannot be re-keyed after signing. */
+export declare const PEER_ADVERT_IDENTITY_KEY_KEY = "identity-key";
+/**
+ * The domain-separation prefix every peer-advert signature is computed over, per spec/transport.cddl: the ASCII string "wire-mesh/peer-advert/v1" followed by one zero byte.
+ *
+ * Deliberately not tokens.cddl's COSE Sig_structure, which every other signature in this codebase reuses via sig1ToBeSigned. An advert's extension tail is an open `* tstr => any` map, so an attacker can craft an advert whose canonical encoding also satisfies token-claims; a Sig_structure over that encoding would then be replayable as a capability token's own signed payload. This prefix makes the two byte strings disjoint by construction, since a Sig_structure always begins with the CBOR head of a 4-element array (0x84) rather than the ASCII "w" this one starts with.
+ */
+export declare const PEER_ADVERT_SIGNING_CONTEXT: Uint8Array<ArrayBuffer>;
+/**
+ * Everything a peer-advert's signature covers: the whole advert apart from `signature` itself. Spelled out as its own interface rather than derived with `Omit<PeerAdvert, "signature">`, which collapses to the bare index signature because peer-advert's open extension tail makes `keyof PeerAdvert` a plain `string`.
+ *
+ * A full PeerAdvert satisfies this structurally, which is what lets peerAdvertSigningInput take either an advert being signed or one being verified without a second overload.
+ */
+export interface UnsignedPeerAdvert {
+  readonly device: DeviceId;
+  readonly addresses: string[];
+  readonly "snapshot-seconds": number;
+  readonly "identity-key": IdentityKey;
+  /** peer-advert's own open extension tail (spec/CONVENTIONS.md's gossip-extension-namespacing convention). Every key here is signed over too, so nothing in the tail can be added, altered, or dropped without invalidating the advert. */
+  readonly [key: string]: unknown;
+}
+/** The crypto primitives verification needs, and nothing else: an advert is self-certifying, so a verifier never consults its own device-id or private key to check one. Narrowed from IdentityPort so a relay hub, which has no reason to hold a signing identity, can be given a verifier without one. */
+export type PeerAdvertVerifier = Pick<IdentityPort, "verify" | "deriveDeviceId">;
+/** The signing half's own dependency: a node only ever signs adverts naming itself, which is exactly why a gateway forwards its local peers' adverts verbatim instead of re-signing them. */
+export type PeerAdvertSigner = Pick<IdentityPort, "sign">;
+/**
+ * The exact bytes a peer-advert's signature is computed over: PEER_ADVERT_SIGNING_CONTEXT followed by the canonical CDE encoding of the advert with its `signature` entry removed and nothing else changed.
+ *
+ * Takes the advert rather than a pre-stripped copy so a verifier derives the input from precisely the bytes it received, leaving no room for the signed and checked views of an advert to disagree.
+ */
+export declare function peerAdvertSigningInput(advert: Readonly<UnsignedPeerAdvert>): Uint8Array<ArrayBuffer>;
+/** Signs an advert's content into the complete peer-advert that goes on the wire. The caller supplies `device` and `identity-key` itself rather than having them read off the signer, since the signer port carries only `sign`: a node building its own self-advert already holds both, and nothing else may legitimately sign an advert at all. */
+export declare function signPeerAdvert(identity: Readonly<PeerAdvertSigner>, advert: Readonly<UnsignedPeerAdvert>): Promise<PeerAdvert>;
+/**
+ * Both validity checks spec/transport.cddl states for a gossiped advert, in the order a verifier must apply them: the embedded identity-key self-certifies (sha256 of its public-key equals the advert's own `device`), and the signature verifies under that same key over peerAdvertSigningInput's bytes.
+ *
+ * Returns a verdict for every input, including a hostile one, and never throws. An advert's `alg` and `public-key` are attacker-chosen (identity-key constrains them to an int and a bstr, nothing more), so importing the key can legitimately fail for an algorithm no verifier implements or for key bytes of the wrong length. An unverifiable advert is a refused advert, exactly as if its signature had simply been wrong, which is why the import failure is turned into `false` here rather than propagated to a caller iterating a frame's other adverts.
+ */
+export declare function verifyPeerAdvert(identity: Readonly<PeerAdvertVerifier>, advert: Readonly<PeerAdvert>): Promise<boolean>;
+//#endregion

package/dist/domain/peer-advert.d.mts

@@ -0,0 +1,45 @@
+import { B as IdentityKey, D as DeviceId, et as PeerAdvert } from "../protocol-Bi2fzBCc.mjs";
+import { t as IdentityPort } from "../identity-Dc4xmwp3.mjs";
+//#region src/domain/peer-advert.d.ts
+/** peer-advert's own signature field, the one entry the signature does not cover, named once here so the signing input and the reserved-extension-key guard cannot drift apart. */
+export declare const PEER_ADVERT_SIGNATURE_KEY = "signature";
+/** peer-advert's own self-certifying key field. Covered by the signature like every other entry, so an advert cannot be re-keyed after signing. */
+export declare const PEER_ADVERT_IDENTITY_KEY_KEY = "identity-key";
+/**
+ * The domain-separation prefix every peer-advert signature is computed over, per spec/transport.cddl: the ASCII string "wire-mesh/peer-advert/v1" followed by one zero byte.
+ *
+ * Deliberately not tokens.cddl's COSE Sig_structure, which every other signature in this codebase reuses via sig1ToBeSigned. An advert's extension tail is an open `* tstr => any` map, so an attacker can craft an advert whose canonical encoding also satisfies token-claims; a Sig_structure over that encoding would then be replayable as a capability token's own signed payload. This prefix makes the two byte strings disjoint by construction, since a Sig_structure always begins with the CBOR head of a 4-element array (0x84) rather than the ASCII "w" this one starts with.
+ */
+export declare const PEER_ADVERT_SIGNING_CONTEXT: Uint8Array<ArrayBuffer>;
+/**
+ * Everything a peer-advert's signature covers: the whole advert apart from `signature` itself. Spelled out as its own interface rather than derived with `Omit<PeerAdvert, "signature">`, which collapses to the bare index signature because peer-advert's open extension tail makes `keyof PeerAdvert` a plain `string`.
+ *
+ * A full PeerAdvert satisfies this structurally, which is what lets peerAdvertSigningInput take either an advert being signed or one being verified without a second overload.
+ */
+export interface UnsignedPeerAdvert {
+  readonly device: DeviceId;
+  readonly addresses: string[];
+  readonly "snapshot-seconds": number;
+  readonly "identity-key": IdentityKey;
+  /** peer-advert's own open extension tail (spec/CONVENTIONS.md's gossip-extension-namespacing convention). Every key here is signed over too, so nothing in the tail can be added, altered, or dropped without invalidating the advert. */
+  readonly [key: string]: unknown;
+}
+/** The crypto primitives verification needs, and nothing else: an advert is self-certifying, so a verifier never consults its own device-id or private key to check one. Narrowed from IdentityPort so a relay hub, which has no reason to hold a signing identity, can be given a verifier without one. */
+export type PeerAdvertVerifier = Pick<IdentityPort, "verify" | "deriveDeviceId">;
+/** The signing half's own dependency: a node only ever signs adverts naming itself, which is exactly why a gateway forwards its local peers' adverts verbatim instead of re-signing them. */
+export type PeerAdvertSigner = Pick<IdentityPort, "sign">;
+/**
+ * The exact bytes a peer-advert's signature is computed over: PEER_ADVERT_SIGNING_CONTEXT followed by the canonical CDE encoding of the advert with its `signature` entry removed and nothing else changed.
+ *
+ * Takes the advert rather than a pre-stripped copy so a verifier derives the input from precisely the bytes it received, leaving no room for the signed and checked views of an advert to disagree.
+ */
+export declare function peerAdvertSigningInput(advert: Readonly<UnsignedPeerAdvert>): Uint8Array<ArrayBuffer>;
+/** Signs an advert's content into the complete peer-advert that goes on the wire. The caller supplies `device` and `identity-key` itself rather than having them read off the signer, since the signer port carries only `sign`: a node building its own self-advert already holds both, and nothing else may legitimately sign an advert at all. */
+export declare function signPeerAdvert(identity: Readonly<PeerAdvertSigner>, advert: Readonly<UnsignedPeerAdvert>): Promise<PeerAdvert>;
+/**
+ * Both validity checks spec/transport.cddl states for a gossiped advert, in the order a verifier must apply them: the embedded identity-key self-certifies (sha256 of its public-key equals the advert's own `device`), and the signature verifies under that same key over peerAdvertSigningInput's bytes.
+ *
+ * Returns a verdict for every input, including a hostile one, and never throws. An advert's `alg` and `public-key` are attacker-chosen (identity-key constrains them to an int and a bstr, nothing more), so importing the key can legitimately fail for an algorithm no verifier implements or for key bytes of the wrong length. An unverifiable advert is a refused advert, exactly as if its signature had simply been wrong, which is why the import failure is turned into `false` here rather than propagated to a caller iterating a frame's other adverts.
+ */
+export declare function verifyPeerAdvert(identity: Readonly<PeerAdvertVerifier>, advert: Readonly<PeerAdvert>): Promise<boolean>;
+//#endregion

package/dist/domain/peer-advert.mjs

@@ -0,0 +1,55 @@
+import { t as bytesEqual } from "../token-scope-Z4bmci4M.mjs";
+import { cdeEncodeOptions, encode } from "cbor2";
+//#region src/domain/peer-advert.ts
+/** peer-advert's own signature field, the one entry the signature does not cover, named once here so the signing input and the reserved-extension-key guard cannot drift apart. */
+const PEER_ADVERT_SIGNATURE_KEY = "signature";
+/** peer-advert's own self-certifying key field. Covered by the signature like every other entry, so an advert cannot be re-keyed after signing. */
+const PEER_ADVERT_IDENTITY_KEY_KEY = "identity-key";
+/**
+* The domain-separation prefix every peer-advert signature is computed over, per spec/transport.cddl: the ASCII string "wire-mesh/peer-advert/v1" followed by one zero byte.
+*
+* Deliberately not tokens.cddl's COSE Sig_structure, which every other signature in this codebase reuses via sig1ToBeSigned. An advert's extension tail is an open `* tstr => any` map, so an attacker can craft an advert whose canonical encoding also satisfies token-claims; a Sig_structure over that encoding would then be replayable as a capability token's own signed payload. This prefix makes the two byte strings disjoint by construction, since a Sig_structure always begins with the CBOR head of a 4-element array (0x84) rather than the ASCII "w" this one starts with.
+*/
+const PEER_ADVERT_SIGNING_CONTEXT = new TextEncoder().encode("wire-mesh/peer-advert/v1\0");
+/**
+* The exact bytes a peer-advert's signature is computed over: PEER_ADVERT_SIGNING_CONTEXT followed by the canonical CDE encoding of the advert with its `signature` entry removed and nothing else changed.
+*
+* Takes the advert rather than a pre-stripped copy so a verifier derives the input from precisely the bytes it received, leaving no room for the signed and checked views of an advert to disagree.
+*/
+function peerAdvertSigningInput(advert) {
+	const content = {};
+	for (const [key, value] of Object.entries(advert)) {
+		if (key === "signature") continue;
+		content[key] = value;
+	}
+	const encoded = encode(content, cdeEncodeOptions);
+	const input = new Uint8Array(PEER_ADVERT_SIGNING_CONTEXT.length + encoded.length);
+	input.set(PEER_ADVERT_SIGNING_CONTEXT, 0);
+	input.set(encoded, PEER_ADVERT_SIGNING_CONTEXT.length);
+	return input;
+}
+/** Signs an advert's content into the complete peer-advert that goes on the wire. The caller supplies `device` and `identity-key` itself rather than having them read off the signer, since the signer port carries only `sign`: a node building its own self-advert already holds both, and nothing else may legitimately sign an advert at all. */
+async function signPeerAdvert(identity, advert) {
+	const signature = await identity.sign(peerAdvertSigningInput(advert));
+	return {
+		...advert,
+		[PEER_ADVERT_SIGNATURE_KEY]: signature
+	};
+}
+/**
+* Both validity checks spec/transport.cddl states for a gossiped advert, in the order a verifier must apply them: the embedded identity-key self-certifies (sha256 of its public-key equals the advert's own `device`), and the signature verifies under that same key over peerAdvertSigningInput's bytes.
+*
+* Returns a verdict for every input, including a hostile one, and never throws. An advert's `alg` and `public-key` are attacker-chosen (identity-key constrains them to an int and a bstr, nothing more), so importing the key can legitimately fail for an algorithm no verifier implements or for key bytes of the wrong length. An unverifiable advert is a refused advert, exactly as if its signature had simply been wrong, which is why the import failure is turned into `false` here rather than propagated to a caller iterating a frame's other adverts.
+*/
+async function verifyPeerAdvert(identity, advert) {
+	const key = advert[PEER_ADVERT_IDENTITY_KEY_KEY];
+	try {
+		const derived = await identity.deriveDeviceId(key["public-key"]);
+		if (!bytesEqual(derived, advert.device)) return false;
+		return await identity.verify(key, peerAdvertSigningInput(advert), advert[PEER_ADVERT_SIGNATURE_KEY]);
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { PEER_ADVERT_IDENTITY_KEY_KEY, PEER_ADVERT_SIGNATURE_KEY, PEER_ADVERT_SIGNING_CONTEXT, peerAdvertSigningInput, signPeerAdvert, verifyPeerAdvert };

package/dist/domain/relay-hub.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_domain_peer_advert = require("./peer-advert.cjs");
 //#region src/domain/relay-hub.ts
 const HEX_RADIX = 16;
 const HEX_DIGITS_PER_BYTE = 2;
@@ -7,12 +8,31 @@ function deviceKey(device) {
 	for (const byte of device) key += byte.toString(HEX_RADIX).padStart(HEX_DIGITS_PER_BYTE, "0");
 	return key;
 }
-function createRelayHub() {
+/** The exact inverse of deviceKey, so a pairing map's own hex keys can be exported as the device-ids they were built from without holding a second copy of the bytes on the forwarding path. */
+function deviceFromKey(key) {
+	const device = new Uint8Array(key.length / HEX_DIGITS_PER_BYTE);
+	for (let i = 0; i < device.length; i++) device[i] = Number.parseInt(key.slice(i * HEX_DIGITS_PER_BYTE, (i + 1) * HEX_DIGITS_PER_BYTE), HEX_RADIX);
+	return device;
+}
+/**
+* Whether an already-verified advert may take over the registration a device currently holds (wire-mesh#225).
+*
+* Strictly newer when it arrives on a different connection from the one holding the registration, so replaying a victim's genuine advert, which carries the victim's own `snapshot-seconds` unchanged since altering it would break the signature, can never steal its route. Newer-or-equal from the connection that already holds it, so an unchanged heartbeat from the rightful owner still refreshes the addresses and extensions the hub replays in catch-up frames.
+*/
+function supersedes(registered, advert, connection) {
+	const incoming = advert["snapshot-seconds"];
+	const held = registered.advert["snapshot-seconds"];
+	return registered.connection === connection ? incoming >= held : incoming > held;
+}
+function createRelayHub(options) {
 	const connections = /* @__PURE__ */ new Set();
 	const devices = /* @__PURE__ */ new Map();
 	const connectionDevice = /* @__PURE__ */ new Map();
 	const pairings = /* @__PURE__ */ new Map();
 	const mostRecentPairing = /* @__PURE__ */ new Map();
+	function stateChanged(connection) {
+		options.onConnectionStateChanged?.(connection);
+	}
 	function pairingsOf(connection) {
 		const existing = pairings.get(connection);
 		if (existing) return existing;
@@ -38,24 +58,88 @@ function createRelayHub() {
 				const peerOwn = pairings.get(peer);
 				if (peerOwn && ownDevice !== void 0) peerOwn.delete(deviceKey(ownDevice));
 				if (mostRecentPairing.get(peer) === connection) mostRecentPairing.delete(peer);
+				stateChanged(peer);
 			}
 			pairings.delete(connection);
 		}
 	}
-	async function handleFrame(connection, frame) {
-		if (frame.type === "gossip") {
-			for (const advert of frame.peers) devices.set(deviceKey(advert.device), {
+	function exportConnection(connection) {
+		const device = connectionDevice.get(connection);
+		if (device === void 0) return;
+		const adverts = [];
+		for (const registration of devices.values()) if (registration.connection === connection) adverts.push(registration.advert);
+		const own = pairings.get(connection);
+		const pairedDevices = [...own?.keys() ?? []].map(deviceFromKey);
+		const recentPeer = mostRecentPairing.get(connection);
+		let mostRecentDevice;
+		if (own && recentPeer) {
+			for (const [key, peer] of own) if (peer === recentPeer) {
+				mostRecentDevice = deviceFromKey(key);
+				break;
+			}
+		}
+		return {
+			device,
+			adverts,
+			pairedDevices,
+			...mostRecentDevice !== void 0 ? { mostRecentDevice } : {}
+		};
+	}
+	function restoreConnections(entries) {
+		const byDevice = /* @__PURE__ */ new Map();
+		for (const { connection, state } of entries) {
+			connections.add(connection);
+			connectionDevice.set(connection, state.device);
+			byDevice.set(deviceKey(state.device), connection);
+			for (const advert of state.adverts) devices.set(deviceKey(advert.device), {
 				connection,
 				advert
 			});
+		}
+		for (const { connection, state } of entries) for (const paired of state.pairedDevices) {
+			const peer = byDevice.get(deviceKey(paired));
+			if (peer === void 0) continue;
+			pairingsOf(connection).set(deviceKey(paired), peer);
+			pairingsOf(peer).set(deviceKey(state.device), connection);
+		}
+		for (const { connection, state } of entries) {
+			const recent = state.mostRecentDevice;
+			if (recent === void 0) continue;
+			const peer = byDevice.get(deviceKey(recent));
+			if (peer !== void 0) mostRecentPairing.set(connection, peer);
+		}
+	}
+	async function handleFrame(connection, frame) {
+		if (frame.type === "gossip") {
+			const supplanted = /* @__PURE__ */ new Set();
+			const accepted = [];
+			for (const advert of frame.peers) {
+				if (!await require_domain_peer_advert.verifyPeerAdvert(options.identity, advert)) continue;
+				const key = deviceKey(advert.device);
+				const previous = devices.get(key);
+				if (previous !== void 0 && !supersedes(previous, advert, connection)) continue;
+				if (previous !== void 0 && previous.connection !== connection) supplanted.add(previous.connection);
+				devices.set(key, {
+					connection,
+					advert
+				});
+				accepted.push(advert);
+			}
+			if (accepted.length === 0) return;
 			for (const registration of devices.values()) if (registration.connection === connection) {
 				connectionDevice.set(connection, registration.advert.device);
 				break;
 			}
+			stateChanged(connection);
+			for (const other of supplanted) stateChanged(other);
+			const forwarded = {
+				type: "gossip",
+				peers: accepted
+			};
 			for (const other of connections) {
 				if (other === connection) continue;
 				try {
-					await other.send(frame);
+					await other.send(forwarded);
 				} catch {}
 			}
 			const catchUp = [];
@@ -74,6 +158,8 @@ function createRelayHub() {
 			const initiatorDevice = connectionDevice.get(connection);
 			if (initiatorDevice === void 0) return;
 			addPairing(connection, initiatorDevice, registration.connection, registration.advert.device);
+			stateChanged(connection);
+			stateChanged(registration.connection);
 			await registration.connection.send({
 				type: "relay-inbound",
 				"source-device": initiatorDevice
@@ -116,6 +202,8 @@ function createRelayHub() {
 		},
 		onFrame: handleFrame,
 		onDisconnect: forgetConnection,
+		exportConnection,
+		restoreConnections,
 		stop() {
 			connections.clear();
 			devices.clear();

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

@@ -1,6 +1,31 @@
-import { N as Frame } from "../protocol-BnbpCk0Z.cjs";
-import { t as Connection } from "../transport-Ca_ZyyZe.cjs";
+import { D as DeviceId, N as Frame, et as PeerAdvert } from "../protocol-Bi2fzBCc.cjs";
+import { t as Connection } from "../transport-Cq_odHy3.cjs";
+import { PeerAdvertVerifier } from "./peer-advert.cjs";
 //#region src/domain/relay-hub.d.ts
+/**
+ * One connection's relay state in serialisable form: everything a hub that never saw the connection register needs, alongside the still-open connection itself, to answer its next frame exactly as the hub that established the state would have. Only device-ids and adverts appear, never a Connection, so a host can persist this wherever it keeps per-connection state.
+ */
+export interface RelayConnectionState {
+  /** The device-id the hub attributes to the connection itself: what its relay-data frames are stamped with as `from-device`, and what a peer's own pairing map keys this connection by. */
+  readonly device: DeviceId;
+  /** Every peer-advert still registered against this connection in the hub's device directory, in registration order, so a restored hub can resolve a relay-connect naming one of them and can replay them in its gossip catch-up. Empty when a later connection has taken over every device-id this one advertised. */
+  readonly adverts: readonly PeerAdvert[];
+  /** The device-id of each peer this connection currently holds a relay pairing with. Order carries no meaning; the unaddressed-relay-data route is `mostRecentDevice` alone. */
+  readonly pairedDevices: readonly DeviceId[];
+  /** The peer a relay-data frame carrying no `to-device` routes to. Absent when the connection has no such fallback, either because it holds no pairings or because the peer that was most recent has since disconnected. */
+  readonly mostRecentDevice?: DeviceId;
+}
+/** One surviving connection paired with what a previous hub instance knew about it, as restoreConnections takes it. */
+export interface RelayConnectionRestore {
+  readonly connection: Readonly<Connection>;
+  readonly state: RelayConnectionState;
+}
+export interface RelayHubOptions {
+  /** The crypto primitives this hub verifies every gossiped advert with (wire-mesh#225). Narrowed to verify/deriveDeviceId rather than a full IdentityPort because an advert is self-certifying: a hub checks one against the key the advert itself carries, and never needs a signing identity of its own to do it. */
+  readonly identity: Readonly<PeerAdvertVerifier>;
+  /** Called whenever the value exportConnection returns for a connection changes: it gossiped an advert, gained or lost a pairing, or had one of its adverts taken over by another connection. A host whose own instance can be torn down while its connections stay open (the Cloudflare hub's hibernating Durable Object) reads the new value back with exportConnection, persists it against the connection, and hands it to a later instance through restoreConnections. */
+  readonly onConnectionStateChanged?: (connection: Readonly<Connection>) => void;
+}
 export interface RelayHub {
   /** Drives one accepted connection until it closes: registers gossip-advertised devices, re-broadcasts each gossip frame to every other connected client and replies to the gossiping connection with a catch-up frame of every other already-known device, answers relay-connect by pairing and notifying the target, forwards relay-data within established pairings, and replies to a bare ping with a bare pong (wire-mesh#181) so a client can time its own sender-to-hub leg independent of anything being relayed. Resolves when the connection's frame stream ends. Internally just registerConnection followed by a loop of onFrame calls and a final onDisconnect -- kept as its own method since a dedicated hub deployment (wire-mesh/cloudflare-hub) has nothing else driving the connection and wants the whole lifecycle in one call. */
   handleConnection: (connection: Readonly<Connection>) => Promise<void>;
@@ -10,8 +35,12 @@ export interface RelayHub {
   onFrame: (connection: Readonly<Connection>, frame: Frame) => Promise<void>;
   /** Cleans up all registry and pairing state for one connection once its own frame stream has ended -- the onSessionEnd counterpart registerConnection/onFrame needs for the shared-consumption case, since this hub's registry is keyed by Connection and has no other way to learn a connection is gone. */
   onDisconnect: (connection: Readonly<Connection>) => void;
+  /** The serialisable relay state of one registered connection, or undefined when it holds none worth keeping: a connection that has never gossiped an advert can neither be named by a relay-connect nor send a routable relay-data frame, so there is nothing for a later hub to restore. */
+  exportConnection: (connection: Readonly<Connection>) => RelayConnectionState | undefined;
+  /** Rebuilds device-registry and pairing state for connections that outlived the hub instance which established it, so a frame arriving on one of them routes as it did before rather than being dropped as unknown. Each entry's connection is registered as if registerConnection had been called for it. Pairings resolve within the batch: a paired device-id no entry claims belonged to a peer that disconnected while no instance was running, and its pairing is correctly left out. Meant for a freshly created hub, before it handles any frame. */
+  restoreConnections: (entries: readonly RelayConnectionRestore[]) => void;
   /** Drops all registry and pairing state -- used by tests and by transport teardown. */
   stop: () => void;
 }
-export declare function createRelayHub(): RelayHub;
+export declare function createRelayHub(options: Readonly<RelayHubOptions>): RelayHub;
 //#endregion

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

@@ -1,6 +1,31 @@
-import { N as Frame } from "../protocol-BnbpCk0Z.mjs";
-import { t as Connection } from "../transport-BH8kGWXt.mjs";
+import { D as DeviceId, N as Frame, et as PeerAdvert } from "../protocol-Bi2fzBCc.mjs";
+import { t as Connection } from "../transport-GcJ4LYVE.mjs";
+import { PeerAdvertVerifier } from "./peer-advert.mjs";
 //#region src/domain/relay-hub.d.ts
+/**
+ * One connection's relay state in serialisable form: everything a hub that never saw the connection register needs, alongside the still-open connection itself, to answer its next frame exactly as the hub that established the state would have. Only device-ids and adverts appear, never a Connection, so a host can persist this wherever it keeps per-connection state.
+ */
+export interface RelayConnectionState {
+  /** The device-id the hub attributes to the connection itself: what its relay-data frames are stamped with as `from-device`, and what a peer's own pairing map keys this connection by. */
+  readonly device: DeviceId;
+  /** Every peer-advert still registered against this connection in the hub's device directory, in registration order, so a restored hub can resolve a relay-connect naming one of them and can replay them in its gossip catch-up. Empty when a later connection has taken over every device-id this one advertised. */
+  readonly adverts: readonly PeerAdvert[];
+  /** The device-id of each peer this connection currently holds a relay pairing with. Order carries no meaning; the unaddressed-relay-data route is `mostRecentDevice` alone. */
+  readonly pairedDevices: readonly DeviceId[];
+  /** The peer a relay-data frame carrying no `to-device` routes to. Absent when the connection has no such fallback, either because it holds no pairings or because the peer that was most recent has since disconnected. */
+  readonly mostRecentDevice?: DeviceId;
+}
+/** One surviving connection paired with what a previous hub instance knew about it, as restoreConnections takes it. */
+export interface RelayConnectionRestore {
+  readonly connection: Readonly<Connection>;
+  readonly state: RelayConnectionState;
+}
+export interface RelayHubOptions {
+  /** The crypto primitives this hub verifies every gossiped advert with (wire-mesh#225). Narrowed to verify/deriveDeviceId rather than a full IdentityPort because an advert is self-certifying: a hub checks one against the key the advert itself carries, and never needs a signing identity of its own to do it. */
+  readonly identity: Readonly<PeerAdvertVerifier>;
+  /** Called whenever the value exportConnection returns for a connection changes: it gossiped an advert, gained or lost a pairing, or had one of its adverts taken over by another connection. A host whose own instance can be torn down while its connections stay open (the Cloudflare hub's hibernating Durable Object) reads the new value back with exportConnection, persists it against the connection, and hands it to a later instance through restoreConnections. */
+  readonly onConnectionStateChanged?: (connection: Readonly<Connection>) => void;
+}
 export interface RelayHub {
   /** Drives one accepted connection until it closes: registers gossip-advertised devices, re-broadcasts each gossip frame to every other connected client and replies to the gossiping connection with a catch-up frame of every other already-known device, answers relay-connect by pairing and notifying the target, forwards relay-data within established pairings, and replies to a bare ping with a bare pong (wire-mesh#181) so a client can time its own sender-to-hub leg independent of anything being relayed. Resolves when the connection's frame stream ends. Internally just registerConnection followed by a loop of onFrame calls and a final onDisconnect -- kept as its own method since a dedicated hub deployment (wire-mesh/cloudflare-hub) has nothing else driving the connection and wants the whole lifecycle in one call. */
   handleConnection: (connection: Readonly<Connection>) => Promise<void>;
@@ -10,8 +35,12 @@ export interface RelayHub {
   onFrame: (connection: Readonly<Connection>, frame: Frame) => Promise<void>;
   /** Cleans up all registry and pairing state for one connection once its own frame stream has ended -- the onSessionEnd counterpart registerConnection/onFrame needs for the shared-consumption case, since this hub's registry is keyed by Connection and has no other way to learn a connection is gone. */
   onDisconnect: (connection: Readonly<Connection>) => void;
+  /** The serialisable relay state of one registered connection, or undefined when it holds none worth keeping: a connection that has never gossiped an advert can neither be named by a relay-connect nor send a routable relay-data frame, so there is nothing for a later hub to restore. */
+  exportConnection: (connection: Readonly<Connection>) => RelayConnectionState | undefined;
+  /** Rebuilds device-registry and pairing state for connections that outlived the hub instance which established it, so a frame arriving on one of them routes as it did before rather than being dropped as unknown. Each entry's connection is registered as if registerConnection had been called for it. Pairings resolve within the batch: a paired device-id no entry claims belonged to a peer that disconnected while no instance was running, and its pairing is correctly left out. Meant for a freshly created hub, before it handles any frame. */
+  restoreConnections: (entries: readonly RelayConnectionRestore[]) => void;
   /** Drops all registry and pairing state -- used by tests and by transport teardown. */
   stop: () => void;
 }
-export declare function createRelayHub(): RelayHub;
+export declare function createRelayHub(options: Readonly<RelayHubOptions>): RelayHub;
 //#endregion

package/dist/domain/relay-hub.mjs

@@ -1,3 +1,4 @@
+import { verifyPeerAdvert } from "./peer-advert.mjs";
 //#region src/domain/relay-hub.ts
 const HEX_RADIX = 16;
 const HEX_DIGITS_PER_BYTE = 2;
@@ -6,12 +7,31 @@ function deviceKey(device) {
 	for (const byte of device) key += byte.toString(HEX_RADIX).padStart(HEX_DIGITS_PER_BYTE, "0");
 	return key;
 }
-function createRelayHub() {
+/** The exact inverse of deviceKey, so a pairing map's own hex keys can be exported as the device-ids they were built from without holding a second copy of the bytes on the forwarding path. */
+function deviceFromKey(key) {
+	const device = new Uint8Array(key.length / HEX_DIGITS_PER_BYTE);
+	for (let i = 0; i < device.length; i++) device[i] = Number.parseInt(key.slice(i * HEX_DIGITS_PER_BYTE, (i + 1) * HEX_DIGITS_PER_BYTE), HEX_RADIX);
+	return device;
+}
+/**
+* Whether an already-verified advert may take over the registration a device currently holds (wire-mesh#225).
+*
+* Strictly newer when it arrives on a different connection from the one holding the registration, so replaying a victim's genuine advert, which carries the victim's own `snapshot-seconds` unchanged since altering it would break the signature, can never steal its route. Newer-or-equal from the connection that already holds it, so an unchanged heartbeat from the rightful owner still refreshes the addresses and extensions the hub replays in catch-up frames.
+*/
+function supersedes(registered, advert, connection) {
+	const incoming = advert["snapshot-seconds"];
+	const held = registered.advert["snapshot-seconds"];
+	return registered.connection === connection ? incoming >= held : incoming > held;
+}
+function createRelayHub(options) {
 	const connections = /* @__PURE__ */ new Set();
 	const devices = /* @__PURE__ */ new Map();
 	const connectionDevice = /* @__PURE__ */ new Map();
 	const pairings = /* @__PURE__ */ new Map();
 	const mostRecentPairing = /* @__PURE__ */ new Map();
+	function stateChanged(connection) {
+		options.onConnectionStateChanged?.(connection);
+	}
 	function pairingsOf(connection) {
 		const existing = pairings.get(connection);
 		if (existing) return existing;
@@ -37,24 +57,88 @@ function createRelayHub() {
 				const peerOwn = pairings.get(peer);
 				if (peerOwn && ownDevice !== void 0) peerOwn.delete(deviceKey(ownDevice));
 				if (mostRecentPairing.get(peer) === connection) mostRecentPairing.delete(peer);
+				stateChanged(peer);
 			}
 			pairings.delete(connection);
 		}
 	}
-	async function handleFrame(connection, frame) {
-		if (frame.type === "gossip") {
-			for (const advert of frame.peers) devices.set(deviceKey(advert.device), {
+	function exportConnection(connection) {
+		const device = connectionDevice.get(connection);
+		if (device === void 0) return;
+		const adverts = [];
+		for (const registration of devices.values()) if (registration.connection === connection) adverts.push(registration.advert);
+		const own = pairings.get(connection);
+		const pairedDevices = [...own?.keys() ?? []].map(deviceFromKey);
+		const recentPeer = mostRecentPairing.get(connection);
+		let mostRecentDevice;
+		if (own && recentPeer) {
+			for (const [key, peer] of own) if (peer === recentPeer) {
+				mostRecentDevice = deviceFromKey(key);
+				break;
+			}
+		}
+		return {
+			device,
+			adverts,
+			pairedDevices,
+			...mostRecentDevice !== void 0 ? { mostRecentDevice } : {}
+		};
+	}
+	function restoreConnections(entries) {
+		const byDevice = /* @__PURE__ */ new Map();
+		for (const { connection, state } of entries) {
+			connections.add(connection);
+			connectionDevice.set(connection, state.device);
+			byDevice.set(deviceKey(state.device), connection);
+			for (const advert of state.adverts) devices.set(deviceKey(advert.device), {
 				connection,
 				advert
 			});
+		}
+		for (const { connection, state } of entries) for (const paired of state.pairedDevices) {
+			const peer = byDevice.get(deviceKey(paired));
+			if (peer === void 0) continue;
+			pairingsOf(connection).set(deviceKey(paired), peer);
+			pairingsOf(peer).set(deviceKey(state.device), connection);
+		}
+		for (const { connection, state } of entries) {
+			const recent = state.mostRecentDevice;
+			if (recent === void 0) continue;
+			const peer = byDevice.get(deviceKey(recent));
+			if (peer !== void 0) mostRecentPairing.set(connection, peer);
+		}
+	}
+	async function handleFrame(connection, frame) {
+		if (frame.type === "gossip") {
+			const supplanted = /* @__PURE__ */ new Set();
+			const accepted = [];
+			for (const advert of frame.peers) {
+				if (!await verifyPeerAdvert(options.identity, advert)) continue;
+				const key = deviceKey(advert.device);
+				const previous = devices.get(key);
+				if (previous !== void 0 && !supersedes(previous, advert, connection)) continue;
+				if (previous !== void 0 && previous.connection !== connection) supplanted.add(previous.connection);
+				devices.set(key, {
+					connection,
+					advert
+				});
+				accepted.push(advert);
+			}
+			if (accepted.length === 0) return;
 			for (const registration of devices.values()) if (registration.connection === connection) {
 				connectionDevice.set(connection, registration.advert.device);
 				break;
 			}
+			stateChanged(connection);
+			for (const other of supplanted) stateChanged(other);
+			const forwarded = {
+				type: "gossip",
+				peers: accepted
+			};
 			for (const other of connections) {
 				if (other === connection) continue;
 				try {
-					await other.send(frame);
+					await other.send(forwarded);
 				} catch {}
 			}
 			const catchUp = [];
@@ -73,6 +157,8 @@ function createRelayHub() {
 			const initiatorDevice = connectionDevice.get(connection);
 			if (initiatorDevice === void 0) return;
 			addPairing(connection, initiatorDevice, registration.connection, registration.advert.device);
+			stateChanged(connection);
+			stateChanged(registration.connection);
 			await registration.connection.send({
 				type: "relay-inbound",
 				"source-device": initiatorDevice
@@ -115,6 +201,8 @@ function createRelayHub() {
 		},
 		onFrame: handleFrame,
 		onDisconnect: forgetConnection,
+		exportConnection,
+		restoreConnections,
 		stop() {
 			connections.clear();
 			devices.clear();

package/dist/domain/relay-use-gate.d.cts

@@ -1,5 +1,5 @@
-import { N as Frame } from "../protocol-BnbpCk0Z.cjs";
-import { t as Connection } from "../transport-Ca_ZyyZe.cjs";
+import { N as Frame } from "../protocol-Bi2fzBCc.cjs";
+import { t as Connection } from "../transport-Cq_odHy3.cjs";
 //#region src/domain/relay-use-gate.d.ts
 export interface RelayUseAuthorizationTracker {
   /** True once authorize() has been called for this exact connection and revoke() has not been called since. */

package/dist/domain/relay-use-gate.d.mts

@@ -1,5 +1,5 @@
-import { N as Frame } from "../protocol-BnbpCk0Z.mjs";
-import { t as Connection } from "../transport-BH8kGWXt.mjs";
+import { N as Frame } from "../protocol-Bi2fzBCc.mjs";
+import { t as Connection } from "../transport-GcJ4LYVE.mjs";
 //#region src/domain/relay-use-gate.d.ts
 export interface RelayUseAuthorizationTracker {
   /** True once authorize() has been called for this exact connection and revoke() has not been called since. */

package/dist/domain/revocation-view.d.cts

@@ -1,5 +1,5 @@
-import { bt as RevocationEntry } from "../protocol-BnbpCk0Z.cjs";
-import { a as RevocationCheck, d as VerifyRevocationEntryOptions, o as RevocationEntryVerdict } from "../tokens-BL2BzOmN.cjs";
+import { bt as RevocationEntry } from "../protocol-Bi2fzBCc.cjs";
+import { a as RevocationCheck, d as VerifyRevocationEntryOptions, o as RevocationEntryVerdict } from "../tokens-BDVxEvl2.cjs";
 //#region src/domain/revocation-view.d.ts
 /**
  * An in-memory RevocationCheck fed by ingested revocation-announce frames. Keyed by token-id alone, per management.cddl's contract: a token-id can legitimately carry multiple recorded entries from different issuers (the token's own issuer, and/or any number of parties holding a delegated manage:revoke authorization over it) -- entriesFor returns every one of them unfiltered, since checking which actually apply (issuer-match, or a verified authorization) is verifyTokenChain's own obligation, not this store's.

package/dist/domain/revocation-view.d.mts

@@ -1,5 +1,5 @@
-import { bt as RevocationEntry } from "../protocol-BnbpCk0Z.mjs";
-import { a as RevocationCheck, d as VerifyRevocationEntryOptions, o as RevocationEntryVerdict } from "../tokens-DtjdYS_a.mjs";
+import { bt as RevocationEntry } from "../protocol-Bi2fzBCc.mjs";
+import { a as RevocationCheck, d as VerifyRevocationEntryOptions, o as RevocationEntryVerdict } from "../tokens-0r9ipK1r.mjs";
 //#region src/domain/revocation-view.d.ts
 /**
  * An in-memory RevocationCheck fed by ingested revocation-announce frames. Keyed by token-id alone, per management.cddl's contract: a token-id can legitimately carry multiple recorded entries from different issuers (the token's own issuer, and/or any number of parties holding a delegated manage:revoke authorization over it) -- entriesFor returns every one of them unfiltered, since checking which actually apply (issuer-match, or a verified authorization) is verifyTokenChain's own obligation, not this store's.

package/dist/domain/room-rekey.d.cts

@@ -1,8 +1,8 @@
-import { D as DeviceId, V as ManageCommand, p as CapabilityToken } from "../protocol-BnbpCk0Z.cjs";
-import { t as IdentityPort } from "../identity-BRlM-Krs.cjs";
+import { D as DeviceId, V as ManageCommand, p as CapabilityToken } from "../protocol-Bi2fzBCc.cjs";
+import { t as IdentityPort } from "../identity-DImeXZcq.cjs";
 import { t as Clock } from "../clock-DiSx-WKM.cjs";
 import { IncomingManageRequest, ManageOutcome, MeshSession } from "./mesh-session.cjs";
-import { a as RevocationCheck } from "../tokens-BL2BzOmN.cjs";
+import { a as RevocationCheck } from "../tokens-BDVxEvl2.cjs";
 //#region src/domain/room-rekey.d.ts
 /**
  * Builds a room.rekey command per room.cddl. The outer verb is room:member, the same "one resource, several inner verbs" pattern room.send/room.leave/room.members already establish -- not a new capability of its own.

package/dist/domain/room-rekey.d.mts

@@ -1,8 +1,8 @@
-import { D as DeviceId, V as ManageCommand, p as CapabilityToken } from "../protocol-BnbpCk0Z.mjs";
-import { t as IdentityPort } from "../identity-DiuayfEd.mjs";
+import { D as DeviceId, V as ManageCommand, p as CapabilityToken } from "../protocol-Bi2fzBCc.mjs";
+import { t as IdentityPort } from "../identity-Dc4xmwp3.mjs";
 import { t as Clock } from "../clock-DiSx-WKM.mjs";
 import { IncomingManageRequest, ManageOutcome, MeshSession } from "./mesh-session.mjs";
-import { a as RevocationCheck } from "../tokens-DtjdYS_a.mjs";
+import { a as RevocationCheck } from "../tokens-0r9ipK1r.mjs";
 //#region src/domain/room-rekey.d.ts
 /**
  * Builds a room.rekey command per room.cddl. The outer verb is room:member, the same "one resource, several inner verbs" pattern room.send/room.leave/room.members already establish -- not a new capability of its own.

package/dist/domain/room-token-verification.d.cts

@@ -1,2 +1,2 @@
-import { a as verifyRoomToken, i as VerifyRoomTokenOptions, n as RoomTokenVerdict, r as RoomTokenVerdictReason, t as ROOM_MEMBER_CAPABILITY } from "../room-token-verification-D9ogJTO3.cjs";
+import { a as verifyRoomToken, i as VerifyRoomTokenOptions, n as RoomTokenVerdict, r as RoomTokenVerdictReason, t as ROOM_MEMBER_CAPABILITY } from "../room-token-verification-CDXkm_Tg.cjs";
 export { ROOM_MEMBER_CAPABILITY, RoomTokenVerdict, RoomTokenVerdictReason, VerifyRoomTokenOptions, verifyRoomToken };

package/dist/domain/room-token-verification.d.mts

@@ -1,2 +1,2 @@
-import { a as verifyRoomToken, i as VerifyRoomTokenOptions, n as RoomTokenVerdict, r as RoomTokenVerdictReason, t as ROOM_MEMBER_CAPABILITY } from "../room-token-verification-NjaqYY4k.mjs";
+import { a as verifyRoomToken, i as VerifyRoomTokenOptions, n as RoomTokenVerdict, r as RoomTokenVerdictReason, t as ROOM_MEMBER_CAPABILITY } from "../room-token-verification-CnHNaA8J.mjs";
 export { ROOM_MEMBER_CAPABILITY, RoomTokenVerdict, RoomTokenVerdictReason, VerifyRoomTokenOptions, verifyRoomToken };