@steve02081504/fount-p2p 0.0.2 → 0.0.4

package/README.md

@@ -34,7 +34,7 @@ Subpath exports mirror source directories, e.g. `@steve02081504/fount-p2p/dag`,
 | L1 | `crypto/`, `wire/`, `schemas/` | Cryptography, wire protocol, canonical validation |
 | L2 | `node/` | Node runtime: `identity`, `entity_store`, `denylist`, `reputation_store` |
 | L3 | `discovery/`, `link/`, `transport/`, `rooms/` | Discovery, RTC links, rooms |
-| L4 | `trust_graph/`, `mailbox/`, `dag/`, `federation/`, `files/`, `entity/` | Federation, store-and-forward, DAG, EVFS |
+| L4 | `trust_graph/`, `mailbox/`, `dag/`, `federation/`, `files/` | Federation, store-and-forward, DAG, EVFS |
 | — | `registries/` | Pluggable registries (event type, part path, room provider, …) |
 
 Facade entry: `index.mjs` (`startNode`, `createGroupLinkSet`, `registerDiscoveryProvider`, …).

package/{entity → core}/logical_entity.mjs

@@ -1,6 +1,7 @@
-import { encodeEntityHash, parseEntityHash } from '../core/entity_id.mjs'
 import { sha256TextHex } from '../crypto/crypto.mjs'
 
+import { encodeEntityHash, parseEntityHash } from './entity_id.mjs'
+
 /** @type {string} 逻辑实体 sentinel nodeHash（非物理节点绑定） */
 export const LOGICAL_ENTITY_SENTINEL_NODE_HASH = '0'.repeat(64)
 

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/{entity/files → files}/acl.mjs

@@ -1,12 +1,12 @@
-import { isLogicalEntityHash } from '../logical_entity.mjs'
-import { isWritableLocalEntity } from '../replica.mjs'
+import { isLogicalEntityHash } from '../core/logical_entity.mjs'
+import { isWritableLocalEntity } from '../node/identity.mjs'
 
 import { checkManifestAcl, resolveManifestAclType } from './manifest_acl_registry.mjs'
 
 /**
  * @param {string} replicaUsername 请求 replica
  * @param {string} ownerEntityHash 文件 owner
- * @param {import('../../files/manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest.mjs').FileManifest} manifest 清单
  * @returns {Promise<boolean>} 是否允许读
  */
 export async function canReadManifest(replicaUsername, ownerEntityHash, manifest) {

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/{entity/files → files}/evfs.mjs

@@ -1,21 +1,21 @@
 import { Buffer } from 'node:buffer'
 import { Readable } from 'node:stream'
 
-import { FEDERATION_CHUNK_MAX_BYTES } from '../../core/constants.mjs'
-import { buildFileManifestFromEnc } from '../../files/assemble.mjs'
-import { encryptReadableToParts } from '../../files/assemble_stream.mjs'
-import { fetchChunk } from '../../files/chunk_fetch.mjs'
-import { getChunk, hasChunk, putChunk } from '../../files/chunk_store.mjs'
-import { normalizeFileManifest, publicTransferKeyDescriptor } from '../../files/manifest.mjs'
-import { assembleManifestPlaintext } from '../../files/transfer_key.mjs'
-import { readDagManifestPlaintext, resolveTransferKeyDeps } from '../../files/transfer_key_registry.mjs'
-import { getEntityStore } from '../../node/instance.mjs'
+import { FEDERATION_CHUNK_MAX_BYTES } from '../core/constants.mjs'
+import { getEntityStore } from '../node/instance.mjs'
 
+import { buildFileManifestFromEnc, encryptPlaintextToParts, encryptPlaintextToMultiPartsAsync } from './assemble.mjs'
+import { encryptReadableToParts } from './assemble_stream.mjs'
+import { fetchChunk } from './chunk_fetch.mjs'
+import { getChunk, hasChunk, putChunk } from './chunk_store.mjs'
+import { normalizeFileManifest, publicTransferKeyDescriptor } from './manifest.mjs'
+import { assembleManifestPlaintext } from './transfer_key.mjs'
+import { readDagManifestPlaintext, resolveTransferKeyDeps } from './transfer_key_registry.mjs'
 
 /**
  * @param {string} ownerEntityHash 所有者
  * @param {string} logicalPath 路径
- * @returns {Promise<import('../../files/manifest.mjs').FileManifest | null>} 归一化 manifest
+ * @returns {Promise<import('./manifest.mjs').FileManifest | null>} 归一化 manifest
  */
 export async function loadFileManifest(ownerEntityHash, logicalPath) {
 	const manifest = await getEntityStore().readManifest(ownerEntityHash, logicalPath)
@@ -23,7 +23,7 @@ export async function loadFileManifest(ownerEntityHash, logicalPath) {
 }
 
 /**
- * @param {import('../../files/manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest.mjs').FileManifest} manifest 清单
  * @returns {Promise<void>}
  */
 export async function saveFileManifest(manifest) {
@@ -31,7 +31,7 @@ export async function saveFileManifest(manifest) {
 }
 
 /**
- * @param {import('../../files/manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest.mjs').FileManifest} manifest 清单
  * @param {Array<Buffer | Uint8Array>} partBytes 密文块
  * @returns {Promise<void>}
  */
@@ -42,7 +42,7 @@ export async function storeManifestParts(manifest, partBytes) {
 
 /**
  * @param {string} replicaUsername 副本用户名
- * @param {import('../../files/manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest.mjs').FileManifest} manifest 清单
  * @param {{ username?: string, fetchChunk?: Function }} [opts] miss 拉取
  * @returns {Promise<Buffer | null>} 明文内容
  */
@@ -90,7 +90,7 @@ export async function readManifestPlaintext(replicaUsername, manifest, opts = {}
 
 /**
  * @param {string} replicaUsername 副本用户名
- * @param {import('../../files/manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest.mjs').FileManifest} manifest 清单
  * @param {{ username?: string, fetchChunk?: Function }} [opts] miss 拉取
  * @returns {Promise<import('node:stream').Readable | null>} 明文流
  */
@@ -107,13 +107,12 @@ export async function readManifestPlaintextStream(replicaUsername, manifest, opt
  * @param {Buffer | Uint8Array} params.plaintext 明文
  * @param {string} [params.name] 文件名
  * @param {string} [params.mimeType] MIME
- * @param {import('../../files/manifest.mjs').CeMode} [params.ceMode] 模式
- * @param {import('../../files/manifest.mjs').TransferKeyDescriptor} [params.transferKeyDescriptor] 传递密钥
+ * @param {import('./manifest.mjs').CeMode} [params.ceMode] 模式
+ * @param {import('./manifest.mjs').TransferKeyDescriptor} [params.transferKeyDescriptor] 传递密钥
  * @param {object} [params.meta] meta
- * @returns {Promise<import('../../files/manifest.mjs').FileManifest>} 写入后的 manifest
+ * @returns {Promise<import('./manifest.mjs').FileManifest>} 写入后的 manifest
  */
 export async function putFileManifest(params) {
-	const { encryptPlaintextToParts, encryptPlaintextToMultiPartsAsync } = await import('../../files/assemble.mjs')
 	const {
 		ownerEntityHash,
 		logicalPath,
@@ -152,10 +151,10 @@ export async function putFileManifest(params) {
  * @param {number} params.plainSize 明文字节数
  * @param {string} [params.name] 文件名
  * @param {string} [params.mimeType] MIME
- * @param {import('../../files/manifest.mjs').CeMode} [params.ceMode] 模式
- * @param {import('../../files/manifest.mjs').TransferKeyDescriptor} [params.transferKeyDescriptor] 传递密钥
+ * @param {import('./manifest.mjs').CeMode} [params.ceMode] 模式
+ * @param {import('./manifest.mjs').TransferKeyDescriptor} [params.transferKeyDescriptor] 传递密钥
  * @param {object} [params.meta] meta
- * @returns {Promise<import('../../files/manifest.mjs').FileManifest>} 写入后的 manifest
+ * @returns {Promise<import('./manifest.mjs').FileManifest>} 写入后的 manifest
  */
 export async function putFileManifestFromStream(params) {
 	const {
@@ -187,3 +186,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('./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/files → files}/evfs_ref.mjs

@@ -1,9 +1,7 @@
-import { isEntityHash128 } from '../../core/entity_id.mjs'
-import { assertSafeEvfsLogicalPath } from '../../core/evfs_logical_path.mjs'
+import { isEntityHash128 } from '../core/entity_id.mjs'
+import { assertSafeEvfsLogicalPath } from '../core/evfs_logical_path.mjs'
 
-/**
- *
- */
+/** @type {string} evfs URI scheme */
 export const EVFS_SCHEME = 'evfs:'
 
 /**

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/{entity/files → files}/manifest_acl_registry.mjs

@@ -5,14 +5,14 @@
 /** @type {Map<string, { ownerId: string, handler: (context: ManifestAclContext, logicalPath?: string) => Promise<boolean> }>} */
 const handlersByType = new Map()
 
-/** @type {Map<string, { ownerId: string, match: (manifest: import('../../files/manifest.mjs').FileManifest | null | undefined, ownerEntityHash: string) => string | null }>} */
+/** @type {Map<string, { ownerId: string, match: (manifest: import('./manifest.mjs').FileManifest | null | undefined, ownerEntityHash: string) => string | null }>} */
 const matchersByOwner = new Map()
 
 /**
  * @typedef {{
  *   replicaUsername: string,
  *   ownerEntityHash: string,
- *   manifest: import('../../files/manifest.mjs').FileManifest,
+ *   manifest: import('./manifest.mjs').FileManifest,
  * }} ManifestAclContext
  */
 
@@ -46,7 +46,7 @@ export function unregisterManifestAcl(type, ownerId) {
 
 /**
  * @param {string} ownerId 注册方
- * @param {(manifest: import('../../files/manifest.mjs').FileManifest | null | undefined, ownerEntityHash: string) => string | null} match ACL 类型匹配
+ * @param {(manifest: import('./manifest.mjs').FileManifest | null | undefined, ownerEntityHash: string) => string | null} match ACL 类型匹配
  * @returns {void}
  */
 export function registerManifestAclMatcher(ownerId, match) {
@@ -68,7 +68,7 @@ export function clearManifestAclRegistry() {
 }
 
 /**
- * @param {import('../../files/manifest.mjs').FileManifest | null | undefined} manifest manifest
+ * @param {import('./manifest.mjs').FileManifest | null | undefined} manifest manifest
  * @param {string} ownerEntityHash 所有者
  * @returns {string | null} ACL 类型
  */

package/files/manifest_fetch.mjs

@@ -0,0 +1,97 @@
+import { randomUUID } from 'node:crypto'
+
+import {
+	manifestFetchExpectedKey,
+	MAX_PENDING_MANIFEST_FETCHES,
+	pendingManifestFetches,
+	registerManifestFetchWait,
+} from '../federation/manifest_fetch_pending.mjs'
+import { isWritableLocalEntity } from '../node/identity.mjs'
+import { getEntityStore } from '../node/instance.mjs'
+
+import { resolveNodeHash } from './chunk_provider_registry.mjs'
+import { loadFileManifest, saveFileManifest } from './evfs.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)
+}