xnx_oauth OAuth2.0 统一登录

功能

• 标准 OAuth2.0 授权码流程，支持 QQ / GitHub / Google 等第三方登录（内置模板，可自定义 provider）
• 多 provider 注册机制：后台 kv 配置 + 其他插件静态注册（OAuthService::registerProvider()）
• 完整授权流程：state 校验防 CSRF、PKCE（S256）支持、SSL 证书校验、原子写入头像
• 登录或绑定四分支：已绑定直接登录、已登录则绑定、邮箱匹配自动合并、其他拒绝并引导注册
• 个人中心绑定管理页 + 后台绑定记录列表（含筛选、分页、强制解绑）
• 字段映射支持嵌套字段（如 a.b），适配各平台差异的 userinfo 响应
• 头像下载到本地 upload/avatar/{dir}/{uid}.png（仅当用户无自定义头像时）
• 多语言（zh-cn / zh-tw / en-us）

文件结构

plugin/xnx_oauth/
├── conf.json
├── install.php / uninstall.php
├── setting.php                      # 后台配置 + 绑定记录管理
├── icon.png
├── model/
│   └── OAuthService.php              # 核心服务（provider 注册、授权、绑定、头像下载）
├── route/
│   └── oauth.php                     # 前台路由：login / callback / bind-manage / unbind
├── admin/
│   └── view/htm/
│       ├── oauth_setting.htm         # 后台 provider 配置页
│       └── oauth_bindlist.htm         # 后台绑定记录列表
├── view/htm/
│   └── my_oauth.htm                  # 个人中心绑定管理页
└── hook/
    ├── model_inc_file.php            # 自动加载 OAuthService
    ├── model_route_table_end.php     # 注册 oauth 路由
    ├── index_route_case_end.php
    ├── admin_sidebar_end.htm         # 后台侧栏入口
    ├── my_sidebar_nav_security_before.htm  # 个人中心侧栏入口
    ├── user_login_submit_after.htm
    ├── user_create_submit_after.htm
    ├── lang_zh_cn_bbs.php
    ├── lang_zh_tw_bbs.php
    └── lang_en_us_bbs.php

配置流程

1. 后台「插件管理」启用 xnx_oauth
2. 进入「插件设置」→「配置」→ 开启「启用 OAuth 登录」
3. 选择要接入的平台（QQ / GitHub / Google 或自定义），填写 AppID / AppSecret、授权 / Token / UserInfo 三个 URL、scope、字段映射
4. 如需 PKCE（如 Google），勾选 enable_pkce
5. 如需邮箱自动合并已有账号，开启 auto_merge_by_email
6. 测试：退出登录 → 访问登录页 → 点击第三方登录 → 完成授权回调跳转个人中心；或在个人中心「安全设置」点击「OAuth 绑定管理」进行绑定 / 解绑

扩展说明

OAuthService 通过 hook/model_inc_file.php 自动加载，可被其他插件调用以注册自定义 provider。

Service 类与方法签名

// 静态注册 provider（推荐在其他插件的 model_inc_file.php 或 hook 中调用）
OAuthService::registerProvider(array $config): void
// $config 关键字段：name, display_name, icon, color,
//   authorize_url, token_url, userinfo_url, pre_userinfo_url(可选),
//   appid, appkey, scope, enable, enable_pkce, field_mapping, extra_params

// 读取 provider
OAuthService::getProviders(): array
OAuthService::getProvider(string $name): ?array
OAuthService::init(): void   // 合并 kv 配置与静态注册（同名后者覆盖并记录 xn_log 警告）

// 实例方法（通过 getInstance() 获取）
$svc = OAuthService::getInstance();
$svc->getAuthUrl(string $provider): array        // ['ok'=>bool, 'url'=>string, 'message'=>string]
$svc->handleCallback($provider, $code, $state): array  // 含 state 校验 + token 换取 + 用户信息映射 + 登录或绑定
$svc->loginOrBind($provider, $userInfo): array
$svc->bindAccount(int $uid, $provider, $userInfo): array
$svc->unbindAccount(int $uid, $provider): array  // 解绑前会校验是否有其他登录方式
$svc->getUserBinds(int $uid): array
$svc->hasOtherLoginMethod(int $uid, string $excludeProvider = ''): bool

触发时机与参数

• registerProvider() 通常在其他插件的 model_inc_file.php hook 中调用，确保 OAuthService::init() 之前完成注册
• 同名 provider 后注册覆盖先注册，会写 xn_log('...', 'oauth_error') 警告
• handleCallback() 内部依次执行：state 校验 → PKCE 校验 → exchangeToken → getUserInfo（QQ 等会先调 pre_userinfo_url 取 openid）→ mapUserInfo（按 field_mapping 映射 openid/unionid/nickname/avatar/email/gender）→ loginOrBind
• 数据表 xnx_oauth_bind 字段含 provider+openid 唯一索引、provider+unionid 普通索引，方便其他插件按 unionid 查询跨平台身份

版本 1.1.0 | 兼容 Xiuno 1.1+