# OAuth 第三方登录注册指南

## 1. Google OAuth

**前往**: [Google Cloud Console](https://console.cloud.google.com/apis/credentials)

**步骤**:
1. 创建项目（或选已有项目）
2. 左侧菜单 → "OAuth consent screen" → 选 External → 填写应用名称（AgentFox）、用户支持邮箱
3. 左侧菜单 → "Credentials" → "Create Credentials" → "OAuth 2.0 Client ID"
4. 应用类型选 **Web application**
5. 名称填 `AgentFox Web`
6. "Authorized redirect URIs" 添加：
   - 开发：`http://localhost:3000/api/auth/oauth/google/callback`
   - 生产：`https://你的域名/api/auth/oauth/google/callback`
7. 创建后拿到 **Client ID** 和 **Client Secret**

**写入 `.env`**:
```
GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPx-xxx
```

---

## 2. GitHub OAuth

**前往**: [GitHub Developer Settings](https://github.com/settings/developers)

**步骤**:
1. "OAuth Apps" → "New OAuth App"
2. 填写：
   - Application name: `AgentFox`
   - Homepage URL: `http://localhost:5173`（开发）
   - Authorization callback URL: `http://localhost:3000/api/auth/oauth/github/callback`
3. 创建后拿到 **Client ID**，点击 "Generate a new client secret" 拿到 **Client Secret**

**写入 `.env`**:
```
GITHUB_CLIENT_ID=Ov23li...
GITHUB_CLIENT_SECRET=xxx
```

> 生产环境需要再创建一个 OAuth App，callback URL 改为生产域名。

---

## 3. Apple Sign In

> 需要 **Apple Developer Program** 付费账号（$99/年）。如果暂时没有，可以先跳过，按钮已在前端显示但会报错提示。

**前往**: [Apple Developer - Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources)

### 3a. 注册 App ID
1. "Identifiers" → "+" → 选 "App IDs" → "App"
2. Description: `AgentFox`
3. Bundle ID: `com.agentfox.web`（Explicit）
4. 勾选 "Sign In with Apple" → Continue → Register

### 3b. 创建 Services ID
1. "Identifiers" → "+" → 选 "Services IDs"
2. Description: `AgentFox Web Login`
3. Identifier: `com.agentfox.web.login` ← 这就是 **APPLE_CLIENT_ID**
4. 勾选 "Sign In with Apple" → Configure:
   - Primary App ID: 选上面创建的 App ID
   - Domains: `你的域名`（开发时用 ngrok）
   - Return URLs: `https://你的域名/api/auth/oauth/apple/callback`
5. Save → Continue → Register

### 3c. 创建 Key
1. "Keys" → "+" → 名称 `AgentFox Auth Key`
2. 勾选 "Sign In with Apple" → Configure → 选 Primary App ID → Save
3. Continue → Register → **下载 .p8 文件**（只能下载一次！）
4. 记下 **Key ID**

### 3d. 找到 Team ID
1. 右上角账户名 → "Membership details"
2. 记下 **Team ID**

**写入 `.env`**:
```
APPLE_CLIENT_ID=com.agentfox.web.login
APPLE_TEAM_ID=XXXXXXXXXX
APPLE_KEY_ID=XXXXXXXXXX
APPLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIGT...这里是.p8文件内容...\n-----END PRIVATE KEY-----"
```

> Apple 回调必须 HTTPS。本地开发可以用 `ngrok http 3000` 获取临时 HTTPS 域名，然后设置 `OAUTH_CALLBACK_BASE_URL=https://xxx.ngrok.io`。

---

## 通用配置

`.env` 中还需要设置回调基础 URL：

```
OAUTH_CALLBACK_BASE_URL=http://localhost:3000
FRONTEND_URL=http://localhost:5173
```

生产环境改为实际域名即可。

## 验证

配置好后启动 `pnpm dev:server` + `pnpm dev:web`，访问 `/login` 页面点击对应按钮即可测试。