@agentunion/kite 1.5.0 → 1.6.1

package/docs//346/217/241/346/211/213/350/256/244/350/257/201/346/226/271/346/241/210.md

@@ -0,0 +1,908 @@
+# 握手认证方案
+
+## 架构模型
+
+```
+本地模块 ──connect──→ Kernel（仅 token 认证）
+远程模块 ──connect──→ Relay ──token──→ Kernel
+```
+
+- Kernel 只认 token，永远不变
+- 远程认证全部收敛在 Relay
+- Kernel 和 Relay 对客户端暴露**完全相同的四步握手协议**
+
+## 握手流程
+
+```
+① 客户端 → WS connect
+② ← challenge（服务端主动推送）
+③ → connect 请求（含 nonce + 版本 + 身份 + 认证）
+④ ← hello-ok / 拒绝
+```
+
+### 时序图 1：本地模块握手（Token 认证）
+
+```mermaid
+sequenceDiagram
+    participant L as Launcher
+    participant M as Module
+    participant K as Kernel
+
+    L->>M: stdin {token}
+    M->>K: WS connect
+    K-->>K: accept
+    K->>M: challenge {nonce, ts, timeout_ms}
+    M->>K: connect {nonce, protocol, client, auth:{method:"token", token}}
+    K-->>K: verify_token (hmac.compare_digest)
+    K-->>K: check protocol.min/max
+    K-->>K: check (device, channel) 并发
+    K->>M: hello-ok {protocol, kernel, identity, policy, features, snapshot}
+    Note over M,K: 已认证，正常通信
+```
+
+### 时序图 2：远程模块握手（配对码认证）
+
+```mermaid
+sequenceDiagram
+    actor U as User
+    participant F as Frontend
+    participant R as Relay
+    participant K as Kernel
+
+    U->>F: 点击获取配对码
+    F->>R: request_code
+    R-->>R: generate code
+    R-->>R: 控制台输出 code (stdout)
+    R->>F: code_generated
+
+    U->>U: 看到配对码
+    U->>F: 输入配对码
+    F->>R: WS connect
+    R-->>R: accept
+    R->>F: challenge {nonce, ts}
+    F->>R: connect {nonce, protocol, auth:{method:"pairing_code", code:"482916"}}
+    R-->>R: verify code
+
+    rect rgb(240, 248, 255)
+        Note over R,K: Relay → Kernel 内部连接
+        R->>K: kernel.generate_tokens
+        K->>R: token
+        R->>K: WS connect
+        K->>R: challenge
+        R->>K: connect {auth:{method:"token"}}
+        K->>R: hello-ok
+    end
+
+    R->>F: hello-ok (透传 kernel 信息 + Relay 策略)
+    Note over F,K: 已认证，Relay 双向代理
+```
+
+### 时序图 3：AID 密码学认证（后续）
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant R as Relay
+    participant K as Kernel
+
+    C->>R: WS connect
+    R-->>R: accept
+    R->>C: challenge {nonce, ts}
+    C-->>C: sign(privkey, "nonce:signed_at:aid")
+    C->>R: connect {nonce, protocol, auth:{method:"aid", aid, signature, signed_at}}
+    R-->>R: lookup aid → pubkey
+    R-->>R: verify signature
+    R-->>R: check signed_at (±10 min)
+    R-->>R: check nonce
+
+    rect rgb(240, 248, 255)
+        Note over R,K: Relay → Kernel 内部连接
+        R->>K: WS connect + token 认证
+        K->>R: hello-ok
+    end
+
+    R->>C: hello-ok
+    Note over C,K: 已认证，Relay 双向代理
+```
+
+### 时序图 4：同 ID 并发连接 — 踢旧连接
+
+```mermaid
+sequenceDiagram
+    participant Old as Module (旧连接)
+    participant New as Module (新连接)
+    participant K as Kernel
+
+    Note over Old,K: 旧连接已认证，正常通信中
+
+    New->>K: WS connect
+    K->>New: challenge
+    New->>K: connect (同 id, 同 device, 同 channel)
+    K-->>K: 检测并发: device+channel 重复
+    K->>Old: {type:"kicked", reason:"replaced"}
+    K--xOld: close (code=4009)
+    Note over Old: 不应自动重连
+    K->>New: hello-ok
+    Note over New,K: 新连接正常通信
+```
+
+### 时序图 5：Token 轮换
+
+```mermaid
+sequenceDiagram
+    participant M as Module
+    participant K as Kernel
+
+    Note over M,K: 首次连接（旧 token）
+    M->>K: WS connect
+    K->>M: challenge
+    M->>K: connect {auth:{token: "old-token"}}
+    K-->>K: verify old-token ✓
+    K-->>K: 决定轮换 token
+    K->>M: hello-ok {token_rotation: {new_token: "xxx", grace_period_ms: 300000}}
+    M-->>M: 保存 new_token
+
+    Note over M,K: 断线重连（使用新 token）
+    M->>K: WS connect
+    K->>M: challenge
+    M->>K: connect {auth:{token: "xxx"}}
+    K-->>K: verify new-token ✓
+    K->>M: hello-ok
+```
+
+### 时序图 6：速率限制（Relay）
+
+```mermaid
+sequenceDiagram
+    participant A as Attacker
+    participant R as Relay
+
+    A->>R: connect (认证失败 1)
+    A->>R: connect (认证失败 2)
+    A->>R: connect (认证失败 3)
+    A->>R: connect (认证失败 4)
+    A->>R: connect (认证失败 5)
+    Note over R: 前 5 次无限制（间隔 ≥ 100ms）
+    A->>R: connect (认证失败 6)
+    Note over R: 触发退避：限制 1 秒
+
+    A->>R: connect
+    R->>A: 4029 rate limited {retry_after_ms: 1000}
+
+    Note over A,R: 1 秒后
+    A->>R: connect (认证失败 7)
+    Note over R: 退避升级：限制 2 秒
+
+    A->>R: connect
+    R->>A: 4029 rate limited {retry_after_ms: 2000}
+
+    Note over A,R: 退避持续翻倍，最长 5 分钟
+```
+
+### 第 ① 步：WS 连接
+
+客户端连接 `ws://{host}:{port}/ws`，Kernel/Relay accept 后立即进入第 ② 步。
+
+### 第 ② 步：challenge
+
+```json
+{
+  "type": "challenge",
+  "nonce": "a1b2c3d4-uuid",
+  "ts": 1710000000000,
+  "timeout_ms": 10000
+}
+```
+
+- `nonce`：UUID，一次性使用，用后即废
+- `ts`：服务端时间戳（毫秒），客户端可用于时钟偏移检测
+- `timeout_ms`：客户端必须在此时间内完成第 ③ 步，否则关闭连接（code=4003）
+- 服务端维护 pending nonce 池，nonce 被使用或超时后从池中移除
+
+### 第 ③ 步：connect 请求
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "connect-1",
+  "method": "connect",
+  "params": {
+    "nonce": "a1b2c3d4-uuid",
+    "protocol": {
+      "min": 1,
+      "max": 1
+    },
+    "client": {
+      "id": "web",
+      "type": "module",
+      "version": "0.5.0",
+      "platform": "python",
+      "device": "server-01",
+      "channel": "default"
+    },
+    "auth": {
+      "method": "token",
+      "token": "xxx"
+    }
+  }
+}
+```
+
+#### params 字段
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `nonce` | ✅ | 回传 challenge 中的 nonce |
+| `protocol` | ✅ | 协议版本范围，不传则握手失败 |
+| `protocol.min` | ✅ | 客户端支持的最低协议版本 |
+| `protocol.max` | ✅ | 客户端支持的最高协议版本 |
+| `client` | ✅ | 客户端身份描述 |
+| `client.id` | ✅ | 模块名 / 客户端标识 |
+| `client.type` | ✅ | `"module"` / `"frontend"` / `"node"` |
+| `client.version` | ✅ | 客户端版本号 |
+| `client.device` | ❌ | 设备标识（同一模块多设备部署时区分） |
+| `client.channel` | ❌ | 通道标识（同一设备多通道连接时区分） |
+| `client.platform` | ❌ | `"python"` / `"nodejs"` / `"browser"` / `"binary"` |
+| `client.runtime` | ❌ | 运行时信息，调试用 |
+| `auth` | ✅ | 认证信息，见下方四种方式 |
+
+#### 版本协商
+
+Kernel/Relay 持有当前协议版本 `PROTOCOL_VERSION`（整数，以 Kernel 版本为基准）。
+
+协商逻辑：
+- `protocol` 字段不存在 → 拒绝（code=4002，`"protocol field required"`）
+- `client.max < PROTOCOL_VERSION` → 拒绝（code=4002，返回 `{"expected": PROTOCOL_VERSION}`）
+- `client.min > PROTOCOL_VERSION` → 拒绝（code=4002，同上）
+- 否则 → 协商成功，取 `min(client.max, PROTOCOL_VERSION)` 作为本次连接使用的版本号
+
+## 认证方式
+
+### 方式 1：Token（本地模块 → Kernel，Relay → Kernel）
+
+Launcher 通过 stdin 分发 Kernel 生成的 token，模块用 token 认证。
+
+```json
+{
+  "method": "token",
+  "token": "kernel-generated-token"
+}
+```
+
+Kernel 验证：`hmac.compare_digest(token, expected)`（时序安全比较）。
+
+### 方式 2：配对码（远程客户端 → Relay）
+
+流程：
+1. 用户在控制台前端选择"配对码登录"
+2. 点击获取配对码，Relay 生成 6 位配对码
+3. 配对码在**服务端控制台**输出，用户通过其他渠道看到
+4. 用户在前端输入配对码
+5. 前端在 connect 请求中携带
+
+```json
+{
+  "method": "pairing_code",
+  "code": "482916"
+}
+```
+
+Relay 验证配对码后，从 Kernel 获取 token，建立代理连接。配对码有效期 5 分钟，一次性。
+
+### 方式 3：短信验证码（远程客户端 → Relay）
+
+机制同配对码，获取方式为手机短信。
+
+```json
+{
+  "method": "sms",
+  "phone": "138xxxx1234",
+  "code": "592831"
+}
+```
+
+Relay 验证验证码 + 手机号在 owners 列表中。
+
+### 方式 4：AID 密码学登录（远程客户端 → Relay，后续增加）
+
+注册阶段：
+1. 客户端本地生成 Ed25519 密钥对
+2. 客户端选择一个 AID（AI Device ID）
+3. 通过已认证的连接（配对码/短信）提交 `{aid, public_key}` 给 Relay 完成绑定
+
+登录阶段：
+
+```json
+{
+  "method": "aid",
+  "aid": "my-device-01",
+  "signature": "base64-ed25519-signature",
+  "signed_at": 1710000000000
+}
+```
+
+签名内容：`"{nonce}:{signed_at}:{aid}"`
+
+Relay 验证：
+- 查找 AID 对应的公钥
+- 验签
+- `signed_at` 与服务端时间偏差 ≤ 10 分钟
+- nonce 匹配且未使用
+
+### 方式 5：邮箱验证码（远程客户端 → Relay）
+
+机制同短信验证码，发送渠道为邮箱。
+
+```json
+{
+  "method": "email",
+  "email": "user@example.com",
+  "code": "592831"
+}
+```
+
+Relay 验证验证码 + 邮箱在授权列表中。
+
+### 方式 6：OAuth 2.0（GitHub / Google / 企业 SSO）
+
+标准 Authorization Code Flow，适配到 WS 握手中。
+
+#### 流程
+
+```mermaid
+sequenceDiagram
+    actor U as User
+    participant F as Frontend
+    participant R as Relay
+    participant O as OAuth Provider<br/>(GitHub/Google)
+
+    U->>F: 点击 "GitHub 登录"
+    F->>R: HTTP GET /auth/oauth/github/authorize
+    R->>F: 302 redirect → GitHub OAuth 授权页
+    F->>O: 用户授权
+    O->>F: redirect callback?code=xxx&state=yyy
+    F->>R: HTTP GET /auth/oauth/callback?code=xxx&state=yyy
+    R-->>R: 验证 state（防 CSRF）
+    R->>O: POST /access_token {code, client_secret}
+    O->>R: {access_token}
+    R->>O: GET /user {access_token}
+    O->>R: {email, name, id}
+    R-->>R: 校验 email/id 是否在授权列表
+    R-->>R: 生成一次性 auth_ticket（60s 有效）
+    R->>F: {auth_ticket: "tic_xxx"}
+
+    Note over F,R: 切换到 WebSocket 握手
+    F->>R: WS connect
+    R->>F: challenge {nonce}
+    F->>R: connect {auth:{method:"oauth", ticket:"tic_xxx"}}
+    R-->>R: 验证 ticket（一次性）
+    R->>F: hello-ok {token_rotation:{new_token:"tok_xxx"}}
+```
+
+#### connect 请求
+
+```json
+{
+  "method": "oauth",
+  "provider": "github",
+  "ticket": "tic_xxx"
+}
+```
+
+`provider` 取值：`"github"` / `"google"` / `"microsoft"` / `"custom"`
+
+#### 关键设计
+
+- OAuth 的 HTTP 回调阶段生成**一次性 auth_ticket**（60 秒有效）
+- 前端拿到 ticket 后走标准 WS 四步握手
+- 这样 OAuth 的 HTTP 流程和 WS 握手协议完全解耦
+- 必须验证 `state` 参数防止 CSRF 攻击
+
+### 方式 7：LDAP / Active Directory（企业内部）
+
+LDAP 是同步验证，直接在 connect 请求中传用户名密码。
+
+```json
+{
+  "method": "ldap",
+  "username": "zhangsan",
+  "password": "xxx",
+  "domain": "corp.example.com"
+}
+```
+
+Relay 收到后：
+1. 连接 LDAP 服务器（`ldap://corp.example.com`）
+2. `bind(username, password)` 验证
+3. 查询用户组/角色信息
+4. 校验是否有 Kite 访问权限
+5. 验证通过 → 颁发 kiteToken
+
+LDAP 不需要 HTTP 回调，直接在 WS 握手中完成。
+
+### 方式 8：SAML 2.0（企业 SSO）
+
+同 OAuth 流程——HTTP 阶段完成 SAML 断言交换，生成 auth_ticket，WS 阶段用 ticket 完成握手。
+
+```json
+{
+  "method": "saml",
+  "ticket": "tic_xxx"
+}
+```
+
+### 方式 9：MFA/2FA（多因素认证）
+
+在其他认证方式的基础上增加第二步验证。客户端在 connect 请求中增加可选 `mfa_code` 字段。
+
+```json
+{
+  "method": "oauth",
+  "ticket": "tic_xxx",
+  "mfa_code": "123456"
+}
+```
+
+Relay 验证 TOTP（Time-based One-Time Password）或短信验证码。高权限账户（role=admin）可强制要求 MFA。
+
+### 认证方式汇总
+
+| method | 验证方式 | 实现阶段 | 适用场景 |
+|--------|----------|----------|----------|
+| `token` | Kite Token | ✅ 现有 | 本地模块 / 已登录重连 |
+| `pairing_code` | 配对码 | ✅ 现有 | 首次登录（无外部依赖） |
+| `sms` | 手机验证码 | ✅ 现有 | 手机号绑定用户 |
+| `email` | 邮箱验证码 | 新增（简单） | 邮箱绑定用户 |
+| `aid` | Ed25519 签名 | 后续 | 设备密钥认证 |
+| `oauth` | OAuth 2.0 | 新增（中等） | GitHub/Google/企业 SSO |
+| `ldap` | LDAP/AD | 新增（中等） | 企业内部用户目录 |
+| `saml` | SAML 2.0 | 新增（较大） | 企业 SSO（复杂场景） |
+| `mfa` | MFA/2FA | 新增（中等） | 高权限账户二次验证 |
+
+## hello-ok 响应
+
+认证通过后返回：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "connect-1",
+  "result": {
+    "type": "hello-ok",
+    "protocol": 1,
+    "kernel": {
+      "version": "0.5.0",
+      "instance_id": "kite-abc123"
+    },
+    "identity": {
+      "module_id": "web",
+      "role": "module",
+      "device": "server-01",
+      "channel": "default"
+    },
+    "policy": {
+      "max_payload_bytes": 1048576,
+      "event_queue_size": 10000,
+      "ping_interval_ms": 5000
+    },
+    "features": {
+      "events": ["module.*", "system.*"],
+      "rpc_namespaces": ["kernel", "launcher", "watchdog"]
+    },
+    "snapshot": {
+      "modules": {
+        "launcher": {"status": "online", "version": "0.5.0"},
+        "web": {"status": "online", "version": "0.5.0"},
+        "watchdog": {"status": "online", "version": "0.3.1"},
+        "backup": {"status": "offline"}
+      },
+      "subscriptions": ["module.*", "system.*"],
+      "pending_events": 0
+    },
+    "token_rotation": {
+      "new_token": "new-token-xxx",
+      "grace_period_ms": 300000
+    }
+  }
+}
+```
+
+### 字段说明
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `type` | ✅ | 固定 `"hello-ok"` |
+| `protocol` | ✅ | 协商后实际使用的协议版本 |
+| `kernel` | ✅ | Kernel 信息（Relay 透传） |
+| `kernel.version` | ✅ | Kernel 版本号 |
+| `kernel.instance_id` | ✅ | 本次 Kernel 运行实例 ID |
+| `identity` | ✅ | 服务端分配/确认的身份信息 |
+| `identity.module_id` | ✅ | 分配的模块 ID |
+| `identity.role` | ✅ | 角色（`"module"` / `"frontend"` / `"node"`） |
+| `identity.device` | ❌ | 确认的设备标识 |
+| `identity.channel` | ❌ | 确认的通道标识 |
+| `policy` | ✅ | 连接策略限制，客户端应遵守 |
+| `policy.max_payload_bytes` | ✅ | 单条消息最大字节数 |
+| `policy.event_queue_size` | ✅ | 事件队列容量 |
+| `policy.ping_interval_ms` | ✅ | 心跳间隔 |
+| `features` | ✅ | 当前可用的事件和 RPC 能力 |
+| `features.events` | ✅ | 可订阅的事件模式列表 |
+| `features.rpc_namespaces` | ✅ | 可调用的 RPC 命名空间列表 |
+| `snapshot` | ✅ | 系统状态快照 |
+| `snapshot.modules` | ✅ | 所有模块的当前在线状态和版本 |
+| `snapshot.subscriptions` | ✅ | 该连接当前的事件订阅列表（重连时恢复） |
+| `snapshot.pending_events` | ✅ | 该模块在断线期间积压的事件数 |
+| `token_rotation` | ❌ | 可选，存在时客户端必须保存新 token |
+| `token_rotation.new_token` | ✅* | 新 token |
+| `token_rotation.grace_period_ms` | ✅* | 旧 token 继续有效的时间窗口 |
+
+snapshot 是初版字段，后续缺什么往里加，客户端不认识的字段忽略即可。
+
+## 同 ID 并发连接
+
+当同一 `client.id` 第二次连接时，按 `(device, channel)` 二元组判定：
+
+| 情况 | 行为 |
+|------|------|
+| device 不同 | ✅ 共存，视为不同设备的合法并发 |
+| device 相同，channel 不同 | ✅ 共存，视为同设备不同通道 |
+| device 和 channel 都相同 | 踢掉**旧连接**，新连接正常进入 |
+
+被踢时旧连接收到：
+
+```json
+{
+  "type": "kicked",
+  "reason": "replaced",
+  "new_device": "server-01",
+  "new_channel": "default"
+}
+```
+
+然后关闭（code=4009）。客户端收到 code=4009 时**不应自动重连**。
+
+## Token 轮换
+
+- Kernel/Relay 在 hello-ok 中可选携带 `token_rotation`
+- 轮换时机由服务端决定（如 token 使用超过 N 天、或每次重连时轮换）
+- 客户端收到 `new_token` 后：
+  1. 立即保存 `new_token`
+  2. 下次连接使用 `new_token`
+  3. 旧 token 在 `grace_period_ms`（默认 5 分钟）内仍有效
+- 服务端维护双 token 窗口：`{module_id: [current_token, old_token, old_expiry]}`
+
+## 连接速率限制
+
+速率限制仅在 **Relay** 层实施（远程连接唯一入口），Kernel 不做限制（本地模块由 Launcher 管理生命周期，无限制）。
+
+### IP 维度
+
+同一 IP 10 秒内最多 200 次连接。超限后拒绝连接（code=4029，reason=`"rate limited"`），10 秒窗口滑动。
+
+### 节点维度（认证失败退避）
+
+按 `(aid, device_id)` 二元组追踪认证失败次数：
+
+| 连续失败次数 | 限制时长 | 说明 |
+|-------------|---------|------|
+| 1-5 | 无限制 | 每次尝试间隔至少 100ms |
+| 6 | 1 秒 | 开始限制 |
+| 7 | 2 秒 | 指数退避 ×2 |
+| 8 | 4 秒 | |
+| 9 | 8 秒 | |
+| ... | ... | 持续翻倍 |
+| N | min(2^(N-6), 300) 秒 | 最长 5 分钟 |
+
+- 每次尝试之间间隔不足 100ms 的请求直接拒绝（不计入失败次数）
+- 认证成功后重置计数器
+- 限制期间的连接直接拒绝（code=4029，reason=`"rate limited"`，响应中携带 `retry_after_ms`）
+
+拒绝响应示例：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "connect-1",
+  "error": {
+    "code": 4029,
+    "message": "rate limited",
+    "data": {
+      "retry_after_ms": 4000
+    }
+  }
+}
+```
+
+## 错误码
+
+统一错误码体系，Kernel 和 Relay 共用：
+
+| 关闭码 | 含义 | 客户端行为 |
+|--------|------|-----------|
+| 4001 | 认证失败（token/配对码/签名无效） | 清除凭据，不重连 |
+| 4002 | 协议版本不兼容 | 不重连，提示升级 |
+| 4003 | 握手超时（challenge 后未及时 connect） | 可重连 |
+| 4009 | 被同 ID 新连接踢掉 | **不重连** |
+| 4010 | nonce 无效（已使用或不匹配） | 可重连（获取新 nonce） |
+| 4029 | 速率限制 | 等待 `retry_after_ms` 后重连 |
+
+## 安全增强特性
+
+### JWT 签名 Token
+
+将当前的随机 token 改为 JWT 格式，提供自包含和防篡改能力。
+
+#### Token 格式
+
+```
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkZXZpY2UtMDEiLCJleHAiOjE3MTI1OTIwMDAsImlhdCI6MTcxMDAwMDAwMCwiZGV2aWNlX2lkIjoiZGV2LTAxIn0.signature
+```
+
+#### Payload 结构
+
+```json
+{
+  "sub": "device-01",
+  "exp": 1712592000,
+  "iat": 1710000000,
+  "device_id": "dev-01",
+  "auth_method": "oauth",
+  "trust_level": "medium"
+}
+```
+
+#### 优缺点
+
+| 优点 | 缺点 |
+|------|------|
+| 自包含（无需查数据库） | 无法主动撤销（需要黑名单） |
+| 防篡改（签名验证） | 体积大（~200 字节 vs 当前 ~40 字节） |
+| 标准化（业界通用） | 泄露后无法更改 payload |
+
+#### 实现方案
+
+使用 `PyJWT` 库，密钥从环境变量 `KITE_JWT_SECRET` 读取。
+
+### 异常检测
+
+监控 token 使用模式，检测异常行为并告警。
+
+#### 检测规则
+
+| 规则 | 阈值 | 动作 |
+|------|------|------|
+| IP 突变 | 同一 token 在 1 小时内从不同国家/地区访问 | 告警 + 要求重新认证 |
+| 异常时段 | 凌晨 2-5 点访问（用户通常不活跃） | 记录日志 |
+| 高频使用 | 1 分钟内超过 100 次请求 | 限流 + 告警 |
+| 设备指纹变化 | 同一 token 的设备指纹突变 | 告警 + 要求重新认证 |
+
+#### 实现方案
+
+后台任务每 5 分钟分析 token 使用记录（存储在 `token_usage.jsonl`），匹配规则引擎，触发告警事件。
+
+### 地理位置限制
+
+Token 记录中增加 `allowed_countries` 字段，限制访问来源。
+
+```json
+{
+  "token": "tok_xxx",
+  "allowed_countries": ["CN", "US"],
+  "allowed_regions": ["Asia/Shanghai", "America/New_York"]
+}
+```
+
+验证时检查 IP 地理位置（使用 MaxMind GeoIP2 数据库），不在白名单内则拒绝。
+
+### 时钟偏移容忍
+
+客户端在收到 challenge 时获取服务端时间戳，自动校准本地时钟。
+
+```json
+{
+  "type": "challenge",
+  "nonce": "xxx",
+  "ts": 1710000000000,
+  "client_offset": 0
+}
+```
+
+客户端计算偏移：`client_offset = server_ts - local_ts`，在后续签名时使用校准后的时间。
+
+AID 签名时间窗口：±10 分钟（正常）→ ±1 小时（极端偏移）。
+
+## 改造清单
+
+### Kernel 侧
+
+| 改造项 | 涉及文件 | 说明 |
+|--------|----------|------|
+| challenge 推送 + nonce 池 | `kernel/server.py` | accept 后主动发 challenge，使用 TTL 字典维护 nonce（`expiringdict`，10000 容量，600s 过期） |
+| `connect` 方法替代 `auth` | `kernel/server.py` | 新 connect 处理逻辑，含 nonce 校验 |
+| 版本范围协商 | `kernel/server.py` | protocol.min/max 校验 + 版本选择 |
+| hello-ok 响应 | `kernel/server.py` | 构建完整 hello-ok（含 snapshot） |
+| 时序安全比较 | `kernel/registry_store.py` | `==` → `hmac.compare_digest()` |
+| 同 ID 并发连接判定 | `kernel/server.py` + `kernel/event_hub.py` | (device, channel) 二元组判定 + 踢旧连接 |
+| token 轮换双窗口 | `kernel/registry_store.py` | 维护 current + old token |
+| URL query 移除 token | `kernel/server.py` | token 只通过 WS 消息体传输 |
+| 速率限制 | `kernel/server.py` | 按 module_id 限制（10s 内最多 20 次认证尝试） |
+| 审计日志 | `kernel/server.py` | 复用 Audit 模块，记录 `auth.*` 事件 |
+
+### Kite Console 模块（Relay 实现）
+
+**注意**：握手认证方案在 `extensions/services/kite_console/` 模块中实现，不是 Web 或 Evol 模块。
+
+| 改造项 | 涉及文件 | 说明 |
+|--------|----------|------|
+| challenge + connect 流程 | `kite_console/relay.py` | 实现统一四步握手 |
+| 版本协商 + hello-ok | `kite_console/relay.py` | 对远程客户端做版本校验，透传 Kernel 信息 |
+| token 轮换 | `kite_console/relay.py` | 滑动 30 天 + 绝对半年上限 |
+| IP 速率限制 | `kite_console/relay.py` | 10s/200 次滑动窗口 |
+| 节点认证失败退避 | `kite_console/relay.py` | (aid, device_id) 维度指数退避 |
+| OAuth 2.0 认证 | `kite_console/oauth.py` | HTTP 授权流程 + state 验证（内存/JWT 双模式） |
+| LDAP 认证 | `kite_console/ldap.py` | 连接 LDAP 服务器验证用户名密码 |
+| SAML 认证 | `kite_console/saml.py` | SAML 断言交换 |
+| MFA/2FA | `kite_console/mfa.py` | TOTP 验证，admin 强制 |
+| 设备指纹 | `kite_console/fingerprint.py` | 前端 + 后端混合指纹 |
+| JWT Token | `kite_console/auth_manager.py` | 使用 PyJWT 生成和验证 token |
+| 异常检测 | `kite_console/anomaly.py` | 规则引擎，后台任务每 5 分钟分析 |
+| 地理位置限制 | `kite_console/geo.py` | MaxMind GeoIP2 验证 IP 地理位置 |
+| 时序安全比较 | `kite_console/auth_manager.py` | `hmac.compare_digest()` |
+| Token 过期机制 | `kite_console/auth_manager.py` | 滑动 30 天 + 绝对半年 |
+| JSONL 归档 | `kite_console/auth_manager.py` | 每月归档旧记录到 `archive/YYYY-MM.jsonl.gz` |
+| Token 撤销实时性 | `kite_console/auth_manager.py` | 撤销时清除内存缓存 `_cache.pop(token)` |
+| 审计日志 | `kite_console/relay.py` | 复用 Audit 模块，记录所有认证事件 |
+| Relay 重定向 | `kite_console/relay.py` | challenge 中可选 redirect 字段 |
+
+### 模块客户端侧
+
+| 改造项 | 涉及文件 | 说明 |
+|--------|----------|------|
+| 接收 challenge + 发 connect | 各模块 entry.py / server.py | 统一模式，改一个抄其他 |
+| 处理 hello-ok | 同上 | 解析 policy + features（可选） |
+| 处理 token 轮换 | 同上 | 收到 new_token 时保存 |
+| 处理 code=4009 不重连 | 同上 | 被踢时终止重连 |
+
+### 前端 JS 侧
+
+| 改造项 | 涉及文件 | 说明 |
+|--------|----------|------|
+| challenge → connect 流程 | `kernel-client.js` | 替代现有 pair/auth 消息 |
+| hello-ok 解析 | `kernel-client.js` | 统一处理认证成功响应 |
+| token 轮换 | `kernel-client.js` | 更新 localStorage 中的 token |
+| code=4009 不重连 | `kernel-client.js` | 被踢时显示提示而非自动重连 |
+| OAuth 登录流程 | `evol-app.js` + 新增 OAuth 页面 | HTTP 授权 → 获取 ticket → WS 握手 |
+
+## Token 管理统一
+
+### 现状
+
+当前 Evol 控制台已有 token 管理面板（`list_tokens`/`revoke_token` RPC），但只管理 kiteToken。
+
+### 统一方案
+
+三种远程登录方式（配对码、短信、AID）认证成功后，都通过 AuthManager 颁发 kiteToken，记录中增加 `auth_method` 字段标识来源：
+
+```json
+{
+  "token": "tok_xxx",
+  "auth_method": "pairing_code",
+  "deviceId": "...",
+  "deviceName": "...",
+  "device_fingerprint": "fp_xxx",
+  "phone": "13800138000",
+  "email": "user@example.com",
+  "oauth_provider": "github",
+  "trust_level": "medium",
+  "createdAt": 1710000000,
+  "lastUsedAt": 1710500000,
+  "expiresAt": 1712592000,
+  "isValid": true
+}
+```
+
+`auth_method` 取值：`"pairing_code"` / `"sms"` / `"email"` / `"aid"` / `"oauth"` / `"ldap"` / `"saml"` / `"mfa"`
+
+### Token 过期机制（滑动 + 绝对上限）
+
+- **滑动窗口**：每次使用延期 30 天
+- **绝对上限**：创建后最多 180 天（半年）强制过期
+- **验证逻辑**：
+  ```python
+  now = time.time()
+  if now > created_at + 180 * 86400:  # 超过半年
+      return False
+  if now > last_used_at + 30 * 86400:  # 超过 30 天未使用
+      return False
+  # 验证通过，更新 last_used_at
+  ```
+
+### 设备信任等级
+
+根据认证方式自动分级：
+
+| 认证方式 | trust_level | 说明 |
+|---------|-------------|------|
+| AID 密码学 | `high` | 设备密钥认证，最安全 |
+| OAuth/LDAP/SAML | `medium` | 企业认证，较安全 |
+| 配对码/短信/邮箱 | `low` | 验证码认证，基础安全 |
+
+### 设备指纹
+
+客户端在 connect 请求中携带 `device_fingerprint`：
+
+- **浏览器**：Canvas/WebGL/字体指纹（使用 FingerprintJS）
+- **原生应用**：硬件 UUID + 系统信息
+- **后端计算**：IP + User-Agent + TLS 指纹
+
+混合指纹（前端 + 后端）提供最强识别能力。
+
+### 管理面板增强
+
+- 按 `auth_method` 分组展示
+- 支持按来源筛选（如只看 OAuth 登录的 token）
+- 批量撤销（如撤销所有配对码登录的 token）
+- 显示登录方式相关信息（OAuth 显示 provider，短信显示手机号）
+- 显示设备指纹和信任等级
+
+### PairingManager 角色调整
+
+PairingManager 退化为只负责配对码生成和验证，不再自己管 token。Token 统一由 AuthManager 管理。
+
+## Relay 负载均衡与重定向
+
+### challenge 中的 redirect 字段
+
+```json
+{
+  "type": "challenge",
+  "nonce": "a1b2c3d4-uuid",
+  "ts": 1710000000000,
+  "timeout_ms": 10000,
+  "redirect": {
+    "url": "wss://relay-02.example.com/ws",
+    "reason": "load_balance"
+  }
+}
+```
+
+### 客户端行为
+
+收到 `redirect` 时：
+1. 关闭当前连接
+2. 连接 `redirect.url`
+3. 在新连接上重新走完整四步握手（新 Relay 会发新的 challenge）
+
+不带 `redirect` 字段 → 在当前连接继续握手（默认行为）。
+
+### 重定向决策
+
+Relay 的重定向决策可以基于：
+- 当前连接数（超过阈值重定向）
+- CPU/内存负载（繁忙时重定向）
+- 外部负载均衡器的指令
+- 维护模式（停机前把新连接全部重定向走）
+
+### 防重定向循环
+
+客户端维护重定向计数器，同一次连接尝试最多重定向 3 次，超过则报错。
+
+### 时序图
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant R1 as Relay-01 (入口)
+    participant R2 as Relay-02 (目标)
+
+    C->>R1: WS connect
+    R1-->>R1: 负载判断：自身繁忙
+    R1->>C: challenge {redirect:{url:"wss://relay-02/ws"}}
+    C--xR1: 关闭连接
+    C-->>C: 重定向计数 +1
+
+    C->>R2: WS connect
+    R2->>C: challenge {nonce, ts}
+    C->>R2: connect {nonce, auth:{...}}
+    R2->>C: hello-ok
+```