@agentunion/fastaun-browser 0.2.18 → 0.2.20

package/_packed_docs/protocol//351/231/204/345/275/225L-E2EE/345/256/236/347/216/260/346/214/207/345/215/227.md

@@ -0,0 +1,267 @@
+# 附录 L：E2EE 实现指南（非规范性）
+
+> **本文档为非规范性内容**：提供端到端加密的实现建议、交互流程、代码示例和安全考虑，不是协议强制要求。
+> 规范性定义见 [08-AUN-E2EE.md](08-AUN-E2EE.md)。
+
+## L.0 加密模式概述
+
+AUN-E2EE 支持两种加密模式，SDK 实现应同时支持。
+
+### L.0.1 模式 1：prekey_ecdh_v2（优先）
+
+**机制**：发送方获取接收方预上传的 prekey，生成临时 ECDH 密钥对，通过四路 ECDH（ephemeral × prekey + ephemeral × identity + sender_identity × prekey + sender_identity × identity）+ HKDF 派生消息密钥。
+
+**优势**：
+- 前向安全（临时密钥用完即丢）
+- 一消息一密钥（每条消息独立临时密钥对）
+- 四路 ECDH 绑定双方身份，防止 prekey 替换攻击和中间人攻击
+- 支持接收方离线
+- 无需在线协商
+
+**限制**：
+- 需要接收方预先上传 prekey
+
+### L.0.2 模式 2：long_term_key（降级）
+
+**机制**：使用接收方长期公钥（从 X.509 证书获取），生成临时 ECDH 密钥对，通过双 DH（ephemeral × recipient_identity + sender_identity × recipient_identity）+ HKDF 派生消息密钥。
+
+**优势**：
+- 支持接收方离线且无 prekey 时发送加密消息
+- 一消息一密钥（每条消息独立临时密钥对）
+- 双 DH 绑定双方身份
+
+**限制**：
+- 不提供严格意义上的前向安全性
+- 长期私钥泄露会导致历史消息被解密
+- Python SDK 默认 `require_forward_secrecy=true`，会拒绝此模式；需显式配置才允许降级
+
+### L.0.3 模式选择策略
+
+SDK 按以下优先级自动选择：
+
+1. **优先**：prekey_ecdh_v2（服务端有接收方 prekey）
+2. **降级**：long_term_key（无 prekey 时）
+
+---
+
+## L.1 交互流程
+
+### L.1.1 prekey_ecdh_v2 时序图
+
+```mermaid
+sequenceDiagram
+    participant Receiver
+    participant Gateway
+    participant Sender
+
+    Note over Receiver: 上线时自动上传 prekey
+    Receiver->>Gateway: message.e2ee.put_prekey {prekey_id, public_key, signature, created_at}
+
+    Note over Sender: 发送加密消息
+    Sender->>Gateway: message.e2ee.get_prekey {aid: receiver}
+    Gateway-->>Sender: {prekey_id, public_key, signature, created_at}
+
+    Note over Sender: 验证 prekey 签名（用 receiver 证书）
+    Note over Sender: 生成临时 ECDH 密钥对
+    Note over Sender: 四路 ECDH：dh1 = ECDH(ephemeral, prekey), dh2 = ECDH(ephemeral, identity), dh3 = ECDH(sender_identity, prekey), dh4 = ECDH(sender_identity, identity)
+    Note over Sender: HKDF(dh1||dh2||dh3||dh4, "aun-prekey-v2:{prekey_id}") → message_key
+    Note over Sender: AES-256-GCM(message_key, plaintext, AAD) → ciphertext
+
+    Sender->>Gateway: message.send {encrypted: true, payload: envelope}
+    Gateway->>Receiver: 推送或 pull
+
+    Note over Receiver: 四路 ECDH(prekey_private + identity_private, ephemeral_public + sender_identity_public) → message_key → 解密
+```
+
+### L.1.2 long_term_key 时序图
+
+```mermaid
+sequenceDiagram
+    participant Sender
+    participant Gateway
+    participant Receiver
+
+    Note over Sender: 获取 receiver 证书（HTTP /pki/cert/{aid}）
+    Sender->>Gateway: GET /pki/cert/{receiver_aid}
+    Gateway-->>Sender: cert_pem
+
+    Note over Sender: 从证书提取长期公钥
+    Note over Sender: 生成临时 ECDH 密钥对
+    Note over Sender: DH1 = ECDH(ephemeral, recipient_identity)
+    Note over Sender: DH2 = ECDH(sender_identity, recipient_identity)
+    Note over Sender: HKDF(DH1 || DH2, info="aun-longterm-v2") → message_key
+    Note over Sender: AES-256-GCM(message_key, plaintext, AAD) → ciphertext
+    Note over Sender: ECDSA 签名(ciphertext + tag + aad_bytes) → sender_signature
+
+    Sender->>Gateway: message.send {encrypted: true, payload: envelope}
+    Gateway->>Receiver: 推送或 pull
+
+    Note over Receiver: 验证 sender_signature（用发送方证书）
+    Note over Receiver: DH1 = ECDH(identity_private, ephemeral)
+    Note over Receiver: DH2 = ECDH(identity_private, sender_identity)
+    Note over Receiver: HKDF → message_key → AES-GCM 解密 → plaintext
+```
+
+---
+
+## L.2 SDK 实现参考（Python）
+
+### L.2.1 通过 AUNClient 发送加密消息（推荐）
+
+```python
+# SDK 自动获取证书和 prekey，自动选择加密模式
+await client.call("message.send", {
+    "to": "bob.agentid.pub",
+    "payload": {"type": "text", "text": "秘密消息"},
+    "encrypt": True,
+})
+```
+
+### L.2.2 通过 AUNClient 接收加密消息
+
+```python
+# 推送自动解密
+client.on("message.received", lambda msg: print(msg["payload"]))
+
+# Pull 自动解密
+result = await client.call("message.pull", {"after_seq": 0, "limit": 50})
+for msg in result["messages"]:
+    if msg.get("encrypted"):
+        print(f"加密模式: {msg['e2ee']['encryption_mode']}")
+        print(f"内容: {msg['payload']}")
+```
+
+### L.2.3 裸 WebSocket 开发者
+
+```python
+from aun_core.e2ee import E2EEManager
+from aun_core.keystore.file import FileKeyStore
+
+# 1. 实例化（纯工具类，无 I/O 依赖）
+e2ee = E2EEManager(
+    identity_fn=lambda: my_identity,
+    keystore=FileKeyStore("~/.aun/myapp"),
+)
+
+# 2. 获取对方证书和 prekey（调用方自行实现 I/O）
+peer_cert_pem = await fetch_cert("bob.agentid.pub")
+prekey = await rpc_call("message.e2ee.get_prekey", {"aid": "bob.agentid.pub"})
+prekey_data = prekey.get("prekey") if prekey.get("found") else None
+
+# 3. 加密（prekey 传入后自动缓存，后续可传 None 复用缓存）
+envelope, ok = e2ee.encrypt_message(
+    to_aid="bob.agentid.pub",
+    payload={"type": "text", "text": "秘密消息"},
+    peer_cert_pem=peer_cert_pem,
+    prekey=prekey_data,
+)
+
+# 4. 通过 WebSocket 发送
+aad = envelope["aad"]
+await rpc_call("message.send", {
+    "to": "bob.agentid.pub",
+    "payload": envelope,
+    "type": "e2ee.encrypted",
+    "encrypted": True,
+    "message_id": aad["message_id"],
+    "timestamp": aad["timestamp"],
+    "delivery_mode": {"mode": "fanout"},
+})
+
+# 5. 解密（内置本地防重放）
+decrypted = e2ee.decrypt_message(raw_message)
+```
+
+---
+
+## L.3 Prekey 管理
+
+### L.3.1 生成与上传
+
+```python
+# E2EEManager 只生成材料，不做 RPC
+material = e2ee.generate_prekey()
+# 返回: {"prekey_id": "uuid", "public_key": "base64", "signature": "base64"}
+
+# 调用方自行上传
+await rpc_call("message.e2ee.put_prekey", material)
+```
+
+AUNClient 连接时自动上传 prekey，并定时轮换（默认每小时）。
+
+### L.3.2 Prekey 签名
+
+签名格式：`ECDSA(identity_private_key, "prekey_id|public_key_b64|created_at")`
+
+接收方用身份私钥签名 prekey（绑定时间戳防止旧 prekey 重放），发送方用接收方证书验证签名，防止服务端替换假 prekey。
+
+### L.3.3 旧 Prekey 私钥保留
+
+旧 prekey 私钥本地保留 7 天（`PREKEY_RETENTION_SECONDS`），确保轮换后在途消息仍可解密。
+
+### L.3.4 Prekey 缓存
+
+E2EEManager 内置 prekey 缓存（默认 TTL 1 小时）：
+
+```python
+e2ee.cache_prekey("bob.agentid.pub", prekey_dict)    # 手动缓存
+cached = e2ee.get_cached_prekey("bob.agentid.pub")    # 查询缓存
+e2ee.invalidate_prekey_cache("bob.agentid.pub")        # 使缓存失效
+```
+
+`encrypt_message` / `encrypt_outbound` 传入 prekey 时自动缓存，传入 None 时自动查缓存。
+
+---
+
+## L.4 防重放
+
+### L.4.1 本地防重放（E2EEManager 内置）
+
+- 维护 `seen_messages` 集合，以 `{sender_aid}:{message_id}` 为 key
+- 同一 key 的消息返回 `None`（拒绝解密）
+- 集合上限 5000 条，超出时淘汰最旧的 20%
+
+### L.4.2 服务端防重放（AUNClient 可选增强）
+
+通过 `server_replay_guard` 配置项开启（默认关闭）：
+
+```python
+client = AUNClient({"server_replay_guard": True})
+```
+
+调用 `message.e2ee.record_replay_guard` RPC，跨进程/跨重启持久化防重放。
+
+---
+
+## L.5 防篡改
+
+AES-GCM + AAD 验证保证消息完整性。AAD 包含以下字段，按 Canonical JSON for AAD 规范序列化（递归键排序 + 紧凑格式 + UTF-8 直接输出，详见 P2P E2EE §8.3）：
+
+| 字段 | 说明 |
+|------|------|
+| `from` | 发送方 AID |
+| `to` | 接收方 AID |
+| `message_id` | 消息唯一标识 |
+| `timestamp` | 发送时间戳（ms） |
+| `encryption_mode` | 加密模式 |
+| `suite` | 算法套件 |
+| `ephemeral_public_key` | 发送方临时公钥 |
+| `recipient_cert_fingerprint` | 接收方证书公钥指纹 |
+
+任何字段被篡改都会导致 AEAD tag 校验失败，解密报错。
+
+---
+
+## L.6 安全建议
+
+1. **不静默降级**：加密失败时不应静默发送明文，应由上层应用显式决定
+2. **临时密钥**：每条消息使用独立的临时 ECDH 密钥对，用完即丢
+3. **私钥保护**：Prekey 私钥通过 FileKeyStore 加密存储（Windows DPAPI / SecretStore）
+4. **证书验证**：发送方必须验证 prekey 签名，防止中间人替换
+5. **Prekey 轮换**：建议每小时轮换一次 prekey，旧私钥保留 7 天
+
+---
+
+## L.7 兼容性说明
+
+- 发送端 **MUST** 使用 `prekey_ecdh_v2`（四路 ECDH）模式发送新消息

package/_packed_docs/protocol//351/231/204/345/275/225M-JWT/350/256/244/350/257/201/345/256/236/347/216/260/346/214/207/345/215/227.md

@@ -0,0 +1,367 @@
+# 附录 M：JWT 认证实现指南（非规范性）
+
+> **本文档为非规范性内容**：提供 JWT Token 认证的实现建议、代码示例和安全考虑，不是协议强制要求。
+
+## M.1 Token 签发实现
+
+### M.1.1 签发流程
+
+**Auth 服务端实现**：
+
+```
+1. 客户端完成两阶段认证
+   ↓
+2. Auth 服务验证签名和证书
+   - 从 cert 中提取公钥
+   - 验证 signature = sign(privateKey, nonce)
+   - 验证 cert 由 CA 签发
+   - 验证 cert 未过期
+   - 验证 cert.CN == aid
+   ↓
+3. Auth 服务生成 JWT token
+   - Header: {"alg": "ES256", "typ": "JWT"}  (P-256 Auth 服务) 或 {"alg": "ES384", "typ": "JWT"} (P-384 Auth 服务)
+   - Payload: {
+       "aid": "alice.aid.pub",
+       "iat": 1709712000,        // 签发时间
+       "exp": 1709798400,        // 过期时间（24小时后）
+       "iss": "auth.aid.pub",      // 签发者（Auth 服务的 AID）
+       "sub": "alice.aid.pub",   // 主体（用户 AID）
+       "aud": "aun"              // 受众（固定值 "aun"，标识 token 用途）
+     }
+   - Signature: ECDSA-SHA256(Header + Payload, Auth_PrivateKey) 或 ECDSA-SHA384
+   ↓
+4. Auth 服务返回 token
+   → {token: "eyJhbGc...", expires_in: 3600}
+```
+
+### M.1.2 JWT Token 结构
+
+```
+eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9.eyJhaWQiOiJhbGljZS5haWQucHViIiwiaWF0IjoxNzA5NzEyMDAwLCJleHAiOjE3MDk3OTg0MDAsImlzcyI6ImFwLmFpZC5wdWIiLCJzdWIiOiJhbGljZS5haWQucHViIn0.signature_bytes
+│                                   │                                                                                                                                  │
+│         Header (Base64)           │                                    Payload (Base64)                                                                              │  Signature
+```
+
+**签名算法**：
+- 算法：ES256（ECDSA-SHA256）或 ES384（ECDSA-SHA384）
+- Auth 服务密钥为 P-256 时使用 ES256，P-384 时使用 ES384
+- 使用 Auth 服务私钥进行 ECDSA 签名（非对称签名）
+- 所有服务持有 Auth 服务公钥证书，可独立验证 token（无需共享密钥）
+
+## M.2 Token 验证实现
+
+### M.2.1 验证流程
+
+**所有 AUN 服务端实现**：
+
+```
+1. 服务收到请求（携带 JWT token）
+   ↓
+2. 提取 token
+   - WebSocket: 从 `auth.connect.params.auth.token` 中获取
+   - 连接状态：token 验证后存储在连接上下文
+   ↓
+3. 解析 token
+   - Base64 解码 Header 和 Payload
+   - 提取签名部分
+   ↓
+4. 验证签名
+   - 使用 Auth 服务的公钥证书
+   - 验证 ECDSA 签名
+   - 算法：ES256（ECDSA-SHA256）或 ES384（ECDSA-SHA384）
+   ↓
+5. 验证 Payload
+   - 检查 exp（过期时间）：exp > now
+   - 检查 iss（签发者）：iss == "auth.aid.pub"
+   - 检查 aud（受众）：aud == "aun"
+   - 检查 aid（用户身份）：aid 格式正确
+   ↓
+6. 提取用户信息
+   - aid: 用户的 Agent Identifier
+   - aud: 验证 aud == "aun"，确认 token 用途
+   - 用于标识请求来源身份（身份认证）
+   - **注意**：JWT 仅提供身份认证，不包含授权信息。资源访问控制由各 AUN 服务根据业务逻辑自行实现
+```
+
+### M.2.2 Go 实现示例
+
+```go
+import (
+    "github.com/golang-jwt/jwt/v5"
+)
+
+// Auth 服务的公钥证书（ECDSA 非对称签名，所有服务持有公钥）
+var authPublicKey *ecdsa.PublicKey
+
+func verifyToken(tokenString string) (*Claims, error) {
+    token, err := jwt.ParseWithClaims(tokenString, &Claims{}, func(token *jwt.Token) (interface{}, error) {
+        // 验证签名算法（ES256 或 ES384）
+        if _, ok := token.Method.(*jwt.SigningMethodECDSA); !ok {
+            return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
+        }
+        return authPublicKey, nil
+    })
+
+    if err != nil {
+        return nil, err
+    }
+
+    if claims, ok := token.Claims.(*Claims); ok && token.Valid {
+        return claims, nil
+    }
+
+    return nil, fmt.Errorf("invalid token")
+}
+
+type Claims struct {
+    AID string `json:"aid"`
+    jwt.RegisteredClaims
+}
+```
+
+## M.3 客户端 Token 使用
+
+### M.3.1 客户端签名实现
+
+在 `auth.aid_login2` 阶段，客户端需要对 nonce 进行签名：
+
+**签名内容**：
+```
+message = nonce + ":" + client_time
+signature = ECDSA_sign(private_key, SHA256(message))
+```
+
+**JavaScript 实现示例**：
+```javascript
+// 客户端签名
+const nonce = "server_challenge_nonce";
+const client_time = Math.floor(Date.now() / 1000);
+const message = `${nonce}:${client_time}`;
+const signature = await crypto.subtle.sign(
+  { name: "ECDSA", hash: "SHA-256" },
+  privateKey,
+  new TextEncoder().encode(message)
+);
+
+// 发送 login_aid2 请求
+const response = await rpc.call('auth.aid_login2', {
+  request_id: requestId,
+  nonce: nonce,
+  client_time: client_time,
+  signature: arrayBufferToBase64(signature),
+  cert: certPem
+});
+
+// 获取 token
+const token = response.token;
+```
+
+### M.3.2 Token 使用示例
+
+Token 统一通过 `auth.connect` 消息传递。每次 WebSocket 连接（包括重连）都必须在收到 Gateway `challenge` 后调用 `auth.connect`：
+
+```javascript
+function sendAuthConnect(ws, nonce, token) {
+  ws.send(JSON.stringify({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'auth.connect',
+    params: {
+      nonce,
+      auth: { method: 'kite_token', token },
+      protocol: { min: '1.0', max: '1.0' },
+      device: { id: 'dev-001', type: 'browser' },
+      client: { name: 'MyApp', version: '1.0.0' },
+      capabilities: { e2ee: true, group_e2ee: true }
+    }
+  }));
+}
+
+// 首次登录：先调用 auth.* 获取 token，再 auth.connect
+const ws = new WebSocket('wss://gateway.example.com/aun');
+ws.onmessage = async (event) => {
+  const msg = JSON.parse(event.data);
+  if (msg.method !== 'challenge') return;
+
+  // 1. 在 auth.connect 之前调用 auth.* 获取 token
+  const token = await loginFlow(ws); // login_aid1 + login_aid2
+
+  // 2. 用 token 调用 auth.connect 完成会话初始化
+  sendAuthConnect(ws, msg.params.nonce, token);
+};
+
+// 重连：直接用已有 token 调用 auth.connect
+const ws2 = new WebSocket('wss://gateway.example.com/aun');
+ws2.onmessage = (event) => {
+  const msg = JSON.parse(event.data);
+  if (msg.method === 'challenge') {
+    sendAuthConnect(ws2, msg.params.nonce, saved_jwt_token);
+  }
+};
+```
+
+**优势**：
+- Token 不出现在 URL、服务器日志和浏览器历史中
+- 统一的传递方式，所有客户端实现一致
+- 与 JSON-RPC 2.0 协议自然融合
+
+## M.4 安全架构
+
+### M.4.1 单一信任根
+
+```
+┌─────────────────────────────────────────────────┐
+│              单一信任根架构                        │
+├─────────────────────────────────────────────────┤
+│                                                 │
+│   Auth 服务                                  │
+│   ├─ 持有私钥（唯一能签发 token）                 │
+│   └─ 签发 JWT token                             │
+│                                                 │
+│   所有 AUN 服务                                  │
+│   ├─ HB (Heartbeat)                             │
+│   ├─ MSG (Message)                              │
+│   ├─ Storage                                    │
+│   ├─ Group                                      │
+│   └─ 都持有 Auth 服务的公钥证书               │
+│      └─ 可以验证 token（ECDSA 非对称签名）       │
+│                                                 │
+│   Gateway                                       │
+│   ├─ 只能转发认证请求                            │
+│   ├─ 无法伪造 Auth 服务的签名                │
+│   └─ 恶意 Gateway 签发的假 token 会被拒绝        │
+│                                                 │
+└─────────────────────────────────────────────────┘
+```
+
+### M.4.2 防止 Gateway 作恶
+
+1. **无法伪造 token**：
+   - Gateway 没有 Auth 服务的私钥
+   - 无法生成有效的 ECDSA 签名
+   - 所有服务都会拒绝无效签名的 token
+
+2. **无法冒充其他用户**：
+   - Token 中的 `aid` 字段标识用户身份
+   - 即使恶意 Gateway 用自己的 AID 获取 token
+   - 也无法访问其他用户的资源（token 中的 aid 与资源归属不匹配）
+
+3. **私钥不经过 Gateway**：
+   - 客户端本地签名 nonce
+   - Gateway 只转发签名，看不到私钥
+   - 无法伪造用户签名
+
+## M.5 Token 生命周期管理
+
+### M.5.1 有效期与刷新
+
+**有效期**：
+- 推荐：1-24 小时
+- 具体由 Auth 服务决定
+
+**过期处理**：
+- 客户端需要重新认证
+- 或使用 `auth.refresh_token` 刷新
+
+**刷新机制**：
+
+AUN 协议定义了简化的单 token 刷新模型（参见主规范 8.3.4 节）：
+- 客户端在已认证连接上调用 `auth.refresh_token`（空参数）
+- Auth 服务返回新的 JWT token
+- 旧 token 在过期前仍然有效
+
+**可选增强：双 Token 模式**
+
+实现方可以选择使用更安全的双 token 模式：
+```
+短期 access_token（1小时）+ 长期 refresh_token（7天）
+access_token 过期后，用 refresh_token 换取新的 access_token
+```
+
+这种模式的优势：
+- access_token 有效期短，降低泄露风险
+- refresh_token 只在刷新时使用，减少暴露
+- 可以实现更细粒度的撤销控制
+
+**注意**：双 token 模式需要扩展 `auth.refresh_token` 的参数和响应结构，不在核心协议规范中定义。
+
+**JWT 与证书绑定**：
+- JWT 的有效期不得超过签发该 JWT 的 Auth 服务证书的有效期
+- 证书过期后所有由该证书签发的 JWT 自动失效
+
+**刷新限制**：
+- 刷新链总时长不超过 30 天，或最多刷新 720 次
+- 达到限制后必须重新用证书签名登录
+
+## M.6 证书轮换与双证书过渡
+
+### M.6.1 轮换通用原则
+
+整个证书层级（Root CA → Issuer CA → Auth 服务/Agent）都存在轮换需求，轮换期间必须保证新旧双证书同时有效：
+
+```
+证书轮换通用原则：
+
+1. 新证书签发时，旧证书仍在有效期内
+2. 进入双证书过渡期：新旧证书并存于证书库
+3. 过渡期内，两张证书都可用于验证
+4. 过渡期结束后（旧证书签发的所有下级证书/JWT 均已过期），旧证书退役
+```
+
+### M.6.2 各层级轮换要点
+
+| 层级 | 典型有效期 | 过渡期 | 影响范围 |
+|------|-----------|--------|---------|
+| Root CA | 20-30 年 | 数年 | 全局信任锚，所有客户端证书库需更新 |
+| Issuer CA | 10-15 年 | 1-2 年 | 该 Issuer 下所有 Agent |
+| Auth 服务证书 | 1-2 年 | ≤ 旧 token 最大剩余有效期 | 已签发的 JWT |
+
+### M.6.3 证书库要求
+
+- `auth.download_cert` 返回的证书库必须包含过渡期内的新旧两张证书
+- 客户端验证证书链时，按证书序列号匹配，新旧证书均可构成有效链
+- Root CA 轮换时，客户端受信列表需同时包含新旧两个根证书，直到旧根签发的所有下级证书全部过期
+
+### M.6.4 Auth 服务证书轮换与 JWT 有效性
+
+Auth 服务证书轮换直接影响 JWT 验证，需特别处理：
+
+- 新 JWT 用新证书私钥签发
+- 旧 JWT 仍可用旧证书公钥验证
+- JWT Header 中通过 `kid`（Key ID）标识签发证书：`{"alg": "ES256", "kid": "auth-cert-sn-002"}`
+- 验证端按 `kid` 匹配证书公钥
+- 过渡期 = 旧 token 最大剩余有效期（通常 ≤ 24 小时）
+- 过渡期结束后，旧 Auth 服务证书退役
+- 客户端无感知，无需重新登录
+
+## M.7 审计与监控
+
+### M.7.1 日志记录
+
+**Auth 服务**：
+- 记录所有 token 签发日志
+- 包含：aid、签发时间、过期时间、客户端信息
+
+**各 AUN 服务**：
+- 记录 token 验证失败日志
+- 包含：token 内容、失败原因、请求来源
+
+### M.7.2 异常检测
+
+- 追踪异常 token 使用模式
+- 检测重放攻击
+- 检测伪造 token 尝试
+
+### M.7.3 Token 撤销
+
+**黑名单机制**：
+- 维护已撤销 token 的黑名单
+- 验证时检查 token 是否在黑名单中
+- 黑名单条目在 token 过期后自动清理
+
+**撤销场景**：
+- 用户主动登出
+- 检测到账户异常
+- 证书被吊销
+
+---