@steve02081504/fount-p2p 0.0.6 → 0.0.7

package/core/tcp_port.mjs

@@ -0,0 +1,11 @@
+/**
+ * 规范化 TCP 端口（advert / peer hint 共用）。
+ * @param {unknown} port 原始端口
+ * @returns {number | null} 有效端口或 null（未提供 / 非法）
+ */
+export function normalizeTcpPort(port) {
+	if (port == null || port === '') return null
+	const value = Number(port)
+	if (!Number.isInteger(value) || value < 1 || value > 65535) return null
+	return value
+}

package/discovery/advert_peer_hints.mjs

@@ -0,0 +1,21 @@
+import { normalizeTcpPort } from '../core/tcp_port.mjs'
+
+import { noteBtPeerHint } from './bt/peer_hints.mjs'
+import { noteLanPeerHint } from './lan_peer_hints.mjs'
+
+/**
+ * 从已验证的 discovery advert + provider meta 写入 LAN/BT peer hints。
+ * 任意 discovery 路径（node / group / scoped topic）收到 advert 时都应调用。
+ * @param {string} verifiedNodeHash 验签通过的 nodeHash
+ * @param {{ tcpPort?: unknown } | null | undefined} body advert body
+ * @param {{ address?: unknown, peripheralId?: unknown } | null | undefined} meta discovery provider meta
+ * @returns {void}
+ */
+export function noteAdvertPeerHints(verifiedNodeHash, body, meta) {
+	if (meta?.peripheralId)
+		noteBtPeerHint(verifiedNodeHash, meta.peripheralId)
+	const tcpPort = normalizeTcpPort(body?.tcpPort)
+	const address = String(meta?.address || '').trim()
+	if (tcpPort != null && address)
+		noteLanPeerHint(verifiedNodeHash, { host: address, port: tcpPort })
+}

package/discovery/{bt.mjs → bt/index.mjs}

@@ -1,56 +1,19 @@
 import { Buffer } from 'node:buffer'
-import process from 'node:process'
+
+import { getBtPeerHint } from './peer_hints.mjs'
+import { loadBleno, loadNoble, resolveBtRole, waitPoweredOn } from './runtime.mjs'
+
+/** 重导出 waitPoweredOn，供 discovery 调用方使用。 */
+export { waitPoweredOn } from './runtime.mjs'
 
 const BT_SERVICE_UUID = 'f017f017f017f017f017f017f017f017'
 const BT_CHARACTERISTIC_UUID = 'f017f017f017f017f017f017f017f018'
+const BT_SIGNAL_CHAR_UUID = 'f017f017f017f017f017f017f017f01b'
 const BT_DEVICE_NAME = 'fount-bt'
 const MAX_ADVERT_BLOB_BYTES = 12 * 1024
+const MAX_SIGNAL_BLOB_BYTES = 8 * 1024
 const PERIPHERAL_RESCAN_MS = 15_000
 
-/**
- * 解析 Bluetooth 发现角色（scan / dual）。
- * @returns {'scan' | 'dual'} 当前平台或环境变量指定的角色
- */
-function resolveBtRole() {
-	const override = String(process.env.FOUNT_BT_DISCOVERY_ROLE || '').trim().toLowerCase()
-	if (override === 'dual') return 'dual'
-	if (override === 'scan') return 'scan'
-	return process.platform === 'win32' ? 'scan' : 'dual'
-}
-
-/**
- * 加载 Noble BLE central 库。
- * @returns {Promise<any>} Noble 运行时实例
- */
-async function loadNoble() {
-	const mod = await import('@stoprocent/noble')
-	if (typeof mod.withBindings === 'function') return mod.withBindings('default')
-	return mod.default ?? mod
-}
-
-/**
- * 加载 Bleno BLE peripheral 库。
- * @returns {Promise<any>} Bleno 运行时实例
- */
-async function loadBleno() {
-	const mod = await import('@stoprocent/bleno')
-	if (typeof mod.withBindings === 'function') return mod.withBindings('default')
-	return mod.default ?? mod
-}
-
-/**
- * 等待 BLE 运行时进入 poweredOn（兼容 noble v1/v2 与 bleno）。
- * @param {*} runtime noble 或 bleno 实例
- * @param {number} [timeout] 超时毫秒
- * @returns {Promise<void>}
- */
-export async function waitPoweredOn(runtime, timeout) {
-	const wait = runtime.waitForPoweredOnAsync ?? runtime.waitForPoweredOn
-	if (typeof wait !== 'function')
-		throw new Error('p2p: bluetooth runtime missing waitForPoweredOn(Async)')
-	return wait.call(runtime, timeout)
-}
-
 /**
  * 探测本机 noble 运行时是否具备 BT 扫描所需 API。
  * @returns {Promise<boolean>} noble 可加载且具备 startScanningAsync 与 waitForPoweredOn(Async) 时为 true
@@ -125,6 +88,7 @@ function addListener(bucket, topic, listener) {
  * - 默认在 Windows 上只启用 scan 侧发现（单适配器 central+peripheral 常冲突）
  * - 其他平台默认 dual：advertise + scan
  * - 通过固定 BLE service + read characteristic 传输完整 advert 列表，避免 31-byte 广告包限制
+ * - dual 下额外暴露 write characteristic 传短信令；central 可按 peer hint 写信令
  *
  * @returns {import('./index.mjs').DiscoveryProvider} Bluetooth 发现提供者
  */
@@ -134,6 +98,8 @@ export function createBluetoothDiscoveryProvider() {
 	const adverts = new Map()
 	/** @type {Map<string, Set<Function>>} */
 	const advertListeners = new Map()
+	/** @type {Map<string, Set<Function>>} */
+	const signalListeners = new Map()
 	/** @type {Map<string, number>} */
 	const inspectedAt = new Map()
 	let nobleRuntime = null
@@ -149,17 +115,17 @@ export function createBluetoothDiscoveryProvider() {
 		if (role === 'scan') return null
 		if (blenoRuntime) return blenoRuntime
 		const bleno = await loadBleno()
-		const characteristic = new bleno.Characteristic({
+		const advertCharacteristic = new bleno.Characteristic({
 			uuid: BT_CHARACTERISTIC_UUID,
 			properties: ['read'],
 			/**
-			 * BLE characteristic 读请求回调。
-			 * @param {*} _handle Bleno handle（未使用）
-			 * @param {number} offset 读取偏移
-			 * @param {Function} callback Bleno 结果回调
+			 * stoprocent/bleno onReadRequest(connection, offset, callback)
+			 * @param {*} _connection 连接句柄
+			 * @param {number} offset 偏移
+			 * @param {Function} callback 结果
 			 * @returns {void}
 			 */
-			onReadRequest(_handle, offset, callback) {
+			onReadRequest(_connection, offset, callback) {
 				try {
 					const blob = serializeAdvertBlob(adverts)
 					if (offset > blob.length) {
@@ -173,11 +139,39 @@ export function createBluetoothDiscoveryProvider() {
 				}
 			},
 		})
+		const signalCharacteristic = new bleno.Characteristic({
+			uuid: BT_SIGNAL_CHAR_UUID,
+			properties: ['write', 'writeWithoutResponse'],
+			/**
+			 * stoprocent/bleno onWriteRequest(connection, data, offset, withoutResponse, callback)
+			 * @param {*} _connection 连接句柄
+			 * @param {Buffer} data 信令 blob
+			 * @param {number} _offset 偏移
+			 * @param {boolean} _withoutResponse 无响应写
+			 * @param {Function} callback 结果
+			 * @returns {void}
+			 */
+			onWriteRequest(_connection, data, _offset, _withoutResponse, callback) {
+				try {
+					const parsed = JSON.parse(Buffer.from(data).toString('utf8'))
+					const topic = String(parsed?.topic || '')
+					const bytes = Uint8Array.from(Buffer.from(String(parsed?.data || ''), 'base64'))
+					if (topic && bytes.byteLength) 
+						for (const listener of signalListeners.get(topic) || [])
+							listener(bytes, { provider: 'bt' })
+					
+					callback(bleno.Characteristic.RESULT_SUCCESS)
+				}
+				catch {
+					callback(bleno.Characteristic.RESULT_UNLIKELY_ERROR)
+				}
+			},
+		})
 		await waitPoweredOn(bleno, 5_000)
 		await bleno.setServicesAsync([
 			new bleno.PrimaryService({
 				uuid: BT_SERVICE_UUID,
-				characteristics: [characteristic],
+				characteristics: [advertCharacteristic, signalCharacteristic],
 			}),
 		])
 		blenoRuntime = bleno
@@ -192,14 +186,14 @@ export function createBluetoothDiscoveryProvider() {
 		if (role === 'scan') return
 		const bleno = await ensurePeripheralRuntime()
 		if (!bleno) return
-		if (!adverts.size) {
+		if (!adverts.size && !signalListeners.size) {
 			if (advertisingStarted) {
 				await bleno.stopAdvertisingAsync().catch(() => { })
 				advertisingStarted = false
 			}
 			return
 		}
-		serializeAdvertBlob(adverts)
+		if (adverts.size) serializeAdvertBlob(adverts)
 		if (!advertisingStarted) {
 			await bleno.startAdvertisingAsync(BT_DEVICE_NAME, [BT_SERVICE_UUID])
 			advertisingStarted = true
@@ -256,10 +250,86 @@ export function createBluetoothDiscoveryProvider() {
 		scanningStarted = true
 	}
 
+	/**
+	 * Central：按 peer hint 连接并对端 signal characteristic 写短包。
+	 * @param {string} topic 信令 topic
+	 * @param {string} to 目标 nodeHash
+	 * @param {Uint8Array} bytes 载荷
+	 * @returns {Promise<void>}
+	 */
+	async function sendSignalViaGatt(topic, to, bytes) {
+		const hint = getBtPeerHint(to)
+		if (!hint) throw new Error('p2p: bt signal missing peer hint')
+		const blob = Buffer.from(JSON.stringify({
+			topic: String(topic),
+			to: String(to),
+			data: Buffer.from(bytes).toString('base64'),
+		}), 'utf8')
+		if (blob.byteLength > MAX_SIGNAL_BLOB_BYTES)
+			throw new Error(`p2p: bt signal blob exceeds ${MAX_SIGNAL_BLOB_BYTES} bytes`)
+		await ensureScanRuntime()
+		const noble = nobleRuntime
+		const wantId = hint.peripheralId
+		/**
+		 * 先查 noble 已缓存的 peripheral，避免只等下一次 advertise 漏报。
+		 * @returns {*|null} 已缓存的 peripheral，未命中为 null
+		 */
+		function cachedPeripheral() {
+			const table = noble?._peripherals
+			if (!table || typeof table !== 'object') return null
+			for (const found of Object.values(table)) {
+				const id = String(found?.id || found?.address || '')
+				if (id === wantId) return found
+			}
+			return null
+		}
+		const peripheral = cachedPeripheral() ?? await new Promise((resolve, reject) => {
+			const deadline = setTimeout(() => {
+				cleanup()
+				reject(new Error('p2p: bt signal peripheral timeout'))
+			}, 8_000)
+			/**
+			 * @returns {void}
+			 */
+			function cleanup() {
+				clearTimeout(deadline)
+				noble.removeListener('discover', onDiscover)
+			}
+			/**
+			 * @param {*} found peripheral
+			 * @returns {void}
+			 */
+			function onDiscover(found) {
+				const id = String(found?.id || found?.address || '')
+				if (id !== wantId) return
+				cleanup()
+				resolve(found)
+			}
+			noble.on('discover', onDiscover)
+			const again = cachedPeripheral()
+			if (again) {
+				cleanup()
+				resolve(again)
+			}
+		})
+		try {
+			await peripheral.connectAsync()
+			const { characteristics } = await peripheral.discoverSomeServicesAndCharacteristicsAsync(
+				[BT_SERVICE_UUID],
+				[BT_SIGNAL_CHAR_UUID],
+			)
+			if (!characteristics?.length) throw new Error('p2p: bt signal characteristic missing')
+			await characteristics[0].writeAsync(blob, false)
+		}
+		finally {
+			try { await peripheral.disconnectAsync() } catch { /* ignore */ }
+		}
+	}
+
 	return {
 		id: 'bt',
 		priority: 20,
-		caps: { canDiscover: true, canSignal: false, canRelay: false },
+		caps: { canDiscover: true, canSignal: true, canRelay: false },
 		/**
 		 * 广播指定 topic 的 advert。
 		 * @param {string} topic advert 主题
@@ -285,5 +355,31 @@ export function createBluetoothDiscoveryProvider() {
 			await ensureScanRuntime()
 			return addListener(advertListeners, String(topic), onAdvert)
 		},
+		/**
+		 * 经 GATT 向近场 peer 发送信令。
+		 * @param {string} topic 信令 topic
+		 * @param {string} to 目标 nodeHash
+		 * @param {Uint8Array} bytes 载荷
+		 * @returns {Promise<void>}
+		 */
+		async sendSignal(topic, to, bytes) {
+			await sendSignalViaGatt(topic, to, bytes)
+		},
+		/**
+		 * 监听经本机 peripheral signal characteristic 写入的信令。
+		 * @param {string} topic 信令 topic
+		 * @param {Function} onSignal 回调
+		 * @returns {Promise<() => void>} 取消订阅
+		 */
+		async onSignal(topic, onSignal) {
+			if (role === 'scan') return () => { }
+			await ensurePeripheralRuntime()
+			await refreshAdvertising()
+			const stop = addListener(signalListeners, String(topic), onSignal)
+			return () => {
+				stop()
+				void refreshAdvertising().catch(() => { })
+			}
+		},
 	}
 }

package/discovery/bt/peer_hints.mjs

@@ -0,0 +1,41 @@
+import { normalizeHex64 } from '../../core/hexIds.mjs'
+import { createTtlMap } from '../../utils/ttl_map.mjs'
+
+/** BT peer hint 存活时间。 */
+export const BT_PEER_HINT_TTL_MS = 5 * 60_000
+
+/** @type {ReturnType<typeof createTtlMap<{ peripheralId: string }>>} */
+const hints = createTtlMap(BT_PEER_HINT_TTL_MS)
+
+/**
+ * 记录近场 BT 扫描到的 nodeHash → peripheral 映射。
+ * @param {string} nodeHash 节点 64 hex
+ * @param {string} peripheralId noble peripheral id / address
+ * @returns {void}
+ */
+export function noteBtPeerHint(nodeHash, peripheralId) {
+	const hash = normalizeHex64(nodeHash)
+	const id = String(peripheralId || '').trim()
+	if (!hash || !id) return
+	hints.set(hash, { peripheralId: id })
+}
+
+/**
+ * 查询未过期的 BT peer hint。
+ * @param {string} nodeHash 节点 64 hex
+ * @param {number} [now=Date.now()] 当前时间（测试可注入）
+ * @returns {{ peripheralId: string } | null} hint 或 null
+ */
+export function getBtPeerHint(nodeHash, now = Date.now()) {
+	const hash = normalizeHex64(nodeHash)
+	if (!hash) return null
+	return hints.get(hash, now)
+}
+
+/**
+ * 清空全部 BT peer hints（测试用）。
+ * @returns {void}
+ */
+export function clearBtPeerHints() {
+	hints.clear()
+}

package/discovery/bt/runtime.mjs

@@ -0,0 +1,46 @@
+import process from 'node:process'
+
+/**
+ * 解析 Bluetooth 角色（scan / dual）。
+ * Win32 默认 scan（单适配器 central+peripheral 常冲突）；可用 FOUNT_BT_DISCOVERY_ROLE 覆盖。
+ * @returns {'scan' | 'dual'} 生效角色
+ */
+export function resolveBtRole() {
+	const override = String(process.env.FOUNT_BT_DISCOVERY_ROLE || '').trim().toLowerCase()
+	if (override === 'dual') return 'dual'
+	if (override === 'scan') return 'scan'
+	return process.platform === 'win32' ? 'scan' : 'dual'
+}
+
+/**
+ * 加载 Noble BLE central。
+ * @returns {Promise<any>} noble 运行时
+ */
+export async function loadNoble() {
+	const mod = await import('@stoprocent/noble')
+	if (typeof mod.withBindings === 'function') return mod.withBindings('default')
+	return mod.default ?? mod
+}
+
+/**
+ * 加载 Bleno BLE peripheral。
+ * @returns {Promise<any>} bleno 运行时
+ */
+export async function loadBleno() {
+	const mod = await import('@stoprocent/bleno')
+	if (typeof mod.withBindings === 'function') return mod.withBindings('default')
+	return mod.default ?? mod
+}
+
+/**
+ * 等待 BLE 运行时 poweredOn（兼容 noble/bleno v1/v2）。
+ * @param {*} runtime noble 或 bleno
+ * @param {number} [timeout] 超时毫秒
+ * @returns {Promise<void>}
+ */
+export async function waitPoweredOn(runtime, timeout) {
+	const wait = runtime.waitForPoweredOnAsync ?? runtime.waitForPoweredOn
+	if (typeof wait !== 'function')
+		throw new Error('p2p: bluetooth runtime missing waitForPoweredOn(Async)')
+	return wait.call(runtime, timeout)
+}

package/discovery/lan_peer_hints.mjs

@@ -0,0 +1,43 @@
+import { normalizeHex64 } from '../core/hexIds.mjs'
+import { normalizeTcpPort } from '../core/tcp_port.mjs'
+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 }>>} */
+const hints = createTtlMap(LAN_PEER_HINT_TTL_MS)
+
+/**
+ * 记录 LAN 上观察到的 nodeHash → host:port。
+ * @param {string} nodeHash 节点 64 hex
+ * @param {{ host: string, port: number }} endpoint 端点
+ * @returns {void}
+ */
+export function noteLanPeerHint(nodeHash, endpoint) {
+	const hash = normalizeHex64(nodeHash)
+	const host = String(endpoint?.host || '').trim()
+	const port = normalizeTcpPort(endpoint?.port)
+	if (!hash || !host || !port) return
+	hints.set(hash, { host, port })
+}
+
+/**
+ * 查询未过期的 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()) {
+	const hash = normalizeHex64(nodeHash)
+	if (!hash) return null
+	return hints.get(hash, now)
+}
+
+/**
+ * 清空全部 LAN peer hints（测试用）。
+ * @returns {void}
+ */
+export function clearLanPeerHints() {
+	hints.clear()
+}

package/discovery/mdns.mjs

@@ -38,7 +38,7 @@ export function createMdnsDiscoveryProvider(options = {}) {
 						resolve()
 					})
 				})
-				socket.on('message', raw => {
+				socket.on('message', (raw, rinfo) => {
 					let packet
 					try { packet = JSON.parse(String(raw)) } catch { return }
 					const listeners = packet.type === 'advert'
@@ -46,8 +46,12 @@ export function createMdnsDiscoveryProvider(options = {}) {
 						: signalListeners.get(String(packet.topic || ''))
 					if (!listeners?.size) return
 					const bytes = Uint8Array.from(Buffer.from(String(packet.data || ''), 'base64'))
+					const meta = {
+						provider: 'mdns',
+						address: String(rinfo?.address || ''),
+					}
 					for (const listener of listeners)
-						listener(bytes, { provider: 'mdns' })
+						listener(bytes, meta)
 				})
 				bound = true
 			})()

package/index.mjs

@@ -1,6 +1,7 @@
 /**
- * Federation P2P 门面：通用引导与房间/发现入口。
- * 重型子系统请直接从子路径导入（如 `./dag/index.mjs`）。
+ * Federation P2P 门面：fount 网络引导与房间/发现入口。
+ * 上层只面对 nodeHash + envelope，不选择 WebRTC/BLE 等传输。
+ * 重型子系统请从子路径导入（如 `./dag`）；勿导入未导出的 `link/`。
  */
 import { registerDiscoveryProvider } from './discovery/index.mjs'
 import { ensureNodeDefaults, getNodeHash } from './node/identity.mjs'

package/link/handshake.mjs

@@ -2,34 +2,50 @@ import { Buffer } from 'node:buffer'
 import { randomBytes } from 'node:crypto'
 
 import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
+import { normalizeTcpPort } from '../core/tcp_port.mjs'
 import { keyPairFromSeed, pubKeyHash, sign, verify } from '../crypto/crypto.mjs'
 import { ensureNodeSeed, getNodeHash } from '../node/identity.mjs'
 
 import { normalizeDtlsFingerprint } from './sdp_fingerprint.mjs'
 
+/** advert / peer-hint 端口规范化（re-export，调用方可直接从 core/tcp_port 导入） */
+export const normalizeAdvertTcpPort = normalizeTcpPort
+
 /**
  * Link 握手签名域标识符。
  */
 export const LINK_HANDSHAKE_DOMAIN = 'fount-link'
 
+/**
+ * 规范化链路绑定材料：DTLS fingerprint 或 64-hex linkId。
+ * @param {unknown} value 原始 binding
+ * @returns {string | null} 规范化 binding，无效时 null
+ */
+export function normalizeLinkBinding(value) {
+	const dtls = normalizeDtlsFingerprint(value)
+	if (dtls) return dtls
+	const hex = normalizeHex64(value)
+	return isHex64(hex) ? hex : null
+}
+
 /**
  * 构造 link auth 待签名字节串。
  * @param {string} peerNonce 对端 hello 中的 nonce（64 位 hex）
- * @param {string} localFingerprint 本地 DTLS fingerprint
+ * @param {string} localBinding 本地绑定材料（DTLS fingerprint 或 linkId）
  * @param {string} localNodeHash 本地节点 nodeHash（64 位 hex）
  * @returns {Uint8Array} 待签名消息字节
  */
-export function buildAuthMessage(peerNonce, localFingerprint, localNodeHash) {
+export function buildAuthMessage(peerNonce, localBinding, localNodeHash) {
 	const nonce = normalizeHex64(peerNonce)
-	const fingerprint = normalizeDtlsFingerprint(localFingerprint)
+	const binding = normalizeLinkBinding(localBinding)
 	const nodeHash = normalizeHex64(localNodeHash)
 	if (!/^[\da-f]{64}$/u.test(nonce))
 		throw new Error('p2p: auth nonce must be 64 hex characters')
-	if (!fingerprint)
-		throw new Error('p2p: DTLS fingerprint missing or invalid')
+	if (!binding)
+		throw new Error('p2p: link binding missing or invalid')
 	if (!isHex64(nodeHash))
 		throw new Error('p2p: nodeHash must be 64 hex characters')
-	return Buffer.from(`${LINK_HANDSHAKE_DOMAIN}\0${nonce}\0${fingerprint}\0${nodeHash}`, 'utf8')
+	return Buffer.from(`${LINK_HANDSHAKE_DOMAIN}\0${nonce}\0${binding}\0${nodeHash}`, 'utf8')
 }
 
 /**
@@ -56,11 +72,11 @@ export function buildHello(options = {}) {
 /**
  * 对 link auth 消息签名。
  * @param {string} peerNonce 对端 hello 中的 nonce
- * @param {string} localFingerprint 本地 DTLS fingerprint
+ * @param {string} localBinding 本地绑定材料（DTLS fingerprint 或 linkId）
  * @param {{ secretKey?: Uint8Array, nodeHash?: string }} [options] 签名密钥与 nodeHash 覆盖
  * @returns {Promise<{ sig: string }>} hex 签名
  */
-export async function buildAuth(peerNonce, localFingerprint, options = {}) {
+export async function buildAuth(peerNonce, localBinding, options = {}) {
 	const seed = options.secretKey
 		? Buffer.from(options.secretKey)
 		: Buffer.from(ensureNodeSeed(), 'hex')
@@ -68,7 +84,7 @@ export async function buildAuth(peerNonce, localFingerprint, options = {}) {
 	const nodeHash = normalizeHex64(options.nodeHash || pubKeyHash(publicKey))
 	if (nodeHash !== pubKeyHash(publicKey))
 		throw new Error('p2p: auth nodeHash does not match secretKey')
-	const message = buildAuthMessage(peerNonce, localFingerprint, nodeHash)
+	const message = buildAuthMessage(peerNonce, localBinding, nodeHash)
 	const signature = await sign(message, secretKey)
 	return { sig: Buffer.from(signature).toString('hex') }
 }
@@ -98,18 +114,18 @@ export function parseHello(hello) {
  * @param {unknown} hello 对端 hello
  * @param {unknown} auth 对端 auth（含 sig）
  * @param {string} expectedNonce 本地 hello 发出的 nonce
- * @param {string} remoteFingerprintFromSdp 从 SDP 提取的远端 DTLS fingerprint
+ * @param {string} remoteBinding 对端绑定材料（DTLS fingerprint 或 linkId）
  * @returns {Promise<string | null>} 验证通过的 nodeHash，失败返回 null
  */
-export async function verifyAuth(hello, auth, expectedNonce, remoteFingerprintFromSdp) {
+export async function verifyAuth(hello, auth, expectedNonce, remoteBinding) {
 	const parsedHello = parseHello(hello)
 	if (!parsedHello) return null
 	const signatureHex = String(auth?.sig ?? '').trim().toLowerCase()
-	const fingerprint = normalizeDtlsFingerprint(remoteFingerprintFromSdp)
-	if (!/^[\da-f]{128}$/u.test(signatureHex) || !fingerprint) return null
+	const binding = normalizeLinkBinding(remoteBinding)
+	if (!/^[\da-f]{128}$/u.test(signatureHex) || !binding) return null
 	const normalizedNonce = normalizeHex64(expectedNonce)
 	if (!isHex64(normalizedNonce)) return null
-	const message = buildAuthMessage(normalizedNonce, fingerprint, parsedHello.nodeHash)
+	const message = buildAuthMessage(normalizedNonce, binding, parsedHello.nodeHash)
 	const ok = await verify(
 		Buffer.from(signatureHex, 'hex'),
 		message,
@@ -123,18 +139,21 @@ export async function verifyAuth(hello, auth, expectedNonce, remoteFingerprintFr
  * @param {string} topic 广播主题
  * @param {number} ts 时间戳（毫秒）
  * @param {string} nodeHash 节点 nodeHash
+ * @param {number | null} [tcpPort=null] 可选 LAN TCP 监听端口（签入消息）
  * @returns {Uint8Array} 待签名消息字节
  */
-export function buildAdvertMessage(topic, ts, nodeHash) {
-	return Buffer.from(`fount-advert\0${String(topic)}\0${String(ts)}\0${normalizeHex64(nodeHash)}`, 'utf8')
+export function buildAdvertMessage(topic, ts, nodeHash, tcpPort = null) {
+	const base = `fount-advert\0${String(topic)}\0${String(ts)}\0${normalizeHex64(nodeHash)}`
+	const port = normalizeTcpPort(tcpPort)
+	return Buffer.from(port == null ? base : `${base}\0${port}`, 'utf8')
 }
 
 /**
  * 构造带签名的 discovery advert。
  * @param {string} topic 广播主题
  * @param {number} [ts=Date.now()] 时间戳（毫秒）
- * @param {{ secretKey?: Uint8Array, nodeHash?: string, nodePubKey?: string } | null} [options] 签名身份，省略则用本地节点
- * @returns {Promise<{ nodeHash: string, nodePubKey: string, ts: number, sig: string }>} 签名 advert
+ * @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
  */
 export async function buildSignedAdvert(topic, ts = Date.now(), options = null) {
 	const seed = options?.secretKey
@@ -145,14 +164,19 @@ export async function buildSignedAdvert(topic, ts = Date.now(), options = null)
 	const nodePubKey = normalizeHex64(options?.nodePubKey || Buffer.from(publicKey).toString('hex'))
 	if (pubKeyHash(Buffer.from(nodePubKey, 'hex')) !== nodeHash)
 		throw new Error('p2p: advert nodePubKey does not match nodeHash')
-	const message = buildAdvertMessage(topic, ts, nodeHash)
+	const tcpPort = normalizeTcpPort(options?.tcpPort)
+	if (options?.tcpPort != null && options.tcpPort !== '' && tcpPort == null)
+		throw new Error('p2p: advert tcpPort invalid')
+	const message = buildAdvertMessage(topic, ts, nodeHash, tcpPort)
 	const sig = await sign(message, secretKey)
-	return {
+	const advert = {
 		nodeHash,
 		nodePubKey,
 		ts,
 		sig: Buffer.from(sig).toString('hex'),
 	}
+	if (tcpPort != null) advert.tcpPort = tcpPort
+	return advert
 }
 
 /**
@@ -169,7 +193,10 @@ export async function verifySignedAdvert(topic, advert, now = Date.now(), maxSke
 	const ts = Number(advert?.ts)
 	const sig = String(advert?.sig ?? '').trim().toLowerCase()
 	if (!Number.isFinite(ts) || Math.abs(now - ts) > maxSkewMs || !/^[\da-f]{128}$/u.test(sig)) return null
-	const message = buildAdvertMessage(topic, ts, parsedHello.nodeHash)
+	const hasTcpPortField = advert?.tcpPort != null && advert.tcpPort !== ''
+	const tcpPort = normalizeTcpPort(advert?.tcpPort)
+	if (hasTcpPortField && tcpPort == null) return null
+	const message = buildAdvertMessage(topic, ts, parsedHello.nodeHash, tcpPort)
 	const ok = await verify(Buffer.from(sig, 'hex'), message, Buffer.from(parsedHello.nodePubKey, 'hex'))
 	return ok ? parsedHello.nodeHash : null
 }