@agentunion/fastaun 0.4.4 → 0.4.6

package/dist/client.js

@@ -11,22 +11,21 @@
  * - 群组 E2EE 全自动编排（建群/加人/踢人/退出）
  */
 import * as crypto from 'node:crypto';
-import * as fs from 'node:fs';
 import * as http from 'node:http';
 import * as https from 'node:https';
-import * as path from 'node:path';
 import { URL } from 'node:url';
-import { configFromMap, getDeviceId, normalizeInstanceId, normalizeSlotId, slotIsolationKey } from './config.js';
+import { configFromMap, getDeviceId, normalizeSlotId, slotIsolationKey } from './config.js';
 import { CryptoProvider } from './crypto.js';
 import { GatewayDiscovery } from './discovery.js';
 import { DnsResilientNet } from './net.js';
 import { AUNError, AuthError, ConnectionError, E2EEError, NotFoundError, PermissionError, StateError, TimeoutError, ValidationError, } from './errors.js';
 import { EventDispatcher } from './events.js';
-import { FileKeyStore } from './keystore/file.js';
+import { LocalTokenStore } from './keystore/local-token-store.js';
 import { AUNLogger } from './logger.js';
 import { normalizeGroupId } from './group-id.js';
 import { RPCTransport } from './transport.js';
 import { AuthFlow } from './auth.js';
+import { AgentMdManager } from './agent-md.js';
 import { SeqTracker } from './seq-tracker.js';
 import { V2Session } from './v2/session/index.js';
 import { encryptP2PMessage, encryptGroupMessage, decryptMessage, } from './v2/e2ee/index.js';
@@ -226,7 +225,6 @@ const SIGNED_METHODS = new Set([
 ]);
 /** peer 证书缓存 TTL（1 小时） */
 const PEER_CERT_CACHE_TTL = 3600;
-const AGENT_MD_HTTP_TIMEOUT_MS = 30_000;
 function normalizeV2WrapPolicy(raw) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         return { explicit: false, version: '', protocol: '', scope: 'device' };
@@ -404,33 +402,93 @@ function lengthPrefixedBytesKey(...parts) {
     }
     return Buffer.concat(chunks);
 }
-function agentMdHttpScheme(gatewayUrl) {
-    const raw = String(gatewayUrl ?? '').trim().toLowerCase();
-    return raw.startsWith('ws://') ? 'http' : 'https';
-}
-function agentMdAuthority(aid, discoveryPort) {
-    const host = String(aid ?? '').trim();
-    if (!host)
-        return '';
-    if (discoveryPort && !host.includes(':'))
-        return `${host}:${discoveryPort}`;
-    return host;
-}
-async function fetchWithTimeout(input, init, timeoutMs = AGENT_MD_HTTP_TIMEOUT_MS) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        return await fetch(input, { ...init, signal: controller.signal });
-    }
-    catch (error) {
-        if (controller.signal.aborted) {
-            throw new AUNError(`agent.md request timed out after ${timeoutMs}ms`);
-        }
-        throw error;
-    }
-    finally {
-        clearTimeout(timer);
-    }
+function createAgentMdManagerForRuntime(opts) {
+    return new AgentMdManager({
+        aunPath: opts.config().aunPath,
+        verifySsl: opts.config().verifySsl,
+        discoveryPort: opts.config().discoveryPort,
+        logger: opts.logger(),
+        ownerAidGetter: opts.ownerAid,
+        currentAidGetter: opts.currentAid,
+        gatewayResolver: async (aid) => {
+            const gatewayUrl = await opts.gateway.resolve(aid);
+            opts.gateway.set(gatewayUrl);
+            return gatewayUrl;
+        },
+        accessTokenResolver: async (aid, gatewayUrl) => {
+            const target = String(aid ?? '').trim();
+            let identity = opts.identity.get();
+            if (!identity || String(identity.aid ?? '') !== target) {
+                throw new StateError('no local identity found, register or load an AID first');
+            }
+            const auth = opts.auth();
+            const cachedToken = String(identity.access_token ?? '');
+            const expiresAt = auth.getAccessTokenExpiry(identity);
+            if (cachedToken && (expiresAt === null || expiresAt > Date.now() / 1000 + 30)) {
+                return cachedToken;
+            }
+            if (identity.refresh_token) {
+                try {
+                    const refreshed = await auth.refreshCachedTokens(gatewayUrl, identity);
+                    const refreshedToken = String(refreshed.access_token ?? '');
+                    const refreshedExpiry = auth.getAccessTokenExpiry(refreshed);
+                    if (refreshedToken && (refreshedExpiry === null || refreshedExpiry > Date.now() / 1000 + 30)) {
+                        opts.identity.set(refreshed);
+                        return refreshedToken;
+                    }
+                }
+                catch {
+                    // refresh 失败时回退到完整 authenticate。
+                }
+            }
+            const result = await auth.authenticate(gatewayUrl, { aid: target });
+            const token = String(result.access_token ?? '');
+            if (!token)
+                throw new StateError('authenticate did not return access_token');
+            identity = auth.loadIdentityOrNone(target) ?? {
+                ...identity,
+                access_token: token,
+                refresh_token: String(result.refresh_token ?? identity.refresh_token ?? ''),
+                access_token_expires_at: typeof result.expires_at === 'number' ? result.expires_at : identity.access_token_expires_at,
+                token_exp: typeof result.expires_at === 'number' ? result.expires_at : identity.token_exp,
+                expires_at: typeof result.expires_at === 'number' ? result.expires_at : identity.expires_at,
+            };
+            opts.identity.set(identity);
+            return token;
+        },
+        peerResolver: async (aid) => {
+            const target = String(aid ?? '').trim();
+            const current = opts.currentAid();
+            if (current?.aid === target)
+                return current;
+            let certPem = '';
+            try {
+                certPem = String(opts.tokenStore().loadCert(target) ?? '').trim();
+            }
+            catch {
+                certPem = '';
+            }
+            if (!certPem) {
+                if (!opts.gateway.get()) {
+                    try {
+                        opts.gateway.set(await opts.gateway.resolve(target));
+                    }
+                    catch { /* best effort before cert fetch */ }
+                }
+                certPem = String(await opts.fetchPeerCert(target) ?? '').trim();
+            }
+            if (!certPem)
+                throw new NotFoundError(`certificate not found for aid: ${target}`);
+            return AID._create({
+                aid: target,
+                aunPath: opts.config().aunPath,
+                certPem,
+                privateKeyPem: null,
+                certValid: true,
+                privateKeyValid: false,
+            });
+        },
+    });
 }
 export class AUNClient {
     /** 原始配置 */
@@ -466,7 +524,7 @@ export class AUNClient {
     /** 认证流程 */
     _auth;
     /** 密钥存储 */
-    _keystore;
+    _tokenStore;
     /** 会话参数（重连用） */
     _sessionParams = null;
     /** 会话选项 */
@@ -479,17 +537,7 @@ export class AUNClient {
     _defaultConnectDeliveryMode;
     /** peer 证书缓存 */
     _certCache = new Map();
-    // AIDs 目录：{agentMdPath}/{aid}/agentmd.json 保存元数据，{agentMdPath}/{aid}/agent.md 保存正文。
-    _agentMdPath = '';
-    _localAgentMdPath = '';
-    _localAgentMdEtag = '';
-    // gateway 在 RPC envelope._meta.agent_md_etag 注入的服务端 etag；纯观察，无下游依赖。
-    _remoteAgentMdEtag = '';
-    _agentMdCache = new Map();
-    _agentMdFetchInflight = new Map();
-    _agentMdDownloadInflight = new Map();
-    _agentMdDownloadActive = 0;
-    _agentMdDownloadWaiters = [];
+    _agentMdManager;
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     _seqTracker = new SeqTracker();
     _seqTrackerContext = null;
@@ -541,7 +589,6 @@ export class AUNClient {
     _peerCache = new Map();
     static V2_SIG_CACHE_TTL_MS = 60 * 60 * 1000;
     static V2_SIG_CACHE_MAX = 16_384;
-    static AGENT_MD_DOWNLOAD_CONCURRENCY = 8;
     _reconnectActive = false;
     _reconnectAbort = null;
     _serverKicked = false;
@@ -564,7 +611,6 @@ export class AUNClient {
         }
         this._configModel = configFromMap(rawConfig);
         const initAid = (inputAid && inputAid.isPrivateKeyValid()) ? inputAid.aid : null;
-        this._agentMdPath = path.join(this._configModel.aunPath, 'AIDs');
         this.config = {
             aun_path: this._configModel.aunPath,
             root_ca_path: this._configModel.rootCaPath,
@@ -588,29 +634,15 @@ export class AUNClient {
             logger: this._clientLog,
         });
         this._discovery = new GatewayDiscovery({ verifySsl: this._configModel.verifySsl, logger: this._clientLog, net: dnsNet });
-        const keystore = new FileKeyStore(this._configModel.aunPath, {
+        const tokenStore = new LocalTokenStore(this._configModel.aunPath, {
             logger: this._logger.for('aun_core.keystore'),
-            secretStoreLogger: this._logger.for('aun_core.secret-store'),
         });
-        this._keystore = keystore;
-        // 启动时被动清理 registerAid 留下的孤儿临时目录（>10 分钟）
-        try {
-            const cleanup = keystore.cleanupPendingDirs;
-            if (typeof cleanup === 'function') {
-                const removed = cleanup.call(keystore, 600_000);
-                if (removed > 0) {
-                    this._clientLog.info(`_pending cleanup removed=${removed}`);
-                }
-            }
-        }
-        catch (err) {
-            this._clientLog.warn(`_pending cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
+        this._tokenStore = tokenStore;
         this._slotId = inputAid?.slotId || 'default';
         this._connectDeliveryMode = normalizeDeliveryModeConfig({ mode: 'fanout' });
         this._defaultConnectDeliveryMode = { ...this._connectDeliveryMode };
         this._auth = new AuthFlow({
-            keystore,
+            tokenStore,
             crypto: new CryptoProvider(),
             aid: initAid,
             deviceId: this._deviceId,
@@ -621,6 +653,24 @@ export class AUNClient {
             net: dnsNet,
         });
         this._aid = initAid;
+        this._agentMdManager = createAgentMdManagerForRuntime({
+            config: () => this._configModel,
+            logger: () => this._logger.for('aun_core.agent_md'),
+            ownerAid: () => this._aid,
+            currentAid: () => this._currentAid,
+            gateway: {
+                resolve: (target) => this._resolveGatewayForAid(target),
+                get: () => this._gatewayUrl,
+                set: (gatewayUrl) => { this._gatewayUrl = gatewayUrl; },
+            },
+            identity: {
+                get: () => this._identity,
+                set: (identity) => { this._identity = identity; },
+            },
+            auth: () => this._auth,
+            tokenStore: () => this._tokenStore,
+            fetchPeerCert: (target) => this._fetchPeerCert(target),
+        });
         this._transport = new RPCTransport({
             eventDispatcher: this._dispatcher,
             timeout: 10_000,
@@ -640,6 +690,7 @@ export class AUNClient {
                     public_key_der_b64: inputAid.publicKey,
                     cert: inputAid.certPem,
                 };
+                this._auth.setIdentity(this._identity);
                 this._state = 'standby';
             }
         }
@@ -729,21 +780,17 @@ export class AUNClient {
             rawConfig.root_ca_path = aid.rootCaPath;
         const nextConfig = configFromMap(rawConfig);
         try {
-            const close = this._keystore.close;
+            const close = this._tokenStore.close;
             if (typeof close === 'function')
-                close.call(this._keystore);
+                close.call(this._tokenStore);
         }
         catch {
-            // best-effort cleanup before switching keystore roots
+            // best-effort cleanup before switching tokenStore roots
         }
         this._configModel = nextConfig;
         this.config.aun_path = nextConfig.aunPath;
         this.config.root_ca_path = nextConfig.rootCaPath;
         this.config.seed_password = nextConfig.seedPassword;
-        this._agentMdPath = path.join(nextConfig.aunPath, 'AIDs');
-        this._agentMdCache.clear();
-        this._agentMdFetchInflight.clear();
-        this._agentMdDownloadInflight.clear();
         this._peerCache.clear();
         this._certCache.clear();
         this._gatewayUrl = null;
@@ -758,13 +805,12 @@ export class AUNClient {
             logger: this._clientLog,
         });
         this._discovery = new GatewayDiscovery({ verifySsl: nextConfig.verifySsl, logger: this._clientLog, net: dnsNet });
-        const keystore = new FileKeyStore(nextConfig.aunPath, {
+        const tokenStore = new LocalTokenStore(nextConfig.aunPath, {
             logger: this._logger.for('aun_core.keystore'),
-            secretStoreLogger: this._logger.for('aun_core.secret-store'),
         });
-        this._keystore = keystore;
+        this._tokenStore = tokenStore;
         this._auth = new AuthFlow({
-            keystore,
+            tokenStore,
             crypto: new CryptoProvider(),
             aid: aid.aid,
             deviceId: this._deviceId,
@@ -774,6 +820,24 @@ export class AUNClient {
             logger: this._logger.for('aun_core.auth'),
             net: dnsNet,
         });
+        this._agentMdManager = createAgentMdManagerForRuntime({
+            config: () => this._configModel,
+            logger: () => this._logger.for('aun_core.agent_md'),
+            ownerAid: () => this._aid,
+            currentAid: () => this._currentAid,
+            gateway: {
+                resolve: (target) => this._resolveGatewayForAid(target),
+                get: () => this._gatewayUrl,
+                set: (gatewayUrl) => { this._gatewayUrl = gatewayUrl; },
+            },
+            identity: {
+                get: () => this._identity,
+                set: (identity) => { this._identity = identity; },
+            },
+            auth: () => this._auth,
+            tokenStore: () => this._tokenStore,
+            fetchPeerCert: (target) => this._fetchPeerCert(target),
+        });
         this._transport = new RPCTransport({
             eventDispatcher: this._dispatcher,
             timeout: 10_000,
@@ -801,6 +865,8 @@ export class AUNClient {
             public_key_der_b64: aid.publicKey,
             cert: aid.certPem,
         };
+        // 注入内存私钥到 AuthFlow，禁止 AuthFlow 内部再走 keystore 解密
+        this._auth.setIdentity(this._identity);
         this._state = 'standby';
         this._closing = false;
         this._lastError = null;
@@ -858,772 +924,12 @@ export class AUNClient {
             throw new StateError('peers requires a loaded identity');
         return [...this._peerCache.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, v]) => v);
     }
-    async _resolveAgentMdUrl(aid) {
-        const target = String(aid ?? '').trim();
-        if (!target)
-            throw new ValidationError('agent.md requires non-empty aid');
-        let gatewayUrl = String(this._gatewayUrl ?? '').trim();
-        if (!gatewayUrl) {
-            try {
-                gatewayUrl = await this._resolveGatewayForAid(target);
-            }
-            catch {
-                gatewayUrl = '';
-            }
-        }
-        return `${agentMdHttpScheme(gatewayUrl)}://${agentMdAuthority(target, this._configModel.discoveryPort)}/agent.md`;
-    }
-    async _ensureAgentMdUploadToken(aid, gatewayUrl) {
-        let identity = this._auth.loadIdentityOrNone(aid);
-        if (!identity && this._identity && String(this._identity.aid ?? '') === aid) {
-            identity = this._identity;
-        }
-        if (!identity) {
-            throw new StateError('no local identity found, register or load an AID first');
-        }
-        const cachedToken = String(identity.access_token ?? '');
-        const expiresAt = this._auth.getAccessTokenExpiry(identity);
-        if (cachedToken && (expiresAt === null || expiresAt > Date.now() / 1000 + 30)) {
-            return cachedToken;
-        }
-        if (identity.refresh_token) {
-            try {
-                const refreshed = await this._auth.refreshCachedTokens(gatewayUrl, identity);
-                const refreshedToken = String(refreshed.access_token ?? '');
-                const refreshedExpiry = this._auth.getAccessTokenExpiry(refreshed);
-                if (refreshedToken && (refreshedExpiry === null || refreshedExpiry > Date.now() / 1000 + 30)) {
-                    this._identity = refreshed;
-                    return refreshedToken;
-                }
-            }
-            catch {
-                // refresh 失败时回退到完整 authenticate。
-            }
-        }
-        const result = await this._auth.authenticate(gatewayUrl, { aid });
-        const token = String(result.access_token ?? '');
-        if (!token)
-            throw new StateError('authenticate did not return access_token');
-        this._identity = this._auth.loadIdentityOrNone(aid) ?? {
-            ...identity,
-            access_token: token,
-            refresh_token: String(result.refresh_token ?? identity.refresh_token ?? ''),
-            access_token_expires_at: typeof result.expires_at === 'number' ? result.expires_at : identity.access_token_expires_at,
-            token_exp: typeof result.expires_at === 'number' ? result.expires_at : identity.token_exp,
-            expires_at: typeof result.expires_at === 'number' ? result.expires_at : identity.expires_at,
-        };
-        return token;
-    }
-    async _uploadAgentMd(content) {
-        const target = String(this._aid ?? this._currentAid?.aid ?? '').trim();
-        if (!target)
-            throw new StateError('uploadAgentMd requires local AID');
-        const gatewayUrl = await this._resolveGatewayForAid(target);
-        this._gatewayUrl = gatewayUrl;
-        const token = await this._ensureAgentMdUploadToken(target, gatewayUrl);
-        const response = await fetchWithTimeout(await this._resolveAgentMdUrl(target), {
-            method: 'PUT',
-            headers: {
-                Authorization: `Bearer ${token}`,
-                'Content-Type': 'text/markdown; charset=utf-8',
-            },
-            body: content,
-        });
-        if (response.status === 404) {
-            throw new NotFoundError(`agent.md endpoint not found for aid: ${target}`);
-        }
-        if (!response.ok) {
-            const message = (await response.text()).trim();
-            throw new AUNError(`upload agent.md failed: HTTP ${response.status}${message ? ` - ${message}` : ''}`);
-        }
-        const payload = await response.json();
-        if (!isJsonObject(payload))
-            throw new AUNError('upload agent.md returned invalid JSON payload');
-        return payload;
-    }
-    async _acquireAgentMdDownloadSlot() {
-        if (this._agentMdDownloadActive < AUNClient.AGENT_MD_DOWNLOAD_CONCURRENCY) {
-            this._agentMdDownloadActive += 1;
-            return () => this._releaseAgentMdDownloadSlot();
-        }
-        await new Promise((resolve) => {
-            this._agentMdDownloadWaiters.push(resolve);
-        });
-        return () => this._releaseAgentMdDownloadSlot();
-    }
-    _releaseAgentMdDownloadSlot() {
-        const next = this._agentMdDownloadWaiters.shift();
-        if (next) {
-            next();
-            return;
-        }
-        if (this._agentMdDownloadActive > 0)
-            this._agentMdDownloadActive -= 1;
-    }
-    async _downloadAgentMd(aid) {
-        const target = String(aid ?? '').trim();
-        if (!target)
-            throw new ValidationError('downloadAgentMd requires non-empty aid');
-        const existing = this._agentMdDownloadInflight.get(target);
-        if (existing)
-            return await existing;
-        const task = (async () => {
-            const release = await this._acquireAgentMdDownloadSlot();
-            try {
-                return await this._downloadAgentMdOnce(target);
-            }
-            finally {
-                release();
-            }
-        })();
-        this._agentMdDownloadInflight.set(target, task);
-        task.finally(() => {
-            if (this._agentMdDownloadInflight.get(target) === task) {
-                this._agentMdDownloadInflight.delete(target);
-            }
-        }).catch(() => undefined);
-        return await task;
-    }
-    async _downloadAgentMdOnce(target) {
-        const cached = this._agentMdCache.get(target);
-        const url = await this._resolveAgentMdUrl(target);
-        let response = await fetchWithTimeout(url, {
-            method: 'GET',
-            headers: { Accept: 'text/markdown' },
-            redirect: 'follow',
-        });
-        if (response.status === 304 && typeof cached?.text === 'string') {
-            return String(cached.text);
-        }
-        if (response.status === 304) {
-            response = await fetchWithTimeout(url, {
-                method: 'GET',
-                headers: { Accept: 'text/markdown' },
-                cache: 'reload',
-                redirect: 'follow',
-            });
-        }
-        if (response.status === 404) {
-            throw new NotFoundError(`agent.md not found for aid: ${target}`);
-        }
-        if (!response.ok) {
-            const message = (await response.text()).trim();
-            throw new AUNError(`download agent.md failed: HTTP ${response.status}${message ? ` - ${message}` : ''}`);
-        }
-        const text = await response.text();
-        const etag = String(response.headers?.get('ETag') ?? response.headers?.get('etag') ?? '').trim();
-        const lastModified = String(response.headers?.get('Last-Modified') ?? response.headers?.get('last-modified') ?? '').trim();
-        this._agentMdCache.set(target, {
-            ...(cached ?? {}),
-            text,
-            etag,
-            lastModified,
-            remote_etag: etag,
-            last_modified: lastModified,
-        });
-        return text;
-    }
-    async _headAgentMd(aid) {
-        const target = String(aid ?? '').trim();
-        if (!target)
-            throw new ValidationError('headAgentMd requires non-empty aid');
-        const response = await fetchWithTimeout(await this._resolveAgentMdUrl(target), {
-            method: 'HEAD',
-            headers: { Accept: 'text/markdown' },
-            redirect: 'follow',
-        }, 15_000);
-        const cached = this._agentMdCache.get(target) ?? {};
-        const etag = String(response.headers?.get('ETag') ?? response.headers?.get('etag') ?? '').trim();
-        const lastModified = String(response.headers?.get('Last-Modified') ?? response.headers?.get('last-modified') ?? '').trim();
-        if (response.status === 404) {
-            return { aid: target, found: false, etag: '', last_modified: '', status: 404 };
-        }
-        const resultEtag = response.status === 304 ? (etag || String(cached.etag ?? cached.remote_etag ?? '')) : etag;
-        const resultLastModified = response.status === 304 ? (lastModified || String(cached.lastModified ?? cached.last_modified ?? '')) : lastModified;
-        if (response.status < 200 || (response.status >= 300 && response.status !== 304)) {
-            throw new AUNError(`head agent.md failed: HTTP ${response.status}`);
-        }
-        this._agentMdCache.set(target, {
-            ...cached,
-            etag: resultEtag,
-            lastModified: resultLastModified,
-            remote_etag: resultEtag,
-            last_modified: resultLastModified,
-        });
-        return { aid: target, found: true, etag: resultEtag, last_modified: resultLastModified, status: response.status };
-    }
-    async _verifyAgentMd(content, aid, certPem) {
-        const target = String(aid ?? '').trim();
-        if (!target)
-            throw new ValidationError('verifyAgentMd requires non-empty aid');
-        let peer = target === this._currentAid?.aid ? this._currentAid : null;
-        if (!peer) {
-            let resolvedCert = String(certPem ?? '').trim();
-            if (!resolvedCert) {
-                try {
-                    resolvedCert = String(this._keystore.loadCert(target) ?? '').trim();
-                }
-                catch {
-                    resolvedCert = '';
-                }
-            }
-            if (!resolvedCert) {
-                if (!this._gatewayUrl) {
-                    try {
-                        this._gatewayUrl = await this._resolveGatewayForAid(target);
-                    }
-                    catch { /* best-effort before cert fetch */ }
-                }
-                resolvedCert = String(await this._fetchPeerCert(target) ?? '').trim();
-            }
-            if (!resolvedCert)
-                throw new NotFoundError(`certificate not found for aid: ${target}`);
-            peer = AID._create({
-                aid: target,
-                aunPath: this._configModel.aunPath,
-                certPem: resolvedCert,
-                privateKeyPem: null,
-                certValid: true,
-                privateKeyValid: false,
-            });
-        }
-        const result = peer.verifyAgentMd(content);
-        if (!result.ok)
-            throw new AUNError(result.error.message);
-        const vd = result.data;
-        return { ...vd, verified: vd.status === 'verified' };
-    }
-    /**
-     * 读取 {agentMdPath}/{self_aid}/agent.md，签名后上传，并把签名结果原子写回本地。
-     */
-    async publishAgentMd() {
-        const target = this._agentMdOwnerAid();
-        if (!target || !this._currentAid) {
-            throw new ValidationError('publishAgentMd requires local AID');
-        }
-        const content = this._readAgentMdContent(target);
-        const signed = this._currentAid?.signAgentMd(content);
-        if (!signed?.ok) {
-            throw new StateError(signed?.error.message ?? 'publishAgentMd requires a valid local AID private key');
-        }
-        const signedContent = signed.data.signed;
-        const result = await this._uploadAgentMd(signedContent);
-        this._localAgentMdEtag = this._agentMdContentEtag(signedContent);
-        const remoteEtag = isJsonObject(result) ? String(result.etag ?? '').trim() : '';
-        if (remoteEtag)
-            this._remoteAgentMdEtag = remoteEtag;
-        this._saveAgentMdRecord(target, {
-            content: signedContent,
-            local_etag: this._localAgentMdEtag,
-            remote_etag: remoteEtag || undefined,
-            last_modified: isJsonObject(result) ? String(result.last_modified ?? '').trim() : '',
-            fetched_at: Date.now(),
-            remote_status: remoteEtag ? 'found' : 'unknown',
-            last_error: '',
-        });
-        return result;
-    }
-    async _startAgentMdFetchTask(target) {
-        const existing = this._agentMdFetchInflight.get(target);
-        if (existing) {
-            return await existing;
-        }
-        const task = this._fetchAgentMdOnce(target);
-        this._agentMdFetchInflight.set(target, task);
-        task.finally(() => {
-            if (this._agentMdFetchInflight.get(target) === task) {
-                this._agentMdFetchInflight.delete(target);
-            }
-        }).catch(() => undefined);
-        return await task;
-    }
-    async _fetchAgentMdOnce(target) {
-        const content = await this._downloadAgentMd(target);
-        const signature = await this._verifyAgentMd(content, target);
-        const isSelf = target === (this._aid ?? '');
-        const localEtag = this._agentMdContentEtag(content);
-        const cacheMeta = this._agentMdAuthCacheMeta(target);
-        const remoteEtag = String(cacheMeta.etag ?? '').trim();
-        const lastModified = String(cacheMeta.lastModified ?? cacheMeta.last_modified ?? '').trim();
-        if (isSelf) {
-            this._localAgentMdEtag = localEtag;
-            if (remoteEtag)
-                this._remoteAgentMdEtag = remoteEtag;
-        }
-        const saved = this._saveAgentMdRecord(target, {
-            content,
-            local_etag: localEtag,
-            remote_etag: remoteEtag || undefined,
-            last_modified: lastModified || undefined,
-            fetched_at: Date.now(),
-            remote_status: 'found',
-            verify_status: isJsonObject(signature) ? String(signature.status ?? '') : '',
-            verify_error: isJsonObject(signature) ? String(signature.reason ?? '') : '',
-            last_error: '',
-        });
-        let inSync = null;
-        if (isSelf) {
-            const remote = remoteEtag || this._remoteAgentMdEtag || '';
-            inSync = localEtag && remote ? localEtag === remote : false;
-        }
-        return {
-            aid: target,
-            content,
-            signature: signature,
-            in_sync: inSync,
-            saved_to: String(saved.saved_to ?? this._agentMdFilePath(target)),
-            save_error: null,
-        };
-    }
-    /**
-     * 设置 agent.md 本地存储根目录；为空时恢复默认 {aun_path}/AIDs。
-     */
-    _setAgentMdRoot(root) {
-        const raw = String(root ?? '').trim();
-        const next = raw || path.join(this._configModel.aunPath, 'AIDs');
-        fs.mkdirSync(next, { recursive: true });
-        this._agentMdPath = next;
-        this._agentMdCache.clear();
-        return this._agentMdPath;
-    }
-    /** 返回本地 agent.md 文件的 etag；未设置或读取失败时返回空串。 */
-    getLocalAgentMdEtag() {
-        return this._localAgentMdEtag;
-    }
-    /**
-     * 返回 gateway 在最近一次 RPC envelope._meta 注入的服务端 agent.md etag。
-     *
-     * 未收到过则为空串；不阻塞调用，纯内存读。
-     */
-    getRemoteAgentMdEtag() {
-        return this._remoteAgentMdEtag;
-    }
-    _agentMdContentEtag(content) {
-        return `"${crypto.createHash('sha256').update(String(content ?? ''), 'utf-8').digest('hex')}"`;
-    }
-    _agentMdOwnerAid() {
-        return String(this._aid ?? '').trim();
-    }
-    _agentMdSafeAid(aid) {
-        const target = String(aid ?? '').trim();
-        if (!target || target.includes('/') || target.includes('\\') || target.includes('\0')) {
-            throw new ValidationError('agent.md aid is empty or contains path separators');
-        }
-        return target;
-    }
-    _agentMdRoot() {
-        const root = this._agentMdPath || path.join(this._configModel.aunPath, 'AIDs');
-        fs.mkdirSync(root, { recursive: true });
-        return root;
-    }
-    _agentMdFilePath(aid) {
-        return path.join(this._agentMdRoot(), this._agentMdSafeAid(aid), 'agent.md');
-    }
-    _agentMdMetaPath(aid) {
-        return path.join(this._agentMdRoot(), this._agentMdSafeAid(aid), 'agentmd.json');
-    }
-    _atomicWriteText(filePath, content) {
-        fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        const tmp = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
-        let fd = null;
-        try {
-            fd = fs.openSync(tmp, 'w');
-            fs.writeFileSync(fd, content, 'utf-8');
-            fs.fsyncSync(fd);
-            fs.closeSync(fd);
-            fd = null;
-            fs.renameSync(tmp, filePath);
-            try {
-                const dirFd = fs.openSync(path.dirname(filePath), 'r');
-                try {
-                    fs.fsyncSync(dirFd);
-                }
-                finally {
-                    fs.closeSync(dirFd);
-                }
-            }
-            catch { /* best effort */ }
-        }
-        finally {
-            if (fd !== null) {
-                try {
-                    fs.closeSync(fd);
-                }
-                catch { /* ignore */ }
-            }
-            if (fs.existsSync(tmp)) {
-                try {
-                    fs.unlinkSync(tmp);
-                }
-                catch { /* ignore */ }
-            }
-        }
-    }
-    _sleepSync(ms) {
-        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-    }
-    _withAgentMdRecordLock(aid, fn) {
-        const lockPath = path.join(path.dirname(this._agentMdMetaPath(aid)), 'agentmd.json.lock');
-        fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-        const deadline = Date.now() + 5000;
-        let fd = null;
-        while (fd === null) {
-            try {
-                fd = fs.openSync(lockPath, 'wx');
-                fs.writeFileSync(fd, `${process.pid}\n`, 'utf-8');
-            }
-            catch (err) {
-                if (err?.code !== 'EEXIST' || Date.now() >= deadline)
-                    throw err;
-                try {
-                    const st = fs.statSync(lockPath);
-                    if (Date.now() - st.mtimeMs > 30000)
-                        fs.unlinkSync(lockPath);
-                }
-                catch { /* ignore */ }
-                this._sleepSync(25);
-            }
-        }
-        try {
-            return fn();
-        }
-        finally {
-            if (fd !== null) {
-                try {
-                    fs.closeSync(fd);
-                }
-                catch { /* ignore */ }
-            }
-            try {
-                fs.unlinkSync(lockPath);
-            }
-            catch { /* ignore */ }
-        }
-    }
-    _writeAgentMdRecordUnlocked(aid, record) {
-        const payload = {};
-        for (const [key, value] of Object.entries(record)) {
-            if (key !== 'content' && value !== undefined && value !== null)
-                payload[key] = value;
-        }
-        payload.aid = this._agentMdSafeAid(aid);
-        this._atomicWriteText(this._agentMdMetaPath(aid), `${JSON.stringify(payload, null, 2)}\n`);
-    }
-    _normalizeAgentMdRecord(aid, data) {
-        if (!isJsonObject(data))
-            return {};
-        const record = {};
-        for (const [key, value] of Object.entries(data)) {
-            if (key !== 'content')
-                record[key] = value;
-        }
-        record.aid = this._agentMdSafeAid(String(record.aid ?? aid));
-        for (const key of ['fetched_at', 'observed_at', 'checked_at', 'updated_at']) {
-            record[key] = Number(record[key] ?? 0) || 0;
-        }
-        return record;
-    }
-    _readAgentMdRecordUnlocked(aid) {
-        const filePath = this._agentMdMetaPath(aid);
-        if (!fs.existsSync(filePath))
-            return {};
-        try {
-            return this._normalizeAgentMdRecord(aid, JSON.parse(fs.readFileSync(filePath, 'utf-8')));
-        }
-        catch (err) {
-            this._clientLog.warn(`agent.md metadata damaged, ignoring: aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
-            return {};
-        }
-    }
-    _readAgentMdContent(aid) {
-        return fs.readFileSync(this._agentMdFilePath(aid), 'utf-8');
-    }
-    _writeAgentMdContent(aid, content) {
-        const filePath = this._agentMdFilePath(aid);
-        this._atomicWriteText(filePath, String(content ?? ''));
-        return filePath;
-    }
-    _agentMdAuthCacheMeta(aid) {
-        try {
-            const record = this._agentMdCache.get(String(aid ?? '').trim());
-            return record && typeof record === 'object' ? { ...record } : {};
-        }
-        catch {
-            return {};
-        }
-    }
-    _loadAgentMdRecord(aid) {
-        const target = String(aid ?? '').trim();
-        if (!target)
-            return null;
-        try {
-            const loaded = this._withAgentMdRecordLock(target, () => {
-                const record = this._readAgentMdRecordUnlocked(target);
-                const next = Object.keys(record).length > 0 ? { ...record, aid: target } : { aid: target };
-                try {
-                    const content = this._readAgentMdContent(target);
-                    next.content = content;
-                    next.local_etag = this._agentMdContentEtag(content);
-                }
-                catch (err) {
-                    if (fs.existsSync(this._agentMdMetaPath(target))) {
-                        this._clientLog.warn(`agent.md content read failed: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
-                    }
-                }
-                return next;
-            });
-            if (Object.keys(loaded).length <= 1)
-                return null;
-            this._agentMdCache.set(target, { ...loaded });
-            return { ...loaded };
-        }
-        catch (err) {
-            this._clientLog.debug(`agent.md cache load skipped: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
-        }
-        return null;
-    }
-    _saveAgentMdRecord(aid, fields) {
-        const target = String(aid ?? '').trim();
-        if (!target)
-            return {};
-        try {
-            const inputFields = { ...fields };
-            const hasContent = Object.prototype.hasOwnProperty.call(inputFields, 'content') && inputFields.content !== undefined && inputFields.content !== null;
-            let savedTo = '';
-            const record = this._withAgentMdRecordLock(target, () => {
-                if (hasContent) {
-                    const content = String(inputFields.content ?? '');
-                    savedTo = this._writeAgentMdContent(target, content);
-                    if (!inputFields.local_etag)
-                        inputFields.local_etag = this._agentMdContentEtag(content);
-                    if (!inputFields.fetched_at)
-                        inputFields.fetched_at = Date.now();
-                }
-                delete inputFields.content;
-                const next = { ...this._readAgentMdRecordUnlocked(target), aid: target };
-                for (const [key, value] of Object.entries(inputFields)) {
-                    if (value !== undefined && value !== null)
-                        next[key] = value;
-                }
-                next.updated_at = Date.now();
-                this._writeAgentMdRecordUnlocked(target, next);
-                return next;
-            });
-            const loaded = { ...record };
-            if (hasContent) {
-                loaded.content = String(fields.content ?? '');
-                if (savedTo)
-                    loaded.saved_to = savedTo;
-            }
-            this._agentMdCache.set(target, { ...loaded });
-            const owner = this._agentMdOwnerAid();
-            if (target === owner) {
-                const localEtag = String(loaded.local_etag ?? '').trim();
-                const remoteEtag = String(loaded.remote_etag ?? '').trim();
-                if (localEtag)
-                    this._localAgentMdEtag = localEtag;
-                if (remoteEtag)
-                    this._remoteAgentMdEtag = remoteEtag;
-            }
-            return { ...loaded };
-        }
-        catch (err) {
-            this._clientLog.debug(`agent.md cache save skipped: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
-        }
-        return {};
-    }
-    _agentMdHasLocalContent(aid, record) {
-        if (record && typeof record.content === 'string' && record.content.length > 0)
-            return true;
-        try {
-            return fs.existsSync(this._agentMdFilePath(aid));
-        }
-        catch {
-            return false;
-        }
-    }
-    _agentMdCheckedAtFresh(checkedAtMs, maxUnsyncedDays) {
-        const days = Number(maxUnsyncedDays || 0);
-        if (!Number.isFinite(days) || days <= 0)
-            return false;
-        if (!Number.isFinite(checkedAtMs) || checkedAtMs <= 0)
-            return false;
-        return Date.now() - checkedAtMs <= days * 86400000;
-    }
-    _agentMdLastModifiedFresh(lastModified, maxUnsyncedDays) {
-        const days = Number(maxUnsyncedDays || 0);
-        if (!Number.isFinite(days) || days <= 0)
-            return false;
-        const ts = Date.parse(String(lastModified ?? '').trim());
-        if (!Number.isFinite(ts))
-            return false;
-        return Date.now() <= ts + days * 86400000;
-    }
-    _scheduleAgentMdFetchIfMissing(aid, record, source = '') {
-        const target = String(aid ?? '').trim();
-        if (!target || this._agentMdHasLocalContent(target, record))
-            return;
-        if (this._agentMdFetchInflight.has(target))
-            return;
-        void this._startAgentMdFetchTask(target).catch((err) => {
-            this._saveAgentMdRecord(target, {
-                last_error: err instanceof Error ? err.message : String(err),
-                remote_status: 'found',
-            });
-            this._clientLog.debug(`agent.md auto fetch failed: aid=${target} source=${source || '-'} err=${err instanceof Error ? err.message : String(err)}`);
-        });
-    }
-    _observeAgentMdMeta(aid, etag = '', lastModified = '', source = '') {
-        const target = String(aid ?? '').trim();
-        const remoteEtag = String(etag ?? '').trim();
-        const remoteLastModified = String(lastModified ?? '').trim();
-        if (!target || (!remoteEtag && !remoteLastModified))
-            return;
-        let before = this._agentMdCache.get(target);
-        if (!before || typeof before !== 'object')
-            before = this._loadAgentMdRecord(target) ?? {};
-        const same = (!remoteEtag || String(before.remote_etag ?? '').trim() === remoteEtag) &&
-            (!remoteLastModified || String(before.last_modified ?? '').trim() === remoteLastModified);
-        let record = { ...before };
-        if (!same || Object.keys(before).length === 0) {
-            const fields = {
-                observed_at: Date.now(),
-                remote_status: 'found',
-            };
-            if (remoteEtag)
-                fields.remote_etag = remoteEtag;
-            if (remoteLastModified)
-                fields.last_modified = remoteLastModified;
-            record = this._saveAgentMdRecord(target, fields) || record;
-        }
-        if (target === this._agentMdOwnerAid() && remoteEtag)
-            this._remoteAgentMdEtag = remoteEtag;
-        this._scheduleAgentMdFetchIfMissing(target, record, source);
-        this._clientLog.debug(`agent.md meta observed: aid=${target} etag=${remoteEtag || '-'} last_modified=${remoteLastModified || '-'} source=${source || '-'}`);
-    }
-    _observeAgentMdEtag(aid, etag, source = '') {
-        this._observeAgentMdMeta(aid, etag, '', source);
-    }
-    _observeAgentMdFromEnvelope(envelope) {
-        if (!isJsonObject(envelope))
-            return;
-        const env = envelope;
-        if (!isJsonObject(env.agent_md))
-            return;
-        const agentMd = env.agent_md;
-        if (!isJsonObject(agentMd.sender))
-            return;
-        const sender = agentMd.sender;
-        let senderAid = String(sender.aid ?? '').trim();
-        if (!senderAid) {
-            const aad = isJsonObject(env.aad) ? env.aad : {};
-            senderAid = String(aad.from ?? env.from ?? '').trim();
-        }
-        this._observeAgentMdMeta(senderAid, String(sender.etag ?? '').trim(), String(sender.last_modified ?? sender.lastModified ?? '').trim(), 'envelope');
-    }
-    async _checkAgentMdCache(aid, maxUnsyncedDays = 1) {
-        const target = String(aid ?? this._aid ?? '').trim();
-        if (!target)
-            throw new ValidationError('checkAgentMd requires aid (or local AID)');
-        const before = this._loadAgentMdRecord(target) ?? {};
-        const localEtag = String(before.local_etag ?? '').trim();
-        const localFound = !!(Object.keys(before).length > 0 && (String(before.content ?? '') || localEtag));
-        const remoteEtagCached = String(before.remote_etag ?? '').trim();
-        const lastModifiedCached = String(before.last_modified ?? '').trim();
-        const checkedAt = Number(before.checked_at ?? 0);
-        const fetchedAt = Number(before.fetched_at ?? 0);
-        const checkedAtCached = checkedAt > 0 ? checkedAt : fetchedAt;
-        const cachedInSync = !!(localFound && localEtag && remoteEtagCached && localEtag === remoteEtagCached);
-        // max_unsynced_days > 0 且距上次 HEAD 在窗口内 → 直接返回缓存；否则强制 HEAD。
-        if (cachedInSync && this._agentMdCheckedAtFresh(checkedAtCached, maxUnsyncedDays)) {
-            return {
-                aid: target,
-                local_found: true,
-                remote_found: true,
-                local_etag: localEtag,
-                remote_etag: remoteEtagCached,
-                in_sync: true,
-                last_modified: lastModifiedCached,
-                status: 200,
-                cached: true,
-                verify_status: String(before.verify_status ?? ''),
-                verify_error: String(before.verify_error ?? ''),
-            };
-        }
-        const remoteFoundCached = !!(remoteEtagCached || String(before.remote_status ?? '') === 'found');
-        if (!localFound &&
-            !remoteFoundCached &&
-            String(before.remote_status ?? '') === 'missing' &&
-            this._agentMdCheckedAtFresh(checkedAtCached, maxUnsyncedDays)) {
-            return {
-                aid: target,
-                local_found: false,
-                remote_found: false,
-                local_etag: '',
-                remote_etag: '',
-                in_sync: false,
-                last_modified: '',
-                status: 404,
-                cached: true,
-                verify_status: '',
-                verify_error: '',
-            };
-        }
-        const now = Date.now();
-        let remote;
-        try {
-            remote = await this._headAgentMd(target);
-        }
-        catch (err) {
-            this._saveAgentMdRecord(target, { checked_at: now, remote_status: 'error', last_error: err instanceof Error ? err.message : String(err) });
-            throw err;
-        }
-        const remoteFound = !!remote.found;
-        const remoteEtag = String(remote.etag ?? '').trim();
-        const lastModified = String(remote.last_modified ?? remote.lastModified ?? '').trim();
-        const saved = this._saveAgentMdRecord(target, {
-            remote_etag: remoteFound ? remoteEtag : '',
-            last_modified: lastModified,
-            checked_at: now,
-            remote_status: remoteFound ? 'found' : 'missing',
-            last_error: '',
-        });
-        if (target === this._agentMdOwnerAid() && remoteEtag)
-            this._remoteAgentMdEtag = remoteEtag;
-        const inSync = !!(localFound && remoteFound && localEtag && remoteEtag && localEtag === remoteEtag);
-        return {
-            aid: target,
-            local_found: localFound,
-            remote_found: remoteFound,
-            local_etag: localEtag,
-            remote_etag: remoteEtag,
-            in_sync: inSync,
-            last_modified: lastModified,
-            status: Number(remote.status ?? (remoteFound ? 200 : 404)),
-            cached: false,
-            verify_status: String(saved.verify_status ?? before.verify_status ?? ''),
-            verify_error: String(saved.verify_error ?? before.verify_error ?? ''),
-        };
+    async uploadAgentMd(content) {
+        return await this._agentMdManager.upload(content);
     }
     /** transport 的 meta observer：吸收 gateway 注入的 _meta 字段。失败不影响业务。 */
     _observeRpcMeta(meta) {
-        if (!meta || typeof meta !== 'object')
-            return;
-        const etag = String(meta.agent_md_etag ?? '').trim();
-        if (etag) {
-            this._remoteAgentMdEtag = etag;
-            this._observeAgentMdMeta(this._aid ?? '', etag, '', 'rpc.self');
-        }
-        const etags = meta.agent_md_etags;
-        if (isJsonObject(etags)) {
-            // role key 优先级：requester / peer 是新规范，其余是兼容旧 SDK 的别名。
-            for (const key of ['requester', 'peer', 'receiver', 'target', 'to', 'sender', 'from']) {
-                const item = etags[key];
-                if (!isJsonObject(item))
-                    continue;
-                this._observeAgentMdMeta(String(item.aid ?? ''), String(item.etag ?? ''), String(item.last_modified ?? item.lastModified ?? ''), `rpc.${key}`);
-            }
-        }
+        this._agentMdManager.observeRpcMeta(meta, this._aid);
     }
     /** 连接状态 */
     get state() {
@@ -1781,8 +1087,8 @@ export class AUNClient {
             this._stopBackgroundTasks();
             this._stopReconnect();
             if (this.state === ConnectionState.NO_IDENTITY || this.state === ConnectionState.CLOSED) {
-                const closableKeyStore = this._keystore;
-                closableKeyStore.close?.();
+                const closableStore = this._tokenStore;
+                closableStore.close?.();
                 this._state = 'closed';
                 this._logger.close();
                 this._resetSeqTrackingState();
@@ -1790,8 +1096,8 @@ export class AUNClient {
                 return;
             }
             await this._transport.close();
-            const closableKeyStore = this._keystore;
-            closableKeyStore.close?.();
+            const closableStore = this._tokenStore;
+            closableStore.close?.();
             this._state = 'closed';
             this._logger.close();
             await this._dispatcher.publish('state_change', { state: this._publicState(this._state) });
@@ -2548,15 +1854,11 @@ export class AUNClient {
         // 注入本地/远端 agent.md etag，让应用层判断版本一致性；失败不影响业务。
         if (isJsonObject(payload)) {
             try {
-                const localEtag = this._localAgentMdEtag || '';
-                const remoteEtag = this._remoteAgentMdEtag || '';
-                if (localEtag || remoteEtag) {
+                const snapshot = this._agentMdManager.eventSnapshot();
+                if (snapshot) {
                     const obj = payload;
                     if (!('_agent_md' in obj)) {
-                        obj._agent_md = {
-                            local_etag: localEtag,
-                            remote_etag: remoteEtag,
-                        };
+                        obj._agent_md = snapshot;
                     }
                 }
             }
@@ -3369,8 +2671,8 @@ export class AUNClient {
             const membershipSnapshot = String(d.membership_snapshot ?? '').trim();
             const policySnapshot = String(d.policy_snapshot ?? '').trim();
             // 1. 验证 prev_state_hash 连续性
-            const loadFn = this._keystore.loadGroupState;
-            const localState = loadFn ? loadFn.call(this._keystore, groupId) : null;
+            const loadFn = this._tokenStore.loadGroupState;
+            const localState = loadFn ? loadFn.call(this._tokenStore, groupId) : null;
             if (localState && localState.state_hash && localState.state_hash !== prevStateHash) {
                 this._clientLog.warn(`state_hash chain discontinuous group=${groupId} local_sv=${localState.state_version} event_sv=${stateVersion}`);
                 // 回源同步
@@ -3396,9 +2698,9 @@ export class AUNClient {
                                 return;
                             }
                         }
-                        const saveFn = this._keystore.saveGroupState;
+                        const saveFn = this._tokenStore.saveGroupState;
                         if (saveFn) {
-                            saveFn.call(this._keystore, groupId, sv, sHash, sEpoch, sMembersJson || membershipSnapshot, sPolicyJson || policySnapshot);
+                            saveFn.call(this._tokenStore, groupId, sv, sHash, sEpoch, sMembersJson || membershipSnapshot, sPolicyJson || policySnapshot);
                         }
                     }
                 }
@@ -3419,9 +2721,9 @@ export class AUNClient {
                 return;
             }
             // 3. 更新本地存储
-            const saveFn = this._keystore.saveGroupState;
+            const saveFn = this._tokenStore.saveGroupState;
             if (saveFn) {
-                saveFn.call(this._keystore, groupId, stateVersion, stateHash, keyEpoch, membershipSnapshot, policySnapshot);
+                saveFn.call(this._tokenStore, groupId, stateVersion, stateHash, keyEpoch, membershipSnapshot, policySnapshot);
             }
             this._clientLog.debug(`_onGroupStateCommitted exit: elapsed=${Date.now() - tStart}ms group=${groupId}`);
         }
@@ -3581,7 +2883,7 @@ export class AUNClient {
         }
         try {
             // peer 证书只存版本目录，不覆盖 cert.pem
-            this._keystore.saveCert(aid, certPem, certFingerprint, { makeActive: false });
+            this._tokenStore.saveCert(aid, certPem, certFingerprint, { makeActive: false });
         }
         catch (exc) {
             this._clientLog.error(`failed to write cert to keystore (aid=${aid}, fp=${certFingerprint ?? ''}): ${formatCaughtError(exc)}`, exc instanceof Error ? exc : undefined);
@@ -3852,9 +3154,9 @@ export class AUNClient {
             return;
         try {
             // 优先从 seq_tracker 表按行读取
-            const loadAll = this._keystore.loadAllSeqs;
+            const loadAll = this._tokenStore.loadAllSeqs;
             if (typeof loadAll === 'function') {
-                let state = loadAll.call(this._keystore, this._aid, this._deviceId, this._slotId);
+                let state = loadAll.call(this._tokenStore, this._aid, this._deviceId, this._slotId);
                 if (state && Object.keys(state).length > 0) {
                     state = this._migrateSeqStateGroupIds(state);
                     this._seqTracker.restoreState(state);
@@ -3862,9 +3164,9 @@ export class AUNClient {
                 }
             }
             // fallback: 从旧 instance_state JSON blob 恢复
-            const loader = this._keystore.loadInstanceState;
+            const loader = this._tokenStore.loadInstanceState;
             if (typeof loader === 'function') {
-                const instanceState = loader.call(this._keystore, this._aid, this._deviceId, this._slotId);
+                const instanceState = loader.call(this._tokenStore, this._aid, this._deviceId, this._slotId);
                 if (instanceState && typeof instanceState.seq_tracker_state === 'object') {
                     let state = instanceState.seq_tracker_state;
                     state = this._migrateSeqStateGroupIds(state);
@@ -3915,20 +3217,20 @@ export class AUNClient {
         }
         this._clientLog.info(`SeqTracker group_id migration: ${Object.keys(renameMap).length} namespaces rewritten`);
         // 落盘
-        const saver = this._keystore.saveSeq;
-        const deleter = this._keystore.deleteSeq;
+        const saver = this._tokenStore.saveSeq;
+        const deleter = this._tokenStore.deleteSeq;
         if (typeof saver === 'function' && this._aid) {
             for (const [oldNs, newNs] of Object.entries(renameMap)) {
                 if (typeof deleter === 'function') {
                     try {
-                        deleter.call(this._keystore, this._aid, this._deviceId, this._slotId, oldNs);
+                        deleter.call(this._tokenStore, this._aid, this._deviceId, this._slotId, oldNs);
                     }
                     catch (e) {
                         this._clientLog.debug(`delete old seq ns failed: ns=${oldNs} err=${formatCaughtError(e)}`);
                     }
                 }
                 try {
-                    saver.call(this._keystore, this._aid, this._deviceId, this._slotId, newNs, newState[newNs]);
+                    saver.call(this._tokenStore, this._aid, this._deviceId, this._slotId, newNs, newState[newNs]);
                 }
                 catch (e) {
                     this._clientLog.debug(`write new seq ns failed: ns=${newNs} err=${formatCaughtError(e)}`);
@@ -3976,17 +3278,17 @@ export class AUNClient {
             return;
         try {
             // 优先按行写入 seq_tracker 表
-            const saveFn = this._keystore.saveSeq;
+            const saveFn = this._tokenStore.saveSeq;
             if (typeof saveFn === 'function') {
                 for (const [ns, seq] of Object.entries(state)) {
-                    saveFn.call(this._keystore, this._aid, this._deviceId, this._slotId, ns, seq);
+                    saveFn.call(this._tokenStore, this._aid, this._deviceId, this._slotId, ns, seq);
                 }
                 return;
             }
             // fallback: 旧版 updateInstanceState JSON blob
-            const updater = this._keystore.updateInstanceState;
+            const updater = this._tokenStore.updateInstanceState;
             if (typeof updater === 'function') {
-                updater.call(this._keystore, this._aid, this._deviceId, this._slotId, (metadata) => {
+                updater.call(this._tokenStore, this._aid, this._deviceId, this._slotId, (metadata) => {
                     metadata.seq_tracker_state = state;
                     return metadata;
                 });
@@ -4009,13 +3311,13 @@ export class AUNClient {
             return;
         const seq = this._seqTracker.getContiguousSeq(ns);
         try {
-            if (seq > 0 && typeof this._keystore.saveSeq === 'function') {
-                this._keystore.saveSeq(this._aid, this._deviceId, this._slotId, ns, seq);
+            if (seq > 0 && typeof this._tokenStore.saveSeq === 'function') {
+                this._tokenStore.saveSeq(this._aid, this._deviceId, this._slotId, ns, seq);
                 return;
             }
-            const deleteSeq = this._keystore.deleteSeq;
+            const deleteSeq = this._tokenStore.deleteSeq;
             if (seq <= 0 && typeof deleteSeq === 'function') {
-                deleteSeq.call(this._keystore, this._aid, this._deviceId, this._slotId, ns);
+                deleteSeq.call(this._tokenStore, this._aid, this._deviceId, this._slotId, ns);
                 return;
             }
             if (seq > 0) {
@@ -4247,17 +3549,7 @@ export class AUNClient {
             this._v2BootstrapCache.clear();
         }
         let identity = this._identity;
-        if (!identity) {
-            try {
-                identity = this._keystore.loadIdentity(this._aid);
-                if (identity)
-                    this._identity = identity;
-            }
-            catch {
-                identity = null;
-            }
-        }
-        // 私钥由 AIDStore 管理，直接从 _currentAid 读取明文私钥
+        // 私钥来自当前 AID 值对象，AUNClient 不从持久化存储读取私钥。
         const currentAid = this._currentAid;
         if (!currentAid?.privateKeyPem) {
             this._clientLog.warn('V2 session init skipped: no AID private key');
@@ -4271,8 +3563,8 @@ export class AUNClient {
         const aidPriv = _v2LeftPad32(_v2B64uToBytes(jwk.d));
         const pubDer = crypto.createPublicKey(privateKey).export({ format: 'der', type: 'spki' });
         const aidPubDer = new Uint8Array(pubDer);
-        const storeProvider = this._keystore;
-        const v2Store = storeProvider.getV2KeyStore?.call(this._keystore, this._aid);
+        const storeProvider = this._tokenStore;
+        const v2Store = storeProvider.getV2KeyStore?.call(this._tokenStore, this._aid);
         if (!v2Store) {
             throw new StateError('V2 key store is unavailable for current keystore');
         }
@@ -4282,6 +3574,28 @@ export class AUNClient {
         this._clientLog.debug(`V2 session initialized aid=${this._aid} device=${this._deviceId}`);
         // 群 state proposal 由服务端在 client.online 时定向通知。
     }
+    _currentV2KeyStore() {
+        if (this._v2KeyStore)
+            return this._v2KeyStore;
+        if (!this._aid)
+            throw new StateError('V2 key store requires a loaded AID');
+        const storeProvider = this._tokenStore;
+        const v2Store = storeProvider.getV2KeyStore?.call(this._tokenStore, this._aid);
+        if (!v2Store) {
+            throw new StateError('V2 key store is unavailable for current identity');
+        }
+        this._v2KeyStore = v2Store;
+        return v2Store;
+    }
+    _saveGroupIdentityToV2(groupAid, identity) {
+        const privateKeyPem = String(identity.private_key_pem ?? '').trim();
+        const publicKeyDerB64 = String(identity.public_key_der_b64 ?? '').trim();
+        if (!groupAid || !privateKeyPem || !publicKeyDerB64) {
+            throw new StateError('group identity is incomplete');
+        }
+        const pubDer = new Uint8Array(Buffer.from(publicKeyDerB64, 'base64'));
+        this._currentV2KeyStore().saveGroupIdentity(this._deviceId, groupAid, privateKeyPem, pubDer);
+    }
     async _v2TrustedIKPubDer(aid) {
         const normalizedAid = String(aid ?? '').trim();
         if (!normalizedAid)
@@ -5263,7 +4577,7 @@ export class AUNClient {
             return null;
         }
         const e2eeMeta = this._v2E2eeMeta(envelope);
-        this._observeAgentMdFromEnvelope(envelope);
+        this._agentMdManager.observeEnvelope(envelope);
         let spkId = '';
         let recipientKeySource = '';
         if (isJsonObject(envelope.recipient)) {
@@ -5468,7 +4782,7 @@ export class AUNClient {
     _attachV2EnvelopeMetadataFromSource(message, source) {
         const envelope = this._extractV2EnvelopeFromSource(source);
         if (envelope) {
-            this._observeAgentMdFromEnvelope(envelope);
+            this._agentMdManager.observeEnvelope(envelope);
             this._attachV2EnvelopeMetadata(message, this._v2E2eeMeta(envelope));
         }
     }
@@ -6555,9 +5869,9 @@ export class AUNClient {
         if (this._gatewayUrl)
             return this._gatewayUrl;
         try {
-            const loadMetadata = this._keystore.loadMetadata;
+            const loadMetadata = this._tokenStore.loadMetadata;
             const cachedGateway = typeof loadMetadata === 'function'
-                ? String(loadMetadata.call(this._keystore, resolvedAid)?.gateway_url ?? '').trim()
+                ? String(loadMetadata.call(this._tokenStore, resolvedAid)?.gateway_url ?? '').trim()
                 : '';
             if (cachedGateway) {
                 this._gatewayUrl = cachedGateway;
@@ -6579,9 +5893,9 @@ export class AUNClient {
                 const gateway = await this._discovery.discover(url);
                 this._gatewayUrl = gateway;
                 try {
-                    const saveMetadata = this._keystore.saveMetadata;
+                    const saveMetadata = this._tokenStore.saveMetadata;
                     if (typeof saveMetadata === 'function') {
-                        saveMetadata.call(this._keystore, resolvedAid, { gateway_url: gateway, gateway_cached_at: Date.now() });
+                        saveMetadata.call(this._tokenStore, resolvedAid, { gateway_url: gateway, gateway_cached_at: Date.now() });
                     }
                 }
                 catch {
@@ -6627,9 +5941,8 @@ export class AUNClient {
     }
     /** 连接后同步身份信息 */
     _syncIdentityAfterConnect(accessToken) {
-        const identity = this._auth.loadIdentityOrNone(this._aid ?? undefined);
+        const identity = this._identity;
         if (identity === null) {
-            this._identity = null;
             return;
         }
         identity.access_token = accessToken;
@@ -6640,9 +5953,7 @@ export class AUNClient {
         const persistIdentity = this._auth._persistIdentity;
         if (typeof persistIdentity === 'function') {
             persistIdentity.call(this._auth, identity);
-            return;
         }
-        this._keystore.saveIdentity(String(identity.aid), identity);
     }
     // ── 内部：参数处理 ────────────────────────────────────────
     /** 规范化连接参数 */
@@ -6826,7 +6137,7 @@ export class AUNClient {
                     scheduleNext();
                     return;
                 }
-                let identity = this._identity ?? this._auth.loadIdentityOrNone() ?? null;
+                let identity = this._identity;
                 if (identity === null) {
                     scheduleNext();
                     return;
@@ -6954,8 +6265,8 @@ export class AUNClient {
         if ('device_id' in params && String(params.device_id ?? '').trim() !== this._deviceId) {
             throw new ValidationError('message.pull/message.ack device_id must match the current client instance');
         }
-        const slotId = normalizeInstanceId(params.slot_id ?? this._slotId, 'slot_id', { allowEmpty: true });
-        if (slotId !== this._slotId) {
+        const slotId = normalizeSlotId(params.slot_id ?? this._slotId, this._slotId);
+        if (slotIsolationKey(slotId) !== slotIsolationKey(this._slotId)) {
             throw new ValidationError('message.pull/message.ack slot_id must match the current client instance');
         }
         params.device_id = this._deviceId;
@@ -7175,8 +6486,7 @@ export class AUNClient {
     }
     // ── Named Group（命名群）高层 API ────────────────────────────
     /**
-     * 创建命名群：本地生成 P-256 keypair，调用 group.create 传入 public_key，
-     * 服务端签发群 AID 证书，返回后将证书和私钥存入 keystore。
+     * 创建命名群：群/P2P 私钥由 V2 数据库存储，不写入 AID 身份私钥存储。
      */
     async createNamedGroup(groupName, opts = {}) {
         const tStart = Date.now();
@@ -7196,15 +6506,10 @@ export class AUNClient {
             const aidCert = result?.aid_cert;
             const groupAid = String(groupInfo?.group_aid ?? '');
             if (groupAid && aidCert) {
-                this._keystore.saveIdentity(groupAid, {
-                    private_key_pem: identity.private_key_pem,
-                    public_key: identity.public_key_der_b64,
-                    curve: 'P-256',
-                    type: 'group_identity',
-                });
+                this._saveGroupIdentityToV2(groupAid, identity);
                 const certPem = String(aidCert.cert ?? '');
                 if (certPem) {
-                    this._keystore.saveCert(groupAid, certPem);
+                    this._tokenStore.saveCert(groupAid, certPem);
                 }
             }
             this._clientLog.debug(`createNamedGroup exit: elapsed=${Date.now() - tStart}ms groupAid=${groupAid}`);
@@ -7235,15 +6540,10 @@ export class AUNClient {
             const aidCert = result?.aid_cert;
             const groupAid = String(groupInfo?.group_aid ?? '');
             if (groupAid && aidCert) {
-                this._keystore.saveIdentity(groupAid, {
-                    private_key_pem: identity.private_key_pem,
-                    public_key: identity.public_key_der_b64,
-                    curve: 'P-256',
-                    type: 'group_identity',
-                });
+                this._saveGroupIdentityToV2(groupAid, identity);
                 const certPem = String(aidCert.cert ?? '');
                 if (certPem) {
-                    this._keystore.saveCert(groupAid, certPem);
+                    this._tokenStore.saveCert(groupAid, certPem);
                 }
             }
             this._clientLog.debug(`bindGroupAid exit: elapsed=${Date.now() - tStart}ms groupAid=${groupAid}`);