@mebular/fleet 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,40 @@
+// @mebular/fleet —— 跨设备多 Agent 协作（任务=记忆）的公共入口。
+//
+// 边界（红线，见 DESIGN.md 与仓库 SEALING.md）：
+// - 只消费 `@mebular/core` 的**公共 API**（`import { ... } from '@mebular/core'`），
+//   不得 `import` core 的内部路径（`src/**`）；
+// - core 不得反向依赖本包（`tests/fleet/boundary.test.ts` 强制）；
+// - 墙钟（`expiresAt`）不进一致性判定。
+export * from './protocol/envelope.js';
+export * from './protocol/events.js';
+export * from './model.js';
+export * from './quota.js';
+export * from './agentdir.js';
+export * from './surface.js';
+export * from './config.js';
+export * from './onboard.js';
+export * from './security.js';
+export * from './quickstart.js';
+export * from './jointoken.js';
+export * from './qr.js';
+export * from './join.js';
+export * from './collab/dag.js';
+export * from './collab/tree.js';
+export * from './collab/negotiation.js';
+export * from './collab/chatter.js';
+export * from './transport/types.js';
+export * from './transport/spool.js';
+export * from './transport/null.js';
+export * from './store/file-store.js';
+export * from './store/mebular-store.js';
+export * from './store/message-store.js';
+export * from './store/daemon-store.js';
+export * from './runtime/planner.js';
+export * from './runtime/fairness.js';
+export * from './runtime/executor.js';
+export * from './runtime/agent.js';
+export * from './runtime/openchamber.js';
+export * from './runtime/openchamber-http.js';
+export * from './runtime/node.js';
+export * from './runtime/worker.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,EAAE;AACF,qCAAqC;AACrC,4EAA4E;AAC5E,sCAAsC;AACtC,sDAAsD;AACtD,4BAA4B;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC"}

package/dist/join.d.ts

@@ -0,0 +1,50 @@
+import { type FleetAgentConfig } from './config.js';
+import type { ServiceInstaller } from './quickstart.js';
+export interface JoinWithTokenInput {
+    dir: string;
+    token: string;
+    device: string;
+    namespace?: string;
+    listen?: string;
+    agents: FleetAgentConfig[];
+    timeoutMs?: number;
+    /** W2：同时配置统一守护（delegated 身份 + fleet daemon 客户端 + 令牌） */
+    daemon?: boolean;
+    daemonPort?: number;
+    joinPort?: number;
+    installDaemon?: ServiceInstaller;
+}
+export interface JoinWithTokenResult {
+    /** C2：写入地址簿的 hint 条数（0 = 旧令牌无 hints） */
+    hinted: number;
+    device: string;
+    dir: string;
+    peer: string;
+    namespace: string;
+    fingerprint: string;
+    alreadyJoined: boolean;
+    inviterDeviceId: string;
+    next: string[];
+    /** W2：统一守护配置结果 */
+    daemon?: {
+        endpoint: string;
+        installed: boolean;
+        note?: string;
+    };
+    /** W2：Agent MCP 配置片段 */
+    agentMcp: Record<string, unknown>;
+}
+/**
+ * C2：把邀请方 hints 落盘到 `<dir>/net/peers.json`（0600）。
+ * 同时写 **deviceId 键**（可读）与 **peerId 键**（由 inviterPublicKey 派生，首次拨号即可命中）。
+ * 返回写入条数；无 hints（旧令牌）→ 0。任何失败都不应让 join 失败。
+ */
+export declare function persistInviterHints(dir: string, token: {
+    inviterDeviceId: string;
+    inviterPublicKey: string;
+    endpoints?: string[];
+    relaySeeds?: string[];
+}): Promise<number>;
+/** B：用令牌加入（**不持有主密钥私钥**）。 */
+export declare function joinWithToken(input: JoinWithTokenInput): Promise<JoinWithTokenResult>;
+//# sourceMappingURL=join.d.ts.map

package/dist/join.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"join.d.ts","sourceRoot":"","sources":["../src/join.ts"],"names":[],"mappings":"AAUA,OAAO,EAQL,KAAK,gBAAgB,EAEtB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAKxD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,gBAAgB,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB;IAClC,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kBAAkB;IAClB,MAAM,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE;IAC5D,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBlB;AAED,6BAA6B;AAC7B,wBAAsB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA2H3F"}

package/dist/join.js

@@ -0,0 +1,167 @@
+// 信任模型 v2（T2）：B 持**加入令牌**加入（不复制主密钥）。
+//
+// 流程：生成设备密钥 → 向 inviter 的 join 端点请求**委派证书**（令牌验签/TTL/一次性）→
+// 落盘身份文件（含证书链，**无主私钥**）→ 写**主公钥**文件 → onboard（登记 inviter 地址）→ 声明成员。
+// 主密钥私钥全程不出现；inviter 可为**任意**在册设备。
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { constants } from 'node:fs';
+import { Mebular, IdentityManager, bytesToHex, hexToBytes, EndpointBook, FileEndpointStore, derivePeerIdHex, RELAY_SEEDS_KEY } from '@mebular/core';
+import { fleetConfigPath, fleetMasterKeyPath, fleetStoragePath, loadFleetConfig, masterKeyFingerprint, readMasterKeyFile, writeMasterKeyFile, } from './config.js';
+import { offlineMebularOptions, onboardDevice } from './onboard.js';
+import { agentMcpConfig, configureDaemonHome } from './quickstart.js';
+import { decodeJoinToken, requestJoin } from './jointoken.js';
+/**
+ * C2：把邀请方 hints 落盘到 `<dir>/net/peers.json`（0600）。
+ * 同时写 **deviceId 键**（可读）与 **peerId 键**（由 inviterPublicKey 派生，首次拨号即可命中）。
+ * 返回写入条数；无 hints（旧令牌）→ 0。任何失败都不应让 join 失败。
+ */
+export async function persistInviterHints(dir, token) {
+    try {
+        const hints = Array.isArray(token.endpoints) ? token.endpoints.filter((a) => typeof a === 'string' && a.length > 0) : [];
+        const seeds = Array.isArray(token.relaySeeds) ? token.relaySeeds.filter((a) => typeof a === 'string' && a.length > 0) : [];
+        if (hints.length === 0 && seeds.length === 0)
+            return 0;
+        const book = new EndpointBook({ store: new FileEndpointStore(join(dir, 'net', 'peers.json')) });
+        await book.load();
+        let count = 0;
+        const keys = [token.inviterDeviceId];
+        try {
+            keys.push(derivePeerIdHex(hexToBytes(token.inviterPublicKey)));
+        }
+        catch {
+            // 公钥非法：只写 deviceId 键
+        }
+        for (const key of keys) {
+            if (hints.length > 0)
+                count += await book.upsert(key, hints, 'paired');
+        }
+        // relay seeds 存保留键（不是对端地址；app 启动时并入 libp2p.relayServers）
+        if (seeds.length > 0)
+            await book.upsert(RELAY_SEEDS_KEY, seeds, 'config');
+        return count;
+    }
+    catch {
+        return 0;
+    }
+}
+/** B：用令牌加入（**不持有主密钥私钥**）。 */
+export async function joinWithToken(input) {
+    const token = decodeJoinToken(input.token);
+    const namespace = input.namespace ?? token.namespace;
+    const listen = input.listen ?? '/ip4/0.0.0.0/tcp/4001';
+    const alreadyJoined = await exists(fleetConfigPath(input.dir));
+    if (alreadyJoined) {
+        const existing = await loadFleetConfig(fleetConfigPath(input.dir));
+        if (existing.device !== input.device) {
+            throw new Error(`目录已被设备 ${existing.device} 占用（--dir ${input.dir}）；换目录或先停用。`);
+        }
+    }
+    await mkdir(input.dir, { recursive: true });
+    const storagePath = fleetStoragePath(input.dir);
+    const keyPath = fleetMasterKeyPath(input.dir);
+    let peerAddr;
+    let securityApproval;
+    if (!alreadyJoined) {
+        const im = new IdentityManager();
+        const deviceKey = await im.generateDeviceKey(input.device, input.device);
+        const issued = await requestJoin({
+            endpoint: token.endpoint,
+            token: input.token,
+            deviceId: input.device,
+            devicePublicKeyHex: bytesToHex(deviceKey.publicKey),
+            ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+        });
+        peerAddr = issued.inviterMultiaddrs[0];
+        securityApproval = issued.securityApproval;
+        const privateKeyPkcs8 = await IdentityManager.exportPrivateKey(deviceKey.privateKey);
+        const record = {
+            deviceId: input.device,
+            deviceName: input.device,
+            publicKeyHex: bytesToHex(deviceKey.publicKey),
+            certificate: issued.certificate,
+            certificateChain: issued.chain,
+            createdAt: Date.now(),
+            privateKeyPkcs8,
+        };
+        await writeFile(`${storagePath}.identity.json`, JSON.stringify(record, null, 2), { mode: 0o600 });
+        const publicOnly = { userMasterKey: hexToBytes(token.masterPublicKey) };
+        await writeMasterKeyFile(keyPath, publicOnly);
+    }
+    // C2：把邀请方 hints（token.endpoints）写入本机地址簿 <dir>/net/peers.json（0600）
+    // 机制在 core（EndpointBook/FileEndpointStore），路径由 app 决定；不改变任何授权。
+    const hinted = await persistInviterHints(input.dir, token);
+    const onboard = await onboardDevice({
+        dir: input.dir,
+        device: input.device,
+        namespace,
+        listen,
+        agents: input.agents,
+        peerDevice: token.inviterDeviceId,
+        ...(peerAddr !== undefined ? { peerAddr } : {}),
+    });
+    const config = onboard.config;
+    const encryption = await readMasterKeyFile(config.masterKeyFile);
+    const mebular = new Mebular(offlineMebularOptions(config, encryption));
+    await mebular.initialize();
+    try {
+        await mebular.declareNamespaceSubscription({
+            namespace,
+            active: true,
+            note: 'join-token self',
+            ...(securityApproval !== undefined
+                ? {
+                    initiator: securityApproval.initiator,
+                    nonce: securityApproval.nonce,
+                    ...(securityApproval.cosign !== undefined ? { cosign: securityApproval.cosign } : {}),
+                }
+                : {}),
+        });
+    }
+    finally {
+        await mebular.shutdown();
+    }
+    // W2 B2：delegated 守护 home（无主私钥）+ fleet daemon 客户端 + （可选）mebular-serve
+    let daemonInfo = null;
+    if (input.daemon === true) {
+        const publicKeyFile = join(input.dir, 'user-master-key.json');
+        await writeFile(publicKeyFile, JSON.stringify({ publicKey: Buffer.from(encryption.userMasterKey).toString('base64') }, null, 2), { mode: 0o600 });
+        const peer = peerAddr ?? config.peers[0]?.addr;
+        const peers = peer !== undefined ? [{ device: token.inviterDeviceId, addr: peer }] : [{ device: token.inviterDeviceId }];
+        const { endpoint } = await configureDaemonHome(input.dir, config, namespace, input.joinPort ?? 4002, input.daemonPort ?? 7331, { userMasterPublicKeyFile: publicKeyFile }, peers);
+        let installed = false;
+        let note;
+        if (input.installDaemon !== undefined) {
+            const outcome = await input.installDaemon(input.dir);
+            installed = outcome.installed;
+            note = outcome.note;
+        }
+        daemonInfo = { endpoint, installed, ...(note !== undefined ? { note } : {}) };
+    }
+    return {
+        hinted,
+        device: config.device,
+        dir: config.dir,
+        peer: token.inviterDeviceId,
+        namespace,
+        fingerprint: masterKeyFingerprint(encryption.userMasterKey),
+        alreadyJoined,
+        inviterDeviceId: token.inviterDeviceId,
+        next: [
+            '本机已声明订阅；对端同步后即可互通（订阅零门槛，无需批准）',
+            ...(hinted > 0 ? [`已写入邀请方地址 hints（${hinted} 条）：本机可在无 --addr 时自动选路连通`] : ['令牌未携带地址 hints（旧令牌）：首次连接仍需显式 --addr']),
+        ],
+        ...(daemonInfo !== null ? { daemon: daemonInfo } : {}),
+        agentMcp: agentMcpConfig(),
+    };
+}
+async function exists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=join.js.map

package/dist/join.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"join.js","sourceRoot":"","sources":["../src/join.ts"],"names":[],"mappings":"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"}

package/dist/jointoken.d.ts

@@ -0,0 +1,144 @@
+import { type Server } from 'node:http';
+import { type DeviceCertificate, type Mebular } from '@mebular/core';
+/** 令牌（inviter 设备私钥签名；不含主密钥）。 */
+export interface JoinToken {
+    v: 1;
+    kind: 'mebular-fleet-join-token';
+    inviterDeviceId: string;
+    /** inviter 设备公钥（hex） */
+    inviterPublicKey: string;
+    /** inviter 的证书链（叶→根），供请求方与验签方锚定到主密钥 */
+    inviterChain: DeviceCertificate[];
+    /** 用户主公钥（hex；公开信息，非秘密） */
+    masterPublicKey: string;
+    namespace: string;
+    nonce: string;
+    issuedAt: number;
+    expiresAt: number;
+    /** join 服务端点（http(s)://host:port） */
+    endpoint: string;
+    /**
+     * C2：邀请方可达的 P2P 地址（multiaddr，新设备 join 后写入地址簿）。
+     * 旧令牌可缺省；缺省时 join 侧不写 hints（行为与历史一致）。
+     */
+    endpoints?: string[];
+    /** C2：邀请方建议的 relay seeds（可选） */
+    relaySeeds?: string[];
+    /**
+     * high 档首次订阅的会签证明（批准记录 + cosign）。新设备把它写进自己的
+     * `namespace_subscription`，证明随记录走、全网验收。
+     */
+    securityApproval?: {
+        approvalId: string;
+        nonce: string;
+        initiator?: string;
+        cosign?: Record<string, unknown>;
+    };
+    /** C2：邀请方是否有公网可达地址（诊断提示用；仅信息，不参与授权） */
+    pubReachable?: boolean;
+    /** inviter 设备私钥对 canonical 数据的签名（base64） */
+    signature: string;
+}
+/** 令牌规范化签名内容（固定键序，排除 signature）。 */
+export declare function canonicalJoinTokenData(token: Omit<JoinToken, 'signature'> & {
+    signature?: string;
+}): string;
+export declare function encodeJoinToken(token: JoinToken): string;
+export declare function decodeJoinToken(text: string): JoinToken;
+/** 脱敏描述：**不含签名**，供日志/报告。 */
+export declare function describeJoinToken(token: JoinToken): Record<string, unknown>;
+/** 令牌 nonce 状态文件（本地；0600）。 */
+export interface JoinNonceState {
+    used: string[];
+    revoked: string[];
+    /**
+     * 当前唯一有效的邀请 nonce（旧状态文件可能没有）。
+     * 生成新令牌时把上一个 active 放入 revoked → 重新生成即让旧令牌失效。
+     */
+    active?: string;
+}
+export declare function joinNonceStatePath(storagePath: string): string;
+export declare function readJoinNonceState(storagePath: string): Promise<JoinNonceState>;
+export declare function writeJoinNonceState(storagePath: string, state: JoinNonceState): Promise<void>;
+/**
+ * 激活新邀请 nonce：把上一个 active 放入 revoked，再落盘新 active。
+ * 生成与兑换共用同一把锁（同进程内存队列 + <state>.lock 跨进程），避免并发丢更新。
+ */
+export declare function activateJoinInvite(storagePath: string, nonce: string): Promise<{
+    revoked: string | null;
+}>;
+/** 签发令牌（inviter 设备私钥）。 */
+export declare function buildJoinToken(input: {
+    mebular: Mebular;
+    deviceId: string;
+    namespace: string;
+    endpoint: string;
+    ttlMs?: number;
+    now?: number;
+    nonce?: string;
+    /** C2：邀请方可达 P2P 地址（缺省自动从本机节点收集） */
+    endpoints?: string[];
+    relaySeeds?: string[];
+    pubReachable?: boolean;
+    /** high 档首次订阅会签（由控制台/CLI 的批准流程带入） */
+    securityApproval?: JoinToken['securityApproval'];
+}): Promise<JoinToken>;
+/** C2：本机可达 P2P 地址（节点监听 + /p2p/<peerId>；无节点则空）。 */
+export declare function collectReachableEndpoints(mebular: Mebular): string[];
+/**
+ * C2：可共享的 relay seeds（供新设备在无法直连时中转）。
+ * app 已把 `network.relaySeeds` 并入 `network.libp2p.relayServers`，此处经公开 getter 读取。
+ */
+export declare function collectRelaySeeds(mebular: Mebular): string[];
+/** 地址是否为回环（用于 pubReachable 提示；判断失败按回环处理）。 */
+export declare function isLoopbackAddress(address: string): boolean;
+export interface VerifyJoinTokenOptions {
+    now?: number;
+    used?: readonly string[];
+    revoked?: readonly string[];
+    /** 仅接受该 inviter（join 服务端 = 本机时使用） */
+    expectedInviter?: string;
+}
+export type JoinTokenFailure = 'signature' | 'chain' | 'inviter' | 'expired' | 'used' | 'revoked';
+/** 校验令牌：签名 → 链锚定主密钥 → inviter 匹配 → TTL → 一次性 → 撕票。 */
+export declare function verifyJoinToken(token: JoinToken, opts?: VerifyJoinTokenOptions): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: JoinTokenFailure;
+}>;
+/** inviter 证书链的指纹（诊断/去重；非密钥材料）。 */
+export declare function chainFingerprint(chain: readonly DeviceCertificate[]): string;
+export interface JoinServiceOptions {
+    mebular: Mebular;
+    deviceId: string;
+    storagePath: string;
+    /** 绑定地址（默认 0.0.0.0）；令牌是 bearer，建议 LAN + 短 TTL */
+    bind?: string;
+    /** 端口（默认 0 = 随机；quickstart 默认 4002） */
+    port: number;
+    log?: (msg: string) => void;
+}
+export interface JoinService {
+    server: Server;
+    port: number;
+    close: () => Promise<void>;
+}
+export declare function startJoinService(opts: JoinServiceOptions): Promise<JoinService>;
+export interface JoinRequestResult {
+    certificate: DeviceCertificate;
+    chain: DeviceCertificate[];
+    namespace: string;
+    inviterDeviceId: string;
+    inviterMultiaddrs: string[];
+    securityApproval?: JoinToken['securityApproval'];
+}
+/** B 持令牌向 inviter 的 join 端点请求委派证书（纯 HTTP；令牌是 bearer）。 */
+export declare function requestJoin(input: {
+    endpoint: string;
+    token: string;
+    deviceId: string;
+    devicePublicKeyHex: string;
+    timeoutMs?: number;
+}): Promise<JoinRequestResult>;
+//# sourceMappingURL=jointoken.d.ts.map

package/dist/jointoken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jointoken.d.ts","sourceRoot":"","sources":["../src/jointoken.ts"],"names":[],"mappings":"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"}