@steve02081504/fount-p2p 0.0.20 → 0.0.22

package/README.md

@@ -107,8 +107,9 @@ Maintainer notes for agents / contributors: [AGENTS.md](./AGENTS.md). Sim harnes
 
 ## Optional dependencies
 
-- `@stoprocent/noble` / `@stoprocent/bleno` — Bluetooth (optionalDependencies). Hardware probe is subprocess-only; see [docs/runtime.md](./docs/runtime.md).
-- `node-datachannel` — WebRTC DataChannels (dependency).
+- `@stoprocent/noble` / `@stoprocent/bleno` — Bluetooth (optionalDependencies). Hardware probe is in-process; see [docs/runtime.md](./docs/runtime.md).
+- `node-datachannel` — native WebRTC DataChannels (optionalDependencies). Preferred when the addon loads.
+- `node-rtc-connection` — pure-JS WebRTC DataChannel fallback (dependency; used on Termux/Android or when native is missing).
 - `ws` — Nostr discovery / signaling / last-resort link WebSockets (dependency).
 
 Group chunk remote storage (S3, etc.) is implemented by the shell as `GroupStoragePlugin` and injected; see `node/storage_plugins.mjs` for the local reference implementation.

package/core/entity_id.mjs

@@ -11,7 +11,7 @@ import {
 import { isHex64, normalizeHex64 } from './hexIds.mjs'
 
 /**
- *
+ * entityHash 编解码与校验（re-export）。
  */
 export {
 	encodeEntityHash,

package/dag/index.mjs

@@ -252,10 +252,10 @@ export function eventsToMetas(events) {
 }
 
 /**
- *
+ * DAG 行内容/签名 canonicalize（re-export）。
  */
 export { canonicalizeRowContent, canonicalizeSignedRow } from './canonicalize_row.mjs'
 /**
- *
+ * 剥离 DAG 事件本地扩展字段（re-export）。
  */
 export { stripDagEventLocalExtensions } from './strip_extensions.mjs'

package/dag/storage.mjs

@@ -6,9 +6,12 @@ import { createInterface } from 'node:readline'
 import { Readable } from 'node:stream'
 import { pipeline } from 'node:stream/promises'
 
-import { atomicTemporaryPath, finalizeAtomicRename } from '../utils/atomic_fs.mjs'
 import { withAsyncMutex } from '../utils/async_mutex.mjs'
+import { atomicTemporaryPath, finalizeAtomicRename } from '../utils/atomic_fs.mjs'
 
+/**
+ * 原子重命名 finalize（re-export）。
+ */
 export { finalizeAtomicRename } from '../utils/atomic_fs.mjs'
 
 /** 流式重写 JSONL 时分块写入的行数上限 */

package/federation/chunk_fetch_pending.mjs

@@ -20,7 +20,7 @@ export function registerChunkFetchWait(key, expectedHash, timeoutMs, options = {
 		return {
 			done: Promise.resolve(null),
 			/**
-			 *
+			 * 槽位已满时的空操作取消。
 			 */
 			cancel: () => { },
 		}

package/federation/entity_key_chain.mjs

@@ -8,7 +8,7 @@ import { hashFromPubKeyHex } from '../core/entity_id.mjs'
 import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
 
 /**
- *
+ * entity 密钥撤销签名的域分隔前缀。
  */
 export const ENTITY_KEY_REVOKE_DOMAIN = 'fount-entity-key-revoke'
 

package/federation/manifest_fetch_pending.mjs

@@ -26,7 +26,7 @@ export function registerManifestFetchWait(key, expectedKey, timeoutMs) {
 		return {
 			done: Promise.resolve(null),
 			/**
-			 *
+			 * 槽位已满时的空操作取消。
 			 */
 			cancel: () => { },
 		}
@@ -57,7 +57,7 @@ export function registerManifestFetchWait(key, expectedKey, timeoutMs) {
 	return {
 		done,
 		/**
-		 *
+		 * 取消等待并以 null 结算。
 		 */
 		cancel: () => {
 			clearTimeout(timer)

package/files/assemble_stream.mjs

@@ -76,7 +76,7 @@ function readStreamChunk(stream) {
 	if (stream.readableEnded) return Promise.resolve(null)
 	return new Promise((resolve, reject) => {
 		/**
-		 *
+		 * readable 时读取下一块密文。
 		 */
 		const onReadable = () => {
 			cleanup()
@@ -84,7 +84,7 @@ function readStreamChunk(stream) {
 			resolve(next ? Buffer.from(next) : Buffer.alloc(0))
 		}
 		/**
-		 *
+		 * 流结束时 resolve null。
 		 */
 		const onEnd = () => {
 			cleanup()
@@ -98,7 +98,7 @@ function readStreamChunk(stream) {
 			reject(error)
 		}
 		/**
-		 *
+		 * 注销流事件监听。
 		 */
 		const cleanup = () => {
 			stream.off('readable', onReadable)
@@ -130,7 +130,7 @@ export function createManifestPlaintextStream(manifest, partStreams, contentKey)
 
 	return new Readable({
 		/**
-		 *
+		 * 按 manifest part 顺序解密密文块并推送明文。
 		 */
 		async read() {
 			if (finished) return

package/files/chunk_responder.mjs

@@ -99,7 +99,7 @@ export function attachTrustGraphFedChunkResponder(username, room, fedOut, guardG
 			if (!String(data.requestId || '')) return
 			await handleFedChunkGetIngress(username, data, peerId, (resp, pid) => {
 				/**
-				 *
+				 * 发送 fed_chunk_data 响应（可经 fedOut 限速队列）。
 				 */
 				const send = () => {
 					try { sendChunkData(resp, pid) }
@@ -123,7 +123,7 @@ export function attachTrustGraphFedChunkResponder(username, room, fedOut, guardG
 			if (!String(data.requestId || '')) return
 			await handleFedManifestGetIngress(username, data, peerId, (resp, pid) => {
 				/**
-				 *
+				 * 发送 fed_manifest_data 响应（可经 fedOut 限速队列）。
 				 */
 				const send = () => {
 					try { sendManifestData(resp, pid) }

package/files/manifest_fetch.mjs

@@ -26,8 +26,8 @@ const manifestInflight = createInflightTable({
 
 /**
  * 拉取公开 manifest；默认不写盘。`cache: true` 或 `cachePublicManifest` 才缓存。
- * 本地已有 publicSig 时仍会 fanout 再校验，按 publishedAt 择新；超时则回退本地。
- * 同 key in-flight 去重；调用方外层超时不 abort，后台继续填缓存。
+ * 本地已有 publicSig 时立即返回，并后台 fanout；`cache: true` 时按 publishedAt 择新写盘。
+ * 冷 miss 仍等 fanout。同 key in-flight 去重；调用方外层超时不 abort，后台继续填缓存。
  * @param {{ username: string, ownerEntityHash: string, logicalPath: string, cache?: boolean, timeoutMs?: number }} context - 拉取上下文
  * @returns {Promise<import('./manifest.mjs').FileManifest | null>} 验签后的 manifest，失败为 null
  */
@@ -42,6 +42,7 @@ export async function fetchPublicManifest(context) {
 		: DEFAULT_MANIFEST_FETCH_TIMEOUT_MS
 	const expectedKey = manifestFetchExpectedKey(ownerEntityHash, logicalPath)
 	const inflightKey = `${username}\0${expectedKey}`
+	const wantCache = context.cache === true
 
 	// 先挂 in-flight（同步），再读本地 — 避免并发调用在 await 间隙各自 start
 	const localPromise = loadFileManifest(ownerEntityHash, logicalPath)
@@ -67,15 +68,21 @@ export async function fetchPublicManifest(context) {
 	const hasLocalPublic = local?.transferKeyDescriptor?.type === 'public' && !!local?.meta?.publicSig
 	if (!shared) return hasLocalPublic ? local : null
 
-	const result = await shared
-
-	if (result && (!hasLocalPublic || shouldPreferIncomingPublicManifest(local, result))) {
-		if (context.cache === true)
-			await cachePublicManifest(ownerEntityHash, logicalPath, result)
-		return result
+	if (hasLocalPublic) {
+		// SWR：立刻回本地；后台 fanout 择新写盘（需 cache: true）
+		if (wantCache) {
+			void shared.then(async result => {
+				if (result && shouldPreferIncomingPublicManifest(local, result))
+					await cachePublicManifest(ownerEntityHash, logicalPath, result)
+			})
+		}
+		return local
 	}
-	if (hasLocalPublic) return local
-	return null
+
+	const result = await shared
+	if (!result) return null
+	if (wantCache) await cachePublicManifest(ownerEntityHash, logicalPath, result)
+	return result
 }
 
 /**

package/link/channel_mux.mjs

@@ -75,35 +75,23 @@ export function pickChannel(action, byteLength) {
 }
 
 /**
- * 读取 RTC 数据通道当前 bufferedAmount，失败时返回 0。
+ * 读取 RTC 数据通道当前 bufferedAmount。
  * @param {RTCDataChannel} channel RTC 数据通道
  * @returns {number} 缓冲区待发送字节数
  */
 export function readBufferedAmount(channel) {
-	try {
-		return Number.isFinite(channel?.bufferedAmount) ? Number(channel.bufferedAmount) : 0
-	}
-	catch {
-		return 0
-	}
+	return channel.bufferedAmount
 }
 
 /**
  * 配置数据通道的 bufferedAmountLowThreshold。
  * @param {RTCDataChannel} channel RTC 数据通道
  * @param {number} [thresholdBytes=CHANNEL_LOW_THRESHOLD_BYTES] 低水位阈值（字节）
- * @returns {number | null} 实际生效的阈值，不支持时返回 null
+ * @returns {number} 实际生效的阈值
  */
 export function configureBufferedAmountLowThreshold(channel, thresholdBytes = CHANNEL_LOW_THRESHOLD_BYTES) {
-	try {
-		channel.bufferedAmountLowThreshold = thresholdBytes
-		return Number.isFinite(channel.bufferedAmountLowThreshold)
-			? Number(channel.bufferedAmountLowThreshold)
-			: null
-	}
-	catch {
-		return null
-	}
+	channel.bufferedAmountLowThreshold = thresholdBytes
+	return channel.bufferedAmountLowThreshold
 }
 
 /**
@@ -113,18 +101,9 @@ export function configureBufferedAmountLowThreshold(channel, thresholdBytes = CH
  * @returns {() => void} 取消订阅函数
  */
 export function onBufferedAmountLow(channel, callback) {
-	/**
-	 * bufferedamountlow 事件处理函数。
-	 * @returns {void}
-	 */
-	const handler = () => callback()
-	channel.addEventListener?.('bufferedamountlow', handler)
-	channel.onbufferedamountlow = handler
-	if (channel.bufferedAmountLow?.subscribe)
-		channel.bufferedAmountLow.subscribe(handler)
+	channel.onbufferedamountlow = callback
 	return () => {
-		channel.removeEventListener?.('bufferedamountlow', handler)
-		if (channel.onbufferedamountlow === handler) channel.onbufferedamountlow = null
+		if (channel.onbufferedamountlow === callback) channel.onbufferedamountlow = null
 	}
 }
 
@@ -163,12 +142,12 @@ export function createChannelSendQueues(options) {
 		const channel = getChannel(channelName)
 		if (channel?.readyState !== 'open') return
 		const queue = queues[channelName]
-		let i = 0
-		while (i < queue.length) {
+		let sent = 0
+		while (sent < queue.length) {
 			if (readBufferedAmount(channel) > highWatermarkBytes) break
-			channel.send(queue[i++].bytes)
+			channel.send(queue[sent++].bytes)
 		}
-		if (i > 0) queue.splice(0, i)
+		if (sent > 0) queue.splice(0, sent)
 	}
 
 	return {

package/link/providers/webrtc.mjs

@@ -1,3 +1,4 @@
+import { toBytes } from '../../core/bytes_codec.mjs'
 import { getSignalingRuntimeConfig } from '../../node/instance.mjs'
 import { nodeDebug } from '../../node/log.mjs'
 import { ms } from '../../utils/duration.mjs'
@@ -11,20 +12,12 @@ import {
 	onBufferedAmountLow,
 } from '../channel_mux.mjs'
 import { asLinkHandle, createLinkPipe } from '../pipe.mjs'
-import {
-	attachChannelMessageListener,
-	attachDataChannelListener,
-	attachIceCandidateListener,
-	loadNodeRtcPolyfill,
-	dataToBytes,
-	waitForChannelState,
-} from '../rtc.mjs'
+import { loadNodeRtcPolyfill, waitForChannelState } from '../rtc/index.mjs'
 import { extractDtlsFingerprint } from '../sdp_fingerprint.mjs'
 
 import { LINK_LEVEL_WEBRTC } from './levels.mjs'
 
 /**
- * 将错误对象格式化为短字符串。
  * @param {unknown} error 原始错误
  * @returns {string} 短 reason
  */
@@ -35,27 +28,21 @@ function formatErrorReason(error) {
 let cachedAvailable = null
 
 /**
- * @returns {boolean} 是否跑在 Deno
- */
-function isDenoRuntime() {
-	return typeof globalThis.Deno !== 'undefined'
-}
-
-/**
- * 探测 WebRTC（node-datachannel）是否可用。
+ * 探测 WebRTC（node-datachannel 或纯 JS fallback）是否可用。
  * @returns {Promise<boolean>} 可用为 true
  */
 export async function canUseWebRtcLink() {
 	if (cachedAvailable !== null) return cachedAvailable
 	try {
-		await loadNodeRtcPolyfill()
+		const rtc = await loadNodeRtcPolyfill()
 		cachedAvailable = true
+		nodeDebug('p2p:webrtc backend', { backend: rtc.backend })
 	}
 	catch (error) {
 		cachedAvailable = false
 		const reason = formatErrorReason(error)
 		nodeDebug('p2p:webrtc unavailable', {
-			err: isDenoRuntime()
+			err: typeof globalThis.Deno !== 'undefined'
 				? `${reason} | deno: see docs/runtime.md (node-datachannel scripts only)`
 				: reason,
 		})
@@ -73,15 +60,16 @@ export async function canUseWebRtcLink() {
  * @param {number} [options.heartbeatMs] 心跳间隔
  * @param {number} [options.idleTimeoutMs] 无入站流量超时
  * @param {number} [options.handshakeTimeoutMs] 握手超时
- * @param {{ RTCPeerConnection: typeof RTCPeerConnection } | null} [options.rtc] RTC 构造器
+ * @param {import('../rtc/polyfill.mjs').LoadedRtcPolyfill} [options.rtc] RTC 构造器
  * @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 trickleIceOff = getSignalingRuntimeConfig().trickleIceOff === true
 	const rtc = options.rtc ?? await loadNodeRtcPolyfill()
+	// 纯 JS 后端只做 trickle（SDP 不含 candidate）；强制开启 trickle。
+	const trickleIceOff = !rtc.forcesTrickleIce && getSignalingRuntimeConfig().trickleIceOff === true
 	const peerConnection = new rtc.RTCPeerConnection(options.iceServers?.length ? { iceServers: options.iceServers } : undefined)
 	const remoteSignalQueue = []
 	const seenRemoteSignals = createLruMap(1024)
@@ -187,14 +175,6 @@ export async function createWebRtcLink(options) {
 		await flushQueuedIceCandidates()
 	}
 
-	/**
-	 * @param {unknown} error addIceCandidate 错误
-	 * @returns {boolean} 是否应暂存后重试
-	 */
-	function shouldRetryQueuedIce(error) {
-		return /without ice transport/i.test(String(error?.message ?? error ?? ''))
-	}
-
 	/**
 	 * @returns {Promise<void>}
 	 */
@@ -216,7 +196,7 @@ export async function createWebRtcLink(options) {
 				await peerConnection.addIceCandidate(candidate)
 			}
 			catch (error) {
-				if (shouldRetryQueuedIce(error)) {
+				if (/without ice transport/i.test(String(error?.message ?? error))) {
 					remoteSignalQueue.unshift(candidate)
 					return
 				}
@@ -261,7 +241,7 @@ export async function createWebRtcLink(options) {
 				await peerConnection.addIceCandidate(message.candidate)
 			}
 			catch (error) {
-				if (shouldRetryQueuedIce(error)) {
+				if (/without ice transport/i.test(String(error?.message ?? error))) {
 					remoteSignalQueue.push(message.candidate)
 					return
 				}
@@ -272,19 +252,23 @@ export async function createWebRtcLink(options) {
 
 	/**
 	 * @param {RTCDataChannel} channel RTC 数据通道
-	 * @returns {Promise<void>}
+	 * @returns {void}
 	 */
-	async function attachChannel(channel) {
+	function attachChannel(channel) {
 		if (channel.label === CHANNEL_CONTROL) controlChannel = channel
 		else if (channel.label === CHANNEL_BULK) bulkChannel = channel
 		else return
-		attachChannelMessageListener(channel, data => {
+		/**
+		 * @param {MessageEvent} event 入站消息事件
+		 * @returns {void}
+		 */
+		channel.onmessage = event => {
 			try {
-				if (typeof data === 'string') pipe.handleInbound(data)
-				else pipe.handleInbound(dataToBytes(data))
+				const data = event.data
+				pipe.handleInbound(typeof data === 'string' ? data : toBytes(data, { allowString: true }))
 			}
 			catch { /* drop */ }
-		})
+		}
 		attachBackpressurePump(channel)
 	}
 
@@ -312,20 +296,29 @@ export async function createWebRtcLink(options) {
 		void handleRemoteSignal(message).catch(error => pipe.close(`signal-error:${formatErrorReason(error)}`))
 	}) ?? null
 
-	attachIceCandidateListener(peerConnection, event => {
+	/**
+	 * @param {RTCPeerConnectionIceEvent} event ICE candidate 事件
+	 * @returns {void}
+	 */
+	peerConnection.onicecandidate = event => {
 		if (trickleIceOff || !event.candidate) return
 		void sendSignal({
 			type: 'ice',
 			candidate: typeof event.candidate.toJSON === 'function' ? event.candidate.toJSON() : event.candidate,
 		}).catch(error => pipe.close(`signal-send-failed:${formatErrorReason(error)}`))
-	})
-	attachDataChannelListener(peerConnection, event => {
-		void attachChannel(event.channel)
-			.then(() => maybeStartPostOpenFlow())
-			.catch(error => pipe.close(`channel-attach-failed:${error?.message ?? 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。 */
+	/**
+	 * 连接失败/断开时递增重连计数并关闭 pipe。
+	 */
 	peerConnection.onconnectionstatechange = () => {
 		if (['failed', 'closed', 'disconnected'].includes(peerConnection.connectionState)) {
 			reconnectCount++
@@ -334,8 +327,8 @@ export async function createWebRtcLink(options) {
 	}
 
 	if (options.initiator) {
-		await attachChannel(peerConnection.createDataChannel(CHANNEL_CONTROL))
-		await attachChannel(peerConnection.createDataChannel(CHANNEL_BULK))
+		attachChannel(peerConnection.createDataChannel(CHANNEL_CONTROL))
+		attachChannel(peerConnection.createDataChannel(CHANNEL_BULK))
 		const offer = await peerConnection.createOffer()
 		await peerConnection.setLocalDescription(offer)
 		await waitForIceGatheringComplete()
@@ -345,7 +338,7 @@ export async function createWebRtcLink(options) {
 		})
 	}
 
-	void maybeStartPostOpenFlow().catch(error => pipe.close(`open-flow-failed:${error?.message ?? error}`))
+	void maybeStartPostOpenFlow().catch(error => pipe.close(`open-flow-failed:${formatErrorReason(error)}`))
 
 	return asLinkHandle(pipe, {
 		/**
@@ -353,7 +346,7 @@ export async function createWebRtcLink(options) {
 		 * @param {'control' | 'bulk'} name 通道名
 		 * @returns {RTCDataChannel | null} 测试用通道
 		 */
-		_channelForTest(name) {
+		channelForTest(name) {
 			return name === CHANNEL_CONTROL ? controlChannel : bulkChannel
 		},
 	})

package/link/rtc/channel.mjs

@@ -0,0 +1,41 @@
+/**
+ * 等待 data channel 进入 open 或 close 状态，超时则 reject。
+ * 同一 channel 可并发等待：新订阅链式调用已有 onopen/onclose，cleanup 只摘掉自身。
+ * @param {RTCDataChannel} channel RTC 数据通道
+ * @param {'open' | 'close'} eventName 目标状态事件名
+ * @param {number} timeoutMs 超时毫秒数
+ * @returns {Promise<void>}
+ */
+export function waitForChannelState(channel, eventName, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		if (eventName === 'open' && channel.readyState === 'open') return resolve()
+		if (eventName === 'close' && channel.readyState === 'closed') return resolve()
+		const eventHandlerProperty = eventName === 'open' ? 'onopen' : 'onclose'
+		const previousHandler = channel[eventHandlerProperty]
+		let active = true
+		const timer = setTimeout(() => {
+			cleanup()
+			reject(new Error(`p2p: data channel ${eventName} timeout after ${timeoutMs}ms`))
+		}, timeoutMs)
+		/**
+		 * 清除超时并恢复 data channel 事件 handler。
+		 */
+		const cleanup = () => {
+			if (!active) return
+			active = false
+			clearTimeout(timer)
+			if (channel[eventHandlerProperty] === chained) channel[eventHandlerProperty] = previousHandler
+		}
+		/**
+		 * @param {...any} eventArguments 原 handler 参数
+		 * @returns {void}
+		 */
+		const chained = (...eventArguments) => {
+			previousHandler?.(...eventArguments)
+			if (!active) return
+			cleanup()
+			resolve()
+		}
+		channel[eventHandlerProperty] = chained
+	})
+}

package/link/rtc/ice_local_hostname.mjs

@@ -0,0 +1,139 @@
+/**
+ * 服务端 WebRTC polyfill 在 Windows 等环境常产出 `.local` host candidate，
+ * 远端无法解析。按 iceLocalHostnamePolicy 改写为 loopback 或丢弃。
+ */
+
+/** @typedef {'none' | 'rewrite-loopback' | 'drop'} IceLocalHostnamePolicy */
+
+/**
+ * @param {string | null | undefined} candidateSdp ICE candidate SDP 行
+ * @param {IceLocalHostnamePolicy} policy 处理策略
+ * @returns {string | null} 处理后的 SDP；drop 策略下不可用时返回 null
+ */
+export function applyIceLocalHostnamePolicy(candidateSdp, policy) {
+	const sdp = String(candidateSdp || '').trim()
+	if (!sdp || !/\.local/i.test(sdp)) return sdp || null
+	if (!/\btyp host\b/i.test(sdp)) return sdp
+	if (policy === 'drop') return null
+	if (policy === 'rewrite-loopback') {
+		const rewritten = sdp.replace(/(\s)[\w-]+\.local(\s|$)/gi, '$1127.0.0.1$2')
+		return rewritten === sdp ? null : rewritten
+	}
+	return sdp
+}
+
+/**
+ * @param {RTCIceCandidate | { candidate?: string } | null | undefined} candidate ICE candidate
+ * @param {typeof RTCIceCandidate} RTCIceCandidateCtor 构造函数
+ * @param {IceLocalHostnamePolicy} policy 处理策略
+ * @returns {RTCIceCandidate | { candidate?: string } | null | undefined} 过滤/改写后的 candidate
+ */
+export function filterIceLocalHostnameCandidate(candidate, RTCIceCandidateCtor, policy) {
+	if (!candidate || policy === 'none') return candidate
+	const raw = candidate.candidate ?? candidate.toJSON?.()?.candidate ?? ''
+	const rewritten = applyIceLocalHostnamePolicy(raw, policy)
+	if (!rewritten) return null
+	if (rewritten === raw) return candidate
+	const init = typeof candidate.toJSON === 'function'
+		? { ...candidate.toJSON(), candidate: rewritten }
+		: { candidate: rewritten, sdpMid: candidate.sdpMid, sdpMLineIndex: candidate.sdpMLineIndex }
+	return new RTCIceCandidateCtor(init)
+}
+
+/**
+ * @param {typeof RTCPeerConnection} BaseRTC 原始 polyfill 类
+ * @param {typeof RTCIceCandidate} RTCIceCandidate ICE candidate 构造函数
+ * @param {IceLocalHostnamePolicy} [policy='drop'] 策略
+ * @returns {typeof RTCPeerConnection} 包装后的 RTCPeerConnection 类（none 时原样返回）
+ */
+export function wrapRtcPeerConnectionForIceLocalHostname(BaseRTC, RTCIceCandidate, policy = 'drop') {
+	if (policy === 'none') return BaseRTC
+
+	const baseRoutesIce = typeof BaseRTC.prototype.prepareIceCandidateEvent === 'function'
+
+	return class IceLocalHostnameFilteredRTCPeerConnection extends BaseRTC {
+		/** @type {((event: RTCPeerConnectionIceEvent) => void) | null} */
+		#userIceHandler = null
+		/** @type {Set<(event: unknown) => void>} */
+		#iceListeners = new Set()
+		/** 去重：同一次 native 派发可能既走 attribute 又走 listener */
+		#lastIceEvent = null
+
+		/**
+		 * drop：不派发；rewrite：仅派发替换 candidate 后的事件。
+		 * @param {RTCPeerConnectionIceEvent | { candidate?: unknown }} event 原始 ICE 事件
+		 * @returns {RTCPeerConnectionIceEvent | { candidate?: unknown } | null} 规范化后的事件；drop 时为 null
+		 */
+		prepareIceCandidateEvent(event) {
+			if (!event?.candidate) return event
+			const filtered = filterIceLocalHostnameCandidate(event.candidate, RTCIceCandidate, policy)
+			if (!filtered) return null
+			return filtered === event.candidate ? event : { candidate: filtered }
+		}
+
+		/**
+		 * @param {RTCConfiguration} [config] RTC 配置
+		 */
+		constructor(config) {
+			super(config)
+			if (baseRoutesIce) return
+
+			// native EventTarget：在派发前规范化，自管 listener，不依赖 stopImmediatePropagation。
+			Object.defineProperty(this, 'onicecandidate', {
+				configurable: true,
+				enumerable: true,
+				/**
+				 * @returns {((event: RTCPeerConnectionIceEvent) => void) | null} 用户 ICE handler
+				 */
+				get: () => this.#userIceHandler,
+				/**
+				 * @param {((event: RTCPeerConnectionIceEvent) => void) | null} handler 用户 ICE handler
+				 * @returns {void}
+				 */
+				set: handler => { this.#userIceHandler = handler },
+			})
+			super.addEventListener('icecandidate', event => this.#deliverIce(event))
+		}
+
+		/**
+		 * @param {RTCPeerConnectionIceEvent | { candidate?: unknown }} event 原始 ICE 事件
+		 * @returns {void}
+		 */
+		#deliverIce = event => {
+			if (this.#lastIceEvent === event) return
+			this.#lastIceEvent = event
+			const normalized = this.prepareIceCandidateEvent(event)
+			if (normalized == null) return
+			this.#userIceHandler?.(normalized)
+			for (const listener of this.#iceListeners) listener(normalized)
+		}
+
+		/**
+		 * @param {string} type 事件名
+		 * @param {(event: unknown) => void} listener 回调
+		 * @param {boolean | AddEventListenerOptions} [options] 监听选项
+		 * @returns {void}
+		 */
+		addEventListener(type, listener, options) {
+			if (!baseRoutesIce && type === 'icecandidate') {
+				this.#iceListeners.add(listener)
+				return
+			}
+			return super.addEventListener(type, listener, options)
+		}
+
+		/**
+		 * @param {string} type 事件名
+		 * @param {(event: unknown) => void} listener 回调
+		 * @param {boolean | EventListenerOptions} [options] 监听选项
+		 * @returns {void}
+		 */
+		removeEventListener(type, listener, options) {
+			if (!baseRoutesIce && type === 'icecandidate') {
+				this.#iceListeners.delete(listener)
+				return
+			}
+			return super.removeEventListener(type, listener, options)
+		}
+	}
+}

package/link/rtc/index.mjs

@@ -0,0 +1,16 @@
+/**
+ * 等待 data channel open/close（re-export）。
+ */
+export { waitForChannelState } from './channel.mjs'
+/**
+ * ICE candidate 本地主机名策略（re-export）。
+ */
+export {
+	applyIceLocalHostnamePolicy,
+	filterIceLocalHostnameCandidate,
+	wrapRtcPeerConnectionForIceLocalHostname,
+} from './ice_local_hostname.mjs'
+/**
+ * Node WebRTC polyfill 加载（re-export）。
+ */
+export { clearNodeRtcPolyfillCache, loadNodeRtcPolyfill } from './polyfill.mjs'