@steve02081504/fount-p2p 0.0.4 → 0.0.6

package/files/assemble_stream.mjs

@@ -1,18 +1,15 @@
 import { Buffer } from 'node:buffer'
-import { createHash } from 'node:crypto'
+import { createHash, randomBytes } from 'node:crypto'
 import { Readable } from 'node:stream'
 
 import { FEDERATION_CHUNK_MAX_BYTES } from '../core/constants.mjs'
-import {
-	encryptConvergentPlaintext,
-	encryptRandomPlaintext,
-} from '../crypto/key.mjs'
 
+import { encryptSliceToPart } from './assemble.mjs'
 import { decryptPart } from './transfer_key.mjs'
 
 /**
  * @typedef {import('./manifest.mjs').CeMode} CeMode
- * @typedef {{ hash: string, size: number, raw: Buffer }} EncryptedPart
+ * @typedef {{ hash: string, size: number, raw: Buffer, contentHash?: string }} EncryptedPart
  */
 
 /**
@@ -21,15 +18,15 @@ import { decryptPart } from './transfer_key.mjs'
  * @param {CeMode} [ceMode] 加密模式
  * @param {(part: EncryptedPart) => Promise<void>} onPart 每块回调
  * @param {number} [maxBytes] 最大字节
- * @returns {Promise<{ contentHash: string, parts: Array<{ hash: string, size: number }>, contentKey?: Buffer }>} 分块结果
+ * @returns {Promise<{ contentHash: string, parts: Array<{ hash: string, size: number, contentHash?: string }>, contentKey?: Buffer }>} 分块结果
  */
 export async function encryptReadableToParts(readable, ceMode = 'convergent', onPart, maxBytes = Infinity) {
 	const digest = createHash('sha256')
 	/** @type {Buffer[]} */
 	let pending = Buffer.alloc(0)
-	/** @type {Array<{ hash: string, size: number }>} */
+	/** @type {Array<{ hash: string, size: number, contentHash?: string }>} */
 	const parts = []
-	let contentKey = null
+	const contentKey = ceMode === 'random' ? randomBytes(32) : null
 	let total = 0
 
 	/**
@@ -38,12 +35,11 @@ export async function encryptReadableToParts(readable, ceMode = 'convergent', on
 	 */
 	const flushSlice = async (slice) => {
 		digest.update(slice)
-		const enc = ceMode === 'random'
-			? encryptRandomPlaintext(slice)
-			: encryptConvergentPlaintext(slice)
-		if (ceMode === 'random') contentKey = enc.contentKey
-		const part = { hash: enc.ciphertextHash, size: enc.raw.length, raw: enc.raw }
-		parts.push({ hash: part.hash, size: part.size })
+		const part = encryptSliceToPart(slice, ceMode, contentKey)
+		/** @type {{ hash: string, size: number, contentHash?: string }} */
+		const meta = { hash: part.hash, size: part.size }
+		if (part.contentHash) meta.contentHash = part.contentHash
+		parts.push(meta)
 		await onPart(part)
 	}
 
@@ -71,55 +67,111 @@ export async function encryptReadableToParts(readable, ceMode = 'convergent', on
 }
 
 /**
- * 将 manifest 各密文块解密后串联为可读流。
+ * @param {import('node:stream').Readable} stream 密文流
+ * @returns {Promise<Buffer | null>} 下一可读块；流结束为 null
+ */
+function readStreamChunk(stream) {
+	const chunk = stream.read()
+	if (chunk) return Promise.resolve(Buffer.from(chunk))
+	if (stream.readableEnded) return Promise.resolve(null)
+	return new Promise((resolve, reject) => {
+		/**
+		 *
+		 */
+		const onReadable = () => {
+			cleanup()
+			const next = stream.read()
+			resolve(next ? Buffer.from(next) : Buffer.alloc(0))
+		}
+		/**
+		 *
+		 */
+		const onEnd = () => {
+			cleanup()
+			resolve(null)
+		}
+		/**
+		 * @param {Error} err 错误
+		 */
+		const onError = err => {
+			cleanup()
+			reject(err)
+		}
+		/**
+		 *
+		 */
+		const cleanup = () => {
+			stream.off('readable', onReadable)
+			stream.off('end', onEnd)
+			stream.off('error', onError)
+		}
+		stream.once('readable', onReadable)
+		stream.once('end', onEnd)
+		stream.once('error', onError)
+	})
+}
+
+/**
+ * 将 manifest 各密文块按 part.size 拼齐后解密，串联为明文可读流。
  * @param {import('./manifest.mjs').FileManifest} manifest 清单
  * @param {import('node:stream').Readable[]} partStreams 按序密文流
  * @param {Buffer | null} contentKey 随机密钥
  * @returns {Readable} 明文流
  */
 export function createManifestPlaintextStream(manifest, partStreams, contentKey) {
+	if (partStreams.length !== manifest.parts.length)
+		throw new Error('part stream count mismatch')
+
 	let partIndex = 0
-	let currentStream = null
+	/** @type {Buffer} */
+	let pending = Buffer.alloc(0)
 	const digest = createHash('sha256')
+	let finished = false
 
 	return new Readable({
 		/**
 		 *
 		 */
 		async read() {
+			if (finished) return
 			try {
-				while (true) {
-					if (!currentStream) {
-						if (partIndex >= partStreams.length) {
-							this.push(null)
-							return
-						}
-						currentStream = partStreams[partIndex++]
+				while (partIndex < manifest.parts.length) {
+					const need = Number(manifest.parts[partIndex].size) || 0
+					const stream = partStreams[partIndex]
+					while (pending.length < need) {
+						const more = await readStreamChunk(stream)
+						if (more === null) break
+						if (more.length) pending = Buffer.concat([pending, more])
+					}
+					if (pending.length < need) {
+						this.destroy(new Error('short ciphertext part'))
+						return
 					}
-					const chunk = currentStream.read()
-					if (chunk === null) {
-						currentStream = await new Promise((resolve, reject) => {
-							currentStream.once('end', () => resolve(null))
-							currentStream.once('error', reject)
-							currentStream.resume()
-						})
-						if (currentStream === null) {
-							currentStream = null
-							continue
-						}
+					const enc = pending.subarray(0, need)
+					pending = pending.subarray(need)
+					if (pending.length) {
+						this.destroy(new Error('trailing ciphertext in part stream'))
+						return
 					}
-					if (chunk?.length) {
-						const plain = decryptPart(Buffer.from(chunk), manifest, contentKey)
-						if (!plain) {
-							this.destroy(new Error('decrypt failed'))
-							return
-						}
-						digest.update(plain)
-						if (!this.push(plain))
-							return
+					const plain = decryptPart(enc, manifest, contentKey, partIndex)
+					if (!plain) {
+						this.destroy(new Error('decrypt failed'))
+						return
+					}
+					digest.update(plain)
+					partIndex++
+					this.push(plain)
+					return
+				}
+				if (manifest.contentHash) {
+					const got = digest.digest('hex')
+					if (got !== String(manifest.contentHash).toLowerCase()) {
+						this.destroy(new Error('contentHash mismatch'))
 						return
 					}
 				}
+				finished = true
+				this.push(null)
 			}
 			catch (error) {
 				this.destroy(error instanceof Error ? error : new Error(String(error)))

package/files/chunk_provider_registry.mjs

@@ -32,12 +32,6 @@ export function unregisterChunkProviders(ownerId) {
 	nodeHashProvidersByOwner.delete(key)
 }
 
-/** @returns {void} */
-export function clearChunkProviderRegistry() {
-	federationFetchersByOwner.clear()
-	nodeHashProvidersByOwner.clear()
-}
-
 /**
  * @param {string} username 用户
  * @param {string} groupId 群 ID

package/files/chunk_responder.mjs

@@ -71,7 +71,7 @@ export function attachNodeScopeFedChunkResponder(username, wire) {
  * 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] 出站队列
+ * @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] 房间键

package/files/chunk_store.mjs

@@ -2,7 +2,6 @@ import { Buffer } from 'node:buffer'
 import fs from 'node:fs'
 import fsp from 'node:fs/promises'
 import { dirname, join } from 'node:path'
-import { Readable } from 'node:stream'
 import { pipeline } from 'node:stream/promises'
 
 import { isHex64 } from '../core/hexIds.mjs'
@@ -74,14 +73,5 @@ export async function putChunk(hash, data) {
 export async function putChunkFromStream(hash, readable) {
 	const filePath = chunkStorePath(hash)
 	await fsp.mkdir(dirname(filePath), { recursive: true })
-	const writable = fs.createWriteStream(filePath)
-	await pipeline(readable, writable)
-}
-
-/**
- * @param {string} hash 64 位十六进制
- * @returns {Readable} chunk 可读流
- */
-export function chunkToReadable(hash) {
-	return createChunkReadStream(hash)
+	await pipeline(readable, fs.createWriteStream(filePath))
 }

package/files/evfs.mjs

@@ -4,13 +4,51 @@ import { Readable } from 'node:stream'
 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 { buildFileManifestFromEnc, encryptPlaintextToMultiPartsAsync, encryptPlaintextToParts, manifestPartsForPersist } from './assemble.mjs'
+import { createManifestPlaintextStream, encryptReadableToParts } from './assemble_stream.mjs'
 import { fetchChunk } from './chunk_fetch.mjs'
-import { getChunk, hasChunk, putChunk } from './chunk_store.mjs'
+import { createChunkReadStream, 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'
+import { assembleManifestPlaintext, resolveContentKey } from './transfer_key.mjs'
+import { readDagManifestPlaintext, resolveTransferKeyDependencies } from './transfer_key_registry.mjs'
+
+/**
+ * @param {string} replicaUsername 副本用户名
+ * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @returns {{ getGroupFileMasterKey?: Function, getVaultMasterKey?: Function }} 密钥依赖
+ */
+function transferKeyDependenciesForReplica(replicaUsername, manifest) {
+	const rawDependencies = resolveTransferKeyDependencies(undefined, manifest)
+	return {
+		getGroupFileMasterKey: rawDependencies.getGroupFileMasterKey
+			? (groupId, keyGeneration) => rawDependencies.getGroupFileMasterKey(replicaUsername, groupId, keyGeneration)
+			: undefined,
+		getVaultMasterKey: rawDependencies.getVaultMasterKey
+			? entityHash => rawDependencies.getVaultMasterKey(replicaUsername, entityHash)
+			: undefined,
+	}
+}
+
+/**
+ * @param {string} username 拉取身份
+ * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {{ fetchChunk?: Function }} [options] miss 拉取
+ * @returns {Promise<boolean>} 全部 part 是否已就位
+ */
+async function ensureManifestPartsLocal(username, manifest, options = {}) {
+	for (const part of manifest.parts) {
+		if (await hasChunk(part.hash)) continue
+		const fetchedChunk = await (options.fetchChunk || fetchChunk)({
+			username,
+			ciphertextHash: part.hash,
+			ownerEntityHash: manifest.ownerEntityHash,
+			groupId: manifest.transferKeyDescriptor.groupId,
+		})
+		if (!fetchedChunk) return false
+		await putChunk(part.hash, fetchedChunk)
+	}
+	return true
+}
 
 /**
  * @param {string} ownerEntityHash 所有者
@@ -43,61 +81,50 @@ export async function storeManifestParts(manifest, partBytes) {
 /**
  * @param {string} replicaUsername 副本用户名
  * @param {import('./manifest.mjs').FileManifest} manifest 清单
- * @param {{ username?: string, fetchChunk?: Function }} [opts] miss 拉取
+ * @param {{ username?: string, fetchChunk?: Function }} [options] miss 拉取
  * @returns {Promise<Buffer | null>} 明文内容
  */
-export async function readManifestPlaintext(replicaUsername, manifest, opts = {}) {
+export async function readManifestPlaintext(replicaUsername, manifest, options = {}) {
 	const dagGroupId = manifest.meta?.groupId
 	if (Array.isArray(manifest.meta?.dagParts) && dagGroupId) {
 		const dagPlain = await readDagManifestPlaintext(replicaUsername, manifest)
 		if (dagPlain) return dagPlain
 	}
 
-	const username = opts.username || replicaUsername
+	const username = options.username || replicaUsername
+	if (!await ensureManifestPartsLocal(username, manifest, options)) return null
+
 	/** @type {Buffer[]} */
 	const partBytes = []
-	for (const part of manifest.parts) {
-		let ciphertextBytes = null
-		if (await hasChunk(part.hash))
-			ciphertextBytes = await getChunk(part.hash)
-		else {
-			const fetchedChunk = await (opts.fetchChunk || fetchChunk)({
-				username,
-				ciphertextHash: part.hash,
-				ownerEntityHash: manifest.ownerEntityHash,
-				groupId: manifest.transferKeyDescriptor.groupId,
-			})
-			if (fetchedChunk) {
-				await putChunk(part.hash, fetchedChunk)
-				ciphertextBytes = Buffer.from(fetchedChunk)
-			}
-		}
-		if (!ciphertextBytes) return null
-		partBytes.push(ciphertextBytes)
-	}
+	for (const part of manifest.parts)
+		partBytes.push(await getChunk(part.hash))
 
-	const rawDeps = resolveTransferKeyDeps(undefined, manifest)
-	const deps = {
-		getGroupFileMasterKey: rawDeps.getGroupFileMasterKey
-			? (groupId, keyGeneration) => rawDeps.getGroupFileMasterKey(replicaUsername, groupId, keyGeneration)
-			: undefined,
-		getVaultMasterKey: rawDeps.getVaultMasterKey
-			? entityHash => rawDeps.getVaultMasterKey(replicaUsername, entityHash)
-			: undefined,
-	}
-	return assembleManifestPlaintext(manifest, partBytes, deps)
+	return assembleManifestPlaintext(manifest, partBytes, transferKeyDependenciesForReplica(replicaUsername, manifest))
 }
 
 /**
  * @param {string} replicaUsername 副本用户名
  * @param {import('./manifest.mjs').FileManifest} manifest 清单
- * @param {{ username?: string, fetchChunk?: Function }} [opts] miss 拉取
+ * @param {{ username?: string, fetchChunk?: Function }} [options] miss 拉取
  * @returns {Promise<import('node:stream').Readable | null>} 明文流
  */
-export async function readManifestPlaintextStream(replicaUsername, manifest, opts = {}) {
-	const plain = await readManifestPlaintext(replicaUsername, manifest, opts)
-	if (!plain) return null
-	return Readable.from(plain)
+export async function readManifestPlaintextStream(replicaUsername, manifest, options = {}) {
+	const dagGroupId = manifest.meta?.groupId
+	if (Array.isArray(manifest.meta?.dagParts) && dagGroupId) {
+		const plain = await readManifestPlaintext(replicaUsername, manifest, options)
+		if (!plain) return null
+		return Readable.from([plain])
+	}
+
+	const username = options.username || replicaUsername
+	if (!await ensureManifestPartsLocal(username, manifest, options)) return null
+
+	const dependencies = transferKeyDependenciesForReplica(replicaUsername, manifest)
+	const contentKey = await resolveContentKey(manifest.transferKeyDescriptor, manifest, dependencies)
+	if (manifest.ceMode === 'random' && !contentKey) return null
+
+	const partStreams = manifest.parts.map(part => createChunkReadStream(part.hash))
+	return createManifestPlaintextStream(manifest, partStreams, contentKey)
 }
 
 /**
@@ -178,7 +205,7 @@ export async function putFileManifestFromStream(params) {
 		size: plainSize,
 		contentHash: enc.contentHash,
 		ceMode,
-		parts: enc.parts,
+		parts: manifestPartsForPersist(enc.parts),
 		transferKeyDescriptor: transferKeyDescriptor || publicTransferKeyDescriptor(),
 		meta,
 	})
@@ -192,16 +219,16 @@ export async function putFileManifestFromStream(params) {
  * @param {string} replicaUsername 副本用户名
  * @param {string} entityHash owner entityHash
  * @param {string} logicalPath EVFS 逻辑路径
- * @param {{ username?: string, fetchChunk?: Function }} [opts] miss 拉取
+ * @param {{ username?: string, fetchChunk?: Function }} [options] miss 拉取
  * @returns {Promise<Buffer | null>} 明文或 null
  */
-export async function readPublicFile(replicaUsername, entityHash, logicalPath, opts = {}) {
+export async function readPublicFile(replicaUsername, entityHash, logicalPath, options = {}) {
 	const { fetchPublicManifest } = await import('./manifest_fetch.mjs')
 	const manifest = await fetchPublicManifest({
-		username: opts.username || replicaUsername,
+		username: options.username || replicaUsername,
 		ownerEntityHash: entityHash,
 		logicalPath,
 	})
 	if (!manifest) return null
-	return readManifestPlaintext(replicaUsername, manifest, opts)
+	return readManifestPlaintext(replicaUsername, manifest, options)
 }

package/files/manifest.mjs

@@ -3,7 +3,7 @@ import { isHex64 } from '../core/hexIds.mjs'
 
 /** @typedef {'plain' | 'convergent' | 'random'} CeMode */
 
-/** @typedef {{ hash: string, size: number }} ManifestPart */
+/** @typedef {{ hash: string, size: number, contentHash?: string }} ManifestPart */
 
 /**
  * @typedef {{
@@ -48,7 +48,16 @@ export function normalizeFileManifest(input) {
 	if (!CE_MODES.has(ceMode)) return null
 	const parts = Array.isArray(input.parts)
 		? input.parts
-			.map(part => ({ hash: String(part?.hash || '').trim().toLowerCase(), size: Number(part?.size) || 0 }))
+			.map(part => {
+				/** @type {ManifestPart} */
+				const out = {
+					hash: String(part?.hash || '').trim().toLowerCase(),
+					size: Number(part?.size) || 0,
+				}
+				const partContentHash = String(part?.contentHash || '').trim().toLowerCase()
+				if (isHex64(partContentHash)) out.contentHash = partContentHash
+				return out
+			})
 			.filter(part => isHex64(part.hash))
 		: []
 	if (!parts.length) return null

package/files/manifest_acl_registry.mjs

@@ -61,12 +61,6 @@ export function unregisterManifestAclMatcher(ownerId) {
 	matchersByOwner.delete(String(ownerId))
 }
 
-/** @returns {void} */
-export function clearManifestAclRegistry() {
-	handlersByType.clear()
-	matchersByOwner.clear()
-}
-
 /**
  * @param {import('./manifest.mjs').FileManifest | null | undefined} manifest manifest
  * @param {string} ownerEntityHash 所有者

package/files/transfer_key.mjs

@@ -15,26 +15,26 @@ import {
 /**
  * @param {TransferKeyDescriptor} descriptor 传递密钥描述符
  * @param {FileManifest} manifest manifest
- * @param {{ getGroupFileMasterKey?: (groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (entityHash: string) => Promise<Buffer | string | null> }} deps 密钥源
+ * @param {{ getGroupFileMasterKey?: (groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (entityHash: string) => Promise<Buffer | string | null> }} dependencies 密钥源
  * @returns {Promise<Buffer | null>} contentKey；plain/convergent 返回 null（按 contentHash 派生）
  */
-export async function resolveContentKey(descriptor, manifest, deps = {}) {
+export async function resolveContentKey(descriptor, manifest, dependencies = {}) {
 	const type = descriptor?.type || 'public'
 	if (type === 'public' || manifest.ceMode === 'plain' || manifest.ceMode === 'convergent')
 		return null
 
 	if (type === 'file-master-key-wrap') {
 		const { groupId, fileId } = descriptor
-		if (!groupId || !fileId || !descriptor.wrappedKey || !deps.getGroupFileMasterKey) return null
-		const groupKey = await deps.getGroupFileMasterKey(String(groupId), descriptor.keyGeneration)
+		if (!groupId || !fileId || !descriptor.wrappedKey || !dependencies.getGroupFileMasterKey) return null
+		const groupKey = await dependencies.getGroupFileMasterKey(String(groupId), descriptor.keyGeneration)
 		if (!groupKey) return null
 		return unwrapContentKey(descriptor.wrappedKey, groupKey, fileId)
 	}
 
 	if (type === 'vault-wrap') {
 		const { entityHash, fileId } = descriptor
-		if (!entityHash || !fileId || !descriptor.wrappedKey || !deps.getVaultMasterKey) return null
-		const vaultKey = await deps.getVaultMasterKey(String(entityHash))
+		if (!entityHash || !fileId || !descriptor.wrappedKey || !dependencies.getVaultMasterKey) return null
+		const vaultKey = await dependencies.getVaultMasterKey(String(entityHash))
 		if (!vaultKey) return null
 		return unwrapContentKey(descriptor.wrappedKey, vaultKey, fileId)
 	}
@@ -46,17 +46,23 @@ export async function resolveContentKey(descriptor, manifest, deps = {}) {
  * @param {Buffer | Uint8Array} encryptedPartBytes 密文块
  * @param {FileManifest} manifest manifest
  * @param {Buffer | null} contentKey random 模式密钥
+ * @param {number} [partIndex] 分块下标（多块 convergent 用 part.contentHash）
  * @returns {Buffer | null} 明文
  */
-export function decryptPart(encryptedPartBytes, manifest, contentKey) {
+export function decryptPart(encryptedPartBytes, manifest, contentKey, partIndex = 0) {
 	if (manifest.ceMode === 'plain')
 		return Buffer.from(encryptedPartBytes)
 
-	if (manifest.ceMode === 'convergent')
-		return decryptConvergentCiphertext(encryptedPartBytes, manifest.contentHash)
+	if (manifest.ceMode === 'convergent') {
+		const partPlainHash = manifest.parts[partIndex]?.contentHash || manifest.contentHash
+		return decryptConvergentCiphertext(encryptedPartBytes, partPlainHash)
+	}
 
-	if (manifest.ceMode === 'random' && contentKey)
-		return decryptRandomCiphertext(encryptedPartBytes, contentKey, manifest.contentHash)
+	if (manifest.ceMode === 'random' && contentKey) {
+		// 多块时各块明文 hash ≠ 整文件 contentHash；完整性在 assemble 末尾校验
+		const verifyHash = manifest.parts.length === 1 ? manifest.contentHash : ''
+		return decryptRandomCiphertext(encryptedPartBytes, contentKey, verifyHash)
+	}
 
 	return null
 }
@@ -64,16 +70,16 @@ export function decryptPart(encryptedPartBytes, manifest, contentKey) {
 /**
  * @param {FileManifest} manifest manifest
  * @param {Array<Buffer | Uint8Array>} partBytes 按序密文块
- * @param {{ getGroupFileMasterKey?: Function, getVaultMasterKey?: Function }} deps 密钥源
+ * @param {{ getGroupFileMasterKey?: Function, getVaultMasterKey?: Function }} dependencies 密钥源
  * @returns {Promise<Buffer | null>} 完整明文
  */
-export async function assembleManifestPlaintext(manifest, partBytes, deps = {}) {
+export async function assembleManifestPlaintext(manifest, partBytes, dependencies = {}) {
 	if (partBytes.length !== manifest.parts.length) return null
-	const contentKey = await resolveContentKey(manifest.transferKeyDescriptor, manifest, deps)
+	const contentKey = await resolveContentKey(manifest.transferKeyDescriptor, manifest, dependencies)
 	/** @type {Buffer[]} */
 	const plains = []
 	for (let index = 0; index < manifest.parts.length; index++) {
-		const plain = decryptPart(partBytes[index], manifest, contentKey)
+		const plain = decryptPart(partBytes[index], manifest, contentKey, index)
 		if (!plain) return null
 		plains.push(plain)
 	}

package/files/transfer_key_registry.mjs

@@ -1,18 +1,18 @@
 /** @type {Map<string, { getGroupFileMasterKey?: (replicaUsername: string, groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (replicaUsername: string, entityHash: string) => Promise<Buffer | string | null> }>} */
-const transferDepsByOwner = new Map()
+const transferDependenciesByOwner = new Map()
 
 /** @type {Map<string, (replicaUsername: string, manifest: import('./manifest.mjs').FileManifest) => Promise<Buffer | null>>} */
 const dagPlaintextReadersByOwner = new Map()
 
 /**
  * @param {string} ownerId 注册方
- * @param {{ getGroupFileMasterKey?: (replicaUsername: string, groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (replicaUsername: string, entityHash: string) => Promise<Buffer | string | null> }} deps 密钥源
+ * @param {{ getGroupFileMasterKey?: (replicaUsername: string, groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (replicaUsername: string, entityHash: string) => Promise<Buffer | string | null> }} dependencies 密钥源
  * @returns {void}
  */
-export function registerTransferKeyDeps(ownerId, deps) {
+export function registerTransferKeyDependencies(ownerId, dependencies) {
 	const key = String(ownerId)
-	const prev = transferDepsByOwner.get(key) || {}
-	transferDepsByOwner.set(key, { ...prev, ...deps })
+	const prev = transferDependenciesByOwner.get(key) || {}
+	transferDependenciesByOwner.set(key, { ...prev, ...dependencies })
 }
 
 /**
@@ -50,20 +50,13 @@ export function unregisterManifestOwnerMatchers(ownerId) {
  * @param {string} ownerId 注册方
  * @returns {void}
  */
-export function unregisterTransferKeyDeps(ownerId) {
+export function unregisterTransferKeyDependencies(ownerId) {
 	const key = String(ownerId)
-	transferDepsByOwner.delete(key)
+	transferDependenciesByOwner.delete(key)
 	dagPlaintextReadersByOwner.delete(key)
 	unregisterManifestOwnerMatchers(key)
 }
 
-/** @returns {void} */
-export function clearTransferKeyRegistry() {
-	transferDepsByOwner.clear()
-	dagPlaintextReadersByOwner.clear()
-	manifestOwnerMatchers.length = 0
-}
-
 /**
  * 从 manifest 推断 transfer key 注册方 id（按 registerManifestOwnerMatcher 注册顺序匹配）。
  * @param {import('./manifest.mjs').FileManifest} manifest 清单
@@ -80,9 +73,9 @@ export function resolveManifestTransferOwnerId(manifest) {
  * @param {import('./manifest.mjs').FileManifest} [manifest] 用于推断 ownerId
  * @returns {{ getGroupFileMasterKey?: (replicaUsername: string, groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (replicaUsername: string, entityHash: string) => Promise<Buffer | string | null> }} 依赖
  */
-export function resolveTransferKeyDeps(ownerId, manifest) {
+export function resolveTransferKeyDependencies(ownerId, manifest) {
 	const resolved = ownerId || (manifest ? resolveManifestTransferOwnerId(manifest) : null)
-	if (resolved) return transferDepsByOwner.get(String(resolved)) || {}
+	if (resolved) return transferDependenciesByOwner.get(String(resolved)) || {}
 	return {}
 }
 

package/governance/branch.mjs

@@ -93,17 +93,6 @@ export function descendantClosureFromTip(rootId, byId) {
 	return out
 }
 
-/**
- * 事件是否在 root 的后代闭包中（含 root）。
- * @param {string} eventId 事件 id
- * @param {string} rootId 根 id
- * @param {Map<string, object>} byId id→事件
- * @returns {boolean} 是否为 root 的后代（含 root 自身）
- */
-export function isDescendantOfTip(eventId, rootId, byId) {
-	return descendantClosureFromTip(rootId, byId).has(eventId)
-}
-
 /**
  * @param {string} tipId 叶 id
  * @param {Map<string, object>} byId id→事件