# 认证与授权

## API Key 认证

所有 OpenAPI 请求都必须携带 `X-API-Key`。

```http
X-API-Key: your-api-key
```

### 请求示例

```bash
curl -H "X-API-Key: your-api-key" https://hdhive.com/api/open/ping
```

## 用户身份来源

业务接口需要能确定调用用户。系统按以下顺序识别用户：

1. `Authorization: Bearer <OpenAPI 用户 Access Token>`：第三方应用授权后获得，必须属于当前应用。
2. `Authorization: Bearer <站内用户 JWT>`：站内登录态 Token。
3. API Key 绑定用户：个人 API Key 或管理员绑定用户的 OpenAPI 应用可回退到绑定用户。

非 `meta` 类接口如果无法确定用户，会返回 `OPENAPI_USER_REQUIRED`。

## 第三方应用授权流程

第三方应用应使用管理员创建的 OpenAPI 应用完成授权：

1. 管理员创建 OpenAPI 应用，配置应用名称、绑定用户、scope、IP 策略、回调地址等。
2. 第三方应用引导用户进入前端授权页 `/openapi/authorize`，并传入 `client_id`、`redirect_uri`、`scope`、`state`。
3. 用户确认授权后，HDHive 前端调用 `POST /api/public/openapi/oauth/authorize`，后端以 JSON 返回一次性授权码。
4. HDHive 前端把用户重定向到第三方 `redirect_uri`，并在 query 中追加 `code` 和原始 `state`。
5. 第三方应用服务端用授权码调用 `POST /api/public/openapi/oauth/token` 换取用户 Access Token 和 Refresh Token。
6. 调用业务接口时同时传入应用 Secret 和用户 Access Token。

```http
X-API-Key: app-secret
Authorization: Bearer user-access-token
```

### 用户授权页

第三方应用应把用户跳转到站点前端授权页，而不是直接展示后端 API：

```text
https://hdhive.com/openapi/authorize?client_id=app_xxx&redirect_uri=https%3A%2F%2Fclient.example.com%2Fcallback&scope=query%20unlock&state=opaque-state
```

| 参数 | 必填 | 说明 |
|---|---|---|
| `client_id` | 是 | OpenAPI 应用公开 Client ID，不是 Secret |
| `redirect_uri` | 是 | 回调地址，必须在应用配置的回调地址列表内 |
| `scope` | 否 | 请求的用户授权 scope，空格分隔；为空时按应用允许范围处理 |
| `state` | 否 | 第三方应用自定义状态，建议用于 CSRF 防护和回跳上下文 |

### 授权码换 Token

后端换取 Token 时必须使用应用 Secret：

```bash
curl -X POST https://hdhive.com/api/public/openapi/oauth/token \\
  -H "X-API-Key: app-secret" \\
  -H "Content-Type: application/json" \\
  -d '{
    "grant_type": "authorization_code",
    "code": "authorization-code",
    "redirect_uri": "https://client.example.com/callback"
  }'
```

返回的 `access_token` 用于业务 OpenAPI 调用，`refresh_token` 用于刷新用户授权 Token。

`redirect_uri` 在换取 Token 时不会触发跳转，它是授权码安全校验字段，必须与创建授权码时传入的 `redirect_uri` 完全一致。后端会用它确认授权码确实来自同一次授权请求，避免授权码被截获后在其他回调上下文中兑换。

### 授权码回调形式

用户确认授权后，第三方应用收到的是浏览器跳转请求：

```text
https://client.example.com/callback?code=authorization-code&state=opaque-state
```

`code` 是一次性授权码，第三方应用应该在自己的服务端用应用 Secret 换取 Token，不要在浏览器里暴露应用 Secret。

## Scope

| scope | 说明 | 典型能力 |
|---|---|---|
| `meta` | 元信息接口 | 健康检查、配额、用量查询 |
| `query` | 查询接口 | 资源查询、分享详情、资源链接检查 |
| `write` | 写入接口 | 创建、更新、删除分享 |
| `unlock` | 解锁接口 | 解锁资源并获取链接 |
| `vip` | VIP 接口 | 用户信息、签到、VIP 用量 |

应用必须拥有对应 scope，用户授权 Token 如果限制了 scope，也必须包含对应 scope。

## 认证错误码

| 错误码 | HTTP 状态码 | 说明 |
|---|---|---|
| `MISSING_API_KEY` | 401 | 未提供 `X-API-Key` |
| `INVALID_API_KEY` | 401 | API Key 无效或不存在 |
| `DISABLED_API_KEY` | 401 | API Key 已被禁用 |
| `EXPIRED_API_KEY` | 401 | API Key 已过期 |
| `INVALID_OPENAPI_USER_TOKEN` | 401 | OpenAPI 用户 Token 无效 |
| `OPENAPI_TOKEN_APP_MISMATCH` | 401 | 用户 Token 不属于当前应用 |
| `OPENAPI_USER_REQUIRED` | 403 | 业务接口缺少用户身份 |
| `SCOPE_NOT_ALLOWED` | 403 | 应用未授权该接口组 |
| `USER_SCOPE_NOT_ALLOWED` | 403 | 用户授权 Token scope 不足 |
| `VIP_REQUIRED` | 403 | 当前用户不满足 Premium 要求 |