feat(oauth2): add email format transformation support (#818)

* feat(oauth2): add email format transformation support

- Add enableEmailFormat, userEmailFormat, userEmailReplace fields
- Support regex pattern matching and replacement template ($1, $2, etc.)
- Add Linux Do OAuth2 template with email format pre-configured
- Add input length limit (256 chars) to prevent ReDoS attacks
- Update admin UI with conditional display and tooltips
- Update documentation (zh/en) with configuration examples

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* chore: update lock files and version

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: restore accessTokenFormat as optional field

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

vitepress-docs/docs/en/guide/feature/user-oauth2.md

@@ -13,6 +13,11 @@
 
 Reference: [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app)
 
+### Linux Do
+
+- Create an application at [Linux Do Connect](https://connect.linux.do/) to obtain `Client ID` and `Client Secret`
+- Linux Do returns a user ID instead of an email, so you need to enable the Email Format feature
+
 ### Authentik
 
 - [Authentik OAuth2 Provider](https://docs.goauthentik.io/docs/providers/oauth2/)
@@ -21,6 +26,43 @@ Reference: [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/bu
 
 ![oauth2](/feature/oauth2.png)
 
+### Configuration Fields
+
+| Field | Description |
+|-------|-------------|
+| Name | OAuth2 provider name, displayed on the login page |
+| Client ID | OAuth2 application ID |
+| Client Secret | OAuth2 application secret |
+| Authorization URL | OAuth2 authorization endpoint |
+| Access Token URL | Endpoint to obtain Access Token |
+| Access Token Params Format | Token request format: `json` or `urlencoded` |
+| User Info URL | Endpoint to get user information |
+| User Email Key | Key for email field in user info, supports JSONPath (e.g., `$[0].email`) |
+| Redirect URL | OAuth2 callback URL |
+| Scope | OAuth2 permission scope |
+
+### Email Format Transformation
+
+When OAuth2 returns a non-standard email format (e.g., returns a user ID), you can enable the Email Format feature.
+
+| Field | Description |
+|-------|-------------|
+| Enable Email Format | Enable email format transformation |
+| Email Regex Pattern | Regular expression to match the original value, use capture groups `()` |
+| Replace Template | Replacement template, use `$1`, `$2`, etc. to reference capture groups |
+
+**Examples:**
+
+| Scenario | Original Value | Regex Pattern | Replace Template | Result |
+|----------|---------------|---------------|------------------|--------|
+| ID to Email | `12345` | `^(.+)$` | `linux_do_$1@oauth.linux.do` | `linux_do_12345@oauth.linux.do` |
+| Change Domain | `john@old.com` | `^(.+)@old\.com$` | `$1@new.com` | `john@new.com` |
+| Extract Username | `john@corp.com` | `^(.+)@.*$` | `$1@mymail.com` | `john@mymail.com` |
+
+### Email Address Allow List
+
+When enabled, only emails from specified domains can login.
+
 ## Test User Login Page
 
 ![oauth2 login](/feature/oauth2-login.png)

vitepress-docs/docs/zh/guide/feature/user-oauth2.md

@@ -13,6 +13,11 @@
 
 参考 [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app)
 
+### Linux Do
+
+- 在 [Linux Do Connect](https://connect.linux.do/) 创建应用获取 `Client ID` 和 `Client Secret`
+- Linux Do 返回的是用户 ID 而非邮箱，需要启用邮箱格式转换功能
+
 ### Authentik
 
 - [Authentik OAuth2 Provider](https://docs.goauthentik.io/docs/providers/oauth2/)
@@ -21,6 +26,43 @@
 
 ![oauth2](/feature/oauth2.png)
 
+### 配置字段说明
+
+| 字段 | 说明 |
+|------|------|
+| Name | OAuth2 提供商名称，显示在登录页面 |
+| Client ID | OAuth2 应用 ID |
+| Client Secret | OAuth2 应用密钥 |
+| Authorization URL | OAuth2 授权端点 |
+| Access Token URL | 获取 Access Token 的端点 |
+| Access Token Params Format | Token 请求格式：`json` 或 `urlencoded` |
+| User Info URL | 获取用户信息的端点 |
+| User Email Key | 用户信息中邮箱字段的 key，支持 JSONPath (如 `$[0].email`) |
+| Redirect URL | OAuth2 回调地址 |
+| Scope | OAuth2 权限范围 |
+
+### 邮箱格式转换
+
+当 OAuth2 返回的不是标准邮箱格式时（如返回用户 ID），可以启用邮箱格式转换功能。
+
+| 字段 | 说明 |
+|------|------|
+| Enable Email Format | 启用邮箱格式转换 |
+| Email Regex Pattern | 正则表达式，用于匹配原始值，使用捕获组 `()` |
+| Replace Template | 替换模板，使用 `$1`、`$2` 等引用捕获组 |
+
+**示例：**
+
+| 场景 | 原始值 | 正则表达式 | 替换模板 | 结果 |
+|------|--------|-----------|----------|------|
+| ID 转邮箱 | `12345` | `^(.+)$` | `linux_do_$1@oauth.linux.do` | `linux_do_12345@oauth.linux.do` |
+| 换域名 | `john@old.com` | `^(.+)@old\.com$` | `$1@new.com` | `john@new.com` |
+| 提取用户名 | `john@corp.com` | `^(.+)@.*$` | `$1@mymail.com` | `john@mymail.com` |
+
+### 邮件地址白名单
+
+启用后，只有指定域名的邮箱才能登录。
+
 ## 测试用户登录页面
 
 ![oauth2 login](/feature/oauth2-login.png)