@steve02081504/fount-p2p 0.0.2 → 0.0.4

package/files/public_manifest.mjs

@@ -0,0 +1,153 @@
+import { Buffer } from 'node:buffer'
+
+import { canonicalStringify } from '../core/canonical_json.mjs'
+import { hashFromPubKeyHex, parseEntityHash } from '../core/entity_id.mjs'
+import { assertSafeEvfsLogicalPath } from '../core/evfs_logical_path.mjs'
+import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
+import { sign, verify } from '../crypto/crypto.mjs'
+
+import { putFileManifest, saveFileManifest } from './evfs.mjs'
+import { normalizeFileManifest, publicTransferKeyDescriptor } from './manifest.mjs'
+
+/** 实体公开 manifest 签名域 */
+export const ENTITY_PUBLIC_MANIFEST_DOMAIN = 'fount-entity-public-manifest'
+
+/**
+ * @param {object} fields 待签名字段
+ * @returns {Buffer} 签名消息字节
+ */
+export function publicManifestSignBytes(fields) {
+	return Buffer.from(canonicalStringify([
+		ENTITY_PUBLIC_MANIFEST_DOMAIN,
+		String(fields.ownerEntityHash || '').trim().toLowerCase(),
+		assertSafeEvfsLogicalPath(fields.logicalPath),
+		Number(fields.publishedAt) || 0,
+		String(fields.contentHash || '').trim().toLowerCase(),
+		Number(fields.size) || 0,
+		String(fields.mimeType || ''),
+		String(fields.name || ''),
+		String(fields.ceMode || ''),
+		fields.parts || [],
+	]), 'utf8')
+}
+
+/**
+ * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {number} publishedAt 发布时间
+ * @param {Uint8Array | Buffer} entitySecretKey recovery 私钥种子
+ * @param {string} entityPubKeyHex recovery 公钥 hex
+ * @returns {Promise<import('./manifest.mjs').FileManifest>} 带 publicSig 的清单
+ */
+export async function attachPublicManifestSig(manifest, publishedAt, entitySecretKey, entityPubKeyHex) {
+	const pubKeyHex = normalizeHex64(entityPubKeyHex)
+	const message = publicManifestSignBytes({
+		ownerEntityHash: manifest.ownerEntityHash,
+		logicalPath: manifest.logicalPath,
+		publishedAt,
+		contentHash: manifest.contentHash,
+		size: manifest.size,
+		mimeType: manifest.mimeType,
+		name: manifest.name,
+		ceMode: manifest.ceMode,
+		parts: manifest.parts,
+	})
+	const sigHex = Buffer.from(await sign(message, entitySecretKey)).toString('hex')
+	return {
+		...manifest,
+		meta: {
+			...manifest.meta || {},
+			publicSig: { publishedAt, pubKeyHex, sigHex },
+		},
+	}
+}
+
+/**
+ * @param {unknown} input 原始 manifest
+ * @returns {Promise<import('./manifest.mjs').FileManifest | null>} 验签通过的清单；非法为 null
+ */
+export async function verifySignedPublicManifest(input) {
+	const manifest = normalizeFileManifest(input)
+	if (!manifest) return null
+	if (manifest.transferKeyDescriptor.type !== 'public') return null
+
+	const publicSig = input?.meta?.publicSig
+	if (!publicSig || typeof publicSig !== 'object') return null
+	const publishedAt = Number(publicSig.publishedAt) || 0
+	const pubKeyHex = normalizeHex64(publicSig.pubKeyHex)
+	const sigHex = String(publicSig.sigHex || '').trim().toLowerCase()
+	if (!isHex64(pubKeyHex) || !/^[\da-f]{128}$/u.test(sigHex) || publishedAt <= 0) return null
+
+	const parsed = parseEntityHash(manifest.ownerEntityHash)
+	if (!parsed) return null
+	if (hashFromPubKeyHex(pubKeyHex) !== parsed.subjectHash) return null
+
+	const message = publicManifestSignBytes({
+		ownerEntityHash: manifest.ownerEntityHash,
+		logicalPath: manifest.logicalPath,
+		publishedAt,
+		contentHash: manifest.contentHash,
+		size: manifest.size,
+		mimeType: manifest.mimeType,
+		name: manifest.name,
+		ceMode: manifest.ceMode,
+		parts: manifest.parts,
+	})
+	const ok = await verify(Buffer.from(sigHex, 'hex'), message, Buffer.from(pubKeyHex, 'hex'))
+	if (!ok) return null
+
+	// 签名只覆盖内容字段：入站 meta 一律丢弃，仅保留 publicSig，
+	// 防止中继注入 dagParts/groupId 等本地扩展改写读取路径。
+	return {
+		...manifest,
+		meta: { publicSig: { publishedAt, pubKeyHex, sigHex } },
+	}
+}
+
+/**
+ * @param {object | null | undefined} localManifest 本地已有清单
+ * @param {import('./manifest.mjs').FileManifest} incoming 入站已验签清单
+ * @returns {boolean} 是否应以 incoming 覆盖本地缓存
+ */
+export function shouldPreferIncomingPublicManifest(localManifest, incoming) {
+	const incomingAt = Number(incoming?.meta?.publicSig?.publishedAt) || 0
+	if (incomingAt <= 0) return false
+	const localAt = Number(localManifest?.meta?.publicSig?.publishedAt) || 0
+	return incomingAt > localAt
+}
+
+/**
+ * @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 {Uint8Array | Buffer} params.entitySecretKey recovery 私钥种子
+ * @param {string} params.entityPubKeyHex recovery 公钥 hex
+ * @param {number} [params.publishedAt] 发布时间（默认 Date.now）
+ * @returns {Promise<import('./manifest.mjs').FileManifest>} 已签名并落盘的公开清单
+ */
+export async function publishPublicFile(params) {
+	const {
+		ownerEntityHash,
+		logicalPath,
+		plaintext,
+		name,
+		mimeType,
+		entitySecretKey,
+		entityPubKeyHex,
+		publishedAt = Date.now(),
+	} = params
+	const base = await putFileManifest({
+		ownerEntityHash,
+		logicalPath,
+		plaintext,
+		name,
+		mimeType,
+		ceMode: 'convergent',
+		transferKeyDescriptor: publicTransferKeyDescriptor(),
+	})
+	const signed = await attachPublicManifestSig(base, publishedAt, entitySecretKey, entityPubKeyHex)
+	await saveFileManifest(signed)
+	return signed
+}

package/link/channel_mux.mjs

@@ -43,6 +43,8 @@ const DEFAULT_ACTION_PRIORITIES = Object.freeze({
 	fed_chunk_get: 5,
 	fed_chunk_data: 5,
 	fed_chunk_ack: 5,
+	fed_manifest_get: 5,
+	fed_manifest_data: 5,
 	fed_partition_bridge: 5,
 	fed_volatile: 10,
 })

package/node/identity.mjs

@@ -1,8 +1,9 @@
+import { Buffer } from 'node:buffer'
 import { randomBytes } from 'node:crypto'
 
-import { entityHashFromRecoveryPubKeyHex } from '../core/entity_id.mjs'
+import { entityHashFromRecoveryPubKeyHex, parseEntityHash } from '../core/entity_id.mjs'
 import { isHex64 } from '../core/hexIds.mjs'
-import { nodeHashFromSeed } from '../entity/node_hash.mjs'
+import { keyPairFromSeed, pubKeyHash } from '../crypto/crypto.mjs'
 import { normalizeMailboxSettings } from '../mailbox/settings.mjs'
 
 import { emitNodeChange } from './instance.mjs'
@@ -11,6 +12,18 @@ import { readNodeJsonSync, writeNodeJsonSync } from './storage.mjs'
 const NODE_SEED_HEX_RE = /^[\da-f]{64}$/iu
 const NODE_JSON = 'node'
 
+/**
+ * 由持久化 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)
+}
+
 /**
  * @returns {object} 节点配置磁盘对象
  */
@@ -97,3 +110,21 @@ export function entityHashFromKeys(nodeHash, recoveryPubKeyHex) {
 	if (!isHex64(nodeHash) || !isHex64(pub)) return null
 	return entityHashFromRecoveryPubKeyHex(nodeHash, pub)
 }
+
+/**
+ * @param {string} recoveryPubKeyHex 64 位十六进制 recovery 公钥
+ * @returns {string | null} 本节点 entityHash
+ */
+export function resolveLocalEntityHashFromRecoveryPubKeyHex(recoveryPubKeyHex) {
+	return entityHashFromKeys(getNodeHash(), recoveryPubKeyHex)
+}
+
+/**
+ * @param {string} entityHash 目标 entityHash
+ * @returns {boolean} 是否为本节点可写实体
+ */
+export function isWritableLocalEntity(entityHash) {
+	const parsed = parseEntityHash(entityHash)
+	if (!parsed) return false
+	return parsed.nodeHash === getNodeHash()
+}

package/node/personal_block.mjs

@@ -5,8 +5,8 @@
  */
 import { parseEntityHash } from '../core/entity_id.mjs'
 import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
-import { isWritableLocalEntity } from '../entity/replica.mjs'
 
+import { isWritableLocalEntity } from './identity.mjs'
 import { isNodeInitialized, getEntityStore } from './instance.mjs'
 
 /** @typedef {'subject' | 'entity'} PersonalListScope */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.2",
+	"version": "0.0.4",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",
@@ -45,8 +45,6 @@
 		"./rooms/*": "./rooms/*.mjs",
 		"./overlay": "./overlay/index.mjs",
 		"./overlay/*": "./overlay/*.mjs",
-		"./entity/*": "./entity/*.mjs",
-		"./entity/files/*": "./entity/files/*.mjs",
 		"./trust_graph/*": "./trust_graph/*.mjs",
 		"./mailbox/*": "./mailbox/*.mjs",
 		"./dag": "./dag/index.mjs",

package/transport/rtc_connection_budget.mjs

@@ -159,6 +159,8 @@ const NON_CRITICAL_FED_ACTIONS = new Set([
 	'fed_chunk_get',
 	'fed_chunk_data',
 	'fed_chunk_ack',
+	'fed_manifest_get',
+	'fed_manifest_data',
 	'part_invoke',
 	'discovery_announce',
 	'discovery_query',

package/entity/files/replica_host_cache.mjs

@@ -1,46 +0,0 @@
-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

@@ -1,19 +0,0 @@
-/**
- * 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

@@ -1,47 +0,0 @@
-/** @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

@@ -1,141 +0,0 @@
-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_id_registry.mjs

@@ -1,40 +0,0 @@
-/** @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

@@ -1,15 +0,0 @@
-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)
-}

package/entity/presentation_registry.mjs

@@ -1,44 +0,0 @@
-/** @typedef {{ query?: { locales?: string | string[] } }} ExpressLikeRequest */
-
-/** @type {((replicaUsername: string, entityHash: string, locales: string[]) => Promise<object>) | null} */
-let infoDefaultsProvider = null
-
-/** @type {((req: ExpressLikeRequest, replicaUsername: string) => string[]) | null} */
-let localesFromRequestProvider = null
-
-/**
- * @param {(replicaUsername: string, entityHash: string, locales: string[]) => Promise<object>} provider 资料默认值解析器
- * @returns {void}
- */
-export function registerEntityPresentationProvider(provider) {
-	infoDefaultsProvider = provider
-}
-
-/**
- * @param {(req: ExpressLikeRequest, replicaUsername: string) => string[]} provider 请求区域设置解析器
- * @returns {void}
- */
-export function registerLocalesFromRequestProvider(provider) {
-	localesFromRequestProvider = provider
-}
-
-/**
- * @param {string} replicaUsername 查看者 replica
- * @param {string} entityHash 目标实体
- * @param {string[]} locales 区域设置优先级
- * @returns {Promise<object | null>} 展示默认值或 null
- */
-export async function resolveInfoDefaultsForEntity(replicaUsername, entityHash, locales) {
-	if (!infoDefaultsProvider) return null
-	return infoDefaultsProvider(replicaUsername, entityHash, locales)
-}
-
-/**
- * @param {ExpressLikeRequest} req HTTP 请求
- * @param {string} replicaUsername 查看者 replica
- * @returns {string[]} 区域设置列表
- */
-export function localesFromRequest(req, replicaUsername) {
-	if (localesFromRequestProvider) return localesFromRequestProvider(req, replicaUsername)
-	return ['zh-CN', 'en-UK']
-}