@steve02081504/fount-p2p 0.0.46 → 0.0.48

package/link/providers/webrtc.mjs

@@ -12,11 +12,65 @@ import {
 	onBufferedAmountLow,
 } from '../channel_mux.mjs'
 import { asLinkHandle, createLinkPipe } from '../pipe.mjs'
+import { iceLocalHostnameLadder } from '../../node/signaling_config.mjs'
 import { loadNodeRtcPolyfill, waitForChannelState } from '../rtc/index.mjs'
 import { extractDtlsFingerprint } from '../sdp_fingerprint.mjs'
 
 import { LINK_LEVEL_WEBRTC } from './levels.mjs'
 
+/** 收到候选后多久无新候选就视为 gathering 收齐（polyfill 不推 complete 时的兜底）。 */
+export const ICE_CANDIDATE_SETTLE_MS = 300
+/** gathering 状态轮询间隔。 */
+const ICE_GATHERING_POLL_MS = 50
+/** 一个候选都没收到时，等这么久就放行让 DTLS/数据通道自行判成败。 */
+export const ICE_GATHERING_STALL_MS = ms('3s')
+
+/**
+ * 无 trickle ICE 时等本地候选收齐。
+ *
+ * 不把 `iceGatheringState === 'complete'` 当作唯一完成条件，也不靠比较 SDP 字符串：服务端 polyfill
+ * （node-datachannel）把候选通过 `icecandidate` 事件派发，`localDescription.sdp` 里并不含候选行，
+ * 而 gathering 状态在「全部 relay 超时」等情况下会长期停在 'gathering'（fount-p2p#37 次要观察）。
+ * 所以完成判据是：状态 complete、收到过候选且一段时间内再无新候选、或一个候选都没收到时直接放行。
+ * 最后一种走 [ICE_GATHERING_STALL_MS]，让 DTLS/数据通道自己判成败，而不是在握手超时后才硬失败。
+ * @param {{ iceGatheringState: () => string, candidateCount?: () => number, handshakeTimeoutMs: number, settleMs?: number, stallMs?: number, onStall?: (elapsedMs: number) => void }} options 观测、超时与窗口配置
+ * @returns {Promise<'complete' | 'stable' | 'stalled'>} 结束原因
+ * @throws {Error} 超过 handshakeTimeoutMs 仍未收齐
+ */
+export async function collectIceGathering(options) {
+	const { iceGatheringState, candidateCount, handshakeTimeoutMs, onStall } = options
+	const settleMs = options.settleMs ?? ICE_CANDIDATE_SETTLE_MS
+	const stallMs = options.stallMs ?? ICE_GATHERING_STALL_MS
+	const startedAt = Date.now()
+	const deadline = startedAt + handshakeTimeoutMs
+	const failIfOverdue = () => {
+		if (Date.now() >= deadline)
+			throw new Error(`p2p: ice gathering incomplete after ${handshakeTimeoutMs}ms`)
+	}
+	const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+	while (true) {
+		if (iceGatheringState() === 'complete') return 'complete'
+		await sleep(ICE_GATHERING_POLL_MS)
+		if (iceGatheringState() === 'complete') return 'complete'
+		const candidates = candidateCount?.() ?? 0
+		// 一个候选都没收到，再等也不会变：放行让 DTLS/数据通道自己判成败。
+		if (!candidates) {
+			const elapsedMs = Date.now() - startedAt
+			if (elapsedMs >= stallMs) {
+				onStall?.(elapsedMs)
+				return 'stalled'
+			}
+			failIfOverdue()
+			continue
+		}
+		// 有候选了：等「再无新候选」的窗口过去；窗口内又来候选就重新计时。
+		await sleep(settleMs)
+		if (iceGatheringState() === 'complete') return 'complete'
+		if ((candidateCount?.() ?? 0) === candidates) return 'stable'
+		failIfOverdue()
+	}
+}
+
 /**
  * @param {unknown} error 原始错误
  * @returns {string} 短 reason
@@ -52,6 +106,11 @@ export async function canUseWebRtcLink() {
 
 /**
  * 建立 WebRTC link（双 DataChannel + discovery 信令）。
+ *
+ * ICE 本地主机名策略按观测结果逐级升级（见 [iceLocalHostnameLadder]）：一级 gathering 后候选集为空
+ * 就换更宽松的一级重建 peer connection 重发 offer（**全新一次建链尝试**，不是重新协商已有连接，
+ * 所以 DTLS 指纹绑定语义不变）。接受方按 offer 里的 `rung` 在同级重建并回 answer，自身不升级，
+ * 故收敛有界。
  * @param {object} options link 配置
  * @param {string | null} [options.nodeHash] 期望的对端 nodeHash
  * @param {boolean} options.initiator 是否为连接发起方
@@ -59,19 +118,25 @@ export async function canUseWebRtcLink() {
  * @param {RTCConfiguration['iceServers']} [options.iceServers] ICE 服务器列表
  * @param {number} [options.heartbeatMs] 心跳间隔
  * @param {number} [options.idleTimeoutMs] 无入站流量超时
- * @param {number} [options.handshakeTimeoutMs] 握手超时
+ * @param {number} [options.handshakeTimeoutMs] 握手超时（同时是整个升级阶梯的总预算）
  * @param {import('../rtc/polyfill.mjs').LoadedRtcPolyfill} [options.rtc] RTC 构造器
+ * @param {typeof import('../rtc/polyfill.mjs').loadNodeRtcPolyfill} [options.loadRtc] RTC 加载函数（测试注入）
+ * @param {typeof createLinkPipe} [options.createPipe] pipe 工厂（测试注入）
+ * @param {number} [options.iceCandidateSettleMs] 候选收齐窗口覆盖（测试注入）
+ * @param {number} [options.iceGatheringStallMs] gathering 停滞窗口覆盖（测试注入）
  * @param {{ nodeHash?: string, nodePubKey?: string, secretKey?: Uint8Array, nonce?: string } | null} [options.localIdentity] 本地握手身份
  * @returns {Promise<import('./index.mjs').LinkHandle>} link 句柄
  */
 export async function createWebRtcLink(options) {
 	const handshakeTimeoutMs = Number(options.handshakeTimeoutMs) || ms('10s')
 	const channelOpenTimeoutMs = Math.max(handshakeTimeoutMs, ms('30s'))
-	const rtc = options.rtc ?? await loadNodeRtcPolyfill()
-	const trickleIceOff = getSignalingRuntimeConfig().channels.webrtc?.trickleIceOff === true
-	const peerConnection = new rtc.RTCPeerConnection(options.iceServers?.length ? { iceServers: options.iceServers } : undefined)
+	const loadRtc = options.loadRtc ?? loadNodeRtcPolyfill
+	const icePolicy = getSignalingRuntimeConfig().channels.webrtc?.iceLocalHostnamePolicy
+	const rungs = iceLocalHostnameLadder(icePolicy)
 	const remoteSignalQueue = []
 	const seenRemoteSignals = createLruMap(1024)
+	/** @type {InstanceType<import('../rtc/polyfill.mjs').LoadedRtcPolyfill['RTCPeerConnection']> & { onicecandidate?: unknown, ondatachannel?: unknown, onconnectionstatechange?: unknown }} */
+	let peerConnection = null
 	let remoteDescriptionSet = false
 	let controlChannel = null
 	let bulkChannel = null
@@ -80,6 +145,9 @@ export async function createWebRtcLink(options) {
 	let controlLowEvents = 0
 	let bulkLowEvents = 0
 	let reconnectCount = 0
+	let rungIndex = 0
+	/** 当前一级收到的 ICE 候选数（polyfill 不把候选写进 SDP，故单独计数）。 */
+	let localCandidateCount = 0
 
 	/**
 	 * @param {unknown} message 信令载荷
@@ -89,7 +157,8 @@ export async function createWebRtcLink(options) {
 		await Promise.resolve(options.signal.send(message))
 	}
 
-	const pipe = createLinkPipe({
+	const createPipe = options.createPipe ?? createLinkPipe
+	const pipe = createPipe({
 		providerId: 'webrtc',
 		level: LINK_LEVEL_WEBRTC,
 		initiator: !!options.initiator,
@@ -98,10 +167,10 @@ export async function createWebRtcLink(options) {
 		heartbeatMs: options.heartbeatMs,
 		idleTimeoutMs: options.idleTimeoutMs,
 		handshakeTimeoutMs,
-		/** @returns {string} 本端 DTLS fingerprint */
-		getLocalBinding: () => extractDtlsFingerprint(peerConnection.localDescription?.sdp || ''),
+		/** @returns {string} 本端 DTLS fingerprint（取当前一级的 peer connection） */
+		getLocalBinding: () => extractDtlsFingerprint(peerConnection?.localDescription?.sdp || ''),
 		/** @returns {string} 对端 DTLS fingerprint */
-		getRemoteBinding: () => extractDtlsFingerprint(peerConnection.remoteDescription?.sdp || ''),
+		getRemoteBinding: () => extractDtlsFingerprint(peerConnection?.remoteDescription?.sdp || ''),
 		/**
 		 * @param {string} text control JSON
 		 * @returns {void}
@@ -127,15 +196,17 @@ export async function createWebRtcLink(options) {
 			sendQueues?.clear()
 			try { controlChannel?.close() } catch { /* ignore */ }
 			try { bulkChannel?.close() } catch { /* ignore */ }
-			try { await peerConnection.close() } catch { /* ignore */ }
+			try { await peerConnection?.close() } catch { /* ignore */ }
 		},
 		/**
 		 * @returns {object} WebRTC 附加 stats
 		 */
 		extraStats() {
 			return {
-				connectionState: peerConnection.connectionState,
-				iceConnectionState: peerConnection.iceConnectionState,
+				connectionState: peerConnection?.connectionState,
+				iceConnectionState: peerConnection?.iceConnectionState,
+				iceLocalHostnamePolicy: rungs[rungIndex],
+				iceRung: rungIndex,
 				reconnectCount,
 				pending: sendQueues?.pending() ?? { control: 0, bulk: 0 },
 				controlBufferedAmount: controlChannel?.bufferedAmount ?? 0,
@@ -175,17 +246,102 @@ export async function createWebRtcLink(options) {
 	}
 
 	/**
+	 * 取第 index 级策略对应的 RTC 构造器（策略在包装期烘入，故每级都要重新取）。
+	 * @param {number} index 阶梯下标
+	 * @returns {Promise<import('../rtc/polyfill.mjs').LoadedRtcPolyfill>} RTC 构造器
+	 */
+	function rtcForRung(index) {
+		if (options.rtc) return options.rtc
+		return loadRtc({ policy: rungs[Math.min(index, rungs.length - 1)] })
+	}
+
+	/**
+	 * 用第 index 级策略重建 peer connection（换级即换 pc：一次全新建链尝试）。
+	 * @param {number} index 阶梯下标
+	 * @returns {Promise<void>}
+	 */
+	async function buildPeerConnection(index) {
+		const previous = peerConnection
+		rungIndex = Math.min(index, rungs.length - 1)
+		const rtc = await rtcForRung(rungIndex)
+		peerConnection = new rtc.RTCPeerConnection(options.iceServers?.length ? { iceServers: options.iceServers } : undefined)
+		remoteDescriptionSet = false
+		remoteSignalQueue.length = 0
+		localCandidateCount = 0
+		attachPeerConnection(peerConnection)
+		if (previous)
+			try { await previous.close() } catch { /* ignore */ }
+		nodeDebug('p2p:webrtc ice rung', {
+			rung: rungIndex,
+			policy: rungs[rungIndex],
+			rungs: rungs.length,
+		})
+	}
+
+	/**
+	 * 确保当前已有一级 peer connection：接受方在收到第一份信令前也要有实例才能 setRemoteDescription。
 	 * @returns {Promise<void>}
 	 */
+	async function ensurePeerConnection() {
+		if (!peerConnection) await buildPeerConnection(rungIndex)
+	}
+
+	/**
+	 * 给 peer connection 挂上事件与回调（换级重建后需重新挂）。
+	 * @param {RTCPeerConnection} connection peer connection
+	 * @returns {void}
+	 */
+	function attachPeerConnection(connection) {
+		// 候选随 description 一次性带出（对端要先有 remoteDescription 才吃候选），故这里只计数、不外发。
+		// 事件 API 由后端提供（W3C 是 addEventListener）；缺失时退化为 onicecandidate 计数。
+		const countCandidate = event => {
+			if (event?.candidate) localCandidateCount++
+		}
+		if (connection.addEventListener) connection.addEventListener('icecandidate', countCandidate)
+		else {
+			const previousHandler = connection.onicecandidate
+			connection.onicecandidate = event => {
+				countCandidate(event)
+				previousHandler?.(event)
+			}
+		}
+		connection.ondatachannel = event => {
+			attachChannel(event.channel)
+			void maybeStartPostOpenFlow().catch(error => pipe.close(`channel-attach-failed:${formatErrorReason(error)}`))
+		}
+		connection.onconnectionstatechange = () => {
+			if (['failed', 'closed', 'disconnected'].includes(connection.connectionState)) {
+				reconnectCount++
+				void pipe.close(`connection-${connection.connectionState}`)
+			}
+		}
+	}
+
+	/**
+	 * 等本地候选收齐（停滞判定见 [collectIceGathering]），并回报本次是否产出了候选。
+	 * @returns {Promise<boolean>} 是否收到过候选
+	 */
 	async function waitForIceGatheringComplete() {
-		if (!trickleIceOff || peerConnection.iceGatheringState === 'complete') return
-		const deadline = Date.now() + handshakeTimeoutMs
-		while (peerConnection.iceGatheringState !== 'complete' && Date.now() < deadline)
-			await new Promise(resolve => setTimeout(resolve, 50))
-		if (peerConnection.iceGatheringState !== 'complete') {
+		try {
+			await collectIceGathering({
+				iceGatheringState: () => peerConnection.iceGatheringState,
+				candidateCount: () => localCandidateCount,
+				handshakeTimeoutMs,
+				settleMs: options.iceCandidateSettleMs,
+				stallMs: options.iceGatheringStallMs,
+				onStall: elapsedMs => nodeDebug('p2p:webrtc ice gathering stalled without candidates', {
+					elapsedMs,
+					rung: rungIndex,
+					policy: rungs[rungIndex],
+					iceServers: options.iceServers?.length || 0,
+				}),
+			})
+		}
+		catch (error) {
 			await pipe.close('ice-gathering-timeout')
-			throw new Error(`p2p: ice gathering incomplete after ${handshakeTimeoutMs}ms`)
+			throw error
 		}
+		return localCandidateCount > 0
 	}
 
 	/**
@@ -214,21 +370,35 @@ export async function createWebRtcLink(options) {
 	 */
 	async function handleRemoteSignal(message) {
 		if (!message?.type) return
+		// 信令与建链是并发的：任何入站信令都要先确保当前这一级已有可用 pc。
+		await ensurePeerConnection()
 		const signalKey = message.type === 'ice' && message.candidate
 			? `ice:${message.candidate.candidate ?? ''}:${message.candidate.sdpMid ?? ''}:${message.candidate.sdpMLineIndex ?? ''}`
 			: JSON.stringify(message)
 		if (seenRemoteSignals.has(signalKey)) return
 		seenRemoteSignals.touch(signalKey, true)
 		if (message.type === 'description' && message.description) {
+			// 接受方按 offer 的级号重建，保证自己的候选过滤策略与发起方同一级；自身不升级，
+			// 所以阶梯收敛有界（由发起方的观测结果驱动）。
+			const remoteRung = Number.isInteger(message.rung) ? Math.max(0, message.rung) : 0
+			if (message.description.type === 'offer' && !options.initiator && remoteRung !== rungIndex)
+				await buildPeerConnection(remoteRung)
 			if (message.description.type === 'answer' && peerConnection.signalingState === 'stable') return
 			await applyRemoteDescription(message.description)
 			if (message.description.type === 'offer') {
 				const answer = await peerConnection.createAnswer()
 				await peerConnection.setLocalDescription(answer)
 				await flushQueuedIceCandidates()
-				await waitForIceGatheringComplete()
+				const hasCandidates = await waitForIceGatheringComplete()
+				nodeDebug('p2p:webrtc answer gathered', {
+					rung: rungIndex,
+					policy: rungs[rungIndex],
+					candidates: localCandidateCount,
+					hasCandidates,
+				})
 				await sendSignal({
 					type: 'description',
+					rung: rungIndex,
 					description: peerConnection.localDescription?.toJSON?.() ?? peerConnection.localDescription ?? answer,
 				})
 				await pipe.maybeSendAuth()
@@ -299,46 +469,55 @@ export async function createWebRtcLink(options) {
 		void handleRemoteSignal(message).catch(error => pipe.close(`signal-error:${formatErrorReason(error)}`))
 	}) ?? null
 
-	/**
-	 * @param {RTCPeerConnectionIceEvent} event ICE candidate 事件
-	 * @returns {void}
-	 */
-	peerConnection.onicecandidate = event => {
-		if (trickleIceOff || !event.candidate) return
-		void sendSignal({
-			type: 'ice',
-			candidate: event.candidate.toJSON?.() || event.candidate,
-		}).catch(error => pipe.close(`signal-send-failed:${formatErrorReason(error)}`))
-	}
-	/**
-	 * @param {RTCDataChannelEvent} event 远端 data channel 事件
-	 * @returns {void}
-	 */
-	peerConnection.ondatachannel = event => {
-		attachChannel(event.channel)
-		void maybeStartPostOpenFlow().catch(error => pipe.close(`channel-attach-failed:${formatErrorReason(error)}`))
-	}
-
-	/**
-	 * 连接失败/断开时递增重连计数并关闭 pipe。
-	 */
-	peerConnection.onconnectionstatechange = () => {
-		if (['failed', 'closed', 'disconnected'].includes(peerConnection.connectionState)) {
-			reconnectCount++
-			void pipe.close(`connection-${peerConnection.connectionState}`)
-		}
-	}
+	// 信令随时可能到，故先为当前一级建好 pc（发起方随后会在阶梯里逐级重建）。
+	await ensurePeerConnection()
 
 	if (options.initiator) {
-		attachChannel(peerConnection.createDataChannel(CHANNEL_CONTROL))
-		attachChannel(peerConnection.createDataChannel(CHANNEL_BULK))
-		const offer = await peerConnection.createOffer()
-		await peerConnection.setLocalDescription(offer)
-		await waitForIceGatheringComplete()
-		await sendSignal({
-			type: 'description',
-			description: peerConnection.localDescription?.toJSON?.() ?? peerConnection.localDescription ?? offer,
-		})
+		// ICE 阶梯：一级 gathering 后候选集为空就升到更宽松的一级，用全新 peer connection 重发 offer。
+		// 总预算沿用 handshakeTimeoutMs，故整条阶梯（含最后一级的数据通道等待）仍有界。
+		const ladderDeadline = Date.now() + handshakeTimeoutMs
+		let sentOffer = false
+		for (let index = 0; index < rungs.length; index++) {
+			await buildPeerConnection(index)
+			attachChannel(peerConnection.createDataChannel(CHANNEL_CONTROL))
+			attachChannel(peerConnection.createDataChannel(CHANNEL_BULK))
+			const offer = await peerConnection.createOffer()
+			await peerConnection.setLocalDescription(offer)
+			const hasCandidates = await waitForIceGatheringComplete()
+			nodeDebug('p2p:webrtc offer gathered', {
+				rung: index,
+				policy: rungs[index],
+				candidates: localCandidateCount,
+			})
+			// 候选集为空说明这一级策略把本机候选全滤掉了（例如只产出 mDNS 候选），换更宽松的一级重建。
+			// 只在预算内、且还有更宽松的一级时升级；`rewrite-loopback` 起点不会走到这里（阶梯只有它自己）。
+			if (!hasCandidates && Date.now() < ladderDeadline && index + 1 < rungs.length) {
+				nodeDebug('p2p:webrtc ice rung escalated', {
+					from: rungs[index],
+					to: rungs[index + 1],
+					rung: index + 1,
+				})
+				continue
+			}
+			await sendSignal({
+				type: 'description',
+				rung: index,
+				description: peerConnection.localDescription?.toJSON?.() ?? peerConnection.localDescription ?? offer,
+			})
+			sentOffer = true
+			if (!hasCandidates)
+				nodeDebug('p2p:webrtc offer has no usable ice candidates', {
+					rung: index,
+					policy: rungs[index],
+					escalatable: index + 1 < rungs.length,
+					iceServers: options.iceServers?.length || 0,
+				})
+			break
+		}
+		if (!sentOffer) {
+			await pipe.close('ice-candidates-empty')
+			throw new Error('p2p: no usable ice candidates after the local hostname ladder')
+		}
 	}
 
 	void maybeStartPostOpenFlow().catch(error => pipe.close(`open-flow-failed:${formatErrorReason(error)}`))

package/link/rtc/polyfill.mjs

@@ -5,6 +5,8 @@ import { nodeDebug } from '../../node/log.mjs'
 
 import { wrapRtcPeerConnectionForIceLocalHostname } from './ice_local_hostname.mjs'
 
+/** @typedef {import('./ice_local_hostname.mjs').IceLocalHostnamePolicy} IceLocalHostnamePolicy */
+
 /** @type {boolean} */
 let exitCleanupHooked = false
 
@@ -87,7 +89,7 @@ function defaultRtcBackends() {
 }
 
 /**
- * @param {{ backends?: RtcBackend[] }} options 后端列表
+ * @param {{ backends?: RtcBackend[], policy?: IceLocalHostnamePolicy }} options 后端列表与策略覆盖
  * @returns {Promise<LoadedRtcPolyfill>} 首个可用后端的 polyfill
  */
 async function loadNodeRtcPolyfillUncached(options) {
@@ -99,7 +101,7 @@ async function loadNodeRtcPolyfillUncached(options) {
 	for (const backend of backends)
 		try {
 			const mod = await backend.load()
-			const iceLocalHostnamePolicy = getSignalingRuntimeConfig().channels.webrtc?.iceLocalHostnamePolicy
+			const iceLocalHostnamePolicy = options.policy ?? getSignalingRuntimeConfig().channels.webrtc?.iceLocalHostnamePolicy
 			return {
 				RTCPeerConnection: wrapRtcPeerConnectionForIceLocalHostname(
 					mod.RTCPeerConnection,
@@ -122,13 +124,14 @@ async function loadNodeRtcPolyfillUncached(options) {
 }
 
 /**
- * 加载 RTC polyfill（node-datachannel 优先，失败则 node-rtc-connection），并按配置包装 RTCPeerConnection。
- * 默认后端路径会缓存首次成功结果；注入 backends 时不走缓存。
- * @param {{ backends?: RtcBackend[] }} [options] 可注入后端列表（测试用）
+ * 加载 RTC polyfill（node-datachannel 优先，失败则 node-rtc-connection），并按 ICE 本地主机名策略包装
+ * RTCPeerConnection。策略是构造期烘进包装类的，所以 ICE 阶梯每换一级都要带 `policy` 重新取一次。
+ * 默认后端路径会缓存首次成功结果（仅在不带 policy 覆盖时）；注入 backends / policy 时不走缓存。
+ * @param {{ backends?: RtcBackend[], policy?: IceLocalHostnamePolicy }} [options] 可注入后端列表与策略覆盖（测试/阶梯用）
  * @returns {Promise<LoadedRtcPolyfill>} RTC 构造器
  */
 export async function loadNodeRtcPolyfill(options = {}) {
-	if (options.backends?.length)
+	if (options.backends?.length || options.policy)
 		return loadNodeRtcPolyfillUncached(options)
 	const epoch = getRtcPolyfillCacheEpoch()
 	if (!cachedDefaultPolyfill || cachedDefaultPolyfillEpoch !== epoch) {

package/node/signaling_config.mjs

@@ -1,4 +1,10 @@
-import process from 'node:process'
+/**
+ * 信令运行时配置。
+ *
+ * webrtc 通道不再有 `trickleIceOff`：本仓库的 ICE 候选是靠 description 一次性带出去的
+ * （对端要先有 remoteDescription 才吃候选），所以「收齐后一次性发送」是信令层的固定语义，
+ * 不是可配置项。`iceLocalHostnamePolicy` 是 ICE 阶梯的起点（见 [iceLocalHostnameLadder]）。
+ */
 
 /** @typedef {'none' | 'rewrite-loopback' | 'drop'} IceLocalHostnamePolicy */
 
@@ -13,20 +19,36 @@ import process from 'node:process'
  */
 
 /**
- * webrtc 通道默认配置。
- * @returns {{ iceLocalHostnamePolicy: IceLocalHostnamePolicy, trickleIceOff: boolean }} webrtc 通道默认配置
+ * ICE 本地主机名策略的升级阶梯（宽松度递增）。
+ *
+ * `.local`（mDNS）候选对端通常解析不了，所以从 `drop` 起；若丢弃后候选集为空，说明这台主机只产出了
+ * mDNS 候选，就升到 `none` 让对端自己处理（对端支持 mDNS 时就能用上）。判据是运行时观测到的候选集，
+ * 不是平台——任何后端、任何主机都走同一条流程。
+ *
+ * `rewrite-loopback` 不在阶梯里：它把候选改写成 `127.0.0.1`，只对同机有意义，发给跨机对端是坏候选。
  */
-function defaultWebRtcConfig() {
-	const iceLocalHostnamePolicy = process.platform === 'win32' ? 'drop' : 'none'
-	return { iceLocalHostnamePolicy, trickleIceOff: iceLocalHostnamePolicy !== 'none' }
-}
+export const ICE_LOCAL_HOSTNAME_LADDER = Object.freeze(['drop', 'none'])
 
 /** 各介质的默认 channel 配置；对象值是启用并覆盖默认。 */
 const DEFAULT_CHANNEL_CONFIG = {
 	nostr: true,
 	lan: true,
 	bt: true,
-	webrtc: defaultWebRtcConfig(),
+	webrtc: { iceLocalHostnamePolicy: ICE_LOCAL_HOSTNAME_LADDER[0] },
+}
+
+/**
+ * 从起点策略推导要依次尝试的策略（宽松度递增），用于把「候选集为空」当成升级信号。
+ * `rewrite-loopback` 作为显式起点时只试它自己：它是调试/同机用途，不应自动放宽成对外候选。
+ * @param {IceLocalHostnamePolicy | undefined | null} [from] 起点策略；未配置/非阶梯项时用阶梯首项
+ * @returns {IceLocalHostnamePolicy[]} 依次尝试的策略（至少一项）
+ */
+export function iceLocalHostnameLadder(from) {
+	if (from === 'rewrite-loopback') return ['rewrite-loopback']
+	if (!ICE_LOCAL_HOSTNAME_LADDER.includes(/** @type {IceLocalHostnamePolicy} */ (from)))
+		return [...ICE_LOCAL_HOSTNAME_LADDER]
+	const startIndex = ICE_LOCAL_HOSTNAME_LADDER.indexOf(/** @type {IceLocalHostnamePolicy} */ (from))
+	return ICE_LOCAL_HOSTNAME_LADDER.slice(startIndex)
 }
 
 /**

package/node/verification.mjs

@@ -0,0 +1,163 @@
+import { randomBytes } from 'node:crypto'
+
+import { isHex64 } from '../core/hexIds.mjs'
+import { sendToNodeLink } from '../transport/link_registry.mjs'
+import { attachNodeScopeFeature } from '../transport/node_scope/features.mjs'
+
+import { getNodeHash } from './identity.mjs'
+
+const MAX_TIMEOUT = 30 * 60 * 1000
+
+/**
+ * @typedef {{ challenge: string, requesterNodeHash: string, expiresAt: number }} NetworkChallenge 挑战
+ */
+
+/**
+ * 创建有界的挑战服务；发送方身份一律取自已认证的网络入口，不信任载荷自称。
+ * @param {{nodeHash: string, send: (peer: string, action: string, payload: object) => Promise<boolean>, now?: () => number}} options 依赖
+ * @returns {object} 挑战服务
+ */
+export function createNetworkVerificationService({ nodeHash, send, now = Date.now }) {
+	const requests = new Map()
+	const proofs = new Map()
+	/**
+	 * 清理已过期的挑战记录。
+	 * @returns {void} 无返回值
+	 */
+	function prune() {
+		for (const [id, entry] of requests) if (entry.expiresAt + 60000 < now()) requests.delete(id)
+	}
+	/**
+	 * 取挑战快照，并把已过期的 pending 收敛为 failed。
+	 * @param {object} entry 挑战状态
+	 * @returns {object} 快照
+	 */
+	function snapshot(entry) {
+		if (entry.status === 'pending' && now() >= entry.expiresAt) entry.status = 'failed', entry.reason = 'timeout'
+		return { ...entry }
+	}
+	return {
+		/**
+		 * 新建一个挑战：限幅超时、限制在途数量，返回待验证快照。
+		 * @param {{ timeoutMs?: number }} [options] 超时选项
+		 * @returns {object} 待验证快照
+		 */
+		create({ timeoutMs = 300000 } = {}) {
+			if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMEOUT) throw new Error('invalid timeoutMs')
+			prune()
+			if (requests.size >= 1024) throw new Error('too many verification requests')
+			const challenge = randomBytes(32).toString('hex')
+			const entry = { challenge, requesterNodeHash: nodeHash, expiresAt: now() + timeoutMs, status: 'pending' }
+			requests.set(challenge, entry)
+			return snapshot(entry)
+		},
+		/**
+		 * 按挑战串读取快照；不存在返回 null。
+		 * @param {string} challenge 挑战串
+		 * @returns {object|null} 快照
+		 */
+		get(challenge) {
+			prune()
+			const entry = requests.get(challenge)
+			return entry ? snapshot(entry) : null
+		},
+		/**
+		 * 处理入站 verification_claim / verification_receipt 动作。
+		 * @param {string} action 网络动作
+		 * @param {object} payload 网络载荷
+		 * @param {string} sender 已认证身份
+		 */
+		async receive(action, payload, sender) {
+			if (!isHex64(sender) || !isHex64(payload?.challenge)) return
+			if (action === 'verification_claim') {
+				const entry = requests.get(payload.challenge)
+				if (!entry || now() >= entry.expiresAt || snapshot(entry).status === 'failed' || entry.expiresAt !== payload.expiresAt) return
+				if (entry.status === 'verified' && entry.nodeHash !== sender) return
+				entry.status = 'verified'
+				entry.nodeHash = sender
+				await send(sender, 'verification_receipt', { challenge: entry.challenge, expiresAt: entry.expiresAt })
+			}
+			if (action === 'verification_receipt') {
+				const proof = proofs.get(payload.challenge)
+				if (proof && proof.requesterNodeHash === sender && proof.expiresAt === payload.expiresAt && now() < proof.expiresAt)
+					proof.resolve({ status: 'verified', nodeHash })
+			}
+		},
+		/**
+		 * 向请求方发起验证并等待回执（去重、并发上限、超时收敛为 failed）。
+		 * @param {NetworkChallenge} request 挑战请求
+		 * @returns {Promise<object>} 验证结果
+		 */
+		async prove({ requesterNodeHash, challenge, expiresAt }) {
+			if (!isHex64(requesterNodeHash) || !isHex64(challenge) || !Number.isSafeInteger(expiresAt) || expiresAt <= now() || expiresAt > now() + MAX_TIMEOUT)
+				return { status: 'failed', reason: 'invalid challenge' }
+			if (proofs.has(challenge)) {
+				const existing = proofs.get(challenge)
+				if (existing.requesterNodeHash !== requesterNodeHash || existing.expiresAt !== expiresAt) return { status: 'failed', reason: 'challenge mismatch' }
+				return existing.promise
+			}
+			if (proofs.size >= 64) return { status: 'failed', reason: 'busy' }
+			let resolve
+			const promise = new Promise(done => { resolve = done })
+			proofs.set(challenge, { requesterNodeHash, expiresAt, resolve, promise })
+			const timer = setTimeout(() => resolve({ status: 'failed', reason: 'timeout' }), Math.min(expiresAt - now(), 15000))
+			try {
+				void send(requesterNodeHash, 'verification_claim', { challenge, expiresAt }).then(sent => {
+					if (!sent) resolve({ status: 'failed', reason: 'unreachable' })
+				}, () => resolve({ status: 'failed', reason: 'unreachable' }))
+				return await promise
+			}
+			finally { clearTimeout(timer); proofs.delete(challenge) }
+		},
+	}
+}
+
+let service
+/**
+ * 把验证动作挂到正在运行的节点的 node scope 上。
+ * @returns {() => void} 卸载 dispose
+ */
+export function attachNetworkVerification() {
+	return attachNodeScopeFeature('verification', wire => {
+		const current = getNetworkVerificationService()
+		const disposers = ['verification_claim', 'verification_receipt'].map(action => wire.on(action, (payload, sender) => {
+			void current.receive(action, payload, sender).catch(() => {})
+		}))
+		return () => { for (const dispose of disposers) dispose(); service = null }
+	})
+}
+
+/**
+ * 取当前节点的验证服务（懒创建单例）。
+ * @returns {ReturnType<typeof createNetworkVerificationService>} 验证服务
+ */
+export function getNetworkVerificationService() {
+	if (!service) service = createNetworkVerificationService({ nodeHash: getNodeHash(), send: sendVerificationEnvelope })
+	return service
+}
+
+/**
+ * 经已认证链路投递验证消息；请求方就是本节点时直接走本地入口。
+ * @param {string} peer 目标身份
+ * @param {string} action 网络动作
+ * @param {object} payload 网络载荷
+ * @returns {Promise<boolean>} 是否已投递
+ */
+async function sendVerificationEnvelope(peer, action, payload) {
+	if (peer === getNodeHash()) {
+		await getNetworkVerificationService().receive(action, payload, peer)
+		return true
+	}
+	return await sendToNodeLink(peer, { scope: 'node', action, payload })
+}
+
+/**
+ * 单次自证：证明本节点可达请求方并收到其回执。
+ * @param {NetworkChallenge} request 挑战请求
+ * @returns {Promise<object>} 验证结果
+ */
+export async function proveNetworkVerification(request) {
+	const dispose = attachNetworkVerification()
+	try { return await getNetworkVerificationService().prove(request) }
+	finally { dispose() }
+}