@seaverse/auth-sdk 0.2.1 → 0.2.2

package/README.md

@@ -126,44 +126,73 @@ await client.resetPassword({
 });
 ```
 
-### 3. OAuth 第三方登录
+### 3. OAuth 第三方登录 (Backend Proxy Mode)
 
-#### Google 登录
+SDK 使用 Backend Proxy Mode，Client Secret 永不暴露给前端，安全性更高。
+
+**优势**:
+- ✅ Client Secret 从不暴露给前端
+- ✅ 支持任意开发者域名(无需在 OAuth 平台配置)
+- ✅ 内置 CSRF 防护
+- ✅ 零配置，开箱即用
+
+**工作流程**:
+1. 前端调用 `{provider}Authorize()` 获取 OAuth URL
+2. 前端重定向用户到 OAuth 提供商
+3. 用户授权后，OAuth 提供商回调到固定的 account-hub URL
+4. account-hub 处理 OAuth，创建 JWT token
+5. account-hub 302 重定向到 `return_url?token=xxx`
+6. 前端从 URL 提取 token 并存储
+
+#### 使用示例
+
+**方式1：使用默认 return_url（当前页面）**
 
 ```typescript
-// 步骤1: 获取Google授权码后，交换token
-const result = await client.googleCodeToToken({
-  code: 'google-auth-code',
-  redirectUri: 'https://yourdomain.com/auth/callback',
-});
+// Google 登录
+const { authorize_url } = await client.googleAuthorize();
+window.location.href = authorize_url;
 
-localStorage.setItem('token', result.token);
+// Discord 登录
+const { authorize_url } = await client.discordAuthorize();
+window.location.href = authorize_url;
 
-// 解绑Google账号
-await client.unlinkGoogle();
+// GitHub 登录
+const { authorize_url } = await client.githubAuthorize();
+window.location.href = authorize_url;
 ```
 
-#### Discord 登录
+**方式2：自定义 return_url**
 
 ```typescript
-const result = await client.discordCodeToToken({
-  code: 'discord-auth-code',
-  redirectUri: 'https://yourdomain.com/auth/callback',
+// 登录后跳转到 dashboard
+const { authorize_url } = await client.googleAuthorize({
+  return_url: 'https://mygame.com/dashboard'
 });
+window.location.href = authorize_url;
+```
 
-// 解绑Discord账号
-await client.unlinkDiscord();
+**在回调页面提取 token**:
+
+```typescript
+// URL: https://mygame.com/?token=eyJhbGc...
+const token = new URLSearchParams(window.location.search).get('token');
+if (token) {
+  localStorage.setItem('token', token);
+  // 登录成功，跳转或更新 UI
+}
 ```
 
-#### GitHub 登录
+#### OAuth 账号解绑
 
 ```typescript
-const result = await client.githubCodeToToken({
-  code: 'github-auth-code',
-  redirectUri: 'https://yourdomain.com/auth/callback',
-});
+// 解绑 Google 账号
+await client.unlinkGoogle();
 
-// 解绑GitHub账号
+// 解绑 Discord 账号
+await client.unlinkDiscord();
+
+// 解绑 GitHub 账号
 await client.unlinkGithub();
 ```
 
@@ -189,7 +218,7 @@ const client = new SeaVerseBackendAPIClient({
   environment: 'production',
 });
 
-// 创建登录弹窗（深色主题）
+// 创建登录弹窗
 const authModal = new AuthModal({
   client,
   theme: 'dark', // 'dark' | 'light' - 默认为 'dark'
@@ -211,20 +240,12 @@ const authModal = new AuthModal({
     console.error('认证错误:', error.message);
   },
 
-  // OAuth配置（可选）
-  oauthConfig: {
-    google: {
-      clientId: 'YOUR_GOOGLE_CLIENT_ID',          // 必填
-      redirectUri: window.location.origin,        // 可选，默认为 window.location.origin
-    },
-    discord: {
-      clientId: 'YOUR_DISCORD_CLIENT_ID',         // 必填
-      redirectUri: window.location.origin,        // 可选，默认为 window.location.origin
-    },
-    github: {
-      clientId: 'YOUR_GITHUB_CLIENT_ID',          // 必填
-      redirectUri: window.location.origin,        // 可选，默认为 window.location.origin
-    },
+  // OAuth 配置（可选）
+  returnUrl: 'https://mygame.com/',  // OAuth 登录后返回的 URL，可选，默认为 window.location.origin
+  enableOAuth: {
+    google: true,   // 启用 Google 登录
+    discord: true,  // 启用 Discord 登录
+    github: true,   // 启用 GitHub 登录
   },
 });
 
@@ -239,64 +260,98 @@ authModal.hide();
 
 // 销毁弹窗
 authModal.destroy();
+```
+
 #### OAuth 配置说明
 
-`oauthConfig` 参数是**完全可选的**：
+`enableOAuth` 参数是**完全可选的**：
 
-- 如果**不提供** `oauthConfig`，则不会显示任何第三方登录按钮
-- 如果**部分配置**（如只配置 Google），则只显示已配置的按钮
+- 如果**不提供** `enableOAuth`，则不会显示任何第三方登录按钮
+- 如果**部分配置**（如只启用 Google），则只显示已启用的按钮
 - 如果**完整配置**所有平台，则显示所有第三方登录按钮
 
 **配置字段说明**：
-- `clientId`：**必填** - OAuth 应用的客户端 ID
-- `redirectUri`：**可选** - OAuth 回调地址，不填则默认为 `window.location.origin`
-- `scope`：**可选** - OAuth 权限范围，每个平台有默认值
+- `returnUrl`：**可选** - OAuth 登录后返回的 URL，不填则默认为 `window.location.origin`
+- `enableOAuth.google`：是否启用 Google 登录
+- `enableOAuth.discord`：是否启用 Discord 登录
+- `enableOAuth.github`：是否启用 GitHub 登录
 
 ```typescript
 // 示例1：无OAuth按钮
-const client1 = new SeaVerseBackendAPIClient({ appId: 'your app id' });
 const authModal1 = new AuthModal({
-  client: client1,
+  client,
   theme: 'dark',
-  // 不传 oauthConfig，不显示任何OAuth按钮
+  // 不传 enableOAuth，不显示任何OAuth按钮
 });
 
 // 示例2：只显示Google登录
-const client2 = new SeaVerseBackendAPIClient({ appId: 'your app id' });
 const authModal2 = new AuthModal({
-  client: client2,
+  client,
   theme: 'light',
-  oauthConfig: {
-    google: {
-      clientId: 'YOUR_GOOGLE_CLIENT_ID',
-      // redirectUri 可选，不填则默认为 window.location.origin
-    },
-    // Discord 和 GitHub 未配置，不会显示这些按钮
+  returnUrl: 'https://mygame.com/dashboard',
+  enableOAuth: {
+    google: true,
+    // Discord 和 GitHub 未启用，不会显示这些按钮
   },
 });
 
-// 示例3：显示所有OAuth按钮（自定义 redirectUri）
-const client3 = new SeaVerseBackendAPIClient({ appId: 'your app id' });
+// 示例3：显示所有OAuth按钮
 const authModal3 = new AuthModal({
-  client: client3,
+  client,
   theme: 'dark',
-  oauthConfig: {
-    google: {
-      clientId: '...',
-      redirectUri: 'https://yourdomain.com/auth/callback' // 自定义回调地址
-    },
-    discord: {
-      clientId: '...'
-      // redirectUri 可选，不填则默认为 window.location.origin
-    },
-    github: {
-      clientId: '...'
-      // redirectUri 可选，不填则默认为 window.location.origin
-    },
+  enableOAuth: {
+    google: true,
+    discord: true,
+    github: true,
   },
 });
 ```
 
+#### 处理 OAuth 回调
+
+在 Backend Proxy Mode 下，OAuth 登录后会重定向到 `returnUrl?token=xxx`。在页面加载时检查并处理token:
+
+```typescript
+// 在页面加载时自动处理 OAuth 回调
+const result = AuthModal.handleOAuthCallback({
+  client,
+  onLoginSuccess: (token) => {
+    localStorage.setItem('token', token);
+    console.log('OAuth 登录成功');
+
+    // 现在可以直接调用需要认证的接口
+    // handleOAuthCallback 已自动调用 client.setToken()
+    client.getCurrentUser()
+      .then(user => console.log('用户信息:', user));
+  },
+});
+
+if (result) {
+  console.log('处理了 OAuth 回调，token:', result.token);
+}
+```
+
+**重要说明**：
+- `handleOAuthCallback()` 会自动调用 `client.setToken(token)` 来更新 client 的认证配置
+- 这意味着在 `onLoginSuccess` 回调之后，所有需要认证的 API（如 `getCurrentUser()`、`logout()` 等）都会自动带上 `Authorization` header
+
+#### 手动设置 Token
+
+如果你不使用 `AuthModal.handleOAuthCallback()`，也可以手动设置 token：
+
+```typescript
+// 从 URL 提取 token
+const token = new URLSearchParams(window.location.search).get('token');
+if (token) {
+  // 手动设置 token
+  client.setToken(token);
+  localStorage.setItem('token', token);
+
+  // 现在可以调用需要认证的接口
+  const user = await client.getCurrentUser();
+}
+```
+
 ### 5. 容器管理
 
 ```typescript
@@ -462,15 +517,16 @@ SDK支持以下环境：
 | `logout()` | - | `SuccessResponse` | 登出 |
 | `forgotPassword()` | `{ email }` | `SuccessResponse` | 忘记密码 |
 | `resetPassword()` | `{ token, new_password }` | `SuccessResponse` | 重置密码 |
+| `setToken()` | `token: string` | `void` | 设置认证 token（OAuth 登录后使用） |
 | `getApiServiceToken()` | - | `ApiServiceTokenResponse` | 获取API Token |
 
 ### OAuth相关
 
 | 方法 | 参数 | 返回值 | 说明 |
 |------|------|--------|------|
-| `googleCodeToToken()` | `{ code, redirectUri }` | `OAuthTokenResponse` | Google登录 |
-| `discordCodeToToken()` | `{ code, redirectUri }` | `OAuthTokenResponse` | Discord登录 |
-| `githubCodeToToken()` | `{ code, redirectUri }` | `OAuthTokenResponse` | GitHub登录 |
+| `googleAuthorize()` | `{ return_url? }` | `OAuthAuthorizeResponse` | Google OAuth 授权 URL |
+| `discordAuthorize()` | `{ return_url? }` | `OAuthAuthorizeResponse` | Discord OAuth 授权 URL |
+| `githubAuthorize()` | `{ return_url? }` | `OAuthAuthorizeResponse` | GitHub OAuth 授权 URL |
 | `unlinkGoogle()` | - | `SuccessResponse` | 解绑Google |
 | `unlinkDiscord()` | - | `SuccessResponse` | 解绑Discord |
 | `unlinkGithub()` | - | `SuccessResponse` | 解绑GitHub |
@@ -547,25 +603,11 @@ interface AuthModalOptions {
   onLoginSuccess?: (token: string, user: any) => void;
   onSignupSuccess?: (token: string, user: any) => void;
   onError?: (error: Error) => void;
-  oauthConfig?: OAuthConfig;
-}
-
-// OAuth配置
-interface OAuthConfig {
-  google?: {
-    clientId: string;        // 必填
-    redirectUri?: string;    // 可选，默认为 window.location.origin
-    scope?: string;          // 可选，默认为 'openid email profile'
-  };
-  discord?: {
-    clientId: string;        // 必填
-    redirectUri?: string;    // 可选，默认为 window.location.origin
-    scope?: string;          // 可选，默认为 'identify email'
-  };
-  github?: {
-    clientId: string;        // 必填
-    redirectUri?: string;    // 可选，默认为 window.location.origin
-    scope?: string;          // 可选，默认为 'read:user user:email'
+  returnUrl?: string;        // OAuth 登录后返回的 URL，可选，默认为 window.location.origin
+  enableOAuth?: {
+    google?: boolean;        // 启用 Google 登录
+    discord?: boolean;       // 启用 Discord 登录
+    github?: boolean;        // 启用 GitHub 登录
   };
 }
 ```