@steve02081504/fount-p2p 0.0.12 → 0.0.14

package/discovery/nostr.mjs

@@ -4,7 +4,18 @@ import { schnorr } from '@noble/curves/secp256k1.js'
 import WebSocket from 'ws'
 
 import { base64ToBytes, hexToBytes, bytesToBase64, bytesToHex } from '../core/bytes_codec.mjs'
+import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
 import { sha256Hex } from '../crypto/crypto.mjs'
+import { nodeDebug, shortHash } from '../node/log.mjs'
+
+import { ingestEncryptedAdvert } from './adverts.mjs'
+import { noteAdvertPeerHints } from './advert_peer_hints.mjs'
+import {
+	encryptSignalPacket,
+	groupRendezvousKey,
+	networkRendezvousKey,
+	nodeRendezvousKey,
+} from './internal/signal_crypto.mjs'
 
 /** 默认 Nostr 中继 URL 列表。 */
 export const DEFAULT_RELAY_URLS = [
@@ -18,14 +29,128 @@ export const NOSTR_CONNECT_TIMEOUT_MS = 2_000
 /** 先 close，超时未 CLOSED 再 terminate（给对端优雅关闭的窗口）。 */
 export const NOSTR_CLOSE_GRACE_MS = 1_000
 
-/** Nostr advert 事件 kind。 */
-export const NOSTR_ADVERT_KIND = 27235
-/** Nostr signal 事件 kind。 */
-export const NOSTR_SIGNAL_KIND = 27236
+/** 单 relay 等待 EVENT OK 回执超时。 */
+export const NOSTR_PUBLISH_OK_TIMEOUT_MS = 3_000
+
+/** Nostr network advert 事件 kind（addressable，可存储）。 */
+export const NOSTR_ADVERT_KIND = 30787
+/** Nostr signal 事件 kind（ephemeral，实时转发）。 */
+export const NOSTR_SIGNAL_KIND = 20787
+
+const ADVERT_TTL_MS = 10 * 60_000
+
+/** @type {Map<string, number>} 网络域 nodeHash → lastSeenAt */
+const visibleByHash = new Map()
+/** @type {Map<string, Map<string, number>>} roomSecret → (nodeHash → lastSeenAt) */
+const visibleByGroup = new Map()
+
+/**
+ * @param {Map<string, number>} pool 可见池
+ * @param {number} now 当前时间
+ * @param {number} ttlMs TTL
+ * @returns {string[]} 未过期 nodeHash
+ */
+function listPoolHashes(pool, now, ttlMs) {
+	/** @type {string[]} */
+	const out = []
+	for (const [hash, seenAt] of pool)
+		if (now - seenAt <= ttlMs) out.push(hash)
+		else pool.delete(hash)
+
+	return out
+}
+
+/**
+ * 写入网络域可见池（非群）。
+ * @param {string} nodeHash 节点 hash
+ * @param {number} [now=Date.now()] 当前时间
+ * @returns {void}
+ */
+export function noteNostrVisibleNode(nodeHash, now = Date.now()) {
+	const hash = normalizeHex64(nodeHash)
+	if (!isHex64(hash)) return
+	visibleByHash.set(hash, now)
+}
+
+/**
+ * 写入群域可见池（与网络域隔离）。
+ * @param {string} roomSecret 房间密钥
+ * @param {string} nodeHash 节点 hash
+ * @param {number} [now=Date.now()] 当前时间
+ * @returns {void}
+ */
+export function noteNostrGroupVisibleNode(roomSecret, nodeHash, now = Date.now()) {
+	const key = String(roomSecret || '')
+	const hash = normalizeHex64(nodeHash)
+	if (!key || !isHex64(hash)) return
+	let pool = visibleByGroup.get(key)
+	if (!pool) {
+		pool = new Map()
+		visibleByGroup.set(key, pool)
+	}
+	pool.set(hash, now)
+}
+
+/**
+ * @param {number} [now=Date.now()] 当前时间
+ * @param {number} [ttlMs=ADVERT_TTL_MS] TTL
+ * @returns {string[]} 网络域可见 nodeHash
+ */
+export function listNostrVisibleNodeHashes(now = Date.now(), ttlMs = ADVERT_TTL_MS) {
+	return listPoolHashes(visibleByHash, now, ttlMs)
+}
+
+/**
+ * @param {string} roomSecret 房间密钥
+ * @param {number} [now=Date.now()] 当前时间
+ * @param {number} [ttlMs=ADVERT_TTL_MS] TTL
+ * @returns {string[]} 该群可见 nodeHash
+ */
+export function listNostrGroupVisibleNodeHashes(roomSecret, now = Date.now(), ttlMs = ADVERT_TTL_MS) {
+	const key = String(roomSecret || '')
+	const pool = visibleByGroup.get(key)
+	if (!pool) return []
+	const out = listPoolHashes(pool, now, ttlMs)
+	if (!pool.size) visibleByGroup.delete(key)
+	return out
+}
+
+/**
+ * 解密并验签后写入 Nostr 可见池；伪造 body.nodeHash 无效。
+ * @param {string} rendezvousKey rendezvous 键
+ * @param {Uint8Array} bytes 加密 advert
+ * @param {{ roomSecret?: string }} [options] 带 roomSecret 时写入群池
+ * @returns {Promise<string | null>} 验签通过的 nodeHash
+ */
+export async function acceptNostrAdvert(rendezvousKey, bytes, options = {}) {
+	const ingested = await ingestEncryptedAdvert(rendezvousKey, bytes)
+	if (!ingested) return null
+	const hash = ingested.verifiedNodeHash
+	const roomSecret = options.roomSecret
+	let firstSeen = true
+	if (roomSecret) {
+		const key = String(roomSecret || '')
+		firstSeen = !visibleByGroup.get(key)?.has(hash)
+		noteNostrGroupVisibleNode(key, hash)
+	}
+	else {
+		firstSeen = !visibleByHash.has(hash)
+		noteNostrVisibleNode(hash)
+	}
+	if (firstSeen)
+		nodeDebug('p2p:nostr peer visible', { peer: shortHash(hash), group: !!roomSecret })
+	noteAdvertPeerHints(hash, ingested.body, options.meta || {})
+	return hash
+}
+
+/** @returns {void} 测试用 */
+export function clearNostrVisibleNodes() {
+	visibleByHash.clear()
+	visibleByGroup.clear()
+}
 
 /**
  * 关掉 WebSocket：已连上则先 close，grace 内未 CLOSED 再 terminate。
- * 连接中直接 terminate（无握手可优雅收尾）。
  * @param {import('ws').WebSocket} ws 连接
  * @returns {void}
  */
@@ -39,7 +164,6 @@ function dropWebSocket(ws) {
 		if (ws.readyState !== WebSocket.CLOSED)
 			try { ws.terminate() } catch { /* ignore */ }
 	}, NOSTR_CLOSE_GRACE_MS)
-	// Grace is polite to the peer; must not pin the process after shutdown.
 	timer.unref()
 	ws.once('close', () => clearTimeout(timer))
 	try {
@@ -52,7 +176,6 @@ function dropWebSocket(ws) {
 }
 
 /**
- * 去重并清洗中继 URL 列表。
  * @param {string[] | undefined | null} urls 原始列表
  * @returns {string[]} 清洗后的列表
  */
@@ -64,7 +187,6 @@ function dedupeRelayUrls(urls) {
 }
 
 /**
- * 合并默认与用户配置的中继 URL（去重）。
  * @param {string[] | undefined | null} userRelayUrls 用户自定义中继列表
  * @returns {string[]} 合并后的中继 URL 列表
  */
@@ -74,7 +196,6 @@ export function mergeSignalingRelayUrls(userRelayUrls) {
 }
 
 /**
- * 签名 Nostr 事件。
  * @param {number} kind 事件 kind
  * @param {string[][]} tags 事件标签
  * @param {string} content 事件内容
@@ -91,7 +212,6 @@ async function signNostrEvent(kind, tags, content, secretKey) {
 }
 
 /**
- * 连接 Nostr 中继 WebSocket（`ws` 包，支持 terminate）。
  * @param {string} relayUrl 中继 URL
  * @param {number} [timeoutMs] 超时毫秒
  * @param {AbortSignal} [signal] 取消信号
@@ -138,13 +258,77 @@ function connectRelay(relayUrl, timeoutMs = NOSTR_CONNECT_TIMEOUT_MS, signal) {
 }
 
 /**
- * 向多个中继并行发布 Nostr 事件（任一成功即可）。
+ * @param {import('ws').WebSocket} ws 已连接 relay
+ * @param {string} relayUrl 中继 URL
+ * @param {object} event 待发布事件
+ * @param {AbortSignal} [signal] 取消信号
+ * @returns {Promise<boolean>} relay 是否接受 EVENT
+ */
+function publishEventOnRelay(ws, relayUrl, event, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new Error('nostr: aborted'))
+			return
+		}
+		let settled = false
+		/**
+		 * @param {boolean} ok relay 是否接受
+		 * @param {Error | null} [error] 失败原因
+		 * @returns {void}
+		 */
+		const finish = (ok, error = null) => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			signal?.removeEventListener('abort', onAbort)
+			ws.off('message', onMessage)
+			if (error) reject(error)
+			else resolve(ok)
+		}
+		/**
+		 * @returns {void}
+		 */
+		const onAbort = () => finish(false, new Error('nostr: aborted'))
+		/**
+		 * @param {import('ws').RawData} data relay 消息
+		 * @returns {void}
+		 */
+		const onMessage = data => {
+			let parsed
+			try { parsed = JSON.parse(String(data)) } catch { return }
+			if (parsed?.[0] !== 'OK' || parsed[1] !== event.id) return
+			const accepted = parsed[2] === true
+			if (!accepted)
+				nodeDebug('p2p:nostr publish rejected', {
+					url: relayUrl,
+					reason: String(parsed[3] || 'rejected'),
+				})
+			finish(accepted)
+		}
+		const timer = setTimeout(
+			() => finish(false, new Error(`nostr: publish ok timeout for ${relayUrl}`)),
+			NOSTR_PUBLISH_OK_TIMEOUT_MS,
+		)
+		timer.unref()
+		signal?.addEventListener('abort', onAbort, { once: true })
+		ws.on('message', onMessage)
+		try {
+			ws.send(JSON.stringify(['EVENT', event]))
+		}
+		catch (error) {
+			finish(false, error instanceof Error ? error : new Error(String(error)))
+		}
+	})
+}
+
+/**
  * @param {string[]} relayUrls 中继 URL 列表
  * @param {object} event 待发布事件
  * @param {AbortSignal} [signal] 取消信号
  * @returns {Promise<void>}
  */
 async function publishEvent(relayUrls, event, signal) {
+	if (!relayUrls.length) throw new Error('nostr: no relay')
 	let published = false
 	let lastError = null
 	await Promise.allSettled(relayUrls.map(async relayUrl => {
@@ -152,8 +336,8 @@ async function publishEvent(relayUrls, event, signal) {
 		const ws = await connectRelay(relayUrl, NOSTR_CONNECT_TIMEOUT_MS, signal)
 		try {
 			if (signal?.aborted) throw new Error('nostr: aborted')
-			ws.send(JSON.stringify(['EVENT', event]))
-			published = true
+			const ok = await publishEventOnRelay(ws, relayUrl, event, signal)
+			if (ok) published = true
 		}
 		catch (error) {
 			lastError = error
@@ -167,7 +351,6 @@ async function publishEvent(relayUrls, event, signal) {
 }
 
 /**
- * 并行渐进连接中继：立刻返回，连上后回调；abort 后 stop 接入并 drop 已开 socket。
  * @param {string[]} relayUrls 中继列表
  * @param {(ws: import('ws').WebSocket, relayUrl: string) => void} onOpen 连上回调
  * @param {AbortSignal} signal 取消信号
@@ -182,18 +365,24 @@ function connectRelaysProgressive(relayUrls, onOpen, signal, sockets) {
 				return
 			}
 			sockets.push(ws)
+			nodeDebug('p2p:nostr relay up', { url: relayUrl })
 			onOpen(ws, relayUrl)
-		}).catch(() => { /* 单路失败正常降级 */ })
+		}).catch(error => {
+			nodeDebug('p2p:nostr relay fail', {
+				url: relayUrl,
+				err: String(error?.message || error),
+			})
+		})
 }
 
 /**
- * 订阅指定 kind 的 Nostr 事件（渐进连中继，立即返回 cleanup）。
+ * 内部：按 rendezvous 键订阅 Nostr kind（topic 不导出）。
  * @param {string[]} relayUrls 中继 URL 列表
- * @param {{ kind: number, topic: string, tagX: string, onPayload: (bytes: Uint8Array, meta: { relayUrl: string, event: object }) => void }} options 订阅选项
+ * @param {{ kind: number, rendezvousKey: string, tagX: string, onPayload: (bytes: Uint8Array, meta: { relayUrl: string, event: object }) => void | Promise<void> }} options 订阅选项
  * @returns {() => void} 取消订阅
  */
 function subscribeNostrKind(relayUrls, options) {
-	const { kind, topic, tagX, onPayload } = options
+	const { kind, rendezvousKey, tagX, onPayload, addressable = false } = options
 	const abortController = new AbortController()
 	/** @type {import('ws').WebSocket[]} */
 	const sockets = []
@@ -206,10 +395,15 @@ function subscribeNostrKind(relayUrls, options) {
 			if (parsed?.[0] !== 'EVENT') return
 			const nostrEvent = parsed[2]
 			if (nostrEvent?.kind !== kind) return
-			try { onPayload(base64ToBytes(nostrEvent.content), { relayUrl, event: nostrEvent }) }
+			try {
+				const result = onPayload(base64ToBytes(nostrEvent.content), { relayUrl, event: nostrEvent })
+				if (result?.then) void result.catch(() => { })
+			}
 			catch { /* ignore */ }
 		})
-		ws.send(JSON.stringify(['REQ', subscriptionId, { kinds: [kind], '#t': [topic], '#x': [tagX] }]))
+		const filter = { kinds: [kind], '#t': [rendezvousKey], '#x': [tagX] }
+		if (addressable) filter['#d'] = [rendezvousKey]
+		ws.send(JSON.stringify(['REQ', subscriptionId, filter]))
 	}, abortController.signal, sockets)
 	return () => {
 		abortController.abort()
@@ -218,92 +412,307 @@ function subscribeNostrKind(relayUrls, options) {
 }
 
 /**
- * 创建 Nostr discovery provider。
- * subscribe/onSignal/advertise 首调用不阻塞等公网中继；连上后渐进生效。
- * `options.relayUrls` 为最终列表（调用方 `mergeSignalingRelayUrls`，或直接传入 `relayOverride`）。
- * 省略 / `undefined` → 默认公网中继；显式 `[]` 表示无中继（不再回填默认）。
- * @param {{ relayUrls?: string[] | null }} [options] 可选最终中继 URL 列表
- * @returns {import('./index.mjs').DiscoveryProvider} Nostr 发现提供者
+ * 创建 Nostr discovery provider（list+connect；topic 仅内部）。
+ * @param {{ relayUrls?: string[] | null, getRelayUrls?: () => string[] | null | undefined }} [options] 中继配置
+ * @returns {import('./index.mjs').DiscoveryProvider} Nostr discovery provider
  */
 export function createNostrDiscoveryProvider(options = {}) {
-	const relayUrls = dedupeRelayUrls(options.relayUrls || DEFAULT_RELAY_URLS)
+	/**
+	 * @returns {string[]} 去重后的中继 URL 列表
+	 */
+	const resolveRelayUrls = () => {
+		if (typeof options.getRelayUrls === 'function') {
+			const urls = options.getRelayUrls()
+			return dedupeRelayUrls(urls == null ? DEFAULT_RELAY_URLS : urls)
+		}
+		if (options.relayUrls === undefined || options.relayUrls === null)
+			return dedupeRelayUrls(DEFAULT_RELAY_URLS)
+		return dedupeRelayUrls(options.relayUrls)
+	}
 	const secretKey = randomBytes(32)
+	/** @type {(() => void) | null} */
+	let stopNetworkAdvertSub = null
+	/** @type {Map<string, () => void>} */
+	const groupSubs = new Map()
+	/** @type {Map<string, () => void>} */
+	const nodeAdvertSubs = new Map()
+	/** @type {Map<string, () => void>} */
+	const nodeSignalSubs = new Map()
+
+	/**
+	 * @returns {void}
+	 */
+	function ensureNetworkAdvertSubscription() {
+		if (stopNetworkAdvertSub) return
+		const rendezvousKey = networkRendezvousKey()
+		stopNetworkAdvertSub = subscribeNostrKind(resolveRelayUrls(), {
+			kind: NOSTR_ADVERT_KIND,
+			rendezvousKey,
+			tagX: 'advert',
+			addressable: true,
+			/**
+			 * @param {Uint8Array} bytes 加密 advert 载荷
+			 * @returns {Promise<void>}
+			 */
+			async onPayload(bytes) {
+				await acceptNostrAdvert(rendezvousKey, bytes)
+			},
+		})
+	}
+
+	/**
+	 * @param {string} roomSecret 房间密钥
+	 * @returns {void}
+	 */
+	function ensureGroupSubscription(roomSecret) {
+		const key = String(roomSecret || '')
+		if (!key || groupSubs.has(key)) return
+		const rendezvousKey = groupRendezvousKey(key)
+		groupSubs.set(key, subscribeNostrKind(resolveRelayUrls(), {
+			kind: NOSTR_ADVERT_KIND,
+			rendezvousKey,
+			tagX: 'advert',
+			addressable: true,
+			/**
+			 * @param {Uint8Array} bytes 加密 advert 载荷
+			 * @returns {Promise<void>}
+			 */
+			async onPayload(bytes) {
+				await acceptNostrAdvert(rendezvousKey, bytes, { roomSecret: key })
+			},
+		}))
+	}
+
 	return {
 		id: 'nostr',
 		priority: 100,
 		caps: { canDiscover: true, canSignal: true, canRelay: false },
 		/**
-		 * 周期性向中继发布 advert 事件（首发后台，不阻塞 ensureRuntime）。
-		 * @param {string} topic advert 主题
-		 * @param {Uint8Array} bytes advert 载荷
-		 * @returns {Promise<() => void>} 取消广播函数
+		 * @param {{ limit?: number, roomSecret?: string }} [options] 扫描选项
+		 * @returns {Promise<string[]>} 可见 nodeHash；带 roomSecret 时仅返回该群池
+		 */
+		async listVisibleNodeHashes(options = {}) {
+			const limit = Math.max(1, Number(options.limit) || 64)
+			if (options.roomSecret) {
+				ensureGroupSubscription(options.roomSecret)
+				return listNostrGroupVisibleNodeHashes(options.roomSecret).slice(0, limit)
+			}
+			ensureNetworkAdvertSubscription()
+			return listNostrVisibleNodeHashes().slice(0, limit)
+		},
+		/**
+		 * 挂上对该节点的内部 advert 订阅（建链由 registry dialer / ensureLinkToNode 完成）。
+		 * @param {string} nodeHash 目标
+		 * @returns {Promise<boolean>} 是否已准备
+		 */
+		async connectToNode(nodeHash) {
+			const hash = normalizeHex64(nodeHash)
+			if (!isHex64(hash)) return false
+			if (!nodeAdvertSubs.has(hash)) {
+				const rendezvousKey = nodeRendezvousKey(hash)
+				nodeAdvertSubs.set(hash, subscribeNostrKind(resolveRelayUrls(), {
+					kind: NOSTR_ADVERT_KIND,
+					rendezvousKey,
+					tagX: 'advert',
+					addressable: true,
+					/**
+					 * @param {Uint8Array} bytes 加密 advert 载荷
+					 * @returns {Promise<void>}
+					 */
+					async onPayload(bytes) {
+						await acceptNostrAdvert(rendezvousKey, bytes)
+					},
+				}))
+			}
+			return true
+		},
+		/**
+		 * @param {() => Promise<object | null>} getBeacon 本机 advert body 工厂
+		 * @returns {Promise<() => void>} 停止函数
 		 */
-		async advertise(topic, bytes) {
+		async startPresence(getBeacon) {
+			const rendezvousKey = networkRendezvousKey()
 			const abortController = new AbortController()
+			ensureNetworkAdvertSubscription()
 			/**
-			 * 向中继发布当前 advert。
 			 * @returns {Promise<void>}
 			 */
 			const publish = async () => {
 				if (abortController.signal.aborted) return
+				const beacon = await getBeacon?.()
+				if (!beacon?.nodeHash) return
+				const advertBody = beacon.advertBody || beacon.body || beacon
+				const bytes = encryptSignalPacket(rendezvousKey, { type: 'advert', body: advertBody })
 				const event = await signNostrEvent(
 					NOSTR_ADVERT_KIND,
-					[['t', topic], ['x', 'advert']],
+					[['t', rendezvousKey], ['x', 'advert'], ['d', rendezvousKey]],
 					bytesToBase64(bytes),
 					secretKey,
 				)
-				await publishEvent(relayUrls, event, abortController.signal)
+				await publishEvent(resolveRelayUrls(), event, abortController.signal)
+				nodeDebug('p2p:nostr presence published', { self: shortHash(beacon.nodeHash) })
 			}
-			void publish().catch(() => { })
-			const timer = setInterval(() => { void publish().catch(() => { }) }, 5 * 60_000)
+			void publish().catch(error => {
+				nodeDebug('p2p:nostr presence publish fail', { err: String(error?.message || error) })
+			})
+			const timer = setInterval(() => {
+				void publish().catch(error => {
+					nodeDebug('p2p:nostr presence publish fail', { err: String(error?.message || error) })
+				})
+			}, 5 * 60_000)
+			timer.unref?.()
 			return () => {
 				abortController.abort()
 				clearInterval(timer)
 			}
 		},
 		/**
-		 * 订阅中继上的 advert 事件（并行渐进连中继，立即返回 cleanup）。
-		 * @param {string} topic advert 主题
-		 * @param {Function} onAdvert advert 回调
-		 * @returns {Promise<() => void>} 取消订阅函数
-		 */
-		async subscribe(topic, onAdvert) {
-			return subscribeNostrKind(relayUrls, {
-				kind: NOSTR_ADVERT_KIND,
-				topic,
-				tagX: 'advert',
-				onPayload: onAdvert,
-			})
-		},
-		/**
-		 * 向中继发布 signal 事件（按需发送，仍等待至少一路成功）。
-		 * @param {string} topic 信令 topic
-		 * @param {string} to 目标节点标识
-		 * @param {Uint8Array} bytes 信令载荷
+		 * @param {string} toNodeHash 目标 nodeHash
+		 * @param {Uint8Array} bytes 加密信令
 		 * @returns {Promise<void>}
 		 */
-		async sendSignal(topic, to, bytes) {
+		async sendNodeSignal(toNodeHash, bytes) {
+			const hash = normalizeHex64(toNodeHash)
+			if (!isHex64(hash)) throw new Error('nostr: invalid nodeHash')
+			const rendezvousKey = nodeRendezvousKey(hash)
 			const event = await signNostrEvent(
 				NOSTR_SIGNAL_KIND,
-				[['t', topic], ['x', 'signal'], ['p', String(to || '')]],
+				[['t', rendezvousKey], ['x', 'signal'], ['p', hash]],
 				bytesToBase64(bytes),
 				secretKey,
 			)
-			await publishEvent(relayUrls, event)
+			await publishEvent(resolveRelayUrls(), event)
 		},
 		/**
-		 * 订阅中继上的 signal 事件（并行渐进连中继，立即返回 cleanup）。
-		 * @param {string} topic 信令 topic
-		 * @param {Function} onSignal 信令回调
-		 * @returns {Promise<() => void>} 取消订阅函数
+		 * @param {string} localNodeHash 本机 nodeHash
+		 * @param {(bytes: Uint8Array) => void} onSignal 信令回调
+		 * @returns {Promise<() => void>} 取消函数
 		 */
-		async onSignal(topic, onSignal) {
-			return subscribeNostrKind(relayUrls, {
+		async listenNodeSignals(localNodeHash, onSignal) {
+			const hash = normalizeHex64(localNodeHash)
+			if (!isHex64(hash)) throw new Error('nostr: invalid nodeHash')
+			const rendezvousKey = nodeRendezvousKey(hash)
+			const existing = nodeSignalSubs.get(hash)
+			if (existing) existing()
+			nodeDebug('p2p:nostr signal listen', { self: shortHash(hash), relays: resolveRelayUrls().length })
+			const stop = subscribeNostrKind(resolveRelayUrls(), {
 				kind: NOSTR_SIGNAL_KIND,
-				topic,
+				rendezvousKey,
 				tagX: 'signal',
 				onPayload: onSignal,
 			})
+			nodeSignalSubs.set(hash, stop)
+			return () => {
+				stop()
+				nodeSignalSubs.delete(hash)
+			}
+		},
+		/**
+		 * @param {string} nodeHash 目标 nodeHash
+		 * @param {(bytes: Uint8Array, meta: object) => void} onAdvert advert 回调
+		 * @returns {Promise<() => void>} 取消函数
+		 */
+		async watchNodeAdvert(nodeHash, onAdvert) {
+			const hash = normalizeHex64(nodeHash)
+			if (!isHex64(hash)) throw new Error('nostr: invalid nodeHash')
+			const rendezvousKey = nodeRendezvousKey(hash)
+			const stop = subscribeNostrKind(resolveRelayUrls(), {
+				kind: NOSTR_ADVERT_KIND,
+				rendezvousKey,
+				tagX: 'advert',
+				addressable: true,
+				/**
+				 * @param {Uint8Array} bytes 加密 advert 载荷
+				 * @param {object} meta relay 元数据
+				 * @returns {void}
+				 */
+				onPayload: (bytes, meta) => onAdvert(bytes, meta),
+			})
+			return stop
+		},
+		/**
+		 * @param {string} roomSecret 房间密钥
+		 * @param {() => Promise<object | null>} getBeacon advert 工厂
+		 * @returns {Promise<() => void>} 停止群 presence 广播
+		 */
+		async startGroupPresence(roomSecret, getBeacon) {
+			const key = String(roomSecret || '')
+			const rendezvousKey = groupRendezvousKey(key)
+			const abortController = new AbortController()
+			ensureGroupSubscription(key)
+			/**
+			 * @returns {Promise<void>}
+			 */
+			const publish = async () => {
+				if (abortController.signal.aborted) return
+				const beacon = await getBeacon?.()
+				if (!beacon?.nodeHash) return
+				const advertBody = beacon.advertBody || beacon.body || beacon
+				const bytes = encryptSignalPacket(rendezvousKey, { type: 'advert', body: advertBody })
+				const event = await signNostrEvent(
+					NOSTR_ADVERT_KIND,
+					[['t', rendezvousKey], ['x', 'advert'], ['d', rendezvousKey]],
+					bytesToBase64(bytes),
+					secretKey,
+				)
+				await publishEvent(resolveRelayUrls(), event, abortController.signal)
+			}
+			void publish().catch(() => { })
+			const timer = setInterval(() => { void publish().catch(() => { }) }, 5 * 60_000)
+			timer.unref?.()
+			return () => {
+				abortController.abort()
+				clearInterval(timer)
+			}
+		},
+		/**
+		 * @param {string} roomSecret 房间密钥
+		 * @param {(bytes: Uint8Array, meta: object) => void} onAdvert 回调
+		 * @returns {Promise<() => void>} 取消群 advert 监听
+		 */
+		async watchGroupAdverts(roomSecret, onAdvert) {
+			const key = String(roomSecret || '')
+			const rendezvousKey = groupRendezvousKey(key)
+			ensureGroupSubscription(key)
+			return subscribeNostrKind(resolveRelayUrls(), {
+				kind: NOSTR_ADVERT_KIND,
+				rendezvousKey,
+				tagX: 'advert',
+				addressable: true,
+				/**
+				 * @param {Uint8Array} bytes 加密 advert 载荷
+				 * @param {object} meta relay 元数据
+				 * @returns {void}
+				 */
+				onPayload: (bytes, meta) => onAdvert(bytes, meta),
+			})
+		},
+		/**
+		 * 供 advert 解析路径写入可见 hash。
+		 * @param {string} nodeHash 节点 hash
+		 * @param {{ roomSecret?: string }} [options] 带 roomSecret 时写入群池
+		 * @returns {void}
+		 */
+		noteVisibleNode(nodeHash, options = {}) {
+			if (options.roomSecret) noteNostrGroupVisibleNode(options.roomSecret, nodeHash)
+			else noteNostrVisibleNode(nodeHash)
+		},
+		/**
+		 * 停止全部内部订阅（reload / unregister 时调用）。
+		 * @returns {void}
+		 */
+		dispose() {
+			stopNetworkAdvertSub?.()
+			stopNetworkAdvertSub = null
+			for (const stop of groupSubs.values())
+				try { stop() } catch { /* ignore */ }
+			groupSubs.clear()
+			for (const stop of nodeAdvertSubs.values())
+				try { stop() } catch { /* ignore */ }
+			nodeAdvertSubs.clear()
+			for (const stop of nodeSignalSubs.values())
+				try { stop() } catch { /* ignore */ }
+			nodeSignalSubs.clear()
 		},
 	}
 }