{ "openapi": "3.1.0", "info": { "title": "auth", "description": "认证与账号服务：工作量证明、口令与验证码登录、二次验证、注册、口令重置与 SSH 公钥。", "license": { "name": "MIT", "identifier": "MIT" }, "version": "1.0.0" }, "paths": { "/api/v1/auth/challenge": { "post": { "tags": [ "auth" ], "summary": "签发工作量证明挑战", "description": "把挑战写进当前会话并返回。客户端需要为 `context` 找出一枚满足 `difficulty`（前导零比特数）的 nonce；`pow.v1` 算法与前端求解器一致。", "operationId": "auth_challenge", "responses": { "200": { "description": "挑战已签发并写入会话", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_ChallengeResponse" }, "example": { "code": 200, "data": { "context": "3xJk9Qp2mV7sLbT1rZa8nHc4wDf6YgU0", "difficulty": 16, "expires_at": 1767139500, "issued_at": 1767139200 }, "message": "success" } } } }, "500": { "description": "`internal`（挑战无法写入会话）/ `cache` / `session` / `serialization`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "internal", "message": "internal server error" } } } } } } }, "/api/v1/auth/login": { "post": { "tags": [ "auth" ], "summary": "口令登录", "description": "用口令登录。`identity` 可以是用户名、邮箱（大小写不敏感）或用户编号，`password_hash` 是客户端先算好的口令摘要，工作量证明的载荷必须是 `identity`。账号启用了多因子时返回 `mfa_required: true` 与 `challenge`，此时会话尚未绑定，需再调 `/api/v1/auth/login/verify`。", "operationId": "auth_login", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserLoginRequest" } } }, "required": true }, "responses": { "200": { "description": "登录成功；`mfa_required` 为真时还需二次验证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_UserLoginResponse" }, "example": { "code": 200, "data": { "challenge": null, "displayname": "Ada", "mfa_required": false, "user_id": 1024, "username": "ada" }, "message": "success" } } } }, "400": { "description": "工作量证明过期、载荷不匹配或请求不合法（`expired`、`invalid_proof`、`invalid_payload`、`malformed_request`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "expired", "message": "challenge expired" } } } }, "401": { "description": "身份或口令不正确（`invalid_credentials`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "invalid_credentials", "message": "invalid credentials" } } } }, "403": { "description": "账号被禁止登录，原因见 `message`（`login_forbidden`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "login_forbidden", "message": "account is banned" } } } }, "429": { "description": "失败次数超出配额（`rate_limited`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "rate_limited", "message": "too many attempts" } } } }, "500": { "description": "服务端故障（`internal`、`database`、`cache`、`session`、`serialization`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "internal", "message": "internal server error" } } } } } } }, "/api/v1/auth/login/code": { "post": { "tags": [ "auth" ], "summary": "发送邮箱登录验证码", "description": "向账号邮箱发送 6 位登录验证码，`expires_in_secs` 为有效期。工作量证明的载荷必须是 `email`。同一账号的发码间隔受 `email_code_rate_limit_secs` 限制。", "operationId": "auth_login_code", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "验证码已发送", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_LoginCodeResponse" }, "example": { "code": 200, "data": { "expires_in_secs": 600 }, "message": "success" } } } }, "400": { "description": "邮箱格式不合法或工作量证明过期、载荷不匹配（`invalid_email`、`expired`、`invalid_proof`、`invalid_payload`、`malformed_request`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "invalid_email", "message": "invalid email address" } } } }, "401": { "description": "邮箱未注册或账号不可用（`invalid_credentials`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "invalid_credentials", "message": "invalid credentials" } } } }, "403": { "description": "账号被禁止登录，原因见 `message`（`login_forbidden`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "login_forbidden", "message": "account is banned" } } } }, "429": { "description": "发码过于频繁（`rate_limited`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "rate_limited", "message": "too many requests" } } } }, "500": { "description": "服务端故障，含邮件发送失败（`internal`、`database`、`cache`、`session`、`email`、`serialization`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "internal", "message": "internal server error" } } } } } } }, "/api/v1/auth/login/code/verify": { "post": { "tags": [ "auth" ], "summary": "邮箱验证码换会话", "description": "用邮箱登录验证码换会话。工作量证明的载荷必须是 `email`。验证码一旦核对通过即作废，连续输错 `max_verify_attempts` 次后需重新申请。账号启用了多因子时返回 `mfa_required: true` 与 `challenge`。", "operationId": "auth_login_code_verify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginCodeVerifyRequest" } } }, "required": true }, "responses": { "200": { "description": "登录成功；`mfa_required` 为真时还需二次验证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_UserLoginResponse" }, "example": { "code": 200, "data": { "challenge": null, "displayname": "Ada", "mfa_required": false, "user_id": 1024, "username": "ada" }, "message": "success" } } } }, "400": { "description": "验证码不正确或已过期，或邮箱格式、工作量证明不合法（`invalid_email_code`、`invalid_email`、`expired`、`invalid_proof`、`invalid_payload`、`malformed_request`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "invalid_email_code", "message": "invalid email code" } } } }, "401": { "description": "邮箱未注册或账号不可用（`invalid_credentials`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "invalid_credentials", "message": "invalid credentials" } } } }, "403": { "description": "账号被禁止登录，原因见 `message`（`login_forbidden`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "login_forbidden", "message": "account is banned" } } } }, "429": { "description": "验证码尝试次数超限或请求过频（`email_code_attempts_exceeded`、`rate_limited`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "email_code_attempts_exceeded", "message": "too many attempts" } } } }, "500": { "description": "服务端故障（`internal`、`database`、`cache`、`session`、`serialization`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "internal", "message": "internal server error" } } } } } } }, "/api/v1/auth/login/verify": { "post": { "tags": [ "auth" ], "summary": "二次验证换会话", "description": "用 6 位 TOTP 动态码或一枚未使用的恢复码完成二次验证并绑定会话。`challenge` 必须与 `/api/v1/auth/login` 或 `/api/v1/auth/login/code/verify` 返回的一致，挑战有效期 300 秒，同一动态码时间步不能重复使用，恢复码用掉即作废。", "operationId": "auth_login_verify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginVerifyRequest" } } }, "required": true }, "responses": { "200": { "description": "登录成功，会话已绑定", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_UserLoginResponse" }, "example": { "code": 200, "data": { "challenge": null, "displayname": "Ada", "mfa_required": false, "user_id": 1024, "username": "ada" }, "message": "success" } } } }, "400": { "description": "挑战过期或对不上、动态码错误、动态码时间步已用过、恢复码无效（`expired`、`malformed_request`、`totp_code_invalid`、`totp_step_reused`、`recovery_code_invalid`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "totp_code_invalid", "message": "invalid totp code" } } } }, "401": { "description": "会话里没有待验证挑战、账号不可用或多因子记录已被撤销（`unauthenticated`、`invalid_credentials`、`mfa_required`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "mfa_required", "message": "multi-factor authentication required" } } } }, "403": { "description": "账号被禁止登录，原因见 `message`（`login_forbidden`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "login_forbidden", "message": "account is banned" } } } }, "429": { "description": "尝试次数超限或恢复码已用尽（`rate_limited`、`recovery_codes_exhausted`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "rate_limited", "message": "too many attempts" } } } }, "500": { "description": "服务端故障（`internal`、`database`、`cache`、`session`、`serialization`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "internal", "message": "internal server error" } } } } } } }, "/api/v1/auth/me": { "get": { "tags": [ "auth" ], "summary": "当前登录用户", "description": "通过会话 Cookie 返回用户自述信息。结果在服务端缓存 300 秒，每第 5 次访问回源刷新；登出与改密会主动失效该缓存。", "operationId": "auth_me", "responses": { "200": { "description": "当前登录用户", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_MeResponse" }, "example": { "code": 200, "data": { "avatar_url": "https://cdn.example.com/avatar/ada.png", "created_at": "2025-11-20T02:15:00Z", "displayname": "Ada", "email": "ada@example.com", "email_verified_at": "2026-01-05T08:30:00Z", "is_admin": false, "user_id": 1024, "username": "ada", "version": 3 }, "message": "success" } } } }, "401": { "description": "会话未绑定用户，或账号已被删除（`unauthenticated`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "unauthenticated", "message": "authentication required" } } } }, "500": { "description": "服务端故障（`internal`、`database`、`cache`、`session`、`serialization`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "internal", "message": "internal server error" } } } } } } }, "/api/v1/auth/password/reset": { "post": { "tags": [ "auth" ], "summary": "申请密码重置", "description": "校验工作量证明（payload = 邮箱的 UTF-8 字节）后，作废该用户其余未消费的重置令牌，签发新令牌（长度 `reset_token_bytes`，有效期 `reset_token_ttl_secs`），库内只存 `sha256_hex(token)` 且 `hash_key_id = \"sha256-v1\"`，同时把摘要写入缓存键 `auth:code:reset:{email}`，发信限流键 `auth:rate:reset:{email}`。", "operationId": "auth_password_reset_request", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordResetRequest" } } }, "required": true }, "responses": { "200": { "description": "申请已受理；是否真的发信不对外披露", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_PasswordResetResponse" }, "example": { "code": 200, "data": { "expires_in_secs": 1800 }, "message": "success" } } } }, "400": { "description": "`invalid_email` / `expired` / `invalid_payload`（payload 与邮箱不一致）/ `invalid_proof`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "invalid_email", "message": "email is invalid" } } } }, "429": { "description": "`rate_limited`（同一邮箱申请过于频繁）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "rate_limited", "message": "too many requests, retry after 60s" } } } }, "500": { "description": "`email`（投递失败）/ `database` / `cache` / `session` / `serialization` / `internal`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "internal", "message": "internal server error" } } } } } } }, "/api/v1/auth/password/reset/confirm": { "post": { "tags": [ "auth" ], "summary": "确认密码重置", "description": "校验工作量证明（payload = `token` 的 UTF-8 字节）与缓存键 `auth:code:reset:{email}`（尝试上限 `max_verify_attempts`，错误计入 `invalid_email_code`）后，条件消费数据库令牌行（`consumed_at` 单次占用），Argon2 重哈希新口令，更新 `password_hash`/`password_updated_at`/`password_must_change`/`security_version + 1`，作废其余令牌并记 `PasswordChange` 审计事件。", "operationId": "auth_password_reset", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordResetConfirmRequest" } } }, "required": true }, "responses": { "200": { "description": "口令已改写；旧口令与其余重置令牌失效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_PasswordResetConfirmResponse" }, "example": { "code": 200, "data": { "user_id": 1234567 }, "message": "success" } } } }, "400": { "description": "`invalid_reset_token`（令牌不存在/已消费/已作废/已过期/账号不可用或凭据代数不匹配）/ `invalid_email_code`（缓存内摘要不匹配或已过期）/ `invalid_password` / `expired` / `invalid_payload` / `invalid_proof`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "invalid_reset_token", "message": "password reset token is invalid" } } } }, "429": { "description": "`email_code_attempts_exceeded`（令牌尝试次数用尽）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "email_code_attempts_exceeded", "message": "too many invalid email verification attempts" } } } }, "500": { "description": "`password_hash`（口令重哈希失败）/ `database` / `cache` / `session` / `serialization` / `internal`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "internal", "message": "internal server error" } } } } } } }, "/api/v1/auth/register": { "post": { "tags": [ "auth" ], "summary": "提交注册", "description": "校验工作量证明（payload = 用户名的 UTF-8 字节）、用户名/展示名/出生日期/邮箱、邮箱验证码（键 `auth:code:register:{email}`，尝试上限 `max_verify_attempts`）后，Argon2 重哈希口令并创建用户与初始档案。成功后写会话（user_id、security_version、renew）并记审计事件。", "operationId": "auth_register", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRegisterRequest" } } }, "required": true }, "responses": { "200": { "description": "注册成功且已登录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_UserRegisterResponse" }, "example": { "code": 200, "data": { "displayname": "Alice", "user_id": 1234567, "username": "alice" }, "message": "success" } } } }, "400": { "description": "`invalid_username` / `invalid_displayname` / `invalid_email` / `invalid_birth_date` / `invalid_password` / `invalid_email_code`（验证码错误或已过期）/ `expired` / `invalid_payload` / `invalid_proof`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "invalid_email_code", "message": "email verification code is invalid" } } } }, "403": { "description": "`under_minimum_age`（未满最小年龄）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "under_minimum_age", "message": "you must be at least 13 years old" } } } }, "409": { "description": "`username_taken` / `email_taken`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "username_taken", "message": "username is already taken" } } } }, "429": { "description": "`email_code_attempts_exceeded`（验证码尝试次数用尽）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "email_code_attempts_exceeded", "message": "too many invalid email verification attempts" } } } }, "500": { "description": "`password_hash`（口令重哈希失败）/ `database` / `cache` / `session` / `serialization` / `internal`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "internal", "message": "internal server error" } } } } } } }, "/api/v1/auth/register/code": { "post": { "tags": [ "auth" ], "summary": "发送注册验证码", "description": "校验工作量证明（payload = 邮箱的 UTF-8 字节）与邮箱格式后，把 6 位验证码写入缓存并寄出。缓存键 `auth:code:register:{email}`，有效期由 `verify_code_ttl_secs` 决定，发码限流键 `auth:rate:register:{email}`。", "operationId": "auth_register_code", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "验证码已写入缓存并寄出", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_RegisterCodeResponse" }, "example": { "code": 200, "data": { "expires_in_secs": 600 }, "message": "success" } } } }, "400": { "description": "`invalid_email`（邮箱格式）/ `expired`（挑战过期）/ `invalid_payload`（payload 与邮箱不一致）/ `invalid_proof`（未满足难度）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "invalid_email", "message": "email is invalid" } } } }, "409": { "description": "`email_taken`（邮箱已注册）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "email_taken", "message": "email is already taken" } } } }, "429": { "description": "`rate_limited`（同一邮箱发码过于频繁）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "rate_limited", "message": "too many requests, retry after 60s" } } } }, "500": { "description": "`email`（投递失败）/ `cache` / `session` / `serialization` / `internal`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "internal", "message": "internal server error" } } } } } } }, "/api/v1/auth/session/logout": { "post": { "tags": [ "auth" ], "summary": "登出", "description": "销毁当前会话，并清掉该用户的 `/api/v1/auth/me` 缓存。匿名调用同样成功，此时 `user_id` 为 `null`。", "operationId": "auth_logout", "responses": { "200": { "description": "会话已销毁", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_LogoutResponse" }, "example": { "code": 200, "data": { "user_id": 1024 }, "message": "success" } } } }, "500": { "description": "服务端故障（`internal`、`database`、`cache`、`session`、`serialization`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "internal", "message": "internal server error" } } } } } } }, "/api/v1/auth/ssh-keys": { "get": { "tags": [ "auth" ], "summary": "列示 SSH 公钥", "description": "按创建时间倒序返回当前账号的公钥，含已吊销与已过期的记录。分页参数由 `page` / `page_size` 控制。查询串不是合法分页参数时由 actix-web 直接返回 400。", "operationId": "auth_ssh_key_list", "parameters": [ { "name": "page", "in": "query", "description": "页码，从 1 开始；默认 1", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "每页条数，默认 20，最多 100", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "公钥列表", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_Vec_SshKeySummary" }, "example": { "code": 200, "data": [ { "algorithm": "ed25519", "created_at": "2026-01-02T03:04:05Z", "description": "笔记本", "expires_at": null, "fingerprint": "SHA256:9pQ2mLk1v3sT6yZx8cV0bN4mR7wQ2eH5jK9aD1sF3gU", "id": "018f2b1c-4d5e-7f80-9a1b-2c3d4e5f6072", "last_used_at": null, "name": "thinkpad", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL9kQ2mXv7Tb1sYz8cV0bN4mR7wQ2eH5jK9aD1sF3gU thinkpad", "revoked_at": null } ], "message": "success" } } } }, "401": { "description": "会话未绑定账号（`unauthenticated`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "unauthenticated", "message": "authentication required" } } } }, "500": { "description": "服务端故障（`internal`、`database`、`session`、`serialization`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "internal", "message": "internal server error" } } } } } }, "post": { "tags": [ "auth" ], "summary": "添加 SSH 公钥", "description": "名称 1~64 字符、备注最长 255 字符，公钥 32~8192 字节且必须是受支持的单行 OpenSSH 公钥，`expires_at` 必须晚于当前时间。重复公钥（指纹唯一）返回 `ssh_key_taken`。添加成功记 `PublicKeyAdded` 审计事件。", "operationId": "auth_ssh_key_add", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshKeyAddRequest" } } }, "required": true }, "responses": { "200": { "description": "公钥已登记", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_SshKeySummary" }, "example": { "code": 200, "data": { "algorithm": "ed25519", "created_at": "2026-01-02T03:04:05Z", "description": "笔记本", "expires_at": null, "fingerprint": "SHA256:9pQ2mLk1v3sT6yZx8cV0bN4mR7wQ2eH5jK9aD1sF3gU", "id": "018f2b1c-4d5e-7f80-9a1b-2c3d4e5f6072", "last_used_at": null, "name": "thinkpad", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL9kQ2mXv7Tb1sYz8cV0bN4mR7wQ2eH5jK9aD1sF3gU thinkpad", "revoked_at": null }, "message": "success" } } } }, "400": { "description": "名称、备注、公钥或过期时间不合法（`ssh_key_name_invalid`、`malformed_request`、`ssh_key_invalid`、`invalid_expiry`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "ssh_key_invalid", "message": "public key is invalid" } } } }, "401": { "description": "会话未绑定账号，或账号已删除 / 不允许使用（`unauthenticated`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "unauthenticated", "message": "authentication required" } } } }, "409": { "description": "同一把公钥已经登记过（`ssh_key_taken`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "ssh_key_taken", "message": "public key is already registered" } } } }, "500": { "description": "服务端故障（`internal`、`database`、`session`、`serialization`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "internal", "message": "internal server error" } } } } } } }, "/api/v1/auth/ssh-keys/{key_id}": { "delete": { "tags": [ "auth" ], "summary": "吊销 SSH 公钥", "description": "把公钥标记为已吊销，记录保留不硬删；重复调用幂等。公钥不存在或不属于当前账号返回 `ssh_key_not_found`。吊销成功记 `PublicKeyRemoved` 审计事件，并递增 `security_version` 让该账号既有的访问令牌一并失效。`key_id` 不是合法 UUID 时由 actix-web 的路径提取器直接返回 400。", "operationId": "auth_ssh_key_delete", "parameters": [ { "name": "key_id", "in": "path", "description": "公钥编号", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "已吊销；重复调用同样返回成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": 200, "data": null, "message": "success" } } } }, "401": { "description": "会话未绑定账号（`unauthenticated`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "unauthenticated", "message": "authentication required" } } } }, "404": { "description": "公钥不存在或不属于当前账号（`ssh_key_not_found`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "ssh_key_not_found", "message": "ssh key does not exist" } } } }, "500": { "description": "服务端故障（`internal`、`database`、`session`、`serialization`）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_NoData" }, "example": { "code": "internal", "message": "internal server error" } } } } } } } }, "components": { "schemas": { "ChallengeResponse": { "type": "object", "required": [ "context", "difficulty", "issued_at", "expires_at" ], "properties": { "context": { "type": "string" }, "difficulty": { "type": "integer", "format": "int32", "minimum": 0 }, "expires_at": { "type": "integer", "format": "int64", "minimum": 0 }, "issued_at": { "type": "integer", "format": "int64", "minimum": 0 } } }, "Envelope_ChallengeResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "data": { "type": "object", "required": [ "context", "difficulty", "issued_at", "expires_at" ], "properties": { "context": { "type": "string" }, "difficulty": { "type": "integer", "format": "int32", "minimum": 0 }, "expires_at": { "type": "integer", "format": "int64", "minimum": 0 }, "issued_at": { "type": "integer", "format": "int64", "minimum": 0 } } }, "error": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } }, "Envelope_LoginCodeResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "data": { "type": "object", "required": [ "expires_in_secs" ], "properties": { "expires_in_secs": { "type": "integer", "format": "int64", "minimum": 0 } } }, "error": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } }, "Envelope_LogoutResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "data": { "type": "object", "properties": { "user_id": { "type": [ "integer", "null" ], "format": "int64" } } }, "error": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } }, "Envelope_MeResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "data": { "type": "object", "required": [ "user_id", "username", "email", "is_admin", "created_at", "version" ], "properties": { "avatar_url": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "displayname": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "email_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_admin": { "type": "boolean" }, "user_id": { "type": "integer", "format": "int64" }, "username": { "type": "string" }, "version": { "type": "integer", "format": "int32" } } }, "error": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } }, "Envelope_NoData": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "data": { "default": null }, "error": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } }, "Envelope_PasswordResetConfirmResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "data": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "integer", "format": "int64" } } }, "error": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } }, "Envelope_PasswordResetResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "data": { "type": "object", "required": [ "expires_in_secs" ], "properties": { "expires_in_secs": { "type": "integer", "format": "int64", "minimum": 0 } } }, "error": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } }, "Envelope_RegisterCodeResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "data": { "type": "object", "required": [ "expires_in_secs" ], "properties": { "expires_in_secs": { "type": "integer", "format": "int64", "minimum": 0 } } }, "error": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } }, "Envelope_SshKeySummary": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "data": { "type": "object", "required": [ "id", "name", "algorithm", "fingerprint", "public_key", "created_at" ], "properties": { "algorithm": { "$ref": "#/components/schemas/SshKeyAlgorithm" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "fingerprint": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "public_key": { "type": "string" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "error": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } }, "Envelope_UserLoginResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "data": { "type": "object", "required": [ "user_id", "username", "mfa_required" ], "properties": { "challenge": { "type": [ "string", "null" ] }, "displayname": { "type": [ "string", "null" ] }, "mfa_required": { "type": "boolean" }, "user_id": { "type": "integer", "format": "int64" }, "username": { "type": "string" } } }, "error": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } }, "Envelope_UserRegisterResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "data": { "type": "object", "required": [ "user_id", "username" ], "properties": { "displayname": { "type": [ "string", "null" ] }, "user_id": { "type": "integer", "format": "int64" }, "username": { "type": "string" } } }, "error": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } }, "Envelope_Vec_SshKeySummary": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "algorithm", "fingerprint", "public_key", "created_at" ], "properties": { "algorithm": { "$ref": "#/components/schemas/SshKeyAlgorithm" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "fingerprint": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "public_key": { "type": "string" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "error": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } }, "LoginCodeRequest": { "type": "object", "required": [ "email", "pow_payload" ], "properties": { "email": { "type": "string" }, "pow_payload": { "$ref": "#/components/schemas/PowProofRequest" } } }, "LoginCodeResponse": { "type": "object", "required": [ "expires_in_secs" ], "properties": { "expires_in_secs": { "type": "integer", "format": "int64", "minimum": 0 } } }, "LoginCodeVerifyRequest": { "type": "object", "required": [ "email", "email_code", "pow_payload" ], "properties": { "email": { "type": "string" }, "email_code": { "type": "string" }, "pow_payload": { "$ref": "#/components/schemas/PowProofRequest" } } }, "LoginVerifyRequest": { "type": "object", "required": [ "challenge", "code" ], "properties": { "challenge": { "type": "string" }, "code": { "type": "string" } } }, "LogoutResponse": { "type": "object", "properties": { "user_id": { "type": [ "integer", "null" ], "format": "int64" } } }, "MeResponse": { "type": "object", "required": [ "user_id", "username", "email", "is_admin", "created_at", "version" ], "properties": { "avatar_url": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "displayname": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "email_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_admin": { "type": "boolean" }, "user_id": { "type": "integer", "format": "int64" }, "username": { "type": "string" }, "version": { "type": "integer", "format": "int32" } } }, "NoData": { "default": null }, "PasswordResetConfirmRequest": { "type": "object", "required": [ "token", "password_hash", "pow_payload" ], "properties": { "password_hash": { "type": "string" }, "pow_payload": { "$ref": "#/components/schemas/PowProofRequest" }, "token": { "type": "string" } } }, "PasswordResetConfirmResponse": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "integer", "format": "int64" } } }, "PasswordResetRequest": { "type": "object", "required": [ "email", "pow_payload" ], "properties": { "email": { "type": "string" }, "pow_payload": { "$ref": "#/components/schemas/PowProofRequest" } } }, "PasswordResetResponse": { "type": "object", "required": [ "expires_in_secs" ], "properties": { "expires_in_secs": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PowProofRequest": { "type": "object", "required": [ "nonce", "payload" ], "properties": { "nonce": { "type": "integer", "format": "int64", "minimum": 0 }, "payload": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } }, "RegisterCodeRequest": { "type": "object", "required": [ "email", "pow_payload" ], "properties": { "email": { "type": "string" }, "pow_payload": { "$ref": "#/components/schemas/PowProofRequest" } } }, "RegisterCodeResponse": { "type": "object", "required": [ "expires_in_secs" ], "properties": { "expires_in_secs": { "type": "integer", "format": "int64", "minimum": 0 } } }, "SshKeyAddRequest": { "type": "object", "required": [ "name", "public_key" ], "properties": { "description": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "public_key": { "type": "string" } } }, "SshKeyAlgorithm": { "type": "string", "enum": [ "rsa", "ed25519", "ecdsa" ] }, "SshKeySummary": { "type": "object", "required": [ "id", "name", "algorithm", "fingerprint", "public_key", "created_at" ], "properties": { "algorithm": { "$ref": "#/components/schemas/SshKeyAlgorithm" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "fingerprint": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "public_key": { "type": "string" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "UserLoginRequest": { "type": "object", "required": [ "identity", "password_hash", "pow_payload" ], "properties": { "identity": { "type": "string" }, "password_hash": { "type": "string" }, "pow_payload": { "$ref": "#/components/schemas/PowProofRequest" } } }, "UserLoginResponse": { "type": "object", "required": [ "user_id", "username", "mfa_required" ], "properties": { "challenge": { "type": [ "string", "null" ] }, "displayname": { "type": [ "string", "null" ] }, "mfa_required": { "type": "boolean" }, "user_id": { "type": "integer", "format": "int64" }, "username": { "type": "string" } } }, "UserRegisterRequest": { "type": "object", "required": [ "username", "birth_date", "email", "password_hash", "email_code", "pow_payload" ], "properties": { "birth_date": { "type": "string" }, "displayname": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "email_code": { "type": "string" }, "password_hash": { "type": "string" }, "pow_payload": { "$ref": "#/components/schemas/PowProofRequest" }, "username": { "type": "string" } } }, "UserRegisterResponse": { "type": "object", "required": [ "user_id", "username" ], "properties": { "displayname": { "type": [ "string", "null" ] }, "user_id": { "type": "integer", "format": "int64" }, "username": { "type": "string" } } } } } }