@steve02081504/fount-p2p 0.0.15 → 0.0.16

package/README.md

@@ -30,7 +30,9 @@ await ensureUserRoom() // slot + runtime only
 attachUserRoomDefaultWires({ replicaUsername: 'alice' }) // full business wires
 ```
 
-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.
+Shells talk to the **fount network** (`ensureLinkToNode` / `sendToNodeLink` / rooms). Do not import `link/providers/*` or choose WebRTC / BLE / LAN / Nostr yourself. Provider registration: `registerLinkProvider` from `@steve02081504/fount-p2p/link` or the facade.
+
+Dial order is descending link **`level`**: `lan_tcp` → `webrtc` → `ble_gatt` → `nostr` (−∞ last resort). Discovery **`priority`** only orders handshake / presence media. Details: [docs/transports.md](./docs/transports.md).
 
 Public transport subpaths: `link_registry`, `user_room`, `group_link_set`, `node_scope`, `room_scopes`, `remote_user_room`. Other `transport/*` modules are internal.
 
@@ -86,7 +88,7 @@ Facade entry: `index.mjs` (`startNode`, `createGroupLinkSet`, `registerDiscovery
 | `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 |
 
-`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).
+`runtime_bootstrap`, `offer_answer`, `advert_ingest` are **internal** (transport). Signal crypto / rendezvous live under `discovery/internal/signal_crypto.mjs` (used by discovery `nostr.mjs` / `adverts.mjs`; not a package export). The Nostr **link** provider (`link/providers/nostr.mjs`) reuses the same discovery signal path (`type: 'link'`) as a last-resort duplex pipe. `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.
 
@@ -99,7 +101,7 @@ npm run test:live     # link / LAN / glare smoke
 npm run test:sim      # tunables co-evolution sim (dev only, not published; --social-tunables to write back)
 ```
 
-During development: `node scripts/check-imports.mjs` validates relative imports. After a layout migration, `node scripts/cleanup-root-duplicates.mjs` removes stale root-level stubs.
+During development: `node scripts/check-imports.mjs` validates relative imports; `node scripts/find-unused-exports.mjs` scans dead exports (`--fount <path>` optional).
 
 Maintainer notes for agents / contributors: [AGENTS.md](./AGENTS.md). Sim harness fidelity: [sim/AGENTS.md](./sim/AGENTS.md).
 
@@ -107,7 +109,7 @@ Maintainer notes for agents / contributors: [AGENTS.md](./AGENTS.md). Sim harnes
 
 - `@stoprocent/noble` / `@stoprocent/bleno` — Bluetooth (optionalDependencies). Hardware probe is subprocess-only; see [docs/runtime.md](./docs/runtime.md).
 - `node-datachannel` — WebRTC DataChannels (dependency).
-- `ws` — Nostr discovery/signaling WebSockets (dependency).
+- `ws` — Nostr discovery / signaling / last-resort link WebSockets (dependency).
 
 Group chunk remote storage (S3, etc.) is implemented by the shell as `GroupStoragePlugin` and injected; see `node/storage_plugins.mjs` for the local reference implementation.
 

package/crypto/channel.mjs

@@ -1,5 +1,5 @@
 /**
- * Domain-key 信封：X25519 ECIES 包装与 AES-GCM 消息载荷（wire scheme 由消费方定义，如 ckg）。
+ * Domain-key 信封：X25519 ECIES 包装与 AES-GCM 消息载荷（wire scheme：channel-key）。
  * 解密 payload 不可脱离外层 DAG Ed25519 签名上下文单独传递或信任。
  */
 import { Buffer } from 'node:buffer'
@@ -7,8 +7,8 @@ import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from 'node:cr
 
 import { unwrapKeyEcies, wrapKeyEcies } from './key.mjs'
 
-/** @type {'ckg'} 频道消息 content 加密 scheme */
-export const CKG_SCHEME = 'ckg'
+/** @type {'channel-key'} 频道消息 content 加密 scheme */
+export const CHANNEL_KEY_SCHEME = 'channel-key'
 
 /** @typedef {{ ephemPub: string, iv: string, ciphertext: string, authTag: string }} EciesWrapBlob */
 
@@ -49,7 +49,7 @@ function messageAesKey(channelKeyHex, channelId, generation) {
 	return Buffer.from(hkdfSync(
 		'sha256',
 		Buffer.from(channelKeyHex, 'hex'),
-		`ckg:${String(channelId)}:${String(generation)}`,
+		`${CHANNEL_KEY_SCHEME}:${String(channelId)}:${String(generation)}`,
 		'',
 		32,
 	))
@@ -60,7 +60,7 @@ function messageAesKey(channelKeyHex, channelId, generation) {
  * @param {string} channelKeyHex K_ch
  * @param {string} channelId 频道 ID
  * @param {number} generation 密钥代际
- * @returns {{ scheme: typeof CKG_SCHEME, channelId: string, generation: number, payload: string }} 频道密钥信封
+ * @returns {{ scheme: typeof CHANNEL_KEY_SCHEME, channelId: string, generation: number, payload: string }} 频道密钥信封
  */
 export function encryptWithChannelKey(plaintext, channelKeyHex, channelId, generation) {
 	const key = messageAesKey(channelKeyHex, channelId, generation)
@@ -70,7 +70,7 @@ export function encryptWithChannelKey(plaintext, channelKeyHex, channelId, gener
 	const ciphertext = Buffer.concat([cipher.update(plain), cipher.final()])
 	const authTag = cipher.getAuthTag()
 	return {
-		scheme: CKG_SCHEME,
+		scheme: CHANNEL_KEY_SCHEME,
 		channelId: String(channelId),
 		generation: Number(generation) || 0,
 		payload: `${iv.toString('base64')}.${ciphertext.toString('base64')}.${authTag.toString('base64')}`,
@@ -84,7 +84,7 @@ export function encryptWithChannelKey(plaintext, channelKeyHex, channelId, gener
  * @returns {string | null} 明文 UTF-8
  */
 export function decryptWithChannelKey(envelope, channelKeyHex, channelId) {
-	if (envelope?.scheme !== CKG_SCHEME || !envelope.payload) return null
+	if (envelope?.scheme !== CHANNEL_KEY_SCHEME || !envelope.payload) return null
 	try {
 		const parts = envelope.payload.split('.')
 		if (parts.length !== 3) return null

package/link/providers/index.mjs

@@ -85,4 +85,5 @@ export {
 	LINK_LEVEL_LAN_TCP,
 	LINK_LEVEL_WEBRTC,
 	LINK_LEVEL_BLE_GATT,
+	LINK_LEVEL_NOSTR,
 } from './levels.mjs'

package/link/providers/levels.mjs

@@ -7,3 +7,5 @@ export const LINK_LEVEL_LAN_TCP = 80
 export const LINK_LEVEL_WEBRTC = 70
 /** BLE GATT 链路 level。 */
 export const LINK_LEVEL_BLE_GATT = 40
+/** Nostr relay 末位数据链（仅其它传输失败后）。 */
+export const LINK_LEVEL_NOSTR = Number.NEGATIVE_INFINITY

package/link/providers/nostr.mjs

@@ -0,0 +1,280 @@
+import { Buffer } from 'node:buffer'
+import { randomBytes } from 'node:crypto'
+
+import { base64ToBytes, bytesToBase64 } from '../../core/bytes_codec.mjs'
+import { normalizeHex64 } from '../../core/hexIds.mjs'
+import { getDiscoveryProvider, sendNodeSignalPacket } from '../../discovery/index.mjs'
+import { mergeSignalingRelayUrls } from '../../discovery/nostr.mjs'
+import { getNodeTransportSettings } from '../../node/identity.mjs'
+import { getSignalingRuntimeConfig } from '../../node/instance.mjs'
+import { ms } from '../../utils/duration.mjs'
+import { createLruMap } from '../../utils/lru.mjs'
+import { asLinkHandle } from '../pipe.mjs'
+
+import { LINK_LEVEL_NOSTR } from './levels.mjs'
+import { createLinkIdBoundPipe } from './link_id_pipe.mjs'
+
+/** 单包 payload（UTF-8 / base64）上限，避免撞 relay content 限制。 */
+const MAX_LINK_PAYLOAD_CHARS = 12 * 1024
+/** open 到达前为同一 linkId 暂存的 c/b 包上限。 */
+const PENDING_PACKETS_MAX = 32
+/** Nostr 链握手超时（relay RTT 更慢）。 */
+const NOSTR_HANDSHAKE_TIMEOUT_MS = ms('30s')
+/** Nostr 链心跳间隔。 */
+const NOSTR_HEARTBEAT_MS = ms('60s')
+/** Nostr 链空闲超时。 */
+const NOSTR_IDLE_TIMEOUT_MS = ms('3m')
+
+/**
+ * @returns {string[]} 当前可用中继 URL
+ */
+function resolveDefaultRelayUrls() {
+	return getSignalingRuntimeConfig().relayOverride
+		?? mergeSignalingRelayUrls(getNodeTransportSettings().relayUrls)
+}
+
+/**
+ * @param {string} remoteNodeHash 对端
+ * @param {object} packet link 包
+ * @returns {Promise<void>}
+ */
+async function publishLinkPacket(remoteNodeHash, packet) {
+	await sendNodeSignalPacket(remoteNodeHash, packet)
+}
+
+/**
+ * 创建 Nostr 末位数据链路 provider（level = -∞）。
+ * @param {{ getRelayUrls?: () => string[] }} [options] 中继解析（测试可注入）
+ * @returns {import('./index.mjs').LinkProvider & { deliverPacket: (packet: object) => void }} provider
+ */
+export function createNostrLinkProvider(options = {}) {
+	const resolveRelayUrls = typeof options.getRelayUrls === 'function'
+		? options.getRelayUrls
+		: resolveDefaultRelayUrls
+
+	/** @type {((link: import('./index.mjs').LinkHandle) => void) | null} */
+	let onInbound = null
+	/** @type {object | null} */
+	let localIdentity = null
+	/**
+	 * @typedef {{
+	 *   pipe: ReturnType<typeof createLinkIdBoundPipe>,
+	 *   remoteNodeHash: string,
+	 *   initiator: boolean,
+	 * }} NostrLinkSession
+	 */
+	/** @type {Map<string, NostrLinkSession>} */
+	const sessions = new Map()
+	/** @type {Map<string, object[]> & { touch: (key: string, value: object[]) => void }} */
+	const pendingByLinkId = createLruMap(64)
+
+	/**
+	 * @returns {boolean} discovery nostr 已注册且有中继
+	 */
+	function isAvailable() {
+		if (!getDiscoveryProvider('nostr')) return false
+		return resolveRelayUrls().length > 0
+	}
+
+	/**
+	 * @param {NostrLinkSession} session 会话
+	 * @param {object} packet link 包
+	 * @returns {void}
+	 */
+	function applySessionPacket(session, packet) {
+		const op = String(packet.op || '')
+		if (op === 'close') {
+			void session.pipe.close('remote-close')
+			return
+		}
+		if (op === 'c') {
+			if (typeof packet.payload !== 'string') return
+			session.pipe.handleInbound(packet.payload)
+			return
+		}
+		if (op === 'b') {
+			if (typeof packet.payload !== 'string') return
+			try {
+				session.pipe.handleInbound(Buffer.from(base64ToBytes(packet.payload)))
+			}
+			catch { /* drop malformed */ }
+		}
+	}
+
+	/**
+	 * @param {string} linkId 链路 id
+	 * @param {object} packet 暂存包
+	 * @returns {void}
+	 */
+	function bufferPending(linkId, packet) {
+		let list = pendingByLinkId.get(linkId)
+		if (!list) {
+			list = []
+			pendingByLinkId.touch(linkId, list)
+		}
+		if (list.length >= PENDING_PACKETS_MAX) list.shift()
+		list.push(packet)
+	}
+
+	/**
+	 * @param {string} remoteNodeHash 对端
+	 * @param {string} linkId 链路 id
+	 * @param {string} op open|c|b|close
+	 * @param {string} [payload] 可选载荷
+	 * @returns {Promise<void>}
+	 */
+	async function sendOp(remoteNodeHash, linkId, op, payload) {
+		if (payload != null && payload.length > MAX_LINK_PAYLOAD_CHARS)
+			throw new Error('p2p: nostr link payload too large')
+		const packet = {
+			type: 'link',
+			op,
+			from: localIdentity?.nodeHash || '',
+			linkId,
+		}
+		if (payload != null) packet.payload = payload
+		await publishLinkPacket(remoteNodeHash, packet)
+	}
+
+	/**
+	 * @param {object} opts 会话选项
+	 * @returns {ReturnType<typeof createLinkIdBoundPipe>} pipe
+	 */
+	function openPipe(opts) {
+		const { linkId, remoteNodeHash, initiator } = opts
+		const pipe = createLinkIdBoundPipe({
+			providerId: 'nostr',
+			level: LINK_LEVEL_NOSTR,
+			initiator: !!initiator,
+			linkId,
+			nodeHash: remoteNodeHash,
+			localIdentity: opts.localIdentity || localIdentity,
+			handshakeTimeoutMs: NOSTR_HANDSHAKE_TIMEOUT_MS,
+			heartbeatMs: NOSTR_HEARTBEAT_MS,
+			idleTimeoutMs: NOSTR_IDLE_TIMEOUT_MS,
+			/**
+			 * @param {string} text control JSON
+			 * @returns {Promise<void>}
+			 */
+			async sendControlText(text) {
+				await sendOp(remoteNodeHash, linkId, 'c', text)
+			},
+			/**
+			 * @param {string} _action action
+			 * @param {Uint8Array} frame 帧
+			 * @returns {Promise<void>}
+			 */
+			async sendFrame(_action, frame) {
+				await sendOp(remoteNodeHash, linkId, 'b', bytesToBase64(frame))
+			},
+			/**
+			 * @returns {Promise<void>}
+			 */
+			async closeTransport() {
+				sessions.delete(linkId)
+				try {
+					await sendOp(remoteNodeHash, linkId, 'close')
+				}
+				catch { /* ignore */ }
+			},
+		})
+		sessions.set(linkId, { pipe, remoteNodeHash, initiator: !!initiator })
+		pipe.onDown(() => { sessions.delete(linkId) })
+		return pipe
+	}
+
+	/**
+	 * 入站已解密的 link 包（由信令 demux 调用）。
+	 * @param {object} packet link 包
+	 * @returns {void}
+	 */
+	function deliverPacket(packet) {
+		if (packet?.type !== 'link') return
+		const linkId = normalizeHex64(packet.linkId)
+		const from = normalizeHex64(packet.from)
+		if (!linkId || !from) return
+		if (localIdentity?.nodeHash && from === localIdentity.nodeHash) return
+
+		const op = String(packet.op || '')
+		if (op === 'open') {
+			if (sessions.has(linkId)) return
+			if (!onInbound || !localIdentity) return
+			const pipe = openPipe({
+				linkId,
+				remoteNodeHash: from,
+				initiator: false,
+				localIdentity,
+			})
+			onInbound(asLinkHandle(pipe))
+			void pipe.startHandshake().catch(() => {
+				sessions.delete(linkId)
+				void pipe.close('accept-failed')
+			})
+			const pending = pendingByLinkId.get(linkId) || []
+			pendingByLinkId.delete(linkId)
+			const session = sessions.get(linkId)
+			if (session)
+				for (const queued of pending)
+					applySessionPacket(session, queued)
+			return
+		}
+
+		const session = sessions.get(linkId)
+		if (!session) {
+			if (op === 'c' || op === 'b' || op === 'close')
+				bufferPending(linkId, packet)
+			return
+		}
+		applySessionPacket(session, packet)
+	}
+
+	return {
+		id: 'nostr',
+		level: LINK_LEVEL_NOSTR,
+		caps: { needsOfferAnswer: false, needsDiscoverySignal: false, probe: 'sync' },
+		isAvailable,
+		/**
+		 * @returns {boolean} 有中继即可
+		 */
+		canReach() {
+			return isAvailable()
+		},
+		deliverPacket,
+		/**
+		 * @param {object} dialOptions dial 选项
+		 * @returns {Promise<import('./index.mjs').LinkHandle | null>} link
+		 */
+		async dial(dialOptions) {
+			if (!isAvailable()) return null
+			const remoteNodeHash = normalizeHex64(dialOptions.nodeHash)
+			if (!remoteNodeHash) return null
+			localIdentity = dialOptions.localIdentity || localIdentity
+			if (!localIdentity?.nodeHash) throw new Error('p2p: nostr dial requires localIdentity')
+			const linkId = randomBytes(32).toString('hex')
+			const pipe = openPipe({
+				linkId,
+				remoteNodeHash,
+				initiator: true,
+				localIdentity,
+			})
+			await sendOp(remoteNodeHash, linkId, 'open')
+			await pipe.startHandshake()
+			return asLinkHandle(pipe)
+		},
+		/**
+		 * @param {{ onInbound: (link: import('./index.mjs').LinkHandle) => void, localIdentity: object }} handlers 回调
+		 * @returns {() => void} 停止 listening
+		 */
+		ensureListening(handlers) {
+			onInbound = handlers.onInbound
+			localIdentity = handlers.localIdentity
+			return () => {
+				onInbound = null
+				for (const session of sessions.values())
+					void session.pipe.close('listen-stop')
+				sessions.clear()
+				pendingByLinkId.clear()
+			}
+		},
+	}
+}

package/package.json

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

package/transport/offer_answer.mjs

@@ -150,11 +150,10 @@ export function createOfferAnswerDial(deps) {
 	}
 
 	/**
-	 * @param {Uint8Array} bytes 加密信令
+	 * @param {object} packet 已解密的 signal 包
 	 * @returns {Promise<void>}
 	 */
-	async function handleIncomingSignal(bytes) {
-		const packet = decryptNodeSignalPacket(localIdentity.nodeHash, bytes)
+	async function handleSignalPacket(packet) {
 		if (packet?.type !== 'signal') return
 		const remoteNodeHash = normalizeHex64(packet.from)
 		const connId = String(packet.connId || '')
@@ -175,6 +174,21 @@ export function createOfferAnswerDial(deps) {
 		session.deliver(packet.body)
 	}
 
+	/**
+	 * @param {Uint8Array} bytes 加密信令
+	 * @returns {Promise<void>}
+	 */
+	async function handleIncomingSignal(bytes) {
+		const packet = decryptNodeSignalPacket(localIdentity.nodeHash, bytes)
+		if (!packet) return
+		if (packet.type === 'link') {
+			const provider = listLinkProviders().find(entry => entry.id === 'nostr')
+			provider?.deliverPacket?.(packet)
+			return
+		}
+		await handleSignalPacket(packet)
+	}
+
 	/**
 	 * @param {import('../link/providers/index.mjs').LinkProvider} provider 链路提供者
 	 * @param {string} remoteNodeHash 远端 nodeHash
@@ -187,5 +201,5 @@ export function createOfferAnswerDial(deps) {
 		return await buildConnLink({ provider, remoteNodeHash, connId, session, initiator: true })
 	}
 
-	return { handleIncomingSignal, dialOfferAnswer }
+	return { handleIncomingSignal, handleSignalPacket, dialOfferAnswer }
 }

package/transport/runtime_bootstrap.mjs

@@ -18,6 +18,7 @@ import {
 	unregisterLinkProvider,
 } from '../link/providers/index.mjs'
 import { createLanTcpLinkProvider } from '../link/providers/lan_tcp.mjs'
+import { createNostrLinkProvider } from '../link/providers/nostr.mjs'
 import { createWebRtcLinkProvider } from '../link/providers/webrtc.mjs'
 import { getNodeTransportSettings } from '../node/identity.mjs'
 import { getSignalingRuntimeConfig, onNodeChange } from '../node/instance.mjs'
@@ -157,6 +158,8 @@ export function createRuntimeBootstrap(deps) {
 		const ids = new Set(listLinkProviders().map(provider => provider.id))
 		if (!ids.has('webrtc'))
 			registerLinkProvider(createWebRtcLinkProvider())
+		if (!ids.has('nostr'))
+			registerLinkProvider(createNostrLinkProvider({ getRelayUrls: resolveNostrRelayUrls }))
 	}
 
 	/**