@agentunion/fastaun 0.5.20 → 0.5.22

package/dist/client.js

@@ -26,7 +26,7 @@ import { normalizeGroupId } from './group-id.js';
 import { validateAIDFormat, validateGroupIDFormat } from './validators.js';
 import { RPCTransport } from './transport.js';
 import { AuthFlow } from './auth.js';
-import { AgentMdManager, buildDefaultAgentMd, updateOwnershipAgentMd } from './agent-md.js';
+import { AgentMdManager, buildDefaultAgentMd } from './agent-md.js';
 import { GroupIndexMetaCache } from './group-index.js';
 import { SeqTracker } from './seq-tracker.js';
 import { ClientRuntime } from './client/runtime.js';
@@ -37,7 +37,7 @@ import { LifecycleController } from './client/lifecycle.js';
 import { PeerDirectory } from './client/peers.js';
 import { RpcPipeline } from './client/rpc-pipeline.js';
 import { CollabClient } from './collab/client.js';
-import { CredentialFacade, OrgFacade, GroupFacade, MailFacade, MessageFacade, StreamFacade } from './facades.js';
+import { DebugFacade, CredentialFacade, OrgFacade, GroupFacade, MailFacade, MessageFacade, StreamFacade } from './facades.js';
 import { StorageVFS } from './storage/vfs.js';
 import { V2E2EECoordinator } from './client/v2-e2ee.js';
 import { GroupStateCoordinator } from './client/group-state.js';
@@ -48,9 +48,9 @@ import { isJsonObject, ConnectionState, STATE_TO_PUBLIC, } from './types.js';
 import { AID } from './aid.js';
 import { certFingerprint, certMatchesFingerprint, normalizeFingerprintHex, publicKeyMatchesFingerprint } from './cert-utils.js';
 import { validateAgentMdCertificate, validateAgentMdDocument } from './agent-md-schema.js';
-import { OwnershipFiles, OwnershipStorageAdapter, ownershipFailure, signOwnershipFile } from './ownership-v21.js';
+import { OwnershipFiles, OwnershipStorageAdapter, ownershipFailure } from './ownership-v21.js';
 import { OwnershipWorkflow } from './ownership-workflow.js';
-import { canonicalJson, createCredential, createMemberCredential, signMembershipBinding, verifyServiceEvent } from './org-protocol.js';
+import { canonicalJson, createCredential, createMemberCredential, signMembershipBinding, digest, validateMembershipBinding, verifyMembershipBinding, verifyCredentialSignature, createRepresentationProof, verifyServiceEvent, buildRequestBinding, validateRequestBinding, CredentialRenewal } from './org-protocol.js';
 function isPromiseLike(value) {
     return Boolean(value && typeof value.then === 'function');
 }
@@ -478,6 +478,7 @@ export class AUNClient {
     /** 当前 AID 值对象（新 API） */
     _currentAid = null;
     _serviceEventIdentityVersion = 0;
+    _serviceEventIdentityAbort = new AbortController();
     /** ownership 关系只在 SDK 内存中编排；服务端不保存状态机。 */
     _ownershipRecords = new Map();
     _ownershipType = 'agent';
@@ -494,10 +495,10 @@ export class AUNClient {
             currentType: () => this.getType(),
             now: () => Math.trunc(Date.now() / 1000),
             readAgentMdFresh: (subAid) => this._agentMdManager.readOwnershipFresh(subAid),
-            submitAgentMdRaw: (subAid, raw, condition) => this._agentMdManager.submitOwnershipRaw(subAid, raw, condition),
+            submitAgentMdRaw: (subAid, raw, condition, assertActive, stage) => this._agentMdManager.submitOwnershipRaw(subAid, raw, condition, assertActive, stage),
             readOwnerMd: (ownerAid, subAid) => this._getOwnershipStorage().readOwnerMd(ownerAid, subAid),
-            writeOwnerMd: (ownerAid, subAid, raw) => this._getOwnershipStorage().writeOwnerMd(ownerAid, subAid, raw),
-            deleteOwnerMd: (ownerAid, subAid) => this._getOwnershipStorage().deleteOwnerMd(ownerAid, subAid),
+            writeOwnerMd: (ownerAid, subAid, raw, original, assertActive) => this._getOwnershipStorage().writeOwnerMd(ownerAid, subAid, raw, original, assertActive),
+            deleteOwnerMd: (ownerAid, subAid, expectedVersion) => this._getOwnershipStorage().deleteOwnerMd(ownerAid, subAid, expectedVersion),
             resolveCertificate: async (aid, fingerprint, purpose) => this._auth.resolveOwnershipCertificate(await this._resolveOwnershipCertificateGateway(aid), aid, fingerprint, purpose),
         });
     }
@@ -505,7 +506,7 @@ export class AUNClient {
         return this._ownershipWorkflow ??= new OwnershipWorkflow({
             currentAid: () => this._aid, store: this._tokenStore, files: this._getOwnershipFiles(),
             currentType: () => this.getType(),
-            send: (to, payload) => this.call('message.send', { to, encrypt: true, payload: payload }),
+            send: (to, payload, messageId) => this.call('message.send', { to, encrypt: true, message_id: messageId, payload: payload }),
             emit: (event, payload) => this._dispatcher.enqueue(event, payload),
         });
     }
@@ -549,6 +550,196 @@ export class AUNClient {
         await this._resumeRegistrationIntent();
         await this._resumeOwnership();
     }
+    _credentialRenewal;
+    _credentialRenewalTimer = null;
+    _credentialRenewalAbort = null;
+    _credentialRenewalScan = Promise.resolve();
+    _getCredentialRenewal() {
+        return this._credentialRenewal ??= new CredentialRenewal({
+            currentAid: () => this._aid ?? '',
+            atomicCheckpointSave: () => this._tokenStore instanceof LocalTokenStore,
+            load: (aid) => (this._tokenStore._loadMetadataStrict?.(aid) ?? this._tokenStore.loadMetadata?.(aid))?.credential_renewals_v1 ?? {},
+            ...(typeof this._tokenStore._loadMetadataStrict === 'function' ? {
+                loadRevocations: (aid) => this._tokenStore._loadMetadataStrict(aid)?.credential_revocations_v1 ?? {},
+                saveRevocations: (aid, state, guard) => {
+                    if (guard && !guard.current())
+                        throw new ValidationError('credential revocation synchronization was superseded');
+                    this._tokenStore.saveMetadata?.(aid, { credential_revocations_v1: state });
+                },
+            } : {}),
+            save: (aid, records, guard) => {
+                const version = this._serviceEventIdentityVersion;
+                const current = () => version === this._serviceEventIdentityVersion && aid === this._aid && (!guard || guard.current());
+                if (!current())
+                    throw new ValidationError('membership event receiver identity changed');
+                const saved = this._tokenStore instanceof LocalTokenStore ? records : Object.fromEntries(Object.entries(records).map(([cid, value]) => {
+                    const record = { ...value };
+                    for (const key of ['submitted_at', 'submission_hash', 'registration_submitted_at', 'registration_submission_hash'])
+                        delete record[key];
+                    return [cid, record];
+                }));
+                this._tokenStore.saveMetadata?.(aid, { credential_renewals_v1: saved });
+                if (!current())
+                    throw new ValidationError('membership event receiver identity changed');
+            },
+            signer: (aid, guard) => this._credentialRenewalSigner(aid, guard),
+            certificate: (aid, fingerprint, signedAt) => signedAt === undefined
+                ? this._fetchServiceEventCertificate(aid, fingerprint) : this._fetchPeerCert(aid, fingerprint, undefined, signedAt),
+            call: (method, params, onSent) => {
+                if (!onSent)
+                    return this._rpcPipeline.call(method, params);
+                const version = this._serviceEventIdentityVersion, aid = this._aid;
+                return this._rpcPipeline['_callWithSent'](method, params, async () => {
+                    if (version !== this._serviceEventIdentityVersion || aid !== this._aid)
+                        throw new ValidationError('credential sender identity changed');
+                    await onSent();
+                });
+            },
+            send: (to, payload) => this.call('message.send', { to, encrypt: true, payload }),
+        });
+    }
+    _assertCredentialNotRevoked(credential, proofChain) {
+        const version = this._serviceEventIdentityVersion, aid = this._aid;
+        const current = () => { if (aid !== this._aid || version !== this._serviceEventIdentityVersion)
+            throw new ValidationError('credential receiver identity changed'); };
+        this._getCredentialRenewal()._assertNotRevoked(credential, proofChain);
+        current();
+        return current;
+    }
+    async _credentialRenewalSigner(aid, guard) {
+        const check = () => { if (guard && !guard.current())
+            throw new ValidationError('credential renewal was superseded'); };
+        check();
+        const stored = this._aidStore?.load(aid);
+        let identity = aid === this._aid && this._identity?.private_key_pem
+            ? AID._create({ aid, aunPath: this._configModel.aunPath, certPem: String(this._identity.cert ?? this._currentAid?.certPem ?? ''), privateKeyPem: String(this._identity.private_key_pem), certValid: true, privateKeyValid: true })
+            : stored?.ok ? stored.data.aid : undefined;
+        if (!identity?.isPrivateKeyValid())
+            return null;
+        const certificate = new crypto.X509Certificate(identity.certPem);
+        const end = Date.parse(certificate.validTo), start = Date.parse(certificate.validFrom);
+        if (end > Date.now() && end - Date.now() < (end - start) / 2 && this._aidStore) {
+            const renewed = await (guard ? this._aidStore._renewCert(aid, guard) : this._aidStore.renewCert(aid));
+            check();
+            if (!renewed.ok)
+                throw new ValidationError(renewed.error.message);
+            const loaded = this._aidStore.load(aid);
+            if (!loaded.ok)
+                throw new ValidationError(loaded.error.message);
+            identity = loaded.data.aid;
+            if (aid === this._aid && this._identity) {
+                this._identity.cert = identity.certPem;
+                this._currentAid = identity;
+            }
+        }
+        return identity;
+    }
+    _currentCredential(input) {
+        const records = this._tokenStore.loadMetadata?.(this._aid ?? '')?.credential_renewals_v1 ?? {};
+        let cid = typeof input === 'string' ? input : String(input.cid);
+        const seen = new Set();
+        while (records[cid]?.successor_cid && !seen.has(cid)) {
+            seen.add(cid);
+            cid = String(records[cid].successor_cid);
+        }
+        return records[cid] ? structuredClone(records[cid]) : null;
+    }
+    _credentialCurrent(input) {
+        return this._getCredentialRenewal().current(input);
+    }
+    async _resumeCredentialRenewalAfterConnect(guard, syncRevocations = false) {
+        if (!this._aid || (guard && !guard.current()))
+            return;
+        await this._safeAsync(guard ? this._credentialRenewalSigner(this._aid, guard) : this._credentialRenewalSigner(this._aid));
+        if (syncRevocations && (!guard || guard.current()))
+            await this._safeAsync(this._getCredentialRenewal()._syncRevocations?.(guard) ?? Promise.resolve());
+        if (!guard || guard.current())
+            await this._getCredentialRenewal().resume(guard);
+    }
+    _startCredentialRenewal() {
+        this._stopCredentialRenewal();
+        const aid = this._aid, version = this._serviceEventIdentityVersion;
+        if (!aid || !['ready', 'connected'].includes(this._state) || this._closing || this._disconnecting)
+            return;
+        const abort = new AbortController();
+        this._credentialRenewalAbort = abort;
+        const current = () => this._credentialRenewalAbort === abort && !abort.signal.aborted && aid === this._aid && version === this._serviceEventIdentityVersion && ['ready', 'connected'].includes(this._state) && !this._closing && !this._disconnecting;
+        const guard = { current, signal: abort.signal };
+        let nextRevocationSync = Date.now() + 3_600_000;
+        const scan = async () => {
+            const task = this._credentialRenewalScan.then(async () => {
+                if (!current())
+                    return;
+                const syncRevocations = Date.now() >= nextRevocationSync;
+                if (syncRevocations)
+                    nextRevocationSync = Date.now() + 3_600_000;
+                await this._resumeCredentialRenewalAfterConnect(guard, syncRevocations);
+            });
+            this._credentialRenewalScan = task.catch(() => { });
+            await this._safeAsync(task);
+            if (current())
+                this._credentialRenewalTimer = setTimeout(() => { void scan(); }, 60_000);
+        };
+        void scan();
+    }
+    _stopCredentialRenewal() {
+        this._credentialRenewalAbort?.abort();
+        this._credentialRenewalAbort = null;
+        if (this._credentialRenewalTimer !== null)
+            clearTimeout(this._credentialRenewalTimer);
+        this._credentialRenewalTimer = null;
+    }
+    _rememberCredential(credential, material, certificate) {
+        if (!material.long_term && certificate) {
+            const cert = new crypto.X509Certificate(typeof certificate === 'string' && !certificate.includes('-----BEGIN CERTIFICATE-----') ? Buffer.from(certificate, 'base64') : certificate);
+            const parent = Array.isArray(credential.proof_chain) ? credential.proof_chain[0] : undefined;
+            const certificateEnd = Math.floor(Date.parse(cert.validTo) / 1000);
+            const defaultEnd = credential.parent != null && isJsonObject(parent) && typeof parent.exp === 'number'
+                ? Math.min(certificateEnd, Number(parent.exp)) : certificateEnd;
+            material = { ...material, long_term: credential.exp === defaultEnd };
+        }
+        this._safeAsync(this._getCredentialRenewal().remember(credential, material));
+    }
+    async _verifyIncomingServiceEvent(event, payload) {
+        const targetAid = this._identity?.aid ?? '';
+        const version = this._serviceEventIdentityVersion;
+        const signal = this._serviceEventIdentityAbort.signal;
+        const expiresAt = Number(payload?.expires_at);
+        const transport = this._transport, connectionGeneration = transport?._connectionGeneration, workerGeneration = transport?._workerGeneration;
+        const current = () => version === this._serviceEventIdentityVersion && targetAid === (this._identity?.aid ?? '') && transport === this._transport && connectionGeneration === this._transport?._connectionGeneration && workerGeneration === this._transport?._workerGeneration && Date.now() / 1000 < expiresAt;
+        const verified = await verifyServiceEvent(event, payload, { targetAid, resolveEventCertificate: (aid, fingerprint) => this._fetchServiceEventCertificate(aid, fingerprint), resolveCredentialService: this.resolveCredentialService });
+        if (!current())
+            throw new ValidationError('service event receiver identity changed');
+        if (['credential.revoked', 'credential.revocationList'].includes(event.replace(/^event\//, ''))) {
+            await this._getCredentialRenewal()._receiveRevocations(payload, { current, signal });
+        }
+        if (event.replace(/^event\//, '') === 'org.member.changed' && isJsonObject(payload) && Object.hasOwn(payload, 'membership_package')) {
+            await this._getCredentialRenewal().importMembershipPackage(payload, { current, signal });
+            if (!current())
+                throw new ValidationError('service event receiver identity changed');
+        }
+        return verified;
+    }
+    async _handleCredentialRenewal(message) {
+        if (!isJsonObject(message))
+            return false;
+        const envelope = message;
+        const content = 'payload' in envelope ? envelope.payload : envelope;
+        const payload = decryptedOwnershipJsonText(content) ?? content;
+        let parsed = payload;
+        if (typeof payload === 'string') {
+            try {
+                parsed = JSON.parse(payload);
+            }
+            catch {
+                return false;
+            }
+        }
+        if (!isJsonObject(parsed) || !['credential.renewal.request', 'credential.renewal.result'].includes(String(parsed.type)))
+            return false;
+        await this._safeAsync(this._getCredentialRenewal().receive(String(envelope.from ?? envelope.from_aid ?? envelope.sender_aid ?? ''), parsed));
+        return true;
+    }
     async _resumeRegistrationIntent() {
         const intent = this._tokenStore.loadMetadata?.(this._aid)?.registration_intent;
         if (['group', 'org'].includes(String(intent?.type ?? this.getType())))
@@ -598,11 +789,13 @@ export class AUNClient {
     _defaultConnectDeliveryMode;
     /** peer 证书缓存 */
     _certCache = new Map();
+    _certFetchInFlight = new Map();
     _agentMdManager;
     _aidStore;
     _groupIdentityOperations = new Map();
     _groupIndexMetaCache = new GroupIndexMetaCache();
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
+    _p2pPeerPullEnabled = true;
     _seqTracker = new SeqTracker();
     _seqTrackerContext = null;
     /** 惰性群同步：已同步过的 group_id 集合 */
@@ -685,6 +878,7 @@ export class AUNClient {
     _storage;
     _collab;
     _message;
+    _debug;
     _mail;
     _group;
     _stream;
@@ -784,7 +978,7 @@ export class AUNClient {
             dnsNet,
         });
         this._transport.setProtocolMetaObserver((meta) => this._observeRpcMeta(meta));
-        this._transport.setServiceEventVerifier((event, payload) => verifyServiceEvent(event, payload, { targetAid: this._identity?.aid ?? '', resolveEventCertificate: (aid, fingerprint) => this._fetchServiceEventCertificate(aid, fingerprint), resolveCredentialService: this.resolveCredentialService }), () => this._identity?.aid ?? '', () => this._serviceEventIdentityVersion);
+        this._transport.setServiceEventVerifier((event, payload) => this._verifyIncomingServiceEvent(event, payload), () => this._identity?.aid ?? '', () => this._serviceEventIdentityVersion);
         this._transport.setProtocolDisconnectCallback((err, closeCode) => this._handleTransportDisconnect(err, closeCode));
         this._transport._onForegroundDrained = () => this._delivery.onForegroundPullsDrained();
         this._transport._onRpcResponse = () => this._delivery.requestBackgroundPullRecovery();
@@ -817,7 +1011,8 @@ export class AUNClient {
         this._dispatcher.subscribeProtocol('_raw.message.read_changed', (data) => this._onRawReadChanged(data, 'p2p'));
         // V2 P2P 推送通知：收到通知后自动走 message.v2.pull 拉取并解密
         this._dispatcher.subscribeProtocol('_raw.peer.v2.message_received', (data) => {
-            const ns = this._aid ? `p2p:${this._aid}` : '';
+            const sender = isJsonObject(data) ? String(data.sender_aid ?? '') : '';
+            const ns = this._p2pPeerPullEnabled ? (sender ? this._delivery.peerNamespace(sender) : '') : this._aid ? `p2p:${this._aid}` : '';
             const hasInline = isJsonObject(data)
                 && isJsonObject(data.inline_message);
             const inlineGeneration = hasInline ? this._delivery.captureInlineAckGeneration() : undefined;
@@ -896,6 +1091,21 @@ export class AUNClient {
             this._collab = new CollabClient(this);
         return this._collab;
     }
+    get debug() {
+        if (!this._debug)
+            this._debug = new DebugFacade(this, async (operation) => {
+                const transport = this._transport;
+                const previous = transport.getTraceMode();
+                transport.setTraceMode('diag');
+                try {
+                    return await operation();
+                }
+                finally {
+                    transport.setTraceMode(previous);
+                }
+            });
+        return this._debug;
+    }
     /** Message facade 入口 */
     get message() {
         if (!this._message)
@@ -974,6 +1184,7 @@ export class AUNClient {
     }
     async bindOwneraid(ownerAid) { return this._getOwnershipWorkflow().bindOwneraid(ownerAid); }
     async bindSubaid(subAid) { return this._getOwnershipWorkflow().bindSubaid(subAid); }
+    async resetOwnershipTask() { return this._getOwnershipWorkflow().resetOwnershipTask(); }
     async releaseSubaid(subAid) { return this._getOwnershipWorkflow().releaseSubaid(subAid); }
     async transferSubaid(subAid, newOwnerAid) { return this._getOwnershipWorkflow().transferSubaid(subAid, newOwnerAid); }
     async checkOwnershipConsensus(subAid) { return this._getOwnershipWorkflow().checkOwnershipConsensus(subAid); }
@@ -1173,7 +1384,7 @@ export class AUNClient {
             dnsNet,
         });
         this._transport.setProtocolMetaObserver((meta) => this._observeRpcMeta(meta));
-        this._transport.setServiceEventVerifier((event, payload) => verifyServiceEvent(event, payload, { targetAid: this._identity?.aid ?? '', resolveEventCertificate: (aid, fingerprint) => this._fetchServiceEventCertificate(aid, fingerprint), resolveCredentialService: this.resolveCredentialService }), () => this._identity?.aid ?? '', () => this._serviceEventIdentityVersion);
+        this._transport.setServiceEventVerifier((event, payload) => this._verifyIncomingServiceEvent(event, payload), () => this._identity?.aid ?? '', () => this._serviceEventIdentityVersion);
         this._transport.setProtocolDisconnectCallback((err, closeCode) => this._handleTransportDisconnect(err, closeCode));
         this._transport._onForegroundDrained = () => this._delivery.onForegroundPullsDrained();
         this._transport._onRpcResponse = () => this._delivery.requestBackgroundPullRecovery();
@@ -1181,7 +1392,10 @@ export class AUNClient {
     loadIdentity(aid) {
         const previousAid = this._aid;
         this._identityRuntime.loadIdentity(aid);
+        this._stopCredentialRenewal();
         this._serviceEventIdentityVersion++;
+        this._serviceEventIdentityAbort.abort();
+        this._serviceEventIdentityAbort = new AbortController();
         this._ensureReadStateIdentity();
         if (previousAid !== this._aid) {
             this._ownershipRecords.clear();
@@ -1289,6 +1503,7 @@ export class AUNClient {
             ? this._ensureReadStateIdentity() : null;
         try {
             const result = await this._rpcPipeline.call(method, params);
+            await this._safeAsync(this._getCredentialRenewal().observe(method, params ?? {}, result));
             if (readIdentity !== null && readIdentity === this._ensureReadStateIdentity())
                 this._observeReadStateResult(method, result, params ?? {});
             return result;
@@ -1318,6 +1533,13 @@ export class AUNClient {
             const groupId = String(params.group_id ?? params.groupId ?? params.group_aid ?? params.groupAid ?? fallback).trim();
             if (!groupId || !store)
                 return false;
+            const groupManager = store._agentMdManager ?? this._agentMdManager;
+            const keystore = store._keystore;
+            let pendingBind = keystore?.loadPendingGroupBind?.(`bind:${groupId}`);
+            if (!pendingBind?.public_key_der_b64 || !pendingBind?.private_key_pem)
+                pendingBind = keystore?.loadPendingGroupBind?.(groupId);
+            if (groupManager.pendingUpload(fallback) && (!pendingBind?.public_key_der_b64 || !pendingBind?.private_key_pem))
+                return false;
             try {
                 await this._runGroupIdentityOperation(groupId, () => this.bindGroupAid({ group_id: groupId }, { aidStore: store }));
             }
@@ -1336,6 +1558,8 @@ export class AUNClient {
             if (!loaded.ok || !loaded.data?.aid?.isPrivateKeyValid())
                 return false;
             const groupManager = store._agentMdManager ?? this._agentMdManager;
+            if (groupManager.pendingUpload(groupAid))
+                return false;
             if (String((groupManager._loadRecord?.(groupAid, true) ?? groupManager.loadRecord(groupAid))?.local_draft_content ?? ''))
                 return false;
             await this._runGroupIdentityOperation(groupAid, () => this._uploadGroupAgentMd(store, groupAid, {}, {}));
@@ -1353,17 +1577,15 @@ export class AUNClient {
         const aid = this._aid;
         if (!aid || !this._currentAid)
             return false;
-        const observed = await this._getOwnershipFiles().readAgent(aid);
-        if (observed.exists || String(this._agentMdManager._loadRecord?.(aid, true)?.local_draft_content ?? this._agentMdManager.loadRecord(aid)?.local_draft_content ?? ''))
+        const observed = await this._agentMdManager.readAgentMdFresh(aid);
+        if (observed.exists || String(this._agentMdManager._loadRecord?.(aid, true)?.local_draft_content ?? this._agentMdManager.loadRecord(aid)?.local_draft_content ?? '') || this._agentMdManager.pendingUpload(aid))
             return false;
         let agentMd = buildDefaultAgentMd(aid, { type: this.getType() });
         try {
             agentMd = this._agentMdManager.readContent(aid) || agentMd;
         }
         catch { }
-        const payload = updateOwnershipAgentMd(agentMd, {});
-        const raw = signOwnershipFile(this._currentAid, payload.endsWith('\n') || payload.endsWith('\r') ? payload : `${payload}\n`, 'agent');
-        await this._agentMdManager.submitOwnershipRaw(aid, raw, { if_none_match: '*' });
+        await this._agentMdManager.upload(agentMd, { if_none_match: '*' });
         return true;
     }
     async _checkIdentityAdmissionAfterConnect() {
@@ -1400,6 +1622,9 @@ export class AUNClient {
             if (!isJsonObject(raw))
                 continue;
             const group = raw;
+            const status = String(group.status ?? '').trim().toLowerCase();
+            if (status && status !== 'active')
+                continue;
             const role = String(group.role ?? group.my_role ?? '').trim().toLowerCase();
             const groupId = String(group.group_id ?? group.groupId ?? group.group_aid ?? group.groupAid ?? '').trim();
             const groupAid = String(group.group_aid ?? group.groupAid ?? groupId).trim();
@@ -1418,6 +1643,8 @@ export class AUNClient {
                         return;
                     }
                     const groupManager = store._agentMdManager ?? this._agentMdManager;
+                    if (groupManager.pendingUpload(groupAid))
+                        return;
                     if (String((groupManager._loadRecord?.(groupAid, true) ?? groupManager.loadRecord(groupAid))?.local_draft_content ?? '')) {
                         await this._agentMdManager.check(groupAid);
                         return;
@@ -1427,8 +1654,6 @@ export class AUNClient {
                         await this.bindGroupAid({ group_id: groupId, group_aid: groupAid }, { aidStore: store });
                         return;
                     }
-                    if (await this._resumeGroupAgentMdUpload(store, groupAid))
-                        return;
                     const checked = await this._agentMdManager.check(groupAid);
                     if (!checked.remote_found) {
                         await this._uploadGroupAgentMd(store, groupAid, {}, {});
@@ -1459,12 +1684,45 @@ export class AUNClient {
                 this._groupIdentityOperations.delete(key);
         }
     }
+    async _resumeOrgRequest(method, params, target) {
+        const binding = params.request_binding;
+        const now = Math.trunc(Date.now() / 1000);
+        if (!isJsonObject(binding) || now < Number(binding.exp))
+            return params;
+        const credentials = isJsonObject(params.credentials) ? params.credentials : {};
+        const credential = ['member_credential', 'approval_credential', 'audit_credential'].map((field) => credentials[field]).find(isJsonObject) ?? params.credential_template;
+        const cid = isJsonObject(credential) ? String(credential.cid) : '';
+        validateRequestBinding(binding, method, target, params, cid, String(params.nonce), String(params.request_id), Number(binding.iat));
+        let exp = now + 300;
+        for (const material of [credential, ...Object.values(credentials).filter((value) => isJsonObject(value) && value.ver === 'aun-cap/1'), ...[params, params.previous_owner, params.new_owner].filter(isJsonObject).flatMap((value) => ['membership_binding', 'credential_template', 'registration_authorization'].map((field) => value[field]))]) {
+            if (isJsonObject(material)) {
+                if (!Number.isInteger(material.exp) || Number(material.exp) <= now)
+                    throw new ValidationError('Org recovery authorization material has expired');
+                exp = Math.min(exp, Number(material.exp));
+            }
+        }
+        const refreshed = { ...params, request_binding: buildRequestBinding(method, target, params, cid, String(params.nonce), String(params.request_id), now, exp) };
+        delete refreshed.client_signature;
+        if (isJsonObject(credentials.representation_proof)) {
+            if (!this._currentAid || !isJsonObject(credential))
+                throw new ValidationError('Org recovery representation signer is unavailable');
+            refreshed.credentials = { ...credentials, representation_proof: createRepresentationProof(credential, refreshed, refreshed.request_binding, this._currentAid, refreshed.proof_chain) };
+        }
+        return refreshed;
+    }
     async createOrg(params = {}, options = {}) {
         const store = options.aidStore;
         const owner = this._currentAid;
         const orgAid = String(params.org_id ?? '').trim();
         if (!store || !owner?.isPrivateKeyValid() || !orgAid)
             throw new ValidationError('createOrg requires aidStore, org_id and current owner identity');
+        const tokens = store._tokenStore;
+        const inputHash = crypto.createHash('sha256').update(canonicalJson(params)).digest('hex');
+        let checkpoint = (typeof tokens._loadMetadataStrict === 'function' ? tokens._loadMetadataStrict(orgAid) : tokens.loadMetadata(orgAid))?.org_identity_creation;
+        if (checkpoint != null && !isJsonObject(checkpoint))
+            throw ownershipFailure('persistence_unavailable', 'Org creation checkpoint is invalid');
+        if (checkpoint && (checkpoint.owner_aid !== owner.aid || checkpoint.input_hash !== inputHash))
+            throw ownershipFailure('conflict', 'pending Org creation context changed');
         this._aidStore = store;
         let identity = store.load(orgAid);
         if (!identity.ok) {
@@ -1476,18 +1734,13 @@ export class AUNClient {
         if (!identity.ok)
             throw ownershipFailure('unavailable', identity.error.message, true);
         const target = options.serviceAid ?? `org.${orgAid.slice(orgAid.indexOf('.') + 1)}`;
-        const tokens = store._tokenStore;
-        const inputHash = crypto.createHash('sha256').update(canonicalJson(params)).digest('hex');
-        let checkpoint = tokens.loadMetadata(orgAid)?.org_identity_creation;
-        if (checkpoint && (checkpoint.owner_aid !== owner.aid || checkpoint.input_hash !== inputHash))
-            throw ownershipFailure('conflict', 'pending Org creation context changed');
         if (!checkpoint) {
             const prepared = this.org.prepareRequest('org.lifecycle.create', { ...params, owner_aid: owner.aid }, target, owner, { orgSigner: identity.data.aid });
             checkpoint = { owner_aid: owner.aid, input_hash: inputHash, source_params: params, prepared, phase: 'create' };
             tokens.saveMetadata(orgAid, { org_identity_creation: checkpoint });
         }
         if (checkpoint.phase === 'create') {
-            const result = await this.call('org.lifecycle.create', checkpoint.prepared);
+            const result = await this.call('org.lifecycle.create', await this._resumeOrgRequest('org.lifecycle.create', checkpoint.prepared, target));
             checkpoint = { ...checkpoint, result, phase: 'upload' };
             tokens.saveMetadata(orgAid, { org_identity_creation: checkpoint });
         }
@@ -1501,33 +1754,60 @@ export class AUNClient {
         if (typeof keyStore?.listIdentities !== 'function' || typeof tokens?.loadMetadata !== 'function')
             return;
         for (const aid of keyStore.listIdentities()) {
-            const metadata = tokens.loadMetadata(aid);
+            const metadata = typeof tokens._loadMetadataStrict === 'function' ? tokens._loadMetadataStrict(aid) : tokens.loadMetadata(aid);
             const creation = metadata?.org_identity_creation;
             const transfer = metadata?.org_identity_transfer;
+            if (creation != null && !isJsonObject(creation) || transfer != null && !isJsonObject(transfer))
+                throw ownershipFailure('persistence_unavailable', 'Org identity checkpoint is invalid');
             try {
                 if (creation?.owner_aid === this._aid) {
                     await this.createOrg(creation.source_params, { aidStore: store });
                     continue;
                 }
-                if (transfer?.owner_aid === this._aid) {
+                if (transfer?.owner_aid === this._aid && transfer.phase !== 'completed') {
                     await this.completeOrgTransfer(transfer.source_params, { aidStore: store });
                     continue;
                 }
-                const orgManager = store._agentMdManager;
-                if (String((orgManager?._loadRecord?.(aid, true) ?? orgManager?.loadRecord?.(aid))?.local_draft_content ?? ''))
-                    continue;
-                const pending = store._agentMdManager.pendingUpload(aid);
-                if (!pending)
-                    continue;
-                const fields = validateAgentMdDocument(pending.content, { expectedAid: aid }).frontmatter;
-                if (fields.type === 'org' && fields.owner === this._aid)
-                    await this._resumeGroupAgentMdUpload(store, aid);
             }
             catch (error) {
                 this._clientLog.warn(`post-connect Org identity recovery failed: aid=${aid} err=${formatCaughtError(error)}`);
             }
         }
     }
+    async _verifyOrgTransferMaterials(params, ownerAid) {
+        const orgAid = String(params.org_id);
+        const previous = params.previous_owner;
+        const next = params.new_owner;
+        const binding = previous.membership_binding;
+        const nextBinding = next.membership_binding;
+        const credential = previous.credential_template;
+        const ext = isJsonObject(credential.ext) ? credential.ext : {};
+        const capability = Array.isArray(credential.cap) && credential.cap.length === 1 && isJsonObject(credential.cap[0]) ? credential.cap[0] : {};
+        const now = Math.trunc(Date.now() / 1000);
+        if (binding.org_id !== orgAid || nextBinding.org_id !== orgAid || binding.member_aid === ownerAid || nextBinding.member_aid !== ownerAid
+            || binding.role !== 'member' || nextBinding.role !== 'owner' || digest(previous.terms) !== binding.terms_hash || digest(next.terms) !== nextBinding.terms_hash
+            || !Number.isSafeInteger(nextBinding.iat) || !Number.isSafeInteger(nextBinding.exp) || Number(nextBinding.iat) > now || Number(nextBinding.exp) <= now
+            || credential.iss !== orgAid || credential.sub !== binding.member_aid || credential.parent != null || credential.delegate !== false
+            || ext.credential_type !== 'member' || ext.bound_to_membership !== true || ext.org_id !== orgAid || ext.membership_id !== binding.membership_id
+            || ext.binding_version !== binding.binding_version || ext.membership_terms_hash !== binding.terms_hash
+            || capability.ns !== 'org' || capability.action !== 'role.member' || capability.resource !== orgAid)
+            throw ownershipFailure('invalid', 'Org transfer membership materials do not match');
+        validateMembershipBinding(binding);
+        const certificates = new Map();
+        for (const [aid, signature] of [[binding.member_aid, binding.member_signature], [orgAid, binding.org_signature], [orgAid, credential.signature]]) {
+            if (!isJsonObject(signature))
+                throw ownershipFailure('invalid', 'Org transfer membership materials do not match');
+            const fingerprint = String(signature.cert_fingerprint);
+            const certificate = await this._auth.resolveOwnershipCertificate(await this._resolveOwnershipCertificateGateway(String(aid)), String(aid), fingerprint);
+            certificates.set(fingerprint, certificate.cert_pem);
+        }
+        const resolve = (fingerprint) => certificates.get(fingerprint);
+        const checkedAt = Math.trunc(Date.now() / 1000);
+        verifyMembershipBinding(binding, resolve, checkedAt, orgAid);
+        verifyCredentialSignature(credential, resolve, checkedAt, orgAid);
+        if (Number(nextBinding.exp) <= checkedAt)
+            throw ownershipFailure('invalid', 'Org transfer membership materials do not match');
+    }
     async completeOrgTransfer(params = {}, options = {}) {
         const store = options.aidStore;
         const owner = this._currentAid;
@@ -1545,9 +1825,19 @@ export class AUNClient {
         const tokenStore = store._tokenStore;
         const pendingKey = `org-transfer:${orgAid}:${transferId}`;
         const inputHash = crypto.createHash('sha256').update(canonicalJson(params)).digest('hex');
-        let pending = tokenStore.loadMetadata(orgAid)?.org_identity_transfer;
+        let pending = (typeof tokenStore._loadMetadataStrict === 'function' ? tokenStore._loadMetadataStrict(orgAid) : tokenStore.loadMetadata(orgAid))?.org_identity_transfer;
+        if (pending != null && !isJsonObject(pending))
+            throw ownershipFailure('persistence_unavailable', 'Org transfer checkpoint is invalid');
+        if (pending?.phase === 'completed' && pending.transfer_id !== transferId)
+            pending = undefined;
         if (pending && (pending.transfer_id !== transferId || pending.owner_aid !== owner.aid || pending.input_hash !== inputHash))
             throw ownershipFailure('conflict', 'pending Org transfer context changed');
+        if (pending?.phase === 'completed') {
+            localStore.clearPendingGroupBind(pendingKey);
+            return pending.result;
+        }
+        if (!pending)
+            await this._verifyOrgTransferMaterials(params, owner.aid);
         let keyPair = localStore.loadPendingGroupBind(pendingKey);
         if (!keyPair) {
             if (pending)
@@ -1568,7 +1858,7 @@ export class AUNClient {
             tokenStore.saveMetadata(orgAid, { org_identity_transfer: pending });
         }
         if (pending.phase === 'rekey') {
-            const result = await this.call('org.lifecycle.transferAccept', pending.rekey_params);
+            const result = await this.call('org.lifecycle.transferAccept', await this._resumeOrgRequest('org.lifecycle.transferAccept', pending.rekey_params, target));
             pending = { ...pending, phase: 'finalize', rekey_result: result };
             tokenStore.saveMetadata(orgAid, { org_identity_transfer: pending });
         }
@@ -1604,9 +1894,9 @@ export class AUNClient {
             pending = { ...pending, finalize_params: this.org.prepareRequest('org.lifecycle.transferAccept', final, target, owner, { orgSigner: orgIdentity }) };
             tokenStore.saveMetadata(orgAid, { org_identity_transfer: pending });
         }
-        const result = await this.call('org.lifecycle.transferAccept', pending.finalize_params);
+        const result = await this.call('org.lifecycle.transferAccept', await this._resumeOrgRequest('org.lifecycle.transferAccept', pending.finalize_params, target));
         await this._uploadOrgAgentMd(store, orgAid, pending.source_params);
-        tokenStore.saveMetadata(orgAid, { org_identity_transfer: null });
+        tokenStore.saveMetadata(orgAid, { org_identity_transfer: { transfer_id: transferId, owner_aid: owner.aid, input_hash: inputHash, phase: 'completed', result } });
         localStore.clearPendingGroupBind(pendingKey);
         return result;
     }
@@ -1859,7 +2149,13 @@ export class AUNClient {
             entityIdentityGetter: (aid, type) => this._freshEntityCertificate(aid, type),
             entitySignerResolver: (aid, fingerprint) => this._freshEntitySigner(aid, fingerprint),
             gatewayResolver: (aid) => identityStore._resolveGateway(aid),
-            accessTokenResolver: (_aid, gatewayUrl) => identityStore._uploadAgentMdToken(identity, gatewayUrl),
+            accessTokenResolver: async () => {
+                const state = identityStore._tokenStore?.loadInstanceState?.(identity.aid, store.deviceId, store.slotId) ?? {};
+                const token = AuthFlow._getCachedAccessToken(state);
+                if (token && String(state.refresh_token ?? '') && !this._auth._validateCachedCredentials(identityStore._authIdentityFromAid(identity)))
+                    return token;
+                return identityStore._uploadAgentMdToken(identity, await identityStore._resolveGateway(identity.aid));
+            },
             aidValidator: (aid) => identityStore._registerFlow.validateAidName(aid),
         });
         return await manager.resumePendingUpload(groupAid);
@@ -2334,6 +2630,11 @@ export class AUNClient {
         const tStart = Date.now();
         this._clientLog.debug(`on enter: event=${event}`);
         const result = this._dispatcher.subscribe(event, handler);
+        if (event === 'message.received' || event === 'message.recalled' || event === 'message.batch') {
+            if (this._p2pPeerPullEnabled)
+                this._delivery.refreshPendingPeers();
+            this._delivery.requestBackgroundPullRecovery();
+        }
         this._clientLog.debug(`on exit: elapsed=${Date.now() - tStart}ms event=${event}`);
         return result;
     }
@@ -2663,7 +2964,10 @@ export class AUNClient {
         if (event === 'message.received') {
             return this._handleOwnershipMessage(payload).then((handled) => {
                 if (!handled)
-                    return this._delivery.publishAppEvent(event, payload, source, deliveryContext);
+                    return this._handleCredentialRenewal(payload).then((renewed) => {
+                        if (!renewed)
+                            return this._delivery.publishAppEvent(event, payload, source, deliveryContext);
+                    });
                 return undefined;
             });
         }
@@ -3094,22 +3398,36 @@ export class AUNClient {
                 this._clientLog.debug(`_fetchPeerCert exit: elapsed=${Date.now() - tStart}ms aid=${aid} (cache_hit)`);
                 return cached.certPem;
             }
-            const gatewayUrl = this._gatewayUrl;
-            if (!gatewayUrl) {
-                throw new ValidationError('gateway url unavailable for e2ee cert fetch');
+            const inFlightKey = `${cacheKey}:timeout:${timeoutMs}`;
+            const pending = this._certFetchInFlight.get(inFlightKey);
+            if (pending)
+                return await pending;
+            const request = (async () => {
+                const gatewayUrl = this._gatewayUrl;
+                if (!gatewayUrl) {
+                    throw new ValidationError('gateway url unavailable for e2ee cert fetch');
+                }
+                const peerGatewayUrl = AUNClient._resolvePeerGatewayUrl(gatewayUrl, aid);
+                const certPem = await _httpGetText(AUNClient._buildCertUrl(peerGatewayUrl, aid, certFingerprint), this._configModel.verifySsl, timeoutMs);
+                const validated = await this._validateAndCachePeerCert({
+                    aid,
+                    certPem,
+                    certFingerprint,
+                    source: 'fetch',
+                    signedAt,
+                    agentMdRead,
+                });
+                this._clientLog.debug(`_fetchPeerCert exit: elapsed=${Date.now() - tStart}ms aid=${aid} (fetched)`);
+                return validated;
+            })();
+            this._certFetchInFlight.set(inFlightKey, request);
+            try {
+                return await request;
+            }
+            finally {
+                if (this._certFetchInFlight.get(inFlightKey) === request)
+                    this._certFetchInFlight.delete(inFlightKey);
             }
-            const peerGatewayUrl = AUNClient._resolvePeerGatewayUrl(gatewayUrl, aid);
-            const certPem = await _httpGetText(AUNClient._buildCertUrl(peerGatewayUrl, aid, certFingerprint), this._configModel.verifySsl, timeoutMs);
-            const validated = await this._validateAndCachePeerCert({
-                aid,
-                certPem,
-                certFingerprint,
-                source: 'fetch',
-                signedAt,
-                agentMdRead,
-            });
-            this._clientLog.debug(`_fetchPeerCert exit: elapsed=${Date.now() - tStart}ms aid=${aid} (fetched)`);
-            return validated;
         }
         catch (err) {
             this._clientLog.debug(`_fetchPeerCert exit (error): elapsed=${Date.now() - tStart}ms aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
@@ -3685,7 +4003,7 @@ export class AUNClient {
     }
     /** 后台 Promise 统一兜底，避免事件回调里的异步异常变成未处理拒绝。 */
     _safeAsync(promise) {
-        promise.catch((exc) => {
+        return promise.then(() => undefined).catch((exc) => {
             this._clientLog.warn(`background task exception: ${formatCaughtError(exc)}`);
         });
     }
@@ -3880,7 +4198,7 @@ export class AUNClient {
         return await this._v2E2EE.ackGroupV2(groupId, upToSeq, groupAid);
     }
     /** 解密单条 V2 pull 消息。缺 sender IK 时先入 pending，后台补齐后重试。 */
-    async _decryptV2Message(msg, allowPending = true, emitUndecryptable = true, rotateKeys = true, observeAgentMd = true, deferStatus, deferKeyFetch = false, source = 'pull') {
+    async _decryptV2Message(msg, allowPending = true, emitUndecryptable = true, rotateKeys = true, observeAgentMd = true, deferStatus, deferKeyFetch = false, source = 'pull', deferredEffects) {
         const session = this._v2Session;
         if (!session)
             return null;
@@ -3896,8 +4214,12 @@ export class AUNClient {
             return null;
         }
         const e2eeMeta = this._v2E2eeMeta(envelope);
-        if (observeAgentMd)
-            this._agentMdManager.observeEnvelope(envelope);
+        if (observeAgentMd) {
+            if (deferredEffects)
+                deferredEffects.push(() => this._agentMdManager.observeEnvelope(envelope));
+            else
+                this._agentMdManager.observeEnvelope(envelope);
+        }
         let spkId = '';
         let recipientKeySource = '';
         if (isJsonObject(envelope.recipient)) {
@@ -3976,8 +4298,12 @@ export class AUNClient {
             };
             this._attachV2EnvelopeMetadata(event, e2eeMeta);
             this._logMessageDebug('decrypt-fail', 'v2.decrypt', undecryptableEvent, event);
-            if (emitUndecryptable)
-                this._dispatcher.enqueue(undecryptableEvent, event);
+            if (emitUndecryptable) {
+                if (deferredEffects)
+                    deferredEffects.push(() => { this._dispatcher.enqueue(undecryptableEvent, event); });
+                else
+                    this._dispatcher.enqueue(undecryptableEvent, event);
+            }
             return null;
         }
         this._clientLog.debug(`V2 decrypt key lookup ok: seq=${String(msg.seq ?? '')}, group=${groupIdForKeys || '<p2p>'}, ik_len=${ikPriv.byteLength}, spk_len=${spkPriv?.byteLength ?? 0}`);
@@ -4015,8 +4341,12 @@ export class AUNClient {
             };
             this._attachV2EnvelopeMetadata(event, e2eeMeta);
             this._logMessageDebug('decrypt-fail', 'v2.decrypt', undecryptableEvent, event);
-            if (emitUndecryptable)
-                this._dispatcher.enqueue(undecryptableEvent, event);
+            if (emitUndecryptable) {
+                if (deferredEffects)
+                    deferredEffects.push(() => { this._dispatcher.enqueue(undecryptableEvent, event); });
+                else
+                    this._dispatcher.enqueue(undecryptableEvent, event);
+            }
             return null;
         }
         let plaintext;
@@ -4044,16 +4374,24 @@ export class AUNClient {
             };
             this._attachV2EnvelopeMetadata(event, e2eeMeta);
             this._logMessageDebug('decrypt-fail', 'v2.decrypt', undecryptableEvent, event);
-            if (emitUndecryptable)
-                this._dispatcher.enqueue(undecryptableEvent, event);
+            if (emitUndecryptable) {
+                if (deferredEffects)
+                    deferredEffects.push(() => { this._dispatcher.enqueue(undecryptableEvent, event); });
+                else
+                    this._dispatcher.enqueue(undecryptableEvent, event);
+            }
             return null;
         }
         if (plaintext === null) {
             this._clientLog.debug(`V2 decrypt returned null plaintext: seq=${String(msg.seq ?? '')}, group=${groupIdForKeys || '<p2p>'}`);
             return null;
         }
-        if (rotateKeys)
-            this._scheduleV2KeyRotationForMessage(msg, envelope);
+        if (rotateKeys) {
+            if (deferredEffects)
+                deferredEffects.push(() => this._scheduleV2KeyRotationForMessage(msg, envelope));
+            else
+                this._scheduleV2KeyRotationForMessage(msg, envelope);
+        }
         const e2ee = this._v2E2eeMeta(envelope);
         let result = {
             message_id: String(msg.message_id ?? ''),
@@ -4149,6 +4487,8 @@ export class AUNClient {
         if (protectedHeaders && Object.keys(protectedHeaders).length > 0) {
             meta.protected_headers = protectedHeaders;
         }
+        if (typeof envelope.need_render === 'boolean')
+            meta.need_render = envelope.need_render;
         const payloadType = String(envelope.payload_type ?? protectedHeaders?.payload_type ?? '').trim();
         if (payloadType) {
             meta.payload_type = payloadType;
@@ -4164,6 +4504,8 @@ export class AUNClient {
         return meta;
     }
     _attachV2EnvelopeMetadata(message, meta) {
+        if (typeof meta.need_render === 'boolean')
+            message.need_render = meta.need_render;
         const payloadType = typeof meta.payload_type === 'string' ? meta.payload_type.trim() : '';
         if (payloadType)
             message.payload_type = payloadType;
@@ -4521,6 +4863,7 @@ export class AUNClient {
     // ── 内部：后台任务 ────────────────────────────────────────
     /** 启动所有后台任务 */
     _startBackgroundTasks() {
+        this._startCredentialRenewal();
         // WebSocket Ping/Pong 由 Gateway 与传输层处理；SDK 不发送 RPC 心跳。
         // 短连接生命周期短，不需要 token 刷新。
         if (this._sessionOptions.connection_kind !== 'short') {
@@ -4530,6 +4873,7 @@ export class AUNClient {
     }
     /** 停止所有后台任务 */
     _stopBackgroundTasks() {
+        this._stopCredentialRenewal();
         if (this._heartbeatTimer !== null) {
             clearInterval(this._heartbeatTimer);
             this._heartbeatTimer = null;