@steve02081504/fount-p2p 0.0.2 → 0.0.3

package/entity/files/evfs.mjs

@@ -187,3 +187,22 @@ export async function putFileManifestFromStream(params) {
 	await saveFileManifest(manifest)
 	return manifest
 }
+
+/**
+ * 读取实体公开文件：本地 miss 时经网络取回签名 manifest，chunk miss 走既有 fetchChunk。
+ * @param {string} replicaUsername 副本用户名
+ * @param {string} entityHash owner entityHash
+ * @param {string} logicalPath EVFS 逻辑路径
+ * @param {{ username?: string, fetchChunk?: Function }} [opts] miss 拉取
+ * @returns {Promise<Buffer | null>} 明文或 null
+ */
+export async function readPublicFile(replicaUsername, entityHash, logicalPath, opts = {}) {
+	const { fetchPublicManifest } = await import('../../files/manifest_fetch.mjs')
+	const manifest = await fetchPublicManifest({
+		username: opts.username || replicaUsername,
+		ownerEntityHash: entityHash,
+		logicalPath,
+	})
+	if (!manifest) return null
+	return readManifestPlaintext(replicaUsername, manifest, opts)
+}

package/federation/manifest_fetch_pending.mjs

@@ -0,0 +1,90 @@
+import { verifySignedPublicManifest } from '../files/public_manifest.mjs'
+
+/** @type {Map<string, { expectedKey: string, timer: ReturnType<typeof setTimeout>, resolve: (v: object | null) => void }>} */
+export const pendingManifestFetches = new Map()
+
+/**
+ *
+ */
+export const MAX_PENDING_MANIFEST_FETCHES = 512
+
+/**
+ * @param {string} ownerEntityHash owner
+ * @param {string} logicalPath 路径
+ * @returns {string} 期望键
+ */
+export function manifestFetchExpectedKey(ownerEntityHash, logicalPath) {
+	return `${String(ownerEntityHash || '').trim().toLowerCase()}\0${String(logicalPath || '').trim().replace(/^\/+/, '')}`
+}
+
+/**
+ * @param {string} key requestId
+ * @param {string} expectedKey owner+path 复合键
+ * @param {number} timeoutMs 超时毫秒
+ * @returns {{ done: Promise<object | null>, cancel: () => void }} 等待 Promise 与取消
+ */
+export function registerManifestFetchWait(key, expectedKey, timeoutMs) {
+	if (!key || pendingManifestFetches.size >= MAX_PENDING_MANIFEST_FETCHES)
+		return {
+			done: Promise.resolve(null),
+			/**
+			 *
+			 */
+			cancel: () => { },
+		}
+
+	/** @type {(value: object | null) => void} */
+	let settle
+	const done = new Promise(resolve => {
+		settle = resolve
+	})
+	const timer = setTimeout(() => {
+		pendingManifestFetches.delete(key)
+		settle(null)
+	}, timeoutMs)
+
+	pendingManifestFetches.set(key, {
+		expectedKey,
+		timer,
+		/**
+		 * @param {object | null} value 验签后的 manifest，超时/取消为 null
+		 */
+		resolve: value => {
+			clearTimeout(timer)
+			pendingManifestFetches.delete(key)
+			settle(value)
+		},
+	})
+
+	return {
+		done,
+		/**
+		 *
+		 */
+		cancel: () => {
+			clearTimeout(timer)
+			pendingManifestFetches.delete(key)
+			settle(null)
+		},
+	}
+}
+
+/**
+ * 处理 fed_manifest_data：验签通过后 resolve pending。
+ * @param {object} payload 入站载荷
+ * @returns {Promise<boolean>} 是否命中并完成等待
+ */
+export async function resolvePendingManifestFetch(payload) {
+	const requestId = String(payload?.requestId || '')
+	if (!requestId) return false
+	const entry = pendingManifestFetches.get(requestId)
+	if (!entry) return false
+
+	const verified = await verifySignedPublicManifest(payload?.manifest)
+	if (!verified) return false
+	const key = manifestFetchExpectedKey(verified.ownerEntityHash, verified.logicalPath)
+	if (key !== entry.expectedKey) return false
+
+	entry.resolve(verified)
+	return true
+}

package/files/chunk_fetch.mjs

@@ -1,19 +1,16 @@
 import { randomUUID } from 'node:crypto'
 
 import { u8ToB64 } from '../core/bytes_codec.mjs'
-import { FEDERATION_CHUNK_FETCH_FANOUT_K } from '../core/constants.mjs'
 import {
 	MAX_PENDING_CHUNK_FETCHES,
 	pendingChunkFetches,
 	registerChunkFetchWait,
 } from '../federation/chunk_fetch_pending.mjs'
-import { loadNetwork } from '../node/network.mjs'
-import { ensureLinkToNode, listLinks } from '../transport/link_registry.mjs'
-import { DEFAULT_TRUST_GRAPH_OWNER, requireTrustGraphProvider } from '../trust_graph/registry.mjs'
 
 import { verifiedChunkBytes } from './chunk_fetch_verify.mjs'
 import { fetchFederationChunk, resolveNodeHash } from './chunk_provider_registry.mjs'
 import { getChunk, hasChunk, putChunk } from './chunk_store.mjs'
+import { fanoutFedFetch } from './fetch_fanout.mjs'
 
 /**
  * @typedef {{
@@ -24,22 +21,6 @@ import { getChunk, hasChunk, putChunk } from './chunk_store.mjs'
  * }} FetchChunkContext
  */
 
-/**
- * @returns {string[]} 全局 CAS miss 时应尝试拨号/发送的 nodeHash 列表
- */
-function chunkFetchPeerTargets() {
-	/** @type {Set<string>} */
-	const targets = new Set()
-	for (const { nodeHash } of listLinks())
-		if (nodeHash) targets.add(String(nodeHash).toLowerCase())
-	const net = loadNetwork()
-	for (const nodeHash of [...net.trustedPeers || [], ...net.explorePeers || []])
-		if (nodeHash) targets.add(String(nodeHash).toLowerCase())
-	for (const hint of net.hints || [])
-		if (hint?.nodeHash) targets.add(String(hint.nodeHash).toLowerCase())
-	return [...targets]
-}
-
 /**
  * @param {FetchChunkContext} context 上下文
  * @returns {Promise<Uint8Array | null>} 密文块
@@ -72,19 +53,7 @@ export async function fetchChunk(context) {
 		chunkHash: hash,
 		ownerEntityHash: context.ownerEntityHash,
 	}
-	const graph = await requireTrustGraphProvider(DEFAULT_TRUST_GRAPH_OWNER).buildMergedGraph(username)
-	const peerTargets = chunkFetchPeerTargets()
-	await Promise.all(peerTargets.map(nodeHash => ensureLinkToNode(nodeHash).catch(() => null)))
-	const tg = requireTrustGraphProvider(DEFAULT_TRUST_GRAPH_OWNER)
-	// 已直连 / follow hint peer 可能不在 trust-graph top-K（非成员 emoji CAS / Social 预览路径）。
-	for (const nodeHash of peerTargets)
-		void tg.sendToNode(username, nodeHash, 'fed_chunk_get', payload, graph)
-	await tg.fanoutToTopNodes(
-		username,
-		'fed_chunk_get',
-		payload,
-		FEDERATION_CHUNK_FETCH_FANOUT_K,
-	)
+	await fanoutFedFetch(username, 'fed_chunk_get', payload)
 	const result = await done
 	const verified = verifiedChunkBytes(hash, result)
 	if (verified) {

package/files/chunk_responder.mjs

@@ -1,6 +1,8 @@
 import { resolvePendingChunkFetch } from '../federation/chunk_fetch_pending.mjs'
+import { resolvePendingManifestFetch } from '../federation/manifest_fetch_pending.mjs'
 
 import { handleIncomingChunkGet } from './chunk_fetch.mjs'
+import { handleIncomingManifestGet } from './manifest_fetch.mjs'
 
 /**
  * @param {string} username 副本用户名 用户名
@@ -22,7 +24,26 @@ export function handleFedChunkDataIngress(data) {
 }
 
 /**
- * node scope user-room wire：注册 fed_chunk_get / fed_chunk_data。
+ * @param {string} username 副本用户名
+ * @param {object} data 入站 fed_manifest_get
+ * @param {string} peerId 对端 id
+ * @param {(resp: object, peerId: string) => void} sendManifestData 发送 fed_manifest_data
+ * @returns {Promise<void>}
+ */
+export async function handleFedManifestGetIngress(username, data, peerId, sendManifestData) {
+	await handleIncomingManifestGet(username, data, sendManifestData, peerId)
+}
+
+/**
+ * @param {object} data 入站 fed_manifest_data
+ * @returns {Promise<void>}
+ */
+export async function handleFedManifestDataIngress(data) {
+	await resolvePendingManifestFetch(data)
+}
+
+/**
+ * node scope user-room wire：注册 fed_chunk_* + fed_manifest_*。
  * @param {string} username 副本用户名 用户名
  * @param {{ on: (name: string, handler: (payload: unknown, peerId: string) => void) => void, send: (name: string, payload: unknown, peerId: string | null) => void }} wire action 表
  * @returns {void}
@@ -35,10 +56,19 @@ export function attachNodeScopeFedChunkResponder(username, wire) {
 		})
 	})
 	wire.on('fed_chunk_data', handleFedChunkDataIngress)
+	wire.on('fed_manifest_get', (data, peerId) => {
+		void handleFedManifestGetIngress(username, data, peerId, (resp, pid) => {
+			try { wire.send('fed_manifest_data', resp, pid) }
+			catch { /* disconnected */ }
+		})
+	})
+	wire.on('fed_manifest_data', data => {
+		void handleFedManifestDataIngress(data)
+	})
 }
 
 /**
- * Trystero room：注册带 requestId 的 fed_chunk_get / fed_chunk_data（TrustGraph 全局 miss）。
+ * Trystero room：注册带 requestId 的 fed_chunk_* + fed_manifest_*（TrustGraph 全局 miss）。
  * @param {string} username 用户
  * @param {object} room Trystero room
  * @param {{ enqueue: (prio: number, fn: () => void) => void }} [fedOut] 出站队列
@@ -50,6 +80,8 @@ export function attachNodeScopeFedChunkResponder(username, wire) {
 export function attachTrustGraphFedChunkResponder(username, room, fedOut, guardGet, rtcLimits = {}, roomKey = '') {
 	const [sendChunkData, getChunkData] = room.makeAction('fed_chunk_data')
 	const [, getChunkGet] = room.makeAction('fed_chunk_get')
+	const [sendManifestData, getManifestData] = room.makeAction('fed_manifest_data')
+	const [, getManifestGet] = room.makeAction('fed_manifest_get')
 
 	getChunkGet((data, peerId) => {
 		if (guardGet && !guardGet(roomKey, 'fed_chunk_get', rtcLimits)) return
@@ -76,4 +108,30 @@ export function attachTrustGraphFedChunkResponder(username, room, fedOut, guardG
 		if (!data || typeof data !== 'object' || !data.requestId) return
 		handleFedChunkDataIngress(data)
 	})
+
+	getManifestGet((data, peerId) => {
+		if (guardGet && !guardGet(roomKey, 'fed_manifest_get', rtcLimits)) return
+		void (async () => {
+			if (!data || typeof data !== 'object') return
+			if (!String(data.requestId || '')) return
+			await handleFedManifestGetIngress(username, data, peerId, (resp, pid) => {
+				/**
+				 *
+				 */
+				const send = () => {
+					try { sendManifestData(resp, pid) }
+					catch (error) {
+						console.warn('federation: trust-graph manifest response failed', error)
+					}
+				}
+				if (fedOut) fedOut.enqueue(6, send)
+				else send()
+			})
+		})().catch(error => console.warn('federation: trust-graph manifest handler failed', error))
+	})
+
+	getManifestData(data => {
+		if (!data || typeof data !== 'object' || !data.requestId) return
+		void handleFedManifestDataIngress(data)
+	})
 }

package/files/fetch_fanout.mjs

@@ -0,0 +1,38 @@
+import { FEDERATION_CHUNK_FETCH_FANOUT_K } from '../core/constants.mjs'
+import { loadNetwork } from '../node/network.mjs'
+import { ensureLinkToNode, listLinks } from '../transport/link_registry.mjs'
+import { DEFAULT_TRUST_GRAPH_OWNER, requireTrustGraphProvider } from '../trust_graph/registry.mjs'
+
+/**
+ * @returns {string[]} 全局 miss 时应尝试拨号/发送的 nodeHash 列表
+ */
+function fetchPeerTargets() {
+	/** @type {Set<string>} */
+	const targets = new Set()
+	for (const { nodeHash } of listLinks())
+		if (nodeHash) targets.add(String(nodeHash).toLowerCase())
+	const net = loadNetwork()
+	for (const nodeHash of [...net.trustedPeers || [], ...net.explorePeers || []])
+		if (nodeHash) targets.add(String(nodeHash).toLowerCase())
+	for (const hint of net.hints || [])
+		if (hint?.nodeHash) targets.add(String(hint.nodeHash).toLowerCase())
+	return [...targets]
+}
+
+/**
+ * 全局 miss 请求扇出：先向已知 peer 定向发送，再 trust-graph top-K fanout。
+ * 已直连 / follow hint peer 可能不在 trust-graph top-K（非成员 emoji CAS / Social 预览路径），故先定向发送。
+ * @param {string} username 用户
+ * @param {string} action wire action 名
+ * @param {object} payload 请求载荷
+ * @returns {Promise<void>}
+ */
+export async function fanoutFedFetch(username, action, payload) {
+	const tg = requireTrustGraphProvider(DEFAULT_TRUST_GRAPH_OWNER)
+	const graph = await tg.buildMergedGraph(username)
+	const peerTargets = fetchPeerTargets()
+	await Promise.all(peerTargets.map(nodeHash => ensureLinkToNode(nodeHash).catch(() => null)))
+	for (const nodeHash of peerTargets)
+		void tg.sendToNode(username, nodeHash, action, payload, graph)
+	await tg.fanoutToTopNodes(username, action, payload, FEDERATION_CHUNK_FETCH_FANOUT_K)
+}

package/files/manifest_fetch.mjs

@@ -0,0 +1,97 @@
+import { randomUUID } from 'node:crypto'
+
+import { loadFileManifest, saveFileManifest } from '../entity/files/evfs.mjs'
+import { isWritableLocalEntity } from '../entity/replica.mjs'
+import {
+	manifestFetchExpectedKey,
+	MAX_PENDING_MANIFEST_FETCHES,
+	pendingManifestFetches,
+	registerManifestFetchWait,
+} from '../federation/manifest_fetch_pending.mjs'
+import { getEntityStore } from '../node/instance.mjs'
+
+import { resolveNodeHash } from './chunk_provider_registry.mjs'
+import { fanoutFedFetch } from './fetch_fanout.mjs'
+import { normalizeFileManifest } from './manifest.mjs'
+import { shouldPreferIncomingPublicManifest } from './public_manifest.mjs'
+
+/**
+ * @param {{ username: string, ownerEntityHash: string, logicalPath: string }} context 上下文
+ * @returns {Promise<import('./manifest.mjs').FileManifest | null>} 验签后的公开清单
+ */
+export async function fetchPublicManifest(context) {
+	const ownerEntityHash = String(context.ownerEntityHash || '').trim().toLowerCase()
+	const logicalPath = String(context.logicalPath || '').trim().replace(/^\/+/, '')
+	const { username } = context
+	if (!ownerEntityHash || !logicalPath || !username) return null
+
+	const local = await loadFileManifest(ownerEntityHash, logicalPath)
+	if (local?.transferKeyDescriptor?.type === 'public' && local?.meta?.publicSig)
+		return local
+
+	if (pendingManifestFetches.size >= MAX_PENDING_MANIFEST_FETCHES) return null
+
+	const requestId = randomUUID()
+	const { done } = registerManifestFetchWait(
+		requestId,
+		manifestFetchExpectedKey(ownerEntityHash, logicalPath),
+		8000,
+	)
+	const { nodeHash } = await resolveNodeHash(username)
+	const payload = {
+		requestId,
+		nodeHash,
+		ownerEntityHash,
+		logicalPath,
+	}
+	await fanoutFedFetch(username, 'fed_manifest_get', payload)
+	const result = await done
+	if (!result) return null
+
+	await maybeCacheIncomingPublicManifest(ownerEntityHash, logicalPath, result)
+	return result
+}
+
+/**
+ * @param {string} ownerEntityHash owner
+ * @param {string} logicalPath 路径
+ * @param {import('./manifest.mjs').FileManifest} incoming 已验签入站清单
+ * @returns {Promise<void>}
+ */
+async function maybeCacheIncomingPublicManifest(ownerEntityHash, logicalPath, incoming) {
+	if (isWritableLocalEntity(ownerEntityHash)) return
+	const store = getEntityStore()
+	const existing = await store.readManifest(ownerEntityHash, logicalPath)
+	if (existing && !shouldPreferIncomingPublicManifest(existing, incoming)) return
+	await saveFileManifest(incoming)
+}
+
+/**
+ * 若本机有已签名公开 manifest 则响应 fed_manifest_get。
+ * @param {string} username 用户
+ * @param {object} payload 请求
+ * @param {(response: object, peerId: string) => void} sendResponse 发送
+ * @param {string} peerId 对端
+ * @returns {Promise<void>}
+ */
+export async function handleIncomingManifestGet(username, payload, sendResponse, peerId) {
+	void username
+	const ownerEntityHash = String(payload?.ownerEntityHash || '').trim().toLowerCase()
+	const logicalPath = String(payload?.logicalPath || '').trim().replace(/^\/+/, '')
+	const requestId = String(payload?.requestId || '')
+	if (!ownerEntityHash || !logicalPath || !requestId) return
+
+	const raw = await getEntityStore().readManifest(ownerEntityHash, logicalPath)
+	const manifest = normalizeFileManifest(raw)
+	if (!manifest) return
+	if (manifest.transferKeyDescriptor.type !== 'public') return
+	if (!raw?.meta?.publicSig) return
+
+	sendResponse({
+		requestId,
+		manifest: {
+			...manifest,
+			meta: { publicSig: raw.meta.publicSig },
+		},
+	}, peerId)
+}

package/files/public_manifest.mjs

@@ -0,0 +1,153 @@
+import { Buffer } from 'node:buffer'
+
+import { canonicalStringify } from '../core/canonical_json.mjs'
+import { hashFromPubKeyHex, parseEntityHash } from '../core/entity_id.mjs'
+import { assertSafeEvfsLogicalPath } from '../core/evfs_logical_path.mjs'
+import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
+import { sign, verify } from '../crypto/crypto.mjs'
+
+import { normalizeFileManifest, publicTransferKeyDescriptor } from './manifest.mjs'
+
+/** 实体公开 manifest 签名域 */
+export const ENTITY_PUBLIC_MANIFEST_DOMAIN = 'fount-entity-public-manifest'
+
+/**
+ * @param {object} fields 待签名字段
+ * @returns {Buffer} 签名消息字节
+ */
+export function publicManifestSignBytes(fields) {
+	return Buffer.from(canonicalStringify([
+		ENTITY_PUBLIC_MANIFEST_DOMAIN,
+		String(fields.ownerEntityHash || '').trim().toLowerCase(),
+		assertSafeEvfsLogicalPath(fields.logicalPath),
+		Number(fields.publishedAt) || 0,
+		String(fields.contentHash || '').trim().toLowerCase(),
+		Number(fields.size) || 0,
+		String(fields.mimeType || ''),
+		String(fields.name || ''),
+		String(fields.ceMode || ''),
+		fields.parts || [],
+	]), 'utf8')
+}
+
+/**
+ * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {number} publishedAt 发布时间
+ * @param {Uint8Array | Buffer} entitySecretKey recovery 私钥种子
+ * @param {string} entityPubKeyHex recovery 公钥 hex
+ * @returns {Promise<import('./manifest.mjs').FileManifest>} 带 publicSig 的清单
+ */
+export async function attachPublicManifestSig(manifest, publishedAt, entitySecretKey, entityPubKeyHex) {
+	const pubKeyHex = normalizeHex64(entityPubKeyHex)
+	const message = publicManifestSignBytes({
+		ownerEntityHash: manifest.ownerEntityHash,
+		logicalPath: manifest.logicalPath,
+		publishedAt,
+		contentHash: manifest.contentHash,
+		size: manifest.size,
+		mimeType: manifest.mimeType,
+		name: manifest.name,
+		ceMode: manifest.ceMode,
+		parts: manifest.parts,
+	})
+	const sigHex = Buffer.from(await sign(message, entitySecretKey)).toString('hex')
+	return {
+		...manifest,
+		meta: {
+			...manifest.meta || {},
+			publicSig: { publishedAt, pubKeyHex, sigHex },
+		},
+	}
+}
+
+/**
+ * @param {unknown} input 原始 manifest
+ * @returns {Promise<import('./manifest.mjs').FileManifest | null>} 验签通过的清单；非法为 null
+ */
+export async function verifySignedPublicManifest(input) {
+	const manifest = normalizeFileManifest(input)
+	if (!manifest) return null
+	if (manifest.transferKeyDescriptor.type !== 'public') return null
+
+	const publicSig = input?.meta?.publicSig
+	if (!publicSig || typeof publicSig !== 'object') return null
+	const publishedAt = Number(publicSig.publishedAt) || 0
+	const pubKeyHex = normalizeHex64(publicSig.pubKeyHex)
+	const sigHex = String(publicSig.sigHex || '').trim().toLowerCase()
+	if (!isHex64(pubKeyHex) || !/^[\da-f]{128}$/u.test(sigHex) || publishedAt <= 0) return null
+
+	const parsed = parseEntityHash(manifest.ownerEntityHash)
+	if (!parsed) return null
+	if (hashFromPubKeyHex(pubKeyHex) !== parsed.subjectHash) return null
+
+	const message = publicManifestSignBytes({
+		ownerEntityHash: manifest.ownerEntityHash,
+		logicalPath: manifest.logicalPath,
+		publishedAt,
+		contentHash: manifest.contentHash,
+		size: manifest.size,
+		mimeType: manifest.mimeType,
+		name: manifest.name,
+		ceMode: manifest.ceMode,
+		parts: manifest.parts,
+	})
+	const ok = await verify(Buffer.from(sigHex, 'hex'), message, Buffer.from(pubKeyHex, 'hex'))
+	if (!ok) return null
+
+	// 签名只覆盖内容字段：入站 meta 一律丢弃，仅保留 publicSig，
+	// 防止中继注入 dagParts/groupId 等本地扩展改写读取路径。
+	return {
+		...manifest,
+		meta: { publicSig: { publishedAt, pubKeyHex, sigHex } },
+	}
+}
+
+/**
+ * @param {object | null | undefined} localManifest 本地已有清单
+ * @param {import('./manifest.mjs').FileManifest} incoming 入站已验签清单
+ * @returns {boolean} 是否应以 incoming 覆盖本地缓存
+ */
+export function shouldPreferIncomingPublicManifest(localManifest, incoming) {
+	const incomingAt = Number(incoming?.meta?.publicSig?.publishedAt) || 0
+	if (incomingAt <= 0) return false
+	const localAt = Number(localManifest?.meta?.publicSig?.publishedAt) || 0
+	return incomingAt > localAt
+}
+
+/**
+ * @param {object} params 参数
+ * @param {string} params.ownerEntityHash owner
+ * @param {string} params.logicalPath 路径
+ * @param {Buffer | Uint8Array} params.plaintext 明文
+ * @param {string} [params.name] 文件名
+ * @param {string} [params.mimeType] MIME
+ * @param {Uint8Array | Buffer} params.entitySecretKey recovery 私钥种子
+ * @param {string} params.entityPubKeyHex recovery 公钥 hex
+ * @param {number} [params.publishedAt] 发布时间（默认 Date.now）
+ * @returns {Promise<import('./manifest.mjs').FileManifest>} 已签名并落盘的公开清单
+ */
+export async function publishPublicFile(params) {
+	const {
+		ownerEntityHash,
+		logicalPath,
+		plaintext,
+		name,
+		mimeType,
+		entitySecretKey,
+		entityPubKeyHex,
+		publishedAt = Date.now(),
+	} = params
+	const { putFileManifest, saveFileManifest } = await import('../entity/files/evfs.mjs')
+	const base = await putFileManifest({
+		ownerEntityHash,
+		logicalPath,
+		plaintext,
+		name,
+		mimeType,
+		ceMode: 'convergent',
+		transferKeyDescriptor: publicTransferKeyDescriptor(),
+	})
+	const signed = await attachPublicManifestSig(base, publishedAt, entitySecretKey, entityPubKeyHex)
+	await saveFileManifest(signed)
+	return signed
+}

package/link/channel_mux.mjs

@@ -43,6 +43,8 @@ const DEFAULT_ACTION_PRIORITIES = Object.freeze({
 	fed_chunk_get: 5,
 	fed_chunk_data: 5,
 	fed_chunk_ack: 5,
+	fed_manifest_get: 5,
+	fed_manifest_data: 5,
 	fed_partition_bridge: 5,
 	fed_volatile: 10,
 })

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.2",
+	"version": "0.0.3",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",

package/transport/rtc_connection_budget.mjs

@@ -159,6 +159,8 @@ const NON_CRITICAL_FED_ACTIONS = new Set([
 	'fed_chunk_get',
 	'fed_chunk_data',
 	'fed_chunk_ack',
+	'fed_manifest_get',
+	'fed_manifest_data',
 	'part_invoke',
 	'discovery_announce',
 	'discovery_query',

package/entity/files/url.mjs

@@ -1,19 +0,0 @@
-/**
- * EVFS 文件 URL 辅助。
- * @param {string} entityHash 128 位十六进制
- * @param {string} logicalPath EVFS 逻辑路径
- * @returns {string} HTTP 地址
- */
-export function entityFileUrl(entityHash, logicalPath) {
-	const path = String(logicalPath || '').trim().replace(/^\/+/, '')
-	return `/api/p2p/entities/${encodeURIComponent(entityHash)}/files/${path.split('/').map(encodeURIComponent).join('/')}`
-}
-
-/**
- * profile 头像 EVFS 路径 URL。
- * @param {string} entityHash 128 位十六进制
- * @returns {string} profile 头像 HTTP 地址
- */
-export function profileAvatarFileUrl(entityHash) {
-	return entityFileUrl(entityHash, 'profile/avatar')
-}

package/entity/localized_core.mjs

@@ -1,141 +0,0 @@
-import { isEntityHash128 } from '../core/entity_id.mjs'
-
-import { profileAvatarFileUrl } from './files/url.mjs'
-
-/**
- * @param {unknown} linkItem 链接项
- * @returns {object | null} 规范化链接项或 null
- */
-function normalizeLink(linkItem) {
-	const url = String(linkItem?.url || '').trim()
-	if (!url) return null
-	return {
-		icon: String(linkItem.icon || '').trim(),
-		name: String(linkItem.name || '').trim(),
-		url,
-	}
-}
-
-/**
- * @param {unknown} localizedInput 原始 localized 字段
- * @returns {Record<string, object>} locale → 切片
- */
-export function normalizeLocalizedMap(localizedInput) {
-	if (!localizedInput) return {}
-	/** @type {Record<string, object>} */
-	const out = {}
-	for (const [key, value] of Object.entries(localizedInput)) {
-		const localeKey = String(key || '').trim()
-		if (!localeKey || !value) continue
-		const tags = Array.isArray(value.tags)
-			? value.tags.map(t => String(t).trim()).filter(Boolean)
-			: undefined
-		const links = Array.isArray(value.links)
-			? value.links.map(normalizeLink).filter(Boolean)
-			: undefined
-		/** @type {Record<string, unknown>} */
-		const slice = {}
-		if (value.name != null) slice.name = String(value.name).trim()
-		if (value.avatar) slice.avatar = String(value.avatar).trim()
-		if (value.description != null) slice.description = String(value.description)
-		if (value.description_markdown != null) slice.description_markdown = String(value.description_markdown)
-		if (value.version) slice.version = String(value.version).trim()
-		if (value.author) slice.author = String(value.author).trim()
-		if (value.home_page) slice.home_page = String(value.home_page).trim()
-		if (value.issue_page) slice.issue_page = String(value.issue_page).trim()
-		if (tags?.length) slice.tags = tags
-		if (links?.length) slice.links = links
-		if (Object.keys(slice).length) out[localeKey] = slice
-	}
-	return out
-}
-
-/**
- * @param {Record<string, object>} localized 多语言切片
- * @param {string[]} locales 区域设置优先级
- * @returns {object | null} 匹配的语言切片
- */
-function pickLocalizedSlice(localized, locales) {
-	const keys = Object.keys(localized || {})
-	if (!keys.length) return null
-	for (const locale of locales || []) {
-		if (localized[locale]) return localized[locale]
-		const prefix = String(locale).split('-')[0]
-		const hit = keys.find(k => k === prefix || k.startsWith(`${prefix}-`))
-		if (hit) return localized[hit]
-	}
-	return localized[keys[0]]
-}
-
-/**
- * @param {string} displayName 展示名
- * @param {{ subjectHash?: string }} profile 资料对象
- * @returns {boolean} 是否为占位展示名
- */
-export function isPlaceholderDisplayName(displayName, profile) {
-	const name = String(displayName || '').trim()
-	if (!name) return true
-	const subjectHash = String(profile?.subjectHash || '').trim().toLowerCase()
-	if (!subjectHash || subjectHash.length < 12) return false
-	const placeholder = `${subjectHash.slice(0, 8)}…${subjectHash.slice(-4)}`
-	return name === placeholder
-}
-
-/**
- * @param {object} stored 磁盘上的 profile 对象
- * @param {string[]} locales 查看者区域设置
- * @param {object} infoDefaults part 默认
- * @returns {object} 合并后的展示字段
- */
-export function resolveProfilePresentation(stored, locales, infoDefaults) {
-	const localized = normalizeLocalizedMap(stored?.localized)
-	const slice = pickLocalizedSlice(localized, locales) || {}
-
-	let name = slice.name?.trim() || infoDefaults.name
-	if (name && isPlaceholderDisplayName(name, stored))
-		name = infoDefaults.name
-
-	const description = slice.description != null
-		? String(slice.description)
-		: infoDefaults.description
-	const description_markdown = slice.description_markdown != null
-		? String(slice.description_markdown)
-		: slice.description != null ? String(slice.description) : infoDefaults.description_markdown
-
-	const tags = slice.tags?.length ? slice.tags : infoDefaults.tags
-	const links = slice.links?.length ? slice.links : infoDefaults.links
-
-	let avatar = slice.avatar?.trim() || infoDefaults.avatar
-	if (avatar && !avatar.startsWith('http') && isEntityHash128(stored?.entityHash))
-		avatar = profileAvatarFileUrl(stored.entityHash)
-	else if (!avatar && isEntityHash128(stored?.entityHash) && stored?.localized)
-		avatar = profileAvatarFileUrl(stored.entityHash)
-
-	return {
-		name: name || infoDefaults.name,
-		avatar: avatar || '',
-		description: description || '',
-		description_markdown: description_markdown || '',
-		version: slice.version?.trim() || infoDefaults.version || '',
-		author: slice.author?.trim() || infoDefaults.author || '',
-		home_page: slice.home_page?.trim() || infoDefaults.home_page || '',
-		issue_page: slice.issue_page?.trim() || infoDefaults.issue_page || '',
-		tags: [...tags],
-		links: [...links],
-	}
-}
-
-/**
- * @param {Record<string, object>} localized 多语言表
- * @param {string} avatarUrl 头像 URL
- * @returns {Record<string, object>} 带头像 URL 的多语言表
- */
-export function applyAvatarToAllLocales(localized, avatarUrl) {
-	const keys = Object.keys(localized)
-	if (!keys.length) return { '': { avatar: avatarUrl } }
-	/** @type {Record<string, object>} */
-	const out = {}
-	for (const key of keys)
-		out[key] = { ...localized[key], avatar: avatarUrl }
-	return out
-}

package/entity/presentation_registry.mjs

@@ -1,44 +0,0 @@
-/** @typedef {{ query?: { locales?: string | string[] } }} ExpressLikeRequest */
-
-/** @type {((replicaUsername: string, entityHash: string, locales: string[]) => Promise<object>) | null} */
-let infoDefaultsProvider = null
-
-/** @type {((req: ExpressLikeRequest, replicaUsername: string) => string[]) | null} */
-let localesFromRequestProvider = null
-
-/**
- * @param {(replicaUsername: string, entityHash: string, locales: string[]) => Promise<object>} provider 资料默认值解析器
- * @returns {void}
- */
-export function registerEntityPresentationProvider(provider) {
-	infoDefaultsProvider = provider
-}
-
-/**
- * @param {(req: ExpressLikeRequest, replicaUsername: string) => string[]} provider 请求区域设置解析器
- * @returns {void}
- */
-export function registerLocalesFromRequestProvider(provider) {
-	localesFromRequestProvider = provider
-}
-
-/**
- * @param {string} replicaUsername 查看者 replica
- * @param {string} entityHash 目标实体
- * @param {string[]} locales 区域设置优先级
- * @returns {Promise<object | null>} 展示默认值或 null
- */
-export async function resolveInfoDefaultsForEntity(replicaUsername, entityHash, locales) {
-	if (!infoDefaultsProvider) return null
-	return infoDefaultsProvider(replicaUsername, entityHash, locales)
-}
-
-/**
- * @param {ExpressLikeRequest} req HTTP 请求
- * @param {string} replicaUsername 查看者 replica
- * @returns {string[]} 区域设置列表
- */
-export function localesFromRequest(req, replicaUsername) {
-	if (localesFromRequestProvider) return localesFromRequestProvider(req, replicaUsername)
-	return ['zh-CN', 'en-UK']
-}

package/entity/profile.mjs

@@ -1,256 +0,0 @@
-import { parseEntityHash } from '../core/entity_id.mjs'
-import { getEntityStore } from '../node/instance.mjs'
-
-import { profileAvatarFileUrl } from './files/url.mjs'
-import {
-	applyAvatarToAllLocales,
-	normalizeLocalizedMap,
-	resolveProfilePresentation,
-} from './localized_core.mjs'
-import { resolveInfoDefaultsForEntity } from './presentation_registry.mjs'
-import { isWritableLocalEntity } from './replica.mjs'
-
-/** 超过该毫秒未心跳则视为离线 */
-const HEARTBEAT_STALE_MS = 120_000
-
-const MANUAL_STATUSES = new Set(['online', 'idle', 'dnd', 'invisible', 'away', 'busy', 'offline'])
-const PROFILE_JSON = 'profile.json'
-
-/**
- * @param {string} entityHash 128 位 entityHash
- * @param {{ nodeHash: string, subjectHash: string }} parsed parseEntityHash 结果
- * @returns {object} 默认资料
- */
-function getDefaultProfile(entityHash, parsed) {
-	return {
-		entityHash,
-		nodeHash: parsed.nodeHash,
-		subjectHash: parsed.subjectHash,
-		localized: {},
-		status: 'online',
-		customStatus: '',
-		lastSeenAt: 0,
-		stats: {
-			joinedAt: Date.now(),
-			messageCount: 0,
-			groupCount: 0,
-			channelCount: 0,
-		},
-	}
-}
-
-/**
- * @param {object} profileData 原始对象
- * @returns {object} 可写入磁盘的资料
- */
-function toStoredProfile(profileData) {
-	return {
-		entityHash: profileData.entityHash,
-		nodeHash: profileData.nodeHash,
-		subjectHash: profileData.subjectHash,
-		localized: normalizeLocalizedMap(profileData.localized),
-		status: profileData.status || 'online',
-		customStatus: String(profileData.customStatus || '').trim(),
-		lastSeenAt: profileData.lastSeenAt || 0,
-		stats: {
-			joinedAt: profileData.stats?.joinedAt || Date.now(),
-			messageCount: profileData.stats?.messageCount || 0,
-			groupCount: profileData.stats?.groupCount || 0,
-			channelCount: profileData.stats?.channelCount || 0,
-		},
-	}
-}
-
-/**
- * @param {object} profile 用户资料
- * @param {string} [viewerEntityHash] 查看者 entityHash
- * @param {{ isSelf?: boolean }} [options] isSelf 为 true 时隐身对本人可见
- * @returns {string} 有效状态
- */
-export function computeEffectiveStatus(profile, viewerEntityHash, options = {}) {
-	const stored = String(profile?.status || 'online')
-	const isSelf = options.isSelf
-		?? (viewerEntityHash && profile?.entityHash === viewerEntityHash)
-	const lastSeen = profile?.lastSeenAt || 0
-	const recentlySeen = lastSeen > 0 && Date.now() - lastSeen < HEARTBEAT_STALE_MS
-
-	if (stored === 'invisible')
-		return isSelf ? 'invisible' : 'offline'
-
-	if (!recentlySeen)
-		return 'offline'
-
-	return stored
-}
-
-/**
- * @param {string} entityHash 128 位 entityHash
- * @param {string | null} [replicaUsername] 展示默认字段用
- * @param {{ groupId?: string, skipPresentation?: boolean, locales?: string[], infoDefaults?: object }} [options] 选项
- * @returns {Promise<object>} 资料对象
- */
-export async function getProfile(entityHash, replicaUsername = null, options = {}) {
-	const parsed = parseEntityHash(entityHash)
-	if (!parsed) throw new Error('invalid entityHash')
-
-	const store = getEntityStore()
-	const defaultProfile = getDefaultProfile(parsed.entityHash, parsed)
-	let stored = defaultProfile
-
-	const onDisk = await store.readEntityJson(parsed.entityHash, PROFILE_JSON)
-	if (onDisk)
-		stored = toStoredProfile({ ...defaultProfile, ...onDisk })
-	else if (isWritableLocalEntity(parsed.entityHash))
-		await store.writeEntityJson(parsed.entityHash, PROFILE_JSON, stored)
-
-	const locales = options.locales || ['zh-CN', 'en-UK']
-	const merged = {
-		...stored,
-		entityHash: parsed.entityHash,
-		nodeHash: parsed.nodeHash,
-		subjectHash: parsed.subjectHash,
-	}
-
-	if (options.skipPresentation) return merged
-
-	let { infoDefaults } = options
-	if (!infoDefaults && replicaUsername)
-		infoDefaults = await resolveInfoDefaultsForEntity(replicaUsername, parsed.entityHash, locales)
-	if (!infoDefaults)
-		infoDefaults = { name: `${parsed.subjectHash.slice(0, 8)}…${parsed.subjectHash.slice(-4)}`, avatar: '', description: '', description_markdown: '', version: '', author: '', home_page: '', issue_page: '', tags: [], links: [] }
-
-	const resolved = resolveProfilePresentation(merged, locales, infoDefaults)
-	return {
-		...merged,
-		...resolved,
-		infoDefaults,
-		localeKeys: Object.keys(merged.localized),
-	}
-}
-
-/**
- * @param {string} replicaUsername 副本用户名 所有者
- * @param {string} entityHash 128 位 entityHash
- * @returns {Promise<void>}
- */
-export async function recordHeartbeat(replicaUsername, entityHash) {
-	void replicaUsername
-	const profile = await getProfile(entityHash, null, { skipPresentation: true })
-	profile.lastSeenAt = Date.now()
-	await getEntityStore().writeEntityJson(entityHash, PROFILE_JSON, toStoredProfile(profile))
-	return { lastSeenAt: profile.lastSeenAt }
-}
-
-/**
- * @param {string} replicaUsername 副本用户名 所有者
- * @param {string} entityHash 128 位 entityHash
- * @param {object} updates 更新内容
- * @param {{ groupId?: string, skipPresentation?: boolean, locales?: string[] }} [options] 选项
- * @returns {Promise<object>} 更新后的资料
- */
-export async function updateProfile(replicaUsername, entityHash, updates, options = {}) {
-	if (!isWritableLocalEntity(entityHash))
-		throw new Error('entity not writable on this replica')
-
-	const profile = await getProfile(entityHash, replicaUsername, {
-		groupId: options.groupId,
-		skipPresentation: true,
-	})
-	const parsed = parseEntityHash(entityHash)
-
-	const localized = updates.localized != null
-		? normalizeLocalizedMap(updates.localized)
-		: profile.localized
-
-	const updatedProfile = toStoredProfile({
-		...profile,
-		entityHash: parsed.entityHash,
-		nodeHash: parsed.nodeHash,
-		subjectHash: parsed.subjectHash,
-		localized,
-		status: updates.status != null ? updates.status : profile.status,
-		customStatus: updates.customStatus != null ? updates.customStatus : profile.customStatus,
-		lastSeenAt: updates.lastSeenAt != null ? updates.lastSeenAt : profile.lastSeenAt,
-		stats: updates.stats ? { ...profile.stats, ...updates.stats } : profile.stats,
-	})
-
-	await getEntityStore().writeEntityJson(entityHash, PROFILE_JSON, updatedProfile)
-	if (options.skipPresentation) return updatedProfile
-	const locales = options.locales || ['zh-CN', 'en-UK']
-	const infoDefaults = await resolveInfoDefaultsForEntity(replicaUsername, entityHash, locales)
-	const resolved = resolveProfilePresentation(updatedProfile, locales, infoDefaults)
-	return { ...updatedProfile, ...resolved, infoDefaults, localeKeys: Object.keys(updatedProfile.localized) }
-}
-
-/**
- * @param {string} replicaUsername 副本用户名 所有者
- * @param {string} entityHash 128 位 entityHash
- * @param {Buffer} fileBuffer 文件缓冲区
- * @param {string} filename 文件名
- * @returns {Promise<string>} 头像 URL
- */
-export async function uploadAvatar(replicaUsername, entityHash, fileBuffer, filename) {
-	if (!isWritableLocalEntity(entityHash))
-		throw new Error('entity not writable on this replica')
-
-	const { putFileManifest } = await import('./files/evfs.mjs')
-	await putFileManifest({
-		ownerEntityHash: entityHash,
-		logicalPath: 'profile/avatar',
-		plaintext: fileBuffer,
-		name: filename || 'avatar',
-		mimeType: 'image/png',
-		ceMode: 'convergent',
-	})
-
-	const avatarUrl = profileAvatarFileUrl(entityHash)
-	const profile = await getProfile(entityHash, replicaUsername, { skipPresentation: true })
-	await updateProfile(replicaUsername, entityHash, {
-		localized: applyAvatarToAllLocales(profile.localized, avatarUrl),
-	}, { skipPresentation: true })
-	return avatarUrl
-}
-
-/**
- * @param {string} entityHash 128 位 entityHash
- * @returns {Promise<object>} 统计字段
- */
-export async function getStats(entityHash) {
-	const profile = await getProfile(entityHash)
-	return profile.stats
-}
-
-/**
- * @param {string} replicaUsername 副本用户名 所有者
- * @param {string} entityHash 128 位 entityHash
- * @param {string} status 状态
- * @param {string} [customStatus] 自定义状态
- * @returns {Promise<{ status: string, customStatus: string, lastSeenAt: number }>} 更新后的状态字段
- */
-export async function updateStatus(replicaUsername, entityHash, status, customStatus = '') {
-	if (!MANUAL_STATUSES.has(status))
-		throw new Error('invalid status')
-	const updated = await updateProfile(replicaUsername, entityHash, {
-		status,
-		customStatus,
-		lastSeenAt: Date.now(),
-	}, { skipPresentation: true })
-	return {
-		status: updated.status,
-		customStatus: updated.customStatus,
-		lastSeenAt: updated.lastSeenAt,
-	}
-}
-
-/**
- * 确保本节点操作者实体目录存在。
- * @param {string} replicaUsername 副本用户名 所有者
- * @param {string} entityHash 128 位 entityHash
- * @returns {Promise<object>} 本节点实体资料
- */
-export async function ensureLocalEntityProfile(replicaUsername, entityHash) {
-	void replicaUsername
-	if (!isWritableLocalEntity(entityHash))
-		throw new Error('entity not on local node')
-	return getProfile(entityHash, replicaUsername, { skipPresentation: true })
-}