@linkfox-web/api-user-center

LinkFox 用户中心接口。登录成功后自动写入 @linkfox-web/http 的会话并同步当前团队，其他 @linkfox-web/api-* 包随即可用；同时注册「刷新 token」「补团队」能力，供所有服务包在 401 时使用。

pnpm add @linkfox-web/http @linkfox-web/api-user-center

| 函数 | 说明 | | --- | --- | | getImageVerifyCode() | 图形验证码，返回 { uuid, imageBase64 } | | getVerifyCode(params) | 发送短信验证码 | | loginByPassword(params) / loginByCode(params) | 账密 / 短信验证码登录 | | getWechatQrCode() / getWechatQrCodeStatus(sessionId) / loginByWechat(params) | 微信扫码登录 | | getUserInfo() | 用户信息与团队列表 | | switchTeam(teamId) | 切换团队并写入会话 | | getPersonalKey(teamId?) | 当前用户在某团队下的个人 API Key 列表；teamId 为用户中心团队 ID，不传取当前团队 | | syncApiKey(teamId?) | 取个人 API Key（优先 USER_PRIMARY）注入 @linkfox-web/ai-tools 配置并返回；只在内存，刷新页面或 switchTeam 后需重新调用 | | logout() | 清除本地会话，并清掉已注入的 API Key |

登录函数的第二个参数可传 { sourceUrl }，默认取 location.href。source、systemId、clientChannel 可通过 configure({ services: { 'user-center': { … } } }) 覆盖。

第三方应用 SSO（iframe）

这套 token 属于第三方应用服务，与上面的主站登录会话、刷新及团队同步相互独立。SDK 不依赖 React 或 Next.js。

import { configure } from '@linkfox-web/http'
import {
  handleThirdPartySsoCallback, startThirdPartySso,
  readThirdPartySsoSession, clearThirdPartySsoSession,
} from '@linkfox-web/api-user-center'

configure({ services: { 'third-party-sso': { baseURL: 'https://agent-studio-api.linkfox.vip' } } })
const clientId = 'your-application-client-id'

// 应用启动时先处理 iframe 回调；返回 true 时仅显示“正在完成登录”，不要跳转或加载业务页。
const isCallback = handleThirdPartySsoCallback()
if (!isCallback) {
  const existing = readThirdPartySsoSession(clientId)
  // existing 非空可恢复页面用户状态；否则在用户点击登录时调用下方示例。
}

// 以下代码放在登录按钮事件中，回调页不得执行：
const controller = new AbortController()
const session = await startThirdPartySso({
  clientId,
  redirectUri: window.location.origin, // /get 支持传回调地址，默认也是当前 origin
  signal: controller.signal,
  getFrameWindow: () => document.querySelector('iframe')?.contentWindow ?? null,
  onAuthorization: ({ authorizationUrl, appName }) => {
    // 使用自己的组件展示 iframe 并加载 authorizationUrl；仅向 UI 提供 URL 和应用名。
  },
})
// 用户取消/组件销毁时 controller.abort()；成功后关闭 iframe 并使用 session.name 等用户信息。
// 退出仅清除当前应用会话：clearThirdPartySsoSession(clientId)。

登录成功后 SDK 用 @linkfox-web/http 的 setSession() 保存会话（附带 ssoClientId，有效期取 JWT 的 exp），@linkfox-web/ai-tools 等服务会自动把 accessToken 放进 Authorization。这会替换当前站点的 http 会话，在主站域名下使用时请先 configure({ cookieKey: 'LINKFOX_SSO_TOKEN' }) 之类的独立键，避免覆盖主站登录。readThirdPartySsoSession(clientId) 只认同一 clientId 写入的会话，过期或损坏时会清掉；clearThirdPartySsoSession(clientId) 不动其他来源的会话。无法保存或 token 缺少有效 exp 时登录失败。解码 exp 只用于本地过期判断，不代替服务端验签；前端 cookie 不具备 HttpOnly。

getThirdPartyApplication(clientId, { redirectUri, signal }) 和 loginThirdPartyApplication(params, { signal }) 可独立调用；后者会保存应用会话。SSO 接口本身均为匿名请求，不向 SSO 服务发送已有 token，不调用主站刷新接口；HTTP 200 中的 { error: { code, message } } 也会作为异常抛出。

startThirdPartySso() 会生成本次授权的随机 state，保留响应中的 PKCE 参数，校验回调 origin、路径、state 和 iframe 来源，最多消费一次 code；默认 5 分钟超时。回调必须与应用同源，根页面不能在回调处理前重定向丢掉查询参数。授权站点必须允许 iframe 嵌入，用户仍需自行完成其身份验证。

本地接口仿真使用用户提供的契约及真实 /get 响应编写（CLI 未登录，未查询远端维护者 mock）：

postman simulation run postman/simulations/third-party-sso.sim.yaml --port 4901 --output ndjson
# 在仓库根目录的另一个终端：
pnpm build
node scripts/check-sso-simulation.mjs

将 SDK 的 third-party-sso.baseURL 指向 http://127.0.0.1:4901/sso；模拟授权码为 simulation-code，模拟 token 仅用于验证流程，不能调用真实服务。