接入说明

面向开发者说明认证接口、会话模型与页面路由兼容关系。

接入说明

StarWork Web 端复用现有 auth-service 认证能力，同时新增浏览器会话支持。

兼容保留的接口

• GET /login
• GET /auth/providers
• GET /auth/:provider/start
• GET /auth/:provider/callback
• POST /auth/session/exchange
• POST /auth/session/transfer
• GET /auth/session/handoff
• GET /auth/session/me
• POST /auth/logout

GET /auth/session/me 当前返回

未登录：

{ "authenticated": false }

已登录时，当前接口除了基础登录态，还会返回当前用户的套餐、积分和 API Key 视图：

{
  "authenticated": true,
  "provider": "dingtalk",
  "token": "<session-token>",
  "user": {
    "id": "user_123",
    "displayName": "Alice",
    "email": "alice@example.com",
    "phone": "13800000000",
    "role": "user"
  },
  "channel": "web",
  "organization": {
    "id": "org_1",
    "name": "OpenWork"
  },
  "activePlan": {
    "id": "plan_pro_monthly",
    "code": "pro",
    "name": "Pro 月付",
    "expiresAt": 1767225600000
  },
  "activePlanCredits": {
    "total": 5000,
    "expiresAt": 1767225600000,
    "packageCount": 1
  },
  "activeTopupCredits": {
    "total": 2000,
    "expiresAt": 1769817600000,
    "packageCount": 2
  },
  "apiKey": "sk-xxxxx",
  "lastSeenAt": 1764139200000,
  "expiresAt": 1764142800000
}

字段说明：

• activePlan: 当前有效套餐及到期时间
• activePlanCredits: 当前有效套餐积分汇总及最近到期时间
• activeTopupCredits: 当前有效加油包积分汇总及最近到期时间
• apiKey: 当前用户绑定的网关 API Key

说明：

• 本接口返回的是“当前有效视图”，不会把已过期套餐或已过期积分包继续返回给调用方
• 免费套餐若被系统自动补齐，会体现在 activePlan
• 当前设计用于 Admin、桌面端同步和后续治理策略编译，不代表 OpenCode 会原生实时回源本接口读取凭据

新增的 Web 语义

GET /auth/:provider/start 支持可选 query：

client=desktop|web
returnTo=/

POST /auth/session/exchange 支持：

{ "grant": "<code>", "channel": "desktop|web" }

POST /auth/session/transfer 支持：

{ "returnTo": "/" }

回调策略

• 桌面端：保持 deep link 返回桌面应用
• Web：在浏览器中写入 starwork_web_session cookie，并跳回 returnTo

会话家族

每次首次登录都会生成一个 session_family_id，桌面端与 Web 通过 transfer / bootstrap 建立的新会话会复用同一个 family。

这意味着：

• 登录一次，多端可通行
• 任一端调用 POST /auth/logout，同一 family 下的 desktop / web 会话会一起失效