@steve02081504/fount-p2p 0.0.36 → 0.0.38

package/docs/nostr_relay_discovery.md

@@ -0,0 +1,92 @@
+# Nostr Relay Discovery & Routing
+
+Nostr is the fount-network fallback transport (`link` level −∞, discovery `priority` 100). This document covers the **relay pool**, NIP-66 discovery, health scoring, advert relay-field signing, and handshake routing. Top-level surface: [signaling.md](signaling.md) · [transports.md](transports.md) · [mesh.md](mesh.md).
+
+Source layout (`discovery/nostr/`):
+- `index.mjs` — provider (presence / signal / advert subscriptions)
+- `relays.mjs` — pool, health, NIP-66 discovery, normalization, persistence
+- `selection.mjs` — handshake routing, backoff, fanout
+- `session.mjs` — shared relay WebSocket sessions / subscribe primitives
+- `census.mjs` — population census worker (kind 30789, HT estimate)
+- `census_math.mjs` — census pure functions (inclusion-probability update, HT estimator)
+- `constants.mjs` — hard limits
+
+## Three-tier sets
+
+`relayPool` (all known) → `workingRelays` (top-`WORKING_RELAYS_COUNT` by health) → `listenRelays` (top-`LISTEN_RELAYS_COUNT` working subset used for publish/listen).
+
+- `public`/`manual` entries are **pinned**: always in `working`/`listen` and never evicted by `clearStale` or pool-cap. Pin count may exceed the nominal caps.
+- `nip66`/`peer` entries are disposable: evicted when stale (`PROBE_STALE_MS`) or when the pool exceeds `POOL_CAP`.
+- Fresh nodes are seeded with `DEFAULT_RELAY_URLS` (`source: 'public'`) so `listenRelays` is never empty at cold start.
+- Persistent connections stay bounded by `workingRelays` (`WORKING_RELAYS_COUNT`, max 32); pins influence selection, not simultaneous connections.
+
+## URL normalization (single ingress)
+
+`normalizeNostrRelayUrl` (in `relays.mjs`) is the only entry for every inbound URL (NIP-66 `d` tag, manual config, peer advert):
+
+- `wss://` always; `ws://` only for loopback/private hosts (local dev/tests).
+- hostname lowercased, default port removed, trailing slashes removed, non-empty path kept.
+- Invalid → `null` → dropped with an audit log (`nodeDebug('invalidRelayUrl', { url, reason })`), never silently cleaned.
+
+## Health score
+
+```text
+failureRate = failureCount / (successCount + failureCount)
+rtt         = clamp(rttMs ?? DEFAULT_RTT_MS, 1, MAX_RTT_MS)
+score       = rtt * (1 + failureRate * FAILURE_WEIGHT)     // FAILURE_WEIGHT = 4
+score      *= STALE_PENALTY                                 // ×2 if lastProbe older than PROBE_STALE_MS
+```
+
+Lower is better. `recordProbeSuccess` / `recordProbeFailure` / `recordPublishResult` share the same counters. Writes to `nodeDir/nostr/relays.json` are **throttled** (2s debounce).
+
+## Persistence
+
+`nodeDir/nostr/relays.json`:
+
+```text
+{
+  "updatedAt": 1234567890,
+  "nostrRelays": [{ "url", "rttMs", "successCount", "failureCount", "lastSuccess", "lastFailure", "lastProbe", "firstSeen", "lastSeen", "source", "nips", "clearnet", "monitorCount" }],
+  "peerRoutes": { "<nodeHash64>": { "listenRelays", "peerPool", "lastGoodNostrRelays", "lastSeen" } }
+}
+```
+
+`peerRoutes` is a local-only cache (never shared).
+
+## NIP-66 discovery
+
+- Bootstrap: `NIP66_BOOTSTRAP_RELAYS` + all `public`/`manual` as fallback, parallel, 10s connect timeout; refreshed every `NIP66_REFRESH_MS` (6h).
+- `REQ` kind 30166 (limit 500) + optional 10166; parse `d` (url), `n` (clearnet only), `N` (must include NIP-01 or be absent), `rtt-open/read/write`.
+- **Trust layering**: same URL reported by ≥2 distinct pubkeys → `monitorCount ≥ 2`; single report is untrusted. All candidates are probed; a successful probe upserts the entry (`source: 'nip66'`, real `monitorCount`), a failed probe drops it. Probes per round are bounded (`MAX_NIP66_PROBES_PER_ROUND`).
+- Discovery is non-blocking (first round deferred to the next macrotask) and cancellable (AbortSignal tears down sockets + NIP-11 fetches), so it never blocks `ensureRuntime` or shutdown.
+- `setNostrRelayDiscoveryEnabledForTests(false)` / `setNip66BootstrapRelaysForTests(urls)` are test-only hooks.
+
+## Advert relay fields & signature
+
+`link/handshake.mjs` extends the advert signature domain: after `lanHosts`, append `\0relays:<hex>` where `<hex>` = UTF-8→hex of `{ p: pool, l: listen }` (both sorted by url, `pool` items `{url, rtt}`).
+
+- `sanitizeAdvertRelayFields` (verify/inbound path): pool ≤ `MAX_ADVERT_RELAY_POOL` (16), rtt ∈ [0, `MAX_RTT_MS`], deduped; listen ≤ `MAX_ADVERT_LISTEN_RELAYS` (32), deduped; dropped entries logged. `buildSignedAdvert` (outbound) uses a strict variant that throws on invalid locally-supplied relay fields instead of dropping them.
+- `verifySignedAdvert` now returns `{ nodeHash, relayPool, listenRelays }` (sanitized). `ingest*Advert` passes these through; consumers must use the verified values, never the raw body.
+- **Any tampering with relay fields invalidates the signature** → advert rejected.
+
+## Handshake routing (`selection.mjs`)
+
+`handshakeTargets(nodeHash, attempt)`:
+- **Round 0**: peer-claimed `listenRelays` top 4 by composite score (own health + peer rtt); else local `workingRelays` top 4; else pinned top 4.
+- **Round ≥1**: backoff `min(2000 · 2^(attempt−1), 60000)`; base on `lastGoodNostrRelays` (expanded via `expandFromHistory` ≤ 16), or weighted-random sample of `workingRelays` (weight `1/score`); round-0 core always included; fanout capped at `MAX_ROUTING_FANOUT` (64).
+- Retries ≤ `MAX_ROUTING_ATTEMPTS` (4).
+
+`routePublishEvent(toNodeHash, event, signal)`: publishes to the current round's targets in parallel via shared sessions; any `OK` records `lastGoodNostrRelays` (last 16) + success; all-fail records failures and backs off. `sendNodeSignal` uses routing; an explicit relay override (test/user pin) publishes directly.
+
+## Census (population estimate)
+
+`census.mjs` implements a population census over nostr (event kind 30789, `t=fount` / `x=census`, content = base64 of the signed packet). It is driven by the `features.census` switch (`setP2PFeatures`).
+
+- Each node keeps an inclusion probability `p`; per window it publishes an Ed25519-signed packet `{ nodeHash, nodePubKey, ts, p, sig }` (message `fount-census\0ts\0nodeHash\0p`) when `rand < p`.
+- The multiplier updates `p' = p·(T/E)` (T = `CENSUS_TARGET_EVENTS`, E = observed window events); E == 0 probes upward by `CENSUS_GROW_FACTOR`. `clampP` keeps `p` in `[CENSUS_MIN_P, 1]`.
+- Readers estimate online nodes with the HT estimator `M̂ = Σ(1/p)` (`estimatePopulation` in `census_math.mjs`), subtract the self-event's weight (`−1/p_self`) and add exactly 1 for the self node.
+- Ingress packets are untrusted: `verifyCensusPacket` canonicalizes, checks `ts` within `CENSUS_TTL_MS`, requires `p ∈ [CENSUS_MIN_P, 1]`, and verifies `nodeHash = sha256(nodePubKey)` plus the Ed25519 signature before `noteCensusEvent` stores the event (deduped by `nodeHash`).
+
+## Config
+
+`channels.nostr.relay` (non-empty array) **overrides** the whole relay set — published/subscribed relays come from that list, not the pool. Without it, `resolveNostrRelayUrls()` returns `getListenRelays()`.

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/fetch.mjs

@@ -6,7 +6,9 @@ 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 { resolveManifestAclType } from './acl_registry.mjs'
 import { normalizeFileManifest } from './normalize.mjs'
 import {
 	manifestFetchExpectedKey,
@@ -14,23 +16,26 @@ import {
 	registerManifestFetchWait,
 } from './pending.mjs'
 import { shouldPreferIncomingPublicManifest } from './public.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,54 +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 => {
-				if (result && shouldPreferIncomingPublicManifest(local, result))
-					await cachePublicManifest(ownerEntityHash, logicalPath, 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 已验签入站清单
@@ -101,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) {
@@ -122,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：ACL servicer 授权后回完整 manifest（读侧解密依赖 meta.dagParts / groupId）。
+	const aclType = resolveManifestAclType(manifest, ownerEntityHash) || manifest.transferKeyDescriptor.type
+	const servicer = getManifestServicer(aclType)
+	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/servicer_registry.mjs

@@ -0,0 +1,51 @@
+/**
+ * Manifest servicer 注册表：按 ACL 类型路由，决定跨节点是否对外提供非 public manifest。
+ * 服务端缺省 deny；未注册的类型直接不响应 fed_manifest_get。
+ */
+
+/** @type {Map<string, { ownerId: string, handler: (context: ManifestServicerContext) => Promise<boolean> | boolean }>} */
+const servicersByType = new Map()
+
+/**
+ * @typedef {{
+ *   manifest: import('./normalize.mjs').FileManifest,
+ *   ownerEntityHash: string,
+ *   logicalPath: string,
+ *   requesterNodeHash: string,
+ *   peerId: string,
+ *   payload: object,
+ * }} ManifestServicerContext
+ */
+
+/**
+ * @param {string} type ACL 类型（如 vault-wrap、file-master-key-wrap，或 resolveManifestAclType 匹配结果）
+ * @param {string} ownerId 注册方
+ * @param {(context: ManifestServicerContext) => Promise<boolean> | boolean} handler 授权判定
+ * @returns {void}
+ */
+export function registerManifestServicer(type, ownerId, handler) {
+	const existing = servicersByType.get(type)
+	if (existing && existing.ownerId !== ownerId)
+		throw new Error(`manifest servicer for '${type}' already registered by '${existing.ownerId}'`)
+	servicersByType.set(type, { ownerId, handler })
+}
+
+/**
+ * @param {string} type ACL 类型
+ * @param {string} ownerId 注册方
+ * @returns {void}
+ */
+export function unregisterManifestServicer(type, ownerId) {
+	const existing = servicersByType.get(type)
+	if (!existing) return
+	if (existing.ownerId === ownerId)
+		servicersByType.delete(type)
+}
+
+/**
+ * @param {string} type ACL 类型
+ * @returns {(context: ManifestServicerContext) => Promise<boolean> | boolean | undefined} 已注册 handler
+ */
+export function getManifestServicer(type) {
+	return servicersByType.get(type)?.handler
+}

package/governance/branch.mjs

@@ -104,7 +104,7 @@ function governanceAuthzScoreForTip(tipId, byId, reputationBySender) {
 	for (const eventId of ancestorClosureFromTip(tipId, byId)) {
 		const event = byId.get(eventId)
 		if (!event || !getGovernanceAuthzTypes().has(event.type)) continue
-		const sender = event.sender
+		const { sender } = event
 		if (sender) score += Number(reputationBySender[sender] ?? 0)
 	}
 	return score

package/governance/join_pow.mjs

@@ -103,8 +103,8 @@ export function verifyJoinPow(powSolution, options) {
 	const anchorRef = String(powSolution.anchorRef ?? '')
 	const { nonce } = powSolution
 	const epoch = Number(powSolution.epoch)
-	const joinerNodeHash = powSolution.joinerNodeHash ?? options.senderNodeHash
-	const senderNodeHash = options.senderNodeHash
+	const { senderNodeHash } = options
+	const joinerNodeHash = powSolution.joinerNodeHash ?? senderNodeHash
 
 	if (!anchorRef || nonce == null || !Number.isFinite(epoch)) return { ok: false, achievedBits: 0 }
 	if (!joinerNodeHash || joinerNodeHash !== senderNodeHash) return { ok: false, achievedBits: 0 }

package/index.mjs

@@ -2,6 +2,7 @@
  * Federation P2P 门面：fount 网络引导与房间/发现入口。
  */
 import { registerDiscoveryProvider } from './discovery/index.mjs'
+import { getNodePopulationEstimate } from './discovery/nostr/census.mjs'
 import {
 	isInfraRunning,
 	setInfraPriority,
@@ -13,9 +14,11 @@ import { ensureNodeDefaults, getNodeHash } from './node/identity.mjs'
 import {
 	closeNode,
 	getNodeDir,
+	getP2PFeatures,
 	initNode,
 	isNodeInitialized,
 	setNodeLogger,
+	setP2PFeatures,
 	setSignalingRuntimeConfig,
 } from './node/instance.mjs'
 import { setConnectivityDebug } from './node/log.mjs'
@@ -73,6 +76,8 @@ export {
 	getLinkRegistry,
 	getNodeDir,
 	getNodeHash,
+	getNodePopulationEstimate,
+	getP2PFeatures,
 	getPeerHealth,
 	getReputationExportAllowlist,
 	getReputationLocks,
@@ -94,6 +99,7 @@ export {
 	setConnectivityDebug,
 	setInfraPriority,
 	setNodeLogger,
+	setP2PFeatures,
 	setReputationExportAllowlist,
 	setReputationTable,
 	setRoutingProfile,
@@ -105,20 +111,21 @@ export {
 }
 
 /**
- * @param {{ nodeDir?: string, entityStore?: import('./node/entity_store.mjs').EntityStore, logger?: object | null, signaling?: import('./node/signaling_config.mjs').SignalingRuntimeConfig }} [options] - 首次 init 时的节点选项
+ * @param {{ nodeDir?: string, entityStore?: import('./node/entity_store.mjs').EntityStore, logger?: object | null, signaling?: import('./node/signaling_config.mjs').SignalingRuntimeConfig, features?: Record<string, boolean> }} [options] - 首次 init 时的节点选项
  * @returns {Promise<void>}
  */
 export async function startNode(options = {}) {
 	if (!isNodeInitialized()) {
-		const { nodeDir, entityStore, logger, signaling, ...rest } = options
+		const { nodeDir, entityStore, logger, signaling, features, ...rest } = options
 		if (Object.keys(rest).length)
 			throw new Error('p2p: startNode unknown options')
 		initNode({ nodeDir, entityStore })
 		if (logger !== undefined) setNodeLogger(logger)
 		if (signaling !== undefined) setSignalingRuntimeConfig(signaling)
+		if (features !== undefined) setP2PFeatures(features)
 	}
-	else if (options?.nodeDir || options?.entityStore || options?.logger !== undefined || options?.signaling)
-		throw new Error('p2p: startNode options ignored after initNode — use setNodeLogger / setSignalingRuntimeConfig')
+	else if (options?.nodeDir || options?.entityStore || options?.logger !== undefined || options?.signaling || options?.features)
+		throw new Error('p2p: startNode options ignored after initNode — use setNodeLogger / setSignalingRuntimeConfig / setP2PFeatures')
 
 	ensureNodeDefaults()
 	await getLinkRegistry().ensureRuntime()