用户注册与登录

本页说明如何用 Qoni SDK 让你的 App 用户通过 GenAuth 托管页注册和登录，拿到用户 ID 和登录态（Access Token）。之后为用户创建 Agent、把 Agent 绑定给用户、请用户委托权限，都从这里开始。

设计草案：托管登录 SDK

本页保留托管登录的目标设计。npm 0.9.0 没有 genauth.auth.createLoginUrl() 或 exchangeLoginCode()，下面的设计契约类型检查不代表这两个方法可以运行。当前应用使用已有 GenAuth/OIDC 登录集成取得用户 ID 与 Access Token；正式包可调用 currentUser() / genauth.userInfo() 读取用户，见 Qoni SDK。

注册和登录都在 Qoni 托管页面完成，走标准的 OIDC 授权码流程：你的服务端只负责生成跳转地址和兑换授权码，用户的密码不会经过你的服务端。

前置条件

• Node.js 20.11 或更高版本。
• 一组 Qoni AccessKey ID 和 Secret。
• 在 Qoni Console 的应用配置中登记登录回调地址，例如 https://app.example.com/auth/qoni/callback。

安装 SDK，并在 App 服务端初始化客户端：

npm install @qoniai/qoni

import { Qoni } from '@qoniai/qoni'

// 只在 App 服务端初始化；AccessKey 不能下发到浏览器或手机端
const qoni = new Qoni({
  accessKey: process.env.QONI_ACCESS_KEY!,
  secretKey: process.env.QONI_SECRET_KEY!,
})

1. 跳转到托管页

用户点击「注册」或「登录」时，生成托管页地址，把浏览器重定向过去：

const login = await qoni.genauth.auth.createLoginUrl({
  redirectUri: 'https://app.example.com/auth/qoni/callback',
  state: '<csrf-state>', // App 生成并保存，回调时核对
  screen: 'signup', // 新用户直接打开注册页；老用户传 'login'
})
console.log(login.url) // 把浏览器重定向到这个地址

• redirectUri 必须和 Console 中登记的回调地址完全一致，否则托管页会拒绝跳转回来。
• state 由你的 App 生成并保存在用户的会话里，回调时核对，用来防止跨站请求伪造。
• screen 只决定先打开哪个页面；用户在托管页里可以在注册和登录之间切换。

2. 回调时换取用户身份

用户完成注册或登录后，Qoni 带着 code 和 state 回到 redirectUri。先核对 state，再用 code 换取用户身份：

const session = await qoni.genauth.auth.exchangeLoginCode({
  code: '<callback-code>',
  redirectUri: 'https://app.example.com/auth/qoni/callback',
})
const user = session.user // user.id 是这位用户在 GenAuth 中的 ID
console.log(user.id, user.isNewUser, session.expiresIn)

• session.user.id 是用户在 GenAuth 中的 ID，之后的委托、审计都用它识别用户。
• session.accessToken 代表用户当前的登录态。为用户绑定 Agent 时要用它证明用户本人在场，见 Personal Agent：绑定用户与 Agent。把它和用户 ID 一起保存在服务端的会话里，不要下发到浏览器。
• user.isNewUser 为 true 时是刚注册的用户，可以在这里引导用户完成首次设置，例如为他创建 Agent。
• code 只能兑换一次，并且很快过期。兑换失败时，让用户重新走第 1 步。

检查点：拿到了 user.id 和 session.accessToken，state 与第 1 步保存的一致。

下一步

• 阅读 Personal Agent，为已登录的用户创建 Agent、完成绑定和委托，再让 Agent 替用户办事。
• 阅读 第一次委托：30 分钟跑通，了解委托令牌的完整链路。