@agentunion/fastaun-browser 0.2.15 → 0.2.16

package/dist/client.js

@@ -15,7 +15,7 @@ import { CustodyNamespace } from './namespaces/custody.js';
 import { MetaNamespace } from './namespaces/meta.js';
 import { CryptoProvider, uint8ToBase64, base64ToUint8, pemToArrayBuffer, p1363ToDer, toBufferSource } from './crypto.js';
 import { E2EEManager, _certificateSha256Fingerprint as certificateSha256Fingerprint, _ecdsaVerifyDer as ecdsaVerifyDer, _importCertPublicKeyEcdsa as importCertPublicKeyEcdsa, } from './e2ee.js';
-import { GroupE2EEManager, computeMembershipCommitment, storeGroupSecret, buildKeyDistribution, buildKeyRequest, buildMembershipManifest, signMembershipManifest, } from './e2ee-group.js';
+import { GroupE2EEManager, computeMembershipCommitment, computeStateHash, storeGroupSecret, storeGroupSecretEpoch, buildKeyDistribution, buildKeyRequest, buildMembershipManifest, signMembershipManifest, verifyEpochChain, } from './e2ee-group.js';
 import { IndexedDBKeyStore } from './keystore/indexeddb.js';
 import { AUNError, AuthError, ConnectionError, E2EEError, PermissionError, StateError, ValidationError, } from './errors.js';
 import { isJsonObject, } from './types.js';
@@ -67,11 +67,16 @@ const SIGNED_METHODS = new Set([
     'group.resources.delete', 'group.resources.request_add',
     'group.resources.direct_add', 'group.resources.approve_request',
     'group.resources.reject_request',
+    'group.commit_state',
+    'group.e2ee.begin_rotation', 'group.e2ee.commit_rotation',
+    'group.e2ee.abort_rotation',
+    'group.ban', 'group.unban',
+    'group.dissolve', 'group.suspend', 'group.resume',
 ]);
 const DEFAULT_SESSION_OPTIONS = {
     auto_reconnect: true,
     heartbeat_interval: 30.0,
-    token_refresh_before: 60.0,
+    token_refresh_before: 1800.0,
     retry: {
         initial_delay: 1.0,
         max_delay: 64.0,
@@ -86,6 +91,7 @@ const DEFAULT_SESSION_OPTIONS = {
 };
 const RECONNECT_MIN_BASE_DELAY_SECONDS = 1.0;
 const RECONNECT_MAX_BASE_DELAY_SECONDS = 64.0;
+const TOKEN_REFRESH_CHECK_INTERVAL_MS = 30_000;
 const GROUP_ROTATION_LEASE_MS = 120_000;
 const GROUP_ROTATION_RETRY_MAX_DELAY_MS = 300_000;
 const PENDING_DECRYPT_LIMIT = 100;
@@ -112,7 +118,8 @@ function reconnectSleepDelaySeconds(baseDelay, maxBaseDelay) {
     return baseDelay + Math.random() * maxBaseDelay;
 }
 /** 对端证书缓存 TTL（秒） */
-const PEER_CERT_CACHE_TTL = 600;
+const PEER_CERT_CACHE_TTL = 3600;
+const PEER_PREKEYS_CACHE_TTL = 3600;
 /**
  * 将 WebSocket URL 转为对应的 HTTP URL
  */
@@ -234,6 +241,19 @@ function normalizePeerPrekeys(prekeys) {
     }
     return filtered;
 }
+/** 判断加密失败是否由过期的对端证书或 prekey 引起，可通过刷新缓存重试 */
+function isRetryablePeerMaterialError(error) {
+    const localCode = String(error?.localCode ?? error?.code ?? '').trim();
+    if (localCode === 'PEER_CERT_FINGERPRINT_MISMATCH'
+        || localCode === 'PREKEY_CERT_FINGERPRINT_MISMATCH'
+        || localCode === 'PREKEY_SIGNATURE_VERIFY_FAILED') {
+        return true;
+    }
+    const message = error instanceof Error ? error.message : String(error ?? '');
+    return message.includes('peer cert fingerprint mismatch for ')
+        || message.includes('prekey cert fingerprint mismatch')
+        || message.includes('prekey 签名验证失败');
+}
 function formatCaughtError(error) {
     return error instanceof Error ? error : String(error);
 }
@@ -325,8 +345,6 @@ export class AUNClient {
     // 后台任务 handle（浏览器 setInterval/setTimeout）
     _heartbeatTimer = null;
     _tokenRefreshTimer = null;
-    /** 非连接状态下 token 刷新的退避计数器 */
-    _tokenDisconnectedRetries = 0;
     _tokenRefreshFailures = 0;
     _prekeyRefreshTimer = null;
     _groupEpochCleanupTimer = null;
@@ -345,6 +363,8 @@ export class AUNClient {
     _groupEpochRotationInflight = new Set();
     _groupEpochRecoveryInflight = new Map();
     _groupMembershipRotationDone = new Set();
+    /** 群密钥 backfill 去重：已完成/进行中的 key 集合，防止重复分发 */
+    _groupMemberKeyBackfillDone = new Set();
     _groupEpochRotationRetryTimers = new Map();
     /** Lazy group sync：首次发送群消息前自动拉取历史 */
     _groupSynced = new Set();
@@ -413,6 +433,10 @@ export class AUNClient {
         this._dispatcher.subscribe('_raw.group.changed', (data) => {
             this._onRawGroupChanged(data);
         });
+        // 群组状态提交事件：验证 state_hash 链并更新本地存储
+        this._dispatcher.subscribe('_raw.group.state_committed', (data) => {
+            this._safeAsync(this._onGroupStateCommitted(data));
+        });
         // 其他事件直接透传
         for (const evt of ['message.recalled', 'message.ack', 'storage.object_changed']) {
             this._dispatcher.subscribe(`_raw.${evt}`, (data) => {
@@ -465,13 +489,23 @@ export class AUNClient {
         if (this._state !== 'idle' && this._state !== 'closed' && this._state !== 'disconnected') {
             throw new StateError(`connect not allowed in state ${this._state}`);
         }
+        this._state = 'connecting';
         const params = { ...auth, ...options };
         const normalized = this._normalizeConnectParams(params);
         this._sessionParams = normalized;
         this._sessionOptions = this._buildSessionOptions(normalized);
         this._transport.setTimeout(this._sessionOptions.timeouts.call);
         this._closing = false;
-        await this._connectOnce(normalized, false);
+        try {
+            await this._connectOnce(normalized, false);
+        }
+        catch (err) {
+            // 连接失败时回退状态，允许重试
+            if (this._state === 'connecting' || this._state === 'authenticating') {
+                this._state = 'disconnected';
+            }
+            throw err;
+        }
     }
     /** 断开连接但保留本地状态，可再次 connect */
     async disconnect() {
@@ -741,8 +775,11 @@ export class AUNClient {
             const groupId = this._extractGroupIdFromResult(result) || String(p.group_id ?? '');
             if (groupId && this._membershipRotationChanged(method, result)) {
                 const expectedEpoch = this._membershipRotationExpectedEpoch(result);
+                // 自加入方法（request_join/use_invite_code）需要 allowMember=true，
+                // 因为新成员角色是 member，必须允许 member 参与 leader 选举。
+                const allowMember = method === 'group.request_join' || method === 'group.use_invite_code';
                 // P0-12: await rotation 完成（带超时兜底），确保后续 group.send 使用新 epoch
-                const rotationPromise = this._maybeLeadRotateGroupEpoch(groupId, this._membershipRotationTriggerId(groupId, result), expectedEpoch);
+                const rotationPromise = this._maybeLeadRotateGroupEpoch(groupId, this._membershipRotationTriggerId(groupId, result), expectedEpoch, allowMember);
                 const timeoutPromise = new Promise((resolve) => globalThis.setTimeout(resolve, 5000));
                 await Promise.race([rotationPromise, timeoutPromise]).catch((exc) => console.warn('membership RPC epoch rotation fallback failed:', exc));
             }
@@ -1082,6 +1119,11 @@ export class AUNClient {
                             // 消息事件由 _fillGroupGap 负责，事件补洞不重复投递
                             if (et === 'group.message_created')
                                 continue;
+                            // 验签：有 client_signature 就验（与实时事件路径对齐）
+                            const cs = evt.client_signature;
+                            if (cs && typeof cs === 'object') {
+                                evt._verified = await this._verifyEventSignature(evt, cs);
+                            }
                             // group.changed 或缺失/其他 → 发布到 group.changed（向后兼容）
                             await this._dispatcher.publish('group.changed', evt);
                         }
@@ -1277,51 +1319,6 @@ export class AUNClient {
         await this._drainOrderedMessages(ns);
         return true;
     }
-    /**
-     * 上线/重连后一次性同步所有已加入群：
-     * 1. 有 epoch key 的群 → 补消息 + 补事件
-     * 2. 无 epoch key 的群 → 主动向 owner 请求密钥恢复 + 补事件
-     */
-    async _syncAllGroupsOnce() {
-        try {
-            const result = await this.call('group.list_my', {});
-            if (!isJsonObject(result))
-                return;
-            const items = result.items;
-            if (!Array.isArray(items))
-                return;
-            for (const g of items) {
-                if (isJsonObject(g)) {
-                    const gid = (g.group_id ?? '');
-                    if (gid) {
-                        const hasSecret = await this._groupE2ee.hasSecret(gid);
-                        if (!hasSecret) {
-                            // 没有 epoch key → 主动向 owner 请求密钥恢复（与 Python 对齐）
-                            const ownerAid = (g.owner_aid ?? '');
-                            if (ownerAid && ownerAid !== this._aid) {
-                                await this._requestGroupKeyFrom(gid, ownerAid);
-                            }
-                            else {
-                                console.debug(`[aun_core] 群 ${gid} 无 epoch key 且无法确定 owner，等待推送触发恢复`);
-                            }
-                        }
-                        else {
-                            // 有 epoch key → 补消息
-                            await this._fillGroupGap(gid);
-                        }
-                        // 所有群都补事件（事件不加密）
-                        await this._fillGroupEventGap(gid);
-                    }
-                }
-            }
-        }
-        catch (exc) {
-            console.warn('[aun_core] 上线群组同步失败，群消息可能不完整:', exc);
-            this._dispatcher.publish('group.sync_failed', {
-                error: exc instanceof Error ? exc.message : String(exc),
-            }).catch(() => { });
-        }
-    }
     /** 主动向指定成员请求群组密钥（用于重连时无 epoch key 的群）（与 Python 对齐） */
     async _requestGroupKeyFrom(groupId, targetAid, epoch = 0) {
         try {
@@ -1497,14 +1494,35 @@ export class AUNClient {
                     }
                 }
             }
+            // 成员加入：按 action 区分策略
+            // - member_added / join_approved（私密群/审批群）：admin 必然在线，立即轮换
+            // - joined / invite_code_used（开放群/邀请码群）：所有在线成员延迟轮换，新成员自己延迟更长
             if (['member_added', 'joined', 'join_approved', 'invite_code_used'].includes(String(d.action ?? ''))) {
                 if (groupId) {
+                    const action = String(d.action ?? '');
                     const expectedEpoch = this._membershipRotationExpectedEpoch(d);
-                    if (expectedEpoch === null) {
-                        console.debug('membership event without old_epoch skipped for epoch rotation: aid=%s group=%s action=%s event_seq=%s', this._aid ?? '', groupId, String(d.action ?? ''), String(d.event_seq ?? ''));
+                    const joinedAids = this._joinedMemberAidsFromPayload(d);
+                    const isSelfJoining = joinedAids.includes(this._aid ?? '') && (action === 'joined' || action === 'invite_code_used');
+                    if (isSelfJoining || (action === 'joined' || action === 'invite_code_used')) {
+                        // open/invite_code 群：所有在线成员都参与延迟轮换
+                        // 新成员自己延迟更长，优先让其他在线成员先轮换
+                        const triggerId = this._membershipRotationTriggerId(groupId, d);
+                        if (!isSelfJoining) {
+                            this._safeAsync(this._maybeBackfillKeyToJoinedMember(groupId, d, triggerId));
+                        }
+                        if (expectedEpoch !== null) {
+                            const delay = isSelfJoining ? AUNClient._SELF_JOIN_ROTATION_DELAY_MS : undefined;
+                            this._safeAsync(this._delayedRotateAfterJoin(groupId, triggerId, expectedEpoch, true, delay));
+                        }
                     }
                     else {
-                        this._safeAsync(this._maybeLeadRotateGroupEpoch(groupId, this._membershipRotationTriggerId(groupId, d), expectedEpoch));
+                        if (expectedEpoch === null) {
+                            const triggerId = this._membershipRotationTriggerId(groupId, d);
+                            this._safeAsync(this._maybeBackfillKeyToJoinedMember(groupId, d, triggerId));
+                        }
+                        else {
+                            this._safeAsync(this._maybeLeadRotateGroupEpoch(groupId, this._membershipRotationTriggerId(groupId, d), expectedEpoch));
+                        }
                     }
                 }
             }
@@ -1520,6 +1538,107 @@ export class AUNClient {
             await this._dispatcher.publish('group.changed', data);
         }
     }
+    /**
+     * 处理 event/group.state_committed：验证 state_hash 链并更新本地存储。
+     * 当 prev_state_hash 与本地不连续时回源 group.get_state，并对回源数据做 hash 验证。
+     */
+    async _onGroupStateCommitted(data) {
+        if (!isJsonObject(data))
+            return;
+        const d = data;
+        const groupId = String(d.group_id ?? '').trim();
+        if (!groupId)
+            return;
+        // 提交者签名验证
+        const cs = d.client_signature;
+        if (cs && isJsonObject(cs)) {
+            const verified = await this._verifyEventSignature(d, cs);
+            if (verified === false) {
+                console.warn('[aun_core] state_committed 提交者签名验证失败 group=%s', groupId);
+                return;
+            }
+            d._verified = verified;
+        }
+        const stateVersion = Number(d.state_version ?? 0);
+        const stateHash = String(d.state_hash ?? '').trim();
+        const prevStateHash = String(d.prev_state_hash ?? '').trim();
+        const keyEpoch = Number(d.key_epoch ?? 0);
+        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
+            ? await loadFn.call(this._keystore, groupId)
+            : null;
+        if (localState && localState.state_hash && localState.state_hash !== prevStateHash) {
+            console.warn('[aun_core] state_hash 链不连续 group=%s local_sv=%d event_sv=%d', groupId, localState.state_version, stateVersion);
+            // 回源同步
+            try {
+                const serverState = await this._transport.call('group.get_state', { group_id: groupId });
+                if (serverState && typeof serverState.state_version !== 'undefined') {
+                    const sv = Number(serverState.state_version);
+                    const sHash = String(serverState.state_hash ?? '');
+                    const sEpoch = Number(serverState.key_epoch ?? 0);
+                    const sMembersJson = String(serverState.membership_snapshot ?? '');
+                    const sPolicyJson = String(serverState.policy_snapshot ?? '');
+                    const sPrev = String(serverState.prev_state_hash ?? '');
+                    // 回源也做 hash 验证
+                    if (sMembersJson && sHash) {
+                        const sMembers = sMembersJson ? JSON.parse(sMembersJson) : [];
+                        const sPolicy = sPolicyJson ? JSON.parse(sPolicyJson) : {};
+                        const computed = await computeStateHash({
+                            groupId, stateVersion: sv, keyEpoch: sEpoch,
+                            members: sMembers, policy: sPolicy, prevStateHash: sPrev,
+                        });
+                        if (computed !== sHash) {
+                            console.warn('[aun_core] 回源 state_hash 验证失败 group=%s sv=%d expected=%s got=%s', groupId, sv, sHash, computed);
+                            return;
+                        }
+                    }
+                    const saveFn = this._keystore.saveGroupState;
+                    if (saveFn) {
+                        await saveFn.call(this._keystore, groupId, {
+                            group_id: groupId,
+                            state_version: sv,
+                            state_hash: sHash,
+                            key_epoch: sEpoch,
+                            membership_json: sMembersJson || membershipSnapshot,
+                            policy_json: sPolicyJson || policySnapshot,
+                            updated_at: Date.now(),
+                        });
+                    }
+                }
+            }
+            catch (exc) {
+                console.warn('[aun_core] state 回源失败 group=%s:', groupId, exc);
+            }
+            return;
+        }
+        // 2. 本地重算验证
+        const members = membershipSnapshot ? JSON.parse(membershipSnapshot) : [];
+        const policy = policySnapshot ? JSON.parse(policySnapshot) : {};
+        const computed = await computeStateHash({
+            groupId, stateVersion, keyEpoch,
+            members, policy, prevStateHash,
+        });
+        if (computed !== stateHash) {
+            console.warn('[aun_core] state_hash 重算不匹配 group=%s sv=%d expected=%s got=%s', groupId, stateVersion, stateHash, computed);
+            return;
+        }
+        // 3. 更新本地存储
+        const saveFn = this._keystore.saveGroupState;
+        if (saveFn) {
+            await saveFn.call(this._keystore, groupId, {
+                group_id: groupId,
+                state_version: stateVersion,
+                state_hash: stateHash,
+                key_epoch: keyEpoch,
+                membership_json: membershipSnapshot,
+                policy_json: policySnapshot,
+                updated_at: Date.now(),
+            });
+        }
+    }
     /**
      * 群组解散后清理本地状态：
      * - keystore 中的 epoch key 数据
@@ -1624,50 +1743,60 @@ export class AUNClient {
         if (!this._p2pSynced) {
             await this._lazySyncP2p();
         }
-        const recipientPrekeys = await this._fetchPeerPrekeys(toAid);
-        const selfSyncCopies = await this._buildSelfSyncCopies({
-            logicalToAid: toAid,
-            payload,
-            messageId,
-            timestamp,
-            protectedHeaders,
-        });
-        if (recipientPrekeys.length <= 1 && selfSyncCopies.length === 0) {
-            return await this._sendEncryptedSingle({
-                toAid,
-                payload,
-                messageId,
-                timestamp,
-                prekey: recipientPrekeys[0],
-                persistRequired,
-                protectedHeaders,
+        // 内部发送逻辑，refreshPeerMaterial=true 时强制清缓存重新拉取对端材料
+        const sendAttempt = async (refreshPeerMaterial = false) => {
+            const recipientPrekeys = refreshPeerMaterial
+                ? await this._refreshPeerPrekeys(toAid)
+                : await this._fetchPeerPrekeys(toAid);
+            const selfSyncCopies = await this._buildSelfSyncCopies({
+                logicalToAid: toAid, payload, messageId, timestamp, protectedHeaders,
             });
-        }
-        const recipientCopies = await this._buildRecipientDeviceCopies({
-            toAid,
-            payload,
-            messageId,
-            timestamp,
-            prekeys: recipientPrekeys,
-            protectedHeaders,
-        });
-        const sendParams = {
-            to: toAid,
-            payload: {
+            // 多设备过滤：只保留有有效 device_id 的可路由 prekey，
+            // 占位符 PREKEY_FALLBACK_DEVICE_ID 表示服务端未分配真实设备 ID，不可用于多设备路由
+            const routablePrekeys = recipientPrekeys.filter(pk => {
+                const did = String(pk.device_id ?? '').trim();
+                return did && did !== PREKEY_FALLBACK_DEVICE_ID;
+            });
+            const canUseMultiDevice = routablePrekeys.length > 0
+                && (routablePrekeys.length > 1 || selfSyncCopies.length > 0);
+            if (!canUseMultiDevice) {
+                return await this._sendEncryptedSingle({
+                    toAid, payload, messageId, timestamp,
+                    prekey: routablePrekeys[0] ?? recipientPrekeys[0],
+                    persistRequired, protectedHeaders,
+                });
+            }
+            const recipientCopies = await this._buildRecipientDeviceCopies({
+                toAid, payload, messageId, timestamp,
+                prekeys: routablePrekeys, protectedHeaders,
+            });
+            const sendParams = {
+                to: toAid,
+                payload: {
+                    type: 'e2ee.multi_device',
+                    logical_message_id: messageId,
+                    recipient_copies: recipientCopies,
+                    self_copies: selfSyncCopies,
+                },
                 type: 'e2ee.multi_device',
-                logical_message_id: messageId,
-                recipient_copies: recipientCopies,
-                self_copies: selfSyncCopies,
-            },
-            type: 'e2ee.multi_device',
-            encrypted: true,
-            message_id: messageId,
-            timestamp,
+                encrypted: true,
+                message_id: messageId,
+                timestamp,
+            };
+            if (persistRequired)
+                sendParams.persist_required = true;
+            return this._transport.call('message.send', sendParams);
         };
-        if (persistRequired) {
-            sendParams.persist_required = true;
+        // 首次尝试（使用缓存）；若对端证书/prekey 过期导致指纹不匹配，清缓存后重试一次
+        try {
+            return await sendAttempt(false);
         }
-        return this._transport.call('message.send', sendParams);
+        catch (exc) {
+            if (!isRetryablePeerMaterialError(exc))
+                throw exc;
+            console.warn(`[aun_core] peer cert/prekey mismatch for ${toAid}, refreshing and retrying once`);
+        }
+        return await sendAttempt(true);
     }
     /**
      * 首次发送 P2P 消息前懒拉取历史消息，同步 seqTracker 避免空洞。
@@ -1731,6 +1860,8 @@ export class AUNClient {
         const certCache = new Map();
         for (const prekey of normalizePeerPrekeys(opts.prekeys)) {
             const deviceId = String(prekey.device_id ?? '').trim();
+            if (!deviceId)
+                continue; // 跳过无 device_id 的 prekey，防止构造不可路由的多设备副本
             const peerCertFingerprint = String(prekey.cert_fingerprint ?? '').trim().toLowerCase();
             const cacheKey = peerCertFingerprint || '__default__';
             let peerCertPem = certCache.get(cacheKey);
@@ -1796,7 +1927,15 @@ export class AUNClient {
             if (deviceId && deviceId === this._deviceId) {
                 continue;
             }
-            const peerCertPem = await this._resolveSelfCopyPeerCert(String(prekey.cert_fingerprint ?? '').trim().toLowerCase() || undefined);
+            let peerCertPem;
+            try {
+                peerCertPem = await this._resolveSelfCopyPeerCert(String(prekey.cert_fingerprint ?? '').trim().toLowerCase() || undefined);
+            }
+            catch (e) {
+                // 旧设备的 prekey 可能携带已轮换的证书指纹，跳过该设备的自同步副本
+                console.warn(`self-sync 跳过设备 ${deviceId}: 证书解析失败 (${e})，可能是旧 prekey`);
+                continue;
+            }
             const [envelope, encryptResult] = await this._encryptCopyPayload({
                 logicalToAid: opts.logicalToAid,
                 payload: opts.payload,
@@ -2164,7 +2303,7 @@ export class AUNClient {
             console.warn(`[aun_core] group ${groupId} epoch precheck failed: ${formatCaughtError(exc)}`);
             return;
         }
-        let serverEpoch = Number(epochResult.epoch ?? 0);
+        let serverEpoch = Number(epochResult.committed_epoch ?? epochResult.epoch ?? 0);
         if (!Number.isFinite(serverEpoch))
             return;
         const pending = isJsonObject(epochResult.pending_rotation) ? epochResult.pending_rotation : null;
@@ -2180,7 +2319,7 @@ export class AUNClient {
         let effectiveLocalEpoch = initialLocalEpoch;
         if (serverEpoch === 0 && effectiveLocalEpoch === 1) {
             epochResult = await this._recoverInitialGroupEpochIfNeeded(groupId, effectiveLocalEpoch, epochResult);
-            serverEpoch = Number(epochResult.epoch ?? 0);
+            serverEpoch = Number(epochResult.committed_epoch ?? epochResult.epoch ?? 0);
             if (serverEpoch === 0) {
                 throw new StateError(`group ${groupId} initial epoch sync has not completed; refuse to send with local epoch 1 while server epoch is 0`);
             }
@@ -2192,7 +2331,9 @@ export class AUNClient {
             while (Date.now() < waitDeadline) {
                 await new Promise(resolve => setTimeout(resolve, 150));
                 const refreshed = await this.call('group.e2ee.get_epoch', { group_id: groupId });
-                const refreshedEpoch = isJsonObject(refreshed) ? Number(refreshed.epoch ?? 0) : 0;
+                const refreshedEpoch = isJsonObject(refreshed)
+                    ? Number(refreshed.committed_epoch ?? refreshed.epoch ?? 0)
+                    : 0;
                 const currentLocal = await this._groupE2ee.currentEpoch(groupId);
                 if (Number.isFinite(refreshedEpoch) && refreshedEpoch > serverEpoch) {
                     epochResult = refreshed;
@@ -2208,7 +2349,7 @@ export class AUNClient {
             }
         }
         console.warn(`[aun_core] group ${groupId} local epoch=${effectiveLocalEpoch} < server epoch=${serverEpoch}; requesting key recovery`);
-        await this._requestGroupKeyFromCandidates(groupId, serverEpoch, epochResult);
+        await this._recoverGroupEpochKey(groupId, serverEpoch, '', 5000);
         const deadline = Date.now() + 5000;
         while (Date.now() < deadline) {
             await new Promise(resolve => setTimeout(resolve, 150));
@@ -2281,8 +2422,23 @@ export class AUNClient {
     async _ensureCommittedGroupSecretForSend(groupId, committedEpoch, epochResult) {
         if (committedEpoch <= 0)
             return committedEpoch;
-        const secretData = await this._groupE2ee.loadSecret(groupId, committedEpoch);
-        const committedRotation = isJsonObject(epochResult.committed_rotation) ? epochResult.committed_rotation : null;
+        let secretData = await this._groupE2ee.loadSecret(groupId, committedEpoch);
+        let committedRotation = isJsonObject(epochResult.committed_rotation) ? epochResult.committed_rotation : null;
+        if (await this._committedRotationMembershipGap(groupId, committedEpoch, committedRotation)) {
+            const allowMember = await this._groupAllowsMemberEpochRotation(groupId);
+            console.warn(`[aun_core] 群 ${groupId} committed epoch ${committedEpoch} 的成员快照与当前成员不一致，触发成员变更轮换修复`);
+            await this._maybeLeadRotateGroupEpoch(groupId, `${groupId}:committed_membership_gap:aid:${this._aid}:epoch:${committedEpoch}`, committedEpoch, allowMember);
+            const refreshed = await this._committedGroupEpochState(groupId);
+            const refreshedCommittedEpoch = Number(refreshed.committed_epoch ?? refreshed.epoch ?? committedEpoch);
+            if (Number.isFinite(refreshedCommittedEpoch) && refreshedCommittedEpoch > committedEpoch) {
+                committedEpoch = refreshedCommittedEpoch;
+                committedRotation = isJsonObject(refreshed.committed_rotation) ? refreshed.committed_rotation : null;
+                secretData = await this._groupE2ee.loadSecret(groupId, committedEpoch);
+            }
+            if (await this._committedRotationMembershipGap(groupId, committedEpoch, committedRotation)) {
+                throw new StateError(`group ${groupId} committed membership is stale at epoch ${committedEpoch}; key rotation repair has not completed`);
+            }
+        }
         if (this._groupSecretMatchesCommittedRotation(secretData, committedRotation)) {
             return committedEpoch;
         }
@@ -2303,6 +2459,45 @@ export class AUNClient {
         }
         return committedEpoch;
     }
+    async _committedRotationMembershipGap(groupId, committedEpoch, committedRotation) {
+        if (!this._aid || committedEpoch <= 0 || !committedRotation)
+            return false;
+        const expectedMembers = Array.isArray(committedRotation.expected_members)
+            ? committedRotation.expected_members.map((item) => String(item ?? '').trim()).filter(Boolean).sort()
+            : [];
+        if (expectedMembers.length === 0)
+            return false;
+        try {
+            const membersResult = await this.call('group.get_members', { group_id: groupId });
+            const rawMembers = isJsonObject(membersResult)
+                ? (Array.isArray(membersResult.members) ? membersResult.members : membersResult.items)
+                : [];
+            if (!Array.isArray(rawMembers))
+                return false;
+            const activeMembers = rawMembers
+                .filter((item) => isJsonObject(item))
+                .map((item) => ({
+                aid: String(item.aid ?? '').trim(),
+                status: String(item.status ?? 'active').trim().toLowerCase(),
+            }))
+                .filter((item) => item.aid && ['', 'active'].includes(item.status))
+                .map((item) => item.aid)
+                .sort();
+            if (!activeMembers.includes(this._aid) || activeMembers.length === 0)
+                return false;
+            if (activeMembers.join('\n') !== expectedMembers.join('\n')) {
+                const missing = activeMembers.filter((aid) => !expectedMembers.includes(aid));
+                const extra = expectedMembers.filter((aid) => !activeMembers.includes(aid));
+                console.info(`[aun_core] 群 ${groupId} committed membership gap: epoch=${committedEpoch} missing=${JSON.stringify(missing)} extra=${JSON.stringify(extra)}`);
+                return true;
+            }
+            return false;
+        }
+        catch (exc) {
+            console.debug(`[aun_core] 查询当前成员失败，无法判断 committed membership gap: group=${groupId} err=${formatCaughtError(exc)}`);
+            return false;
+        }
+    }
     // ── E2EE 自动解密 ────────────────────────────────
     /** 解密单条 P2P 消息 */
     async _decryptSingleMessage(message) {
@@ -2348,19 +2543,25 @@ export class AUNClient {
             if (payload !== null
                 && payload.type === 'e2ee.encrypted'
                 && (msg.encrypted === true || !('encrypted' in msg))) {
-                const fromAid = (msg.from ?? '');
-                const senderCertFingerprint = String(payload.sender_cert_fingerprint ?? payload.aad?.sender_cert_fingerprint ?? '').trim().toLowerCase();
-                if (fromAid) {
-                    const certReady = await this._ensureSenderCertCached(fromAid, senderCertFingerprint || undefined);
-                    if (!certReady) {
-                        console.warn(`无法获取发送方 ${fromAid} 的证书，跳过解密`);
-                        continue;
+                try {
+                    const fromAid = (msg.from ?? '');
+                    const senderCertFingerprint = String(payload.sender_cert_fingerprint ?? payload.aad?.sender_cert_fingerprint ?? '').trim().toLowerCase();
+                    if (fromAid) {
+                        const certReady = await this._ensureSenderCertCached(fromAid, senderCertFingerprint || undefined);
+                        if (!certReady) {
+                            console.warn('[aun_core] 无法获取发送方 %s 的证书，跳过解密', fromAid);
+                            continue;
+                        }
+                    }
+                    // Pull 场景：跳过防重放和 timestamp 窗口检查（push 已处理过的消息仍需要能解密）
+                    const decrypted = await this._e2ee.decryptMessage(msg, { skipReplay: true });
+                    if (decrypted !== null) {
+                        result.push(decrypted);
                     }
                 }
-                // Pull 场景：跳过防重放和 timestamp 窗口检查（push 已处理过的消息仍需要能解密）
-                const decrypted = await this._e2ee.decryptMessage(msg, { skipReplay: true });
-                if (decrypted !== null) {
-                    result.push(decrypted);
+                catch (decryptExc) {
+                    console.warn('[aun_core] pull 消息解密失败，跳过: from=%s mid=%s err=%s', (msg.from ?? ''), mid, decryptExc instanceof Error ? decryptExc.message : String(decryptExc));
+                    continue;
                 }
             }
             else {
@@ -2431,7 +2632,251 @@ export class AUNClient {
         this._groupEpochRecoveryInflight.set(key, promise);
         return promise;
     }
+    static _extractGroupJoinMode(payload) {
+        if (!isJsonObject(payload))
+            return '';
+        for (const key of ['join_mode', 'mode']) {
+            const v = String(payload[key] ?? '').trim().toLowerCase();
+            if (v)
+                return v;
+        }
+        for (const key of ['join_requirements', 'join']) {
+            const nested = payload[key];
+            if (isJsonObject(nested)) {
+                for (const nk of ['mode', 'join_mode']) {
+                    const v = String(nested[nk] ?? '').trim().toLowerCase();
+                    if (v)
+                        return v;
+                }
+            }
+        }
+        if (isJsonObject(payload.group)) {
+            const v = AUNClient._extractGroupJoinMode(payload.group);
+            if (v)
+                return v;
+        }
+        const settings = payload.settings;
+        if (isJsonObject(settings)) {
+            for (const key of ['join.mode', 'join_mode', 'mode']) {
+                const v = String(settings[key] ?? '').trim().toLowerCase();
+                if (v)
+                    return v;
+            }
+        }
+        if (Array.isArray(settings)) {
+            for (const item of settings) {
+                if (!isJsonObject(item))
+                    continue;
+                const k = String(item.key ?? item.name ?? '').trim().toLowerCase();
+                if (k === 'join.mode' || k === 'join_mode' || k === 'mode') {
+                    const v = String(item.value ?? '').trim().toLowerCase();
+                    if (v)
+                        return v;
+                }
+            }
+        }
+        return '';
+    }
+    static _joinModeAllowsMemberEpochRotation(mode) {
+        const m = mode.trim().toLowerCase();
+        return m === 'open' || m === 'invite_only' || m === 'invite_code';
+    }
+    async _groupAllowsMemberEpochRotation(groupId) {
+        try {
+            const resp = await this.call('group.get_join_requirements', { group_id: groupId });
+            const mode = AUNClient._extractGroupJoinMode(resp);
+            if (mode)
+                return AUNClient._joinModeAllowsMemberEpochRotation(mode);
+        }
+        catch { /* best effort */ }
+        try {
+            const resp = await this.call('group.get_settings', { group_id: groupId, keys: ['join.mode'] });
+            const mode = AUNClient._extractGroupJoinMode(resp);
+            if (mode)
+                return AUNClient._joinModeAllowsMemberEpochRotation(mode);
+        }
+        catch { /* best effort */ }
+        try {
+            const resp = await this.call('group.get', { group_id: groupId });
+            const mode = AUNClient._extractGroupJoinMode(resp);
+            if (mode)
+                return AUNClient._joinModeAllowsMemberEpochRotation(mode);
+        }
+        catch { /* best effort */ }
+        return false;
+    }
+    /** 尝试从服务端拉取 ECIES 加密的 epoch key 并解密存入 keystore */
+    async _tryRecoverEpochKeyFromServer(groupId, epoch) {
+        try {
+            const params = { group_id: groupId };
+            if (epoch > 0)
+                params.epoch = epoch;
+            const result = await this.call('group.e2ee.get_epoch_key', params);
+            if (!isJsonObject(result))
+                return false;
+            const encryptedB64 = result.encrypted_key;
+            if (!encryptedB64 || typeof encryptedB64 !== 'string')
+                return false;
+            const serverEpoch = Number(result.epoch ?? epoch);
+            const encryptedBytes = base64ToUint8(encryptedB64);
+            // 用自己的 AID 私钥 ECIES 解密
+            const myAid = this._aid || '';
+            const keyPair = await this._keystore.loadKeyPair(myAid);
+            if (!keyPair?.private_key_pem)
+                return false;
+            const { eciesDecrypt } = await import('./e2ee-group.js');
+            const groupSecret = await eciesDecrypt(keyPair.private_key_pem, encryptedBytes);
+            if (!groupSecret || groupSecret.length !== 32)
+                return false;
+            // 获取成员列表和 committed_rotation 用于 commitment / epoch_chain 验证
+            let memberAids = [];
+            let committedRotation = null;
+            let epochChain = '';
+            try {
+                const epochInfo = await this.call('group.e2ee.get_epoch', { group_id: groupId });
+                if (isJsonObject(epochInfo)) {
+                    if (Array.isArray(epochInfo.members)) {
+                        memberAids = epochInfo.members
+                            .map((m) => {
+                            if (typeof m === 'string')
+                                return m;
+                            if (isJsonObject(m) && typeof m.aid === 'string')
+                                return m.aid;
+                            return '';
+                        })
+                            .filter((s) => s.length > 0);
+                    }
+                    if (isJsonObject(epochInfo.committed_rotation)) {
+                        committedRotation = epochInfo.committed_rotation;
+                        const rawChain = String(committedRotation.epoch_chain ?? '').trim();
+                        if (rawChain)
+                            epochChain = rawChain;
+                        if (Array.isArray(committedRotation.expected_members) && committedRotation.expected_members.length > 0) {
+                            memberAids = committedRotation.expected_members
+                                .map(item => String(item ?? '').trim())
+                                .filter(s => s.length > 0);
+                        }
+                    }
+                }
+            }
+            catch { /* best effort */ }
+            if (memberAids.length === 0)
+                return false;
+            const commitment = await computeMembershipCommitment(memberAids, serverEpoch, groupId, groupSecret);
+            let epochChainUnverified = null;
+            let epochChainUnverifiedReason = null;
+            if (committedRotation) {
+                const committedEpoch = Number(committedRotation.target_epoch ?? serverEpoch);
+                const committedCommitment = String(committedRotation.key_commitment ?? '').trim();
+                if (committedEpoch === serverEpoch && committedCommitment && committedCommitment !== commitment) {
+                    return false;
+                }
+                if (epochChain && committedEpoch === serverEpoch) {
+                    let rotatorAid = '';
+                    for (const key of ['rotated_by', 'lease_owner', 'committed_by']) {
+                        const v = String(committedRotation[key] ?? '').trim();
+                        if (v) {
+                            rotatorAid = v;
+                            break;
+                        }
+                    }
+                    const prevData = await this._groupE2ee.loadSecret(groupId, serverEpoch - 1);
+                    const prevChain = String(prevData?.epoch_chain ?? '').trim();
+                    if (prevChain && rotatorAid) {
+                        if (!await verifyEpochChain(epochChain, prevChain, serverEpoch, commitment, rotatorAid)) {
+                            return false;
+                        }
+                        epochChainUnverified = false;
+                    }
+                    else {
+                        epochChainUnverified = true;
+                        epochChainUnverifiedReason = prevChain ? 'missing_rotator_aid' : 'missing_prev_chain';
+                    }
+                }
+            }
+            await storeGroupSecretEpoch(this._keystore, myAid, groupId, serverEpoch, groupSecret, commitment, memberAids, epochChain || undefined, '', epochChainUnverified, epochChainUnverifiedReason);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** 为每个成员用其 AID 证书公钥 ECIES 加密 group_secret */
+    async _buildEpochEncryptedKeys(info, memberAids, targetEpoch, groupId) {
+        try {
+            const { eciesEncrypt } = await import('./e2ee-group.js');
+            // 从 distribution payload 中提取 group_secret
+            let groupSecretBytes = null;
+            const distributions = Array.isArray(info.distributions) ? info.distributions : [];
+            for (const dist of distributions) {
+                if (isJsonObject(dist) && isJsonObject(dist.payload)) {
+                    const gsB64 = dist.payload.group_secret;
+                    if (typeof gsB64 === 'string' && gsB64.length > 0) {
+                        groupSecretBytes = base64ToUint8(gsB64);
+                        break;
+                    }
+                }
+            }
+            if (!groupSecretBytes) {
+                const loaded = await this._groupE2ee.loadSecret(groupId, targetEpoch);
+                if (loaded?.secret) {
+                    groupSecretBytes = loaded.secret;
+                }
+                else {
+                    return {};
+                }
+            }
+            const encryptedKeys = {};
+            for (const aid of memberAids) {
+                try {
+                    const certPem = await this._fetchPeerCert(aid);
+                    // 从 PEM 证书提取 EC 公钥（未压缩 65 字节）
+                    const pubkeyBytes = await this._extractEcPubkeyFromCert(certPem);
+                    if (!pubkeyBytes)
+                        continue;
+                    const ciphertext = await eciesEncrypt(pubkeyBytes, groupSecretBytes);
+                    encryptedKeys[aid] = uint8ToBase64(ciphertext);
+                }
+                catch {
+                    continue;
+                }
+            }
+            return encryptedKeys;
+        }
+        catch {
+            return {};
+        }
+    }
+    /** 从 PEM 证书中提取 EC 公钥的未压缩字节（65B） */
+    async _extractEcPubkeyFromCert(certPem) {
+        try {
+            // 导入证书公钥为 ECDSA CryptoKey（exportable）
+            const pubKey = await importCertPublicKeyEcdsa(certPem);
+            // 导出 JWK 获取 x, y 坐标
+            const jwk = await crypto.subtle.exportKey('jwk', pubKey);
+            if (jwk.crv !== 'P-256' || !jwk.x || !jwk.y)
+                return null;
+            // base64url → 标准 base64 → Uint8Array
+            const xBytes = base64ToUint8(jwk.x.replace(/-/g, '+').replace(/_/g, '/'));
+            const yBytes = base64ToUint8(jwk.y.replace(/-/g, '+').replace(/_/g, '/'));
+            const result = new Uint8Array(65);
+            result[0] = 0x04;
+            result.set(xBytes, 1);
+            result.set(yBytes, 33);
+            return result;
+        }
+        catch {
+            return null;
+        }
+    }
     async _doRecoverGroupEpochKey(groupId, epoch, senderAid, timeoutMs) {
+        // 仅 open / invite_code 群允许从服务端拉取 ECIES 加密的 epoch key
+        if (await this._groupAllowsMemberEpochRotation(groupId)) {
+            if (await this._tryRecoverEpochKeyFromServer(groupId, epoch)) {
+                this._scheduleRetryPendingDecryptMsgs(groupId);
+                return true;
+            }
+        }
         let epochResult = { epoch };
         try {
             const raw = await this.call('group.e2ee.get_epoch', { group_id: groupId });
@@ -2445,7 +2890,30 @@ export class AUNClient {
             const current = Array.isArray(epochResult.recovery_candidates) ? epochResult.recovery_candidates : [];
             epochResult.recovery_candidates = [senderAid, ...current];
         }
-        await this._requestGroupKeyFromCandidates(groupId, epoch, epochResult);
+        // 在线优先恢复：先查在线成员列表，只向在线成员发送密钥请求
+        let onlineAids = null;
+        try {
+            const onlineResp = await this.call('group.get_online_members', { group_id: groupId });
+            if (isJsonObject(onlineResp)) {
+                const rawMembers = Array.isArray(onlineResp.members) ? onlineResp.members
+                    : Array.isArray(onlineResp.items) ? onlineResp.items : [];
+                onlineAids = rawMembers
+                    .filter((m) => isJsonObject(m) && m.online === true && String(m.aid ?? '') !== this._aid)
+                    .map(m => String(m.aid ?? ''));
+            }
+        }
+        catch {
+            // get_online_members 不可用时回退全量候选
+        }
+        if (onlineAids !== null) {
+            if (onlineAids.length === 0) {
+                return false;
+            }
+            await this._requestGroupKeyFromOnline(groupId, epoch, onlineAids, epochResult);
+        }
+        else {
+            await this._requestGroupKeyFromCandidates(groupId, epoch, epochResult);
+        }
         const deadline = Date.now() + timeoutMs;
         while (Date.now() < deadline) {
             await new Promise(resolve => setTimeout(resolve, 150));
@@ -2461,6 +2929,22 @@ export class AUNClient {
             this._scheduleRetryPendingDecryptMsgs(groupId);
         return ready;
     }
+    /** 只向在线成员发送密钥恢复请求 */
+    async _requestGroupKeyFromOnline(groupId, epoch, onlineAids, epochResult) {
+        const candidates = await this._groupKeyRecoveryCandidates(groupId, epochResult);
+        const ordered = [];
+        for (const aid of candidates) {
+            if (onlineAids.includes(aid) && !ordered.includes(aid))
+                ordered.push(aid);
+        }
+        for (const aid of onlineAids) {
+            if (!ordered.includes(aid))
+                ordered.push(aid);
+        }
+        for (const aid of ordered) {
+            await this._requestGroupKeyFrom(groupId, aid, epoch);
+        }
+    }
     async _groupEpochSecretReadyForRecovery(groupId, epoch, secret) {
         if (!isJsonObject(secret))
             return false;
@@ -2588,19 +3072,27 @@ export class AUNClient {
                 message_id: thoughtId,
                 payload: payload ?? {},
                 created_at: Number(item.created_at ?? 0),
+                ...(isJsonObject(item.context) ? { context: item.context } : {}),
             };
             const decrypted = await this._decryptGroupMessage(message, { skipReplay: true });
+            let decryptFailed = false;
             if (payload?.type === 'e2ee.group_encrypted' && groupId && !decrypted.e2ee) {
-                this._enqueuePendingDecrypt(groupId, message);
-                continue;
+                decryptFailed = true;
+                // 安全网：触发 epoch key 恢复（内部有去重，重复调用安全）
+                const epoch = Number(payload.epoch ?? 0);
+                if (epoch > 0) {
+                    this._recoverGroupEpochKey(groupId, epoch, senderAid, 5000).catch(() => { });
+                }
             }
             const thought = {
                 thought_id: thoughtId,
                 message_id: thoughtId,
-                payload: decrypted.payload,
+                payload: decryptFailed ? (payload ?? {}) : decrypted.payload,
                 created_at: item.created_at,
                 e2ee: decrypted.e2ee,
             };
+            if (decryptFailed)
+                thought.decrypt_failed = true;
             if ('context' in item)
                 thought.context = item.context;
             thoughts.push(thought);
@@ -2631,19 +3123,26 @@ export class AUNClient {
                 encrypted: item.encrypted !== false,
                 timestamp: Number(item.created_at ?? 0),
             };
+            if (isJsonObject(item.context))
+                message.context = item.context;
             let decrypted = message;
+            let decryptFailed = false;
             if (payload?.type === 'e2ee.encrypted') {
                 const senderCertFingerprint = String(payload.sender_cert_fingerprint ?? payload.aad?.sender_cert_fingerprint ?? '').trim().toLowerCase();
                 if (fromAid) {
                     const certReady = await this._ensureSenderCertCached(fromAid, senderCertFingerprint || undefined);
                     if (!certReady) {
-                        console.warn('[aun_core] 无法获取发送方证书，跳过 message.thought.get 解密:', fromAid);
-                        continue;
+                        console.warn('[aun_core] p2p.thought.decrypt failed: 无法获取发送方证书 thought_id=' + thoughtId + ' from=' + fromAid);
+                        decryptFailed = true;
                     }
                 }
-                decrypted = await this._e2ee.decryptMessage(message, { skipReplay: true });
-                if (decrypted === null || (isJsonObject(decrypted.payload) && decrypted.payload.type === 'e2ee.encrypted')) {
-                    continue;
+                if (!decryptFailed) {
+                    decrypted = await this._e2ee.decryptMessage(message, { skipReplay: true });
+                    if (decrypted === null || (isJsonObject(decrypted.payload) && decrypted.payload.type === 'e2ee.encrypted')) {
+                        console.warn('[aun_core] p2p.thought.decrypt failed thought_id=' + thoughtId);
+                        decryptFailed = true;
+                        decrypted = message;
+                    }
                 }
             }
             const thought = {
@@ -2655,6 +3154,8 @@ export class AUNClient {
                 created_at: item.created_at,
                 e2ee: decrypted.e2ee,
             };
+            if (decryptFailed)
+                thought.decrypt_failed = true;
             if ('context' in item)
                 thought.context = item.context;
             thoughts.push(thought);
@@ -2718,6 +3219,11 @@ export class AUNClient {
             result = await this._groupE2ee.handleIncoming(actualPayload);
             if (result === 'distribution') {
                 await this._discardGroupDistributionIfStale(actualPayload);
+                // 收到 epoch key 说明该群有活动，触发惰性同步建立 seq 基线
+                const distGroupId = actualPayload.group_id;
+                if (distGroupId && !this._groupSynced.has(distGroupId)) {
+                    this._lazySyncGroup(distGroupId).catch(() => { });
+                }
             }
         }
         catch (exc) {
@@ -2737,7 +3243,9 @@ export class AUNClient {
             const groupId = (actualPayload.group_id ?? '');
             const requester = (actualPayload.requester_aid ?? '');
             let members = await this._groupE2ee.getMemberAids(groupId);
-            // 请求者不在本地成员列表时，回源查询服务端最新成员列表
+            // 请求者不在本地成员列表时，回源查询服务端最新成员列表（仅用于判断是否响应，不写回本地存储）
+            // P0 历史隔离：不再将回源结果更新到当前 epoch 的 member_aids/commitment，
+            // 避免用当前成员覆盖已固化的历史 epoch 快照。
             if (requester && !members.includes(requester)) {
                 try {
                     const membersResult = await this.call('group.get_members', { group_id: groupId });
@@ -2745,15 +3253,6 @@ export class AUNClient {
                         ? membersResult.members
                         : [];
                     members = memberList.map(m => String(m.aid ?? ''));
-                    // 更新本地当前 epoch 的 member_aids/commitment
-                    if (members.includes(requester)) {
-                        const secretData = await this._groupE2ee.loadSecret(groupId);
-                        if (secretData && this._aid) {
-                            const epoch = secretData.epoch;
-                            const commitment = await computeMembershipCommitment(members, epoch, groupId, secretData.secret);
-                            await storeGroupSecret(this._keystore, this._aid, groupId, epoch, secretData.secret, commitment, members);
-                        }
-                    }
                 }
                 catch (exc) {
                     console.warn(`群组 ${groupId} 成员列表回源失败:`, exc);
@@ -2906,7 +3405,7 @@ export class AUNClient {
             if (normalized.length > 0) {
                 this._peerPrekeysCache.set(peerAid, {
                     items: normalized.map((item) => ({ ...item })),
-                    expireAt: Date.now() / 1000 + 300,
+                    expireAt: Date.now() / 1000 + PEER_PREKEYS_CACHE_TTL,
                 });
                 this._e2ee.cachePrekey(peerAid, normalized[0]);
                 return normalized;
@@ -2920,7 +3419,7 @@ export class AUNClient {
             if (normalized.length > 0) {
                 this._peerPrekeysCache.set(peerAid, {
                     items: normalized.map((item) => ({ ...item })),
-                    expireAt: Date.now() / 1000 + 300,
+                    expireAt: Date.now() / 1000 + PEER_PREKEYS_CACHE_TTL,
                 });
                 this._e2ee.cachePrekey(peerAid, normalized[0]);
                 return normalized.map((item) => ({ ...item }));
@@ -2931,6 +3430,25 @@ export class AUNClient {
         }
         return [];
     }
+    /** 清除对端 prekey 的双层缓存（_peerPrekeysCache + e2ee 内部缓存） */
+    _invalidatePeerPrekeyCache(peerAid) {
+        this._peerPrekeysCache.delete(peerAid);
+        this._e2ee.invalidatePrekeyCache(peerAid);
+    }
+    /** 清除对端证书缓存（精确匹配 aid 或 aid# 前缀的所有条目） */
+    _clearPeerCertCache(peerAid) {
+        for (const cacheKey of this._certCache.keys()) {
+            if (cacheKey === peerAid || cacheKey.startsWith(`${peerAid}#`)) {
+                this._certCache.delete(cacheKey);
+            }
+        }
+    }
+    /** 清除对端所有缓存后重新拉取 prekey（用于指纹不匹配时的强制刷新） */
+    async _refreshPeerPrekeys(peerAid) {
+        this._invalidatePeerPrekeyCache(peerAid);
+        this._clearPeerCertCache(peerAid);
+        return await this._fetchPeerPrekeys(peerAid);
+    }
     /** 获取对方 prekey（兼容接口，优先返回第一条 device prekey）。 */
     async _fetchPeerPrekey(peerAid) {
         const cachedList = this._peerPrekeysCache.get(peerAid);
@@ -3001,7 +3519,11 @@ export class AUNClient {
      * 零信任要求：不直接信任 keystore 中可能由恶意服务端注入的证书。
      */
     _getVerifiedPeerCert(aid, certFingerprint) {
-        const cached = this._certCache.get(certCacheKey(aid, certFingerprint));
+        let cached = this._certCache.get(certCacheKey(aid, certFingerprint));
+        // 带 fingerprint 查不到时，降级用 aid 再查一次
+        if (!cached && certFingerprint) {
+            cached = this._certCache.get(certCacheKey(aid, undefined));
+        }
         const now = Date.now() / 1000;
         if (cached && now < cached.validatedAt + PEER_CERT_CACHE_TTL * 2) {
             return cached.certPem;
@@ -3173,8 +3695,17 @@ export class AUNClient {
                 if (Number.isFinite(epoch) && epoch > 0 && epoch <= committedEpoch) {
                     if (committedRotation && Number(committedRotation.target_epoch ?? committedEpoch) === epoch) {
                         const committedCommitment = String(committedRotation.key_commitment ?? '').trim();
-                        if (committedCommitment && commitment && committedCommitment !== commitment)
-                            return false;
+                        if (committedCommitment && commitment && committedCommitment !== commitment) {
+                            const expectedMembers = Array.isArray(committedRotation.expected_members)
+                                ? committedRotation.expected_members.map((item) => String(item ?? '').trim()).filter(Boolean)
+                                : [];
+                            if (this._aid && !expectedMembers.includes(this._aid)) {
+                                console.debug(`[aun_core] 放行 group key 分发：新成员恢复 commitment 不匹配属正常 group=${groupId} epoch=${epoch}`);
+                            }
+                            else {
+                                return false;
+                            }
+                        }
                     }
                     return true;
                 }
@@ -3243,8 +3774,17 @@ export class AUNClient {
             const committedRotation = isJsonObject(epochResult.committed_rotation) ? epochResult.committed_rotation : null;
             if (committedRotation && Number(committedRotation.target_epoch ?? committedEpoch) === epoch) {
                 const committedCommitment = String(committedRotation.key_commitment ?? '').trim();
-                if (committedCommitment && commitment && committedCommitment !== commitment)
-                    return false;
+                if (committedCommitment && commitment && committedCommitment !== commitment) {
+                    const expectedMembers = Array.isArray(committedRotation.expected_members)
+                        ? committedRotation.expected_members.map((item) => String(item ?? '').trim()).filter(Boolean)
+                        : [];
+                    if (this._aid && !expectedMembers.includes(this._aid)) {
+                        console.debug(`[aun_core] 放行 group key response：新成员恢复 commitment 不匹配属正常 group=${groupId} epoch=${epoch}`);
+                    }
+                    else {
+                        return false;
+                    }
+                }
             }
             return true;
         }
@@ -3351,7 +3891,15 @@ export class AUNClient {
                         await this._abortGroupRotation(activeRotationId, 'self_ack_failed');
                         return;
                     }
-                    const commitResult = await this.call('group.e2ee.commit_rotation', { rotation_id: activeRotationId });
+                    const commitParams2 = { rotation_id: activeRotationId };
+                    const createMembers = secretData.member_aids.length > 0 ? secretData.member_aids : (this._aid ? [this._aid] : []);
+                    const encKeys2 = await this._buildEpochEncryptedKeys({ distributions: [{ payload: { group_secret: uint8ToBase64(secretData.secret) } }] }, createMembers, 1, groupId);
+                    if (await this._groupAllowsMemberEpochRotation(groupId)) {
+                        if (encKeys2 && Object.keys(encKeys2).length > 0) {
+                            commitParams2.encrypted_keys = encKeys2;
+                        }
+                    }
+                    const commitResult = await this.call('group.e2ee.commit_rotation', commitParams2);
                     if (isJsonObject(commitResult) && commitResult.success === true) {
                         await storeGroupSecret(this._keystore, this._aid, groupId, 1, secretData.secret, secretData.commitment, secretData.member_aids, secretData.epoch_chain);
                         return;
@@ -3379,7 +3927,7 @@ export class AUNClient {
      * H21: 基于"排序最小 admin = leader"选举，其他 admin 走 jitter 兜底重试。
      * 避免所有剩余 admin 同时触发 `_rotateGroupEpoch` 造成 CAS 风暴。
      */
-    async _maybeLeadRotateGroupEpoch(groupId, triggerId = '', expectedEpoch = null) {
+    async _maybeLeadRotateGroupEpoch(groupId, triggerId = '', expectedEpoch = null, allowMember = false) {
         const myAid = this._aid;
         if (!myAid || this._closing || this._state !== 'connected')
             return;
@@ -3408,24 +3956,45 @@ export class AUNClient {
             if (!Array.isArray(rawList))
                 return;
             const admins = [];
+            const members = [];
             for (const m of rawList) {
                 if (!isJsonObject(m))
                     continue;
                 const role = String(m.role ?? '');
                 const aid = String(m.aid ?? '');
-                if (aid && (role === 'admin' || role === 'owner'))
+                if (!aid)
+                    continue;
+                if (role === 'admin' || role === 'owner') {
                     admins.push(aid);
+                }
+                else if (allowMember && role === 'member') {
+                    members.push(aid);
+                }
             }
-            if (admins.length === 0)
+            // 候选列表：admin/owner 排序在前，member 排序在后
+            let candidates = [...admins.sort(), ...members.sort()];
+            if (candidates.length === 0)
                 return;
-            admins.sort();
-            const leader = admins[0];
+            // 没有当前 epoch key 的成员不参与 leader 选举
+            if (expectedEpoch !== null && expectedEpoch > 0) {
+                const localSecret = await this._groupE2ee.loadSecret(groupId, expectedEpoch);
+                if (!localSecret) {
+                    const filtered = candidates.filter(c => c !== myAid);
+                    if (filtered.length > 0) {
+                        candidates = filtered;
+                    }
+                    else if (!allowMember) {
+                        return;
+                    }
+                }
+            }
+            const leader = candidates[0];
             if (leader === myAid) {
                 // 我是 leader，直接发起
                 await this._rotateGroupEpoch(groupId, triggerId, expectedEpoch);
                 return;
             }
-            if (!admins.includes(myAid))
+            if (!candidates.includes(myAid))
                 return;
             // 非 leader：随机 jitter（2~6s）后查询服务端 epoch 是否已被 leader 推进
             const jitterMs = 2000 + Math.floor(Math.random() * 4000);
@@ -3515,8 +4084,21 @@ export class AUNClient {
             }
             const currentEpoch = expectedEpoch ?? serverEpoch;
             const targetEpoch = currentEpoch + 1;
+            let prevChainHint = null;
+            const localPrev = await this._groupE2ee.loadSecret(groupId, currentEpoch);
+            const localPrevChain = String(localPrev?.epoch_chain ?? '').trim();
+            if (!localPrevChain && isJsonObject(epochResult)) {
+                const cr = epochResult.committed_rotation;
+                if (isJsonObject(cr)) {
+                    const rawChain = String(cr.epoch_chain ?? '').trim();
+                    if (rawChain) {
+                        prevChainHint = rawChain;
+                        console.info(`[aun_core] 轮换补充 prev epoch chain from server: group=${groupId} epoch=${currentEpoch}`);
+                    }
+                }
+            }
             const rotationId = `rot-${_uuidV4().replace(/-/g, '')}`;
-            const info = await this._groupE2ee.rotateEpochTo(groupId, targetEpoch, memberAids, { rotationId });
+            const info = await this._groupE2ee.rotateEpochTo(groupId, targetEpoch, memberAids, { rotationId, prevChainHint });
             this._attachRotationId(info, rotationId);
             const discardGeneratedPending = async () => {
                 try {
@@ -3609,7 +4191,15 @@ export class AUNClient {
                 await discardGeneratedPending();
                 return;
             }
-            const commitResult = await this.call('group.e2ee.commit_rotation', { rotation_id: activeRotationId });
+            const commitParams = { rotation_id: activeRotationId };
+            // 构建 per-member ECIES 加密的 epoch key 上传到服务端
+            if (await this._groupAllowsMemberEpochRotation(groupId)) {
+                const encryptedKeys = await this._buildEpochEncryptedKeys(info, memberAids, targetEpoch, groupId);
+                if (encryptedKeys && Object.keys(encryptedKeys).length > 0) {
+                    commitParams.encrypted_keys = encryptedKeys;
+                }
+            }
+            const commitResult = await this.call('group.e2ee.commit_rotation', commitParams);
             if (!isJsonObject(commitResult) || commitResult.success !== true) {
                 console.warn('group epoch commit failed (group=%s, rotation=%s, returned=%s)', groupId, activeRotationId, JSON.stringify(commitResult));
                 this._scheduleGroupRotationRetry(groupId, {
@@ -3649,6 +4239,78 @@ export class AUNClient {
             this._logE2eeError('rotate_epoch', groupId, '', exc);
         }
     }
+    /** 从成员加入事件 payload 中提取新加入的成员 AID 列表。 */
+    _joinedMemberAidsFromPayload(payload) {
+        const aids = new Set();
+        const addAid = (value) => {
+            const aid = String(value ?? '').trim();
+            if (aid)
+                aids.add(aid);
+        };
+        addAid(payload.aid ?? payload.applicant_aid ?? payload.applicantAid);
+        for (const key of ['member_aid', 'target_aid', 'new_member_aid', 'used_by']) {
+            addAid(payload[key]);
+        }
+        for (const key of ['member', 'request', 'invite_code']) {
+            const nested = isJsonObject(payload[key]) ? payload[key] : null;
+            if (!nested)
+                continue;
+            addAid(nested.aid ?? nested.applicant_aid ?? nested.applicantAid);
+            for (const nk of ['member_aid', 'target_aid', 'used_by'])
+                addAid(nested[nk]);
+        }
+        if (Array.isArray(payload.results)) {
+            for (const item of payload.results) {
+                if (!isJsonObject(item))
+                    continue;
+                const obj = item;
+                const status = String(obj.status ?? '').trim().toLowerCase();
+                if (status !== 'approved' && obj.approved !== true)
+                    continue;
+                addAid(obj.aid ?? obj.applicant_aid ?? obj.applicantAid);
+                for (const key of ['member_aid', 'target_aid'])
+                    addAid(obj[key]);
+                for (const key of ['member', 'request']) {
+                    const nested = isJsonObject(obj[key]) ? obj[key] : null;
+                    if (!nested)
+                        continue;
+                    addAid(nested.aid ?? nested.applicant_aid);
+                    for (const nk of ['member_aid', 'target_aid'])
+                        addAid(nested[nk]);
+                }
+            }
+        }
+        return Array.from(aids);
+    }
+    // ── 入群密钥恢复策略 ──────────────────────────────────────
+    /** 延迟轮换等待时间（毫秒） */
+    static _JOIN_ROTATION_DELAY_MS = 3000;
+    // 新成员自身延迟轮换时间：优先让其他在线成员先轮换
+    static _SELF_JOIN_ROTATION_DELAY_MS = 6000;
+    /** open/invite_code 入群后延迟轮换。 */
+    async _delayedRotateAfterJoin(groupId, triggerId, expectedEpoch, allowMember = false, delayMs) {
+        await new Promise(resolve => setTimeout(resolve, delayMs ?? AUNClient._JOIN_ROTATION_DELAY_MS));
+        await this._maybeLeadRotateGroupEpoch(groupId, triggerId, expectedEpoch, allowMember);
+    }
+    /** 当新成员加入但缺少 old_epoch 时，将当前 epoch 密钥分发给新成员。 */
+    async _maybeBackfillKeyToJoinedMember(groupId, payload, triggerId = '') {
+        const memberAids = this._joinedMemberAidsFromPayload(payload)
+            .filter(aid => aid && aid !== this._aid);
+        if (!groupId || !this._aid || memberAids.length === 0)
+            return;
+        if (!(await this._groupE2ee.hasSecret(groupId)))
+            return;
+        for (const memberAid of memberAids) {
+            const dedupeKey = `${triggerId || this._membershipRotationTriggerId(groupId, payload)}:backfill:${memberAid}`;
+            if (this._groupMemberKeyBackfillDone.has(dedupeKey))
+                continue;
+            this._groupMemberKeyBackfillDone.add(dedupeKey);
+            if (this._groupMemberKeyBackfillDone.size > 2000) {
+                this._groupMemberKeyBackfillDone = new Set(Array.from(this._groupMemberKeyBackfillDone).slice(-1000));
+            }
+            await this._distributeKeyToNewMember(groupId, memberAid);
+        }
+    }
     /**
      * 将当前 group_secret 通过 P2P E2EE 分发给新成员。
      * 先拉服务端最新成员列表，更新本地，构建签名 manifest，再分发。
@@ -3678,7 +4340,7 @@ export class AUNClient {
             if (identity && identity.private_key_pem) {
                 manifest = await signMembershipManifest(manifest, identity.private_key_pem);
             }
-            const distPayload = await buildKeyDistribution(groupId, epoch, secretData.secret, memberAids, this._aid, manifest);
+            const distPayload = await buildKeyDistribution(groupId, epoch, secretData.secret, memberAids, this._aid, manifest, String(secretData.epoch_chain ?? ''));
             // 重试 3 次，间隔递增（1s, 2s）
             for (let attempt = 0; attempt < 3; attempt++) {
                 try {
@@ -3934,8 +4596,6 @@ export class AUNClient {
         this._startTokenRefresh();
         this._startPrekeyRefresh();
         this._startGroupEpochTasks();
-        // 上线/重连后一次性补齐群消息和群事件
-        this._safeAsync(this._syncAllGroupsOnce());
     }
     _stopBackgroundTasks() {
         if (this._heartbeatTimer !== null) {
@@ -3971,9 +4631,10 @@ export class AUNClient {
     _startHeartbeat() {
         if (this._heartbeatTimer !== null)
             return;
-        const interval = this._sessionOptions.heartbeat_interval * 1000;
-        if (interval <= 0)
+        const rawIntervalSeconds = Number(this._sessionOptions.heartbeat_interval ?? DEFAULT_SESSION_OPTIONS.heartbeat_interval);
+        if (!Number.isFinite(rawIntervalSeconds) || rawIntervalSeconds <= 0)
             return;
+        const interval = Math.max(rawIntervalSeconds, 30) * 1000;
         // M25: 把连续失败阈值从 3 次收窄到 2 次。既能容忍一次网络抖动/GC 暂停，
         // 又把半开连接的检测延迟从 3 个心跳周期降到 2 个，避免 RPC 长时间挂起。
         // 真正的 socket 死亡由 ws.on('close') 立即触发 _handleTransportDisconnect，
@@ -4002,32 +4663,35 @@ export class AUNClient {
     _startTokenRefresh() {
         if (this._tokenRefreshTimer !== null)
             return;
-        const scheduleRefresh = () => {
+        const rawLead = Number(this._sessionOptions.token_refresh_before ?? DEFAULT_SESSION_OPTIONS.token_refresh_before);
+        const lead = Number.isFinite(rawLead) && rawLead > 0
+            ? rawLead
+            : DEFAULT_SESSION_OPTIONS.token_refresh_before;
+        const scheduleRefresh = (delayMs = TOKEN_REFRESH_CHECK_INTERVAL_MS) => {
             if (this._closing)
                 return;
-            const lead = this._sessionOptions.token_refresh_before;
-            const minimumDelay = 1000;
-            if (this._state !== 'connected' || !this._gatewayUrl) {
-                // 非连接状态下使用指数退避，避免 1s 轮询浪费 CPU
-                this._tokenDisconnectedRetries++;
-                const backoff = Math.min(minimumDelay * Math.pow(2, this._tokenDisconnectedRetries), 60_000);
-                this._tokenRefreshTimer = globalThis.setTimeout(scheduleRefresh, backoff);
-                return;
-            }
-            // 连接恢复后重置退避计数器
-            this._tokenDisconnectedRetries = 0;
-            let identity = this._identity;
-            if (!identity) {
-                this._tokenRefreshTimer = globalThis.setTimeout(scheduleRefresh, minimumDelay);
-                return;
-            }
-            const expiresAt = this._auth.getAccessTokenExpiry(identity);
-            if (expiresAt === null) {
-                this._tokenRefreshTimer = globalThis.setTimeout(scheduleRefresh, minimumDelay);
-                return;
-            }
-            const delay = Math.max((expiresAt - lead) * 1000 - Date.now(), minimumDelay);
             this._tokenRefreshTimer = globalThis.setTimeout(async () => {
+                if (this._closing)
+                    return;
+                this._tokenRefreshTimer = null;
+                if (this._state !== 'connected' || !this._gatewayUrl) {
+                    scheduleRefresh();
+                    return;
+                }
+                let identity = this._identity;
+                if (!identity) {
+                    scheduleRefresh();
+                    return;
+                }
+                const expiresAt = this._auth.getAccessTokenExpiry(identity);
+                if (expiresAt === null) {
+                    scheduleRefresh();
+                    return;
+                }
+                if ((expiresAt - Date.now() / 1000) > lead) {
+                    scheduleRefresh();
+                    return;
+                }
                 if (this._state !== 'connected' || !this._gatewayUrl || this._closing) {
                     scheduleRefresh();
                     return;
@@ -4065,9 +4729,9 @@ export class AUNClient {
                     }
                 }
                 scheduleRefresh();
-            }, delay);
+            }, delayMs);
         };
-        scheduleRefresh();
+        scheduleRefresh(0);
     }
     /** Prekey 轮换定时器：定期检查本地 prekey 数量，不足时自动补充上传 */
     _startPrekeyRefresh() {
@@ -4387,6 +5051,69 @@ export class AUNClient {
         this._reconnectActive = false;
         this._reconnectAbort = null;
     }
+    // ── Named Group（命名群）高层 API ────────────────────────────
+    /**
+     * 创建命名群：本地生成 P-256 keypair，调用 group.create 传入 public_key，
+     * 服务端签发群 AID 证书，返回后将证书和私钥存入 keystore。
+     */
+    async createNamedGroup(groupName, opts = {}) {
+        const cp = new CryptoProvider();
+        const identity = await cp.generateIdentity();
+        const params = {};
+        for (const [k, v] of Object.entries(opts)) {
+            params[k] = v;
+        }
+        params.group_name = groupName;
+        params.public_key = identity.public_key_der_b64;
+        params.curve = 'P-256';
+        const result = await this.call('group.create', params);
+        const groupInfo = result?.group;
+        const aidCert = result?.aid_cert;
+        const groupAid = String(groupInfo?.group_aid ?? '');
+        if (groupAid && aidCert) {
+            await this._keystore.saveIdentity(groupAid, {
+                private_key_pem: identity.private_key_pem,
+                public_key: identity.public_key_der_b64,
+                curve: 'P-256',
+                type: 'group_identity',
+            });
+            const certPem = String(aidCert.cert ?? '');
+            if (certPem) {
+                await this._keystore.saveCert(groupAid, certPem);
+            }
+        }
+        return result;
+    }
+    /**
+     * 为已有普通群绑定命名 AID（升级为命名群）。
+     */
+    async bindGroupAid(groupId, groupName) {
+        const cp = new CryptoProvider();
+        const identity = await cp.generateIdentity();
+        const params = {
+            group_id: groupId,
+            group_name: groupName,
+            public_key: identity.public_key_der_b64,
+            curve: 'P-256',
+        };
+        const result = await this.call('group.bind_aid', params);
+        const groupInfo = result?.group;
+        const aidCert = result?.aid_cert;
+        const groupAid = String(groupInfo?.group_aid ?? '');
+        if (groupAid && aidCert) {
+            await this._keystore.saveIdentity(groupAid, {
+                private_key_pem: identity.private_key_pem,
+                public_key: identity.public_key_der_b64,
+                curve: 'P-256',
+                type: 'group_identity',
+            });
+            const certPem = String(aidCert.cert ?? '');
+            if (certPem) {
+                await this._keystore.saveCert(groupAid, certPem);
+            }
+        }
+        return result;
+    }
     /** 判断是否应重试重连 */
     _shouldRetryReconnect(error) {
         if (error instanceof AuthError) {