# 总体架构

## 分层总览

```mermaid
graph TB
    subgraph App["应用层"]
        A1["AI Agent / 人类开发者 / 前端应用"]
        A2["client.call(method, params)"]
        A3["client.on(event, handler)"]
    end

    subgraph RPC["RPC Manual（文档层，非代码）"]
        R1["message.* - P2P 消息"]
        R2["group.* - 群组管理"]
        R3["storage.* - 对象存储"]
        R4["meta.* - 元信息查询"]
        R5["定义方法签名、参数、返回值、错误码"]
    end

    subgraph Core["SDK Core（代码封装层）"]
        C1["AUNClient - 连接生命周期、call()、on()"]
        C2["Auth - create_aid、authenticate、token"]
        C3["Transport - WebSocket + JSON-RPC 2.0"]
        C4["E2EE - 端到端加密与群组 epoch 密钥管理"]
        C5["KeyStore - ECC 密钥对持久化"]
        C6["SecretStore - 令牌安全存储"]
        C7["EventDispatcher - 发布-订阅事件分发"]
    end

    subgraph Trans["传输层"]
        T1["WebSocket (JSON-RPC 2.0) + HTTP (数据面)"]
        T2["TLS 1.3"]
    end

    App --> RPC
    RPC --> Core
    Core --> Trans
```

**Core 封装边界**：凡涉及密码学运算、本地状态管理、连接状态机的，由 Core 封装。凡业务层的请求-响应交互，由 RPC Manual 描述、调用者自行 `call()`。

## 网络拓扑

AUN 协议设计支持三种连接模式。**当前各语言 SDK 的稳定连接模式都是 Gateway；Peer/Relay 仍停留在协议定义层。**

### 当前 SDK 支持矩阵

| SDK | Gateway | Peer | Relay |
|-----|---------|------|-------|
| Python | 已实现 | `connect(topology={"mode":"peer"})` 明确报未实现 | `connect(topology={"mode":"relay"})` 明确报未实现 |
| Browser JS | 已实现 | 明确报未实现 | 明确报未实现 |
| TypeScript | 已实现 | 明确报未实现 | 明确报未实现 |
| Go | 已实现（当前按 `gateway` URL 建立会话） | 未实现独立 peer 传输 | 未实现独立 relay 传输 |

### Gateway 模式（已实现）

```
Client ──WebSocket──▶ Gateway ──JSON-RPC──▶ Kernel ──▶ 各服务模块
                         │
                    JWT 认证、权限检查、事件转发
```

- 客户端通过 Gateway 接入，Gateway 负责认证和权限控制
- 适用于公网接入、移动端、浏览器

### Peer 模式（协议已定义，SDK connect 未实现）

```
Client A ◀──WebSocket──▶ Client B
              │
         双向证书验证（peer.hello / hello_reply / confirm）
```

- 两个 Agent 直接建立 WebSocket 连接
- 通过证书互验完成双向认证，不依赖 JWT
- 适用于局域网、已知对端地址的场景
- 当前 Python / Browser JS / TypeScript SDK 会显式拒绝 peer 拓扑
- Go SDK 当前也不会建立独立的 peer 传输

### Relay 模式（协议已定义，SDK connect 未实现）

```
Client A ──▶ Relay ◀── Client B
               │
          AID 路由转发（零信任笨管道）
```

- Relay 仅维护 AID→WebSocket 映射并转发消息
- 不验证证书、不签发 JWT、不解析消息内容
- 认证由端到端 peer.* 握手完成（穿透 Relay）
- 适用于 NAT 穿透、无法直连的场景
- 当前 Python / Browser JS / TypeScript SDK 会显式拒绝 relay 拓扑
- Go SDK 当前也不会建立独立的 relay 传输

### 拓扑对上层的透明性

下表描述的是**协议设计目标**。当前 SDK 的实际连接生命周期仍主要落在 Gateway 模式：

| 特性 | Gateway | Peer | Relay |
|------|---------|------|-------|
| 认证方式 | JWT（auth.* + initialize） | 证书互验（peer.*） | peer.* 穿透 Relay |
| 权限模型 | 角色（admin/agent/viewer） | 对等（双方平级） | 对等 |
| 事件推送 | Gateway 转发 | 对端直接推送 | Relay 转发 |
| `client.call()` | 一致 | 一致 | 一致 |
| `client.on()` | 一致 | 一致 | 一致 |

## Namespace 全景

| Namespace | 定位 | 方法数 | 数据面 |
|-----------|------|--------|--------|
| **message** | P2P 消息收发、离线存储、送达确认 | 6 | 无 |
| **group** | 群组生命周期、成员管理、群消息、资源共享 | 50+ | HTTP（群资源下载） |
| **storage** | 对象存储、文件上传下载、配额管理 | 12 | HTTP（大文件上传/下载） |
| **meta** | 心跳、状态查询、信任根证书 | 3 | 无 |

**Namespace 间关系**：
- `group` 依赖 `storage` 管理群资源（头像、附件）
- `message` 和 `group` 共享相似的 seq/ack 投递模型
- `meta` 独立于所有业务 namespace

**未来 namespace**（协议已规划，尚未实现）：
- `federation.*` — 跨 Issuer 消息路由（mTLS）
- `search.*` — Agent 搜索与发现
- `task.*` — Agent 协作与任务执行

## 数据流

### 请求-响应（RPC）

```mermaid
sequenceDiagram
    participant A as 应用层
    participant C as SDK Core
    participant S as 服务端

    A->>C: client.call(method, params)
    C->>S: JSON-RPC Request<br/>{method, params, id}
    S-->>C: JSON-RPC Response<br/>{result, id}
    C-->>A: return result
```

### 事件推送（Notification）

```mermaid
sequenceDiagram
    participant S as 服务端
    participant C as SDK Core
    participant A as 应用层

    S->>C: JSON-RPC Notification<br/>{method: "event/xxx"}
    C->>A: dispatch("xxx", payload)
    Note over A: handler(payload)
```

### 数据面（HTTP，仅 storage 和 group resources）

```mermaid
sequenceDiagram
    participant A as 应用层
    participant C as SDK Core / 应用层
    participant S as 服务端
    participant B as Blob 后端

    A->>C: 1. RPC: 申请 ticket
    C->>S: create_upload_session
    S-->>C: {upload_url}

    A->>C: 2. HTTP: 上传数据
    C->>B: HTTP PUT upload_url

    A->>C: 3. RPC: 确认上传
    C->>S: complete_upload
    S-->>C: {PutResult}
```

> 注：数据面的 HTTP 调用不在 SDK Core 封装范围内。RPC Manual 中会详细说明 ticket 流程，调用者用 aiohttp/requests/fetch 等自行完成 HTTP 部分。

## 认证与安全模型

### 证书链

```
Root CA (P-384, pathlen=2)
  └── Registry CA (P-384, pathlen=1)
        └── Issuer CA (P-384, pathlen=0)
              └── Agent cert (P-256)
```

- 每个 Agent 持有 P-256 密钥对和 X.509 证书
- 证书由 Issuer CA 签发，通过 `auth.create_aid` 获得
- 证书链可离线验证（不依赖在线服务）

### 认证流程

```mermaid
sequenceDiagram
    participant C as Client
    participant S as Server (Auth)

    C->>S: auth.aid_login1<br/>{aid, cert_chain, nonce_c}
    Note over S: 验证证书链<br/>签名 nonce_c
    S-->>C: {nonce_s, server_sig}

    Note over C: 验证 server_sig

    C->>S: auth.aid_login2<br/>{client_sig(nonce_s)}
    Note over S: 验证 client_sig<br/>签发 JWT
    S-->>C: {access_token, refresh_token}
```

### 安全层级

| 层级 | 机制 | 保护范围 |
|------|------|---------|
| 传输层 | TLS 1.3 | 链路加密 |
| 认证层 | 双向 ECDSA 挑战-响应 + JWT | 身份验证 |
| 应用层（可选） | E2EE (P256_HKDF_SHA256_AES_256_GCM) | 端到端内容加密 |

E2EE 是独立的安全层，横跨三种网络拓扑，不替代传输层 TLS 和认证层 JWT/证书验证。
