@steve02081504/fount-p2p 0.0.13 → 0.0.14

package/discovery/advert_peer_hints.mjs

@@ -1,13 +1,15 @@
 import { normalizeTcpPort } from '../core/tcp_port.mjs'
 
 import { noteBtPeerHint } from './bt/peer_hints.mjs'
+import { normalizeLanHosts } from './lan_interfaces.mjs'
 import { noteLanPeerHint } from './lan_peer_hints.mjs'
 
 /**
  * 从已验证的 discovery advert + provider meta 写入 LAN/BT peer hints。
  * 任意 discovery 路径（node / group / scoped）收到 advert 时都应调用。
+ * meta.address（观测地址）优先于 body.lanHosts（自报地址）。
  * @param {string} verifiedNodeHash 验签通过的 nodeHash
- * @param {{ tcpPort?: unknown } | null | undefined} body advert body
+ * @param {{ tcpPort?: unknown, lanHosts?: unknown } | null | undefined} body advert body
  * @param {{ address?: unknown, peripheralId?: unknown } | null | undefined} meta discovery provider meta
  * @returns {void}
  */
@@ -15,7 +17,11 @@ export function noteAdvertPeerHints(verifiedNodeHash, body, meta) {
 	if (meta?.peripheralId)
 		noteBtPeerHint(verifiedNodeHash, meta.peripheralId)
 	const tcpPort = normalizeTcpPort(body?.tcpPort)
+	if (tcpPort == null) return
+	// lanHosts 先写（差→优，unshift 后优在前），再写观测 address，使 address 最优先
+	for (const host of normalizeLanHosts(body?.lanHosts).toReversed())
+		noteLanPeerHint(verifiedNodeHash, { host, port: tcpPort })
 	const address = String(meta?.address || '').trim()
-	if (tcpPort != null && address)
+	if (address)
 		noteLanPeerHint(verifiedNodeHash, { host: address, port: tcpPort })
 }

package/discovery/adverts.mjs

@@ -1,6 +1,8 @@
 import { normalizeHex64 } from '../core/hexIds.mjs'
 import { buildSignedAdvert, verifySignedAdvert } from '../link/handshake.mjs'
 
+import { listMulticastIpv4Addresses } from './lan_interfaces.mjs'
+
 import {
 	decryptSignalPacket,
 	encryptSignalPacket,
@@ -33,9 +35,13 @@ export function rendezvousKeyForScope(scope, selfNodeHash) {
  */
 export async function buildSignedAdvertForScope(scope, localIdentity, tcpPort) {
 	const key = rendezvousKeyForScope(scope, localIdentity.nodeHash)
+	const lanHosts = scope === 'network' && tcpPort != null
+		? listMulticastIpv4Addresses()
+		: []
 	return await buildSignedAdvert(key, Date.now(), {
 		...localIdentity,
 		...tcpPort != null ? { tcpPort } : {},
+		...lanHosts.length ? { lanHosts } : {},
 	})
 }
 

package/discovery/lan.mjs

@@ -5,8 +5,10 @@ import { base64ToBytes, bytesToBase64 } from '../core/bytes_codec.mjs'
 import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
 import { nodeDebug, shortHash } from '../node/log.mjs'
 
+import { noteAdvertPeerHints } from './advert_peer_hints.mjs'
 import { ingestNetworkAdvert } from './adverts.mjs'
-import { getLanPeerHint, noteLanPeerHint } from './lan_peer_hints.mjs'
+import { listMulticastIpv4Addresses } from './lan_interfaces.mjs'
+import { getLanPeerHint } from './lan_peer_hints.mjs'
 
 const DEFAULT_PORT = 53531
 const DEFAULT_GROUP = '239.255.42.99'
@@ -51,25 +53,26 @@ export function clearLanVisibleNodes() {
 /**
  * Untrusted ingress：验签 network advert 后写入可见池 / peer hint。
  * @param {Uint8Array} advertBytes 加密 network advert
- * @param {{ address?: string }} [meta] 发送方地址
+ * @param {{ address?: string, skipNodeHash?: string }} [meta] 发送方地址 / 本机 nodeHash（过滤自回环）
  * @returns {Promise<{ verifiedNodeHash: string, body: object } | null>} 验签结果
  */
 export async function acceptLanPresenceAdvert(advertBytes, meta = {}) {
 	if (!advertBytes?.byteLength) return null
 	const ingested = await ingestNetworkAdvert(advertBytes, meta)
 	if (!ingested) return null
+	const skipHash = meta.skipNodeHash ? normalizeHex64(meta.skipNodeHash) : null
+	if (skipHash && ingested.verifiedNodeHash === skipHash) return ingested
 	const firstSeen = !visibleByHash.has(ingested.verifiedNodeHash)
 	noteLanVisibleNode(ingested.verifiedNodeHash)
-	const host = String(meta.address || '').trim()
-	const tcpPort = Number(ingested.body?.tcpPort)
-	if (host && Number.isFinite(tcpPort) && tcpPort > 0)
-		noteLanPeerHint(ingested.verifiedNodeHash, { host, port: tcpPort })
-	if (firstSeen)
+	noteAdvertPeerHints(ingested.verifiedNodeHash, ingested.body, meta)
+	if (firstSeen) {
+		const host = String(meta.address || '').trim()
 		nodeDebug('p2p:lan peer visible', {
 			peer: shortHash(ingested.verifiedNodeHash),
 			host: host || undefined,
-			tcpPort: tcpPort > 0 ? tcpPort : undefined,
+			tcpPort: ingested.body?.tcpPort,
 		})
+	}
 	return ingested
 }
 
@@ -88,10 +91,27 @@ export function createLanDiscoveryProvider(options = {}) {
 	let refs = 0
 	/** @type {ReturnType<typeof setInterval> | null} */
 	let beaconTimer = null
+	/** @type {string | null} */
+	let selfNodeHash = null
+	/** @type {Set<string>} */
+	const joinedAddresses = new Set()
 
 	/**
-	 * @returns {import('node:dgram').Socket} 复用的组播 UDP socket
+	 * @param {import('node:dgram').Socket} sock UDP socket
+	 * @returns {void}
 	 */
+	function ensureMemberships(sock) {
+		for (const addr of listMulticastIpv4Addresses()) {
+			if (joinedAddresses.has(addr)) continue
+			try {
+				sock.addMembership(group, addr)
+				joinedAddresses.add(addr)
+			}
+			catch { /* ignore per-interface join failure */ }
+		}
+		if (!joinedAddresses.size)
+			try { sock.addMembership(group) } catch { /* ignore */ }
+	}
 	function getSocket() {
 		return socket ||= dgram.createSocket({ type: 'udp4', reuseAddr: true })
 	}
@@ -108,7 +128,7 @@ export function createLanDiscoveryProvider(options = {}) {
 					sock.once('error', reject)
 					sock.bind(port, '0.0.0.0', () => {
 						sock.off('error', reject)
-						sock.addMembership(group)
+						ensureMemberships(sock)
 						sock.setMulticastTTL(1)
 						resolve()
 					})
@@ -117,6 +137,7 @@ export function createLanDiscoveryProvider(options = {}) {
 					try { sock.close() } catch { /* ignore */ }
 					if (socket === sock) socket = null
 					bound = false
+					joinedAddresses.clear()
 					return
 				}
 				sock.on('message', (raw, rinfo) => {
@@ -131,8 +152,11 @@ export function createLanDiscoveryProvider(options = {}) {
 					}
 					catch { return }
 					if (!advertBytes?.byteLength) return
-					void acceptLanPresenceAdvert(advertBytes, { address: rinfo?.address, provider: 'lan' })
-						.catch(() => { })
+					void acceptLanPresenceAdvert(advertBytes, {
+						address: rinfo?.address,
+						provider: 'lan',
+						skipNodeHash: selfNodeHash || undefined,
+					}).catch(() => { })
 				})
 				bound = true
 			})().finally(() => {
@@ -148,10 +172,34 @@ export function createLanDiscoveryProvider(options = {}) {
 	async function multicastBeacon(beacon) {
 		await ensureBound()
 		const sock = getSocket()
+		ensureMemberships(sock)
 		const packet = Buffer.from(JSON.stringify({ type: 'presence', ...beacon }))
-		await new Promise((resolve, reject) => {
+		const addrs = listMulticastIpv4Addresses()
+		/**
+		 * @param {string | undefined} ifaceAddr 组播出口地址
+		 * @returns {Promise<void>}
+		 */
+		const sendOnce = ifaceAddr => new Promise((resolve, reject) => {
+			if (ifaceAddr) sock.setMulticastInterface(ifaceAddr)
 			sock.send(packet, port, group, error => error ? reject(error) : resolve())
 		})
+		if (!addrs.length) {
+			await sendOnce()
+			return
+		}
+		let sent = 0
+		/** @type {unknown} */
+		let lastError = null
+		for (const addr of addrs) {
+			try {
+				await sendOnce(addr)
+				sent++
+			}
+			catch (error) {
+				lastError = error
+			}
+		}
+		if (!sent) throw lastError || new Error('p2p: lan multicast send failed')
 	}
 
 	/**
@@ -164,6 +212,8 @@ export function createLanDiscoveryProvider(options = {}) {
 			refs = Math.max(0, refs - 1)
 			if (refs > 0 || !socket) return
 			if (beaconTimer) { clearInterval(beaconTimer); beaconTimer = null }
+			selfNodeHash = null
+			joinedAddresses.clear()
 			try { socket.close() } catch { /* ignore */ }
 			socket = null
 			bound = false
@@ -206,6 +256,7 @@ export function createLanDiscoveryProvider(options = {}) {
 			const send = async () => {
 				const body = await getBeacon?.()
 				if (!body) return
+				if (body.nodeHash) selfNodeHash = normalizeHex64(body.nodeHash)
 				const advertBytes = body.advertBytes?.byteLength
 					? body.advertBytes
 					: null

package/discovery/lan_interfaces.mjs

@@ -0,0 +1,78 @@
+import os from 'node:os'
+
+/** advert / 组播 beacon 携带的 LAN IPv4 上限 */
+export const MAX_LAN_HOSTS = 4
+
+const IPV4_RE = /^(?:\d{1,3}\.){3}\d{1,3}$/
+
+/**
+ * untrusted ingress：清洗 advert body 中的 LAN IPv4 列表。
+ * @param {unknown} input 原始 lanHosts
+ * @returns {string[]} 去重后的 IPv4 列表
+ */
+export function normalizeLanHosts(input) {
+	if (!input) return []
+	const arr = Array.isArray(input) ? input : [input]
+	const seen = new Set()
+	/** @type {string[]} */
+	const out = []
+	for (const item of arr) {
+		const host = String(item || '').trim()
+		if (!host || !IPV4_RE.test(host) || seen.has(host)) continue
+		seen.add(host)
+		out.push(host)
+		if (out.length >= MAX_LAN_HOSTS) break
+	}
+	return out
+}
+
+/**
+ * @param {string} addr IPv4
+ * @returns {number} 排序权重（越小越优先）
+ */
+function lanAddressRank(addr) {
+	if (addr.startsWith('169.254.')) return 100
+	if (addr.startsWith('192.168.56.')) return 90
+	if (addr.startsWith('192.168.')) return 10
+	if (addr.startsWith('10.')) return 20
+	const match = /^172\.(\d+)\./u.exec(addr)
+	if (match && Number(match[1]) >= 16 && Number(match[1]) <= 31) return 30
+	return 50
+}
+
+/**
+ * @param {string[]} addrs IPv4 列表
+ * @returns {string[]} 按 LAN 可达性优先排序
+ */
+function prioritizeLanAddresses(addrs) {
+	return [...addrs].sort((left, right) => lanAddressRank(left) - lanAddressRank(right))
+}
+
+/**
+ * @param {string | number} family os.networkInterfaces family
+ * @returns {boolean} 是否 IPv4
+ */
+function isIpv4Family(family) {
+	return family === 'IPv4' || family === 4
+}
+
+/**
+ * 本机可用于 LAN 组播 / advert 的非 internal IPv4 地址。
+ * @returns {string[]} 去重、排序后的地址列表
+ */
+export function listMulticastIpv4Addresses() {
+	const seen = new Set()
+	/** @type {string[]} */
+	const addrs = []
+	for (const ifaces of Object.values(os.networkInterfaces())) {
+		if (!ifaces) continue
+		for (const iface of ifaces) {
+			if (iface.internal || !isIpv4Family(iface.family)) continue
+			const addr = String(iface.address || '').trim()
+			if (!addr || seen.has(addr)) continue
+			seen.add(addr)
+			addrs.push(addr)
+		}
+	}
+	return prioritizeLanAddresses(addrs).slice(0, MAX_LAN_HOSTS)
+}

package/discovery/lan_peer_hints.mjs

@@ -5,11 +5,15 @@ import { createTtlMap } from '../utils/ttl_map.mjs'
 /** LAN peer hint 存活时间。 */
 export const LAN_PEER_HINT_TTL_MS = 5 * 60_000
 
-/** @type {ReturnType<typeof createTtlMap<{ host: string, port: number }>>} */
+/** 单 peer 保留的 endpoint 上限。 */
+const MAX_ENDPOINTS = 8
+
+/** @type {ReturnType<typeof createTtlMap<{ endpoints: { host: string, port: number }[] }>>} */
 const hints = createTtlMap(LAN_PEER_HINT_TTL_MS)
 
 /**
  * 记录 LAN 上观察到的 nodeHash → host:port。
+ * 最新写入排在最前（dial / getLanPeerHint 优先用新观测）。
  * @param {string} nodeHash 节点 64 hex
  * @param {{ host: string, port: number }} endpoint 端点
  * @returns {void}
@@ -19,19 +23,32 @@ export function noteLanPeerHint(nodeHash, endpoint) {
 	const host = String(endpoint?.host || '').trim()
 	const port = normalizeTcpPort(endpoint?.port)
 	if (!hash || !host || !port) return
-	hints.set(hash, { host, port })
+	const existing = hints.get(hash)?.endpoints ?? []
+	const next = existing.filter(item => !(item.host === host && item.port === port))
+	next.unshift({ host, port })
+	hints.set(hash, { endpoints: next.slice(0, MAX_ENDPOINTS) })
 }
 
 /**
- * 查询未过期的 LAN peer hint。
+ * 查询未过期的首个 LAN peer hint（最新观测）。
  * @param {string} nodeHash 节点 64 hex
  * @param {number} [now=Date.now()] 当前时间（测试可注入）
  * @returns {{ host: string, port: number } | null} hint 或 null
  */
 export function getLanPeerHint(nodeHash, now = Date.now()) {
+	return listLanPeerHints(nodeHash, now)[0] ?? null
+}
+
+/**
+ * 查询未过期的全部 LAN peer hint（最新在前）。
+ * @param {string} nodeHash 节点 64 hex
+ * @param {number} [now=Date.now()] 当前时间（测试可注入）
+ * @returns {{ host: string, port: number }[]} hint 列表
+ */
+export function listLanPeerHints(nodeHash, now = Date.now()) {
 	const hash = normalizeHex64(nodeHash)
-	if (!hash) return null
-	return hints.get(hash, now)
+	if (!hash) return []
+	return hints.get(hash, now)?.endpoints ?? []
 }
 
 /**

package/discovery/nostr.mjs

@@ -9,6 +9,7 @@ import { sha256Hex } from '../crypto/crypto.mjs'
 import { nodeDebug, shortHash } from '../node/log.mjs'
 
 import { ingestEncryptedAdvert } from './adverts.mjs'
+import { noteAdvertPeerHints } from './advert_peer_hints.mjs'
 import {
 	encryptSignalPacket,
 	groupRendezvousKey,
@@ -28,10 +29,13 @@ export const NOSTR_CONNECT_TIMEOUT_MS = 2_000
 /** 先 close，超时未 CLOSED 再 terminate（给对端优雅关闭的窗口）。 */
 export const NOSTR_CLOSE_GRACE_MS = 1_000
 
-/** Nostr advert 事件 kind。 */
-export const NOSTR_ADVERT_KIND = 27235
-/** Nostr signal 事件 kind。 */
-export const NOSTR_SIGNAL_KIND = 27236
+/** 单 relay 等待 EVENT OK 回执超时。 */
+export const NOSTR_PUBLISH_OK_TIMEOUT_MS = 3_000
+
+/** Nostr network advert 事件 kind（addressable，可存储）。 */
+export const NOSTR_ADVERT_KIND = 30787
+/** Nostr signal 事件 kind（ephemeral，实时转发）。 */
+export const NOSTR_SIGNAL_KIND = 20787
 
 const ADVERT_TTL_MS = 10 * 60_000
 
@@ -135,6 +139,7 @@ export async function acceptNostrAdvert(rendezvousKey, bytes, options = {}) {
 	}
 	if (firstSeen)
 		nodeDebug('p2p:nostr peer visible', { peer: shortHash(hash), group: !!roomSecret })
+	noteAdvertPeerHints(hash, ingested.body, options.meta || {})
 	return hash
 }
 
@@ -252,6 +257,70 @@ function connectRelay(relayUrl, timeoutMs = NOSTR_CONNECT_TIMEOUT_MS, signal) {
 	})
 }
 
+/**
+ * @param {import('ws').WebSocket} ws 已连接 relay
+ * @param {string} relayUrl 中继 URL
+ * @param {object} event 待发布事件
+ * @param {AbortSignal} [signal] 取消信号
+ * @returns {Promise<boolean>} relay 是否接受 EVENT
+ */
+function publishEventOnRelay(ws, relayUrl, event, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new Error('nostr: aborted'))
+			return
+		}
+		let settled = false
+		/**
+		 * @param {boolean} ok relay 是否接受
+		 * @param {Error | null} [error] 失败原因
+		 * @returns {void}
+		 */
+		const finish = (ok, error = null) => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			signal?.removeEventListener('abort', onAbort)
+			ws.off('message', onMessage)
+			if (error) reject(error)
+			else resolve(ok)
+		}
+		/**
+		 * @returns {void}
+		 */
+		const onAbort = () => finish(false, new Error('nostr: aborted'))
+		/**
+		 * @param {import('ws').RawData} data relay 消息
+		 * @returns {void}
+		 */
+		const onMessage = data => {
+			let parsed
+			try { parsed = JSON.parse(String(data)) } catch { return }
+			if (parsed?.[0] !== 'OK' || parsed[1] !== event.id) return
+			const accepted = parsed[2] === true
+			if (!accepted)
+				nodeDebug('p2p:nostr publish rejected', {
+					url: relayUrl,
+					reason: String(parsed[3] || 'rejected'),
+				})
+			finish(accepted)
+		}
+		const timer = setTimeout(
+			() => finish(false, new Error(`nostr: publish ok timeout for ${relayUrl}`)),
+			NOSTR_PUBLISH_OK_TIMEOUT_MS,
+		)
+		timer.unref()
+		signal?.addEventListener('abort', onAbort, { once: true })
+		ws.on('message', onMessage)
+		try {
+			ws.send(JSON.stringify(['EVENT', event]))
+		}
+		catch (error) {
+			finish(false, error instanceof Error ? error : new Error(String(error)))
+		}
+	})
+}
+
 /**
  * @param {string[]} relayUrls 中继 URL 列表
  * @param {object} event 待发布事件
@@ -267,8 +336,8 @@ async function publishEvent(relayUrls, event, signal) {
 		const ws = await connectRelay(relayUrl, NOSTR_CONNECT_TIMEOUT_MS, signal)
 		try {
 			if (signal?.aborted) throw new Error('nostr: aborted')
-			ws.send(JSON.stringify(['EVENT', event]))
-			published = true
+			const ok = await publishEventOnRelay(ws, relayUrl, event, signal)
+			if (ok) published = true
 		}
 		catch (error) {
 			lastError = error
@@ -313,7 +382,7 @@ function connectRelaysProgressive(relayUrls, onOpen, signal, sockets) {
  * @returns {() => void} 取消订阅
  */
 function subscribeNostrKind(relayUrls, options) {
-	const { kind, rendezvousKey, tagX, onPayload } = options
+	const { kind, rendezvousKey, tagX, onPayload, addressable = false } = options
 	const abortController = new AbortController()
 	/** @type {import('ws').WebSocket[]} */
 	const sockets = []
@@ -332,7 +401,9 @@ function subscribeNostrKind(relayUrls, options) {
 			}
 			catch { /* ignore */ }
 		})
-		ws.send(JSON.stringify(['REQ', subscriptionId, { kinds: [kind], '#t': [rendezvousKey], '#x': [tagX] }]))
+		const filter = { kinds: [kind], '#t': [rendezvousKey], '#x': [tagX] }
+		if (addressable) filter['#d'] = [rendezvousKey]
+		ws.send(JSON.stringify(['REQ', subscriptionId, filter]))
 	}, abortController.signal, sockets)
 	return () => {
 		abortController.abort()
@@ -378,6 +449,7 @@ export function createNostrDiscoveryProvider(options = {}) {
 			kind: NOSTR_ADVERT_KIND,
 			rendezvousKey,
 			tagX: 'advert',
+			addressable: true,
 			/**
 			 * @param {Uint8Array} bytes 加密 advert 载荷
 			 * @returns {Promise<void>}
@@ -400,6 +472,7 @@ export function createNostrDiscoveryProvider(options = {}) {
 			kind: NOSTR_ADVERT_KIND,
 			rendezvousKey,
 			tagX: 'advert',
+			addressable: true,
 			/**
 			 * @param {Uint8Array} bytes 加密 advert 载荷
 			 * @returns {Promise<void>}
@@ -441,6 +514,7 @@ export function createNostrDiscoveryProvider(options = {}) {
 					kind: NOSTR_ADVERT_KIND,
 					rendezvousKey,
 					tagX: 'advert',
+					addressable: true,
 					/**
 					 * @param {Uint8Array} bytes 加密 advert 载荷
 					 * @returns {Promise<void>}
@@ -467,12 +541,11 @@ export function createNostrDiscoveryProvider(options = {}) {
 				if (abortController.signal.aborted) return
 				const beacon = await getBeacon?.()
 				if (!beacon?.nodeHash) return
-				noteNostrVisibleNode(beacon.nodeHash)
 				const advertBody = beacon.advertBody || beacon.body || beacon
 				const bytes = encryptSignalPacket(rendezvousKey, { type: 'advert', body: advertBody })
 				const event = await signNostrEvent(
 					NOSTR_ADVERT_KIND,
-					[['t', rendezvousKey], ['x', 'advert']],
+					[['t', rendezvousKey], ['x', 'advert'], ['d', rendezvousKey]],
 					bytesToBase64(bytes),
 					secretKey,
 				)
@@ -547,6 +620,7 @@ export function createNostrDiscoveryProvider(options = {}) {
 				kind: NOSTR_ADVERT_KIND,
 				rendezvousKey,
 				tagX: 'advert',
+				addressable: true,
 				/**
 				 * @param {Uint8Array} bytes 加密 advert 载荷
 				 * @param {object} meta relay 元数据
@@ -573,12 +647,11 @@ export function createNostrDiscoveryProvider(options = {}) {
 				if (abortController.signal.aborted) return
 				const beacon = await getBeacon?.()
 				if (!beacon?.nodeHash) return
-				noteNostrGroupVisibleNode(key, beacon.nodeHash)
 				const advertBody = beacon.advertBody || beacon.body || beacon
 				const bytes = encryptSignalPacket(rendezvousKey, { type: 'advert', body: advertBody })
 				const event = await signNostrEvent(
 					NOSTR_ADVERT_KIND,
-					[['t', rendezvousKey], ['x', 'advert']],
+					[['t', rendezvousKey], ['x', 'advert'], ['d', rendezvousKey]],
 					bytesToBase64(bytes),
 					secretKey,
 				)
@@ -605,6 +678,7 @@ export function createNostrDiscoveryProvider(options = {}) {
 				kind: NOSTR_ADVERT_KIND,
 				rendezvousKey,
 				tagX: 'advert',
+				addressable: true,
 				/**
 				 * @param {Uint8Array} bytes 加密 advert 载荷
 				 * @param {object} meta relay 元数据

package/link/handshake.mjs

@@ -2,6 +2,7 @@ import { Buffer } from 'node:buffer'
 import { randomBytes } from 'node:crypto'
 
 import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
+import { normalizeLanHosts } from '../discovery/lan_interfaces.mjs'
 import { normalizeTcpPort } from '../core/tcp_port.mjs'
 import { keyPairFromSeed, pubKeyHash, sign, verify } from '../crypto/crypto.mjs'
 import { ensureNodeSeed, getNodeHash } from '../node/identity.mjs'
@@ -139,20 +140,24 @@ export async function verifyAuth(hello, auth, expectedNonce, remoteBinding) {
  * @param {number} ts 时间戳（毫秒）
  * @param {string} nodeHash 节点 nodeHash
  * @param {number | null} [tcpPort=null] 可选 LAN TCP 监听端口（签入消息）
+ * @param {unknown} [lanHosts=null] 可选 LAN IPv4 列表（签入消息）
  * @returns {Uint8Array} 待签名消息字节
  */
-export function buildAdvertMessage(rendezvousKey, ts, nodeHash, tcpPort = null) {
+export function buildAdvertMessage(rendezvousKey, ts, nodeHash, tcpPort = null, lanHosts = null) {
 	const base = `fount-advert\0${String(rendezvousKey)}\0${String(ts)}\0${normalizeHex64(nodeHash)}`
 	const port = normalizeTcpPort(tcpPort)
-	return Buffer.from(port ? `${base}\0${port}` : base, 'utf8')
+	let message = port ? `${base}\0${port}` : base
+	const hosts = normalizeLanHosts(lanHosts)
+	if (hosts.length) message += `\0${hosts.join(',')}`
+	return Buffer.from(message, 'utf8')
 }
 
 /**
  * 构造带签名的 discovery advert。
  * @param {string} rendezvousKey discovery 内部汇合键
  * @param {number} [ts=Date.now()] 时间戳（毫秒）
- * @param {{ secretKey?: Uint8Array, nodeHash?: string, nodePubKey?: string, tcpPort?: number } | null} [options] 签名身份与可选 tcpPort
- * @returns {Promise<{ nodeHash: string, nodePubKey: string, ts: number, sig: string, tcpPort?: number }>} 签名 advert
+ * @param {{ secretKey?: Uint8Array, nodeHash?: string, nodePubKey?: string, tcpPort?: number, lanHosts?: unknown }} | null} [options] 签名身份与可选 tcpPort / lanHosts
+ * @returns {Promise<{ nodeHash: string, nodePubKey: string, ts: number, sig: string, tcpPort?: number, lanHosts?: string[] }>} 签名 advert
  */
 export async function buildSignedAdvert(rendezvousKey, ts = Date.now(), options = null) {
 	const seed = options?.secretKey
@@ -166,7 +171,8 @@ export async function buildSignedAdvert(rendezvousKey, ts = Date.now(), options
 	const tcpPort = normalizeTcpPort(options?.tcpPort)
 	if (options?.tcpPort && !tcpPort)
 		throw new Error('p2p: advert tcpPort invalid')
-	const message = buildAdvertMessage(rendezvousKey, ts, nodeHash, tcpPort)
+	const lanHosts = normalizeLanHosts(options?.lanHosts)
+	const message = buildAdvertMessage(rendezvousKey, ts, nodeHash, tcpPort, lanHosts)
 	const sig = await sign(message, secretKey)
 	const advert = {
 		nodeHash,
@@ -175,6 +181,7 @@ export async function buildSignedAdvert(rendezvousKey, ts = Date.now(), options
 		sig: Buffer.from(sig).toString('hex'),
 	}
 	if (tcpPort) advert.tcpPort = tcpPort
+	if (lanHosts.length) advert.lanHosts = lanHosts
 	return advert
 }
 
@@ -195,7 +202,8 @@ export async function verifySignedAdvert(rendezvousKey, advert, now = Date.now()
 	const hasTcpPortField = !!advert?.tcpPort
 	const tcpPort = normalizeTcpPort(advert?.tcpPort)
 	if (hasTcpPortField && !tcpPort) return null
-	const message = buildAdvertMessage(rendezvousKey, ts, parsedHello.nodeHash, tcpPort)
+	const lanHosts = normalizeLanHosts(advert?.lanHosts)
+	const message = buildAdvertMessage(rendezvousKey, ts, parsedHello.nodeHash, tcpPort, lanHosts)
 	const ok = await verify(Buffer.from(sig, 'hex'), message, Buffer.from(parsedHello.nodePubKey, 'hex'))
 	return ok ? parsedHello.nodeHash : null
 }

package/link/providers/lan_tcp.mjs

@@ -3,13 +3,50 @@ import { randomBytes } from 'node:crypto'
 import net from 'node:net'
 
 import { normalizeHex64 } from '../../core/hexIds.mjs'
-import { getLanPeerHint } from '../../discovery/lan_peer_hints.mjs'
+import { getLanPeerHint, listLanPeerHints } from '../../discovery/lan_peer_hints.mjs'
 import { asLinkHandle } from '../pipe.mjs'
 
 import { LINK_LEVEL_LAN_TCP } from './levels.mjs'
 import { buildLinkOpen, createLinkIdBoundPipe, parseLinkOpen } from './link_id_pipe.mjs'
 
 const MAX_FRAME_BYTES = 1 << 20
+/** LAN TCP 单 endpoint 连接超时。 */
+const LAN_TCP_CONNECT_TIMEOUT_MS = 3_000
+
+/**
+ * @param {string} host 目标 host
+ * @param {number} port 目标 port
+ * @param {number} [timeoutMs=LAN_TCP_CONNECT_TIMEOUT_MS] 超时
+ * @returns {Promise<import('node:net').Socket>} 已连接 socket
+ */
+function connectTcp(host, port, timeoutMs = LAN_TCP_CONNECT_TIMEOUT_MS) {
+	return new Promise((resolve, reject) => {
+		const conn = net.createConnection({ host, port })
+		const timer = setTimeout(() => {
+			conn.destroy()
+			reject(new Error(`p2p: lan_tcp connect timeout ${host}:${port}`))
+		}, timeoutMs)
+		/**
+		 * @param {Error} error 连接错误
+		 * @returns {void}
+		 */
+		const onError = error => {
+			clearTimeout(timer)
+			conn.off('connect', onConnect)
+			reject(error)
+		}
+		/**
+		 * @returns {void}
+		 */
+		function onConnect() {
+			clearTimeout(timer)
+			conn.off('error', onError)
+			resolve(conn)
+		}
+		conn.once('error', onError)
+		conn.once('connect', onConnect)
+	})
+}
 
 /**
  * 在 socket 上挂 length-prefix 编解码（u32be + payload）。
@@ -168,41 +205,33 @@ async function openTcpPipe(options) {
  */
 async function dialLanTcp(options) {
 	const remoteNodeHash = normalizeHex64(options.nodeHash)
-	const hint = getLanPeerHint(remoteNodeHash)
-	if (!hint) throw new Error('p2p: lan_tcp no peer hint')
+	const hints = listLanPeerHints(remoteNodeHash)
+	if (!hints.length) throw new Error('p2p: lan_tcp no peer hint')
 
-	const socket = await new Promise((resolve, reject) => {
-		const conn = net.createConnection({ host: hint.host, port: hint.port })
-		/**
-		 * @param {Error} error 连接错误
-		 * @returns {void}
-		 */
-		const onError = error => {
-			conn.off('connect', onConnect)
-			reject(error)
+	let lastError = null
+	for (const hint of hints) {
+		/** @type {import('node:net').Socket | null} */
+		let socket = null
+		try {
+			socket = await connectTcp(hint.host, hint.port)
+			const link = await openTcpPipe({
+				initiator: true,
+				linkId: randomBytes(32).toString('hex'),
+				nodeHash: remoteNodeHash,
+				localIdentity: options.localIdentity,
+				socket,
+				host: hint.host,
+				port: hint.port,
+			})
+			await link.ready
+			return link
 		}
-		/**
-		 * @returns {void}
-		 */
-		function onConnect() {
-			conn.off('error', onError)
-			resolve(conn)
+		catch (error) {
+			lastError = error
+			try { socket?.destroy() } catch { /* ignore */ }
 		}
-		conn.once('error', onError)
-		conn.once('connect', onConnect)
-	})
-
-	const link = await openTcpPipe({
-		initiator: true,
-		linkId: randomBytes(32).toString('hex'),
-		nodeHash: remoteNodeHash,
-		localIdentity: options.localIdentity,
-		socket,
-		host: hint.host,
-		port: hint.port,
-	})
-	await link.ready
-	return link
+	}
+	throw lastError || new Error('p2p: lan_tcp dial failed')
 }
 
 /**

package/link/providers/webrtc.mjs

@@ -1,4 +1,5 @@
 import { getSignalingRuntimeConfig } from '../../node/instance.mjs'
+import { nodeDebug } from '../../node/log.mjs'
 import { ms } from '../../utils/duration.mjs'
 import { createLruMap } from '../../utils/lru.mjs'
 import {
@@ -43,8 +44,9 @@ export async function canUseWebRtcLink() {
 		await loadNodeRtcPolyfill()
 		cachedAvailable = true
 	}
-	catch {
+	catch (error) {
 		cachedAvailable = false
+		nodeDebug('p2p:webrtc unavailable', { err: formatErrorReason(error) })
 	}
 	return cachedAvailable
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.13",
+	"version": "0.0.14",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",