@steve02081504/fount-p2p 0.0.0

package/entity/files/evfs.mjs

@@ -0,0 +1,189 @@
+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'
+
+
+/**
+ * @param {string} ownerEntityHash 所有者
+ * @param {string} logicalPath 路径
+ * @returns {Promise<import('../../files/manifest.mjs').FileManifest | null>} 归一化 manifest
+ */
+export async function loadFileManifest(ownerEntityHash, logicalPath) {
+	const manifest = await getEntityStore().readManifest(ownerEntityHash, logicalPath)
+	return manifest ? normalizeFileManifest(manifest) : null
+}
+
+/**
+ * @param {import('../../files/manifest.mjs').FileManifest} manifest 清单
+ * @returns {Promise<void>}
+ */
+export async function saveFileManifest(manifest) {
+	await getEntityStore().writeManifest(manifest.ownerEntityHash, manifest.logicalPath, manifest)
+}
+
+/**
+ * @param {import('../../files/manifest.mjs').FileManifest} manifest 清单
+ * @param {Array<Buffer | Uint8Array>} partBytes 密文块
+ * @returns {Promise<void>}
+ */
+export async function storeManifestParts(manifest, partBytes) {
+	for (let index = 0; index < manifest.parts.length; index++)
+		await putChunk(manifest.parts[index].hash, partBytes[index])
+}
+
+/**
+ * @param {string} replicaUsername 副本用户名
+ * @param {import('../../files/manifest.mjs').FileManifest} manifest 清单
+ * @param {{ username?: string, fetchChunk?: Function }} [opts] miss 拉取
+ * @returns {Promise<Buffer | null>} 明文内容
+ */
+export async function readManifestPlaintext(replicaUsername, manifest, opts = {}) {
+	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
+	/** @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)
+	}
+
+	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)
+}
+
+/**
+ * @param {string} replicaUsername 副本用户名
+ * @param {import('../../files/manifest.mjs').FileManifest} manifest 清单
+ * @param {{ username?: string, fetchChunk?: Function }} [opts] 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)
+}
+
+/**
+ * @param {object} params 参数
+ * @param {string} params.ownerEntityHash owner
+ * @param {string} params.logicalPath 路径
+ * @param {Buffer | Uint8Array} params.plaintext 明文
+ * @param {string} [params.name] 文件名
+ * @param {string} [params.mimeType] MIME
+ * @param {import('../../files/manifest.mjs').CeMode} [params.ceMode] 模式
+ * @param {import('../../files/manifest.mjs').TransferKeyDescriptor} [params.transferKeyDescriptor] 传递密钥
+ * @param {object} [params.meta] meta
+ * @returns {Promise<import('../../files/manifest.mjs').FileManifest>} 写入后的 manifest
+ */
+export async function putFileManifest(params) {
+	const { encryptPlaintextToParts, encryptPlaintextToMultiPartsAsync } = await import('../../files/assemble.mjs')
+	const {
+		ownerEntityHash,
+		logicalPath,
+		plaintext,
+		name,
+		mimeType,
+		ceMode = 'convergent',
+		transferKeyDescriptor,
+		meta,
+	} = params
+	const plainBuf = Buffer.from(plaintext)
+	const enc = plainBuf.length > FEDERATION_CHUNK_MAX_BYTES
+		? await encryptPlaintextToMultiPartsAsync(plainBuf, ceMode)
+		: encryptPlaintextToParts(plainBuf, ceMode)
+	const manifest = buildFileManifestFromEnc({
+		ownerEntityHash,
+		logicalPath,
+		plaintext: plainBuf,
+		name,
+		mimeType,
+		ceMode,
+		transferKeyDescriptor: transferKeyDescriptor || publicTransferKeyDescriptor(),
+		meta,
+	}, enc)
+	await storeManifestParts(manifest, enc.parts.map(part => part.raw))
+	await saveFileManifest(manifest)
+	return manifest
+}
+
+/**
+ * 流式写入文件（请求流 -> 加密分块 -> chunk store）。
+ * @param {object} params 参数
+ * @param {string} params.ownerEntityHash owner
+ * @param {string} params.logicalPath 路径
+ * @param {import('node:stream').Readable} params.readable 明文流
+ * @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 {object} [params.meta] meta
+ * @returns {Promise<import('../../files/manifest.mjs').FileManifest>} 写入后的 manifest
+ */
+export async function putFileManifestFromStream(params) {
+	const {
+		ownerEntityHash,
+		logicalPath,
+		readable,
+		plainSize,
+		name,
+		mimeType,
+		ceMode = 'convergent',
+		transferKeyDescriptor,
+		meta,
+	} = params
+	const enc = await encryptReadableToParts(readable, ceMode, async part =>
+		putChunk(part.hash, part.raw), plainSize)
+	const manifest = normalizeFileManifest({
+		ownerEntityHash: ownerEntityHash.toLowerCase(),
+		logicalPath: logicalPath.replace(/^\/+/, ''),
+		name: name || logicalPath.split('/').pop() || 'file',
+		mimeType: mimeType || 'application/octet-stream',
+		size: plainSize,
+		contentHash: enc.contentHash,
+		ceMode,
+		parts: enc.parts,
+		transferKeyDescriptor: transferKeyDescriptor || publicTransferKeyDescriptor(),
+		meta,
+	})
+	if (!manifest) throw new Error('invalid manifest')
+	await saveFileManifest(manifest)
+	return manifest
+}

package/entity/files/evfs_ref.mjs

@@ -0,0 +1,37 @@
+import { isEntityHash128 } from '../../core/entity_id.mjs'
+import { assertSafeEvfsLogicalPath } from '../../core/evfs_logical_path.mjs'
+
+/**
+ *
+ */
+export const EVFS_SCHEME = 'evfs:'
+
+/**
+ * @param {string} entityHash 128 位十六进制
+ * @param {string} logicalPath EVFS 路径
+ * @returns {string} evfs URI 引用
+ */
+export function formatEvfsRef(entityHash, logicalPath) {
+	const eh = String(entityHash).trim().toLowerCase()
+	const safePath = assertSafeEvfsLogicalPath(logicalPath)
+	return `${EVFS_SCHEME}//${eh}/${safePath}`
+}
+
+/**
+ * @param {string} ref evfs URI
+ * @returns {{ entityHash: string, logicalPath: string } | null} 解析结果；非法为 null
+ */
+export function parseEvfsRef(ref) {
+	if (typeof ref !== 'string' || !ref.startsWith(EVFS_SCHEME)) return null
+	try {
+		const url = new URL(ref)
+		if (url.protocol !== 'evfs:') return null
+		const entityHash = String(url.hostname || '').trim().toLowerCase()
+		const logicalPath = String(url.pathname || '').replace(/^\/+/, '')
+		if (!isEntityHash128(entityHash)) return null
+		return { entityHash, logicalPath: assertSafeEvfsLogicalPath(logicalPath) }
+	}
+	catch {
+		return null
+	}
+}

package/entity/files/manifest_acl_registry.mjs

@@ -0,0 +1,93 @@
+/**
+ * Manifest ACL 注册表：按 transferKeyDescriptor.type 路由，不硬编码业务概念。
+ */
+
+/** @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 }>} */
+const matchersByOwner = new Map()
+
+/**
+ * @typedef {{
+ *   replicaUsername: string,
+ *   ownerEntityHash: string,
+ *   manifest: import('../../files/manifest.mjs').FileManifest,
+ * }} ManifestAclContext
+ */
+
+/**
+ * @param {string} type transferKeyDescriptor.type（如 vault-wrap、file-master-key-wrap）
+ * @param {string} ownerId 注册方
+ * @param {(context: ManifestAclContext, logicalPath?: string) => Promise<boolean>} handler ACL 检查
+ * @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 })
+}
+
+/**
+ * @param {string} type transferKeyDescriptor.type
+ * @param {string} ownerId 注册方
+ * @returns {void}
+ */
+export function unregisterManifestAcl(type, ownerId) {
+	const key = String(type)
+	const existing = handlersByType.get(key)
+	if (!existing) return
+	if (existing.ownerId === String(ownerId))
+		handlersByType.delete(key)
+}
+
+/**
+ * @param {string} ownerId 注册方
+ * @param {(manifest: import('../../files/manifest.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 })
+}
+
+/**
+ * @param {string} ownerId 注册方
+ * @returns {void}
+ */
+export function unregisterManifestAclMatcher(ownerId) {
+	matchersByOwner.delete(String(ownerId))
+}
+
+/** @returns {void} */
+export function clearManifestAclRegistry() {
+	handlersByType.clear()
+	matchersByOwner.clear()
+}
+
+/**
+ * @param {import('../../files/manifest.mjs').FileManifest | null | undefined} manifest manifest
+ * @param {string} ownerEntityHash 所有者
+ * @returns {string | null} ACL 类型
+ */
+export function resolveManifestAclType(manifest, ownerEntityHash) {
+	for (const { match } of matchersByOwner.values()) {
+		const type = match(manifest, ownerEntityHash)
+		if (type) return type
+	}
+	return null
+}
+
+/**
+ * @param {string} type transferKeyDescriptor.type
+ * @param {ManifestAclContext} context 上下文
+ * @param {string} [logicalPath] 写路径（仅写 ACL 需要）
+ * @returns {Promise<boolean>} 是否允许（未注册为 false）
+ */
+export async function checkManifestAcl(type, context, logicalPath) {
+	const row = handlersByType.get(String(type))
+	if (!row?.handler) return false
+	return row.handler(context, logicalPath)
+}

package/entity/files/replica_host_cache.mjs

@@ -0,0 +1,46 @@
+import { getEntityStore } from '../../node/instance.mjs'
+
+/** @type {Map<string, { replica: string | null, at: number }>} */
+const replicaHostCache = new Map()
+
+const REPLICA_HOST_CACHE_MS = 60_000
+
+/**
+ * @param {string | string[]} [entityHash] owner（单个或批量）
+ * @returns {void}
+ */
+export function invalidateReplicaHostCache(entityHash) {
+	if (Array.isArray(entityHash)) {
+		for (const eh of entityHash)
+			replicaHostCache.delete(String(eh).trim().toLowerCase())
+		return
+	}
+	if (entityHash) {
+		replicaHostCache.delete(String(entityHash).trim().toLowerCase())
+		return
+	}
+	replicaHostCache.clear()
+}
+
+/**
+ * @param {string} ownerEntityHash 所有者
+ * @returns {Promise<string | null>} 托管 manifest 的 replica
+ */
+export async function findReplicaHostingEntityFiles(ownerEntityHash) {
+	const eh = String(ownerEntityHash).trim().toLowerCase()
+	const cached = replicaHostCache.get(eh)
+	if (cached && Date.now() - cached.at < REPLICA_HOST_CACHE_MS)
+		return cached.replica
+
+	const store = getEntityStore()
+	if (typeof store.findHostingUser === 'function') {
+		const replica = await store.findHostingUser(eh)
+		replicaHostCache.set(eh, { replica, at: Date.now() })
+		return replica
+	}
+
+	const files = await store.listEntityFiles(eh)
+	const replica = files.length ? '__node__' : null
+	replicaHostCache.set(eh, { replica, at: Date.now() })
+	return replica
+}

package/entity/files/url.mjs

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

package/entity/hosting_registry.mjs

@@ -0,0 +1,47 @@
+/** @type {((username: string, entityHash: string) => string | null) | null} */
+let resolveAgentCharPartName = null
+
+/** @type {((username: string) => { entityHash: string, charPartName: string }[]) | null} */
+let listLocalAgents = null
+
+/**
+ * Chat Load 时注册：解析本地 agent 的 chars 目录名。
+ * @param {(username: string, entityHash: string) => string | null} resolver 解析函数
+ * @returns {void}
+ */
+export function registerAgentCharResolver(resolver) {
+	resolveAgentCharPartName = resolver
+}
+
+/**
+ * Chat Load 时注册：枚举 replica 下本地 agent 实体。
+ * @param {(username: string) => { entityHash: string, charPartName: string }[]} provider 枚举函数
+ * @returns {void}
+ */
+export function registerListLocalAgentsProvider(provider) {
+	listLocalAgents = provider
+}
+
+/** @returns {void} */
+export function unregisterAgentCharResolver() {
+	resolveAgentCharPartName = null
+}
+
+/** @returns {void} */
+export function unregisterListLocalAgentsProvider() {
+	listLocalAgents = null
+}
+
+/**
+ * @returns {((username: string, entityHash: string) => string | null) | null} 已注册解析器
+ */
+export function getAgentCharResolver() {
+	return resolveAgentCharPartName
+}
+
+/**
+ * @returns {((username: string) => { entityHash: string, charPartName: string }[]) | null} 已注册枚举器
+ */
+export function getListLocalAgentsProvider() {
+	return listLocalAgents
+}

package/entity/localized_core.mjs

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

package/entity/logical_entity.mjs

@@ -0,0 +1,25 @@
+import { encodeEntityHash, parseEntityHash } from '../core/entity_id.mjs'
+import { sha256TextHex } from '../crypto/crypto.mjs'
+
+/** @type {string} 逻辑实体 sentinel nodeHash（非物理节点绑定） */
+export const LOGICAL_ENTITY_SENTINEL_NODE_HASH = '0'.repeat(64)
+
+/**
+ * @param {string} subject 完整 subject 字符串（调用方负责命名空间前缀）
+ * @returns {string} 128 位 logical entityHash
+ */
+export function logicalEntityHash(subject) {
+	const s = String(subject || '').trim()
+	if (!s) throw new Error('subject required')
+	return encodeEntityHash(LOGICAL_ENTITY_SENTINEL_NODE_HASH, sha256TextHex(s))
+}
+
+/**
+ * @param {unknown} entityHash 128 位十六进制
+ * @returns {boolean} 是否为 logical entity（sentinel nodeHash）
+ */
+export function isLogicalEntityHash(entityHash) {
+	const parsed = parseEntityHash(entityHash)
+	if (!parsed) return false
+	return parsed.nodeHash === LOGICAL_ENTITY_SENTINEL_NODE_HASH
+}

package/entity/logical_entity_id_registry.mjs

@@ -0,0 +1,40 @@
+/** @type {Map<string, (username: string, entityHash: string) => Promise<string | null>>} */
+const resolversByOwner = new Map()
+
+/**
+ * @param {string} ownerId 注册方
+ * @param {(username: string, entityHash: string) => Promise<string | null>} resolver logical entity id 反查
+ * @returns {void}
+ */
+export function registerLogicalEntityIdResolver(ownerId, resolver) {
+	resolversByOwner.set(String(ownerId), resolver)
+}
+
+/**
+ * @param {string} ownerId 注册方
+ * @returns {void}
+ */
+export function unregisterLogicalEntityIdResolver(ownerId) {
+	resolversByOwner.delete(String(ownerId))
+}
+
+/** @returns {void} */
+export function clearLogicalEntityIdRegistry() {
+	resolversByOwner.clear()
+}
+
+/**
+ * @param {string} username 副本用户名
+ * @param {string} entityHash 128 位十六进制 logical entity
+ * @returns {Promise<string | null>} 逻辑实体 id
+ */
+export async function resolveLogicalEntityId(username, entityHash) {
+	for (const resolver of resolversByOwner.values())
+		try {
+			const id = await resolver(username, entityHash)
+			if (id) return id
+		}
+		catch { /* next */ }
+
+	return null
+}

package/entity/node_hash.mjs

@@ -0,0 +1,15 @@
+import { Buffer } from 'node:buffer'
+
+import { keyPairFromSeed, pubKeyHash } from '../crypto/crypto.mjs'
+
+/**
+ * 由持久化 nodeSeed 派生 nodeHash（64 hex）。
+ * @param {string} seedHex 32 字节 hex
+ * @returns {string} 节点哈希
+ */
+export function nodeHashFromSeed(seedHex) {
+	const seed = Buffer.from(String(seedHex).trim(), 'hex')
+	if (seed.length !== 32) throw new Error('invalid node seed')
+	const { publicKey } = keyPairFromSeed(seed)
+	return pubKeyHash(publicKey)
+}