@agentunion/fastaun-browser 0.5.1 → 0.5.2

package/_packed_docs/sdk/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md

@@ -105,12 +105,15 @@ print(auth["access_token"], auth["gateway"])
 ### 连接
 
 ```python
-await client.connect({
-    "slot_id": "main",
-    "connection_kind": "long",
-    "auto_reconnect": True,
-    "heartbeat_interval": 30.0,
-    "token_refresh_before": 60.0,
+await client.connect({
+    "slot_id": "main",
+    "connection_kind": "long",
+    "delivery_mode": {"mode": "fanout"},
+    "background_sync": True,
+    "extra_info": {"app": "demo"},
+    "auto_reconnect": True,
+    "heartbeat_interval": 30.0,
+    "token_refresh_before": 60.0,
     "retry": {
         "initial_delay": 1.0,
         "max_delay": 64.0,
@@ -126,12 +129,14 @@ await client.connect({
 | 选项 | 说明 |
 |------|------|
 | `slot_id` | 同一设备内的实例槽位；允许 `/`、`:`、空格作为共享隔离键分隔符 |
-| `connection_kind` | `"long"` 或 `"short"` |
-| `short_ttl_ms` | 短连接服务端兜底超时 |
-| `delivery_mode` | 连接级投递语义 |
-| `auto_reconnect` | 断线后是否自动重连 |
-| `heartbeat_interval` | 心跳间隔，秒 |
-| `token_refresh_before` | token 过期前刷新提前量，秒 |
+| `connection_kind` | `"long"` 或 `"short"` |
+| `short_ttl_ms` | 短连接服务端兜底超时 |
+| `delivery_mode` | 连接级投递语义 |
+| `extra_info` | 应用层自定义连接信息；下划线开头的键不会透传给 Gateway |
+| `background_sync` | 连接成功后是否执行 SDK 后台补洞 / 未读同步，默认开启 |
+| `auto_reconnect` | 断线后是否自动重连 |
+| `heartbeat_interval` | 心跳间隔，秒 |
+| `token_refresh_before` | token 过期前刷新提前量，秒 |
 | `retry.initial_delay` / `retry.max_delay` | 退避重连参数 |
 | `timeouts.connect/call/http` | 连接、RPC、HTTP 超时 |
 
@@ -188,10 +193,11 @@ print(client.can_connect, client.can_send, client.is_online)
 
 | 事件 | 说明 |
 |------|------|
-| `state_change` | 状态变化，payload 中的 `state` 是九态公开值 |
-| `connection.error` | 连接、认证、重连错误 |
-| `token.refreshed` | token 自动刷新完成 |
-| `message.received` | 收到消息 |
+| `state_change` | 状态变化，payload 中的 `state` 是九态公开值 |
+| `connection.error` | 连接、认证、重连错误 |
+| `token.refreshed` | token 自动刷新完成 |
+| `token.refresh_exhausted` | refresh_token 缺失、过期或刷新链耗尽，SDK 已清理本地 token，下一次重连会重新走完整登录 |
+| `message.received` | 收到消息 |
 | `group.changed` | 群组事件 |
 | `message.undecryptable` / `group.message_undecryptable` | E2EE 解密失败 |
 
@@ -238,8 +244,10 @@ state = await store.check_agent_md("bob.agentid.pub", ttl_days=1)
 | `AUNClient` | 连接、事件和 RPC 调用；不再暴露 agent.md 上传入口 |
 
 本地落盘位置由 SDK 管理。Python / TypeScript / Go 写入 `{aun_path}/AIDs/{aid}/agent.md` 和同目录 `agentmd.json`；浏览器 JavaScript 写入 IndexedDB 的等价 logical key，存储不可用时退化为内存缓存。agent.md 不写入 SQLite，也不再使用旧 `{aun_path}/AgentMDs` 目录。
-
----
+
+连接后的 RPC 响应、事件推送和消息信封会被 SDK 自动观察：Gateway `_meta.agent_md_etags` 中的 `requester`、`peer`、`group` 以及兼容别名 `receiver`、`target`、`to`、`sender`、`from` 会更新对应 AID 的 `remote_etag` / `last_modified`；V2 信封中的 `agent_md.sender` 和 `agent_md.group` 也会写入同一份本地记录。`group` 表示群自身 `group_aid` / `group_id` 的 agent.md，缺少 `aid` 时 SDK 会从信封顶层或 AAD 的 `group_aid` / `group_id` 兜底。
+
+---
 
 ## RPC 调用
 

package/_packed_docs/sdk/05-E2EE/345/212/240/345/257/206/351/200/232/344/277/241.md

@@ -41,14 +41,14 @@ await client.call("message.send", {
 })
 ```
 
-SDK 优先使用 prekey_ecdh_v2，并默认要求前向保密：
-
-1. **prekey_ecdh_v2** — 对方有预上传的 prekey，四路 ECDH（ephemeral×prekey + ephemeral×identity + sender×prekey + sender×identity），前向安全，附带发送方签名
-2. **long_term_key** — 对方无 prekey，双路 ECDH（ephemeral×recipient_identity + sender×recipient_identity）+ HKDF 派生密钥（降级模式），附带发送方签名
-
-> Python SDK 默认 `require_forward_secrecy=true`，当加密结果不满足前向保密（无论是因为无 prekey 还是 prekey 加密失败降级到 long_term_key）时拒绝发送并抛出错误。需显式配置 `require_forward_secrecy=false` 才允许降级。
-
-每条消息独立生成临时 ECDH 密钥对，实现一消息一密钥。
+当前 SDK 使用 E2EE V2 多设备 wrap 主路径：
+
+1. 发送前通过 `message.v2.bootstrap` 或 `group.v2.bootstrap` 获取接收方当前活跃设备、设备 prekey、self-sync 设备和 audit recipients。
+2. SDK 为每条消息生成独立 `master_key`、消息 nonce 和发送方临时 session key，只加密一次正文。
+3. SDK 为每个接收设备生成一条 recipient wrap。设备有可用 SPK 时使用 `3DH` wrap；缺少 SPK 的兼容场景才使用 `1DH` wrap。
+4. E2EE 信封包含 `sender_signature`、AAD、`recipients_digest` / Merkle proof，接收端必须验签、验 AAD、验 recipient proof 后再解密。
+
+每条消息独立密钥；V2 当前主路径不再使用旧 `prekey_ecdh_v2` / `long_term_key` 信封作为默认发送格式。旧术语只用于历史兼容文档或迁移排查。
 
 ## ProtectedHeaders 与可验证上下文
 
@@ -65,9 +65,11 @@ SDK 优先使用 prekey_ecdh_v2，并默认要求前向保密：
 
 `payload_type` 不需要应用层传入。SDK 会读取加密前 `payload.type`，自动写入 `protected_headers.payload_type`，接收端解密后会校验它与明文 `payload.type` 一致。
 
-`protected_headers` / `headers` 是 send/thought 参数的顶层字段，不放入单独的 `envelope` 入参对象，也不属于业务 `payload`。裸 WebSocket 客户端若自行发送已加密信封，需要把 protected headers 放在自构造的 E2EE 信封内并自行完成 `_auth`，服务端不会替裸 RPC 调用生成或校验明文侧的 protected headers。
-
-示例：
+`protected_headers` / `headers` 是 send/thought 参数的顶层字段，不放入单独的 `envelope` 入参对象，也不属于业务 `payload`。裸 WebSocket 客户端若自行发送已加密信封，需要把 protected headers 放在自构造的 E2EE 信封内并自行完成 `_auth`，服务端不会替裸 RPC 调用生成或校验明文侧的 protected headers。
+
+`agent_md` 是独立于 E2EE 的版本提示元数据，不属于 `protected_headers`，也不参与 AAD 或业务鉴权。当前 Message Service V2 P2P 信封可携带 `agent_md.sender`；SDK 也识别 `agent_md.group`。Gateway 在 RPC response / event push 的 `_meta.agent_md_etags` 中注入 `requester`、`peer`、`group`，四端 SDK 会自动写入对应 AID 的 `remote_etag` / `last_modified`，后续仍以下载后的 agent.md 签名验证作为可信依据。
+
+示例：
 
 ```python
 from aun_core import ProtectedHeaders
@@ -103,7 +105,8 @@ await client.call("group.send", {
 
 ```json
 {
-  "type": "e2ee.encrypted",
+  "type": "e2ee.p2p_encrypted",
+  "version": "v2",
   "ciphertext": "...",
   "protected_headers": {
     "device_id": "dev-123",
@@ -127,8 +130,8 @@ await client.call("group.send", {
 
 计算规则：
 
-1. 解密流程会派生出本条消息的 `message_key`。
-2. `metadata_key = HMAC-SHA256(message_key, "aun-envelope-metadata-key-v1")`。
+1. 解密流程会得到本条消息的 `master_key`。
+2. `metadata_key = HMAC-SHA256(master_key, "aun-envelope-metadata-key-v1")`。
 3. 对字典去掉 `_auth` 后做 canonical JSON：UTF-8、key 排序、紧凑分隔符。
 4. `tag = HMAC-SHA256(metadata_key, domain + "\0" + canonical_json(body))`。
 5. `domain` 对 `protected_headers` 为 `aun-protected-headers-v1`，对 `context` 为 `aun-protected-context-v1`。
@@ -294,24 +297,20 @@ for msg in result["messages"]:
 
 ---
 
-## Prekey 管理
-
-连接时 SDK 自动上传 prekey，并定时轮换（默认每小时）。一般无需手动管理。
-
-手动上传 prekey：
-
-```python
-# 通过 AUNClient 上传（生成 + RPC）
-await client._upload_prekey()
-```
-
-底层 API（E2EEManager 只生成材料，不做 RPC）：
-
-```python
-prekey_material = client.e2ee.generate_prekey()
-# 返回 {"prekey_id": "...", "public_key": "...", "signature": "...", "created_at": ...}
-# 需要自行上传：await transport.call("message.e2ee.put_prekey", prekey_material)
-```
+## V2 设备公钥与 SPK 管理
+
+连接成功后，SDK 会初始化本设备 V2 session，生成或加载 IK / SPK，并通过 `message.v2.put_peer_pk` 幂等注册当前 P2P 设备 SPK。群组路径会按群生成独立 group SPK，并通过 `group.v2.put_group_pk` 注册。应用层一般无需手动管理这些密钥。
+
+当前主路径的要点：
+
+- P2P 设备 SPK 的 `key_source` 为 `peer_device_prekey`，由 AID 私钥签名背书。
+- 群内独立 group SPK 的 `key_source` 为 `group_device_prekey`，按规范化后的 `group_aid` 隔离。
+- SDK 发送前通过 `message.v2.bootstrap` / `group.v2.bootstrap` 获取目标设备集合和当前 SPK。
+- 旧 SPK 会在本地保留一段安全窗口，用于解密引用旧 SPK 的历史消息；满足已消费和保留窗口条件后才销毁。
+
+裸 WebSocket 客户端如果绕过 SDK，需要自行完成同等的 SPK 生成、AID 私钥签名、注册和 bootstrap 逻辑。旧 `message.e2ee.put_prekey/get_prekey` 只用于 legacy `prekey_ecdh_v2` 信封兼容，不是当前 SDK 的默认路径。
+
+SPK 签名里的 `spk_timestamp` 使用 Unix 秒；消息、群事件和服务端 `timestamp` / `created_at` 等主路径时间字段仍使用 Unix 毫秒。
 
 ---
 
@@ -361,7 +360,7 @@ client = AUNClient(aid)
 | P2P 消息默认要求发送方签名 | 无 `sender_signature` 的消息被拒绝 |
 | 群组消息默认要求发送方签名 | `require_signature=True`，无签名或无发送方证书的消息被拒绝 |
 | 群组 E2EE 为固定启用能力 | `group_e2ee=true`，不可关闭 |
-| 默认要求前向保密 | `require_forward_secrecy=true`，无 prekey 时拒绝 long_term_key 降级 |
-| 客户端操作签名 | `group.send`/`group.kick`/`group.add_member`/`group.leave` 等操作自动附加 `client_signature`，服务端强制验签 |
+| 默认要求前向保密 | V2 优先使用设备 SPK 的 `3DH` wrap；缺少 SPK 的 `1DH` 路径仅作为兼容降级 |
+| 客户端操作签名 | SDK 会为关键操作附加 `client_signature`；Gateway 对 `send/pull/ack` 等常规 RPC 优先使用连接级身份认证，只有身份声明与连接不一致、敏感操作、能力身份或主动携签场景才执行 ECDSA 验签 |
 
 

package/_packed_docs/sdk/06-API/346/211/213/345/206/214.md

@@ -116,9 +116,11 @@ Python、TS/Node 与 Go 的 `AIDStore` 本地方法返回 Result 包装；浏览
 | `cached` | bool | 是否命中 TTL 窗口内的本地检查记录 |
 | `verify_status` / `verify_error` | str | 最近一次下载验签状态 |
 
-agent.md 本地记录不写入 SQLite。Python / TypeScript / Go 使用 `{aun_path}/AIDs/{aid}/agent.md` 与 `agentmd.json`；浏览器 JavaScript 使用 IndexedDB 等价 key，存储不可用时退化为内存缓存。
-
-> **v0.4.2 变更**：`discoveryPort` 配置项已移除，Gateway 地址完全由 SDK 根据 AID issuer 自动发现，无需手动指定端口。
+agent.md 本地记录不写入 SQLite。Python / TypeScript / Go 使用 `{aun_path}/AIDs/{aid}/agent.md` 与 `agentmd.json`；浏览器 JavaScript 使用 IndexedDB 等价 key，存储不可用时退化为内存缓存。
+
+`remote_etag` / `last_modified` 除了来自 `check_agent_md()` 的 HEAD，也会由连接后的内部观察器更新：SDK 会读取 RPC response / event push `_meta.agent_md_etags` 的 `requester`、`peer`、`group` 及兼容别名，并读取 V2 envelope 的 `agent_md.sender` / `agent_md.group`。`group` 记录使用群自身 `group_aid` / `group_id` 作为 AID key。
+
+> **v0.4.2 变更**：`discoveryPort` 配置项已移除，Gateway 地址完全由 SDK 根据 AID issuer 自动发现，无需手动指定端口。
 
 ---
 
@@ -260,7 +262,7 @@ await client.call("meta.trust_roots", {})
 ```python
 await client.notify("notification/client.activity", {"state": "idle"})
 await client.notify("event/app.typing", {"thread_id": "t1"}, to="bob.agentid.pub", ttl_ms=5000)
-await client.notify("event/app.presence", {"state": "active"}, group_id="group.agentid.pub/123")
+await client.notify("event/app.presence", {"state": "active"}, group_id="g-abc123.agentid.pub")
 ```
 
 路由选项：
@@ -268,7 +270,7 @@ await client.notify("event/app.presence", {"state": "active"}, group_id="group.a
 | 选项 | 说明 |
 |------|------|
 | `to` / `To` | 目标 AID；可同域或跨域 |
-| `group_id` / `groupId` / `GroupID` | 目标群；与 `to` 互斥 |
+| `group_id` / `groupId` / `GroupID` | 目标群；兼容参数名，值使用目标态 `group_aid`，与 `to` 互斥 |
 | `device_id` / `deviceId` / `DeviceID` | 限定目标 AID 的在线设备；必须配合 `to` |
 | `slot_id` / `slotId` / `SlotID` | 限定目标设备的在线 slot；必须配合 `device_id` |
 | `ttl_ms` / `ttlMs` / `TTLMS` | `0..60000`，只控制在线投递过期，不表示离线缓存 |
@@ -307,10 +309,11 @@ headers = client.get_protected_headers()
 
 说明：
 
-- agent.md 上传、下载和检查入口都在 `AIDStore`；`AUNClient` 不再暴露上传入口。
-- 上传要求目标 AID 已在本地加载且私钥有效；SDK 会对正文签名，并通过 `AuthFlow` 获取或复用该 AID 的 access_token。
-- SDK 发起 GET 时只发送 `Accept: text/markdown`，不主动发送 `If-None-Match` / `If-Modified-Since`。如果服务端异常返回 304，本地有内容则复用；无内容时再发一次无条件 GET。
-- `Accept: text/markdown` 与 agent.md 的 YAML frontmatter + Markdown 格式兼容；agent.md 仍是 Markdown 媒体类型上的结构化约定。
+- agent.md 上传、下载和检查入口都在 `AIDStore`；`AUNClient` 不再暴露上传入口。
+- 上传要求目标 AID 已在本地加载且私钥有效；SDK 会对正文签名，并通过 `AuthFlow` 获取或复用该 AID 的 access_token。
+- SDK 发起 GET 时只发送 `Accept: text/markdown`，不主动发送 `If-None-Match` / `If-Modified-Since`。如果服务端异常返回 304，本地有内容则复用；无内容时再发一次无条件 GET。
+- SDK 会自动从 Gateway `_meta.agent_md_etags` 和信封 `agent_md` 观察远端版本；`requester`、`peer`、`group` 是标准角色键，`receiver`、`target`、`to`、`sender`、`from` 是兼容别名。
+- `Accept: text/markdown` 与 agent.md 的 YAML frontmatter + Markdown 格式兼容；agent.md 仍是 Markdown 媒体类型上的结构化约定。
 
 ---
 
@@ -415,14 +418,16 @@ sub.unsubscribe()
 
 | 事件 | 说明 |
 |------|------|
-| `state_change` | 状态变化，`state` 为九态公开值 |
-| `connection.error` | 连接或重连错误 |
-| `token.refreshed` | token 刷新完成 |
-| `message.received` | 收到 P2P 消息 |
-| `message.ack` | 消息 ack |
-| `message.undecryptable` | P2P E2EE 解密失败 |
-| `group.changed` | 群组事件 |
-| `group.message_undecryptable` | 群 E2EE 解密失败 |
+| `state_change` | 状态变化，`state` 为九态公开值 |
+| `connection.error` | 连接或重连错误 |
+| `token.refreshed` | token 刷新完成 |
+| `token.refresh_exhausted` | refresh_token 缺失、过期或刷新链耗尽，SDK 已清理本地 token 并等待重新登录 |
+| `message.received` | 收到 P2P 消息 |
+| `message.ack` | 消息 ack |
+| `message.undecryptable` | P2P E2EE 解密失败 |
+| `group.changed` | 群组事件 |
+| `group.message_undecryptable` | 群 E2EE 解密失败 |
+| `storage.object_changed` | Storage 对象变更事件透传 |
 
 ---
 

package/_packed_docs/sdk/07-/351/224/231/350/257/257/345/244/204/347/220/206.md

@@ -143,12 +143,16 @@ await client.call("message.send", params)  # 非 ready 状态会抛 ConnectionEr
 发送前检查：
 
 ```python
-if not client.can_send:
-    await client.connect({"auto_reconnect": True})
-```
-
-### E2EE 解密失败
-
-P2P 或群消息解密失败通常由 prekey 不匹配、AAD 篡改、密文损坏或群 epoch 不一致引起。SDK 会发布 `message.undecryptable` / `group.message_undecryptable` 事件，应用可记录并继续处理其他消息。
+if not client.can_send:
+    await client.connect({"auto_reconnect": True})
+```
+
+### refresh_token 失效
+
+当自动刷新命中 `missing refresh_token`、`invalid_or_expired_refresh_token`、刷新链耗尽或服务端返回 `relogin_required=true` 时，SDK 会清理本地 `access_token` / `refresh_token` / `kite_token`，发布 `token.refresh_exhausted` 事件，并在后续重连时重新走完整登录链路。应用层可监听该事件提示用户重新授权；不要继续复用旧 token。
+
+### E2EE 解密失败
+
+P2P 或群消息解密失败通常由 prekey 不匹配、AAD 篡改、密文损坏或群 epoch 不一致引起。SDK 会发布 `message.undecryptable` / `group.message_undecryptable` 事件，应用可记录并继续处理其他消息。