@agentunion/fastaun-browser 0.5.3 → 0.5.6

package/_packed_docs/cli/CLI/346/211/213/345/206/214.md

@@ -282,10 +282,12 @@ aun agentmd check bob.agentid.pub --max-unsynced-days 1
 密钥：
 
 ```powershell
-aun keys list
-aun keys rotate --type spk
-aun keys change-seed --old-seed .seed --new-seed "new-seed"
-```
+aun keys list
+aun keys rotate --type spk
+aun keys change-seed --old-seed "current-seed" --new-seed "new-seed"
+```
+
+SDK 正常启动和密钥读取只使用显式传入的 seed，不会自动读取 `.seed` 或回退到 `.seed.migrated.*`。显式执行 `change-seed` 时，`--old-seed` 可以直接提供当前 seed_password；传入 `.seed` 则明确要求迁移 `{aun_path}/.seed`，仅在迁移成功后归档旧文件。
 
 诊断：
 

package/_packed_docs/protocol/06-/346/234/215/345/212/241/345/215/217/350/256/256.md

@@ -16,7 +16,7 @@
 |---------|------|------|---------|---------|
 | `auth.*` | 核心 | AID 注册、认证、令牌管理 | auth 服务 | WebSocket |
 | `ca.*` | 核心 | 证书签发、续期、吊销 | ca 服务 | WebSocket / HTTP |
-| `message.*` | 核心 | 点对点消息路由、E2EE V2 设备密钥/bootstrap | message 服务 | WebSocket |
+| `message.*` | 核心 | 点对点消息路由、E2EE prekey 管理 | message 服务 | WebSocket |
 | `meta.*` | 核心 | 健康检查、状态查询、受信根证书 | meta 服务 | WebSocket |
 | `storage.*` | 扩展 | 对象存储、大文件上传下载（详见 [11-Storage-子协议.md](11-Storage-子协议.md)） | storage 服务 | WebSocket + HTTP |
 | `group.*` | 扩展 | 群组管理、群消息、资源共享（详见 [10-Group-子协议.md](10-Group-子协议.md)） | group 服务 | WebSocket |
@@ -290,7 +290,7 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
 |------|:----:|------|
 | `to` | ✅ | 接收者 AID |
 | `payload` | ✅ | 消息载荷，对协议层透明，由应用层定义 |
-| `type` | ❌ | 信封/封装类型，普通业务消息无需填写；SDK V2 加密发送时自动使用 `e2ee.p2p_encrypted` |
+| `type` | ❌ | 信封/封装类型，普通业务消息无需填写；SDK 加密发送时自动使用 `e2ee.encrypted` |
 | `encrypted` | ❌ | E2EE 标记（默认 `false`） |
 | `message_id` | ❌ | 幂等键（客户端提供或服务端生成 UUID） |
 | `timestamp` | ❌ | 客户端时间戳（毫秒），服务端忽略此字段，始终使用服务端时间 |
@@ -382,9 +382,10 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
 | 参数 | 必需 | 说明 |
 |------|:----:|------|
 | `after_seq` | ❌ | 起始序列号（默认 0），返回 `seq > after_seq` 的消息 |
-| `limit` | ❌ | 单次返回上限（默认 50，最大 50；`pull_max_limit` 配置只能进一步收紧） |
+| `limit` | ❌ | 单次返回上限（默认 50，最大 50） |
 | `device_id` | ❌ | 多实例消费上下文中的设备标识；缺省时使用连接认证上下文 |
 | `slot_id` | ❌ | 同一设备下的消费槽位；空字符串表示设备单实例模式 |
+| `window_mode` | ❌ | 可选 Pull 模式；`tail` 表示读取以安全 Head 结尾的最新一页 |
 
 **响应**：
 ```json
@@ -419,11 +420,48 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
 | `ephemeral_earliest_available_seq` | integer\|null | 当前临时缓冲中最早可用的 `seq`，`null` 表示无临时消息 |
 | `ephemeral_dropped_count` | integer | 因缓冲淘汰而丢弃的临时消息计数 |
 
-> 客户端可通过 `ephemeral_earliest_available_seq` 判断是否有临时消息丢失：若 `after_seq < ephemeral_earliest_available_seq`，说明存在已被淘汰的消息。
-
-**说明**：不修改消息状态，多设备安全（各 `(aid, device_id, slot_id)` 维护各自的 `after_seq`），同一 `after_seq` 多次调用返回相同结果（幂等）。显式传入的 `device_id` / `slot_id` 若与连接认证上下文不一致，服务端 **MUST** 拒绝请求。
-
-#### `message.ack`
+> 客户端可通过 `ephemeral_earliest_available_seq` 判断是否有临时消息丢失：若 `after_seq < ephemeral_earliest_available_seq`，说明存在已被淘汰的消息。
+
+**说明**：不修改消息状态，多设备安全（各 `(aid, device_id, slot_id)` 维护各自的 `after_seq`），同一 `after_seq` 多次调用返回相同结果（幂等）。显式传入的 `device_id` / `slot_id` 若与连接认证上下文不一致，服务端 **MUST** 拒绝请求。
+
+**Tail 模式**：`window_mode="tail"` 时，服务端固定安全 `head_seq`，返回跨度不超过 `limit` 的最新 seq band，并额外返回：
+
+| 字段 | 说明 |
+|------|------|
+| `window_mode` | 固定为 `tail` |
+| `window_start_seq` | 已扫描窗口的包含式左边界 |
+| `head_seq` | 本次请求固定的安全 Head |
+| `covered_through_seq` | 覆盖终点，正常等于 `head_seq` |
+
+Tail 不推进 ACK、retention/visibility floor、Pull activity 或 catch-up 状态，不接受 `ack_up_to_seq` 或 `force=true`。seq band 内未返回的序号视为服务端永久空号，客户端不得为页内缺号创建 Gap。无 `window_mode` 的旧请求必须保持原请求、响应和副作用语义，以兼容旧 SDK。
+
+#### `message.history`
+
+按 `before_seq` 排他上界向前只读翻页，不修改 ACK、cursor、floor 或 Pull activity。
+
+**参数**：
+
+| 参数 | 必需 | 说明 |
+|------|:----:|------|
+| `before_seq` | ✅ | 正整数排他上界，只返回 `seq < before_seq` 的消息 |
+| `limit` | ❌ | 单页上限（默认 50，最大 50） |
+
+**响应字段**：
+
+| 字段 | 说明 |
+|------|------|
+| `messages` | 页内按 seq 升序 |
+| `window_start_seq` | 本页最小边界；空页为 `null` |
+| `next_before_seq` | 下一页直接使用的排他上界；无更早消息为 `null` |
+| `has_older` | 是否仍有更早的可见消息 |
+| `retention_floor_seq` | 已实际删除、不可恢复的 seq 下界 |
+| `earliest_available_seq` | 当前最早可拉取边界 |
+
+History 不触发实时消息事件。客户端解密 History 结果时不得修改实时 A/T/H 或发送 ACK。
+
+**客户端发布语义**：单个通过校验的 Tail/Forward 响应页内必须按 seq 升序处理，并折叠页内重复 seq。A/T/H 只描述扫描进度，不是应用发布账本；Tail 与 Forward 窗口可重叠，排队超时旁路也可能使多个响应并发完成，因此跨 Push/Tail/Forward 页不承诺唯一或有序。全局去重与排序属于应用层业务仓库职责，不是 SDK 交付契约；应用层必须在 namespace 内按 `message_id` 幂等，并按 `seq` 排序。SDK 进程内折叠只能作为 best-effort 优化。History 不进入实时发布流。
+
+#### `message.ack`
 
 确认已收到消息，推进服务端 ack 游标。
 
@@ -1288,25 +1326,25 @@ event/task.delegated      # 已创建子任务
 
 ### 6.7 端到端加密（E2EE）摘要
 
-> 当前 V2 主路径见 [E2EE_V2消息通信时序图](../sdk/E2EE_V2消息通信时序图.md)、[05-E2EE加密通信](../sdk/05-E2EE加密通信.md) 和 [08-AUN-E2EE-Group.md](08-AUN-E2EE-Group.md)。[08-AUN-E2EE.md](08-AUN-E2EE.md) 仅保留 legacy P2P 信封说明。本节仅保留摘要。
+> 规范性定义见 [08-AUN-E2EE.md](08-AUN-E2EE.md)。本节仅保留摘要。
 
 **核心原则**：
 
 - E2EE 加解密**完全由客户端实现**，无需在线协商
-- 服务端只做认证、路由、设备密钥/群状态查询、密文存储和事件通知，对明文内容完全透明
-- P2P 加密消息通过 `message.send` 承载 V2 `e2ee.p2p_encrypted` envelope；群加密消息通过 `group.v2.send` 承载 V2 `e2ee.group_encrypted` envelope
-- 当前主路径为 V2 多设备 wrap：每条消息一把 `master_key`，按 recipient 设备分别生成 `3DH` / `1DH` wrap，并由接收端验证 `sender_signature`、AAD 和 recipient proof / digest
-
-**服务端兼容性要求**：
-
-- 接受并转发 V2 E2EE envelope；兼容旧 `encrypted: true` 标志
-- 在离线队列和历史消息中存储密文 payload
-- 不对密文 payload 施加额外的语义解析要求
-- 提供 `message.v2.put_peer_pk`、`message.v2.bootstrap`、`group.v2.put_group_pk`、`group.v2.bootstrap` 等 V2 设备密钥和 bootstrap RPC
+- 服务端只做消息中转和 prekey 存储，对加密内容完全透明
+- 加密消息通过 `message.send` 的 `encrypted: true` 标志标识
+- 两级降级：prekey_ecdh_v2（优先，四路 ECDH）→ long_term_key（降级）
+
+**服务端兼容性要求**：
+
+- 接受并转发 `encrypted: true` 的消息
+- 在离线队列和历史消息中存储密文 payload
+- 不对密文 payload 施加额外的语义解析要求
+- 提供 `message.e2ee.put_prekey` / `message.e2ee.get_prekey` RPC
 
 **互操作要求**：
 
-跨语言、跨平台 SDK 的当前互操作以 E2EE V2 多设备 wrap 为准：P2P 参见 SDK V2 时序和各语言 `v2/e2ee` 实现，群组参见 [08-AUN-E2EE-Group.md](08-AUN-E2EE-Group.md)。旧 `e2ee.encrypted` 信封互操作才查 [08-AUN-E2EE.md](08-AUN-E2EE.md)。
+跨语言、跨平台 SDK 的互操作必须以 [08-AUN-E2EE.md](08-AUN-E2EE.md) 中定义的算法套件、密文 payload 格式、AAD 字段、重放保护规则为准。
 
 **错误码**：