@agentunion/fastaun 0.3.3 → 0.3.5

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -12,7 +12,7 @@ SDK 文档聚焦核心封装：**认证（`client.auth`）**、**元信息与信
 
 ## 渐进式查阅流程
 
-### Step 1：只读 Layer 1（L7-34）
+### Step 1：只读 Layer 1（L7-34）
 
 列出所有文档名和章节行区间。能直接定位目标 → 跳 Step 4。
 
@@ -20,13 +20,13 @@ SDK 文档聚焦核心封装：**认证（`client.auth`）**、**元信息与信
 
 仅当 Step 1 不够时，按关键词读：
 
-身份与认证 L40-45 · 连接与状态 L47-52 · E2EE L54-63 · RPC与事件 L65-77 · 配置与存储 L79-85 · 错误处理 L87-90 · AID托管 L45
+身份与认证 L40-45 · 连接与状态 L47-52 · E2EE L54-63 · RPC与事件 L65-77 · 配置与存储 L79-85 · 错误处理 L87-90 · AID托管 L45
 
 ### Step 3：按需读 Layer 3 单篇摘要
 
 仅当需要某篇详情但不确定读哪个章节时：
 
-快速开始 L96-97 · WebSocket协议 L99-100 · 核心概念 L102-103 · 连接与认证 L105-106 · E2EE加密通信 L108-109 · E2EE_V2消息通信时序图 L111-112 · GROUP-E2EE轮换竞态清单 L114-115 · GROUP-E2EE现状对比与改进建议 L117-118 · API参考 L120-121 · 错误处理 L123-124 · 最佳实践 L126-127 · AID托管 L129-130 · 消息Payload L132-133 · 多语言SDK对齐审查 L135-136
+快速开始 L96-97 · WebSocket协议 L99-100 · 核心概念 L102-103 · 连接与认证 L105-106 · E2EE加密通信 L108-109 · E2EE_V2消息通信时序图 L111-112 · GROUP-E2EE轮换竞态清单 L114-115 · GROUP-E2EE现状对比与改进建议 L117-118 · API参考 L120-121 · 错误处理 L123-124 · 最佳实践 L126-127 · AID托管 L129-130 · 消息Payload L132-133 · 多语言SDK对齐审查 L135-136
 
 大多数问题在摘要层就能解答。
 
@@ -42,8 +42,8 @@ SDK 文档聚焦核心封装：**认证（`client.auth`）**、**元信息与信
 | 02 | [WebSocket协议](02-WebSocket协议.md) | 握手流程、消息格式、裸 WebSocket 示例 |
 | 03 | [核心概念](03-核心概念.md) | AID、状态机、认证、E2EE |
 | 04 | [连接与认证](04-连接与认证.md) | 认证封装、call()、on()、连接 |
-| 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE封装、ProtectedHeaders、自定义存储 |
-| - | [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) | V2-only 明文/加密 P2P/GROUP 消息主链路 Mermaid 时序图 |
+| 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE封装、ProtectedHeaders、自定义存储 |
+| - | [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) | V2-only 明文/加密 P2P/GROUP 消息主链路 Mermaid 时序图 |
 | - | [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md) | GROUP epoch key 轮换状态、竞态条件、补测清单 |
 | - | [GROUP-E2EE现状对比与改进建议](GROUP-E2EE现状对比与改进建议.md) | 当前 GROUP E2EE 实现定位、成熟方案对比、风险边界、分阶段改进建议 |
 | 06 | [API手册](06-API手册.md) | AUNClient / AuthNamespace / MetaNamespace（信任根列表与 issuer root 更新） / E2EEManager |
@@ -61,9 +61,9 @@ SDK 文档聚焦核心封装：**认证（`client.auth`）**、**元信息与信
 | 裸 WebSocket 或其他语言实现 | 02-WebSocket协议 |
 | 理解 AID / E2EE 原理 | 03-核心概念 对应章节 |
 | 认证 + 连接 + call/on 用法 | 04-连接与认证 |
-| 需要加密通信 | 05-E2EE加密通信 |
-| 需要查看 E2EE V2 消息主链路时序 | [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) |
-| GROUP E2EE 轮换竞态/测试设计 | [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md) |
+| 需要加密通信 | 05-E2EE加密通信 |
+| 需要查看 E2EE V2 消息主链路时序 | [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) |
+| GROUP E2EE 轮换竞态/测试设计 | [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md) |
 | GROUP E2EE 架构评估/演进路线 | [GROUP-E2EE现状对比与改进建议](GROUP-E2EE现状对比与改进建议.md) |
 | 查消息或思考内容 payload 类型和格式 | [09-payload-reference](09-payload-reference.md) |
 | 查某个方法的签名 | 06-API手册 |

package/_packed_docs/sdk/E2EE_V2/346/266/210/346/201/257/351/200/232/344/277/241/346/227/266/345/272/217/345/233/276.md

@@ -0,0 +1,171 @@
+# E2EE V2 消息通信时序图
+
+本文只描述当前 V2-only 链路下的主要时序：P2P/GROUP 明文消息、P2P/GROUP 加密消息，以及 V2 设备密钥注册前置流程。不包含 V1 E2EE、旧 group epoch secret 分发、thought 内容读写。
+
+## 范围约定
+
+- SDK 默认 `message.send` / `group.send` 为 `encrypt=true`，由 SDK 本地构造 V2 加密 envelope。
+- 显式 `encrypt=false` 时走明文发送；V2 SDK 接收端仍通过 `message.v2.pull` / `group.v2.pull` 合并拉取明文历史行。
+- P2P 加密 envelope 类型为 `e2ee.p2p_encrypted`，通过 `message.send` 提交，服务端按 V2 分流处理。
+- GROUP 加密 envelope 类型为 `e2ee.group_encrypted`，通过 `group.v2.send` 提交。
+- 服务端只做认证、路由、结构校验、密文存储和事件通知，不持有明文 payload，也不执行端到端解密。
+
+## V2 设备密钥注册
+
+```mermaid
+sequenceDiagram
+    participant SDK as 接收方 SDK
+    participant Message as message 服务
+    participant Group as group 服务
+    participant CA as CA/Auth
+
+    SDK->>SDK: 初始化 V2Session<br/>IK=AID 长期密钥，生成或加载 P2P SPK
+    SDK->>Message: message.v2.put_peer_pk<br/>peer_device_prekey + SPK 签名
+    Message->>CA: ca.get_cert / 校验 AID 公钥
+    Message-->>SDK: ok
+
+    opt 已加入某个群
+        SDK->>SDK: ensure_group_spk(group_id)
+        SDK->>Group: group.v2.put_group_pk<br/>group_device_prekey + SPK 签名
+        Group->>CA: ca.get_cert / 校验 AID 公钥
+        Group-->>SDK: ok
+    end
+```
+
+## P2P 明文消息
+
+```mermaid
+sequenceDiagram
+    participant A as Sender SDK
+    participant M as message 服务
+    participant G as gateway
+    participant B as Receiver SDK
+
+    A->>M: message.send<br/>encrypt=false, payload=明文
+    alt 目标跨域
+        M->>G: gateway.forward_federation<br/>namespace=message, method=send
+        G->>M: 转发到目标域 message 服务
+    end
+    M->>M: 按接收方 device 分配 seq<br/>写普通消息存储
+    M->>G: dispatch_event(message.received)
+    G-->>B: event/message.received 或通知
+
+    B->>M: message.v2.pull(after_seq, limit)
+    M-->>B: messages[]<br/>明文行 version=v1 / legacy_v1
+    B->>B: 直接发布 message.received<br/>不做 E2EE 解密
+    B->>M: message.v2.ack(up_to_seq)
+```
+
+## P2P 加密消息
+
+```mermaid
+sequenceDiagram
+    participant A as Sender SDK
+    participant M as message 服务
+    participant G as gateway
+    participant B as Receiver SDK
+
+    A->>M: message.v2.bootstrap(peer_aid=B)
+    M-->>A: B active devices<br/>IK + peer_device_prekey SPK<br/>self_devices + audit_recipients
+
+    A->>A: 构造 recipients<br/>peer + self_sync + audit
+    A->>A: 生成 master_key / msg_nonce / sender_session_key
+    A->>A: 3DH/1DH wrap master_key<br/>AES-GCM 加密 payload<br/>ECDSA 签名 ct+tag+AAD+recipients_digest
+    A->>M: message.send<br/>payload.type=e2ee.p2p_encrypted, version=v2, encrypt=false
+
+    alt 目标跨域
+        M->>G: gateway.forward_federation<br/>namespace=message, method=send
+        G->>M: 转发到目标域 message 服务
+    end
+
+    M->>M: 校验 AAD/from/to/device、t_send、recipients_digest、audit wrap
+    M->>M: 写 v2_peer_messages 共享密文体
+    M->>M: 按 device 写 v2_peer_wraps<br/>seq per owner_aid + device_id
+    M->>G: dispatch_event(peer.v2.message_received)<br/>只含 seq/message_id/device_id
+    G-->>B: peer.v2.message_received
+
+    B->>M: message.v2.pull(after_seq, limit)
+    M-->>B: per-device envelope_json<br/>recipient wrap + merkle_proof
+    B->>B: 验 sender_signature / recipients proof
+    B->>B: 用本地 IK/SPK 解 wrap_key -> master_key
+    B->>B: AES-GCM 解密 payload
+    B-->>B: 发布 message.received
+    B->>M: message.v2.ack(up_to_seq)
+    B->>B: 若消费当前 SPK，异步 rotate_spk()
+```
+
+## GROUP 明文消息
+
+```mermaid
+sequenceDiagram
+    participant A as Sender SDK
+    participant Group as group 服务
+    participant G as gateway
+    participant B as Member SDK
+
+    A->>Group: group.send<br/>encrypt=false, payload=明文
+    Group->>Group: 校验成员/禁言/消息类型/epoch 边界
+    Group->>Group: 写 group_messages + group_events<br/>递增 group.message_seq / event_seq
+    Group->>G: dispatch_event(group.message_created)<br/>member_aids / dispatch 信息
+    G-->>B: group.message_created 通知
+
+    B->>Group: group.v2.pull(group_id, after_seq, limit)
+    Group->>Group: 合并普通明文 group_messages
+    Group-->>B: messages[]<br/>明文行 version=v1 + payload
+    B->>B: 直接发布 group.message_created
+    B->>Group: group.v2.ack(group_id, up_to_seq)
+```
+
+## GROUP 加密消息
+
+```mermaid
+sequenceDiagram
+    participant A as Sender SDK
+    participant Group as group 服务
+    participant Msg as message 服务
+    participant G as gateway
+    participant B as Member SDK
+
+    A->>Group: group.v2.bootstrap(group_id)
+    Group->>Group: 校验成员资格，读取 epoch/state_chain
+    Group->>Group: 读取 v2_group_devices<br/>group_device_prekey
+    Group->>Msg: message.v2.group_bootstrap(member_aids)
+    Msg-->>Group: fallback P2P device prekeys + audit_recipients
+    Group-->>A: devices + epoch + state_commitment<br/>pending/committed members + audit_recipients
+
+    A->>A: 校验 group state 签名 / 分叉
+    A->>A: 构造 targets<br/>member + self_sync + audit
+    A->>A: 生成 e2ee.group_encrypted envelope<br/>AAD 含 group_id/epoch/state_commitment
+    A->>Group: group.v2.send(group_id, envelope)
+
+    alt 群在异域
+        Group->>G: gateway.forward_federation<br/>namespace=group, method=v2.send
+        G->>Group: 转发到群归属域 group 服务
+    end
+
+    Group->>Group: 校验成员、e2ee_version=v2、epoch 匹配
+    Group->>Group: 校验 AAD/from/group_id/from_device/message_id
+    Group->>Group: 校验 recipients 排序、digest、audit wrap
+    Group->>Group: 写 v2_group_messages 共享密文体
+    Group->>Group: 按 recipient 写 v2_group_wraps
+    Group->>G: dispatch_event(group.v2.message_created)<br/>seq/message_id/sender/member_aids
+    G-->>B: group.v2.message_created 通知
+
+    B->>Group: group.v2.pull(group_id, after_seq, limit)
+    Group-->>B: per-device envelope_json<br/>recipient wrap + merkle_proof
+    B->>B: 选择 group_id 对应 group SPK<br/>fallback 到 P2P SPK 仅兼容旧 wrap
+    B->>B: 验签 / 验 proof / 解 wrap / 解密 payload
+    B-->>B: 发布 group.message_created
+    B->>Group: group.v2.ack(group_id, up_to_seq)
+    B->>B: 若消费 group_device_prekey，异步 rotate_group_spk()
+```
+
+## 核心差异
+
+| 场景 | 发送入口 | 服务端存储 | 接收入口 | 解密位置 |
+|------|----------|------------|----------|----------|
+| P2P 明文 | `message.send(encrypt=false)` | 普通 device message | `message.v2.pull` 合并明文行 | 不解密 |
+| P2P 加密 | `message.send` 承载 `e2ee.p2p_encrypted` | `v2_peer_messages` + `v2_peer_wraps` | `message.v2.pull` | 接收方 SDK |
+| GROUP 明文 | `group.send(encrypt=false)` | `group_messages` + `group_events` | `group.v2.pull` 合并明文行 | 不解密 |
+| GROUP 加密 | `group.v2.send` 承载 `e2ee.group_encrypted` | `v2_group_messages` + `v2_group_wraps` | `group.v2.pull` | 接收方 SDK |
+

package/_packed_docs/sdk/INDEX.md

@@ -10,13 +10,13 @@
 |------|------|
 | [01-快速开始](01-快速开始.md) | 最小示例 · 安装 · 配置 · 核心流程 |
 | [02-WebSocket协议](02-WebSocket协议.md) | 握手流程 · 消息格式 · 裸 WebSocket 示例 |
-| [03-核心概念](03-核心概念.md) | AID · 连接状态机 · 认证流程 · E2EE |
-| [04-连接与认证](04-连接与认证.md) | 创建AID · 连接网关 · 网关发现 · 调用RPC · 事件订阅 |
-| [05-E2EE加密通信](05-E2EE加密通信.md) | E2EE加密消息 · ProtectedHeaders · 会话管理 · 自定义密钥存储 |
-| [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) | V2-only 明文/加密 P2P/GROUP 消息主链路 · Mermaid 时序图 |
-| [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md) | GROUP epoch key 轮换状态 · 竞态条件 · 补测清单 |
-| [GROUP-E2EE现状对比与改进建议](GROUP-E2EE现状对比与改进建议.md) | 当前 GROUP E2EE 实现定位 · 成熟方案对比 · 风险边界 · 分阶段改进建议 |
-| [06-API手册](06-API手册.md) | AUNClient · AuthNamespace · MetaNamespace（信任根列表 / issuer root 更新） · E2EEManager · 内置事件 · RPC手册索引 |
+| [03-核心概念](03-核心概念.md) | AID · 连接状态机 · 认证流程 · E2EE |
+| [04-连接与认证](04-连接与认证.md) | 创建AID · 连接网关 · 网关发现 · 调用RPC · 事件订阅 |
+| [05-E2EE加密通信](05-E2EE加密通信.md) | E2EE加密消息 · ProtectedHeaders · 会话管理 · 自定义密钥存储 |
+| [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) | V2-only 明文/加密 P2P/GROUP 消息主链路 · Mermaid 时序图 |
+| [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md) | GROUP epoch key 轮换状态 · 竞态条件 · 补测清单 |
+| [GROUP-E2EE现状对比与改进建议](GROUP-E2EE现状对比与改进建议.md) | 当前 GROUP E2EE 实现定位 · 成熟方案对比 · 风险边界 · 分阶段改进建议 |
+| [06-API手册](06-API手册.md) | AUNClient · AuthNamespace · MetaNamespace（信任根列表 / issuer root 更新） · E2EEManager · 内置事件 · RPC手册索引 |
 | [07-错误处理](07-错误处理.md) | 错误类层级 · 错误码速查 · 重试策略 |
 | [08-最佳实践](08-最佳实践.md) | 幂等初始化 · 多AID隔离 · 环境变量 · 资源清理 |
 | [10-custody-api-manual](10-custody-api-manual.md) | AID 托管 · 手机号验证码 · 备份恢复 · 跨设备复制 |
@@ -52,11 +52,11 @@
 - **连接状态事件** → [06-API手册](06-API手册.md)
 
 ### E2EE 端到端加密
-- **E2EE 机制概述** → [03-核心概念](03-核心概念.md)
-- **加密消息收发** → [05-E2EE加密通信](05-E2EE加密通信.md)
-- **V2-only P2P/GROUP 明文与加密时序** → [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md)
-- **会话管理** → [05-E2EE加密通信](05-E2EE加密通信.md)
-- **GROUP epoch key 轮换竞态/补测清单** → [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md)
+- **E2EE 机制概述** → [03-核心概念](03-核心概念.md)
+- **加密消息收发** → [05-E2EE加密通信](05-E2EE加密通信.md)
+- **V2-only P2P/GROUP 明文与加密时序** → [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md)
+- **会话管理** → [05-E2EE加密通信](05-E2EE加密通信.md)
+- **GROUP epoch key 轮换竞态/补测清单** → [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md)
 - **GROUP E2EE 现状对比与演进建议** → [GROUP-E2EE现状对比与改进建议](GROUP-E2EE现状对比与改进建议.md)
 - **E2EEManager API** → [06-API手册](06-API手册.md)
 - **E2EE 错误类** → [07-错误处理](07-错误处理.md)
@@ -103,16 +103,16 @@
 SDK 的核心抽象。AID 域名格式身份及本地密钥对管理；连接状态机及自动重连；认证流程（挑战-应答）；E2EE 两级离线加密流程。
 
 ### 04-连接与认证
-SDK 高层封装。`create_aid` + `authenticate` 认证流程；`connect` 参数（含自动重连、心跳、令牌刷新）；`client.call()` RPC 调用模式；`client.on()` 事件订阅。
-
-### 05-E2EE加密通信
-E2EE 完整收发流程（加密发送 + 监听解密 + 后台消息循环）；`protected_headers` 与可验证 `context` 元数据；密钥管理（prekey 缓存 / replay guard / group epoch）；自定义 `KeyStore` / `SecretStore` Protocol。
-
-### E2EE_V2消息通信时序图
-当前 V2-only 实现下的主通信链路图。覆盖 V2 设备密钥注册、P2P 明文、P2P 加密、GROUP 明文、GROUP 加密五条时序；明确 P2P 加密走 `message.send` 承载 `e2ee.p2p_encrypted`，GROUP 加密走 `group.v2.send` 承载 `e2ee.group_encrypted`，接收端统一通过 V2 pull 后由 SDK 解密。
-
-### GROUP-E2EE轮换竞态清单
-GROUP epoch key 两阶段轮换的状态边界和竞态检查项。覆盖 pending 期间成员变更、leader 竞争、分发/ack/commit 失败、stale pending、key recovery、旧 epoch 保留等场景，用于补充测试和实现审查。
+SDK 高层封装。`register_aid` + `authenticate` 认证流程；`connect` 参数（含自动重连、心跳、令牌刷新）；`client.call()` RPC 调用模式；`client.on()` 事件订阅。
+
+### 05-E2EE加密通信
+E2EE 完整收发流程（加密发送 + 监听解密 + 后台消息循环）；`protected_headers` 与可验证 `context` 元数据；密钥管理（prekey 缓存 / replay guard / group epoch）；自定义 `KeyStore` / `SecretStore` Protocol。
+
+### E2EE_V2消息通信时序图
+当前 V2-only 实现下的主通信链路图。覆盖 V2 设备密钥注册、P2P 明文、P2P 加密、GROUP 明文、GROUP 加密五条时序；明确 P2P 加密走 `message.send` 承载 `e2ee.p2p_encrypted`，GROUP 加密走 `group.v2.send` 承载 `e2ee.group_encrypted`，接收端统一通过 V2 pull 后由 SDK 解密。
+
+### GROUP-E2EE轮换竞态清单
+GROUP epoch key 两阶段轮换的状态边界和竞态检查项。覆盖 pending 期间成员变更、leader 竞争、分发/ack/commit 失败、stale pending、key recovery、旧 epoch 保留等场景，用于补充测试和实现审查。
 
 ### GROUP-E2EE现状对比与改进建议
 当前 GROUP E2EE 实现的架构评估。对比 Signal Private Groups、WhatsApp Sender Key、Matrix Megolm 和 MLS，明确 AUN 当前处于“内容 E2EE + 服务端可见成员关系”的安全层级；列出旧 epoch key 恢复、signed group state commit、manifest hash / epoch chain 绑定、多设备模型和 epoch 内前向安全等改进方向。

package/_packed_docs/sdk/README.md

@@ -141,7 +141,7 @@ graph TD
 
 | 命名空间 | 职责 | 关键方法 |
 |----------|------|----------|
-| `auth.*` | 身份认证、JWT 签发与刷新 | create_aid / authenticate / refresh_token |
+| `auth.*` | 身份认证、JWT 签发与刷新 | register_aid / authenticate / refresh_token |
 | `peer.*` | 对等认证、证书互验 | hello / verify / establish |
 | `relay.*` | 中继注册与转发 | register / forward / unregister |
 | `message.*` | 消息收发、离线队列、P2P 思考内容 | send / pull / ack / recall / thought.put / thought.get |
@@ -212,7 +212,7 @@ sequenceDiagram
 ```mermaid
 stateDiagram-v2
     [*] --> 未注册
-    未注册 --> 已注册: create_aid（生成密钥对 + 签发证书）
+    未注册 --> 已注册: register_aid（生成密钥对 + 签发证书）
     已注册 --> 已认证: authenticate（Challenge-Response）
     已认证 --> 已连接: connect（WebSocket）
     已连接 --> 已连接: call / on（业务操作）
@@ -261,7 +261,7 @@ async def create_client(aid: str) -> tuple[AUNClient, dict]:
     client = AUNClient({"aun_path": f"~/.aun/{aid}"})
     identity = client._auth.load_identity_or_none(aid)
     if not identity:
-        await client.auth.create_aid({"aid": aid})
+        await client.auth.register_aid({"aid": aid})
     auth = await client.auth.authenticate({"aid": aid})
     return client, auth
 

package/dist/auth.d.ts

@@ -64,10 +64,26 @@ export declare class AuthFlow {
         slotId?: string;
     }): void;
     /**
-     * 创建 AID 并注册到 Gateway。
-     * 如果 AID 已在服务端注册但本地证书丢失，尝试从 PKI 端点下载恢复。
+     * 注册新 AID（原子流程，必须由应用层显式调用）。
+     *
+     * 安全约束（与 Python register_aid 对齐）：
+     *   - **绝不**被 SDK 内部任何路径自动调用（authenticate / connect / 等）
+     *   - 本地已有任何痕迹 → 抛 IdentityConflictError，应用层应改用 loadIdentity
+     *   - 服务端已注册同名 AID → 抛 IdentityConflictError
+     *
+     * 异常分支与恢复：
+     *   A. 全新流程：临时目录生成 keypair → RPC → cert → 原子 rename
+     *   B. 恢复流程：上次 RPC 没收到响应就崩溃；扫描 _pending，公钥匹配
+     *      则下载 cert 完成 promote（防止"已注册但本地没保存"）
      */
-    createAid(gatewayUrl: string, aid: string): Promise<JsonObject>;
+    registerAid(gatewayUrl: string, aid: string): Promise<JsonObject>;
+    /**
+     * 检查 AIDs/_pending/ 下是否有该 aid 的残留，尝试恢复（崩溃恢复）。
+     * 返回 dict 表示恢复成功；null 表示无残留 / 残留已清理；抛错表示明确失败。
+     */
+    private _tryRecoverPendingRegistration;
+    private _writePendingKeypair;
+    private _writePendingCert;
     /**
      * 认证（登录）到 Gateway。
      * 执行两阶段挑战-应答认证，返回 token 信息。
@@ -115,6 +131,10 @@ export declare class AuthFlow {
      * 用于 E2EE 握手中验证通信对端的身份证书。
      */
     verifyPeerCertificate(gatewayUrl: string, certPem: string, expectedAid: string): Promise<void>;
+    /** 预置 Gateway CA 链材料，但不标记为已验证。 */
+    cacheGatewayCaChain(gatewayUrl: string, caChainPems: string[], chainAid?: string): void;
+    /** 丢弃预置或缓存的 Gateway CA 链材料。 */
+    discardGatewayCaChain(gatewayUrl: string, chainAid?: string): void;
     /**
      * 通过临时 WebSocket 发送单次 JSON-RPC 请求。
      * 流程：连接 → 接收 challenge → 发送请求 → 接收响应 → 关闭。
@@ -255,6 +275,23 @@ export declare class AuthFlow {
      * 本地有密钥但无证书、服务端已注册时使用。
      */
     private _recoverCertViaDownload;
+    /**
+     * 验证本地身份是否适合复用 cached token（不走网络）。
+     * 返回空字符串表示通过；非空字符串表示不通过的原因。
+     * 公钥不匹配时直接抛 AuthError（严重安全问题，不能静默降级）。
+     */
+    private _validateCachedCredentials;
+    /**
+     * 防线 B：authenticate 在调 _login 前显式校验 cert 与本地 keypair 公钥一致。
+     * 命中即抛 AuthError，绝不发起两步登录。
+     */
+    private _assertCertMatchesLocalKeypair;
+    /**
+     * 通过 PKI HTTP 端点下载服务端登记的证书。
+     * 404 / 找不到 → 返回 null（视为未注册）；其它 HTTP 错抛 AuthError。
+     * 该方法既用于 recover 路径，也用于 registerAid 全新注册前的查重前置。
+     */
+    protected _downloadRegisteredCert(gatewayUrl: string, aid: string): Promise<string | null>;
     /**
      * 验证服务端返回的 new_cert，通过后才正式接受。
      * 安全要点：CN/公钥/时间 + 完整链验证 + 受信根锚定 + CRL/OCSP。
@@ -272,12 +309,8 @@ export declare class AuthFlow {
     private static _getCachedAccessToken;
     private static readonly _AID_NAME_RE;
     private static _validateAidName;
-    /** 确保本地有指定 AID 的身份（不存在则创建密钥对） */
-    private _ensureLocalIdentity;
-    /** 加载身份信息，不存在时抛出 StateError */
+    /** 加载身份信息，不存在或半成品时抛出 StateError */
     private _loadIdentityOrRaise;
-    /** 确保有身份（不存在时自动创建密钥对） */
-    private _ensureIdentity;
     private _loadInstanceState;
     private _persistIdentity;
     /** 从 challenge 消息中提取 nonce */