@agentunion/fastaun-browser 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

@@ -60,14 +60,12 @@ export declare class AuthFlow {
         slotId?: string;
     }): void;
     /**
-     * 注册新 AID。
+     * 严格注册新 AID（对齐 TS registerAid / Go RegisterAID）。
      *
-     * 流程：
-     *   1. 确保本地密钥对存在
-     *   2. 短连接 RPC 调用 auth.create_aid
-     *   3. 保存返回的证书
+     * 注册与认证彻底分离：此方法绝不被 SDK 内部自动调用，
+     * 必须由应用层显式调用。
      */
-    createAid(gatewayUrl: string, aid: string): Promise<JsonObject>;
+    registerAid(gatewayUrl: string, aid: string): Promise<JsonObject>;
     /**
      * 认证已有 AID — login1/login2 双阶段流程。
      *
@@ -76,7 +74,7 @@ export declare class AuthFlow {
      */
     authenticate(gatewayUrl: string, aid?: string): Promise<JsonObject>;
     /**
-     * 确保已认证（如无身份则先注册再登录）。
+     * 确保已认证。注册和登录彻底分离：无身份或无 cert 直接抛错。
      */
     ensureAuthenticated(gatewayUrl: string): Promise<AuthContext>;
     /**
@@ -117,6 +115,10 @@ export declare class AuthFlow {
     /** fetch GET 返回 JSON */
     private _fetchJson;
     private _createAid;
+    /** 下载服务端当前登记的证书；未注册返回 null */
+    private _downloadRegisteredCert;
+    /** 防线 B：cert 公钥必须与本地 keypair 公钥一致，否则拒绝登录 */
+    private _assertCertMatchesLocalKeypair;
     /** 下载已注册证书恢复本地状态 */
     private _recoverCertViaDownload;
     private _login;
@@ -153,11 +155,8 @@ export declare class AuthFlow {
     private static readonly _AID_NAME_RE;
     private static _validateAidName;
     /** 确保本地有密钥对（没有则生成） */
-    private _ensureLocalIdentity;
-    /** 加载身份，不存在时抛出异常 */
+    /** 加载身份，不存在或半成品时抛出异常 */
     private _loadIdentityOrRaise;
-    /** 确保有身份（无则尝试生成） */
-    private _ensureIdentity;
     private _loadInstanceState;
     private _persistIdentity;
     /** 清理过期的 gateway 缓存条目（供外部定时调用） */

package/dist/auth.d.ts.map

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