@agentunion/fastaun-browser 0.4.4 → 0.4.6

package/dist/client.js

@@ -4,7 +4,7 @@
 //   - HTTP 使用 fetch() 而非 Node http
 //   - 无文件系统（IndexedDB via keystore）
 //   - 后台任务使用 setTimeout/setInterval
-import { createConfig, getDeviceId, normalizeInstanceId, normalizeSlotId, slotIsolationKey } from './config.js';
+import { createConfig, getDeviceId, normalizeSlotId, slotIsolationKey } from './config.js';
 import { EventDispatcher } from './events.js';
 import { normalizeGroupId } from './group-id.js';
 import { GatewayDiscovery } from './discovery.js';
@@ -12,12 +12,13 @@ import { RPCTransport } from './transport.js';
 import { AuthFlow } from './auth.js';
 import { SeqTracker } from './seq-tracker.js';
 import { CryptoProvider, uint8ToBase64, base64ToUint8, pemToArrayBuffer, p1363ToDer, certificateSha256Fingerprint, ecdsaSignDer, ecdsaVerifyDer, importCertPublicKeyEcdsa, importPrivateKeyEcdsa, } from './crypto.js';
-import { IndexedDBKeyStore } from './keystore/indexeddb.js';
+import { IndexedDBTokenStore } from './keystore/indexeddb-token-store.js';
 import { V2Session, V2KeyStore } from './v2/session/index.js';
 import { encryptP2PMessage, encryptGroupMessage, decryptMessage, } from './v2/e2ee/index.js';
 import { ecdsaVerifyRaw } from './v2/crypto/ecdsa.js';
 import { computeStateCommitment } from './v2/state/index.js';
 import { AUNLogger } from './logger.js';
+import { AgentMdManager } from './agent-md.js';
 import { AUNError, AuthError, ConnectionError, E2EEError, NotFoundError, PermissionError, StateError, ValidationError, } from './errors.js';
 import { isJsonObject, ConnectionState, STATE_TO_PUBLIC, } from './types.js';
 import { AID } from './aid.js';
@@ -239,7 +240,6 @@ function reconnectSleepDelaySeconds(baseDelay, maxBaseDelay) {
 /** 对端证书缓存 TTL（秒） */
 const PEER_CERT_CACHE_TTL = 3600;
 const PEER_PREKEYS_CACHE_TTL = 3600;
-const AGENT_MD_HTTP_TIMEOUT_MS = 30_000;
 /**
  * 将 WebSocket URL 转为对应的 HTTP URL
  */
@@ -272,28 +272,89 @@ function buildCertUrl(gatewayUrl, aid, certFingerprint) {
     }
     return url.toString();
 }
-function agentMdHttpScheme(gatewayUrl) {
-    const raw = String(gatewayUrl ?? '').trim().toLowerCase();
-    return raw.startsWith('ws://') ? 'http' : 'https';
-}
-function agentMdAuthority(aid) {
-    return String(aid ?? '').trim();
-}
-async function fetchWithTimeout(input, init, timeoutMs = AGENT_MD_HTTP_TIMEOUT_MS) {
-    const controller = new AbortController();
-    const timer = globalThis.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 {
-        globalThis.clearTimeout(timer);
-    }
+function createAgentMdManagerForRuntime(opts) {
+    return new AgentMdManager({
+        aunPath: opts.config().aunPath,
+        tokenStore: opts.tokenStore(),
+        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 = await opts.auth().loadIdentityOrNone(target);
+            if (!identity && opts.identity.get() && String(opts.identity.get()?.aid ?? '') === target) {
+                identity = opts.identity.get();
+            }
+            if (!identity) {
+                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, target);
+            const token = String(result.access_token ?? '');
+            if (!token)
+                throw new StateError('authenticate did not return access_token');
+            const fallbackIdentity = {
+                ...identity,
+                access_token: token,
+                refresh_token: String(result.refresh_token ?? identity.refresh_token ?? ''),
+            };
+            const fallbackExpiresAt = Number(result.expires_at ?? identity.expires_at ?? NaN);
+            if (Number.isFinite(fallbackExpiresAt))
+                fallbackIdentity.expires_at = fallbackExpiresAt;
+            opts.identity.set(await auth.loadIdentityOrNone(target) ?? fallbackIdentity);
+            return token;
+        },
+        peerResolver: async (aid) => {
+            const target = String(aid ?? '').trim();
+            const current = opts.currentAid();
+            if (current?.aid === target)
+                return current;
+            let certPem = String(await opts.tokenStore().loadCert(target) ?? '').trim();
+            if (!certPem) {
+                if (!opts.gateway.get()) {
+                    try {
+                        opts.gateway.set(await opts.gateway.resolve(target));
+                    }
+                    catch { /* best effort */ }
+                }
+                certPem = String(await opts.fetchPeerCert(target) ?? '').trim();
+            }
+            if (!certPem)
+                throw new NotFoundError(`certificate not found for aid: ${target}`);
+            return await AID.create({
+                aid: target,
+                aunPath: opts.config().aunPath,
+                certPem,
+                privateKeyPem: null,
+                certValid: true,
+                privateKeyValid: false,
+            });
+        },
+    });
 }
 /**
  * 跨域时将 Gateway URL 替换为 peer 所在域的 Gateway URL。
@@ -664,7 +725,7 @@ export class AUNClient {
     _sessionOptions = { ...DEFAULT_SESSION_OPTIONS };
     _dispatcher;
     _discovery;
-    _keystore;
+    _tokenStore;
     _auth;
     _transport;
     // E2EE 编排状态（内存缓存）
@@ -699,20 +760,8 @@ export class AUNClient {
     /** 最近一次已成功确认的 membership_snapshot；相同快照直接跳过。 */
     _v2AutoProposeLastSnapshot = new Map();
     _v2LazyProposeTriggered = new Map();
-    /**
-     * 本地 agent.md 内容对应的 etag（quoted sha256 hex，与服务端 _agent_md_etag 一致）。
-     *
-     * 由 publishAgentMd() / fetchAgentMd(自身 aid) 写入；用于跟服务端 RPC 注入的 _meta.agent_md_etag
-     * 比对，触发"本地未发布到服务端"或"服务端版本更新"的 UI 提示。
-     */
-    _localAgentMdEtag = '';
-    /** gateway 在 RPC envelope._meta.agent_md_etag 注入的服务端 etag；纯观察，无下游依赖。 */
-    _remoteAgentMdEtag = '';
-    /** 浏览器侧 AIDs 逻辑根目录，正文映射到 IndexedDB 里的 {aid}/agent.md。 */
-    _agentMdPath = '';
-    _agentMdCache = new Map();
-    _agentMdFetchInflight = new Set();
-    _agentMdLock = Promise.resolve();
+    /** agent.md 运行时管理器，负责上传、下载、缓存和 RPC 元数据观察。 */
+    _agentMdManager;
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     _seqTracker = new SeqTracker();
     _seqTrackerContext = null;
@@ -751,7 +800,7 @@ export class AUNClient {
     _clientLog;
     _logAuth;
     _logTransport;
-    _logKeystore;
+    _tokenStoreLog;
     _logDiscovery;
     _logEvents;
     constructor(aid) {
@@ -770,7 +819,6 @@ export class AUNClient {
             root_ca_path: this.configModel.rootCaPem,
             seed_password: this.configModel.seedPassword,
         };
-        this._agentMdPath = this._agentMdDefaultRoot();
         this._deviceId = (inputAid?.deviceId) || getDeviceId();
         // Logger 必须最早初始化（其他子模块构造时通过 logger 输出）
         this._logger = new AUNLogger({ debug: _debug, aunPath: this.configModel.aunPath });
@@ -778,18 +826,18 @@ export class AUNClient {
         this._clientLog = this._logger.for('aun_core.client');
         this._logAuth = this._logger.for('aun_core.auth');
         this._logTransport = this._logger.for('aun_core.transport');
-        this._logKeystore = this._logger.for('aun_core.keystore');
+        this._tokenStoreLog = this._logger.for('aun_core.keystore');
         this._logDiscovery = this._logger.for('aun_core.discovery');
         this._logEvents = this._logger.for('aun_core.events');
         this._clientLog.info(`AUNClient initialized: debug=${_debug} aunPath=${this.configModel.aunPath} aid=${initAid ?? '-'}`);
         this._dispatcher = new EventDispatcher();
         this._discovery = new GatewayDiscovery();
-        this._keystore = new IndexedDBKeyStore({});
+        this._tokenStore = new IndexedDBTokenStore();
         this._slotId = inputAid?.slotId || 'default';
         this._connectDeliveryMode = normalizeDeliveryModeConfig({ mode: 'fanout' });
         this._defaultConnectDeliveryMode = { ...this._connectDeliveryMode };
         this._auth = new AuthFlow({
-            keystore: this._keystore,
+            tokenStore: this._tokenStore,
             crypto: new CryptoProvider(),
             aid: initAid,
             deviceId: this._deviceId,
@@ -798,6 +846,24 @@ export class AUNClient {
             verifySsl: this.configModel.verifySsl,
         });
         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: DEFAULT_SESSION_OPTIONS.timeouts.call,
@@ -817,6 +883,7 @@ export class AUNClient {
                     public_key_der_b64: inputAid.publicKey,
                     cert: inputAid.certPem,
                 };
+                this._auth.setIdentity(this._identity);
                 this._state = 'disconnected';
             }
         }
@@ -827,8 +894,8 @@ export class AUNClient {
         if (typeof this._discovery.setLogger === 'function') {
             this._discovery.setLogger(this._logger.for('aun_core.discovery'));
         }
-        if (typeof this._keystore.setLogger === 'function') {
-            this._keystore.setLogger(this._logKeystore);
+        if (typeof this._tokenStore.setLogger === 'function') {
+            this._tokenStore.setLogger(this._tokenStoreLog);
         }
         // 内部订阅：推送消息 re-publish 给用户（V2 加密消息走 _raw.peer.v2.message_received）
         this._dispatcher.subscribe('_raw.message.received', (data) => {
@@ -880,664 +947,15 @@ export class AUNClient {
     get aid() {
         return this._aid;
     }
-    _setAgentMdRoot(root) {
-        const next = String(root ?? '').trim() || this._agentMdDefaultRoot();
-        this._agentMdPath = next;
-        this._agentMdCache.clear();
-        return next;
-    }
-    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 = '';
-            }
-        }
-        const authority = agentMdAuthority(target);
-        return `${agentMdHttpScheme(gatewayUrl)}://${authority}/agent.md`;
-    }
-    async _ensureAgentMdUploadToken(aid, gatewayUrl) {
-        let identity = await 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');
-        const fallbackIdentity = {
-            ...identity,
-            access_token: token,
-            refresh_token: String(result.refresh_token ?? identity.refresh_token ?? ''),
-        };
-        const fallbackExpiresAt = Number(result.expires_at ?? identity.expires_at ?? NaN);
-        if (Number.isFinite(fallbackExpiresAt))
-            fallbackIdentity.expires_at = fallbackExpiresAt;
-        this._identity = await this._auth.loadIdentityOrNone(aid) ?? fallbackIdentity;
-        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 _downloadAgentMd(aid) {
-        const target = String(aid ?? '').trim();
-        if (!target)
-            throw new ValidationError('downloadAgentMd requires non-empty aid');
-        const cached = this._agentMdCache.get(target);
-        const url = await this._resolveAgentMdUrl(target);
-        const 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 === 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' },
-        });
-        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 };
-        }
-        if (!response.ok) {
-            throw new AUNError(`head agent.md failed: HTTP ${response.status}`);
-        }
-        const cached = this._agentMdCache.get(target) ?? {};
-        this._agentMdCache.set(target, {
-            ...cached,
-            etag,
-            lastModified,
-            remote_etag: etag,
-            last_modified: lastModified,
-        });
-        return { aid: target, found: true, etag, last_modified: lastModified, status: response.status };
-    }
-    async _verifyAgentMd(content, aid) {
-        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 certPem = String(await this._keystore.loadCert(target) ?? '').trim();
-            if (!certPem) {
-                certPem = String(await this._fetchPeerCert(target) ?? '').trim();
-            }
-            if (!certPem)
-                throw new NotFoundError(`certificate not found for aid: ${target}`);
-            peer = await AID.create({
-                aid: target,
-                aunPath: this.configModel.aunPath,
-                certPem,
-                privateKeyPem: null,
-                certValid: true,
-                privateKeyValid: false,
-            });
-        }
-        const result = await peer.verifyAgentMd(content);
-        if (!result.ok)
-            throw new AUNError(result.error.message);
-        return { ...result.data, verified: result.data.status === 'verified' };
-    }
-    /**
-     * 浏览器版本 publishAgentMd。默认从 {agentMdPath}/{self_aid}/agent.md 的等价 IndexedDB 正文读取，
-     * 然后签名、上传，并刷新 agentmd.json 元数据。
-     *
-     * 兼容旧浏览器调用：传入 content 时会先写入等价正文，再从该正文发布。
-     */
-    async publishAgentMd(content) {
-        const target = this._agentMdOwnerAid();
-        if (!target || !this._currentAid) {
-            throw new ValidationError('publishAgentMd requires local AID');
-        }
-        if (content !== undefined && content !== null) {
-            const text = String(content ?? '');
-            if (text.length === 0) {
-                throw new ValidationError('publishAgentMd requires non-empty content');
-            }
-            await this._saveAgentMdRecord(target, {
-                content: text,
-                local_etag: await this._agentMdContentEtag(text),
-                fetched_at: Date.now(),
-            });
-        }
-        const localContent = await this._readAgentMdContent(target);
-        if (localContent === null || localContent.length === 0) {
-            throw new ValidationError('publishAgentMd requires local agent.md content');
-        }
-        const signedResult = await this._currentAid?.signAgentMd(localContent);
-        if (!signedResult?.ok) {
-            throw new StateError(signedResult?.error.message ?? 'publishAgentMd requires a valid local AID private key');
-        }
-        const signed = signedResult.data.signed;
-        const result = await this._uploadAgentMd(signed);
-        this._localAgentMdEtag = await this._agentMdContentEtag(signed);
-        const remoteEtag = isJsonObject(result) ? String(result.etag ?? '').trim() : '';
-        if (remoteEtag)
-            this._remoteAgentMdEtag = remoteEtag;
-        await this._saveAgentMdRecord(target, {
-            content: signed,
-            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;
-    }
-    /**
-     * 浏览器版本 fetchAgentMd。aid 缺省时取自身；下载后的正文固定写入
-     * {agentMdPath}/{aid}/agent.md 的等价 IndexedDB 正文，agentmd.json 只保存元数据。
-     */
-    async _fetchAgentMdCache(aid) {
-        const target = String(aid ?? this._aid ?? '').trim();
-        if (!target) {
-            throw new ValidationError('fetchAgentMd requires aid (or local AID)');
-        }
-        const content = await this._downloadAgentMd(target);
-        const signature = await this._verifyAgentMd(content, target);
-        const isSelf = target === (this._aid ?? '');
-        const localEtag = await 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;
-        }
-        await 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 in_sync = null;
-        if (isSelf) {
-            const remote = remoteEtag || this._remoteAgentMdEtag || '';
-            in_sync = localEtag && remote ? localEtag === remote : false;
-        }
-        return {
-            aid: target,
-            content,
-            signature: signature,
-            in_sync,
-        };
-    }
-    getLocalAgentMdEtag() {
-        return this._localAgentMdEtag;
-    }
-    getRemoteAgentMdEtag() {
-        return this._remoteAgentMdEtag;
-    }
-    async _agentMdContentEtag(content) {
-        const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(String(content ?? '')));
-        const hex = Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, '0')).join('');
-        return `"${hex}"`;
-    }
-    _agentMdOwnerAid() {
-        return String(this._aid ?? '').trim();
-    }
-    _agentMdDefaultRoot() {
-        return this._joinAgentMdPath(this.configModel.aunPath || '.', 'AIDs');
-    }
-    _joinAgentMdPath(base, name) {
-        const left = String(base ?? '').trim().replace(/[\\/]+$/g, '');
-        return left ? `${left}/${name}` : name;
-    }
-    _agentMdRoot() {
-        return this._agentMdPath || this._agentMdDefaultRoot();
-    }
-    _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;
-    }
-    _agentMdMetaKey(aid) {
-        return `${this._agentMdSafeAid(aid)}/agentmd.json`;
-    }
-    _agentMdContentKey(aid) {
-        return `${this._agentMdSafeAid(aid)}/agent.md`;
-    }
-    async _readAgentMdStorage(logicalKey) {
-        const key = String(logicalKey ?? '').trim();
-        if (!key)
-            return null;
-        const load = this._keystore.loadAgentMdCache;
-        if (typeof load !== 'function') {
-            throw new Error('IndexedDB agent.md storage unavailable');
-        }
-        const record = await load.call(this._keystore, this._agentMdRoot(), key);
-        if (record && Object.prototype.hasOwnProperty.call(record, 'content')) {
-            return String(record.content ?? '');
-        }
-        return null;
-    }
-    async _writeAgentMdStorage(logicalKey, content) {
-        const key = String(logicalKey ?? '').trim();
-        if (!key)
-            return;
-        const save = this._keystore.upsertAgentMdCache;
-        if (typeof save !== 'function') {
-            throw new Error('IndexedDB agent.md storage unavailable');
-        }
-        const text = String(content ?? '');
-        await save.call(this._keystore, this._agentMdRoot(), key, {
-            content: text,
-            local_etag: await this._agentMdContentEtag(text),
-            fetched_at: Date.now(),
-        });
-    }
-    async _withAgentMdLock(fn) {
-        const previous = this._agentMdLock.catch(() => undefined);
-        let release;
-        const current = new Promise((resolve) => { release = resolve; });
-        this._agentMdLock = previous.then(() => current);
-        await previous;
-        try {
-            return await fn();
-        }
-        finally {
-            release();
-        }
-    }
-    _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;
-    }
-    async _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);
-        await this._writeAgentMdStorage(this._agentMdMetaKey(aid), `${JSON.stringify(payload, null, 2)}\n`);
-    }
-    async _readAgentMdRecordUnlocked(aid) {
-        const raw = await this._readAgentMdStorage(this._agentMdMetaKey(aid));
-        if (raw === null)
-            return {};
-        try {
-            return this._normalizeAgentMdRecord(aid, JSON.parse(raw));
-        }
-        catch (err) {
-            this._clientLog.warn(`agent.md metadata damaged, ignoring: aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
-            return {};
-        }
-    }
-    async _readAgentMdContent(aid) {
-        return await this._readAgentMdStorage(this._agentMdContentKey(aid));
-    }
-    async _writeAgentMdContent(aid, content) {
-        await this._writeAgentMdStorage(this._agentMdContentKey(aid), String(content ?? ''));
-    }
-    _agentMdAuthCacheMeta(aid) {
-        try {
-            const record = this._agentMdCache.get(String(aid ?? '').trim());
-            return record && typeof record === 'object' ? { ...record } : {};
-        }
-        catch {
-            return {};
-        }
-    }
-    async _loadAgentMdRecord(aid) {
-        const target = String(aid ?? '').trim();
-        if (!target)
-            return null;
-        try {
-            const loaded = await this._withAgentMdLock(async () => {
-                const record = await this._readAgentMdRecordUnlocked(target);
-                const next = Object.keys(record).length > 0 ? { ...record, aid: target } : { aid: target };
-                try {
-                    const content = await this._readAgentMdContent(target);
-                    if (content !== null) {
-                        next.content = content;
-                        next.local_etag = await this._agentMdContentEtag(content);
-                    }
-                    else {
-                        // 元数据存在但正文缺失
-                        const metaRaw = await this._readAgentMdStorage(this._agentMdMetaKey(target));
-                        if (metaRaw !== null) {
-                            this._clientLog.warn(`agent.md content read failed: aid=${target}`);
-                        }
-                    }
-                }
-                catch (err) {
-                    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;
-    }
-    async _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;
-            if (hasContent) {
-                const text = String(inputFields.content ?? '');
-                await this._writeAgentMdContent(target, text);
-                if (!inputFields.local_etag)
-                    inputFields.local_etag = await this._agentMdContentEtag(text);
-                if (!inputFields.fetched_at)
-                    inputFields.fetched_at = Date.now();
-            }
-            delete inputFields.content;
-            const record = await this._withAgentMdLock(async () => {
-                const next = { ...(await 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();
-                await this._writeAgentMdRecordUnlocked(target, next);
-                return next;
-            });
-            const loaded = { ...record };
-            if (hasContent)
-                loaded.content = String(fields.content ?? '');
-            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 {};
-    }
-    async _agentMdHasLocalContent(aid, record) {
-        if (record && typeof record.content === 'string' && record.content.length > 0)
-            return true;
-        try {
-            return (await this._readAgentMdContent(aid)) !== null;
-        }
-        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;
-    }
-    async _scheduleAgentMdFetchIfMissing(aid, record, source = '') {
-        const target = String(aid ?? '').trim();
-        if (!target || await this._agentMdHasLocalContent(target, record))
-            return;
-        if (this._agentMdFetchInflight.has(target))
-            return;
-        this._agentMdFetchInflight.add(target);
-        try {
-            await this._fetchAgentMdCache(target);
-        }
-        catch (err) {
-            await 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)}`);
-        }
-        finally {
-            this._agentMdFetchInflight.delete(target);
-        }
-    }
-    async _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 = await 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 = await this._saveAgentMdRecord(target, fields) || record;
-        }
-        if (target === this._agentMdOwnerAid() && remoteEtag)
-            this._remoteAgentMdEtag = remoteEtag;
-        await this._scheduleAgentMdFetchIfMissing(target, record, source);
-        this._clientLog.debug(`agent.md meta observed: aid=${target} etag=${remoteEtag || '-'} last_modified=${remoteLastModified || '-'} source=${source || '-'}`);
-    }
-    async _observeAgentMdEtag(aid, etag, source = '') {
-        await this._observeAgentMdMeta(aid, etag, '', source);
+    async uploadAgentMd(content) {
+        return await this._agentMdManager.upload(content);
     }
     async _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();
-        }
-        await this._observeAgentMdMeta(senderAid, String(sender.etag ?? '').trim(), String(sender.last_modified ?? sender.lastModified ?? '').trim(), 'envelope');
-    }
-    async _checkAgentMdCache(aid, maxUnsyncedDays = 0) {
-        const target = String(aid ?? this._aid ?? '').trim();
-        if (!target)
-            throw new ValidationError('checkAgentMd requires aid (or local AID)');
-        const before = await 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 checkedAtCached = Number(before.checked_at ?? 0);
-        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 now = Date.now();
-        let remote;
-        try {
-            remote = await this._headAgentMd(target);
-        }
-        catch (err) {
-            await 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 = await 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 ?? ''),
-        };
+        await this._agentMdManager.observeEnvelope(envelope);
     }
     /** transport 的 meta observer：吸收 gateway 注入的 _meta 字段。失败不影响业务。 */
     async _observeRpcMeta(meta) {
-        if (!isJsonObject(meta))
-            return;
-        const etag = String(meta.agent_md_etag ?? '').trim();
-        if (etag) {
-            this._remoteAgentMdEtag = etag;
-            await 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;
-                await this._observeAgentMdMeta(String(item.aid ?? ''), String(item.etag ?? ''), String(item.last_modified ?? item.lastModified ?? ''), `rpc.${key}`);
-            }
-        }
+        await this._agentMdManager.observeRpcMeta(meta, this._aid);
     }
     get state() {
         return this._publicState(this._state);
@@ -1597,9 +1015,6 @@ export class AUNClient {
         this.config.aun_path = nextConfig.aunPath;
         this.config.root_ca_path = nextConfig.rootCaPem;
         this.config.seed_password = nextConfig.seedPassword;
-        this._agentMdPath = this._agentMdDefaultRoot();
-        this._agentMdCache.clear();
-        this._agentMdFetchInflight.clear();
         this._peerCache.clear();
         this._certCache.clear();
         this._gatewayUrl = null;
@@ -1610,13 +1025,13 @@ export class AUNClient {
         this._clientLog = this._logger.for('aun_core.client');
         this._logAuth = this._logger.for('aun_core.auth');
         this._logTransport = this._logger.for('aun_core.transport');
-        this._logKeystore = this._logger.for('aun_core.keystore');
+        this._tokenStoreLog = this._logger.for('aun_core.keystore');
         this._logDiscovery = this._logger.for('aun_core.discovery');
         this._logEvents = this._logger.for('aun_core.events');
         this._discovery = new GatewayDiscovery();
-        this._keystore = new IndexedDBKeyStore({});
+        this._tokenStore = new IndexedDBTokenStore();
         this._auth = new AuthFlow({
-            keystore: this._keystore,
+            tokenStore: this._tokenStore,
             crypto: new CryptoProvider(),
             aid: aid.aid,
             deviceId: this._deviceId,
@@ -1624,6 +1039,24 @@ export class AUNClient {
             rootCaPem: nextConfig.rootCaPem,
             verifySsl: nextConfig.verifySsl,
         });
+        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: DEFAULT_SESSION_OPTIONS.timeouts.call,
@@ -1640,8 +1073,8 @@ export class AUNClient {
         if (typeof this._discovery.setLogger === 'function') {
             this._discovery.setLogger(this._logDiscovery);
         }
-        if (typeof this._keystore.setLogger === 'function') {
-            this._keystore.setLogger(this._logKeystore);
+        if (typeof this._tokenStore.setLogger === 'function') {
+            this._tokenStore.setLogger(this._tokenStoreLog);
         }
     }
     loadIdentity(aid) {
@@ -1660,6 +1093,8 @@ export class AUNClient {
             public_key_der_b64: aid.publicKey,
             cert: aid.certPem,
         };
+        // 注入内存私钥到 AuthFlow，禁止 AuthFlow 内部再走 keystore 解密
+        this._auth.setIdentity(this._identity);
         this._state = 'disconnected';
         this._closing = false;
     }
@@ -2756,8 +2191,9 @@ export class AUNClient {
         // 注入本地/远端 agent.md etag，让应用层判断版本一致性；失败不影响业务。
         if (isJsonObject(payload)) {
             try {
-                const localEtag = this._localAgentMdEtag || '';
-                const remoteEtag = this._remoteAgentMdEtag || '';
+                const snapshot = this._agentMdManager.eventSnapshot();
+                const localEtag = snapshot?.local_etag || '';
+                const remoteEtag = snapshot?.remote_etag || '';
                 if ((localEtag || remoteEtag) && payload._agent_md === undefined) {
                     payload._agent_md = {
                         local_etag: localEtag,
@@ -3048,9 +2484,9 @@ 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 loadFn = this._tokenStore.loadGroupState;
         const localState = loadFn
-            ? await loadFn.call(this._keystore, groupId)
+            ? await loadFn.call(this._tokenStore, groupId)
             : null;
         if (localState && localState.state_hash && localState.state_hash !== prevStateHash) {
             this._clientLog.warn('[aun_core] state_hash 链不连续 group=%s local_sv=%d event_sv=%d', groupId, localState.state_version, stateVersion);
@@ -3077,9 +2513,9 @@ export class AUNClient {
                             return;
                         }
                     }
-                    const saveFn = this._keystore.saveGroupState;
+                    const saveFn = this._tokenStore.saveGroupState;
                     if (saveFn) {
-                        await saveFn.call(this._keystore, groupId, {
+                        await saveFn.call(this._tokenStore, groupId, {
                             group_id: groupId,
                             state_version: sv,
                             state_hash: sHash,
@@ -3108,9 +2544,9 @@ export class AUNClient {
             return;
         }
         // 3. 更新本地存储
-        const saveFn = this._keystore.saveGroupState;
+        const saveFn = this._tokenStore.saveGroupState;
         if (saveFn) {
-            await saveFn.call(this._keystore, groupId, {
+            await saveFn.call(this._tokenStore, groupId, {
                 group_id: groupId,
                 state_version: stateVersion,
                 state_hash: stateHash,
@@ -3543,7 +2979,7 @@ export class AUNClient {
             });
             try {
                 // peer 证书只存版本目录，不覆盖 cert.pem
-                await this._keystore.saveCert(aid, certPem, certFingerprint, { makeActive: false });
+                await this._tokenStore.saveCert(aid, certPem, certFingerprint, { makeActive: false });
             }
             catch (exc) {
                 this._clientLog.error(`write cert to keystore failed (aid=${aid}): ${String(exc)}`, exc instanceof Error ? exc : undefined);
@@ -3563,7 +2999,7 @@ export class AUNClient {
         const now = Date.now() / 1000;
         if (cached && now < cached.refreshAfter)
             return true;
-        const localCert = await this._keystore.loadCert(aid, certFingerprint);
+        const localCert = await this._tokenStore.loadCert(aid, certFingerprint);
         if (localCert) {
             if (certFingerprint) {
                 const actualFingerprint = await this._certFingerprint(localCert);
@@ -3588,7 +3024,7 @@ export class AUNClient {
         try {
             const certPem = await this._fetchPeerCert(aid, certFingerprint);
             // peer 证书只存版本目录，不覆盖 cert.pem
-            await this._keystore.saveCert(aid, certPem, certFingerprint, { makeActive: false });
+            await this._tokenStore.saveCert(aid, certPem, certFingerprint, { makeActive: false });
             return true;
         }
         catch (exc) {
@@ -3786,9 +3222,9 @@ export class AUNClient {
         if (this._gatewayUrl)
             return this._gatewayUrl;
         try {
-            const getMetadata = this._keystore.getMetadata;
+            const getMetadata = this._tokenStore.getMetadata;
             const raw = typeof getMetadata === 'function'
-                ? String(await getMetadata.call(this._keystore, target, 'gateway_url') ?? '').trim()
+                ? String(await getMetadata.call(this._tokenStore, target, 'gateway_url') ?? '').trim()
                 : '';
             if (raw) {
                 const gateway = raw.startsWith('"') && raw.endsWith('"') ? String(JSON.parse(raw)).trim() : raw;
@@ -3814,9 +3250,9 @@ export class AUNClient {
                 const gateway = await this._discovery.discover(url);
                 this._gatewayUrl = gateway;
                 try {
-                    const setMetadata = this._keystore.setMetadata;
+                    const setMetadata = this._tokenStore.setMetadata;
                     if (typeof setMetadata === 'function') {
-                        await setMetadata.call(this._keystore, target, 'gateway_url', gateway);
+                        await setMetadata.call(this._tokenStore, target, 'gateway_url', gateway);
                     }
                 }
                 catch {
@@ -3853,13 +3289,8 @@ export class AUNClient {
         return [gateway];
     }
     async _syncIdentityAfterConnect(accessToken) {
-        let identity = null;
-        try {
-            identity = await this._auth.loadIdentityOrNone(this._aid ?? undefined);
-        }
-        catch { /* 忽略 */ }
+        const identity = this._identity;
         if (!identity) {
-            this._identity = null;
             return;
         }
         identity.access_token = accessToken;
@@ -3870,9 +3301,6 @@ export class AUNClient {
             if (typeof persistIdentity === 'function') {
                 await persistIdentity.call(this._auth, identity);
             }
-            else {
-                await this._keystore.saveIdentity(String(identity.aid), identity);
-            }
         }
     }
     // ── 内部：参数处理 ────────────────────────────────
@@ -4213,8 +3641,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;
@@ -4382,8 +3810,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();
@@ -4403,15 +3830,10 @@ export class AUNClient {
             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',
-                });
+                await this._saveGroupIdentityToV2(groupAid, identity);
                 const certPem = String(aidCert.cert ?? '');
                 if (certPem) {
-                    await this._keystore.saveCert(groupAid, certPem);
+                    await this._tokenStore.saveCert(groupAid, certPem);
                 }
             }
             this._clientLog.debug(`createNamedGroup exit: elapsed=${Date.now() - tStart}ms group_aid=${groupAid}`);
@@ -4442,15 +3864,10 @@ export class AUNClient {
             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',
-                });
+                await this._saveGroupIdentityToV2(groupAid, identity);
                 const certPem = String(aidCert.cert ?? '');
                 if (certPem) {
-                    await this._keystore.saveCert(groupAid, certPem);
+                    await this._tokenStore.saveCert(groupAid, certPem);
                 }
             }
             this._clientLog.debug(`bindGroupAid exit: elapsed=${Date.now() - tStart}ms group_aid=${groupAid}`);
@@ -4494,7 +3911,7 @@ export class AUNClient {
         const slotId = this._slotId;
         try {
             // 优先从 seq_tracker 表按行读取
-            const loadAll = this._keystore.loadAllSeqs?.bind(this._keystore);
+            const loadAll = this._tokenStore.loadAllSeqs?.bind(this._tokenStore);
             if (typeof loadAll === 'function') {
                 let state = await loadAll(aid, deviceId, slotId);
                 if (this._seqTrackerContext !== context)
@@ -4506,7 +3923,7 @@ export class AUNClient {
                 return;
             }
             // fallback: 从旧 instance_state JSON blob 恢复
-            const loader = this._keystore.loadInstanceState?.bind(this._keystore);
+            const loader = this._tokenStore.loadInstanceState?.bind(this._tokenStore);
             if (typeof loader !== 'function')
                 return;
             const stateHolder = await loader(aid, deviceId, slotId);
@@ -4564,8 +3981,8 @@ export class AUNClient {
         const aid = this._aid;
         const deviceId = this._deviceId;
         const slotId = this._slotId;
-        const saver = this._keystore.saveSeq?.bind(this._keystore);
-        const deleter = this._keystore.deleteSeq?.bind(this._keystore);
+        const saver = this._tokenStore.saveSeq?.bind(this._tokenStore);
+        const deleter = this._tokenStore.deleteSeq?.bind(this._tokenStore);
         if (typeof saver === 'function') {
             for (const [oldNs, newNs] of Object.entries(renameMap)) {
                 if (typeof deleter === 'function') {
@@ -4629,7 +4046,7 @@ export class AUNClient {
             return;
         try {
             // 优先按行写入 seq_tracker 表
-            const saveFn = this._keystore.saveSeq?.bind(this._keystore);
+            const saveFn = this._tokenStore.saveSeq?.bind(this._tokenStore);
             if (typeof saveFn === 'function') {
                 for (const [ns, seq] of Object.entries(state)) {
                     saveFn(this._aid, this._deviceId, this._slotId, ns, seq).catch((exc) => {
@@ -4645,8 +4062,8 @@ export class AUNClient {
                 return;
             }
             // fallback: 旧版 updateInstanceState JSON blob
-            if (typeof this._keystore.updateInstanceState === 'function') {
-                this._keystore.updateInstanceState(this._aid, this._deviceId, this._slotId, (current) => {
+            if (typeof this._tokenStore.updateInstanceState === 'function') {
+                this._tokenStore.updateInstanceState(this._aid, this._deviceId, this._slotId, (current) => {
                     current.seq_tracker_state = state;
                     return current;
                 }).catch((exc) => {
@@ -4675,15 +4092,15 @@ 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).catch((exc) => {
+            if (seq > 0 && typeof this._tokenStore.saveSeq === 'function') {
+                this._tokenStore.saveSeq(this._aid, this._deviceId, this._slotId, ns, seq).catch((exc) => {
                     this._clientLog.debug(`persist repaired seq failed: ns=${ns} err=${formatCaughtError(exc)}`);
                 });
                 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).catch((exc) => {
+                deleteSeq.call(this._tokenStore, this._aid, this._deviceId, this._slotId, ns).catch((exc) => {
                     this._clientLog.debug(`delete repaired seq failed: ns=${ns} err=${formatCaughtError(exc)}`);
                 });
                 return;
@@ -4735,7 +4152,7 @@ export class AUNClient {
     async _initV2Session() {
         if (!this._aid)
             return;
-        // 私钥由 AIDStore 管理，直接从 _currentAid 读取明文私钥
+        // 私钥来自当前 AID 值对象，AUNClient 不从持久化存储读取私钥。
         const currentAid = this._currentAid;
         if (!currentAid?.privateKeyPem) {
             this._clientLog.warn('V2 session init skipped: no AID private key');
@@ -4776,6 +4193,20 @@ export class AUNClient {
         // 上线时自动确认 pending state proposals
         this._safeAsync(this._v2AutoConfirmPendingProposals());
     }
+    _v2StoreDeviceId() {
+        return `aid:${encodeURIComponent(String(this._aid ?? ''))}|device:${encodeURIComponent(String(this._deviceId ?? ''))}`;
+    }
+    async _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');
+        }
+        if (!this._v2KeyStore) {
+            this._v2KeyStore = await V2KeyStore.open();
+        }
+        await this._v2KeyStore.saveGroupIdentity(this._v2StoreDeviceId(), groupAid, privateKeyPem, base64ToUint8(publicKeyDerB64));
+    }
     async _v2TrustedIKPubDer(aid) {
         const normalizedAid = String(aid ?? '').trim();
         if (!normalizedAid)