# chongming-auth

auth 域共享契约包：网关内置登录与 auth 插件（用户管理）的公共依赖。
两侧不允许互相 import（插件/worker SDK 保持与网关解耦），共享物只放这里。

## 职责拆分（auth 域）

| 部分 | 归属 | 说明 |
| --- | --- | --- |
| Users 模型（唯一权威定义） | 本包 | 禁止在别处重复定义同表模型 |
| 建库 / admin 种子 / 登录校验 / JWT 签发 | 本包 | `store.py` |
| `POST /api/v1/auth/login`（内置登录端点） | 网关核心 `chongming/app/routes/auth.py` | 管理平面可用性底线：auth 插件缩容/故障时登录与 admin API 仍可用 |
| 注册 / 资料 / 改密（用户管理） | auth 插件 `plugins.auth` | 可替换的业务部分，支持 inline/external |

## 稳定契约（改动即破坏性变更）

1. **JWT claims**：`sub / username / email / full_name / avatar_url / phone /
   is_verified / is_superuser / created_at / updated_at / last_login_at`，
   token 有效期默认 10800s（`DEFAULT_TOKEN_EXPIRES_SECONDS`）。
   网关 admin API 依赖 `is_superuser` 判定超管（`worker_admin.py`）；
   网关 JWT 校验依赖（`core/auth.py`）按 `[security]` 的 secret/algorithm 验签。
2. **登录响应 shape**：`{result, token, message, timestamp}`，失败文案
   （`用户名错误` / `密码错误` / `用户已经注销或被禁用`）与前端兼容。
3. **users 表 schema**：对既有 `auth.db`（SQLite）与 PostgreSQL users 表零迁移。

## 数据库定位

与 `chongming_worker.Plugin.init_database` 语义一致：

- 配置含 `database.url`（插件 config.toml 的 `[workers.config.database]`）→ PostgreSQL；
- 否则 SQLite：`data_dir/auth.db`（`[workers.config]` 的 `data_dir`，默认 `./data`）。

网关 lifespan（`setup_auth_store`）与 auth 插件读取同一份配置，指向同一张表。

## 用法

```python
from chongming_auth import open_database, seed_admin, verify_login, issue_token

db = await open_database({"data_dir": "./data"})   # 或 {"database": {"url": "postgresql://..."}}
await seed_admin(db)                                # 幂等，多进程并发安全
user, message = await verify_login(db, "admin", "admin")
if user is not None:
    token = issue_token(user, secret, algorithm)
```

## 开发

```bash
cd utils/auth
uv sync
uv run pytest
```