@seaverse/auth-sdk 0.3.8 → 0.4.0

package/README.md

@@ -94,7 +94,261 @@ const health = await client.getHealth();
 console.log('Health:', health);
 ```
 
-### 2. 用户认证
+### 2. Iframe 场景下的 Token 获取
+
+当你的应用被嵌入到 iframe 中时，可以使用 `getIframeToken()` 方法从父页面获取认证 token。这对于第三方登录重定向场景特别有用。
+
+#### 检查是否在 iframe 中运行
+
+在调用 iframe 相关方法前，建议先检查应用是否在 iframe 中运行：
+
+```typescript
+import { SeaVerseBackendAPIClient } from '@seaverse/auth-sdk';
+
+// 方式 1: 使用静态方法（无需 client 实例）
+if (SeaVerseBackendAPIClient.isInIframe()) {
+  console.log('应用正在 iframe 中运行');
+} else {
+  console.log('应用不在 iframe 中运行');
+}
+
+// 方式 2: 使用实例方法
+const client = new SeaVerseBackendAPIClient({
+  appId: 'your app id',
+});
+
+if (client.isInIframe()) {
+  console.log('应用正在 iframe 中运行');
+  // 可以安全地调用 getIframeToken()
+}
+```
+
+#### 子页面 (iframe 内) 使用方式
+
+```typescript
+import { SeaVerseBackendAPIClient } from '@seaverse/auth-sdk';
+
+const client = new SeaVerseBackendAPIClient({
+  appId: 'your app id',
+});
+
+// 先检查是否在 iframe 中
+if (!client.isInIframe()) {
+  console.log('应用不在 iframe 中，跳过 token 获取');
+  // 可以使用其他登录方式
+} else {
+  // 在 iframe 中请求父页面的 token
+  try {
+    const token = await client.getIframeToken({
+      timeout: 10000 // 可选，默认 30 秒
+    });
+
+    // 设置 token 到 client
+    client.setToken(token);
+    localStorage.setItem('token', token);
+
+    console.log('成功从父页面获取 token');
+
+    // 现在可以使用需要认证的 API
+    const user = await client.getCurrentUser();
+    console.log('当前用户:', user);
+  } catch (error) {
+    console.error('获取 token 失败:', error);
+  }
+}
+```
+
+#### 父页面监听并响应 token 请求
+
+```typescript
+// 父页面需要监听来自 iframe 的 token 请求
+window.addEventListener('message', (event) => {
+  // 检查消息类型
+  if (event.data.type === 'seaverse:get_token') {
+    const requestId = event.data.requestId;
+
+    // 获取你的 token (从 localStorage、API 等)
+    const token = localStorage.getItem('token');
+
+    if (token) {
+      // 发送 token 给 iframe
+      event.source.postMessage({
+        type: 'seaverse:token',
+        requestId: requestId,
+        payload: {
+          accessToken: token,
+          expiresIn: 3600,
+        },
+      }, '*');
+    } else {
+      // 发送错误消息
+      event.source.postMessage({
+        type: 'seaverse:token_error',
+        requestId: requestId,
+        error: 'No token available',
+      }, '*');
+    }
+  }
+});
+```
+
+#### 完整的 iframe 登录流程示例
+
+```typescript
+// 子页面 (iframe)
+import { SeaVerseBackendAPIClient } from '@seaverse/auth-sdk';
+
+const client = new SeaVerseBackendAPIClient({
+  appId: 'your app id',
+});
+
+async function initIframeApp() {
+  // 0. 检查是否在 iframe 中
+  if (!client.isInIframe()) {
+    console.log('应用不在 iframe 中，使用常规登录流程');
+    // 使用常规登录流程
+    showLoginForm();
+    return;
+  }
+
+  try {
+    // 1. 尝试从父页面获取 token
+    const token = await client.getIframeToken();
+    client.setToken(token);
+    localStorage.setItem('token', token);
+
+    // 2. 验证 token 并获取用户信息
+    const user = await client.getCurrentUser();
+    console.log('已登录:', user);
+
+    // 3. 继续应用逻辑
+    startApp(user);
+  } catch (error) {
+    // 4. 如果获取失败，通知父页面需要登录
+    window.parent.postMessage({
+      type: 'seaverse:need_login',
+    }, '*');
+  }
+}
+
+initIframeApp();
+```
+
+```typescript
+// 父页面
+window.addEventListener('message', (event) => {
+  // 处理 token 请求
+  if (event.data.type === 'seaverse:get_token') {
+    const requestId = event.data.requestId;
+    const token = localStorage.getItem('token');
+
+    if (token) {
+      event.source.postMessage({
+        type: 'seaverse:token',
+        requestId: requestId,
+        payload: {
+          accessToken: token,
+          expiresIn: 3600,
+        },
+      }, '*');
+    } else {
+      // 如果没有 token，唤起登录
+      showLoginModal();
+    }
+  }
+
+  // 处理需要登录的消息
+  if (event.data.type === 'seaverse:need_login') {
+    showLoginModal();
+  }
+});
+
+// 登录成功后，通知 iframe
+function onLoginSuccess(newToken) {
+  const iframe = document.querySelector('iframe');
+  iframe.contentWindow.postMessage({
+    type: 'seaverse:token',
+    requestId: 'auto', // 自动登录时可以使用固定 ID
+    payload: {
+      accessToken: newToken,
+      expiresIn: 3600,
+    },
+  }, '*');
+}
+```
+
+#### TypeScript 类型定义
+
+SDK 提供了完整的 TypeScript 类型支持:
+
+```typescript
+import type {
+  IframeTokenRequestMessage,
+  IframeTokenResponseMessage,
+  IframeTokenErrorMessage,
+} from '@seaverse/auth-sdk';
+
+// Token 请求消息
+const request: IframeTokenRequestMessage = {
+  type: 'seaverse:get_token',
+  requestId: 'unique-id',
+};
+
+// Token 响应消息
+const response: IframeTokenResponseMessage = {
+  type: 'seaverse:token',
+  requestId: 'unique-id',
+  payload: {
+    accessToken: 'jwt-token',
+    expiresIn: 3600,
+  },
+};
+
+// 错误消息
+const error: IframeTokenErrorMessage = {
+  type: 'seaverse:token_error',
+  requestId: 'unique-id',
+  error: 'Token not available',
+};
+```
+
+#### 安全注意事项
+
+1. **使用特定 origin**: 在生产环境中，建议使用特定的 origin 而不是 `'*'`:
+   ```typescript
+   // 父页面
+   const ALLOWED_ORIGIN = 'https://your-iframe-domain.com';
+   event.source.postMessage(message, ALLOWED_ORIGIN);
+
+   // 子页面发送时也可以指定
+   window.parent.postMessage(message, 'https://parent-domain.com');
+   ```
+
+2. **验证消息来源**: 在处理 postMessage 时验证 origin:
+   ```typescript
+   window.addEventListener('message', (event) => {
+     // 验证来源
+     if (event.origin !== 'https://trusted-domain.com') {
+       return;
+     }
+     // 处理消息...
+   });
+   ```
+
+3. **Token 过期处理**: 记得处理 token 过期的情况:
+   ```typescript
+   try {
+     const user = await client.getCurrentUser();
+   } catch (error) {
+     if (error.response?.status === 401) {
+       // Token 过期，重新获取
+       const newToken = await client.getIframeToken();
+       client.setToken(newToken);
+     }
+   }
+   ```
+
+### 3. 用户认证
 
 ```typescript
 // 注册新用户
@@ -150,7 +404,7 @@ await client.resetPassword({
 });
 ```
 
-### 3. OAuth 第三方登录 (Backend Proxy Mode)
+### 4. OAuth 第三方登录 (Backend Proxy Mode)
 
 SDK 使用 Backend Proxy Mode，Client Secret 永不暴露给前端，安全性更高。
 
@@ -220,7 +474,7 @@ await client.unlinkDiscord();
 await client.unlinkGithub();
 ```
 
-### 4. 使用登录UI组件
+### 5. 使用登录UI组件
 
 SDK 提供精美的登录弹窗组件，支持深色和浅色两种主题：
 
@@ -436,7 +690,7 @@ if (token) {
 }
 ```
 
-### 5. 容器管理
+### 6. 容器管理
 
 ```typescript
 // 列出所有容器
@@ -471,7 +725,7 @@ await client.unregisterContainer({
 const stats = await client.getContainerStats();
 ```
 
-### 6. 技能市场
+### 7. 技能市场
 
 ```typescript
 // 列出市场技能
@@ -500,7 +754,7 @@ await client.uninstallSkill({
 });
 ```
 
-### 7. 邀请码管理
+### 8. 邀请码管理
 
 ```typescript
 // 申请邀请码（当用户没有邀请码时）
@@ -550,7 +804,7 @@ const usages = await client.getInviteUsages('inv_abc123', {
 console.log('使用记录:', usages.data.usages);
 ```
 
-### 8. 邮箱验证与邀请码绑定
+### 9. 邮箱验证与邀请码绑定
 
 #### 邮箱验证（自动登录）
 
@@ -734,7 +988,7 @@ const inviteCodeInfo = AuthModal.handleInviteCodeRequired(
 );
 ```
 
-### 9. 其他功能
+### 10. 其他功能
 
 ```typescript
 // 获取API Service Token
@@ -937,6 +1191,8 @@ SDK支持以下环境：
 | `forgotPassword()` | `{ email, frontend_url? }` | `SuccessResponse` | 忘记密码，frontend_url 默认为 window.location.href |
 | `resetPassword()` | `{ token, new_password }` | `SuccessResponse` | 重置密码 |
 | `setToken()` | `token: string` | `void` | 设置认证 token（OAuth 登录后使用） |
+| `isInIframe()` | - | `boolean` | 检查应用是否在 iframe 中运行（支持静态方法和实例方法） |
+| `getIframeToken()` | `{ timeout? }` | `Promise<string>` | 从父页面获取 token（仅 iframe 场景），timeout 默认 30000ms |
 | `getApiServiceToken()` | - | `ApiServiceTokenResponse` | 获取API Token |
 
 #### 注册流程说明

package/dist/index.cjs

@@ -1285,6 +1285,148 @@ class SeaVerseBackendAPIClient {
         // Update the httpClient's auth
         this.httpClient.auth = auth;
     }
+    /**
+     * Check if the application is running inside an iframe
+     * This is a utility method to detect iframe context before calling iframe-specific methods
+     *
+     * @returns true if running in an iframe, false otherwise
+     *
+     * @example
+     * // Check if in iframe before requesting token
+     * if (client.isInIframe()) {
+     *   const token = await client.getIframeToken();
+     *   client.setToken(token);
+     * } else {
+     *   console.log('Not running in an iframe');
+     * }
+     *
+     * @example
+     * // Use as a static method without client instance
+     * if (SeaVerseBackendAPIClient.isInIframe()) {
+     *   console.log('Application is embedded in an iframe');
+     * }
+     */
+    static isInIframe() {
+        // Only works in browser environment
+        if (typeof window === 'undefined') {
+            return false;
+        }
+        // Check if window.self is not equal to window.top
+        // This is the standard way to detect if running in an iframe
+        try {
+            return window.self !== window.top;
+        }
+        catch (e) {
+            // If we get a SecurityError (cross-origin iframe), we're definitely in an iframe
+            return true;
+        }
+    }
+    /**
+     * Instance method to check if running in an iframe
+     * Calls the static method for convenience
+     *
+     * @returns true if running in an iframe, false otherwise
+     */
+    isInIframe() {
+        return SeaVerseBackendAPIClient.isInIframe();
+    }
+    /**
+     * Get token from parent window via iframe communication
+     * This method is designed for scenarios where the application is embedded in an iframe
+     * and needs to obtain authentication tokens from the parent page
+     *
+     * @param options - Configuration options
+     * @param options.timeout - Timeout in milliseconds (default: 30000)
+     * @returns Promise that resolves with the access token
+     *
+     * @example
+     * // In an iframe application
+     * try {
+     *   const token = await client.getIframeToken({ timeout: 10000 });
+     *   client.setToken(token);
+     *   localStorage.setItem('token', token);
+     *   console.log('Successfully obtained token from parent');
+     * } catch (error) {
+     *   console.error('Failed to get token from parent:', error);
+     * }
+     *
+     * @example
+     * // Parent page should listen for token requests and respond:
+     * window.addEventListener('message', (event) => {
+     *   if (event.data.type === 'seaverse:get_token') {
+     *     const requestId = event.data.requestId;
+     *     // Get your token (from localStorage, API, etc.)
+     *     const token = localStorage.getItem('token');
+     *     // Send token back to iframe
+     *     event.source.postMessage({
+     *       type: 'seaverse:token',
+     *       requestId: requestId,
+     *       payload: {
+     *         accessToken: token,
+     *         expiresIn: 3600,
+     *       },
+     *     }, '*');
+     *   }
+     * });
+     */
+    getIframeToken(options) {
+        // Only works in browser environment
+        if (typeof window === 'undefined') {
+            return Promise.reject(new Error('getIframeToken() can only be used in browser environment'));
+        }
+        // Check if we're in an iframe
+        if (!this.isInIframe()) {
+            return Promise.reject(new Error('getIframeToken() can only be used inside an iframe'));
+        }
+        const timeout = options?.timeout || 30000; // Default 30 seconds
+        const requestId = `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+        return new Promise((resolve, reject) => {
+            let timeoutId = null;
+            let messageHandler = null;
+            // Cleanup function
+            const cleanup = () => {
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                    timeoutId = null;
+                }
+                if (messageHandler) {
+                    window.removeEventListener('message', messageHandler);
+                    messageHandler = null;
+                }
+            };
+            // Set up timeout
+            timeoutId = setTimeout(() => {
+                cleanup();
+                reject(new Error(`Token request timeout after ${timeout}ms`));
+            }, timeout);
+            // Set up message listener
+            messageHandler = (event) => {
+                const data = event.data;
+                // Check if this is a response to our request
+                if (data &&
+                    typeof data === 'object' &&
+                    data.requestId === requestId) {
+                    if (data.type === 'seaverse:token') {
+                        cleanup();
+                        const tokenData = data;
+                        resolve(tokenData.payload.accessToken);
+                    }
+                    else if (data.type === 'seaverse:token_error') {
+                        cleanup();
+                        const errorData = data;
+                        reject(new Error(errorData.error || 'Failed to get token from parent'));
+                    }
+                }
+            };
+            window.addEventListener('message', messageHandler);
+            // Send request to parent
+            const requestMessage = {
+                type: 'seaverse:get_token',
+                requestId,
+            };
+            window.parent.postMessage(requestMessage, '*');
+        });
+    }
     // ============================================================================
     // Authentication & OAuth APIs
     // ============================================================================