@steve02081504/fount-p2p 0.0.43 → 0.0.44

package/AGENTS.md

@@ -66,6 +66,7 @@ Deno / native / BT: [runtime.md](docs/runtime.md).
 ### Node / network
 
 - **Node data:** `initNode({ nodeDir, entityStore? })` — `node.json`, `network.json`, `denylist.json`, `reputation.json`, `mailbox/`, `chunks/`. Default EntityStore: `{nodeDir}/entities/`. No `FOUNT_*` env knobs — subprocess IPC uses argv.
+- **Storage vs runtime:** local identity (`ensureNodeSeed` / `getNodeHash` / `resolveLocalEntityHashFromRecoveryPubKeyHex`, all `node/storage` JSON helpers) must not require `initNode`. Configure the dir with `configureNodeStorage({ nodeDir })` (idempotent; cannot switch while running — `closeNode()` first) and only call `initNode` when the network should run. Hosts configure storage unconditionally so entities have a local identity with P2P disabled. [runtime.md](docs/runtime.md)
 - **fount network:** shells use `startNode` / `ensureLinkToNode` / `sendToNodeLink` / rooms — never import `link/` internals or pick a transport. Providers: `registerLinkProvider` from `./link` or facade.
 - **Link `level` vs discovery `priority`:** descending `level` picks data transport (`nostr` = −∞ last resort); ascending `priority` orders handshake/presence media only. [transports.md](docs/transports.md)
 - **Mesh first / no versioning:** ≥N links (K acquaintances + N−K explore); discovery API is `listVisibleNodeHashes` + `connectToNode` only; no topic on the fount-network surface; no version/compat fields. [mesh.md](docs/mesh.md)

package/docs/runtime.md

@@ -2,6 +2,24 @@
 
 `ensureRuntime`, startup/shutdown budgets, and Bluetooth hardware probe. Day-to-day shell rules: [AGENTS.md](../AGENTS.md). Providers: [transports.md](transports.md). Mesh N/K: [mesh.md](mesh.md).
 
+## Offline local identity (storage without a running node)
+
+Three independent stages — do not couple them:
+
+1. **Storage** — `configureNodeStorage({ nodeDir })` records where `node.json` / identity seed live. No runtime, no disk I/O, no discovery.
+2. **Local identity** — `ensureNodeSeed` / `getNodeHash` / `resolveLocalEntityHashFromRecoveryPubKeyHex` (and `node/storage` JSON helpers) only need stage 1, so a local `entityHash` can be created while federation is off.
+3. **Network** — `initNode({ nodeDir, entityStore })` builds the runtime and link graph. Same `nodeDir` as stage 1 reuses the persisted seed and hashes.
+
+```javascript
+import { configureNodeStorage } from '@steve02081504/fount-p2p/node/instance'
+import { resolveLocalEntityHashFromRecoveryPubKeyHex } from '@steve02081504/fount-p2p/node/identity'
+
+configureNodeStorage({ nodeDir: '/data/p2p/node' })
+const entityHash = resolveLocalEntityHashFromRecoveryPubKeyHex(recoveryPubKeyHex) // works with P2P disabled
+```
+
+`configureNodeStorage` is idempotent for the same dir; switching dirs while a node is running is rejected (call `closeNode()` first). `closeNode()` clears the storage config, so re-configure after closing. Consumer hosts (fount, subfount) call `configureNodeStorage` unconditionally at startup and only call `initNode` when P2P is enabled.
+
 ## `ensureRuntime` contract
 
 Returns after registering lan / nostr discovery providers (subject to the signaling `channels` whitelist), registering all enabled link providers (including `ble_gatt`), and scheduling background warm — does **not** await lan_tcp listen, Nostr relays, or BT availability.

package/index.mjs

@@ -13,6 +13,7 @@ import { registerLinkProvider } from './link/providers/index.mjs'
 import { ensureNodeDefaults, getNodeHash } from './node/identity.mjs'
 import {
 	closeNode,
+	configureNodeStorage,
 	getNodeDir,
 	getP2PFeatures,
 	initNode,
@@ -65,6 +66,7 @@ export {
 	attachNodeScopeDefaultFeatures,
 	closeNode,
 	configureLinkRegistry,
+	configureNodeStorage,
 	createGroupLinkSet,
 	createScopedLinkRoom,
 	ensureChannelAvailable,

package/node/identity.mjs

@@ -42,6 +42,8 @@ function saveNodeFile(patch) {
 }
 
 /**
+ * 确保本地节点 seed 已持久化并返回。
+ * 只依赖本地存储目录（`configureNodeStorage` 或 `initNode` 提供），不要求运行中的节点。
  * @returns {string} 64 位十六进制 节点种子
  */
 export function ensureNodeSeed() {
@@ -54,6 +56,8 @@ export function ensureNodeSeed() {
 }
 
 /**
+ * 由本地 seed 派生本节点 nodeHash。
+ * 只依赖本地存储目录，不要求运行中的节点。
  * @returns {string} 本节点 64 hex nodeHash
  */
 export function getNodeHash() {
@@ -111,6 +115,8 @@ export function entityHashFromKeys(nodeHash, recoveryPubKeyHex) {
 }
 
 /**
+ * 由本地 nodeHash 与 recovery 公钥派生本节点 entityHash。
+ * 只依赖本地存储目录，不要求运行中的节点（联邦未启动时也可创建本地身份）。
  * @param {string} recoveryPubKeyHex 64 位十六进制 recovery 公钥
  * @returns {string | null} 本节点 entityHash
  */

package/node/instance.mjs

@@ -22,6 +22,13 @@ import { defaultSignalingRuntimeConfig, resolveSignalingRuntimeConfig } from './
 /** @type {NodeRuntime | null} */
 let runtime = null
 
+/**
+ * 本地节点数据目录。与 `runtime` 解耦：身份 seed 等纯本地持久化只依赖存储目录，
+ * 不要求 `initNode()`（联邦未启动时也要能派生本地身份）。
+ * @type {string | null}
+ */
+let nodeStorageDir = null
+
 /** @type {Set<(event: string, payload?: unknown) => void>} */
 const changeListeners = new Set()
 
@@ -35,6 +42,28 @@ export function getRtcPolyfillCacheEpoch() {
 	return rtcPolyfillCacheEpoch
 }
 
+/**
+ * 配置本地节点数据目录（`node.json` / 身份 seed 等纯本地持久化位置），
+ * 不初始化节点运行时、不创建 disk 资源、不启动发现或连接。
+ *
+ * 配置后 `getNodeDir` / `ensureNodeSeed` / `getNodeHash` /
+ * `resolveLocalEntityHashFromRecoveryPubKeyHex` 可在无运行节点时使用；
+ * 之后以同一目录调用 `initNode` 会复用已持久化的 seed 与身份。
+ *
+ * 同目录重复配置为幂等；运行中的节点不允许切换到不同目录，须先 `closeNode()`。
+ * @param {{ nodeDir: string }} options - 本地节点数据目录
+ * @returns {string} 规范化为绝对路径后的目录
+ */
+export function configureNodeStorage(options) {
+	const rawDir = options?.nodeDir
+	if (typeof rawDir !== 'string' || !rawDir) throw new Error('p2p: configureNodeStorage requires nodeDir')
+	const nodeDir = path.resolve(rawDir)
+	if (runtime && runtime.nodeDir !== nodeDir)
+		throw new Error('p2p: running node uses another nodeDir — call closeNode() before reconfiguring storage')
+	nodeStorageDir = nodeDir
+	return nodeDir
+}
+
 /**
  * @param {{ nodeDir: string, entityStore?: import('./entity_store.mjs').EntityStore }} options - 节点目录与可选 entity store
  * @returns {NodeRuntime} 初始化后的运行时
@@ -43,7 +72,7 @@ export function initNode(options) {
 	if (runtime) throw new Error('p2p: initNode already called — use setNodeLogger / setSignalingRuntimeConfig or closeNode')
 	if (options?.logger !== undefined || options?.signaling !== undefined)
 		throw new Error('p2p: initNode only accepts nodeDir/entityStore — use setNodeLogger / setSignalingRuntimeConfig')
-	const nodeDir = path.resolve(options.nodeDir)
+	const nodeDir = options?.nodeDir == null ? nodeStorageDir : configureNodeStorage({ nodeDir: options.nodeDir })
 	if (!nodeDir) throw new Error('p2p: initNode requires nodeDir')
 	const entityStore = options.entityStore ?? createFsEntityStore(path.join(nodeDir, 'entities'))
 	runtime = {
@@ -123,10 +152,12 @@ export function getP2PFeatures() {
 }
 
 /**
- * @returns {string} 节点数据目录绝对路径
+ * @returns {string} 节点数据目录绝对路径；未配置且节点未初始化时抛错
  */
 export function getNodeDir() {
-	return getNode().nodeDir
+	if (runtime) return runtime.nodeDir
+	if (nodeStorageDir) return nodeStorageDir
+	throw new Error('p2p: node storage not configured — call configureNodeStorage() or initNode() first')
 }
 
 /**
@@ -164,12 +195,13 @@ export function onNodeChange(listener) {
 }
 
 /**
- * 关闭节点：释放全部文件句柄（chunk 读/写流等）并清空运行时与监听器。
- * 之后可用 initNode 重新引导。
+ * 关闭节点：释放全部文件句柄（chunk 读/写流等）并清空运行时、存储目录配置与监听器。
+ * 之后可用 initNode / configureNodeStorage 重新引导。
  * @returns {Promise<void>}
  */
 export async function closeNode() {
 	runtime = null
+	nodeStorageDir = null
 	changeListeners.clear()
 	rtcPolyfillCacheEpoch++
 	await closeAllFileStreams()

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.43",
+	"version": "0.0.44",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",
@@ -15,7 +15,7 @@
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/steve02081504/fount-p2p.git",
-		"directory": "."
+		"directory": "js"
 	},
 	"engines": {
 		"node": ">=20"