{ "swagger": "2.0", "info": { "description": "多因素认证服务，提供TOTP、短信验证码、邮件验证、推送通知等多种MFA方式", "title": "MFA Service API", "contact": {}, "version": "1.0.0" }, "basePath": "/api/v1", "paths": { "/admin/mfa/config-audit-logs": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询MFA配置变更的审计日志，支持按操作类型、目标类型、操作者、日期范围筛选。需要管理员权限。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "获取MFA配置审计日志", "parameters": [ { "type": "string", "description": "操作类型过滤", "name": "action", "in": "query" }, { "type": "string", "description": "目标类型过滤", "name": "target_type", "in": "query" }, { "type": "string", "description": "操作者ID过滤", "name": "operator_id", "in": "query" }, { "type": "string", "description": "开始日期（YYYY-MM-DD）", "name": "start_date", "in": "query" }, { "type": "string", "description": "结束日期（YYYY-MM-DD）", "name": "end_date", "in": "query" }, { "type": "integer", "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "description": "每页条数", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "审计日志查询结果", "schema": { "$ref": "#/definitions/dto.MFAConfigAuditLogListResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/mfa/ip-whitelist": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询租户配置的所有IP白名单规则。需要管理员权限。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "列出IP白名单", "responses": { "200": { "description": "IP白名单列表", "schema": { "$ref": "#/definitions/dto.IPWhitelistListResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "post": { "security": [ { "bearerAuth": [] } ], "description": "为租户添加一个IP白名单规则（CIDR格式），用于自适应MFA风险评分的IP信任检查。参考：NIST SP 800-63B §5.2 (Risk-based Authentication)。需要管理员权限。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "创建IP白名单", "parameters": [ { "description": "创建IP白名单请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.CreateIPWhitelistRequest" } } ], "responses": { "201": { "description": "创建成功", "schema": { "$ref": "#/definitions/dto.IPWhitelistDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/mfa/ip-whitelist/{id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据ID查询指定的IP白名单规则。需要管理员权限。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "获取IP白名单", "parameters": [ { "type": "string", "description": "实体ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "IP白名单详情", "schema": { "$ref": "#/definitions/dto.IPWhitelistDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "put": { "security": [ { "bearerAuth": [] } ], "description": "更新指定IP白名单规则的标签、CIDR或启用状态。需要管理员权限。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "更新IP白名单", "parameters": [ { "type": "string", "description": "实体ID", "name": "id", "in": "path", "required": true }, { "description": "更新IP白名单请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UpdateIPWhitelistRequest" } } ], "responses": { "200": { "description": "更新成功", "schema": { "$ref": "#/definitions/dto.IPWhitelistDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "删除指定的IP白名单规则。需要管理员权限。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "删除IP白名单", "parameters": [ { "type": "string", "description": "实体ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "删除成功" }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/mfa/push/challenges": { "get": { "security": [ { "bearerAuth": [] } ], "description": "分页查询推送MFA挑战列表，支持按状态和用户过滤。参考：NIST SP 800-63B §5.1.7、OWASP ASVS V2.8。需要管理员权限。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin", "MFA" ], "summary": "管理端查看推送挑战列表", "parameters": [ { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页条数", "name": "page_size", "in": "query" }, { "type": "string", "description": "状态过滤（pending/approved/denied/expired）", "name": "status", "in": "query" }, { "type": "string", "description": "用户ID过滤", "name": "user_id", "in": "query" } ], "responses": { "200": { "description": "挑战列表", "schema": { "$ref": "#/definitions/dto.AdminPushChallengeListResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/mfa/push/stats": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询指定租户的推送挑战按状态统计（pending/approved/denied/expired）。参考：NIST SP 800-63B §5.1.7、OWASP ASVS V2.8。需要管理员权限。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin", "MFA" ], "summary": "获取Push MFA挑战统计", "responses": { "200": { "description": "统计数据", "schema": { "$ref": "#/definitions/dto.PushStatsDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/mfa/reset/{user_id}": { "delete": { "security": [ { "bearerAuth": [] } ], "description": "管理员强制重置指定用户的所有MFA配置（TOTP设备、MFA配置），用户下次登录需重新设置。需要管理员权限。", "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "管理员重置用户MFA", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "MFA重置成功", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/mfa/risk-policies": { "get": { "security": [ { "bearerAuth": [] } ], "description": "获取租户配置的所有风险等级策略列表。参考：NIST SP 800-63B §5.2 (Risk-based Authentication)。需要管理员权限。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "列出所有风险策略", "responses": { "200": { "description": "风险策略列表", "schema": { "$ref": "#/definitions/dto.RiskPolicyListResponseWrap" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/mfa/risk-policies/evaluate": { "post": { "security": [ { "bearerAuth": [] } ], "description": "传入用户上下文（user_id、IP、设备指纹），返回评估的风险等级和要求的MFA方法。参考：NIST SP 800-63B §5.2 (Risk-based Authentication)。需要管理员权限。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "评估风险策略", "parameters": [ { "description": "评估请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.EvaluateRiskPolicyRequest" } } ], "responses": { "200": { "description": "评估结果", "schema": { "$ref": "#/definitions/dto.EvaluateRiskPolicyDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/mfa/risk-policies/{level}": { "put": { "security": [ { "bearerAuth": [] } ], "description": "更新租户指定风险等级的MFA因子要求。参考：NIST SP 800-63B §5.2 (Risk-based Authentication)。需要管理员权限。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "更新指定等级的风险策略", "parameters": [ { "type": "string", "description": "风险等级（low/medium/high）", "name": "level", "in": "path", "required": true }, { "description": "策略更新请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UpdateRiskPolicyByLevelRequest" } } ], "responses": { "200": { "description": "更新后的策略", "schema": { "$ref": "#/definitions/dto.RiskPolicyItemDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "删除租户指定风险等级的自定义策略，恢复默认值。参考：NIST SP 800-63B §5.2 (Risk-based Authentication)。需要管理员权限。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "删除指定等级的风险策略", "parameters": [ { "type": "string", "description": "风险等级（low/medium/high）", "name": "level", "in": "path", "required": true } ], "responses": { "204": { "description": "删除成功，恢复默认" }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/admin/mfa/risk-policy": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询基于风险评分的自适应MFA策略配置，从数据库读取租户配置的策略。参考：NIST SP 800-63B §5.2 (Risk-based Authentication)。需要管理员权限。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "获取MFA风险策略", "responses": { "200": { "description": "风险策略", "schema": { "$ref": "#/definitions/dto.RiskPolicyDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "put": { "security": [ { "bearerAuth": [] } ], "description": "全量更新租户的低/中/高风险等级的MFA因子要求。参考：NIST SP 800-63B §5.2 (Risk-based Authentication)。需要管理员权限。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "更新MFA风险策略", "parameters": [ { "description": "风险策略更新请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UpdateRiskPolicyRequest" } } ], "responses": { "200": { "description": "更新后的风险策略", "schema": { "$ref": "#/definitions/dto.RiskPolicyDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/internal/mfa/erase": { "post": { "description": "内部API：硬删除指定用户的所有MFA配置、TOTP设备、WebAuthn凭证和受信设备，用于GDPR删除Saga。需要InternalAPIKey认证。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "内部擦除用户MFA数据", "parameters": [ { "description": "内部擦除MFA请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.InternalEraseMFARequest" } } ], "responses": { "200": { "description": "擦除成功", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "缺少内部API认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/internal/mfa/push/challenge/{id}": { "get": { "description": "内部API：根据挑战ID和用户ID查询Push MFA挑战状态，供identity-service在MFA验证流程中调用。需要InternalAPIKey认证和X-Tenant-ID请求头。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Internal", "MFA" ], "summary": "内部获取Push挑战状态", "parameters": [ { "type": "string", "description": "挑战ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "用户ID", "name": "user_id", "in": "query", "required": true }, { "type": "string", "description": "租户ID", "name": "X-Tenant-ID", "in": "header", "required": true } ], "responses": { "200": { "description": "挑战状态", "schema": { "$ref": "#/definitions/dto.PushChallengeStatusDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "缺少内部API认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "挑战未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/internal/mfa/status/{user_id}": { "get": { "description": "内部获取用户MFA状态，无需JWT认证，供其他服务（identity-service）调用。需要X-Tenant-ID请求头。参考：OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "内部获取用户MFA状态", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "MFA状态", "schema": { "$ref": "#/definitions/dto.InternalMFAStatusDetailResponse" } }, "400": { "description": "参数错误或缺少X-Tenant-ID", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "缺少内部API认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/internal/mfa/totp/devices": { "get": { "description": "内部获取用户TOTP设备列表，无需JWT认证，供其他服务（identity-service）调用。需要X-Tenant-ID和InternalAPIKey认证。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "内部获取TOTP设备列表", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "query", "required": true }, { "type": "string", "description": "租户ID", "name": "X-Tenant-ID", "in": "header", "required": true } ], "responses": { "200": { "description": "TOTP设备列表", "schema": { "$ref": "#/definitions/dto.TOTPDeviceListResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "缺少内部API认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/internal/mfa/totp/disable": { "post": { "description": "内部禁用用户的TOTP多因素认证，无需密码验证，供其他服务（identity-service）调用。需要X-Tenant-ID和InternalAPIKey认证。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "内部禁用TOTP", "parameters": [ { "description": "内部禁用TOTP请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.InternalTOTPDisableRequest" } } ], "responses": { "200": { "description": "禁用成功", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "缺少内部API认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/internal/mfa/totp/validate": { "post": { "description": "内部验证用户TOTP码，无需JWT认证，供其他服务（identity-service）在登录时调用。需要InternalAPIKey认证。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "内部验证TOTP码", "parameters": [ { "description": "内部TOTP验证请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.InternalTOTPValidateRequest" } } ], "responses": { "200": { "description": "验证结果", "schema": { "$ref": "#/definitions/dto.ValidDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "缺少内部API认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/backup-codes": { "get": { "security": [ { "bearerAuth": [] } ], "description": "解密并返回当前用户的全部备用恢复码，需step-up认证。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "查看备用码", "responses": { "200": { "description": "备用码列表", "schema": { "$ref": "#/definitions/dto.GetBackupCodesDetailResponse" } }, "400": { "description": "业务错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证或step-up过期", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/backup-codes/count": { "get": { "security": [ { "bearerAuth": [] } ], "description": "返回当前用户备用恢复码的数量和是否为即将用尽的状态。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "查看备用码数量", "responses": { "200": { "description": "备用码数量", "schema": { "$ref": "#/definitions/dto.BackupCodesCountDetailResponse" } }, "400": { "description": "业务错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/backup-codes/generate": { "post": { "security": [ { "bearerAuth": [] } ], "description": "为用户生成10个备用恢复码，用于TOTP不可用时进行身份验证。恢复码仅显示一次，请妥善保存。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "生成备用恢复码", "parameters": [ { "description": "生成备用码请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.GenerateBackupCodesRequest" } } ], "responses": { "200": { "description": "备用码生成成功", "schema": { "$ref": "#/definitions/dto.BackupCodesDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/backup-codes/verify": { "post": { "security": [ { "bearerAuth": [] } ], "description": "验证备用恢复码，返回验证结果和剩余备用码数量，用于前端独立处理备用码登录流程。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "独立备用码验证", "parameters": [ { "description": "备用码验证请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.BackupCodeVerifyRequest" } } ], "responses": { "200": { "description": "验证结果", "schema": { "$ref": "#/definitions/dto.BackupCodeVerifyDetailResponse" } }, "400": { "description": "参数错误或备用码无效", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/challenge": { "post": { "security": [ { "bearerAuth": [] } ], "description": "为指定用户创建一次性的MFA挑战码，支持短信、邮件、TOTP、推送等多种验证方式，用于登录或敏感操作前的二次认证。参考：NIST SP 800-63B §5.1.7 (Verifier Impersonation Resistance)、OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "创建通用MFA挑战", "parameters": [ { "description": "MFA挑战请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.MFAChallengeRequest" } } ], "responses": { "201": { "description": "挑战码创建成功", "schema": { "$ref": "#/definitions/dto.MFAChallengeDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "挑战未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "429": { "description": "请求过于频繁", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/credentials/{id}/primary": { "post": { "security": [ { "bearerAuth": [] } ], "description": "将指定的MFA凭证设为该用户的主认证方式，同时取消其他凭证的主认证状态。参考：OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "设置主认证方式", "parameters": [ { "type": "string", "description": "凭证ID", "name": "id", "in": "path", "required": true }, { "description": "设置主认证方式请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.SetPrimaryCredentialRequest" } } ], "responses": { "200": { "description": "设置成功", "schema": { "$ref": "#/definitions/dto.SetPrimaryCredentialDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "凭证未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/devices/sync": { "get": { "security": [ { "bearerAuth": [] } ], "description": "列出用户所有的设备同步记录，返回解密后的TOTP设备数据。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "列出同步设备", "responses": { "200": { "description": "设备同步列表", "schema": { "$ref": "#/definitions/dto.DeviceSyncListResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "post": { "security": [ { "bearerAuth": [] } ], "description": "上传设备TOTP配置数据，加密存储并返回同步令牌。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "同步设备数据", "parameters": [ { "description": "设备同步数据", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.DeviceSyncRequest" } } ], "responses": { "201": { "description": "设备同步成功", "schema": { "$ref": "#/definitions/dto.DeviceSyncDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "409": { "description": "设备数量已达上限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/email/disable": { "post": { "security": [ { "bearerAuth": [] } ], "description": "验证邮箱验证码后禁用Email MFA认证。参考：OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "禁用邮箱 MFA", "parameters": [ { "description": "禁用邮箱MFA请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.EmailDisableRequest" } } ], "responses": { "200": { "description": "禁用成功", "schema": { "$ref": "#/definitions/dto.DisabledDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "429": { "description": "请求过于频繁", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/email/enroll": { "put": { "security": [ { "bearerAuth": [] } ], "description": "为用户注册邮箱MFA认证方式。参考：OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "Email MFA注册", "parameters": [ { "description": "邮箱MFA注册请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.EmailEnrollRequest" } } ], "responses": { "201": { "description": "注册成功", "schema": { "$ref": "#/definitions/dto.EmailEnrollDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/email/send": { "post": { "security": [ { "bearerAuth": [] } ], "description": "向用户邮箱发送验证码，用于邮箱MFA认证。生产环境不返回验证码明文。参考：OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "发送邮箱验证码", "parameters": [ { "description": "发送邮箱验证码请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.EmailSendRequest" } } ], "responses": { "200": { "description": "发送成功", "schema": { "$ref": "#/definitions/dto.EmailSendDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "429": { "description": "请求过于频繁", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/email/verify": { "post": { "security": [ { "bearerAuth": [] } ], "description": "验证用户提交的邮箱验证码，判断其有效性。使用限流保护。参考：OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "验证邮箱验证", "parameters": [ { "description": "邮箱验证请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.EmailVerifyRequest" } } ], "responses": { "200": { "description": "验证结果", "schema": { "$ref": "#/definitions/dto.EmailVerifyDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "429": { "description": "请求过于频繁", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/methods": { "get": { "security": [ { "bearerAuth": [] } ], "description": "列出用户所有已配置的MFA方法（TOTP/SMS/Email/WebAuthn）。参考：OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "列出MFA方法", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "query", "required": true } ], "responses": { "200": { "description": "MFA方法列表", "schema": { "$ref": "#/definitions/dto.MFAMethodListResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/methods/{method_type}": { "delete": { "security": [ { "bearerAuth": [] } ], "description": "删除指定类型的MFA认证方式。参考：OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "删除MFA方法", "parameters": [ { "type": "string", "description": "MFA方法类型（totp/sms/email）", "name": "method_type", "in": "path", "required": true }, { "type": "string", "description": "用户ID", "name": "user_id", "in": "query", "required": true } ], "responses": { "200": { "description": "删除成功", "schema": { "$ref": "#/definitions/dto.MFAMethodDeleteDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/push/approve": { "post": { "security": [ { "bearerAuth": [] } ], "description": "用户通过设备批准Push MFA挑战，完成身份验证。支持 Number Matching 验证。参考：NIST SP 800-63B §5.1.7 (Verifier Impersonation Resistance)、OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "批准Push MFA挑战", "parameters": [ { "description": "Push批准请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.PushApproveRequest" } } ], "responses": { "200": { "description": "批准成功", "schema": { "$ref": "#/definitions/dto.ValidDetailResponse" } }, "400": { "description": "参数错误或挑战已过期", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "挑战未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/push/challenge": { "post": { "security": [ { "bearerAuth": [] } ], "description": "创建Push MFA挑战，通过notification-service推送批准请求到用户设备，包含 Number Matching 防钓鱼保护。参考：NIST SP 800-63B §5.1.7 (Verifier Impersonation Resistance)、OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "创建Push MFA挑战", "parameters": [ { "description": "Push挑战创建请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.PushChallengeRequest" } } ], "responses": { "201": { "description": "挑战创建成功", "schema": { "$ref": "#/definitions/dto.PushChallengeDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "设备未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "429": { "description": "请求过于频繁", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/push/challenge/{id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据挑战ID查询单条Push MFA挑战的当前状态，用于登录页面轮询。参考：NIST SP 800-63B §5.1.7 (Verifier Impersonation Resistance)、OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "获取Push挑战状态", "parameters": [ { "type": "string", "description": "挑战ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "挑战状态", "schema": { "$ref": "#/definitions/dto.PushChallengeStatusDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "挑战未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/push/deny": { "post": { "security": [ { "bearerAuth": [] } ], "description": "用户通过设备拒绝Push MFA挑战。参考：NIST SP 800-63B §5.1.7 (Verifier Impersonation Resistance)、OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "拒绝Push MFA挑战", "parameters": [ { "description": "Push拒绝请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.PushDenyRequest" } } ], "responses": { "200": { "description": "拒绝成功", "schema": { "$ref": "#/definitions/dto.ValidDetailResponse" } }, "400": { "description": "参数错误或挑战已过期", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "挑战未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/push/history": { "get": { "security": [ { "bearerAuth": [] } ], "description": "分页查询用户的Push MFA挑战历史记录。参考：NIST SP 800-63B §5.1.7、OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "获取Push MFA挑战历史", "parameters": [ { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页条数", "name": "page_size", "in": "query" }, { "type": "string", "description": "状态过滤（pending/approved/denied/expired）", "name": "status", "in": "query" } ], "responses": { "200": { "description": "挑战历史列表", "schema": { "$ref": "#/definitions/dto.PushHistoryListResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/sms/disable": { "post": { "security": [ { "bearerAuth": [] } ], "description": "验证短信验证码后禁用SMS MFA认证。参考：OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "禁用短信 MFA", "parameters": [ { "description": "禁用SMS请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.SMSDisableRequest" } } ], "responses": { "200": { "description": "禁用成功", "schema": { "$ref": "#/definitions/dto.DisabledDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "429": { "description": "请求过于频繁", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/sms/enroll": { "put": { "security": [ { "bearerAuth": [] } ], "description": "为用户注册短信MFA认证方式。参考：OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "SMS MFA注册", "parameters": [ { "description": "SMS注册请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.SMSEnrollRequest" } } ], "responses": { "201": { "description": "注册成功", "schema": { "$ref": "#/definitions/dto.SMSEnrollDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/sms/send": { "post": { "security": [ { "bearerAuth": [] } ], "description": "向用户手机发送短信验证码，用于短信MFA认证。生产环境不返回验证码明文。参考：OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "发送短信验证码", "parameters": [ { "description": "发送短信验证码请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.SMSSendRequest" } } ], "responses": { "200": { "description": "发送成功", "schema": { "$ref": "#/definitions/dto.SMSSendDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "429": { "description": "请求过于频繁", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/sms/verify": { "post": { "security": [ { "bearerAuth": [] } ], "description": "验证用户输入的短信验证码，完成短信MFA认证。使用限流保护。参考：OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "验证短信验证", "parameters": [ { "description": "短信验证请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.SMSVerifyRequest" } } ], "responses": { "200": { "description": "验证结果", "schema": { "$ref": "#/definitions/dto.SMSVerifyDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "429": { "description": "请求过于频繁", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/status/{user_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "查询用户已启用的MFA方式和状态。参考：OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "获取用户MFA状态", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "MFA状态", "schema": { "$ref": "#/definitions/dto.MFAStatusDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/step-up": { "post": { "security": [ { "bearerAuth": [] } ], "description": "对已登录用户的敏感操作进行二次MFA认证验证，支持TOTP、短信、邮箱三种方式。使用限流保护。参考：NIST SP 800-63B §5.1.7、OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "MFA步进认证", "parameters": [ { "description": "步进认证请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.StepUpRequest" } } ], "responses": { "200": { "description": "步进认证结果", "schema": { "$ref": "#/definitions/dto.StepUpDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "429": { "description": "请求过于频繁", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/totp/devices": { "get": { "security": [ { "bearerAuth": [] } ], "description": "列出用户的所有TOTP设备，支持多设备管理。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "列出TOTP设备", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "query", "required": true } ], "responses": { "200": { "description": "TOTP设备列表", "schema": { "$ref": "#/definitions/dto.TOTPDeviceListResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "post": { "security": [ { "bearerAuth": [] } ], "description": "为用户注册一个新的TOTP设备，生成独立的密钥和二维码，支持多设备管理。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "注册TOTP设备", "parameters": [ { "description": "TOTP设备注册请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.TOTPDeviceRegisterRequest" } } ], "responses": { "201": { "description": "设备注册成功", "schema": { "$ref": "#/definitions/dto.TOTPDeviceRegisterDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "409": { "description": "设备数量已达上限", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/totp/devices/{id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据ID获取指定TOTP设备的详细信息。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "获取TOTP设备详情", "parameters": [ { "type": "string", "description": "设备ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "设备详情", "schema": { "$ref": "#/definitions/dto.TOTPDeviceItem" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "设备未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "撤销指定的TOTP设备，需要提供当前TOTP验证码进行验证。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "撤销TOTP设备", "parameters": [ { "type": "string", "description": "设备ID", "name": "id", "in": "path", "required": true }, { "description": "撤销设备请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.TOTPDeviceRevokeRequest" } } ], "responses": { "200": { "description": "设备已撤销", "schema": { "$ref": "#/definitions/dto.DisabledDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "设备未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/totp/devices/{id}/disable": { "post": { "security": [ { "bearerAuth": [] } ], "description": "禁用指定的TOTP设备，切换Enabled状态为false。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "禁用TOTP设备", "parameters": [ { "type": "string", "description": "设备ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "设备已禁用", "schema": { "$ref": "#/definitions/dto.TOTPDeviceItem" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "设备未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/totp/devices/{id}/enable": { "post": { "security": [ { "bearerAuth": [] } ], "description": "启用指定的TOTP设备，切换Enabled状态为true，无需重新注册。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "启用TOTP设备", "parameters": [ { "type": "string", "description": "设备ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "设备已启用", "schema": { "$ref": "#/definitions/dto.TOTPDeviceItem" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "设备未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/totp/disable": { "post": { "security": [ { "bearerAuth": [] } ], "description": "禁用用户的TOTP多因素认证，需要提供当前TOTP码或备用码进行验证。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "禁用TOTP", "parameters": [ { "description": "禁用TOTP请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.TOTPDisableRequest" } } ], "responses": { "200": { "description": "禁用成功", "schema": { "$ref": "#/definitions/dto.DisabledDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/totp/enable": { "post": { "security": [ { "bearerAuth": [] } ], "description": "为用户启用基于时间的一次性密码(TOTP)认证，生成密钥和二维码，返回备用恢复码。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "启用TOTP多因素认证", "parameters": [ { "description": "TOTP启用请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.TOTPEnableRequest" } } ], "responses": { "200": { "description": "TOTP配置信息，包含密钥URL和二维码", "schema": { "$ref": "#/definitions/dto.TOTPEnableDetailResponse" } }, "400": { "description": "参数错误或TOTP已启用", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/totp/setup": { "post": { "security": [ { "bearerAuth": [] } ], "description": "为用户启用基于时间的一次性密码(TOTP)认证，生成密钥和二维码，返回备用恢复码。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "启用TOTP多因素认证", "parameters": [ { "description": "TOTP启用请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.TOTPEnableRequest" } } ], "responses": { "200": { "description": "TOTP配置信息，包含密钥URL和二维码", "schema": { "$ref": "#/definitions/dto.TOTPEnableDetailResponse" } }, "400": { "description": "参数错误或TOTP已启用", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/totp/validate": { "post": { "security": [ { "bearerAuth": [] } ], "description": "用户登录时验证TOTP动态码，支持备用恢复码。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "验证TOTP码（登录时）", "parameters": [ { "description": "TOTP验证请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.TOTPValidateRequest" } } ], "responses": { "200": { "description": "验证结果", "schema": { "$ref": "#/definitions/dto.ValidDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/totp/verify": { "post": { "security": [ { "bearerAuth": [] } ], "description": "验证用户提交的TOTP验证码，验证通过后启用TOTP多因素认证。使用限流保护（checkRateLimit）。参考：RFC 6238 (TOTP)、OWASP ASVS V2.8.3。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "验证并启用TOTP", "parameters": [ { "description": "TOTP验证请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.TOTPVerifyRequest" } } ], "responses": { "200": { "description": "验证成功", "schema": { "$ref": "#/definitions/dto.ValidDetailResponse" } }, "400": { "description": "参数错误或验证码无效", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "429": { "description": "请求过于频繁", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/trusted-devices": { "get": { "security": [ { "bearerAuth": [] } ], "description": "列出用户所有受信设备。参考：NIST SP 800-63B §5.1、OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "列出受信设备", "responses": { "200": { "description": "受信设备列表", "schema": { "$ref": "#/definitions/dto.TrustedDeviceListResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "post": { "security": [ { "bearerAuth": [] } ], "description": "将当前设备标记为受信设备，30天内免MFA验证。参考：NIST SP 800-63B §5.1 (Verifier Impersonation Resistance)、OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "记住受信设备", "parameters": [ { "description": "记住设备请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.TrustDeviceRequest" } } ], "responses": { "201": { "description": "受信设备", "schema": { "$ref": "#/definitions/dto.TrustedDeviceDataResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "409": { "description": "设备已注册", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "撤销用户所有受信设备，所有设备后续需重新MFA验证。参考：NIST SP 800-63B §5.1、OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "撤销所有受信设备", "responses": { "200": { "description": "已撤销数量", "schema": { "$ref": "#/definitions/dto.TrustedDeviceCountDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/trusted-devices/check": { "get": { "security": [ { "bearerAuth": [] } ], "description": "通过设备指纹检查设备是否在受信列表中。参考：NIST SP 800-63B §5.1、OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "检查设备是否受信", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "query", "required": true }, { "type": "string", "description": "设备指纹", "name": "fingerprint", "in": "query", "required": true } ], "responses": { "200": { "description": "是否受信", "schema": { "$ref": "#/definitions/dto.ValidDetailResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/trusted-devices/cleanup": { "post": { "security": [ { "bearerAuth": [] } ], "description": "清理所有已过期的受信设备记录。参考：NIST SP 800-63B §5.1、OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "清理过期受信设备", "responses": { "200": { "description": "清理完成", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/trusted-devices/{id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据ID获取指定受信设备的详细信息。参考：NIST SP 800-63B §5.1、OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "获取受信设备详情", "parameters": [ { "type": "string", "description": "受信设备ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "受信设备", "schema": { "$ref": "#/definitions/dto.TrustedDeviceItem" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "设备未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "撤销指定受信设备，该设备后续需重新MFA验证。参考：NIST SP 800-63B §5.1、OWASP ASVS V2.8。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "撤销受信设备", "parameters": [ { "type": "string", "description": "设备ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "撤销成功" }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "设备未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/webauthn/credentials": { "get": { "security": [ { "bearerAuth": [] } ], "description": "列出用户所有已注册的WebAuthn/通行密钥凭证，包含名称和最后使用时间。参考：W3C WebAuthn Level 2、FIDO2 CTAP 2.1。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "列出WebAuthn凭证", "parameters": [ { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页条数", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "凭证列表", "schema": { "$ref": "#/definitions/dto.WebAuthnCredentialListResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } }, "/mfa/webauthn/credentials/{id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据ID获取指定WebAuthn凭证的详细信息。参考：W3C WebAuthn Level 2、FIDO2 CTAP 2.1。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "获取WebAuthn凭证详情", "parameters": [ { "type": "string", "description": "凭证ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "凭证详情", "schema": { "$ref": "#/definitions/dto.WebAuthnCredentialDataResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "凭证未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "put": { "security": [ { "bearerAuth": [] } ], "description": "重命名指定WebAuthn凭证的设备名称。参考：W3C WebAuthn Level 2、FIDO2 CTAP 2.1。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "重命名WebAuthn凭证", "parameters": [ { "type": "string", "description": "凭证ID", "name": "id", "in": "path", "required": true }, { "description": "重命名请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UpdateWebAuthnCredentialRequest" } } ], "responses": { "200": { "description": "更新后的凭证", "schema": { "$ref": "#/definitions/dto.WebAuthnCredentialDataResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "凭证未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "删除指定WebAuthn凭证。参考：W3C WebAuthn Level 2、FIDO2 CTAP 2.1。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MFA" ], "summary": "删除WebAuthn凭证", "parameters": [ { "type": "string", "description": "凭证ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "删除成功" }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "404": { "description": "凭证未找到", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } }, "500": { "description": "服务器内部错误", "schema": { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.SimpleResponse" } } } } } }, "definitions": { "dto.AdminPushChallengeItem": { "type": "object", "properties": { "challenge_id": { "type": "string", "example": "chal-abc123" }, "created_at": { "type": "string", "example": "2026-05-25T08:00:00Z" }, "login_context": { "type": "string", "example": "login from Beijing" }, "number_matching": { "type": "string", "example": "42" }, "resolved_at": { "type": "string", "example": "2026-05-25T08:05:00Z" }, "status": { "type": "string", "example": "pending" }, "user_id": { "type": "string", "example": "user-001" } } }, "dto.AdminPushChallengeListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.AdminPushChallengeItem" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.BackupCodeVerifyDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.BackupCodeVerifyResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.BackupCodeVerifyRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "example": "12345678" } } }, "dto.BackupCodeVerifyResponse": { "type": "object", "properties": { "remaining_codes": { "type": "integer", "example": 9 }, "valid": { "type": "boolean", "example": true } } }, "dto.BackupCodesCountDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.BackupCodesCountResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.BackupCodesCountResponse": { "type": "object", "properties": { "count": { "type": "integer", "example": 8 }, "max_codes": { "type": "integer", "example": 10 }, "message": { "type": "string" }, "should_regenerate": { "type": "boolean", "example": false } } }, "dto.BackupCodesDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.BackupCodesResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.BackupCodesResponse": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" }, "example": [ "[\"12345678\"", "\"23456789\"]" ] }, "message": { "type": "string", "example": "Store these backup codes securely" } } }, "dto.CreateIPWhitelistRequest": { "type": "object", "required": [ "cidr", "label" ], "properties": { "cidr": { "type": "string", "example": "192.168.1.0/24" }, "label": { "type": "string", "example": "office network" } } }, "dto.DeviceSyncDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.DeviceSyncResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.DeviceSyncListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.DeviceSyncResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.DeviceSyncRequest": { "type": "object", "required": [ "device_name", "totp_devices" ], "properties": { "device_fingerprint": { "type": "string", "example": "fp-abc123" }, "device_name": { "type": "string", "example": "iPhone 15" }, "totp_devices": { "type": "string", "example": "[{\"secret\":\"JBSWY3DPEHPK3PXP\"}]" } } }, "dto.DeviceSyncResponse": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-05-21T12:00:00Z" }, "device_fingerprint": { "type": "string", "example": "fp-abc123" }, "device_name": { "type": "string", "example": "iPhone 15" }, "id": { "type": "string", "example": "devsync_abc123" }, "last_sync_at": { "type": "string", "example": "2026-05-21T12:00:00Z" }, "sync_token": { "type": "string", "example": "hex-sync-token" }, "totp_devices": { "type": "string", "example": "[{\"secret\":\"JBSWY3DPEHPK3PXP\"}]" } } }, "dto.DisabledDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.DisabledResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.DisabledResponse": { "type": "object", "properties": { "disabled": { "type": "boolean", "example": true } } }, "dto.EmailDisableRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "dto.EmailEnrollDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.EmailEnrollResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.EmailEnrollRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "example": "user@example.com" } } }, "dto.EmailEnrollResponse": { "type": "object", "properties": { "email": { "type": "string", "example": "user@example.com" }, "enabled": { "type": "boolean", "example": false }, "method_type": { "type": "string", "example": "email" }, "status": { "type": "string", "example": "pending_verification" }, "verified": { "type": "boolean", "example": false } } }, "dto.EmailSendData": { "type": "object", "properties": { "code": { "type": "string" }, "expires": { "type": "string" }, "sent": { "type": "boolean" } } }, "dto.EmailSendDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.EmailSendData" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.EmailSendRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string" }, "purpose": { "type": "string" } } }, "dto.EmailVerifyDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.ValidResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.EmailVerifyRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "email": { "description": "邮箱地址，用于创建 MFAConfig 记录", "type": "string" } } }, "dto.EvaluateRiskPolicyDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.EvaluateRiskPolicyResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.EvaluateRiskPolicyRequest": { "type": "object", "required": [ "user_id" ], "properties": { "device_fingerprint": { "type": "string" }, "ip": { "type": "string" }, "user_id": { "type": "string" } } }, "dto.EvaluateRiskPolicyResponse": { "type": "object", "properties": { "is_new_device": { "type": "boolean", "example": false }, "level": { "type": "string", "example": "medium" }, "required_methods": { "type": "array", "items": { "type": "string" }, "example": [ "[\"totp\"", "\"sms\"]" ] } } }, "dto.GenerateBackupCodesRequest": { "type": "object" }, "dto.GetBackupCodesDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.GetBackupCodesResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.GetBackupCodesResponse": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" }, "example": [ "[\"12345678\"", "\"23456789\"]" ] }, "count": { "type": "integer", "example": 8 }, "message": { "type": "string", "example": "Store these codes securely" } } }, "dto.IPWhitelistDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.IPWhitelistResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.IPWhitelistListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.IPWhitelistResponse" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.IPWhitelistResponse": { "type": "object", "properties": { "cidr": { "type": "string", "example": "192.168.1.0/24" }, "created_at": { "type": "string", "example": "2026-05-15T08:00:00Z" }, "enabled": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "wl_abc123" }, "label": { "type": "string", "example": "office network" }, "tenant_id": { "type": "string", "example": "tnt_001" } } }, "dto.InternalEraseMFARequest": { "type": "object", "required": [ "tenant_id", "user_id" ], "properties": { "tenant_id": { "type": "string" }, "user_id": { "type": "string" } } }, "dto.InternalMFAStatusDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.InternalMFAStatusResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.InternalMFAStatusResponse": { "type": "object", "properties": { "email": { "$ref": "#/definitions/dto.MFAMethodStatus" }, "sms": { "$ref": "#/definitions/dto.MFAMethodStatus" }, "totp": { "$ref": "#/definitions/dto.MFAMethodStatus" } } }, "dto.InternalTOTPDisableRequest": { "type": "object", "required": [ "tenant_id", "user_id" ], "properties": { "tenant_id": { "type": "string" }, "user_id": { "type": "string" } } }, "dto.InternalTOTPValidateRequest": { "type": "object", "required": [ "code", "user_id" ], "properties": { "code": { "type": "string" }, "tenant_id": { "type": "string" }, "user_id": { "type": "string" } } }, "dto.MFAChallengeDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.MFAChallengeResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.MFAChallengeRequest": { "type": "object", "required": [ "method" ], "properties": { "method": { "type": "string", "example": "sms" } } }, "dto.MFAChallengeResponse": { "type": "object", "properties": { "challenge_id": { "type": "string", "example": "challenge-1234567890" }, "created_at": { "type": "string", "example": "2026-04-14T12:00:00Z" }, "expires_in": { "type": "integer", "example": 300 }, "method": { "type": "string", "example": "sms" }, "tenant_id": { "type": "string", "example": "tenant-001" }, "user_id": { "type": "string", "example": "user-001" } } }, "dto.MFAConfigAuditLogItem": { "type": "object", "properties": { "action": { "type": "string", "example": "mfa_totp.enabled" }, "id": { "type": "string", "example": "log_abc123" }, "message": { "type": "string", "example": "TOTP enabled successfully" }, "module": { "type": "string", "example": "data" }, "operator_id": { "type": "string", "example": "usr_admin" }, "target_id": { "type": "string", "example": "mfa_abc123" }, "target_type": { "type": "string", "example": "mfa_totp" }, "tenant_id": { "type": "string", "example": "tnt_001" }, "timestamp": { "type": "string", "example": "2026-05-15T10:00:00Z" } } }, "dto.MFAConfigAuditLogListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.MFAConfigAuditLogItem" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.MFADeletedResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true }, "type": { "type": "string", "example": "sms" } } }, "dto.MFAMethodDeleteDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.MFADeletedResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.MFAMethodItem": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-05-14T08:00:00Z" }, "detail": { "type": "string", "example": "+8613800****000" }, "enabled": { "type": "boolean", "example": true }, "method_type": { "type": "string", "example": "totp" }, "primary": { "type": "boolean", "example": true }, "verified": { "type": "boolean", "example": true } } }, "dto.MFAMethodListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.MFAMethodItem" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.MFAMethodStatus": { "type": "object", "properties": { "email": { "type": "string", "example": "user@example.com" }, "enabled": { "type": "boolean", "example": true }, "phone": { "type": "string", "example": "+8613800****000" }, "verified": { "type": "boolean", "example": true } } }, "dto.MFAStatusDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.MFAStatusResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.MFAStatusResponse": { "type": "object", "properties": { "email_address": { "type": "string", "example": "user@example.com" }, "email_enabled": { "type": "boolean", "example": true }, "sms_enabled": { "type": "boolean", "example": false }, "sms_phone": { "type": "string", "example": "+8613800****000" }, "totp_enabled": { "type": "boolean", "example": true } } }, "dto.PushApproveRequest": { "type": "object", "required": [ "challenge_id", "number_matching" ], "properties": { "challenge_id": { "type": "string", "example": "chal-abc123" }, "device_key": { "type": "string", "example": "hmac-sig" }, "number_matching": { "type": "string", "example": "42" } } }, "dto.PushChallengeDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PushChallengeResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PushChallengeRequest": { "type": "object", "properties": { "device_id": { "type": "string", "example": "dev-001" }, "login_context": { "type": "string", "example": "login from Beijing" } } }, "dto.PushChallengeResponse": { "type": "object", "properties": { "challenge_id": { "type": "string", "example": "chal-abc123" }, "created_at": { "type": "string", "example": "2026-05-12T12:00:00Z" }, "expires_in": { "type": "integer", "example": 120 }, "login_context": { "type": "string", "example": "login from Beijing" }, "number_matching": { "type": "string", "example": "42" }, "status": { "type": "string", "example": "pending" }, "user_id": { "type": "string", "example": "user-001" } } }, "dto.PushChallengeStatusDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PushChallengeStatusResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PushChallengeStatusResponse": { "type": "object", "properties": { "challenge_id": { "type": "string", "example": "chal-abc123" }, "login_context": { "type": "string", "example": "login from Beijing" }, "number_matching": { "type": "string", "example": "42" }, "resolved_at": { "type": "string", "example": "2026-05-25T12:05:00Z" }, "status": { "type": "string", "example": "approved" } } }, "dto.PushDenyRequest": { "type": "object", "required": [ "challenge_id", "number_matching" ], "properties": { "challenge_id": { "type": "string", "example": "chal-abc123" }, "device_key": { "type": "string", "example": "hmac-sig" }, "number_matching": { "type": "string", "example": "42" } } }, "dto.PushHistoryItem": { "type": "object", "properties": { "challenge_id": { "type": "string", "example": "chal-abc123" }, "created_at": { "type": "string", "example": "2026-05-25T08:00:00Z" }, "login_context": { "type": "string", "example": "login from Beijing" }, "resolved_at": { "type": "string", "example": "2026-05-25T08:05:00Z" }, "status": { "type": "string", "example": "approved" } } }, "dto.PushHistoryListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.PushHistoryItem" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.PushStatsDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.PushStatsResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.PushStatsResponse": { "type": "object", "properties": { "approved": { "type": "integer", "example": 89 }, "denied": { "type": "integer", "example": 12 }, "expired": { "type": "integer", "example": 34 }, "pending": { "type": "integer", "example": 125 }, "total": { "type": "integer", "example": 260 } } }, "dto.RiskPolicyDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.RiskPolicyResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.RiskPolicyItem": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-05-25T08:00:00Z" }, "description": { "type": "string", "example": "High-risk policy for new devices" }, "enabled": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "rp_abc123" }, "level": { "type": "string", "example": "high" }, "required_methods": { "type": "array", "items": { "type": "string" }, "example": [ "[\"totp\"", "\"sms\"]" ] }, "updated_at": { "type": "string", "example": "2026-05-25T08:00:00Z" } } }, "dto.RiskPolicyItemDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.RiskPolicyItem" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.RiskPolicyLevel": { "type": "object", "properties": { "required_methods": { "type": "array", "items": { "type": "string" }, "example": [ "[\"totp\"", "\"sms\"]" ] } } }, "dto.RiskPolicyListResponseWrap": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.RiskPolicyItem" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.RiskPolicyResponse": { "type": "object", "properties": { "high_risk": { "$ref": "#/definitions/dto.RiskPolicyLevel" }, "low_risk": { "$ref": "#/definitions/dto.RiskPolicyLevel" }, "medium_risk": { "$ref": "#/definitions/dto.RiskPolicyLevel" }, "tenant_id": { "type": "string", "example": "tnt_abc123" } } }, "dto.SMSDisableRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "dto.SMSEnrollDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.SMSEnrollResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.SMSEnrollRequest": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "example": "+8613800138000" } } }, "dto.SMSEnrollResponse": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": false }, "method_type": { "type": "string", "example": "sms" }, "phone": { "type": "string", "example": "+8613800****000" }, "status": { "type": "string", "example": "pending_verification" }, "verified": { "type": "boolean", "example": false } } }, "dto.SMSSendDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.SMSSendResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.SMSSendRequest": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string" }, "purpose": { "description": "login, bind, reset", "type": "string" } } }, "dto.SMSSendResponse": { "type": "object", "properties": { "code": { "type": "string", "example": "123456" }, "expires": { "type": "string", "example": "2026-05-25T12:05:00Z" }, "sent": { "type": "boolean", "example": true } } }, "dto.SMSVerifyDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.SMSVerifyResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.SMSVerifyRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "phone": { "description": "手机号，用于创建 MFAConfig 记录", "type": "string" } } }, "dto.SMSVerifyResponse": { "type": "object", "properties": { "valid": { "type": "boolean", "example": true } } }, "dto.SetPrimaryCredentialDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.SetPrimaryCredentialResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.SetPrimaryCredentialRequest": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" } } }, "dto.SetPrimaryCredentialResponse": { "type": "object", "properties": { "credential_id": { "type": "string", "example": "cred_abc123def456" }, "primary": { "type": "boolean", "example": true }, "type": { "type": "string", "example": "totp" } } }, "dto.StepUpDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.StepUpResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.StepUpRequest": { "type": "object", "required": [ "code", "method", "user_id" ], "properties": { "code": { "type": "string", "example": "123456" }, "method": { "type": "string", "enum": [ "totp", "sms", "email" ], "example": "totp" }, "user_id": { "type": "string", "example": "usr_abc123" } } }, "dto.StepUpResponse": { "type": "object", "properties": { "expires_in": { "type": "integer", "example": 300 }, "message": { "type": "string", "example": "step-up authentication successful" }, "step_up_token": { "type": "string", "example": "eyJ..." }, "valid": { "type": "boolean", "example": true } } }, "dto.TOTPDeviceItem": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-05-12T12:00:00Z" }, "device_id": { "type": "string", "example": "dev-abc123" }, "device_name": { "type": "string", "example": "iPhone 15" }, "enabled": { "type": "boolean", "example": true }, "last_used_at": { "type": "string", "example": "2026-05-12T12:00:00Z" }, "verified": { "type": "boolean", "example": true } } }, "dto.TOTPDeviceListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.TOTPDeviceItem" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.TOTPDeviceRegisterDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.TOTPDeviceRegisterResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.TOTPDeviceRegisterRequest": { "type": "object", "required": [ "device_name" ], "properties": { "account": { "type": "string", "example": "user@example.com" }, "device_fingerprint": { "type": "string", "example": "fp-abc123" }, "device_name": { "type": "string", "example": "iPhone 15" } } }, "dto.TOTPDeviceRegisterResponse": { "type": "object", "properties": { "device_id": { "type": "string", "example": "dev-abc123" }, "device_name": { "type": "string", "example": "iPhone 15" }, "qr_code": { "type": "string", "example": "data:image/png;base64,..." }, "qr_code_url": { "type": "string", "example": "otpauth://totp/..." }, "secret": { "type": "string", "example": "JBSWY3DPEHPK3PXP" } } }, "dto.TOTPDeviceRevokeRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "example": "123456" } } }, "dto.TOTPDisableRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "dto.TOTPEnableDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.TOTPEnableResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.TOTPEnableRequest": { "type": "object", "properties": { "account": { "type": "string" }, "device_name": { "type": "string" } } }, "dto.TOTPEnableResponse": { "type": "object", "properties": { "backup_codes": { "type": "array", "items": { "type": "string" }, "example": [ "[\"12345678\"", "\"23456789\"]" ] }, "qr_code": { "type": "string", "example": "data:image/png;base64,iVBORw0KGgo..." }, "qr_code_url": { "type": "string", "example": "otpauth://totp/AuthMS:user@example.com?secret=JBSWY3DPEHPK3PXP\u0026issuer=AuthMS" }, "secret": { "type": "string", "example": "JBSWY3DPEHPK3PXP" }, "setup_url": { "type": "string", "example": "https://auth.example.com/mfa/totp/setup" } } }, "dto.TOTPValidateRequest": { "type": "object", "required": [ "code", "user_id" ], "properties": { "code": { "type": "string" }, "user_id": { "type": "string" } } }, "dto.TOTPVerifyRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "dto.TrustDeviceRequest": { "type": "object", "required": [ "device_fingerprint", "device_name" ], "properties": { "device_fingerprint": { "type": "string" }, "device_name": { "type": "string" }, "user_agent": { "type": "string" } } }, "dto.TrustedDeviceCountDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.TrustedDeviceCountResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.TrustedDeviceCountResponse": { "type": "object", "properties": { "count": { "type": "integer", "example": 3 } } }, "dto.TrustedDeviceDataResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.TrustedDeviceItem" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.TrustedDeviceItem": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-05-25T08:00:00Z" }, "device_name": { "type": "string", "example": "iPhone 15" }, "id": { "type": "string", "example": "td_abc123" }, "ip_address": { "type": "string", "example": "192.168.1.100" }, "trusted_until": { "type": "string", "example": "2026-06-25T08:00:00Z" } } }, "dto.TrustedDeviceListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.TrustedDeviceItem" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.UpdateIPWhitelistRequest": { "type": "object", "properties": { "cidr": { "type": "string" }, "enabled": { "type": "boolean" }, "label": { "type": "string" } } }, "dto.UpdateRiskPolicyByLevelRequest": { "type": "object", "required": [ "required_methods" ], "properties": { "description": { "type": "string" }, "enabled": { "type": "boolean" }, "required_methods": { "type": "array", "items": { "type": "string" } } } }, "dto.UpdateRiskPolicyRequest": { "type": "object", "required": [ "high_risk", "low_risk", "medium_risk" ], "properties": { "high_risk": { "type": "array", "items": { "type": "string" } }, "low_risk": { "type": "array", "items": { "type": "string" } }, "medium_risk": { "type": "array", "items": { "type": "string" } } } }, "dto.UpdateWebAuthnCredentialRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "dto.ValidDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.ValidResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.ValidResponse": { "type": "object", "properties": { "valid": { "type": "boolean", "example": true } } }, "dto.WebAuthnCredentialDataResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/dto.WebAuthnCredentialItem" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.WebAuthnCredentialItem": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-05-20T08:00:00Z" }, "credential_id": { "type": "string", "example": "cred_xyz789" }, "device_info": { "type": "string", "example": "FIDO2" }, "id": { "type": "string", "example": "wc_abc123" }, "last_used_at": { "type": "string", "example": "2026-05-25T08:00:00Z" }, "name": { "type": "string", "example": "YubiKey 5C" } } }, "dto.WebAuthnCredentialListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/dto.WebAuthnCredentialItem" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/gitee_com_linmes_authms_base_dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "gitee_com_linmes_authms_base_dto.PageInfo": { "type": "object", "properties": { "has_next": { "description": "HasNext indicates whether there is a next page", "type": "boolean" }, "has_prev": { "description": "HasPrev indicates whether there is a previous page", "type": "boolean" }, "page": { "description": "Page is the current page number (1-based)", "type": "integer" }, "page_size": { "description": "PageSize is the number of items per page", "type": "integer" }, "total": { "description": "Total is the total number of items across all pages", "type": "integer" }, "total_pages": { "description": "TotalPages is the total number of pages", "type": "integer" } } }, "gitee_com_linmes_authms_base_dto.SimpleResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } } }, "securityDefinitions": { "bearerAuth": { "description": "Type \"Bearer\" followed by a space and JWT token.", "type": "apiKey", "name": "Authorization", "in": "header" } }, "tags": [ { "description": "多因素认证：TOTP、短信、邮件、生物识别、Push", "name": "MFA" }, { "description": "管理员接口：用户管理、系统配置、安全策略", "name": "Admin" } ] }