@mebular/mcp 0.0.0-stage → 0.1.0

package/src/config.mjs

@@ -0,0 +1,265 @@
+// MCP 侧配置加载（G6.2）
+//
+// 优先级：CLI > env > .mebular/config.json > 默认。
+// 密钥不落 config：主密钥来自 env / config.encryption.keyFile / <home>/user-master-key.json，
+// 都没有则生成并持久化到 <home>/user-master-key.json（0600）。
+
+import { existsSync, readFileSync } from 'node:fs';
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { Mebular, IdentityManager, FileEndpointStore, EndpointBook } from '@mebular/core';
+import { homeDir } from './home.mjs';
+
+/** 统一家目录（唯一真源，F-INST-1）：见 `./home.mjs`。 */
+export { homeDir };
+
+export function configPath(home) {
+  return process.env.MEBULAR_CONFIG ?? join(home, 'config.json');
+}
+
+/** C2：候选地址簿文件（0600；机制在 core，路径由 app 决定）。 */
+export function endpointsPath(home) {
+  return process.env.MEBULAR_ENDPOINTS_FILE ?? join(home, 'net', 'peers.json');
+}
+
+/** C2：配置里的配对 hints（deviceId/peerId → multiaddr 列表），形状容错。 */
+export function networkHints(config) {
+  const raw = config?.network?.endpoints;
+  const out = {};
+  if (!raw || typeof raw !== 'object') return out;
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof key !== 'string' || !Array.isArray(value)) continue;
+    const addrs = value.filter((entry) => typeof entry === 'string' && entry.length > 0);
+    if (addrs.length > 0) out[key] = addrs;
+  }
+  return out;
+}
+
+/**
+ * C2：从地址簿保留键读取 relay seeds（配对令牌随附；daemon 启动时并入 relayServers）。
+ * 读失败一律返回 []（地址簿问题不得阻断启动）。
+ */
+export async function relaySeedsFromBook(home) {
+  try {
+    const book = new EndpointBook({ store: new FileEndpointStore(endpointsPath(home)) });
+    await book.load();
+    return book.relaySeeds();
+  } catch {
+    return [];
+  }
+}
+
+/** C2：relay seeds（客户端可用于中转的 relay multiaddr；并入 libp2p.relayServers）。 */
+export function relaySeeds(config) {
+  const raw = config?.network?.relaySeeds;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((entry) => typeof entry === 'string' && entry.length > 0);
+}
+
+export async function loadConfigFile(home) {
+  const path = configPath(home);
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(await readFile(path, 'utf-8'));
+  } catch (error) {
+    throw new Error(`配置文件损坏：${path}（${error.message}）`);
+  }
+}
+
+function truthy(value, fallback) {
+  if (value === undefined) return fallback;
+  return value === true || value === 'true' || value === '1';
+}
+
+async function readKeyRecord(source) {
+  const data = existsSync(source)
+    ? JSON.parse(await readFile(source, 'utf-8'))
+    : JSON.parse(source);
+  return {
+    userMasterKey: new Uint8Array(Buffer.from(data.publicKey, 'base64')),
+    userMasterPrivateKey: await IdentityManager.importPrivateKey(data.privateKeyPkcs8),
+  };
+}
+
+/** 解析用户主密钥；按 env > config.keyFile > <home>/user-master-key.json > 生成并持久化 */
+export async function resolveMasterKeys(home, config) {
+  const envFile = process.env.MEBULAR_USER_MASTER_KEY_FILE;
+  const envInline = process.env.MEBULAR_USER_MASTER_KEY;
+  if (envFile) return readKeyRecord(envFile);
+  if (envInline) return readKeyRecord(envInline);
+
+  const configuredFile = config.encryption?.keyFile;
+  if (configuredFile) return readKeyRecord(configuredFile);
+
+  const defaultFile = join(home, 'user-master-key.json');
+  if (existsSync(defaultFile)) return readKeyRecord(defaultFile);
+
+  const master = await new IdentityManager().generateUserMasterKey();
+  const record = {
+    publicKey: Buffer.from(master.publicKey).toString('base64'),
+    privateKeyPkcs8: await IdentityManager.exportPrivateKey(master.privateKey),
+    createdAt: new Date().toISOString(),
+  };
+  await mkdir(dirname(defaultFile), { recursive: true });
+  await writeFile(defaultFile, JSON.stringify(record, null, 2), 'utf-8');
+  await chmod(defaultFile, 0o600);
+  return { userMasterKey: master.publicKey, userMasterPrivateKey: master.privateKey };
+}
+
+/**
+ * 身份模式（W2）：`root`（持有用户主密钥私钥）或 `delegated`（仅委派证书链 + 设备钥，**无主私钥**）。
+ * 判定：显式 `identity.mode` 优先；否则存在 `<storagePath>.identity.json` 且无本地主私钥 → delegated。
+ */
+export function identityMode(home, config, storagePath) {
+  const explicit = config.identity?.mode;
+  if (explicit === 'root' || explicit === 'delegated') return explicit;
+  const identityFile = `${storagePath}.identity.json`;
+  const masterFile = config.encryption?.keyFile ?? join(home, 'user-master-key.json');
+  if (existsSync(identityFile)) {
+    try {
+      const rec = JSON.parse(readFileSync(masterFile, 'utf-8'));
+      if (typeof rec.privateKeyPkcs8 !== 'string') return 'delegated';
+    } catch {
+      return 'delegated';
+    }
+  }
+  return 'root';
+}
+
+/** 读取**用户主公钥**（委派模式只需公钥；`config.encryption.userMasterPublicKeyFile` 或 <home>/user-master-key.json）。 */
+export async function resolveMasterPublicKey(home, config) {
+  const file = config.encryption?.userMasterPublicKeyFile ?? join(home, 'user-master-key.json');
+  if (!existsSync(file)) {
+    throw new Error(`委派身份模式需要用户主公钥：${file}（配置 encryption.userMasterPublicKeyFile 或放入该文件）`);
+  }
+  const data = JSON.parse(await readFile(file, 'utf-8'));
+  if (typeof data.publicKey !== 'string') throw new Error(`主公钥文件形状非法：${file}`);
+  return new Uint8Array(Buffer.from(data.publicKey, 'base64'));
+}
+
+/** 依配置构建并初始化 Mebular 门面 */
+export async function createMebular() {
+  const home = homeDir();
+  const config = await loadConfigFile(home);
+  const storageAdapter = config.storageAdapter ?? 'json';
+  const storagePath = process.env.MEBULAR_STORAGE_PATH
+    ?? config.storagePath
+    ?? join(home, storageAdapter === 'sqlite' ? 'store.sqlite' : 'store.jsonl');
+  const deviceId = process.env.MEBULAR_DEVICE_ID ?? config.deviceId ?? `device-${process.env.HOSTNAME ?? 'local'}`;
+  const deviceName = process.env.MEBULAR_DEVICE_NAME ?? config.deviceName;
+  const mode = identityMode(home, config, storagePath);
+  // 生效值快照（console 设置卡应展示这些，而不是静态 config，否则 CLI/env 覆盖后卡片会失真）
+  const effective = {
+    deviceName: deviceName ?? null,
+    identityMode: mode,
+    storageAdapter,
+    encryptionLevel: config.encryption?.level ?? 'none',
+    networkEnabled: truthy(process.env.MEBULAR_NETWORK_ENABLED, config.network?.enabled ?? false),
+    autoSync: config.sync?.autoSync ?? true,
+    // C2：候选地址簿（自动选路）与端点簿文件
+    autoConnect: config.network?.autoConnect !== false,
+    endpointsPath: endpointsPath(home),
+    endpointsCount: Object.keys(networkHints(config)).length,
+    relaySeeds: relaySeeds(config),
+    // C3：LAN 自动发现
+    lanEnabled: config.network?.lan?.enabled !== false,
+    lanAutoDial: config.network?.lan?.autoDial !== false,
+    lanDefaultFactory: config.network?.lan?.defaultFactory !== false,
+    pushOnWrite: truthy(process.env.MEBULAR_PUSH_ON_WRITE, config.sync?.pushOnWrite ?? true),
+    pushOnWriteThrottleMs: config.sync?.pushOnWriteThrottleMs ?? null,
+    peerWhitelist: Array.isArray(config.sync?.peerWhitelist) ? [...config.sync.peerWhitelist] : [],
+    semanticEnabled: truthy(process.env.MEBULAR_SEMANTIC_ENABLED, config.semantic?.enabled ?? false),
+    semanticMinScore: config.semantic?.minScore ?? 0.2,
+  };
+  const masterKeys =
+    mode === 'delegated'
+      ? { userMasterKey: await resolveMasterPublicKey(home, config) }
+      : await resolveMasterKeys(home, config);
+
+  // C2：地址簿里的 seeds（配对时随令牌写入）+ 配置 seeds → 客户端 relay 列表
+  const bookSeeds = effective.networkEnabled ? await relaySeedsFromBook(home) : [];
+  const app = new Mebular({
+    storagePath,
+    deviceId,
+    ...(deviceName ? { deviceName } : {}),
+    ...(config.storageAdapter ? { storageAdapter: config.storageAdapter } : {}),
+    encryption: {
+      level: effective.encryptionLevel,
+      userMasterKey: masterKeys.userMasterKey,
+      ...(masterKeys.userMasterPrivateKey !== undefined ? { userMasterPrivateKey: masterKeys.userMasterPrivateKey } : {}),
+      ...(process.env[config.encryption?.passphraseEnv ?? 'MEBULAR_PASSPHRASE']
+        ? { passphrase: process.env[config.encryption?.passphraseEnv ?? 'MEBULAR_PASSPHRASE'] }
+        : {}),
+    },
+    network: {
+      enabled: effective.networkEnabled,
+      // C2：无显式地址时走候选地址簿（默认开）；hints/端点簿由 app 注入，core 不读文件
+      autoConnect: effective.autoConnect,
+      // 常驻入口：默认真 mDNS（策略在 app；库形态默认关闭）
+      lan: {
+        enabled: effective.lanEnabled,
+        autoDial: effective.lanAutoDial,
+        defaultFactory: effective.lanEnabled && effective.lanDefaultFactory,
+      },
+      endpoints: networkHints(config),
+      endpointStore: new FileEndpointStore(effective.endpointsPath),
+      // C4：NAT 穿透（AutoNAT/DCUtR）直通；未配置 = auto（依赖在场即启用）
+      ...(config.network?.nat ? { nat: config.network.nat } : {}),
+      ...(config.network?.libp2p || bookSeeds.length > 0
+        ? {
+            libp2p: {
+              ...(config.network.libp2p.listen ? { listen: config.network.libp2p.listen } : {}),
+              ...(() => {
+                const seeds = [...new Set([...(config.network.libp2p.relayServers ?? []), ...effective.relaySeeds, ...bookSeeds])];
+                return seeds.length > 0 ? { relayServers: seeds } : {};
+              })(),
+              ...(config.network.libp2p.relayPolicy ? { relayPolicy: config.network.libp2p.relayPolicy } : {}),
+              ...(config.network.libp2p.relayServer !== undefined
+                ? { relayServer: config.network.libp2p.relayServer }
+                : {}),
+              ...(config.network.libp2p.relayUnlimited !== undefined
+                ? { relayUnlimited: config.network.libp2p.relayUnlimited }
+                : {}),
+            },
+          }
+        : {}),
+    },
+    sync: {
+      autoSync: config.sync?.autoSync ?? true,
+      // 常驻入口（MCP serve）默认实时：写入即推（含反向 nudge）+ 周期 anti-entropy。
+      // 库形态默认关闭（见 README「同步触发时机」）；可显式置 false 关闭。
+      pushOnWrite: effective.pushOnWrite,
+      ...(effective.pushOnWriteThrottleMs !== null ? { pushOnWriteThrottleMs: effective.pushOnWriteThrottleMs } : {}),
+      antiEntropy: config.sync?.antiEntropy ?? { enabled: true, intervalMs: 600000, jitterRatio: 0.2 },
+      // P3 · 收敛健康度：常驻入口默认开启（纯观察层；形状照 antiEntropy 先例）。
+      // 会话尾状态指纹（C3 A 类可选字段）随之启用；kill-switch：config.json 置
+      // sync.convergence = { enabled:false } 即回默认静默观察。
+      convergence: config.sync?.convergence ?? { enabled: true },
+      ...(config.sync?.snapshotThreshold !== undefined
+        ? { snapshotThreshold: config.sync.snapshotThreshold }
+        : {}),
+      ...(Array.isArray(config.sync?.namespaces) ? { namespaces: config.sync.namespaces } : {}),
+      ...(Array.isArray(config.sync?.peerWhitelist) ? { peerWhitelist: config.sync.peerWhitelist } : {}),
+    },
+    semantic: {
+      enabled: effective.semanticEnabled,
+      ...(config.semantic?.model ? { model: config.semantic.model } : {}),
+      ...(config.semantic?.cacheDir ? { cacheDir: config.semantic.cacheDir } : {}),
+      ...(config.semantic?.minScore !== undefined ? { minScore: config.semantic.minScore } : {}),
+    },
+  });
+  await app.initialize();
+  // W2：按 config.network.peers 主动拨号（daemon 形态的点对点建立；只有一方需地址）
+  for (const peer of config.network?.peers ?? []) {
+    if (typeof peer?.addr !== 'string' || peer.addr.length === 0) continue;
+    const id = /\/p2p\/([^/]+)/.exec(peer.addr)?.[1] ?? peer.device;
+    try {
+      await app.node?.connectToPeer({ id, multihash: new Uint8Array(), pubKey: new Uint8Array() }, peer.addr);
+    } catch {
+      // 由后续 anti-entropy / doctor 暴露
+    }
+  }
+  return { app, home, config, storagePath, deviceId, identityMode: mode, effective };
+}
+
+export { homedir } from 'node:os';

package/src/fleet-events.mjs

@@ -0,0 +1,207 @@
+// Fleet 事件流：把**真实任务事件**映射为 `/admin/events` 的 `fleet` 广播载荷。
+//
+// 任务事件以图示记忆节点（`type='task_event'`）承载；事件日志里对应
+// `node_created` 事件（`data.node` 即任务节点）。本模块只做只读映射与接线：
+//   - 本地写入：`eventLog.on('event-appended')`（仅本地 append 触发）
+//   - 远端应用：`sync.on('events-applied')`（按 eventIds 回查 eventLog）
+// 不写存储、不改任务/同步协议。无效事件一律返回 null / 静默跳过，不抛异常。
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/** 任务事件节点的类型（`MebularTaskEventStore` 默认值）。 */
+export const TASK_EVENT_NODE_TYPE = 'task_event';
+
+/** 任务域默认 namespace（`fleet.config.json` 缺省 / 缺文件）。 */
+export const TASK_NAMESPACE_DEFAULT = 'tasks';
+
+/** 当前可广播的 TaskEvent 类型 → `fleet` 载荷的 `eventType`（先只保证 created）。 */
+const FLEET_EVENT_TYPES = Object.freeze({
+  created: 'created',
+});
+
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const nonEmptyString = (value) => typeof value === 'string' && value.length > 0;
+
+/**
+ * 从事件日志事件中取任务节点。兼容三种形状：
+ *   1) 日志事件：`{ type:'node_created', data:{ node:{ type:'task_event', ... } } }`
+ *   2) 带 node 字段：`{ node:{ type:'task_event', ... } }`
+ *   3) 裸任务节点：`{ type:'task_event', content:{...}, namespace }`
+ */
+function taskNodeOf(event) {
+  if (!isRecord(event)) return null;
+  const data = isRecord(event.data) ? event.data : null;
+  const candidates = [
+    data?.node,
+    event.node,
+    data && data.type === TASK_EVENT_NODE_TYPE ? data : null,
+    event.type === TASK_EVENT_NODE_TYPE ? event : null,
+  ];
+  for (const candidate of candidates) {
+    if (isRecord(candidate) && candidate.type === TASK_EVENT_NODE_TYPE) return candidate;
+  }
+  return null;
+}
+
+/** 事件的 namespace：节点优先；日志事件回退自身；缺失按 core 语义视为 `default`。 */
+function namespaceOf(event, node) {
+  if (nonEmptyString(node?.namespace)) return node.namespace;
+  if (nonEmptyString(event?.namespace)) return event.namespace;
+  if (nonEmptyString(event?.data?.namespace)) return event.data.namespace;
+  return 'default';
+}
+
+/**
+ * 纯映射：事件 → `fleet` SSE 载荷（无效 / 不属于任务域 / 非 created / 缺字段 → null）。
+ *
+ * 载荷契约（前端按此实现，勿改字段名）：
+ * `{ at, fromDeviceId, toDeviceId, taskId, eventType:'created', namespace }`
+ * `at` 为广播时刻（与本文件其它 SSE 事件一致）。
+ *
+ * @param {unknown} event 事件日志事件（或任务节点）
+ * @param {{ namespace?: string, now?: (() => number) | number }} [options]
+ */
+export function fleetEventFromEvent(event, options = {}) {
+  try {
+    const namespace = nonEmptyString(options.namespace) ? options.namespace : TASK_NAMESPACE_DEFAULT;
+    const node = taskNodeOf(event);
+    if (!node) return null;
+    if (namespaceOf(event, node) !== namespace) return null;
+
+    const content = isRecord(node.content)
+      ? node.content
+      : (isRecord(event?.content) ? event.content : null);
+    if (!content) return null;
+    if (typeof content.type !== 'string') return null;
+
+    const eventType = FLEET_EVENT_TYPES[content.type];
+    if (!eventType) return null;
+
+    const taskId = nonEmptyString(content.taskId) ? content.taskId : null;
+    const fromDeviceId = nonEmptyString(content.actor?.device) ? content.actor.device : null;
+    const toDeviceId = nonEmptyString(content.to?.device) ? content.to.device : null;
+    if (!taskId || !fromDeviceId || !toDeviceId) return null;
+
+    const now = typeof options.now === 'function' ? options.now() : options.now;
+    const at = Number.isFinite(now) ? Number(now) : Date.now();
+
+    return { at, fromDeviceId, toDeviceId, taskId, eventType, namespace };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 读取本机任务域：优先 `fleet.config.json` 的 `namespace`；缺文件 / 解析失败时回退
+ * 守护运行时的 namespace（`config.sync.namespaces[0]`，默认 `tasks`）。
+ */
+export async function resolveFleetNamespace({ home, fallback = TASK_NAMESPACE_DEFAULT } = {}) {
+  const fallbackNamespace = nonEmptyString(fallback) ? fallback : TASK_NAMESPACE_DEFAULT;
+  if (!nonEmptyString(home)) return fallbackNamespace;
+  try {
+    const raw = JSON.parse(await readFile(join(home, 'fleet.config.json'), 'utf-8'));
+    return nonEmptyString(raw?.namespace) ? raw.namespace : fallbackNamespace;
+  } catch {
+    return fallbackNamespace;
+  }
+}
+
+/**
+ * 接线：把事件源接到 `send('fleet', payload)`，返回清理函数（移除监听、停止后续投递）。
+ *
+ * - 同一事件只广播一次：以日志事件 id + `taskId#eventType` 双键去重；
+ *   本地 append 与远端应用的同一条事件共享日志 id，因此不会重复。
+ * - 远端 `events-applied` 只拿到 eventIds，用 `eventLog.getEvent(id)` 回查完整事件。
+ * - 去重集合有上界（默认 4096），按插入顺序淘汰最旧键，避免长连接无界增长。
+ */
+export function attachFleetEvents({
+  eventLog,
+  sync = null,
+  namespace = TASK_NAMESPACE_DEFAULT,
+  send,
+  now = Date.now,
+  dedupeLimit = 4096,
+} = {}) {
+  if (!eventLog || typeof eventLog.on !== 'function' || typeof send !== 'function') {
+    return () => undefined;
+  }
+  const targetNamespace = nonEmptyString(namespace) ? namespace : TASK_NAMESPACE_DEFAULT;
+  const limit = Number.isFinite(dedupeLimit) && dedupeLimit > 0 ? Math.floor(dedupeLimit) : 4096;
+  const seen = new Set();
+  let closed = false;
+
+  const claim = (keys) => {
+    const present = keys.filter(nonEmptyString);
+    if (present.some((key) => seen.has(key))) return false;
+    for (const key of present) {
+      seen.add(key);
+      if (seen.size > limit) {
+        const oldest = seen.values().next().value;
+        if (oldest !== undefined) seen.delete(oldest);
+      }
+    }
+    return true;
+  };
+
+  const emit = (event) => {
+    if (closed) return false;
+    const payload = fleetEventFromEvent(event, { namespace: targetNamespace, now });
+    if (!payload) return false;
+    const keys = [];
+    if (nonEmptyString(event?.id)) keys.push(`event:${event.id}`);
+    keys.push(`task:${payload.taskId}#${payload.eventType}`);
+    if (!claim(keys)) return false;
+    try {
+      send('fleet', payload);
+    } catch {
+      // 连接已断开：不抛出，继续等清理
+    }
+    return true;
+  };
+
+  const onAppended = (event) => {
+    emit(event);
+  };
+
+  const onEventsApplied = (info) => {
+    if (closed || typeof eventLog.getEvent !== 'function') return;
+    const ids = Array.isArray(info?.eventIds) ? info.eventIds : [];
+    if (ids.length === 0) return;
+    void (async () => {
+      for (const id of ids) {
+        if (closed) return;
+        let event = null;
+        try {
+          event = await eventLog.getEvent(id);
+        } catch {
+          continue;
+        }
+        if (event) emit(event);
+      }
+    })().catch(() => undefined);
+  };
+
+  eventLog.on('event-appended', onAppended);
+  const removeApplied = () => {
+    if (sync && typeof sync.off === 'function') sync.off('events-applied', onEventsApplied);
+  };
+  if (sync && typeof sync.on === 'function') sync.on('events-applied', onEventsApplied);
+
+  return () => {
+    if (closed) return;
+    closed = true;
+    try {
+      if (typeof eventLog.off === 'function') eventLog.off('event-appended', onAppended);
+      else if (typeof eventLog.removeListener === 'function') eventLog.removeListener('event-appended', onAppended);
+    } catch {
+      // ignore
+    }
+    try {
+      removeApplied();
+    } catch {
+      // ignore
+    }
+  };
+}

package/src/home.mjs

@@ -0,0 +1,16 @@
+// 统一家目录（唯一真源，F-INST-1）
+//
+// `MEBULAR_HOME` 覆盖，缺省 `~/.mebular`。CLI（bin/mebular.mjs）与配置解析
+// （src/config.mjs）**必须共用本模块**，避免「bin 用 <cwd>/.mebular、config 用
+// ~/.mebular」的分裂（会导致 store lock 与 service.heartbeat 各写一边）。
+//
+// 本模块刻意不引入任何重依赖（不 import @mebular/core），以便 bin 在任意
+// 子命令（含 --version）下都能轻量加载。
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** 统一家目录：`MEBULAR_HOME` 覆盖，缺省 `~/.mebular`。 */
+export function homeDir() {
+  return process.env.MEBULAR_HOME ?? join(homedir(), '.mebular');
+}

package/src/jointoken.mjs

@@ -0,0 +1,31 @@
+// W2/F-UNI：守护侧加入令牌与 join 服务的**薄 re-export**。
+//
+// 唯一实现在 `@mebular/fleet`（`packages/fleet/src/jointoken.ts`）：令牌原语（canonical/encode/decode/verify/
+// build）· nonce 状态 · inviter join 服务（`startJoinService`）· joiner 流程（`joinWithToken`）。
+// 本文件**不定义任何业务逻辑**，只做名字映射，避免历史上「两份实现」再次漂移。
+//
+// 防漂移断言见 `npm run check:surface-parity`：全仓 `encodeJoinToken|verifyJoinToken` 的
+// 定义数必须为 1（多一处即红）。
+//
+// 令牌签发前查 `app.getBlockedDevices()`（被移出设备拒签），见 `serve.mjs` 的
+// `/admin/api/invite`；兑换侧不耦合，保持令牌与设备移出分离。
+export {
+  canonicalJoinTokenData,
+  decodeJoinToken,
+  encodeJoinToken,
+  buildJoinToken,
+  describeJoinToken,
+  verifyJoinToken,
+  collectReachableEndpoints,
+  collectRelaySeeds,
+  isLoopbackAddress,
+  chainFingerprint,
+  joinNonceStatePath,
+  readJoinNonceState,
+  writeJoinNonceState,
+  activateJoinInvite,
+  requestJoin,
+  joinWithToken,
+  persistInviterHints,
+  startJoinService as createJoinServer,
+} from '../../fleet/dist/index.js';

package/src/lan-host.mjs

@@ -0,0 +1,36 @@
+// F-C6：加入令牌里的 endpoint 必须是**新设备可直达**的地址（跨机时回环地址必然失败）。
+// bind 为通配（0.0.0.0 / :: / 空）时选一个可对外通告的 LAN IPv4（无则回环，并由上层给出 warning）。
+import { networkInterfaces } from 'node:os';
+
+const WILDCARD_BINDS = new Set(['0.0.0.0', '::', '[::]', '*', '']);
+
+/** 选一个可对外通告的 LAN IPv4（无则 127.0.0.1）。 */
+export function pickLanHost() {
+  const ifaces = networkInterfaces();
+  for (const list of Object.values(ifaces)) {
+    for (const info of list ?? []) {
+      if (info.family === 'IPv4' && !info.internal) return info.address;
+    }
+  }
+  return '127.0.0.1';
+}
+
+/** bind 地址 → 对外通告地址（通配时取 LAN IPv4）。 */
+export function advertiseHost(bind) {
+  const value = typeof bind === 'string' ? bind : '';
+  return WILDCARD_BINDS.has(value) ? pickLanHost() : value;
+}
+
+/** 是否回环/本机地址（用于提示「新设备不可达」）。 */
+export function isLoopbackHost(host) {
+  return host === '127.0.0.1' || host === 'localhost' || host === '::1' || host === '::ffff:127.0.0.1';
+}
+
+/** 解析 endpoint 的 hostname；非法 URL 返回 null。 */
+export function endpointHostname(endpoint) {
+  try {
+    return new URL(endpoint).hostname;
+  } catch {
+    return null;
+  }
+}