@steve02081504/fount-p2p 0.0.0

package/timeline/prune.mjs

@@ -0,0 +1,39 @@
+import { mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+import { topologicalCanonicalOrder } from '../dag/index.mjs'
+import { readJsonl, writeJsonlSynced } from '../dag/storage.mjs'
+import { invalidateTopologicalOrderMemo } from '../federation/topo_order_memo.mjs'
+import { descendantClosureFromTip } from '../governance/branch.mjs'
+
+/**
+ * 将 events.jsonl 裁剪为 checkpoint 起后代闭包（连通子图，非拓扑下标切片）。
+ * @param {string} eventsFilePath events.jsonl 路径
+ * @param {object | null} checkpoint 含 checkpoint_event_id 的快照
+ * @param {(row: object) => object} [sanitize] 行规范化
+ * @returns {Promise<{ pruned: boolean, kept: number, dropped: number }>} 裁剪统计
+ */
+export async function pruneEventsJsonlAfterCheckpoint(eventsFilePath, checkpoint, sanitize = row => row) {
+	const tipId = checkpoint?.checkpoint_event_id
+	if (!tipId) return { pruned: false, kept: 0, dropped: 0 }
+	const events = await readJsonl(eventsFilePath, { sanitize })
+	if (!events.length) return { pruned: false, kept: 0, dropped: 0 }
+	const byId = new Map(events.map(dagEvent => [dagEvent.id, dagEvent]))
+	if (!byId.has(tipId)) return { pruned: false, kept: events.length, dropped: 0 }
+
+	const keepIds = descendantClosureFromTip(tipId, byId)
+	const order = topologicalCanonicalOrder(events.map(dagEvent => ({
+		id: dagEvent.id,
+		prev_event_ids: dagEvent.prev_event_ids,
+		hlc: dagEvent.hlc,
+		node_id: dagEvent.node_id,
+		sender: dagEvent.sender,
+	})))
+	const kept = order.map(id => byId.get(id)).filter(ev => ev && keepIds.has(ev.id))
+	const dropped = events.length - kept.length
+	if (dropped <= 0) return { pruned: false, kept: kept.length, dropped: 0 }
+	await mkdir(dirname(eventsFilePath), { recursive: true })
+	await writeJsonlSynced(eventsFilePath, kept)
+	invalidateTopologicalOrderMemo(eventsFilePath)
+	return { pruned: true, kept: kept.length, dropped }
+}

package/timeline/retention.mjs

@@ -0,0 +1,54 @@
+import { mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+import { topologicalCanonicalOrder } from '../dag/index.mjs'
+import { readJsonl, writeJsonlSynced } from '../dag/storage.mjs'
+import { invalidateTopologicalOrderMemo } from '../federation/topo_order_memo.mjs'
+import { computeDagTipIdsFromEvents, selectConsensusBranchTip } from '../governance/branch.mjs'
+import { computeRetentionKeepIds } from '../node/retention_policy.mjs'
+
+/**
+ * @param {string} eventsFilePath events.jsonl 路径
+ * @param {object | null} checkpointHint 检查点提示
+ * @param {{ maxDepth: number, maxMs: number, anchorTypes: Set<string> }} policy 保留策略
+ * @param {(row: object) => object} sanitize 行规范化
+ * @returns {Promise<{ pruned: boolean, kept: number, dropped: number }>} 裁剪统计
+ */
+export async function enforceTimelineEventRetention(
+	eventsFilePath,
+	checkpointHint,
+	policy,
+	sanitize = row => row,
+) {
+	const events = await readJsonl(eventsFilePath, { sanitize })
+	if (!events.length) return { pruned: false, kept: 0, dropped: 0 }
+	const maxDepth = Math.max(256, Number(policy.maxDepth) || 200_000)
+	const maxMs = Math.max(3_600_000, Number(policy.maxMs) || 365 * 24 * 3600 * 1000)
+	const cutoffWall = Date.now() - maxMs
+	const byId = new Map(events.map(e => [e.id, e]))
+	const order = topologicalCanonicalOrder(events.map(e => ({
+		id: e.id,
+		prev_event_ids: e.prev_event_ids,
+		hlc: e.hlc,
+		node_id: e.node_id,
+		sender: e.sender,
+	})))
+	const tips = computeDagTipIdsFromEvents(events)
+	const branchTipId = selectConsensusBranchTip(tips, byId)
+	const checkpointTipId = checkpointHint?.checkpoint_event_id || null
+	const keepIds = computeRetentionKeepIds(order, byId, {
+		maxDepth,
+		cutoffWall,
+		anchorTypes: policy.anchorTypes,
+		checkpointTipId,
+		branchTipId,
+	})
+	if (keepIds.size >= events.length) return { pruned: false, kept: events.length, dropped: 0 }
+	const kept = order.map(id => byId.get(id)).filter(ev => ev && keepIds.has(ev.id))
+	const dropped = events.length - kept.length
+	if (dropped <= 0) return { pruned: false, kept: kept.length, dropped: 0 }
+	await mkdir(dirname(eventsFilePath), { recursive: true })
+	await writeJsonlSynced(eventsFilePath, kept)
+	invalidateTopologicalOrderMemo(eventsFilePath)
+	return { pruned: true, kept: kept.length, dropped }
+}

package/timeline/retention_runner.mjs

@@ -0,0 +1,35 @@
+import { readJsonl } from '../dag/storage.mjs'
+
+import { pruneEventsJsonlAfterCheckpoint } from './prune.mjs'
+import { enforceTimelineEventRetention } from './retention.mjs'
+
+/**
+ * @param {{
+ *   eventsFilePath: string,
+ *   readCheckpoint: () => Promise<object | null>,
+ *   policy: { maxDepth: number, maxMs: number, anchorTypes: Set<string> },
+ *   sanitize?: (row: object) => object,
+ * }} args 保留参数
+ * @returns {Promise<{ pruned: boolean, kept: number, dropped: number }>} 裁剪统计
+ */
+export async function enforceDagRetention({ eventsFilePath, readCheckpoint, policy, sanitize = row => row }) {
+	const checkpoint = await readCheckpoint()
+	return enforceTimelineEventRetention(eventsFilePath, checkpoint, policy, sanitize)
+}
+
+/**
+ * @param {{
+ *   eventsFilePath: string,
+ *   checkpoint: object | null,
+ *   policy: { maxDepth: number, maxMs: number, anchorTypes: Set<string> },
+ *   sanitize: (row: object) => object,
+ *   compactTrigger: number,
+ * }} args 维护参数
+ * @returns {Promise<void>}
+ */
+export async function runTimelineMaintenance({ eventsFilePath, checkpoint, policy, sanitize, compactTrigger }) {
+	await enforceTimelineEventRetention(eventsFilePath, checkpoint, policy, sanitize)
+	const count = (await readJsonl(eventsFilePath, { sanitize })).length
+	if (count > compactTrigger && checkpoint?.checkpoint_event_id)
+		await pruneEventsJsonlAfterCheckpoint(eventsFilePath, checkpoint, sanitize)
+}

package/timeline/verify_remote.mjs

@@ -0,0 +1,25 @@
+/**
+ * Social / 时间线远程入站 ed25519 验签（sender 为 pubKeyHash，公钥来自 senderPubKey）。
+ */
+import { Buffer } from 'node:buffer'
+
+import { isHex64, isSignatureHex128 } from '../core/hexIds.mjs'
+import { pubKeyHash, verify } from '../crypto/crypto.mjs'
+import { eventBodyForSign, signPayloadBytes } from '../dag/index.mjs'
+
+/**
+ * @param {object} event 含 signature、sender、senderPubKey 的签名事件
+ * @returns {Promise<boolean>} 验签是否通过
+ */
+export async function verifyTimelineRemoteSignature(event) {
+	const sender = String(event?.sender || '').trim().toLowerCase()
+	if (!isHex64(sender)) return false
+	const signatureHex = String(event?.signature || '').trim()
+	if (!isSignatureHex128(signatureHex)) return false
+	const pubKeyHex = String(event?.senderPubKey || '').trim().toLowerCase()
+	if (!isHex64(pubKeyHex)) return false
+	const publicKeyBytes = new Uint8Array(Buffer.from(pubKeyHex, 'hex'))
+	if (pubKeyHash(publicKeyBytes) !== sender) return false
+	const signatureBytes = new Uint8Array(Buffer.from(signatureHex, 'hex'))
+	return await verify(signatureBytes, signPayloadBytes(eventBodyForSign(event)), publicKeyBytes)
+}

package/transport/group_link_set.mjs

@@ -0,0 +1,324 @@
+import { advertiseTopic, subscribeTopic } from '../discovery/index.mjs'
+import { buildSignedAdvert, verifySignedAdvert } from '../link/handshake.mjs'
+import { loadPeerPoolView } from '../node/network.mjs'
+import { loadReputation } from '../node/reputation_store.mjs'
+
+import {
+	groupRendezvousTopic,
+	decryptSignalPacket,
+	encryptSignalPacket,
+	getLinkRegistry,
+} from './link_registry.mjs'
+import { resolveFederationPoolLimits, selectLinkTargetsFromMembers } from './peer_pool.mjs'
+
+
+/**
+ * 创建基于 link registry 的群组联邦房间。
+ * @param {object} opts 选项
+ * @param {string} opts.groupId 群组 id
+ * @param {string} opts.roomSecret 房间密钥（用于 rendezvous topic）
+ * @param {string[]} opts.members 初始成员 nodeHash 列表
+ * @param {object} [opts.groupSettings] 群设置（连接预算：trustedPeerSlots/explorePeerSlots/maxPeers 等）
+ * @returns {{ groupId: string, scope: string, start: () => Promise<void>, leave: () => Promise<void>, getRoster: () => Array<{ peerId: string, remoteNodeHash: string }>, getPeerIdByNodeHash: (nodeHash: string) => string | null, sendToPeer: (peerId: string, actionName: string, payload: unknown) => Promise<boolean>, send: (actionName: string, payload: unknown, peerId?: string | null) => Promise<number>, onEnvelope: (cb: (senderNodeHash: string, envelope: object) => void) => () => void, onPeerJoin: (cb: (peerId: string) => void) => () => void, onPeerLeave: (cb: (peerId: string) => void) => () => void, getPeers: () => Record<string, true>, makeAction: (name: string) => [(payload: unknown, peerId?: string | string[] | null) => Promise<void>, (handler: (payload: unknown, peerId: string) => void) => void], registerCleanup: (fn: () => void) => void, isActive: () => boolean }} 群组 link set 接口
+ */
+export function createGroupLinkSet(opts) {
+	const registry = opts.registry ?? getLinkRegistry()
+	const autoconnect = opts.autoconnect !== false
+	const groupId = String(opts.groupId)
+	const scope = `group:${groupId}`
+	const topic = groupRendezvousTopic(opts.roomSecret)
+	const members = new Set((Array.isArray(opts.members) ? opts.members : []).map(String))
+	const selfNodeHash = registry.localIdentity.nodeHash
+	const groupSettings = opts.groupSettings ?? {}
+	// 初始成员是调用方明确知道的引导集合（如 introducer/creator/seed），作为必连锚点保证引导期连通。
+	const initialAnchors = new Set(members)
+	/** @type {ReturnType<typeof setTimeout> | null} */
+	let dialTimer = null
+	/** @type {Set<Function>} */
+	const cleanups = new Set()
+	/** @type {Set<Function>} */
+	const envelopeListeners = new Set()
+	/** @type {Set<(peerId: string) => void>} */
+	const peerJoinListeners = new Set()
+	/** @type {Set<(peerId: string) => void>} */
+	const peerLeaveListeners = new Set()
+	/** @type {Set<string>} */
+	const announcedPeers = new Set()
+	/** @type {Map<string, { handler: ((payload: unknown, peerId: string) => void) | null, backlog: Array<{ payload: unknown, peerId: string }> }>} */
+	const actionEntries = new Map()
+	let active = true
+
+	/**
+	 * 注册 leave 时执行的清理回调。
+	 * @param {() => void} fn 清理函数
+	 * @returns {void}
+	 */
+	function registerCleanup(fn) {
+		if (typeof fn !== 'function') return
+		cleanups.add(fn)
+	}
+
+	/**
+	 * 向 peer 事件监听器集合广播。
+	 * @param {Set<(peerId: string) => void>} listeners 监听器集合
+	 * @param {string} peerId 目标 peer id
+	 * @returns {void}
+	 */
+	function emitPeerListeners(listeners, peerId) {
+		for (const listener of listeners)
+			try { listener(peerId) } catch { /* ignore */ }
+	}
+
+	/**
+	 * 记录 peer 加入并通知监听器。
+	 * @param {string} peerId 加入的 peer id
+	 * @returns {void}
+	 */
+	function notePeerJoin(peerId) {
+		if (!peerId || announcedPeers.has(peerId)) return
+		announcedPeers.add(peerId)
+		emitPeerListeners(peerJoinListeners, peerId)
+	}
+
+	/**
+	 * 记录 peer 离开并通知监听器。
+	 * @param {string} peerId 离开的 peer id
+	 * @returns {void}
+	 */
+	function notePeerLeave(peerId) {
+		if (!peerId || !announcedPeers.has(peerId)) return
+		announcedPeers.delete(peerId)
+		emitPeerListeners(peerLeaveListeners, peerId)
+	}
+
+	/**
+	 * 将新发现的 nodeHash 加入成员集合并更新 scope 兴趣。
+	 * @param {string} nodeHash 候选节点 64 hex
+	 * @returns {void}
+	 */
+	function notePeerCandidate(nodeHash) {
+		const normalized = String(nodeHash || '')
+		if (!normalized || normalized === selfNodeHash || members.has(normalized)) return
+		members.add(normalized)
+		registry.registerScopeInterest(scope, [...members])
+		// 若链路先于"得知其群成员身份"建立（如 warmup/连节点先连上，之后才收到其群 advert/envelope），
+		// onLinkUp 当时因 !members.has 被跳过，这里补发 peer-join，触发 bootstrap flush（member_join 自证推送）。
+		if (registry.getLink(normalized)) notePeerJoin(normalized)
+		scheduleDial()
+	}
+
+	/**
+	 * 依信任稀疏池从当前成员选出建链目标（top-K 信任 + 随机 explore + 初始锚点必连），拨号未连接者。
+	 * 不主动断连（超预算由 registry 全局 trimToBudget 兜底）。
+	 * @returns {void}
+	 */
+	function selectAndDial() {
+		if (!autoconnect || !active) return
+		const targets = selectLinkTargetsFromMembers({
+			members,
+			selfNodeHash,
+			rep: loadReputation(),
+			peers: loadPeerPoolView(groupId),
+			limits: resolveFederationPoolLimits(groupSettings),
+			anchors: initialAnchors,
+		})
+		for (const nodeHash of targets)
+			if (nodeHash !== selfNodeHash && !registry.getLink(nodeHash))
+				void registry.ensureLinkToNode(nodeHash).catch(() => null)
+	}
+
+	/**
+	 * 去抖触发一次建链目标重算（成员变化时调用，避免频繁重算）。
+	 * @returns {void}
+	 */
+	function scheduleDial() {
+		if (!autoconnect || !active || dialTimer) return
+		dialTimer = setTimeout(() => { dialTimer = null; selectAndDial() }, 200)
+	}
+
+	/**
+	 * 获取或创建指定 action 的 handler/backlog 条目。
+	 * @param {string} name action 名称
+	 * @returns {{ handler: ((payload: unknown, peerId: string) => void) | null, backlog: Array<{ payload: unknown, peerId: string }> }} action 条目
+	 */
+	function getActionEntry(name) {
+		const key = String(name)
+		if (!actionEntries.has(key))
+			actionEntries.set(key, { handler: null, backlog: [] })
+		return actionEntries.get(key)
+	}
+
+	/**
+	 * 返回当前已连接且非自身的成员 roster。
+	 * @returns {Array<{ peerId: string, remoteNodeHash: string }>} 在线成员列表
+	 */
+	function activeRoster() {
+		return [...members]
+			.filter(nodeHash => nodeHash !== selfNodeHash && registry.getLink(nodeHash))
+			.map(nodeHash => ({ peerId: nodeHash, remoteNodeHash: nodeHash }))
+	}
+
+	/**
+	 * 启动 discovery、scope 订阅与成员自动连接。
+	 * @returns {Promise<void>}
+	 */
+	async function start() {
+		// 房间就绪本身就意味着本节点应当可被发现；不能等到首次外拨 ensureLinkToNode 才懒启动 runtime，
+		// 否则“只有自己一个成员”的创建者房间会永远不监听 node topic，后来的 joiner 也就永远拨不进来。
+		if (typeof registry.ensureRuntime === 'function')
+			await registry.ensureRuntime()
+		registry.registerScopeInterest(scope, [...members])
+		registerCleanup(registry.subscribeScope(scope, (senderNodeHash, envelope) => {
+			notePeerCandidate(senderNodeHash)
+			const entry = actionEntries.get(String(envelope?.action || ''))
+			if (entry)
+				if (entry.handler) entry.handler(envelope.payload, senderNodeHash)
+				else entry.backlog.push({ payload: envelope.payload, peerId: senderNodeHash })
+
+			for (const listener of envelopeListeners)
+				listener(senderNodeHash, envelope)
+		}))
+		registerCleanup(registry.onLinkUp(nodeHash => {
+			if (!members.has(nodeHash) || nodeHash === selfNodeHash) return
+			notePeerJoin(nodeHash)
+		}))
+		registerCleanup(registry.onLinkDown(nodeHash => {
+			if (!members.has(nodeHash) || nodeHash === selfNodeHash) return
+			notePeerLeave(nodeHash)
+		}))
+		registerCleanup(await subscribeTopic(topic, async bytes => {
+			const packet = decryptSignalPacket(topic, bytes)
+			if (packet?.type !== 'advert' || !packet.body) return
+			const verifiedNodeHash = await verifySignedAdvert(topic, packet.body)
+			if (!verifiedNodeHash || verifiedNodeHash === selfNodeHash) return
+			// 发现新成员：并入成员集并去抖重算稀疏建链目标（notePeerCandidate 内部会 scheduleDial）。
+			notePeerCandidate(verifiedNodeHash)
+		}))
+		registerCleanup(await advertiseTopic(topic, encryptSignalPacket(topic, {
+			type: 'advert',
+			body: await buildSignedAdvert(topic, Date.now(), registry.localIdentity),
+		})))
+		if (autoconnect) selectAndDial()
+		for (const { peerId } of activeRoster())
+			notePeerJoin(peerId)
+	}
+
+	return {
+		groupId,
+		scope,
+		start,
+		/**
+		 * 停止房间并执行所有已注册清理。
+		 * @returns {Promise<void>}
+		 */
+		async leave() {
+			if (!active) return
+			active = false
+			if (dialTimer) { clearTimeout(dialTimer); dialTimer = null }
+			registry.releaseScopeInterest(scope)
+			for (const cleanup of cleanups)
+				try { cleanup() } catch { /* ignore */ }
+			cleanups.clear()
+		},
+		getRoster: activeRoster,
+		/**
+		 * 按 nodeHash 查找已连接 peer id。
+		 * @param {string} nodeHash 目标节点 64 hex
+		 * @returns {string | null} 对端 id；无链路时为 null
+		 */
+		getPeerIdByNodeHash(nodeHash) {
+			return registry.getLink(nodeHash) ? String(nodeHash) : null
+		},
+		/**
+		 * 向单个 peer 发送 scope action。
+		 * @param {string} peerId 目标 peer id
+		 * @param {string} actionName action 名称
+		 * @param {unknown} payload 载荷
+		 * @returns {Promise<boolean>} 是否发送成功
+		 */
+		async sendToPeer(peerId, actionName, payload) {
+			return await registry.sendToNodeLink(peerId, { scope, action: String(actionName), payload })
+		},
+		/**
+		 * 向单个或全部在线成员发送 action。
+		 * @param {string} actionName action 名称
+		 * @param {unknown} payload 载荷
+		 * @param {string | null} [peerId] 目标 peer；null 时广播
+		 * @returns {Promise<number>} 成功发送的 peer 数
+		 */
+		async send(actionName, payload, peerId = null) {
+			if (peerId) return await this.sendToPeer(peerId, actionName, payload) ? 1 : 0
+			let sent = 0
+			for (const { peerId: targetPeerId } of activeRoster())
+				if (await registry.sendToNodeLink(targetPeerId, { scope, action: String(actionName), payload })) sent++
+			return sent
+		},
+		/**
+		 * 订阅入站 envelope。
+		 * @param {(senderNodeHash: string, envelope: object) => void} cb 回调
+		 * @returns {() => void} 取消订阅函数
+		 */
+		onEnvelope(cb) {
+			envelopeListeners.add(cb)
+			return () => envelopeListeners.delete(cb)
+		},
+		/**
+		 * 订阅 peer 加入事件（含当前已在线 peer 的即时回调）。
+		 * @param {(peerId: string) => void} cb 回调
+		 * @returns {() => void} 取消订阅函数
+		 */
+		onPeerJoin(cb) {
+			peerJoinListeners.add(cb)
+			for (const { peerId } of activeRoster())
+				if (peerId) announcedPeers.add(peerId)
+			for (const peerId of announcedPeers)
+				try { cb(peerId) } catch { /* ignore */ }
+			return () => peerJoinListeners.delete(cb)
+		},
+		/**
+		 * 订阅 peer 离开事件。
+		 * @param {(peerId: string) => void} cb 回调
+		 * @returns {() => void} 取消订阅函数
+		 */
+		onPeerLeave(cb) {
+			peerLeaveListeners.add(cb)
+			return () => peerLeaveListeners.delete(cb)
+		},
+		/**
+		 * 返回当前在线 peer 的 Record 映射。
+		 * @returns {Record<string, true>} peerId → true
+		 */
+		getPeers() {
+			return Object.fromEntries(activeRoster().map(({ peerId }) => [peerId, true]))
+		},
+		/**
+		 * 创建兼容 room.makeAction 的 [send, on] 函数对。
+		 * @param {string} name action 名称
+		 * @returns {[(payload: unknown, peerId?: string | string[] | null) => Promise<void>, (handler: (payload: unknown, peerId: string) => void) => void]} send 与 on 函数对
+		 */
+		makeAction(name) {
+			const actionName = String(name)
+			return [
+				async (payload, peerId = null) => {
+					if (Array.isArray(peerId)) {
+						await Promise.all(peerId.map(targetPeerId => this.sendToPeer(targetPeerId, actionName, payload)))
+						return
+					}
+					await this.send(actionName, payload, peerId)
+				},
+				handler => {
+					const entry = getActionEntry(actionName)
+					entry.handler = handler
+					for (const pending of entry.backlog.splice(0))
+						handler(pending.payload, pending.peerId)
+				},
+			]
+		},
+		registerCleanup,
+		/**
+		 * 房间是否仍处于活跃状态。
+		 * @returns {boolean} 是否活跃
+		 */
+		isActive() { return active },
+	}
+}

package/transport/ice_servers.mjs

@@ -0,0 +1,72 @@
+/**
+ * 群级 ICE/TURN 配置解析（groupSettings.iceServers → RTCPeerConnection / Trystero）。
+ */
+
+const ICE_URL_RE = /^(stun|turn|turns):/iu
+const MAX_ICE_SERVERS = 8
+
+/** @type {{ urls: string, username?: string, credential?: string }[]} */
+export const DEFAULT_ICE_SERVERS = [
+	{ urls: 'stun:stun.l.google.com:19302' },
+]
+
+/**
+ * @param {unknown} raw 单条 ICE 配置
+ * @returns {{ urls: string, username?: string, credential?: string } | null} 合法条目或 null
+ */
+function normalizeIceEntry(raw) {
+	if (!raw || typeof raw !== 'object') return null
+	const urlsRaw = raw.urls
+	const urlsList = Array.isArray(urlsRaw)
+		? urlsRaw.map(u => String(u).trim()).filter(Boolean)
+		: [String(urlsRaw || '').trim()].filter(Boolean)
+	if (!urlsList.length) return null
+	for (const u of urlsList)
+		if (!ICE_URL_RE.test(u)) return null
+	const username = raw.username != null ? String(raw.username) : undefined
+	const credential = raw.credential != null ? String(raw.credential) : undefined
+	if ((username && !credential) || (!username && credential)) return null
+	return {
+		urls: urlsList.length === 1 ? urlsList[0] : urlsList,
+		...username ? { username, credential } : {},
+	}
+}
+
+/**
+ * @param {unknown} groupSettings 物化群设置
+ * @returns {{ urls: string, username?: string, credential?: string }[]} 合法 ICE 列表
+ */
+export function resolveIceServers(groupSettings) {
+	const fromSettings = Array.isArray(groupSettings?.iceServers) ? groupSettings.iceServers : []
+	const out = []
+	for (const raw of fromSettings) {
+		const entry = normalizeIceEntry(raw)
+		if (entry) out.push(entry)
+		if (out.length >= MAX_ICE_SERVERS) break
+	}
+	return out.length ? out : [...DEFAULT_ICE_SERVERS]
+}
+
+/**
+ * @param {unknown} groupSettings 物化群设置
+ * @returns {{ iceServers: ReturnType<typeof resolveIceServers> }} Trystero rtcConfig 片段
+ */
+export function resolveIceServersForTrystero(groupSettings) {
+	return { iceServers: resolveIceServers(groupSettings) }
+}
+
+/**
+ * 校验并规范化待写入 DAG 的 iceServers 数组。
+ * @param {unknown} raw 请求体字段
+ * @returns {{ urls: string, username?: string, credential?: string }[]} 校验后的 ICE 列表
+ */
+export function sanitizeIceServersForSettings(raw) {
+	if (!Array.isArray(raw)) return [...DEFAULT_ICE_SERVERS]
+	const out = []
+	for (const item of raw) {
+		const entry = normalizeIceEntry(item)
+		if (entry) out.push(entry)
+		if (out.length >= MAX_ICE_SERVERS) break
+	}
+	return out.length ? out : [...DEFAULT_ICE_SERVERS]
+}