@agentunion/fastaun 0.2.16 → 0.2.18

package/dist/e2ee-group.js

@@ -7,6 +7,7 @@
 import * as crypto from 'node:crypto';
 import { E2EEError, E2EEGroupSecretMissingError, } from './errors.js';
 import { isJsonObject, } from './types.js';
+const _noopLogger = { error: () => { }, warn: () => { }, info: () => { }, debug: () => { } };
 // ── 辅助：证书 SHA-256 指纹 ──────────────────────────────────────
 /** PEM 证书 → sha256:{hex} 指纹（与 Python/Go/JS SDK 一致） */
 function certSha256Fingerprint(certPem) {
@@ -459,17 +460,26 @@ export function encryptGroupMessage(groupId, epoch, groupSecret, payload, opts)
  */
 export function decryptGroupMessage(message, groupSecrets, senderCertPem, opts) {
     const requireSignature = opts?.requireSignature ?? true;
+    const logger = opts?.logger;
     const payload = isJsonObject(message.payload) ? message.payload : null;
-    if (payload === null)
+    if (payload === null) {
+        logger?.warn(`decryptGroupMessage rejected: payload is not an object mid=${String(message.message_id ?? '')}`);
         return null;
-    if (payload.type !== 'e2ee.group_encrypted')
+    }
+    if (payload.type !== 'e2ee.group_encrypted') {
+        logger?.warn(`decryptGroupMessage rejected: unexpected payload.type=${String(payload.type)} mid=${String(message.message_id ?? '')}`);
         return null;
+    }
     const epoch = payload.epoch;
-    if (epoch == null)
+    if (epoch == null) {
+        logger?.warn(`decryptGroupMessage rejected: missing epoch mid=${String(message.message_id ?? '')}`);
         return null;
+    }
     const groupSecret = groupSecrets.get(epoch);
-    if (!groupSecret)
+    if (!groupSecret) {
+        logger?.warn(`decryptGroupMessage rejected: no group secret for epoch=${epoch} mid=${String(message.message_id ?? '')}`);
         return null;
+    }
     try {
         // 优先从 AAD 读取 group_id 和 message_id
         const aad = isJsonObject(payload.aad) ? payload.aad : undefined;
@@ -482,34 +492,44 @@ export function decryptGroupMessage(message, groupSecrets, senderCertPem, opts)
             messageId = aad.message_id || message.message_id || '';
             aadFrom = aad.from || '';
             // 外层路由字段与 AAD 绑定校验
-            if (outerGroupId && groupId !== outerGroupId)
+            if (outerGroupId && groupId !== outerGroupId) {
+                logger?.warn(`decryptGroupMessage rejected: outer group_id does not match aad.group_id outer=${outerGroupId} aad=${groupId}`);
                 return null;
+            }
             if (aadFrom) {
                 const outerFrom = message.from || '';
                 const outerSender = message.sender_aid || '';
-                if (outerFrom && outerFrom !== aadFrom)
+                if (outerFrom && outerFrom !== aadFrom) {
+                    logger?.warn(`decryptGroupMessage rejected: outer from does not match aad.from outer=${outerFrom} aad=${aadFrom}`);
                     return null;
-                if (outerSender && outerSender !== aadFrom)
+                }
+                if (outerSender && outerSender !== aadFrom) {
+                    logger?.warn(`decryptGroupMessage rejected: outer sender_aid does not match aad.from outer=${outerSender} aad=${aadFrom}`);
                     return null;
+                }
             }
         }
         else {
             groupId = outerGroupId;
             messageId = message.message_id || '';
         }
-        if (!groupId || !messageId)
+        if (!groupId || !messageId) {
+            logger?.warn(`decryptGroupMessage rejected: missing group_id or message_id group=${groupId} mid=${messageId}`);
             return null;
+        }
         const msgKey = deriveGroupMsgKey(groupSecret, groupId, messageId);
         const nonce = Buffer.from(payload.nonce, 'base64');
         const ciphertext = Buffer.from(payload.ciphertext, 'base64');
         const tag = Buffer.from(payload.tag, 'base64');
         if (!verifyEnvelopeMetadataAuth(payload, msgKey)) {
+            logger?.warn(`decryptGroupMessage rejected: envelope metadata auth failed group=${groupId} mid=${messageId}`);
             return null;
         }
         const aadBytes = aad ? aadBytesGroup(aad) : Buffer.alloc(0);
         const plaintext = aesGcmDecrypt(msgKey, ciphertext, tag, nonce, aadBytes);
         const decoded = JSON.parse(plaintext.toString('utf-8'));
         if (!validateDecryptedEnvelopeMetadata(decoded, payload, message)) {
+            logger?.warn(`decryptGroupMessage rejected: decrypted envelope metadata validation failed group=${groupId} mid=${messageId}`);
             return null;
         }
         const e2ee = {
@@ -533,43 +553,56 @@ export function decryptGroupMessage(message, groupSecrets, senderCertPem, opts)
         // 发送方签名验证
         const senderSigB64 = payload.sender_signature;
         if (requireSignature) {
-            if (!senderSigB64)
+            if (!senderSigB64) {
+                logger?.warn(`decryptGroupMessage rejected: sender signature required but missing group=${groupId} mid=${messageId}`);
                 return null;
-            if (!senderCertPem)
+            }
+            if (!senderCertPem) {
+                logger?.warn(`decryptGroupMessage rejected: sender signature required but senderCertPem missing group=${groupId} mid=${messageId}`);
                 return null;
+            }
             try {
                 const senderPub = pemToCertPublicKey(senderCertPem);
                 const sigBytes = Buffer.from(senderSigB64, 'base64');
                 const verifyPayload = Buffer.concat([ciphertext, tag, aadBytes]);
-                if (!ecdsaVerify(senderPub, sigBytes, verifyPayload))
+                if (!ecdsaVerify(senderPub, sigBytes, verifyPayload)) {
+                    logger?.warn(`decryptGroupMessage rejected: sender signature verification failed group=${groupId} mid=${messageId}`);
                     return null;
+                }
                 if (isJsonObject(result.e2ee))
                     result.e2ee.sender_verified = true;
             }
-            catch {
+            catch (exc) {
+                logger?.warn(`decryptGroupMessage rejected: sender signature verification threw group=${groupId} mid=${messageId} err=${String(exc)}`);
                 return null;
             }
         }
         else if (senderCertPem) {
             // 非零信任模式但提供了证书：有证书时强制验签
-            if (!senderSigB64)
+            if (!senderSigB64) {
+                logger?.warn(`decryptGroupMessage rejected: senderCertPem present but signature missing group=${groupId} mid=${messageId}`);
                 return null;
+            }
             try {
                 const senderPub = pemToCertPublicKey(senderCertPem);
                 const sigBytes = Buffer.from(senderSigB64, 'base64');
                 const verifyPayload = Buffer.concat([ciphertext, tag, aadBytes]);
-                if (!ecdsaVerify(senderPub, sigBytes, verifyPayload))
+                if (!ecdsaVerify(senderPub, sigBytes, verifyPayload)) {
+                    logger?.warn(`decryptGroupMessage rejected: optional sender signature verification failed group=${groupId} mid=${messageId}`);
                     return null;
+                }
                 if (isJsonObject(result.e2ee))
                     result.e2ee.sender_verified = true;
             }
-            catch {
+            catch (exc) {
+                logger?.warn(`decryptGroupMessage rejected: optional sender signature verification threw group=${groupId} mid=${messageId} err=${String(exc)}`);
                 return null;
             }
         }
         return result;
     }
-    catch {
+    catch (exc) {
+        logger?.warn(`decryptGroupMessage rejected: decrypt threw mid=${String(message.message_id ?? '')} err=${String(exc)}`);
         return null;
     }
 }
@@ -747,12 +780,12 @@ export function loadGroupSecret(keystore, aid, groupId, epoch) {
     }
     return loaded;
 }
-function assessIncomingEpochChain(keystore, aid, groupId, epoch, commitment, incomingChain, rotationId, rotatorAid, source) {
+function assessIncomingEpochChain(keystore, aid, groupId, epoch, commitment, incomingChain, rotationId, rotatorAid, source, logger = _noopLogger) {
     const chain = (incomingChain ?? '').trim();
     const rid = rotationId.trim();
     const rotator = rotatorAid.trim();
     if (rid && !chain) {
-        console.warn(`[e2ee-group] 拒绝缺少 epoch_chain 的新 rotation key source=${source} group=${groupId} epoch=${epoch} rotation=${rid}`);
+        logger.warn(`[e2ee-group] rejecting rotation key missing epoch_chain source=${source} group=${groupId} epoch=${epoch} rotation=${rid}`);
         return { ok: false };
     }
     const current = loadGroupSecret(keystore, aid, groupId);
@@ -763,7 +796,7 @@ function assessIncomingEpochChain(keystore, aid, groupId, epoch, commitment, inc
             return { ok: true };
         if (rid && chain && currentChain && currentChain !== chain) {
             if (!(currentPendingRotationId && currentPendingRotationId !== rid)) {
-                console.warn(`[e2ee-group] 拒绝同 epoch 分叉 chain source=${source} group=${groupId} epoch=${epoch} rotation=${rid}`);
+                logger.warn(`[e2ee-group] rejecting same-epoch chain fork source=${source} group=${groupId} epoch=${epoch} rotation=${rid}`);
                 return { ok: false };
             }
         }
@@ -776,17 +809,17 @@ function assessIncomingEpochChain(keystore, aid, groupId, epoch, commitment, inc
         return { ok: true, unverified: true, reason: 'missing_prev_chain' };
     if (!rotator) {
         if (rid) {
-            console.warn(`[e2ee-group] 拒绝缺少 rotator_aid 的新 rotation key source=${source} group=${groupId} epoch=${epoch} rotation=${rid}`);
+            logger.warn(`[e2ee-group] rejecting rotation key missing rotator_aid source=${source} group=${groupId} epoch=${epoch} rotation=${rid}`);
             return { ok: false };
         }
         return { ok: true, unverified: true, reason: 'missing_rotator_aid' };
     }
     if (!verifyEpochChain(chain, prevChain, epoch, commitment, rotator)) {
         if (rid) {
-            console.warn(`[e2ee-group] 拒绝 epoch_chain 验证失败的新 rotation key source=${source} group=${groupId} epoch=${epoch} rotation=${rid}`);
+            logger.warn(`[e2ee-group] rejecting rotation key with failed epoch_chain verification source=${source} group=${groupId} epoch=${epoch} rotation=${rid}`);
             return { ok: false };
         }
-        console.warn(`[e2ee-group] epoch_chain 验证失败，按兼容档接收并标记未验证 source=${source} group=${groupId} epoch=${epoch}`);
+        logger.warn(`[e2ee-group] epoch_chain verification failed, accepting as unverified for compatibility source=${source} group=${groupId} epoch=${epoch}`);
         return { ok: true, unverified: true, reason: 'chain_mismatch_legacy' };
     }
     if (!rid)
@@ -914,7 +947,7 @@ export function buildKeyDistribution(groupId, epoch, groupSecret, memberAids, di
     return result;
 }
 /** 处理收到的 group key 分发消息 */
-export function handleKeyDistribution(message, keystore, aid, initiatorCertPem) {
+export function handleKeyDistribution(message, keystore, aid, initiatorCertPem, logger) {
     const payload = 'group_id' in message
         ? message
         : (isJsonObject(message.payload) ? message.payload : message);
@@ -923,40 +956,58 @@ export function handleKeyDistribution(message, keystore, aid, initiatorCertPem)
     const groupSecretB64 = payload.group_secret;
     const commitment = payload.commitment;
     const memberAids = payload.member_aids ?? [];
-    if (!groupId || epoch == null || !groupSecretB64 || !commitment)
+    logger?.debug(`handleKeyDistribution enter: group=${String(groupId ?? '')}, epoch=${String(epoch ?? '')}, aid=${aid}, members=${memberAids.length}`);
+    if (!groupId || epoch == null || !groupSecretB64 || !commitment) {
+        logger?.warn(`handleKeyDistribution rejected: missing required fields group=${String(groupId ?? '')} epoch=${String(epoch ?? '')} has_secret=${!!groupSecretB64} has_commitment=${!!commitment}`);
         return false;
+    }
     // 验证 Membership Manifest 签名
     const manifest = isJsonObject(payload.manifest) ? payload.manifest : undefined;
     if (initiatorCertPem) {
-        if (!manifest)
+        if (!manifest) {
+            logger?.warn(`handleKeyDistribution rejected: manifest required when initiatorCertPem present group=${groupId} epoch=${epoch}`);
             return false;
-        if (!verifyMembershipManifest(manifest, initiatorCertPem))
+        }
+        if (!verifyMembershipManifest(manifest, initiatorCertPem)) {
+            logger?.warn(`handleKeyDistribution rejected: manifest signature verification failed group=${groupId} epoch=${epoch}`);
             return false;
-        if (manifest.group_id !== groupId || manifest.epoch !== epoch)
+        }
+        if (manifest.group_id !== groupId || manifest.epoch !== epoch) {
+            logger?.warn(`handleKeyDistribution rejected: manifest group_id/epoch mismatch group=${groupId} epoch=${epoch} manifest_group=${String(manifest.group_id)} manifest_epoch=${String(manifest.epoch)}`);
             return false;
+        }
         const manifestMembers = [...(manifest.member_aids ?? [])].sort();
         const payloadMembers = [...memberAids].sort();
-        if (JSON.stringify(manifestMembers) !== JSON.stringify(payloadMembers))
+        if (JSON.stringify(manifestMembers) !== JSON.stringify(payloadMembers)) {
+            logger?.warn(`handleKeyDistribution rejected: manifest members mismatch payload members group=${groupId} epoch=${epoch}`);
             return false;
+        }
     }
     else if (manifest) {
-        if (manifest.group_id !== groupId || manifest.epoch !== epoch)
+        if (manifest.group_id !== groupId || manifest.epoch !== epoch) {
+            logger?.warn(`handleKeyDistribution rejected: manifest group_id/epoch mismatch (no cert) group=${groupId} epoch=${epoch}`);
             return false;
+        }
         const manifestMembers = [...(manifest.member_aids ?? [])].sort();
         const payloadMembers = [...memberAids].sort();
-        if (JSON.stringify(manifestMembers) !== JSON.stringify(payloadMembers))
+        if (JSON.stringify(manifestMembers) !== JSON.stringify(payloadMembers)) {
+            logger?.warn(`handleKeyDistribution rejected: manifest members mismatch payload members (no cert) group=${groupId} epoch=${epoch}`);
             return false;
+        }
     }
     const groupSecret = Buffer.from(groupSecretB64, 'base64');
     // 验证 commitment
     if (!verifyMembershipCommitment(commitment, memberAids, epoch, groupId, aid, groupSecret)) {
+        logger?.warn(`handleKeyDistribution rejected: commitment verification failed group=${groupId} epoch=${epoch}`);
         return false;
     }
     const incomingChain = typeof payload.epoch_chain === 'string' ? payload.epoch_chain : undefined;
     const rotationId = typeof payload.rotation_id === 'string' ? payload.rotation_id : '';
-    const chainAssessment = assessIncomingEpochChain(keystore, aid, groupId, epoch, commitment, incomingChain, rotationId, String(payload.distributed_by ?? payload.rotator_aid ?? ''), 'key_distribution');
-    if (!chainAssessment.ok)
+    const chainAssessment = assessIncomingEpochChain(keystore, aid, groupId, epoch, commitment, incomingChain, rotationId, String(payload.distributed_by ?? payload.rotator_aid ?? ''), 'key_distribution', logger);
+    if (!chainAssessment.ok) {
+        logger?.warn(`handleKeyDistribution rejected: epoch chain assessment failed group=${groupId} epoch=${epoch} reason=${chainAssessment.reason ?? ''}`);
         return false;
+    }
     return storeGroupSecret(keystore, aid, groupId, epoch, groupSecret, commitment, memberAids, incomingChain, rotationId, chainAssessment.unverified, chainAssessment.reason);
 }
 /** 构建密钥请求 payload */
@@ -971,26 +1022,34 @@ export function buildKeyRequest(groupId, epoch, requesterAid, requestId) {
     };
 }
 /** 处理收到的密钥请求 */
-export function handleKeyRequest(request, keystore, aid, currentMembers, privateKeyPem) {
+export function handleKeyRequest(request, keystore, aid, currentMembers, privateKeyPem, logger) {
     const payload = 'group_id' in request
         ? request
         : (isJsonObject(request.payload) ? request.payload : request);
     const requesterAid = payload.requester_aid;
     const groupId = payload.group_id;
     const epoch = payload.epoch;
-    if (!requesterAid || !groupId || epoch == null)
+    logger?.debug(`handleKeyRequest enter: group=${String(groupId ?? '')}, epoch=${String(epoch ?? '')}, requester=${String(requesterAid ?? '')}, aid=${aid}`);
+    if (!requesterAid || !groupId || epoch == null) {
+        logger?.warn(`handleKeyRequest rejected: missing required fields requester=${String(requesterAid ?? '')} group=${String(groupId ?? '')} epoch=${String(epoch ?? '')}`);
         return null;
+    }
     // 验证请求者是群成员
-    if (!currentMembers.includes(requesterAid))
+    if (!currentMembers.includes(requesterAid)) {
+        logger?.warn(`handleKeyRequest rejected: requester not in current members group=${groupId} requester=${requesterAid}`);
         return null;
+    }
     // 查本地密钥
     const secretData = loadGroupSecret(keystore, aid, groupId, epoch);
-    if (!secretData)
+    if (!secretData) {
+        logger?.warn(`handleKeyRequest rejected: no local secret for epoch group=${groupId} epoch=${epoch}`);
         return null;
+    }
     // 历史隔离：密钥存储中记录了该 epoch 的成员列表，
     // 若请求者不在该列表中，说明其不属于该 epoch，直接拒绝（不响应）。
     const memberAids = (secretData.member_aids ?? []).map(String).filter(Boolean).sort();
     if (memberAids.length > 0 && !memberAids.includes(requesterAid)) {
+        logger?.warn(`handleKeyRequest rejected: requester not in epoch member list group=${groupId} epoch=${epoch} requester=${requesterAid}`);
         return null;
     }
     // 确定响应使用的成员列表：优先使用密钥存储中的成员列表，
@@ -1029,55 +1088,84 @@ export function handleKeyResponse(response, keystore, aid, opts) {
     const groupSecretB64 = payload.group_secret;
     const commitment = payload.commitment;
     const memberAids = payload.member_aids ?? [];
-    if (!groupId || epoch == null || !groupSecretB64 || !commitment)
+    const logger = opts?.logger;
+    logger?.debug(`handleKeyResponse enter: group=${String(groupId ?? '')}, epoch=${String(epoch ?? '')}, responder=${String(payload.responder_aid ?? '')}, aid=${aid}, strict=${!!opts?.strict}`);
+    if (!groupId || epoch == null || !groupSecretB64 || !commitment) {
+        logger?.warn(`handleKeyResponse rejected: missing required fields group=${String(groupId ?? '')} epoch=${String(epoch ?? '')} has_secret=${!!groupSecretB64} has_commitment=${!!commitment}`);
         return false;
+    }
     const expected = opts?.expectedRequest ?? null;
     if (expected) {
-        if (payload.requester_aid !== aid)
+        if (payload.requester_aid !== aid) {
+            logger?.warn(`handleKeyResponse rejected: requester_aid mismatch group=${groupId} epoch=${epoch} got=${String(payload.requester_aid)} expected=${aid}`);
             return false;
+        }
         const expectedResponder = String(expected._expected_responder_aid ?? '');
-        if (expectedResponder && payload.responder_aid !== expectedResponder)
+        if (expectedResponder && payload.responder_aid !== expectedResponder) {
+            logger?.warn(`handleKeyResponse rejected: responder_aid mismatch group=${groupId} epoch=${epoch} got=${String(payload.responder_aid)} expected=${expectedResponder}`);
             return false;
-        if (payload.request_id !== expected.request_id)
+        }
+        if (payload.request_id !== expected.request_id) {
+            logger?.warn(`handleKeyResponse rejected: request_id mismatch group=${groupId} epoch=${epoch}`);
             return false;
-        if (payload.group_id !== expected.group_id)
+        }
+        if (payload.group_id !== expected.group_id) {
+            logger?.warn(`handleKeyResponse rejected: group_id mismatch with expected request`);
             return false;
-        if (Number(payload.epoch ?? 0) !== Number(expected.epoch ?? 0))
+        }
+        if (Number(payload.epoch ?? 0) !== Number(expected.epoch ?? 0)) {
+            logger?.warn(`handleKeyResponse rejected: epoch mismatch with expected request group=${groupId}`);
             return false;
+        }
     }
     const responderAid = String(payload.responder_aid ?? '');
     if (opts?.strict) {
-        if (!responderAid || !opts.responderCertPem)
+        if (!responderAid || !opts.responderCertPem) {
+            logger?.warn(`handleKeyResponse rejected (strict): missing responder aid or cert group=${groupId} epoch=${epoch}`);
             return false;
-        if ((opts.currentMembers?.length ?? 0) > 0 && !opts.currentMembers.includes(responderAid))
+        }
+        if ((opts.currentMembers?.length ?? 0) > 0 && !opts.currentMembers.includes(responderAid)) {
+            logger?.warn(`handleKeyResponse rejected (strict): responder not in current members group=${groupId} epoch=${epoch} responder=${responderAid}`);
             return false;
-        if (!verifyGroupKeyResponseSignature(payload, opts.responderCertPem))
+        }
+        if (!verifyGroupKeyResponseSignature(payload, opts.responderCertPem)) {
+            logger?.warn(`handleKeyResponse rejected (strict): response signature verification failed group=${groupId} epoch=${epoch} responder=${responderAid}`);
             return false;
+        }
     }
     else if (opts?.responderCertPem && payload.response_signature) {
-        if (!verifyGroupKeyResponseSignature(payload, opts.responderCertPem))
+        if (!verifyGroupKeyResponseSignature(payload, opts.responderCertPem)) {
+            logger?.warn(`handleKeyResponse rejected: response signature verification failed group=${groupId} epoch=${epoch} responder=${responderAid}`);
             return false;
+        }
     }
     const groupSecret = Buffer.from(groupSecretB64, 'base64');
     if (!verifyMembershipCommitment(commitment, memberAids, epoch, groupId, aid, groupSecret)) {
+        logger?.warn(`handleKeyResponse rejected: commitment verification failed group=${groupId} epoch=${epoch}`);
         return false;
     }
     const manifest = isJsonObject(payload.manifest) ? payload.manifest : null;
     if (manifest) {
-        if (manifest.group_id !== groupId || manifest.epoch !== epoch)
+        if (manifest.group_id !== groupId || manifest.epoch !== epoch) {
+            logger?.warn(`handleKeyResponse rejected: manifest group_id/epoch mismatch group=${groupId} epoch=${epoch}`);
             return false;
+        }
         const manifestMembers = Array.isArray(manifest.member_aids)
             ? manifest.member_aids.map((item) => String(item ?? '').trim()).filter(Boolean).sort()
             : [];
         const payloadMembers = memberAids.map((item) => String(item ?? '').trim()).filter(Boolean).sort();
-        if (manifestMembers.length > 0 && manifestMembers.join('\n') !== payloadMembers.join('\n'))
+        if (manifestMembers.length > 0 && manifestMembers.join('\n') !== payloadMembers.join('\n')) {
+            logger?.warn(`handleKeyResponse rejected: manifest members mismatch payload members group=${groupId} epoch=${epoch}`);
             return false;
+        }
     }
     const incomingChain = typeof payload.epoch_chain === 'string' ? payload.epoch_chain : undefined;
     const rotationId = typeof payload.rotation_id === 'string' ? payload.rotation_id : '';
-    const chainAssessment = assessIncomingEpochChain(keystore, aid, groupId, epoch, commitment, incomingChain, rotationId, String(payload.distributed_by ?? payload.rotator_aid ?? payload.responder_aid ?? ''), 'key_response');
-    if (!chainAssessment.ok)
+    const chainAssessment = assessIncomingEpochChain(keystore, aid, groupId, epoch, commitment, incomingChain, rotationId, String(payload.distributed_by ?? payload.rotator_aid ?? payload.responder_aid ?? ''), 'key_response', opts?.logger);
+    if (!chainAssessment.ok) {
+        logger?.warn(`handleKeyResponse rejected: epoch chain assessment failed group=${groupId} epoch=${epoch} reason=${chainAssessment.reason ?? ''}`);
         return false;
+    }
     return storeGroupSecretEpoch(keystore, aid, groupId, epoch, groupSecret, commitment, memberAids, incomingChain, rotationId, chainAssessment.unverified, chainAssessment.reason);
 }
 // ── GroupE2EEManager 类 ───────────────────────────────────────
@@ -1090,6 +1178,7 @@ export class GroupE2EEManager {
     _senderCertResolver;
     _initiatorCertResolver;
     _pendingKeyRequests = new Map();
+    _logger;
     constructor(opts) {
         this._identityFn = opts.identityFn;
         this._keystore = opts.keystore;
@@ -1098,6 +1187,7 @@ export class GroupE2EEManager {
         this._responseThrottle = new GroupKeyRequestThrottle(opts.responseCooldown ?? 30);
         this._senderCertResolver = opts.senderCertResolver ?? null;
         this._initiatorCertResolver = opts.initiatorCertResolver ?? null;
+        this._logger = opts.logger ?? _noopLogger;
     }
     // ── 密钥管理 ──────────────────────────────────────────
     /** 用当前身份私钥签名 manifest */
@@ -1111,6 +1201,7 @@ export class GroupE2EEManager {
     /** 创建首个 epoch。返回 {epoch, commitment, distributions: [{to, payload}]} */
     createEpoch(groupId, memberAids) {
         const aid = this._currentAid();
+        this._logger.debug(`create first epoch: groupId=${groupId}, members=${memberAids.length}, aid=${aid}`);
         const gs = generateGroupSecret();
         const epoch = 1;
         const commitment = computeMembershipCommitment(memberAids, epoch, groupId, gs);
@@ -1118,6 +1209,7 @@ export class GroupE2EEManager {
         storeGroupSecret(this._keystore, aid, groupId, epoch, gs, commitment, memberAids, epochChain);
         const manifest = this._signManifest(buildMembershipManifest(groupId, epoch, null, memberAids, { initiatorAid: aid }));
         const distPayload = buildKeyDistribution(groupId, epoch, gs, memberAids, aid, manifest, epochChain);
+        this._logger.debug(`create first epoch success: groupId=${groupId}, epoch=${epoch}`);
         return {
             epoch,
             commitment,
@@ -1132,16 +1224,19 @@ export class GroupE2EEManager {
         const current = loadGroupSecret(this._keystore, aid, groupId);
         const prevEpoch = current ? Number(current.epoch) : null;
         const newEpoch = (prevEpoch ?? 0) + 1;
+        this._logger.debug(`rotateEpoch start: groupId=${groupId}, prevEpoch=${prevEpoch}, newEpoch=${newEpoch}, members=${memberAids.length}`);
         const gs = generateGroupSecret();
         const commitment = computeMembershipCommitment(memberAids, newEpoch, groupId, gs);
         const prevChain = current?.epoch_chain ?? null;
         const epochChain = computeEpochChain(prevChain, newEpoch, commitment, aid);
         const stored = storeGroupSecret(this._keystore, aid, groupId, newEpoch, gs, commitment, memberAids, epochChain);
         if (!stored) {
+            this._logger.warn(`rotateEpoch failed (epoch already exists or newer): groupId=${groupId}, newEpoch=${newEpoch}`);
             throw new Error(`group ${groupId} epoch ${newEpoch} secret already exists or is newer; abort distribution`);
         }
         const manifest = this._signManifest(buildMembershipManifest(groupId, newEpoch, prevEpoch, memberAids, { initiatorAid: aid }));
         const distPayload = buildKeyDistribution(groupId, newEpoch, gs, memberAids, aid, manifest, epochChain);
+        this._logger.debug(`rotateEpoch success: groupId=${groupId}, newEpoch=${newEpoch}`);
         return {
             epoch: newEpoch,
             commitment,
@@ -1153,6 +1248,7 @@ export class GroupE2EEManager {
     /** 指定目标 epoch 号轮换（配合服务端 CAS 使用） */
     rotateEpochTo(groupId, newEpoch, memberAids, opts) {
         const aid = this._currentAid();
+        this._logger.debug(`rotateEpochTo start: groupId=${groupId}, newEpoch=${newEpoch}, members=${memberAids.length}`);
         const current = loadGroupSecret(this._keystore, aid, groupId, newEpoch - 1)
             ?? loadGroupSecret(this._keystore, aid, groupId);
         const gs = generateGroupSecret();
@@ -1165,6 +1261,7 @@ export class GroupE2EEManager {
         const rotationId = opts?.rotationId ?? '';
         const stored = storeGroupSecret(this._keystore, aid, groupId, newEpoch, gs, commitment, memberAids, epochChain, rotationId);
         if (!stored) {
+            this._logger.warn(`rotateEpochTo failed (epoch already exists or newer): groupId=${groupId}, newEpoch=${newEpoch}`);
             throw new Error(`group ${groupId} epoch ${newEpoch} secret already exists or is newer; abort distribution`);
         }
         const manifest = this._signManifest(buildMembershipManifest(groupId, newEpoch, newEpoch - 1, memberAids, { initiatorAid: aid }));
@@ -1172,6 +1269,7 @@ export class GroupE2EEManager {
         if (rotationId) {
             distPayload.rotation_id = rotationId;
         }
+        this._logger.debug(`rotateEpochTo success: groupId=${groupId}, newEpoch=${newEpoch}, rotationId=${rotationId}`);
         return {
             epoch: newEpoch,
             commitment,
@@ -1186,8 +1284,10 @@ export class GroupE2EEManager {
     /** 加密群消息（含发送方签名）。无密钥时抛 E2EEGroupSecretMissingError。 */
     encrypt(groupId, payload, opts) {
         const aid = this._currentAid();
+        this._logger.debug(`group message encrypt start: groupId=${groupId}, aid=${aid}`);
         const secretData = loadGroupSecret(this._keystore, aid, groupId);
         if (!secretData) {
+            this._logger.error(`group message encrypt failed: missing group secret, groupId=${groupId}`);
             throw new E2EEGroupSecretMissingError(`no group secret for ${groupId}`);
         }
         const identity = this._identityFn();
@@ -1197,7 +1297,7 @@ export class GroupE2EEManager {
             throw new E2EEError('sender identity private key unavailable for group message signing');
         }
         const senderCertPem = identity ? identity.cert ?? null : null;
-        return encryptGroupMessage(groupId, secretData.epoch, secretData.secret, payload, {
+        const result = encryptGroupMessage(groupId, secretData.epoch, secretData.secret, payload, {
             fromAid: aid,
             messageId: opts?.messageId ?? `gm-${crypto.randomUUID()}`,
             timestamp: opts?.timestamp ?? Date.now(),
@@ -1206,6 +1306,8 @@ export class GroupE2EEManager {
             protectedHeaders: opts?.protectedHeaders ?? opts?.protected_headers ?? opts?.headers,
             context: opts?.context ?? null,
         });
+        this._logger.debug(`group message encrypt success: groupId=${groupId}, epoch=${secretData.epoch}`);
+        return result;
     }
     /** 使用指定 epoch 加密群消息。 */
     encryptWithEpoch(groupId, epoch, payload, opts) {
@@ -1238,12 +1340,14 @@ export class GroupE2EEManager {
         }
         const groupId = message.group_id || '';
         const sender = message.from || message.sender_aid || '';
+        this._logger.debug(`group message decrypt start: groupId=${groupId}, from=${sender}`);
         // 防重放预检：优先使用 AAD 内 message_id
         const aad = isJsonObject(payload.aad) ? payload.aad : undefined;
         const aadMsgId = aad ? (aad.message_id ?? '') : '';
         const msgId = aadMsgId || message.message_id || '';
         if (!opts?.skipReplay && groupId && sender && msgId) {
             if (this._replayGuard.isSeen(groupId, sender, msgId)) {
+                this._logger.debug(`group message replay blocked: groupId=${groupId}, from=${sender}, mid=${msgId}`);
                 // 返回原消息（不含 e2ee 字段），调用方可通过缺失 e2ee 识别 replay
                 return message;
             }
@@ -1253,18 +1357,26 @@ export class GroupE2EEManager {
         if (this._senderCertResolver && sender) {
             senderCertPem = this._senderCertResolver(sender);
         }
-        if (!senderCertPem)
+        if (!senderCertPem) {
+            this._logger.warn(`group message decrypt rejected: sender cert unavailable, groupId=${groupId}, from=${sender}`);
             return null;
+        }
         const allSecrets = loadAllGroupSecrets(this._keystore, this._currentAid(), groupId);
-        if (allSecrets.size === 0)
+        if (allSecrets.size === 0) {
+            this._logger.warn(`group message decrypt failed: no group secret, groupId=${groupId}`);
             return null;
-        const result = decryptGroupMessage(message, allSecrets, senderCertPem);
+        }
+        const result = decryptGroupMessage(message, allSecrets, senderCertPem, { logger: this._logger });
         // 解密成功后记录防重放
         if (result != null) {
             const finalMsgId = aadMsgId || message.message_id || '';
             if (!opts?.skipReplay && groupId && sender && finalMsgId) {
                 this._replayGuard.record(groupId, sender, finalMsgId);
             }
+            this._logger.debug(`group message decrypt success: groupId=${groupId}, from=${sender}, mid=${msgId}`);
+        }
+        else {
+            this._logger.warn(`group message decrypt failed: groupId=${groupId}, from=${sender}, mid=${msgId}`);
         }
         return result;
     }
@@ -1283,19 +1395,33 @@ export class GroupE2EEManager {
         const msgType = payload.type || '';
         const aid = this._currentAid();
         if (msgType === 'e2ee.group_key_distribution') {
-            let initiatorCert = null;
+            const groupId = payload.group_id || '';
+            const epoch = payload.epoch;
             const distributedBy = payload.distributed_by || '';
+            this._logger.debug(`received key distribution: groupId=${groupId}, epoch=${epoch}, from=${distributedBy}`);
+            let initiatorCert = null;
             if (this._initiatorCertResolver && distributedBy) {
                 initiatorCert = this._initiatorCertResolver(distributedBy);
             }
-            const ok = handleKeyDistribution(payload, this._keystore, aid, initiatorCert);
+            const ok = handleKeyDistribution(payload, this._keystore, aid, initiatorCert, this._logger);
+            if (ok) {
+                this._logger.debug(`key distribution handled successfully: groupId=${groupId}, epoch=${epoch}`);
+            }
+            else {
+                this._logger.warn(`key distribution rejected: groupId=${groupId}, epoch=${epoch}, from=${distributedBy}`);
+            }
             return ok ? 'distribution' : 'distribution_rejected';
         }
         if (msgType === 'e2ee.group_key_response') {
+            const groupId = payload.group_id || '';
+            const epoch = payload.epoch;
+            this._logger.debug(`received key response: groupId=${groupId}, epoch=${epoch}`);
             const pendingKey = `${String(payload.group_id ?? '')}:${String(payload.epoch ?? '')}:${String(payload.request_id ?? '')}`;
             const expected = this._pendingKeyRequests.get(pendingKey) ?? null;
-            if (expected === null)
+            if (expected === null) {
+                this._logger.warn(`key response rejected (no matching request): groupId=${groupId}, epoch=${epoch}`);
                 return 'response_rejected';
+            }
             const responderAid = String(payload.responder_aid ?? '');
             const responderCertPem = responderAid && this._initiatorCertResolver
                 ? this._initiatorCertResolver(responderAid)
@@ -1305,12 +1431,22 @@ export class GroupE2EEManager {
                 responderCertPem,
                 currentMembers: this.getMemberAids(String(payload.group_id ?? '')),
                 strict: true,
+                logger: this._logger,
             });
             if (ok && expected)
                 this._pendingKeyRequests.delete(pendingKey);
+            if (ok) {
+                this._logger.debug(`key response handled successfully: groupId=${groupId}, epoch=${epoch}, responder=${responderAid}`);
+            }
+            else {
+                this._logger.warn(`key response verification failed: groupId=${groupId}, epoch=${epoch}, responder=${responderAid}`);
+            }
             return ok ? 'response' : 'response_rejected';
         }
         if (msgType === 'e2ee.group_key_request') {
+            const groupId = payload.group_id || '';
+            const requester = payload.requester_aid || '';
+            this._logger.debug(`received key request: groupId=${groupId}, requester=${requester}, epoch=${payload.epoch}`);
             return 'request';
         }
         return null;
@@ -1350,16 +1486,28 @@ export class GroupE2EEManager {
         if (!requester || !groupId)
             return null;
         // 成员资格验证
-        if (!members.includes(requester))
+        if (!members.includes(requester)) {
+            this._logger.warn(`key request rejected (not a member): groupId=${groupId}, requester=${requester}`);
             return null;
+        }
         if (!this._responseThrottle.allow(`response:${groupId}:${requester}`)) {
+            this._logger.debug(`key request throttled: groupId=${groupId}, requester=${requester}`);
             return null;
         }
         const identity = this._identityFn();
         const privateKeyPem = identity.private_key_pem;
-        if (!privateKeyPem)
+        if (!privateKeyPem) {
+            this._logger.error(`key request handling failed: missing private key, groupId=${groupId}`);
             return null;
-        return handleKeyRequest(requestPayload, this._keystore, this._currentAid(), members, privateKeyPem);
+        }
+        const response = handleKeyRequest(requestPayload, this._keystore, this._currentAid(), members, privateKeyPem, this._logger);
+        if (response) {
+            this._logger.debug(`key request responded: groupId=${groupId}, requester=${requester}, epoch=${requestPayload.epoch}`);
+        }
+        else {
+            this._logger.warn(`key request handling failed (no local key or requester not in epoch members): groupId=${groupId}, requester=${requester}`);
+        }
+        return response;
     }
     // ── 状态查询 ──────────────────────────────────────────
     /** 检查是否有群组密钥 */
@@ -1378,7 +1526,14 @@ export class GroupE2EEManager {
     }
     /** 加载群组密钥数据 */
     loadSecret(groupId, epoch) {
-        return loadGroupSecret(this._keystore, this._currentAid(), groupId, epoch);
+        const result = loadGroupSecret(this._keystore, this._currentAid(), groupId, epoch);
+        if (result) {
+            this._logger.debug(`load group secret success: groupId=${groupId}, epoch=${result.epoch}`);
+        }
+        else {
+            this._logger.debug(`load group secret not found: groupId=${groupId}, requestedEpoch=${epoch ?? 'latest'}`);
+        }
+        return result;
     }
     /** 清理过期的旧 epoch */
     cleanup(groupId, retentionSeconds = OLD_EPOCH_RETENTION_SECONDS) {