@agentunion/fastaun 0.2.14 → 0.2.16

package/dist/e2ee-group.d.ts

@@ -5,6 +5,7 @@
  * 内置防重放、epoch 降级防护、密钥请求频率限制。
  */
 import type { KeyStore } from './keystore/index.js';
+import type { ProtectedHeadersInput } from './e2ee.js';
 import { type IdentityRecord, type JsonObject, type Message } from './types.js';
 export interface LoadedGroupSecret {
     epoch: number;
@@ -16,6 +17,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 的字节。
@@ -37,6 +52,10 @@ export declare function encryptGroupMessage(groupId: string, epoch: number, grou
     timestamp: number;
     senderPrivateKeyPem?: string | null;
     senderCertPem?: string | null;
+    protectedHeaders?: ProtectedHeadersInput;
+    protected_headers?: ProtectedHeadersInput;
+    headers?: ProtectedHeadersInput;
+    context?: JsonObject | null;
 }): JsonObject;
 /**
  * 解密群组消息。
@@ -57,6 +76,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[];
@@ -148,12 +183,27 @@ 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。 */
-    encrypt(groupId: string, payload: JsonObject): JsonObject;
+    encrypt(groupId: string, payload: JsonObject, opts?: {
+        protectedHeaders?: ProtectedHeadersInput;
+        protected_headers?: ProtectedHeadersInput;
+        headers?: ProtectedHeadersInput;
+        context?: JsonObject | null;
+        messageId?: string;
+        timestamp?: number;
+    }): JsonObject;
     /** 使用指定 epoch 加密群消息。 */
-    encryptWithEpoch(groupId: string, epoch: number, payload: JsonObject): JsonObject;
+    encryptWithEpoch(groupId: string, epoch: number, payload: JsonObject, opts?: {
+        protectedHeaders?: ProtectedHeadersInput;
+        protected_headers?: ProtectedHeadersInput;
+        headers?: ProtectedHeadersInput;
+        context?: JsonObject | null;
+        messageId?: string;
+        timestamp?: number;
+    }): JsonObject;
     /** 解密单条群消息。内置防重放 + 发送方验签。 */
     decrypt(message: Message, opts?: {
         skipReplay?: boolean;
@@ -188,5 +238,7 @@ export declare class GroupE2EEManager {
     cleanExpiredCaches(): void;
     /** 删除群组的所有本地状态（群组解散时使用） */
     removeGroup(groupId: string): void;
+    /** 加载指定群组的所有 epoch 密钥。返回 Map<epoch, Buffer>。 */
+    loadAllSecrets(groupId: string): Map<number, Buffer>;
     private _currentAid;
 }

package/dist/e2ee-group.js

@@ -28,8 +28,71 @@ const AAD_MATCH_FIELDS_GROUP = [
     'group_id', 'from', 'message_id',
     'epoch', 'encryption_mode', 'suite',
 ];
+const AAD_OPTIONAL_FIELDS = [
+    'payload_type', 'protected_headers', 'context_type', 'context_id',
+];
+const METADATA_AUTH_FIELD = '_auth';
+const METADATA_AUTH_ALG = 'HMAC-SHA256';
+const METADATA_KEY_DOMAIN = Buffer.from('aun-envelope-metadata-key-v1', 'utf-8');
+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');
 /**
@@ -179,17 +242,154 @@ function pemToCertPublicKey(certPem) {
     return x509.publicKey;
 }
 // ── 群组 AAD 工具 ─────────────────────────────────────────────
+function canonicalStringify(value) {
+    if (value === null || value === undefined)
+        return 'null';
+    if (Array.isArray(value)) {
+        return `[${value.map(item => canonicalStringify(item)).join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const record = value;
+        const pairs = Object.keys(record)
+            .sort()
+            .map(key => `${JSON.stringify(key)}:${canonicalStringify(record[key])}`);
+        return `{${pairs.join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+function hasOwn(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+function normalizeProtectedHeaderKey(key) {
+    const value = String(key ?? '').trim().toLowerCase();
+    if (!value || !/^[a-z0-9_-]+$/.test(value)) {
+        throw new E2EEError('protected header key must match [a-z0-9_-]+');
+    }
+    if (value === METADATA_AUTH_FIELD) {
+        throw new E2EEError('protected header key is reserved');
+    }
+    return value;
+}
+function normalizeProtectedHeaders(headers) {
+    if (headers == null)
+        return {};
+    const toObject = headers.toObject;
+    const raw = typeof toObject === 'function' ? toObject.call(headers) : headers;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new E2EEError('protected_headers must be an object');
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(raw)) {
+        result[normalizeProtectedHeaderKey(key)] = value == null ? '' : String(value);
+    }
+    return result;
+}
+function copyOptionalEnvelopeMetadata(envelope, messageKey, opts) {
+    const payloadType = String(opts?.payloadType ?? '').trim();
+    const protectedHeaders = normalizeProtectedHeaders(opts?.protectedHeaders);
+    if (payloadType) {
+        protectedHeaders.payload_type = payloadType;
+    }
+    if (Object.keys(protectedHeaders).length > 0) {
+        envelope.protected_headers = withMetadataAuth(protectedHeaders, messageKey, PROTECTED_HEADERS_DOMAIN);
+    }
+    const contextMetadata = normalizeContextMetadata(opts?.context);
+    if (Object.keys(contextMetadata).length > 0) {
+        envelope.context = withMetadataAuth(contextMetadata, messageKey, PROTECTED_CONTEXT_DOMAIN);
+    }
+}
+function metadataBody(metadata) {
+    const body = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (key !== METADATA_AUTH_FIELD) {
+            body[key] = value;
+        }
+    }
+    return body;
+}
+function metadataAuthTag(key, domain, body) {
+    const metadataKey = crypto.createHmac('sha256', key).update(METADATA_KEY_DOMAIN).digest();
+    return crypto.createHmac('sha256', metadataKey)
+        .update(domain)
+        .update(Buffer.from([0]))
+        .update(Buffer.from(canonicalStringify(body), 'utf-8'))
+        .digest();
+}
+function withMetadataAuth(metadata, key, domain) {
+    const body = metadataBody(metadata);
+    if (Object.keys(body).length === 0)
+        return {};
+    const tag = metadataAuthTag(key, domain, body);
+    return {
+        ...body,
+        [METADATA_AUTH_FIELD]: {
+            alg: METADATA_AUTH_ALG,
+            tag: tag.toString('base64'),
+        },
+    };
+}
+function verifyMetadataAuth(metadata, key, domain) {
+    if (metadata == null)
+        return true;
+    if (typeof metadata !== 'object' || Array.isArray(metadata))
+        return false;
+    const record = metadata;
+    const auth = record[METADATA_AUTH_FIELD];
+    if (!auth || typeof auth !== 'object' || Array.isArray(auth))
+        return false;
+    const authObj = auth;
+    if (authObj.alg !== METADATA_AUTH_ALG)
+        return false;
+    if (typeof authObj.tag !== 'string' || !authObj.tag)
+        return false;
+    const body = metadataBody(record);
+    if (Object.keys(body).length === 0)
+        return false;
+    const actual = Buffer.from(authObj.tag, 'base64');
+    const expected = metadataAuthTag(key, domain, body);
+    return actual.length === expected.length && crypto.timingSafeEqual(actual, expected);
+}
+function verifyEnvelopeMetadataAuth(payload, messageKey) {
+    return verifyMetadataAuth(payload.protected_headers, messageKey, PROTECTED_HEADERS_DOMAIN)
+        && verifyMetadataAuth(payload.context, messageKey, PROTECTED_CONTEXT_DOMAIN);
+}
+function normalizeContextMetadata(context) {
+    if (!context || typeof context !== 'object' || Array.isArray(context))
+        return {};
+    return metadataBody(context);
+}
+function exposedEnvelopeMetadata(metadata) {
+    if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata))
+        return undefined;
+    const body = metadataBody(metadata);
+    return Object.keys(body).length > 0 ? body : undefined;
+}
+function validateDecryptedEnvelopeMetadata(decoded, payload, message) {
+    if (payload.protected_headers && typeof payload.protected_headers === 'object' && !Array.isArray(payload.protected_headers)) {
+        const headers = metadataBody(payload.protected_headers);
+        if (hasOwn(headers, 'payload_type')) {
+            if (!decoded || typeof decoded !== 'object' || Array.isArray(decoded))
+                return false;
+            if (String(decoded.type ?? '') !== String(headers.payload_type ?? '')) {
+                return false;
+            }
+        }
+    }
+    if (payload.context && typeof payload.context === 'object' && !Array.isArray(payload.context)) {
+        const protectedContext = metadataBody(payload.context);
+        const outerContext = normalizeContextMetadata(message?.context);
+        if (canonicalStringify(outerContext) !== canonicalStringify(protectedContext))
+            return false;
+    }
+    return true;
+}
 /** 群组 AAD 序列化（sorted keys, compact JSON） */
 function aadBytesGroup(aad) {
     const obj = {};
     for (const field of AAD_FIELDS_GROUP) {
         obj[field] = aad[field] ?? null;
     }
-    const sorted = {};
-    for (const k of Object.keys(obj).sort()) {
-        sorted[k] = obj[k];
-    }
-    return Buffer.from(JSON.stringify(sorted), 'utf-8');
+    return Buffer.from(canonicalStringify(obj), 'utf-8');
 }
 /** 群组 AAD 字段匹配检查 */
 function aadMatchesGroup(expected, actual) {
@@ -222,19 +422,24 @@ export function encryptGroupMessage(groupId, epoch, groupSecret, payload, opts)
         encryption_mode: MODE_EPOCH_GROUP_KEY,
         suite: SUITE,
     };
-    const aadBytes = aadBytesGroup(aad);
-    const { ciphertext, tag, nonce } = aesGcmEncrypt(msgKey, plaintext, aadBytes);
     const envelope = {
         type: 'e2ee.group_encrypted',
         version: '1',
         encryption_mode: MODE_EPOCH_GROUP_KEY,
         suite: SUITE,
         epoch,
-        nonce: nonce.toString('base64'),
-        ciphertext: ciphertext.toString('base64'),
-        tag: tag.toString('base64'),
-        aad,
     };
+    copyOptionalEnvelopeMetadata(envelope, msgKey, {
+        payloadType: payload.type,
+        protectedHeaders: opts.protectedHeaders ?? opts.protected_headers ?? opts.headers,
+        context: opts.context ?? null,
+    });
+    const aadBytes = aadBytesGroup(aad);
+    const { ciphertext, tag, nonce } = aesGcmEncrypt(msgKey, plaintext, aadBytes);
+    envelope.nonce = nonce.toString('base64');
+    envelope.ciphertext = ciphertext.toString('base64');
+    envelope.tag = tag.toString('base64');
+    envelope.aad = aad;
     // 发送方签名
     if (opts.senderPrivateKeyPem) {
         const signPayload = Buffer.concat([ciphertext, tag, aadBytes]);
@@ -298,19 +503,32 @@ export function decryptGroupMessage(message, groupSecrets, senderCertPem, opts)
         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)) {
+            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)) {
+            return null;
+        }
+        const e2ee = {
+            encryption_mode: MODE_EPOCH_GROUP_KEY,
+            suite: SUITE,
+            epoch,
+            sender_verified: false,
+        };
+        const protectedHeaders = exposedEnvelopeMetadata(payload.protected_headers);
+        if (protectedHeaders)
+            e2ee.protected_headers = protectedHeaders;
+        const context = exposedEnvelopeMetadata(payload.context);
+        if (context)
+            e2ee.context = context;
         const result = {
             ...message,
             payload: decoded,
             encrypted: true,
-            e2ee: {
-                encryption_mode: MODE_EPOCH_GROUP_KEY,
-                suite: SUITE,
-                epoch,
-                sender_verified: false,
-            },
+            e2ee,
         };
         // 发送方签名验证
         const senderSigB64 = payload.sender_signature;
@@ -382,6 +600,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) {
@@ -733,19 +987,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,
@@ -758,7 +1013,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;
@@ -806,6 +1062,17 @@ 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');
@@ -890,7 +1157,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);
@@ -914,7 +1184,7 @@ export class GroupE2EEManager {
         return discardPendingGroupSecret(this._keystore, this._currentAid(), groupId, epoch, rotationId);
     }
     /** 加密群消息（含发送方签名）。无密钥时抛 E2EEGroupSecretMissingError。 */
-    encrypt(groupId, payload) {
+    encrypt(groupId, payload, opts) {
         const aid = this._currentAid();
         const secretData = loadGroupSecret(this._keystore, aid, groupId);
         if (!secretData) {
@@ -929,14 +1199,16 @@ export class GroupE2EEManager {
         const senderCertPem = identity ? identity.cert ?? null : null;
         return encryptGroupMessage(groupId, secretData.epoch, secretData.secret, payload, {
             fromAid: aid,
-            messageId: `gm-${crypto.randomUUID()}`,
-            timestamp: Date.now(),
+            messageId: opts?.messageId ?? `gm-${crypto.randomUUID()}`,
+            timestamp: opts?.timestamp ?? Date.now(),
             senderPrivateKeyPem: senderPkPem,
             senderCertPem,
+            protectedHeaders: opts?.protectedHeaders ?? opts?.protected_headers ?? opts?.headers,
+            context: opts?.context ?? null,
         });
     }
     /** 使用指定 epoch 加密群消息。 */
-    encryptWithEpoch(groupId, epoch, payload) {
+    encryptWithEpoch(groupId, epoch, payload, opts) {
         const aid = this._currentAid();
         const secretData = loadGroupSecret(this._keystore, aid, groupId, epoch);
         if (!secretData) {
@@ -950,10 +1222,12 @@ export class GroupE2EEManager {
         const senderCertPem = identity ? identity.cert ?? null : null;
         return encryptGroupMessage(groupId, secretData.epoch, secretData.secret, payload, {
             fromAid: aid,
-            messageId: `gm-${crypto.randomUUID()}`,
-            timestamp: Date.now(),
+            messageId: opts?.messageId ?? `gm-${crypto.randomUUID()}`,
+            timestamp: opts?.timestamp ?? Date.now(),
             senderPrivateKeyPem: senderPkPem,
             senderCertPem,
+            protectedHeaders: opts?.protectedHeaders ?? opts?.protected_headers ?? opts?.headers,
+            context: opts?.context ?? null,
         });
     }
     /** 解密单条群消息。内置防重放 + 发送方验签。 */
@@ -1123,6 +1397,10 @@ export class GroupE2EEManager {
             // keystore 不支持 delete 时忽略（降级方案已在 deleteKeyStoreGroupState 中处理）
         }
     }
+    /** 加载指定群组的所有 epoch 密钥。返回 Map<epoch, Buffer>。 */
+    loadAllSecrets(groupId) {
+        return loadAllGroupSecrets(this._keystore, this._currentAid(), groupId);
+    }
     _currentAid() {
         const identity = this._identityFn();
         const aid = identity.aid;