@steve02081504/fount-p2p 0.0.0

package/governance/join_pow.mjs

@@ -0,0 +1,165 @@
+/**
+ * 无状态入群 PoW：绑定群近期 DAG tip/checkpoint root，任意 replica 可独立验证。
+ */
+import { createHash } from 'node:crypto'
+
+import admissionTunables from './tunables.json' with { type: 'json' }
+
+/** 默认 epoch 窗口（1 小时） */
+export const JOIN_POW_DEFAULT_EPOCH_MS = 3_600_000
+
+/** 默认 epoch 偏移容忍（±1 个 epoch） */
+export const JOIN_POW_DEFAULT_EPOCH_SKEW = 1
+
+/**
+ * @param {object} fields  preimage 字段
+ * @param {string} fields.groupId 群 ID
+ * @param {string} fields.anchorRef 近期 tip 或 checkpoint root
+ * @param {string} fields.joinerNodeHash 入群者 nodeHash
+ * @param {number|string} fields.epoch epoch 桶
+ * @param {string|number} fields.nonce 随机 nonce
+ * @returns {string} SHA-256 十六进制
+ */
+export function computeJoinPowHash({ groupId, anchorRef, joinerNodeHash, epoch, nonce }) {
+	const preimage = `${String(groupId)}:${String(anchorRef)}:${String(joinerNodeHash)}:${String(epoch)}:${String(nonce)}`
+	return createHash('sha256').update(preimage, 'utf8').digest('hex')
+}
+
+/**
+ * @param {string} hexHash SHA-256 十六进制
+ * @param {number} difficultyBits 前导零 bit 数
+ * @returns {boolean} 是否满足难度
+ */
+export function joinPowHashMeetsDifficulty(hexHash, difficultyBits) {
+	const bits = Math.max(0, Math.min(256, Math.floor(Number(difficultyBits) || 0)))
+	if (bits <= 0) return true
+	const neededHexChars = Math.ceil(bits / 4)
+	const prefix = hexHash.slice(0, neededHexChars)
+	if (prefix.length < neededHexChars) return false
+	for (let i = 0; i < prefix.length; i++) {
+		const nibble = Number.parseInt(prefix[i], 16)
+		if (!Number.isFinite(nibble)) return false
+		const nibbleBits = i < neededHexChars - 1 ? 4 : bits - i * 4
+		const mask = (0xF << (4 - nibbleBits)) & 0xF
+		if ((nibble & mask) !== 0) return false
+	}
+	return true
+}
+
+/**
+ * @param {string} hexHash SHA-256 十六进制
+ * @returns {number} 实际达成的前导零 bit 数 0..256
+ */
+export function countAchievedLeadingZeroBits(hexHash) {
+	let bits = 0
+	for (let i = 0; i < hexHash.length; i++) {
+		const nibble = Number.parseInt(hexHash[i], 16)
+		if (!Number.isFinite(nibble)) break
+		if (nibble === 0) {
+			bits += 4
+			continue
+		}
+		for (let b = 3; b >= 0; b--)
+			if ((nibble & (1 << b)) === 0) bits++
+			else return bits
+
+	}
+	return bits
+}
+
+/**
+ * floor 以上自愿多做 bit 的 log 递减封顶信誉加成。
+ * @param {number} achievedBits 解实际达成 bit
+ * @param {number} floorBits 准入 floor
+ * @param {typeof admissionTunables} [tunables] admission tunables
+ * @returns {number} 加成 0..cap
+ */
+export function powVoluntaryBonus(achievedBits, floorBits, tunables = admissionTunables) {
+	const cap = Number(tunables.powVoluntaryBonusCap ?? 0)
+	const scale = Math.max(1, Number(tunables.powVoluntaryBonusScaleBits ?? 6))
+	if (!Number.isFinite(cap) || cap <= 0) return 0
+	const extra = Math.max(0, Math.floor(Number(achievedBits) || 0) - Math.floor(Number(floorBits) || 0))
+	if (extra <= 0) return 0
+	return cap * (1 - 2 ** (-extra / scale))
+}
+
+/**
+ * @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 偏移
+ * @returns {{ ok: boolean, achievedBits: number }} 校验结果与实际达成 bit
+ */
+export function verifyJoinPow(powSolution, opts) {
+	const floorBits = Math.max(0, Math.floor(Number(opts.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.nonce
+	const epoch = Number(powSolution.epoch)
+	const joinerNodeHash = String(powSolution.joinerNodeHash ?? opts.senderNodeHash ?? '').trim().toLowerCase()
+	const senderNodeHash = String(opts.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)
+	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)
+	if (Math.abs(epoch - nowEpoch) > skew) return { ok: false, achievedBits: 0 }
+
+	const hash = computeJoinPowHash({
+		groupId: opts.groupId,
+		anchorRef,
+		joinerNodeHash,
+		epoch,
+		nonce: String(nonce),
+	})
+	const achievedBits = countAchievedLeadingZeroBits(hash)
+	return {
+		ok: joinPowHashMeetsDifficulty(hash, floorBits),
+		achievedBits,
+	}
+}
+
+/**
+ * 浏览器/Node 通用求解（同步 brute-force，适合低难度）。
+ * @param {object} fields preimage 字段（不含 nonce）
+ * @param {number} floorBits 准入 floor（前导零 bit）
+ * @param {number} [maxAttempts=5_000_000] 最大尝试次数
+ * @param {number} [targetBits] 目标 bit（省略则等于 floor）
+ * @returns {{ anchorRef: string, joinerNodeHash: string, epoch: number, nonce: string, achievedBits: number } | null} solution
+ */
+export function solveJoinPow(fields, floorBits, maxAttempts = 5_000_000, targetBits) {
+	const floor = Math.max(1, Math.floor(Number(floorBits) || 1))
+	const target = Math.max(floor, Math.floor(Number(targetBits) || floor))
+	let best = null
+	for (let nonce = 0; nonce < maxAttempts; nonce++) {
+		const hash = computeJoinPowHash({ ...fields, nonce: String(nonce) })
+		const achieved = countAchievedLeadingZeroBits(hash)
+		if (achieved >= floor) {
+			const solution = { ...fields, nonce: String(nonce), achievedBits: achieved }
+			if (achieved >= target) return solution
+			if (!best || achieved > best.achievedBits) best = solution
+		}
+	}
+	return best
+}
+
+/**
+ * @param {number} difficultyBits 难度 bit
+ * @returns {number} 期望哈希次数（2^bits）
+ */
+export function expectedJoinPowHashes(difficultyBits) {
+	const bits = Math.max(0, Math.floor(Number(difficultyBits) || 0))
+	return bits <= 52 ? 2 ** bits : Number.MAX_SAFE_INTEGER
+}

package/governance/owner_succession_ballot.mjs

@@ -0,0 +1,57 @@
+/**
+ * 群主继任联署选票验签（§8）：管理员对固定 canonical 载荷签名，达到阈值即通过。
+ */
+import { Buffer } from 'node:buffer'
+
+import { canonicalStringify } from '../core/canonical_json.mjs'
+import { isHex64, isSignatureHex128 } from '../core/hexIds.mjs'
+import { pubKeyHash, verify } from '../crypto/crypto.mjs'
+
+const BALLOT_DOMAIN = 'fount-owner-succession'
+
+/**
+ * @param {{ proposedOwnerPubKeyHash: string, groupId: string, ballotId: string }} ballot 选票正文
+ * @returns {Buffer} 验签消息
+ */
+export function ownerSuccessionBallotSignBytes(ballot) {
+	const body = {
+		proposedOwnerPubKeyHash: String(ballot.proposedOwnerPubKeyHash ?? '').trim().toLowerCase(),
+		groupId: String(ballot.groupId ?? '').trim(),
+		ballotId: String(ballot.ballotId ?? '').trim(),
+	}
+	return Buffer.from(`${BALLOT_DOMAIN}\0${canonicalStringify(body)}`, 'utf8')
+}
+
+/**
+ * 校验管理员联署是否达到 `thresholdRatio`（默认半数以上）。
+ * @param {{ proposedOwnerPubKeyHash: string, groupId: string, ballotId: string, adminSignatures: Array<{ pubKeyHex: string, signature: string }> }} ballot 选票正文与签名列表
+ * @param {Set<string>} adminPubKeyHashes 合法管理员公钥指纹
+ * @param {number} [thresholdRatio] 通过比例 (0,1]
+ * @returns {Promise<boolean>} 达到阈值时为 true
+ */
+export async function verifyOwnerSuccessionThreshold(ballot, adminPubKeyHashes, thresholdRatio = 0.5) {
+	const admins = adminPubKeyHashes instanceof Set ? adminPubKeyHashes : new Set(adminPubKeyHashes)
+	if (!admins.size) return false
+
+	const ratio = Number(thresholdRatio)
+	if (!Number.isFinite(ratio) || ratio <= 0 || ratio > 1) return false
+
+	const signBytes = ownerSuccessionBallotSignBytes(ballot)
+	const needed = Math.ceil(admins.size * ratio)
+	const seen = new Set()
+	let valid = 0
+
+	for (const entry of ballot.adminSignatures || []) {
+		const pubKeyHex = String(entry?.pubKeyHex ?? '').trim().toLowerCase()
+		const signatureHex = String(entry?.signature ?? '').trim().toLowerCase()
+		if (!isHex64(pubKeyHex) || !isSignatureHex128(signatureHex)) continue
+
+		const hash = pubKeyHash(Buffer.from(pubKeyHex, 'hex'))
+		if (!admins.has(hash) || seen.has(hash)) continue
+		if (!await verify(Buffer.from(signatureHex, 'hex'), signBytes, Buffer.from(pubKeyHex, 'hex'))) continue
+
+		seen.add(hash)
+		if (++valid >= needed) return true
+	}
+	return false
+}

package/governance/tunables.json

@@ -0,0 +1,7 @@
+{
+	"powFloorBits": 18,
+	"powVoluntaryBonusCap": 0.12,
+	"powVoluntaryBonusScaleBits": 6,
+	"powEpochMs": 3600000,
+	"powEpochSkew": 1
+}

package/index.mjs

@@ -0,0 +1,39 @@
+/**
+ * Federation P2P 门面：通用引导与房间/发现入口。
+ * 重型子系统请直接从子路径导入（如 `./dag/index.mjs`）。
+ */
+import { registerDiscoveryProvider } from './discovery/index.mjs'
+import { ensureNodeDefaults, getNodeHash } from './node/identity.mjs'
+import { getNodeDir, initNode, isNodeInitialized } from './node/instance.mjs'
+import { createScopedLinkRoom } from './rooms/scoped_link.mjs'
+import { createGroupLinkSet } from './transport/group_link_set.mjs'
+import { getLinkRegistry } from './transport/link_registry.mjs'
+import { ensureUserRoom } from './transport/user_room.mjs'
+
+/**
+ *
+ */
+export {
+	createGroupLinkSet,
+	createScopedLinkRoom,
+	ensureNodeDefaults,
+	ensureUserRoom,
+	getLinkRegistry,
+	getNodeDir,
+	getNodeHash,
+	initNode,
+	isNodeInitialized,
+	registerDiscoveryProvider,
+}
+
+/**
+ * 初始化并启动 P2P 节点运行时（身份、链路网、link registry）。
+ * @param {{ nodeDir: string, entityStore?: import('./node/entity_store.mjs').EntityStore, logger?: object, signaling?: import('./node/signaling_config.mjs').SignalingRuntimeConfig }} options 节点配置
+ * @returns {Promise<void>}
+ */
+export async function startNode(options) {
+	if (!isNodeInitialized())
+		initNode(options)
+	ensureNodeDefaults()
+	await getLinkRegistry().ensureRuntime()
+}

package/link/channel_mux.mjs

@@ -0,0 +1,222 @@
+/**
+ * control 通道名：低延迟、小载荷与路由类消息。
+ */
+export const CHANNEL_CONTROL = 'control'
+/**
+ * bulk 通道名：大载荷与低优先级消息。
+ */
+export const CHANNEL_BULK = 'bulk'
+/**
+ * bufferedAmount 低水位默认阈值（256 KiB）。
+ */
+export const CHANNEL_LOW_THRESHOLD_BYTES = 256 * 1024
+/**
+ * 发送队列高水位默认阈值（1 MiB）。
+ */
+export const CHANNEL_HIGH_WATERMARK_BYTES = 1024 * 1024
+/**
+ * 超过此字节数优先走 bulk 通道（64 KiB）。
+ */
+export const BULK_CHANNEL_MIN_BYTES = 64 * 1024
+
+const DEFAULT_ACTION_PRIORITIES = Object.freeze({
+	dag_event: 0,
+	gossip_request: 1,
+	gossip_response: 2,
+	channel_history_want: 2,
+	fed_bootstrap_request: 2,
+	fed_bootstrap_response: 2,
+	fed_join_snapshot_request: 2,
+	fed_archive_month_want: 2,
+	fed_archive_month_response: 2,
+	mailbox_put: 2,
+	mailbox_want: 2,
+	mailbox_give: 2,
+	fed_tip_ping: 3,
+	discovery_announce: 3,
+	discovery_query: 3,
+	discovery_query_response: 3,
+	part_invoke: 3,
+	part_invoke_response: 3,
+	char_rpc: 3,
+	fed_chunk_put: 5,
+	fed_chunk_get: 5,
+	fed_chunk_data: 5,
+	fed_chunk_ack: 5,
+	fed_partition_bridge: 5,
+	fed_volatile: 10,
+})
+
+/**
+ * 根据 action 名称解析发送优先级，数值越小越优先。
+ * @param {string} action 消息 action 名称
+ * @returns {number} 优先级（未知 action 默认 5）
+ */
+export function resolveActionPriority(action) {
+	return DEFAULT_ACTION_PRIORITIES[String(action || '').trim()] ?? 5
+}
+
+/**
+ * 根据 action 与载荷大小选择 control 或 bulk 通道。
+ * @param {string} action 消息 action 名称
+ * @param {number} byteLength 载荷字节长度
+ * @returns {'control' | 'bulk'} 目标通道名
+ */
+export function pickChannel(action, byteLength) {
+	const normalized = String(action || '').trim()
+	if (normalized === 'ping' || normalized === 'pong' || normalized.startsWith('route_'))
+		return CHANNEL_CONTROL
+	if (Number(byteLength) > BULK_CHANNEL_MIN_BYTES)
+		return CHANNEL_BULK
+	return resolveActionPriority(normalized) <= 3 ? CHANNEL_CONTROL : CHANNEL_BULK
+}
+
+/**
+ * 读取 RTC 数据通道当前 bufferedAmount，失败时返回 0。
+ * @param {RTCDataChannel} channel RTC 数据通道
+ * @returns {number} 缓冲区待发送字节数
+ */
+export function readBufferedAmount(channel) {
+	try {
+		return Number.isFinite(channel?.bufferedAmount) ? Number(channel.bufferedAmount) : 0
+	}
+	catch {
+		return 0
+	}
+}
+
+/**
+ * 配置数据通道的 bufferedAmountLowThreshold。
+ * @param {RTCDataChannel} channel RTC 数据通道
+ * @param {number} [thresholdBytes=CHANNEL_LOW_THRESHOLD_BYTES] 低水位阈值（字节）
+ * @returns {number | null} 实际生效的阈值，不支持时返回 null
+ */
+export function configureBufferedAmountLowThreshold(channel, thresholdBytes = CHANNEL_LOW_THRESHOLD_BYTES) {
+	try {
+		channel.bufferedAmountLowThreshold = thresholdBytes
+		return Number.isFinite(channel.bufferedAmountLowThreshold)
+			? Number(channel.bufferedAmountLowThreshold)
+			: null
+	}
+	catch {
+		return null
+	}
+}
+
+/**
+ * 订阅 bufferedamountlow 事件，返回取消订阅函数。
+ * @param {RTCDataChannel} channel RTC 数据通道
+ * @param {() => void} cb 低水位回调
+ * @returns {() => void} 取消订阅函数
+ */
+export function onBufferedAmountLow(channel, cb) {
+	/**
+	 * bufferedamountlow 事件处理函数。
+	 * @returns {void}
+	 */
+	const handler = () => cb()
+	channel.addEventListener?.('bufferedamountlow', handler)
+	channel.onbufferedamountlow = handler
+	if (channel.bufferedAmountLow?.subscribe)
+		channel.bufferedAmountLow.subscribe(handler)
+	return () => {
+		channel.removeEventListener?.('bufferedamountlow', handler)
+		if (channel.onbufferedamountlow === handler) channel.onbufferedamountlow = null
+	}
+}
+
+/**
+ * 创建带优先级队列的双通道发送器（control/bulk）。
+ * @param {{ getChannel: (name: 'control' | 'bulk') => RTCDataChannel | null | undefined, highWatermarkBytes?: number }} opts 通道访问与高水位配置
+ * @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.getChannel
+	const highWatermarkBytes = Math.max(CHANNEL_LOW_THRESHOLD_BYTES, Number(opts.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 }} */
+	const scheduled = { control: false, bulk: false }
+	let seq = 0
+
+	/**
+	 * 在 microtask 中调度指定通道的 flush。
+	 * @param {'control' | 'bulk'} channelName 通道名
+	 * @returns {void}
+	 */
+	const scheduleFlush = channelName => {
+		if (scheduled[channelName]) return
+		scheduled[channelName] = true
+		queueMicrotask(() => flush(channelName))
+	}
+
+	/**
+	 * 将队列中的帧写入指定通道，受高水位限制。
+	 * @param {'control' | 'bulk'} channelName 通道名
+	 * @returns {void}
+	 */
+	const flush = channelName => {
+		scheduled[channelName] = false
+		const channel = getChannel(channelName)
+		if (!channel || channel.readyState !== 'open') return
+		const queue = queues[channelName]
+		while (queue.length) {
+			if (readBufferedAmount(channel) > highWatermarkBytes) return
+			const item = queue.shift()
+			channel.send(item.bytes)
+		}
+	}
+
+	return {
+		/**
+		 * 按优先级将字节帧入队并调度发送。
+		 * @param {string} action 消息 action（用于选通道与优先级）
+		 * @param {Uint8Array} bytes 待发送帧字节
+		 * @param {'control' | 'bulk'} [preferredChannel] 强制使用的通道，省略则自动选择
+		 * @returns {void}
+		 */
+		enqueue(action, bytes, preferredChannel) {
+			const channelName = preferredChannel ?? pickChannel(action, bytes.byteLength)
+			const queue = queues[channelName]
+			const priority = resolveActionPriority(action)
+			const item = { priority, seq: ++seq, bytes }
+			let lo = 0
+			let hi = queue.length
+			while (lo < hi) {
+				const mid = (lo + hi) >> 1
+				const compare = priority - queue[mid].priority || item.seq - queue[mid].seq
+				if (compare < 0) hi = mid
+				else lo = mid + 1
+			}
+			queue.splice(lo, 0, item)
+			scheduleFlush(channelName)
+		},
+		/**
+		 * 调度 flush：指定通道或双通道。
+		 * @param {'control' | 'bulk'} [channelName] 通道名，省略则 flush 全部
+		 * @returns {void}
+		 */
+		flush(channelName) {
+			if (channelName) scheduleFlush(channelName)
+			else {
+				scheduleFlush(CHANNEL_CONTROL)
+				scheduleFlush(CHANNEL_BULK)
+			}
+		},
+		/**
+		 * 返回各通道待发送帧数量。
+		 * @returns {{ control: number, bulk: number }} control 与 bulk 队列长度
+		 */
+		pending() {
+			return { control: queues.control.length, bulk: queues.bulk.length }
+		},
+		/**
+		 * 清空所有发送队列。
+		 * @returns {void}
+		 */
+		clear() {
+			queues.control.length = 0
+			queues.bulk.length = 0
+		},
+	}
+}