@agentunion/fastaun-browser 0.3.6 → 0.4.1

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

@@ -48,142 +48,142 @@ SDK 优先使用 prekey_ecdh_v2，并默认要求前向保密：
 
 > Python SDK 默认 `require_forward_secrecy=true`，当加密结果不满足前向保密（无论是因为无 prekey 还是 prekey 加密失败降级到 long_term_key）时拒绝发送并抛出错误。需显式配置 `require_forward_secrecy=false` 才允许降级。
 
-每条消息独立生成临时 ECDH 密钥对，实现一消息一密钥。
-
-## ProtectedHeaders 与可验证上下文
-
-`protected_headers` 是 E2EE 信封里的可选元数据字典，语义接近 HTTP headers：适合放 `device_id`、`slot_id`、`device_name`、`os`、`sdk_version`、`app_name` 等需要被接收端识别、且需要防篡改的非业务内容。`payload` 仍然类似 HTTP body，业务内容应放在 `payload` 内。
-
-`protected_headers` 会随 E2EE 信封发送，接收端可以读取，因此它提供完整性保护，不提供机密性保护。不要把访问令牌、私钥、隐私正文或其他只允许端到端可见的内容放入 `protected_headers`；这类内容应放进加密的 `payload`。
-
-发送方可以在以下 SDK 调用中传入 `protected_headers`，各 SDK 也兼容别名 `headers`：
-
-- `message.send`
-- `message.thought.put`
-- `group.send`
-- `group.thought.put`
-
-`payload_type` 不需要应用层传入。SDK 会读取加密前 `payload.type`，自动写入 `protected_headers.payload_type`，接收端解密后会校验它与明文 `payload.type` 一致。
-
-示例：
-
-```python
-from aun_core import ProtectedHeaders
-
-headers = (
-    ProtectedHeaders()
-    .set("device_id", "dev-123")
-    .set("slot_id", "desktop")
-    .set("sdk_version", "0.2.8")
-    .set("app_name", "my-agent")
-)
-
-await client.call("message.send", {
-    "to": "bob.agentid.pub",
-    "payload": {"type": "text", "text": "秘密消息"},
-    "protected_headers": headers,
-})
-```
-
-应用层也可以直接传普通字典：
-
-```python
-await client.call("group.send", {
-    "group_id": "10001.example.com",
-    "payload": {"type": "text", "text": "群组消息"},
-    "protected_headers": {"device_id": "dev-123", "slot_id": "desktop"},
-})
-```
-
-### 防篡改机制
-
-为兼容旧 E2EE 信封，`protected_headers` 和 `context` 不加入原有信封整体 AAD。它们各自带一个 `_auth` 字段，自包含完整性校验信息：
-
-```json
-{
-  "type": "e2ee.encrypted",
-  "ciphertext": "...",
-  "protected_headers": {
-    "device_id": "dev-123",
-    "slot_id": "desktop",
-    "payload_type": "text",
-    "_auth": {
-      "alg": "HMAC-SHA256",
-      "tag": "base64..."
-    }
-  },
-  "context": {
-    "type": "run",
-    "id": "run-xxx",
-    "_auth": {
-      "alg": "HMAC-SHA256",
-      "tag": "base64..."
-    }
-  }
-}
-```
-
-计算规则：
-
-1. 解密流程会派生出本条消息的 `message_key`。
-2. `metadata_key = HMAC-SHA256(message_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`。
-
-只有持有本条消息密钥的发送端和接收端能生成或验证 `_auth.tag`。中间服务可以看到这些元数据，但不能在不破坏校验的情况下修改它们。
-
-兼容策略：
-
-- 老消息没有 `protected_headers` / `context` 时照常解密。
-- 新消息一旦携带 `protected_headers` 或 E2EE 信封内的 `context`，就必须携带对应 `_auth`。
-- `_auth` 校验失败、`payload_type` 与解密后 `payload.type` 不一致，或信封内 `context` 与外层 thought selector 不一致时，SDK 视为解密失败。
-
-### 接收端读取
-
-SDK 会在验签/验 `_auth` 后，把 `_auth` 去掉，只把业务可见字段回传给应用层：
-
-```python
-msg = result["messages"][0]
-headers = msg.get("e2ee", {}).get("protected_headers", {})
-device_id = headers.get("device_id")
-payload_type = headers.get("payload_type")
-```
-
-对于 thought，顶层 `context.type + context.id` 仍是服务端定位 thought head 的 selector；E2EE 信封内的 `context` 只是对这个 selector 的端到端完整性绑定。
-
-## P2P 思考内容
-
-P2P 思考内容不是普通消息，不广播、不进 `message.pull`、不分配 seq、无需 ack，也不持久化。它只通过 `message.thought.put/get` 读写，并强制使用 P2P E2EE。
-
-thought selector 只使用顶层 `context.type + context.id`，推荐 `{"type": "run", "id": "run-xxx"}`。如果需要展示被引用消息摘要，应放在加密后的 `payload.quote` 或 `payload.client_context` 中，不作为服务端 selector。
-
-```python
-await client.call("message.thought.put", {
-    "to": "bob.agentid.pub",
-    "context": {"type": "run", "id": "run-xxx"},
-    "payload": {"type": "thought", "text": "先核对 Bob 的约束，再输出答复"},
-})
-```
-
-读取对方写给当前用户的 thought 时，指定 `sender_aid` 和同一个 `context`：
-
-```python
-result = await client.call("message.thought.get", {
-    "sender_aid": "bob.agentid.pub",
-    "context": {"type": "run", "id": "run-xxx"},
-})
-```
+每条消息独立生成临时 ECDH 密钥对，实现一消息一密钥。
+
+## ProtectedHeaders 与可验证上下文
+
+`protected_headers` 是 E2EE 信封里的可选元数据字典，语义接近 HTTP headers：适合放 `device_id`、`slot_id`、`device_name`、`os`、`sdk_version`、`app_name` 等需要被接收端识别、且需要防篡改的非业务内容。`payload` 仍然类似 HTTP body，业务内容应放在 `payload` 内。
+
+`protected_headers` 会随 E2EE 信封发送，接收端可以读取，因此它提供完整性保护，不提供机密性保护。不要把访问令牌、私钥、隐私正文或其他只允许端到端可见的内容放入 `protected_headers`；这类内容应放进加密的 `payload`。
+
+发送方可以在以下 SDK 调用中传入 `protected_headers`，各 SDK 也兼容别名 `headers`：
+
+- `message.send`
+- `message.thought.put`
+- `group.send`
+- `group.thought.put`
+
+`payload_type` 不需要应用层传入。SDK 会读取加密前 `payload.type`，自动写入 `protected_headers.payload_type`，接收端解密后会校验它与明文 `payload.type` 一致。
+
+示例：
+
+```python
+from aun_core import ProtectedHeaders
+
+headers = (
+    ProtectedHeaders()
+    .set("device_id", "dev-123")
+    .set("slot_id", "desktop")
+    .set("sdk_version", "0.4.0")
+    .set("app_name", "my-agent")
+)
+
+await client.call("message.send", {
+    "to": "bob.agentid.pub",
+    "payload": {"type": "text", "text": "秘密消息"},
+    "protected_headers": headers,
+})
+```
+
+应用层也可以直接传普通字典：
+
+```python
+await client.call("group.send", {
+    "group_id": "10001.example.com",
+    "payload": {"type": "text", "text": "群组消息"},
+    "protected_headers": {"device_id": "dev-123", "slot_id": "desktop"},
+})
+```
+
+### 防篡改机制
+
+为兼容旧 E2EE 信封，`protected_headers` 和 `context` 不加入原有信封整体 AAD。它们各自带一个 `_auth` 字段，自包含完整性校验信息：
+
+```json
+{
+  "type": "e2ee.encrypted",
+  "ciphertext": "...",
+  "protected_headers": {
+    "device_id": "dev-123",
+    "slot_id": "desktop",
+    "payload_type": "text",
+    "_auth": {
+      "alg": "HMAC-SHA256",
+      "tag": "base64..."
+    }
+  },
+  "context": {
+    "type": "run",
+    "id": "run-xxx",
+    "_auth": {
+      "alg": "HMAC-SHA256",
+      "tag": "base64..."
+    }
+  }
+}
+```
+
+计算规则：
+
+1. 解密流程会派生出本条消息的 `message_key`。
+2. `metadata_key = HMAC-SHA256(message_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`。
+
+只有持有本条消息密钥的发送端和接收端能生成或验证 `_auth.tag`。中间服务可以看到这些元数据，但不能在不破坏校验的情况下修改它们。
+
+兼容策略：
+
+- 老消息没有 `protected_headers` / `context` 时照常解密。
+- 新消息一旦携带 `protected_headers` 或 E2EE 信封内的 `context`，就必须携带对应 `_auth`。
+- `_auth` 校验失败、`payload_type` 与解密后 `payload.type` 不一致，或信封内 `context` 与外层 thought selector 不一致时，SDK 视为解密失败。
+
+### 接收端读取
+
+SDK 会在验签/验 `_auth` 后，把 `_auth` 去掉，只把业务可见字段回传给应用层：
+
+```python
+msg = result["messages"][0]
+headers = msg.get("e2ee", {}).get("protected_headers", {})
+device_id = headers.get("device_id")
+payload_type = headers.get("payload_type")
+```
+
+对于 thought，顶层 `context.type + context.id` 仍是服务端定位 thought head 的 selector；E2EE 信封内的 `context` 只是对这个 selector 的端到端完整性绑定。
+
+## P2P 思考内容
+
+P2P 思考内容不是普通消息，不广播、不进 `message.pull`、不分配 seq、无需 ack，也不持久化。它只通过 `message.thought.put/get` 读写，并强制使用 P2P E2EE。
+
+thought selector 只使用顶层 `context.type + context.id`，推荐 `{"type": "run", "id": "run-xxx"}`。如果需要展示被引用消息摘要，应放在加密后的 `payload.quote` 或 `payload.client_context` 中，不作为服务端 selector。
+
+```python
+await client.call("message.thought.put", {
+    "to": "bob.agentid.pub",
+    "context": {"type": "run", "id": "run-xxx"},
+    "payload": {"type": "thought", "text": "先核对 Bob 的约束，再输出答复"},
+})
+```
+
+读取对方写给当前用户的 thought 时，指定 `sender_aid` 和同一个 `context`：
+
+```python
+result = await client.call("message.thought.get", {
+    "sender_aid": "bob.agentid.pub",
+    "context": {"type": "run", "id": "run-xxx"},
+})
+```
 
 读取自己写给对方的 thought 时，还需要指定 `peer_aid` 或 `to`：
 
 ```python
-result = await client.call("message.thought.get", {
-    "sender_aid": "alice.agentid.pub",
-    "peer_aid": "bob.agentid.pub",
-    "context": {"type": "run", "id": "run-xxx"},
-})
-```
+result = await client.call("message.thought.get", {
+    "sender_aid": "alice.agentid.pub",
+    "peer_aid": "bob.agentid.pub",
+    "context": {"type": "run", "id": "run-xxx"},
+})
+```
 
 SDK 返回的 `result["thoughts"]` 是已解密数组。`message.thought.get` 是查询操作，重复读取同一条 thought 不按消息 replay 消费处理。
 
@@ -200,7 +200,7 @@ SDK 的群组 E2EE 编排对使用者透明：
 群组 E2EE 是必选能力，所有客户端必须支持。当前 Python SDK 固定启用，无需也不能通过配置关闭；成员加入时也固定轮换 epoch，无应用层开关：
 
 ```python
-client = AUNClient({})
+client = AUNClient(aid)
 ```
 
 **重要**：所有客户端必须声明群组 E2EE 能力。服务端当前仅对在线客户端做能力校验；离线客户端入群时不做强制检查。消息是否加密由发送者自主决定。
@@ -242,27 +242,27 @@ for msg in result["messages"]:
 
 ### 群思考内容
 
-群思考内容不是普通群消息，不广播、不进 `group.pull`、不分配 seq、无需 ack，也不持久化。它只通过 `group.thought.put/get` 读写，并强制使用群组 E2EE。
-
-群 thought selector 同样只使用顶层 `context.type + context.id`。
+群思考内容不是普通群消息，不广播、不进 `group.pull`、不分配 seq、无需 ack，也不持久化。它只通过 `group.thought.put/get` 读写，并强制使用群组 E2EE。
+
+群 thought selector 同样只使用顶层 `context.type + context.id`。
 
 ```python
-await client.call("group.thought.put", {
-    "group_id": "g-abc123.agentid.pub",
-    "context": {"type": "run", "id": "run-xxx"},
-    "payload": {"type": "thought", "text": "正在比较两个候选方案"},
-})
-```
+await client.call("group.thought.put", {
+    "group_id": "g-abc123.agentid.pub",
+    "context": {"type": "run", "id": "run-xxx"},
+    "payload": {"type": "thought", "text": "正在比较两个候选方案"},
+})
+```
 
-读取时必须指定 thought 作者和同一个 `context`：
+读取时必须指定 thought 作者和同一个 `context`：
 
 ```python
-result = await client.call("group.thought.get", {
-    "group_id": "g-abc123.agentid.pub",
-    "sender_aid": "alice.agentid.pub",
-    "context": {"type": "run", "id": "run-xxx"},
-})
-```
+result = await client.call("group.thought.get", {
+    "group_id": "g-abc123.agentid.pub",
+    "sender_aid": "alice.agentid.pub",
+    "context": {"type": "run", "id": "run-xxx"},
+})
+```
 
 SDK 返回的 `result["thoughts"]` 是已解密数组。`group.thought.get` 是查询操作，重复读取同一条 thought 不按消息 replay 消费处理。
 
@@ -576,10 +576,10 @@ class MyKeyStore:
     def load_metadata(self, aid: str) -> dict | None: ...
     def save_metadata(self, aid: str, metadata: dict) -> None: ...
 
-client = AUNClient({"aun_path": "..."})
+client = AUNClient(aid)
 ```
 
-`AUNClient` 不接收外部 `keystore` 参数。若需替换 `KeyStore`，应按 SDK 内部接口规范扩展实现，再由对应语言 SDK 的内部装配层接入。
+`AUNClient` 不接收外部 `keystore` 参数，也不再通过配置字典选择本地身份。若需替换 `KeyStore`，应按 SDK 内部接口规范扩展实现，再由对应语言 SDK 的内部装配层接入。
 
 ---
 
@@ -593,10 +593,10 @@ class MySecretStore:
     def reveal(self, scope: str, name: str, record: dict) -> bytes | None: ...
     def clear(self, scope: str, name: str) -> None: ...
 
-client = AUNClient({"aun_path": "..."})
+client = AUNClient(aid)
 ```
 
-`AUNClient` 构造函数只保留 `aun_path`、`root_ca_path`、`seed_password`。`SecretStore` / `KeyStore` / `SQLiteBackup` 属于 SDK 内部基础设施，不作为应用层构造参数暴露。
+`AUNClient` 构造函数只接收可选 AID 对象和会话选项。`SecretStore` / `KeyStore` / `SQLiteBackup` 属于 SDK 内部基础设施，不作为应用层构造参数暴露。
 
 ---