@agentunion/fastaun-browser 0.5.0 → 0.5.1

package/dist/client.js

@@ -7,6 +7,7 @@
 import { createConfig, getDeviceId, normalizeSlotId } from './config.js';
 import { EventDispatcher } from './events.js';
 import { normalizeGroupId } from './group-id.js';
+import { validateAIDFormat, validateGroupIDFormat } from './validators.js';
 import { GatewayDiscovery } from './discovery.js';
 import { AIDStore } from './aid-store.js';
 import { RPCTransport } from './transport.js';
@@ -30,7 +31,7 @@ import { ecdsaVerifyRaw } from './v2/crypto/ecdsa.js';
 import { AUNLogger } from './logger.js';
 import { AgentMdManager } from './agent-md.js';
 import { certMatchesFingerprint, normalizeFingerprintHex } from './cert-utils.js';
-import { AUNError, AuthError, ConnectionError, E2EEError, NotFoundError, PermissionError, StateError, ValidationError, } from './errors.js';
+import { AUNError, AuthError, ConnectionError, E2EEError, NotFoundError, PermissionError, StateError, TimeoutError, ValidationError, } from './errors.js';
 import { isJsonObject, ConnectionState, STATE_TO_PUBLIC, } from './types.js';
 import { AID } from './aid.js';
 function getV2DeviceId(dev) {
@@ -105,8 +106,8 @@ const NON_IDEMPOTENT_TIMEOUT = 35;
 const NON_IDEMPOTENT_METHODS = new Set([
     'message.send', 'group.send', 'group.create', 'group.invite',
     'group.kick', 'group.remove_member', 'group.leave', 'group.dissolve',
-    'group.update_name', 'group.update_avatar', 'group.update_announcement',
-    'group.update_settings',
+    'group.set_settings',
+    'group.update_announcement', 'group.update_rules',
     'storage.put_object', 'storage.delete_object',
     'storage.create_share_link', 'storage.revoke_share_link',
     'storage.get_by_share',
@@ -126,6 +127,7 @@ const NON_IDEMPOTENT_METHODS = new Set([
     'message.thought.put', 'group.thought.put',
     'group.add_member', 'group.bind_group_aid', 'group.complete_transfer',
     'group.fs.mkdir', 'group.fs.rm', 'group.fs.cp', 'group.fs.mv',
+    'group.fs.set_acl', 'group.fs.remove_acl',
     'group.fs.mount', 'group.fs.umount',
     'group.fs.check_upload', 'group.fs.create_upload_session',
     'group.fs.complete_upload', 'group.fs.create_download_ticket',
@@ -146,9 +148,9 @@ const SIGNED_METHODS = new Set([
     'group.v2.propose_state', 'group.v2.confirm_state',
     'group.v2.get_proposal',
     'group.kick', 'group.add_member',
-    'group.leave', 'group.remove_member', 'group.update_rules',
-    'group.update', 'group.update_announcement',
-    'group.update_join_requirements', 'group.set_role',
+    'group.leave', 'group.remove_member',
+    'group.update',
+    'group.set_role',
     'group.transfer_owner', 'group.bind_group_aid', 'group.complete_transfer',
     'group.review_join_request',
     'group.batch_review_join_request',
@@ -156,7 +158,10 @@ const SIGNED_METHODS = new Set([
     'group.thought.put',
     'message.thought.put',
     'group.set_settings',
+    'group.update_announcement',
+    'group.update_rules',
     'group.fs.mkdir', 'group.fs.rm', 'group.fs.cp', 'group.fs.mv',
+    'group.fs.set_acl', 'group.fs.remove_acl',
     'group.fs.mount', 'group.fs.umount',
     'group.fs.check_upload', 'group.fs.create_upload_session',
     'group.fs.complete_upload', 'group.fs.create_download_ticket',
@@ -736,7 +741,7 @@ export class AUNClient {
         this._dispatcher.subscribe('_raw.group.message_recalled', (data) => {
             this._safeAsync(this._onRawGroupMessageRecalled(data));
         });
-        // 群组变更事件：验签 + 透传 + gap 检测
+        // 群组变更事件：验签 + 透传 + gap 检测 + V2 state/SPK 维护
         this._dispatcher.subscribe('_raw.group.changed', (data) => {
             this._onRawGroupChanged(data);
         });
@@ -747,9 +752,6 @@ export class AUNClient {
         this._dispatcher.subscribe('_raw.group.v2.message_created', (data) => {
             this._safeAsync(this._onRawGroupV2MessageCreated(data));
         });
-        this._dispatcher.subscribe('_raw.group.v2.epoch_rotated', (data) => {
-            this._safeAsync(this._onV2EpochRotated(data));
-        });
         this._dispatcher.subscribe('_raw.group.v2.state_proposed', (data) => {
             this._safeAsync(this._onV2StateProposed(data));
         });
@@ -1047,7 +1049,22 @@ export class AUNClient {
      * 自动解密 message.pull/group.pull、Group E2EE 生命周期编排。
      */
     async call(method, params) {
-        return await this._rpcPipeline.call(method, params);
+        try {
+            return await this._rpcPipeline.call(method, params);
+        }
+        catch (err) {
+            await this._maybeHandleHalfOpenRpcFailure(err);
+            throw err;
+        }
+    }
+    async _maybeHandleHalfOpenRpcFailure(err) {
+        if (this._closing || this.state !== ConnectionState.READY)
+            return;
+        if (!this._sessionOptions?.auto_reconnect || this._reconnectActive)
+            return;
+        if (!(err instanceof ConnectionError) && !(err instanceof TimeoutError))
+            return;
+        await this._handleTransportDisconnect(err);
     }
     async createGroup(params = {}) {
         if (!isJsonObject(params)) {
@@ -1101,8 +1118,33 @@ export class AUNClient {
         if (!store) {
             throw new ValidationError('bindGroupAid requires aidStore');
         }
-        const keyPair = await new CryptoProvider().generateIdentity();
+        const groupId = String(params.group_id ?? params.group_aid ?? '').trim();
+        const keystore = store._keystore;
+        let keyPair = null;
+        // 优先复用 pending 槽位中已暂存的待绑定密钥（崩溃/重试幂等）
+        if (groupId && keystore && typeof keystore.loadPendingGroupBind === 'function') {
+            keyPair = await keystore.loadPendingGroupBind(groupId);
+        }
+        if (!keyPair || !keyPair.public_key_der_b64 || !keyPair.private_key_pem) {
+            // 未命中 pending，生成新密钥
+            const generated = await new CryptoProvider().generateIdentity();
+            keyPair = {
+                private_key_pem: generated.private_key_pem,
+                public_key_der_b64: generated.public_key_der_b64,
+                curve: generated.curve,
+            };
+            // 发 RPC 前先落盘暂存，确保崩溃后重试能复用同一密钥
+            if (groupId && keystore && typeof keystore.savePendingGroupBind === 'function') {
+                await keystore.savePendingGroupBind(groupId, keyPair);
+            }
+        }
+        if (!keyPair) {
+            throw new ValidationError('bindGroupAid: failed to generate or load key pair');
+        }
         const payload = { ...params };
+        if (!String(payload.group_id ?? '').trim() && groupId) {
+            payload.group_id = groupId;
+        }
         payload.public_key = keyPair.public_key_der_b64;
         payload.curve = keyPair.curve;
         const result = await this.call('group.bind_group_aid', payload);
@@ -1123,6 +1165,95 @@ export class AUNClient {
         if (!imported.ok) {
             throw new ValidationError(imported.error.message);
         }
+        // 落盘成功，清除 pending 槽位
+        if (groupId && keystore && typeof keystore.clearPendingGroupBind === 'function') {
+            await keystore.clearPendingGroupBind(groupId);
+        }
+        return result;
+    }
+    async renewGroupAid(params = {}, options = {}) {
+        if (!isJsonObject(params)) {
+            throw new ValidationError('renewGroupAid params must be an object');
+        }
+        const store = options.aidStore;
+        if (!store) {
+            throw new ValidationError('renewGroupAid requires aidStore');
+        }
+        const groupId = String(params.group_id ?? params.group_aid ?? '').trim();
+        if (!groupId) {
+            throw new ValidationError('renewGroupAid requires group_id or group_aid');
+        }
+        let groupAid = String(params.group_aid ?? '').trim();
+        if (!groupAid) {
+            const info = await this.call('group.get_info', { group_id: groupId, required: ['member'] });
+            groupAid = String(info?.group_aid ?? '').trim();
+        }
+        if (!groupAid) {
+            throw new ValidationError('renewGroupAid: unable to determine group_aid');
+        }
+        const loaded = await store.load(groupAid);
+        if (!loaded.ok || !loaded.data) {
+            throw new ValidationError(`renewGroupAid: group_aid identity not found: ${groupAid}`);
+        }
+        const oldAidObj = loaded.data.aid;
+        if (!oldAidObj.isPrivateKeyValid() || !oldAidObj.privateKeyPem) {
+            throw new ValidationError(`renewGroupAid: group_aid has no private key: ${groupAid}`);
+        }
+        const oldPublicKey = oldAidObj.publicKey;
+        if (!oldPublicKey) {
+            throw new ValidationError(`renewGroupAid: cannot determine old public key for ${groupAid}`);
+        }
+        const newKeyPair = await new CryptoProvider().generateIdentity();
+        const newPublicKey = newKeyPair.public_key_der_b64;
+        const newPrivateKey = newKeyPair.private_key_pem;
+        const curve = newKeyPair.curve || 'P-256';
+        if (!newPublicKey || !newPrivateKey) {
+            throw new ValidationError('renewGroupAid: generated incomplete group identity');
+        }
+        const nonce = globalThis.crypto.randomUUID().replace(/-/g, '');
+        const issuedMs = Date.now();
+        const oldHash = bytesToHex(new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(oldPublicKey))));
+        const newHash = bytesToHex(new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(newPublicKey))));
+        const canonical = [
+            'aun-group-aid-renew-v1',
+            groupId.toLowerCase(),
+            groupAid.toLowerCase(),
+            oldHash,
+            newHash,
+            nonce,
+            String(issuedMs),
+        ].join('|');
+        const signed = await oldAidObj.sign(canonical);
+        if (!signed.ok) {
+            throw new ValidationError(`renewGroupAid: sign failed: ${signed.error.message}`);
+        }
+        const payload = { ...params };
+        if (!String(payload.group_id ?? '').trim()) {
+            payload.group_id = groupId;
+        }
+        payload.group_aid = groupAid;
+        payload.old_public_key = oldPublicKey;
+        payload.new_public_key = newPublicKey;
+        payload.curve = curve;
+        payload.renew_proof = { nonce, issued_ms: issuedMs, signature: signed.data.signature };
+        const result = await this.call('group.renew_group_aid', payload);
+        const resultMap = isJsonObject(result) ? result : {};
+        const group = isJsonObject(resultMap.group) ? resultMap.group : {};
+        const aidCert = isJsonObject(resultMap.aid_cert) ? resultMap.aid_cert : {};
+        const returnedGroupAid = String(group.group_aid ?? resultMap.group_aid ?? groupAid).trim();
+        const certPem = String(aidCert.cert ?? aidCert.cert_pem ?? resultMap.cert ?? resultMap.cert_pem ?? '').trim();
+        if (!returnedGroupAid || !certPem) {
+            throw new ValidationError('renewGroupAid response missing group.group_aid or aid_cert.cert');
+        }
+        const imported = await store.importGroupIdentity(returnedGroupAid, {
+            private_key_pem: newPrivateKey,
+            public_key_der_b64: newPublicKey,
+            curve,
+            cert_pem: certPem,
+        });
+        if (!imported.ok) {
+            throw new ValidationError(`renewGroupAid failed to persist group identity: ${imported.error.message}`);
+        }
         return result;
     }
     async startGroupTransfer(params = {}, options = {}) {
@@ -1140,10 +1271,8 @@ export class AUNClient {
         }
         let groupAid = String(params.group_aid ?? '').trim();
         if (!groupAid) {
-            const info = await this.call('group.get', { group_id: groupId });
-            const infoMap = isJsonObject(info) ? info : {};
-            const grp = isJsonObject(infoMap.group) ? infoMap.group : infoMap;
-            groupAid = String(grp.group_aid ?? '').trim();
+            const info = await this.call('group.get_info', { group_id: groupId, required: ['member'] });
+            groupAid = String(info?.group_aid ?? '').trim();
         }
         if (!groupAid) {
             throw new ValidationError('startGroupTransfer: unable to determine group_aid');
@@ -1190,10 +1319,8 @@ export class AUNClient {
         }
         let groupAid = String(params.group_aid ?? '').trim();
         if (!groupAid) {
-            const info = await this.call('group.get', { group_id: groupId });
-            const infoMap = isJsonObject(info) ? info : {};
-            const grp = isJsonObject(infoMap.group) ? infoMap.group : infoMap;
-            groupAid = String(grp.group_aid ?? '').trim();
+            const info = await this.call('group.get_info', { group_id: groupId, required: ['member'] });
+            groupAid = String(info?.group_aid ?? '').trim();
         }
         if (!groupAid) {
             throw new ValidationError('completeGroupTransfer: unable to determine group_aid');
@@ -1277,7 +1404,7 @@ export class AUNClient {
             throw new ValidationError('notify payload is too large');
         }
         const targetAid = String(options.to ?? '').trim();
-        const targetGroupId = String(options.group_id ?? options.groupId ?? '').trim();
+        const targetGroupId = String(options.group_aid ?? options.groupAid ?? options.group_id ?? options.groupId ?? '').trim();
         const targetDeviceId = String(options.device_id ?? options.deviceId ?? '').trim();
         const targetSlotId = String(options.slot_id ?? options.slotId ?? '').trim();
         const ttl = AUNClient._normalizeNotifyTtl(options.ttl_ms ?? options.ttlMs);
@@ -1289,6 +1416,8 @@ export class AUNClient {
         }
         if (targetAid) {
             const eventMethod = AUNClient._validateNotifyEventMethod(method);
+            // 校验目标 AID 格式（拒绝 __system__ 等非法格式）
+            validateAIDFormat(targetAid, 'notify.to');
             const target = { type: 'aid', aid: targetAid };
             if (targetDeviceId)
                 target.device_id = targetDeviceId;
@@ -1305,11 +1434,14 @@ export class AUNClient {
         }
         if (targetGroupId) {
             const eventMethod = AUNClient._validateNotifyEventMethod(method);
+            // 校验目标 Group ID 格式
+            validateGroupIDFormat(targetGroupId, 'notify.group_id');
             const normalizedGroupId = normalizeGroupId(targetGroupId);
             if (!normalizedGroupId) {
                 throw new ValidationError('group_id is required for group notify');
             }
             const routeParams = {
+                group_aid: normalizedGroupId,
                 group_id: normalizedGroupId,
                 deliver: { method: eventMethod, params: payload },
             };
@@ -1335,8 +1467,11 @@ export class AUNClient {
         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);
+        if (method.startsWith('group.') && p.group_aid !== undefined && p.group_aid !== null) {
+            p.group_aid = normalizeGroupId(String(p.group_aid)) || String(p.group_aid);
+        }
+        else if (method.startsWith('group.') && p.group_id !== undefined && p.group_id !== null) {
+            p.group_aid = normalizeGroupId(String(p.group_id)) || String(p.group_id);
         }
         if (method.startsWith('group.') && p.device_id === undefined) {
             p.device_id = this._deviceId;
@@ -1448,19 +1583,19 @@ export class AUNClient {
     }
     _extractGroupIdFromResult(result) {
         const group = isJsonObject(result.group) ? result.group : null;
-        const gid = group ? String(group.group_id ?? '') : '';
+        const gid = group ? String(group.group_aid ?? group.group_id ?? '') : '';
         if (gid)
             return gid;
-        const directGid = String(result.group_id ?? '');
+        const directGid = String(result.group_aid ?? result.group_id ?? '');
         if (directGid)
             return directGid;
         const member = isJsonObject(result.member) ? result.member : null;
-        return member ? String(member.group_id ?? '') : '';
+        return member ? String(member.group_aid ?? member.group_id ?? '') : '';
     }
     async _onRawGroupChanged(data) {
         const tStart = Date.now();
         const action = String(data?.action ?? '');
-        const groupIdInit = String(data?.group_id ?? '');
+        const groupIdInit = String(data?.group_aid ?? data?.group_id ?? '');
         this._clientLog.debug(`_onRawGroupChanged enter: group_id=${groupIdInit} action=${action}`);
         try {
             if (isJsonObject(data)) {
@@ -1476,7 +1611,7 @@ export class AUNClient {
                         d._verified = this._isEventSignatureVerified(verified);
                     }
                 }
-                const groupId = (d.group_id ?? '');
+                const groupId = (d.group_aid ?? d.group_id ?? '');
                 await this._delivery.handleGroupChangedEventSeq(d, groupId);
             }
             else {
@@ -1509,9 +1644,13 @@ export class AUNClient {
         this._v2E2EE.deleteBootstrapCacheEntry(`group:${groupId}`);
         this._v2GroupSecurityLevels.delete(groupId);
         this._v2StateChains.delete(groupId);
-        this._seqTracker.removeNamespace(`group:${groupId}`);
-        this._seqTracker.removeNamespace(`group_event:${groupId}`);
-        this._saveSeqTrackerState();
+        const groupNs = `group:${groupId}`;
+        const groupEventNs = `group_event:${groupId}`;
+        this._seqTracker.removeNamespace(groupNs);
+        this._seqTracker.removeNamespace(groupEventNs);
+        this._persistRepairedSeq(groupNs);
+        this._persistRepairedSeq(groupEventNs);
+        void this._saveSeqTrackerState();
         // 2. 清理补洞去重缓存中的相关条目
         for (const key of this._gapFillDone.keys()) {
             if (key.includes(groupId)) {
@@ -1519,10 +1658,10 @@ export class AUNClient {
             }
         }
         // 3. 清理推送 seq 去重缓存
-        this._pushedSeqs.delete(`group:${groupId}`);
-        this._pushedSeqs.delete(`group_event:${groupId}`);
-        this._pendingOrderedMsgs.delete(`group:${groupId}`);
-        this._pendingOrderedMsgs.delete(`group_event:${groupId}`);
+        this._pushedSeqs.delete(groupNs);
+        this._pushedSeqs.delete(groupEventNs);
+        this._pendingOrderedMsgs.delete(groupNs);
+        this._pendingOrderedMsgs.delete(groupEventNs);
         this._clientLog.info(`cleanup dissolved group ${groupId}  local state`);
     }
     async _verifyEventSignature(_event, cs) {
@@ -2019,7 +2158,7 @@ export class AUNClient {
         let consecutiveFailures = 0;
         const maxFailures = 2;
         this._heartbeatTimer = setInterval(async () => {
-            if (this._state !== 'connected' || this._closing)
+            if (this.state !== ConnectionState.READY || this._closing)
                 return;
             try {
                 const pong = await this._transport.call('meta.ping', {});
@@ -2054,7 +2193,7 @@ export class AUNClient {
             clearInterval(this._heartbeatTimer);
             this._heartbeatTimer = null;
         }
-        if (newInterval > 0 && this._state === 'connected' && !this._closing) {
+        if (newInterval > 0 && this.state === ConnectionState.READY && !this._closing) {
             this._startHeartbeat();
         }
     }
@@ -2073,7 +2212,7 @@ export class AUNClient {
                 if (this._closing)
                     return;
                 this._tokenRefreshTimer = null;
-                if (this._state !== 'connected' || !this._gatewayUrl) {
+                if (this.state !== ConnectionState.READY || !this._gatewayUrl) {
                     scheduleRefresh();
                     return;
                 }
@@ -2091,14 +2230,14 @@ export class AUNClient {
                     scheduleRefresh();
                     return;
                 }
-                if (this._state !== 'connected' || !this._gatewayUrl || this._closing) {
+                if (this.state !== ConnectionState.READY || !this._gatewayUrl || this._closing) {
                     scheduleRefresh();
                     return;
                 }
                 try {
                     identity = await this._auth.refreshCachedTokens(this._gatewayUrl, identity);
                     // 刷新期间可能已断线，复检状态，避免写回 stale identity
-                    if (this._state !== 'connected') {
+                    if (this.state !== ConnectionState.READY) {
                         scheduleRefresh();
                         return;
                     }
@@ -2183,6 +2322,9 @@ export class AUNClient {
         this._state = 'standby';
         // 先停止后台任务，避免心跳/token刷新在重连期间继续触发
         this._stopBackgroundTasks();
+        void this._transport.close().catch((exc) => {
+            this._clientLog.debug(`transport cleanup skipped: ${formatCaughtError(exc)}`);
+        });
         await this._dispatcher.publish('state_change', {
             state: this._publicState(this._state),
             error,
@@ -2361,6 +2503,7 @@ export class AUNClient {
         return JSON.stringify([this._aid, this._deviceId, this._slotId]);
     }
     _resetSeqTrackingState() {
+        void this._saveSeqTrackerState();
         this._resetV2IdentityRuntime();
         this._seqTracker = new SeqTracker();
         this._seqTrackerContext = null;
@@ -2381,6 +2524,7 @@ export class AUNClient {
         const nextContext = this._currentSeqTrackerContext();
         if (nextContext === this._seqTrackerContext)
             return;
+        void this._saveSeqTrackerState();
         this._seqTracker = new SeqTracker();
         this._gapFillDone.clear();
         this._pushedSeqs.clear();
@@ -2400,6 +2544,9 @@ export class AUNClient {
     _saveSeqTrackerState() {
         return this._delivery.saveSeqTrackerState();
     }
+    _persistSeq(ns, forceSeq) {
+        return this._delivery.persistSeq(ns, forceSeq);
+    }
     _persistRepairedSeq(ns) {
         return this._delivery.persistRepairedSeq(ns);
     }
@@ -2916,12 +3063,6 @@ export class AUNClient {
     async _onV2PushNotification(data) {
         return this._delivery.onV2PushNotification(data);
     }
-    /**
-     * 处理 V2 epoch 轮换事件：清除 bootstrap 缓存 + 触发 SPK rotation。
-     */
-    async _onV2EpochRotated(data) {
-        return this._v2E2EE.handleV2EpochRotated(data);
-    }
     /** 安全执行异步操作（不阻塞调用方，错误打 warning 便于排障） */
     _safeAsync(promise) {
         promise.catch((exc) => {