@agentunion/fastaun 0.4.3 → 0.4.5

package/dist/client.js

@@ -37,6 +37,14 @@ import { AID } from './aid.js';
 function isPromiseLike(value) {
     return Boolean(value && typeof value.then === 'function');
 }
+function isAIDObject(value) {
+    const candidate = value;
+    return Boolean(candidate
+        && typeof candidate === 'object'
+        && typeof candidate.aid === 'string'
+        && typeof candidate.aunPath === 'string'
+        && typeof candidate.isPrivateKeyValid === 'function');
+}
 /**
  * 递归排序键的 JSON 序列化（Canonical JSON for AUN）
  * 等价于 Python json.dumps(sort_keys=True, separators=(",",":"), ensure_ascii=False)
@@ -128,6 +136,20 @@ const DEFAULT_SESSION_OPTIONS = {
         http: 30.0,
     },
 };
+const PUBLIC_CONNECTION_OPTION_KEYS = new Set([
+    'auto_reconnect',
+    'connect_timeout',
+    'retry_initial_delay',
+    'retry_max_delay',
+    'retry_max_attempts',
+    'heartbeat_interval',
+    'call_timeout',
+    'connection_kind',
+    'short_ttl_ms',
+    'delivery_mode',
+    'extra_info',
+    'background_sync',
+]);
 const PROTECTED_HEADERS_METHODS = new Set([
     'message.send',
     'group.send',
@@ -444,7 +466,7 @@ export class AUNClient {
     /** 认证流程 */
     _auth;
     /** 密钥存储 */
-    _keystore;
+    _tokenStore;
     /** 会话参数（重连用） */
     _sessionParams = null;
     /** 会话选项 */
@@ -498,6 +520,7 @@ export class AUNClient {
     // ── V2 E2EE 状态 ──────────────────────────────────────────────
     _v2Session;
     _v2KeyStore;
+    _v2SessionInitInFlight = null;
     /** V2 bootstrap 缓存：aid/group:id → 设备列表 + 时间戳 */
     _v2BootstrapCache = new Map();
     _connectCapabilities = null;
@@ -527,10 +550,10 @@ export class AUNClient {
     _logger;
     _clientLog;
     constructor(aid) {
-        if (typeof aid === 'string') {
-            throw new ValidationError('AUNClient aid must be an AID object, not a string');
+        if (aid !== null && aid !== undefined && !isAIDObject(aid)) {
+            throw new ValidationError('AUNClient only accepts an AID object or no argument');
         }
-        const inputAid = (aid !== null && aid !== undefined && typeof aid.aunPath === 'string' && typeof aid.isPrivateKeyValid === 'function') ? aid : null;
+        const inputAid = aid ?? null;
         const rawConfig = {};
         if (inputAid) {
             rawConfig.aun_path = inputAid.aunPath;
@@ -565,30 +588,16 @@ export class AUNClient {
             logger: this._clientLog,
         });
         this._discovery = new GatewayDiscovery({ verifySsl: this._configModel.verifySsl, logger: this._clientLog, net: dnsNet });
-        const keystore = new FileKeyStore(this._configModel.aunPath, {
-            encryptionSeed: this._configModel.seedPassword ?? undefined,
+        const tokenStore = new FileKeyStore(this._configModel.aunPath, {
             logger: this._logger.for('aun_core.keystore'),
             secretStoreLogger: this._logger.for('aun_core.secret-store'),
         });
-        this._keystore = keystore;
-        // 启动时被动清理 registerAid 留下的孤儿临时目录（>10 分钟）
-        try {
-            const cleanup = keystore.cleanupPendingDirs;
-            if (typeof cleanup === 'function') {
-                const removed = cleanup.call(keystore, 600_000);
-                if (removed > 0) {
-                    this._clientLog.info(`_pending cleanup removed=${removed}`);
-                }
-            }
-        }
-        catch (err) {
-            this._clientLog.warn(`_pending cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
+        this._tokenStore = tokenStore;
         this._slotId = inputAid?.slotId || 'default';
         this._connectDeliveryMode = normalizeDeliveryModeConfig({ mode: 'fanout' });
         this._defaultConnectDeliveryMode = { ...this._connectDeliveryMode };
         this._auth = new AuthFlow({
-            keystore,
+            tokenStore,
             crypto: new CryptoProvider(),
             aid: initAid,
             deviceId: this._deviceId,
@@ -614,10 +623,11 @@ export class AUNClient {
                 this._currentAid = inputAid;
                 this._identity = {
                     aid: inputAid.aid,
-                    private_key_pem: inputAid._privateKeyPem ?? '',
+                    private_key_pem: inputAid.privateKeyPem,
                     public_key_der_b64: inputAid.publicKey,
                     cert: inputAid.certPem,
                 };
+                this._auth.setIdentity(this._identity);
                 this._state = 'standby';
             }
         }
@@ -697,6 +707,71 @@ export class AUNClient {
     get lastErrorCode() {
         return this._lastErrorCode;
     }
+    _applyAidRuntimeContext(aid) {
+        const rawConfig = {
+            aun_path: aid.aunPath,
+            verify_ssl: aid.verifySsl,
+            debug: aid.debug,
+        };
+        if (aid.rootCaPath)
+            rawConfig.root_ca_path = aid.rootCaPath;
+        const nextConfig = configFromMap(rawConfig);
+        try {
+            const close = this._tokenStore.close;
+            if (typeof close === 'function')
+                close.call(this._tokenStore);
+        }
+        catch {
+            // best-effort cleanup before switching tokenStore roots
+        }
+        this._configModel = nextConfig;
+        this.config.aun_path = nextConfig.aunPath;
+        this.config.root_ca_path = nextConfig.rootCaPath;
+        this.config.seed_password = nextConfig.seedPassword;
+        this._agentMdPath = path.join(nextConfig.aunPath, 'AIDs');
+        this._agentMdCache.clear();
+        this._agentMdFetchInflight.clear();
+        this._agentMdDownloadInflight.clear();
+        this._peerCache.clear();
+        this._certCache.clear();
+        this._gatewayUrl = null;
+        this._deviceId = aid.deviceId || getDeviceId(nextConfig.aunPath);
+        this._slotId = aid.slotId || 'default';
+        const debugFlag = nextConfig.debug;
+        this._logger = new AUNLogger({ debug: debugFlag, aunPath: nextConfig.aunPath });
+        this._logger.bindDeviceId(this._deviceId);
+        this._clientLog = this._logger.for('aun_core.client');
+        const dnsNet = new DnsResilientNet({
+            verifySsl: nextConfig.verifySsl,
+            logger: this._clientLog,
+        });
+        this._discovery = new GatewayDiscovery({ verifySsl: nextConfig.verifySsl, logger: this._clientLog, net: dnsNet });
+        const tokenStore = new FileKeyStore(nextConfig.aunPath, {
+            logger: this._logger.for('aun_core.keystore'),
+            secretStoreLogger: this._logger.for('aun_core.secret-store'),
+        });
+        this._tokenStore = tokenStore;
+        this._auth = new AuthFlow({
+            tokenStore,
+            crypto: new CryptoProvider(),
+            aid: aid.aid,
+            deviceId: this._deviceId,
+            slotId: this._slotId,
+            rootCaPath: nextConfig.rootCaPath ?? undefined,
+            verifySsl: nextConfig.verifySsl,
+            logger: this._logger.for('aun_core.auth'),
+            net: dnsNet,
+        });
+        this._transport = new RPCTransport({
+            eventDispatcher: this._dispatcher,
+            timeout: 10_000,
+            onDisconnect: (err, closeCode) => this._handleTransportDisconnect(err, closeCode),
+            verifySsl: nextConfig.verifySsl,
+            logger: this._logger.for('aun_core.transport'),
+            dnsNet,
+        });
+        this._transport.setMetaObserver((meta) => this._observeRpcMeta(meta));
+    }
     loadIdentity(aid) {
         if (!aid?.isPrivateKeyValid()) {
             throw new StateError('loadIdentity requires an AID with a valid private key');
@@ -705,16 +780,17 @@ export class AUNClient {
         if (publicState !== ConnectionState.NO_IDENTITY && publicState !== ConnectionState.CLOSED) {
             throw new StateError(`loadIdentity not allowed in state ${publicState}`);
         }
+        this._applyAidRuntimeContext(aid);
         this._currentAid = aid;
         this._aid = aid.aid;
         this._identity = {
             aid: aid.aid,
-            private_key_pem: aid._privateKeyPem ?? '',
+            private_key_pem: aid.privateKeyPem,
             public_key_der_b64: aid.publicKey,
             cert: aid.certPem,
         };
-        this._auth._aid = aid.aid;
-        this._slotId = aid.slotId || 'default';
+        // 注入内存私钥到 AuthFlow，禁止 AuthFlow 内部再走 keystore 解密
+        this._auth.setIdentity(this._identity);
         this._state = 'standby';
         this._closing = false;
         this._lastError = null;
@@ -788,10 +864,7 @@ export class AUNClient {
         return `${agentMdHttpScheme(gatewayUrl)}://${agentMdAuthority(target, this._configModel.discoveryPort)}/agent.md`;
     }
     async _ensureAgentMdUploadToken(aid, gatewayUrl) {
-        let identity = this._auth.loadIdentityOrNone(aid);
-        if (!identity && this._identity && String(this._identity.aid ?? '') === aid) {
-            identity = this._identity;
-        }
+        let identity = this._identity && String(this._identity.aid ?? '') === aid ? this._identity : null;
         if (!identity) {
             throw new StateError('no local identity found, register or load an AID first');
         }
@@ -975,7 +1048,7 @@ export class AUNClient {
             let resolvedCert = String(certPem ?? '').trim();
             if (!resolvedCert) {
                 try {
-                    resolvedCert = String(this._keystore.loadCert(target) ?? '').trim();
+                    resolvedCert = String(this._tokenStore.loadCert(target) ?? '').trim();
                 }
                 catch {
                     resolvedCert = '';
@@ -1589,10 +1662,11 @@ export class AUNClient {
     async connect(opts) {
         const tStart = Date.now();
         // 先校验非法参数（ValidationError），再检查身份（StateError）
-        if (opts !== undefined && typeof opts === 'object') {
+        if (opts !== undefined && opts !== null && typeof opts === 'object') {
             const raw = opts;
-            if ('access_token' in raw || 'aid' in raw || 'token' in raw) {
-                throw new ValidationError('connect options must not include access_token/aid; these are managed internally');
+            const invalid = Object.keys(raw).filter((key) => !PUBLIC_CONNECTION_OPTION_KEYS.has(key)).sort();
+            if (invalid.length > 0) {
+                throw new ValidationError(`connect options contain unsupported field(s): ${invalid.join(', ')}`);
             }
         }
         const target = this._currentAid?.aid ?? this._aid ?? '';
@@ -1694,8 +1768,8 @@ export class AUNClient {
             this._stopBackgroundTasks();
             this._stopReconnect();
             if (this.state === ConnectionState.NO_IDENTITY || this.state === ConnectionState.CLOSED) {
-                const closableKeyStore = this._keystore;
-                closableKeyStore.close?.();
+                const closableStore = this._tokenStore;
+                closableStore.close?.();
                 this._state = 'closed';
                 this._logger.close();
                 this._resetSeqTrackingState();
@@ -1703,8 +1777,8 @@ export class AUNClient {
                 return;
             }
             await this._transport.close();
-            const closableKeyStore = this._keystore;
-            closableKeyStore.close?.();
+            const closableStore = this._tokenStore;
+            closableStore.close?.();
             this._state = 'closed';
             this._logger.close();
             await this._dispatcher.publish('state_change', { state: this._publicState(this._state) });
@@ -1788,6 +1862,14 @@ export class AUNClient {
             }
             this._validateOutboundCall(method, p);
             this._injectMessageCursorContext(method, p);
+            if (method.startsWith('group.')
+                && !('_group_cursor_params' in p)
+                && !Boolean(p._pull_gate_locked)) {
+                const explicitCursorParams = this._groupCursorParams(p);
+                if (Object.keys(explicitCursorParams).length > 0) {
+                    p._group_cursor_params = explicitCursorParams;
+                }
+            }
             // group.* 方法的 group_id 归一化为 canonical 格式（兼容老/污染数据）
             if (method.startsWith('group.') && p.group_id !== undefined && p.group_id !== null) {
                 const rawGroupId = String(p.group_id);
@@ -1889,7 +1971,17 @@ export class AUNClient {
                     throw new ValidationError('group.pull requires group_id');
                 }
                 await this._ensureV2SessionReady('group.pull');
-                const messages = await runWithRpcPriority(() => this._pullGroupV2(String(p.group_id), Number(p.after_seq ?? p.after_message_seq ?? 0) || 0, Number(p.limit ?? 50) || 50, { gateLocked: true }));
+                const hasExplicitAfterSeq = 'after_seq' in p || 'after_message_seq' in p;
+                const cursorParams = this._explicitGroupCursorParams(p);
+                const ownsCursor = Object.keys(cursorParams).length === 0 || this._groupCursorTargetsCurrentInstance(cursorParams);
+                const pullOpts = { gateLocked: true };
+                if (hasExplicitAfterSeq)
+                    pullOpts.explicitAfterSeq = true;
+                if (Object.keys(cursorParams).length > 0)
+                    pullOpts.cursorParams = cursorParams;
+                if (!ownsCursor)
+                    pullOpts.ownsCursor = false;
+                const messages = await runWithRpcPriority(() => this._pullGroupV2(String(p.group_id), Number(p.after_seq ?? p.after_message_seq ?? 0) || 0, Number(p.limit ?? 50) || 50, pullOpts));
                 return { messages };
             }
             if (method === 'group.ack_messages' || method === 'group.v2.ack') {
@@ -1897,12 +1989,18 @@ export class AUNClient {
                     throw new ValidationError('group.ack_messages requires group_id');
                 }
                 await this._ensureV2SessionReady('group.ack_messages');
+                const cursorParams = this._explicitGroupCursorParams(p);
+                const ownsCursor = Object.keys(cursorParams).length === 0 || this._groupCursorTargetsCurrentInstance(cursorParams);
+                if (method === 'group.ack_messages' && !ownsCursor) {
+                    return await runWithRpcPriority(() => this._rawGroupAckMessages(p));
+                }
                 return await runWithRpcPriority(() => this._ackGroupV2(String(p.group_id), Number(p.seq ?? p.msg_seq ?? p.up_to_seq ?? 0) || undefined));
             }
             if (method === 'message.pull') {
                 delete p._skip_auto_ack;
                 delete p.skip_auto_ack;
             }
+            delete p._group_cursor_params;
             // 关键操作自动附加客户端签名
             if (SIGNED_METHODS.has(method)) {
                 if (this._shouldSkipClientSignature(method, p)) {
@@ -1973,6 +2071,7 @@ export class AUNClient {
         delete p._pull_gate_locked;
         delete p._skip_auto_ack;
         delete p.skip_auto_ack;
+        delete p._group_cursor_params;
         if (method.startsWith('group.') && p.group_id !== undefined && p.group_id !== null) {
             p.group_id = normalizeGroupId(String(p.group_id)) || String(p.group_id);
         }
@@ -2021,13 +2120,12 @@ export class AUNClient {
      * 签名覆盖所有非 _ 前缀且非 client_signature 的业务字段。
      */
     _signClientOperation(method, params) {
-        const identity = this._identity;
-        if (!identity || !identity.private_key_pem)
+        const currentAid = this._currentAid;
+        if (!currentAid?.privateKeyPem)
             return;
         try {
-            const aid = String(identity.aid ?? '');
+            const aid = currentAid.aid;
             const ts = String(Math.floor(Date.now() / 1000));
-            // 计算 params hash — 必须递归排序所有键（与 Python json.dumps(sort_keys=True, separators=(",",":")) 一致）
             const paramsForHash = {};
             for (const [k, v] of Object.entries(params)) {
                 if (k !== 'client_signature' && !k.startsWith('_')) {
@@ -2037,11 +2135,11 @@ export class AUNClient {
             const paramsJson = stableStringify(paramsForHash);
             const paramsHash = crypto.createHash('sha256').update(paramsJson, 'utf-8').digest('hex');
             const signData = Buffer.from(`${method}|${aid}|${ts}|${paramsHash}`, 'utf-8');
-            const privateKey = crypto.createPrivateKey(String(identity.private_key_pem));
+            const privateKey = crypto.createPrivateKey(currentAid.privateKeyPem);
             const signature = crypto.sign('SHA256', signData, privateKey);
             // 证书指纹
             let certFingerprint = '';
-            const certPem = String(identity.cert ?? '');
+            const certPem = currentAid.certPem;
             if (certPem) {
                 const certObj = new crypto.X509Certificate(certPem);
                 certFingerprint = 'sha256:' + certObj.fingerprint256.replace(/:/g, '').toLowerCase();
@@ -2747,6 +2845,27 @@ export class AUNClient {
         }
         return Math.max(0, ...values.filter((value) => Number.isFinite(value)));
     }
+    _groupCursorParams(params) {
+        const cursorParams = {};
+        for (const key of ['device_id', 'slot_id', 'device_name', 'device_type']) {
+            const value = params[key];
+            if (value !== undefined && value !== null)
+                cursorParams[key] = value;
+        }
+        return cursorParams;
+    }
+    _explicitGroupCursorParams(params) {
+        const value = params._group_cursor_params;
+        if (!isJsonObject(value))
+            return {};
+        return { ...value };
+    }
+    _groupCursorTargetsCurrentInstance(params) {
+        const deviceId = String(params.device_id ?? '').trim();
+        const slotId = String(params.slot_id ?? '').trim();
+        return (!deviceId || deviceId === (this._deviceId ?? ''))
+            && (!slotId || slotId === (this._slotId ?? ''));
+    }
     _schedulePullFollowup(method, params, result) {
         if (method === 'message.pull')
             method = 'message.v2.pull';
@@ -3237,8 +3356,8 @@ export class AUNClient {
             const membershipSnapshot = String(d.membership_snapshot ?? '').trim();
             const policySnapshot = String(d.policy_snapshot ?? '').trim();
             // 1. 验证 prev_state_hash 连续性
-            const loadFn = this._keystore.loadGroupState;
-            const localState = loadFn ? loadFn.call(this._keystore, groupId) : null;
+            const loadFn = this._tokenStore.loadGroupState;
+            const localState = loadFn ? loadFn.call(this._tokenStore, groupId) : null;
             if (localState && localState.state_hash && localState.state_hash !== prevStateHash) {
                 this._clientLog.warn(`state_hash chain discontinuous group=${groupId} local_sv=${localState.state_version} event_sv=${stateVersion}`);
                 // 回源同步
@@ -3264,9 +3383,9 @@ export class AUNClient {
                                 return;
                             }
                         }
-                        const saveFn = this._keystore.saveGroupState;
+                        const saveFn = this._tokenStore.saveGroupState;
                         if (saveFn) {
-                            saveFn.call(this._keystore, groupId, sv, sHash, sEpoch, sMembersJson || membershipSnapshot, sPolicyJson || policySnapshot);
+                            saveFn.call(this._tokenStore, groupId, sv, sHash, sEpoch, sMembersJson || membershipSnapshot, sPolicyJson || policySnapshot);
                         }
                     }
                 }
@@ -3287,9 +3406,9 @@ export class AUNClient {
                 return;
             }
             // 3. 更新本地存储
-            const saveFn = this._keystore.saveGroupState;
+            const saveFn = this._tokenStore.saveGroupState;
             if (saveFn) {
-                saveFn.call(this._keystore, groupId, stateVersion, stateHash, keyEpoch, membershipSnapshot, policySnapshot);
+                saveFn.call(this._tokenStore, groupId, stateVersion, stateHash, keyEpoch, membershipSnapshot, policySnapshot);
             }
             this._clientLog.debug(`_onGroupStateCommitted exit: elapsed=${Date.now() - tStart}ms group=${groupId}`);
         }
@@ -3449,7 +3568,7 @@ export class AUNClient {
         }
         try {
             // peer 证书只存版本目录，不覆盖 cert.pem
-            this._keystore.saveCert(aid, certPem, certFingerprint, { makeActive: false });
+            this._tokenStore.saveCert(aid, certPem, certFingerprint, { makeActive: false });
         }
         catch (exc) {
             this._clientLog.error(`failed to write cert to keystore (aid=${aid}, fp=${certFingerprint ?? ''}): ${formatCaughtError(exc)}`, exc instanceof Error ? exc : undefined);
@@ -3720,9 +3839,9 @@ export class AUNClient {
             return;
         try {
             // 优先从 seq_tracker 表按行读取
-            const loadAll = this._keystore.loadAllSeqs;
+            const loadAll = this._tokenStore.loadAllSeqs;
             if (typeof loadAll === 'function') {
-                let state = loadAll.call(this._keystore, this._aid, this._deviceId, this._slotId);
+                let state = loadAll.call(this._tokenStore, this._aid, this._deviceId, this._slotId);
                 if (state && Object.keys(state).length > 0) {
                     state = this._migrateSeqStateGroupIds(state);
                     this._seqTracker.restoreState(state);
@@ -3730,9 +3849,9 @@ export class AUNClient {
                 }
             }
             // fallback: 从旧 instance_state JSON blob 恢复
-            const loader = this._keystore.loadInstanceState;
+            const loader = this._tokenStore.loadInstanceState;
             if (typeof loader === 'function') {
-                const instanceState = loader.call(this._keystore, this._aid, this._deviceId, this._slotId);
+                const instanceState = loader.call(this._tokenStore, this._aid, this._deviceId, this._slotId);
                 if (instanceState && typeof instanceState.seq_tracker_state === 'object') {
                     let state = instanceState.seq_tracker_state;
                     state = this._migrateSeqStateGroupIds(state);
@@ -3783,20 +3902,20 @@ export class AUNClient {
         }
         this._clientLog.info(`SeqTracker group_id migration: ${Object.keys(renameMap).length} namespaces rewritten`);
         // 落盘
-        const saver = this._keystore.saveSeq;
-        const deleter = this._keystore.deleteSeq;
+        const saver = this._tokenStore.saveSeq;
+        const deleter = this._tokenStore.deleteSeq;
         if (typeof saver === 'function' && this._aid) {
             for (const [oldNs, newNs] of Object.entries(renameMap)) {
                 if (typeof deleter === 'function') {
                     try {
-                        deleter.call(this._keystore, this._aid, this._deviceId, this._slotId, oldNs);
+                        deleter.call(this._tokenStore, this._aid, this._deviceId, this._slotId, oldNs);
                     }
                     catch (e) {
                         this._clientLog.debug(`delete old seq ns failed: ns=${oldNs} err=${formatCaughtError(e)}`);
                     }
                 }
                 try {
-                    saver.call(this._keystore, this._aid, this._deviceId, this._slotId, newNs, newState[newNs]);
+                    saver.call(this._tokenStore, this._aid, this._deviceId, this._slotId, newNs, newState[newNs]);
                 }
                 catch (e) {
                     this._clientLog.debug(`write new seq ns failed: ns=${newNs} err=${formatCaughtError(e)}`);
@@ -3844,17 +3963,17 @@ export class AUNClient {
             return;
         try {
             // 优先按行写入 seq_tracker 表
-            const saveFn = this._keystore.saveSeq;
+            const saveFn = this._tokenStore.saveSeq;
             if (typeof saveFn === 'function') {
                 for (const [ns, seq] of Object.entries(state)) {
-                    saveFn.call(this._keystore, this._aid, this._deviceId, this._slotId, ns, seq);
+                    saveFn.call(this._tokenStore, this._aid, this._deviceId, this._slotId, ns, seq);
                 }
                 return;
             }
             // fallback: 旧版 updateInstanceState JSON blob
-            const updater = this._keystore.updateInstanceState;
+            const updater = this._tokenStore.updateInstanceState;
             if (typeof updater === 'function') {
-                updater.call(this._keystore, this._aid, this._deviceId, this._slotId, (metadata) => {
+                updater.call(this._tokenStore, this._aid, this._deviceId, this._slotId, (metadata) => {
                     metadata.seq_tracker_state = state;
                     return metadata;
                 });
@@ -3877,13 +3996,13 @@ export class AUNClient {
             return;
         const seq = this._seqTracker.getContiguousSeq(ns);
         try {
-            if (seq > 0 && typeof this._keystore.saveSeq === 'function') {
-                this._keystore.saveSeq(this._aid, this._deviceId, this._slotId, ns, seq);
+            if (seq > 0 && typeof this._tokenStore.saveSeq === 'function') {
+                this._tokenStore.saveSeq(this._aid, this._deviceId, this._slotId, ns, seq);
                 return;
             }
-            const deleteSeq = this._keystore.deleteSeq;
+            const deleteSeq = this._tokenStore.deleteSeq;
             if (seq <= 0 && typeof deleteSeq === 'function') {
-                deleteSeq.call(this._keystore, this._aid, this._deviceId, this._slotId, ns);
+                deleteSeq.call(this._tokenStore, this._aid, this._deviceId, this._slotId, ns);
                 return;
             }
             if (seq > 0) {
@@ -4026,16 +4145,26 @@ export class AUNClient {
                 this._restoreSeqTrackerState();
             }
             this._startBackgroundTasks();
-            // V2 E2EE：初始化 session 并注册本设备 SPK。
-            try {
-                await this._initV2Session();
+            const connectionKind = String(params.connection_kind ?? 'long');
+            const isShortConnection = connectionKind === 'short';
+            if (!isShortConnection) {
+                // V2 E2EE：长连接上线时初始化 session 并注册本设备 SPK。
+                try {
+                    await this._initV2Session();
+                }
+                catch (exc) {
+                    this._clientLog.warn(`V2 session init failed (non-fatal): ${formatCaughtError(exc)}`);
+                }
             }
-            catch (exc) {
-                this._clientLog.warn(`V2 session init failed (non-fatal): ${formatCaughtError(exc)}`);
+            else {
+                this._clientLog.debug('V2 session init deferred for short connection');
             }
             // connect/reconnect 成功后自动触发一次 P2P message.v2.pull，补齐离线期间积压
             // 群消息按惰性触发，不在此处主动 pull
-            if (this._sessionOptions.background_sync !== false) {
+            const hasExplicitBackgroundSync = Object.prototype.hasOwnProperty.call(params, 'background_sync');
+            const backgroundSyncEnabled = this._sessionOptions.background_sync !== false
+                && (!isShortConnection || hasExplicitBackgroundSync);
+            if (backgroundSyncEnabled) {
                 void this._fillP2pGap().catch((exc) => {
                     this._clientLog.warn(`schedule post-connect P2P gap fill failed: ${formatCaughtError(exc)}`);
                 });
@@ -4074,6 +4203,15 @@ export class AUNClient {
     }
     /** V2-only：所有加密入口都必须有 V2 session。 */
     async _ensureV2SessionReady(method, errorMessage) {
+        if (!this._v2Session) {
+            if (!this._v2SessionInitInFlight) {
+                this._v2SessionInitInFlight = this._initV2Session()
+                    .finally(() => {
+                    this._v2SessionInitInFlight = null;
+                });
+            }
+            await this._v2SessionInitInFlight;
+        }
         if (!this._v2Session) {
             throw new StateError(errorMessage ?? `V2 session not initialized; encrypted ${method} requires E2EE V2`);
         }
@@ -4096,42 +4234,13 @@ export class AUNClient {
             this._v2BootstrapCache.clear();
         }
         let identity = this._identity;
-        if (!identity) {
-            try {
-                identity = this._keystore.loadIdentity(this._aid);
-                if (identity)
-                    this._identity = identity;
-            }
-            catch {
-                identity = null;
-            }
-        }
-        if (!identity?.private_key_pem) {
-            // fallback：缓存的 identity 可能被 instanceState 污染，重新从 keystore 加载
-            try {
-                identity = this._keystore.loadIdentity(this._aid);
-                if (identity?.private_key_pem) {
-                    this._identity = identity;
-                    this._clientLog.warn('V2 session init: identity cache was stale, reloaded from keystore');
-                    // 重新持久化 instance_state，清理脏数据
-                    const persistIdentity = this._auth._persistIdentity;
-                    if (typeof persistIdentity === 'function') {
-                        try {
-                            persistIdentity.call(this._auth, identity);
-                        }
-                        catch { /* best-effort */ }
-                    }
-                }
-            }
-            catch {
-                identity = null;
-            }
-        }
-        if (!identity?.private_key_pem) {
+        // 私钥由 AIDStore 管理，直接从 _currentAid 读取明文私钥
+        const currentAid = this._currentAid;
+        if (!currentAid?.privateKeyPem) {
             this._clientLog.warn('V2 session init skipped: no AID private key');
             return;
         }
-        const privateKey = crypto.createPrivateKey(String(identity.private_key_pem));
+        const privateKey = crypto.createPrivateKey(currentAid.privateKeyPem);
         const jwk = privateKey.export({ format: 'jwk' });
         if (jwk.kty !== 'EC' || jwk.crv !== 'P-256' || !jwk.d) {
             throw new StateError('AID private key must be EC P-256');
@@ -4139,8 +4248,8 @@ export class AUNClient {
         const aidPriv = _v2LeftPad32(_v2B64uToBytes(jwk.d));
         const pubDer = crypto.createPublicKey(privateKey).export({ format: 'der', type: 'spki' });
         const aidPubDer = new Uint8Array(pubDer);
-        const storeProvider = this._keystore;
-        const v2Store = storeProvider.getV2KeyStore?.call(this._keystore, this._aid);
+        const storeProvider = this._tokenStore;
+        const v2Store = storeProvider.getV2KeyStore?.call(this._tokenStore, this._aid);
         if (!v2Store) {
             throw new StateError('V2 key store is unavailable for current keystore');
         }
@@ -4150,6 +4259,28 @@ export class AUNClient {
         this._clientLog.debug(`V2 session initialized aid=${this._aid} device=${this._deviceId}`);
         // 群 state proposal 由服务端在 client.online 时定向通知。
     }
+    _currentV2KeyStore() {
+        if (this._v2KeyStore)
+            return this._v2KeyStore;
+        if (!this._aid)
+            throw new StateError('V2 key store requires a loaded AID');
+        const storeProvider = this._tokenStore;
+        const v2Store = storeProvider.getV2KeyStore?.call(this._tokenStore, this._aid);
+        if (!v2Store) {
+            throw new StateError('V2 key store is unavailable for current identity');
+        }
+        this._v2KeyStore = v2Store;
+        return v2Store;
+    }
+    _saveGroupIdentityToV2(groupAid, identity) {
+        const privateKeyPem = String(identity.private_key_pem ?? '').trim();
+        const publicKeyDerB64 = String(identity.public_key_der_b64 ?? '').trim();
+        if (!groupAid || !privateKeyPem || !publicKeyDerB64) {
+            throw new StateError('group identity is incomplete');
+        }
+        const pubDer = new Uint8Array(Buffer.from(publicKeyDerB64, 'base64'));
+        this._currentV2KeyStore().saveGroupIdentity(this._deviceId, groupAid, privateKeyPem, pubDer);
+    }
     async _v2TrustedIKPubDer(aid) {
         const normalizedAid = String(aid ?? '').trim();
         if (!normalizedAid)
@@ -4677,6 +4808,7 @@ export class AUNClient {
                 decrypted.push(plaintext);
                 this._logMessageDebug('decrypt-ok', 'message.v2.pull', 'message.received', plaintext);
             }
+            const hasServerAckSeq = Object.prototype.hasOwnProperty.call(result, 'server_ack_seq');
             const serverAckSeq = Number(result.server_ack_seq ?? 0);
             if (ns && Number.isFinite(serverAckSeq) && serverAckSeq > 0) {
                 const contig = this._seqTracker.getContiguousSeq(ns);
@@ -4692,7 +4824,11 @@ export class AUNClient {
                     await this._drainOrderedMessages(ns, undefined, true);
                     this._saveSeqTrackerState();
                 }
-                if (messages.length > 0 && contigAdvanced && ackSeq > 0 && !opts?.skipAutoAck) {
+                const ackNeeded = messages.length > 0
+                    && ackSeq > 0
+                    && !opts?.skipAutoAck
+                    && (contigAdvanced || (hasServerAckSeq && ackSeq > serverAckSeq));
+                if (ackNeeded) {
                     this._clientLog.debug(`message.v2.pull scheduling auto-ack: ns=${ns}, ack_seq=${ackSeq}, raw_count=${messages.length}`);
                     this._safeAsync(this._ackV2(ackSeq).then(() => undefined));
                 }
@@ -4955,7 +5091,9 @@ export class AUNClient {
         }
         const decrypted = [];
         let totalRawCount = 0;
-        let nextAfterSeq = afterSeq || this._seqTracker.getContiguousSeq(ns);
+        const cursorParams = opts?.cursorParams ?? {};
+        const ownsCursor = opts?.ownsCursor !== false;
+        let nextAfterSeq = opts?.explicitAfterSeq ? afterSeq : (afterSeq || this._seqTracker.getContiguousSeq(ns));
         let pageCount = 0;
         const maxPages = 100;
         while (pageCount < maxPages) {
@@ -4965,6 +5103,7 @@ export class AUNClient {
                 group_id: gid,
                 after_seq: nextAfterSeq,
                 limit,
+                ...cursorParams,
             });
             const messages = (Array.isArray(result.messages) ? result.messages : []);
             totalRawCount += messages.length;
@@ -5043,7 +5182,9 @@ export class AUNClient {
                 decrypted.push(plaintext);
                 this._logMessageDebug('decrypt-ok', 'group.v2.pull', 'group.message_created', plaintext);
             }
-            const retentionFloor = this._pullRetentionFloor(result, 'retention_floor_message_seq', 'retention_floor_message_seq');
+            const cursorCurrentSeq = Number(cursor?.current_seq ?? 0);
+            const hasServerCursor = cursor !== null && Object.prototype.hasOwnProperty.call(cursor, 'current_seq');
+            const retentionFloor = Math.max(this._pullRetentionFloor(result, 'retention_floor_message_seq', 'retention_floor_message_seq'), Number.isFinite(cursorCurrentSeq) ? cursorCurrentSeq : 0);
             if (retentionFloor > 0) {
                 const contig = this._seqTracker.getContiguousSeq(ns);
                 if (contig < retentionFloor) {
@@ -5057,11 +5198,17 @@ export class AUNClient {
                 await this._drainOrderedMessages(ns, undefined, true);
                 this._saveSeqTrackerState();
             }
-            if (messages.length > 0 && contigAdvanced && ackSeq > 0) {
+            const ackNeeded = messages.length > 0
+                && ackSeq > 0
+                && ownsCursor
+                && (contigAdvanced || (hasServerCursor && ackSeq > cursorCurrentSeq));
+            if (ackNeeded) {
                 this._clientLog.debug(`group.v2.pull scheduling auto-ack: group=${gid}, ns=${ns}, ack_seq=${ackSeq}, raw_count=${messages.length}`);
                 this._safeAsync(this._ackGroupV2(gid, ackSeq).then(() => undefined));
             }
             const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
+            if (!ownsCursor)
+                break;
             if (messages.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false)
                 break;
             nextAfterSeq = nextAfter;
@@ -5072,6 +5219,10 @@ export class AUNClient {
         this._clientLog.debug(`group.v2.pull done: group=${gid}, requested_after_seq=${afterSeq}, pages=${pageCount}, decrypted=${decrypted.length}, ns=${ns}`);
         return decrypted;
     }
+    async _rawGroupAckMessages(params) {
+        const p = { ...params };
+        return await this._callRawV2Rpc('group.ack_messages', p);
+    }
     /** V2 Group ack。 */
     async _ackGroupV2(groupId, upToSeq) {
         const gid = normalizeGroupId(groupId) || String(groupId ?? '').trim();
@@ -6071,7 +6222,7 @@ export class AUNClient {
                 return;
             }
             let signature = '';
-            const privateKeyPem = String(this._identity?.private_key_pem ?? '');
+            const privateKeyPem = this._currentAid?.privateKeyPem ?? '';
             if (privateKeyPem) {
                 try {
                     const signPayload = stableStringify({
@@ -6403,9 +6554,9 @@ export class AUNClient {
         if (this._gatewayUrl)
             return this._gatewayUrl;
         try {
-            const loadMetadata = this._keystore.loadMetadata;
+            const loadMetadata = this._tokenStore.loadMetadata;
             const cachedGateway = typeof loadMetadata === 'function'
-                ? String(loadMetadata.call(this._keystore, resolvedAid)?.gateway_url ?? '').trim()
+                ? String(loadMetadata.call(this._tokenStore, resolvedAid)?.gateway_url ?? '').trim()
                 : '';
             if (cachedGateway) {
                 this._gatewayUrl = cachedGateway;
@@ -6427,9 +6578,9 @@ export class AUNClient {
                 const gateway = await this._discovery.discover(url);
                 this._gatewayUrl = gateway;
                 try {
-                    const saveMetadata = this._keystore.saveMetadata;
+                    const saveMetadata = this._tokenStore.saveMetadata;
                     if (typeof saveMetadata === 'function') {
-                        saveMetadata.call(this._keystore, resolvedAid, { gateway_url: gateway, gateway_cached_at: Date.now() });
+                        saveMetadata.call(this._tokenStore, resolvedAid, { gateway_url: gateway, gateway_cached_at: Date.now() });
                     }
                 }
                 catch {
@@ -6475,9 +6626,8 @@ export class AUNClient {
     }
     /** 连接后同步身份信息 */
     _syncIdentityAfterConnect(accessToken) {
-        const identity = this._auth.loadIdentityOrNone(this._aid ?? undefined);
+        const identity = this._identity;
         if (identity === null) {
-            this._identity = null;
             return;
         }
         identity.access_token = accessToken;
@@ -6488,9 +6638,7 @@ export class AUNClient {
         const persistIdentity = this._auth._persistIdentity;
         if (typeof persistIdentity === 'function') {
             persistIdentity.call(this._auth, identity);
-            return;
         }
-        this._keystore.saveIdentity(String(identity.aid), identity);
     }
     // ── 内部：参数处理 ────────────────────────────────────────
     /** 规范化连接参数 */
@@ -6674,7 +6822,7 @@ export class AUNClient {
                     scheduleNext();
                     return;
                 }
-                let identity = this._identity ?? this._auth.loadIdentityOrNone() ?? null;
+                let identity = this._identity;
                 if (identity === null) {
                     scheduleNext();
                     return;
@@ -7023,8 +7171,7 @@ export class AUNClient {
     }
     // ── Named Group（命名群）高层 API ────────────────────────────
     /**
-     * 创建命名群：本地生成 P-256 keypair，调用 group.create 传入 public_key，
-     * 服务端签发群 AID 证书，返回后将证书和私钥存入 keystore。
+     * 创建命名群：群/P2P 私钥由 V2 数据库存储，不写入 AID 身份私钥存储。
      */
     async createNamedGroup(groupName, opts = {}) {
         const tStart = Date.now();
@@ -7044,15 +7191,10 @@ export class AUNClient {
             const aidCert = result?.aid_cert;
             const groupAid = String(groupInfo?.group_aid ?? '');
             if (groupAid && aidCert) {
-                this._keystore.saveIdentity(groupAid, {
-                    private_key_pem: identity.private_key_pem,
-                    public_key: identity.public_key_der_b64,
-                    curve: 'P-256',
-                    type: 'group_identity',
-                });
+                this._saveGroupIdentityToV2(groupAid, identity);
                 const certPem = String(aidCert.cert ?? '');
                 if (certPem) {
-                    this._keystore.saveCert(groupAid, certPem);
+                    this._tokenStore.saveCert(groupAid, certPem);
                 }
             }
             this._clientLog.debug(`createNamedGroup exit: elapsed=${Date.now() - tStart}ms groupAid=${groupAid}`);
@@ -7083,15 +7225,10 @@ export class AUNClient {
             const aidCert = result?.aid_cert;
             const groupAid = String(groupInfo?.group_aid ?? '');
             if (groupAid && aidCert) {
-                this._keystore.saveIdentity(groupAid, {
-                    private_key_pem: identity.private_key_pem,
-                    public_key: identity.public_key_der_b64,
-                    curve: 'P-256',
-                    type: 'group_identity',
-                });
+                this._saveGroupIdentityToV2(groupAid, identity);
                 const certPem = String(aidCert.cert ?? '');
                 if (certPem) {
-                    this._keystore.saveCert(groupAid, certPem);
+                    this._tokenStore.saveCert(groupAid, certPem);
                 }
             }
             this._clientLog.debug(`bindGroupAid exit: elapsed=${Date.now() - tStart}ms groupAid=${groupAid}`);