@agentunion/fastaun 0.2.15 → 0.2.17

package/dist/config.d.ts

@@ -36,6 +36,8 @@ export interface AUNConfig {
     requireForwardSecrecy: boolean;
     /** 防重放窗口（秒） */
     replayWindowSeconds: number;
+    /** 是否启用 debug 模式（DEBUG 级别输出 + 文件日志） */
+    debug: boolean;
 }
 /** 返回默认配置 */
 export declare function defaultConfig(): AUNConfig;

package/dist/config.js

@@ -93,6 +93,7 @@ export function defaultConfig() {
         verifySsl: resolveVerifySslFromEnv(),
         requireForwardSecrecy: true,
         replayWindowSeconds: 300,
+        debug: false,
     };
 }
 // ── 从字典构建配置 ───────────────────────────────────────────
@@ -114,6 +115,7 @@ export function configFromMap(raw) {
         verifySsl: readBoolean(raw.verify_ssl ?? raw.verifySSL ?? raw.verifySsl, def.verifySsl),
         requireForwardSecrecy: readBoolean(raw.require_forward_secrecy ?? raw.requireForwardSecrecy, def.requireForwardSecrecy),
         replayWindowSeconds: readOptionalNumber(raw.replay_window_seconds ?? raw.replayWindowSeconds, def.replayWindowSeconds) ?? def.replayWindowSeconds,
+        debug: readBoolean(raw.debug, def.debug),
     };
 }
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/e2ee-group.d.ts

@@ -7,6 +7,7 @@
 import type { KeyStore } from './keystore/index.js';
 import type { ProtectedHeadersInput } from './e2ee.js';
 import { type IdentityRecord, type JsonObject, type Message } from './types.js';
+import type { ModuleLogger } from './logger.js';
 export interface LoadedGroupSecret {
     epoch: number;
     secret: Buffer;
@@ -17,6 +18,20 @@ export interface LoadedGroupSecret {
     epoch_chain_unverified?: boolean;
     epoch_chain_unverified_reason?: string;
 }
+/**
+ * ECIES 加密：P-256 ECDH + HKDF-SHA256 + AES-256-GCM。
+ * @param peerPubkeyBytes 65 字节未压缩 P-256 公钥 (0x04 开头)
+ * @param plaintext 待加密明文
+ * @returns ephemeral_pubkey(65B) || iv(12B) || ciphertext || tag(16B)
+ */
+export declare function eciesEncrypt(peerPubkeyBytes: Buffer, plaintext: Buffer): Buffer;
+/**
+ * ECIES 解密：对应 eciesEncrypt。
+ * @param privateKeyPem 自己的 PEM 格式 EC 私钥
+ * @param ciphertext ephemeral_pubkey(65B) || iv(12B) || encrypted || tag(16B)
+ * @returns 解密后的明文
+ */
+export declare function eciesDecrypt(privateKeyPem: string, ciphertext: Buffer): Buffer;
 /**
  * 计算 Epoch Transcript Chain。
  * genesis（prev_chain=null）使用固定前缀；后续 epoch 使用上一个 chain 的字节。
@@ -62,6 +77,22 @@ export declare function computeMembershipCommitment(memberAids: string[], epoch:
  * 2. 检查 myAid 是否在 memberAids 中
  */
 export declare function verifyMembershipCommitment(commitment: string, memberAids: string[], epoch: number, groupId: string, myAid: string, groupSecret: Buffer): boolean;
+/**
+ * 计算群组状态哈希（链式）。
+ * state_hash = SHA-256(group_id | 0x00 | state_version(u64be) | 0x00 |
+ *   key_epoch(u64be) | 0x00 | membership_block | 0x00 | policy_block | 0x00 | prev_state_hash(32B))
+ */
+export declare function computeStateHash(params: {
+    groupId: string;
+    stateVersion: number;
+    keyEpoch: number;
+    members: Array<{
+        aid: string;
+        role: string;
+    }>;
+    policy: Record<string, unknown>;
+    prevStateHash: string;
+}): string;
 /** 构建 Membership Manifest（未签名） */
 export declare function buildMembershipManifest(groupId: string, epoch: number, prevEpoch: number | null, memberAids: string[], opts?: {
     added?: string[];
@@ -115,7 +146,7 @@ export declare function generateGroupSecret(): Buffer;
 /** 构建 group key 分发消息 payload */
 export declare function buildKeyDistribution(groupId: string, epoch: number, groupSecret: Buffer, memberAids: string[], distributedBy: string, manifest?: JsonObject | null, epochChain?: string): JsonObject;
 /** 处理收到的 group key 分发消息 */
-export declare function handleKeyDistribution(message: Message | JsonObject, keystore: KeyStore, aid: string, initiatorCertPem?: string | null): boolean;
+export declare function handleKeyDistribution(message: Message | JsonObject, keystore: KeyStore, aid: string, initiatorCertPem?: string | null, logger?: ModuleLogger): boolean;
 /** 构建密钥请求 payload */
 export declare function buildKeyRequest(groupId: string, epoch: number, requesterAid: string, requestId?: string): JsonObject;
 /** 处理收到的密钥请求 */
@@ -126,6 +157,7 @@ export declare function handleKeyResponse(response: Message | JsonObject, keysto
     responderCertPem?: string | null;
     currentMembers?: string[];
     strict?: boolean;
+    logger?: ModuleLogger;
 }): boolean;
 export declare class GroupE2EEManager {
     private _identityFn;
@@ -136,6 +168,7 @@ export declare class GroupE2EEManager {
     private _senderCertResolver;
     private _initiatorCertResolver;
     private _pendingKeyRequests;
+    private _logger;
     constructor(opts: {
         identityFn: () => IdentityRecord;
         keystore: KeyStore;
@@ -143,6 +176,7 @@ export declare class GroupE2EEManager {
         responseCooldown?: number;
         senderCertResolver?: (aid: string) => string | null;
         initiatorCertResolver?: (aid: string) => string | null;
+        logger?: ModuleLogger;
     });
     /** 用当前身份私钥签名 manifest */
     private _signManifest;
@@ -153,6 +187,7 @@ export declare class GroupE2EEManager {
     /** 指定目标 epoch 号轮换（配合服务端 CAS 使用） */
     rotateEpochTo(groupId: string, newEpoch: number, memberAids: string[], opts?: {
         rotationId?: string;
+        prevChainHint?: string | null;
     }): JsonObject;
     discardPendingSecret(groupId: string, epoch: number, rotationId: string): boolean;
     /** 加密群消息（含发送方签名）。无密钥时抛 E2EEGroupSecretMissingError。 */

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) {
@@ -38,6 +39,61 @@ const PROTECTED_HEADERS_DOMAIN = Buffer.from('aun-protected-headers-v1', 'utf-8'
 const PROTECTED_CONTEXT_DOMAIN = Buffer.from('aun-protected-context-v1', 'utf-8');
 /** 旧 epoch 默认保留 7 天 */
 const OLD_EPOCH_RETENTION_SECONDS = 7 * 24 * 3600;
+// ── ECIES (P-256 ECDH + HKDF-SHA256 + AES-256-GCM) ──────────
+const ECIES_HKDF_INFO = Buffer.from('aun-epoch-key-ecies', 'utf-8');
+/**
+ * ECIES 加密：P-256 ECDH + HKDF-SHA256 + AES-256-GCM。
+ * @param peerPubkeyBytes 65 字节未压缩 P-256 公钥 (0x04 开头)
+ * @param plaintext 待加密明文
+ * @returns ephemeral_pubkey(65B) || iv(12B) || ciphertext || tag(16B)
+ */
+export function eciesEncrypt(peerPubkeyBytes, plaintext) {
+    // 生成临时密钥对
+    const ephemeral = crypto.createECDH('prime256v1');
+    ephemeral.generateKeys();
+    const ephemeralPubBytes = ephemeral.getPublicKey(); // 65 字节未压缩
+    // ECDH 共享密钥
+    const shared = ephemeral.computeSecret(peerPubkeyBytes);
+    // HKDF 派生 32 字节 AES 密钥
+    const derived = crypto.hkdfSync('sha256', shared, Buffer.alloc(0), ECIES_HKDF_INFO, 32);
+    const aesKey = Buffer.from(derived);
+    // AES-256-GCM 加密
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', aesKey, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag(); // 16 字节
+    return Buffer.concat([ephemeralPubBytes, iv, encrypted, tag]);
+}
+/**
+ * ECIES 解密：对应 eciesEncrypt。
+ * @param privateKeyPem 自己的 PEM 格式 EC 私钥
+ * @param ciphertext ephemeral_pubkey(65B) || iv(12B) || encrypted || tag(16B)
+ * @returns 解密后的明文
+ */
+export function eciesDecrypt(privateKeyPem, ciphertext) {
+    if (ciphertext.length < 65 + 12 + 16) {
+        throw new E2EEError('ECIES ciphertext too short');
+    }
+    const ephemeralPubBytes = ciphertext.subarray(0, 65);
+    const iv = ciphertext.subarray(65, 77);
+    const encryptedWithTag = ciphertext.subarray(77);
+    const tag = encryptedWithTag.subarray(encryptedWithTag.length - 16);
+    const encrypted = encryptedWithTag.subarray(0, encryptedWithTag.length - 16);
+    // 从 PEM 私钥创建 ECDH 并计算共享密钥
+    const privKeyObj = crypto.createPrivateKey(privateKeyPem);
+    const ecdh = crypto.createECDH('prime256v1');
+    // 从 JWK 提取私钥 d 值设置到 ECDH
+    const jwk = privKeyObj.export({ format: 'jwk' });
+    ecdh.setPrivateKey(Buffer.from(jwk.d, 'base64url'));
+    const shared = ecdh.computeSecret(ephemeralPubBytes);
+    // HKDF 派生 AES 密钥
+    const derived = crypto.hkdfSync('sha256', shared, Buffer.alloc(0), ECIES_HKDF_INFO, 32);
+    const aesKey = Buffer.from(derived);
+    // AES-256-GCM 解密
+    const decipher = crypto.createDecipheriv('aes-256-gcm', aesKey, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(encrypted), decipher.final()]);
+}
 // ── Epoch Transcript Chain ────────────────────────────────────
 const EPOCH_CHAIN_GENESIS_PREFIX = Buffer.from('aun-epoch-chain:genesis', 'utf-8');
 /**
@@ -545,6 +601,42 @@ export function verifyMembershipCommitment(commitment, memberAids, epoch, groupI
         return false;
     return crypto.timingSafeEqual(a, b);
 }
+// ── State Hash ────────────────────────────────────────────────
+/**
+ * 计算群组状态哈希（链式）。
+ * state_hash = SHA-256(group_id | 0x00 | state_version(u64be) | 0x00 |
+ *   key_epoch(u64be) | 0x00 | membership_block | 0x00 | policy_block | 0x00 | prev_state_hash(32B))
+ */
+export function computeStateHash(params) {
+    const { groupId, stateVersion, keyEpoch, members, policy, prevStateHash } = params;
+    // 按 AID 排序，构建 membership_block
+    const sorted = [...members].sort((a, b) => a.aid.localeCompare(b.aid));
+    const membershipBlock = sorted.map(m => `${m.aid}:${m.role}`).join('|');
+    // 按 key 排序的 canonical JSON（无空格）
+    const sortedPolicy = {};
+    for (const key of Object.keys(policy).sort()) {
+        sortedPolicy[key] = policy[key];
+    }
+    const policyBlock = Object.keys(policy).length > 0 ? JSON.stringify(sortedPolicy) : '';
+    // prev_state_hash: 32 字节，空则全零
+    const prevBytes = prevStateHash
+        ? Buffer.from(prevStateHash, 'hex')
+        : Buffer.alloc(32);
+    // state_version / key_epoch → uint64 big-endian
+    const svBuf = Buffer.alloc(8);
+    svBuf.writeBigUInt64BE(BigInt(stateVersion));
+    const keBuf = Buffer.alloc(8);
+    keBuf.writeBigUInt64BE(BigInt(keyEpoch));
+    const data = Buffer.concat([
+        Buffer.from(groupId, 'utf-8'), Buffer.from([0x00]),
+        svBuf, Buffer.from([0x00]),
+        keBuf, Buffer.from([0x00]),
+        Buffer.from(membershipBlock, 'utf-8'), Buffer.from([0x00]),
+        Buffer.from(policyBlock, 'utf-8'), Buffer.from([0x00]),
+        prevBytes,
+    ]);
+    return crypto.createHash('sha256').update(data).digest('hex');
+}
 // ── Membership Manifest ───────────────────────────────────────
 /** 构建 Membership Manifest（未签名） */
 export function buildMembershipManifest(groupId, epoch, prevEpoch, memberAids, opts) {
@@ -656,12 +748,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] 拒绝缺少 epoch_chain 的新 rotation key source=${source} group=${groupId} epoch=${epoch} rotation=${rid}`);
         return { ok: false };
     }
     const current = loadGroupSecret(keystore, aid, groupId);
@@ -672,7 +764,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] 拒绝同 epoch 分叉 chain source=${source} group=${groupId} epoch=${epoch} rotation=${rid}`);
                 return { ok: false };
             }
         }
@@ -685,17 +777,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] 拒绝缺少 rotator_aid 的新 rotation key 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] 拒绝 epoch_chain 验证失败的新 rotation key 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 验证失败，按兼容档接收并标记未验证 source=${source} group=${groupId} epoch=${epoch}`);
         return { ok: true, unverified: true, reason: 'chain_mismatch_legacy' };
     }
     if (!rid)
@@ -823,7 +915,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);
@@ -863,7 +955,7 @@ export function handleKeyDistribution(message, keystore, aid, initiatorCertPem)
     }
     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');
+    const chainAssessment = assessIncomingEpochChain(keystore, aid, groupId, epoch, commitment, incomingChain, rotationId, String(payload.distributed_by ?? payload.rotator_aid ?? ''), 'key_distribution', logger);
     if (!chainAssessment.ok)
         return false;
     return storeGroupSecret(keystore, aid, groupId, epoch, groupSecret, commitment, memberAids, incomingChain, rotationId, chainAssessment.unverified, chainAssessment.reason);
@@ -896,19 +988,20 @@ export function handleKeyRequest(request, keystore, aid, currentMembers, private
     const secretData = loadGroupSecret(keystore, aid, groupId, epoch);
     if (!secretData)
         return null;
-    let commitmentStr = secretData.commitment ?? '';
+    // 历史隔离：密钥存储中记录了该 epoch 的成员列表，
+    // 若请求者不在该列表中，说明其不属于该 epoch，直接拒绝（不响应）。
     const memberAids = (secretData.member_aids ?? []).map(String).filter(Boolean).sort();
-    const currentMemberAids = currentMembers.map(String).filter(Boolean).sort();
-    let responseMemberAids = memberAids.length > 0 ? memberAids : currentMemberAids;
-    let includeEpochChain = true;
-    if (currentMemberAids.includes(requesterAid) && !responseMemberAids.includes(requesterAid)) {
-        responseMemberAids = currentMemberAids;
-        commitmentStr = computeMembershipCommitment(responseMemberAids, epoch, groupId, secretData.secret);
-        includeEpochChain = false;
-    }
-    else if (!commitmentStr) {
-        commitmentStr = computeMembershipCommitment(responseMemberAids, epoch, groupId, secretData.secret);
+    if (memberAids.length > 0 && !memberAids.includes(requesterAid)) {
+        return null;
     }
+    // 确定响应使用的成员列表：优先使用密钥存储中的成员列表，
+    // 若为空（旧数据），则降级使用当前成员列表。
+    const responseMemberAids = memberAids.length > 0
+        ? memberAids
+        : currentMembers.map(String).filter(Boolean).sort();
+    // 若存储中无 commitment，按当前成员列表重新计算
+    const commitmentStr = secretData.commitment
+        || computeMembershipCommitment(responseMemberAids, epoch, groupId, secretData.secret);
     const response = {
         type: 'e2ee.group_key_response',
         group_id: groupId,
@@ -921,7 +1014,8 @@ export function handleKeyRequest(request, keystore, aid, currentMembers, private
         responder_aid: aid,
         issued_at: Date.now(),
     };
-    if (includeEpochChain && secretData.epoch_chain !== undefined) {
+    // epoch_chain 始终包含（若有），供接收方验证历史轮转链
+    if (secretData.epoch_chain !== undefined) {
         response.epoch_chain = secretData.epoch_chain;
     }
     return privateKeyPem ? signGroupKeyResponse(response, privateKeyPem) : response;
@@ -969,9 +1063,20 @@ export function handleKeyResponse(response, keystore, aid, opts) {
     if (!verifyMembershipCommitment(commitment, memberAids, epoch, groupId, aid, groupSecret)) {
         return false;
     }
+    const manifest = isJsonObject(payload.manifest) ? payload.manifest : null;
+    if (manifest) {
+        if (manifest.group_id !== groupId || manifest.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'))
+            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');
+    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)
         return false;
     return storeGroupSecretEpoch(keystore, aid, groupId, epoch, groupSecret, commitment, memberAids, incomingChain, rotationId, chainAssessment.unverified, chainAssessment.reason);
@@ -986,6 +1091,7 @@ export class GroupE2EEManager {
     _senderCertResolver;
     _initiatorCertResolver;
     _pendingKeyRequests = new Map();
+    _logger;
     constructor(opts) {
         this._identityFn = opts.identityFn;
         this._keystore = opts.keystore;
@@ -994,6 +1100,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 */
@@ -1053,7 +1160,10 @@ export class GroupE2EEManager {
             ?? loadGroupSecret(this._keystore, aid, groupId);
         const gs = generateGroupSecret();
         const commitment = computeMembershipCommitment(memberAids, newEpoch, groupId, gs);
-        const prevChain = current?.epoch_chain ?? null;
+        let prevChain = current?.epoch_chain ?? null;
+        if (!prevChain && opts?.prevChainHint) {
+            prevChain = opts.prevChainHint;
+        }
         const epochChain = computeEpochChain(prevChain, newEpoch, commitment, aid);
         const rotationId = opts?.rotationId ?? '';
         const stored = storeGroupSecret(this._keystore, aid, groupId, newEpoch, gs, commitment, memberAids, epochChain, rotationId);
@@ -1181,7 +1291,7 @@ export class GroupE2EEManager {
             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);
             return ok ? 'distribution' : 'distribution_rejected';
         }
         if (msgType === 'e2ee.group_key_response') {
@@ -1198,6 +1308,7 @@ export class GroupE2EEManager {
                 responderCertPem,
                 currentMembers: this.getMemberAids(String(payload.group_id ?? '')),
                 strict: true,
+                logger: this._logger,
             });
             if (ok && expected)
                 this._pendingKeyRequests.delete(pendingKey);