@agentunion/fastaun-browser 0.2.19 → 0.2.20

package/_packed_docs/protocol/03-Gateway-/350/277/236/346/216/245/346/250/241/345/274/217.md

@@ -0,0 +1,262 @@
+# 3. Gateway 连接模式
+
+## 3.1 Gateway 模式定位
+
+Gateway 是 AUN 三种平级连接模式之一（Gateway / [Peer](04-Peer-子协议.md) / [Relay](05-Relay-子协议.md)），**不是协议唯一入口**。
+
+**适用场景**：浏览器、移动端、需要设备管理和在线状态的标准接入。
+
+**Gateway 职责**：
+
+- 本域消息路由（按 AID 转发到本地服务）
+- 跨域消息路由（Gateway-to-Gateway 转发）
+- JWT token 验证
+- 请求转发到 AUN 服务（Auth、Message 等）
+- **不持有**用户 AID 私钥
+- **不处理**业务逻辑
+
+## 3.2 前置条件
+
+- 已创建 AID（通过 `auth.create_aid`）
+- 已获取可用于 `auth.connect` 的访问凭证（常见为 `auth.aid_login1` + `auth.aid_login2` 返回的 JWT access_token）
+- 或已有未过期的 token（重连场景）
+
+## 3.3 Gateway 发现
+
+客户端通过 Well-Known 端点自动发现可用的 Gateway 地址。
+
+**请求**：
+
+```
+GET https://{aid}/.well-known/aun-gateway
+```
+
+其中 `{aid}` 为目标 Agent 的完整 AID（如 `my-agent.agentid.pub`）。
+
+**响应**（`Content-Type: application/json`）：
+
+```json
+{
+  "gateways": [
+    {"url": "wss://gw1.agentid.pub/ws", "priority": 1},
+    {"url": "wss://gw2.agentid.pub/ws", "priority": 2}
+  ]
+}
+```
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|:----:|------|
+| `gateways` | array | ✅ | 可用 Gateway 列表，不可为空 |
+| `gateways[].url` | string | ✅ | Gateway WebSocket 地址（`ws://` 或 `wss://`） |
+| `gateways[].priority` | integer | ❌ | 优先级，数值越小优先级越高，默认 999 |
+
+**客户端行为**：
+
+1. 按 `priority` 升序排序
+2. 选择优先级最高（数值最小）的 Gateway 尝试连接
+3. 连接失败时可降级到下一优先级
+4. 发现结果应缓存，避免每次连接重复查询
+
+## 3.4 连接时序
+
+```
+WebSocket 连接建立
+  ← challenge（服务端推送 nonce）
+  → auth.aid_login1 (可选，已有 token 时跳过)
+  → auth.aid_login2 (可选)
+  → auth.connect(nonce, auth, protocol, device, client, delivery_mode, capabilities)
+  ← {status: "ok", protocol, identity, ...}
+  → READY，进入 Gateway 业务态
+```
+
+> `auth.aid_login1/2` 为可选：如果客户端已持有有效 token，可直接调用 `auth.connect`。
+
+## 3.5 auth.connect
+
+客户端通过 `auth.connect` 完成会话初始化，Gateway 验证认证凭证后建立到 Kernel 的代理连接，返回 `status: "ok"` 即进入 READY 状态。
+
+### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| nonce | string | 是 | 服务端 challenge 中下发的 nonce |
+| auth.method | string | 是 | 认证方式（`"kite_token"` / `"aid"` / `"pairing_code"`） |
+| auth.token | string | 条件必填 | 当 `auth.method="kite_token"` 时必填。当前实现兼容 JWT access_token 与 kite_token |
+| auth.code | string | 条件必填 | 当 `auth.method="pairing_code"` 时必填 |
+| auth.aid | string | 条件必填 | 当 `auth.method="aid"` 时必填，必须是完整 AID |
+| auth.request_id | string | 条件必填 | 当 `auth.method="aid"` 时必填，对应 `auth.aid_login1` 返回的 `request_id` |
+| auth.nonce | string | 条件必填 | 当 `auth.method="aid"` 时必填，对应 `auth.aid_login1` 返回的一次性 nonce |
+| auth.client_time | integer | 条件必填 | 当 `auth.method="aid"` 时必填，客户端毫秒时间戳 |
+| auth.signature | string | 条件必填 | 当 `auth.method="aid"` 时必填，对 `auth.nonce` 的签名 |
+| protocol.min | string | 是 | 客户端支持的最低协议版本 |
+| protocol.max | string | 是 | 客户端支持的最高协议版本 |
+| device.id | string | 推荐 | 设备唯一标识。SDK 默认从 `~/.aun/.device_id` 稳定读取 |
+| device.type | string | 推荐 | 设备类型（desktop/mobile/browser） |
+| client.slot_id | string | 否 | 同一 `device.id` 下的实例槽位。仅在 `device.id` 存在时可用 |
+| delivery_mode.mode | string | 否 | 连接级投递模式：`fanout` 或 `queue` |
+| delivery_mode.routing | string | 否 | 仅 `queue` 时有效：`round_robin` 或 `sender_affinity` |
+| delivery_mode.affinity_ttl_ms | integer | 否 | 仅 `queue + sender_affinity` 时有效，表示发送者粘性保持时长 |
+| capabilities | object | 否 | 客户端能力声明 |
+| client | object | 否 | 客户端信息（名称、版本等） |
+
+**当前实现补充**：
+
+- 顶层 `nonce` 与 `auth.nonce` 语义不同：前者是 Gateway challenge nonce，后者仅 `aid` 模式使用，来自 `auth.aid_login1`
+- `aid` 模式的 `auth.signature` 由客户端对 `auth.nonce` 进行签名；裸 WebSocket 客户端若先获取了 JWT access_token，也可直接改用 `kite_token` 模式连接
+
+**协议版本与能力语义**：
+
+- `protocol.min/max` 在 `auth.connect` 阶段参与 Gateway 会话的协议版本协商。Gateway 将客户端版本范围与服务端支持范围取交集，并选择交集中的最高版本作为响应字段 `protocol`。
+- 若双方版本范围没有交集，Gateway 返回 JSON-RPC 错误 `-32000`，错误数据包含 `server_range` 和 `client_range`，随后关闭 WebSocket 连接。
+- 当前 Gateway 为兼容旧客户端，会把缺失的 `protocol.min/max` 按 `"1.0"` 处理；新客户端仍应显式发送 `protocol: {"min": "1.0", "max": "1.0"}`。
+- `auth.connect.params.capabilities` 是**客户端能力声明**，绑定到当前连接。Gateway 会把它记录到会话，并通过 `client.online` 事件转发给业务服务。
+- `hello-ok.result.capabilities` 是**服务端能力公告**，表示 Gateway/服务端当前暴露的命名空间和功能，不是对客户端能力取交集后的结果。
+- 因此当前机制应描述为“协议版本协商 + 客户端能力声明 + 服务端能力公告”。除非某个扩展明确规定交集规则，否则不要把 `capabilities` 理解为完整的双向能力协商。
+
+**连接约束**：
+
+- 未传 `device.id` 的客户端按 legacy 语义处理，不支持多实例槽位。
+- `client.slot_id` 只能和 `device.id` 一起使用；否则返回 `slot_requires_device_id`。
+- `device.id` 非空但 `client.slot_id` 为空时，同一 `(aid, device.id)` 只允许一个在线实例；冲突时返回 `device_singleton_conflict`。
+- `device.id` 与 `client.slot_id` 同时存在时，同一 `(aid, device.id, client.slot_id)` 只允许一个在线实例；冲突时返回 `slot_conflict`。
+- 同一 `aid` 的所有在线连接必须声明一致的 `delivery_mode`；冲突时返回 `delivery_mode_conflict`。
+- `queue + sender_affinity` 为 best-effort 粘性路由：同一发送者会尽量命中同一实例，实例下线后自动切换。
+
+**capabilities 字段说明**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `e2ee` | boolean | 是否支持 P2P E2EE（接收和发送） |
+| `group_e2ee` | boolean | 是否支持群组 E2EE（接收、解密、密钥协议处理）。所有现代客户端必须声明为 `true` |
+
+当前 Group 服务会读取 `client.online` 中的 `group_e2ee`，用于本域客户端入群、加人等流程的准入检查。跨域客户端的能力声明不会随 `client.online` 跨域传播，服务端按跨域信任策略处理。
+
+请求示例：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "auth.connect",
+  "params": {
+    "nonce": "challenge-nonce-from-server",
+    "auth": {"method": "kite_token", "token": "eyJhbGciOi..."},
+    "protocol": {"min": "1.0", "max": "1.0"},
+    "device": {"id": "dev-001", "type": "browser"},
+    "client": {"slot_id": "slot-a"},
+    "delivery_mode": {
+      "mode": "queue",
+      "routing": "sender_affinity",
+      "affinity_ttl_ms": 300000
+    },
+    "capabilities": {
+      "e2ee": true,
+      "group_e2ee": true
+    }
+  }
+}
+```
+
+### 响应字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| status | string | `"ok"` 表示成功 |
+| protocol | string | 协商后的协议版本 |
+| server_time | number | 服务器时间（Unix 时间戳） |
+| authenticated | boolean | 认证状态 |
+| identity | object | 认证身份信息（含 module_id、role、aid） |
+| connection | object | 连接信息（id、device_id） |
+| bridgeInfo | object | Bridge 信息（name、version） |
+| capabilities | object | 服务端能力声明 |
+| trust_level | string | 信任等级 |
+| token | string | 可选，首次登录时返回 kite_token 供后续重连 |
+
+响应示例：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "status": "ok",
+    "protocol": "1.0",
+    "server_time": 1711234567.890,
+    "authenticated": true,
+    "identity": {
+      "module_id": "gateway-client-abc123",
+      "role": "admin",
+      "aid": "alice.agentid.pub"
+    },
+    "trust_level": "low",
+    "connection": {"id": "conn_gateway-client-abc123", "device_id": "dev-001"},
+    "bridgeInfo": {"name": "Kite Gateway", "version": "0.1"},
+    "capabilities": {
+      "namespaces": ["auth", "message", "meta", "group", "storage", "stream"],
+      "features": {
+        "e2ee": false,
+        "binary_message": false,
+        "max_message_size": 1048576
+      }
+    }
+  }
+}
+```
+
+### 错误码
+
+| 错误码 | 说明 |
+|--------|------|
+| -32000 | 协议版本不匹配 |
+| 4000 | 缺少必要参数（auth.method、nonce 等） |
+| 4001 | 认证失败（token 无效或过期） |
+| 4010 | Nonce 无效或已过期 |
+| 4500 | 服务端内部错误（Auth 服务或 Kernel 不可达） |
+
+**典型错误消息**：
+
+- `slot_requires_device_id`
+- `device_singleton_conflict`
+- `slot_conflict`
+- `delivery_mode_conflict`
+
+### 连接超时
+
+WebSocket 连接建立后 **30 秒**内未完成 `auth.connect`，服务端关闭连接。
+
+## 3.6 心跳与重连
+
+- **心跳**：应用层 `meta.ping`，推荐间隔 30 秒
+- **Token 过期**：连接期间 token 过期时，调用 `auth.refresh_token` 刷新
+- **重连**：新建 WebSocket 连接 → `auth.connect(token)` 重新初始化
+
+> 重连不保留前一次连接的会话状态，需重新 `auth.connect`。
+
+## 3.7 与 auth.* 的关系
+
+| 职责 | 负责方 |
+|------|--------|
+| AID 创建 / 登录 / token 签发与刷新 | `auth.*`（Auth 服务） |
+| Gateway 会话初始化与连接管理 | `auth.connect` |
+| token 转发验证 | Gateway |
+
+- `auth.aid_login1/2` 用于获取 token（身份凭证）
+- Gateway 不处理 `auth.*` 登录逻辑，仅转发到 Auth 服务
+- `auth.connect` 完成 Gateway 模式的会话初始化
+
+## 3.8 跨域消息路由（Gateway-to-Gateway）
+
+当本域客户端需要向其他 Issuer 域的 AID 发送消息时，Gateway 负责跨域中继。
+
+### 路由流程
+
+```
+本域客户端 → 本域 Gateway → 远端 Gateway → 远端服务 → 目标 AID
+```
+
+**关键特性**：
+- 本域服务（Message/Group/Mail）无需感知远端域，只需将跨域请求发给本地 Gateway
+- Gateway 根据目标 AID 的 Issuer 部分（如 `bob.example.com` 中的 `example.com`）发现远端 Gateway
+- Gateway 间通过 WebSocket 长连接通信，复用 JSON-RPC 2.0 协议
+- 远端 Gateway 验证请求后转发到本域服务
+- **auth 管凭证，auth.connect 管连接**——两者职责不同

package/_packed_docs/protocol/04-Peer-/345/255/220/345/215/217/350/256/256.md

@@ -0,0 +1,180 @@
+# 4. Peer 子协议
+
+## 4.1 目标与适用场景
+
+`peer.*` 是 AUN 核心协议的**对等认证子协议**。
+
+**适用场景**：
+
+- **Peer 直连模式** — 双方有可达网络地址，直接 WebSocket 连接
+- **Relay 模式** — 穿透 [Relay](05-Relay-子协议.md) 完成端到端认证
+
+**设计目标**：
+
+- 复用 AID + X.509 证书链信任（见 [02-证书与信任体系](02-证书与信任体系.md)）
+- 不依赖 JWT
+- 对称 challenge-response 双向认证
+- 认证后用 `message.*` 通信
+
+## 4.2 角色与前置条件
+
+- **发起方（Initiator）**：主动发起 `peer.hello` 的一方
+- **响应方（Responder）**：接收并回复的一方
+
+**前置条件**：
+
+- 双方各持有有效 AID 证书和对应私钥
+- 双方各持有受信根证书列表（用于验证对端证书链）
+
+## 4.3 状态机
+
+```
+CONNECTED
+  → initialize(mode=peer)
+  → INITIALIZED
+  → peer.hello
+  → PEER_CHALLENGED
+  → peer.hello_reply
+  → PEER_VERIFIED
+  → peer.confirm
+  → AUTHENTICATED
+  → notification/initialized
+  → READY
+```
+
+## 4.4 peer.hello
+
+发起对等认证。
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| aid | string | 是 | 发起方 AID |
+| cert | string | 是 | 发起方 Agent 证书（PEM） |
+| nonce | string | 是 | 发起方随机挑战（UUID） |
+| protocol | object | 是 | `{min, max}` 协议版本范围 |
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "peer.hello",
+  "params": {
+    "aid": "alice.aid.pub",
+    "cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
+    "nonce": "550e8400-e29b-41d4-a716-446655440000",
+    "protocol": { "min": "0.1", "max": "0.1" }
+  }
+}
+```
+
+## 4.5 peer.hello_reply
+
+响应对等认证并签名对端 nonce。
+
+**响应字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| aid | string | 响应方 AID |
+| cert | string | 响应方 Agent 证书（PEM） |
+| nonce | string | 响应方随机挑战（UUID） |
+| nonce_signature | string | 响应方用私钥对**发起方 nonce** 的签名（Base64） |
+| protocol | string | 协商后的协议版本 |
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "aid": "bob.aid.pub",
+    "cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
+    "nonce": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+    "nonce_signature": "MEUCIQD...",
+    "protocol": "0.1"
+  }
+}
+```
+
+## 4.6 peer.confirm
+
+发起方验证响应方签名后，签名响应方 nonce。
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| nonce_signature | string | 是 | 发起方用私钥对**响应方 nonce** 的签名（Base64） |
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "peer.confirm",
+  "params": {
+    "nonce_signature": "MEYCIQCx..."
+  }
+}
+```
+
+## 4.7 peer.confirmed
+
+认证完成确认。响应方验证签名后返回。
+
+**响应字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| status | string | `"ok"` |
+| authenticated | boolean | `true` |
+| identity | object | `{aid: "alice.aid.pub"}` |
+
+## 4.8 证书链验证规则
+
+1. 验证对端证书链到受信 Root CA（Root CA → Registry CA → Issuer CA → Agent cert）
+2. 校验证书 CN/SAN 与声称的 `aid` 一致
+3. 检查证书有效期
+4. 检查证书吊销状态（CRL 或 OCSP，如可用）
+
+## 4.9 Nonce 与签名规则
+
+- Nonce **一次性使用**，推荐有效期 30-60 秒
+- 签名算法根据证书曲线：
+  - P-256 → ECDSA-SHA256
+  - P-384 → ECDSA-SHA384
+- 验证方使用证书中的公钥验证签名
+- 签名输入为 nonce 原始字节（UTF-8 编码）
+
+## 4.10 版本协商
+
+发起方在 `peer.hello` 中提供 `{min, max}` 版本范围，响应方在 `peer.hello_reply` 中返回双方都支持的**最高版本**。如无交集，返回错误码 -32000。
+
+## 4.11 Peer 地址发现
+
+四种方式：
+
+1. **手动配置** — 直接指定对端地址
+2. **DNS SRV** — `_aun-peer._tcp.{domain}`
+3. **Gateway 信令交换** — 通过 Gateway 传递 `peer.offer` → `peer.accept`（NAT 穿透辅助）
+4. **Agent 目录服务** — 查询 Agent 目录获取端点信息
+
+## 4.12 错误码
+
+| 错误码 | 说明 |
+|--------|------|
+| -32100 | 证书链验证失败 |
+| -32101 | Nonce 已过期 |
+| -32102 | Nonce 重用检测 |
+| -32103 | 签名验证失败 |
+| -32104 | AID 与证书不匹配 |
+| -32105 | 握手状态非法 |
+
+## 4.13 认证完成后的会话语义
+
+认证完成后：
+
+- 双方进入 AUTHENTICATED → READY 状态
+- 可调用所有业务方法（`message.*` 等）
+- 身份由**证书链验证结果**确定，非 JWT
+- 会话生命周期与 WebSocket 连接绑定

package/_packed_docs/protocol/05-Relay-/345/255/220/345/215/217/350/256/256.md

@@ -0,0 +1,164 @@
+# 5. Relay 子协议
+
+## 5.1 目标与适用场景
+
+`relay.*` 是 AUN 核心协议的**中继传输子协议**。
+
+**适用场景**：双方都在 NAT 后无公网 IP，需要轻量中继转发。
+
+Relay 实现极简，核心逻辑约 200 行代码即可完成。
+
+## 5.2 Relay 职责边界
+
+**职责**：
+
+- 维护 AID → WebSocket 连接映射
+- 按目标 AID 转发消息
+- 维持连接与基础流控
+
+**非职责**：
+
+- 不验证证书链
+- 不签发 JWT
+- 不解析内层 `peer.*` 或 `message.*`
+- 不存储历史消息
+
+> Relay 是**零信任笨管道**，所有安全保障由端到端的 [peer.*](04-Peer-子协议.md) 完成。
+
+## 5.3 状态机
+
+```
+CONNECTED
+  → initialize(mode=relay)
+  → INITIALIZED
+  → relay.register
+  → RELAY_REGISTERED
+  → relay.forward(peer.hello)
+  → ...peer.* 穿透认证...
+  → AUTHENTICATED
+  → notification/initialized
+  → READY
+```
+
+## 5.4 relay.register
+
+注册 AID 到 Relay，建立 AID → 连接映射。
+
+**请求**：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "relay.register",
+  "params": { "aid": "alice.aid.pub" }
+}
+```
+
+**响应**：
+
+```json
+{ "jsonrpc": "2.0", "id": 1, "result": { "status": "ok" } }
+```
+
+## 5.5 relay.forward
+
+向指定 AID 转发任意 JSON-RPC 消息。
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| to | string | 是 | 目标 AID |
+| message | object | 是 | 要转发的完整 JSON-RPC 消息 |
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "relay.forward",
+  "params": {
+    "to": "bob.aid.pub",
+    "message": {
+      "jsonrpc": "2.0",
+      "id": 1,
+      "method": "peer.hello",
+      "params": {
+        "aid": "alice.aid.pub",
+        "cert": "-----BEGIN CERTIFICATE-----\n...",
+        "nonce": "550e8400-e29b-41d4-a716-446655440000",
+        "protocol": { "min": "0.1", "max": "0.1" }
+      }
+    }
+  }
+}
+```
+
+**响应**：
+
+```json
+{ "jsonrpc": "2.0", "id": 2, "result": { "status": "forwarded" } }
+```
+
+## 5.6 event/relay.message
+
+Relay 向目标 Agent 投递消息（JSON-RPC Notification）。
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event/relay.message",
+  "params": {
+    "from": "alice.aid.pub",
+    "message": {
+      "jsonrpc": "2.0",
+      "id": 1,
+      "method": "peer.hello",
+      "params": { "..." : "..." }
+    }
+  }
+}
+```
+
+## 5.7 内层消息透明封装规则
+
+- Relay **不解析** `message` 内容
+- Relay 将 `from` 绑定到当前连接已注册的 AID（**不信任**内层 message 中的 from）
+- 可限制最大转发消息尺寸（推荐 64KB）和速率
+
+## 5.8 与 peer.* 的关系
+
+Relay 模式下的身份认证流程：
+
+1. 双方连接 Relay → `initialize(mode=relay)` → `relay.register`
+2. 发起方：`relay.forward({to: "bob", message: peer.hello})`
+3. 对端收到 `event/relay.message`，提取内层 `peer.hello` 处理
+4. 响应方：`relay.forward({to: "alice", message: peer.hello_reply})`
+5. 继续 `peer.confirm` / `peer.confirmed` 流程（均通过 relay.forward 传输）
+6. 认证完成后，业务消息同样通过 `relay.forward` / `event/relay.message` 交换
+
+**Relay 只是传输管道，认证由 [peer.*](04-Peer-子协议.md) 完成。**
+
+## 5.9 Relay 发现
+
+1. **手动配置** — 直接指定 Relay 地址
+2. **公共 Relay 列表** — 自动选择延迟最低的节点
+3. **Gateway 兼任 Relay** — Gateway 实现可同时提供 Relay 功能
+
+## 5.10 错误码
+
+| 错误码 | 说明 |
+|--------|------|
+| -32150 | 未注册，需先 relay.register |
+| -32151 | 目标 AID 未找到 |
+| -32152 | 发送方 AID 不匹配 |
+| -32153 | 转发消息体过大 |
+| -32154 | 速率限制 |
+
+## 5.11 安全说明
+
+- Relay 是**零信任笨管道**，不参与任何认证
+- 不持有 JWT，不验证身份
+- 消息内容对 Relay 完全透明（尤其适合 E2EE 场景）
+- 所有身份验证由端到端 `peer.*` 完成
+- Relay 唯一的安全保障是 `from` 字段绑定（防止 AID 伪装）