@steve02081504/fount-p2p 0.0.0

package/files/chunk_store.mjs

@@ -0,0 +1,87 @@
+import { Buffer } from 'node:buffer'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { Readable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+
+import { isHex64 } from '../core/hexIds.mjs'
+import { getNodeDir } from '../node/instance.mjs'
+
+/**
+ * @returns {string} `{nodeDir}/chunks`
+ */
+export function chunkStoreRoot() {
+	return join(getNodeDir(), 'chunks')
+}
+
+/**
+ * @param {string} hash 64 位十六进制 ciphertextHash
+ * @returns {string} 块文件绝对路径
+ */
+export function chunkStorePath(hash) {
+	const chunkHash = String(hash).trim().toLowerCase()
+	if (!isHex64(chunkHash)) throw new Error('invalid chunk hash')
+	return join(chunkStoreRoot(), chunkHash.slice(0, 2), `${chunkHash}.bin`)
+}
+
+/**
+ * @param {string} hash 64 位十六进制
+ * @returns {Promise<boolean>} 本地是否存在
+ */
+export async function hasChunk(hash) {
+	try {
+		await fsp.access(chunkStorePath(hash))
+		return true
+	}
+	catch {
+		return false
+	}
+}
+
+/**
+ * @param {string} hash 64 位十六进制
+ * @returns {Promise<Buffer>} 块字节
+ */
+export async function getChunk(hash) {
+	return fsp.readFile(chunkStorePath(hash))
+}
+
+/**
+ * @param {string} hash 64 位十六进制
+ * @returns {import('node:fs').ReadStream} 可读流
+ */
+export function createChunkReadStream(hash) {
+	return fs.createReadStream(chunkStorePath(hash))
+}
+
+/**
+ * @param {string} hash 64 位十六进制
+ * @param {string | Buffer | Uint8Array} data 块数据
+ * @returns {Promise<void>}
+ */
+export async function putChunk(hash, data) {
+	const filePath = chunkStorePath(hash)
+	await fsp.mkdir(dirname(filePath), { recursive: true })
+	await fsp.writeFile(filePath, Buffer.from(data))
+}
+
+/**
+ * @param {string} hash 64 位十六进制
+ * @param {import('node:stream').Readable} readable 密文流
+ * @returns {Promise<void>}
+ */
+export async function putChunkFromStream(hash, readable) {
+	const filePath = chunkStorePath(hash)
+	await fsp.mkdir(dirname(filePath), { recursive: true })
+	const writable = fs.createWriteStream(filePath)
+	await pipeline(readable, writable)
+}
+
+/**
+ * @param {string} hash 64 位十六进制
+ * @returns {Readable} chunk 可读流
+ */
+export function chunkToReadable(hash) {
+	return createChunkReadStream(hash)
+}

package/files/manifest.mjs

@@ -0,0 +1,99 @@
+import { isEntityHash128 } from '../core/entity_id.mjs'
+import { isHex64 } from '../core/hexIds.mjs'
+
+/** @typedef {'plain' | 'convergent' | 'random'} CeMode */
+
+/** @typedef {{ hash: string, size: number }} ManifestPart */
+
+/**
+ * @typedef {{
+ *   type: 'public' | 'file-master-key-wrap' | 'vault-wrap' | 'identity-wrap',
+ *   wrappedKey?: { iv: string, ciphertext: string, authTag: string },
+ *   groupId?: string,
+ *   fileId?: string,
+ *   entityHash?: string,
+ *   keyGeneration?: number,
+ * }} TransferKeyDescriptor
+ */
+
+/**
+ * @typedef {{
+ *   ownerEntityHash: string,
+ *   logicalPath: string,
+ *   name: string,
+ *   mimeType: string,
+ *   size: number,
+ *   contentHash: string,
+ *   ceMode: CeMode,
+ *   parts: ManifestPart[],
+ *   transferKeyDescriptor: TransferKeyDescriptor,
+ *   meta?: object,
+ * }} FileManifest
+ */
+
+const CE_MODES = new Set(['plain', 'convergent', 'random'])
+const TRANSFER_TYPES = new Set(['public', 'file-master-key-wrap', 'vault-wrap', 'identity-wrap'])
+
+/**
+ * @param {unknown} input 原始对象
+ * @returns {FileManifest | null} 校验后的 manifest
+ */
+export function normalizeFileManifest(input) {
+	if (!input || typeof input !== 'object') return null
+	const ownerEntityHash = String(input.ownerEntityHash || '').trim().toLowerCase()
+	if (!isEntityHash128(ownerEntityHash)) return null
+	const logicalPath = String(input.logicalPath || '').trim().replace(/^\/+/, '').replace(/\\/g, '/')
+	if (!logicalPath) return null
+	const ceMode = String(input.ceMode || 'convergent')
+	if (!CE_MODES.has(ceMode)) return null
+	const parts = Array.isArray(input.parts)
+		? input.parts
+			.map(part => ({ hash: String(part?.hash || '').trim().toLowerCase(), size: Number(part?.size) || 0 }))
+			.filter(part => isHex64(part.hash))
+		: []
+	if (!parts.length) return null
+	const transferKeyDescriptor = normalizeTransferKeyDescriptor(input.transferKeyDescriptor)
+	if (!transferKeyDescriptor) return null
+	return {
+		ownerEntityHash,
+		logicalPath,
+		name: String(input.name || logicalPath.split('/').pop() || 'file'),
+		mimeType: String(input.mimeType || 'application/octet-stream'),
+		size: Number(input.size) || 0,
+		contentHash: String(input.contentHash || '').trim().toLowerCase(),
+		ceMode: /** @type {CeMode} */ ceMode,
+		parts,
+		transferKeyDescriptor,
+		meta: input.meta?.constructor === Object ? { ...input.meta } : undefined,
+	}
+}
+
+/**
+ * @param {unknown} input 描述符
+ * @returns {TransferKeyDescriptor | null} 校验后的传输密钥描述符
+ */
+export function normalizeTransferKeyDescriptor(input) {
+	if (!input || typeof input !== 'object') return null
+	const type = String(input.type || '').trim()
+	if (!TRANSFER_TYPES.has(type)) return null
+	/** @type {TransferKeyDescriptor} */
+	const out = { type: /** @type {TransferKeyDescriptor['type']} */ type }
+	if (input.wrappedKey?.constructor === Object)
+		out.wrappedKey = {
+			iv: String(input.wrappedKey.iv || ''),
+			ciphertext: String(input.wrappedKey.ciphertext || ''),
+			authTag: String(input.wrappedKey.authTag || ''),
+		}
+	if (input.groupId) out.groupId = String(input.groupId).trim()
+	if (input.fileId) out.fileId = String(input.fileId).trim()
+	if (input.entityHash) out.entityHash = String(input.entityHash).trim().toLowerCase()
+	if (input.keyGeneration != null) out.keyGeneration = Number(input.keyGeneration) || 0
+	return out
+}
+
+/**
+ * @returns {TransferKeyDescriptor} public 描述符
+ */
+export function publicTransferKeyDescriptor() {
+	return { type: 'public' }
+}

package/files/transfer_key.mjs

@@ -0,0 +1,87 @@
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+
+import {
+	decryptConvergentCiphertext,
+	decryptRandomCiphertext,
+	unwrapContentKey,
+} from '../crypto/key.mjs'
+
+/**
+ * @typedef {import('./manifest.mjs').FileManifest} FileManifest
+ * @typedef {import('./manifest.mjs').TransferKeyDescriptor} TransferKeyDescriptor
+ */
+
+/**
+ * @param {TransferKeyDescriptor} descriptor 传递密钥描述符
+ * @param {FileManifest} manifest manifest
+ * @param {{ getGroupFileMasterKey?: (groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (entityHash: string) => Promise<Buffer | string | null> }} deps 密钥源
+ * @returns {Promise<Buffer | null>} contentKey；plain/convergent 返回 null（按 contentHash 派生）
+ */
+export async function resolveContentKey(descriptor, manifest, deps = {}) {
+	const type = descriptor?.type || 'public'
+	if (type === 'public' || manifest.ceMode === 'plain' || manifest.ceMode === 'convergent')
+		return null
+
+	if (type === 'file-master-key-wrap') {
+		const groupId = descriptor.groupId
+		const fileId = descriptor.fileId
+		if (!groupId || !fileId || !descriptor.wrappedKey || !deps.getGroupFileMasterKey) return null
+		const groupKey = await deps.getGroupFileMasterKey(String(groupId), descriptor.keyGeneration)
+		if (!groupKey) return null
+		return unwrapContentKey(descriptor.wrappedKey, groupKey, fileId)
+	}
+
+	if (type === 'vault-wrap') {
+		const entityHash = descriptor.entityHash
+		const fileId = descriptor.fileId
+		if (!entityHash || !fileId || !descriptor.wrappedKey || !deps.getVaultMasterKey) return null
+		const vaultKey = await deps.getVaultMasterKey(String(entityHash))
+		if (!vaultKey) return null
+		return unwrapContentKey(descriptor.wrappedKey, vaultKey, fileId)
+	}
+
+	return null
+}
+
+/**
+ * @param {Buffer | Uint8Array} encryptedPartBytes 密文块
+ * @param {FileManifest} manifest manifest
+ * @param {Buffer | null} contentKey random 模式密钥
+ * @returns {Buffer | null} 明文
+ */
+export function decryptPart(encryptedPartBytes, manifest, contentKey) {
+	if (manifest.ceMode === 'plain')
+		return Buffer.from(encryptedPartBytes)
+
+	if (manifest.ceMode === 'convergent')
+		return decryptConvergentCiphertext(encryptedPartBytes, manifest.contentHash)
+
+	if (manifest.ceMode === 'random' && contentKey)
+		return decryptRandomCiphertext(encryptedPartBytes, contentKey, manifest.contentHash)
+
+	return null
+}
+
+/**
+ * @param {FileManifest} manifest manifest
+ * @param {Array<Buffer | Uint8Array>} partBytes 按序密文块
+ * @param {{ getGroupFileMasterKey?: Function, getVaultMasterKey?: Function }} deps 密钥源
+ * @returns {Promise<Buffer | null>} 完整明文
+ */
+export async function assembleManifestPlaintext(manifest, partBytes, deps = {}) {
+	if (partBytes.length !== manifest.parts.length) return null
+	const contentKey = await resolveContentKey(manifest.transferKeyDescriptor, manifest, deps)
+	/** @type {Buffer[]} */
+	const plains = []
+	for (let index = 0; index < manifest.parts.length; index++) {
+		const plain = decryptPart(partBytes[index], manifest, contentKey)
+		if (!plain) return null
+		plains.push(plain)
+	}
+	const merged = Buffer.concat(plains)
+	if (manifest.contentHash)
+		if (createHash('sha256').update(merged).digest('hex') !== manifest.contentHash.toLowerCase()) return null
+
+	return merged
+}

package/files/transfer_key_registry.mjs

@@ -0,0 +1,108 @@
+/** @type {Map<string, { getGroupFileMasterKey?: (replicaUsername: string, groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (replicaUsername: string, entityHash: string) => Promise<Buffer | string | null> }>} */
+const transferDepsByOwner = new Map()
+
+/** @type {Map<string, (replicaUsername: string, manifest: import('./manifest.mjs').FileManifest) => Promise<Buffer | null>>} */
+const dagPlaintextReadersByOwner = new Map()
+
+/**
+ * @param {string} ownerId 注册方
+ * @param {{ getGroupFileMasterKey?: (replicaUsername: string, groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (replicaUsername: string, entityHash: string) => Promise<Buffer | string | null> }} deps 密钥源
+ * @returns {void}
+ */
+export function registerTransferKeyDeps(ownerId, deps) {
+	const key = String(ownerId)
+	const prev = transferDepsByOwner.get(key) || {}
+	transferDepsByOwner.set(key, { ...prev, ...deps })
+}
+
+/**
+ * @param {string} ownerId 注册方
+ * @param {(replicaUsername: string, manifest: import('./manifest.mjs').FileManifest) => Promise<Buffer | null>} reader dagParts 明文读取
+ * @returns {void}
+ */
+export function registerDagManifestPlaintextReader(ownerId, reader) {
+	dagPlaintextReadersByOwner.set(String(ownerId), reader)
+}
+
+/** @type {Array<{ ownerId: string, match: (manifest: import('./manifest.mjs').FileManifest) => boolean }>} */
+const manifestOwnerMatchers = []
+
+/**
+ * @param {string} ownerId 注册方
+ * @param {(manifest: import('./manifest.mjs').FileManifest) => boolean} match manifest 匹配谓词
+ * @returns {void}
+ */
+export function registerManifestOwnerMatcher(ownerId, match) {
+	manifestOwnerMatchers.push({ ownerId: String(ownerId), match })
+}
+
+/**
+ * @param {string} ownerId 注册方
+ * @returns {void}
+ */
+export function unregisterManifestOwnerMatchers(ownerId) {
+	const id = String(ownerId)
+	for (let i = manifestOwnerMatchers.length - 1; i >= 0; i--)
+		if (manifestOwnerMatchers[i].ownerId === id) manifestOwnerMatchers.splice(i, 1)
+}
+
+/**
+ * @param {string} ownerId 注册方
+ * @returns {void}
+ */
+export function unregisterTransferKeyDeps(ownerId) {
+	const key = String(ownerId)
+	transferDepsByOwner.delete(key)
+	dagPlaintextReadersByOwner.delete(key)
+	unregisterManifestOwnerMatchers(key)
+}
+
+/** @returns {void} */
+export function clearTransferKeyRegistry() {
+	transferDepsByOwner.clear()
+	dagPlaintextReadersByOwner.clear()
+	manifestOwnerMatchers.length = 0
+}
+
+/**
+ * 从 manifest 推断 transfer key 注册方 id（按 registerManifestOwnerMatcher 注册顺序匹配）。
+ * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @returns {string | null} 所有者 id
+ */
+export function resolveManifestTransferOwnerId(manifest) {
+	for (const { ownerId, match } of manifestOwnerMatchers)
+		if (match(manifest)) return ownerId
+	return null
+}
+
+/**
+ * @param {string} [ownerId] 显式注册方；省略时按 manifest 推断
+ * @param {import('./manifest.mjs').FileManifest} [manifest] 用于推断 ownerId
+ * @returns {{ getGroupFileMasterKey?: (replicaUsername: string, groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (replicaUsername: string, entityHash: string) => Promise<Buffer | string | null> }} 依赖
+ */
+export function resolveTransferKeyDeps(ownerId, manifest) {
+	const resolved = ownerId || (manifest ? resolveManifestTransferOwnerId(manifest) : null)
+	if (resolved) return transferDepsByOwner.get(String(resolved)) || {}
+	return {}
+}
+
+/**
+ * @param {string} replicaUsername 副本用户名
+ * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @returns {Promise<Buffer | null>} 明文；无 reader 或未命中为 null
+ */
+export async function readDagManifestPlaintext(replicaUsername, manifest) {
+	const ownerId = resolveManifestTransferOwnerId(manifest)
+	if (ownerId) {
+		const reader = dagPlaintextReadersByOwner.get(ownerId)
+		if (reader)
+			try {
+				const buf = await reader(replicaUsername, manifest)
+				if (buf?.length) return buf
+			}
+			catch { /* fall through */ }
+		return null
+	}
+
+	return null
+}

package/governance/branch.mjs

@@ -0,0 +1,230 @@
+import { sortedPrevEventIds } from '../dag/index.mjs'
+import { getGovernanceAuthzTypes } from '../registries/event_type.mjs'
+
+/**
+ * 事件是否存在指向本地缺失父的悬挂引用（DAG 不完整）。
+ * @param {Array<{ id: string, prev_event_ids?: unknown }>} events 事件列表
+ * @returns {boolean} 存在悬挂父则为 true
+ */
+export function hasDanglingParents(events) {
+	if (!events.length) return false
+	const byId = new Map(events.map(event => [event.id, event]))
+	for (const event of events)
+		for (const parentId of sortedPrevEventIds(event.prev_event_ids))
+			if (!byId.has(parentId)) return true
+	return false
+}
+
+/**
+ * 计算 DAG 叶事件 id。
+ * @param {Array<{ id: string, prev_event_ids?: unknown }>} events 事件列表
+ * @returns {string[]} 叶 id 列表
+ */
+export function computeDagTipIdsFromEvents(events) {
+	if (!events.length) return []
+	const referenced = new Set()
+	for (const event of events)
+		for (const parentId of sortedPrevEventIds(event.prev_event_ids))
+			referenced.add(parentId)
+
+	const tips = []
+	for (const event of events)
+		if (event.id && !referenced.has(event.id)) tips.push(event.id)
+	return tips
+}
+
+/**
+ * 从 tip 沿父指针闭包祖先 id。
+ * @param {string} tipId 叶事件 id
+ * @param {Map<string, { id: string, prev_event_ids?: unknown }>} byId id→事件
+ * @returns {Set<string>} 祖先 id 集
+ */
+export function ancestorClosureFromTip(tipId, byId) {
+	const out = new Set()
+	const stack = [tipId]
+	while (stack.length) {
+		const id = stack.pop()
+		if (!id || out.has(id)) continue
+		out.add(id)
+		const event = byId.get(id)
+		if (!event) continue
+		for (const parentId of sortedPrevEventIds(event.prev_event_ids))
+			if (byId.has(parentId)) stack.push(parentId)
+	}
+	return out
+}
+
+/**
+ * 构建 id → 子事件 id 列表（仅含图内边）。
+ * @param {Map<string, { id: string, prev_event_ids?: unknown }>} byId id→事件
+ * @returns {Map<string, string[]>} 父 id → 子 id 列表
+ */
+export function buildDagChildrenMap(byId) {
+	/** @type {Map<string, string[]>} */
+	const children = new Map()
+	for (const event of byId.values())
+		for (const parentId of sortedPrevEventIds(event.prev_event_ids)) {
+			if (!byId.has(parentId)) continue
+			const list = children.get(parentId)
+			if (list) list.push(event.id)
+			else children.set(parentId, [event.id])
+		}
+
+	return children
+}
+
+/**
+ * 从根沿子指针正向闭包（checkpoint 之后保留的后缀）。
+ * @param {string} rootId 根事件 id（通常为 checkpoint_event_id）
+ * @param {Map<string, { id: string, prev_event_ids?: unknown }>} byId id→事件
+ * @returns {Set<string>} 根及其后代 id
+ */
+export function descendantClosureFromTip(rootId, byId) {
+	if (!rootId || !byId.has(rootId)) return new Set()
+	const children = buildDagChildrenMap(byId)
+	const out = new Set()
+	const stack = [rootId]
+	while (stack.length) {
+		const id = stack.pop()
+		if (!id || out.has(id)) continue
+		out.add(id)
+		for (const childId of children.get(id) || []) stack.push(childId)
+	}
+	return out
+}
+
+/**
+ * 事件是否在 root 的后代闭包中（含 root）。
+ * @param {string} eventId 事件 id
+ * @param {string} rootId 根 id
+ * @param {Map<string, object>} byId id→事件
+ * @returns {boolean} 是否为 root 的后代（含 root 自身）
+ */
+export function isDescendantOfTip(eventId, rootId, byId) {
+	return descendantClosureFromTip(rootId, byId).has(eventId)
+}
+
+/**
+ * @param {string} tipId 叶 id
+ * @param {Map<string, object>} byId id→事件
+ * @param {Record<string, number>} reputationBySender 发送方主观信誉
+ * @returns {number} 该叶上治理事件信誉加权和
+ */
+function governanceAuthzScoreForTip(tipId, byId, reputationBySender) {
+	let score = 0
+	for (const eventId of ancestorClosureFromTip(tipId, byId)) {
+		const event = byId.get(eventId)
+		if (!event || !getGovernanceAuthzTypes().has(event.type)) continue
+		const sender = String(event.sender).trim().toLowerCase()
+		if (sender) score += Number(reputationBySender[sender] ?? 0)
+	}
+	return score
+}
+
+/**
+ * 纯客观选支：仅统计治理事件数量，同分按 tipId 字典序（不读本地信誉）。
+ * @param {string[]} tips 当前叶 id 列表
+ * @param {Map<string, object>} byId id→事件
+ * @returns {string | null} 选定 tip
+ */
+export function selectConsensusBranchTip(tips, byId) {
+	if (!tips.length) return null
+	if (tips.length === 1) return tips[0]
+	let best = tips[0]
+	let bestScore = -Infinity
+	for (const tip of tips) {
+		let score = 0
+		for (const eventId of ancestorClosureFromTip(tip, byId)) {
+			const event = byId.get(eventId)
+			if (event && getGovernanceAuthzTypes().has(event.type)) score++
+		}
+		if (score > bestScore || (score === bestScore && tip > best)) {
+			bestScore = score
+			best = tip
+		}
+	}
+	return best
+}
+
+/**
+ * 主观选支（仅 UI 预览 `localViewBranchTip`；checkpoint/联邦/ACL 必须用 consensus）。
+ * @param {string[]} tips 当前叶 id 列表
+ * @param {Map<string, object>} byId id→事件
+ * @param {Record<string, number>} [reputationBySender] 发送方主观信誉
+ * @param {string | null} [preferredTipId] 用户显式选支
+ * @returns {string | null} 选定 tip
+ */
+export function selectAuthzBranchTip(tips, byId, reputationBySender = {}, preferredTipId = null) {
+	if (!tips.length) return null
+	if (preferredTipId && tips.includes(preferredTipId)) return preferredTipId
+	if (tips.length === 1) return tips[0]
+
+	let best = tips[0]
+	let bestScore = -Infinity
+	for (const tip of tips) {
+		const score = governanceAuthzScoreForTip(tip, byId, reputationBySender)
+		if (score > bestScore || (score === bestScore && tip > best)) {
+			bestScore = score
+			best = tip
+		}
+	}
+	return best
+}
+
+/**
+ * 为每个 DAG 叶计算治理事件信誉加权和（§8 选支可视化）。
+ * @param {string[]} tips 叶 id 列表
+ * @param {Map<string, object>} byId id→事件
+ * @param {Record<string, number>} [reputationBySender] 发送方主观信誉
+ * @returns {Record<string, number>} tipId → 分数
+ */
+export function computeTipAuthzScores(tips, byId, reputationBySender = {}) {
+	/** @type {Record<string, number>} */
+	const out = {}
+	for (const tip of tips)
+		out[tip] = governanceAuthzScoreForTip(tip, byId, reputationBySender)
+	return out
+}
+
+/**
+ * 为每个 DAG 叶计算客观治理计数分（用于共识分支可视化）。
+ * @param {string[]} tips 叶 id 列表
+ * @param {Map<string, object>} byId id→事件
+ * @returns {Record<string, number>} tipId → 客观分
+ */
+export function computeTipConsensusScores(tips, byId) {
+	/** @type {Record<string, number>} */
+	const out = {}
+	for (const tip of tips) {
+		let score = 0
+		for (const eventId of ancestorClosureFromTip(tip, byId)) {
+			const event = byId.get(eventId)
+			if (event && getGovernanceAuthzTypes().has(event.type)) score++
+		}
+		out[tip] = score
+	}
+	return out
+}
+
+/**
+ * 规范拓扑序中属于选定分支的事件 id。
+ * @param {string[]} topologicalOrder 拓扑序 id 列表
+ * @param {Map<string, object>} byId id→事件
+ * @param {string | null} branchTipId 分支尖
+ * @returns {string[]} 可折叠的 id 子序列
+ */
+export function authzFoldOrderIds(topologicalOrder, byId, branchTipId) {
+	if (!branchTipId) return topologicalOrder
+	const allowed = ancestorClosureFromTip(branchTipId, byId)
+	return topologicalOrder.filter(id => allowed.has(id))
+}
+
+/**
+ * 是否存在未合并的治理分叉。
+ * @param {string[]} tips DAG 叶列表
+ * @param {string | null} branchTipId 当前权限分支尖
+ * @returns {boolean} 多叶且已选支时为 true
+ */
+export function hasGovernanceFork(tips, branchTipId) {
+	return tips.length > 1 && !!branchTipId
+}