@steve02081504/fount-p2p 0.0.22 → 0.0.24

package/files/assemble_stream.mjs

@@ -8,7 +8,7 @@ import { encryptSliceToPart } from './assemble.mjs'
 import { decryptPart } from './transfer_key.mjs'
 
 /**
- * @typedef {import('./manifest.mjs').CeMode} CeMode
+ * @typedef {import('./manifest/normalize.mjs').CeMode} CeMode
  * @typedef {{ hash: string, size: number, raw: Buffer, contentHash?: string }} EncryptedPart
  */
 
@@ -113,7 +113,7 @@ function readStreamChunk(stream) {
 
 /**
  * 将 manifest 各密文块按 part.size 拼齐后解密，串联为明文可读流。
- * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
  * @param {import('node:stream').Readable[]} partStreams 按序密文流
  * @param {Buffer | null} contentKey 随机密钥
  * @returns {Readable} 明文流

package/files/chunk/fetch.mjs

@@ -0,0 +1,101 @@
+import { bytesToBase64 } from '../../core/bytes_codec.mjs'
+import { assertHex64 } from '../../core/hexIds.mjs'
+import { ms } from '../../utils/duration.mjs'
+import { createInflightTable } from '../../utils/inflight_table.mjs'
+import { beginFedFanoutFetch } from '../fed/fetch_shared.mjs'
+
+import {
+	MAX_PENDING_CHUNK_FETCHES,
+	registerChunkFetchWait,
+} from './pending.mjs'
+import { fetchFederationChunk } from './provider_registry.mjs'
+import { getChunk, hasChunk, putChunk } from './store.mjs'
+import { verifiedChunkBytes } from './verify.mjs'
+
+const DEFAULT_CHUNK_FETCH_TIMEOUT_MS = ms('8s')
+
+/** 同 username+hash 共享一次 fanout；队满只丢已超基础超时的队首。 */
+const chunkInflight = createInflightTable({
+	maxSize: MAX_PENDING_CHUNK_FETCHES,
+	baseTimeoutMs: DEFAULT_CHUNK_FETCH_TIMEOUT_MS,
+})
+
+/**
+ * @typedef {{
+ *   username: string,
+ *   ciphertextHash: string,
+ *   ownerEntityHash?: string,
+ *   groupId?: string,
+ * }} FetchChunkContext
+ */
+
+/**
+ * @param {FetchChunkContext} context 上下文
+ * @returns {Promise<Uint8Array | null>} 密文块
+ */
+export async function fetchChunk(context) {
+	const hash = String(context.ciphertextHash || '').trim().toLowerCase()
+	const { username } = context
+	if (!hash || !username) return null
+
+	if (await hasChunk(hash))
+		return new Uint8Array(await getChunk(hash))
+
+	if (context.groupId) {
+		const verified = verifiedChunkBytes(hash, await fetchFederationChunk(username, context.groupId, hash))
+		if (verified) {
+			await putChunk(hash, verified)
+			return verified
+		}
+	}
+
+	const shared = beginFedFanoutFetch({
+		inflight: chunkInflight,
+		inflightKey: `${username}\0${hash}`,
+		username,
+		action: 'fed_chunk_get',
+		/**
+		 * @param {string} requestId 请求 id
+		 * @returns {{ done: Promise<Uint8Array | null>, cancel: () => void }} 等待句柄
+		 */
+		registerWait: requestId => registerChunkFetchWait(requestId, hash, DEFAULT_CHUNK_FETCH_TIMEOUT_MS),
+		/**
+		 * @param {string} requestId 请求 id
+		 * @param {string} nodeHash 目标节点 hash
+		 * @returns {object} fanout 载荷
+		 */
+		buildPayload: (requestId, nodeHash) => ({
+			requestId,
+			nodeHash,
+			chunkHash: hash,
+			ownerEntityHash: context.ownerEntityHash,
+		}),
+	})
+	if (!shared) return null
+
+	const verified = verifiedChunkBytes(hash, await shared)
+	if (verified) {
+		await putChunk(hash, verified)
+		return verified
+	}
+	return null
+}
+
+/**
+ * 若本机有 chunk 则响应 fed_chunk_get。
+ * @param {object} payload 请求
+ * @param {(response: object, peerId: string) => void} sendResponse 发送
+ * @param {string} peerId 对端
+ * @returns {Promise<void>}
+ */
+export async function handleIncomingChunkGet(payload, sendResponse, peerId) {
+	let hash
+	try {
+		hash = assertHex64(payload?.chunkHash, 'chunkHash')
+	}
+	catch { return }
+	if (!await hasChunk(hash)) return
+	const chunkBytes = await getChunk(hash)
+	if (!chunkBytes?.length) return
+	sendResponse({ requestId: payload.requestId, dataBase64: bytesToBase64(chunkBytes) }, peerId)
+}

package/files/chunk/pending.mjs

@@ -0,0 +1,59 @@
+import { base64ToBytes } from '../../core/bytes_codec.mjs'
+import { createFetchWaitTable } from '../../utils/fetch_wait.mjs'
+
+import { verifiedChunkBytes } from './verify.mjs'
+
+/** 并发 pending chunk fetch 上限。 */
+export const MAX_PENDING_CHUNK_FETCHES = 2048
+
+const table = createFetchWaitTable({ maxSize: MAX_PENDING_CHUNK_FETCHES })
+
+/** @type {typeof table.pending} */
+export const pendingChunkFetches = table.pending
+
+/**
+ * 注册 chunk 拉取等待槽（requestId 或 compositeKey）。
+ * @param {string} key 唯一等待键
+ * @param {string} expectedHash 期望 64 hex 密文哈希
+ * @param {number} timeoutMs 超时毫秒
+ * @param {{ rejectOnTimeout?: boolean }} [options] rejectOnTimeout 时 Promise 以 Error 拒绝
+ * @returns {{ done: Promise<Uint8Array | null>, cancel: () => void }} 等待 Promise 与取消函数
+ */
+export function registerChunkFetchWait(key, expectedHash, timeoutMs, options = {}) {
+	return table.register(key, expectedHash, timeoutMs, options)
+}
+
+/**
+ * 按等待键解析入站 chunk 响应（校验哈希后 resolve）。
+ * @param {string} key 等待键
+ * @param {string} expectedHash 期望哈希
+ * @param {Uint8Array | null} bytes 密文块
+ * @returns {boolean} 是否命中并完成等待
+ */
+export function resolveChunkFetchWait(key, expectedHash, bytes) {
+	const entry = table.peek(key)
+	if (!entry || entry.expectedKey !== expectedHash) return false
+	const verified = bytes ? verifiedChunkBytes(expectedHash, bytes) : null
+	if (bytes && !verified) return false
+	return table.settle(key, verified)
+}
+
+/**
+ * 处理 fed_chunk_data / 带 requestId 的响应载荷。
+ * @param {object} payload 入站载荷
+ * @returns {boolean} 是否命中 pending
+ */
+export function resolvePendingChunkFetch(payload) {
+	const requestId = typeof payload?.requestId === 'string' ? payload.requestId : ''
+	if (!requestId) return false
+	const entry = table.peek(requestId)
+	if (!entry) return false
+	if (typeof payload?.dataBase64 === 'string') {
+		try {
+			return resolveChunkFetchWait(requestId, entry.expectedKey, base64ToBytes(payload.dataBase64))
+		}
+		catch { /* keep waiting */ }
+		return false
+	}
+	return table.settle(requestId, null)
+}

package/files/{chunk_provider_registry.mjs → chunk/provider_registry.mjs}

@@ -10,7 +10,7 @@ const nodeHashProvidersByOwner = new Map()
  * @returns {void}
  */
 export function registerFederationChunkFetcher(ownerId, fetcher) {
-	federationFetchersByOwner.set(String(ownerId), fetcher)
+	federationFetchersByOwner.set(ownerId, fetcher)
 }
 
 /**
@@ -19,7 +19,7 @@ export function registerFederationChunkFetcher(ownerId, fetcher) {
  * @returns {void}
  */
 export function registerNodeHashProvider(ownerId, provider) {
-	nodeHashProvidersByOwner.set(String(ownerId), provider)
+	nodeHashProvidersByOwner.set(ownerId, provider)
 }
 
 /**
@@ -27,9 +27,8 @@ export function registerNodeHashProvider(ownerId, provider) {
  * @returns {void}
  */
 export function unregisterChunkProviders(ownerId) {
-	const key = String(ownerId)
-	federationFetchersByOwner.delete(key)
-	nodeHashProvidersByOwner.delete(key)
+	federationFetchersByOwner.delete(ownerId)
+	nodeHashProvidersByOwner.delete(ownerId)
 }
 
 /**

package/files/chunk/responder.mjs

@@ -0,0 +1,104 @@
+import { handleIncomingManifestGet } from '../manifest/fetch.mjs'
+import { resolvePendingManifestFetch } from '../manifest/pending.mjs'
+
+import { handleIncomingChunkGet } from './fetch.mjs'
+import { resolvePendingChunkFetch } from './pending.mjs'
+
+/**
+ * 群联邦 / TrustGraph 路径：响应带 requestId 的 fed_chunk_get。
+ * @param {object} data 入站 fed_chunk_get
+ * @param {string} peerId 对端 id
+ * @param {(resp: object, peerId: string) => void} sendChunkData 发送 fed_chunk_data
+ * @returns {Promise<void>}
+ */
+export async function handleFedChunkGetIngress(data, peerId, sendChunkData) {
+	await handleIncomingChunkGet(data, sendChunkData, peerId)
+}
+
+/**
+ * @param {object} data 入站 fed_chunk_data（含 requestId 时 resolve pending fetch）
+ * @returns {boolean} 是否命中 pending
+ */
+export function handleFedChunkDataIngress(data) {
+	return resolvePendingChunkFetch(data)
+}
+
+/**
+ * @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(data, peerId, sendManifestData) {
+	await handleIncomingManifestGet(data, sendManifestData, peerId)
+}
+
+/**
+ * @param {object} data 入站 fed_manifest_data
+ * @returns {Promise<boolean>} 是否命中 pending
+ */
+export function handleFedManifestDataIngress(data) {
+	return resolvePendingManifestFetch(data)
+}
+
+/**
+ * @param {(resp: object, peerId: string) => void} sendData 发送
+ * @param {{ enqueue: (prio: number, cleanup: () => void) => void }} [fedOut] 出站限速队列
+ * @returns {(resp: object, peerId: string) => void} 可入队的发送
+ */
+function wrapSend(sendData, fedOut) {
+	if (!fedOut) return sendData
+	return (resp, peerId) => {
+		fedOut.enqueue(6, () => {
+			try { sendData(resp, peerId) }
+			catch { /* peer gone */ }
+		})
+	}
+}
+
+/**
+ * Trystero room：注册带 requestId 的 fed_chunk_* + fed_manifest_*（TrustGraph / 群全局 miss）。
+ * @param {object} room Trystero room
+ * @param {{ enqueue: (prio: number, cleanup: () => void) => void }} [fedOut] 出站队列
+ * @param {(roomKey: string, action: string, rtcLimits: object) => boolean} [guardGet] RTC 负载守卫
+ * @param {object} [rtcLimits] RTC 限额
+ * @param {string} [roomKey] 房间键
+ * @returns {void}
+ */
+export function attachTrustGraphFedChunkResponder(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')
+
+	const sendChunk = wrapSend((resp, peerId) => {
+		try { sendChunkData(resp, peerId) }
+		catch { /* peer gone */ }
+	}, fedOut)
+	const sendManifest = wrapSend((resp, peerId) => {
+		try { sendManifestData(resp, peerId) }
+		catch { /* peer gone */ }
+	}, fedOut)
+
+	getChunkGet((data, peerId) => {
+		if (guardGet && !guardGet(roomKey, 'fed_chunk_get', rtcLimits)) return
+		if (!data?.requestId) return
+		void handleFedChunkGetIngress(data, peerId, sendChunk)
+	})
+
+	getChunkData(data => {
+		if (!data?.requestId) return
+		handleFedChunkDataIngress(data)
+	})
+
+	getManifestGet((data, peerId) => {
+		if (guardGet && !guardGet(roomKey, 'fed_manifest_get', rtcLimits)) return
+		if (!data?.requestId) return
+		void handleFedManifestGetIngress(data, peerId, sendManifest)
+	})
+
+	getManifestData(data => {
+		if (!data?.requestId) return
+		handleFedManifestDataIngress(data)
+	})
+}

package/files/{chunk_store.mjs → chunk/store.mjs}

@@ -4,8 +4,8 @@ import fsp from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { pipeline } from 'node:stream/promises'
 
-import { isHex64 } from '../core/hexIds.mjs'
-import { getNodeDir } from '../node/instance.mjs'
+import { isHex64 } from '../../core/hexIds.mjs'
+import { getNodeDir } from '../../node/instance.mjs'
 
 /**
  * @returns {string} `{nodeDir}/chunks`

package/files/{chunk_fetch_verify.mjs → chunk/verify.mjs}

@@ -1,5 +1,5 @@
-import { isHex64 } from '../core/hexIds.mjs'
-import { sha256Hex } from '../crypto/crypto.mjs'
+import { isHex64 } from '../../core/hexIds.mjs'
+import { sha256Hex } from '../../crypto/crypto.mjs'
 
 /**
  * @param {string} chunkHash 期望的 64 hex 密文哈希

package/files/evfs.mjs

@@ -6,15 +6,15 @@ import { getEntityStore } from '../node/instance.mjs'
 
 import { buildFileManifestFromEnc, encryptPlaintextToMultiPartsAsync, encryptPlaintextToParts, manifestPartsForPersist } from './assemble.mjs'
 import { createManifestPlaintextStream, encryptReadableToParts } from './assemble_stream.mjs'
-import { fetchChunk } from './chunk_fetch.mjs'
-import { createChunkReadStream, getChunk, hasChunk, putChunk } from './chunk_store.mjs'
-import { normalizeFileManifest, publicTransferKeyDescriptor } from './manifest.mjs'
+import { fetchChunk } from './chunk/fetch.mjs'
+import { createChunkReadStream, getChunk, hasChunk, putChunk } from './chunk/store.mjs'
+import { normalizeFileManifest, publicTransferKeyDescriptor } from './manifest/normalize.mjs'
 import { assembleManifestPlaintext, resolveContentKey } from './transfer_key.mjs'
 import { readDagManifestPlaintext, resolveTransferKeyDependencies } from './transfer_key_registry.mjs'
 
 /**
  * @param {string} replicaUsername 副本用户名
- * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
  * @returns {{ getGroupFileMasterKey?: Function, getVaultMasterKey?: Function }} 密钥依赖
  */
 function transferKeyDependenciesForReplica(replicaUsername, manifest) {
@@ -31,7 +31,7 @@ function transferKeyDependenciesForReplica(replicaUsername, manifest) {
 
 /**
  * @param {string} username 拉取身份
- * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
  * @param {{ fetchChunk?: Function }} [options] miss 拉取
  * @returns {Promise<boolean>} 全部 part 是否已就位
  */
@@ -53,15 +53,14 @@ async function ensureManifestPartsLocal(username, manifest, options = {}) {
 /**
  * @param {string} ownerEntityHash 所有者
  * @param {string} logicalPath 路径
- * @returns {Promise<import('./manifest.mjs').FileManifest | null>} 归一化 manifest
+ * @returns {Promise<import('./manifest/normalize.mjs').FileManifest | null>} 本机已写盘的 manifest
  */
 export async function loadFileManifest(ownerEntityHash, logicalPath) {
-	const manifest = await getEntityStore().readManifest(ownerEntityHash, logicalPath)
-	return manifest ? normalizeFileManifest(manifest) : null
+	return getEntityStore().readManifest(ownerEntityHash, logicalPath)
 }
 
 /**
- * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
  * @returns {Promise<void>}
  */
 export async function saveFileManifest(manifest) {
@@ -69,7 +68,7 @@ export async function saveFileManifest(manifest) {
 }
 
 /**
- * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
  * @param {Array<Buffer | Uint8Array>} partBytes 密文块
  * @returns {Promise<void>}
  */
@@ -80,7 +79,7 @@ export async function storeManifestParts(manifest, partBytes) {
 
 /**
  * @param {string} replicaUsername 副本用户名
- * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
  * @param {{ username?: string, fetchChunk?: Function }} [options] miss 拉取
  * @returns {Promise<Buffer | null>} 明文内容
  */
@@ -104,7 +103,7 @@ export async function readManifestPlaintext(replicaUsername, manifest, options =
 
 /**
  * @param {string} replicaUsername 副本用户名
- * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
  * @param {{ username?: string, fetchChunk?: Function }} [options] miss 拉取
  * @returns {Promise<import('node:stream').Readable | null>} 明文流
  */
@@ -134,10 +133,10 @@ export async function readManifestPlaintextStream(replicaUsername, manifest, opt
  * @param {Buffer | Uint8Array} parameters.plaintext 明文
  * @param {string} [parameters.name] 文件名
  * @param {string} [parameters.mimeType] MIME
- * @param {import('./manifest.mjs').CeMode} [parameters.ceMode] 模式
- * @param {import('./manifest.mjs').TransferKeyDescriptor} [parameters.transferKeyDescriptor] 传递密钥
+ * @param {import('./manifest/normalize.mjs').CeMode} [parameters.ceMode] 模式
+ * @param {import('./manifest/normalize.mjs').TransferKeyDescriptor} [parameters.transferKeyDescriptor] 传递密钥
  * @param {object} [parameters.meta] meta
- * @returns {Promise<import('./manifest.mjs').FileManifest>} 写入后的 manifest
+ * @returns {Promise<import('./manifest/normalize.mjs').FileManifest>} 写入后的 manifest
  */
 export async function putFileManifest(parameters) {
 	const {
@@ -178,10 +177,10 @@ export async function putFileManifest(parameters) {
  * @param {number} parameters.plainSize 明文字节数
  * @param {string} [parameters.name] 文件名
  * @param {string} [parameters.mimeType] MIME
- * @param {import('./manifest.mjs').CeMode} [parameters.ceMode] 模式
- * @param {import('./manifest.mjs').TransferKeyDescriptor} [parameters.transferKeyDescriptor] 传递密钥
+ * @param {import('./manifest/normalize.mjs').CeMode} [parameters.ceMode] 模式
+ * @param {import('./manifest/normalize.mjs').TransferKeyDescriptor} [parameters.transferKeyDescriptor] 传递密钥
  * @param {object} [parameters.meta] meta
- * @returns {Promise<import('./manifest.mjs').FileManifest>} 写入后的 manifest
+ * @returns {Promise<import('./manifest/normalize.mjs').FileManifest>} 写入后的 manifest
  */
 export async function putFileManifestFromStream(parameters) {
 	const {
@@ -223,7 +222,7 @@ export async function putFileManifestFromStream(parameters) {
  * @returns {Promise<Buffer | null>} 明文或 null
  */
 export async function readPublicFile(replicaUsername, entityHash, logicalPath, options = {}) {
-	const { fetchPublicManifest } = await import('./manifest_fetch.mjs')
+	const { fetchPublicManifest } = await import('./manifest/fetch.mjs')
 	const manifest = await fetchPublicManifest({
 		username: options.username || replicaUsername,
 		ownerEntityHash: entityHash,

package/files/fed/fetch_shared.mjs

@@ -0,0 +1,39 @@
+import { randomUUID } from 'node:crypto'
+
+import { resolveNodeHash } from '../chunk/provider_registry.mjs'
+import { fanoutFedFetch } from '../fetch_fanout.mjs'
+
+/**
+ * inflight + pending wait + fanout 共用骨架。
+ * @template T
+ * @param {{
+ *   inflight: { acquire: (key: string, start: () => { done: Promise<T | null>, cancel: () => void }) => Promise<T | null> | null },
+ *   inflightKey: string,
+ *   username: string,
+ *   action: string,
+ *   registerWait: (requestId: string) => { done: Promise<T | null>, cancel: () => void },
+ *   buildPayload: (requestId: string, nodeHash: string) => object,
+ * }} options 选项
+ * @returns {Promise<T | null> | null} 共享 Promise；队满为 null
+ */
+export function beginFedFanoutFetch({
+	inflight,
+	inflightKey,
+	username,
+	action,
+	registerWait,
+	buildPayload,
+}) {
+	return inflight.acquire(inflightKey, () => {
+		const requestId = randomUUID()
+		const wait = registerWait(requestId)
+		void (async () => {
+			try {
+				const { nodeHash } = await resolveNodeHash(username)
+				await fanoutFedFetch(username, action, buildPayload(requestId, nodeHash))
+			}
+			catch { /* pending wait 超时/cancel 负责 settle */ }
+		})()
+		return { done: wait.done, cancel: wait.cancel }
+	})
+}

package/files/fed/responder.mjs

@@ -0,0 +1,47 @@
+import { subscribeWire } from '../../wire/subscribe.mjs'
+import { handleIncomingChunkGet } from '../chunk/fetch.mjs'
+import { resolvePendingChunkFetch } from '../chunk/pending.mjs'
+import { handleIncomingManifestGet } from '../manifest/fetch.mjs'
+import { resolvePendingManifestFetch } from '../manifest/pending.mjs'
+
+/** @typedef {import('../../wire/adapter.mjs').WireAdapter} WireAdapter */
+
+/**
+ * node scope wire：注册 fed_chunk_* + fed_manifest_*。
+ * @param {WireAdapter} wire action 表
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachNodeScopeFedResponder(wire) {
+	return subscribeWire(wire, {
+		/**
+		 * @param {unknown} data chunk 请求载荷
+		 * @param {string} peerId 对端 nodeHash
+		 */
+		fed_chunk_get(data, peerId) {
+			void handleIncomingChunkGet(data, (resp, pid) => {
+				try { wire.send('fed_chunk_data', resp, pid) }
+				catch { /* disconnected */ }
+			}, peerId)
+		},
+		/**
+		 * @param {unknown} data chunk 响应载荷
+		 */
+		fed_chunk_data(data) { resolvePendingChunkFetch(data) },
+		/**
+		 * @param {unknown} data manifest 请求载荷
+		 * @param {string} peerId 对端 nodeHash
+		 */
+		fed_manifest_get(data, peerId) {
+			void handleIncomingManifestGet(data, (resp, pid) => {
+				try { wire.send('fed_manifest_data', resp, pid) }
+				catch { /* disconnected */ }
+			}, peerId)
+		},
+		/**
+		 * @param {unknown} data manifest 响应载荷
+		 */
+		fed_manifest_data(data) {
+			void resolvePendingManifestFetch(data)
+		},
+	})
+}

package/files/{acl.mjs → manifest/acl.mjs}

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

package/files/{manifest_acl_registry.mjs → 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('./manifest.mjs').FileManifest | null | undefined, ownerEntityHash: string) => string | null }>} */
+/** @type {Map<string, { ownerId: string, match: (manifest: import('./normalize.mjs').FileManifest | null | undefined, ownerEntityHash: string) => string | null }>} */
 const matchersByOwner = new Map()
 
 /**
  * @typedef {{
  *   replicaUsername: string,
  *   ownerEntityHash: string,
- *   manifest: import('./manifest.mjs').FileManifest,
+ *   manifest: import('./normalize.mjs').FileManifest,
  * }} ManifestAclContext
  */
 
@@ -23,12 +23,10 @@ const matchersByOwner = new Map()
  * @returns {void}
  */
 export function registerManifestAcl(type, ownerId, handler) {
-	const key = String(type)
-	const owner = String(ownerId)
-	const existing = handlersByType.get(key)
-	if (existing && existing.ownerId !== owner)
-		throw new Error(`manifest acl handler for '${key}' already registered by '${existing.ownerId}'`)
-	handlersByType.set(key, { ownerId: owner, handler })
+	const existing = handlersByType.get(type)
+	if (existing && existing.ownerId !== ownerId)
+		throw new Error(`manifest acl handler for '${type}' already registered by '${existing.ownerId}'`)
+	handlersByType.set(type, { ownerId, handler })
 }
 
 /**
@@ -37,20 +35,19 @@ export function registerManifestAcl(type, ownerId, handler) {
  * @returns {void}
  */
 export function unregisterManifestAcl(type, ownerId) {
-	const key = String(type)
-	const existing = handlersByType.get(key)
+	const existing = handlersByType.get(type)
 	if (!existing) return
-	if (existing.ownerId === String(ownerId))
-		handlersByType.delete(key)
+	if (existing.ownerId === ownerId)
+		handlersByType.delete(type)
 }
 
 /**
  * @param {string} ownerId 注册方
- * @param {(manifest: import('./manifest.mjs').FileManifest | null | undefined, ownerEntityHash: string) => string | null} match ACL 类型匹配
+ * @param {(manifest: import('./normalize.mjs').FileManifest | null | undefined, ownerEntityHash: string) => string | null} match ACL 类型匹配
  * @returns {void}
  */
 export function registerManifestAclMatcher(ownerId, match) {
-	matchersByOwner.set(String(ownerId), { ownerId: String(ownerId), match })
+	matchersByOwner.set(ownerId, { ownerId, match })
 }
 
 /**
@@ -58,11 +55,11 @@ export function registerManifestAclMatcher(ownerId, match) {
  * @returns {void}
  */
 export function unregisterManifestAclMatcher(ownerId) {
-	matchersByOwner.delete(String(ownerId))
+	matchersByOwner.delete(ownerId)
 }
 
 /**
- * @param {import('./manifest.mjs').FileManifest | null | undefined} manifest manifest
+ * @param {import('./normalize.mjs').FileManifest | null | undefined} manifest manifest
  * @param {string} ownerEntityHash 所有者
  * @returns {string | null} ACL 类型
  */
@@ -81,7 +78,7 @@ export function resolveManifestAclType(manifest, ownerEntityHash) {
  * @returns {Promise<boolean>} 是否允许（未注册为 false）
  */
 export async function checkManifestAcl(type, context, logicalPath) {
-	const row = handlersByType.get(String(type))
+	const row = handlersByType.get(type)
 	if (!row?.handler) return false
 	return row.handler(context, logicalPath)
 }