# Auth Worker 插件

用户认证与授权插件，提供完整的用户管理系统。

---

## 功能

- **用户注册**：用户名 + 邮箱 + 密码注册，自动校验唯一性
- **用户登录**：JWT Token 签发，有效期 3 小时
- **获取用户信息**：根据 JWT Token 获取完整用户档案
- **修改密码**：旧密码验证 + 新密码更新
- **更新资料**：更新全名、邮箱、头像、手机号等信息
- **自动初始化**：首次启动自动创建 `admin` 管理员账户

---

## 数据库

使用 SQLite（通过 `chongming-database` 异步封装），数据库文件位于 `data/storage/chongming/auth.db`。

### Users 表结构

| 字段              | 类型              | 说明                              |
| ----------------- | ----------------- | --------------------------------- |
| `id`              | `str` (PK)        | UUID 格式主键                     |
| `username`        | `str(50)` UNIQUE  | 登录用户名                        |
| `email`           | `str(255)` UNIQUE | 电子邮箱                          |
| `hashed_password` | `str(255)`        | Argon2id 加密密码                 |
| `full_name`       | `str(100)`        | 用户全名（可选）                  |
| `avatar_url`      | `str(500)`        | 头像链接（可选）                  |
| `phone`           | `str(20)`         | 手机号码（可选）                  |
| `is_active`       | `bool`            | 账户启用状态（默认 `true`）       |
| `is_verified`     | `bool`            | 邮箱/手机验证状态（默认 `false`） |
| `is_superuser`    | `bool`            | 超级管理员标识（默认 `false`）    |
| `created_at`      | `datetime`        | 创建时间                          |
| `updated_at`      | `datetime`        | 最后更新时间                      |
| `last_login_at`   | `datetime`        | 最后登录时间（可选）              |

密码使用 Rust 实现的 **Argon2id** 哈希，内存成本 19456 KiB，迭代 2 次，并行度 1。

---

## API 端点

所有端点路由前缀为 `/auth`。

### `POST /auth/register` — 用户注册

无需认证。

```json
// 请求
{
  "username": "john",
  "password": "secret123",
  "email": "john@example.com",
  "full_name": "John Doe",
  "phone": "13800138000"
}

// 响应
{
  "result": "success",
  "message": "注册成功",
  "user_id": "a1b2c3d4_12345_1720000000.123",
  "timestamp": 1720000000.123
}
```

### `POST /auth/login` — 登录

无需认证。

```json
// 请求
{
  "username": "admin",
  "password": "admin"
}

// 响应
{
  "result": "success",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "message": "登录成功",
  "timestamp": 1720000000.123
}
```

JWT Token 有效期 3 小时，载荷包含：`sub`（用户ID）、`username`、`email`、`full_name`、`is_superuser` 等。

### `GET /auth/me?user_id=<id>` — 获取用户信息

需要 JWT 鉴权（`Authorization: Bearer <token>`）。

```json
// 响应
{
  "result": "success",
  "id": "a1b2c3d4_12345_1720000000.123",
  "username": "john",
  "email": "john@example.com",
  "full_name": "John Doe",
  "avatar_url": null,
  "phone": "13800138000",
  "is_active": true,
  "is_verified": false,
  "is_superuser": false,
  "created_at": "2024-01-01T00:00:00+00:00",
  "updated_at": "2024-01-01T00:00:00+00:00",
  "last_login_at": null
}
```

### `POST /auth/change_password` — 修改密码

需要 JWT 鉴权。

```json
// 请求
{
  "user_id": "a1b2c3d4_12345_1720000000.123",
  "old_password": "secret123",
  "new_password": "newSecret456"
}

// 响应
{
  "result": "success",
  "message": "密码修改成功",
  "timestamp": 1720000000.123
}
```

### `POST /auth/update_profile` — 更新用户资料

需要 JWT 鉴权。仅更新非空字段。

```json
// 请求
{
  "user_id": "a1b2c3d4_12345_1720000000.123",
  "full_name": "John Updated",
  "email": "",
  "avatar_url": "https://example.com/avatar.png",
  "phone": ""
}

// 响应
{
  "result": "success",
  "message": "资料更新成功",
  "timestamp": 1720000000.123
}
```

---

## 默认管理员账户

首次启动时自动创建：

| 字段         | 值                    |
| ------------ | --------------------- |
| **用户名**   | `admin`               |
| **密码**     | `admin`               |
| **邮箱**     | `admin@example.com`   |
| **超管权限** | `is_superuser = true` |

> ⚠️ **生产环境务必修改默认密码！**

---

## 安全说明

- 密码使用 **Argon2id**（Rust 实现），对抗 GPU/ASIC 暴力破解
- JWT 使用 **HS256** 算法，密钥在 `config.toml` 的 `[security]` 节配置
- JWT 有效期 3 小时，过期后需重新登录
- 支持用户软禁用（`is_active = false`）
- 接口级鉴权控制：每个端点可通过 TOML 的 `auth_required` 独立配置

---

## 依赖

| 工具包               | 用途                                 |
| -------------------- | ------------------------------------ |
| `chongming-database` | 异步 SQLite 数据库操作               |
| `chongming-jwt`      | Rust JWT 编码/验证                   |
| `chongming-password` | Rust Argon2id 密码哈希               |
| `chongming-config`   | 全局配置加载                         |
| `chongming-worker`   | `@rpc_method` 装饰器 + Worker 运行时 |