@steve02081504/fount-p2p 0.0.0

package/overlay/index.mjs

@@ -0,0 +1,191 @@
+import { Buffer } from 'node:buffer'
+
+import { pubKeyHash, sign, verify } from '../crypto/crypto.mjs'
+import { randomMsgIdHex } from '../link/frame.mjs'
+import { createLruMap } from '../utils/lru.mjs'
+
+const ROUTE_DOMAIN = 'fount-route-v1'
+
+/**
+ * 构造 overlay 路由签名用的字节序列。
+ * @param {string} reqId 路由请求 id
+ * @param {string[]} path 已遍历节点路径
+ * @returns {Uint8Array} 待签名字节
+ */
+function routeSignBytes(reqId, path) {
+	return Buffer.from(`${ROUTE_DOMAIN}\0${reqId}\0${path.join(',')}`, 'utf8')
+}
+
+/**
+ * 创建 overlay 多跳路由与 relay 路由器。
+ * @param {object} registry link registry（含 localIdentity、sendToNodeLink、listLinks、subscribeScope）
+ * @param {number} [ttl=3] 默认路由 TTL（最大跳数）
+ * @returns {object} 路由器接口（discoverRoute、relay、onRelay、close）
+ */
+export function createOverlayRouter(registry, ttl = 3) {
+	const selfNodeHash = registry.localIdentity.nodeHash
+	const selfPubKey = registry.localIdentity.nodePubKey
+	const secretKey = registry.localIdentity.secretKey
+	const seenReqs = createLruMap(4096)
+	/** @type {Map<string, { resolve: (path: string[]) => void, reject: (err: Error) => void, timer: number }>} */
+	const pendingRoutes = new Map()
+	/** @type {Set<(body: unknown, meta: { path: string[], from: string }) => void>} */
+	const relayListeners = new Set()
+
+	/**
+	 * 经 overlay scope 向节点发送 payload。
+	 * @param {string} nodeHash 目标节点 64 hex
+	 * @param {object} payload overlay action 载荷
+	 * @returns {Promise<void>}
+	 */
+	async function sendOverlay(nodeHash, payload) {
+		await registry.sendToNodeLink(nodeHash, { scope: 'overlay', action: payload.action, payload })
+	}
+
+	/**
+	 * 处理入站 overlay envelope（route_req / route_resp / relay）。
+	 * @param {string} senderNodeHash 发送方节点 64 hex
+	 * @param {object} envelope overlay 信封
+	 * @returns {Promise<void>}
+	 */
+	async function handleOverlay(senderNodeHash, envelope) {
+		const payload = envelope?.payload
+		const action = String(envelope?.action || '')
+		if (!payload || typeof payload !== 'object') return
+		if (action === 'route_req') {
+			const reqId = String(payload.reqId || '')
+			const target = String(payload.target || '')
+			const hops = Array.isArray(payload.path) ? payload.path.map(String) : []
+			const remainingTtl = Number(payload.ttl)
+			if (!reqId || !target || !hops.length || remainingTtl <= 0) return
+			if (seenReqs.has(reqId) || hops.includes(selfNodeHash) || hops.length > 6) return
+			seenReqs.touch(reqId, true)
+			const nextPath = [...hops, selfNodeHash]
+			if (target === selfNodeHash) {
+				const sig = await sign(routeSignBytes(reqId, nextPath), secretKey)
+				const prevHop = hops[hops.length - 1]
+				if (prevHop)
+					await sendOverlay(prevHop, {
+						action: 'route_resp',
+						reqId,
+						path: nextPath,
+						nodePubKey: selfPubKey,
+						sig: Buffer.from(sig).toString('hex'),
+					})
+				return
+			}
+			for (const { nodeHash } of registry.listLinks())
+				if (nodeHash !== senderNodeHash && !hops.includes(nodeHash))
+					await sendOverlay(nodeHash, {
+						action: 'route_req',
+						reqId,
+						target,
+						ttl: remainingTtl - 1,
+						path: nextPath,
+					})
+			return
+		}
+		if (action === 'route_resp') {
+			const reqId = String(payload.reqId || '')
+			const path = Array.isArray(payload.path) ? payload.path.map(String) : []
+			const nodePubKey = String(payload.nodePubKey || '')
+			const sigHex = String(payload.sig || '')
+			if (!reqId || path.length < 2 || !nodePubKey || !sigHex) return
+			if (pubKeyHash(Buffer.from(nodePubKey, 'hex')) !== path[path.length - 1]) return
+			const ok = await verify(Buffer.from(sigHex, 'hex'), routeSignBytes(reqId, path), Buffer.from(nodePubKey, 'hex'))
+			if (!ok) return
+			if (path[0] === selfNodeHash) {
+				const pending = pendingRoutes.get(reqId)
+				if (!pending) return
+				clearTimeout(pending.timer)
+				pendingRoutes.delete(reqId)
+				pending.resolve(path)
+				return
+			}
+			const index = path.indexOf(selfNodeHash)
+			if (index <= 0) return
+			await sendOverlay(path[index - 1], payload)
+			return
+		}
+		if (action === 'relay') {
+			const path = Array.isArray(payload.path) ? payload.path.map(String) : []
+			const index = Number(payload.idx)
+			if (!path.length || path[index] !== selfNodeHash) return
+			if (index === path.length - 1) {
+				for (const listener of relayListeners)
+					listener(payload.body, { path, from: senderNodeHash })
+				return
+			}
+			await sendOverlay(path[index + 1], {
+				action: 'relay',
+				path,
+				idx: index + 1,
+				body: payload.body,
+			})
+		}
+	}
+
+	const unsubscribe = registry.subscribeScope('overlay', handleOverlay)
+
+	return {
+		/**
+		 * 发现到目标节点的签名路由路径。
+		 * @param {string} targetNodeHash 目标节点 64 hex
+		 * @param {object} [opts] 选项
+		 * @param {number} [opts.ttl] 路由 TTL
+		 * @param {number} [opts.timeoutMs] 超时毫秒
+		 * @returns {Promise<string[]>} 从本节点到目标的 nodeHash 路径
+		 */
+		async discoverRoute(targetNodeHash, opts = {}) {
+			const reqId = randomMsgIdHex()
+			const maxTtl = Number(opts.ttl) || ttl
+			const timeoutMs = Number(opts.timeoutMs) || 10_000
+			const promise = new Promise((resolve, reject) => {
+				const timer = setTimeout(() => {
+					pendingRoutes.delete(reqId)
+					reject(new Error(`overlay: route discovery timeout for ${targetNodeHash}`))
+				}, timeoutMs)
+				pendingRoutes.set(reqId, { resolve, reject, timer })
+			})
+			for (const { nodeHash } of registry.listLinks())
+				await sendOverlay(nodeHash, {
+					action: 'route_req',
+					reqId,
+					target: targetNodeHash,
+					ttl: maxTtl,
+					path: [selfNodeHash],
+				})
+			return await promise
+		},
+		/**
+		 * 沿已发现路径 relay 载荷到路径末端。
+		 * @param {string[]} path 路由路径（首节点须为本节点）
+		 * @param {unknown} body relay 载荷
+		 * @returns {Promise<void>}
+		 */
+		async relay(path, body) {
+			if (!Array.isArray(path) || path[0] !== selfNodeHash || path.length < 2)
+				throw new Error('overlay: invalid relay path')
+			await sendOverlay(path[1], { action: 'relay', path, idx: 1, body })
+		},
+		/**
+		 * 订阅 relay 到达本节点（路径末端）的载荷。
+		 * @param {(body: unknown, meta: { path: string[], from: string }) => void} listener 回调
+		 * @returns {() => void} 取消订阅函数
+		 */
+		onRelay(listener) {
+			relayListeners.add(listener)
+			return () => relayListeners.delete(listener)
+		},
+		/**
+		 * 关闭路由器并清理 pending 与监听器。
+		 * @returns {void}
+		 */
+		close() {
+			unsubscribe()
+			for (const pending of pendingRoutes.values()) clearTimeout(pending.timer)
+			pendingRoutes.clear()
+			relayListeners.clear()
+		},
+	}
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+	"name": "@steve02081504/fount-p2p",
+	"version": "0.0.0",
+	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
+	"categories": [
+		"network",
+		"p2p",
+		"fount",
+		"AI"
+	],
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/steve02081504/fount-p2p.git",
+		"directory": "."
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"scripts": {
+		"test": "node --test --test-concurrency=1 --test-force-exit test/pure/*.test.mjs test/integration/*.test.mjs",
+		"test:live": "node --test --test-concurrency=1 --test-force-exit test/live/*.test.mjs",
+		"test:sim": "node --test --test-concurrency=1 --test-force-exit sim/test/*.test.mjs"
+	},
+	"files": [
+		"**/*.mjs",
+		"**/*.json",
+		"!test/**",
+		"!sim/**",
+		"!scripts/**"
+	],
+	"exports": {
+		".": "./index.mjs",
+		"./core/*": "./core/*.mjs",
+		"./crypto": "./crypto/crypto.mjs",
+		"./crypto/*": "./crypto/*.mjs",
+		"./wire/*": "./wire/*.mjs",
+		"./schemas/*": "./schemas/*.mjs",
+		"./node/*": "./node/*.mjs",
+		"./discovery": "./discovery/index.mjs",
+		"./discovery/*": "./discovery/*.mjs",
+		"./link/*": "./link/*.mjs",
+		"./transport/*": "./transport/*.mjs",
+		"./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",
+		"./dag/*": "./dag/*.mjs",
+		"./timeline/*": "./timeline/*.mjs",
+		"./files/*": "./files/*.mjs",
+		"./federation/*": "./federation/*.mjs",
+		"./governance/*": "./governance/*.mjs",
+		"./registries/*": "./registries/*.mjs",
+		"./permissions": "./permissions/index.mjs",
+		"./reputation/*": "./reputation/*.mjs",
+		"./utils/*": "./utils/*.mjs"
+	},
+	"dependencies": {
+		"@noble/curves": "^1.9.0",
+		"node-datachannel": "^0.11.0"
+	},
+	"devDependencies": {
+		"@steve02081504/exec": "file:../../exec"
+	},
+	"optionalDependencies": {
+		"@stoprocent/bleno": "^0.11.0",
+		"@stoprocent/noble": "^1.9.0"
+	}
+}

package/permissions/bitmask.mjs

@@ -0,0 +1,35 @@
+/**
+ * 通用权限位图编解码。
+ */
+
+/**
+ * @param {readonly string[]} order 权限名有序列表（位序固定）
+ * @returns {{ encode: (permissions: Record<string, boolean> | null | undefined) => bigint, decode: (bits: bigint) => Record<string, boolean> }} codec
+ */
+export function createPermissionCodec(order) {
+	const names = [...order]
+	/**
+	 * @param {Record<string, boolean> | null | undefined} permissions 权限对象
+	 * @returns {bigint} 按位编码
+	 */
+	function encode(permissions) {
+		let bits = 0n
+		if (!permissions) return bits
+		for (let index = 0; index < names.length; index++)
+			if (permissions[names[index]])
+				bits |= 1n << BigInt(index)
+		return bits
+	}
+	/**
+	 * @param {bigint} bits 权限位
+	 * @returns {Record<string, boolean>} 各权限名到布尔值
+	 */
+	function decode(bits) {
+		/** @type {Record<string, boolean>} */
+		const permissions = {}
+		for (let index = 0; index < names.length; index++)
+			permissions[names[index]] = Boolean(bits & (1n << BigInt(index)))
+		return permissions
+	}
+	return { encode, decode }
+}

package/permissions/evaluator.mjs

@@ -0,0 +1,90 @@
+/**
+ * Discord 式「按特定度分层」权限求值器工厂。
+ */
+import { createPermissionCodec } from './bitmask.mjs'
+import { applyDenyAllowOverride, mergeRoleOverrides } from './layered.mjs'
+
+/**
+ * @typedef {object} LayeredEvaluatorSchema
+ * @property {readonly string[]} order 权限名有序列表
+ * @property {string} superuserName 旁路全部 scope 覆写的权限名（如 ADMIN）
+ * @property {string} [everyoneRoleId='@everyone'] scope 内最宽角色 id
+ */
+
+/**
+ * @param {LayeredEvaluatorSchema} schema 求值 schema
+ * @returns {{
+ *   order: readonly string[],
+ *   encode: (permissions: Record<string, boolean> | null | undefined) => bigint,
+ *   decode: (bits: bigint) => Record<string, boolean>,
+ *   calculate: (member: { roles?: string[] }, roles: Record<string, { permissions?: Record<string, boolean> }>, scopeId: string, scopeOverrides: Record<string, Record<string, { deny?: Record<string, boolean>, allow?: Record<string, boolean> }>>) => Record<string, boolean>,
+ *   has: (member: object, permission: string, roles: object, scopeId: string, scopeOverrides: object) => boolean,
+ * }} evaluator
+ */
+export function createLayeredEvaluator(schema) {
+	const { encode, decode } = createPermissionCodec(schema.order)
+	const superuserBit = 1n << BigInt(schema.order.indexOf(schema.superuserName))
+	const everyoneRoleId = schema.everyoneRoleId ?? '@everyone'
+
+	/**
+	 * @param {{ roles?: string[] }} member 成员
+	 * @param {Record<string, { permissions?: Record<string, boolean> }>} roles 角色映射
+	 * @param {string} scopeId scope id（如 channelId）
+	 * @param {Record<string, Record<string, { deny?: Record<string, boolean>, allow?: Record<string, boolean> }>>} scopeOverrides scope 覆写表
+	 * @returns {Record<string, boolean>} 最终权限
+	 */
+	function calculate(member, roles, scopeId, scopeOverrides) {
+		const roleIds = member.roles || []
+
+		let baseBits = 0n
+		for (const roleId of roleIds) {
+			const role = roles[roleId]
+			if (role) baseBits |= encode(role.permissions)
+		}
+
+		if (baseBits & superuserBit) {
+			/** @type {Record<string, boolean>} */
+			const perms = {}
+			for (const p of schema.order) perms[p] = true
+			return perms
+		}
+
+		let bits = baseBits
+		const scopeOverride = scopeOverrides?.[scopeId]
+		if (scopeOverride) {
+			const everyone = scopeOverride[everyoneRoleId]
+			if (everyone)
+				bits = applyDenyAllowOverride(bits, everyone, encode)
+
+			const roleOverrides = []
+			for (const roleId of roleIds) {
+				if (roleId === everyoneRoleId) continue
+				const override = scopeOverride[roleId]
+				if (override) roleOverrides.push(override)
+			}
+			bits = mergeRoleOverrides(bits, roleOverrides, encode)
+		}
+
+		return decode(bits)
+	}
+
+	/**
+	 * @param {object} member 成员
+	 * @param {string} permission 权限名
+	 * @param {object} roles 角色映射
+	 * @param {string} scopeId scope id
+	 * @param {object} scopeOverrides scope 覆写表
+	 * @returns {boolean} 是否具备权限
+	 */
+	function has(member, permission, roles, scopeId, scopeOverrides) {
+		return calculate(member, roles, scopeId, scopeOverrides)[permission] === true
+	}
+
+	return {
+		order: schema.order,
+		encode,
+		decode,
+		calculate,
+		has,
+	}
+}

package/permissions/index.mjs

@@ -0,0 +1,12 @@
+/**
+ *
+ */
+export { createPermissionCodec } from './bitmask.mjs'
+/**
+ *
+ */
+export { applyDenyAllowOverride, mergeRoleOverrides } from './layered.mjs'
+/**
+ *
+ */
+export { createLayeredEvaluator } from './evaluator.mjs'

package/permissions/layered.mjs

@@ -0,0 +1,39 @@
+/**
+ * 分层 allow/deny 覆写：先去 deny 再叠 allow。
+ */
+
+/**
+ * @param {bigint} baseBits 基线权限位
+ * @param {{ deny?: Record<string, boolean> | null, allow?: Record<string, boolean> | null }} override 覆写
+ * @param {(permissions: Record<string, boolean> | null | undefined) => bigint} encode 编码函数
+ * @returns {bigint} 覆写后的权限位
+ */
+export function applyDenyAllowOverride(baseBits, override, encode) {
+	if (!override) return baseBits
+	let bits = baseBits
+	if (override.deny)
+		bits &= ~encode(override.deny)
+	if (override.allow)
+		bits |= encode(override.allow)
+	return bits
+}
+
+/**
+ * 合并多个角色的 allow/deny 后整体应用（顺序无关）。
+ * @param {bigint} baseBits 基线权限位
+ * @param {Array<{ deny?: Record<string, boolean> | null, allow?: Record<string, boolean> | null }>} overrides 覆写列表
+ * @param {(permissions: Record<string, boolean> | null | undefined) => bigint} encode 编码函数
+ * @returns {bigint} 覆写后的权限位
+ */
+export function mergeRoleOverrides(baseBits, overrides, encode) {
+	let roleAllow = 0n
+	let roleDeny = 0n
+	for (const override of overrides) {
+		if (!override) continue
+		if (override.allow)
+			roleAllow |= encode(override.allow)
+		if (override.deny)
+			roleDeny |= encode(override.deny)
+	}
+	return (baseBits & ~roleDeny) | roleAllow
+}

package/registries/action.mjs

@@ -0,0 +1,94 @@
+/**
+ * 基于 room.makeAction(name) 的通用 action 注册表。
+ */
+
+/**
+ * P2P 房间 action 注册表，封装 makeAction 的 send/receive 对。
+ */
+export class ActionRegistry {
+	/** @type {Map<string, { send: Function, get: Function }>} */
+	#entries = new Map()
+
+	/**
+	 * @param {{ makeAction: (name: string) => [Function, Function] }} room 提供 makeAction 的房间对象
+	 */
+	constructor(room) {
+		this.room = room
+	}
+
+	/**
+	 * 预注册一个或多个 action 名称。
+	 * @param {string | string[]} names action 名称或名称列表
+	 * @returns {ActionRegistry} 当前实例（链式调用）
+	 */
+	register(names) {
+		const list = Array.isArray(names) ? names : [names]
+		for (const name of list)
+			this.#ensureEntry(name)
+		return this
+	}
+
+	/**
+	 * 获取或创建指定 action 的 send/get 条目。
+	 * @param {string} name action 名称
+	 * @returns {{ send: Function, get: Function }} send 与 get 函数对
+	 */
+	#ensureEntry(name) {
+		let entry = this.#entries.get(name)
+		if (!entry) {
+			const [send, get] = this.room.makeAction(name)
+			entry = { send, get }
+			this.#entries.set(name, entry)
+		}
+		return entry
+	}
+
+	/**
+	 * 获取指定 action 的发送函数。
+	 * @param {string} name action 名称
+	 * @returns {Function} 发送函数
+	 */
+	sender(name) {
+		return this.#ensureEntry(name).send
+	}
+
+	/**
+	 * 获取指定 action 的接收注册函数。
+	 * @param {string} name action 名称
+	 * @returns {Function} 接收注册函数
+	 */
+	receiver(name) {
+		return this.#ensureEntry(name).get
+	}
+
+	/**
+	 * 向指定 peer 发送 action 载荷。
+	 * @param {string} name action 名称
+	 * @param {unknown} payload 载荷
+	 * @param {string | null} [peerId] 目标 peer；null 表示广播
+	 * @returns {void}
+	 */
+	send(name, payload, peerId = null) {
+		void this.sender(name)(payload, peerId)
+	}
+
+	/**
+	 * 注册 action 入站 handler。
+	 * @param {string} name action 名称
+	 * @param {(payload: unknown, peerId: string) => void} handler 入站回调
+	 * @returns {ActionRegistry} 当前实例（链式调用）
+	 */
+	on(name, handler) {
+		this.receiver(name)(handler)
+		return this
+	}
+}
+
+/**
+ * 创建 ActionRegistry 实例。
+ * @param {{ makeAction: (name: string) => [Function, Function] }} room 提供 makeAction 的房间对象
+ * @returns {ActionRegistry} 新注册表
+ */
+export function createActionRegistry(room) {
+	return new ActionRegistry(room)
+}

package/registries/event_type.mjs

@@ -0,0 +1,75 @@
+/**
+ * @typedef {object} EventTypeFlags
+ * @property {boolean} [aclGated]
+ * @property {boolean} [gcExclude]
+ * @property {boolean} [governance]
+ * @property {boolean} [permissionAnchor]
+ */
+
+/** @type {Map<string, Record<string, EventTypeFlags>>} */
+const defsByOwner = new Map()
+
+/**
+ * @param {string} ownerId 注册方
+ * @param {Record<string, EventTypeFlags>} defs 事件 type 元数据
+ * @returns {void}
+ */
+export function registerEventTypeDefs(ownerId, defs) {
+	defsByOwner.set(String(ownerId), defs)
+}
+
+/**
+ * @param {string} ownerId 注册方
+ * @returns {void}
+ */
+export function unregisterEventTypeDefs(ownerId) {
+	defsByOwner.delete(String(ownerId))
+}
+
+/** @returns {void} */
+export function clearEventTypeRegistry() {
+	defsByOwner.clear()
+}
+
+/**
+ * @returns {Record<string, EventTypeFlags>} 合并后的 defs
+ */
+export function mergedEventTypeDefs() {
+	/** @type {Record<string, EventTypeFlags>} */
+	const merged = {}
+	for (const defs of defsByOwner.values())
+		Object.assign(merged, defs)
+	return merged
+}
+
+/**
+ * @param {'aclGated' | 'gcExclude' | 'governance' | 'permissionAnchor'} flag 标志位名
+ * @returns {Set<string>} 含该标志的事件 type 集合
+ */
+export function typesWithFlag(flag) {
+	return new Set(Object.entries(mergedEventTypeDefs()).filter(([, f]) => f[flag]).map(([k]) => k))
+}
+
+/** §8 治理分叉选支：祖先闭包内计入信誉加权的类型。 */
+/** @returns {Set<string>} 治理事件 type 集合 */
+export function getGovernanceAuthzTypes() {
+	return typesWithFlag('governance')
+}
+
+/** 联邦入站/中继前须物化 ACL 门控的类型。 */
+/** @returns {Set<string>} ACL 门控事件 type 集合 */
+export function getFederationAclGatedEventTypes() {
+	return typesWithFlag('aclGated')
+}
+
+/** §6.2 频道 GC 沉寂计时排除的类型。 */
+/** @returns {Set<string>} GC 排除事件 type 集合 */
+export function getChannelGcExcludedEventTypes() {
+	return typesWithFlag('gcExclude')
+}
+
+/** 裁剪时不得早于最早一条权限锚点事件（§7.1）。 */
+/** @returns {Set<string>} 权限锚点事件 type 集合 */
+export function getPermissionAnchorTypes() {
+	return typesWithFlag('permissionAnchor')
+}