@steve02081504/fount-p2p 0.0.9 → 0.0.11

package/transport/offer_answer.mjs

@@ -0,0 +1,190 @@
+import { randomBytes } from 'node:crypto'
+
+import { normalizeHex64 } from '../core/hexIds.mjs'
+import { sendSignal } from '../discovery/index.mjs'
+import { listLinkProviders } from '../link/providers/index.mjs'
+
+import { decryptSignalPacket, encryptSignalPacket, nodeRendezvousTopic } from './signal_crypto.mjs'
+
+/**
+ * 创建带 backlog 的缓冲信令会话。
+ * @param {(message: unknown) => Promise<void>} sendRemote 远端发送回调
+ * @returns {{ send: (message: unknown) => Promise<void>, onRemote: (handler: (message: unknown) => void) => () => void, deliver: (message: unknown) => void, clear: () => void }} 信令会话
+ */
+export function createBufferedSignalSession(sendRemote) {
+	/** @type {Set<(message: unknown) => void>} */
+	const handlers = new Set()
+	/** @type {unknown[]} */
+	const backlog = []
+	return {
+		/**
+		 * 发送信令消息到远端。
+		 * @param {unknown} message 信令消息
+		 * @returns {Promise<void>}
+		 */
+		async send(message) {
+			await sendRemote(message)
+		},
+		/**
+		 * 注册远端信令 handler（含 backlog 回放）。
+		 * @param {(message: unknown) => void} handler 入站回调
+		 * @returns {() => void} 取消订阅函数
+		 */
+		onRemote(handler) {
+			handlers.add(handler)
+			for (const pending of backlog.splice(0))
+				handler(pending)
+			return () => handlers.delete(handler)
+		},
+		/**
+		 * 投递信令消息；无 handler 时入 backlog。
+		 * @param {unknown} message 信令消息
+		 * @returns {void}
+		 */
+		deliver(message) {
+			if (!handlers.size) {
+				backlog.push(message)
+				return
+			}
+			for (const handler of handlers)
+				handler(message)
+		},
+		/**
+		 * 清空 backlog 与 handler。
+		 * @returns {void}
+		 */
+		clear() {
+			backlog.length = 0
+			handlers.clear()
+		},
+	}
+}
+
+/**
+ * 判断信令 body 是否为发起方 offer（据此决定入站是否新建应答 PC）。
+ * @param {unknown} body 信令 body
+ * @returns {boolean} 是 offer 则 true
+ */
+function isOfferSignalBody(body) {
+	return !!body && typeof body === 'object'
+		&& body.type === 'description'
+		&& body.description?.type === 'offer'
+}
+
+/**
+ * 找已注册的 offer/answer provider（按 level 降序的第一个）。
+ * @returns {import('../link/providers/index.mjs').LinkProvider | null} 命中的 provider；无则 null
+ */
+export function findOfferAnswerProvider() {
+	return listLinkProviders().find(provider => provider.caps?.needsOfferAnswer) ?? null
+}
+
+/**
+ * Offer/answer glare 拨号控制器（WebRTC 等 needsOfferAnswer provider）。
+ * @param {object} deps 依赖注入
+ * @param {{ nodeHash: string, nodePubKey: string, secretKey: Uint8Array }} deps.localIdentity 本地身份
+ * @param {RTCConfiguration['iceServers']} deps.iceServers ICE 服务器列表
+ * @param {string} deps.selfTopic 本机 rendezvous topic
+ * @param {Map<string, ReturnType<typeof createBufferedSignalSession>>} deps.signalSessions 按 connId 索引的信令会话
+ * @param {(remoteNodeHash: string, link: object) => Promise<void>} deps.registerResolvedLink 注册规范链
+ * @param {() => Promise<void>} deps.trimToBudget 超预算驱逐
+ * @param {(remoteNodeHash: string) => object | null | undefined} deps.getCanonicalLink 读取当前规范链
+ * @returns {{ handleIncomingSignal: (bytes: Uint8Array) => Promise<void>, dialOfferAnswer: (provider: import('../link/providers/index.mjs').LinkProvider, remoteNodeHash: string) => Promise<object | null> }} 入站信令与主动拨号
+ */
+export function createOfferAnswerDial(deps) {
+	const {
+		localIdentity,
+		iceServers,
+		selfTopic,
+		signalSessions,
+		registerResolvedLink,
+		trimToBudget,
+		getCanonicalLink,
+	} = deps
+
+	/**
+	 * 为单条 PC 创建按 connId 标记的信令会话。
+	 * @param {string} remoteNodeHash 远端节点 64 hex
+	 * @param {string} connId 连接标识
+	 * @returns {ReturnType<typeof createBufferedSignalSession>} 信令会话
+	 */
+	function createConnSession(remoteNodeHash, connId) {
+		const normalized = normalizeHex64(remoteNodeHash)
+		const topic = nodeRendezvousTopic(normalized)
+		return createBufferedSignalSession(async message => {
+			await sendSignal(topic, normalized, encryptSignalPacket(topic, {
+				type: 'signal',
+				from: localIdentity.nodeHash,
+				connId,
+				body: message,
+			}))
+		})
+	}
+
+	/**
+	 * Offer/answer provider：为一条 connId 会话建链并走 glare 择一。
+	 * @param {{ provider: import('../link/providers/index.mjs').LinkProvider, remoteNodeHash: string, connId: string, session: ReturnType<typeof createBufferedSignalSession>, initiator: boolean }} options 建链参数
+	 * @returns {Promise<object | null>} 当前规范链；失败 null
+	 */
+	async function buildConnLink({ provider, remoteNodeHash, connId, session, initiator }) {
+		try {
+			if (initiator) await trimToBudget()
+			const link = await (initiator ? provider.dial : provider.accept)({
+				nodeHash: remoteNodeHash,
+				signal: session,
+				iceServers,
+				localIdentity,
+			})
+			if (!link) {
+				signalSessions.delete(connId)
+				return null
+			}
+			link.onDown(() => signalSessions.delete(connId))
+			await link.ready
+			await registerResolvedLink(remoteNodeHash, link)
+			return getCanonicalLink(remoteNodeHash) ?? null
+		}
+		catch {
+			signalSessions.delete(connId)
+			return null
+		}
+	}
+
+	/**
+	 * 处理入站加密信令并可能发起被动建链。
+	 * @param {Uint8Array} bytes 加密信令字节
+	 * @returns {Promise<void>}
+	 */
+	async function handleIncomingSignal(bytes) {
+		const packet = decryptSignalPacket(selfTopic, bytes)
+		if (!packet || packet.type !== 'signal') return
+		const remoteNodeHash = normalizeHex64(packet.from)
+		const connId = String(packet.connId || '')
+		if (!remoteNodeHash || remoteNodeHash === localIdentity.nodeHash || !connId) return
+		let session = signalSessions.get(connId)
+		if (!session) {
+			if (!isOfferSignalBody(packet.body)) return
+			const provider = findOfferAnswerProvider()
+			if (!provider) return
+			session = createConnSession(remoteNodeHash, connId)
+			signalSessions.set(connId, session)
+			void buildConnLink({ provider, remoteNodeHash, connId, session, initiator: false })
+		}
+		session.deliver(packet.body)
+	}
+
+	/**
+	 * 经 offer/answer provider 拨号（discovery signal + glare）。
+	 * @param {import('../link/providers/index.mjs').LinkProvider} provider 链路提供者
+	 * @param {string} remoteNodeHash 远端 64 hex
+	 * @returns {Promise<object | null>} 当前规范链；失败 null
+	 */
+	async function dialOfferAnswer(provider, remoteNodeHash) {
+		const connId = randomBytes(16).toString('hex')
+		const session = createConnSession(remoteNodeHash, connId)
+		signalSessions.set(connId, session)
+		return await buildConnLink({ provider, remoteNodeHash, connId, session, initiator: true })
+	}
+
+	return { handleIncomingSignal, dialOfferAnswer }
+}

package/transport/runtime_bootstrap.mjs

@@ -0,0 +1,363 @@
+import { normalizeTcpPort } from '../core/tcp_port.mjs'
+import { advertiseTopic, listenSignals, listDiscoveryProviders, registerDiscoveryProvider } from '../discovery/index.mjs'
+import { createMdnsDiscoveryProvider } from '../discovery/mdns.mjs'
+import { mergeSignalingRelayUrls, createNostrDiscoveryProvider } from '../discovery/nostr.mjs'
+import { buildSignedAdvert } from '../link/handshake.mjs'
+import { createBleGattLinkProvider } from '../link/providers/ble_gatt.mjs'
+import {
+	listLinkProviders,
+	registerLinkProvider,
+	unregisterLinkProvider,
+} from '../link/providers/index.mjs'
+import { createLanTcpLinkProvider } from '../link/providers/lan_tcp.mjs'
+import { createWebRtcLinkProvider } from '../link/providers/webrtc.mjs'
+import { getNodeTransportSettings } from '../node/identity.mjs'
+import { getSignalingRuntimeConfig } from '../node/instance.mjs'
+
+import { encryptSignalPacket } from './signal_crypto.mjs'
+
+/**
+ * Provider 是否会在 isAvailable() 调用时触发 native/异步探测（不得在 ensureRuntime 快路径调用）。
+ * @param {import('../link/providers/index.mjs').LinkProvider} provider 链路提供者
+ * @returns {boolean} `caps.probe === 'native'` 时 true
+ */
+export function providerHasNativeProbe(provider) {
+	return provider.caps?.probe === 'native'
+}
+
+/**
+ * 收集快路径应 listen 的 provider（仅 owned lan_tcp + 同步可用者）。
+ * 切勿调用 caps.probe==='native' 的 isAvailable（会触发 ble/webrtc 探测）。
+ * @param {import('../link/providers/index.mjs').LinkProvider | null} ownedLanTcp 本 registry 持有的 lan_tcp
+ * @returns {import('../link/providers/index.mjs').LinkProvider[]} 可在 ensureRuntime 快路径 listen 的 provider
+ */
+export function collectFastListenProviders(ownedLanTcp) {
+	/** @type {import('../link/providers/index.mjs').LinkProvider[]} */
+	const listenProviders = []
+	if (ownedLanTcp) listenProviders.push(ownedLanTcp)
+	for (const provider of listLinkProviders()) {
+		const id = String(provider.id)
+		if (id.startsWith('lan_tcp') || id.startsWith('ble_gatt')) continue
+		if (typeof provider.ensureListening !== 'function') continue
+		if (providerHasNativeProbe(provider)) continue
+		if (typeof provider.isAvailable === 'function') {
+			try {
+				const available = provider.isAvailable()
+				// 未标 probe:native 却返回 thenable：跳过，勿 await。
+				if (available && typeof available.then === 'function') continue
+				if (!available) continue
+			}
+			catch { continue }
+		}
+		listenProviders.push(provider)
+	}
+	return listenProviders
+}
+
+/**
+ * Discovery + link listen 暖机（ensureRuntime 立即返回；listen/公网/BT 后台渐进）。
+ * @param {object} deps 依赖注入
+ * @param {{ nodeHash: string, nodePubKey: string, secretKey: Uint8Array }} deps.localIdentity 本地身份
+ * @param {string} deps.selfTopic 本机 rendezvous topic
+ * @param {boolean} deps.autoRegisterDiscoveryProviders 是否自动注册 discovery provider
+ * @param {boolean} deps.autoRegisterLinkProviders 是否自动注册内置 link provider
+ * @param {(link: object) => void} deps.onInboundLink 入站链路回调
+ * @param {(bytes: Uint8Array) => Promise<void>} deps.handleIncomingSignal 入站加密信令处理
+ * @returns {{
+ *   ensureRuntime: () => Promise<void>,
+ *   whenListening: () => Promise<void>,
+ *   whenSignalListening: () => Promise<void>,
+ *   buildLocalAdvert: (topic: string) => Promise<object>,
+ *   lanTcpPort: () => number | null,
+ *   ownedLanTcp: () => object | null,
+ *   ownedBleGatt: () => object | null,
+ *   shutdown: () => Promise<void>,
+ * }} 运行时暖机句柄
+ */
+export function createRuntimeBootstrap(deps) {
+	const {
+		localIdentity,
+		selfTopic,
+		autoRegisterDiscoveryProviders,
+		autoRegisterLinkProviders,
+		onInboundLink,
+		handleIncomingSignal,
+	} = deps
+
+	let runtimeStarted = false
+	/** @type {Promise<void> | null} */
+	let runtimeStart = null
+	/** @type {Promise<void> | null} */
+	let lanListenReady = null
+	/** @type {Promise<void> | null} selfTopic listenSignals 已挂上（offer/answer dial 前必须等） */
+	let signalListenReady = null
+	/** @type {Promise<void> | null} */
+	let runtimeWarm = null
+	/** @type {Promise<void> | null} */
+	let bluetoothWarm = null
+	/** @type {(() => void) | null} */
+	let stopAdvert = null
+	/** @type {(() => void) | null} */
+	let stopSignalListener = null
+	/** @type {Array<() => void>} */
+	const stopLinkListeners = []
+	/** @type {ReturnType<typeof createLanTcpLinkProvider> | null} */
+	let ownedLanTcp = null
+	/** @type {ReturnType<typeof createBleGattLinkProvider> | null} */
+	let ownedBleGatt = null
+	/** @type {number} shutdown 时递增，后台任务检查后退出 */
+	let generation = 0
+
+	/**
+	 * 暖机是否仍在运行（shutdown 后为 false）。
+	 * @returns {boolean} runtime 已启动且未 shutdown 时 true
+	 */
+	function isLive() {
+		return runtimeStarted
+	}
+
+	/**
+	 * 自动注册默认 LinkProvider（lan_tcp / webrtc / ble_gatt）。
+	 * @returns {Promise<void>}
+	 */
+	async function ensureLinkProviders() {
+		if (!autoRegisterLinkProviders) return
+		if (!ownedLanTcp) {
+			ownedLanTcp = createLanTcpLinkProvider()
+			registerLinkProvider(ownedLanTcp)
+		}
+		if (!ownedBleGatt) {
+			ownedBleGatt = createBleGattLinkProvider()
+			registerLinkProvider(ownedBleGatt)
+		}
+		const ids = new Set(listLinkProviders().map(provider => provider.id))
+		if (!ids.has('webrtc'))
+			registerLinkProvider(createWebRtcLinkProvider())
+	}
+
+	/**
+	 * 本 registry 的 LAN TCP 监听端口。
+	 * @returns {number | null} listen 端口；未 listen 为 null
+	 */
+	function lanTcpPort() {
+		const endpoint = typeof ownedLanTcp?.localEndpoint === 'function' ? ownedLanTcp.localEndpoint() : null
+		return normalizeTcpPort(endpoint?.port)
+	}
+
+	/**
+	 * 等待本地 lan_tcp listen 落定。shell / startNode 不应调用。
+	 * @returns {Promise<void>}
+	 */
+	async function whenListening() {
+		if (lanListenReady) await lanListenReady.catch(() => { })
+	}
+
+	/**
+	 * 等待 selfTopic 信令监听挂上（needsOfferAnswer dial 前调用）。
+	 * @returns {Promise<void>}
+	 */
+	async function whenSignalListening() {
+		if (signalListenReady) await signalListenReady.catch(() => { })
+	}
+
+	/**
+	 * 构造带本机身份与（若已 listen）tcpPort 的签名 advert。
+	 * @param {string} topic 广播主题
+	 * @returns {Promise<object>} 签名 advert
+	 */
+	async function buildLocalAdvert(topic) {
+		await whenListening()
+		const tcpPort = lanTcpPort()
+		return await buildSignedAdvert(topic, Date.now(), {
+			...localIdentity,
+			...tcpPort != null ? { tcpPort } : {},
+		})
+	}
+
+	/**
+	 * 对单个 link provider 调用 ensureListening，收集 stop。
+	 * @param {import('../link/providers/index.mjs').LinkProvider} provider 链路提供者
+	 * @returns {Promise<void>}
+	 */
+	async function startProviderListening(provider) {
+		if (typeof provider.ensureListening !== 'function') return
+		try {
+			const stop = await provider.ensureListening({
+				localIdentity,
+				onInbound: onInboundLink,
+			})
+			if (typeof stop === 'function') stopLinkListeners.push(stop)
+		}
+		catch { /* provider listen unavailable — normal degrade */ }
+	}
+
+	/**
+	 * 把晚注册 provider 的 stop 链到现有 cleanup。
+	 * @param {'signal' | 'advert'} kind 停止钩子类型
+	 * @param {() => void} stop 新 provider 的取消函数
+	 * @returns {void}
+	 */
+	function chainStop(kind, stop) {
+		if (kind === 'signal') {
+			const prev = stopSignalListener
+			stopSignalListener = () => {
+				try { stop() } catch { /* ignore */ }
+				prev?.()
+			}
+			return
+		}
+		const prev = stopAdvert
+		stopAdvert = () => {
+			try { stop() } catch { /* ignore */ }
+			prev?.()
+		}
+	}
+
+	/**
+	 * 后台探测 BT discovery / ble_gatt listen。
+	 * @param {number} gen 启动世代
+	 * @returns {Promise<void>}
+	 */
+	async function warmBluetoothTask(gen) {
+		if (autoRegisterDiscoveryProviders) {
+			const providerIds = new Set(listDiscoveryProviders().map(provider => provider.id))
+			if (!providerIds.has('bt')) {
+				const bt = await import('../discovery/bt/index.mjs').catch(() => null)
+				if (generation !== gen || !isLive()) return
+				if (await bt?.canUseBluetoothDiscovery?.()) {
+					if (generation !== gen || !isLive()) return
+					const provider = bt.createBluetoothDiscoveryProvider()
+					registerDiscoveryProvider(provider)
+					if (generation !== gen || !isLive()) return
+					if (provider.caps?.canSignal && typeof provider.onSignal === 'function')
+						try {
+							const stop = await provider.onSignal(selfTopic, bytes => {
+								void handleIncomingSignal(bytes).catch(() => { })
+							})
+							if (typeof stop === 'function' && generation === gen && isLive())
+								chainStop('signal', stop)
+						}
+						catch { /* ignore */ }
+					if (provider.caps?.canDiscover && typeof provider.advertise === 'function')
+						try {
+							const stop = await provider.advertise(selfTopic, encryptSignalPacket(selfTopic, {
+								type: 'advert',
+								body: await buildLocalAdvert(selfTopic),
+							}))
+							if (typeof stop === 'function' && generation === gen && isLive())
+								chainStop('advert', stop)
+						}
+						catch { /* ignore */ }
+				}
+			}
+		}
+		if (generation !== gen || !isLive()) return
+		if (ownedBleGatt && await Promise.resolve(ownedBleGatt.isAvailable())) {
+			if (generation !== gen || !isLive()) return
+			await startProviderListening(ownedBleGatt)
+		}
+	}
+
+	/**
+	 * 后台：lan_tcp listen → selfTopic listenSignals/advertise。
+	 * @param {number} gen 启动世代（shutdown 时递增以作废后台任务）
+	 * @returns {Promise<void>}
+	 */
+	function warmListenAndDiscovery(gen) {
+		const listenProviders = collectFastListenProviders(ownedLanTcp)
+		// 同步挂上 Promise，避免 ensureRuntime 返回后 buildLocalAdvert 看不到 lanListenReady。
+		lanListenReady = Promise.all(listenProviders.map(provider => startProviderListening(provider))).then(() => { })
+		signalListenReady = (async () => {
+			await lanListenReady.catch(() => { })
+			if (generation !== gen || !isLive()) return
+			if (!listDiscoveryProviders().length) return
+			stopSignalListener = await listenSignals(selfTopic, bytes => {
+				void handleIncomingSignal(bytes).catch(() => { })
+			})
+		})()
+		return (async () => {
+			await signalListenReady.catch(() => { })
+			if (generation !== gen || !isLive()) return
+			if (!listDiscoveryProviders().length) return
+			stopAdvert = await advertiseTopic(selfTopic, encryptSignalPacket(selfTopic, {
+				type: 'advert',
+				body: await buildLocalAdvert(selfTopic),
+			}))
+		})()
+	}
+
+	/**
+	 * 仅注册 provider 并调度后台暖机后立即返回。
+	 * @returns {Promise<void>}
+	 */
+	async function ensureRuntime() {
+		if (runtimeStarted) return
+		if (runtimeStart) return await runtimeStart
+		runtimeStart = (async () => {
+			runtimeStarted = true
+			const gen = generation
+			await ensureLinkProviders()
+			if (autoRegisterDiscoveryProviders) {
+				const providerIds = new Set(listDiscoveryProviders().map(provider => provider.id))
+				if (!providerIds.has('mdns'))
+					registerDiscoveryProvider(createMdnsDiscoveryProvider())
+				if (!providerIds.has('nostr'))
+					registerDiscoveryProvider(createNostrDiscoveryProvider({
+						relayUrls: getSignalingRuntimeConfig().relayOverride
+							?? mergeSignalingRelayUrls(getNodeTransportSettings().relayUrls),
+					}))
+			}
+			bluetoothWarm = warmBluetoothTask(gen).catch(() => { })
+			runtimeWarm = warmListenAndDiscovery(gen)
+			void runtimeWarm.catch(() => { })
+		})()
+		try {
+			await runtimeStart
+		}
+		finally {
+			runtimeStart = null
+		}
+	}
+
+	/**
+	 * 停止暖机与 owned providers（链路表由 registry 自行清理）。
+	 * 不 await bluetoothWarm：noble/poweredOn 可能挂死；generation 已作废其后副作用。
+	 * @returns {Promise<void>}
+	 */
+	async function shutdown() {
+		runtimeStarted = false
+		generation++
+		await runtimeWarm?.catch(() => { })
+		stopAdvert?.()
+		stopSignalListener?.()
+		stopAdvert = null
+		stopSignalListener = null
+		for (const stop of stopLinkListeners.splice(0))
+			try { stop() } catch { /* ignore */ }
+		if (ownedLanTcp) {
+			unregisterLinkProvider(ownedLanTcp.id)
+			ownedLanTcp = null
+		}
+		if (ownedBleGatt) {
+			unregisterLinkProvider(ownedBleGatt.id)
+			ownedBleGatt = null
+		}
+		lanListenReady = null
+		signalListenReady = null
+		runtimeWarm = null
+		bluetoothWarm = null
+	}
+
+	return {
+		ensureRuntime,
+		whenListening,
+		whenSignalListening,
+		buildLocalAdvert,
+		lanTcpPort,
+		/** @returns {ReturnType<typeof createLanTcpLinkProvider> | null} 本 registry 持有的 lan_tcp */
+		ownedLanTcp: () => ownedLanTcp,
+		/** @returns {ReturnType<typeof createBleGattLinkProvider> | null} 本 registry 持有的 ble_gatt */
+		ownedBleGatt: () => ownedBleGatt,
+		shutdown,
+	}
+}

package/transport/signal_crypto.mjs

@@ -0,0 +1,82 @@
+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'
+
+const SIGNAL_DOMAIN = 'fount-signal'
+const NODE_TOPIC_DOMAIN = 'fount-rdv-node:'
+const GROUP_TOPIC_DOMAIN = 'fount-rdv-group:'
+
+/**
+ * 由 nodeHash 派生节点 rendezvous topic。
+ * @param {string} nodeHash 节点 64 hex
+ * @returns {string} rendezvous topic 哈希
+ */
+export function nodeRendezvousTopic(nodeHash) {
+	return sha256Hex(`${NODE_TOPIC_DOMAIN}${normalizeHex64(nodeHash)}`)
+}
+
+/**
+ * 由房间密钥派生群组 rendezvous topic。
+ * @param {string} roomSecret 房间密钥
+ * @returns {string} rendezvous topic 哈希
+ */
+export function groupRendezvousTopic(roomSecret) {
+	return sha256Hex(`${GROUP_TOPIC_DOMAIN}${String(roomSecret || '')}`)
+}
+
+/**
+ * 由 topic 派生信令 AES 密钥。
+ * @param {string} topic rendezvous 主题
+ * @returns {Buffer} AES-256 密钥
+ */
+function signalKeyForTopic(topic) {
+	return createHash('sha256').update(`${SIGNAL_DOMAIN}:${String(topic)}`).digest()
+}
+
+/**
+ * 加密信令包为 AES-GCM 字节序列。
+ * @param {string} topic rendezvous 主题
+ * @param {unknown} packet 待加密 JSON 对象
+ * @returns {Uint8Array} 加密后的字节
+ */
+export function encryptSignalPacket(topic, packet) {
+	const iv = randomBytes(12)
+	const cipher = createCipheriv('aes-256-gcm', signalKeyForTopic(topic), iv)
+	const ciphertext = Buffer.concat([
+		cipher.update(Buffer.from(JSON.stringify(packet), 'utf8')),
+		cipher.final(),
+	])
+	return Buffer.from(JSON.stringify({
+		iv: iv.toString('base64'),
+		authTag: cipher.getAuthTag().toString('base64'),
+		ciphertext: ciphertext.toString('base64'),
+	}))
+}
+
+/**
+ * 解密信令包；失败时返回 null。
+ * @param {string} topic rendezvous 主题
+ * @param {Uint8Array} bytes 加密字节
+ * @returns {object | null} 解密后的 JSON 对象
+ */
+export function decryptSignalPacket(topic, bytes) {
+	try {
+		const payload = JSON.parse(Buffer.from(bytes).toString('utf8'))
+		const decipher = createDecipheriv(
+			'aes-256-gcm',
+			signalKeyForTopic(topic),
+			Buffer.from(payload.iv, 'base64'),
+		)
+		decipher.setAuthTag(Buffer.from(payload.authTag, 'base64'))
+		const plain = Buffer.concat([
+			decipher.update(Buffer.from(payload.ciphertext, 'base64')),
+			decipher.final(),
+		])
+		return JSON.parse(plain.toString('utf8'))
+	}
+	catch {
+		return null
+	}
+}