@steve02081504/fount-p2p 0.0.12 → 0.0.13

package/discovery/index.mjs

@@ -1,10 +1,27 @@
-/** @typedef {{ id: string, priority: number, caps: { canDiscover?: boolean, canSignal?: boolean, canRelay?: boolean }, advertise?: (topic: string, bytes: Uint8Array) => (() => void) | Promise<() => void>, subscribe?: (topic: string, onAdvert: (bytes: Uint8Array, meta?: object) => void) => (() => void) | Promise<() => void>, sendSignal?: (topic: string, to: string, bytes: Uint8Array) => boolean | void | Promise<boolean | void>, onSignal?: (topic: string, onSignal: (bytes: Uint8Array, meta?: object) => void) => (() => void) | Promise<() => void> }} DiscoveryProvider */
+import { normalizeHex64 } from '../core/hexIds.mjs'
+import { nodeDebug, shortHash } from '../node/log.mjs'
+
+import { ingestGroupAdvert, ingestNodeAdvert } from './adverts.mjs'
+import { decryptSignalPacket, encryptSignalPacket, nodeRendezvousKey } from './internal/signal_crypto.mjs'
+
+/** @typedef {{ id: string, priority: number, caps?: { canDiscover?: boolean, canSignal?: boolean, canRelay?: boolean }, listVisibleNodeHashes?: (options?: { limit?: number, roomSecret?: string }) => Promise<string[]>, connectToNode?: (nodeHash: string, options?: object) => Promise<boolean | null>, startPresence?: (getBeacon: () => Promise<object | null>) => Promise<() => void>, startGroupPresence?: (roomSecret: string, getBeacon: () => Promise<object | null>) => Promise<() => void>, sendNodeSignal?: (toNodeHash: string, bytes: Uint8Array) => Promise<boolean | void>, listenNodeSignals?: (localNodeHash: string, onSignal: (bytes: Uint8Array) => void) => Promise<() => void>, watchNodeAdvert?: (nodeHash: string, onAdvert: (bytes: Uint8Array, meta: object) => void) => Promise<() => void>, watchGroupAdverts?: (roomSecret: string, onAdvert: (bytes: Uint8Array, meta: object) => void) => Promise<() => void>, noteVisibleNode?: (nodeHash: string, options?: { roomSecret?: string }) => void, dispose?: () => void }} DiscoveryProvider */
 
 /** @type {Map<string, DiscoveryProvider>} */
 const providers = new Map()
 
+/** @type {((nodeHash: string) => Promise<object | null>) | null} */
+let linkDialer = null
+
+/**
+ * 由 link registry 注入：discovery.connectToNode 经此建链（dialer 内负责 prepare）。
+ * @param {((nodeHash: string) => Promise<object | null>) | null} dialer 拨号函数
+ * @returns {void}
+ */
+export function setDiscoveryLinkDialer(dialer) {
+	linkDialer = dialer
+}
+
 /**
- * 注册 discovery provider。
  * @param {DiscoveryProvider} provider 发现提供者
  * @returns {() => void} 注销函数
  */
@@ -15,111 +32,299 @@ export function registerDiscoveryProvider(provider) {
 }
 
 /**
- * 注销 discovery provider。
  * @param {string} id 提供者 id
  * @returns {void}
  */
 export function unregisterDiscoveryProvider(id) {
+	const provider = providers.get(String(id))
 	providers.delete(String(id))
+	try { provider?.dispose?.() } catch { /* ignore */ }
 }
 
-/**
- * 清空全部 discovery provider。
- * @returns {void}
- */
+/** @returns {void} */
 export function clearDiscoveryProviders() {
+	const list = [...providers.values()]
 	providers.clear()
+	for (const provider of list)
+		try { provider.dispose?.() } catch { /* ignore */ }
 }
 
-/**
- * 列出已注册的 discovery provider（按 priority 排序）。
- * @returns {DiscoveryProvider[]} 提供者列表
- */
+/** @returns {DiscoveryProvider[]} 按 priority 升序排列的已注册提供者 */
 export function listDiscoveryProviders() {
 	return [...providers.values()].sort((left, right) => Number(left.priority || 0) - Number(right.priority || 0))
 }
 
 /**
- * 并行启动各 provider 的 async 钩子；单路失败静默。
- * @param {DiscoveryProvider[]} list 提供者列表
- * @param {(provider: DiscoveryProvider) => Promise<(() => void) | null | undefined>} run 单路启动
- * @returns {Promise<() => void>} 统一取消函数
+ * @param {string} id 提供者 id
+ * @returns {DiscoveryProvider | undefined} 对应 id 的提供者，未注册为 undefined
+ */
+export function getDiscoveryProvider(id) {
+	return providers.get(String(id))
+}
+
+/**
+ * @param {string} method provider 方法名
+ * @returns {DiscoveryProvider[]} 实现了指定方法的提供者列表
+ */
+function providersWith(method) {
+	return listDiscoveryProviders().filter(provider => typeof provider[method] === 'function')
+}
+
+/**
+ * @param {Array<(() => void) | null | undefined>} cleanups 清理函数
+ * @returns {() => void} 调用时依次执行各 cleanup
  */
-async function startProvidersParallel(list, run) {
-	const settled = await Promise.all(list.map(async provider => {
+function composeCleanups(cleanups) {
+	return () => {
+		for (const stop of cleanups)
+			if (typeof stop === 'function') try { stop() } catch { /* ignore */ }
+	}
+}
+
+/**
+ * 对各实现了 method 的 provider 并行调用，合并 cleanup。
+ * @param {string} method provider 方法名
+ * @param {unknown[]} methodArguments 参数
+ * @param {{ errorLabel?: string, requireAny?: boolean }} [options] requireAny 默认 true
+ * @returns {Promise<() => void>} 合并各 provider 返回的 cleanup
+ */
+async function fanInProviderMethod(method, methodArguments, options = {}) {
+	const requireAny = options.requireAny !== false
+	const capable = providersWith(method)
+	if (requireAny && !capable.length) throw new Error(options.errorLabel || `p2p: ${method} unavailable`)
+	const cleanups = await Promise.all(capable.map(async provider => {
 		try {
-			const cleanup = await run(provider)
-			return typeof cleanup === 'function' ? cleanup : null
+			return await provider[method](...methodArguments)
 		}
 		catch {
 			return null
 		}
 	}))
-	const cleanups = settled.filter(Boolean)
-	return () => {
-		for (const cleanup of cleanups)
-			try { cleanup() } catch { /* ignore */ }
+	if (requireAny && !cleanups.some(stop => typeof stop === 'function'))
+		throw new Error(options.errorLabel || `p2p: ${method} unavailable`)
+	return composeCleanups(cleanups)
+}
+
+/**
+ * 合并各 provider 可见 nodeHash（带 roomSecret 时各介质只返回本群池；不懂群的介质应返回 []）。
+ * @param {{ limit?: number, roomSecret?: string }} [options] 扫描选项
+ * @returns {Promise<string[]>} 去重后的 nodeHash 列表
+ */
+export async function listVisibleNodeHashes(options = {}) {
+	const limit = Math.max(1, Number(options.limit) || 64)
+	const seen = new Set()
+	/** @type {Record<string, string[]>} */
+	const byProvider = {}
+	for (const provider of listDiscoveryProviders()) {
+		if (typeof provider.listVisibleNodeHashes !== 'function') continue
+		try {
+			const hashes = await provider.listVisibleNodeHashes(options)
+			byProvider[provider.id] = hashes.map(hash => shortHash(hash))
+			for (const hash of hashes) {
+				if (hash) seen.add(hash)
+				if (seen.size >= limit) break
+			}
+			if (seen.size >= limit) break
+		}
+		catch (error) {
+			nodeDebug('p2p:discovery list fail', {
+				provider: provider.id,
+				err: String(error?.message || error),
+			})
+		}
 	}
+	const out = [...seen].slice(0, limit)
+	nodeDebug('p2p:discovery visible', {
+		total: out.length,
+		group: !!options.roomSecret,
+		byProvider,
+	})
+	return out
 }
 
 /**
- * 通过所有可用 provider 广播 topic advert。
- * 单路失败静默（正常降级）；其它 provider 仍可成功。
- * @param {string} topic advert 主题
- * @param {Uint8Array} bytes advert 载荷
- * @returns {Promise<() => void>} 统一取消函数
+ * 各发现介质准备通往 nodeHash 的路径（hint / 订阅 / 近场），不建链。
+ * @param {string} nodeHash 目标 nodeHash
+ * @param {object} [options] 额外选项
+ * @returns {Promise<void>}
  */
-export async function advertiseTopic(topic, bytes) {
-	const list = listDiscoveryProviders().filter(provider => provider.caps?.canDiscover && typeof provider.advertise === 'function')
-	return startProvidersParallel(list, provider => provider.advertise(topic, bytes))
+export async function prepareConnectToNode(nodeHash, options = {}) {
+	const hash = normalizeHex64(nodeHash)
+	for (const provider of listDiscoveryProviders()) {
+		if (typeof provider.connectToNode !== 'function') continue
+		try { await provider.connectToNode(hash, options) }
+		catch { /* prepare next medium */ }
+	}
 }
 
 /**
- * 通过所有可用 provider 订阅 topic advert。
- * 单路失败静默（正常降级）。
- * @param {string} topic advert 主题
- * @param {(bytes: Uint8Array, meta?: object) => void} onAdvert advert 回调
- * @returns {Promise<() => void>} 统一取消函数
+ * 经 registry dialer 建链（dialer 内 prepare）；无 dialer 时仅 prepare，返回 false。
+ * @param {string} nodeHash 目标 nodeHash
+ * @param {object} [options] 无 dialer 时转交 prepare
+ * @returns {Promise<boolean>} 是否建链成功
  */
-export async function subscribeTopic(topic, onAdvert) {
-	const list = listDiscoveryProviders().filter(provider => provider.caps?.canDiscover && typeof provider.subscribe === 'function')
-	return startProvidersParallel(list, provider => provider.subscribe(topic, onAdvert))
+export async function connectToNode(nodeHash, options = {}) {
+	const hash = normalizeHex64(nodeHash)
+	if (!linkDialer) {
+		await prepareConnectToNode(hash, options)
+		nodeDebug('p2p:discovery connect skip', { peer: shortHash(hash), reason: 'no-dialer' })
+		return false
+	}
+	try {
+		const ok = !!await linkDialer(hash)
+		nodeDebug(ok ? 'p2p:discovery connect ok' : 'p2p:discovery connect miss', { peer: shortHash(hash) })
+		return ok
+	}
+	catch (error) {
+		nodeDebug('p2p:discovery connect fail', {
+			peer: shortHash(hash),
+			err: String(error?.message || error),
+		})
+		return false
+	}
 }
 
 /**
- * 通过 discovery provider 发送信令。
- * provider 返回 `false` = 本路不可达（正常降级，不计成功）；其它返回值 / void = 已投递。
- * 单路 throw 静默；全部未投递才 throw。
- * @param {string} topic 信令 topic
- * @param {string} to 目标节点标识
- * @param {Uint8Array} bytes 信令载荷
+ * 经各可信令介质发送；任一成功即返回。
+ * @param {string} toNodeHash 目标 nodeHash
+ * @param {Uint8Array} bytes 载荷
  * @returns {Promise<void>}
  */
-export async function sendSignal(topic, to, bytes) {
-	const capable = listDiscoveryProviders().filter(provider => provider.caps?.canSignal && typeof provider.sendSignal === 'function')
-	if (!capable.length) throw new Error('p2p: no discovery provider can signal')
-	let sent = false
+export async function sendNodeSignal(toNodeHash, bytes) {
+	const capable = providersWith('sendNodeSignal')
+	if (!capable.length) throw new Error('p2p: signaling unavailable')
 	let lastError = null
-	await Promise.all(capable.map(async provider => {
+	for (const provider of capable)
 		try {
-			if (await Promise.resolve(provider.sendSignal(topic, to, bytes)) !== false)
-				sent = true
+			const result = await provider.sendNodeSignal(toNodeHash, bytes)
+			if (result !== false) return
 		}
 		catch (error) {
 			lastError = error
 		}
-	}))
-	if (!sent) throw lastError || new Error('p2p: no discovery provider delivered signal')
+
+	if (lastError) throw lastError
+	throw new Error('p2p: signaling unavailable')
+}
+
+/**
+ * 在各可信令介质上监听；返回统一取消。
+ * @param {string} localNodeHash 本机 nodeHash
+ * @param {(bytes: Uint8Array) => void} onSignal 回调
+ * @returns {Promise<() => void>} 取消函数
+ */
+export async function listenNodeSignals(localNodeHash, onSignal) {
+	return fanInProviderMethod('listenNodeSignals', [localNodeHash, onSignal], {
+		errorLabel: 'p2p: signaling unavailable',
+	})
 }
 
 /**
- * 通过所有可用 provider 监听信令。
- * 单路失败静默（正常降级）。
- * @param {string} topic 信令 topic
- * @param {(bytes: Uint8Array, meta?: object) => void} onSignal 信令回调
- * @returns {Promise<() => void>} 统一取消函数
+ * 启动各 provider 的 presence（若支持）。
+ * @param {() => Promise<object | null>} getBeacon 本机 beacon
+ * @returns {Promise<() => void>} 统一停止函数
  */
-export async function listenSignals(topic, onSignal) {
-	const list = listDiscoveryProviders().filter(provider => provider.caps?.canSignal && typeof provider.onSignal === 'function')
-	return startProvidersParallel(list, provider => provider.onSignal(topic, onSignal))
+export async function startDiscoveryPresence(getBeacon) {
+	return fanInProviderMethod('startPresence', [getBeacon], { requireAny: false })
 }
+
+/**
+ * 监听指定 nodeHash 的 advert（各支持介质 fan-in）。
+ * @param {string} nodeHash 目标 nodeHash
+ * @param {(bytes: Uint8Array, meta: object) => void} onAdvert 回调
+ * @returns {Promise<() => void>} 取消函数
+ */
+export async function watchNodeAdvert(nodeHash, onAdvert) {
+	return fanInProviderMethod('watchNodeAdvert', [nodeHash, onAdvert], {
+		errorLabel: 'p2p: node advert watch unavailable',
+	})
+}
+
+/**
+ * 群 advert 监听（各支持介质 fan-in）。
+ * @param {string} roomSecret 房间密钥
+ * @param {(bytes: Uint8Array, meta: object) => void} onAdvert 回调
+ * @returns {Promise<() => void>} 取消群 advert 监听
+ */
+export async function watchGroupAdverts(roomSecret, onAdvert) {
+	return fanInProviderMethod('watchGroupAdverts', [roomSecret, onAdvert], {
+		errorLabel: 'p2p: group advert watch unavailable',
+	})
+}
+
+/**
+ * 群 presence 广播（各支持介质 fan-out）。
+ * @param {string} roomSecret 房间密钥
+ * @param {() => Promise<object | null>} getBeacon advert 工厂
+ * @returns {Promise<() => void>} 停止群 presence 广播
+ */
+export async function startGroupPresence(roomSecret, getBeacon) {
+	return fanInProviderMethod('startGroupPresence', [roomSecret, getBeacon], {
+		errorLabel: 'p2p: group presence unavailable',
+	})
+}
+
+/**
+ * 向节点发送 JSON 信令包（discovery 内部加解密）。
+ * @param {string} toNodeHash 目标 nodeHash
+ * @param {unknown} packet JSON 载荷
+ * @returns {Promise<void>}
+ */
+export async function sendNodeSignalPacket(toNodeHash, packet) {
+	const hash = normalizeHex64(toNodeHash)
+	await sendNodeSignal(hash, encryptSignalPacket(nodeRendezvousKey(hash), packet))
+}
+
+/**
+ * 解密发往本机的节点信令包。
+ * @param {string} localNodeHash 本机 nodeHash
+ * @param {Uint8Array} bytes 加密字节
+ * @returns {object | null} 解密 JSON
+ */
+export function decryptNodeSignalPacket(localNodeHash, bytes) {
+	return decryptSignalPacket(nodeRendezvousKey(normalizeHex64(localNodeHash)), bytes)
+}
+
+/**
+ * advert 验签后写入各介质可见池。
+ * @param {string} verifiedNodeHash 已验签 nodeHash
+ * @param {{ roomSecret?: string }} [options] 带 roomSecret 时写入群池
+ * @returns {void}
+ */
+export function noteVisibleNodeFromAdvert(verifiedNodeHash, options = {}) {
+	for (const provider of listDiscoveryProviders())
+		provider.noteVisibleNode?.(verifiedNodeHash, options)
+}
+
+/**
+ * 监听指定 nodeHash 的 advert，验签后回调。
+ * @param {string} nodeHash 目标 nodeHash
+ * @param {(verifiedNodeHash: string, body: object, meta: object) => void | Promise<void>} onAdvert 回调
+ * @returns {Promise<() => void>} 取消函数
+ */
+export async function watchVerifiedNodeAdvert(nodeHash, onAdvert) {
+	return await watchNodeAdvert(nodeHash, async (bytes, meta) => {
+		const ingested = await ingestNodeAdvert(nodeHash, bytes, meta)
+		if (!ingested) return
+		noteVisibleNodeFromAdvert(ingested.verifiedNodeHash)
+		await Promise.resolve(onAdvert(ingested.verifiedNodeHash, ingested.body, meta))
+	})
+}
+
+/**
+ * 群 advert 监听 + 验签；写入群可见池。
+ * @param {string} roomSecret 房间密钥
+ * @param {(verifiedNodeHash: string, body: object, meta: object) => void | Promise<void>} onAdvert 回调
+ * @returns {Promise<() => void>} 取消群 advert 验签监听
+ */
+export async function watchVerifiedGroupAdverts(roomSecret, onAdvert) {
+	return await watchGroupAdverts(roomSecret, async (bytes, meta) => {
+		const ingested = await ingestGroupAdvert(roomSecret, bytes, meta)
+		if (!ingested) return
+		noteVisibleNodeFromAdvert(ingested.verifiedNodeHash, { roomSecret })
+		await Promise.resolve(onAdvert(ingested.verifiedNodeHash, ingested.body, meta))
+	})
+}
+
+/** 再导出：scope advert 构建/加密/验签（见 `adverts.mjs`）。 */
+export { buildSignedAdvertForScope, encryptAdvertForScope, encryptAdvertPacket, ingestEncryptedAdvert, ingestGroupAdvert, ingestNetworkAdvert, ingestNodeAdvert } from './adverts.mjs'

package/discovery/internal/signal_crypto.mjs

@@ -0,0 +1,109 @@
+import { Buffer } from 'node:buffer'
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto'
+
+import { normalizeHex64 } from '../../core/hexIds.mjs'
+import { sha256Hex } from '../../crypto/crypto.mjs'
+import { createLruMap } from '../../utils/lru.mjs'
+
+const SIGNAL_DOMAIN = 'fount-signal'
+const NODE_RENDEZVOUS_DOMAIN = 'fount-rdv-node:'
+const GROUP_RENDEZVOUS_DOMAIN = 'fount-rdv-group:'
+const NETWORK_RENDEZVOUS_DOMAIN = 'fount-rdv-network:'
+
+/** rendezvous 键 → AES-256 密钥缓存上限 */
+export const SIGNAL_KEY_CACHE_MAX = 512
+
+/**
+ * 节点 rendezvous 键（discovery advert / signal）。
+ * @param {string} nodeHash 节点 64 hex
+ * @returns {string} rendezvous 键
+ */
+export function nodeRendezvousKey(nodeHash) {
+	return sha256Hex(`${NODE_RENDEZVOUS_DOMAIN}${normalizeHex64(nodeHash)}`)
+}
+
+/**
+ * 群组 rendezvous 键（roomSecret）。
+ * @param {string} roomSecret 房间密钥
+ * @returns {string} rendezvous 键
+ */
+export function groupRendezvousKey(roomSecret) {
+	return sha256Hex(`${GROUP_RENDEZVOUS_DOMAIN}${roomSecret}`)
+}
+
+/**
+ * 全网 network-scope rendezvous 键。
+ * @returns {string} rendezvous 键
+ */
+export function networkRendezvousKey() {
+	return sha256Hex(NETWORK_RENDEZVOUS_DOMAIN)
+}
+
+/** rendezvous 键 → AES-256 密钥 LRU */
+const signalKeysByKey = createLruMap(SIGNAL_KEY_CACHE_MAX)
+
+/**
+ * @param {string} rendezvousKey rendezvous 键
+ * @returns {Buffer} AES-256 密钥
+ */
+function signalKeyForRendezvous(rendezvousKey) {
+	let cached = signalKeysByKey.get(rendezvousKey)
+	if (cached) {
+		signalKeysByKey.touch(rendezvousKey, cached)
+		return cached
+	}
+	cached = createHash('sha256').update(`${SIGNAL_DOMAIN}:${rendezvousKey}`).digest()
+	signalKeysByKey.touch(rendezvousKey, cached)
+	return cached
+}
+
+/** @returns {number} 密钥缓存条目数（测试用） */
+export function signalKeyCacheSize() {
+	return signalKeysByKey.size
+}
+
+/**
+ * AES-GCM 封装 JSON 信令 / advert 包。
+ * @param {string} rendezvousKey rendezvous 键
+ * @param {unknown} packet 待加密 JSON
+ * @returns {Uint8Array} 加密字节
+ */
+export function encryptSignalPacket(rendezvousKey, packet) {
+	const iv = randomBytes(12)
+	const cipher = createCipheriv('aes-256-gcm', signalKeyForRendezvous(rendezvousKey), 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'),
+	}))
+}
+
+/**
+ * Untrusted ingress：AES-GCM 解密信令 / advert；失败返回 null。
+ * @param {string} rendezvousKey rendezvous 键
+ * @param {Uint8Array} bytes 加密字节
+ * @returns {object | null} 解密 JSON 或 null
+ */
+export function decryptSignalPacket(rendezvousKey, bytes) {
+	try {
+		const payload = JSON.parse(Buffer.from(bytes).toString('utf8'))
+		const decipher = createDecipheriv(
+			'aes-256-gcm',
+			signalKeyForRendezvous(rendezvousKey),
+			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
+	}
+}