# Auth OAuth 插件 — 第三方授权登录示例（身份源插件）

基于 `chongming-auth` 共享契约实现**身份源插件**的参考实现：准入判断归插件，
平台凭证签发归 `chongming_auth.issue_token`（claims 契约与网关内置登录完全一致）。
第三方身份登录后拿到的 token 与内置登录**完全等价**——网关 JWT 验签、
`user_info` 随信封透传、admin API 判超管全部无缝生效。

## 提供的身份源

| 身份源 | 模式 | 端点 |
| --- | --- | --- |
| GitHub | OAuth2 授权码（SPA JSON 流程） | `GET /auth/oauth/github_authorize`、`POST /auth/oauth/github_callback` |
| 手机号 | 一次性验证码（演示模式） | `POST /auth/oauth/phone_send_code`、`POST /auth/oauth/phone_login` |

## 身份源插件的标准形态（写新身份源时照此扩展）

1. **准入**：校验第三方凭据（OAuth code / OTP / LDAP 密码 / ...）；
2. **映射**：在插件自有绑定表 `identity_bindings(provider, provider_uid, user_id)`
   中 find-or-create——老用户换身份源登录仍是同一账号体系；
3. **建号**：无绑定时新建 `users` 账号（密码为随机不可用值）+ 绑定记录，
   与网关内置登录**共用同一张 users 表**（`chongming_auth.open_database`）；
4. **签发**：`chongming_auth.issue_token(user, secret, algorithm)`。

扩展新身份源（LDAP / 企业微信 / 飞书 / OIDC ...）只需：加一个 provider 对接模块
+ 一组 TOML 路由 + 一个 `@rpc_method` 端点，调 `store.find_or_create_user` 即可。

## 配置

`config/workers/auth_oauth/config.toml` 的 `[workers.config]`：

```toml
return_otp_in_response = true   # 演示模式：验证码随响应返回。生产必须 false 并接短信通道

[workers.config.github]
client_id / client_secret / redirect_uri / scope
```

## 安全说明（务必阅读）

- **本插件须以 inline 模式运行**（默认）：`issue_token` 需要 `[security]` 签名密钥，
  external 进程持有该密钥即能铸造超管 token。external 化前需平台提供内部签发 API
  或按 issuer 分离密钥。
- `return_otp_in_response` 仅限本地演示，生产必须关闭并接真实短信通道。
- OAuth state 与 OTP 验证码均存共享缓存（`chongming_cache`），一次性消费、300s 过期。

## 踩坑记录（写插件必读）

**插件必须提供 `models/pydantic.py`**（gen_models 产物位置，手写等价物亦可）。
网关契约校验按 `plugins.<type>.models.pydantic` → `src.plugins....` → `workers....`
顺序探测；缺失时 `src.plugins.` 兜底路径会以第二个模块名重新执行整个插件包
（父包导入链），插件内自定义 SQLModel 表会在全局元数据中重复定义，
网关启动即崩（`Table 'xxx' is already defined for this MetaData instance`）。

## 依赖

| 工具包 | 用途 |
| --- | --- |
| `chongming-auth` | Users 模型 / 建库 / 登录校验 / issue_token（共享契约） |
| `chongming-cache` | OAuth state 与 OTP 验证码存储 |
| `chongming-worker` | `@rpc_method` 装饰器 + Worker 运行时 |
| `httpx` | GitHub OAuth API 调用 |