@agentunion/fastaun-browser 0.5.20 → 0.5.21

package/dist/client.js

@@ -20,7 +20,7 @@ import { IdentityRuntimeManager } from './client/identity.js';
 import { LifecycleController } from './client/lifecycle.js';
 import { PeerDirectory } from './client/peers.js';
 import { RpcPipeline } from './client/rpc-pipeline.js';
-import { CredentialFacade, GroupFacade, MailFacade, MessageFacade, OrgFacade, StreamFacade } from './facades.js';
+import { DebugFacade, CredentialFacade, GroupFacade, MailFacade, MessageFacade, OrgFacade, StreamFacade } from './facades.js';
 import { StorageVFS } from './storage/vfs.js';
 import { CollabClient } from './collab/client.js';
 import { V2E2EECoordinator } from './client/v2-e2ee.js';
@@ -39,7 +39,7 @@ import { AUNError, AuthError, ConnectionError, E2EEError, NotFoundError, Permiss
 import { isJsonObject, ConnectionState, STATE_TO_PUBLIC, } from './types.js';
 import { AID } from './aid.js';
 import { OwnershipFiles, OwnershipStorageAdapter, ownershipSha256 } from './ownership-v21.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';
 import { OwnershipWorkflow, parseOwnershipRegistrationIntent } from './ownership-workflow.js';
 import { buildOwnershipMessage, encryptIdentity, decryptIdentity, } from './ownership-proof.js';
 function getV2DeviceId(dev) {
@@ -466,6 +466,7 @@ function v2E2eeMeta(envelope) {
         suite,
         encryption_mode: `v2_${modeSuite}`,
         forward_secrecy: true,
+        need_render: envelope.need_render !== false,
     };
     const protectedHeaders = metadataWithoutAuth(envelope.protected_headers);
     if (protectedHeaders && Object.keys(protectedHeaders).length > 0) {
@@ -488,6 +489,8 @@ function v2E2eeMeta(envelope) {
 function attachV2EnvelopeMetadata(message, meta) {
     if (!meta)
         return;
+    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;
@@ -589,6 +592,7 @@ export class AUNClient {
     config;
     _aid = null;
     _serviceEventIdentityVersion = 0;
+    _serviceEventIdentityAbort = new AbortController();
     _identity = null;
     _state = 'idle';
     _currentAid = null;
@@ -674,6 +678,7 @@ export class AUNClient {
     _transport;
     // E2EE 编排状态（内存缓存）
     _certCache = new Map();
+    _certFetchInFlight = new Map();
     // 后台任务 handle（浏览器 setInterval/setTimeout）
     _heartbeatTimer = null;
     _heartbeatCount = 0;
@@ -714,6 +719,7 @@ export class AUNClient {
     _groupIndexCacheLoaded = new Set();
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     _seqTracker = new SeqTracker();
+    _p2pPeerPullEnabled = true;
     _seqTrackerContext = null;
     /** 补洞去重：已完成/进行中的 key 集合，防止重复 pull 同一区间 */
     _gapFillDone = new Set();
@@ -772,10 +778,173 @@ export class AUNClient {
     _storage;
     _collab;
     _messageFacade;
+    _debugFacade;
     _mailFacade;
     _groupFacade;
     _streamFacade;
     _credentialFacade;
+    _credentialRenewal;
+    _credentialRenewalTimer = null;
+    _credentialRenewalAbort = null;
+    _credentialRenewalScan = Promise.resolve();
+    _getCredentialRenewal() {
+        return this._credentialRenewal ??= new CredentialRenewal({
+            currentAid: () => this._aid ?? '',
+            atomicCheckpointSave: () => this._tokenStore instanceof IndexedDBTokenStore,
+            load: async (aid) => JSON.parse(await (this._tokenStore._getMetadataStrict?.(aid, 'credential_renewals_v1') ?? this._tokenStore.getMetadata?.(aid, 'credential_renewals_v1')) || '{}'),
+            ...(typeof this._tokenStore._getMetadataStrict === 'function' ? {
+                loadRevocations: async (aid) => JSON.parse(await this._tokenStore._getMetadataStrict(aid, 'credential_revocations_v1') || '{}'),
+                saveRevocations: async (aid, state, guard) => {
+                    if (guard)
+                        await this._tokenStore._setMetadataIfCurrent(aid, 'credential_revocations_v1', JSON.stringify(state), guard);
+                    else
+                        await this._tokenStore.setMetadata?.(aid, 'credential_revocations_v1', JSON.stringify(state));
+                },
+            } : {}),
+            save: async (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 IndexedDBTokenStore ? 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];
+                }));
+                if (typeof this._tokenStore._setMetadataIfCurrent === 'function')
+                    await this._tokenStore._setMetadataIfCurrent(aid, 'credential_renewals_v1', JSON.stringify(saved), { current, signal: guard?.signal });
+                else
+                    await this._tokenStore.setMetadata?.(aid, 'credential_renewals_v1', JSON.stringify(saved));
+                if (!current())
+                    throw new ValidationError('membership event receiver identity changed');
+            },
+            signer: (aid, guard) => this._credentialSigningIdentity(aid, guard),
+            certificate: (aid, fingerprint, signedAt) => signedAt === undefined
+                ? this._resolveServiceEventCertificate(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 }),
+        });
+    }
+    async _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'); };
+        await this._getCredentialRenewal()._assertNotRevoked(credential, proofChain);
+        current();
+        return current;
+    }
+    async _credentialSigningIdentity(aid, guard) {
+        const check = () => { if (guard && !guard.current())
+            throw new ValidationError('credential renewal was superseded'); };
+        check();
+        const stored = await this._aidStore?.load(aid);
+        check();
+        let identity = aid === this._aid && this._identity?.private_key_pem
+            ? await 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;
+        check();
+        const certificate = parseCertMetadata(identity.certPem);
+        const end = certificate.notAfter.getTime(), start = certificate.notBefore.getTime();
+        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 = await this._aidStore.load(aid);
+            check();
+            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;
+    }
+    _startCredentialRenewal() {
+        this._stopCredentialRenewal();
+        const aid = this._aid, version = this._serviceEventIdentityVersion;
+        if (!aid || this._state !== 'connected' || 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 && this._state === 'connected' && !this._closing && !this._disconnecting;
+        const guard = { current, signal: abort.signal };
+        const scan = async () => {
+            const task = this._credentialRenewalScan.then(async () => {
+                if (!current())
+                    return;
+                await this._credentialSigningIdentity(aid, guard);
+                if (current())
+                    await this._safeAsync(this._getCredentialRenewal()._syncRevocations?.(guard) ?? Promise.resolve());
+                if (current())
+                    await this._getCredentialRenewal().resume(guard);
+            });
+            this._credentialRenewalScan = task.catch(() => { });
+            this._safeAsync(task);
+            await task.catch(() => { });
+            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 === undefined && certificate) {
+            const pem = typeof certificate === 'string' ? certificate : arrayBufferToPem(exactArrayBuffer(certificate), 'CERTIFICATE');
+            const parent = Array.isArray(credential.proof_chain) ? credential.proof_chain[0] : undefined;
+            material = { ...material, long_term: credential.exp === Math.min(Math.floor(parseCertMetadata(pem).notAfter.getTime() / 1000), credential.parent != null && parent ? Number(parent.exp) : Infinity) };
+        }
+        this._safeAsync(this._getCredentialRenewal().remember(credential, material));
+    }
+    _credentialCurrent(input) {
+        return this._getCredentialRenewal().current(input);
+    }
+    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;
+        if (Number(parsed.exp) <= Date.now() / 1000)
+            return true;
+        try {
+            await this._getCredentialRenewal().receive(String(envelope.from ?? envelope.from_aid ?? envelope.sender_aid ?? ''), parsed);
+        }
+        catch { }
+        return true;
+    }
     _orgFacade;
     _groupInvitePending = new Map();
     _groupInviteStateAid = null;
@@ -982,6 +1151,21 @@ export class AUNClient {
             this._collab = new CollabClient(this);
         return this._collab;
     }
+    get debug() {
+        if (!this._debugFacade)
+            this._debugFacade = 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._debugFacade;
+    }
     /** Message RPC facade 入口 */
     get message() {
         if (!this._messageFacade)
@@ -1240,9 +1424,9 @@ export class AUNClient {
                     return this._currentAid;
                 },
                 readAgentMdFresh: (aid) => this._agentMdManager.readOwnershipFresh(aid),
-                submitAgentMdRaw: (aid, raw, condition) => this._agentMdManager.submitOwnershipRaw(aid, raw, condition),
+                submitAgentMdRaw: (aid, raw, condition, guard) => this._agentMdManager.submitOwnershipRaw(aid, raw, condition, guard),
                 readOwnerMd: (owner, sub) => storage.readOwnerMd(owner, sub),
-                writeOwnerMd: (owner, sub, raw) => storage.writeOwnerMd(owner, sub, raw),
+                writeOwnerMd: (owner, sub, raw, original, guard) => storage.writeOwnerMd(owner, sub, raw, original, guard),
                 deleteOwnerMd: (owner, sub) => storage.deleteOwnerMd(owner, sub),
                 resolveCertificate: async (aid, fingerprint, keyPurpose) => this._auth.resolveOwnershipCertificate(await this._resolveOwnershipCertificateGateway(aid), aid, fingerprint, keyPurpose),
             });
@@ -1257,6 +1441,7 @@ export class AUNClient {
     }
     async bindOwneraid(ownerAid) { return await this._ownershipV21().bindOwneraid(ownerAid); }
     async bindSubaid(subAid) { return await this._ownershipV21().bindSubaid(subAid); }
+    async resetOwnershipTask() { return await this._ownershipV21().resetOwnershipTask(); }
     async releaseSubaid(subAid) { return await this._ownershipV21().releaseSubaid(subAid); }
     async transferSubaid(subAid, newOwnerAid) { return await this._ownershipV21().transferSubaid(subAid, newOwnerAid); }
     async checkOwnershipConsensus(subAid) { return await this._ownershipV21().checkOwnershipConsensus(subAid); }
@@ -1805,9 +1990,13 @@ export class AUNClient {
     loadIdentity(aid) {
         const previousAid = this._aid;
         this._identityRuntime.loadIdentity(aid);
+        this._stopCredentialRenewal();
         this._dispatcher.setEventIdentity(this._aid ?? '');
-        if (previousAid !== this._aid)
+        if (previousAid !== this._aid) {
             this._serviceEventIdentityVersion++;
+            this._serviceEventIdentityAbort.abort();
+            this._serviceEventIdentityAbort = new AbortController();
+        }
         this._ensureReadStateIdentity();
         if (previousAid !== this._aid) {
             this._ownershipRecords.clear();
@@ -1882,6 +2071,10 @@ export class AUNClient {
             ? this._ensureReadStateIdentity() : null;
         try {
             const result = await this._rpcPipeline.call(method, params);
+            try {
+                await this._getCredentialRenewal().observe(method, params ?? {}, result);
+            }
+            catch { }
             if (readIdentity !== null && readIdentity === this._ensureReadStateIdentity())
                 this._observeReadStateResult(method, result, params ?? {});
             return result;
@@ -2053,12 +2246,46 @@ 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: await 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 = await ownershipSha256(canonicalJson(params));
+        const raw = await (typeof tokens._getMetadataStrict === 'function' ? tokens._getMetadataStrict(orgAid, 'org_identity_creation') : tokens.getMetadata(orgAid, 'org_identity_creation'));
+        let checkpoint = raw ? JSON.parse(raw) : undefined;
+        if (raw && !isJsonObject(checkpoint))
+            throw new StateError('Org creation checkpoint is invalid', { stringCode: 'persistence_unavailable' });
+        if (checkpoint && (checkpoint.owner_aid !== owner.aid || checkpoint.input_hash !== inputHash))
+            throw new StateError('pending Org creation context changed', { stringCode: 'conflict', retryable: false });
         this._aidStore = store;
         let identity = await store.load(orgAid);
         if (!identity.ok) {
@@ -2070,19 +2297,13 @@ export class AUNClient {
         if (!identity.ok)
             throw new StateError(identity.error.message, { stringCode: 'unavailable', retryable: true });
         const target = options.serviceAid ?? `org.${orgAid.slice(orgAid.indexOf('.') + 1)}`;
-        const tokens = store._tokenStore;
-        const inputHash = await ownershipSha256(canonicalJson(params));
-        const raw = await tokens.getMetadata(orgAid, 'org_identity_creation');
-        let checkpoint = raw ? JSON.parse(raw) : undefined;
-        if (checkpoint && (checkpoint.owner_aid !== owner.aid || checkpoint.input_hash !== inputHash))
-            throw new StateError('pending Org creation context changed', { stringCode: 'conflict', retryable: false });
         if (!checkpoint) {
             const prepared = await 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: structuredClone(params), prepared, phase: 'create' };
             await tokens.setMetadata(orgAid, 'org_identity_creation', JSON.stringify(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' };
             await tokens.setMetadata(orgAid, 'org_identity_creation', JSON.stringify(checkpoint));
         }
@@ -2097,10 +2318,12 @@ export class AUNClient {
             return;
         for (const aid of await keyStore.listIdentities()) {
             try {
-                const creationRaw = await tokens.getMetadata(aid, 'org_identity_creation');
-                const transferRaw = await tokens.getMetadata(aid, 'org_identity_transfer');
+                const creationRaw = await (typeof tokens._getMetadataStrict === 'function' ? tokens._getMetadataStrict(aid, 'org_identity_creation') : tokens.getMetadata(aid, 'org_identity_creation'));
+                const transferRaw = await (typeof tokens._getMetadataStrict === 'function' ? tokens._getMetadataStrict(aid, 'org_identity_transfer') : tokens.getMetadata(aid, 'org_identity_transfer'));
                 const creation = creationRaw ? JSON.parse(creationRaw) : undefined;
                 const transfer = transferRaw ? JSON.parse(transferRaw) : undefined;
+                if (creationRaw && !isJsonObject(creation) || transferRaw && !isJsonObject(transfer))
+                    throw new StateError('Org identity checkpoint is invalid', { stringCode: 'persistence_unavailable' });
                 if (creation?.owner_aid === this._aid) {
                     await this.createOrg(creation.source_params, { aidStore: store });
                     continue;
@@ -2123,6 +2346,40 @@ export class AUNClient {
             }
         }
     }
+    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 new StateError('Org transfer membership materials do not match', { stringCode: 'invalid', retryable: false });
+        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 new StateError('Org transfer membership materials do not match', { stringCode: 'invalid', retryable: false });
+            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);
+        await verifyMembershipBinding(binding, resolve, checkedAt, orgAid);
+        await verifyCredentialSignature(credential, resolve, checkedAt, orgAid);
+        if (Number(nextBinding.exp) <= checkedAt)
+            throw new StateError('Org transfer membership materials do not match', { stringCode: 'invalid', retryable: false });
+    }
     async completeOrgTransfer(params = {}, options = {}) {
         const store = options.aidStore;
         const owner = this._currentAid;
@@ -2139,10 +2396,14 @@ export class AUNClient {
         const localStore = store._keystore;
         const tokenStore = store._tokenStore;
         const inputHash = await ownershipSha256(canonicalJson(params));
-        const raw = await tokenStore.getMetadata(orgAid, 'org_identity_transfer');
+        const raw = await (typeof tokenStore._getMetadataStrict === 'function' ? tokenStore._getMetadataStrict(orgAid, 'org_identity_transfer') : tokenStore.getMetadata(orgAid, 'org_identity_transfer'));
         let pending = raw ? JSON.parse(raw) : undefined;
+        if (raw && !isJsonObject(pending))
+            throw new StateError('Org transfer checkpoint is invalid', { stringCode: 'persistence_unavailable' });
         if (pending && (pending.transfer_id !== transferId || pending.owner_aid !== owner.aid || pending.input_hash !== inputHash))
             throw new StateError('pending Org transfer context changed', { stringCode: 'conflict', retryable: false });
+        if (!pending)
+            await this._verifyOrgTransferMaterials(params, owner.aid);
         const pendingKey = `org-transfer:${orgAid}:${transferId}`;
         let keyPair = await localStore.loadPendingGroupBind(pendingKey);
         if (!keyPair) {
@@ -2164,7 +2425,7 @@ export class AUNClient {
             await tokenStore.setMetadata(orgAid, 'org_identity_transfer', JSON.stringify(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 };
             await tokenStore.setMetadata(orgAid, 'org_identity_transfer', JSON.stringify(pending));
         }
@@ -2201,7 +2462,7 @@ export class AUNClient {
             pending = { ...pending, finalize_params: await this.org.prepareRequest('org.lifecycle.transferAccept', final, target, owner, { orgSigner: orgIdentity }) };
             await tokenStore.setMetadata(orgAid, 'org_identity_transfer', JSON.stringify(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);
         await tokenStore.setMetadata(orgAid, 'org_identity_transfer', '');
         await localStore.clearPendingGroupBind(pendingKey);
@@ -2478,6 +2739,7 @@ export class AUNClient {
         return await manager.resumePendingUpload(groupAid);
     }
     async _uploadGroupAgentMd(store, groupAid, params, group, uploaderAid) {
+        this._aidStore = store;
         if (await this._resumeGroupAgentMdUpload(store, groupAid))
             return;
         if (typeof store.uploadAgentMd !== 'function') {
@@ -3162,13 +3424,15 @@ export class AUNClient {
     async _fillP2pGap() {
         return this._delivery.fillP2pGap();
     }
-    _markPublishedSeq(ns, seq) {
-        this._delivery.markPublishedSeq(ns, seq);
+    _markPublishedSeq(ns, seq, page) {
+        this._delivery.markPublishedSeq(ns, seq, page);
     }
-    async _publishAppEvent(event, payload, source = 'direct', ns = '', batch) {
+    async _publishAppEvent(event, payload, source = 'direct', ns = '', batch, page) {
         if (event === 'message.received' && await this._handleOwnershipMessage(payload))
             return;
-        await this._delivery.publishAppEvent(event, payload, source, ns, batch);
+        if (event === 'message.received' && await this._handleCredentialRenewal(payload))
+            return;
+        await this._delivery.publishAppEvent(event, payload, source, ns, batch, page);
     }
     _echoTimestamp() {
         const now = new Date();
@@ -3209,14 +3473,14 @@ export class AUNClient {
         const trace = `${this._echoTimestamp()} [AUN-SDK.receive] aid=${this._aid ?? '-'} conn_uptime=${uptime}s`;
         msg.payload = { ...payload, text: payload.text + '\n' + trace };
     }
-    async _drainOrderedMessages(ns, beforeSeq, pullResponse = false, persist = true, throughSeq) {
-        await this._delivery.drainOrderedMessages(ns, beforeSeq, pullResponse, persist, undefined, 'pull', throughSeq);
+    async _drainOrderedMessages(ns, beforeSeq, pullResponse = false, persist = true, throughSeq, page) {
+        await this._delivery.drainOrderedMessages(ns, beforeSeq, pullResponse, persist, undefined, 'pull', throughSeq, page);
     }
-    async _publishOrderedMessage(event, ns, seq, payload, source = 'push', batch) {
-        return this._delivery.publishOrderedMessage(event, ns, seq, payload, source, batch);
+    async _publishOrderedMessage(event, ns, seq, payload, source = 'push', batch, page) {
+        return this._delivery.publishOrderedMessage(event, ns, seq, payload, source, batch, page);
     }
-    async _publishPulledMessage(event, ns, seq, payload, persist = true, source = 'pull', batch) {
-        return this._delivery.publishPulledMessage(event, ns, seq, payload, persist, source, batch);
+    async _publishPulledMessage(event, ns, seq, payload, persist = true, source = 'pull', batch, page) {
+        return this._delivery.publishPulledMessage(event, ns, seq, payload, persist, source, batch, page);
     }
     _extractGroupIdFromResult(result) {
         const group = isJsonObject(result.group) ? result.group : null;
@@ -3679,9 +3943,17 @@ export class AUNClient {
     async _verifyIncomingServiceEvent(event, payload) {
         const targetAid = this._aid || this._currentAid?.aid || '';
         const version = this._serviceEventIdentityVersion;
+        const signal = this._serviceEventIdentityAbort.signal;
+        const expiresAt = Number(payload?.expires_at);
+        const current = () => version === this._serviceEventIdentityVersion && targetAid === (this._aid || this._currentAid?.aid || '') && Date.now() / 1000 < expiresAt;
         const verified = await verifyServiceEvent(event, payload, { targetAid, resolveEventCertificate: (service, fingerprint) => this._resolveServiceEventCertificate(service, fingerprint), resolveCredentialService: (cid) => this.resolveCredentialService?.(cid) });
-        if (version !== this._serviceEventIdentityVersion || targetAid !== (this._aid || this._currentAid?.aid || ''))
+        if (!current())
             throw new ValidationError('service event receiver identity changed');
+        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 _fetchPeerCert(aid, certFingerprint, timeoutMs = 5000, signedAt, agentMdRead = false) {
@@ -3695,62 +3967,75 @@ export class AUNClient {
                 this._clientLog.debug(`_fetchPeerCert exit: elapsed=${Date.now() - tStart}ms aid=${aid} source=cache`);
                 return cached.certPem;
             }
-            const gatewayUrl = this._gatewayUrl;
-            if (!gatewayUrl) {
-                throw new ValidationError('gateway url unavailable for e2ee cert fetch');
-            }
-            // 跨域时用 peer 所在域的 Gateway URL
-            const peerGatewayUrl = resolvePeerGatewayUrl(gatewayUrl, aid);
-            let certPem;
-            const certUrl = buildCertUrl(peerGatewayUrl, aid, certFingerprint);
-            // 兼容旧浏览器，不使用 AbortSignal.timeout（Chrome 103+ 才支持）
-            const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-            try {
-                const resp = await fetch(certUrl, { signal: controller.signal });
-                if (!resp.ok)
-                    throw new ValidationError(`failed to fetch peer cert for ${aid}: HTTP ${resp.status}`);
-                certPem = await resp.text();
-            }
-            finally {
-                clearTimeout(timeoutId);
-            }
-            // H7: 严格校验指纹（DER SHA-256 或 SPKI SHA-256 任一匹配即可）
-            if (certFingerprint) {
-                const expectedFP = String(certFingerprint).trim().toLowerCase();
-                if (!normalizeFingerprintHex(expectedFP)) {
-                    throw new ValidationError(`unsupported cert_fingerprint format for ${aid}: ${expectedFP.slice(0, 24)}`);
+            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');
                 }
-                if (!(await certMatchesFingerprint(certPem, expectedFP))) {
-                    throw new ValidationError(`peer cert fingerprint mismatch for ${aid}: expected=${expectedFP.slice(0, 24)}...`);
+                // 跨域时用 peer 所在域的 Gateway URL
+                const peerGatewayUrl = resolvePeerGatewayUrl(gatewayUrl, aid);
+                let certPem;
+                const certUrl = buildCertUrl(peerGatewayUrl, aid, certFingerprint);
+                // 兼容旧浏览器，不使用 AbortSignal.timeout（Chrome 103+ 才支持）
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+                try {
+                    const resp = await fetch(certUrl, { signal: controller.signal });
+                    if (!resp.ok)
+                        throw new ValidationError(`failed to fetch peer cert for ${aid}: HTTP ${resp.status}`);
+                    certPem = await resp.text();
                 }
-            }
-            // 完整 PKI 验证：链 + CRL + OCSP + AID 绑定
-            try {
-                if (signedAt === undefined)
-                    await this._auth.verifyPeerCertificate(peerGatewayUrl, certPem, aid);
-                else if (agentMdRead)
-                    await this._auth.verifyPeerCertificate(peerGatewayUrl, certPem, aid, signedAt, false, true);
-                else
-                    await this._auth.verifyPeerCertificate(peerGatewayUrl, certPem, aid, signedAt);
-            }
-            catch (exc) {
-                throw new ValidationError(`peer cert verification failed for ${aid}: ${exc}`);
-            }
-            this._certCache.set(cacheKey, {
-                certPem,
-                validatedAt: now,
-                refreshAfter: now + PEER_CERT_CACHE_TTL,
-            });
+                finally {
+                    clearTimeout(timeoutId);
+                }
+                // H7: 严格校验指纹（DER SHA-256 或 SPKI SHA-256 任一匹配即可）
+                if (certFingerprint) {
+                    const expectedFP = String(certFingerprint).trim().toLowerCase();
+                    if (!normalizeFingerprintHex(expectedFP)) {
+                        throw new ValidationError(`unsupported cert_fingerprint format for ${aid}: ${expectedFP.slice(0, 24)}`);
+                    }
+                    if (!(await certMatchesFingerprint(certPem, expectedFP))) {
+                        throw new ValidationError(`peer cert fingerprint mismatch for ${aid}: expected=${expectedFP.slice(0, 24)}...`);
+                    }
+                }
+                // 完整 PKI 验证：链 + CRL + OCSP + AID 绑定
+                try {
+                    if (signedAt === undefined)
+                        await this._auth.verifyPeerCertificate(peerGatewayUrl, certPem, aid);
+                    else if (agentMdRead)
+                        await this._auth.verifyPeerCertificate(peerGatewayUrl, certPem, aid, signedAt, false, true);
+                    else
+                        await this._auth.verifyPeerCertificate(peerGatewayUrl, certPem, aid, signedAt);
+                }
+                catch (exc) {
+                    throw new ValidationError(`peer cert verification failed for ${aid}: ${exc}`);
+                }
+                this._certCache.set(cacheKey, {
+                    certPem,
+                    validatedAt: now,
+                    refreshAfter: now + PEER_CERT_CACHE_TTL,
+                });
+                try {
+                    // peer 证书只存版本目录，不覆盖 cert.pem
+                    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);
+                }
+                this._clientLog.debug(`_fetchPeerCert exit: elapsed=${Date.now() - tStart}ms aid=${aid} source=fetched`);
+                return certPem;
+            })();
+            this._certFetchInFlight.set(inFlightKey, request);
             try {
-                // peer 证书只存版本目录，不覆盖 cert.pem
-                await this._tokenStore.saveCert(aid, certPem, certFingerprint, { makeActive: false });
+                return await request;
             }
-            catch (exc) {
-                this._clientLog.error(`write cert to keystore failed (aid=${aid}): ${String(exc)}`, exc instanceof Error ? exc : undefined);
+            finally {
+                this._certFetchInFlight.delete(inFlightKey);
             }
-            this._clientLog.debug(`_fetchPeerCert exit: elapsed=${Date.now() - tStart}ms aid=${aid} source=fetched`);
-            return certPem;
         }
         catch (err) {
             this._clientLog.debug(`_fetchPeerCert exit (error): elapsed=${Date.now() - tStart}ms aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
@@ -4169,6 +4454,7 @@ export class AUNClient {
     }
     // ── 内部：后台任务 ────────────────────────────────
     _startBackgroundTasks() {
+        this._startCredentialRenewal();
         this._startOwnershipRecovery();
         // WebSocket Ping/Pong 由 Gateway 与传输层处理；SDK 不发送 RPC 心跳。
         // 短连接生命周期短，不需要 token 刷新。
@@ -4198,6 +4484,7 @@ export class AUNClient {
         }
     }
     _stopBackgroundTasks() {
+        this._stopCredentialRenewal();
         this._ownershipRecoveryGeneration += 1;
         if (this._ownershipRecoveryTimer !== null) {
             clearTimeout(this._ownershipRecoveryTimer);
@@ -4951,7 +5238,7 @@ export class AUNClient {
      * undecryptable 事件、成功消费后触发 SPK 轮换。inline Push 在游标提交和
      * Head/正文绑定校验前调用本入口时必须显式关闭这些副作用。
      */
-    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;
@@ -4967,8 +5254,12 @@ export class AUNClient {
             return null;
         }
         const e2eeMeta = v2E2eeMeta(envelope);
-        if (observeAgentMd)
-            await this._observeAgentMdFromEnvelope(envelope);
+        if (observeAgentMd) {
+            if (deferredEffects)
+                deferredEffects.push(() => this._observeAgentMdFromEnvelope(envelope));
+            else
+                await this._observeAgentMdFromEnvelope(envelope);
+        }
         // 确定 spk_id 和 recipient_key_source
         let spkId = '';
         let recipientKeySource = '';
@@ -5053,7 +5344,10 @@ export class AUNClient {
                         source,
                     };
                     attachV2EnvelopeMetadata(event, e2eeMeta);
-                    this._dispatcher.enqueue(undecryptableEvent, event);
+                    if (deferredEffects)
+                        deferredEffects.push(() => this._dispatcher.enqueue(undecryptableEvent, event));
+                    else
+                        this._dispatcher.enqueue(undecryptableEvent, event);
                 }
                 catch { /* publish 异常不影响主流程 */ }
             }
@@ -5094,7 +5388,10 @@ export class AUNClient {
                         source,
                     };
                     attachV2EnvelopeMetadata(event, e2eeMeta);
-                    this._dispatcher.enqueue(undecryptableEvent, event);
+                    if (deferredEffects)
+                        deferredEffects.push(() => this._dispatcher.enqueue(undecryptableEvent, event));
+                    else
+                        this._dispatcher.enqueue(undecryptableEvent, event);
                 }
                 catch { /* publish 异常不影响主流程 */ }
             }
@@ -5126,7 +5423,10 @@ export class AUNClient {
                         source,
                     };
                     attachV2EnvelopeMetadata(event, e2eeMeta);
-                    this._dispatcher.enqueue(undecryptableEvent, event);
+                    if (deferredEffects)
+                        deferredEffects.push(() => this._dispatcher.enqueue(undecryptableEvent, event));
+                    else
+                        this._dispatcher.enqueue(undecryptableEvent, event);
                 }
                 catch { /* publish 异常不影响主流程 */ }
             }
@@ -5135,8 +5435,12 @@ export class AUNClient {
         if (plaintext == null)
             return null;
         // 消费触发 SPK 轮换（fire-and-forget，不阻塞消息处理）
-        if (rotateKeys)
-            this._scheduleV2KeyRotationForMessage(msg, envelope);
+        if (rotateKeys) {
+            if (deferredEffects)
+                deferredEffects.push(() => this._scheduleV2KeyRotationForMessage(msg, envelope));
+            else
+                this._scheduleV2KeyRotationForMessage(msg, envelope);
+        }
         const e2ee = v2E2eeMeta(envelope);
         let result = {
             message_id: String(msg.message_id ?? ''),