@steve02081504/fount-p2p 0.0.37 → 0.0.39

package/AGENTS.md

@@ -53,12 +53,12 @@ Deno / native / BT: [runtime.md](docs/runtime.md).
 
 ### Trust / ingress
 
-- **Untrusted ingress only:** discovery adverts/signals, link/overlay envelopes, group federation frames, `remoteIngest`, `part_timeline_*` / `part_invoke`, `part_query_*`, public manifest (`fed_manifest_data`). Validate / `canonicalize*` / `verifySignedPublicManifest` **only** here.
+- **Untrusted ingress only:** discovery adverts/signals, link/overlay envelopes, group federation frames, `remoteIngest`, `part_timeline_*` / `part_invoke`, `part_query_*`, manifest fetch responses (`fed_manifest_data`). Validate / `canonicalize*` / `verifySignedPublicManifest` **only** here. Non-public `fed_manifest_data` is accepted only into an `allowNonPublic` pending slot (targeted fanout) and passes `normalizeFileManifest` + owner/path match — the serving node's servicer is the authorization gate. [evfs.md](docs/evfs.md)
 - **Trusted after disk:** from `events.jsonl`, only `stripDagEventLocalExtensions` — no re-canonicalization upstream.
 - **Fanout vs targeted / timed collect:** [wire.md](docs/wire.md).
 - **Channel encryption:** per-channel `K_ch`, scheme `channel-key` (`CHANNEL_KEY_SCHEME`); decrypted payloads are untrusted outside DAG Ed25519 context.
 - **Denylist vs personal lists:** node `denylist.json` vs per-entity `personal_block.json` / `personal_hide.json`.
-- **Manifest ACL / transfer owner:** shells register matchers; core does not hard-code chat/social types.
+- **Manifest ACL / transfer owner / servicer:** ownership is routed by `registerManifestOwner` matchers only; ACL & servicer handlers are keyed by `ownerId` (a `type` may be reused across families but never acts as a routing key). Core does not hard-code chat/social types. Non-public manifests are served cross-node only via a registered servicer; unclaimed non-public is denied (no `type` fallback).
 
 ### Node / network
 

package/docs/evfs.md

@@ -1,4 +1,4 @@
-# EVFS public manifests & fetch
+# EVFS manifests & fetch
 
 Day-to-day package rules: [AGENTS.md](../AGENTS.md). Implementation: `files/` (`evfs`, `evfs_ref`, `chunk/*`, `manifest/*`).
 
@@ -16,17 +16,29 @@ Day-to-day package rules: [AGENTS.md](../AGENTS.md). Implementation: `files/` (`
 - Signature covers **content fields only**. After verify, drop incoming `meta` except `publicSig`.
 - Profile / avatar meaning belongs in the shell — not in this package.
 
-## `fetchPublicManifest`
+## `fetchManifest`
 
 | Case | Behavior |
 | --- | --- |
-| Default options | No cache write |
-| Local hit with `publicSig` | Return immediately; fanout revalidates in the background. With `cache: true`, write only when remote `publishedAt` is newer |
-| Cold miss | Await fanout |
-| Same key in flight | Deduped via `utils/inflight_table` |
+| Default options | Node-scope fanout; **only** signed public manifests accepted; no cache write |
+| Local public hit with `publicSig` | Return immediately; fanout revalidates in the background. With `cache: true`, write only when remote `publishedAt` is newer |
+| Local non-public hit | Return immediately (**targeted mode only**); no revalidation (no publish order to compare); public mode refuses non-public local |
+| `fanoutTargets` given | Fanout **only** to that node set; accepts signed public **or** normalized non-public manifests; non-public hit is cached locally by default |
+| Same key in flight | Deduped via `utils/inflight_table` (key includes `public`/`targeted` mode) |
 
 Outer caller timeouts must **not** abort the in-flight work — background fill continues after the caller gives up.
 
-## ACL
+## Non-public (ACL-gated) manifests
 
-Shells register matchers via the ACL registry. Core does not hard-code chat/social entity types.
+- `file-master-key-wrap` / `vault-wrap` / `identity-wrap` manifests carry no author signature, so the remote-acquisition trust boundary is **not** a signature — it is the **fanout target set** plus the **serving node's authorization**.
+- Client: the caller passes the authorized node set (group roster / cabinet members) as `fanoutTargets`. `fed_manifest_get` is sent only to those nodes; a response is accepted when it normalizes, its `ownerEntityHash`+`logicalPath` match the request, and its authenticated `senderNodeHash` belongs to the target set.
+- Server: `handleIncomingManifestGet` refuses non-public manifests unless a **servicer** is registered for the matched owner family. Shells call `registerManifestOwner(ownerId, match)` to claim ownership and `registerManifestServicer(ownerId, handler)` to serve; the handler receives `{ manifest, ownerEntityHash, logicalPath, requesterNodeHash, peerId, payload }` and returns a boolean. `requesterNodeHash` is **always** the transport-authenticated sender nodeHash (`peerId`); the client no longer self-asserts a `nodeHash` in `fed_manifest_get`, so the fanout target node can never be mistaken for the requester — authorization must still be enforced from the trust graph / group membership.
+- Non-public responses carry the **full manifest including `meta`** (public responses strip meta to `publicSig`): the reader needs `meta.dagParts` / `meta.groupId` to read DAG plaintext.
+- Confidentiality does not rely on manifest secrecy: ciphertext blocks are content-addressed, AES-GCM authenticated, and decryption requires a wrap key held by the shell. A forged manifest can at worst fail the read (DoS), never decrypt content.
+
+## ACL & owner routing
+
+- Ownership is decided **only** by matchers: `registerManifestOwner(ownerId, match)` with `match(manifest, ownerEntityHash)` returning a boolean. `transferKeyDescriptor.type` is **not** a routing key — the same type (e.g. `file-master-key-wrap`) may be reused by several families (chat group, cabinet shared, vault, …).
+- Matchers must be mutually exclusive: a manifest belongs to exactly one family; resolution is first-match in registration order. A broad matcher that claims another family's entities will shadow them, so matchers should key on their own entity namespace (e.g. the `fount:chat:group:` prefix).
+- Local read/write ACL (`registerManifestAcl(ownerId, handler)`) and cross-node serve (`registerManifestServicer(ownerId, handler)`) are both keyed by `ownerId` (same `ownerId` as `registerTransferKeyDependencies`). A claimed family with no handler denies (fail-closed); an unclaimed non-public manifest is denied cross-node — there is no `type` fallback.
+- Core does not hard-code chat/social entity types.

package/files/chunk/responder.mjs

@@ -60,8 +60,8 @@ export function attachTrustGraphFedChunkResponder(room, fedOut, guardGet, rtcLim
 		void handleIncomingManifestGet(data, sendManifest, peerId)
 	})
 
-	getManifestData(data => {
+	getManifestData((data, peerId) => {
 		if (!data?.requestId) return
-		resolvePendingManifestFetch(data)
+		resolvePendingManifestFetch({ ...data, senderNodeHash: peerId })
 	})
 }

package/files/evfs.mjs

@@ -222,8 +222,8 @@ 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 manifest = await fetchPublicManifest({
+	const { fetchManifest } = await import('./manifest/fetch.mjs')
+	const manifest = await fetchManifest({
 		username: options.username || replicaUsername,
 		ownerEntityHash: entityHash,
 		logicalPath,

package/files/fed/fetch_shared.mjs

@@ -13,6 +13,7 @@ import { fanoutFedFetch } from '../fetch_fanout.mjs'
  *   action: string,
  *   registerWait: (requestId: string) => { done: Promise<T | null>, cancel: () => void },
  *   buildPayload: (requestId: string, nodeHash: string) => object,
+ *   fanoutTargets?: string[],
  * }} options 选项
  * @returns {Promise<T | null> | null} 共享 Promise；队满为 null
  */
@@ -23,6 +24,7 @@ export function beginFedFanoutFetch({
 	action,
 	registerWait,
 	buildPayload,
+	fanoutTargets,
 }) {
 	return inflight.acquire(inflightKey, () => {
 		const requestId = randomUUID()
@@ -30,7 +32,7 @@ export function beginFedFanoutFetch({
 		void (async () => {
 			try {
 				const { nodeHash } = await resolveNodeHash(username)
-				await fanoutFedFetch(username, action, buildPayload(requestId, nodeHash))
+				await fanoutFedFetch(username, action, buildPayload(requestId, nodeHash), fanoutTargets)
 			}
 			catch { /* pending wait 超时/cancel 负责 settle */ }
 		})()

package/files/fed/responder.mjs

@@ -39,9 +39,10 @@ export function attachNodeScopeFedResponder(wire) {
 		},
 		/**
 		 * @param {unknown} data manifest 响应载荷
+		 * @param {string} peerId 对端 nodeHash
 		 */
-		fed_manifest_data(data) {
-			void resolvePendingManifestFetch(data)
+		fed_manifest_data(data, peerId) {
+			void resolvePendingManifestFetch({ ...data, senderNodeHash: peerId })
 		},
 	})
 }

package/files/fetch_fanout.mjs

@@ -1,4 +1,5 @@
 import { FEDERATION_CHUNK_FETCH_FANOUT_K } from '../core/constants.mjs'
+import { isHex64 } from '../core/hexIds.mjs'
 import { loadNetwork } from '../node/network.mjs'
 import { ensureLinkToNode, listLinks } from '../transport/link_registry.mjs'
 import { DEFAULT_TRUST_GRAPH_OWNER, requireTrustGraphProvider } from '../trust_graph/registry.mjs'
@@ -19,20 +20,40 @@ function fetchPeerTargets() {
 	return [...targets]
 }
 
+/**
+ * 规范化目标节点集：过滤非 64hex、去重（保持插入序）。fanout 与 manifest in-flight key 共用。
+ * @param {string[]} [targets] 目标节点集
+ * @returns {string[]} 规范化后的目标节点集
+ */
+export function canonicalizeFanoutTargets(targets) {
+	return targets ? [...new Set(targets.filter(isHex64))] : []
+}
+
 /**
  * 全局 miss 请求扇出：先向已知 peer 定向发送，再 trust-graph top-K fanout。
  * 已直连 / follow hint peer 可能不在 trust-graph top-K（非成员 emoji CAS / Social 预览路径），故先定向发送。
  * @param {string} username 用户
  * @param {string} action wire action 名
  * @param {object} payload 请求载荷
+ * @param {string[]} [fanoutTargets] 显式目标节点集（非 public manifest 的授权边界）；提供时（含空/全非法集）只发目标集，不走 node-scope
  * @returns {Promise<void>}
  */
-export async function fanoutFedFetch(username, action, payload) {
-	const tg = requireTrustGraphProvider(DEFAULT_TRUST_GRAPH_OWNER)
-	const graph = await tg.buildMergedGraph(username)
+export async function fanoutFedFetch(username, action, payload, fanoutTargets) {
+	const trustGraph = requireTrustGraphProvider(DEFAULT_TRUST_GRAPH_OWNER)
+	if (fanoutTargets !== undefined) {
+		// 定向：只发显式目标集（非 public manifest 的授权边界）。
+		// 空/全非法集也视为定向——调用方显式提供目标集即声明授权边界，不发 node-scope。
+		// 依赖已有链路/群房间投递，不主动拨号——目标本就是已授权成员，无通道即不应服务。
+		const graph = await trustGraph.buildMergedGraph(username)
+		for (const nodeHash of canonicalizeFanoutTargets(fanoutTargets))
+			void trustGraph.sendToNode(username, nodeHash, action, payload, graph)
+		return
+	}
+
+	const graph = await trustGraph.buildMergedGraph(username)
 	const peerTargets = fetchPeerTargets()
 	await Promise.all(peerTargets.map(nodeHash => ensureLinkToNode(nodeHash).catch(() => null)))
 	for (const nodeHash of peerTargets)
-		void tg.sendToNode(username, nodeHash, action, payload, graph)
-	await tg.fanoutToTopNodes(username, action, payload, FEDERATION_CHUNK_FETCH_FANOUT_K)
+		void trustGraph.sendToNode(username, nodeHash, action, payload, graph)
+	await trustGraph.fanoutToTopNodes(username, action, payload, FEDERATION_CHUNK_FETCH_FANOUT_K)
 }

package/files/manifest/acl.mjs

@@ -1,38 +1,67 @@
 import { isLogicalEntityHash } from '../../core/logical_entity.mjs'
 import { isWritableLocalEntity } from '../../node/identity.mjs'
 
-import { checkManifestAcl, resolveManifestAclType } from './acl_registry.mjs'
+import { resolveManifestOwner } from './routing.mjs'
 
 /**
+ * @typedef {{
+ *   replicaUsername: string,
+ *   ownerEntityHash: string,
+ *   manifest: import('./normalize.mjs').FileManifest | object,
+ * }} ManifestAclContext
+ */
+
+/** @type {Map<string, (context: ManifestAclContext, logicalPath?: string) => Promise<boolean>>} */
+const aclHandlers = new Map()
+
+/**
+ * 注册本族 manifest 的本地读写授权判定（ownerId 须与 registerManifestOwner 一致）。
+ * @param {string} ownerId 注册方
+ * @param {(context: ManifestAclContext, logicalPath?: string) => Promise<boolean>} handler 授权判定
+ * @returns {void}
+ */
+export function registerManifestAcl(ownerId, handler) {
+	aclHandlers.set(ownerId, handler)
+}
+
+/**
+ * @param {string} ownerId 注册方
+ * @returns {void}
+ */
+export function unregisterManifestAcl(ownerId) {
+	aclHandlers.delete(ownerId)
+}
+
+/**
+ * 本地读授权：仅认 matcher 结果——命中族须注册 ACL handler，否则 deny。
  * @param {string} replicaUsername 请求 replica
  * @param {string} ownerEntityHash 文件 owner
  * @param {import('./normalize.mjs').FileManifest} manifest 清单
  * @returns {Promise<boolean>} 是否允许读
  */
 export async function canReadManifest(replicaUsername, ownerEntityHash, manifest) {
-	const type = resolveManifestAclType(manifest, ownerEntityHash)
-	if (type)
-		return checkManifestAcl(type, { replicaUsername, ownerEntityHash, manifest })
-
-	if (isLogicalEntityHash(ownerEntityHash))
+	const ownerId = resolveManifestOwner(manifest, ownerEntityHash)
+	if (ownerId) {
+		const handler = aclHandlers.get(ownerId)
+		if (handler) return handler({ replicaUsername, ownerEntityHash, manifest })
 		return false
-
-	return true
+	}
+	return !isLogicalEntityHash(ownerEntityHash)
 }
 
 /**
+ * 本地写授权：仅认 matcher 结果（写路径无 manifest，只按 ownerEntityHash 判定）。
  * @param {string} replicaUsername 请求 replica
  * @param {string} ownerEntityHash 所有者
  * @param {string} logicalPath 路径
  * @returns {Promise<boolean>} 是否允许写
  */
 export async function canWriteManifestPath(replicaUsername, ownerEntityHash, logicalPath) {
-	const type = resolveManifestAclType(null, ownerEntityHash)
-	if (type)
-		return checkManifestAcl(type, { replicaUsername, ownerEntityHash, manifest: /** @type {any} */ {} }, logicalPath)
-
-	if (isLogicalEntityHash(ownerEntityHash))
+	const ownerId = resolveManifestOwner(null, ownerEntityHash)
+	if (ownerId) {
+		const handler = aclHandlers.get(ownerId)
+		if (handler) return handler({ replicaUsername, ownerEntityHash, manifest: {} }, logicalPath)
 		return false
-
-	return isWritableLocalEntity(ownerEntityHash)
+	}
+	return !isLogicalEntityHash(ownerEntityHash) && isWritableLocalEntity(ownerEntityHash)
 }

package/files/manifest/fetch.mjs

@@ -6,6 +6,7 @@ import { ms } from '../../utils/duration.mjs'
 import { createInflightTable } from '../../utils/inflight_table.mjs'
 import { loadFileManifest, saveFileManifest } from '../evfs.mjs'
 import { beginFedFanoutFetch } from '../fed/fetch_shared.mjs'
+import { canonicalizeFanoutTargets } from '../fetch_fanout.mjs'
 
 import { normalizeFileManifest } from './normalize.mjs'
 import {
@@ -14,23 +15,27 @@ import {
 	registerManifestFetchWait,
 } from './pending.mjs'
 import { shouldPreferIncomingPublicManifest } from './public.mjs'
+import { resolveManifestOwner } from './routing.mjs'
+import { getManifestServicer } from './servicer_registry.mjs'
 
 const DEFAULT_MANIFEST_FETCH_TIMEOUT_MS = ms('8s')
 
-/** 同 username+owner+path 共享一次 fanout；队满只丢已超基础超时的队首。 */
+/** 同 username+owner+path+模式 共享一次 fanout；队满只丢已超基础超时的队首。 */
 const manifestInflight = createInflightTable({
 	maxSize: MAX_PENDING_MANIFEST_FETCHES,
 	baseTimeoutMs: DEFAULT_MANIFEST_FETCH_TIMEOUT_MS,
 })
 
 /**
- * 拉取公开 manifest；默认不写盘。`cache: true` 或 `cachePublicManifest` 才缓存。
- * 本地已有 publicSig 时立即返回，并后台 fanout；`cache: true` 时按 publishedAt 择新写盘。
- * 冷 miss 仍等 fanout。同 key in-flight 去重；调用方外层超时不 abort，后台继续填缓存。
- * @param {{ username: string, ownerEntityHash: string, logicalPath: string, cache?: boolean, timeoutMs?: number }} context - 拉取上下文
- * @returns {Promise<import('./normalize.mjs').FileManifest | null>} 验签后的 manifest，失败为 null
+ * 拉取 manifest。默认走 node-scope public 语义（仅接受验签公开 manifest）；
+ * 传入 `fanoutTargets` 时只向目标集 fanout，并接受无签名的非 public manifest（信任边界 = 目标集 + 服务端 servicer）。
+ * 非 public 命中默认写盘；public 按 `cache: true` 择新写盘。
+ * 本地已验签公开缓存立即返回（`cache: true` 时后台 fanout 刷新）；非 public / 未验签 public 本地命中仅 targeted 模式返回，
+ * public 模式拒绝。同 key（含规范化目标集）in-flight 去重；调用方外层超时不 abort，后台继续填缓存。
+ * @param {{ username: string, ownerEntityHash: string, logicalPath: string, fanoutTargets?: string[], cache?: boolean, timeoutMs?: number }} context - 拉取上下文
+ * @returns {Promise<import('./normalize.mjs').FileManifest | null>} 校验后的 manifest，失败为 null
  */
-export async function fetchPublicManifest(context) {
+export async function fetchManifest(context) {
 	const { ownerEntityHash, username } = context
 	const logicalPath = context.logicalPath.replace(/^\/+/, '')
 	if (!ownerEntityHash || !logicalPath || !username) return null
@@ -40,52 +45,67 @@ export async function fetchPublicManifest(context) {
 		: DEFAULT_MANIFEST_FETCH_TIMEOUT_MS
 	const expectedKey = manifestFetchExpectedKey(ownerEntityHash, logicalPath)
 	const wantCache = context.cache === true
+	const targeted = Array.isArray(context.fanoutTargets)
+	const fanoutTargets = targeted ? canonicalizeFanoutTargets(context.fanoutTargets) : undefined
 
-	// 先挂 in-flight（同步），再读本地 — 避免并发调用在 await 间隙各自 start
+	// 先同步挂 in-flight，再读本地 — 避免并发调用在 await 间隙各自 start（本地慢读可能晚于对端结算）。
 	const localPromise = loadFileManifest(ownerEntityHash, logicalPath)
 	const shared = beginFedFanoutFetch({
 		inflight: manifestInflight,
-		inflightKey: `${username}\0${expectedKey}`,
+		inflightKey: `${username}\0${expectedKey}\0${targeted ? 'targeted' : 'public'}` + (fanoutTargets?.length ? `\0${fanoutTargets.join('\0')}` : ''),
 		username,
 		action: 'fed_manifest_get',
 		/**
 		 * @param {string} requestId 请求 id
 		 * @returns {{ done: Promise<import('./normalize.mjs').FileManifest | null>, cancel: () => void }} 等待句柄
 		 */
-		registerWait: requestId => registerManifestFetchWait(requestId, expectedKey, timeoutMs),
+		registerWait: requestId => registerManifestFetchWait(
+			requestId,
+			expectedKey,
+			timeoutMs,
+			targeted ? { allowNonPublic: true, targetNodeHashes: fanoutTargets } : undefined,
+		),
 		/**
 		 * @param {string} requestId 请求 id
-		 * @param {string} nodeHash 目标节点 hash
 		 * @returns {object} fanout 载荷
 		 */
-		buildPayload: (requestId, nodeHash) => ({
+		buildPayload: requestId => ({
 			requestId,
-			nodeHash,
 			ownerEntityHash,
 			logicalPath,
 		}),
+		fanoutTargets,
 	})
-
 	const local = await localPromise
-	const hasLocalPublic = local?.transferKeyDescriptor?.type === 'public' && !!local?.meta?.publicSig
-	if (!shared) return hasLocalPublic ? local : null
 
-	if (hasLocalPublic) {
-		if (wantCache) void shared.then(async result => {
+	// 本地已验签公开命中：立即返回；cache: true 时后台 fanout 择新刷新。
+	const isLocalPublic = local?.transferKeyDescriptor?.type === 'public' && !!local?.meta?.publicSig
+	if (isLocalPublic) {
+		if (wantCache && shared) void shared.then(async result => {
 			if (result && shouldPreferIncomingPublicManifest(local, result))
 				await cachePublicManifest(ownerEntityHash, logicalPath, result)
 		})
 		return local
 	}
 
+	// 本地非 public / 未验签 public 命中：仅 targeted 模式返回（授权边界 = 目标集）；public 模式拒绝。
+	if (local) return targeted ? local : null
+
+	if (!shared) return null
+
 	const result = await shared
 	if (!result) return null
-	if (wantCache) await cachePublicManifest(ownerEntityHash, logicalPath, result)
+	if (wantCache || targeted)
+		if (result.transferKeyDescriptor.type === 'public')
+			await cachePublicManifest(ownerEntityHash, logicalPath, result)
+		else if (!isWritableLocalEntity(ownerEntityHash))
+			await saveFileManifest(result)
+
 	return result
 }
 
 /**
- * 将已验签公开 manifest 写入本地缓存（显式 apply；`fetchPublicManifest` 默认不调用）。
+ * 将已验签公开 manifest 写入本地缓存（显式 apply；`fetchManifest` public 模式默认不调用）。
  * @param {string} ownerEntityHash owner
  * @param {string} logicalPath 路径
  * @param {import('./normalize.mjs').FileManifest} incoming 已验签入站清单
@@ -99,10 +119,10 @@ export async function cachePublicManifest(ownerEntityHash, logicalPath, incoming
 }
 
 /**
- * 若本机有已签名公开 manifest 则响应 fed_manifest_get。
+ * 响应 fed_manifest_get：public 只回验签公开清单；非 public 经 ACL servicer 授权后回完整清单。
  * @param {object} payload 请求
  * @param {(response: object, peerId: string) => void} sendResponse 发送
- * @param {string} peerId 对端
+ * @param {string} peerId 对端（传输层认证的发送方 nodeHash，即 requesterNodeHash）
  * @returns {Promise<void>}
  */
 export async function handleIncomingManifestGet(payload, sendResponse, peerId) {
@@ -120,14 +140,31 @@ export async function handleIncomingManifestGet(payload, sendResponse, peerId) {
 	const raw = await getEntityStore().readManifest(ownerEntityHash, logicalPath)
 	const manifest = normalizeFileManifest(raw)
 	if (!manifest) return
-	if (manifest.transferKeyDescriptor.type !== 'public') return
-	if (!raw?.meta?.publicSig) return
-
-	sendResponse({
-		requestId,
-		manifest: {
-			...manifest,
-			meta: { publicSig: raw.meta.publicSig },
-		},
-	}, peerId)
+
+	if (manifest.transferKeyDescriptor.type === 'public') {
+		if (!raw?.meta?.publicSig) return
+		sendResponse({
+			requestId,
+			manifest: {
+				...manifest,
+				meta: { publicSig: raw.meta.publicSig },
+			},
+		}, peerId)
+		return
+	}
+
+	// 非 public：仅认 matcher 命中的族 servicer（无 matcher 即 deny，不按 transferKeyDescriptor.type 兜底路由）。
+	const ownerId = resolveManifestOwner(manifest, ownerEntityHash)
+	const servicer = getManifestServicer(ownerId)
+	if (!servicer) return
+	const allowed = await servicer({
+		manifest,
+		ownerEntityHash,
+		logicalPath,
+		requesterNodeHash: peerId,
+		peerId,
+		payload,
+	})
+	if (!allowed) return
+	sendResponse({ requestId, manifest }, peerId)
 }

package/files/manifest/pending.mjs

@@ -1,6 +1,7 @@
 import { compositeKey } from '../../core/composite_key.mjs'
 import { createFetchWaitTable } from '../../utils/fetch_wait.mjs'
 
+import { normalizeFileManifest } from './normalize.mjs'
 import { verifySignedPublicManifest } from './public.mjs'
 
 /** 并发 pending manifest fetch 上限。 */
@@ -24,14 +25,15 @@ export function manifestFetchExpectedKey(ownerEntityHash, logicalPath) {
  * @param {string} key requestId
  * @param {string} expectedKey owner+path 复合键
  * @param {number} timeoutMs 超时毫秒
+ * @param {{ allowNonPublic?: boolean, targetNodeHashes?: string[] }} [options] allowNonPublic 时接受无签名的非 public manifest（sender 须在 targetNodeHashes 内）
  * @returns {{ done: Promise<object | null>, cancel: () => void }} 等待 Promise 与取消
  */
-export function registerManifestFetchWait(key, expectedKey, timeoutMs) {
-	return table.register(key, expectedKey, timeoutMs)
+export function registerManifestFetchWait(key, expectedKey, timeoutMs, options) {
+	return table.register(key, expectedKey, timeoutMs, options)
 }
 
 /**
- * 处理 fed_manifest_data：验签通过后 resolve pending。
+ * 处理 fed_manifest_data：public 验签通过或（allowNonPublic 槽位）非 public 校验通过后 resolve pending。
  * @param {object} payload 入站载荷
  * @returns {Promise<boolean>} 是否命中并完成等待
  */
@@ -42,9 +44,21 @@ export async function resolvePendingManifestFetch(payload) {
 	if (!entry) return false
 
 	const verified = await verifySignedPublicManifest(payload?.manifest)
-	if (!verified) return false
-	const key = manifestFetchExpectedKey(verified.ownerEntityHash, verified.logicalPath)
-	if (key !== entry.expectedKey) return false
+	if (verified) {
+		const key = manifestFetchExpectedKey(verified.ownerEntityHash, verified.logicalPath)
+		if (key !== entry.expectedKey) return false
+		return table.settle(requestId, verified)
+	}
 
-	return table.settle(requestId, verified)
+	if (entry.options?.allowNonPublic) {
+		const normalized = normalizeFileManifest(payload?.manifest)
+		if (!normalized) return false
+		const key = manifestFetchExpectedKey(normalized.ownerEntityHash, normalized.logicalPath)
+		if (key !== entry.expectedKey) return false
+		// 授权边界 = 目标集：无签名 manifest 仅接受来自目标节点集的响应。
+		if (!entry.options?.targetNodeHashes?.includes(payload?.senderNodeHash)) return false
+		return table.settle(requestId, normalized)
+	}
+
+	return false
 }

package/files/manifest/routing.mjs

@@ -0,0 +1,38 @@
+/**
+ * Manifest 族路由：matcher 声明「该 manifest / 实体归哪个族（ownerId）所有」。
+ * matcher 是唯一路由依据（注册序先命中者）；`transferKeyDescriptor.type` 可被多族复用、不参与路由。
+ * 族间 matcher 必须互斥，否则按注册顺序先到先得。
+ */
+
+/** @type {Array<{ ownerId: string, match: (manifest: import('./normalize.mjs').FileManifest | null, ownerEntityHash: string) => boolean }>} */
+const owners = []
+
+/**
+ * @param {string} ownerId 注册方
+ * @param {(manifest: import('./normalize.mjs').FileManifest | null, ownerEntityHash: string) => boolean} match 归属判定
+ * @returns {void}
+ */
+export function registerManifestOwner(ownerId, match) {
+	owners.push({ ownerId, match })
+}
+
+/**
+ * @param {string} ownerId 注册方
+ * @returns {void}
+ */
+export function unregisterManifestOwner(ownerId) {
+	for (let index = owners.length - 1; index >= 0; index--)
+		if (owners[index].ownerId === ownerId) owners.splice(index, 1)
+}
+
+/**
+ * 解析 manifest 归属族；无命中为 null（非 public 跨节点即 deny）。
+ * @param {import('./normalize.mjs').FileManifest | null} manifest manifest（写路径可空）
+ * @param {string} ownerEntityHash 所有者
+ * @returns {string | null} 族 id
+ */
+export function resolveManifestOwner(manifest, ownerEntityHash) {
+	for (const { ownerId, match } of owners)
+		if (match(manifest, ownerEntityHash)) return ownerId
+	return null
+}

package/files/manifest/servicer_registry.mjs

@@ -0,0 +1,43 @@
+/**
+ * Manifest servicer 注册表：按族（ownerId）路由，决定跨节点是否对外提供非 public manifest。
+ * type 可被多族复用；路由只经 registerManifestOwner 的 matcher 唯一命中。服务端缺省 deny。
+ */
+
+/** @type {Map<string, (context: ManifestServicerContext) => Promise<boolean> | boolean>} */
+const servicersByOwner = new Map()
+
+/**
+ * @typedef {{
+ * 	manifest: import('./normalize.mjs').FileManifest,
+ * 	ownerEntityHash: string,
+ * 	logicalPath: string,
+ * 	requesterNodeHash: string,
+ * 	peerId: string,
+ * 	payload: object,
+ * }} ManifestServicerContext
+ */
+
+/**
+ * @param {string} ownerId 注册方（族，须与 registerManifestOwner 一致）
+ * @param {(context: ManifestServicerContext) => Promise<boolean> | boolean} handler 授权判定
+ * @returns {void}
+ */
+export function registerManifestServicer(ownerId, handler) {
+	servicersByOwner.set(ownerId, handler)
+}
+
+/**
+ * @param {string} ownerId 注册方
+ * @returns {void}
+ */
+export function unregisterManifestServicer(ownerId) {
+	servicersByOwner.delete(ownerId)
+}
+
+/**
+ * @param {string} ownerId 族 id
+ * @returns {(context: ManifestServicerContext) => Promise<boolean> | boolean | undefined} 已注册 handler
+ */
+export function getManifestServicer(ownerId) {
+	return servicersByOwner.get(ownerId)
+}

package/files/transfer_key_registry.mjs

@@ -1,3 +1,5 @@
+import { resolveManifestOwner } from './manifest/routing.mjs'
+
 /** @type {Map<string, { getGroupFileMasterKey?: (replicaUsername: string, groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (replicaUsername: string, entityHash: string) => Promise<Buffer | string | null> }>} */
 const transferDependenciesByOwner = new Map()
 
@@ -5,14 +7,13 @@ const transferDependenciesByOwner = new Map()
 const dagPlaintextReadersByOwner = new Map()
 
 /**
- * @param {string} ownerId 注册方
+ * @param {string} ownerId 注册方（族，须与 registerManifestOwner 一致）
  * @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 registerTransferKeyDependencies(ownerId, dependencies) {
-	const key = ownerId
-	const prev = transferDependenciesByOwner.get(key) || {}
-	transferDependenciesByOwner.set(key, { ...prev, ...dependencies })
+	const prev = transferDependenciesByOwner.get(ownerId) || {}
+	transferDependenciesByOwner.set(ownerId, { ...prev, ...dependencies })
 }
 
 /**
@@ -24,48 +25,13 @@ export function registerDagManifestPlaintextReader(ownerId, reader) {
 	dagPlaintextReadersByOwner.set(ownerId, reader)
 }
 
-/** @type {Array<{ ownerId: string, match: (manifest: import('./manifest/normalize.mjs').FileManifest) => boolean }>} */
-const manifestOwnerMatchers = []
-
-/**
- * @param {string} ownerId 注册方
- * @param {(manifest: import('./manifest/normalize.mjs').FileManifest) => boolean} match manifest 匹配谓词
- * @returns {void}
- */
-export function registerManifestOwnerMatcher(ownerId, match) {
-	manifestOwnerMatchers.push({ ownerId, match })
-}
-
-/**
- * @param {string} ownerId 注册方
- * @returns {void}
- */
-export function unregisterManifestOwnerMatchers(ownerId) {
-	const id = ownerId
-	for (let i = manifestOwnerMatchers.length - 1; i >= 0; i--)
-		if (manifestOwnerMatchers[i].ownerId === id) manifestOwnerMatchers.splice(i, 1)
-}
-
 /**
  * @param {string} ownerId 注册方
  * @returns {void}
  */
 export function unregisterTransferKeyDependencies(ownerId) {
-	const key = ownerId
-	transferDependenciesByOwner.delete(key)
-	dagPlaintextReadersByOwner.delete(key)
-	unregisterManifestOwnerMatchers(key)
-}
-
-/**
- * 从 manifest 推断 transfer key 注册方 id（按 registerManifestOwnerMatcher 注册顺序匹配）。
- * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
- * @returns {string | null} 所有者 id
- */
-export function resolveManifestTransferOwnerId(manifest) {
-	for (const { ownerId, match } of manifestOwnerMatchers)
-		if (match(manifest)) return ownerId
-	return null
+	transferDependenciesByOwner.delete(ownerId)
+	dagPlaintextReadersByOwner.delete(ownerId)
 }
 
 /**
@@ -74,7 +40,7 @@ export function resolveManifestTransferOwnerId(manifest) {
  * @returns {{ getGroupFileMasterKey?: (replicaUsername: string, groupId: string, keyGeneration?: number) => Promise<Buffer | string | null>, getVaultMasterKey?: (replicaUsername: string, entityHash: string) => Promise<Buffer | string | null> }} 依赖
  */
 export function resolveTransferKeyDependencies(ownerId, manifest) {
-	const resolved = ownerId || (manifest ? resolveManifestTransferOwnerId(manifest) : null)
+	const resolved = ownerId || (manifest ? resolveManifestOwner(manifest, manifest.ownerEntityHash) : null)
 	if (resolved) return transferDependenciesByOwner.get(resolved) || {}
 	return {}
 }
@@ -85,7 +51,7 @@ export function resolveTransferKeyDependencies(ownerId, manifest) {
  * @returns {Promise<Buffer | null>} 明文；无 reader 或未命中为 null
  */
 export async function readDagManifestPlaintext(replicaUsername, manifest) {
-	const ownerId = resolveManifestTransferOwnerId(manifest)
+	const ownerId = resolveManifestOwner(manifest, manifest.ownerEntityHash)
 	if (ownerId) {
 		const reader = dagPlaintextReadersByOwner.get(ownerId)
 		if (reader)
@@ -93,9 +59,7 @@ export async function readDagManifestPlaintext(replicaUsername, manifest) {
 				const buffer = await reader(replicaUsername, manifest)
 				if (buffer?.length) return buffer
 			}
-			catch { /* fall through */ }
-		return null
+			catch { /* 读取失败则回落到分块路径 */ }
 	}
-
 	return null
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.37",
+	"version": "0.0.39",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",

package/utils/fetch_wait.mjs

@@ -1,16 +1,21 @@
+/**
+ * 可扩展等待选项；`rejectOnTimeout` 由本表消费，其余字段透传存储供业务读取（不在此硬编码业务字段）。
+ * @typedef {{ rejectOnTimeout?: boolean, [key: string]: unknown }} FetchWaitOptions
+ */
+
 /**
  * 有界 pending fetch 等待表（chunk / manifest 等入站响应槽）。
  * @template T
  * @param {{ maxSize: number }} options 容量
  * @returns {{
- *   pending: Map<string, { expectedKey: string, timer: ReturnType<typeof setTimeout>, finish: (value: T | null | Error) => void, handle: { done: Promise<T | null>, cancel: () => void } }>,
- *   register: (key: string, expectedKey: string, timeoutMs: number, options?: { rejectOnTimeout?: boolean }) => { done: Promise<T | null>, cancel: () => void },
- *   peek: (key: string) => { expectedKey: string, timer: ReturnType<typeof setTimeout>, finish: (value: T | null | Error) => void, handle: { done: Promise<T | null>, cancel: () => void } } | undefined,
+ *   pending: Map<string, { expectedKey: string, timer: ReturnType<typeof setTimeout>, finish: (value: T | null | Error) => void, handle: { done: Promise<T | null>, cancel: () => void }, options: FetchWaitOptions }>,
+ *   register: (key: string, expectedKey: string, timeoutMs: number, options?: FetchWaitOptions) => { done: Promise<T | null>, cancel: () => void },
+ *   peek: (key: string) => { expectedKey: string, timer: ReturnType<typeof setTimeout>, finish: (value: T | null | Error) => void, handle: { done: Promise<T | null>, cancel: () => void }, options: FetchWaitOptions } | undefined,
  *   settle: (key: string, value: T | null | Error) => boolean,
  * }} 等待表 API
  */
 export function createFetchWaitTable({ maxSize }) {
-	/** @type {Map<string, { expectedKey: string, timer: ReturnType<typeof setTimeout>, finish: (value: T | null | Error) => void, handle: { done: Promise<T | null>, cancel: () => void } }>} */
+	/** @type {Map<string, { expectedKey: string, timer: ReturnType<typeof setTimeout>, finish: (value: T | null | Error) => void, handle: { done: Promise<T | null>, cancel: () => void }, options: FetchWaitOptions }>} */
 	const pending = new Map()
 
 	/**
@@ -34,7 +39,7 @@ export function createFetchWaitTable({ maxSize }) {
 		 * @param {string} key 唯一等待键
 		 * @param {string} expectedKey 期望匹配键
 		 * @param {number} timeoutMs 超时
-		 * @param {{ rejectOnTimeout?: boolean }} [options] 超时是否 reject
+		 * @param {FetchWaitOptions} [options] 可扩展等待选项（rejectOnTimeout 由本表消费）
 		 * @returns {{ done: Promise<T | null>, cancel: () => void }} 等待句柄
 		 */
 		register(key, expectedKey, timeoutMs, options = {}) {
@@ -80,14 +85,14 @@ export function createFetchWaitTable({ maxSize }) {
 				/** @returns {void} 取消等待 */
 				cancel: () => settle(key, null),
 			}
-			pending.set(key, { expectedKey, timer, finish, handle })
+			pending.set(key, { expectedKey, timer, finish, handle, options })
 			return handle
 		},
 
 		/**
 		 * 只读查看，不移除。
 		 * @param {string} key 等待键
-		 * @returns {{ expectedKey: string, timer: ReturnType<typeof setTimeout>, finish: (value: T | null | Error) => void, handle: { done: Promise<T | null>, cancel: () => void } } | undefined} 等待条目
+		 * @returns {{ expectedKey: string, timer: ReturnType<typeof setTimeout>, finish: (value: T | null | Error) => void, handle: { done: Promise<T | null>, cancel: () => void }, options: FetchWaitOptions } | undefined} 等待条目
 		 */
 		peek(key) {
 			return pending.get(key)

package/files/manifest/acl_registry.mjs

@@ -1,84 +0,0 @@
-/**
- * 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('./normalize.mjs').FileManifest | null | undefined, ownerEntityHash: string) => string | null }>} */
-const matchersByOwner = new Map()
-
-/**
- * @typedef {{
- *   replicaUsername: string,
- *   ownerEntityHash: string,
- *   manifest: import('./normalize.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 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 })
-}
-
-/**
- * @param {string} type transferKeyDescriptor.type
- * @param {string} ownerId 注册方
- * @returns {void}
- */
-export function unregisterManifestAcl(type, ownerId) {
-	const existing = handlersByType.get(type)
-	if (!existing) return
-	if (existing.ownerId === ownerId)
-		handlersByType.delete(type)
-}
-
-/**
- * @param {string} ownerId 注册方
- * @param {(manifest: import('./normalize.mjs').FileManifest | null | undefined, ownerEntityHash: string) => string | null} match ACL 类型匹配
- * @returns {void}
- */
-export function registerManifestAclMatcher(ownerId, match) {
-	matchersByOwner.set(ownerId, { ownerId, match })
-}
-
-/**
- * @param {string} ownerId 注册方
- * @returns {void}
- */
-export function unregisterManifestAclMatcher(ownerId) {
-	matchersByOwner.delete(ownerId)
-}
-
-/**
- * @param {import('./normalize.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(type)
-	if (!row?.handler) return false
-	return row.handler(context, logicalPath)
-}