@steve02081504/fount-p2p 0.0.14 → 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.
 
@@ -44,6 +46,14 @@ npx @steve02081504/fount-p2p
 
 Default `nodeDir`: Windows `%LOCALAPPDATA%/fount-p2p/node`; elsewhere `~/.local/share/fount-p2p/node`.
 
+Deno (optional; WebRTC needs explicit native scripts — **not** blanket `--allow-scripts`):
+
+```bash
+deno run -A --minimum-dependency-age=0 --node-modules-dir=auto --allow-scripts=npm:node-datachannel npm:@steve02081504/fount-p2p
+```
+
+See [docs/runtime.md](./docs/runtime.md).
+
 ```javascript
 import { initNode, startNode, startInfra, stopInfra, setInfraPriority } from '@steve02081504/fount-p2p'
 
@@ -78,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.
 
@@ -91,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).
 
@@ -99,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/deno.json

@@ -1,4 +1,7 @@
 {
 	"nodeModulesDir": "none",
-	"lock": false
+	"lock": false,
+	"allowScripts": [
+		"npm:node-datachannel"
+	]
 }

package/discovery/adverts.mjs

@@ -1,8 +1,6 @@
 import { normalizeHex64 } from '../core/hexIds.mjs'
 import { buildSignedAdvert, verifySignedAdvert } from '../link/handshake.mjs'
 
-import { listMulticastIpv4Addresses } from './lan_interfaces.mjs'
-
 import {
 	decryptSignalPacket,
 	encryptSignalPacket,
@@ -10,6 +8,7 @@ import {
 	networkRendezvousKey,
 	nodeRendezvousKey,
 } from './internal/signal_crypto.mjs'
+import { listMulticastIpv4Addresses } from './lan_interfaces.mjs'
 
 /** @typedef {'node' | 'network' | { roomSecret: string }} AdvertScope */
 

package/discovery/bt/index.mjs

@@ -4,6 +4,7 @@ import { isHex64, normalizeHex64 } from '../../core/hexIds.mjs'
 import { nodeDebug, shortHash } from '../../node/log.mjs'
 import { noteAdvertPeerHints } from '../advert_peer_hints.mjs'
 import { ingestNetworkAdvert } from '../adverts.mjs'
+import { noteDiscoveryPeerClue } from '../peer_clue.mjs'
 
 import { getBtPeerHint } from './peer_hints.mjs'
 import { canUseBluetoothRuntime, loadBleno, loadNoble, resolveBtRole, waitPoweredOn } from './runtime.mjs'
@@ -106,11 +107,13 @@ export async function acceptBtScannedPresence(bytes, meta) {
 	const firstSeen = !visibleByHash.has(ingested.verifiedNodeHash)
 	noteBtVisibleNode(ingested.verifiedNodeHash)
 	noteAdvertPeerHints(ingested.verifiedNodeHash, ingested.body, meta)
-	if (firstSeen)
+	if (firstSeen) {
+		noteDiscoveryPeerClue(ingested.verifiedNodeHash)
 		nodeDebug('p2p:bt peer visible', {
 			peer: shortHash(ingested.verifiedNodeHash),
 			peripheralId,
 		})
+	}
 	return ingested
 }
 

package/discovery/lan.mjs

@@ -9,6 +9,7 @@ import { noteAdvertPeerHints } from './advert_peer_hints.mjs'
 import { ingestNetworkAdvert } from './adverts.mjs'
 import { listMulticastIpv4Addresses } from './lan_interfaces.mjs'
 import { getLanPeerHint } from './lan_peer_hints.mjs'
+import { noteDiscoveryPeerClue } from './peer_clue.mjs'
 
 const DEFAULT_PORT = 53531
 const DEFAULT_GROUP = '239.255.42.99'
@@ -66,6 +67,7 @@ export async function acceptLanPresenceAdvert(advertBytes, meta = {}) {
 	noteLanVisibleNode(ingested.verifiedNodeHash)
 	noteAdvertPeerHints(ingested.verifiedNodeHash, ingested.body, meta)
 	if (firstSeen) {
+		noteDiscoveryPeerClue(ingested.verifiedNodeHash)
 		const host = String(meta.address || '').trim()
 		nodeDebug('p2p:lan peer visible', {
 			peer: shortHash(ingested.verifiedNodeHash),
@@ -78,7 +80,7 @@ export async function acceptLanPresenceAdvert(advertBytes, meta = {}) {
 
 /**
  * LAN UDP presence：段内 beacon，非 topic 订阅模型。
- * @param {{ port?: number, group?: string }} [options] 配置
+ * @param {{ port?: number, group?: string, localNodeHash?: string }} [options] 配置
  * @returns {import('./index.mjs').DiscoveryProvider} LAN 发现提供者
  */
 export function createLanDiscoveryProvider(options = {}) {
@@ -91,12 +93,14 @@ export function createLanDiscoveryProvider(options = {}) {
 	let refs = 0
 	/** @type {ReturnType<typeof setInterval> | null} */
 	let beaconTimer = null
+	const seededSelf = normalizeHex64(options.localNodeHash)
 	/** @type {string | null} */
-	let selfNodeHash = null
+	let selfNodeHash = isHex64(seededSelf) ? seededSelf : null
 	/** @type {Set<string>} */
 	const joinedAddresses = new Set()
 
 	/**
+	 * 在每个本机 IPv4 接口上加入组播组；全部失败则回退到默认接口。
 	 * @param {import('node:dgram').Socket} sock UDP socket
 	 * @returns {void}
 	 */
@@ -112,6 +116,11 @@ export function createLanDiscoveryProvider(options = {}) {
 		if (!joinedAddresses.size)
 			try { sock.addMembership(group) } catch { /* ignore */ }
 	}
+
+	/**
+	 * 懒创建复用的 udp4 socket（reuseAddr，便于同机多实例绑同一 port）。
+	 * @returns {import('node:dgram').Socket} 组播 presence socket
+	 */
 	function getSocket() {
 		return socket ||= dgram.createSocket({ type: 'udp4', reuseAddr: true })
 	}
@@ -190,7 +199,7 @@ export function createLanDiscoveryProvider(options = {}) {
 		let sent = 0
 		/** @type {unknown} */
 		let lastError = null
-		for (const addr of addrs) {
+		for (const addr of addrs)
 			try {
 				await sendOnce(addr)
 				sent++
@@ -198,7 +207,6 @@ export function createLanDiscoveryProvider(options = {}) {
 			catch (error) {
 				lastError = error
 			}
-		}
 		if (!sent) throw lastError || new Error('p2p: lan multicast send failed')
 	}