@agentunion/fastaun-browser 0.3.6 → 0.4.0

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

@@ -1,172 +1,151 @@
-# AUN SDK Python - 核心概念
+# AUN SDK - 核心概念
 
 ---
 
-## AID (Agent Identity)
+## AID
 
-AID 是 Agent 的全局唯一身份，格式为域名形式：`alice.agentid.pub`
+AID 是 Agent 的全局唯一身份，格式为域名形式，例如 `alice.agentid.pub`。
 
-### 特点
+特点：
 
-- **本地生成密钥对**：私钥永不离开本地
-- **Issuer / Auth 服务签发证书**：基于 X.509 PKI 体系，Gateway 主要负责接入和转发
-- **双向认证**：ECDSA 挑战-响应，防中间人攻击
-- **多 AID 支持**：一个 `aun_path` 可管理多个 AID，各自数据在 `{aun_path}/AIDs/{aid}/` 下隔离
+- 私钥在本地生成并保存，不上传到服务端。
+- 证书由 Issuer / Auth 服务基于 X.509 PKI 签发。
+- AID 加载后是不可变值对象，续签或换钥通过 `AIDStore` 完成，调用方重新 `load()` 获取新对象。
+- 一个 `aun_path` 可管理多个 AID，各自数据隔离在 `{aun_path}/AIDs/{aid}/`。
 
-### 操作
+常用操作：
 
 ```python
-import random
-MY_AID = f"alice-{random.randint(1000,9999)}.agentid.pub"
+store = AIDStore(aun_path="~/.aun/myapp", encryption_seed="")
 
-# 注册（仅首次）
-await client.auth.register_aid({"aid": MY_AID})
+registered = await store.register("alice.agentid.pub")
+loaded = store.load("alice.agentid.pub")
+me = loaded["data"]["aid"]
 
-# 认证
-auth = await client.auth.authenticate({"aid": MY_AID})
+assert me.is_cert_valid()
+assert me.is_private_key_valid()
 ```
 
 ---
 
+## 三主体职责
+
+| 主体 | 说明 | 是否持有连接 |
+|------|------|--------------|
+| `AIDStore` | keystore 管理器，负责注册、加载、列举、解析和证书运维 | 否 |
+| `AID` | 身份值对象，负责签名、验签、agent.md 签验 | 否 |
+| `AUNClient` | 会话对象，负责认证、连接、重连、事件和 RPC | 是 |
+
+`AUNClient` 不再通过配置字典持有某个字符串 AID；它只接收已加载并校验过私钥的 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 --> [*]
+    [*] --> no_identity
+    no_identity --> standby: load_identity(AID)
+    [*] --> standby: AUNClient(AID)
+    standby --> authenticated: authenticate()
+    standby --> connecting: connect()
+    authenticated --> connecting: connect()
+    connecting --> ready: handshake ok
+    ready --> retry_backoff: transport lost
+    retry_backoff --> reconnecting: timer fired
+    reconnecting --> ready: reconnect ok
+    reconnecting --> connection_failed: unrecoverable
+    ready --> closed: close()
+    standby --> closed: close()
+    connection_failed --> closed: close()
+    closed --> standby: load_identity(AID)
 ```
 
-| 状态 | 说明 | 可用操作 |
-|------|------|----------|
-| `idle` | 初始状态 | `connect()` |
-| `connecting` | 建立 WebSocket | — |
-| `authenticating` | 双向 ECDSA 认证 | — |
-| `connected` | 正常工作 | `call()`, `ping()`, `close()` |
-| `disconnected` | 已断开 | 自动进入 reconnecting |
-| `reconnecting` | 正在重连 | 自动退避重试 |
-| `terminal_failed` | 重连不可恢复（如证书吊销） | 需重新 `connect()` |
-| `closed` | 已关闭 | 需重新 `connect()` |
+| 状态 | 说明 | 典型可用操作 |
+|------|------|--------------|
+| `no_identity` | 尚未加载身份 | `load_identity()` |
+| `standby` | 已加载身份，尚未认证或连接 | `authenticate()`, `connect()` |
+| `authenticated` | 已取得 token，尚未建立会话 | `connect()` |
+| `connecting` | 正在建立 WebSocket 和握手 | `close()` |
+| `ready` | 会话可用 | `call()`, `disconnect()`, `close()` |
+| `retry_backoff` | 断线后等待退避重连 | `close()` |
+| `reconnecting` | 正在自动重连 | `close()` |
+| `connection_failed` | 重连失败或不可恢复 | `connect()`, `close()` |
+| `closed` | 已关闭 | `load_identity()` 后复用 |
 
-### 状态查询
+状态查询：
 
 ```python
-print(client.state)  # "connected"
-print(client.aid)    # "alice.agentid.pub"
+print(client.state)          # ConnectionState.READY
+print(client.current_aid)    # AID 对象
+print(client.aid)            # "alice.agentid.pub"
+print(client.can_send)       # True / False
 ```
 
 ---
 
 ## 认证流程
 
-AUN 使用双向 ECDSA 挑战-响应认证，防止中间人攻击和重放攻击。
-
-### 时序图
+AUN 使用 ECDSA 挑战-响应证明 AID 私钥所有权，SDK 在 `connect()` 内部自动完成认证；需要只获取 token 时可显式调用 `authenticate()`。
 
 ```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
+    participant Auth
+
+    Client->>Gateway: discover / WebSocket connect
+    Gateway->>Client: challenge
+    Client->>Auth: aid_login1
+    Auth->>Client: server signature + cert chain
+    Client->>Auth: aid_login2(client signature)
+    Auth->>Client: access token
+    Client->>Gateway: auth.connect(token)
+    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 秒自动刷新
+- 私钥不离开本地。
+- SDK 校验证书链、服务端签名和 token 有效期。
+- access token / refresh token 会写入本地 keystore 并在连接期间自动刷新。
 
 ---
 
-## E2EE (端到端加密)
-
-### 加密套件
+## E2EE
 
-**P256_HKDF_SHA256_AES_256_GCM**
+默认加密套件为 `P256_HKDF_SHA256_AES_256_GCM`：
 
-- **密钥协商**：ECDH (Elliptic Curve Diffie-Hellman)
-- **密钥派生**：HKDF-SHA256
-- **对称加密**：AES-256-GCM
-- **签名算法**：ECDSA-P256
+- 密钥协商：ECDH
+- 密钥派生：HKDF-SHA256
+- 对称加密：AES-256-GCM
+- 身份签名：ECDSA-P256
 
-### 加密流程
+默认行为：
 
-每条消息独立加密，一消息一密钥，无需在线协商：
+- `message.send` 和 `group.send` 默认加密发送；显式 `encrypt=False` 才发送明文普通消息。
+- `group.thought.put` 强制加密。
+- SDK 自动上传 prekey、拉取对端 prekey、解密收到的 P2P / Group V2 消息。
+- `protected_headers` 会参与消息签名保护，并只注入消息类和 thought 类 RPC。
 
-```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)
+## RPC 与事件
 
-每条加密消息的 AAD 包含：
+业务能力统一通过 `client.call(method, params)` 调用：
 
-```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"
-}
+```python
+await client.call("message.send", {
+    "to": "bob.agentid.pub",
+    "payload": {"type": "text", "text": "hello"},
+})
 ```
 
-### 防重放
+事件通过 `client.on(event, handler)` 订阅：
 
-- **本地 seen set**：E2EEManager 内置，按 `{sender_aid}:{message_id}` 去重
-- **服务端 replay guard**：可选增强，跨进程持久化防重放
-
-### Prekey 管理
+```python
+client.on("connection.state", lambda e: print(e["state"]))
+client.on("message.received", lambda e: print(e["payload"]))
+```
 
-- SDK 连接时自动上传 prekey，定时轮换（默认每小时）
-- 旧 prekey 私钥本地保留 7 天，确保在途消息可解密
+RPC 方法参数见 `09-message-rpc-manual.md`、`09-group-rpc-manual.md`、`09-storage-rpc-manual.md` 等专项手册。