@steve02081504/fount-p2p 0.0.10 → 0.0.12

package/transport/link_registry.mjs

@@ -1,106 +1,19 @@
 import { Buffer } from 'node:buffer'
-import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto'
 
 import { compareHex64Asc, normalizeHex64 } from '../core/hexIds.mjs'
-import { normalizeTcpPort } from '../core/tcp_port.mjs'
-import { sha256Hex, keyPairFromSeed } from '../crypto/crypto.mjs'
-import { noteAdvertPeerHints } from '../discovery/advert_peer_hints.mjs'
-import { advertiseTopic, listenSignals, listDiscoveryProviders, registerDiscoveryProvider, sendSignal, subscribeTopic } from '../discovery/index.mjs'
-import { createMdnsDiscoveryProvider } from '../discovery/mdns.mjs'
-import { mergeSignalingRelayUrls, createNostrDiscoveryProvider } from '../discovery/nostr.mjs'
-import { buildSignedAdvert, verifySignedAdvert } from '../link/handshake.mjs'
-import { createBleGattLinkProvider } from '../link/providers/ble_gatt.mjs'
-import {
-	listAvailableLinkProviders,
-	listLinkProviders,
-	registerLinkProvider,
-	unregisterLinkProvider,
-} from '../link/providers/index.mjs'
-import { createLanTcpLinkProvider } from '../link/providers/lan_tcp.mjs'
-import { createWebRtcLinkProvider } from '../link/providers/webrtc.mjs'
-import { ensureNodeSeed, getNodeHash, getNodeTransportSettings } from '../node/identity.mjs'
-import { getSignalingRuntimeConfig } from '../node/instance.mjs'
+import { keyPairFromSeed } from '../crypto/crypto.mjs'
+import { subscribeTopic } from '../discovery/index.mjs'
+import { listLinkProviders } from '../link/providers/index.mjs'
+import { ensureNodeSeed, getNodeHash } from '../node/identity.mjs'
 import { createOverlayRouter } from '../overlay/index.mjs'
+import { emitSafe } from '../utils/emit_safe.mjs'
 import { createLruMap } from '../utils/lru.mjs'
 
+import { ingestSignedAdvert } from './advert_ingest.mjs'
 import { DEFAULT_ICE_SERVERS } from './ice_servers.mjs'
-
-const SIGNAL_DOMAIN = 'fount-signal'
-const NODE_TOPIC_DOMAIN = 'fount-rdv-node:'
-const GROUP_TOPIC_DOMAIN = 'fount-rdv-group:'
-
-/**
- * 由 nodeHash 派生节点 rendezvous topic。
- * @param {string} nodeHash 节点 64 hex
- * @returns {string} rendezvous topic 哈希
- */
-export function nodeRendezvousTopic(nodeHash) {
-	return sha256Hex(`${NODE_TOPIC_DOMAIN}${normalizeHex64(nodeHash)}`)
-}
-
-/**
- * 由房间密钥派生群组 rendezvous topic。
- * @param {string} roomSecret 房间密钥
- * @returns {string} rendezvous topic 哈希
- */
-export function groupRendezvousTopic(roomSecret) {
-	return sha256Hex(`${GROUP_TOPIC_DOMAIN}${String(roomSecret || '')}`)
-}
-
-/**
- * 由 topic 派生信令 AES 密钥。
- * @param {string} topic rendezvous 主题
- * @returns {Buffer} AES-256 密钥
- */
-function signalKeyForTopic(topic) {
-	return createHash('sha256').update(`${SIGNAL_DOMAIN}:${String(topic)}`).digest()
-}
-
-/**
- * 加密信令包为 AES-GCM 字节序列。
- * @param {string} topic rendezvous 主题
- * @param {unknown} packet 待加密 JSON 对象
- * @returns {Uint8Array} 加密后的字节
- */
-export function encryptSignalPacket(topic, packet) {
-	const iv = randomBytes(12)
-	const cipher = createCipheriv('aes-256-gcm', signalKeyForTopic(topic), iv)
-	const ciphertext = Buffer.concat([
-		cipher.update(Buffer.from(JSON.stringify(packet), 'utf8')),
-		cipher.final(),
-	])
-	return Buffer.from(JSON.stringify({
-		iv: iv.toString('base64'),
-		authTag: cipher.getAuthTag().toString('base64'),
-		ciphertext: ciphertext.toString('base64'),
-	}))
-}
-
-/**
- * 解密信令包；失败时返回 null。
- * @param {string} topic rendezvous 主题
- * @param {Uint8Array} bytes 加密字节
- * @returns {object | null} 解密后的 JSON 对象
- */
-export function decryptSignalPacket(topic, bytes) {
-	try {
-		const payload = JSON.parse(Buffer.from(bytes).toString('utf8'))
-		const decipher = createDecipheriv(
-			'aes-256-gcm',
-			signalKeyForTopic(topic),
-			Buffer.from(payload.iv, 'base64'),
-		)
-		decipher.setAuthTag(Buffer.from(payload.authTag, 'base64'))
-		const plain = Buffer.concat([
-			decipher.update(Buffer.from(payload.ciphertext, 'base64')),
-			decipher.final(),
-		])
-		return JSON.parse(plain.toString('utf8'))
-	}
-	catch {
-		return null
-	}
-}
+import { createOfferAnswerDial } from './offer_answer.mjs'
+import { createRuntimeBootstrap } from './runtime_bootstrap.mjs'
+import { nodeRendezvousTopic } from './signal_crypto.mjs'
 
 /**
  * 解析或从节点种子推导本地身份。
@@ -123,60 +36,6 @@ function resolveLocalIdentity(localIdentity) {
 	}
 }
 
-/**
- * 创建带 backlog 的缓冲信令会话。
- * @param {(message: unknown) => Promise<void>} sendRemote 远端发送回调
- * @returns {{ send: (message: unknown) => Promise<void>, onRemote: (handler: (message: unknown) => void) => () => void, deliver: (message: unknown) => void, clear: () => void }} 信令会话
- */
-function createBufferedSignalSession(sendRemote) {
-	/** @type {Set<(message: unknown) => void>} */
-	const handlers = new Set()
-	/** @type {unknown[]} */
-	const backlog = []
-	return {
-		/**
-		 * 发送信令消息到远端。
-		 * @param {unknown} message 信令消息
-		 * @returns {Promise<void>}
-		 */
-		async send(message) {
-			await sendRemote(message)
-		},
-		/**
-		 * 注册远端信令 handler（含 backlog 回放）。
-		 * @param {(message: unknown) => void} handler 入站回调
-		 * @returns {() => void} 取消订阅函数
-		 */
-		onRemote(handler) {
-			handlers.add(handler)
-			for (const pending of backlog.splice(0))
-				handler(pending)
-			return () => handlers.delete(handler)
-		},
-		/**
-		 * 投递信令消息；无 handler 时入 backlog。
-		 * @param {unknown} message 信令消息
-		 * @returns {void}
-		 */
-		deliver(message) {
-			if (!handlers.size) {
-				backlog.push(message)
-				return
-			}
-			for (const handler of handlers)
-				handler(message)
-		},
-		/**
-		 * 清空 backlog 与 handler。
-		 * @returns {void}
-		 */
-		clear() {
-			backlog.length = 0
-			handlers.clear()
-		},
-	}
-}
-
 /**
  * 向 Map<key, Set<listener>> 订阅并返回取消函数。
  * @param {Map<string, Set<Function>>} buckets 监听器桶
@@ -209,14 +68,12 @@ export function createLinkRegistry(options = {}) {
 	const localIdentity = resolveLocalIdentity(options.localIdentity)
 	const iceServers = options.iceServers?.length ? options.iceServers : DEFAULT_ICE_SERVERS
 	const maxActive = Math.max(4, Number(options.maxActive) || 32)
-	const autoRegisterDiscoveryProviders = options.autoRegisterDiscoveryProviders !== false
-	const autoRegisterLinkProviders = options.autoRegisterLinkProviders !== false
 	const selfTopic = nodeRendezvousTopic(localIdentity.nodeHash)
 	/** @type {Map<string, object>} */
 	const links = new Map()
-	/** @type {Map<string, Promise<object | null>>} 按 nodeHash 去重的主动外拨 */
+	/** @type {Map<string, Promise<object | null>>} */
 	const inflights = new Map()
-	/** @type {Map<string, ReturnType<typeof createBufferedSignalSession>>} 按 connId 索引的信令会话（每条 PC 一个方向） */
+	/** @type {Map<string, ReturnType<typeof import('./offer_answer.mjs').createBufferedSignalSession>>} */
 	const signalSessions = new Map()
 	/** @type {Map<string, Set<string>>} */
 	const scopeInterests = new Map()
@@ -229,180 +86,23 @@ export function createLinkRegistry(options = {}) {
 	/** @type {Set<(nodeHash: string, reason: string) => void>} */
 	const linkDownListeners = new Set()
 	const recentAdverts = createLruMap(1024)
-	let runtimeStarted = false
-	let stopAdvert = null
-	let stopSignalListener = null
-	/** @type {Array<() => void>} */
-	const stopLinkListeners = []
 	let overlayRouter = null
-	/** @type {ReturnType<typeof createLanTcpLinkProvider> | null} 本 registry 持有的 lan_tcp 实例 */
-	let ownedLanTcp = null
-	/** @type {ReturnType<typeof createBleGattLinkProvider> | null} 本 registry 持有的 ble_gatt 实例 */
-	let ownedBleGatt = null
-
-	/**
-	 * 自动注册默认 LinkProvider（lan_tcp / webrtc / ble_gatt）。
-	 * lan_tcp / ble_gatt 每 registry 一个实例（避免 ensureListening 覆盖他人的 localIdentity）；
-	 * webrtc 按 id 单例注册。拨号时再经 isAvailable / canReach 跳过。
-	 * @returns {Promise<void>}
-	 */
-	async function ensureLinkProviders() {
-		if (!autoRegisterLinkProviders) return
-		if (!ownedLanTcp) {
-			ownedLanTcp = createLanTcpLinkProvider()
-			registerLinkProvider(ownedLanTcp)
-		}
-		if (!ownedBleGatt) {
-			ownedBleGatt = createBleGattLinkProvider()
-			registerLinkProvider(ownedBleGatt)
-		}
-		const ids = new Set(listLinkProviders().map(provider => provider.id))
-		if (!ids.has('webrtc'))
-			registerLinkProvider(createWebRtcLinkProvider())
-	}
-
-	/**
-	 * 本 registry 的 LAN TCP 监听端口。
-	 * @returns {number | null} listen 端口；未 listen 为 null
-	 */
-	function resolveLanTcpPort() {
-		const endpoint = typeof ownedLanTcp?.localEndpoint === 'function' ? ownedLanTcp.localEndpoint() : null
-		return normalizeTcpPort(endpoint?.port)
-	}
-
-	/**
-	 * 构造带本机身份与（若已 listen）tcpPort 的签名 advert。
-	 * node / group / scoped 广播共用，保证 LAN hint 可从任意 topic 学到。
-	 * @param {string} topic 广播主题
-	 * @returns {Promise<{ nodeHash: string, nodePubKey: string, ts: number, sig: string, tcpPort?: number }>} 签名 advert
-	 */
-	async function buildLocalAdvert(topic) {
-		const tcpPort = resolveLanTcpPort()
-		return await buildSignedAdvert(topic, Date.now(), {
-			...localIdentity,
-			...tcpPort != null ? { tcpPort } : {},
-		})
-	}
-
-	/**
-	 * 启动 discovery + link provider listening。
-	 * 先 ensureListening（拿到 lan_tcp 端口），再广播带 tcpPort 的 advert。
-	 * @returns {Promise<void>}
-	 */
-	async function ensureDiscoveryRuntime() {
-		if (runtimeStarted) return
-		runtimeStarted = true
-		await ensureLinkProviders()
-		if (autoRegisterDiscoveryProviders) {
-			const providerIds = new Set(listDiscoveryProviders().map(provider => provider.id))
-			if (!providerIds.has('mdns'))
-				registerDiscoveryProvider(createMdnsDiscoveryProvider())
-			if (!providerIds.has('bt')) {
-				const bt = await import('../discovery/bt/index.mjs').catch(() => null)
-				if (await bt?.canUseBluetoothDiscovery?.())
-					registerDiscoveryProvider(bt.createBluetoothDiscoveryProvider())
-			}
-			if (!providerIds.has('nostr'))
-				// 测试通过 initNode({ signaling: { relayOverride } }) 注入共享 loopback relay；生产则回落到用户 relay + 默认公网 relay。
-				// 新 discovery 栈也必须尊重这层 runtime override，否则 live 双节点测试会各打各的公网 relay。
-				registerDiscoveryProvider(createNostrDiscoveryProvider({
-					relayUrls: getSignalingRuntimeConfig().relayOverride
-						?? mergeSignalingRelayUrls(getNodeTransportSettings().relayUrls),
-				}))
-		}
-		// 只对本 registry 持有的 lan_tcp / ble_gatt 调用 ensureListening。
-		// 切勿遍历其它 registry 的 lan_tcp:* / ble_gatt:* ——会覆盖其 localIdentity/onInbound。
-		/** @type {import('../link/providers/index.mjs').LinkProvider[]} */
-		const listenProviders = []
-		if (ownedLanTcp) listenProviders.push(ownedLanTcp)
-		// 无适配器时 isAvailable 应在 import native 前返回 false；勿无条件 ensureListening（会 loadBleno）。
-		if (ownedBleGatt && await Promise.resolve(ownedBleGatt.isAvailable()))
-			listenProviders.push(ownedBleGatt)
-		for (const provider of await listAvailableLinkProviders()) {
-			const id = String(provider.id)
-			if (id.startsWith('lan_tcp') || id.startsWith('ble_gatt')) continue
-			if (typeof provider.ensureListening === 'function')
-				listenProviders.push(provider)
-		}
-		for (const provider of listenProviders) 
-			try {
-				const stop = await provider.ensureListening({
-					localIdentity,
-					/**
-					 * @param {object} link 入站链路
-					 * @returns {void}
-					 */
-					onInbound(link) {
-						void (async () => {
-							try {
-								await link.ready
-								const remote = normalizeHex64(link.nodeHash)
-								if (!remote) {
-									await link.close('inbound-no-nodehash')
-									return
-								}
-								await registerResolvedLink(remote, link)
-							}
-							catch { /* ignore failed inbound */ }
-						})()
-					},
-				})
-				if (typeof stop === 'function') stopLinkListeners.push(stop)
-			}
-			catch { /* provider listen unavailable — normal degrade */ }
-		
-		if (listDiscoveryProviders().length) {
-			stopSignalListener = await listenSignals(selfTopic, bytes => {
-				void handleIncomingSignal(bytes).catch(() => { })
-			})
-			stopAdvert = await advertiseTopic(selfTopic, encryptSignalPacket(selfTopic, {
-				type: 'advert',
-				body: await buildLocalAdvert(selfTopic),
-			}))
-		}
-	}
-
-	/**
-	 * 为单条 PC 创建按 connId 标记的信令会话。出站信令都带上 connId，
-	 * 使同一对节点的两个方向（各自一条 PC）在信令层互不串扰。
-	 * @param {string} remoteNodeHash 远端节点 64 hex
-	 * @param {string} connId 连接标识
-	 * @returns {ReturnType<typeof createBufferedSignalSession>} 信令会话
-	 */
-	function createConnSession(remoteNodeHash, connId) {
-		const normalized = normalizeHex64(remoteNodeHash)
-		const topic = nodeRendezvousTopic(normalized)
-		return createBufferedSignalSession(async message => {
-			await sendSignal(topic, normalized, encryptSignalPacket(topic, {
-				type: 'signal',
-				from: localIdentity.nodeHash,
-				connId,
-				body: message,
-			}))
-		})
-	}
 
-	/**
-	 * 判断信令 body 是否为发起方 offer（据此决定入站是否新建应答 PC）。
-	 * @param {unknown} body 信令 body
-	 * @returns {boolean} 是 offer 则 true
-	 */
-	function isOfferSignalBody(body) {
-		return !!body && typeof body === 'object'
-			&& body.type === 'description'
-			&& body.description?.type === 'offer'
-	}
+	/** @type {(bytes: Uint8Array) => Promise<void>} */
+	let handleIncomingSignal = async () => { }
+	/** @type {(provider: import('../link/providers/index.mjs').LinkProvider, remoteNodeHash: string) => Promise<object | null>} */
+	let dialOfferAnswer = async () => null
 
 	/**
 	 * 择链：更高 level 优先；同 level 时保留由较小 nodeHash 发起的那条（glare 两端一致）。
-	 * @param {object} link 链路实例
+	 * @param {object} link 候选链路
 	 * @param {string} remoteNodeHash 远端节点 64 hex
-	 * @param {object | null} [against] 现有规范链
-	 * @returns {boolean} 本条链应保留则 true
+	 * @param {object | null} [against] 当前规范链
+	 * @returns {boolean} 候选链应保留为规范链时 true
 	 */
 	function linkIsPreferred(link, remoteNodeHash, against = null) {
-		const level = Number(link.level) || 0
-		const againstLevel = Number(against?.level) || 0
+		const level = link.level || 0
+		const againstLevel = against?.level || 0
 		if (against && level !== againstLevel) return level > againstLevel
 		const cmp = compareHex64Asc(localIdentity.nodeHash, remoteNodeHash)
 		return link.initiator ? cmp < 0 : cmp > 0
@@ -419,12 +119,10 @@ export function createLinkRegistry(options = {}) {
 			void dispatchEnvelope(senderNodeHash, envelope, link).catch(() => { })
 		})
 		link.onDown(reason => {
-			// 只有关闭的是当前规范链路才对外报 linkDown；双 PC 并存期关掉的败者不应误发 peer-leave。
 			const wasCanonical = links.get(remoteNodeHash) === link
 			if (!wasCanonical) return
 			links.delete(remoteNodeHash)
-			for (const listener of linkDownListeners)
-				try { listener(remoteNodeHash, reason) } catch { /* ignore */ }
+			emitSafe(linkDownListeners, remoteNodeHash, reason)
 		})
 	}
 
@@ -438,79 +136,48 @@ export function createLinkRegistry(options = {}) {
 		const normalized = normalizeHex64(remoteNodeHash)
 		const existing = links.get(normalized)
 		if (existing && existing !== candidate && !linkIsPreferred(candidate, normalized, existing)) {
-			await candidate.close(Number(candidate.level) !== Number(existing.level) ? 'provider-loser' : 'glare-loser')
+			await candidate.close(candidate.level !== existing.level ? 'provider-loser' : 'glare-loser')
 			return
 		}
 		links.set(normalized, candidate)
 		wireLink(normalized, candidate)
 		if (existing && existing !== candidate)
-			await existing.close(Number(candidate.level) !== Number(existing.level) ? 'provider-replaced' : 'glare-replaced')
-		for (const listener of linkUpListeners)
-			try { listener(normalized, candidate) } catch { /* ignore */ }
+			await existing.close(candidate.level !== existing.level ? 'provider-replaced' : 'glare-replaced')
+		emitSafe(linkUpListeners, normalized, candidate)
 	}
 
 	/**
-	 * 找已注册的 offer/answer provider（按 level 降序的第一个）。
-	 * @returns {import('../link/providers/index.mjs').LinkProvider | null} 命中的 provider
-	 */
-	function findOfferAnswerProvider() {
-		return listLinkProviders().find(provider => provider.caps?.needsOfferAnswer) ?? null
-	}
-
-	/**
-	 * Offer/answer provider：为一条 connId 会话建链并走 glare 择一。
-	 * @param {{ provider: import('../link/providers/index.mjs').LinkProvider, remoteNodeHash: string, connId: string, session: ReturnType<typeof createBufferedSignalSession>, initiator: boolean }} options 建链参数
-	 * @returns {Promise<object | null>} 当前规范链；失败 null
+	 * 入站链路共用 onInbound（lan_tcp / 后台 ble 等）。
+	 * @param {object} link 入站链路
+	 * @returns {void}
 	 */
-	async function buildConnLink({ provider, remoteNodeHash, connId, session, initiator }) {
-		try {
-			if (initiator) await trimToBudget()
-			const link = await (initiator ? provider.dial : provider.accept)({
-				nodeHash: remoteNodeHash,
-				signal: session,
-				iceServers,
-				localIdentity,
-			})
-			if (!link) {
-				signalSessions.delete(connId)
-				return null
+	function onInboundLink(link) {
+		void (async () => {
+			try {
+				await link.ready
+				const remote = normalizeHex64(link.nodeHash)
+				if (!remote) {
+					await link.close('inbound-no-nodehash')
+					return
+				}
+				await registerResolvedLink(remote, link)
 			}
-			link.onDown(() => signalSessions.delete(connId))
-			await link.ready
-			await registerResolvedLink(remoteNodeHash, link)
-			return links.get(remoteNodeHash) ?? null
-		}
-		catch {
-			signalSessions.delete(connId)
-			return null
-		}
+			catch { /* ignore failed inbound */ }
+		})()
 	}
 
-	/**
-	 * 处理入站加密信令并可能发起被动建链。
-	 * @param {Uint8Array} bytes 加密信令字节
-	 * @returns {Promise<void>}
-	 */
-	async function handleIncomingSignal(bytes) {
-		const packet = decryptSignalPacket(selfTopic, bytes)
-		if (!packet || packet.type !== 'signal') return
-		const remoteNodeHash = normalizeHex64(packet.from)
-		const connId = String(packet.connId || '')
-		if (!remoteNodeHash || remoteNodeHash === localIdentity.nodeHash || !connId) return
-		// 仅 needsOfferAnswer 走双 PC glare；其它 provider 不吃 SDP 信令。
-		let session = signalSessions.get(connId)
-		if (!session) {
-			// 只有全新的 offer 才开一条独立应答 PC；answer/ice 若无对应 connId 会话则是迟到/无效帧，丢弃。
-			// 应答 PC 按 connId 独立创建，不受按 nodeHash 去重的 inflight 阻挡——这是支持双向同时建链的关键。
-			if (!isOfferSignalBody(packet.body)) return
-			const provider = findOfferAnswerProvider()
-			if (!provider) return
-			session = createConnSession(remoteNodeHash, connId)
-			signalSessions.set(connId, session)
-			void buildConnLink({ provider, remoteNodeHash, connId, session, initiator: false })
-		}
-		session.deliver(packet.body)
-	}
+	const bootstrap = createRuntimeBootstrap({
+		localIdentity,
+		selfTopic,
+		autoRegisterDiscoveryProviders: options.autoRegisterDiscoveryProviders !== false,
+		autoRegisterLinkProviders: options.autoRegisterLinkProviders !== false,
+		onInboundLink,
+		/**
+		 * @param {Uint8Array} bytes 入站信令字节
+		 * @returns {void}
+		 */
+		handleIncomingSignal: bytes => handleIncomingSignal(bytes),
+	})
 
 	/**
 	 * 计算节点在 scope 兴趣中的权重（用于 eviction）。
@@ -530,24 +197,38 @@ export function createLinkRegistry(options = {}) {
 	 */
 	async function trimToBudget() {
 		if (links.size < maxActive) return
-		const candidates = [...links.entries()]
-			.sort((left, right) => scopeWeight(left[0]) - scopeWeight(right[0]) || compareHex64Asc(left[0], right[0]))
-		const victim = candidates[0]
-		if (victim) await victim[1].close('budget-evict')
+		let victimHash = null
+		let victimLink = null
+		let victimWeight = Infinity
+		for (const [nodeHash, link] of links) {
+			const weight = scopeWeight(nodeHash)
+			if (
+				victimHash == null
+				|| weight < victimWeight
+				|| (weight === victimWeight && compareHex64Asc(nodeHash, victimHash) < 0)
+			) {
+				victimHash = nodeHash
+				victimLink = link
+				victimWeight = weight
+			}
+		}
+		if (victimLink) await victimLink.close('budget-evict')
 	}
 
-	/**
-	 * 经 offer/answer provider 拨号（discovery signal + glare）。
-	 * @param {import('../link/providers/index.mjs').LinkProvider} provider 链路提供者
-	 * @param {string} remoteNodeHash 远端 64 hex
-	 * @returns {Promise<object | null>} 当前规范链；失败 null
-	 */
-	async function dialOfferAnswer(provider, remoteNodeHash) {
-		const connId = randomBytes(16).toString('hex')
-		const session = createConnSession(remoteNodeHash, connId)
-		signalSessions.set(connId, session)
-		return await buildConnLink({ provider, remoteNodeHash, connId, session, initiator: true })
-	}
+	; ({ handleIncomingSignal, dialOfferAnswer } = createOfferAnswerDial({
+		localIdentity,
+		iceServers,
+		selfTopic,
+		signalSessions,
+		registerResolvedLink,
+		trimToBudget,
+		/**
+		 * 读取当前规范链。
+		 * @param {string} remoteNodeHash 远端节点 64 hex
+		 * @returns {object | null | undefined} 规范链实例
+		 */
+		getCanonicalLink: remoteNodeHash => links.get(normalizeHex64(remoteNodeHash)),
+	}))
 
 	/**
 	 * 经非 offer/answer provider 拨号。
@@ -574,21 +255,25 @@ export function createLinkRegistry(options = {}) {
 	 * @returns {Promise<object | null>} 链路实例；失败时 null
 	 */
 	async function ensureDirectLinkToNode(remoteNodeHash) {
-		await ensureDiscoveryRuntime()
+		await bootstrap.ensureRuntime()
+		await bootstrap.whenSignalListening()
 		const normalized = normalizeHex64(remoteNodeHash)
 		if (!normalized || normalized === localIdentity.nodeHash) return null
 		if (links.has(normalized)) return links.get(normalized)
 		if (inflights.has(normalized)) return await inflights.get(normalized)
 		const task = (async () => {
-			const providers = await listAvailableLinkProviders()
-			for (const provider of providers) 
+			const providers = listLinkProviders()
+			for (const provider of providers)
 				try {
 					if (typeof provider.canReach === 'function') {
 						const reachable = await Promise.resolve(provider.canReach({ nodeHash: normalized }))
 						if (!reachable) continue
 					}
+					if (typeof provider.isAvailable === 'function') {
+						const available = await Promise.resolve(provider.isAvailable())
+						if (!available) continue
+					}
 					if (provider.caps?.needsOfferAnswer) {
-						// soft-fail 返回 null（不 throw）；必须 continue 才能落到更低 level。
 						const link = await dialOfferAnswer(provider, normalized)
 						if (link) return link
 						continue
@@ -597,7 +282,7 @@ export function createLinkRegistry(options = {}) {
 					if (link) return link
 				}
 				catch { /* dial failed — try next provider */ }
-			
+
 			return null
 		})().finally(() => inflights.delete(normalized))
 		inflights.set(normalized, task)
@@ -632,10 +317,7 @@ export function createLinkRegistry(options = {}) {
 		overlayRouter = createOverlayRouter({
 			localIdentity,
 			sendToNodeLink: sendDirectToNodeLink,
-			/**
-			 * 列出当前所有活跃链路。
-			 * @returns {Array<{ nodeHash: string, link: object }>} 链路列表
-			 */
+			/** @returns {Array<{ nodeHash: string, link: object }>} 当前活跃链路列表 */
 			listLinks() {
 				return [...links.entries()].map(([nodeHash, link]) => ({ nodeHash, link }))
 			},
@@ -656,8 +338,9 @@ export function createLinkRegistry(options = {}) {
 	async function relayEnvelopeToNode(remoteNodeHash, envelope) {
 		if (!links.size || envelope?.scope === 'overlay') return false
 		try {
-			const path = await getOverlayRouter().discoverRoute(remoteNodeHash)
-			await getOverlayRouter().relay(path, envelope)
+			const overlay = getOverlayRouter()
+			const path = await overlay.discoverRoute(remoteNodeHash)
+			await overlay.relay(path, envelope)
 			return true
 		}
 		catch {
@@ -665,15 +348,6 @@ export function createLinkRegistry(options = {}) {
 		}
 	}
 
-	/**
-	 * 确保到远端节点的链路（直连或被动应答）。
-	 * @param {string} remoteNodeHash 远端节点 64 hex
-	 * @returns {Promise<object | null>} 链路实例
-	 */
-	async function ensureLinkToNode(remoteNodeHash) {
-		return await ensureDirectLinkToNode(remoteNodeHash)
-	}
-
 	/**
 	 * 发送 envelope：优先直连，失败则 overlay relay。
 	 * @param {string} remoteNodeHash 远端节点 64 hex
@@ -685,6 +359,17 @@ export function createLinkRegistry(options = {}) {
 			|| await relayEnvelopeToNode(remoteNodeHash, envelope)
 	}
 
+	/**
+	 * 同步结果直接返回；thenable 才 await（避免每条 envelope 造 microtask）。
+	 * @param {unknown} value 可能为 Promise 的返回值
+	 * @returns {Promise<unknown>} 已 resolve 的值
+	 */
+	async function maybeAwait(value) {
+		if (value != null && typeof /** @type {{ then?: unknown }} */ value.then === 'function')
+			return await value
+		return value
+	}
+
 	/**
 	 * 将入站 envelope 派发到 scope 监听器（经 authorizer 校验）。
 	 * @param {string} senderNodeHash 发送方节点 64 hex
@@ -693,45 +378,46 @@ export function createLinkRegistry(options = {}) {
 	 * @returns {Promise<void>}
 	 */
 	async function dispatchEnvelope(senderNodeHash, envelope, link) {
-		const scope = String(envelope?.scope || '')
+		const scope = envelope.scope || ''
 		for (const [prefix, authorizer] of scopeAuthorizers.entries())
 			if (scope.startsWith(prefix)) {
-				const allowed = await Promise.resolve(authorizer(scope, senderNodeHash, envelope, link))
+				const allowed = await maybeAwait(authorizer(scope, senderNodeHash, envelope, link))
 				if (!allowed) return
 			}
 		for (const [prefix, listeners] of scopeListeners.entries())
 			if (scope.startsWith(prefix))
 				for (const listener of listeners)
-					await Promise.resolve(listener(senderNodeHash, envelope, link))
+					await maybeAwait(listener(senderNodeHash, envelope, link))
 	}
 
 	/**
 	 * 订阅指定 scope 前缀的 envelope。
 	 * @param {string} prefix scope 前缀
-	 * @param {(senderNodeHash: string, envelope: { scope: string, action: string, payload: unknown }, link: object) => void | Promise<void>} listener 监听器
+	 * @param {Function} listener 监听器
 	 * @returns {() => void} 取消订阅函数
 	 */
 	function subscribeScope(prefix, listener) {
-		return subscribeBucket(scopeListeners, String(prefix), listener)
+		return subscribeBucket(scopeListeners, prefix, listener)
 	}
 
 	/**
 	 * 注册 scope 前缀的 authorizer（入站校验）。
 	 * @param {string} prefix scope 前缀
-	 * @param {(scope: string, senderNodeHash: string, envelope: object, link: object) => boolean | Promise<boolean>} authorizer 校验函数
+	 * @param {Function} authorizer 校验函数
 	 * @returns {() => void} 取消注册函数
 	 */
 	function registerScopeAuthorizer(prefix, authorizer) {
-		scopeAuthorizers.set(String(prefix), authorizer)
-		return () => scopeAuthorizers.delete(String(prefix))
+		scopeAuthorizers.set(prefix, authorizer)
+		return () => scopeAuthorizers.delete(prefix)
 	}
 
 	return {
 		localIdentity,
-		buildLocalAdvert,
-		lanTcpPort: resolveLanTcpPort,
-		ensureRuntime: ensureDiscoveryRuntime,
-		ensureLinkToNode,
+		buildLocalAdvert: bootstrap.buildLocalAdvert,
+		lanTcpPort: bootstrap.lanTcpPort,
+		whenListening: bootstrap.whenListening,
+		ensureRuntime: bootstrap.ensureRuntime,
+		ensureLinkToNode: ensureDirectLinkToNode,
 		/**
 		 * 获取到指定节点的活跃链路。
 		 * @param {string} nodeHash 节点 64 hex
@@ -785,7 +471,7 @@ export function createLinkRegistry(options = {}) {
 		 * @returns {void}
 		 */
 		registerScopeInterest(scope, nodeHashes) {
-			scopeInterests.set(String(scope), new Set((Array.isArray(nodeHashes) ? nodeHashes : []).map(normalizeHex64).filter(Boolean)))
+			scopeInterests.set(scope, new Set((nodeHashes || []).map(normalizeHex64).filter(Boolean)))
 		},
 		/**
 		 * 释放 scope 兴趣。
@@ -793,7 +479,7 @@ export function createLinkRegistry(options = {}) {
 		 * @returns {void}
 		 */
 		releaseScopeInterest(scope) {
-			scopeInterests.delete(String(scope))
+			scopeInterests.delete(scope)
 		},
 		registerScopeAuthorizer,
 		subscribeScope,
@@ -806,13 +492,10 @@ export function createLinkRegistry(options = {}) {
 		async subscribeNodeAdvert(nodeHash, onAdvert) {
 			const topic = nodeRendezvousTopic(nodeHash)
 			return await subscribeTopic(topic, async (bytes, meta) => {
-				const packet = decryptSignalPacket(topic, bytes)
-				if (packet?.type !== 'advert') return
-				const verifiedNodeHash = await verifySignedAdvert(topic, packet.body)
-				if (!verifiedNodeHash) return
-				noteAdvertPeerHints(verifiedNodeHash, packet.body, meta)
-				recentAdverts.touch(verifiedNodeHash, Date.now())
-				await Promise.resolve(onAdvert(verifiedNodeHash, packet.body))
+				const ingested = await ingestSignedAdvert(topic, bytes, meta)
+				if (!ingested) return
+				recentAdverts.touch(ingested.verifiedNodeHash, Date.now())
+				await Promise.resolve(onAdvert(ingested.verifiedNodeHash, ingested.body))
 			})
 		},
 		recentAdverts,
@@ -822,10 +505,7 @@ export function createLinkRegistry(options = {}) {
 		 * @returns {Promise<void>}
 		 */
 		async shutdown() {
-			stopAdvert?.()
-			stopSignalListener?.()
-			for (const stop of stopLinkListeners.splice(0))
-				try { stop() } catch { /* ignore */ }
+			await bootstrap.shutdown()
 			overlayRouter?.close()
 			overlayRouter = null
 			for (const link of links.values())
@@ -834,99 +514,77 @@ export function createLinkRegistry(options = {}) {
 			inflights.clear()
 			for (const session of signalSessions.values()) session.clear()
 			signalSessions.clear()
-			if (ownedLanTcp) {
-				unregisterLinkProvider(ownedLanTcp.id)
-				ownedLanTcp = null
-			}
-			if (ownedBleGatt) {
-				unregisterLinkProvider(ownedBleGatt.id)
-				ownedBleGatt = null
-			}
-			runtimeStarted = false
 		},
 	}
 }
 
 let defaultRegistry = null
 
+/**
+ * 默认 registry 尚未创建时暂存的 scope authorizer 条目。
+ * 注册阶段不应触发 createLinkRegistry / resolveLocalIdentity；绑定在 getLinkRegistry flush 时完成。
+ * @type {Array<{ prefix: string, authorizer: Function, unregister: (() => void) | null }>}
+ */
+const pendingScopeAuthorizers = []
+
 /**
  * 获取进程级默认 link registry 单例。
  * @returns {ReturnType<typeof createLinkRegistry>} 默认 registry
  */
 export function getLinkRegistry() {
-	if (!defaultRegistry) defaultRegistry = createLinkRegistry()
+	if (defaultRegistry) return defaultRegistry
+	defaultRegistry = createLinkRegistry()
+	for (const entry of pendingScopeAuthorizers)
+		entry.unregister = defaultRegistry.registerScopeAuthorizer(entry.prefix, entry.authorizer)
+	pendingScopeAuthorizers.length = 0
 	return defaultRegistry
 }
 
 /**
- * 默认 registry 的 ensureLinkToNode 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['ensureLinkToNode']>} 链路实例
- */
-export const ensureLinkToNode = (...args) => getLinkRegistry().ensureLinkToNode(...args)
-/**
- * 默认 registry 的 getLink 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['getLink']>} 链路实例
- */
-export const getLink = (...args) => getLinkRegistry().getLink(...args)
-/**
- * 默认 registry 的 listLinks 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['listLinks']>} 链路列表
- */
-export const listLinks = (...args) => getLinkRegistry().listLinks(...args)
-/**
- * 默认 registry 的 closeLink 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['closeLink']>} 关闭完成
- */
-export const closeLink = (...args) => getLinkRegistry().closeLink(...args)
-/**
- * 默认 registry 的 sendToNodeLink 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['sendToNodeLink']>} 是否成功
- */
-export const sendToNodeLink = (...args) => getLinkRegistry().sendToNodeLink(...args)
-/**
- * 默认 registry 的 relayEnvelopeToNode 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['relayEnvelopeToNode']>} 是否成功
- */
-export const relayEnvelopeToNode = (...args) => getLinkRegistry().relayEnvelopeToNode(...args)
-/**
- * 默认 registry 的 onLinkUp 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['onLinkUp']>} 取消订阅函数
- */
-export const onLinkUp = (...args) => getLinkRegistry().onLinkUp(...args)
-/**
- * 默认 registry 的 onLinkDown 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['onLinkDown']>} 取消订阅函数
- */
-export const onLinkDown = (...args) => getLinkRegistry().onLinkDown(...args)
-/**
- * 默认 registry 的 registerScopeInterest 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['registerScopeInterest']>} 无返回值
- */
-export const registerScopeInterest = (...args) => getLinkRegistry().registerScopeInterest(...args)
-/**
- * 默认 registry 的 releaseScopeInterest 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['releaseScopeInterest']>} 无返回值
- */
-export const releaseScopeInterest = (...args) => getLinkRegistry().releaseScopeInterest(...args)
-/**
- * 默认 registry 的 registerScopeAuthorizer 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['registerScopeAuthorizer']>} 取消注册函数
+ * 默认 registry 方法代理。
+ * @param {string} name registry 方法名
+ * @returns {(...args: unknown[]) => unknown} 绑定到 getLinkRegistry()[name] 的函数
  */
-export const registerScopeAuthorizer = (...args) => getLinkRegistry().registerScopeAuthorizer(...args)
+const bindRegistryMethod = name => (...args) => getLinkRegistry()[name](...args)
+
+/** @type {(...args: unknown[]) => unknown} */
+export const ensureLinkToNode = bindRegistryMethod('ensureLinkToNode')
+/** @type {(...args: unknown[]) => unknown} */
+export const getLink = bindRegistryMethod('getLink')
+/** @type {(...args: unknown[]) => unknown} */
+export const listLinks = bindRegistryMethod('listLinks')
+/** @type {(...args: unknown[]) => unknown} */
+export const closeLink = bindRegistryMethod('closeLink')
+/** @type {(...args: unknown[]) => unknown} */
+export const sendToNodeLink = bindRegistryMethod('sendToNodeLink')
+/** @type {(...args: unknown[]) => unknown} */
+export const relayEnvelopeToNode = bindRegistryMethod('relayEnvelopeToNode')
+/** @type {(...args: unknown[]) => unknown} */
+export const onLinkUp = bindRegistryMethod('onLinkUp')
+/** @type {(...args: unknown[]) => unknown} */
+export const onLinkDown = bindRegistryMethod('onLinkDown')
+/** @type {(...args: unknown[]) => unknown} */
+export const registerScopeInterest = bindRegistryMethod('registerScopeInterest')
+/** @type {(...args: unknown[]) => unknown} */
+export const releaseScopeInterest = bindRegistryMethod('releaseScopeInterest')
+/** @type {(...args: unknown[]) => unknown} */
+export const subscribeScope = bindRegistryMethod('subscribeScope')
+
 /**
- * 默认 registry 的 subscribeScope 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['subscribeScope']>} 取消订阅函数
+ * 注册默认 registry 的 scope authorizer。
+ * 不急切创建 registry（不必 resolveLocalIdentity）；首次 getLinkRegistry 时 flush。
+ * @param {string} prefix scope 前缀
+ * @param {Function} authorizer 校验函数
+ * @returns {() => void} 取消注册函数
  */
-export const subscribeScope = (...args) => getLinkRegistry().subscribeScope(...args)
+export function registerScopeAuthorizer(prefix, authorizer) {
+	if (defaultRegistry) return defaultRegistry.registerScopeAuthorizer(prefix, authorizer)
+
+	const entry = { prefix, authorizer, unregister: null }
+	pendingScopeAuthorizers.push(entry)
+	return () => {
+		const index = pendingScopeAuthorizers.indexOf(entry)
+		if (index !== -1) pendingScopeAuthorizers.splice(index, 1)
+		entry.unregister?.()
+	}
+}