@agentunion/fastaun 0.2.13

package/dist/secret-store/file-store.js

@@ -0,0 +1,124 @@
+/**
+ * 基于文件的 SecretStore（AES-256-GCM 加密）
+ *
+ * 密钥派生：
+ *   - 传入 encryptionSeed → 从 seed 字符串派生
+ *   - 未传 → 从 {root}/.seed 文件派生（首次自动生成）
+ *
+ * 与 Python SDK 的 FileSecretStore 完全对齐。
+ */
+import { createCipheriv, createDecipheriv, createHmac, pbkdf2Sync, randomBytes, } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, } from 'node:fs';
+import { join } from 'node:path';
+function decodeSecretPart(value) {
+    if (/^[0-9a-fA-F]+$/.test(value) && value.length % 2 === 0) {
+        return Buffer.from(value, 'hex');
+    }
+    return Buffer.from(value, 'base64');
+}
+export class FileSecretStore {
+    _root;
+    _masterKey;
+    constructor(root, encryptionSeed, sqliteBackup) {
+        this._root = root;
+        mkdirSync(this._root, { recursive: true });
+        let seedBytes;
+        if (encryptionSeed) {
+            seedBytes = Buffer.from(encryptionSeed, 'utf-8');
+        }
+        else {
+            seedBytes = this._loadOrCreateSeed(sqliteBackup);
+        }
+        // PBKDF2 派生主密钥，与 Python SDK 参数完全一致
+        this._masterKey = pbkdf2Sync(seedBytes, 'aun_file_secret_store_v1', 100_000, 32, 'sha256');
+    }
+    protect(scope, name, plaintext) {
+        const key = this._deriveKey(scope, name);
+        const nonce = randomBytes(12);
+        const cipher = createCipheriv('aes-256-gcm', key, nonce);
+        const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        return {
+            scheme: 'file_aes',
+            name,
+            persisted: true,
+            nonce: nonce.toString('base64'),
+            ciphertext: encrypted.toString('base64'),
+            tag: tag.toString('base64'),
+        };
+    }
+    reveal(scope, name, record) {
+        if (record.scheme !== 'file_aes')
+            return null;
+        if (String(record.name ?? '') !== name)
+            return null;
+        const nonceB64 = String(record.nonce ?? '');
+        const ctB64 = String(record.ciphertext ?? '');
+        const tagB64 = String(record.tag ?? '');
+        if (!nonceB64 || !ctB64 || !tagB64)
+            return null;
+        const key = this._deriveKey(scope, name);
+        try {
+            const decipher = createDecipheriv('aes-256-gcm', key, decodeSecretPart(nonceB64));
+            decipher.setAuthTag(decodeSecretPart(tagB64));
+            const decrypted = Buffer.concat([
+                decipher.update(decodeSecretPart(ctB64)),
+                decipher.final(),
+            ]);
+            return decrypted;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** 使用 HMAC-SHA256 从主密钥派生子密钥 */
+    _deriveKey(scope, name) {
+        return createHmac('sha256', this._masterKey)
+            .update(`aun:${scope}:${name}\x01`)
+            .digest();
+    }
+    /** 三级恢复：文件 → SQLite → 新建，双写确保一致 */
+    _loadOrCreateSeed(backup) {
+        const seedPath = join(this._root, '.seed');
+        let source = '';
+        // 1. 先读文件
+        if (existsSync(seedPath)) {
+            const seed = readFileSync(seedPath);
+            source = 'file';
+            // 双写：确保 SQLite 也有
+            if (backup)
+                backup.backupSeed(seed);
+            return seed;
+        }
+        // 2. 文件不存在 → 读 SQLite
+        if (backup) {
+            const restored = backup.restoreSeed();
+            if (restored && restored.length > 0) {
+                source = 'sqlite';
+                console.log('从 SQLite 恢复 .seed 文件');
+                writeFileSync(seedPath, restored);
+                if (process.platform !== 'win32') {
+                    try {
+                        chmodSync(seedPath, 0o600);
+                    }
+                    catch { /* ignore */ }
+                }
+                return restored;
+            }
+        }
+        // 3. 都没有 → 生成新 seed
+        const seed = randomBytes(32);
+        writeFileSync(seedPath, seed);
+        if (process.platform !== 'win32') {
+            try {
+                chmodSync(seedPath, 0o600);
+            }
+            catch { /* ignore */ }
+        }
+        // 双写：备份到 SQLite
+        if (backup)
+            backup.backupSeed(seed);
+        return seed;
+    }
+}
+//# sourceMappingURL=file-store.js.map

package/dist/secret-store/file-store.js.map

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

package/dist/secret-store/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SecretStore 接口定义 + 默认工厂函数
+ *
+ * 与 Python SDK 的 SecretStore Protocol 完全对齐。
+ */
+import type { SecretRecord } from '../types.js';
+/** 密钥保护/恢复接口 */
+export interface SecretStore {
+    /**
+     * 保护明文数据，返回加密记录（可持久化）。
+     */
+    protect(scope: string, name: string, plaintext: Buffer): SecretRecord;
+    /**
+     * 从加密记录恢复明文数据。
+     * 解密失败或格式不匹配返回 null。
+     */
+    reveal(scope: string, name: string, record: SecretRecord): Buffer | null;
+}
+/**
+ * 创建默认的 SecretStore 实例。
+ *
+ * TypeScript SDK 统一使用 FileSecretStore（AES-256-GCM），
+ * 不区分平台原生方案（与 Python SDK v0.2.0+ 对齐：写入统一用 file_aes）。
+ */
+export declare function createDefaultSecretStore(root?: string, encryptionSeed?: string, sqliteBackup?: {
+    backupSeed(seed: Buffer): void;
+    restoreSeed(): Buffer | null;
+}): SecretStore;

package/dist/secret-store/index.js

@@ -0,0 +1,19 @@
+/**
+ * SecretStore 接口定义 + 默认工厂函数
+ *
+ * 与 Python SDK 的 SecretStore Protocol 完全对齐。
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { FileSecretStore } from './file-store.js';
+/**
+ * 创建默认的 SecretStore 实例。
+ *
+ * TypeScript SDK 统一使用 FileSecretStore（AES-256-GCM），
+ * 不区分平台原生方案（与 Python SDK v0.2.0+ 对齐：写入统一用 file_aes）。
+ */
+export function createDefaultSecretStore(root, encryptionSeed, sqliteBackup) {
+    const storeRoot = root ?? join(homedir(), '.aun');
+    return new FileSecretStore(storeRoot, encryptionSeed, sqliteBackup);
+}
+//# sourceMappingURL=index.js.map

package/dist/secret-store/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/secret-store/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAiBlD;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CACtC,IAAa,EACb,cAAuB,EACvB,YAA+E;IAE/E,MAAM,SAAS,GAAG,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;IAClD,OAAO,IAAI,eAAe,CAAC,SAAS,EAAE,cAAc,EAAE,YAAY,CAAC,CAAC;AACtE,CAAC"}

package/dist/seq-tracker.d.ts

@@ -0,0 +1,29 @@
+import type { JsonObject } from './types.js';
+export declare class SeqTracker {
+    private _trackers;
+    private _get;
+    getContiguousSeq(ns: string): number;
+    getMaxSeenSeq(ns: string): number;
+    /** S2: 从持久化（keystore 最近 ack seq）恢复 baseline，
+     *  以便首条 push 消息能构造 [baseline+1, seq-1] 的历史 gap。
+     *  必须在收到首条消息前调用。 */
+    setBaseline(ns: string, baselineSeq: number): void;
+    /** 记录收到的 seq，返回 true 表示需要 pull 补齐空洞 */
+    onMessageSeq(ns: string, seq: number): boolean;
+    /** pull 返回后更新 tracker 状态 */
+    onPullResult(ns: string, messages: JsonObject[]): void;
+    private _tryAdvance;
+    private _shouldProbe;
+    /** S2: 服务端明确告知某区间无消息（tombstone）→ 将 gap 标记为 resolved */
+    markGapResolvedByTombstone(ns: string, gapStart: number, gapEnd: number): void;
+    /** 强制跳过不连续区间，将 contiguousSeq 拨到指定位置。
+     *  当服务端返回 server_ack_seq 且本地 contiguousSeq 落后时调用，
+     *  跳过 [contiguousSeq, server_ack_seq) 这段不连续区间。 */
+    forceContiguousSeq(ns: string, seq: number): void;
+    /** 删除指定命名空间的所有跟踪状态（群组解散时使用） */
+    removeNamespace(ns: string): void;
+    /** 导出各命名空间的 contiguousSeq，用于持久化 */
+    exportState(): Record<string, number>;
+    /** 从持久化数据恢复各命名空间的 contiguousSeq */
+    restoreState(state: Record<string, number>): void;
+}

package/dist/seq-tracker.js

@@ -0,0 +1,221 @@
+// ── 消息序列号跟踪与空洞检测 ──────────────────────────────
+//
+// SeqTracker 维护按命名空间（group_id 或 conversation_id）分组的消息序列连续性。
+// 用法：群消息 key = "group:" + groupId，P2P 消息 key = "p2p:" + myAid
+const BACKOFF_INTERVALS = [1, 3, 10, 30, 60]; // 秒
+// S2: 删除"probeCount >= 5 强制 resolved"的硬限制；仅用作 backoff 索引上限。
+// resolved 只应由"完整补齐"或服务端明确 tombstone 驱动。
+const MAX_PROBE_COUNT = 5;
+function gapKey(start, end) {
+    return `${start}:${end}`;
+}
+/** 统一使用 Date.now() 返回绝对时间戳（毫秒），
+ *  避免 performance.now()（相对时间）与 Date.now()（绝对时间）混用导致语义不一致。 */
+function nowMs() {
+    return Date.now();
+}
+export class SeqTracker {
+    _trackers = new Map();
+    _get(ns) {
+        let t = this._trackers.get(ns);
+        if (!t) {
+            t = { contiguousSeq: 0, maxSeenSeq: 0, receivedSeqs: new Set(), pendingGaps: new Map() };
+            this._trackers.set(ns, t);
+        }
+        return t;
+    }
+    getContiguousSeq(ns) {
+        return this._get(ns).contiguousSeq;
+    }
+    getMaxSeenSeq(ns) {
+        return this._get(ns).maxSeenSeq;
+    }
+    /** S2: 从持久化（keystore 最近 ack seq）恢复 baseline，
+     *  以便首条 push 消息能构造 [baseline+1, seq-1] 的历史 gap。
+     *  必须在收到首条消息前调用。 */
+    setBaseline(ns, baselineSeq) {
+        if (baselineSeq <= 0)
+            return;
+        const t = this._get(ns);
+        if (t.contiguousSeq === 0 && t.maxSeenSeq === 0) {
+            t.contiguousSeq = baselineSeq;
+            t.maxSeenSeq = baselineSeq;
+        }
+    }
+    /** 记录收到的 seq，返回 true 表示需要 pull 补齐空洞 */
+    onMessageSeq(ns, seq) {
+        if (seq <= 0)
+            return false;
+        const t = this._get(ns);
+        if (seq <= t.contiguousSeq)
+            return false;
+        // S2: 首次收到消息时，必须构造 [1, seq-1] 的历史 gap 来触发补洞，
+        // 而不是把当前 seq 当成 baseline 丢弃历史。
+        if (t.contiguousSeq === 0 && t.maxSeenSeq === 0) {
+            if (seq === 1) {
+                t.contiguousSeq = seq;
+                t.maxSeenSeq = seq;
+                return false;
+            }
+            t.maxSeenSeq = seq;
+            t.receivedSeqs.add(seq);
+            const histKey = gapKey(1, seq - 1);
+            t.pendingGaps.set(histKey, {
+                gapStart: 1, gapEnd: seq - 1,
+                lastProbeAt: 0, probeCount: 0, resolved: false,
+            });
+            return true;
+        }
+        t.receivedSeqs.add(seq);
+        t.maxSeenSeq = Math.max(t.maxSeenSeq, seq);
+        if (seq === t.contiguousSeq + 1) {
+            t.contiguousSeq = seq;
+            t.receivedSeqs.delete(seq);
+            this._tryAdvance(t);
+            return false;
+        }
+        // 空洞
+        const gs = t.contiguousSeq + 1;
+        const ge = seq - 1;
+        const key = gapKey(gs, ge);
+        const existing = t.pendingGaps.get(key);
+        if (existing) {
+            if (existing.resolved) {
+                t.contiguousSeq = Math.max(t.contiguousSeq, existing.gapEnd);
+                t.pendingGaps.delete(key);
+                this._tryAdvance(t);
+                return false;
+            }
+            if (!this._shouldProbe(existing))
+                return false;
+        }
+        else {
+            t.pendingGaps.set(key, {
+                gapStart: gs, gapEnd: ge,
+                lastProbeAt: 0, probeCount: 0, resolved: false,
+            });
+        }
+        return true;
+    }
+    /** pull 返回后更新 tracker 状态 */
+    onPullResult(ns, messages) {
+        const t = this._get(ns);
+        const pulledSeqs = new Set();
+        for (const m of messages) {
+            const s = m.seq;
+            if (typeof s === 'number' && s > 0)
+                pulledSeqs.add(s);
+        }
+        const now = nowMs();
+        for (const [key, probe] of t.pendingGaps) {
+            if (probe.resolved)
+                continue;
+            probe.lastProbeAt = now;
+            probe.probeCount += 1;
+            let allCovered = true;
+            let anyHit = false;
+            for (let s = probe.gapStart; s <= probe.gapEnd; s++) {
+                if (pulledSeqs.has(s)) {
+                    anyHit = true;
+                }
+                else {
+                    allCovered = false;
+                }
+            }
+            if (allCovered) {
+                probe.resolved = true;
+            }
+            // S2: 不再因 probeCount >= 3 自动 resolved；仅由完整补齐 / 服务端 tombstone 驱动。
+        }
+        for (const s of pulledSeqs) {
+            t.receivedSeqs.add(s);
+        }
+        if (pulledSeqs.size) {
+            t.maxSeenSeq = Math.max(t.maxSeenSeq, Math.max(...pulledSeqs));
+        }
+        this._tryAdvance(t);
+    }
+    _tryAdvance(t) {
+        // 先清理已解决的空洞
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const [key, probe] of t.pendingGaps) {
+                if (probe.resolved && probe.gapStart <= t.contiguousSeq + 1) {
+                    t.contiguousSeq = Math.max(t.contiguousSeq, probe.gapEnd);
+                    t.pendingGaps.delete(key);
+                    changed = true;
+                }
+            }
+        }
+        // 从 contiguous+1 逐个推进（检查 receivedSeqs）
+        while (t.receivedSeqs.has(t.contiguousSeq + 1)) {
+            t.contiguousSeq += 1;
+            t.receivedSeqs.delete(t.contiguousSeq);
+        }
+    }
+    _shouldProbe(probe) {
+        // S2: 不再以 probeCount >= MAX_PROBE_COUNT 为由将 probe 置为 resolved。
+        // 超出 backoff 表长度后按最长间隔持续重试。
+        const now = nowMs();
+        const idx = Math.min(probe.probeCount, BACKOFF_INTERVALS.length - 1);
+        const interval = BACKOFF_INTERVALS[idx] * 1000; // 秒转毫秒
+        return now - probe.lastProbeAt >= interval;
+    }
+    /** S2: 服务端明确告知某区间无消息（tombstone）→ 将 gap 标记为 resolved */
+    markGapResolvedByTombstone(ns, gapStart, gapEnd) {
+        const t = this._get(ns);
+        for (const [, probe] of t.pendingGaps) {
+            if (probe.gapStart >= gapStart && probe.gapEnd <= gapEnd) {
+                probe.resolved = true;
+            }
+        }
+        this._tryAdvance(t);
+    }
+    /** 强制跳过不连续区间，将 contiguousSeq 拨到指定位置。
+     *  当服务端返回 server_ack_seq 且本地 contiguousSeq 落后时调用，
+     *  跳过 [contiguousSeq, server_ack_seq) 这段不连续区间。 */
+    forceContiguousSeq(ns, seq) {
+        const t = this._get(ns);
+        if (seq > t.contiguousSeq) {
+            // 清除被跳过区间内的 pendingGaps
+            for (const [key, probe] of t.pendingGaps) {
+                if (probe.gapEnd <= seq) {
+                    t.pendingGaps.delete(key);
+                }
+            }
+            // 清除被跳过区间内的 receivedSeqs
+            for (const s of t.receivedSeqs) {
+                if (s <= seq)
+                    t.receivedSeqs.delete(s);
+            }
+            t.contiguousSeq = seq;
+            t.maxSeenSeq = Math.max(t.maxSeenSeq, seq);
+            this._tryAdvance(t);
+        }
+    }
+    /** 删除指定命名空间的所有跟踪状态（群组解散时使用） */
+    removeNamespace(ns) {
+        this._trackers.delete(ns);
+    }
+    /** 导出各命名空间的 contiguousSeq，用于持久化 */
+    exportState() {
+        const result = {};
+        for (const [ns, t] of this._trackers) {
+            if (t.contiguousSeq > 0)
+                result[ns] = t.contiguousSeq;
+        }
+        return result;
+    }
+    /** 从持久化数据恢复各命名空间的 contiguousSeq */
+    restoreState(state) {
+        for (const [ns, seq] of Object.entries(state)) {
+            if (typeof seq === 'number' && seq > 0) {
+                const t = this._get(ns);
+                t.contiguousSeq = Math.max(t.contiguousSeq, seq);
+                t.maxSeenSeq = Math.max(t.maxSeenSeq, seq);
+            }
+        }
+    }
+}
+//# sourceMappingURL=seq-tracker.js.map

package/dist/seq-tracker.js.map

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

package/dist/transport.d.ts

@@ -0,0 +1,60 @@
+/**
+ * RPC 传输层
+ *
+ * 基于 WebSocket（ws 包）的 JSON-RPC 2.0 传输层。
+ * 与 Python SDK 的 RPCTransport 完全对齐：
+ * - connect → 接收初始 challenge
+ * - call → 请求/响应匹配
+ * - 事件路由 → EventDispatcher
+ */
+import type { EventDispatcher } from './events.js';
+import { type RpcMessage, type RpcParams, type RpcResult } from './types.js';
+/** 断线回调，closeCode 为 WebSocket close code（1006 = 网络异常断开，其他 = 服务端主动关闭） */
+export type DisconnectCallback = (error: Error | null, closeCode?: number) => void | Promise<void>;
+/**
+ * WebSocket JSON-RPC 2.0 传输层
+ */
+export declare class RPCTransport {
+    private _dispatcher;
+    private _timeout;
+    private _onDisconnect;
+    private _verifySsl;
+    private _ws;
+    private _closed;
+    private _challenge;
+    private _pending;
+    private _idCounter;
+    constructor(opts: {
+        eventDispatcher: EventDispatcher;
+        timeout?: number;
+        onDisconnect?: DisconnectCallback | null;
+        verifySsl?: boolean;
+    });
+    /** 设置默认 RPC 超时（毫秒） */
+    setTimeout(timeout: number): void;
+    /** 获取上次连接的 challenge 消息 */
+    get challenge(): RpcMessage | null;
+    /**
+     * 连接到 Gateway WebSocket 端点。
+     * 返回初始 challenge 消息（如果有）。
+     */
+    connect(url: string): Promise<RpcMessage | null>;
+    /**
+     * 内部：使用已创建的 WebSocket 实例完成握手。
+     * 握手阶段（open 后到首条消息处理完毕）如果发生 error 或解析失败，
+     * 会回滚 _ws / _closed，确保不留下半连接状态。
+     */
+    private _connectWithWs;
+    /** 关闭连接 */
+    close(): Promise<void>;
+    /**
+     * 发送 JSON-RPC 2.0 请求并等待响应。
+     */
+    call(method: string, params?: RpcParams, timeout?: number): Promise<RpcResult>;
+    /** 设置 WebSocket 监听器（首条消息已处理后调用） */
+    private _setupListeners;
+    /** 路由消息：RPC 响应 / challenge / 事件 / 通知 */
+    private _routeMessage;
+    /** 解码 WebSocket 消息为 JSON 对象 */
+    private _decodeMessage;
+}