@agentunion/fastaun-browser 0.2.19 → 0.2.20

package/_packed_docs/sdk/03-/346/240/270/345/277/203/346/246/202/345/277/265.md

@@ -0,0 +1,172 @@
+# AUN SDK Python - 核心概念
+
+---
+
+## AID (Agent Identity)
+
+AID 是 Agent 的全局唯一身份，格式为域名形式：`alice.agentid.pub`
+
+### 特点
+
+- **本地生成密钥对**：私钥永不离开本地
+- **Issuer / Auth 服务签发证书**：基于 X.509 PKI 体系，Gateway 主要负责接入和转发
+- **双向认证**：ECDSA 挑战-响应，防中间人攻击
+- **多 AID 支持**：一个 `aun_path` 可管理多个 AID，各自数据在 `{aun_path}/AIDs/{aid}/` 下隔离
+
+### 操作
+
+```python
+import random
+MY_AID = f"alice-{random.randint(1000,9999)}.agentid.pub"
+
+# 创建（仅首次）
+await client.auth.create_aid({"aid": MY_AID})
+
+# 认证
+auth = await client.auth.authenticate({"aid": MY_AID})
+```
+
+---
+
+## 连接状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> idle
+    idle --> connecting: connect()
+    connecting --> authenticating
+    authenticating --> connected
+    connected --> disconnected: 断线
+    disconnected --> reconnecting: 自动重连
+    reconnecting --> connecting: 重试
+    reconnecting --> terminal_failed: 不可恢复
+    connected --> closed: close()
+    disconnected --> closed: close()
+    closed --> [*]
+```
+
+| 状态 | 说明 | 可用操作 |
+|------|------|----------|
+| `idle` | 初始状态 | `connect()` |
+| `connecting` | 建立 WebSocket | — |
+| `authenticating` | 双向 ECDSA 认证 | — |
+| `connected` | 正常工作 | `call()`, `ping()`, `close()` |
+| `disconnected` | 已断开 | 自动进入 reconnecting |
+| `reconnecting` | 正在重连 | 自动退避重试 |
+| `terminal_failed` | 重连不可恢复（如证书吊销） | 需重新 `connect()` |
+| `closed` | 已关闭 | 需重新 `connect()` |
+
+### 状态查询
+
+```python
+print(client.state)  # "connected"
+print(client.aid)    # "alice.agentid.pub"
+```
+
+---
+
+## 认证流程
+
+AUN 使用双向 ECDSA 挑战-响应认证，防止中间人攻击和重放攻击。
+
+### 时序图
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Gateway
+
+    Client->>Gateway: WebSocket Connect
+    Gateway->>Client: challenge (server_nonce)
+
+    Client->>Gateway: auth.aid_login1 (client_nonce)
+    Gateway->>Client: server_signature + cert_chain
+
+    Client->>Gateway: auth.aid_login2 (client_signature)
+    Gateway->>Client: access_token (JWT)
+
+    Client->>Gateway: auth.connect (bearer auth)
+    Gateway->>Client: session OK
+```
+
+### 关键步骤
+
+1. **WebSocket 握手**：建立传输层连接
+2. **Challenge**：Gateway 发送会话 challenge nonce
+3. **Login Phase 1**：Client 调用 `auth.aid_login1`，Auth 服务返回签名和 `auth_cert`
+4. **证书验证**：Client 验证 Auth 服务证书链（含 CRL/OCSP 检查）
+5. **Login Phase 2**：Client 对 Auth 服务返回的 nonce 签名，Auth 服务验证后返回 JWT
+6. **Session 建立**：Client 用 JWT 调用 `auth.connect`，建立会话
+
+### 令牌管理
+
+- **Access Token**：短期令牌（默认 1 小时），用于 RPC 调用
+- **Refresh Token**：长期令牌（默认 7 天），用于刷新 Access Token
+- **自动刷新**：SDK 在 Access Token 过期前 60 秒自动刷新
+
+---
+
+## E2EE (端到端加密)
+
+### 加密套件
+
+**P256_HKDF_SHA256_AES_256_GCM**
+
+- **密钥协商**：ECDH (Elliptic Curve Diffie-Hellman)
+- **密钥派生**：HKDF-SHA256
+- **对称加密**：AES-256-GCM
+- **签名算法**：ECDSA-P256
+
+### 加密流程
+
+每条消息独立加密，一消息一密钥，无需在线协商：
+
+```mermaid
+sequenceDiagram
+    participant Sender
+    participant Gateway
+    participant Receiver
+
+    Receiver->>Gateway: 上传 prekey（公钥 + 签名）
+    Sender->>Gateway: 获取 Receiver 的 prekey 和证书
+    Note over Sender: 验证 prekey 签名 → 临时 ECDH → message_key
+    Sender->>Gateway: e2ee.encrypted (ciphertext + tag + AAD)
+    Gateway->>Receiver: 推送或 pull
+    Note over Receiver: 用 prekey 私钥 + 临时公钥 → ECDH → message_key → 解密
+```
+
+### 加密模式
+
+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 时拒绝 long_term_key 降级。
+
+### AAD (Additional Authenticated Data)
+
+每条加密消息的 AAD 包含：
+
+```json
+{
+  "from": "alice.agentid.pub",
+  "to": "bob.agentid.pub",
+  "message_id": "uuid",
+  "timestamp": 1234567890000,
+  "encryption_mode": "prekey_ecdh_v2",
+  "suite": "P256_HKDF_SHA256_AES_256_GCM",
+  "ephemeral_public_key": "base64",
+  "recipient_cert_fingerprint": "sha256:...",
+  "sender_cert_fingerprint": "sha256:...",
+  "prekey_id": "uuid"
+}
+```
+
+### 防重放
+
+- **本地 seen set**：E2EEManager 内置，按 `{sender_aid}:{message_id}` 去重
+- **服务端 replay guard**：可选增强，跨进程持久化防重放
+
+### Prekey 管理
+
+- SDK 连接时自动上传 prekey，定时轮换（默认每小时）
+- 旧 prekey 私钥本地保留 7 天，确保在途消息可解密

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

@@ -0,0 +1,373 @@
+# AUN SDK Python - 连接与认证
+
+---
+
+## 创建 AID 和认证
+
+```python
+from aun_core import AUNClient
+
+async def setup(aid: str):
+    client = AUNClient()  # 默认 aun_path: ~/.aun
+
+    # 创建 AID
+    try:
+        result = await client.auth.create_aid({"aid": aid})
+        # result: {"aid": ..., "cert_pem": ..., "gateway": ...}
+    except Exception as e:
+        print(f"创建 AID 失败: {e}")
+        raise
+
+    auth = await client.auth.authenticate({"aid": aid})
+    # auth: {"aid": ..., "access_token": ..., "refresh_token": ...,
+    #        "expires_at": ..., "gateway": ...}
+    return client, auth
+```
+
+---
+
+## 连接到网关
+
+**必须先调用 `client.auth.authenticate()` 获取令牌和网关地址，再调用 `connect()`，此步骤不可跳过。** `authenticate()` 返回的 `gateway` 字段即为网关 WebSocket 地址。
+
+> 当前各语言 SDK 的稳定连接模式都是 Gateway。协议层虽然定义了 Peer / Relay，但 Python SDK 的 `connect(topology=...)` 目前会对 `peer` / `relay` 明确返回未实现。
+
+### 基础连接
+
+```python
+# 第一步：认证
+auth = await client.auth.authenticate({"aid": MY_AID})
+# auth["access_token"] — 访问令牌
+# auth["gateway"]      — 网关 WebSocket 地址
+
+# 第二步：连接（auth 结果 + 连接选项）
+await client.connect(auth, {})
+```
+
+### 完整连接选项
+
+```python
+# 以下为可选覆盖值；不传时默认 auto_reconnect=true、heartbeat_interval=30、
+# token_refresh_before=60、retry.initial_delay=1.0、retry.max_delay=64.0、
+# timeouts={connect:5, call:10, http:30}
+await client.connect(auth, {
+    "auto_reconnect": True,                 # 断线自动重连
+    "heartbeat_interval": 30.0,             # 心跳间隔（秒）
+    "token_refresh_before": 60.0,           # 令牌刷新提前量（秒）
+    "connection_kind": "long",              # 可选，"long"（默认）或 "short"
+    "short_ttl_ms": 30000,                  # 可选，仅 kind=short 时有效，服务端兜底超时
+    "retry": {
+        "initial_delay": 1.0,               # 初始退避延迟
+        "max_delay": 64.0,                  # 最大退避延迟
+    },
+    "timeouts": {
+        "connect": 5.0,                     # WebSocket 连接超时
+        "call": 10.0,                       # RPC 调用超时
+        "http": 30.0,                       # HTTP 请求超时
+    },
+})
+```
+
+> 当前实现只读取 `retry.initial_delay` / `retry.max_delay`；未提供 `retry.max_attempts` 选项，上层如需停止自动重连，应主动关闭客户端。
+
+**长短连接共存**：同一 `(aid, device_id, slot_id)` 槽位下允许 1 条长连接 + 最多 10 条短连接。长连接承担服务端推送（消息、事件）；短连接仅用于 RPC 请求-响应后立即断开（CLI 工具场景）。短连接默认禁用 `auto_reconnect`、心跳和 token 主动刷新。
+
+### 长连接 / 短连接代码示例
+
+#### 长连接（守护进程：常驻收件箱）
+
+```python
+from aun_core import AUNClient
+
+client = AUNClient({"aun_path": "/home/alice/.aun/alice"})
+# 首次：走完整 login + discovery；之后：复用 keystore 里的 cached token + gateway_url
+auth = await client.auth.authenticate({"aid": "alice.example.com"})
+await client.connect(auth, {
+    "connection_kind": "long",       # 默认值，可省略
+    "slot_id": "main",
+    "auto_reconnect": True,
+})
+
+# 监听消息推送
+client.on("message.received", lambda data: print(data["payload"]))
+
+# 常驻
+await asyncio.Event().wait()
+```
+
+#### 短连接（CLI 工具：发完即退）
+
+```python
+from aun_core import AUNClient
+
+# 关键：使用与长连接守护进程相同的 aun_path → 共享 keystore → 自动复用 token
+client = AUNClient({"aun_path": "/home/alice/.aun/alice"})
+
+# authenticate 自动从 keystore 读 cached access_token，跳过两阶段 login
+auth = await client.auth.authenticate({"aid": "alice.example.com"})
+
+# connect 时声明 short kind + 同 slot_id（与长连接共存于同一槽位）
+await client.connect(auth, {
+    "connection_kind": "short",
+    "slot_id": "main",                # 与长连接同 slot
+    "short_ttl_ms": 30000,            # 服务端兜底超时（防 CLI 异常退出占名额）
+})
+
+# 发 RPC，响应原路返回到这条短连接
+result = await client.call("message.send", {
+    "to": "bob.example.com",
+    "payload": {"type": "text", "text": "hello"},
+})
+
+# 短连接发完立即关闭（不影响长连接守护进程）
+await client.close()
+```
+
+#### Token 复用机制
+
+同一 `aun_path` 的多个 AUNClient 实例自动共享 keystore，包括：
+
+- `access_token`（JWT，1 小时有效期）
+- `refresh_token`（7 天有效期）
+- `access_token_expires_at`（精确到秒）
+- `gateway_url`（well-known discovery 结果）
+
+`authenticate()` 调用时优先读 keystore 中的有效 cached_token，命中则跳过两阶段 login（`auth.aid_login1` + `auth.aid_login2`），节省一次 well-known discovery + 两次 RPC 往返。
+
+长连接守护进程的后台 `_token_refresh_task` 会在 token 过期前 30 分钟自动刷新并写回 keystore。CLI 短连接每次启动直接读到最新 token，无需关心刷新细节。
+
+token 过期或 refresh 失败时，SDK 自动 fallback：cached_token → refresh_token → 完整两阶段 login，应用层无感。
+
+#### 三种典型场景
+
+| 场景 | aun_path | connection_kind | slot_id |
+|---|---|---|---|
+| 守护进程常驻接收 | `/home/alice/.aun/alice` | `"long"` | `"main"` |
+| CLI 工具发消息 | `/home/alice/.aun/alice`（同上） | `"short"` | `"main"`（同上） |
+| 多实例独立运行 | `/home/alice/.aun/instance-N`（不同） | `"long"` | 自定义 |
+
+> 跨语言用法：TS / JS 用 `connectionKind` / `slotId`（camelCase），Go 用 `ConnectionKind` / `SlotID`（PascalCase），其余语义一致。
+
+### 查看状态
+
+```python
+print(client.state)  # "connected"
+print(client.aid)    # "alice.agentid.pub"
+```
+
+---
+
+## 网关自动发现
+
+`create_aid()` / `authenticate()` 内部会自动发现 Gateway。
+
+- 生产配置（`verify_ssl=true`）下，优先尝试 `https://{aid}/.well-known/aun-gateway`
+- 若失败，则回退到 `https://gateway.{issuer}/.well-known/aun-gateway`
+- 开发配置（`verify_ssl=false`）下，为兼容未启用泛域名的环境，尝试顺序相反
+
+发现到的 Gateway URL 会缓存在客户端内部，后续 `connect()` 默认复用。
+
+发现成功后，SDK 会基于服务器返回的 Gateway WebSocket URL 动态构造健康检查地址：将末尾路径替换为 `/health`，并将 `wss://` / `ws://` 分别转换为 `https://` / `http://`。例如 `wss://gateway.example.com/aun` 会检查 `https://gateway.example.com/health`。健康检查使用 `GET /health`，结果可通过 `client.gateway_health`（Python）/ `client.gatewayHealth`（TS/JS）/ `client.GatewayHealth()`（Go）查询，也可主动调用 `check_gateway_health(url)` 触发检查。
+
+### 跨域通信
+
+当发送消息到不同 Issuer 的 AID 时（如 `alice.aid.pub` 发送给 `bob.example.com`），调用方式对用户保持一致：
+
+1. 应用层仍通过当前 Gateway 会话调用 `message.send`
+2. 需要对端证书/预密钥时，SDK 会根据目标 AID 的 issuer 派生或发现目标 Gateway 的 HTTP 端点
+3. 真正的跨域消息路由由 Gateway / Federation 服务端链路完成，而不是由 SDK 为每个目标额外建立一个远端 WebSocket 会话
+
+**对用户完全透明**，无需额外配置。跨域消息和本域消息使用相同的 API：
+
+```python
+# 本域消息
+await client.call("message.send", {"to": "bob.aid.pub", ...})
+
+# 跨域消息（自动路由）
+await client.call("message.send", {"to": "charlie.example.com", ...})
+```
+
+> 跨域路由的详细实现机制见协议文档：[附录I-跨域消息路由实现指南](../src/aun_core/docs/protocol/附录I-跨域消息路由实现指南.md)
+
+---
+
+## Agent Web / agent.md
+
+Name Service 同时提供面向 Agent Web 的标准 HTTP 资源：
+
+- `PUT https://{aid}/agent.md`
+  需要 `Authorization: Bearer <access_token>`，用于上传或覆盖当前 AID 的公开 `agent.md`
+- `GET https://{aid}/agent.md`
+  匿名下载指定 AID 的 `agent.md`
+- `HEAD https://{aid}/agent.md`
+  匿名查询是否存在，并获取 `ETag`、`Last-Modified`、`Cache-Control`
+
+SDK 已封装上传、下载、签名、验签高层方法：
+
+```python
+signed_agent_md = await client.auth.sign_agent_md(agent_md_text)
+await client.auth.upload_agent_md(signed_agent_md)
+peer_agent_md = await client.auth.download_agent_md("bob.agentid.pub")
+peer_verify_result = await client.auth.verify_agent_md(peer_agent_md, aid="bob.agentid.pub")
+```
+
+其中：
+
+- `sign_agent_md()` 使用当前本地身份私钥在文件尾部追加 `AUN-SIGNATURE` 块；若已有尾部签名块，会先剥离再重签
+- `verify_agent_md()` 返回三态结果：`verified`、`invalid`、`unsigned`；未传 `cert_pem` 时会按 `aid + cert_fingerprint` 拉取对端证书
+- `upload_agent_md()` 会自动复用本地缓存的 access token；若 token 缺失或过期，会自动重新认证后再上传
+- `download_agent_md()` 不需要登录态，直接匿名下载
+- 签名块不改变服务端 HTTP 端点；上传前是否签名由应用层决定
+- 服务端返回短时缓存头，调用方也可以直接使用上述 HTTP 端点自行下载或做缓存协商
+- 常见错误返回：
+  `PUT /agent.md` 可能返回 `401`（缺失或无效 token）、`403`（token 的 AID 与 Host 不匹配）、`400`（frontmatter 非法或 frontmatter.aid 与 Host 不匹配）、`413`（文档超过大小上限）
+  `GET/HEAD /agent.md` 在目标尚未发布时返回 `404`
+
+---
+
+## 调用 RPC 方法
+
+### `client.call(method, params)` — 通用 RPC 接口
+
+认证连接后，所有业务操作通过 `client.call()` 调用服务端 RPC 方法：
+
+```python
+result = await client.call(method: str, params: dict | None = None) -> Any
+```
+
+**示例：**
+
+```python
+# 发送消息
+result = await client.call("message.send", {
+    "to": "bob.agentid.pub",
+    "payload": {"type": "text", "text": "Hello!"},
+})
+print(result)  # {"message_id": "...", "seq": 123, "status": "sent"}
+
+# 拉取消息
+result = await client.call("message.pull", {"after_seq": 0, "limit": 20})
+print(result)  # {"messages": [...], "count": 5, "latest_seq": 128}
+
+# 创建群组
+result = await client.call("group.create", {
+    "name": "项目组",
+    "members": ["bob.agentid.pub", "carol.agentid.pub"],
+})
+print(result)  # {"group_id": "...", "created_at": ...}
+```
+
+**错误处理：**
+
+```python
+from aun_core import AUNError, NotFoundError, RateLimitError
+
+try:
+    result = await client.call("message.send", {...})
+except NotFoundError as e:
+    print(f"目标不存在: {e.code}")
+except RateLimitError as e:
+    print(f"请求限流，{e.data['retry_after']}秒后重试")
+except AUNError as e:
+    print(f"RPC 错误: code={e.code}, retryable={e.retryable}")
+```
+
+**RPC 方法完整参数和响应格式见 RPC 手册：**
+
+| 领域 | 手册 | 涵盖方法 |
+|------|------|----------|
+| 消息 | [09-message-rpc-manual.md](09-message-rpc-manual.md) | message.send / pull / ack / recall / thought.put / thought.get |
+| 群组 | [09-group-rpc-manual.md](09-group-rpc-manual.md) | 群组生命周期、成员管理、群设置、群消息、群 thought |
+| 存储 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) | 文件上传下载、对象存储 |
+| 元信息 | [09-meta-rpc-manual.md](09-meta-rpc-manual.md) | meta.ping / status / trust_roots |
+
+---
+
+## 事件订阅
+
+### `client.on(event, handler)` — 订阅事件
+
+**`on()` 应在 `connect()` 之前调用**，否则连接建立瞬间触发的事件（如 `connection.state`）会丢失。
+
+服务端推送的事件通过 `client.on()` 订阅，支持同步和异步 handler：
+
+```python
+subscription = client.on(event: str, handler: Callable) -> Subscription
+```
+
+**同步 handler：**
+
+```python
+def on_message(event):
+    print(f"收到消息: {event['payload']}")
+
+sub = client.on("message.received", on_message)
+```
+
+**异步 handler：**
+
+```python
+async def on_message(event):
+    await process_message(event)
+    await client.call("message.ack", {"seq": event["seq"]})
+
+sub = client.on("message.received", on_message)
+```
+
+**只触发一次（手动取消订阅）：**
+
+```python
+def on_state_change(e):
+    print(f"状态变更: {e}")
+    sub.unsubscribe()  # 触发后立即取消
+
+sub = client.on("connection.state", on_state_change)
+```
+
+**取消订阅：**
+
+```python
+sub = client.on("message.received", handler)
+# ... 稍后
+sub.unsubscribe()
+```
+
+**多个 handler：**
+
+```python
+# 同一事件可注册多个 handler，按注册顺序依次调用
+client.on("message.received", log_message)
+client.on("message.received", update_ui)
+client.on("message.received", send_notification)
+```
+
+**常用事件示例：**
+
+```python
+# 连接状态变化
+client.on("connection.state", lambda e: print(f"状态: {e['state']}"))
+
+# 消息推送
+client.on("message.received", handle_new_message)
+
+# 群组变更
+client.on("group.changed", lambda e: print(f"群组 {e['group_id']} 已更新"))
+
+# 令牌刷新
+client.on("token.refreshed", lambda e: print(f"令牌已刷新: {e['aid']}"))
+
+# 连接错误
+client.on("connection.error", lambda e: print(f"连接错误: {e}"))
+```
+
+内置事件完整列表见 [06-API手册.md](06-API手册.md) 的「内置事件」节。
+
+---
+
+## 关闭连接
+
+```python
+await client.close()
+```
+
+关闭后状态变为 `"closed"`，不可复用，需重新创建 `AUNClient`。