@agentunion/kite 1.4.0 → 1.6.0

package/docs//350/256/244/350/257/201/346/250/241/345/235/227/344/270/216Gateway/350/256/276/350/256/241/346/226/271/346/241/210.md

@@ -0,0 +1,765 @@
+# 认证模块与 Gateway 设计方案
+
+## 1. 问题与目标
+
+现有认证逻辑全部耦合在 `kite_console/relay.py` 中（配对码、Token、OAuth、MFA）。需要：
+
+- 将认证逻辑抽离为独立的 **Auth 模块**（标准 Kite 模块）
+- 新增独立的 **Gateway 模块**（标准 Kite 模块，独立端口）
+- kite_console 的 Relay 组件保持为控制台内部组件，与 Gateway 在认证流程上行为一致
+- 全程使用 **JSON-RPC 2.0** 格式，包括握手阶段
+
+## 2. 系统拓扑
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                          Kite 实例                               │
+│                                                                  │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
+│  │ Launcher │  │ Watchdog │  │   Web    │  │  Backup  │  ...   │
+│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘        │
+│       └──────────────┼─────────────┼─────────────┘              │
+│                      │  stdin token│                             │
+│               ┌──────▼─────────────▼──────┐                     │
+│               │         Kernel            │                     │
+│               │  Registry·EventHub·RPC    │                     │
+│               └──┬──────────┬──────────┬──┘                     │
+│                  │          │          │                         │
+│          ┌───────▼──┐  ┌───▼────┐  ┌──▼─────────────┐          │
+│          │   Auth   │  │Gateway │  │  Kite Console  │          │
+│          │ (认证服务)│  │ (网关) │  │ (控制台+Relay) │          │
+│          │ 纯RPC服务 │  │WS+HTTP │  │  HTTP+WS      │          │
+│          └──────────┘  └───┬────┘  └──────┬─────────┘          │
+│                            │              │                     │
+└────────────────────────────┼──────────────┼─────────────────────┘
+                             │              │
+                   ┌─────────▼──┐  ┌────────▼────────┐
+                   │  远程模块   │  │  浏览器/远程客户端│
+                   │ (卫星Kite)  │  │  (控制台前端)    │
+                   └────────────┘  └─────────────────┘
+```
+
+### 2.1 三个角色
+
+| 角色 | 性质 | 职责 | 对外端口 |
+|------|------|------|----------|
+| **Auth** | 标准 Kite 模块 | 认证逻辑 + Token 持久化 + 审计 | 无（纯 RPC） |
+| **Gateway** | 标准 Kite 模块 | 远程接入网关（WS + OAuth HTTP 回调） | 独立端口 |
+| **Relay** | kite_console 内部组件 | 控制台复用端口的接入层 | 复用控制台端口 |
+
+### 2.2 状态分层
+
+| 状态类型 | 归属 | 生命周期 | 重启后 |
+|----------|------|----------|--------|
+| nonce 池 | Gateway/Relay | 连接级，秒级 | 连接断了 nonce 自然失效 |
+| session 映射 | Gateway/Relay | 连接级 | 连接断了 session 无意义 |
+| 权限配置 | Gateway/Relay | 启动时加载 | 从配置重新加载 |
+| 速率限制（IP/设备） | Gateway/Relay | 进程级 | 重置，可接受 |
+| Token 记录 | Auth | 持久化（JSONL） | 不丢失 |
+| 设备/账号注册 | Auth | 持久化 | 不丢失 |
+| 审计日志 | Auth | 持久化 | 不丢失 |
+| 速率限制（账号级） | Auth | 进程级 | 重置，可接受 |
+
+Gateway/Relay 的状态全是**连接绑定的临时状态**。Gateway 重启 → 所有连接断开 → 所有状态自然失效 → 客户端重连重新认证。
+
+## 3. 协议格式
+
+**全程 JSON-RPC 2.0**，包括握手阶段。不引入非标消息格式。
+
+### 3.1 challenge（JSON-RPC notification）
+
+Gateway/Relay 在 accept 连接后主动推送：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "challenge",
+  "params": {
+    "nonce": "a1b2c3d4-uuid",
+    "ts": 1710000000000,
+    "timeout_ms": 10000,
+    "auth_methods": ["pairing_code", "sms", "email", "oauth", "kite_token"],
+    "protocol": { "version": 1 }
+  }
+}
+```
+
+- notification（无 `id` 字段），不需要客户端回复
+- `timeout_ms`：整个 pre-auth 阶段的超时，超时后关闭连接
+- `auth_methods`：Gateway 启动时从 Auth 模块查询并缓存
+
+### 3.2 pre-auth RPC（JSON-RPC request/response）
+
+challenge 之后、auth.connect 之前，客户端可调用有限的 pre-auth 方法：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-1",
+  "method": "auth.request_pairing_code",
+  "params": {}
+}
+```
+
+Gateway **透明转发**这些请求到 Auth 模块（通过 Kernel RPC 路由），返回结果后**关闭连接**，避免未认证客户端长时间占用网关资源。
+
+### 3.3 auth.connect（JSON-RPC request）
+
+客户端发起认证：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "connect-1",
+  "method": "auth.connect",
+  "params": {
+    "nonce": "a1b2c3d4-uuid",
+    "protocol": { "min": 1, "max": 1 },
+    "client": {
+      "id": "my-app",
+      "type": "frontend",
+      "version": "1.0.0",
+      "device": "browser-01",
+      "channel": "default"
+    },
+    "auth": {
+      "method": "pairing_code",
+      "code": "482916"
+    }
+  }
+}
+```
+
+**`auth.connect` 不是透明转发**——Gateway 拦截处理：
+1. 验证 nonce（本地消费）
+2. 提取 auth 信息，调用 `auth.verify()` RPC（通过 Kernel 转发到 Auth 模块）
+3. 成功后为客户端创建到 Kernel 的代理连接
+4. 返回 hello-ok
+
+### 3.4 hello-ok（JSON-RPC response）
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "connect-1",
+  "result": {
+    "protocol": 1,
+    "kernel": { "version": "0.5.0", "instance_id": "kite-abc123" },
+    "identity": { "module_id": "frontend-xxx", "role": "admin" },
+    "token": "tok_xxx",
+    "policy": { "max_payload_bytes": 1048576, "ping_interval_ms": 5000 },
+    "features": { "events": ["module.*"], "rpc_namespaces": ["kernel", "auth"] }
+  }
+}
+```
+
+### 3.5 pre-auth 方法分类
+
+| 方法 | Gateway 行为 | 连接处理 |
+|------|-------------|----------|
+| `auth.request_pairing_code` | 透明转发到 Auth | 返回后**关闭连接** |
+| `auth.send_sms_code` | 透明转发到 Auth | 返回后**关闭连接** |
+| `auth.send_email_code` | 透明转发到 Auth | 返回后**关闭连接** |
+| `auth.get_oauth_url` | 透明转发到 Auth | 返回后**关闭连接** |
+| `auth.connect` | Gateway 拦截处理 | 成功→保持连接进入 relay；失败→关闭 |
+| 其他任何方法 | **拒绝**（4001 Unauthorized） | — |
+
+## 4. 完整认证时序图
+
+### 4.1 配对码登录
+
+```mermaid
+sequenceDiagram
+    actor U as 用户
+    participant C as 远程客户端
+    participant GW as Gateway/Relay
+    participant K as Kernel
+    participant A as Auth 模块
+
+    Note over C,A: ── 阶段1：获取配对码（短连接）──
+
+    C->>GW: WS connect
+    GW->>GW: accept，生成 nonce
+    GW->>C: notification: challenge {nonce, ts, auth_methods}
+    C->>GW: request: auth.request_pairing_code()
+    GW->>K: RPC: auth.request_pairing_code()
+    K->>A: 转发
+    A->>A: 生成配对码 482916（5分钟过期）
+    A->>K: event.publish(auth.code_generated, {code})
+    A->>K: {code:"482916", expires_at:xxx}
+    K->>GW: 转发响应
+    GW->>C: response: {code:"482916", expires_at:xxx}
+    GW--xC: 关闭连接（pre-auth 短连接）
+
+    Note over U: 用户通过控制台/其他渠道看到配对码
+
+    Note over C,A: ── 阶段2：提交配对码认证（新连接）──
+
+    C->>GW: WS connect（新连接）
+    GW->>GW: accept，生成新 nonce
+    GW->>C: notification: challenge {nonce, ts, auth_methods}
+    C->>GW: request: auth.connect {nonce, client:{...}, auth:{method:"pairing_code", code:"482916"}}
+    GW->>GW: 验证 nonce ✓（消费后删除）
+    GW->>K: RPC: auth.verify({method:"pairing_code", code:"482916", client_info:{...}})
+    K->>A: 转发
+    A->>A: 验证配对码 ✓（消费后删除）
+    A->>K: RPC: kernel.generate_token({module_id:"frontend-xxx"})
+    K->>K: 生成 token，注册到 token_map
+    K->>A: {token:"tok_xxx"}
+    A->>A: 存储 token 元数据（auth_method, device, trust_level）
+    A->>K: event.publish(auth.success)
+    A->>K: {success:true, token:"tok_xxx", role:"admin", trust_level:"low"}
+    K->>GW: 转发响应
+
+    Note over GW,K: ── 阶段3：建立代理连接 ──
+
+    GW->>K: WS connect /ws?id=frontend-xxx
+    GW->>K: auth {token:"tok_xxx"}
+    K->>GW: auth ok
+    GW->>K: registry.register({module_id:"frontend-xxx"})
+    GW->>K: event.publish(module.ready)
+    GW->>C: response: hello-ok {protocol, kernel, identity, token:"tok_xxx"}
+
+    Note over C,K: ═══ 认证完成，进入 JSON-RPC 透传模式 ═══
+```
+
+### 4.2 短信验证码登录
+
+```mermaid
+sequenceDiagram
+    actor U as 用户
+    participant C as 远程客户端
+    participant GW as Gateway/Relay
+    participant K as Kernel
+    participant A as Auth 模块
+    participant SMS as 短信服务商
+
+    Note over C,A: ── 阶段1：请求发送验证码（短连接）──
+
+    C->>GW: WS connect
+    GW->>C: notification: challenge {nonce, ts, auth_methods}
+    C->>GW: request: auth.send_sms_code({phone:"138xxxx1234"})
+    GW->>K: RPC: auth.send_sms_code({phone:"138xxxx1234"})
+    K->>A: 转发
+    A->>A: 校验手机号在授权列表 ✓
+    A->>A: 账号级速率限制检查 ✓
+    A->>A: 生成验证码 592831（5分钟过期）
+    A->>SMS: 发送短信
+    A->>K: {sent:true, expires_at:xxx}
+    K->>GW: 转发响应
+    GW->>C: response: {sent:true, expires_at:xxx}
+    GW--xC: 关闭连接
+
+    Note over U: 用户收到短信
+
+    Note over C,A: ── 阶段2：提交验证码认证（新连接）──
+
+    C->>GW: WS connect
+    GW->>C: notification: challenge {nonce, ts, auth_methods}
+    C->>GW: request: auth.connect {nonce, auth:{method:"sms", phone:"138xxxx1234", code:"592831"}}
+    GW->>GW: 验证 nonce ✓
+    GW->>K: RPC: auth.verify({method:"sms", phone:"138xxxx1234", code:"592831", client_info:{...}})
+    K->>A: 转发
+    A->>A: 验证验证码 ✓ + 手机号授权 ✓
+    A->>K: kernel.generate_token(...)
+    K->>A: {token:"tok_xxx"}
+    A->>K: {success:true, token:"tok_xxx", role:"admin", trust_level:"low"}
+    K->>GW: 转发响应
+    GW->>K: 建立代理连接（同 4.1 阶段3）
+    GW->>C: response: hello-ok {token:"tok_xxx", ...}
+```
+
+### 4.3 OAuth 登录
+
+```mermaid
+sequenceDiagram
+    actor U as 用户
+    participant C as 远程客户端(浏览器)
+    participant GW as Gateway/Relay
+    participant K as Kernel
+    participant A as Auth 模块
+    participant O as OAuth Provider
+
+    Note over C,O: ── 阶段1：获取授权 URL（短连接）──
+
+    C->>GW: WS connect
+    GW->>C: notification: challenge {nonce, ts, auth_methods}
+    C->>GW: request: auth.get_oauth_url({provider:"github"})
+    GW->>K: RPC: auth.get_oauth_url({provider:"github", redirect_uri:"https://gw:28800/auth/oauth/callback"})
+    K->>A: 转发
+    A->>A: 生成 state（防 CSRF），存储
+    A->>K: {auth_url:"https://github.com/login/oauth/authorize?...", state:"xxx"}
+    K->>GW: 转发响应
+    GW->>C: response: {auth_url:"...", state:"xxx"}
+    GW--xC: 关闭连接
+
+    Note over C,O: ── 阶段2：用户在 OAuth Provider 授权 ──
+
+    C->>O: 跳转到授权页
+    U->>O: 授权
+    O->>GW: HTTP redirect: GET /auth/oauth/callback?code=abc&state=xxx
+
+    Note over GW,A: ── 阶段3：Gateway HTTP 回调处理 ──
+
+    GW->>K: RPC: auth.oauth_callback({provider:"github", code:"abc", state:"xxx"})
+    K->>A: 转发
+    A->>A: 验证 state ✓
+    A->>O: POST /access_token {code, client_secret}
+    O->>A: {access_token}
+    A->>O: GET /user
+    O->>A: {email, name, id}
+    A->>A: 校验授权列表 ✓
+    A->>A: 生成 auth_ticket（60s 有效，一次性）
+    A->>K: {ticket:"tic_xxx"}
+    K->>GW: 转发响应
+    GW->>C: HTTP 200 {ticket:"tic_xxx"}
+
+    Note over C,A: ── 阶段4：用 ticket 完成 WS 认证（新连接）──
+
+    C->>GW: WS connect
+    GW->>C: notification: challenge {nonce, ts, auth_methods}
+    C->>GW: request: auth.connect {nonce, auth:{method:"oauth", ticket:"tic_xxx"}}
+    GW->>GW: 验证 nonce ✓
+    GW->>K: RPC: auth.verify({method:"oauth", ticket:"tic_xxx", client_info:{...}})
+    K->>A: 转发
+    A->>A: 验证 ticket ✓（一次性消费）
+    A->>K: kernel.generate_token(...)
+    K->>A: {token:"tok_xxx"}
+    A->>K: {success:true, token:"tok_xxx", role:"admin", trust_level:"medium"}
+    K->>GW: 转发响应
+    GW->>K: 建立代理连接（同 4.1 阶段3）
+    GW->>C: response: hello-ok {token:"tok_xxx", ...}
+```
+
+### 4.4 已有 Token 重连
+
+```mermaid
+sequenceDiagram
+    participant C as 远程客户端
+    participant GW as Gateway/Relay
+    participant K as Kernel
+    participant A as Auth 模块
+
+    C->>GW: WS connect
+    GW->>C: notification: challenge {nonce, ts, auth_methods}
+    C->>GW: request: auth.connect {nonce, auth:{method:"kite_token", token:"tok_xxx"}}
+    GW->>GW: 验证 nonce ✓
+    GW->>K: RPC: auth.verify({method:"kite_token", token:"tok_xxx", client_info:{...}})
+    K->>A: 转发
+    A->>A: 验证 token（滑动30天 + 绝对180天）✓
+    A->>A: 更新 last_used_at
+    A->>K: {success:true, role:"admin", trust_level:"low"}
+    K->>GW: 转发响应
+
+    Note over GW: token 已存在，无需 kernel.generate_token
+
+    GW->>K: 建立代理连接（用已有 token）
+    GW->>C: response: hello-ok {...}
+```
+
+### 4.5 Token 撤销实时生效
+
+```mermaid
+sequenceDiagram
+    participant Admin as 管理员
+    participant KC as Kite Console
+    participant K as Kernel
+    participant A as Auth 模块
+    participant GW as Gateway
+    participant C as 远程客户端
+
+    Admin->>KC: Token 管理面板 → 撤销
+    KC->>K: RPC: auth.revoke_token({token:"tok_xxx"})
+    K->>A: 转发
+    A->>A: 标记 token 无效
+    A->>K: event.publish(auth.token.revoked, {token:"tok_xxx"})
+    A->>K: {success:true}
+
+    K->>GW: 事件: auth.token.revoked {token:"tok_xxx"}
+    GW->>GW: 查找使用该 token 的 session
+    GW->>C: notification: kicked {reason:"token_revoked"}
+    GW--xC: close (code=4001)
+    GW->>K: 清理代理连接
+```
+
+## 5. 速率限制分层
+
+### 5.1 Gateway/Relay 层（连接级）
+
+| 维度 | 策略 | 说明 |
+|------|------|------|
+| IP | 10s 内最多 200 次连接 | 防 DDoS |
+| 设备 ID | 10s 内最多 20 次认证尝试 | 防暴力破解 |
+| pre-auth 超时 | challenge 后 10s 内必须完成 | 防连接占用 |
+
+### 5.2 Auth 模块层（账号级）
+
+| 维度 | 策略 | 说明 |
+|------|------|------|
+| 手机号 | 60s 内最多 1 次发送 | 防短信轰炸 |
+| 邮箱 | 60s 内最多 1 次发送 | 防邮件轰炸 |
+| 配对码尝试 | 连续 5 次失败后指数退避 | 防猜码 |
+| OAuth state | 60s 过期，一次性 | 防 CSRF 重放 |
+| auth_ticket | 60s 过期，一次性 | 防 ticket 重放 |
+
+Gateway 管连接级限流，Auth 管业务级限流，各司其职。
+
+## 6. Gateway 模块设计
+
+### 6.1 模块定义
+
+```yaml
+# extensions/services/gateway/module.md
+---
+name: gateway
+display_name: Gateway
+type: service
+state: enabled
+runtime: python
+entry: entry.py
+subscriptions:
+  - module.ready
+  - module.shutdown
+  - auth.token.revoked
+config:
+  ws_port: 28800
+  ws_host: "0.0.0.0"
+  tls:
+    enabled: false
+    cert: ""
+    key: ""
+  max_connections: 1000
+  challenge_timeout_ms: 10000
+  nonce_pool_size: 10000
+  nonce_ttl: 600
+---
+```
+
+### 6.2 Gateway 启动流程
+
+```mermaid
+sequenceDiagram
+    participant L as Launcher
+    participant GW as Gateway
+    participant K as Kernel
+    participant A as Auth 模块
+
+    L->>GW: stdin boot_info {token, kernel_host, kernel_port}
+    GW->>K: WS connect + token 认证
+    K->>GW: auth ok
+    GW->>K: registry.register({module_id:"gateway"})
+    GW->>K: event.subscribe({patterns:["auth.token.revoked"]})
+    GW->>K: RPC: auth.get_supported_methods()
+    K->>A: 转发
+    A->>K: {methods:["pairing_code","sms","email","oauth","kite_token"]}
+    K->>GW: 转发响应
+    GW->>GW: 缓存 auth_methods
+    GW->>GW: 启动 WS 服务器 :28800（+ OAuth HTTP 回调）
+    GW->>K: event.publish(module.ready)
+```
+
+### 6.3 Gateway 连接处理流程
+
+```mermaid
+flowchart TD
+    A[远程客户端 WS connect] --> B[accept]
+    B --> C[IP 速率限制检查]
+    C -->|超限| D[拒绝 4029]
+    C -->|通过| E[生成 nonce，发送 challenge]
+    E --> F{等待客户端消息}
+    F -->|超时| G[关闭 4003]
+    F -->|收到| H{method?}
+
+    H -->|auth.request_pairing_code<br/>auth.send_sms_code<br/>auth.send_email_code<br/>auth.get_oauth_url| I[透明转发到 Auth]
+    I --> J[返回结果]
+    J --> K[关闭连接]
+
+    H -->|auth.connect| L[验证 nonce]
+    L -->|无效| M[关闭 4010]
+    L -->|有效| N[调 auth.verify via Kernel]
+    N --> O{认证结果}
+    O -->|失败| P[返回错误，关闭 4001]
+    O -->|成功| Q[获取 token + role]
+    Q --> R[建立到 Kernel 的代理连接]
+    R --> S[返回 hello-ok]
+    S --> T[进入双向 JSON-RPC 透传]
+
+    H -->|其他方法| U[拒绝 4001 Unauthorized]
+```
+
+### 6.4 Gateway 与 Relay 的异同
+
+| 维度 | Relay（kite_console 组件） | Gateway（独立模块） |
+|------|--------------------------|-------------------|
+| 端口 | 复用控制台 HTTP 端口 | 独立 WS/WSS 端口 |
+| HTTP 能力 | 依赖 kite_console 的 FastAPI | 自带 OAuth 回调 HTTP 端口 |
+| 客户端类型 | 浏览器前端 | 远程模块、卫星 Kite、App |
+| 部署 | 随 kite_console 启动 | 独立模块，可选启用 |
+| 认证流程 | 与 Gateway 完全一致 | 与 Relay 完全一致 |
+| 代码关系 | 各自独立实现（零共享代码） | 各自独立实现 |
+
+## 7. Auth 模块设计
+
+### 7.1 模块定义
+
+```yaml
+# extensions/services/auth/module.md
+---
+name: auth
+display_name: Auth
+type: service
+state: enabled
+runtime: python
+entry: entry.py
+events:
+  - auth.success
+  - auth.failed
+  - auth.rate_limited
+  - auth.code_generated
+  - auth.token.created
+  - auth.token.revoked
+  - auth.token.expired
+  - auth.token.rotated
+  - auth.device.registered
+  - auth.anomaly.*
+subscriptions:
+  - module.ready
+  - module.shutdown
+---
+```
+
+### 7.2 RPC 方法
+
+#### 认证类
+
+| 方法 | 调用者 | 说明 |
+|------|--------|------|
+| `auth.verify` | Gateway/Relay | 统一认证入口，验证各种凭据 |
+| `auth.request_pairing_code` | Gateway/Relay（代客户端） | 生成配对码 |
+| `auth.send_sms_code` | Gateway/Relay（代客户端） | 发送短信验证码 |
+| `auth.send_email_code` | Gateway/Relay（代客户端） | 发送邮箱验证码 |
+| `auth.get_oauth_url` | Gateway/Relay（代客户端） | 生成 OAuth 授权 URL |
+| `auth.oauth_callback` | Gateway（HTTP 回调） | 处理 OAuth 回调，返回 ticket |
+| `auth.get_supported_methods` | Gateway/Relay（启动时） | 查询支持的认证方式 |
+| `auth.register_aid` | 已认证客户端 | 注册 AID 设备密钥 |
+| `auth.setup_mfa` | 已认证客户端 | 绑定 MFA |
+
+#### Token 管理类
+
+| 方法 | 调用者 | 说明 |
+|------|--------|------|
+| `auth.list_tokens` | 控制台前端 | 列出 token（支持按 auth_method 筛选） |
+| `auth.revoke_token` | 控制台前端 | 撤销单个 token |
+| `auth.revoke_tokens_by_method` | 控制台前端 | 按认证方式批量撤销 |
+| `auth.refresh_token` | Gateway/Relay | 刷新 token 有效期 |
+
+#### 审计类
+
+| 方法 | 调用者 | 说明 |
+|------|--------|------|
+| `auth.query_logs` | 控制台前端 | 查询认证日志 |
+| `auth.get_stats` | 控制台前端 | 认证统计 |
+
+### 7.3 `auth.verify` 统一入口
+
+```json
+// 请求
+{
+  "method": "pairing_code",
+  "code": "482916",
+  "client_info": {
+    "device": "browser-01",
+    "channel": "default",
+    "ip": "1.2.3.4",
+    "platform": "browser"
+  }
+}
+
+// 成功响应
+{
+  "success": true,
+  "token": "tok_xxx",
+  "role": "admin",
+  "trust_level": "low",
+  "module_id": "frontend-xxx"
+}
+
+// 失败响应
+{
+  "success": false,
+  "error": "invalid_code",
+  "retry_after_ms": 0
+}
+```
+
+Auth 模块内部根据 `method` 分发到对应的 verifier。
+
+### 7.4 Auth 模块文件结构
+
+```
+extensions/services/auth/
+├── module.md
+├── entry.py                 # 模块入口
+├── rpc_handler.py           # RPC 分发
+├── verifiers/               # 各认证方式
+│   ├── pairing_code.py
+│   ├── sms.py
+│   ├── email_code.py
+│   ├── oauth.py
+│   ├── kite_token.py
+│   ├── aid.py
+│   └── mfa.py
+├── token_store.py           # Token 持久化（JSONL）
+├── audit_logger.py          # 审计日志
+└── anomaly_detector.py      # 异常检测
+```
+
+## 8. 关键设计决策与挑剔评估
+
+### 8.1 challenge 由接入层发，不经过 Auth
+
+**决策**：Gateway/Relay 自己生成 nonce、发送 challenge、验证 nonce。Auth 模块不感知 nonce。
+
+**理由**：
+- nonce 是连接级防重放，与 TCP 连接绑定，天然属于接入层
+- Gateway/Relay 已经是认证过的 Kite 模块，有自己的 Kernel 连接，调 `auth.verify()` 就是普通跨模块 RPC
+- Kernel 不需要任何改动
+
+**风险评估**：无。nonce 丢失（Gateway 重启）= 连接断开 = 客户端重连拿新 nonce，零代价。
+
+### 8.2 pre-auth 短连接策略
+
+**决策**：请求配对码/验证码/OAuth URL 后立即关闭连接。只有 `auth.connect` 成功后才保持长连接。
+
+**理由**：未认证客户端不应长时间占用网关连接资源。恶意客户端可以大量建立连接但不认证，耗尽 Gateway 连接池。
+
+**风险评估**：客户端需要建立两次连接（请求码 + 认证），多一次 TCP 握手开销。可接受——安全性优先于便利性。
+
+### 8.3 auth.connect 由 Gateway 拦截，不透传
+
+**决策**：`auth.connect` 不像其他 `auth.*` 方法那样透传到 Auth 模块。Gateway 拦截它，本地验证 nonce，然后调 `auth.verify()`。
+
+**理由**：
+- nonce 在 Gateway 本地，必须由 Gateway 验证
+- 认证成功后 Gateway 需要创建代理连接，这是 Gateway 的职责
+- Auth 模块不需要知道 `auth.connect` 的存在，它只回答 `auth.verify()`
+
+**风险评估**：Gateway 和 Relay 都需要实现 `auth.connect` 的拦截逻辑。但这是接入层的核心职责，不可避免。
+
+### 8.4 Auth 模块单点故障
+
+**问题**：Auth 模块挂了会怎样？
+
+**已登录客户端的通信链路**：
+
+```
+客户端 ←→ Gateway ←→ Kernel ←→ 目标模块
+```
+
+Auth 模块**不在这条链路上**。认证成功后，Gateway 已为客户端建立了独立的 Kernel 代理连接，后续通信直接透传，不经过 Auth。
+
+**影响范围**：
+
+| 场景 | Auth 挂了期间 | Auth 重启后 |
+|------|-------------|------------|
+| 已登录的远程客户端 | ✅ 不受影响，正常通信 | ✅ 无需重新登录 |
+| 本地模块 | ✅ 不受影响（Launcher/Kernel 管理） | ✅ 无影响 |
+| 新的远程登录请求 | ❌ 失败（auth.verify 返回 MODULE_OFFLINE） | ✅ 恢复 |
+| Token 撤销操作 | ❌ 不可用 | ✅ 恢复 |
+| Token 管理面板 | ❌ 不可用 | ✅ 恢复 |
+
+**结论**：Auth 挂了的唯一影响是**这期间无法新登录**。Auth 重启后从 JSONL 恢复 token 记录，所有功能恢复，无需任何客户端重新登录。Watchdog 监控 Auth 模块，异常时自动重启。
+
+### 8.5 Gateway 重启的重连风暴
+
+**问题**：Gateway 重启 → 所有远程客户端同时断线 → 同时重连。
+
+**评估**：
+- 客户端已有指数退避 + jitter（`kernel-client.js`），重连自然错开
+- 持有 kite_token 的客户端：`auth.verify({method:"kite_token"})` 验证很快，无用户交互
+- 无 token 的客户端：需要重新走配对码/短信流程，但这种情况少
+- Gateway 的 IP 速率限制会平滑突发流量
+
+**结论**：可接受。
+
+### 8.6 OAuth HTTP 回调在 Gateway 上
+
+**问题**：Gateway 是 WS 网关，现在还要提供 HTTP 端口处理 OAuth 回调。
+
+**评估**：
+- OAuth 回调是标准 HTTP GET，逻辑极简（收到 code+state → 调 `auth.oauth_callback()` RPC → 返回 ticket）
+- Gateway 可以在 WS 端口旁边开一个轻量 HTTP handler，或复用同一端口（如 aiohttp 同时支持 WS 和 HTTP）
+- kite_console 的 Relay 不需要单独处理，因为 kite_console 本身就有 FastAPI HTTP 服务
+
+**结论**：可接受。Gateway 增加一个 `/auth/oauth/callback` HTTP 路由即可。
+
+### 8.7 auth_methods 缓存一致性
+
+**问题**：Gateway 启动时查询 `auth.get_supported_methods()` 并缓存。如果 Auth 模块后续动态增减认证方式，Gateway 的缓存过期。
+
+**评估**：
+- 认证方式变更极低频（部署级别的变更）
+- Auth 模块可以在方法变更时发布事件 `auth.methods_changed`，Gateway 订阅后刷新缓存
+- 或者 Gateway 定期刷新（如每 5 分钟）
+
+**结论**：初期不需要动态刷新，Gateway 重启即可。后续按需加事件通知。
+
+### 8.8 Kernel 零改动确认
+
+本方案 **Kernel 不需要任何改动**：
+
+- Gateway/Relay 用自己的 token 连 Kernel → 已有机制
+- 调 `auth.*` RPC → Kernel 标准跨模块转发，已有机制
+- `kernel.generate_token()` → 已有内置方法
+- 事件发布/订阅 → 已有机制
+- 为客户端创建新的 Kernel 连接 → 已有机制（现有 Relay 就是这么做的）
+
+### 8.9 Kernel 重启后的 Token 失效问题
+
+**问题**：Kernel 重启后 `token_map`（内存）清空，但 Auth 的 JSONL 里还记着之前颁发的 token。客户端拿旧 token 重连时，Auth 说"有效"，但 Kernel 不认识了。
+
+**解决方案**：Auth 模块订阅 `module.ready`（kernel）事件。Kernel 重启后，Auth 检测到 kernel ready，将所有存活的 token 通过 `kernel.register_tokens()` 批量重新注册到 Kernel 的 `token_map`。
+
+```mermaid
+sequenceDiagram
+    participant K as Kernel（重启后）
+    participant A as Auth 模块
+
+    K->>K: 启动，token_map 为空
+    A->>A: 收到 module.ready(kernel) 事件
+    A->>A: 从 JSONL 加载所有存活 token
+    A->>K: RPC: kernel.register_tokens([{module_id, token}, ...])
+    K->>K: 批量注册到 token_map
+    K->>A: {registered: N}
+    Note over K,A: token_map 恢复，旧 token 重新可用
+```
+
+这样 Kernel 重启对已登录客户端透明——Gateway 重连 Kernel 后，客户端的 token 仍然有效。
+
+## 9. 迁移路径
+
+### 阶段一：Auth 模块
+
+1. 创建 `extensions/services/auth/` 模块骨架
+2. 实现 `auth.verify()`（先支持 pairing_code + kite_token）
+3. 实现 `auth.request_pairing_code()`
+4. 实现 `auth.list_tokens()` / `auth.revoke_token()`
+5. 改造 kite_console Relay：认证逻辑改为调 `auth.*` RPC
+6. 测试：现有配对码登录和 Token 登录流程不受影响
+
+### 阶段二：Gateway 模块
+
+1. 创建 `extensions/services/gateway/` 模块骨架
+2. 实现 WS 服务器 + challenge/connect 握手
+3. 实现 pre-auth 白名单 + 速率限制
+4. 实现代理连接建立 + 双向 JSON-RPC 透传
+5. 实现 OAuth HTTP 回调端点
+6. 测试：远程模块通过 Gateway 端口接入
+
+### 阶段三：扩展认证方式
+
+1. Auth 模块新增 verifier：sms、email、oauth、aid
+2. 前端增加多种登录方式 UI
+3. 控制台增加 Token 管理界面增强
+4. 异常检测后台任务
+