insforge 1.2.10 → 1.3.0

package/GITHUB_OAUTH_SETUP.md

@@ -1,49 +1,49 @@
-# GitHub OAuth Application Setup Guide
-
-This document will guide you through the steps to create and configure a GitHub OAuth application for using GitHub login functionality in your project.
-
-## Step 1: Create a GitHub OAuth Application
-
-1.  **Log in to your GitHub account**.
-2.  Navigate to your developer settings page:
-    *   Click on your profile avatar in the top right corner.
-    *   Select **Settings**.
-    *   In the left sidebar, select **Developer settings**.
-3.  On the Developer settings page, select **OAuth Apps**, then click the **New OAuth App** button.
-
-## Step 2: Fill in Application Information
-
-On the "Register a new OAuth application" page, you need to fill in the following information:
-
-*   **Application name**: Give your application a descriptive name, such as `Insforge Dev Login`.
-*   **Homepage URL**: Your application's homepage URL. In development environment, you can set it to `http://localhost:7130` or your frontend development server address.
-*   **Application description** (optional): Provide a brief description of your application.
-*   **Authorization callback URL**: This is the URL where GitHub will redirect users after authorization. For local development, make sure to set it to:
-    ```
-    http://localhost:7130/api/auth/oauth/github/callback
-    ```
-    **Note**: This URL must exactly match the callback URL configured in your backend service, otherwise the OAuth flow will fail.
-
-After filling in the information, click **Register application**.
-
-## Step 3: Get Client ID and Client Secret
-
-After creating the application, you will be redirected to the application's settings page. Here you can see the **Client ID**.
-
-To get the **Client Secret**, click the **Generate a new client secret** button. GitHub will generate a secret and display it to you.
-
-**Important**: The Client Secret will only be shown once. Please copy it immediately and keep it secure. If you lose it, you will need to generate a new one.
-
-## Step 4: Configure Environment Variables
-
-After obtaining the Client ID and Client Secret, you need to add them to your project's `.env` file. Make sure your `.env` file (or corresponding environment configuration file) contains the following two lines:
-
-```env
-GITHUB_CLIENT_ID=YOUR_GITHUB_CLIENT_ID
-GITHUB_CLIENT_SECRET=YOUR_GITHUB_CLIENT_SECRET
-GITHUB_REDIRECT_URI=http://localhost:7130/api/auth/oauth/github/callback
-```
-
-Replace `YOUR_GITHUB_CLIENT_ID` and `YOUR_GITHUB_CLIENT_SECRET` with the actual values you obtained in the previous step.
-
-After completing the above steps, your application is ready to use GitHub OAuth for user authentication.
+# GitHub OAuth Application Setup Guide
+
+This document will guide you through the steps to create and configure a GitHub OAuth application for using GitHub login functionality in your project.
+
+## Step 1: Create a GitHub OAuth Application
+
+1.  **Log in to your GitHub account**.
+2.  Navigate to your developer settings page:
+    *   Click on your profile avatar in the top right corner.
+    *   Select **Settings**.
+    *   In the left sidebar, select **Developer settings**.
+3.  On the Developer settings page, select **OAuth Apps**, then click the **New OAuth App** button.
+
+## Step 2: Fill in Application Information
+
+On the "Register a new OAuth application" page, you need to fill in the following information:
+
+*   **Application name**: Give your application a descriptive name, such as `Insforge Dev Login`.
+*   **Homepage URL**: Your application's homepage URL. In development environment, you can set it to `http://localhost:7130` or your frontend development server address.
+*   **Application description** (optional): Provide a brief description of your application.
+*   **Authorization callback URL**: This is the URL where GitHub will redirect users after authorization. For local development, make sure to set it to:
+    ```
+    http://localhost:7130/api/auth/oauth/github/callback
+    ```
+    **Note**: This URL must exactly match the callback URL configured in your backend service, otherwise the OAuth flow will fail.
+
+After filling in the information, click **Register application**.
+
+## Step 3: Get Client ID and Client Secret
+
+After creating the application, you will be redirected to the application's settings page. Here you can see the **Client ID**.
+
+To get the **Client Secret**, click the **Generate a new client secret** button. GitHub will generate a secret and display it to you.
+
+**Important**: The Client Secret will only be shown once. Please copy it immediately and keep it secure. If you lose it, you will need to generate a new one.
+
+## Step 4: Configure Environment Variables
+
+After obtaining the Client ID and Client Secret, you need to add them to your project's `.env` file. Make sure your `.env` file (or corresponding environment configuration file) contains the following two lines:
+
+```env
+GITHUB_CLIENT_ID=YOUR_GITHUB_CLIENT_ID
+GITHUB_CLIENT_SECRET=YOUR_GITHUB_CLIENT_SECRET
+GITHUB_REDIRECT_URI=http://localhost:7130/api/auth/oauth/github/callback
+```
+
+Replace `YOUR_GITHUB_CLIENT_ID` and `YOUR_GITHUB_CLIENT_SECRET` with the actual values you obtained in the previous step.
+
+After completing the above steps, your application is ready to use GitHub OAuth for user authentication.

package/GOOGLE_OAUTH_SETUP.md

@@ -1,148 +1,148 @@
-# Google OAuth Login Setup Guide
-
-## Overview
-
-This project has integrated Google OAuth login functionality, supporting user authentication through Google accounts.
-
-## Environment Variable Configuration
-
-Add the following configuration to your `.env` file:
-
-```env
-# Google OAuth Configuration
-GOOGLE_CLIENT_ID=your_google_client_id
-GOOGLE_CLIENT_SECRET=your_google_client_secret
-GOOGLE_REDIRECT_URI=http://localhost:7130/api/oauth/google/callback
-```
-
-## Google Cloud Console Setup
-
-1. Visit [Google Cloud Console](https://console.cloud.google.com/)
-2. Create a new project or select an existing project
-3. Enable Google+ API and Google Identity API
-4. Create an OAuth 2.0 Client ID in the "Credentials" page
-5. Configure authorized redirect URIs:
-       - Development environment: `http://localhost:7130/api/auth/oauth/google/callback`
-    - Production environment: `https://yourdomain.com/api/auth/oauth/google/callback`
-
-## API Endpoints
-
-### 1. Get Google OAuth Authorization URL
-
-**Endpoint:** `GET /api/auth/v1/google-auth`
-
-**Parameters:**
-- `redirect_url`: Redirect URL after successful login
-
-**Response:**
-```json
-{
-  "success": true,
-  "data": {
-    "auth_url": "https://accounts.google.com/oauth/authorize?..."
-  }
-}
-```
-
-**Example:**
-```bash
-curl "http://localhost:7130/api/auth/v1/google-auth?redirect_url=http://localhost:7131/dashboard"
-```
-
-### 2. Google OAuth Callback Handling
-
-**Endpoint:** `GET /api/auth/oauth/google/callback`
-
-**Parameters:**
-- `code`: Authorization code returned by Google
-- `state`: State parameter (optional)
-
-**Process:**
-1. Receive Google authorization code
-2. Exchange for access token and ID token
-3. Verify ID token and retrieve user information
-4. Find or create user record
-5. Generate JWT token
-6. Redirect to specified URL with token information
-
-**Redirect URL Format:**
-```
-{redirect_url}?token={jwt_token}&user_id={user_id}&email={email}&name={name}
-```
-
-## User Flow
-
-### New User Registration
-1. User clicks "Sign in with Google"
-2. Redirect to Google authorization page
-3. After user authorization, system creates new user record:
-   - Create basic authentication record in `auth` table
-   - Create Google identity record in `identifies` table
-   - Create user profile record in `profiles` table
-4. Return JWT token and user information
-
-### Existing User Login
-1. User clicks "Sign in with Google"
-2. Redirect to Google authorization page
-3. After user authorization, system:
-   - Searches for user in `identifies` table by `provider` and `provider_id`
-   - Updates `last_login_at` timestamp
-4. Return JWT token and user information
-
-### Email Association
-- If user already exists but not associated with Google account, system will automatically associate
-- If Google account is already associated with another user, an error will be returned
-
-## Frontend Integration Example
-
-```javascript
-// 1. Get authorization URL
-const response = await fetch('/api/auth/v1/google-auth?redirect_url=/dashboard');
-const { auth_url } = await response.json();
-
-// 2. Redirect to Google authorization page
-window.location.href = auth_url;
-
-// 3. Handle returned token in callback page
-const urlParams = new URLSearchParams(window.location.search);
-const token = urlParams.get('token');
-const userId = urlParams.get('user_id');
-
-if (token) {
-  // Store token
-  localStorage.setItem('auth_token', token);
-  // Navigate to main page
-  window.location.href = '/dashboard';
-}
-```
-
-## Error Handling
-
-Common error codes:
-
-- `MISSING_FIELD`: Missing required parameters
-- `INVALID_CREDENTIALS`: Google token verification failed
-- `ALREADY_EXISTS`: User already exists
-
-## Security Considerations
-
-1. Ensure `GOOGLE_CLIENT_SECRET` environment variable is stored securely
-2. Use HTTPS in production environment
-3. Validate redirect URL legitimacy
-4. Regularly rotate JWT keys
-5. Monitor abnormal login activities
-
-## Troubleshooting
-
-1. **"Invalid redirect_uri" Error**
-   - Check redirect URI configuration in Google Cloud Console
-   - Ensure it matches the `GOOGLE_REDIRECT_URI` environment variable
-
-2. **"Invalid client" Error**
-   - Verify `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are correct
-   - Ensure necessary APIs are enabled in Google Cloud Console project
-
-3. **"Token verification failed" Error**
-   - Check network connectivity
-   - Verify Google API service status
-   - Confirm client ID configuration is correct
+# Google OAuth Login Setup Guide
+
+## Overview
+
+This project has integrated Google OAuth login functionality, supporting user authentication through Google accounts.
+
+## Environment Variable Configuration
+
+Add the following configuration to your `.env` file:
+
+```env
+# Google OAuth Configuration
+GOOGLE_CLIENT_ID=your_google_client_id
+GOOGLE_CLIENT_SECRET=your_google_client_secret
+GOOGLE_REDIRECT_URI=http://localhost:7130/api/oauth/google/callback
+```
+
+## Google Cloud Console Setup
+
+1. Visit [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select an existing project
+3. Enable Google+ API and Google Identity API
+4. Create an OAuth 2.0 Client ID in the "Credentials" page
+5. Configure authorized redirect URIs:
+       - Development environment: `http://localhost:7130/api/auth/oauth/google/callback`
+    - Production environment: `https://yourdomain.com/api/auth/oauth/google/callback`
+
+## API Endpoints
+
+### 1. Get Google OAuth Authorization URL
+
+**Endpoint:** `GET /api/auth/v1/google-auth`
+
+**Parameters:**
+- `redirect_url`: Redirect URL after successful login
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "auth_url": "https://accounts.google.com/oauth/authorize?..."
+  }
+}
+```
+
+**Example:**
+```bash
+curl "http://localhost:7130/api/auth/v1/google-auth?redirect_url=http://localhost:7131/dashboard"
+```
+
+### 2. Google OAuth Callback Handling
+
+**Endpoint:** `GET /api/auth/oauth/google/callback`
+
+**Parameters:**
+- `code`: Authorization code returned by Google
+- `state`: State parameter (optional)
+
+**Process:**
+1. Receive Google authorization code
+2. Exchange for access token and ID token
+3. Verify ID token and retrieve user information
+4. Find or create user record
+5. Generate JWT token
+6. Redirect to specified URL with token information
+
+**Redirect URL Format:**
+```
+{redirect_url}?token={jwt_token}&user_id={user_id}&email={email}&name={name}
+```
+
+## User Flow
+
+### New User Registration
+1. User clicks "Sign in with Google"
+2. Redirect to Google authorization page
+3. After user authorization, system creates new user record:
+   - Create basic authentication record in `auth` table
+   - Create Google identity record in `identifies` table
+   - Create user profile record in `profiles` table
+4. Return JWT token and user information
+
+### Existing User Login
+1. User clicks "Sign in with Google"
+2. Redirect to Google authorization page
+3. After user authorization, system:
+   - Searches for user in `identifies` table by `provider` and `provider_id`
+   - Updates `last_login_at` timestamp
+4. Return JWT token and user information
+
+### Email Association
+- If user already exists but not associated with Google account, system will automatically associate
+- If Google account is already associated with another user, an error will be returned
+
+## Frontend Integration Example
+
+```javascript
+// 1. Get authorization URL
+const response = await fetch('/api/auth/v1/google-auth?redirect_url=/dashboard');
+const { auth_url } = await response.json();
+
+// 2. Redirect to Google authorization page
+window.location.href = auth_url;
+
+// 3. Handle returned token in callback page
+const urlParams = new URLSearchParams(window.location.search);
+const token = urlParams.get('token');
+const userId = urlParams.get('user_id');
+
+if (token) {
+  // Store token
+  localStorage.setItem('auth_token', token);
+  // Navigate to main page
+  window.location.href = '/dashboard';
+}
+```
+
+## Error Handling
+
+Common error codes:
+
+- `MISSING_FIELD`: Missing required parameters
+- `INVALID_CREDENTIALS`: Google token verification failed
+- `ALREADY_EXISTS`: User already exists
+
+## Security Considerations
+
+1. Ensure `GOOGLE_CLIENT_SECRET` environment variable is stored securely
+2. Use HTTPS in production environment
+3. Validate redirect URL legitimacy
+4. Regularly rotate JWT keys
+5. Monitor abnormal login activities
+
+## Troubleshooting
+
+1. **"Invalid redirect_uri" Error**
+   - Check redirect URI configuration in Google Cloud Console
+   - Ensure it matches the `GOOGLE_REDIRECT_URI` environment variable
+
+2. **"Invalid client" Error**
+   - Verify `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are correct
+   - Ensure necessary APIs are enabled in Google Cloud Console project
+
+3. **"Token verification failed" Error**
+   - Check network connectivity
+   - Verify Google API service status
+   - Confirm client ID configuration is correct