heicode/docs/integration/heicode-oauth-flow.md

HeiCode 浏览器登录流程（客户端 ↔ Manager）

本文给出 Heicode 客户端通过浏览器完成 Manager 登录的端到端流程，并说明字段、错误模型与扩展点。当前实现以 loopback 直接回 token 为主，OAuth2 + PKCE 已在客户端预留。

代码位置：

• 客户端：cc-haha/src/server/api/heicode-auth.ts
• 服务端：new-api/controller/heicode_oauth.go、new-api/router/heicode-router.go

一、设计目标

• 用户启动 Heicode 客户端 → 看到登录卡片 → 点击「浏览器登录」
• 浏览器跳到 Manager 控制台，完成账号登录
• Manager 颁发 / 复用一条专用 Token，回跳客户端 loopback 地址
• 客户端落地 Token，激活 Provider，自动拉模型列表

整体不要求平台事先支持完整 OAuth2，loopback + token 即可工作；后续可平滑切换到 Authorization Code + PKCE。

二、参与方与端点

端点	谁实现	用途
POST /api/heicode-auth/oauth/start	客户端本地服务	生成 state / PKCE，返回 authorize URL
GET /heicode/oauth/authorize	Manager（new-api）	校验 loopback、引导登录、回跳 token
GET /heicode/oauth/session	Manager（new-api）	给「请先登录」过渡页轮询登录态
GET /api/heicode-auth/oauth/callback	客户端本地服务	接收 token / code，落地并激活

三、当前实现（loopback + token 直回）

sequenceDiagram
  autonumber
  participant U as 用户
  participant C as Heicode 客户端<br/>(本地 HTTP 服务)
  participant B as 浏览器
  participant M as Heicode Manager<br/>(new-api)

  U->>C: 点击「浏览器登录」
  C->>C: 生成 state / PKCE 并写入会话
  C-->>B: 返回 authorize URL
  B->>M: GET /heicode/oauth/authorize?state=...&redirect_uri=...&provider_id=...
  alt 用户未登录
    M-->>B: 渲染过渡页（链接到 /login）
    loop 每 1.5s
      B->>M: GET /heicode/oauth/session
      M-->>B: { logged_in }
    end
    B->>M: 重新请求 authorize
  end
  M->>M: 校验 loopback redirect_uri
  M->>M: 取或新建名为 "HeiCode" 的 Token
  M-->>B: 302 redirect_uri?state=...&token=sk-XXXX
  B->>C: GET /api/heicode-auth/oauth/callback?token=...&state=...
  C->>C: 校验 state、激活 Provider、拉模型
  C-->>B: 返回成功页（用户可关闭浏览器）

关键校验

• state 与 redirect_uri 必填，redirect_uri 必须是 loopback 主机：127.0.0.1 / localhost / ::1
• 客户端会话过期（默认 5 分钟）后回调直接判失败
• 客户端默认从 ?token= / ?access_token= / ?apiKey= / ?apikey= 任一字段读取 Token

字段表

名称	在	说明
state	URL query	客户端生成的不可猜测随机串，回跳时校验
redirect_uri	URL query	必须是 loopback；Manager 会拒绝其它主机
provider_id	URL query	taijiaicloud / clawdrouter；用于客户端识别落到哪个 provider
token	回跳 query	Manager 颁发的 HeiCode 专用 Token，前缀 sk-
code / code_verifier	标准 OAuth	当前 loopback 模式不使用；启用 PKCE 时必需
code_challenge / code_challenge_method	URL query	启用 PKCE 时由客户端附带，方法固定 S256
client_id / scope	URL query	启用 PKCE 时附带，分别来自客户端环境变量

四、扩展形态：标准 OAuth2 + PKCE

当平台具备 token 端点后，仅需在客户端配置环境变量即可启用：

变量	用途
HEICODE_<PROVIDER>_OAUTH_AUTHORIZE_URL	自定义 authorize 端点
HEICODE_<PROVIDER>_OAUTH_TOKEN_URL	code → access_token 交换端点
HEICODE_<PROVIDER>_OAUTH_CLIENT_ID	OAuth Client ID（启用 PKCE 时必需）
HEICODE_<PROVIDER>_OAUTH_SCOPE	申请的 scope，例如 models:read,messages:write

详见 [../onboarding/env-variables.md](../onboarding/env-variables.md)。

sequenceDiagram
  participant C as 客户端
  participant B as 浏览器
  participant P as 平台 Authorize
  participant T as 平台 Token

  C->>B: authorize URL?response_type=code&client_id&...&code_challenge
  B->>P: 用户登录授权
  P-->>B: 302 redirect_uri?code=&state=
  B->>C: callback?code=&state=
  C->>T: POST /token { grant_type=authorization_code, code, code_verifier, ... }
  T-->>C: { access_token }
  C->>C: 激活 Provider 并拉模型

五、错误模型

触发	HTTP / 行为	客户端展示
state / redirect_uri 缺失	Manager 400	浏览器停留报错
redirect_uri 非 loopback	Manager 400 redirect_uri must be a loopback address	检查客户端配置
用户未登录	Manager 渲染过渡页并轮询 session	浏览器停留并自动跳转
客户端会话过期	客户端 callback 返回错误页	提示「登录会话已过期，请回到 HeiCode 重试」
平台未配置 token 端点但只回了 code	客户端 callback 错误页	提示「平台未配置 token 交换端点」
Provider 模型校验失败	客户端 400	拉模型异常或返回空集

六、与 Agnet API 设计的衔接

• 这里的 Token 用于 Heicode 客户端调 Manager；Manager 调 Agnet 时使用 [./agnet-platform-api-design.md](./agnet-platform-api-design.md) §2.1 / §2.2 中的 M2M JWT 或用户委派令牌
• 跨链路追踪建议在 Manager 调 Agnet 时附带 X-Heicode-Correlation-Id 与本登录会话关联

七、安全注意事项

• 客户端必须在每次启动时 新生成 state / code_verifier，禁止复用
• Manager 必须 拒绝 非 loopback 的 redirect_uri（已实现）
• Token 长生命周期使用前提：Manager 端可吊销且具备审计；不要在跨设备粘贴中传播
• 出现安全事件时，Manager 应能批量吊销名为 HeiCode 的 Token