# OAuth2 Provider 配置文档

> 创建日期：2026-05-26

---

## 概述

OAuth2 模块采用配置驱动的架构设计，内置 Provider 通过配置文件注册，添加新 Provider 只需配置无需编写代码。

---

## 内置 Provider

### GitHub

**配置项：**

| 环境变量 | 说明 |
|----------|------|
| `GITHUB_CLIENT_ID` | GitHub OAuth App 的 Client ID |
| `GITHUB_CLIENT_SECRET` | GitHub OAuth App 的 Client Secret |

**申请步骤：**

1. 登录 [GitHub Developer Settings](https://github.com/settings/developers)
2. 点击 "New OAuth App"
3. 填写应用信息：
   - **Application name**: 应用名称
   - **Homepage URL**: `http://localhost:3000`（开发环境）
   - **Authorization callback URL**: `http://localhost:3000/api/auth/oauth/github/callback`
4. 创建后复制 `Client ID` 和 `Client Secret`

**权限范围：** `read:user user:email`

**用户信息映射：**

```typescript
{
  "id": 123456,                    // -> providerUserId
  "login": "username",              // -> username
  "email": "user@example.com",     // -> email (需授权)
  "avatar_url": "https://..."      // -> avatar
}
```

---

### Google (预留)

**配置项：**

| 环境变量 | 说明 |
|----------|------|
| `GOOGLE_CLIENT_ID` | Google OAuth 2.0 Client ID |
| `GOOGLE_CLIENT_SECRET` | Google OAuth 2.0 Client Secret |

**申请步骤：**

1. 登录 [Google Cloud Console](https://console.cloud.google.com/)
2. 创建项目（或选择已有项目）
3. 启用 Google+ API
4. 配置 OAuth consent screen
5. 创建 OAuth 2.0 Client ID凭据
6. 添加回调 URL：`http://localhost:3000/api/auth/oauth/google/callback`

**权限范围：** `openid email profile`

**用户信息映射：**

```typescript
{
  "sub": "123456789",              // -> providerUserId
  "name": "User Name",             // -> username
  "email": "user@example.com",     // -> email
  "picture": "https://..."         // -> avatar
}
```

---

## 添加自定义 Provider

### 方式一：配置驱动（推荐）

对于标准 OAuth2 Provider，只需在 Provider 注册表中添加配置：

```typescript
// packages/oauth/src/providers/index.ts
import { GitHubProvider } from './github';
import { createOAuthProviders } from './factory';

export const oauthProviders = createOAuthProviders({
  github: new GitHubProvider({
    clientId: process.env.GITHUB_CLIENT_ID!,
    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
  }),
  // 添加新 Provider：
  // myprovider: new CustomProvider({
  //   clientId: process.env.MYPROVIDER_CLIENT_ID!,
  //   clientSecret: process.env.MYPROVIDER_CLIENT_SECRET!,
  //   // 自定义配置...
  // }),
});
```

### 方式二：实现 Provider 接口

对于非标准 OAuth2 Provider，需要实现 `OAuthProvider` 接口：

```typescript
// packages/oauth/src/providers/custom.ts
import type { OAuthProvider, OAuthUserInfo } from './base';
import { z } from 'zod';

export class CustomProvider implements OAuthProvider {
  name = 'custom';
  icon = '🔐';
  clientId: string;
  clientSecret: string;
  authorizeUrl = 'https://custom.example.com/oauth/authorize';
  tokenUrl = 'https://custom.example.com/oauth/token';
  userInfoUrl = 'https://custom.example.com/oauth/userinfo';
  scopes = ['read:user'];

  constructor(config: { clientId: string; clientSecret: string }) {
    this.clientId = config.clientId;
    this.clientSecret = config.clientSecret;
  }

  mapUserInfo(raw: Record<string, unknown>): OAuthUserInfo {
    return {
      provider: this.name,
      providerUserId: String(raw.id),
      username: String(raw.username ?? ''),
      email: String(raw.email ?? ''),
      avatar: String(raw.avatar_url ?? ''),
    };
  }
}
```

---

## Provider 接口规范

```typescript
interface OAuthProvider {
  // 提供商名称（唯一标识）
  name: string;

  // 图标（emoji 或 Icon 组件名）
  icon: string;

  // OAuth 配置
  clientId: string;
  clientSecret: string;
  authorizeUrl: string;
  tokenUrl: string;
  userInfoUrl: string;
  scopes: string[];

  // 用户信息映射
  mapUserInfo(raw: Record<string, unknown>): OAuthUserInfo;
}
```

---

## 环境变量配置示例

```bash
# .env 或 .env.local

# GitHub OAuth
GITHUB_CLIENT_ID=Iv1.xxxxxxxxxxxxxxxx
GITHUB_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Google OAuth (预留)
GOOGLE_CLIENT_ID=xxxxx-xxxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=xxxxx-xxxxx
```

---

## Provider 开发检查清单

- [ ] 在 [Provider 设置平台](https://github.com/settings/developers) 注册应用
- [ ] 配置正确的回调 URL：`https://your-domain.com/api/auth/oauth/{provider}/callback`
- [ ] 获取 `clientId` 和 `clientSecret`
- [ ] 设置环境变量
- [ ] 实现 `mapUserInfo` 方法（字段映射）
- [ ] 测试完整的 OAuth 流程
- [ ] 验证用户信息正确获取（username、email、avatar）