@steve02081504/fount-p2p 0.0.1 → 0.0.3

package/README.md

@@ -44,7 +44,8 @@ Root contains only the facade and package metadata; all modules live in layered
 ## Tests
 
 ```bash
-npm test              # pure + integration (--test-force-exit: node-datachannel leaves native handles)
+npm test              # package pure + integration (Node)
+npm run test:fount    # cross-repo bridge (Deno; requires fount on PATH)
 npm run test:live     # RTC / link smoke (requires node-datachannel)
 npm run test:sim      # tunables co-evolution sim (dev only, not published; --social-tunables to write back)
 ```

package/core/entity_id.mjs

@@ -34,18 +34,18 @@ export function hashFromPubKeyHex(pubKeyHex) {
 /**
  * @param {string} nodeHash 成员所属节点 hash
  * @param {string} recoveryPubKeyHex 32 字节 recovery 公钥 hex（稳定身份锚）
- * @returns {string} 用户 entityHash
+ * @returns {string} entityHash
  */
-export function userEntityHashFromRecoveryPubKeyHex(nodeHash, recoveryPubKeyHex) {
+export function entityHashFromRecoveryPubKeyHex(nodeHash, recoveryPubKeyHex) {
 	return encodeEntityHash(nodeHash, hashFromPubKeyHex(recoveryPubKeyHex))
 }
 
 /**
  * @param {string} nodeHash 成员所属节点 hash
  * @param {string} subjectHash 成员签名 pubKeyHash（DAG sender）
- * @returns {string} 用户 entityHash
+ * @returns {string} entityHash
  */
-export function userEntityHashFromSubjectHash(nodeHash, subjectHash) {
+export function entityHashFromSubjectHash(nodeHash, subjectHash) {
 	const node = normalizeHex64(nodeHash)
 	const subject = normalizeHex64(subjectHash)
 	if (!isHex64(node) || !isHex64(subject)) throw new Error('invalid subject hash')

package/deno.json

@@ -0,0 +1,4 @@
+{
+	"nodeModulesDir": "none",
+	"lock": false
+}

package/discovery/bt.mjs

@@ -53,7 +53,7 @@ export async function waitPoweredOn(runtime, timeout) {
 
 /**
  * 探测本机 noble 运行时是否具备 BT 扫描所需 API。
- * @returns {Promise<boolean>}
+ * @returns {Promise<boolean>} noble 可加载且具备 startScanningAsync 与 waitForPoweredOn(Async) 时为 true
  */
 export async function canUseBluetoothDiscovery() {
 	try {

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/entity/replica.mjs

@@ -1,12 +1,12 @@
 import { parseEntityHash } from '../core/entity_id.mjs'
-import { operatorEntityHashFromKeys, getNodeHash } from '../node/identity.mjs'
+import { entityHashFromKeys, getNodeHash } from '../node/identity.mjs'
 
 /**
  * @param {string} recoveryPubKeyHex 64 位十六进制 recovery 公钥
- * @returns {string | null} 本节点操作者 entityHash
+ * @returns {string | null} 本节点 entityHash
  */
-export function resolveLocalOperatorEntityHash(recoveryPubKeyHex) {
-	return operatorEntityHashFromKeys(getNodeHash(), recoveryPubKeyHex)
+export function resolveLocalEntityHashFromRecoveryPubKeyHex(recoveryPubKeyHex) {
+	return entityHashFromKeys(getNodeHash(), recoveryPubKeyHex)
 }
 
 /**

package/federation/{operator_key_chain.mjs → entity_key_chain.mjs}

@@ -1,5 +1,5 @@
 /**
- * Operator 密钥历史链：entityHash 锚定 recovery 公钥，活跃钥可轮换。
+ * Entity 密钥历史链：entityHash 锚定 recovery 公钥，活跃钥可轮换。
  */
 import { Buffer } from 'node:buffer'
 
@@ -10,7 +10,7 @@ import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
 /**
  *
  */
-export const OPERATOR_KEY_REVOKE_DOMAIN = 'fount-operator-key-revoke'
+export const ENTITY_KEY_REVOKE_DOMAIN = 'fount-entity-key-revoke'
 
 /**
  * @typedef {{
@@ -19,7 +19,7 @@ export const OPERATOR_KEY_REVOKE_DOMAIN = 'fount-operator-key-revoke'
  *   attestedBy: 'recovery' | 'active' | 'revoked',
  *   validFrom?: number,
  *   revokedGenerations?: number[],
- * }} OperatorKeyHistoryEntry
+ * }} EntityKeyHistoryEntry
  */
 
 /**
@@ -42,7 +42,7 @@ export function activeSenderHashFromPubKeyHex(activePubKeyHex) {
  * @param {string} recoveryPubKeyHex recovery 公钥
  * @param {string} activePubKeyHex 初始活跃公钥
  * @param {number} [validFrom] 生效时间
- * @returns {OperatorKeyHistoryEntry[]} 创世链
+ * @returns {EntityKeyHistoryEntry[]} 创世链
  */
 export function createGenesisKeyHistory(recoveryPubKeyHex, activePubKeyHex, validFrom = Date.now()) {
 	return [{
@@ -54,7 +54,7 @@ export function createGenesisKeyHistory(recoveryPubKeyHex, activePubKeyHex, vali
 }
 
 /**
- * @param {OperatorKeyHistoryEntry[]} keyHistory 密钥历史
+ * @param {EntityKeyHistoryEntry[]} keyHistory 密钥历史
  * @param {number} generation 代际
  * @returns {string | null} 活跃公钥 hex
  */
@@ -64,7 +64,7 @@ export function resolveActiveKeyAtGeneration(keyHistory, generation) {
 }
 
 /**
- * @param {OperatorKeyHistoryEntry[]} keyHistory 密钥历史
+ * @param {EntityKeyHistoryEntry[]} keyHistory 密钥历史
  * @returns {number} 最新代际，无则 -1
  */
 export function resolveLatestActiveGeneration(keyHistory) {
@@ -73,7 +73,7 @@ export function resolveLatestActiveGeneration(keyHistory) {
 }
 
 /**
- * @param {OperatorKeyHistoryEntry[]} keyHistory 密钥历史
+ * @param {EntityKeyHistoryEntry[]} keyHistory 密钥历史
  * @param {number} generation 代际
  * @returns {boolean} 是否已吊销
  */
@@ -84,7 +84,7 @@ export function isActiveGenerationRevoked(keyHistory, generation) {
 }
 
 /**
- * @param {OperatorKeyHistoryEntry[]} keyHistory 密钥历史
+ * @param {EntityKeyHistoryEntry[]} keyHistory 密钥历史
  * @param {string} recoveryPubKeyHex recovery 公钥
  * @param {string} senderPubKeyHash 事件 sender（64 hex pubKeyHash）
  * @returns {boolean} sender 是否为未吊销的活跃钥
@@ -112,18 +112,18 @@ export function isRecoverySender(recoveryPubKeyHex, senderPubKeyHash) {
 
 /**
  * @param {object} state 物化状态
- * @param {object} event operator_key_rotate 事件
+ * @param {object} event entity_key_rotate 事件
  * @returns {object} 更新后状态
  */
-export function reduceOperatorKeyRotate(state, event) {
+export function reduceEntityKeyRotate(state, event) {
 	const generation = Number(event.content?.generation)
 	const activePubKeyHex = normalizeHex64(event.content?.activePubKeyHex || '')
 	if (!Number.isFinite(generation) || generation < 0 || !isHex64(activePubKeyHex))
 		return state
-	state.operatorKeyHistory = state.operatorKeyHistory || []
-	if (state.operatorKeyHistory.some(row => row.generation === generation))
+	state.entityKeyHistory = state.entityKeyHistory || []
+	if (state.entityKeyHistory.some(row => row.generation === generation))
 		return state
-	state.operatorKeyHistory.push({
+	state.entityKeyHistory.push({
 		generation,
 		activePubKeyHex,
 		attestedBy: generation === 0 ? 'recovery' : 'active',
@@ -134,10 +134,10 @@ export function reduceOperatorKeyRotate(state, event) {
 
 /**
  * @param {object} state 物化状态
- * @param {object} event operator_key_revoke 事件
+ * @param {object} event entity_key_revoke 事件
  * @returns {object} 更新后状态
  */
-export function reduceOperatorKeyRevoke(state, event) {
+export function reduceEntityKeyRevoke(state, event) {
 	const newGeneration = Number(event.content?.newGeneration)
 	const activePubKeyHex = normalizeHex64(event.content?.activePubKeyHex || '')
 	const revokeGenerations = Array.isArray(event.content?.revokeGenerations)
@@ -145,17 +145,17 @@ export function reduceOperatorKeyRevoke(state, event) {
 		: []
 	if (!Number.isFinite(newGeneration) || newGeneration < 0 || !isHex64(activePubKeyHex))
 		return state
-	state.operatorKeyHistory = state.operatorKeyHistory || []
+	state.entityKeyHistory = state.entityKeyHistory || []
 	for (const gen of revokeGenerations) {
-		const entry = state.operatorKeyHistory.find(row => row.generation === gen)
+		const entry = state.entityKeyHistory.find(row => row.generation === gen)
 		if (entry) {
 			entry.revokedGenerations = entry.revokedGenerations || []
 			if (!entry.revokedGenerations.includes(gen))
 				entry.revokedGenerations.push(gen)
 		}
 	}
-	if (!state.operatorKeyHistory.some(row => row.generation === newGeneration))
-		state.operatorKeyHistory.push({
+	if (!state.entityKeyHistory.some(row => row.generation === newGeneration))
+		state.entityKeyHistory.push({
 			generation: newGeneration,
 			activePubKeyHex,
 			attestedBy: 'recovery',
@@ -166,35 +166,34 @@ export function reduceOperatorKeyRevoke(state, event) {
 }
 /**
  * @param {object[]} events 时间线事件（拓扑序）
- * @returns {{ recoveryPubKeyHex: string | null, operatorKeyHistory: OperatorKeyHistoryEntry[] }} 折叠密钥链
+ * @returns {{ recoveryPubKeyHex: string | null, entityKeyHistory: EntityKeyHistoryEntry[] }} 折叠密钥链
  */
-export function foldOperatorKeyHistoryFromEvents(events) {
-	/** @type {OperatorKeyHistoryEntry[]} */
-	let operatorKeyHistory = []
+export function foldEntityKeyHistoryFromEvents(events) {
+	/** @type {EntityKeyHistoryEntry[]} */
+	let entityKeyHistory = []
 	for (const event of events || []) {
-		if (event.type === 'operator_key_rotate') {
-			const state = reduceOperatorKeyRotate({ operatorKeyHistory }, event)
-			operatorKeyHistory = state.operatorKeyHistory
+		if (event.type === 'entity_key_rotate') {
+			const state = reduceEntityKeyRotate({ entityKeyHistory }, event)
+			entityKeyHistory = state.entityKeyHistory
 		}
-		if (event.type === 'operator_key_revoke') {
-			const state = reduceOperatorKeyRevoke({ operatorKeyHistory }, event)
-			operatorKeyHistory = state.operatorKeyHistory
+		if (event.type === 'entity_key_revoke') {
+			const state = reduceEntityKeyRevoke({ entityKeyHistory }, event)
+			entityKeyHistory = state.entityKeyHistory
 		}
 	}
-	return { recoveryPubKeyHex: null, operatorKeyHistory }
+	return { recoveryPubKeyHex: null, entityKeyHistory }
 }
 
 /**
  * @param {object} revokeBody 吊销正文
  * @returns {Buffer} 固定域签名消息
  */
-export function operatorKeyRevokeSignBytes(revokeBody) {
+export function entityKeyRevokeSignBytes(revokeBody) {
 	const body = {
 		revokeGenerations: (revokeBody.revokeGenerations || []).map(g => Number(g)),
 		newGeneration: Number(revokeBody.newGeneration),
 		activePubKeyHex: normalizeHex64(revokeBody.activePubKeyHex || ''),
 		entityHash: String(revokeBody.entityHash || '').trim().toLowerCase(),
 	}
-	return Buffer.from(`${OPERATOR_KEY_REVOKE_DOMAIN}\0${canonicalStringify(body)}`, 'utf8')
+	return Buffer.from(`${ENTITY_KEY_REVOKE_DOMAIN}\0${canonicalStringify(body)}`, 'utf8')
 }
-

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,29 +21,13 @@ 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>} 密文块
  */
 export async function fetchChunk(context) {
 	const hash = String(context.ciphertextHash || '').trim().toLowerCase()
-	const username = context.username
+	const { username } = context
 	if (!hash || !username) return null
 
 	if (await hasChunk(hash))
@@ -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)
+}