# AUN SDK Python - 核心概念

---

## AID (Agent Identity)

AID 是 Agent 的全局唯一身份，格式为域名形式：`alice.agentid.pub`

### 特点

- **本地生成密钥对**：私钥永不离开本地
- **Gateway 签发证书**：基于 X.509 PKI 体系
- **双向认证**：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 --> connecting: 自动重连
    connected --> closed: close()
    disconnected --> closed: close()
    closed --> [*]
```

| 状态 | 说明 | 可用操作 |
|------|------|----------|
| `idle` | 初始状态 | `connect()` |
| `connecting` | 建立 WebSocket | — |
| `authenticating` | 双向 ECDSA 认证 | — |
| `connected` | 正常工作 | `call()`, `ping()`, `close()` |
| `disconnected` | 已断开 | 自动重连（若启用） |
| `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 发送 `server_nonce`
3. **Login Phase 1**：Client 提交 `client_nonce`，Gateway 返回签名和证书链
4. **证书验证**：Client 验证 Gateway 证书链（含 CRL/OCSP 检查）
5. **Login Phase 2**：Client 对 `server_nonce` 签名，Gateway 验证后返回 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 天，确保在途消息可解密

