@agentunion/fastaun 0.2.20 → 0.3.1

package/dist/client.d.ts

@@ -6,12 +6,11 @@
  * - 连接/断线重连/关闭
  * - RPC 调用（含 E2EE 自动加解密编排）
  * - 事件自动解密管线（P2P + 群组）
- * - 后台任务（心跳、token 刷新、prekey 轮换、epoch 清理/轮换）
+ * - 后台任务（心跳、token 刷新、V2 bootstrap 缓存清理）
  * - 客户端签名（关键操作）
  * - 群组 E2EE 全自动编排（建群/加人/踢人/退出）
  */
-import { E2EEManager } from './e2ee.js';
-import { GroupE2EEManager } from './e2ee-group.js';
+import type { ProtectedHeadersInput } from './protected-headers.js';
 import { type Subscription, type EventHandler } from './events.js';
 import { AuthNamespace } from './namespaces/auth.js';
 import { CustodyNamespace } from './namespaces/custody.js';
@@ -51,10 +50,6 @@ export declare class AUNClient {
     private _auth;
     /** 密钥存储 */
     private _keystore;
-    /** E2EE 管理器 */
-    private _e2ee;
-    /** 群组 E2EE 管理器 */
-    private _groupE2ee;
     /** Auth 命名空间 */
     readonly auth: AuthNamespace;
     /** AID 托管命名空间 */
@@ -73,10 +68,6 @@ export declare class AUNClient {
     private _defaultConnectDeliveryMode;
     /** peer 证书缓存 */
     private _certCache;
-    private _peerPrekeysCache;
-    private _prekeyReplenishInflight;
-    private _prekeyReplenished;
-    private _activePrekeyId;
     private _localAgentMdPath;
     private _localAgentMdEtag;
     private _remoteAgentMdEtag;
@@ -91,20 +82,31 @@ export declare class AUNClient {
     private _pushedSeqs;
     /** 已解密但因 seq 空洞暂缓发布的应用层消息（按 namespace -> seq） */
     private _pendingOrderedMsgs;
-    private _pendingDecryptMsgs;
-    private _groupEpochRotationInflight;
-    private _groupEpochRecoveryInflight;
-    private _groupMembershipRotationDone;
-    /** 群密钥 backfill 去重：已完成/进行中的 key 集合，防止重复分发 */
-    private _groupMemberKeyBackfillDone;
-    private _groupEpochRotationRetryTimers;
     private _heartbeatTimer;
     private _tokenRefreshTimer;
     private _tokenRefreshFailures;
-    private _prekeyRefreshTimer;
-    private _groupEpochCleanupTimer;
-    private _groupEpochRotateTimer;
     private _cacheCleanupTimer;
+    private _v2Session?;
+    private _v2KeyStore?;
+    /** V2 bootstrap 缓存：aid/group:id → 设备列表 + 时间戳 */
+    private _v2BootstrapCache;
+    private _connectCapabilities;
+    private _v2SigCache;
+    private _v2StateChains;
+    private _v2GroupSecurityLevels;
+    /** 同一 group 的 V2 自动提案串行化，避免并发重复提交同一 state_version。 */
+    private _v2AutoProposeInflight;
+    /** 同一 group 在运行中的自动提案期间收到的新触发，结束后至多再补跑一次。 */
+    private _v2AutoProposePending;
+    /** 最近一次已成功提交的 membership_snapshot；相同快照直接跳过。 */
+    private _v2AutoProposeLastSnapshot;
+    private _v2LazyProposeTriggered;
+    private _v2PullInflight;
+    private _v2PullPending;
+    private static readonly V2_BOOTSTRAP_TTL_MS;
+    private static readonly V2_RETRYABLE_CODES;
+    private static readonly V2_SIG_CACHE_TTL_MS;
+    private static readonly V2_SIG_CACHE_MAX;
     private _reconnectActive;
     private _reconnectAbort;
     private _serverKicked;
@@ -115,6 +117,21 @@ export declare class AUNClient {
     constructor(config?: RpcParams, debug?: boolean);
     /** 当前 AID */
     get aid(): string | null;
+    /**
+     * 读取本地 agent.md，签名后上传，并刷新本地 etag。
+     */
+    publishAgentMd(path: string): Promise<Record<string, unknown>>;
+    /**
+     * 下载 agent.md 并自动验签；可选写盘；目标是自身 AID 时刷新本地 etag。
+     */
+    fetchAgentMd(aid?: string | null, savePath?: string | null): Promise<{
+        aid: string;
+        content: string;
+        signature: Record<string, unknown>;
+        in_sync: boolean | null;
+        saved_to: string | null;
+        save_error: string | null;
+    }>;
     /**
      * 记录本地 agent.md 文件路径并一次性计算 etag（quoted sha256，与服务端一致）。
      *
@@ -139,10 +156,6 @@ export declare class AUNClient {
     private _observeRpcMeta;
     /** 连接状态 */
     get state(): string;
-    /** E2EE 管理器 */
-    get e2ee(): E2EEManager;
-    /** 群组 E2EE 管理器 */
-    get groupE2ee(): GroupE2EEManager;
     /** 最近一次 gateway health check 结果，null 表示尚未检查 */
     get gatewayHealth(): boolean | null;
     /** 向 gatewayUrl 的 /health 端点发送 GET 请求，检查网关可用性 */
@@ -184,35 +197,6 @@ export declare class AUNClient {
     /** P2-13: 取消订阅事件（对齐 Python/JS off 方法） */
     off(event: string, handler: EventHandler): void;
     private _protectedHeadersFromParams;
-    /** 自动加密并发送 P2P 消息 */
-    private _sendEncrypted;
-    private _buildRecipientDeviceCopies;
-    private _resolveSelfCopyPeerCert;
-    private _buildSelfSyncCopies;
-    private _encryptCopyPayload;
-    private _ensureEncryptResult;
-    /** 自动加密并发送群组消息 */
-    private _sendGroupEncrypted;
-    private _putGroupThoughtEncrypted;
-    private _putMessageThoughtEncrypted;
-    private _callGroupEncryptedRpc;
-    private _prepareGroupEncryptedRpcParams;
-    /** 惰性同步：首次激活群时 pull 最近消息，建立 seq 基线 */
-    private _lazySyncGroup;
-    private _isGroupEpochTooOldError;
-    private _isGroupEpochRotationPendingError;
-    private _isGroupEpochChangedDuringSendError;
-    private _isRecoverableGroupEpochError;
-    private _groupKeyRecoveryCandidates;
-    private _requestGroupKeyFrom;
-    private _requestGroupKeyFromCandidates;
-    private _recoverInitialGroupEpochIfNeeded;
-    private _ensureGroupEpochReady;
-    private _waitForGroupMembershipEpochFloor;
-    private _committedGroupEpochState;
-    private _groupSecretMatchesCommittedRotation;
-    private _ensureCommittedGroupSecretForSend;
-    private _committedRotationMembershipGap;
     /**
      * 为关键操作附加客户端 ECDSA 签名（client_signature 字段）。
      * 签名覆盖所有非 _ 前缀且非 client_signature 的业务字段。
@@ -237,7 +221,7 @@ export declare class AUNClient {
     private _fillGroupGap;
     /** 后台补齐 P2P 消息空洞 */
     private _fillP2pGap;
-    /** 清理 pushedSeqs 中 <= contiguousSeq 的条目，防止无限增长 */
+    /** 只按硬上限裁剪 published guard，不能按 contiguousSeq 清理。 */
     private _prunePushedSeqs;
     private _markPublishedSeq;
     private _enqueueOrderedMessage;
@@ -252,15 +236,9 @@ export declare class AUNClient {
     private _messageTargetsCurrentInstance;
     private _drainOrderedMessages;
     private _publishOrderedMessage;
+    private _publishPulledMessage;
     /** 后台补齐群事件空洞 */
     private _fillGroupEventGap;
-    /**
-     * 处理群组变更事件：透传给用户，并在成员离开/被踢时自动触发 epoch 轮换。
-     * 按协议，轮换由剩余在线 admin/owner 负责。
-     */
-    private _membershipRotationExpectedEpoch;
-    private _membershipRotationTriggerId;
-    private _membershipRotationChanged;
     private _extractGroupIdFromResult;
     private _onRawGroupChanged;
     /**
@@ -268,17 +246,7 @@ export declare class AUNClient {
      * 当链断裂时回源 group.get_state，并对回源结果做本地 hash 重算验证。
      */
     private _onGroupStateCommitted;
-    /**
-     * 成员退出/被踢后，判断本地是否为 leader admin 并发起 epoch 轮换。
-     * 避免所有剩余 admin 同时触发 `_rotateGroupEpoch` 造成 CAS 风暴。
-     */
-    private _maybeLeadRotateGroupEpoch;
-    /**
-     * 群组解散后清理本地状态：
-     * - keystore 中的 epoch key 数据
-     * - seq_tracker 中的群消息和群事件 seq 记录
-     * - 补洞去重缓存中的相关条目
-     */
+    /** 群组解散后清理本地 V2 缓存、seq_tracker 和补洞去重缓存。 */
     private _cleanupDissolvedGroup;
     /** 同步验签群事件 client_signature。返回 true/false/"pending"。 */
     /**
@@ -288,100 +256,15 @@ export declare class AUNClient {
      * 并触发 `signature_pending` 事件让上层感知。
      */
     private _verifyEventSignatureAsync;
-    /** 尝试处理 P2P 传输的群组密钥消息。返回 true 表示已处理（不再传播）。 */
-    private _tryHandleGroupKeyMessage;
     /**
+     * 获取对方证书（带缓存 + 完整 PKI 验证）。  /**
      * 获取对方证书（带缓存 + 完整 PKI 验证）。
      * 跨域时自动路由到 peer 所在域的 Gateway。
      */
     private _fetchPeerCert;
-    /** 获取对方所有设备的 prekey 列表。 */
-    private _fetchPeerPrekeys;
-    /** 获取对方的单个 prekey（兼容接口，优先返回第一条 device prekey）。 */
-    private _fetchPeerPrekey;
-    /** 清除对端 prekey 的双层缓存（_peerPrekeysCache + e2ee 内部缓存） */
-    private _invalidatePeerPrekeyCache;
-    /** 清除对端证书缓存（精确匹配 aid 或 aid# 前缀的所有条目） */
-    private _clearPeerCertCache;
-    /** 清除对端所有缓存后重新拉取 prekey（用于指纹不匹配时的强制刷新） */
-    private _refreshPeerPrekeys;
-    /** 生成 prekey 并上传到服务端 */
-    private _uploadPrekey;
-    /**
-     * 确保发送方证书在本地 keystore 中可用且未过期。
-     * 返回 true 表示证书已就绪（PKI 验证通过），false 表示不可用。
-     */
-    private _ensureSenderCertCached;
-    /**
-     * 获取经过 PKI 验证的 peer 证书（仅信任内存缓存中已验证的证书）。
-     * 零信任：不直接信任 keystore 中可能由恶意服务端注入的证书。
-     */
-    private _getVerifiedPeerCert;
-    /** 解密单条 P2P 消息 */
-    private _decryptSingleMessage;
-    /** 批量解密 P2P 消息（用于 message.pull） */
-    private _decryptMessages;
-    /** 解密单条群组消息。opts.skipReplay 用于 group.pull 场景跳过防重放。 */
-    private _enqueuePendingDecrypt;
-    private _retryPendingDecryptMsgs;
-    /**
-     * recovery 兜底定时：N 秒后如果 pending queue 仍有未解开消息，强制推进 cursor。
-     * 同一 group 短时间内只调度一次。
-     */
-    private _recoveryTimeoutScheduled;
-    private _scheduleRecoveryTimeout;
-    private _scheduleRetryPendingDecryptMsgs;
-    private _recoverGroupEpochKey;
-    private static _extractGroupJoinMode;
-    private static _joinModeAllowsMemberEpochRotation;
-    private _groupAllowsMemberEpochRotation;
-    /** 尝试从服务端拉取 ECIES 加密的 epoch key 并解密存入 keystore */
-    private _tryRecoverEpochKeyFromServer;
-    /** 为每个成员用其 AID 证书公钥 ECIES 加密 group_secret，返回 {aid: base64_ciphertext} */
-    private _buildEpochEncryptedKeys;
-    private _doRecoverGroupEpochKey;
-    /** 只向在线成员发送密钥恢复请求 */
-    private _requestGroupKeyFromOnline;
-    private _groupEpochSecretReadyForRecovery;
-    private _pendingGroupSecretStillCurrent;
-    private _decryptGroupMessage;
-    private _attachGroupDispatchModeToPayload;
-    /** 批量解密群组消息（用于 group.pull，跳过防重放） */
-    private _decryptGroupMessages;
     private _decryptGroupThoughts;
     private _decryptMessageThoughts;
-    private _attachRotationId;
-    private _getGroupMemberAids;
-    private _distributeGroupEpochKey;
-    private _heartbeatGroupRotation;
-    private _ackGroupRotationKey;
-    private _verifyActiveGroupRotationDistribution;
-    private _discardGroupDistributionIfStale;
-    private _verifyGroupKeyResponseEpoch;
-    private _abortGroupRotation;
-    private _rotationExpectedMembersStale;
-    private _rotationRetryDelayMs;
-    private _scheduleGroupRotationRetry;
-    /** 建群后将本地 epoch 1 同步到服务端（服务端初始为 0），最多重试 3 次 */
-    private _syncEpochToServer;
-    /**
-     * 为指定群组轮换 epoch 并分发新密钥。
-     * 使用服务端两阶段 rotation，避免服务端先提交但密钥未分发。
-     */
-    private _rotateGroupEpoch;
-    /** 将当前 group_secret 通过 P2P E2EE 分发给新成员 */
-    private _distributeKeyToNewMember;
-    /** 从成员加入事件 payload 中提取新加入的成员 AID 列表。 */
-    private _joinedMemberAidsFromPayload;
-    /** 延迟轮换等待时间（毫秒）：给新成员恢复 committed_epoch 的窗口 */
-    private static readonly _JOIN_ROTATION_DELAY_MS;
-    private static readonly _SELF_JOIN_ROTATION_DELAY_MS;
-    /** open/invite_code 入群后延迟轮换。 */
-    private _delayedRotateAfterJoin;
-    /** 当新成员加入但缺少 old_epoch 时，将当前 epoch 密钥分发给新成员。 */
-    private _maybeBackfillKeyToJoinedMember;
-    private _buildRotationSignature;
-    /** 从 keystore 恢复 SeqTracker 状态 */
+    /** 从 keystore 恢复 SeqTracker 状态 */ /** 从 keystore 恢复 SeqTracker 状态 */
     private _restoreSeqTrackerState;
     /**
      * 把 seq_tracker state 里 group_event:/group_msg: 前缀的老/污染 group_id 归一化为 canonical。
@@ -402,6 +285,78 @@ export declare class AUNClient {
     private static _buildCertUrl;
     /** 执行一次连接流程 */
     private _connectOnce;
+    /** 记录当前 connect 声明的 E2EE 能力；缺失时按 SDK 默认能力（V2）处理。 */
+    private _captureCapabilitiesFromConnect;
+    /** 当前连接是否按 V2 P2P E2EE 处理；未声明 capabilities 时视同支持 V2。 */
+    private _clientUsesV2P2P;
+    /** 当前连接是否按 V2 Group E2EE 处理；未声明 capabilities 时视同支持 V2。 */
+    private _clientUsesV2Group;
+    /** 后台 Promise 统一兜底，避免事件回调里的异步异常变成未处理拒绝。 */
+    private _safeAsync;
+    /** V2-only：所有加密入口都必须有 V2 session。 */
+    private _ensureV2SessionReady;
+    private _v2CallFn;
+    /**
+     * 初始化 V2 session：IK 使用 AID 长期私钥，SPK 存储在 per-AID SQLite 的 v2_device_keys 表。
+     * connect 成功后会自动调用；重复调用幂等。
+     */
+    initV2Session(): Promise<void>;
+    private _getV2SenderPubDer;
+    /**
+     * 构造 V2 P2P envelope；message.send 与 message.thought.put 共用。
+     */
+    private _buildV2P2PEnvelope;
+    /** V2 P2P 加密发送，推测性缓存失败后刷新 bootstrap 重试一次。 */
+    sendV2(to: string, payload: Record<string, unknown>, opts?: {
+        messageId?: string;
+        timestamp?: number;
+        protectedHeaders?: ProtectedHeadersInput;
+        context?: Record<string, unknown>;
+    }): Promise<unknown>;
+    /** V2 P2P 拉取并解密；直接方法返回消息数组，call("message.pull") 会包装为 {messages}. */
+    pullV2(afterSeq?: number, limit?: number): Promise<Array<Record<string, unknown>>>;
+    /** V2 P2P ack，并触发旧 SPK 销毁自检。 */
+    ackV2(upToSeq?: number): Promise<unknown>;
+    /** V2 Group 加密发送，推测性缓存失败后刷新 bootstrap 重试一次。 */
+    sendGroupV2(groupId: string, payload: Record<string, unknown>, opts?: {
+        messageId?: string;
+        timestamp?: number;
+        protectedHeaders?: ProtectedHeadersInput;
+        context?: Record<string, unknown>;
+    }): Promise<unknown>;
+    /** 构造 V2 Group envelope；group.send 与 group.thought.put 共用。 */
+    private _buildV2GroupEnvelope;
+    private _pullGroupV2Internal;
+    /** V2 Group 拉取并解密；直接方法返回消息数组，call("group.pull") 会包装为 {messages}. */
+    pullGroupV2(groupId: string, afterSeq?: number, limit?: number): Promise<Array<Record<string, unknown>>>;
+    /** V2 Group ack。 */
+    ackGroupV2(groupId: string, upToSeq?: number): Promise<unknown>;
+    /** 解密单条 V2 pull 消息。失败返回 null 并发布 undecryptable。 */
+    private _decryptV2Message;
+    private _putMessageThoughtEncryptedV2;
+    private _putGroupThoughtEncryptedV2;
+    /** 解密 thought 中直接透传的 V2 envelope。 */
+    private _decryptV2EnvelopeForThought;
+    private _publishV2GroupSecurityLevel;
+    private _v2VerifyStateSignature;
+    private _v2CheckFork;
+    private _v2MaybeTriggerAutoPropose;
+    private _v2AutoProposeState;
+    private _v2LeaderDelayMs;
+    private _v2AutoProposeLeaderDelay;
+    private _v2VerifyCommittedStateBase;
+    private _doV2AutoProposeState;
+    private _v2VerifyPendingProposalAgainstBase;
+    private _v2ConfirmPendingProposal;
+    private _v2AutoConfirmPendingProposals;
+    private _onV2PushNotification;
+    private _onV2StateProposed;
+    private _onV2StateRetryNeeded;
+    private _onV2StateConfirmed;
+    private _onRawGroupV2MessageCreated;
+    /** Push 通知带 payload 时的就地解密（复用 _decryptV2Message） */
+    private _decryptV2PushMessage;
+    private _onV2EpochRotated;
     /** 从参数中解析 Gateway URL */
     private _resolveGateway;
     /** 连接后同步身份信息 */
@@ -420,16 +375,12 @@ export declare class AUNClient {
     private _applyServerHeartbeatInterval;
     /** 启动 token 刷新任务 */
     private _startTokenRefreshTask;
-    /** 启动 prekey 刷新任务 */
-    private _startPrekeyRefreshTask;
-    private _extractConsumedPrekeyId;
     private _validateMessageRecipient;
     private _validateOutboundCall;
     private _currentMessageDeliveryMode;
     private _injectMessageCursorContext;
-    private _schedulePrekeyReplenishIfConsumed;
-    /** 启动群组 epoch 相关后台任务 */
-    private _startGroupEpochTasks;
+    /** 启动 V2 缓存清理后台任务 */
+    private _startV2MaintenanceTasks;
     /** 允许 Node.js 进程在只剩定时器时退出 */
     private _unrefTimer;
     /** 不重连 close code 集合：认证失败/权限错误/被踢等，重连无意义 */