@steve02081504/fount-p2p 0.0.5 → 0.0.7

package/files/evfs.mjs

@@ -10,21 +10,21 @@ import { fetchChunk } from './chunk_fetch.mjs'
 import { createChunkReadStream, getChunk, hasChunk, putChunk } from './chunk_store.mjs'
 import { normalizeFileManifest, publicTransferKeyDescriptor } from './manifest.mjs'
 import { assembleManifestPlaintext, resolveContentKey } from './transfer_key.mjs'
-import { readDagManifestPlaintext, resolveTransferKeyDeps } from './transfer_key_registry.mjs'
+import { readDagManifestPlaintext, resolveTransferKeyDependencies } from './transfer_key_registry.mjs'
 
 /**
  * @param {string} replicaUsername 副本用户名
  * @param {import('./manifest.mjs').FileManifest} manifest 清单
  * @returns {{ getGroupFileMasterKey?: Function, getVaultMasterKey?: Function }} 密钥依赖
  */
-function transferKeyDepsForReplica(replicaUsername, manifest) {
-	const rawDeps = resolveTransferKeyDeps(undefined, manifest)
+function transferKeyDependenciesForReplica(replicaUsername, manifest) {
+	const rawDependencies = resolveTransferKeyDependencies(undefined, manifest)
 	return {
-		getGroupFileMasterKey: rawDeps.getGroupFileMasterKey
-			? (groupId, keyGeneration) => rawDeps.getGroupFileMasterKey(replicaUsername, groupId, keyGeneration)
+		getGroupFileMasterKey: rawDependencies.getGroupFileMasterKey
+			? (groupId, keyGeneration) => rawDependencies.getGroupFileMasterKey(replicaUsername, groupId, keyGeneration)
 			: undefined,
-		getVaultMasterKey: rawDeps.getVaultMasterKey
-			? entityHash => rawDeps.getVaultMasterKey(replicaUsername, entityHash)
+		getVaultMasterKey: rawDependencies.getVaultMasterKey
+			? entityHash => rawDependencies.getVaultMasterKey(replicaUsername, entityHash)
 			: undefined,
 	}
 }
@@ -32,13 +32,13 @@ function transferKeyDepsForReplica(replicaUsername, manifest) {
 /**
  * @param {string} username 拉取身份
  * @param {import('./manifest.mjs').FileManifest} manifest 清单
- * @param {{ fetchChunk?: Function }} [opts] miss 拉取
+ * @param {{ fetchChunk?: Function }} [options] miss 拉取
  * @returns {Promise<boolean>} 全部 part 是否已就位
  */
-async function ensureManifestPartsLocal(username, manifest, opts = {}) {
+async function ensureManifestPartsLocal(username, manifest, options = {}) {
 	for (const part of manifest.parts) {
 		if (await hasChunk(part.hash)) continue
-		const fetchedChunk = await (opts.fetchChunk || fetchChunk)({
+		const fetchedChunk = await (options.fetchChunk || fetchChunk)({
 			username,
 			ciphertextHash: part.hash,
 			ownerEntityHash: manifest.ownerEntityHash,
@@ -81,46 +81,46 @@ export async function storeManifestParts(manifest, partBytes) {
 /**
  * @param {string} replicaUsername 副本用户名
  * @param {import('./manifest.mjs').FileManifest} manifest 清单
- * @param {{ username?: string, fetchChunk?: Function }} [opts] miss 拉取
+ * @param {{ username?: string, fetchChunk?: Function }} [options] miss 拉取
  * @returns {Promise<Buffer | null>} 明文内容
  */
-export async function readManifestPlaintext(replicaUsername, manifest, opts = {}) {
+export async function readManifestPlaintext(replicaUsername, manifest, options = {}) {
 	const dagGroupId = manifest.meta?.groupId
 	if (Array.isArray(manifest.meta?.dagParts) && dagGroupId) {
 		const dagPlain = await readDagManifestPlaintext(replicaUsername, manifest)
 		if (dagPlain) return dagPlain
 	}
 
-	const username = opts.username || replicaUsername
-	if (!await ensureManifestPartsLocal(username, manifest, opts)) return null
+	const username = options.username || replicaUsername
+	if (!await ensureManifestPartsLocal(username, manifest, options)) return null
 
 	/** @type {Buffer[]} */
 	const partBytes = []
 	for (const part of manifest.parts)
 		partBytes.push(await getChunk(part.hash))
 
-	return assembleManifestPlaintext(manifest, partBytes, transferKeyDepsForReplica(replicaUsername, manifest))
+	return assembleManifestPlaintext(manifest, partBytes, transferKeyDependenciesForReplica(replicaUsername, manifest))
 }
 
 /**
  * @param {string} replicaUsername 副本用户名
  * @param {import('./manifest.mjs').FileManifest} manifest 清单
- * @param {{ username?: string, fetchChunk?: Function }} [opts] miss 拉取
+ * @param {{ username?: string, fetchChunk?: Function }} [options] miss 拉取
  * @returns {Promise<import('node:stream').Readable | null>} 明文流
  */
-export async function readManifestPlaintextStream(replicaUsername, manifest, opts = {}) {
+export async function readManifestPlaintextStream(replicaUsername, manifest, options = {}) {
 	const dagGroupId = manifest.meta?.groupId
 	if (Array.isArray(manifest.meta?.dagParts) && dagGroupId) {
-		const plain = await readManifestPlaintext(replicaUsername, manifest, opts)
+		const plain = await readManifestPlaintext(replicaUsername, manifest, options)
 		if (!plain) return null
 		return Readable.from([plain])
 	}
 
-	const username = opts.username || replicaUsername
-	if (!await ensureManifestPartsLocal(username, manifest, opts)) return null
+	const username = options.username || replicaUsername
+	if (!await ensureManifestPartsLocal(username, manifest, options)) return null
 
-	const deps = transferKeyDepsForReplica(replicaUsername, manifest)
-	const contentKey = await resolveContentKey(manifest.transferKeyDescriptor, manifest, deps)
+	const dependencies = transferKeyDependenciesForReplica(replicaUsername, manifest)
+	const contentKey = await resolveContentKey(manifest.transferKeyDescriptor, manifest, dependencies)
 	if (manifest.ceMode === 'random' && !contentKey) return null
 
 	const partStreams = manifest.parts.map(part => createChunkReadStream(part.hash))
@@ -219,16 +219,16 @@ export async function putFileManifestFromStream(params) {
  * @param {string} replicaUsername 副本用户名
  * @param {string} entityHash owner entityHash
  * @param {string} logicalPath EVFS 逻辑路径
- * @param {{ username?: string, fetchChunk?: Function }} [opts] miss 拉取
+ * @param {{ username?: string, fetchChunk?: Function }} [options] miss 拉取
  * @returns {Promise<Buffer | null>} 明文或 null
  */
-export async function readPublicFile(replicaUsername, entityHash, logicalPath, opts = {}) {
+export async function readPublicFile(replicaUsername, entityHash, logicalPath, options = {}) {
 	const { fetchPublicManifest } = await import('./manifest_fetch.mjs')
 	const manifest = await fetchPublicManifest({
-		username: opts.username || replicaUsername,
+		username: options.username || replicaUsername,
 		ownerEntityHash: entityHash,
 		logicalPath,
 	})
 	if (!manifest) return null
-	return readManifestPlaintext(replicaUsername, manifest, opts)
+	return readManifestPlaintext(replicaUsername, manifest, options)
 }

package/files/transfer_key.mjs

@@ -15,26 +15,26 @@ import {
 /**
  * @param {TransferKeyDescriptor} descriptor 传递密钥描述符
  * @param {FileManifest} manifest manifest
- * @param {{ getGroupFileMasterKey?: (groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (entityHash: string) => Promise<Buffer | string | null> }} deps 密钥源
+ * @param {{ getGroupFileMasterKey?: (groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (entityHash: string) => Promise<Buffer | string | null> }} dependencies 密钥源
  * @returns {Promise<Buffer | null>} contentKey；plain/convergent 返回 null（按 contentHash 派生）
  */
-export async function resolveContentKey(descriptor, manifest, deps = {}) {
+export async function resolveContentKey(descriptor, manifest, dependencies = {}) {
 	const type = descriptor?.type || 'public'
 	if (type === 'public' || manifest.ceMode === 'plain' || manifest.ceMode === 'convergent')
 		return null
 
 	if (type === 'file-master-key-wrap') {
 		const { groupId, fileId } = descriptor
-		if (!groupId || !fileId || !descriptor.wrappedKey || !deps.getGroupFileMasterKey) return null
-		const groupKey = await deps.getGroupFileMasterKey(String(groupId), descriptor.keyGeneration)
+		if (!groupId || !fileId || !descriptor.wrappedKey || !dependencies.getGroupFileMasterKey) return null
+		const groupKey = await dependencies.getGroupFileMasterKey(String(groupId), descriptor.keyGeneration)
 		if (!groupKey) return null
 		return unwrapContentKey(descriptor.wrappedKey, groupKey, fileId)
 	}
 
 	if (type === 'vault-wrap') {
 		const { entityHash, fileId } = descriptor
-		if (!entityHash || !fileId || !descriptor.wrappedKey || !deps.getVaultMasterKey) return null
-		const vaultKey = await deps.getVaultMasterKey(String(entityHash))
+		if (!entityHash || !fileId || !descriptor.wrappedKey || !dependencies.getVaultMasterKey) return null
+		const vaultKey = await dependencies.getVaultMasterKey(String(entityHash))
 		if (!vaultKey) return null
 		return unwrapContentKey(descriptor.wrappedKey, vaultKey, fileId)
 	}
@@ -70,12 +70,12 @@ export function decryptPart(encryptedPartBytes, manifest, contentKey, partIndex
 /**
  * @param {FileManifest} manifest manifest
  * @param {Array<Buffer | Uint8Array>} partBytes 按序密文块
- * @param {{ getGroupFileMasterKey?: Function, getVaultMasterKey?: Function }} deps 密钥源
+ * @param {{ getGroupFileMasterKey?: Function, getVaultMasterKey?: Function }} dependencies 密钥源
  * @returns {Promise<Buffer | null>} 完整明文
  */
-export async function assembleManifestPlaintext(manifest, partBytes, deps = {}) {
+export async function assembleManifestPlaintext(manifest, partBytes, dependencies = {}) {
 	if (partBytes.length !== manifest.parts.length) return null
-	const contentKey = await resolveContentKey(manifest.transferKeyDescriptor, manifest, deps)
+	const contentKey = await resolveContentKey(manifest.transferKeyDescriptor, manifest, dependencies)
 	/** @type {Buffer[]} */
 	const plains = []
 	for (let index = 0; index < manifest.parts.length; index++) {

package/files/transfer_key_registry.mjs

@@ -1,18 +1,18 @@
 /** @type {Map<string, { getGroupFileMasterKey?: (replicaUsername: string, groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (replicaUsername: string, entityHash: string) => Promise<Buffer | string | null> }>} */
-const transferDepsByOwner = new Map()
+const transferDependenciesByOwner = new Map()
 
 /** @type {Map<string, (replicaUsername: string, manifest: import('./manifest.mjs').FileManifest) => Promise<Buffer | null>>} */
 const dagPlaintextReadersByOwner = new Map()
 
 /**
  * @param {string} ownerId 注册方
- * @param {{ getGroupFileMasterKey?: (replicaUsername: string, groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (replicaUsername: string, entityHash: string) => Promise<Buffer | string | null> }} deps 密钥源
+ * @param {{ getGroupFileMasterKey?: (replicaUsername: string, groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (replicaUsername: string, entityHash: string) => Promise<Buffer | string | null> }} dependencies 密钥源
  * @returns {void}
  */
-export function registerTransferKeyDeps(ownerId, deps) {
+export function registerTransferKeyDependencies(ownerId, dependencies) {
 	const key = String(ownerId)
-	const prev = transferDepsByOwner.get(key) || {}
-	transferDepsByOwner.set(key, { ...prev, ...deps })
+	const prev = transferDependenciesByOwner.get(key) || {}
+	transferDependenciesByOwner.set(key, { ...prev, ...dependencies })
 }
 
 /**
@@ -50,9 +50,9 @@ export function unregisterManifestOwnerMatchers(ownerId) {
  * @param {string} ownerId 注册方
  * @returns {void}
  */
-export function unregisterTransferKeyDeps(ownerId) {
+export function unregisterTransferKeyDependencies(ownerId) {
 	const key = String(ownerId)
-	transferDepsByOwner.delete(key)
+	transferDependenciesByOwner.delete(key)
 	dagPlaintextReadersByOwner.delete(key)
 	unregisterManifestOwnerMatchers(key)
 }
@@ -73,9 +73,9 @@ export function resolveManifestTransferOwnerId(manifest) {
  * @param {import('./manifest.mjs').FileManifest} [manifest] 用于推断 ownerId
  * @returns {{ getGroupFileMasterKey?: (replicaUsername: string, groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (replicaUsername: string, entityHash: string) => Promise<Buffer | string | null> }} 依赖
  */
-export function resolveTransferKeyDeps(ownerId, manifest) {
+export function resolveTransferKeyDependencies(ownerId, manifest) {
 	const resolved = ownerId || (manifest ? resolveManifestTransferOwnerId(manifest) : null)
-	if (resolved) return transferDepsByOwner.get(String(resolved)) || {}
+	if (resolved) return transferDependenciesByOwner.get(String(resolved)) || {}
 	return {}
 }
 

package/governance/join_pow.mjs

@@ -85,40 +85,40 @@ export function powVoluntaryBonus(achievedBits, floorBits, tunables = admissionT
 
 /**
  * @param {object} powSolution 客户端 solution
- * @param {object} opts 校验上下文
- * @param {string} opts.groupId 群 ID
- * @param {string} opts.senderNodeHash 签名者 nodeHash（须与 joiner 绑定）
- * @param {string[]} opts.knownAnchors 近期 tip / checkpoint root 列表
- * @param {number} [opts.now=Date.now()] 当前时间
- * @param {number} [opts.difficultyBits=0] 准入 floor（前导零 bit）
- * @param {number} [opts.epochMs=JOIN_POW_DEFAULT_EPOCH_MS] epoch 长度
- * @param {number} [opts.epochSkew=JOIN_POW_DEFAULT_EPOCH_SKEW] 允许 epoch 偏移
+ * @param {object} options 校验上下文
+ * @param {string} options.groupId 群 ID
+ * @param {string} options.senderNodeHash 签名者 nodeHash（须与 joiner 绑定）
+ * @param {string[]} options.knownAnchors 近期 tip / checkpoint root 列表
+ * @param {number} [options.now=Date.now()] 当前时间
+ * @param {number} [options.difficultyBits=0] 准入 floor（前导零 bit）
+ * @param {number} [options.epochMs=JOIN_POW_DEFAULT_EPOCH_MS] epoch 长度
+ * @param {number} [options.epochSkew=JOIN_POW_DEFAULT_EPOCH_SKEW] 允许 epoch 偏移
  * @returns {{ ok: boolean, achievedBits: number }} 校验结果与实际达成 bit
  */
-export function verifyJoinPow(powSolution, opts) {
-	const floorBits = Math.max(0, Math.floor(Number(opts.difficultyBits) || 0))
+export function verifyJoinPow(powSolution, options) {
+	const floorBits = Math.max(0, Math.floor(Number(options.difficultyBits) || 0))
 	if (floorBits <= 0) return { ok: true, achievedBits: 0 }
 	if (!powSolution || typeof powSolution !== 'object') return { ok: false, achievedBits: 0 }
 
 	const anchorRef = String(powSolution.anchorRef ?? '').trim()
 	const { nonce } = powSolution
 	const epoch = Number(powSolution.epoch)
-	const joinerNodeHash = String(powSolution.joinerNodeHash ?? opts.senderNodeHash ?? '').trim().toLowerCase()
-	const senderNodeHash = String(opts.senderNodeHash ?? '').trim().toLowerCase()
+	const joinerNodeHash = String(powSolution.joinerNodeHash ?? options.senderNodeHash ?? '').trim().toLowerCase()
+	const senderNodeHash = String(options.senderNodeHash ?? '').trim().toLowerCase()
 
 	if (!anchorRef || nonce == null || !Number.isFinite(epoch)) return { ok: false, achievedBits: 0 }
 	if (!joinerNodeHash || joinerNodeHash !== senderNodeHash) return { ok: false, achievedBits: 0 }
 
-	const anchors = (opts.knownAnchors ?? []).map(a => String(a).trim()).filter(Boolean)
+	const anchors = (options.knownAnchors ?? []).map(a => String(a).trim()).filter(Boolean)
 	if (!anchors.length || !anchors.includes(anchorRef)) return { ok: false, achievedBits: 0 }
 
-	const epochMs = Math.max(60_000, Number(opts.epochMs) || JOIN_POW_DEFAULT_EPOCH_MS)
-	const skew = Math.max(0, Math.floor(Number(opts.epochSkew) ?? JOIN_POW_DEFAULT_EPOCH_SKEW))
-	const nowEpoch = Math.floor((opts.now ?? Date.now()) / epochMs)
+	const epochMs = Math.max(60_000, Number(options.epochMs) || JOIN_POW_DEFAULT_EPOCH_MS)
+	const skew = Math.max(0, Math.floor(Number(options.epochSkew) ?? JOIN_POW_DEFAULT_EPOCH_SKEW))
+	const nowEpoch = Math.floor((options.now ?? Date.now()) / epochMs)
 	if (Math.abs(epoch - nowEpoch) > skew) return { ok: false, achievedBits: 0 }
 
 	const hash = computeJoinPowHash({
-		groupId: opts.groupId,
+		groupId: options.groupId,
 		anchorRef,
 		joinerNodeHash,
 		epoch,

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/channel_mux.mjs

@@ -110,15 +110,15 @@ export function configureBufferedAmountLowThreshold(channel, thresholdBytes = CH
 /**
  * 订阅 bufferedamountlow 事件，返回取消订阅函数。
  * @param {RTCDataChannel} channel RTC 数据通道
- * @param {() => void} cb 低水位回调
+ * @param {() => void} callback 低水位回调
  * @returns {() => void} 取消订阅函数
  */
-export function onBufferedAmountLow(channel, cb) {
+export function onBufferedAmountLow(channel, callback) {
 	/**
 	 * bufferedamountlow 事件处理函数。
 	 * @returns {void}
 	 */
-	const handler = () => cb()
+	const handler = () => callback()
 	channel.addEventListener?.('bufferedamountlow', handler)
 	channel.onbufferedamountlow = handler
 	if (channel.bufferedAmountLow?.subscribe)
@@ -131,12 +131,12 @@ export function onBufferedAmountLow(channel, cb) {
 
 /**
  * 创建带优先级队列的双通道发送器（control/bulk）。
- * @param {{ getChannel: (name: 'control' | 'bulk') => RTCDataChannel | null | undefined, highWatermarkBytes?: number }} opts 通道访问与高水位配置
+ * @param {{ getChannel: (name: 'control' | 'bulk') => RTCDataChannel | null | undefined, highWatermarkBytes?: number }} options 通道访问与高水位配置
  * @returns {{ enqueue: (action: string, bytes: Uint8Array, preferredChannel?: 'control' | 'bulk') => void, flush: (channelName?: 'control' | 'bulk') => void, pending: () => { control: number, bulk: number }, clear: () => void }} 发送队列 API
  */
-export function createChannelSendQueues(opts) {
-	const { getChannel } = opts
-	const highWatermarkBytes = Math.max(CHANNEL_LOW_THRESHOLD_BYTES, Number(opts.highWatermarkBytes) || CHANNEL_HIGH_WATERMARK_BYTES)
+export function createChannelSendQueues(options) {
+	const { getChannel } = options
+	const highWatermarkBytes = Math.max(CHANNEL_LOW_THRESHOLD_BYTES, Number(options.highWatermarkBytes) || CHANNEL_HIGH_WATERMARK_BYTES)
 	/** @type {{ control: Array<{ priority: number, seq: number, bytes: Uint8Array }>, bulk: Array<{ priority: number, seq: number, bytes: Uint8Array }> }} */
 	const queues = { control: [], bulk: [] }
 	/** @type {{ control: boolean, bulk: boolean }} */

package/link/frame.mjs

@@ -150,13 +150,13 @@ function concatChunks(chunks) {
 
 /**
  * 创建分片消息重组器。
- * @param {{ maxMessageBytes?: number, maxPartials?: number, partialTimeoutMs?: number }} [opts] 大小、并发分片数与超时配置
+ * @param {{ maxMessageBytes?: number, maxPartials?: number, partialTimeoutMs?: number }} [options] 大小、并发分片数与超时配置
  * @returns {{ push: (frame: Uint8Array | ArrayBuffer | ArrayBufferView, now?: number) => Uint8Array | null, prune: (now?: number) => string[], clear: () => void, size: () => number }} 重组器 API
  */
-export function createReassembler(opts = {}) {
-	const maxMessageBytes = Math.max(1024, Number(opts.maxMessageBytes) || DEFAULT_MAX_MESSAGE_BYTES)
-	const maxPartials = Math.max(1, Number(opts.maxPartials) || DEFAULT_MAX_PARTIAL_MESSAGES)
-	const partialTimeoutMs = Math.max(1000, Number(opts.partialTimeoutMs) || DEFAULT_PARTIAL_TIMEOUT_MS)
+export function createReassembler(options = {}) {
+	const maxMessageBytes = Math.max(1024, Number(options.maxMessageBytes) || DEFAULT_MAX_MESSAGE_BYTES)
+	const maxPartials = Math.max(1, Number(options.maxPartials) || DEFAULT_MAX_PARTIAL_MESSAGES)
+	const partialTimeoutMs = Math.max(1000, Number(options.partialTimeoutMs) || DEFAULT_PARTIAL_TIMEOUT_MS)
 	/** @type {Map<string, { total: number, chunks: Uint8Array[], seen: boolean[], bytes: number, firstSeenAt: number, lastSeenAt: number }>} */
 	const partials = new Map()
 

package/link/handshake.mjs

@@ -2,50 +2,66 @@ 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')
 }
 
 /**
  * 构造 link hello 握手包。
- * @param {{ nodeHash?: string, nodePubKey?: string, nonce?: string }} [opts] 可选身份字段，省略则从本地节点种子推导
+ * @param {{ nodeHash?: string, nodePubKey?: string, nonce?: string }} [options] 可选身份字段，省略则从本地节点种子推导
  * @returns {{ v: 1, nodeHash: string, nodePubKey: string, nonce: string }} hello 对象
  */
-export function buildHello(opts = {}) {
+export function buildHello(options = {}) {
 	let publicKey = null
-	if (!opts.nodeHash || !opts.nodePubKey) {
+	if (!options.nodeHash || !options.nodePubKey) {
 		const derived = keyPairFromSeed(Buffer.from(ensureNodeSeed(), 'hex'))
 		publicKey = derived.publicKey
 	}
-	const nodeHash = normalizeHex64(opts.nodeHash || getNodeHash())
-	const nodePubKey = normalizeHex64(opts.nodePubKey || Buffer.from(publicKey).toString('hex'))
-	const nonce = normalizeHex64(opts.nonce || randomBytes(32).toString('hex'))
+	const nodeHash = normalizeHex64(options.nodeHash || getNodeHash())
+	const nodePubKey = normalizeHex64(options.nodePubKey || Buffer.from(publicKey).toString('hex'))
+	const nonce = normalizeHex64(options.nonce || randomBytes(32).toString('hex'))
 	if (!isHex64(nodeHash) || !isHex64(nodePubKey) || !isHex64(nonce))
 		throw new Error('p2p: invalid hello fields')
 	if (pubKeyHash(Buffer.from(nodePubKey, 'hex')) !== nodeHash)
@@ -56,19 +72,19 @@ export function buildHello(opts = {}) {
 /**
  * 对 link auth 消息签名。
  * @param {string} peerNonce 对端 hello 中的 nonce
- * @param {string} localFingerprint 本地 DTLS fingerprint
- * @param {{ secretKey?: Uint8Array, nodeHash?: string }} [opts] 签名密钥与 nodeHash 覆盖
+ * @param {string} localBinding 本地绑定材料（DTLS fingerprint 或 linkId）
+ * @param {{ secretKey?: Uint8Array, nodeHash?: string }} [options] 签名密钥与 nodeHash 覆盖
  * @returns {Promise<{ sig: string }>} hex 签名
  */
-export async function buildAuth(peerNonce, localFingerprint, opts = {}) {
-	const seed = opts.secretKey
-		? Buffer.from(opts.secretKey)
+export async function buildAuth(peerNonce, localBinding, options = {}) {
+	const seed = options.secretKey
+		? Buffer.from(options.secretKey)
 		: Buffer.from(ensureNodeSeed(), 'hex')
 	const { publicKey, secretKey } = keyPairFromSeed(seed)
-	const nodeHash = normalizeHex64(opts.nodeHash || pubKeyHash(publicKey))
+	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,36 +139,44 @@ 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} [opts] 签名身份，省略则用本地节点
- * @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(), opts = null) {
-	const seed = opts?.secretKey
-		? Buffer.from(opts.secretKey)
+export async function buildSignedAdvert(topic, ts = Date.now(), options = null) {
+	const seed = options?.secretKey
+		? Buffer.from(options.secretKey)
 		: Buffer.from(ensureNodeSeed(), 'hex')
 	const { publicKey, secretKey } = keyPairFromSeed(seed)
-	const nodeHash = normalizeHex64(opts?.nodeHash || pubKeyHash(publicKey))
-	const nodePubKey = normalizeHex64(opts?.nodePubKey || Buffer.from(publicKey).toString('hex'))
+	const nodeHash = normalizeHex64(options?.nodeHash || pubKeyHash(publicKey))
+	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
 }