@steve02081504/fount-p2p 0.0.12 → 0.0.13

package/README.md

@@ -18,15 +18,43 @@ Requires **Node.js ≥ 20** (ESM + `import ... with { type: 'json' }`).
 ## Quick start
 
 ```javascript
-import { startNode, createScopedLinkRoom, ensureUserRoom } from '@steve02081504/fount-p2p'
+import {
+ startNode,
+ ensureUserRoom,
+ attachUserRoomDefaultWires,
+ createScopedLinkRoom,
+} from '@steve02081504/fount-p2p'
 
 await startNode({ nodeDir: '/path/to/p2p/node' })
-await ensureUserRoom()
+await ensureUserRoom() // slot + runtime only
+attachUserRoomDefaultWires({ replicaUsername: 'alice' }) // full business wires
 ```
 
-Shells talk to the **fount network** (`ensureLinkToNode` / `sendToNodeLink` / rooms). Do not import `link/` or choose WebRTC / BLE / LAN yourself.
+Shells talk to the **fount network** (`ensureLinkToNode` / `sendToNodeLink` / rooms). Do not import `link/providers/*` or choose WebRTC / BLE / LAN yourself. Provider registration: `registerLinkProvider` from `@steve02081504/fount-p2p/link` or the facade.
 
-Subpath exports mirror source directories, e.g. `@steve02081504/fount-p2p/dag`, `@steve02081504/fount-p2p/transport/link_registry`, `@steve02081504/fount-p2p/transport/signal_crypto`, `@steve02081504/fount-p2p/registries/event_type`.
+Public transport subpaths: `link_registry`, `user_room`, `group_link_set`, `node_scope`, `room_scopes`, `remote_user_room`. Other `transport/*` modules are internal.
+
+## Infra relay (optional)
+
+Public-good overlay + mailbox only — does **not** attach `rep_sync` or full user-room wires:
+
+```bash
+npx @steve02081504/fount-p2p
+```
+
+Default `nodeDir`: Windows `%LOCALAPPDATA%/fount-p2p/node`; elsewhere `~/.local/share/fount-p2p/node`.
+
+```javascript
+import { initNode, startNode, startInfra, stopInfra, setInfraPriority } from '@steve02081504/fount-p2p'
+
+initNode({ nodeDir })
+await startNode()
+await startInfra({ maxActive: 64 }) // logger defaults to console; pass null to silence
+setInfraPriority({ useLocalReputation: true }) // optional; reads local reputation.json only
+await stopInfra()
+```
+
+Reputation pull/apply is separate: `pullReputationFromNode` → JSON; `setReputationTable` writes. See [docs/infra.md](./docs/infra.md).
 
 ## Layout
 
@@ -35,22 +63,22 @@ Subpath exports mirror source directories, e.g. `@steve02081504/fount-p2p/dag`,
 | L0 | `core/` | Pure primitives: `hexIds`, `entity_id*`, `canonical_json` |
 | L1 | `crypto/`, `wire/`, `schemas/` | Cryptography, wire protocol, canonical validation |
 | L2 | `node/` | Node runtime: `identity`, `entity_store`, `denylist`, `reputation_store` |
-| L3 | `discovery/`, `link/`, `transport/`, `rooms/` | Discovery + fount-network registry/rooms (`link/providers` are package-private) |
+| L3 | `discovery/`, `link/`, `transport/`, `rooms/` | Discovery + fount-network registry/rooms (`./link` = provider registration only) |
 | L4 | `trust_graph/`, `mailbox/`, `dag/`, `federation/`, `files/`, `governance/`, `reputation/` | Federation, store-and-forward, DAG, EVFS, tunables |
+| — | `infra/` | Optional public-good relay (`startInfra` / CLI) |
 | — | `registries/` | Pluggable registries (event type, part path, room provider, …) |
 
 Facade entry: `index.mjs` (`startNode`, `createGroupLinkSet`, `registerDiscoveryProvider`, …).
 
-**Transport modules** (exported under `./transport/*`):
+**Public transport modules:**
 
 | Module | Role |
 |---|---|
 | `link_registry.mjs` | fount-network facade: dial fallback, scope/overlay |
-| `runtime_bootstrap.mjs` | Progressive `ensureRuntime` (register + background listen / discovery / BT) |
-| `offer_answer.mjs` | Discovery-signal glare for offer/answer providers |
-| `signal_crypto.mjs` | Rendezvous topics + AES-GCM signal packets |
+| `user_room.mjs` / `group_link_set.mjs` / `node_scope.mjs` | rooms + composable node-scope wires |
+| `room_scopes.mjs` / `remote_user_room.mjs` | scope constants / remote user slot |
 
-`ensureRuntime` returns after registration and scheduling warm-up; it does not await lan_tcp listen, public relays, or Bluetooth. See [docs/runtime.md](./docs/runtime.md) and [docs/transports.md](./docs/transports.md).
+`runtime_bootstrap`, `offer_answer`, `advert_ingest` are **internal** (transport). Signal crypto / rendezvous live under `discovery/internal/signal_crypto.mjs` (used by `nostr.mjs` / `adverts.mjs`; not a package export). `ensureRuntime` returns after registration and scheduling warm-up; it does not await lan_tcp listen, public relays, or Bluetooth. `setSignalingRuntimeConfig` → `reloadDiscoveryRelays`. See [docs/runtime.md](./docs/runtime.md) and [docs/transports.md](./docs/transports.md).
 
 Root contains only the facade and package metadata; all modules live in layered subdirectories.
 
@@ -77,5 +105,8 @@ Group chunk remote storage (S3, etc.) is implemented by the shell as `GroupStora
 
 ## Docs
 
+- Mesh keep-alive / bootstrap (N/K, mesh-first): [`docs/mesh.md`](./docs/mesh.md)
 - Transports and provider fallback: [`docs/transports.md`](./docs/transports.md)
 - Signaling and WebRTC glare: [`docs/signaling.md`](./docs/signaling.md)
+- Runtime bootstrap / BT probe: [`docs/runtime.md`](./docs/runtime.md)
+- Infra relay / node-scope attaches: [`docs/infra.md`](./docs/infra.md)

package/core/composite_key.mjs

@@ -77,15 +77,15 @@ export function mapDeleteByPrefix(map, ...prefixParts) {
  * 遍历前缀子树；回调收到前缀之后的各段与值。
  * @template V
  * @param {Map<string, V>} map 根表
- * @param {...(string | ((tail: string[], value: V) => void))} prefixPartsAndFn 前缀段 + 末尾回调
+ * @param {...(string | ((tail: string[], value: V) => void))} prefixPartsAndCallback 前缀段 + 末尾回调
  * @returns {void}
  */
-export function mapForEachUnder(map, ...prefixPartsAndFn) {
-	const fn = prefixPartsAndFn.pop()
-	const prefix = compositePrefix(...prefixPartsAndFn)
+export function mapForEachUnder(map, ...prefixPartsAndCallback) {
+	const callback = prefixPartsAndCallback.pop()
+	const prefix = compositePrefix(...prefixPartsAndCallback)
 	for (const [k, value] of map) {
 		if (!k.startsWith(prefix)) continue
 		const tail = k.slice(prefix.length).split(SEP).filter(Boolean)
-		fn(tail, value)
+		callback(tail, value)
 	}
 }

package/crypto/crypto.mjs

@@ -150,9 +150,9 @@ export function sha256TextHex(text) {
 /**
  * Buffer / Uint8Array → 小写 hex 字符串
  *
- * @param {Uint8Array|Buffer} buf 二进制缓冲
+ * @param {Uint8Array|Buffer} buffer 二进制缓冲
  * @returns {string} 小写十六进制文本
  */
-function bufferToHexSimple(buf) {
-	return Buffer.from(buf).toString('hex')
+function bufferToHexSimple(buffer) {
+	return Buffer.from(buffer).toString('hex')
 }

package/crypto/key.mjs

@@ -164,8 +164,8 @@ function edPubToX25519(edPub) {
 	for (let i = 31; i >= 0; i--) y = (y << 8n) | BigInt(yCopy[i])
 	const u = (1n + y) * modInv(1n - y + P25519, P25519) % P25519
 	const result = new Uint8Array(32)
-	let tmp = u
-	for (let i = 0; i < 32; i++) { result[i] = Number(tmp & 0xffn); tmp >>= 8n }
+	let remaining = u
+	for (let i = 0; i < 32; i++) { result[i] = Number(remaining & 0xffn); remaining >>= 8n }
 	return result
 }
 
@@ -346,11 +346,11 @@ export function encryptRandomPlaintextWithKey(plaintext, contentKey) {
  */
 export function decryptConvergentCiphertext(raw, contentHashHex) {
 	try {
-		const buf = Buffer.from(raw)
-		if (buf.length < 28) return null
-		const iv = buf.subarray(0, 12)
-		const authTag = buf.subarray(12, 28)
-		const ciphertext = buf.subarray(28)
+		const buffer = Buffer.from(raw)
+		if (buffer.length < 28) return null
+		const iv = buffer.subarray(0, 12)
+		const authTag = buffer.subarray(12, 28)
+		const ciphertext = buffer.subarray(28)
 		const contentKey = deriveContentKey(contentHashHex)
 		const decipher = createDecipheriv('aes-256-gcm', contentKey, iv)
 		decipher.setAuthTag(authTag)
@@ -371,11 +371,11 @@ export function decryptConvergentCiphertext(raw, contentHashHex) {
  */
 export function decryptRandomCiphertext(raw, contentKey, contentHashHex = '') {
 	try {
-		const buf = Buffer.from(raw)
-		if (buf.length < 28) return null
-		const iv = buf.subarray(0, 12)
-		const authTag = buf.subarray(12, 28)
-		const ciphertext = buf.subarray(28)
+		const buffer = Buffer.from(raw)
+		if (buffer.length < 28) return null
+		const iv = buffer.subarray(0, 12)
+		const authTag = buffer.subarray(12, 28)
+		const ciphertext = buffer.subarray(28)
 		const decipher = createDecipheriv('aes-256-gcm', Buffer.from(contentKey), iv)
 		decipher.setAuthTag(authTag)
 		const plain = Buffer.concat([decipher.update(ciphertext), decipher.final()])

package/dag/storage.mjs

@@ -20,40 +20,40 @@ const ATOMIC_RENAME_RETRY_CODES = new Set(['EPERM', 'EBUSY', 'EACCES'])
  * @param {string} filePath 目标路径
  * @returns {string} 唯一临时文件路径
  */
-function atomicTmpPath(filePath) {
+function atomicTemporaryPath(filePath) {
 	return `${filePath}.tmp.${process.pid}.${randomUUID()}`
 }
 
 /**
- * @param {string} tmp 临时文件路径
+ * @param {string} temporaryPath 临时文件路径
  * @returns {Promise<void>}
  */
-async function cleanupAtomicTmp(tmp) {
-	try { await unlink(tmp) } catch { /* ok */ }
+async function cleanupAtomicTemporary(temporaryPath) {
+	try { await unlink(temporaryPath) } catch { /* ok */ }
 }
 
 /**
- * 完成原子写的最终 rename；若目标目录已在 cleanup 中消失，则清理残余 tmp 后静默返回。
- * @param {string} tmp 临时文件路径
+ * 完成原子写的最终 rename；若目标目录已在 cleanup 中消失，则清理残余临时文件后静默返回。
+ * @param {string} temporaryPath 临时文件路径
  * @param {string} filePath 最终目标路径
  * @returns {Promise<boolean>} 是否已成功落到目标路径
  */
-export async function finalizeAtomicRename(tmp, filePath) {
+export async function finalizeAtomicRename(temporaryPath, filePath) {
 	/** @type {NodeJS.ErrnoException | undefined} */
 	let lastError
 	for (const delayMs of ATOMIC_RENAME_RETRY_DELAYS_MS) {
 		if (delayMs) await sleep(delayMs)
 		try {
-			await rename(tmp, filePath)
+			await rename(temporaryPath, filePath)
 			return true
 		}
-		catch (err) {
-			lastError = err
-			if (ATOMIC_RENAME_RETRY_CODES.has(err?.code)) continue
+		catch (error) {
+			lastError = error
+			if (ATOMIC_RENAME_RETRY_CODES.has(error?.code)) continue
 			break
 		}
 	}
-	await cleanupAtomicTmp(tmp)
+	await cleanupAtomicTemporary(temporaryPath)
 	if (lastError?.code === 'ENOENT') return false
 	throw lastError
 }
@@ -132,7 +132,7 @@ export async function* readJsonlStream(filePath, options = {}) {
 export async function rewriteJsonlKeeping(filePath, keep, options = {}) {
 	const dir = dirname(filePath)
 	await mkdir(dir, { recursive: true })
-	const tmp = atomicTmpPath(filePath)
+	const temporaryPath = atomicTemporaryPath(filePath)
 	/** @type {object[]} */
 	const buffer = []
 	let kept = 0
@@ -143,7 +143,7 @@ export async function rewriteJsonlKeeping(filePath, keep, options = {}) {
 		let block = ''
 		for (const row of buffer)
 			block += `${JSON.stringify(row)}\n`
-		await appendFile(tmp, block, 'utf8')
+		await appendFile(temporaryPath, block, 'utf8')
 		buffer.length = 0
 	}
 	try {
@@ -159,7 +159,7 @@ export async function rewriteJsonlKeeping(filePath, keep, options = {}) {
 	}
 	catch { /* source missing */ }
 	if (kept > 0 || dropped > 0)
-		await finalizeAtomicRename(tmp, filePath)
+		await finalizeAtomicRename(temporaryPath, filePath)
 	else
 		try { await writeFile(filePath, '', 'utf8') }
 		catch { /* ok */ }
@@ -179,9 +179,9 @@ export async function readJsonlTipId(filePath) {
 			const { size } = await fh.stat()
 			if (!size) return null
 			const chunk = Math.min(size, 65_536)
-			const buf = Buffer.alloc(chunk)
-			await fh.read(buf, 0, chunk, size - chunk)
-			const lines = buf.toString('utf8').split('\n').filter(Boolean)
+			const buffer = Buffer.alloc(chunk)
+			await fh.read(buffer, 0, chunk, size - chunk)
+			const lines = buffer.toString('utf8').split('\n').filter(Boolean)
 			const last = lines[lines.length - 1]
 			if (!last) return null
 			const row = JSON.parse(last)
@@ -205,14 +205,14 @@ export async function readJsonlTipId(filePath) {
 export async function writeJsonl(filePath, records) {
 	const dir = dirname(filePath)
 	await mkdir(dir, { recursive: true })
-	const tmp = atomicTmpPath(filePath)
+	const temporaryPath = atomicTemporaryPath(filePath)
 	/** @returns {Generator<string>} JSONL 行 */
 	function* lines() {
 		for (const rec of records)
 			yield `${JSON.stringify(rec)}\n`
 	}
-	await pipeline(Readable.from(lines()), createWriteStream(tmp, { encoding: 'utf8' }))
-	await finalizeAtomicRename(tmp, filePath)
+	await pipeline(Readable.from(lines()), createWriteStream(temporaryPath, { encoding: 'utf8' }))
+	await finalizeAtomicRename(temporaryPath, filePath)
 }
 
 /**
@@ -253,18 +253,18 @@ export async function appendJsonlSynced(filePath, record) {
 
 /**
  * 写入原子临时文件；若父目录已在 cleanup 竞态中消失（ENOENT）则返回 false。
- * @param {string} tmp 临时文件路径
+ * @param {string} temporaryPath 临时文件路径
  * @param {string} data 文件内容
  * @returns {Promise<boolean>} 是否已写入
  */
-async function writeAtomicTmp(tmp, data) {
+async function writeAtomicTemporary(temporaryPath, data) {
 	try {
-		await writeFile(tmp, data, 'utf8')
+		await writeFile(temporaryPath, data, 'utf8')
 		return true
 	}
-	catch (err) {
-		if (err?.code === 'ENOENT') return false
-		throw err
+	catch (error) {
+		if (error?.code === 'ENOENT') return false
+		throw error
 	}
 }
 
@@ -277,9 +277,9 @@ async function writeAtomicTmp(tmp, data) {
 export async function writeJsonAtomic(filePath, obj) {
 	const dir = dirname(filePath)
 	await mkdir(dir, { recursive: true })
-	const tmp = atomicTmpPath(filePath)
-	if (!await writeAtomicTmp(tmp, JSON.stringify(obj, null, '\t'))) return
-	await finalizeAtomicRename(tmp, filePath)
+	const temporaryPath = atomicTemporaryPath(filePath)
+	if (!await writeAtomicTemporary(temporaryPath, JSON.stringify(obj, null, '\t'))) return
+	await finalizeAtomicRename(temporaryPath, filePath)
 }
 
 /**
@@ -291,16 +291,16 @@ export async function writeJsonAtomic(filePath, obj) {
 export async function writeJsonAtomicSynced(filePath, obj) {
 	const dir = dirname(filePath)
 	await mkdir(dir, { recursive: true })
-	const tmp = atomicTmpPath(filePath)
-	if (!await writeAtomicTmp(tmp, JSON.stringify(obj, null, '\t'))) return
-	const fh = await open(tmp, 'r+')
+	const temporaryPath = atomicTemporaryPath(filePath)
+	if (!await writeAtomicTemporary(temporaryPath, JSON.stringify(obj, null, '\t'))) return
+	const fileHandle = await open(temporaryPath, 'r+')
 	try {
-		await fh.sync()
+		await fileHandle.sync()
 	}
 	finally {
-		await fh.close()
+		await fileHandle.close()
 	}
-	if (!await finalizeAtomicRename(tmp, filePath)) return
+	if (!await finalizeAtomicRename(temporaryPath, filePath)) return
 	const outFh = await open(filePath, 'r+')
 	try {
 		await outFh.sync()

package/discovery/advert_peer_hints.mjs

@@ -5,7 +5,7 @@ import { noteLanPeerHint } from './lan_peer_hints.mjs'
 
 /**
  * 从已验证的 discovery advert + provider meta 写入 LAN/BT peer hints。
- * 任意 discovery 路径（node / group / scoped topic）收到 advert 时都应调用。
+ * 任意 discovery 路径（node / group / scoped）收到 advert 时都应调用。
  * @param {string} verifiedNodeHash 验签通过的 nodeHash
  * @param {{ tcpPort?: unknown } | null | undefined} body advert body
  * @param {{ address?: unknown, peripheralId?: unknown } | null | undefined} meta discovery provider meta

package/discovery/adverts.mjs

@@ -0,0 +1,109 @@
+import { normalizeHex64 } from '../core/hexIds.mjs'
+import { buildSignedAdvert, verifySignedAdvert } from '../link/handshake.mjs'
+
+import {
+	decryptSignalPacket,
+	encryptSignalPacket,
+	groupRendezvousKey,
+	networkRendezvousKey,
+	nodeRendezvousKey,
+} from './internal/signal_crypto.mjs'
+
+/** @typedef {'node' | 'network' | { roomSecret: string }} AdvertScope */
+
+/**
+ * 按 scope 派生 rendezvous 键。
+ * @param {AdvertScope} scope advert 域
+ * @param {string} selfNodeHash 本机 nodeHash
+ * @returns {string} rendezvous 键（discovery 内部）
+ */
+export function rendezvousKeyForScope(scope, selfNodeHash) {
+	if (scope === 'network') return networkRendezvousKey()
+	if (scope === 'node') return nodeRendezvousKey(selfNodeHash)
+	if (scope?.roomSecret) return groupRendezvousKey(scope.roomSecret)
+	throw new Error('p2p: invalid advert scope')
+}
+
+/**
+ * 为本机身份构建已签名 advert body。
+ * @param {AdvertScope} scope advert 域
+ * @param {{ nodeHash: string, nodePubKey: string, secretKey: Uint8Array }} localIdentity 本地身份
+ * @param {number | null | undefined} [tcpPort] LAN TCP 端口
+ * @returns {Promise<object>} 签名 advert body
+ */
+export async function buildSignedAdvertForScope(scope, localIdentity, tcpPort) {
+	const key = rendezvousKeyForScope(scope, localIdentity.nodeHash)
+	return await buildSignedAdvert(key, Date.now(), {
+		...localIdentity,
+		...tcpPort != null ? { tcpPort } : {},
+	})
+}
+
+/**
+ * AES-GCM 封装已签名 advert 包。
+ * @param {string} rendezvousKey rendezvous 键
+ * @param {object} advertBody 已签名 advert
+ * @returns {Uint8Array} 加密 advert 字节
+ */
+export function encryptAdvertPacket(rendezvousKey, advertBody) {
+	return encryptSignalPacket(rendezvousKey, { type: 'advert', body: advertBody })
+}
+
+/**
+ * 按 scope 加密已签名 advert。
+ * @param {AdvertScope} scope advert 域
+ * @param {{ nodeHash: string }} localIdentity 本地身份（仅需 nodeHash）
+ * @param {object} advertBody 已签名 advert
+ * @returns {Uint8Array} 加密 advert 字节
+ */
+export function encryptAdvertForScope(scope, localIdentity, advertBody) {
+	return encryptAdvertPacket(rendezvousKeyForScope(scope, localIdentity.nodeHash), advertBody)
+}
+
+/**
+ * Untrusted ingress：解密并验签 advert；失败返回 null，不抛。不写入可见池 / peer hints。
+ * @param {string} rendezvousKey rendezvous 键
+ * @param {Uint8Array} bytes 加密 advert
+ * @param {object} [meta] 元数据
+ * @returns {Promise<{ verifiedNodeHash: string, body: object } | null>} 验签成功返回 nodeHash 与 advert body，否则 null
+ */
+export async function ingestEncryptedAdvert(rendezvousKey, bytes, meta) {
+	void meta
+	const packet = decryptSignalPacket(rendezvousKey, bytes)
+	if (packet?.type !== 'advert' || !packet.body) return null
+	const verifiedNodeHash = await verifySignedAdvert(rendezvousKey, packet.body)
+	if (!verifiedNodeHash) return null
+	return { verifiedNodeHash, body: packet.body }
+}
+
+/**
+ * Untrusted ingress：验签 network-scope advert；失败返回 null。不写盘 / 不写 hints。
+ * @param {Uint8Array} bytes 加密 advert
+ * @param {object} [meta] 元数据
+ * @returns {Promise<{ verifiedNodeHash: string, body: object } | null>} 验签成功返回 nodeHash 与 advert body，否则 null
+ */
+export async function ingestNetworkAdvert(bytes, meta) {
+	return ingestEncryptedAdvert(networkRendezvousKey(), bytes, meta)
+}
+
+/**
+ * Untrusted ingress：验签 node-scope advert；失败返回 null。不写盘 / 不写 hints。
+ * @param {string} nodeHash 目标 nodeHash
+ * @param {Uint8Array} bytes 加密 advert
+ * @param {object} [meta] 元数据
+ * @returns {Promise<{ verifiedNodeHash: string, body: object } | null>} 验签成功返回 nodeHash 与 advert body，否则 null
+ */
+export async function ingestNodeAdvert(nodeHash, bytes, meta) {
+	return ingestEncryptedAdvert(nodeRendezvousKey(normalizeHex64(nodeHash)), bytes, meta)
+}
+
+/**
+ * Untrusted ingress：验签 group-scope advert；失败返回 null。不写盘 / 不写 hints。
+ * @param {string} roomSecret 房间密钥
+ * @param {Uint8Array} bytes 加密 advert
+ * @param {object} [meta] 元数据
+ * @returns {Promise<{ verifiedNodeHash: string, body: object } | null>} 验签成功返回 nodeHash 与 advert body，否则 null
+ */
+export async function ingestGroupAdvert(roomSecret, bytes, meta) {
+	return ingestEncryptedAdvert(groupRendezvousKey(roomSecret), bytes, meta)
+}