@steve02081504/fount-p2p 0.0.0

package/node/reputation_store.mjs

@@ -0,0 +1,326 @@
+import { assertHex64, isHex64, normalizeHex64 } from '../core/hexIds.mjs'
+import { recordWantIdsBackoff, wantIdsPeerKey } from '../federation/want_ids.mjs'
+import {
+	applyDecayCollusionAfterSlashPure,
+	applyReputationResetToScoresPure,
+	applySubjectiveSlashPure,
+	bumpChunkStorageReputationPure,
+	bumpReputationOnRelayPure,
+	ensureReputationShape,
+	isQuarantinedPure,
+	observeBehaviorSamplePure,
+	penalizeArchiveServeMismatchPure,
+	penalizeChunkStorageFailurePure,
+	pruneReputationFile,
+	recordGossipAllUnknownWantPure,
+	recordMessageRateViolationPure,
+	resolveSlashAlertTtlMsPure,
+	seedMemberReputationFromIntroducerPure,
+} from '../reputation/engine.mjs'
+import { pickNodeScoreFromReputation } from '../reputation/pick_score.mjs'
+import reputationTunables from '../reputation/tunables.json' with { type: 'json' }
+import { invalidateTrustGraphCache } from '../trust_graph/cache.mjs'
+import { withAsyncMutex } from '../utils/async_mutex.mjs'
+
+import { getNodeDir, getNodeLogger, isNodeInitialized } from './instance.mjs'
+import { readNodeJsonSync, writeNodeJsonSync } from './storage.mjs'
+
+const DATA_NAME = 'reputation'
+
+/** @type {((opts: object) => Promise<boolean>) | null} */
+let blockReputationHandler = null
+
+/**
+ * Shell Load 时注册：公开 block/unblock → 信誉传导。
+ * @param {(opts: object) => Promise<boolean>} handler block/unblock 信誉传导回调
+ * @returns {void}
+ */
+export function registerBlockReputationHandler(handler) {
+	blockReputationHandler = handler
+}
+
+/** @returns {void} */
+export function unregisterBlockReputationHandler() {
+	blockReputationHandler = null
+}
+
+/**
+ * @typedef {{
+ *   byNodeHash: Record<string, { score: number, offenseStreak?: number, lastOffenseAt?: number, blockPenalties?: Record<string, { penalty: number, appliedAt: number, decayedRefund?: number }> }>
+ *   wantUnknownHits: Array<{ peerNodeHash: string, t: number }>
+ *   relayBumpSeen: Array<{ peerNodeHash: string, key: string, t: number }>
+ * }} ReputationFile
+ */
+
+/** @type {ReputationFile | null} */
+let reputationCache = null
+
+/** @type {string | null} */
+let reputationCacheNodeDir = null
+
+/**
+ * @param {(data: ReputationFile) => void | Promise<void>} mutator 突变
+ * @returns {Promise<void>}
+ */
+export function mutateReputation(mutator) {
+	return withAsyncMutex('reputation', async () => {
+		const data = loadReputation()
+		await mutator(data)
+		saveReputation(data)
+	})
+}
+
+/**
+ * @returns {ReputationFile} 节点级信誉表
+ */
+export function loadReputation() {
+	const nodeDir = isNodeInitialized() ? getNodeDir() : ''
+	if (reputationCache && reputationCacheNodeDir === nodeDir) return reputationCache
+	reputationCacheNodeDir = nodeDir
+	reputationCache = ensureReputationShape(readNodeJsonSync(DATA_NAME) || {})
+	return reputationCache
+}
+
+/**
+ * @param {ReputationFile} data 信誉表
+ * @returns {void}
+ */
+export function saveReputation(data) {
+	pruneReputationFile(data)
+	writeNodeJsonSync(DATA_NAME, data)
+	reputationCache = data
+	invalidateTrustGraphCache()
+}
+
+/**
+ * @param {string} peerNodeHash 对端节点
+ * @param {string} [dedupeKey] 去重键
+ * @returns {Promise<void>}
+ */
+export function bumpReputationOnRelay(peerNodeHash, dedupeKey) {
+	return mutateReputation(data => {
+		bumpReputationOnRelayPure(data, peerNodeHash, dedupeKey)
+	})
+}
+
+/**
+ * @param {string} groupId 群 ID（仅用于 want 去重键）
+ * @param {string} peerNodeHash 请求方
+ * @returns {Promise<void>}
+ */
+export function recordGossipAllUnknownWant(groupId, peerNodeHash) {
+	return mutateReputation(data => {
+		if (recordGossipAllUnknownWantPure(data, peerNodeHash))
+			recordWantIdsBackoff(wantIdsPeerKey(groupId, peerNodeHash))
+	})
+}
+
+/**
+ * @param {string} peerNodeHash 对端
+ * @param {number} [excessRatio=1] 超速超额比例 0..1
+ * @returns {Promise<void>}
+ */
+export function recordMessageRateViolation(peerNodeHash, excessRatio = 1) {
+	const id = String(peerNodeHash || '').trim()
+	if (!id) return Promise.resolve()
+	return mutateReputation(data => {
+		recordMessageRateViolationPure(data, id, undefined, excessRatio)
+		observeBehaviorSamplePure(data, id, 1)
+	})
+}
+
+/**
+ * @param {string} peerNodeHash 对端
+ * @param {number} sample 行为样本强度
+ * @returns {Promise<boolean>} 是否触发异常隔离
+ */
+export async function observePeerBehavior(peerNodeHash, sample) {
+	const id = String(peerNodeHash || '').trim()
+	if (!id) return false
+	let anomaly = false
+	await mutateReputation(data => {
+		const result = observeBehaviorSamplePure(data, id, sample)
+		anomaly = result.anomaly
+	})
+	return anomaly
+}
+
+/**
+ * @param {string} peerNodeHash 对端
+ * @returns {boolean} 是否处于本地隔离
+ */
+export function isPeerQuarantined(peerNodeHash) {
+	return isQuarantinedPure(loadReputation(), peerNodeHash)
+}
+
+/**
+ * @param {string} storagePeerKey 责任方
+ * @returns {void}
+ */
+export function bumpChunkStorageReputation(storagePeerKey) {
+	const id = String(storagePeerKey || '').trim()
+	if (!id) return
+	void mutateReputation(data => {
+		bumpChunkStorageReputationPure(data, id)
+	})
+}
+
+/**
+ * @param {string} blamePeerKey 责任方
+ * @returns {void}
+ */
+export function penalizeChunkStorageFailure(blamePeerKey) {
+	const id = String(blamePeerKey || '').trim()
+	if (!id) return
+	void mutateReputation(data => {
+		penalizeChunkStorageFailurePure(data, id)
+	})
+}
+
+/**
+ * @param {string} peerNodeHash 对端 nodeHash
+ * @returns {void}
+ */
+export function penalizeArchiveServeMismatch(peerNodeHash) {
+	const id = String(peerNodeHash || '').trim()
+	if (!id) return
+	void mutateReputation(data => {
+		penalizeArchiveServeMismatchPure(data, id)
+	})
+}
+
+/**
+ * @param {object | null | undefined} groupSettings 群设置
+ * @returns {number} 毫秒
+ */
+export function resolveSlashAlertTtlMs(groupSettings) {
+	return resolveSlashAlertTtlMsPure(groupSettings)
+}
+
+/**
+ * @param {object} alert VOLATILE slash 载荷
+ * @returns {boolean} 是否已应用
+ */
+export async function applyVolatileSlashAlert(alert) {
+	const expiresAt = Number(alert?.expiresAt)
+	if (Number.isFinite(expiresAt) && Date.now() > expiresAt) return false
+	const target = normalizeHex64(alert?.targetPubKeyHash)
+	const sender = normalizeHex64(alert?.sender)
+	if (!isHex64(target) || !isHex64(sender)) return false
+	const claim = Number.isFinite(Number(alert?.claim)) ? Number(alert.claim) : reputationTunables.slashDefaultClaim
+	await mutateReputation(data => {
+		applySubjectiveSlashPure(data, target, sender, claim, false)
+	})
+	return true
+}
+
+/**
+ * @param {string} senderPubKeyHash 签发者
+ * @param {{ targetPubKeyHash: string, claim?: number }} content Slash 内容
+ * @param {object} [groupSettings] 群设置
+ * @returns {object} VOLATILE 载荷
+ */
+export function buildAndApplyUnverifiedSlashAlert(senderPubKeyHash, content, groupSettings = {}) {
+	const targetPubKeyHash = assertHex64(content.targetPubKeyHash, 'slash target')
+	const claim = Number.isFinite(Number(content.claim)) ? Number(content.claim) : reputationTunables.slashDefaultClaim
+	const sender = assertHex64(senderPubKeyHash, 'slash sender')
+	const ttl = resolveSlashAlertTtlMs(groupSettings)
+	return {
+		type: 'reputation_slash_alert',
+		targetPubKeyHash,
+		sender,
+		claim,
+		expiresAt: Date.now() + ttl,
+	}
+}
+
+/**
+ * @param {string} username 用户（readEvents 回调用）
+ * @param {string} groupId 群
+ * @param {object} event reputation_slash 事件
+ * @param {(username: string, groupId: string) => Promise<object[]>} readEvents 读 DAG 事件
+ * @returns {Promise<void>}
+ */
+export async function applySubjectiveSlashFromEvent(username, groupId, event, readEvents) {
+	if (event.type !== 'reputation_slash') return
+	const { content } = event
+	const target = content.targetPubKeyHash.trim().toLowerCase()
+	const sender = event.sender.trim().toLowerCase()
+
+	await mutateReputation(async data => {
+		const verified = content.verified && await verifySlashProof(username, groupId, content, readEvents)
+		const claim = Number(content.claim ?? (verified ? reputationTunables.slashVerifiedDefaultClaim : reputationTunables.slashUnverifiedDefaultClaim))
+		applySubjectiveSlashPure(data, target, sender, claim, verified)
+	})
+}
+
+/**
+ * @param {string} username 用户
+ * @param {string} groupId 群
+ * @param {object} content slash 内容
+ * @param {(username: string, groupId: string) => Promise<object[]>} readEvents 读 DAG
+ * @returns {Promise<boolean>} 是否找到 proof 对应事件
+ */
+async function verifySlashProof(username, groupId, content, readEvents) {
+	const eventId = content?.proof?.eventId?.trim().toLowerCase()
+	if (!eventId) return false
+	const events = await readEvents(username, groupId)
+	return events.some(event => event.id === eventId)
+}
+
+/**
+ * @param {string} targetPubKeyHash 目标
+ * @param {Array<{ from?: string, to?: string }>} inviteEdges 邀请边
+ * @returns {void}
+ */
+export function applyDecayCollusionAfterSlash(targetPubKeyHash, inviteEdges) {
+	void mutateReputation(data => {
+		const applied = applyDecayCollusionAfterSlashPure(data, targetPubKeyHash, inviteEdges)
+		if (applied.length)
+			getNodeLogger().warn?.('reputation: collusion decay after slash', {
+				target: targetPubKeyHash.trim().toLowerCase(),
+				upstreamCount: applied.length,
+				hops: applied.map(row => row.hop),
+			})
+	})
+}
+
+/**
+ * @param {string} targetPubKeyHash 目标
+ * @returns {void}
+ */
+export function applyReputationResetToScores(targetPubKeyHash) {
+	void mutateReputation(data => {
+		applyReputationResetToScoresPure(data, targetPubKeyHash)
+	})
+}
+
+/**
+ * @param {string} memberPubKeyHash 新成员
+ * @param {string} [introducerPubKeyHash] 介绍者
+ * @param {number} [repEdge] 边信任
+ * @param {number} [powBonus=0] 入群 PoW 自愿封顶加成
+ * @returns {void}
+ */
+export function seedMemberReputationFromIntroducer(memberPubKeyHash, introducerPubKeyHash, repEdge, powBonus = 0) {
+	void mutateReputation(data => {
+		seedMemberReputationFromIntroducerPure(data, memberPubKeyHash, introducerPubKeyHash, repEdge, undefined, powBonus)
+	})
+}
+
+/**
+ * @param {string} nodeId 64 位十六进制
+ * @returns {number} 信誉分
+ */
+export function pickNodeScore(nodeId) {
+	return pickNodeScoreFromReputation(loadReputation(), nodeId)
+}
+
+/**
+ * @param {object} opts applyFollowedBlockSignal 参数
+ * @returns {Promise<boolean>} 是否已应用
+ */
+export async function applyBlockReputationSignal(opts) {
+	if (!blockReputationHandler) return false
+	return blockReputationHandler(opts)
+}

package/node/retention_policy.mjs

@@ -0,0 +1,82 @@
+import { sortedPrevEventIds } from '../dag/index.mjs'
+import {
+	authzFoldOrderIds,
+	descendantClosureFromTip,
+} from '../governance/branch.mjs'
+import { getPermissionAnchorTypes } from '../registries/event_type.mjs'
+
+/**
+ * @param {string[]} order 拓扑序 id 列表
+ * @param {Map<string, object>} byId id → 事件
+ * @returns {number} 最早须保留的事件下标
+ */
+export function permissionAnchorStartIndex(order, byId) {
+	let anchor = order.length
+	for (let index = order.length - 1; index >= 0; index--) {
+		const ev = byId.get(order[index])
+		if (ev && getPermissionAnchorTypes().has(ev.type)) anchor = index
+	}
+	return anchor
+}
+
+/**
+ * 在共识分支上计算须保留的事件 id（连通子图，不用拓扑下标切片）。
+ * @param {string[]} order 规范拓扑序
+ * @param {Map<string, object>} byId id → 事件
+ * @param {object} opts 保留策略
+ * @param {number} opts.maxDepth 分支上最大事件深度
+ * @param {number} opts.cutoffWall 最早保留的 HLC wall
+ * @param {Set<string>} opts.anchorTypes 权限锚点事件类型
+ * @param {string | null} [opts.checkpointTipId] checkpoint 尖
+ * @param {string | null} [opts.branchTipId] 共识分支尖
+ * @returns {Set<string>} 保留 id
+ */
+export function computeRetentionKeepIds(order, byId, opts) {
+	const { maxDepth, cutoffWall, anchorTypes, checkpointTipId, branchTipId } = opts
+	const branchOrder = authzFoldOrderIds(order, byId, branchTipId)
+	const branchSet = new Set(branchOrder)
+	if (!branchSet.size) return new Set()
+
+	/** @type {Set<string>} */
+	const keep = new Set()
+	/** @type {Set<string>} */
+	const ancestorSeeds = new Set()
+
+	if (checkpointTipId && branchSet.has(checkpointTipId))
+		for (const id of descendantClosureFromTip(checkpointTipId, byId))
+			if (branchSet.has(id)) keep.add(id)
+
+	for (let index = branchOrder.length - 1; index >= 0; index--) {
+		const ev = byId.get(branchOrder[index])
+		if (ev && anchorTypes.has(ev.type)) {
+			ancestorSeeds.add(branchOrder[index])
+			break
+		}
+	}
+
+	for (const id of branchOrder) {
+		const ev = byId.get(id)
+		const wall = Number(ev?.hlc?.wall ?? 0)
+		if (wall >= cutoffWall) ancestorSeeds.add(id)
+	}
+
+	if (branchOrder.length > maxDepth)
+		for (const id of branchOrder.slice(-maxDepth))
+			ancestorSeeds.add(id)
+
+	const stack = [...ancestorSeeds]
+	while (stack.length) {
+		const id = stack.pop()
+		if (!id || !branchSet.has(id) || keep.has(id)) continue
+		keep.add(id)
+		const event = byId.get(id)
+		if (!event) continue
+		for (const parentId of sortedPrevEventIds(event.prev_event_ids))
+			if (branchSet.has(parentId)) stack.push(parentId)
+	}
+
+	if (!keep.size)
+		for (const id of branchOrder) keep.add(id)
+
+	return keep
+}

package/node/signaling_config.mjs

@@ -0,0 +1,32 @@
+import process from 'node:process'
+
+/** @typedef {'none' | 'rewrite-loopback' | 'drop'} MdnsCandidatePolicy */
+
+/**
+ * @typedef {{
+ *   relayOverride: string[] | null
+ *   mdnsPolicy: MdnsCandidatePolicy
+ *   trickleIceOff: boolean
+ * }} SignalingRuntimeConfig
+ */
+
+/**
+ * 生产默认：win32 丢弃 .local host candidate；其它平台不过滤。
+ * @returns {SignalingRuntimeConfig} 生产默认信令配置
+ */
+export function defaultSignalingRuntimeConfig() {
+	const mdnsPolicy = process.platform === 'win32' ? 'drop' : 'none'
+	return {
+		relayOverride: null,
+		mdnsPolicy,
+		trickleIceOff: mdnsPolicy !== 'none',
+	}
+}
+
+/**
+ * 生产默认信令配置；测试通过 initNode({ signaling }) 注入。
+ * @returns {SignalingRuntimeConfig} 生产默认信令配置
+ */
+export function resolveSignalingRuntimeConfig() {
+	return defaultSignalingRuntimeConfig()
+}

package/node/storage.mjs

@@ -0,0 +1,30 @@
+import path from 'node:path'
+
+import { readJsonFileSync, writeJsonFileSync } from '../utils/json_io.mjs'
+
+import { getNodeDir } from './instance.mjs'
+
+/**
+ * @param {string} name 不含扩展名的配置文件名
+ * @returns {string} 绝对路径
+ */
+export function nodeJsonPath(name) {
+	return path.join(getNodeDir(), `${name}.json`)
+}
+
+/**
+ * @param {string} name 配置文件名
+ * @returns {object | null} 解析后的 JSON 或 null
+ */
+export function readNodeJsonSync(name) {
+	return readJsonFileSync(nodeJsonPath(name))
+}
+
+/**
+ * @param {string} name 配置文件名
+ * @param {unknown} data 数据
+ * @returns {void}
+ */
+export function writeNodeJsonSync(name, data) {
+	writeJsonFileSync(nodeJsonPath(name), data)
+}

package/node/storage_plugins.mjs

@@ -0,0 +1,71 @@
+import { mkdir, writeFile, readFile, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * 群组分块存储插件：put/get/delete + 不透明 storageLocator。
+ * S3、多副本等后端由 shell 注入实现，本包只提供本地参考实现。
+ *
+ * @typedef {{
+ *   putChunk: (groupId: string, chunkHash: string, data: Uint8Array) => Promise<{ storageLocator: string }>,
+ *   getChunk: (locator: string) => Promise<Uint8Array>,
+ *   deleteChunk: (locator: string) => Promise<void>,
+ * }} GroupStoragePlugin
+ */
+
+/**
+ * @param {unknown} error 存储删除错误
+ * @returns {boolean} 是否为「文件不存在」
+ */
+function isEnoent(error) {
+	return /** @type {{ code?: string }} */ error?.code === 'ENOENT'
+}
+
+/**
+ * 默认：本地目录 {baseDir}/groups/{groupId}/chunks/（baseDir 一般为用户 shells/chat）
+ *
+ * @param {string} baseDir 绝对路径
+ * @returns {GroupStoragePlugin} 本地文件系统实现的 put/get/delete
+ */
+export function createLocalStoragePlugin(baseDir) {
+	return {
+		storagePeerId: 'local',
+		/**
+		 * @param {string} groupId 群组 id
+		 * @param {string} chunkHash 分块内容哈希（文件名）
+		 * @param {Uint8Array} data 原始字节
+		 * @returns {Promise<{ storageLocator: string }>} `local:` 前缀的定位符
+		 */
+		async putChunk(groupId, chunkHash, data) {
+			const dir = join(baseDir, 'groups', groupId, 'chunks')
+			await mkdir(dir, { recursive: true })
+			const name = `${chunkHash}.bin`
+			await writeFile(join(dir, name), data)
+			return { storageLocator: `local:${groupId}/chunks/${name}` }
+		},
+		/**
+		 * @param {string} locator `local:...` 格式
+		 * @returns {Promise<Uint8Array>} 文件内容
+		 */
+		async getChunk(locator) {
+			const localLocatorMatch = String(locator).match(/^local:([^/]+)\/chunks\/(.+)$/)
+			if (!localLocatorMatch) throw new Error('Invalid local locator')
+			const chunkPath = join(baseDir, 'groups', localLocatorMatch[1], 'chunks', localLocatorMatch[2])
+			return new Uint8Array(await readFile(chunkPath))
+		},
+		/**
+		 * @param {string} locator `local:...` 格式
+		 * @returns {Promise<void>}
+		 */
+		async deleteChunk(locator) {
+			const localLocatorMatch = String(locator).match(/^local:([^/]+)\/chunks\/(.+)$/)
+			if (!localLocatorMatch) return
+			const chunkPath = join(baseDir, 'groups', localLocatorMatch[1], 'chunks', localLocatorMatch[2])
+			try {
+				await unlink(chunkPath)
+			}
+			catch (error) {
+				if (!isEnoent(error)) throw error
+			}
+		},
+	}
+}

package/node/user_paths.mjs

@@ -0,0 +1,10 @@
+import path from 'node:path'
+
+import { getNodeDir } from './instance.mjs'
+
+/**
+ * @returns {string} P2P 邮箱存储转发 JSONL 路径
+ */
+export function mailboxStorePath() {
+	return path.join(getNodeDir(), 'mailbox', 'store.jsonl')
+}