# API 文档（RESTful v1）

统一前缀 `/api/v1`；会话基于 cookie（HttpOnly/Secure/SameSite，`withCredentials`）。
成功响应 `{"data": ...}`；失败响应 `{"error": "..."}`，HTTP 状态码语义化
（400 参数/401 未登录/403 无权限/404 不存在/409 冲突/429 限速/500 内部）。

权限：`-` 公开，`admin` 管理员会话，`user` 外部用户会话。

## 认证 /auth

| 方法 | 路径 | 说明 | 权限 |
|---|---|---|---|
| GET | `/auth/captcha` | 图形验证码 `{captcha_id, image}`（base64 PNG data URI） | - |
| POST | `/auth/otp/send` | 外部用户：用户名+图形验证码 → 发 OTP 邮件（60s 冷却）。body: `{username, captcha_id, captcha_code}` | - |
| POST | `/auth/otp/login` | `{username, code}` → 建 cookie 会话 | - |
| POST | `/auth/admin/login` | `{username, password}` → 建 cookie 会话 | - |
| POST | `/auth/admin/forgot` | `{username}` → 发密码重置邮件（不存在也返回成功，防枚举） | - |
| POST | `/auth/admin/reset` | `{token, new_password}` → 重置密码 | - |
| POST | `/auth/logout` | 登出（删会话 + 清 cookie） | admin/user |
| GET | `/auth/me` | 当前主体 `{user_type, id, username, email}` | admin/user |

## 用户 /users（admin）

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/users?page=&page_size=&status=&supervisor=` | 列表（分页 `{total, items}`） |
| POST | `/users` | 创建。body: `{username(不含ext_), email, supervisor, purpose, ttl_days(0=默认)}` → `{id, username, status, expire_at}` |
| GET | `/users/:id` | 详情 |
| PATCH | `/users/:id` | 更新（可空字段省略）。body: `{email?, supervisor?, purpose?}` |
| POST | `/users/:id/disable` | 禁用（清空 authorized_keys，SSH 立即失效） |
| POST | `/users/:id/enable` | 启用（按 DB 密钥恢复） |
| POST | `/users/:id/extend` | 延期。body: `{days(0=默认)}` → `{expire_at}`；已过期在回收期内可恢复 |
| DELETE | `/users/:id` | 删除并回收（系统账号+家目录+密钥，保留审计） |
| GET | `/users/:id/keys` | 用户密钥列表 |

## 我的 /me（user）

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/me/keys` | 我的密钥列表 |
| POST | `/me/keys` | 上传公钥 `{name, public_key}`（格式/重复校验 + 同步 authorized_keys） |
| PATCH | `/me/keys/:id` | 重命名 `{name}` |
| DELETE | `/me/keys/:id` | 吊销（立即失效） |
| GET | `/me/audit?page=&page_size=` | 我的审计痕迹（本人为操作者或对象） |

## 申请审批 /approvals

| 方法 | 路径 | 说明 | 权限 |
|---|---|---|---|
| POST | `/approvals` | 提交申请 `{username, email, supervisor, purpose}`（不含 ext_） | - |
| GET | `/approvals?status=` | 列表（pending/approved/rejected） | admin |
| POST | `/approvals/:id/review` | 审批 `{approve: bool, reason}`（拒绝必填理由） | admin |

## 审计 /audit（admin）

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/audit?page=&page_size=&actor=&action=&resource_type=&resource_id=&since=&until=` | 查询（since/until 为 RFC3339） |
| GET | `/audit/export?since=&until=` | CSV 导出（UTF-8 BOM，`Content-Disposition` 下载） |

## 系统设置 /settings（admin）

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/settings` | 全部设置项 `{items: [{key, value, overridden}]}`（config 默认 + settings 覆盖） |
| PUT | `/settings` | 更新 `{key, value}`（白名单 key：`policy.default_ttl` / `policy.recycle_period` / `policy.audit_retention`，值为时长） |

## 仪表盘 /admin（admin）

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/admin/stats` | `{total, active, disabled, expired, expiring_soon[], pending_approvals}`（近 30 天待过期） |

## 其他

| 方法 | 路径 | 说明 | 权限 |
|---|---|---|---|
| GET | `/healthz` | 健康检查 `{status, version, uptime, go, timestamp}` | - |

## 审计动作一览

`auth.admin_login`、`auth.otp_send`、`auth.otp_login`、`auth.logout`、
`user.create/update/disable/enable/extend/delete`、`key.create/rename/revoke`、
`approval.submit/review`、`lifecycle.expire`（到期锁定）、`lifecycle.recycle`（回收删除）。
`detail` 为 JSON 字符串；`result` ∈ `success|failed`。